Skip to content

feat(shot): lay out with a device's safe area with --safe-area #50

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
koji-1009 merged 2 commits into from
Nov 5, 2026
Merged

feat(shot): lay out with a device's safe area with --safe-area #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a50d05
feat(shot): lay out with a device's safe area with --safe-area
koji-1009 Nov 4, 2026
1eb351c
docs(api): say what ShotSetup.safeArea holds for a run without one
koji-1009 Nov 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
The device a shot is drawn as.

* `shutter shot --pixel-ratio <ratio>` (and `semantics`, and `shot(pixelRatio:)`) draws every preview at that device pixel ratio instead of 2: the PNG is the shot's logical size times the ratio, and what reads the ratio, such as `MediaQuery.devicePixelRatioOf` and an `AssetImage` picking its variant, follows it as on the device. `shot` prints it, `manifest.json` records it, `diff` prints both runs' when they differ and returns it as `ShotSetup.pixelRatio`. It is not part of shot ids.
* `shutter shot --safe-area <top>,<bottom>` (and `semantics`, and `shot(safeArea: SafeAreaInsets(...))`) lays every preview out with those safe area insets in logical pixels, which `flutter test` reports as none: the view reports them as its padding and view padding, so an `AppBar` grows by the top inset and a `SafeArea` keeps out of them as on the device; with `--keyboard`, the keyboard absorbs the bottom inset from the padding. The status bar and home indicator are not drawn. `shot` prints the insets, `manifest.json` records them, `diff` prints both runs' when they differ and returns them as `ShotSetup.safeArea`. They are not part of shot ids.

## 1.3.0

Expand Down
21 changes: 11 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,19 +154,20 @@ Each is followed by `--settle` milliseconds; shoot again with another `--settle`
`--keyboard <height>` lays a screen out as with its on-screen keyboard up, which `--enter` does not raise; the keyboard itself is not drawn, and `--keyboard-tint 9E9E9E` paints its area gray.
`--platform ios` draws the app as iOS instead of Android, the platform `flutter test` runs as: the theme, the back button, page transitions, and adaptive widgets follow.
`--pixel-ratio 3` draws at the device pixel ratio of the device a screen is laid out for, instead of 2.
`--safe-area 59,34` lays a screen out with that device's safe area insets, top and bottom, which `flutter test` reports as none; the status bar and home indicator are not drawn.

## Subcommands

| Command | Purpose |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent` | The step-by-step playbook for AI agents. |
| `manual` | The reference: preview files, drawing model, engine, runs, ids, diff, output, exit codes. |
| `doctor` | Check the Flutter SDK version, its font cache, and the project's shell (`--shell`). |
| `init` | Write `<preview dir>/shell.dart`, or the `--shell` file. |
| `shot` | Render the named preview files, or one `--widget`, into a new run (`--widget`/`--import`/`--size`, `--settle`, `--shell`, `--tap`/`--enter`/`--press`/`--hover`/`--focus`, `--capture`/`--viewport`, `--keyboard`/`--keyboard-tint`, `--network-image`, `--platform`, `--pixel-ratio`). |
| `semantics` | Draw the semantics tree of the same subjects into a new run, with the options of `shot` except `--keyboard-tint`. |
| `diff <a> <b>` | Compare two runs (`--images`, `--composite`). |
| `prune` | Delete every run but the newest `--keep <n>`. |
| Command | Purpose |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agent` | The step-by-step playbook for AI agents. |
| `manual` | The reference: preview files, drawing model, engine, runs, ids, diff, output, exit codes. |
| `doctor` | Check the Flutter SDK version, its font cache, and the project's shell (`--shell`). |
| `init` | Write `<preview dir>/shell.dart`, or the `--shell` file. |
| `shot` | Render the named preview files, or one `--widget`, into a new run (`--widget`/`--import`/`--size`, `--settle`, `--shell`, `--tap`/`--enter`/`--press`/`--hover`/`--focus`, `--capture`/`--viewport`, `--keyboard`/`--keyboard-tint`, `--network-image`, `--platform`, `--pixel-ratio`, `--safe-area`). |
| `semantics` | Draw the semantics tree of the same subjects into a new run, with the options of `shot` except `--keyboard-tint`. |
| `diff <a> <b>` | Compare two runs (`--images`, `--composite`). |
| `prune` | Delete every run but the newest `--keep <n>`. |

## Exit codes

Expand Down
1 change: 1 addition & 0 deletions doc/agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ Widget settingsSignedOut() => const SettingsPage(user: null);
* Top-level functions, static methods, and constructors without required arguments are all valid targets; `MultiPreview` and `Preview` subclasses work too.
* Shots are drawn as Android, the platform `flutter test` runs as. For an app that ships on iOS, or a change to iOS-only code, pass `--platform ios` to the before and after shots alike: the theme, the back button, page transitions, adaptive widgets, and the app's own `defaultTargetPlatform` checks then draw as on an iPhone. `diff` prints `platform:` when the two runs differ in it.
* Shots are drawn at a device pixel ratio of 2. For the device a screen is laid out for, pass its ratio to the before and after shots alike, `--pixel-ratio 3` for an iPhone: an `AssetImage` then picks that ratio's variant. The PNG is the shot's `size` times the ratio; when you post it, show it at `size`'s width. `diff` prints `pixel_ratio:` when the two runs differ in it.
* Shots are laid out without a safe area, as no phone is. For a screen, pass the device's insets, top and bottom in logical pixels, to the before and after shots alike, `--safe-area 59,34` for example (the device's `MediaQuery.viewPaddingOf(context)`): the `AppBar` then grows under the status bar and a `SafeArea` keeps out of the insets as on the device. The status bar and the home indicator are not drawn; say so when you post the image.

## Shell

Expand Down
Loading
Loading