Files
pipelines/app/notes/ipad-layout-review.md
T
alan 9b6809c9a1 iPad layout review notes and native fixture host
Run the full-app fixture entry on an iOS simulator: options from a file in
the app's tmp dir or the environment, route via a route provider, a narrow
strip for Split View widths, and a small in-app tap/type driver.
2026-11-03 17:32:58 +00:00

214 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# iPad layout review (iOS simulator)
Review only. No app source under `lib/` (or `ios/`) is changed by this note's
commit. Screenshots are in `notes/ipad-layout-review/` (downscaled JPEGs of the
simulator captures; the crops are full resolution).
## Setup
- Simulators (iOS 26.4 runtime): iPad Air 13-inch (M4)
`6D1598AE-46C0-4B2B-90FB-882BB48DE3FB` (1024x1366 pt) and iPad Pro 11-inch
(M5) `A670C822-A32A-40DD-AF6C-EF1F162A81B4` (834x1194 pt). Debug build
installed with `flutter run -t tool/search_selection_probe_entry.dart -d <sim>
--debug --no-resident`. No live server, data dir or physical device was used.
- Data: the full-app fixture entry. It previously compiled for the web only
(`package:web`, `dart:js_interop` probes, URL query). This commit adds
`tool/fixture_host/` (tool-only) so the same entry runs natively:
- the options are read from `fixture_query.txt` in the app's tmp dir
(`xcrun simctl get_app_container <sim> net.awan.pipelines.next data`/tmp),
or the launch environment / `--dart-define=FIXTURE_QUERY` (the
`SIMCTL_CHILD_` environment did not reach the app on this runtime);
- `route=` goes through a `PlatformRouteInformationProvider`;
- `server=ws://127.0.0.1:PORT/connect` points artifact fetches at a loopback
file server (here `python3 -m http.server 0 --bind 127.0.0.1` serving
`artifacts/7/2/release-report.txt`); the socket stays in-process;
- `connect=1` runs the real launch flow with no saved server (Connect screen);
- `width=N` lays the app out in an N-pt strip at the window's left edge
(approximates Split View / narrow windows; system insets stay the
full window's);
- `do=` is a small in-app driver (`tap:<label>`, `tapxy:x,y`,
`drag:x,y,dx,dy`, `type:<text>`, `labels`, `wait:ms`), because `simctl`
cannot tap. Labels with `·` or other non-ASCII must use `tapxy`.
The browser build and `tool/capture/` work as before (rebuilt and used for
the web comparison shots).
- Fixture options used for chat: `chats=8&colors=1&msgs=60,20&rich=1&links=1&tasks=4`.
### What could not be driven
- **Rotation.** `simctl` has no rotate command, Simulator.app GUI scripting
timed out (no accessibility permission), and `SystemChrome
.setPreferredOrientations` is ignored for an iPad app that supports
multitasking. A temporary, uncommitted `UIRequiresFullScreen` build (reverted
right after; `git diff ios/` is clean) did not rotate either: iPadOS 26 put
the app into a 1024x~765 window instead (`air-l-test.jpg`). Landscape is
therefore covered by the web build at 1366x1024 and 1210x834 (same Material
code, no safe-area insets) and is **unverified on iOS**. Orientation-change
glitches were not tested.
- **Split View / Stage Manager sizes.** Not drivable; approximated with
`width=375/507/600/683` on the Air (portrait height). Breakpoints from
`lib/shell/list_detail_policy.dart`: list beside detail from 600 pt wide
(`kListDetailMinWidth`), list pane 240–440 pt (`kListPaneMinWidth`,
`kListPaneMaxWidth`), detail at least 320 pt. iPadOS 26 windowing did
produce one real windowed launch on its own (`air-win-chat0.jpg`).
- Keyboard: the simulator ran headless, so the software keyboard showed for
every focused field.
## Findings (most severe first)
### 1. High: iPadOS 26 window controls cover the list pane's title pill
- Screen: Chat list (any destination's top-left title pill), Air 13, windowed
(iPadOS 26 windowed apps, ~1024x765 window).
- Wrong: the system window controls (red/yellow/green) sit on top of the
"Chat" title pill, hiding the title and the top of the pill, and they take
the touches meant for it. The app pads the top bar only by the safe area,
which does not include the window-controls region.
- Expected: the leading top-bar content clears the window controls (UIKit's
window-control layout margin), as native iPadOS 26 apps do, e.g. by
shifting the title pill right or down when the controls are present.
- Screenshots: `air-win-chat0.jpg`, `air-win-chat0-crop.jpg`; the same window
on Runs with the pill just clearing the controls: `air-l-test-crop.jpg`.
- Likely source: `lib/shell/adaptive_shell.dart` (`_ListPaneBar`, the top
padding passed to the bar), `lib/ui/adaptive/segmented_bar.dart`. Flutter
does not expose the window-controls margin, so this likely needs a small
platform inset (iOS embedder/plugin) feeding the bar's leading padding.
### 2. High: narrow list pane collapses the top bar (blank title, cramped and clipped icons)
- Screen: Runs and Pipelines list panes beside a detail. Air 13 portrait after
dragging the divider to its minimum (full screen), and Air at `width=600`
(both give the 240 pt list pane); `width=683` (≈ half of a 13" landscape
screen); Pro 11 portrait at the default list width.
- Wrong: the title pill keeps its glass but its text disappears entirely at
240 pt ("Runs" becomes an empty pill), ellipsises to "R..." at ~270 pt and
to "Pipe..." on the Pro 11 default. The five action icons squeeze to about
30 pt pitch (below the 44 pt minimum target) and the last one ("Select") is
clipped by the pill's rounded end.
- Expected: the title stays readable (it is the destination name) and actions
keep 44 pt targets; overflowing actions should move into an overflow menu
rather than squeeze, or the pane's minimum should be wide enough for the
bar's content.
- Screenshots: `air-p-divider-narrow.jpg`, `air-w600-runs.jpg`,
`air-w600-runs-bar.jpg`, `air-w683-runs-bar.jpg`, `pro-p-pipelines.jpg`.
- Likely source: `lib/ui/adaptive/segmented_bar.dart` (`_actionIslands` lets
icons "squeeze together", `minTitleShare`), `lib/shell/list_detail_policy.dart`
(`kListPaneMinWidth` = 240).
### 3. Medium: list rows lose status, date and actions in narrow panes
- Screen: Runs list and Chat list beside a detail at `width=600`/`683`
(240–270 pt list pane).
- Wrong: run rows drop the status icon, the date and the "More actions"
button; chat rows drop the harness avatar and the time; subtitles truncate
to "claude-opus · /workspa...". A failed run is no longer distinguishable
from a succeeded one in the list.
- Expected: status (at least the coloured icon) survives any list width;
hidden row actions need another route (swipe/long-press) that is visible.
- Screenshots: `air-w600-runs.jpg`, `air-w683-run7.jpg`, `air-w600-chat0.jpg`,
`air-w683-chat0.jpg`.
- Likely source: `lib/ui/layout/app_list_row.dart` (the shared row the run
and chat lists use; see `notes/app-list-row.md`).
### 4. Medium: Settings shows the tab buttons where a list pane would be
- Screen: Settings, Air 13 portrait, light and dark.
- Wrong: Settings is a single full-width page, but the floating tab buttons
stay centred under an absent 330 pt list column, i.e. over the left part of
the settings cards, with "Pipelines" highlighted. At the default scroll
position they cover the notification footnote text. The settings column is
capped at ~590 pt and left-aligned, leaving the right ~40% of a 13" screen
empty, which reads as unfinished next to the centred Connect screen.
(The page's end padding is correct: the last card scrolls clear.)
- Expected: on a page without a list pane, centre the tab buttons in the
window (or under the content column) and centre or widen the content column
on wide windows.
- Screenshots: `air-p-settings.jpg`, `air-p-dark-settings.jpg`,
`air-p-settings-end.jpg`; web at 1210x834 has the same placement:
`web-1210x834-settings.jpg`.
- Likely source: `lib/shell/adaptive_shell.dart` (the bar's
`split = _bar.split(_selected) || showsListBesideDetail(context)` keeps it
under the list column "so it never jumps sides"),
`lib/features/settings/settings_layout.dart`.
### 5. Low: bottom controls in the detail pane are not consistent
- Screen: run/stage detail vs artifact viewer vs diff viewer, Air 13 portrait.
- Wrong: detail tab buttons are round floating buttons at the trailing edge;
the artifact viewer's actions (download/share/open/link) are a glass pill at
the leading edge; the diff viewer's "1 of 3" pager is a full-width glass bar.
Three placements for the same bottom-chrome role in one pane.
- Expected: one placement rule for detail bottom chrome (trailing, matching
the tab buttons), or a deliberate, documented difference.
- Screenshots: `air-p-stage-artifacts.jpg`, `air-p-artifact-viewer.jpg`,
`air-p-diff.jpg`.
- Likely source: `lib/features/artifacts/ui/` (viewer actions),
`lib/features/changes/widgets/` (diff viewer pager),
`lib/ui/adaptive/glass_bar.dart`.
### 6. Low: sheets end close to the bottom edge and rounded corner
- Screen: chat background-task sheet, Air 13 portrait.
- Wrong: the last row ("Agent "Review part 3" finished … Finished") sits about
30 pt above the bottom edge, with the trailing status next to the display's
rounded corner and the window resize grip.
- Expected: sheet content padded by the bottom safe area plus the sheet's own
padding. The chat information sheet is otherwise sized well: confined to
the detail pane, not overly wide (`air-p-chat-info.jpg`).
- Screenshots: `air-p-task-group.jpg`, `air-p-task-group-crop.jpg`.
- Likely source: `lib/features/chat/ui/transcript/chat_task_notices_group.dart`.
### 7. Low: Material control heights below 44 pt
- Screen: Connect, Settings (Air 13 portrait).
- Wrong: filled and outlined buttons ("Continue", "Find servers on this
network", "Disconnect", "Sign in") are about 40 pt tall, under the iOS 44 pt
minimum. This follows from using Material defaults on iOS.
- Expected: either accept it as the Material choice or raise the tap-target
size for touch (`materialTapTargetSize`/minimum size in the iOS theme).
- Screenshots: `air-p-connect.jpg`, `air-p-settings.jpg`.
- Likely source: `lib/ui/theme/app_theme.dart`.
### 8. Low: transcript text shows beside the floating chat title
- Screen: open chat, Pro 11 and Air 13 portrait.
- Wrong: scrolled message text runs right up to and between the title pill
and the model pill (on the Pro 11, a link fragment shows between them). It
is legible but noisy. The colour wash only tints the top band.
- Expected: a slightly stronger top fade behind the pills, as on the list
pane's bar.
- Screenshots: `pro-p-chat0.jpg`, `air-p-chat0.jpg`, `air-p-dark-chat0.jpg`.
- Likely source: `lib/ui/adaptive/top_glass_strip.dart`,
`lib/ui/adaptive/glass_pill.dart`.
### 9. Low: tab buttons and composer are not on one baseline
- Screen: open chat, Air 13 portrait.
- Wrong: the list pane's tab buttons and the detail pane's composer sit side
by side but their bottoms differ by a few points (the tabs are taller and
sit lower).
- Expected: a shared bottom inset for both panes' floating chrome.
- Screenshot: `air-p-chat0.jpg`.
- Likely source: `lib/shell/list_detail.dart`,
`lib/ui/adaptive/floating_bar_layout.dart`.
## Checked and fine
- Status bar, home indicator and rounded display corners: the top bars clear
the status bar and the floating tab buttons and composer clear the bottom
inset in full screen on both iPads (`air-p-run7.jpg`, `pro-p-stage-build.jpg`).
- Tab-button placement: under the list pane when list and detail are shown;
under the run detail's own tabs on the trailing side; at compact widths
(375 pt) the detail's own tabs replace the shell tabs (`air-w375-run7.jpg`,
`air-w375-chat0.jpg`).
- Keyboard and composer: the composer moves above the software keyboard and
grows to seven lines without covering the transcript or the send button
(`air-p-composer-multiline.jpg`). Search keeps results above the keyboard
(`air-p-search.jpg`).
- Divider drag works and persists; the tab buttons recentre in the new list
width (`air-p-divider-narrow.jpg`, but see finding 2).
- Chat information sheet: sized to the detail pane (`air-p-chat-info.jpg`).
- Dark mode: glass pills, colour-washed rows and status chips stay legible
(`air-p-dark-run7.jpg`, `air-p-dark-chat0.jpg`).
- Pipeline detail, run graph and diff content: no clipping
(`air-p-pipeline24.jpg`, `air-p-diff.jpg`).
- Compared with the web build at 1366x1024 / 1210x834 (`web-1366x1024-run7.jpg`,
`web-1210x834-chat0.jpg`): the layout is the same. iOS uses SF at a smaller
optical size, and on the web the tab buttons sit lower because there is no
bottom inset. In web landscape the 440 pt list pane leaves the title and
icons enough room, so finding 2 does not show there.
Fixture limits: the fixture does not implement `list_schedules` and
`notification_settings`, so those sections show fixture errors; the run graph
only shows with `graph=1`.