Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

Merge plan/sway-large-illust-1021 (sway: the Sway layer on a cycle's frames at their own size, on the breath, a region moved whole and across apart from down; sway-inspect: a seam under a third moving region is no seam, record schema 3; breathe: a smooth breath's beat chosen to miss the hands) into main, after test-parts-full-timeout, validated in sprite-gen/sway-large-illust-1021

Soohong Kimbf3593ba9cc4
diff --cc CHANGELOG.md
index 76cdff6,3cfdcbe..290ee9f
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -34,37 -44,10 +44,40 @@@ The Breathe layer still supports `pixel
`tests/effects/test_breathe_js_mirror.py` checks curator refusal wording and byte identity with the pixel bake.
`tests/effects/test_breathe_smooth.py` checks pixel and smooth byte goldens and shared anatomy and strain measurements.
`tests/effects/test_breathe_publish.py` checks that the stand-in bake accepts the new argument.
+ `tests/video/test_sway_frames.py`, `tests/video/test_sway_breath.py`, `tests/video/test_sway_flat_across.py`, and `tests/video/test_sway_seams.py` check the Sway paths, drives, weights, gains and seams.
+ `tests/effects/test_breath_beat.py` checks beat choice and refusals.
+ `tests/video/test_follow_stretch_floor.py` and `tests/video/test_follow_inspect.py` cover the changed inspection schema and frames options.
+- **Tests**: A plain `pytest` runs a fast bundle: tests marked `slow` are deselected, the header points to `pytest --full`, and the summary counts deselections. `pytest --full` runs every test. The release lane, `scripts/linux_lane.sh`, passes `--full` to both `pytest` calls, including `-m real_rife`, so its gate still runs every test. `tests/release/test_fast_bundle.py` checks both calls and probes selection with and without `--full`. The `slow` rule in `pyproject.toml` is 1 s per case or 5 s across a function's cases on an 8-core M1 running the whole suite; marking a function marks every case. Five tests remain unmarked as the only fast callers of `video-stop`, `workflow`, `defaults`, `video-sway`, and `export-aseprite`. Three fixture-first tests remain unmarked because other fast tests build their fixtures. In `tests/frames/test_ui_kit.py`, the fast bundle keeps 16 of 512 scattered-drawing grid seeds, 8 of 256 full-size-frame band grid seeds, 9 of 256 missing-element sets, 2 of 17 counterexample sheets, and one placement and start in each publish sweep. `tests/curate/test_anchor_selection.py` extracts each run once per module instead of repeating 1.5 to 2.6 s of setup per test; 25 of 27 affected tests are now fast. Removed `tests/video/test_loop_overlap.py::test_a_tail_on_its_own_beat_is_closed_at_the_wrap_with_the_clips_frames_a_cycle_apart[on]`; its wordless case makes the same call with the default "on". Removed `tests/video/test_walk_steps.py::test_cycle_align_takes_a_loop_cut_two_steps_as_one_cycle` and `tests/video/test_one_step_cut.py::test_cycle_align_takes_the_loop_cut_again_on_its_count`; `tests/video/test_loop_prop_seam_held.py::test_cycle_align_aligns_a_two_step_loop_as_the_one_cycle_it_is` covers alignment from recorded `steps: 2`. Merged `tests/video/test_loop_overlap.py::test_the_cli_passes_overlap_wrap_off_and_on_is_its_default` into `tests/video/test_loop_overlap.py::test_with_the_overlapped_wrap_off_nothing_is_read_for_the_wrap_and_the_gate_refuses_the_cut_as_filmed`, retaining both sets of assertions on one CLI cut with `--overlap-wrap off`. In a new virtual environment, the former suite ran 7,881 tests (7,880 passed, 1 skipped) in 21 minutes 54 seconds; `pytest --full` now runs 7,881, including two new release tests, and the fast bundle runs 6,555 in about 6 minutes. Package code, commands, and outputs are unchanged.
+
+**Upgrading from 3.0.0: the `sprite-gen logo` text checks read a refused image once more before refusing it, and on codex they read on a fixed model and effort.** A mood or logo reading of `mismatch` or `no-text` is read again, up to `logo.MAX_READS` readings, which is 2. One reading that spells the asked text passes. An image is refused only when every reading differs. A logo now costs four to six calls: two images and two text checks, each read once or twice. Beyond a check's second reading nothing is sent again on its own. On codex the text checks no longer follow the login's `~/.codex/config.toml`. They read on `gpt-6-sol` at reasoning effort `high`, and the report names the model and effort of every reading. **`sprite-gen logo` refuses a chroma key that is one of the title's own colours, and a cut that is see-through inside its letters.** A letter colour in the key's hue is, by its pixels, a mix with the key, so the matte cuts it see-through. `--chroma-key auto` now skips a key whose hue covers 5 % or more of the title's box in the mood image, or 1 % when the brief names a colour in that hue. When both keys are the title's colours, the run is refused at the new step `key` before the lettering image is bought. After the matte, see-through pixels walled in by the lettering, farther from it than the logo's own glow reaches, refuse the logo at `matte` on 1 % of the visible lettering or more. A run that went through before with a key in the title's hue, or with a see-through cut inside its letters, is now refused at `key` or at `matte` instead of passing with `status: ok`. Runs whose title carries neither key's hue pick the same key as before.
+
+- **A misreading is read once more before it refuses an image.** Before, each check read the image once, and one misreading refused it. A model reading stylised lettering can read the same picture two ways, so a correctly drawn title could be refused on one reading. Both checks use the one rule, `logo.read_text`. A call that fails is not asked again. With no reading before it, the check is `unverified` as before. With a misreading before it, the misreading stands and the image is refused. A refusal message names every reading, for example `the mood image reads ['IO'] and then ['I0'], not ['ION']`. docs/logo.md records a measurement on a synthetic pixel title drawn one stroke short (the Hangul syllable 쿠 drawn as 구, the middle bar of ㅋ left out). The codex reader at gpt-6-sol/high read it as 구 in 10 readings of 10 and never as 쿠, so neither one reading nor a check of two readings (0 of 5) passed the wrong picture. A second reading can only pass a wrong picture if the reader writes a stroke that is not drawn.
+- `logo.report.json`: `text_check.mood` and `text_check.logo` keep the deciding reading's `verdict` and `read` and gain `max_reads` and `readings`, each reading in order with its `reading` number, `verdict` and `read` lines, or `reason` when it could not be read. `calls` lists a check's call once per reading, each with `reading` (1 or 2) and `effort` (`null` where the provider names none).
+- Codex reader: the text checks run `codex exec --model gpt-6-sol -c model_reasoning_effort="high"`, named on each call, so a check's verdict does not change with the machine it runs on. Before, each machine read on its own config and the report recorded `model: null`. The values are `facing_vision.CODEX_READ_MODEL` and `facing_vision.CODEX_READ_EFFORT`. `--model` still names the images' model only. The facing check still runs on the login's config, unchanged. The xAI and OpenAI text checks read on their own fixed models, as before.
+- Python callers: `logo.read_text` returns `(check, calls)`, a list of call records, instead of `(check, call)`. `facing_vision.codex_inspect` takes optional `model` and `effort` keyword arguments. Without them its command line is as before.
+- **With `--chroma-key auto`, a key in the title's hue is not chosen.** `logo_matte.choose_key` rules out a key whose hue is 5 % or more of the title's box (`logo_matte.CLASH_HUED_PCT`), or 1 % (`logo_matte.NAMED_CLASH_HUED_PCT`) when `--style` or `--scene` names a colour in its hue (`logo.KEY_COLOUR_WORDS`: green, mint, lime, emerald, jade, chartreuse for green; magenta, fuchsia, pink, purple, violet, plum, orchid for magenta). A word alone never rules a key out; the pixels decide. The keys left are scored as before. When both keys are the title's colours there is no third: the run is refused at `key` (`refused_at: key`) before the lettering image is bought. The message gives each key's share and the brief's words for it and says to restyle the title without one of the two hues or to name the key to lose with `--chroma-key` (`--mood <mood.png>` skips the mood image). An explicit `--chroma-key` is kept; when it is one of the title's colours, a warning says so. Before, such a cut passed with `status: ok`, no warning, `key_hue_left` 0 and a matching text check.
+- **A cut that is see-through inside its letters is refused at `matte`.** `logo_matte.see_through_inside` measures see-through pixels (coverage under 240 of 255) walled in by opaque lettering and farther from it than the logo's own glow reaches beside it. Walled in means no way out to the picture's edge except across opaque pixels: the way out starts from the transparent pixels on the edge of the trimmed logo and runs through transparent pixels and see-through ones; a see-through gap of 2 px or narrower does not count as a way, a transparent gap of any width does. A hole joined to the outside, even through one pixel, is outside; a transparent hole walled in by the letters (an O's counter, or a letter colour cut all the way to nothing) is no way out, and a see-through patch round such a hole is still counted inside. Transparent pixels are never counted, only see-through ones. The same way out decides the glow's reach (`glow_reach_px`): the 99th percentile of how far the see-through pixels that have a way out to the picture's edge lie from the opaque lettering, and at least 2 px. On 1 % of the visible lettering or more (`logo_matte.INSIDE_MAX_PCT`) the logo is refused before its text is read, the cut is kept as `logo.rejected.png` and the preview is written. The message says to generate the lettering again on the other key or to restyle the title without that colour. Only the logo matte's own cut (`method: logo-unmix`) is refused; a lettering image returned with its own alpha is measured, not refused. A glow fades out beside the letters and pools in a counter no farther than it reaches there, so glows are not counted.
+- `logo.report.json`: `steps.key.scores.<key>` gains `named`, `clash_at_pct` and `clashes`, and `steps.key.key` is `null` when refused at `key`. `logo` gains `see_through_inside` with `px`, `pct_of_visible`, `glow_reach_px`, `max_pct` and `wide`. `refused_at` can now be `key`.
+- Python callers: `logo_matte.choose_key(mood, box=None, named=None)` takes `named`, the brief's colour words per key from `logo.named_colours(style, scene)`, and returns `key: None` when both keys are the title's colours. `logo_matte.see_through_inside(image)` is new.
+- **Tests**: `tests/gen/test_logo.py` checks that one matching reading is the whole check, that a misreading read again as asked passes at either check, that two misreadings refuse the mood image and refuse the logo and keep it aside with a refusal naming both, that a check reads no more than `MAX_READS` (set to 3, a third reading is taken), that a failed call is not asked again, that a misreading stands when the second call failed, and that the report names the reader model and effort of every reading. The existing refusal tests now script two misreadings. `tests/gen/test_vision_read.py` checks that codex reads on the named model and effort, passed before the image list, that docs/logo.md names both values, and that the facing check's command carries neither. `tests/frames/test_logo_matte.py` checks that a title in both keys' hues (synthetic patchwork letters: pink and plum in magenta's hue, mint in green's) gets neither key, that a colour in a key's hue rules the key out, that a colour the brief names rules it out at the smaller share while the same share unnamed and the word with no such pixels do not, that on green the mint patches are cut see-through and found inside (9.5 % of the visible lettering) while the other key keeps them and finds nothing, that six glow fixtures (a white glow, an outlined cyan glow, a cyan glow pooled in an O's counter on green and on magenta, an orange glow on green, pixel lettering) find nothing inside, that a mint patch walled in by a navy letter on green is still found inside, with the glow's reach at 2 px, when one or four squares of the key in it are cut to nothing, that a hole glued to the letter's edge is inside while sealed and outside once one pixel joins it to the key round the letter, and that big hollow O and A letters find nothing inside, plain or with a glow pooled round a counter whose middle stays clear (three glows). `tests/gen/test_logo.py` checks that a title in both keys' hues is refused at `key` before the lettering is bought, that a named key in the title's hue is kept and the warning says so, that a see-through cut is refused at `matte` and kept aside with no text check, with or without a 9x9 square of the key in the middle of its patch, and that a glowing title is not see-through inside. `tests/logo_lettering.py` gains the `quilt` fixture: square fabric patches in outlined pixel letters, one with a counter, on a key. It also gains `walled_patch` (a navy letter with a mint patch on pure green, with squares or a pixel of the key painted in) and `hollow_letters` (the big O and A shapes), which `lettering` draws through its new `shapes` argument.
+
+**Upgrading from 3.0.0:** Existing runs and commands do not change. This release adds two verbs and a JavaScript player. The wheel now also carries `sprite_gen/video/*.mjs`.
+
+- `sprite-gen video-face` builds a face pack from a reference, a keyed talking clip, and keyed body motions.
+- `sprite-gen face-bake` runs the pack's player through node to bake a voice onto body frames, with optional MP4 and beside video output.
+- Face request kind `sprite-gen-face-request`, version 1, records face geometry, clip placement, a rest loop, and optional own-mouth spans or timelines.
+- Face pack kind `sprite-gen-face-pack`, version 1, carries sprites, body cells, anchors, keeps, rules, a report, a copied player, and SHA-256 digests.
+- The lower-face layer covers the mouth, jaw line, cheeks, and chin. The body's own dark grey and black that reach in from the layer's boundary, such as a headset boom or a choker, the body's own lines in the layer's feather, and a hand that reaches over the face from outside the layer stay above it.
+- Each body frame receives a place, size, and tilt anchor. The pack records anchor residuals and corrects outlying readings against neighbouring frames. A body frame whose own mouth is closed has its place read again on a ring of skin round the mouth, because a head that turns moves its hair, headset, and cheeks further than its mouth, and a frame whose mouth is open takes the move of the read frames round it. The pack records each frame's move and the frames read on the ring.
+- Talking frames are assigned to smile or neutral sets by closed-mouth lift. Entry chooses a matching set and rest.
+- The player `sprite-gen-face-v1.mjs` contains the voice flap, face pick, scene plan, and live canvas playback rules.
+- A clip's own mouth and sound finish before a requested line starts. The voice and layer then wait together for the first frame whose switch to the chosen rest is within the 1.4 jump line. Layer exit also uses that jump line.
+- The live player keeps one queue of every `play` and `say` request, in the order the calls are made, and starts each request on the frame after the one before it has ended, so two voices never overlap. A line placed right after a clip with its own mouth is planned together with that clip, the plan `planScene` makes and `face-bake --play` bakes, and its voice and layer start at the plan's `line_start` after the own-mouth span. The queue has no length limit and drops nothing: a request whose sound does not load or decode, or whose line `planScene` refuses, rejects its promise when its turn comes, and the next request goes on.
+- Bakes check pack digests, changed pixels outside the weight, and composite jumps. Refused bakes retain their frames for inspection.
+- See [docs/face-parts.md](docs/face-parts.md) for the request, pack, player, commands, and limits.
+- **Tests**: `tests/video/test_face_layer.py` uses `tests/talking_face.py` to check smile and neutral sets; clip entry set and rest; own-mouth timelines, including a close during voiced sound and refusal of a missing or never-closing timeline; a head 60 px from its place and tilted 3 degrees; a head that turns, tilting up to 5 degrees about its mouth while its hair, headset, and cheeks move up to 12 px sideways and its mouth stays where it is, with two of its eleven frames open, whose anchor place is within 1 px of the mouth on closed frames and within 2 px on the two open frames and whose tilt is the band's, below minus 2.5 degrees where the turn is fullest; hand, headset boom, and choker keeps; a tongue in the body's own open mouth, joined to a hand by a finger at its corner, covered by the layer; unchanged pixels outside the weight; synthetic cells keeping the key's colour under no coverage; digests and new-folder pack writes; the player flap against its original numpy rule and the pick against the draft Viterbi over every frame; a line waiting for a clip's own mouth and for a frame its layer can come on at; the live player run by node on a fake audio clock, with two lines requested during a greeting's own mouth, three lines requested on the loop, one line requested during the own mouth and one after it, a line whose voice loads late, a line requested right after a clip whose sound loads late, a line whose voice loads only after the greeting's own mouth has ended or only after the greeting has ended, which waits for the greeting to end while the greeting plays to its end with the layer off, a line that plays on the loop when requested right after a clip whose sound fails to load, and a request that fails; loop and post-greeting bakes with greeting frames unchanged byte for byte; and refusal of a changed pack.
+
## v3.0.0 - Remove rig layer composition
**Upgrading from 2.46.0: `sprite-gen compose-layers` and its other launch forms are removed, and rig layer declarations are no longer read.** `compose-atlas` no longer writes a manifest `rig` block or `animation.rows.<state>.track` for a run that declared a rig. Runs that never declared `rig`, `layers` or a state `track` get the same manifest as before. Existing run files and `layers/` folders stay on disk.
diff --cc SKILL.md
index 0011aff,28eab0b..b11cb19
--- a/SKILL.md
+++ b/SKILL.md
@@@ -95,18 -115,16 +95,18 @@@ front-facing observations also remain u
| Continue or edit an existing clip | `video-extend`, `video-edit` | [video](docs/video.md) |
| A clip run left unfinished (its line or report names a `request_id`): ask for it again, never submit it again | `video-resume --request-id <id>` | [video](docs/video.md#sprite-gen-video-resume--ask-again-for-an-unfinished-generation) |
| Grok video sprites | `video-set` | [video-pipeline](docs/video-pipeline.md) |
- | A soft part of a walk loop sways with the body (the Sway layer; a chest, a belly): an ellipse in the first cell, after `video-cycle-align`, `--read-on <sha256>` where it was read on the cut the loop was aligned from; `--stretch-floor D` to keep a least area | `video-sway` (old name `video-follow`) | [video-pipeline](docs/video-pipeline.md#6-the-sway-layer--video-sway) |
- | Where that ellipse is carried in every other cell, and what the move changes there (an arm crossing a chest moves with it; the stretch, the bend and the seam): a record and boards of every cell, nothing moved | `video-sway-inspect` (old name `video-follow-inspect`) | [video-pipeline](docs/video-pipeline.md#inspecting-a-sway--video-sway-inspect) |
+ | A soft part of a walk loop or cycle frames sways with the body (the Sway layer): an ellipse after `video-cycle-align`, `--read-on <sha256>` for a cut, `--stretch-floor D` for least area, `--frames` for full frames, `--breathe` for the breath drive, a flat share to move a region whole, and `--gain-across` for across gain | `video-sway` (old name `video-follow`) | [video-pipeline](docs/video-pipeline.md#6-the-sway-layer--video-sway) |
+ | Where an ellipse is carried in every other cell, and what the move changes there (an arm crossing a chest moves with it; the stretch, the bend and the seam): a record and boards of every cell, nothing moved; a seam under a third moving region is not counted | `video-sway-inspect` (old name `video-follow-inspect`) | [video-pipeline](docs/video-pipeline.md#inspecting-a-sway--video-sway-inspect) |
-| A set's directions on one sheet, standing on one ground line (a 3×3 board, an engine import): rows in compass order S SW W NW N NE E SE from each loop's `--view`, one cell size, every row as cut, an optional centre picture (`--center`) at the rows' standing height; loops of different lengths are laid and said to differ (`same_length` false) — align the set first | `video-set-sheet` | [video-pipeline](docs/video-pipeline.md#7-one-sheet-for-a-set--video-set-sheet) |
-| A walk or run that stops, from the clip's own start played backwards: a one-shot strip (`loop: false`, `hold_last: true`), GIF, WebP and report beside the loop, ending on the still as filmed; leaves the loop from the cell nearest the entry (`from_cell`), drift taken out across the frames by a straight share; a seam past 1.4 steps (`--seam-max`), a run-up that comes back to a pose it left (another motion, however short) or one over 1.5 cycles (`--run-up-max`) refused; ghost screen checked, cells placed and anchored to match the loop's pivot | `video-stop` | [video-pipeline](docs/video-pipeline.md#8-a-walk-or-run-that-stops--video-stop) |
+| A set's directions on one sheet, standing on one ground line (a 3×3 board, an engine import) | `video-set-sheet` | [video-pipeline](docs/video-pipeline.md#7-one-sheet-for-a-set--video-set-sheet) |
+| A walk or run that stops, from the clip's own start played backwards | `video-stop` | [video-pipeline](docs/video-pipeline.md#8-a-walk-or-run-that-stops--video-stop) |
+| Build a talking lower-face pack anchored to every frame of body motions from a reference and keyed clips. | `video-face` | [face-parts](docs/face-parts.md) |
+| Bake a voice and the pack's face layer onto body frames, optionally after a clip's own mouth and sound. | `face-bake` | [face-parts](docs/face-parts.md#face-bake) |
| Compare the currently displayed loop with a final candidate, including after follow-through | `video-loop-compare` | [loop-comparison](docs/loop-comparison.md) |
| Restore post-processing damage in the current cut from its exact source times, preserving normal cells and playback | `video-source-manifest` → `video-loop-repair` → `video-loop-compare` | [source restoration](docs/loop-comparison.md#restoring-the-active-cut-from-source) |
-| Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크) | `video-canvas`, `video-prompt --no-last-frame`, the agent's own MCP tools (quote, user approval, generate, save the mp4), then `video-frames` and `video-loop` (a walk or run with `--anchor motion-auto`, which holds its size), and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories (a set it stops on a loop that may hold two cycles: look at that loop, count its strides, and pass `--cycles <loop>=<k>`; a loop the report lists under `unnamed_feet` — its view could not tell the feet apart, or only by too small a margin (`low-margin`): look at its first candidate frame, say which own foot lands there, and align again with `--foot <loop>=left|right`). `video-set` is not run on this route, so the set stage it runs by default (`--align-cycles auto`) is yours to run. sprite-gen never calls the MCP. Walk, run and jump only: ZCRE's `grok-imagine-video-1.5` has no end frame, so idle, attack and diagonal walks are refused unless `--unpinned` | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) |
+| Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크) | `video-canvas`, `video-prompt --no-last-frame`, the agent's own MCP tools (quote, user approval, generate, save the mp4), then `video-frames` and `video-loop`, and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories. sprite-gen never calls the MCP. | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) |
| Typography logo, wordmark or title lettering (로고, 타이포그래피, 타이틀 글자): the title lettered into a title screen or poster first, then only its lettering redrawn on a key and cut out with its glow; the text is read back and a misspelt logo refused | `logo --text … --style …` (`--mood` to start from a picture you have, `--lettering` to cut again for nothing) | [logo](docs/logo.md) |
| Ordinary image or edit | `gen --provider codex` or `gen --provider grok` (the subscription login first; without one grok uses `XAI_API_KEY`, and a codex signed in with an API key bills it — both per call, said on stderr) | [gen](docs/gen.md) |
-| Pixel art the model draws directly as a grid, 8–48 px (best at 32 or less): an icon, a prop, a monster, a character still, four directions, a walk draft, a tile, or a hand-drawn motion of up to 64 frames drawn four a call (`--motion`, `{name, pose}` frames, `--duration-ms`), in a style of your own (`--style`) — on your Claude subscription (`claude` signed in), or without one on `ANTHROPIC_API_KEY`, **billed per call**; `grid.txt` is the truth, `--grid` re-renders an edited one, `--resume` collects a batch instead of buying it twice | `pixel-draw` | [pixel-draw](docs/pixel-draw.md) |
+| Pixel art the model draws directly as a grid, 8–48 px, on your Claude subscription (`claude` signed in), or without one on `ANTHROPIC_API_KEY`, **billed per call** | `pixel-draw` | [pixel-draw](docs/pixel-draw.md) |
| Image generation with no login available (server, container, SaaS) | `gen --provider openai` — server/SaaS route on `OPENAI_API_KEY`, **billed per call**, never a default; it runs only when named, or when the user chose it for a codex that cannot run | [gen](docs/gen.md#subscription-first--openai-runs-only-when-you-chose-it) |
| Base and direction anchors | `anchor` | [directional-anchor-workflow](docs/directional-anchor-workflow.md) |
| Curation view or existing image candidates | `curation`, `unpack-atlas --pngs-dir` | [curation](docs/curation.md) |
diff --cc docs/video-pipeline.md
index a78eb9c,8605c4c..ddd1cf4
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@@ -567,12 -1336,38 +569,13 @@@ sprite-gen video-sway --frames set/fron
at the centre and 0 at the rim (cos²), sampled as premultiplied bilinear colour; outside it no
pixel changes. A move so large that the weight's slope folds the picture over
(offset × π / (2 · radius) ≥ 1) is refused: lower `--gain` or give the region larger radii.
+ A cell in which every region's offset is 0 is copied byte for byte, including colour under clear pixels; this holds for every sway, including `--gain 0`. A move clears that colour because the WebP check refuses it.
-- **`--on-fold lower`** lowers the gain for you instead of refusing, region by region. The move
- is the gain times the move at gain 1, so the gain at which a region folds is
- 2 · radius / (π · move at gain 1), and a region that folds at `--gain` takes the largest gain
- under that, in steps of 0.01; a region that does not fold keeps `--gain`. Every part hangs on
- the same body and answers the same motion, but how far a part can move before it folds is its
- own size, so a small part (an ear) does not hold a large one (a chest) back. No region goes under 1, the
+- **`--on-fold lower`** lowers the gain for you instead of refusing, region by region. No region goes under 1, the
mass as measured: one that would have to is **held** — it does not move at all, so a
follow-through is never quietly weaker than the motion it answers — and named, on stderr and in
- the record. The strip is refused only when every region is held (the message names the largest
- region and the largest gain that would not fold it). Where regions of different gains overlap,
- the larger move wins; the move there is nowhere steeper than either region's own, so nothing
- folds. A strip whose regions all take one gain — one region, or regions that fold alike, or
- none that folds — is written as one gain for the strip writes it, byte for byte, and its `gain` is
- then the `--gain` that gives this strip by itself. The default stays `refuse`, with the same
- message as 2.24.0; a strip that does not fold is the same under either.
+ the record. The default stays `refuse`; a strip that does not fold is the same under either.
- **What it writes**: the strip, GIF and WebP over the loop's own (both animations re-opened and
- checked as `video-loop` checks them), and `follow` in `<name>.strip.json` (the regions, the
- settings, the body's height in the first cell `body_px`, the first and last level it was worn
- down to `body_worn_px`, the body's bob `body_bob_px` (side to side, up and down), `dx_px`/`dy_px` per cell, `reach_px`; `gain` is the gain used and
- `gain_requested` the one asked for, and `fold` says whether it was lowered, the move asked for,
- the move at gain 1, and per region its smaller radius, how near the used move is to folding it
- (`ratio`, under 1) and the gain at which it folds). Where the regions took gains of their own,
- each region's entry also says the gain it moved by (`gain`, 0 when held) and whether it was
- held (`held`); the strip's `gain` is then the largest of them, `dx_px`/`dy_px` and `reach_px`
- are that gain's (a region moves by its own gain over that one times them), and `fold.ratio` is
- the nearest any region came to folding. A lowered gain is also named on stderr — per region,
- with the `--region` it was given, where they differ — and so is a held region; the printed
- summary then carries `region_gains`.
- All four are written and checked beside the loop first and moved over its files only once the
- record is written too, so a run that fails on the way — an animation that fails its check, a
- record that does not serialise — leaves the strip, GIF, WebP and record as they were.
+ checked as `video-loop` checks them).
`cycle/` is left as cut. The strip as it was is kept as `follow.source.png`; running
`video-sway` again reads from it, so a second run never moves a moved strip. `--board` writes the cells before and after where the part
sits lowest and highest, on white.
@@@ -602,6 -1431,48 +605,39 @@@ nothing of the source: a line there is
cut, give `--read-on` too: the floor is then read on the cut's motion, so a turned loop is lowered,
held or refused as the cut is.
-The floor holds the stretch, and only the stretch: what a move also does to a line — it tilts it,
-and where two regions overlap it bends it at their seam — lowers only as the gain lowers.
-`video-sway-inspect` writes all three (below).
-
-What carries a region into a cell is the lay of the body's outline (`carry_basis: {"reading":
-"outline-lay", "region": "unverified"}`). Two strips whose alpha is the same in every cell are
-carried alike, whatever moved inside the outline; whose pixels are inside a carried ellipse is not
-read, and nothing here moves a region on a guess of it.
-
+ #### A cycle's frames at their own size: `--frames <folder> --out <new folder>`
+
+ A loop's strip holds at most 64 cells and 32,000 px across. Cells 960 px wide allow 33 of them, so a cycle of large frames must be cut down to fit. The strip stays the delivery format; `video-sway --frames <folder> --out <new folder> [--fps F]` sways the full cycle before that cut.
+
+ - **The frames** are PNGs in name order, all one size, from a `video-loop` `cycle/` folder or the output of `sprite-gen breathe`. Regions are given in frame pixels. `--frames` and `--loop-dir` are alternatives, and one is required.
+ - **The output** contains the moved frames under their original names and `sway.json` beside them. The folder checks and whole writing are the same as `sprite-gen breathe`: real paths rule out an output equal to, inside, or containing the frames folder; the output must be new or empty; and unequal frame sizes are refused before anything is made. The command writes in a staging folder beside the output and renames it into place when complete. A failed run leaves nothing, and the frames folder is only read.
+ - **The move** uses `solve_cells` for both paths. A strip cut from these frames at scale 1, with no cell left out and each region moved by the crop origin `source_rect`, moves cell for cell exactly as the frames path does, byte for byte once cut back, at the frame time written in the strip meta. `--fps F` uses `round(1000 / F, 2)` milliseconds: 24 fps is 41.67 ms. The exact `1000/24` ms gives another sway.
+ - **The time** comes from `--fps` or, for a whole `video-loop` `cycle/`, from the loop strip meta's `cycle_seconds` and `cycle_frames`. A conflicting `--fps` is refused. The damped mass requires a frame time, so other frames folders need `--fps` unless `--breathe` supplies the drive. `--read-on` is refused with `--frames`; `--frames` requires `--out`; `--out` and `--fps` are refused with `--loop-dir`.
+ - **The record** in `sway.json` has `frames`, `frame_ms` (null on the breath), and the same record as the loop's `follow`, with `source` naming the frames folder. Body motion is read at the frames' full size by `body_motion`. Reducing them changes that reading and its offsets. On large frames, reading can take minutes. The old name `video-follow --frames ...` writes the same bytes.
+
+ #### On the breath: `--breathe <breathe.json>`
+
+ A breathing idle can move its body only a pixel or two while its head stays still. Reading the outline turns that motion into whole-pixel steps; the damped mass answers those steps, so the part barely moves at its default settings or sways to the steps when pushed further. `--breathe <breathe.json>` drives the part from the Breathe layer's breath instead.
+
+ - **The record** is the `breathe.json` written beside breathed frames. It supplies config, phases and `resolved.anatomy`. Only `mode: smooth` is accepted; a pixel breath is refused because its travelling wave moves the first cell. The config passes `state_breathe` checks, `fit_breathe_pattern` recomputes the phases and compares them with the record, and `frames`, the phase count and the swayed cell count must agree. A hand-written record is checked the same way.
+ - **The drive** uses the Breathe layer's own functions. Chest lift is `lift x w`, where `w` is `smooth_wave`, from 0 at rest to 1 at the in-breath peak, and `lift = depth x (anatomy height - basis_row)` is given by `breathe.smooth_lift`. The part follows the late curve `w_late = smooth_shoulder_wave`, whose time is warped by `t - lag x sin(π t)`. Its offset is `gain x lift x (w - w_late)`, against the chest's rise in the record's `chest_dir`; 0 points straight up, so that offset points straight down.
+ - **The rest** has `w = w_late = 0`, so the first cell, rests between breaths and the close have zero offset. On a synthetic loop, the step across the close is 3-4% of the largest inner step. The body's outline still determines each cell's carried ellipse.
+ - **The lag** is a share of one breath, above 0 and below `1/π`; its default is 0.15. At `1/π` warped time stops, and beyond it runs backwards. On a synthetic 144-cell loop at 24 fps with two breaths, lags 0.1, 0.15 and 0.2 reach 0.28, 0.44 and 0.59 of lift at gain 1. The part peaks 7, 11 and 14 cells late, or 0.29, 0.46 and 0.58 s. Reach depends on lag rather than breath length.
+ - **The settings and record** use a default `--gain` of 1 on the breath, against 2.5 on body motion. `--freq` and `--zeta` are refused with `--breathe`; `--fps` is refused with `--breathe --frames`; `--lag` requires `--breathe`. The record's `drive` carries `kind: breath`, `breathe_sha256`, `lag`, `lift_px`, `heading_deg`, and `breaths` or `breath_peaks` in place of `freq_hz`, `zeta` and `harmonics`. Its way is `common-lay/breath-late/cos2-bilinear/1`. `--loop-dir` also accepts this drive when its strip has one cell per phase.
+
+ ```bash
+ sprite-gen breathe <cycle> <breathed> --mode smooth --breaths 2
+ sprite-gen video-sway --frames <breathed> --out <swayed> --breathe <breathed>/breathe.json --region <cx,cy,rx,ry>
+ ```
+
+ #### A region moved whole, and across apart from down: `cx,cy,rx,ry,flat`, `--gain-across G`
+
+ `--region cx,cy,rx,ry[,flat]` gives a region an optional fifth number, `flat`, from 0 to 0.9. It is the share of the way from centre to rim that moves in full. Over the remaining distance the weight falls from 1 to 0 by cos², using the Breathe layer's `breathe.flat_cos2`. A large region weighted by cos² alone presses its outer part inward; one flat region can move the part whole instead of laying many small circles over it. On a synthetic chest, one flat region gave a least part weight of 0.82 and a mean of 0.99, against 0.84 and 0.97 for 112 circles, at a fifth of the move time.
+
+ The fold rule reads the radius left after the flat centre: the smaller radius x `(1 - flat)`. It folds at `offset x π / (2 x radius x (1 - flat)) >= 1`. `--stretch-floor` reads the least area as `1 - (π/2)/(1 - flat) x hypot(ox/rx, oy/ry)`. Both closed forms stay on the safe side of measured values by 0.004 to 0.013. The record's `fold.regions[i].radius_px` is that reduced radius. A `flat` of 0, or one left out, gives the four-number region's strip, record and inspection byte for byte. Values outside the range are refused.
+
+ `--gain-across G` sets the gain across independently; `--gain` then sets the gain down. Without it, across uses `--gain` as before, byte for byte. When `--on-fold lower` or the floor lowers a region's gain, its across move falls in the same proportion. The existing area rule reads moves with different across and down components and stays on the safe side by 0.0004 to 0.008. `--gain 0` with non-zero `--gain-across` is refused. The record carries `gain_across`, the across gain the strip's `gain` moved by, and carries `gain_across_requested` only when given.
+
### Inspecting a sway — `video-sway-inspect`
The ellipse is given in the first cell, where somebody looked. Into every other cell it is carried by the body's motion, and there nobody looked: an arm that swings across a chest is inside the chest's ellipse in those cells and moves with it, and so does a sleeve of the chest's own colour, which no count of colours finds. The Sway layer does not read what a pixel belongs to. `video-sway-inspect` (old name `video-follow-inspect`) writes what somebody needs in order to look, and moves nothing:
@@@ -609,9 -1480,19 +645,10 @@@
```bash
sprite-gen video-sway-inspect --loop-dir set/front-run/loop --region 136,164,60,50 [--region …] \
[--gain 2.5] [--on-fold refuse|lower] [--freq 2.4] [--zeta 0.6] [--read-on <sha256>] [--stretch-floor D] \
- --out-dir inspect/front-run [--scale 2] [--columns 8]
+ [--breathe <breathe.json> [--lag 0.15]] [--gain-across G] --out-dir inspect/front-run [--scale 2] [--columns 8]
```
-- **Asked as `video-sway` is, answered by the same code.** It takes `video-sway`'s arguments
- (all but `--board`), reads the strip as cut — `follow.source.png` where a follow-through was
- already written, the strip itself where none was — and solves it where `video-sway` does
- (`follow.read_request`, `follow.solve`): the carry, each region's gain, the offsets and the
- moved cells are computed in one place, and both commands read them there. What `video-sway`
- refuses it refuses in the same words under its own name, and then writes nothing.
- It takes `--breathe`, `--lag`, `--gain-across` and flat regions as `video-sway` does, and stays on a loop directory without `--frames`.
-- **The loop directory is read and never written**: not the strip, not its meta, and not the
- `follow.source.png` that `video-sway` keeps on its first run. An `--out-dir` at or under the
- loop directory is refused. Run before `video-sway`, it changes nothing `video-sway` writes.
++- It takes `--breathe`, `--lag`, `--gain-across` and flat regions as `video-sway` does, and stays on a loop directory without `--frames`.
- **What is inside an ellipse is not read.** Every region is written `ownership: "unknown"` in
every cell, the first included, from its centre to its rim; no cell is marked or held on a
guess. `solid_px` counts the body's silhouette under the ellipse (alpha ≥ 128), not whose