Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
Merge plan/loop-silent-pass-1021 (video-loop: a walk's every step is gated between its drawings, reading a pixel's jitter by its geometry; a frame left off the flow is named and --unfixed refuse fails it; a fixed cut is counted; the seam's refusal says why) into main, validated in sprite-gen/loop-silent-pass-1021
Soohong Kimbf6f31fd7628
diff --cc CHANGELOG.mdindex f1a6d3f,948a556..288c9e8--- a/CHANGELOG.md+++ b/CHANGELOG.md@@@ -2,469 -2,16 +2,477 @@@All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.-## Unreleased - The loop check inspects steps between drawings, checks fixed cut step counts, warns on unfixed repair frames, and explains seam failures+## Unreleased++**Upgrading from 3.0.0: Bakes retain the same bytes for figures whose anatomy is unchanged. The `pixel` refusal message now names the sides and pixel counts. A figure that had `face-absent` may now have a face, with a lower rigid boundary only when that face ends below the neck. `video-sway-inspect` records use schema 3, and a cell whose every offset is 0 is now copied as it was, including colour under clear pixels with `--gain 0`; the other changes add options, and without them the strip, records and inspection stay as before.**++The Breathe layer still supports `pixel` and `smooth`.++- **Changed: Pixel refusal.** `pixel` still refuses stretched content past the top, left, or right of a cell instead of cropping it.+ The message names each side and its opaque pixel count. A pixel past a corner counts on both sides.+ When an overflowing side is the drawing's own border, the message also gives the number of pixels covering that edge.+ It advises `--mode smooth` or sidecar `mode: "smooth"` for an illustration cut by its frame.+ It advises a wider cell margin or lower `depth` for a pixel sprite.+ It warns that padding, baking, and cropping back silently loses pushed off content.+ The curator preview uses the same refusal wording.+ The border reading follows the 2% rule in [video pipeline](docs/video-pipeline.md) section 3.+ See [breathing](docs/breathing.md) for behavior at frame edges.+- **New: Second eye pair search.** It runs only when the existing search finds no pair.+ Its minimum eye area is 0.2% of opaque pixels above the neck.+ Its eye width to height limit is 3.0, and its minimum eye center distance from the body axis is 0.02 of content width.+ Pair placement, separation, size similarity, and row overlap conditions remain the same.+ A face found by this search clears `face-absent`. It lowers the boundary only if the face ends below the neck.+- **Faster: Breathe bakes.** Array operations speed up pixel outline thinning, appendage weights, and row mapping.+ `smooth` solves displacement only for pixels that move.+ Anatomy and settings checks run once per row, and `sprite-gen breathe` shares one anatomy measurement between its report and bake.+ On synthetic 960 x 960 cells with Apple M1, bake time fell from 0.20 s to 0.10 s for `smooth`.+ For an outlined figure with arms in `pixel`, it fell from 0.98 s to 0.05 s.+ These measurements exclude PNG reading and writing.+ `bake_breathe_sequence(images, cfg, anat=None)` and `anatomy_report(images, cfg, anat=None)` accept measured anatomy.+ `protect(anat)` accepts one column or an array of columns.+- **New: Sway on a cycle's frames.** `video-sway --frames` moves full-size frames and writes them with `sway.json` to a new folder.+ A whole `cycle/` can supply its frame time; other damped-mass runs require `--fps`.+- **New: Sway on the breath.** `--breathe` drives the move from a checked smooth `breathe.json`, with `--lag` setting how late the part follows.+ The first cell, rests and close have zero offset.+- **New: A region moved whole.** A fifth `--region` number, `flat`, keeps the centre at full weight before the weight falls to the rim.+- **New: Across apart from down.** `--gain-across` sets the across gain separately from `--gain`, which sets the gain down.+- **Changed: Zero-offset cells.** A cell where no region moves is copied byte for byte, including colour under clear pixels.+- **Changed: Inspection seams.** `video-sway-inspect` drops a pair's seam points covered by a third moving region.+ Its record uses `schema_version` 3.+- **New: Breathe beat chosen to miss the hands.** In `smooth` mode, `--avoid-region` chooses a breath beat whose peaks keep the chest above the hands' own rise and records the choice in `breathe.json`.+- **Tests:** `tests/effects/test_breathe.py` checks border counts, advice, smooth edge preservation, and the second face search.+ `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.++**Upgrading from 2.45.3: This release changes defaults for video frames.**++Outputs that change bytes are frames from `video-frames` and `video-set` on a green or magenta key.+These changes occur within 6 px inside the keyed silhouette only.+Video frames keyed with explicit `--decontam palette` also change bytes, because they use the same video fit.++Outputs that do not change bytes include runs on a white key, subjects with no interior, and runs with `--alpha-mode brightness`.+Stills (`cutout`, `gen`) and row extraction (`extract`, `inspect`) do not change bytes.+Runs with `--decontam off` also give the 2.45.3 bytes back exactly.++To get the 2.45.3 frames back, pass:+`--decontam off`++- **Default change: `video-frames` and `video-set` now default to `--decontam auto` (before: `off`).**+ This release updates these defaults to clean chroma-bleed edges automatically.++ On a chroma key, H.264 4:2:0 chroma mixes key colour into strands one to three pixels wide.+ With decontamination off, a red hair strand on green keeps an olive rim.+ The `auto` pass restores the subject's own colour to those edges.++ The video default stayed `off` until now out of caution rather than any known defect.+ The pass was benchmarked on a green key only.+ The video fit is less decisive than the still fit.+ In the documentation's benchmark table, the video-fit row (10.8 % residual contamination, 9.38/8.73 halo, 91.4 % recall) was measured in September 2026 with flank recovery.+ It has not been remeasured since flank recovery was dropped, because those benchmark inputs and tools are not at hand.+ The diagnosis table in `docs/chroma-alpha.md` (its `decontam` section) has the current video fit's numbers.+ Still-fit rows in that table are unchanged.++ Earlier fixes resolved the Grok-magenta regression through the key-hue cap and corrected the frame-edge interaction.+ No blocking defect remains known.++ On synthetic diagnosis clips (CRF 18, `--spill small`, 6 frames, one machine), `auto` reduced key contamination on red strands on painted green from 24.2 % to 10.2 %, and on pure green from 27.4 % to 10.9 %.+ Halo composite error on dark and white backgrounds shifted from 11.6/12.1 to 9.6/10.1 on painted green, and from 12.0/11.9 to 10.0/9.9 on pure green.+ Strand recall stayed at 91.4 % on painted green and 92.4 % on pure green.+ Strand recall no longer rises with the pass, because that gain came from the flank that the video fit no longer recovers.+ Halo gains are smaller than before for the same reason.+ On these moving scenes, key contamination is about one point higher than with the hold and settle alone, because a change of call now takes a few frames to reach the fit's colour.++ Key contamination dropped from 3.4 % to 0.5 % on magenta, and from 5.4 % to 1.8 % on Grok darker magenta.+ Halo shifted from 15.0/19.6 to 12.7/16.4 on magenta, and from 20.7/31.5 to 19.3/30.0 on Grok darker magenta (compared to 17.1/24.7 when flank recovery was present).+ Strand recall shifted from 87.0 % to 86.9 % on magenta and from 73.3 % to 73.2 % on Grok darker magenta.+ Outline ink CIELAB error shifted from 19.3 to 20.2 on magenta, and from 21.7 to 22.6 on Grok darker magenta.+ Red hair counts as key-coloured material there, so the palette is not key-free and the warning line appears.++ Contamination dropped from 20.6 % to 8.8 % on a translucent glow scene (halo 12.6/9.4 to 11.7/8.5, strand recall 85.7 % to 85.4 %).+ It dropped from 23.8 % to 11.4 % on a small green charm scene (halo 11.8/12.9 to 10.0/11.1, strand recall 90.7 %).++ Changed pixels make up about 2.4 % of each frame (4.7 % in translucent scenes).+ All changed pixels lie within 6 px inside the silhouette.+ Nothing outside the silhouette changes any more.+ Interior pixels remain byte-identical.++ Stills (`cutout`, `gen`) and row extraction (`extract`, `inspect`) still default to `off`.+ The row extractor frames are a derived cache that `heal` re-derives, so changing their default would silently rewrite existing runs.+ Stills remain as they were.++- **Temporal fit: The video fit holds edge decisions across frames, blends a change of call over frames, settles still pixels, and drops flank recovery.**+ With default `auto`, the edge of a subject standing still sparkled from frame to frame where `--decontam off` remained calm.+ Codec noise pushed edge pixels across the pass's threshold tests from frame to frame.+ These tests decide blends, tints, material behind, explained pixels, palette colours, and flank coverage.+ Each crossing changed the written colour by far more than the noise itself did.+ The raw matte with `off` follows codec noise smoothly, staying calm despite keeping an olive rim.++ `video-frames` and `video-set` now maintain a clip history in clip order.+ This history passes to each frame through `decontaminate` as `history` (`decontam_history` in `cutout` and `remove_chroma_background`).++ Each test now holds its previous outcome at that pixel until current evidence passes the bar the other way by 16 (an RGB distance, `VIDEO_HOLD`).+ A palette colour picked in the previous frame stays unless another colour's line passes closer by 16.+ Moving pixels change their evidence far beyond 16 and are decided afresh.+ Only near-threshold calls stick.+ With the hold alone, a call that did change could still move a still edge through the whole gap between the matte and the fit in one frame.++ The blend mixes two renderings made from this frame's evidence at every pixel the pass examines.+ One is the matte with its key hue capped, and the other is the fit's palette colour at the pixel's light, with the fit's coverage where the call refits coverage and the matte's coverage elsewhere.+ For a palette-colour change, the fit's rendering mixes the two colours' renderings.+ A new palette colour waits until the change in hand is done, while a return to the old colour turns that change around.+ The mix moves toward this frame's call by at most 0.2 a frame (`VIDEO_BLEND`).+ It moves less if needed to limit the output change to 4 (`VIDEO_STEP`) plus 0.25 (`VIDEO_STEP_MOTION`) per unit the source moved, measured in premultiplied colour or coverage across its 3x3 box.+ A pixel new to the band starts at its call if it was transparent in the previous frame, and otherwise starts from the matte.+ Both renderings follow a moving subject at once; the change of call is spread over frames.++ A still pixel whose mix moved, has not reached its call, or came into or left the band moves at most 4 a frame from its previous output, measured in premultiplied colour and coverage.+ Here, still means its source moved by at most 8 in any channel anywhere in its 3x3 box (`VIDEO_STILL`).+ A pixel the hard cut keyed in this frame stays transparent.++ Still pixels settle toward the current fit when their mix is at its call in both frames.+ When a pixel was written in both frames in the same palette colour, and its source is still, it settles.+ It moves a tenth of the way (`VIDEO_SETTLE` 0.1) toward this frame's fit and stays within 12 per channel (`VIDEO_SETTLE_REACH`) of it.+ When it must catch up to get within 12, it now moves at most 4 a frame in premultiplied colour and coverage instead of moving all at once.+ This dampens codec noise while following real slow changes within 12 levels.++ The video fit also drops flank recovery.+ It no longer gives coverage back to keyed pixels (hard cut background within 3 px of the subject).+ Decoded chroma blur created faint blends on keyed pixels, and codec noise carried them back and forth over the noise floor.+ This filled dark gaps between strands with a faint smear that came and went across frames.+ The video fit now examines the band only (subject pixels within 6 px of the keyed background).+ The still fit keeps its flank recovery unchanged.++ With history enabled, frame bytes depend strictly on previous frames in clip order and remain deterministic.+ A single video-fit call without history gives the same band bytes as before, leaving keyed flank pixels as the matte keyed them.++ On a synthetic still scene under decoder noise (red strands 1 to 3 px wide on painted green, 8 frames, sigma 2):+ Mean edge change between frames on a dark background was 2.34 with `off` (99th percentile 8.3).+ With the hold and settle alone, the mean was 2.27 (99th percentile 8.3).+ With the blend and still steps, the mean is 2.25 (99th percentile 8.0).+ Key contamination on that scene was 6.5 % with `off`, 2.3 % with the hold and settle alone, and 2.4 % now.++ On a second synthetic scene, decoder noise changed between two frames and the source then stayed still for 19 frames.+ With the hold and settle alone, changed calls appeared in one frame and their pixels stopped moving when the source stopped.+ Now those edge pixels keep moving toward their new calls, by no more than 4.31 premultiplied a frame including uint8 rounding, and arrive by frame 14.++ Per-frame stats and clip totals include `held_px`, `blending_px`, and `settled_px`.+ `held_px` counts pixels where a held outcome or colour differed from an independent fit.+ `blending_px` counts pixels showing a mix of two calls rather than this frame's call.+ `settled_px` counts pixels the settle or a still step moved from the previous frame's output.+ In video, `recovered_px` is now 0.++ Keying cost was remeasured on an Intel i5-7500 with a 1080x1920 synthetic clip at CRF 18 and `--spill small`, six frames, one process per run, in the same session.+ Keying took 1.14 s a frame with `off`, 3.25 s with the hold and settle alone, and 3.36 s now.+ Peak memory was about 400 MB with `off`, 945 MB with the hold and settle alone, and 1155 MB now, adding about 365 MB over `off` per megapixel.+ Because `video-set` keys three items at once by default, it can use about 2.3 GB more than `off` at that size.++- **Guards: Two new guards protect key-coloured details and material behind edges in the video fit.**+ The still fit output is unchanged byte for byte, but explicit `--decontam palette` runs in video also use these guards.++ The key-coloured parts guard protects small details that share the key colour.+ A subject can own a key-coloured part too small for the palette to keep, such as a green charm on red hair under a green key.+ When such a part covers under 0.5 % of the interior, the palette learns key-free colours.+ Without the guard, the pass repainted the rim in the nearest key-free colour, turning the green charm's rim brown.++ Now, when the palette is key-free, band pixels within 6 px of such a part keep the matte's bytes.+ There is no flank in video any more, so this guard covers band pixels only.+ This applies to pixels near parts that are opaque, deeper than 6 px, and have key hue above 8.+ The key-hue cap leaves those pixels alone.++ On synthetic tests, the share of the charm's key-coloured edge pixels that lost half their key hue or coverage was 0.77 with `off` and 0.82 now.+ Its colour error was 41.7 with `off` and 45.6 now (64.9 without the guard in the diagnosis).++ The material-behind guard preserves edges where subject material continues to the silhouette boundary.+ A band pixel keeps the matte's bytes when its colour, observed directly or at its own luma, falls within the opaque margin of the mean colour of subject pixels right behind it.+ This check reads subject pixels deeper than 2 px within a 3 px box radius.+ Such pixels are treated as material continued to the edge rather than blends or tints.+ The key-hue cap still applies to them.+ Unlike the still fit, this guard does not require the pixel to be free of the key's hue, because decoded chroma blur gives every edge some key colour.++- **Diagnostics: A one-line stderr warning and new report fields track skipped frames and guard activity.**+ `video-frames` prints a single line on stderr after its JSON summary when edge decontamination warrants attention.+ The line starts with `video-frames: warning: decontam auto ...` and ends by naming `--decontam off` as the way to keep the matte as it is.++ The warning prints when `auto` ran on no frames, when `auto` skipped some frames, or when the subject owns key-coloured material so the palette is not key-free.+ On magenta keys, the red hair's blue channel sits more than 8 above its green, making the hair key-coloured material (9.6 % of the interior on magenta and 6.6 % on Grok's darker magenta) and triggering this warning.+ The warning also prints when the key-coloured part guard kept edge pixels, reporting how many and noting that thin details farther out may be repainted.+ A few key-hued pixels deep inside from codec noise guard no edge and raise no warning.+ Brightness alpha raises no warning.+ `video-set` prefixes this warning line with the item name and records it under `warnings` in the set report.++ The JSON report adds `decontam.reason` for the first skip reason and `decontam.skipped_frames` when frames are skipped.+ Per-frame stats and clip totals in the video fit add `key_part_kept_px`, `behind_kept_px`, `held_px`, `blending_px`, and `settled_px`.+ Where `auto` cannot run, frames remain exactly as the matte keyed them.+ The report records "the white matte has no key colour to remove" for a white key.+ It records "no interior to learn the subject's colours from" when no pixel lies deeper than 6 px inside the silhouette.+ Under `--alpha-mode brightness`, `auto` defaults to off, recording `{"mode": "auto", "applied_frames": 0, "reason": "brightness alpha has no key colour to remove"}`.+ Explicit `--decontam palette` with brightness alpha remains refused.++ Known limits apply to this release.++ The hold works on pixels that stay put.+ A change of call on a still edge arrives at most 4 a frame.+ The largest change, between the matte's full coverage and a faint fit, can take up to about 64 frames, or about 2.7 s at 24 fps.+ Until it arrives, the edge shows a mix of the matte's colour and the fit's.+ A strand that moves is decided afresh in every frame, while its change of call is spread over a few frames and both renderings follow it.+ A moving edge still changes from frame to frame as its colour does, so a red rim moving over a dark background changes more than the olive rim `off` leaves.+ Pixels whose call changes show a mix of the two calls for a few frames.++ The settle follows a slow change within 12 levels per channel and catches up past that at most 4 a frame.++ The video fit gives back no coverage the hard cut keyed.+ Outer pixels of a soft edge that the cut erased stay erased.+ Only on stills, outside a dark outline the flank can give a few faint pixels in the subject's colour.++ A thin feature whose colour is absent from the interior can be read as a palette colour plus key.+ For example, a thin yellow line beside red hair with a pink highlight turned pink (colour error 26.2 with `off`, 47.5 now).+ `--decontam off` keeps that line.++ A thin key-coloured detail farther than 6 px from any key-coloured interior is repainted in a palette colour.++ The thinnest strands retain some olive because decoders share chroma across aligned 2x2 blocks, leaving a one-pixel strand with half the key's chroma.+ A block-aware fit is planned separately.++ Pixel-art rows binarizing alpha, the green-only benchmark, and increased processing time and memory remain known limits.++- **Tests**: `tests/frames/test_chroma_decontam.py` checks that both video verbs default to `auto` and that still verbs and the row extractor do not.+ It checks that `off` gives the engine's original bytes.+ It checks that `video-set` hands its value to `video-frames` and lists the warning.+ It checks that a white key, a subject with no interior, and brightness alpha give the same bytes as `off` with the reason.++ A new section tests the video fit over time on the red-strand scene standing still while decoder noise changes every frame (luma per pixel, chroma per aligned 2x2 block, eight frames).+ The default's edge changes from one frame to the next no more than `off`'s, in mean and at the 99th percentile.+ The edge is still cleaned, with key contamination at most half of `off`'s.+ Clip totals count held and settled pixels, and the first frame has none.+ A frame given twice comes out with the same bytes both times.+ Another test decodes one frame of the red-strand scene, then holds a second noise draw (sigma 3) still for nineteen frames.+ After the source stops changing, the default keeps moving toward the calls the noise changed.+ No pixel moves more than `VIDEO_STEP` in one frame in premultiplied colour or coverage, plus one for uint8 rounding.+ It arrives by the last frame.+ Clip totals count `blending_px`, and the first frame has none.++ The video fit leaves every pixel the hard cut keyed transparent and recovers nothing.+ The still fit still recovers its flank.++ Changed tests reflect dropped flank recovery in video.+ A head 6 px under the top frame edge passes the edge gate under the default and keeps the blur rows below the edge band as the matte keyed them.+ For magenta skin tone in a 4:2:0 frame, the video fit's halo is read on the band where it acts (at most 0.9 of `off`'s), and the keyed flank keeps the matte's bytes.+ The still fit keeps its halved halo.++ The rim of a small green charm keeps the matte's pixels and loses at most 0.1 more than `off` while strands away from it are cleaned.+ On magenta and Grok magenta, halo and alpha error do not rise.++ A few key-hued pixels deep inside raise no warning.+ `video-frames` prints the warning line on stderr.++ `tests/video/test_gait_guard_anchor_wide.py` has its stand-in for `run_frames` take `decontam` and checks that the set's `auto` reaches it.+ **Upgrading from 2.45.3: Every cut 2.45.3 passed that neither new reading refuses gives the same loop files byte for byte.** Strip, sidecar, frames, GIF and WebP bytes match with the same stderr save new warning lines, measured on a batch of walk clips cut with caller arguments (the automatic walk cut, cuts by hand, forced cuts). The report gains `step_gate` on walk or run loops and `cycle.step_count` on fixed walk or run cuts, `producer` names the new version, and the CLI summary gains `step_gate`, whose `jitter` names the frames entered by steps over 2.5 that are a pixel's jitter, along with `jump_repair.unfixed`. Refusals outside the new readings keep their lines word for word, except the seam line's end where warning lines name a part on a beat of its own. Callers matching failure lines by first words need rules for `video-loop: loop step ratio` (the clip jumps inside: film again), `video-loop: loop step count refutes the fixed cut` (cutting again by hand failed), and `video-loop: loop frames left off the flow` only if passing `--unfixed refuse`; failure reasons can also be read from `seam_refusal`. Any `--seam-max` past 2.5 lifts the step gate and count refusal, so forced delivery keeps passing `--seam-max 1000`. Reading feet on a fixed walk or run cut costs less than the distance matrix read by every cut. As a known limit, the seam gate and the body anchor's rule from 2.45.3 still read frames, not drawings, so a walk held on twos or threes whose cut wraps between two drawings is still refused where it closes between its drawings.++ - **Behavior change: Walk and run loops that play round now pass a step gate that inspects spacing between drawings.** After the seam gate, cells are read between drawings rather than frame by frame, so held animation on twos or threes does not appear uneven when drawings span multiple frames. The largest step from one drawing to the next, the wrap included, over the mean of the others, must be at most `STEP_RATIO_MAX` (2.5), else the loop fails with `video-loop: loop step ratio <ratio> exceeds 2.5 (<kind> length <L> frames from <start>, into frame <frame>, read between its <n> drawings); the loop jumps inside — regenerate the clip`, with jump repair reason `: frame <frame> lies off the walk's flow, and the jump repair's frame there was refused (<faults>), so it plays as filmed` before ` — regenerate the clip` where present. A step over 2.5 is exempt from the bound when it is a pixel's jitter (`loop.step_jitter`): the move that aligns its drawing with the previous drawing with the least coverage difference, measured on alpha so colour has no effect, is at most `STEP_JITTER_PX` (1.5) pixels of the frames as filmed, and the step with that move taken back is within 2.5 of the mean. In a walk going away from the camera, foot rises of a whole crop row measure 2.5 to 3.6 times the mean as drawn, black or grey, but move one pixel and pass without a warning line. One frame of a 400 px tall walk cut moved 6 px and back moves 2 pixels of the frames as filmed, and the gate refuses the loop in every colour, including black. The report records `step_gate` on every walk or run loop (`drawings`, `hold`, `mean_step`, `largest_ratio`, `largest_from`, `largest_into`, `wrap_ratio`, `max`, `jitter`, `lifted`, `kept`; `skipped` for fewer than three drawings). The bound is the larger of 2.5 and `--seam-max`, so any `--seam-max` past 2.5 lifts it; a scan or forced delivery with `--seam-max 1000` keeps a loop whose largest step is over 2.5 with warning `video-loop: warning: the loop's largest step between drawings is <ratio>x their mean (into frame <frame>), over 2.5: it jumps inside — kept, as --seam-max <seam-max> lifts the step gate` and `step_gate.kept`.+ - **Behavior change: Fixed cuts fail when foot crossings count an odd number of steps.** Manual walk or run cuts using `--cycle fixed` now read the clip's foot crossings and evaluate the cut, matching `--anchor motion-auto`. The report records `cycle.step_count` with `chosen_by: caller`. A cut counted an odd number of steps fails with `video-loop: loop step count refutes the fixed cut <start>/<L> — the clip's crossings count one step, each seen where a walk loops on two, and an odd count swaps the legs at the wrap; cut it again two steps long (about <2 steps> frames)`. An even count is not refused by the count check, and the exemption `--anchor motion-auto` makes for a pass hidden among feet held together (the clip a cut on the same picture) applies identically through shared `local_cycle.same_picture_count`. The strip is unchanged, and there is no `steps` field. Any `--seam-max` past 2.5 lifts this refusal; a scan or forced delivery with `--seam-max 1000` keeps an odd step cut with warning `video-loop: warning: the clip's crossings count the fixed cut <start>/<L> one step, each seen: a walk loops on two steps, and an odd count swaps the legs at the wrap — kept, as --seam-max <seam-max> lifts the step gate` and records `cycle.step_count.lifted`.+ - **New: Refused jump repair drawings are listed in `jump_repair.unfixed` and can fail the command.** When jump repair refuses a frame group, its frames remain as filmed; where the playing loop still reads a drawing of it 3.0 or more of its window's usual steps off the flow, that drawing is recorded in `jump_repair.unfixed` alongside `refused` (the faults). Every `unfixed` drawing prints warning line `video-loop: warning: frame <frame> of the loop lies <off>x its window's usual step off the walk's flow after the jump repair: the group that would bring it back was refused (<faults>), so it plays as filmed — a jump played as filmed; --unfixed refuse refuses such a loop (docs/loop-repair.md section 2)`. A new flag `--unfixed warn|refuse` (default `warn`) controls handling: `refuse` fails such a loop with an error line starting `video-loop: loop frames left off the flow — `. This failure is not lifted by `--seam-max`.+ - **Fix: The seam gate failure line explains the cause where warning lines know it.** The first words of the failure line stay the same up to `the cycle does not close — `; where warning lines name a part on a beat of its own (an `--anchor motion-auto` cut two steps long by the clip's crossings whose wrap the gate refuses), the rest says so and names what became of the overlapped wrap, for example `video-loop: loop seam ratio <ratio> exceeds 2.0 (periodic length <L> frames from <start>); the cycle does not close — the cut covers two steps by the clip's crossings, and a part on a beat of its own (a tail, a held prop) closes on no cut of two steps: the overlapped wrap was not made (turned off (--overlap-wrap off)) — regenerate with that part moving on the walk's beat`. Elsewhere the line is word for word as before. Every refusal by the wrap, steps, or count records `seam_refusal` in the report (`reading`: `wrap`, `steps` or `count`). For `wrap`, it records `ratio`, `max`, `reason` (`own-beat` or null), and `overlap_wrap`. For `steps`, it records `ratio`, `max`, `into`, `reason` (`repair-refused`, `unfixed` or null), plus `frames` and `refused` where a reason was found. For `count`, it records `cut`, `verdict`, `k`, `why`, and `two_steps`.+ - **Tests** — `tests/video/test_loop_silent_pass.py`: a side walk in place with a middle frame moved 10 px fails the step gate while its wrap passes, recording `step_gate` and `seam_refusal`, kept by `--seam-max 1000` with a warning line; an eight drawing walk on threes passes when frame by frame steps exceed 2.5; melted ponytail outlines and smeared stand in RIFE frames stay `unfixed` with faults, cite the refused frame in step gate lines, and fail under `--unfixed refuse`; CLI tests confirm `--unfixed` defaults to `warn` and rejects other words. Hand cuts fail on one step, pass at two, keep one step cuts under `--seam-max 1000`, and exempt hidden far feet on twos. A walker whose tail swings on its own beat fails seam checks with the reason in its line and `seam_refusal`; a sideways wrap shift keeps its line word for word with `seam_refusal.reason` null. The walk going away from the camera passes with foot rises of a whole crop row as drawn, black and in a grey near the backdrop: its steps over 2.5 times the mean move one pixel and are recorded in `step_gate.jitter`. A standing side walk with a frame moved 2 px and back fails on that step as drawn, black and in that grey, with every frame's alpha the same. In `tests/video/test_body_anchor_gate.py`, the sliding side walk with its first frame moved 3 px is refused on the step into frame 1: those 3 px take up the sideways slide at the wrap and put the jump inside the loop. The seam still reads the source frames and is not read again.++## 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.++### Breaking++The rig layer feature has no replacement in 3.0.0:++| Removed | Use |+|---|---|+| `sprite-gen compose-layers`, `python -m sprite_gen.compose.compose_layers`, `scripts/compose_layers.py` | No replacement. The CLI verb now ends as an unknown command with argparse exit code 2. |+| `sprite_gen/compose/layers.py` (declaration checks for rig profiles, row tracks and composite stacks), `sprite_gen/compose/compose_layers.py` (baking declared stacks into `<run>/layers/`) | No replacement. |+| `sprite-request.json` keys `rig`, `layers` and `states.<state>.track` | Remove them with `sprite-gen migrate-request <run> --apply`. |+| `sprite_gen.spec.runio.normalize_retired_fit_keys` | `normalize_retired_keys`, which returns a list of keys moved or left out, or an empty list. |+| `docs/layer-tracks.md` | No replacement. Its links are gone from the other docs, READMEs and `SKILL.md`; the skill description no longer lists "rig layers". |++- `prepare` drops the retired keys from `--request` and `--request-json`, naming them in its existing stderr note. Code no longer reads them. On the first read of an old run's request, the process prints one stderr line naming the keys, treats them as absent in memory and leaves the file byte for byte unchanged. Unrelated request rewrites, including reroll and interpolate takes and curation fps edits, preserve those keys as they were.+- `sprite-gen migrate-request <run>` lists the keys it would remove without writing. `--apply` removes them from the file; a second apply has nothing to move. The changed bytes move `run_revision`, and the command names the curation rows it will drop before writing. The command also retains its existing `fit.pixel_perfect` to `fit.pixel_unfake` migration. `runio.migrate_request_file` now returns the list of keys moved or left out instead of a boolean.+- Talking face parts are planned as a new feature in a later 3.x minor release.+- **Tests**: Added `tests/spec/test_request_retired_rig_keys.py` to check the one-time stderr note and unchanged old request bytes, migration dry runs and repeated applies, preservation on unrelated edits, and named drops in `prepare`. Removed `tests/compose/test_layer_compose.py`, `tests/compose/test_layer_contract.py` and `tests/packaging/test_layer_cli_entrypoint.py` with the feature.++## v2.46.0 - Changed loop and framing defaults, recognition of cyan or yellow leaning green border keys, Breathe smooth mode and Sway commands++**Upgrading from 2.45.3: Some existing runs produce different bytes because defaults changed.**+`video-loop --cycle pinned` with `--anchor none` now blends the wrap when the pin passes its gate and the pinned last frame redraws the first.+A redraw means the first cell differs from the pinned frame by more than `--seam-max` (default 2.0) times the cut's median step at full size.+Those cuts have different `cycle/` cells over the last half second, and a different strip, GIF and WebP.+`video-set` takes this default for idle and attack clips filmed with their first frame as the last; a walk or run cut the same way is blended too.+The blend does not read the state, and `--wrap-blend off` cuts as filmed.+Every pinned cut gains the report key `wrap_blend`, which also appears in strip metadata where the blend applied.+A source projection reads a blended strip as `source-processing-unsupported`.+Under `--repair auto` or `--repair on`, a loop that is not a walk or run and is cut to play as a loop now has its wrap read against the steps beside it.+This excludes `--cycle once`, `once-return` and an effect's lifetime.+When the wrap step exceeds `--seam-max` times the mean of the three steps on either side and exceeds 0.005, RIFE makes one, two or four frames round the wrap again.+Such a loop can have different cells, strip, GIF and WebP, or pass where 2.45.3 refused it.+Its report now reads `jump_repair.reading: "seam"` instead of `"why": "not a gait state (...)"`.+Without RIFE, a wrap needing the bridge is cut as filmed and a `warning:` line names `sprite-gen rife install`; with `--repair on`, the run is refused.+The bridge reads the wrap after the blend, so a pinned idle or attack can receive both.+A pinned clip whose pin the gate refuses is not bridged and is refused on its pin as before.+Walk and run loops retain their 2.45.3 bytes except when cut pinned with `--anchor none` and a last frame that redraws the first; `--wrap-blend off` restores those bytes.+For a loop that is not a walk or run, `--repair off --wrap-blend off` restores the 2.45.3 cells, strip, GIF and WebP, with `"why": "--repair off"` in the report.+Do not use `--repair off` to restore a walk or run: it also disables the jump repair that ran by default in 2.45.3.+The default `video-frames` edge check (`edge_policy`) is now `border` instead of `refuse`.+A clip whose first-frame subject covers at least 2 % of the outermost row or column on the top, left or right now passes where 2.45.3 refused every frame as "framed too tight".+If the first frame crosses no side, it is judged and worded as in 2.45.3; `--allow-subject-edge-contact` and `--allow-edge-contact` also judge as before.+In a refusal, the top, left and right numbers now count pixels the border does not take.+The `video-frames` report gains `edge_border`, and each contact row gains `rim`.+A refused `video-frames` run leaves frames in `keyed.refused/`, removes `keyed/` even from an earlier run, and writes a report with `status` set to `passed` or `refused`.+A refused `video-loop` run removes an earlier cut's `cycle/`, strip, strip metadata, GIF, WebP, `cycle.source/` and `follow.source.png` from the output folder; a cut already written is kept as `cycle.refused/`.+A passing run delivers the same bytes as before, while a caller that misses a refusal's exit code no longer finds an earlier run's files.+Borders already recognised as a green key in 2.45.3 key byte for byte as before under the same key.+A border green leaning toward cyan or yellow, such as `#00B140`, now uses the green key: `cutout --key auto` and `video-frames` use it instead of the position-based white matte, `video-canvas` repaints such a still to the exact key and accepts `--key green`, and `video-frames --spill auto` reads it as `full`.+Those outputs can change; Python callers of `extract.detect_background_key_rgb` can pass the new `threshold` argument, which the engine supplies from `--key-threshold` (default 96).+New commands are `sprite-gen breathe`, `video-sway` and `video-sway-inspect`, and Breathe gains a smooth mode for large illustrations and video frames.+Breathe without `mode` or with `mode: "pixel"` keeps the same bytes and sidecar; new Breathe values set to 0 or omitted also keep the same bytes.+`video-follow` and `video-follow-inspect` keep their names and files, including the `follow` record, `follow.source.png` strip and `follow-inspect.*` inspection files.+Moving the written names to `sway` is a later change made together with the tools that read them.+Every command now reopens stdout and stderr as UTF-8 where needed so it can print on Windows consoles or pipes using cp949 or cp1252; importing `sprite_gen` leaves the caller's streams alone.+Restoration schemas remain `source-restoration-v5`, repair report `schema_version` 4 and comparison `schema_version` 6, while the report's `producer` names the new version.+2.45.3 changed only the `--anchor body` seam check, so detailed comparisons below with 2.45.2 for keying, framing and `video-frames` also hold for 2.45.3.++- **Changed (default):** A video model given the first frame as the last draws that frame again (softer or sharper, another tone, hair strands a pixel over).+ The pin gate reads the pose and passes.+ The drawing stays, so the loop's wrap shows one jump in sharpness where every other step shows the motion.+ Over the cut's last half second (K = min(round(0.5 s x fps), floor(L / 4)) cells, 12 at 24 fps), wrap blending adds back j/(K+1) of the redraw's difference (first cell minus pinned frame, premultiplied) on the j-th cell.+ Each pose stays the cell's own, and its drawing turns into the first cell's by the wrap.+ Only a redraw is ramped.+ A pixel is held where the two ends hold a part, a line or a dot in different places, and where a ramp cell does not stand where the pinned frame stands.+ This check applies after one softness match of at most 0.7 px.+ A pixel is held if it is more than 12 levels outside what the other end holds within 1 px on a 7x7 mean or a 7 px run, over black and over white.+ It is also held if its value is more than 12 outside the other end's 1 px range where the other end has under half this end's range there, in any direction, length or width.+ Held pixels are widened 3 px and the weight feathered 7x7.+ A pixel of weight 0 is the filmed byte.+ A ramp that steps more than the cut already does, or that does not shrink the wrap, is not used: the cut is written as filmed and a `warning:` line says so.+ A wrap still over `--seam-max` after blending also gets a `warning:` line.+ New flag (default `auto`, and `video-set` takes the default):+ `video-loop --wrap-blend auto|off`+ New report key `wrap_blend` on every pinned cut (`applied`, `why`, `K`, `cells`, `residual_ratio`, `wrap_ratio_before`, `wrap_ratio_after`, `ramp_step_max_ratio`, `bound_ratio`, `pose_share`, `presence_share`, `never_settled`, `equalize`, `after_check`, `seconds`).+ `wrap_blend: {cells, K}` appears in the strip metadata where it applied, and in the CLI summary.+ [loop repair](docs/loop-repair.md#6-the-redrawn-wrap-a-pinned-clip-whose-last-frame-the-model-drew-again)+- **Tests**: `tests/video/test_wrap_blend.py` on synthetic clips:+ a redraw of tone and 0.5 px softness has its wrap brought from 7.31x to 0.57x the median step and only the ramp's cells, strip, GIF and WebP differ from off;+ an arm still coming down in the ramp stays the filmed arm;+ a part moved 2 to 64 px, or present at one end only, is never drawn twice (the 14 px part on a flat figure is cut as filmed with a warning);+ 1 px lines moved 2 to 32 px on a flat figure are byte for byte;+ stripes swinging inside the ramp keep their swing;+ a strand against the silhouette is held over white where black alone lets it through;+ the softness match blurs the sharper end, never past 0.7 px;+ the idle-still fixture gives every output byte for byte;+ fixed cuts, body-anchored pinned cuts and refused pins are not touched;+ a ramp that steps past the cut is refused with a warning;+ a 1 px line at slope 1/3 moved 8 px is held line for line, thin structures change by at most 2 levels and busier quiet grounds by at most 3, strands off the silhouette by none.+- **Changed: `video-loop` bridges a jumping wrap on idle and action loops (`repair.seam_bridge`).** Under `--repair auto` (the default) or `--repair on`, a loop whose state is not a gait (idle, jump, attack, or a generic in-place action) has its wrap read against the steps beside it; where it jumps, one, two, or four frames round the wrap are made again by RIFE between the frames either side; the loop is not read for its flow (an idle's own motion would leave it). See [loop repair](docs/loop-repair.md#the-seam-bridge-a-loop-that-is-not-a-walk-whose-wrap-jumps).+- **Tests**: `tests/video/test_seam_bridge.py` covers the synthetic idle with wrap jump J = 2.6 closed by one frame and passing the gate, J = 5 tried at one and two frames then closed by four, J = 12 refused without frames made, J = 1 closed loop untouched without an interpolator, whole-pixel stepped motion not bridged, near-still loop under the noise floor not bridged, loop drawn on twos skipped, real RIFE (rife-v4.6 with augmentation) closing J = 2.6 without faults, frames made with a fault (a stand-in painting a dark patch: smear at every width, seven calls, nothing taken, gate refuses as before), missing RIFE where the wrap is cut as filmed with the install line in `jump_repair` and a `warning:` line, a wrap that reads as a step saying nothing, `--repair on` refusing with the install line, a pinned clip whose pin the gate refuses skipped without reading and refused on its pin, the CLI summary naming the frames made, and the report naming the RIFE that made them; a `--repair on` run without RIFE, in an output folder where an earlier cut passed, refused on a wrap needing the bridge and leaving none of that cut's `cycle/`, strip, strip metadata, GIF or WebP, and no `cycle.refused/` because the new cut was not yet written.+- **Default change: A drawing cut by its own frame is no longer refused as framed too tight.** A bust or half-length drawing runs off the frame itself (its sleeve cut off at the left, its hair at the top), so in every frame of its clip the subject touches those edges and no canvas gives it room there. In 2.45.2 the default `video-frames` edge check refused every frame of such a clip with "the subject touches the frame edge ... framed too tight". Only a flag let it through: `--allow-subject-edge-contact`, which also lets through a subject that really leaves the frame, or `--allow-edge-contact`, which turns the check off. The default (`edge_policy` is now `border`, was `refuse`) reads the drawing's own border on the clip's first frame, keyed with its specks erased: a side (top, left, right) whose outermost row or column the subject covers for at least 2 % of its length (`frames.BORDER_MIN_FRACTION`) is a border side. Subject contact there is accepted in every frame, wherever along the side. Subject contact on any other side is still refused as framed too tight (a bust cut at the top and left whose hand leaves the right). The top / left / right numbers in a refusal are now the pixels the border does not take, so a caller that reads them to choose a taller or wider canvas reads the side that needs room. Leftover key is still refused, except the body's rim the matte cut loose: a key-only piece is accepted only on a border side the same frame's subject reaches, holding fewer than 8 pixels in all (`SPECK_MIN_PX`) and lying wholly within 10 px of the frame's body (`frames.RIM_REACH`, counted each way and diagonally; the body is the largest piece holding a pixel off the key). A thin outline blended with the key leaves such pieces at the edge between strands. Larger pieces, farther pieces, pieces on other sides or on a side the frame's subject left, and a detached stain beside a sleeve on the same side are refused as in 2.45.2. A clip whose first frame crosses no side is judged and worded exactly as in 2.45.2, byte for byte. The two flags judge as in 2.45.2. Taking a side as the border prints one stderr line. The report gains `edge_border` (`frame`, `sides`, `outer_px`, `min_fraction`, `rim_reach`, `rim_under_px`); each contact row gains `rim`, and under the default `border` (pixels taken) and `off` (pixels not taken, by side). Known limit: a hand that newly leaves the frame on a side that is already a border side is accepted; by position it cannot be told from the sleeve moving along the edge. [video pipeline](docs/video-pipeline.md), section 3.+- **Default change: A refused run hands nothing over.** A caller that does not read the exit code used a refused run's output as if it had passed. In 2.45.2 a refused `video-frames` run left its keyed frames in `keyed/` and wrote no report. `keyed/` was not emptied before keying, so a pass after a longer earlier run in the same folder also held the earlier run's extra frames. A refused `video-loop` run could leave a mixed set: for example after the pin gate refused, `cycle/` and the strip were the refused run's while the GIF and WebP were an earlier run's; a refusal before the cut left the earlier run's whole set. Now `video-frames` keys into a hidden working folder and hands over `keyed/` only when the run passes. A refused run (the edge check, or a frame keyed to 0 % transparency) leaves its frames as `keyed.refused/` and no `keyed/`, not even an earlier run's. A pass removes `keyed.refused/`. The report is written either way, with `status` (`passed` or `refused`); a refused report adds `error`, `refused_dir` and `keyed_dir: null`. Keyed frames that pass are the same bytes as before. Every `video-loop` refusal that writes `status: failed` (selection, motion anchor, jump repair, jolt, pin, seam, a strip with no body, a GIF or WebP that could not be written or verified) removes `cycle/`, `<name>.strip.png`, `<name>.strip.json`, `<name>.gif`, `<name>.webp`, `cycle.source/` and `follow.source.png` from the output folder. A cut it had already written is kept as `cycle.refused/`, which the next pass removes. A strip with no body and a GIF or WebP that could not be written now also write the failed report. Argument errors touch nothing. [video pipeline](docs/video-pipeline.md), sections 3 and 4.+- **Tests** - `tests/video/test_edge_border.py` (a bust cut at the top and left passes and the report names its border; a padded jump whose head leaves the top and a first frame with a 2 px wisp on the top are refused with the 2.45.2 message, byte for byte; a key-only patch with no border is worded as in 2.45.2; a hand leaving the right of a bust is framing, its message counting only the right; a hand leaving a border side elsewhere is accepted (the known limit); leftover key that is not the body's rim is refused (a patch on the right, a 48 px fringe beside the sleeve, a patch where the sleeve left, a detached 20 x 90 stain, 2 px pieces 11 and 14 px from the sleeve, pieces of 8 px and more, stripes hugging the head, stains beside the head, a fringe on a side that is not the border, a fringe above a head clear of the top band, a stain round a fleck of the body's colour); 1 px dots are judged piece by piece; 2 px pieces 2 to 10 px from the sleeve and a 7 px piece are the rim; an 8 px piece with 4 pixels in the band and a 7 px piece 11 px away are refused; the two flags judge as in 2.45.2; `classify_edge_contact` counts the rim; a refused `video-frames` run leaves `keyed.refused/`, no `keyed/` and a refused report; a pass after a refusal leaves `keyed/` alone; a pass over a longer run holds its own frames only; a frame keyed to 0 % transparency is refused the same way; an argument error touches nothing; a `video-loop` cut refused after it was written hands nothing over and keeps `cycle.refused/`, removed by the next pass; a cut refused before it was written hands nothing over; a loop argument error touches nothing), `tests/video/test_canvas_key_normalize.py` and `tests/video/test_fit_tight.py` (the 2.45.2 default's framing and mixed-contact tests now move the contact after the first frame and read the refused frames from `keyed.refused/`), `tests/video/test_edge_speck_lead_in.py` (the default policy is named `border`, and the refused frames are read from `keyed.refused/`), `tests/frames/test_chroma_key_relative.py` (the edge-contact split states the `rim` count `classify_edge_contact` now gives).+- **Fix: Green screens that lean toward cyan or yellow are now recognised as border keys.** A green screen that leans toward cyan or yellow was not recognised as the key on the border. Examples: the studio chroma-key green `#00B140`, (0, 177, 64); (0, 200, 90), which leans toward cyan; (90, 210, 0), which leans toward yellow. Each sits more than 96 from pure green. With `--key green` the whole background stayed opaque, and `video-canvas` refused `--key green` on such a still; but with `--key auto` the old rule did not take the green route at all: `cutout` and `video-frames` routed the frame to the white (position-based) matte, and `video-canvas` treated the still as a non-key base and did not normalize it. `video-frames --spill auto` did not always choose `full`: when the reference still had the same leaning green, `auto` read the surviving background as key material and chose `small`; when it chose `full` (a reference whose own background the old rule did recognise), the clip's surviving background was despilled to a blue-grey instead of being erased. The cause was that the border rule `extract.is_border_key_candidate` held every unkeyed channel under 64. That bar was set between magentas, whose one unkeyed channel (green) tells a painted magenta from hot pink. Green has two unkeyed channels, and a green screen leans on one of them. For the fix, the darkest unkeyed channel keeps the bar (under 64, and at most 35 % of the brightest keyed channel). The brightest one only has to stay under half of the brightest keyed channel (`extract._BORDER_KEY_MAX_LEAN_RATIO`, 0.5), that is a hue nearer green than yellow or cyan (between 90 and 150 degrees). The border detector, `extract.detect_background_key_rgb`, reads the lean second. It first counts, on their own, the candidates the 2.45.2 rule admitted. When those make up at least 12% of the samples, it returns the mean of their most populated bin, exactly the colour 2.45.2 returned. Below 12%, the samples only the lean admits join them, but their most populated bin gives the colour only where the declared key's own cut would leave that background on the border. Two conditions, both needed: the samples only the lean admits that lie farther from the declared key than the cut (the radius the caller keys with: the new `threshold` argument of `detect_background_key_rgb`, which the engine sets from `--key-threshold`, 96 by default), in that most populated bin or in a bin beside it on every channel, make up at least 2% of the samples; and the candidates outside that bin and the bins beside it make up less than 12% of the samples (the border holds one key-coloured background). Otherwise the declared key is kept, as in 2.45.2. A leaning border the declared key clears by itself gains nothing from the leaning colour; its ball would only reach further into a subject near that colour: (0, 210, 80) sits 91.8 from pure green, inside the cut of 96, so the declared key erases that background on its own, and a teal subject (0, 154, 149), 180 from the key, is kept; read as the painted colour, (0, 210, 80), 88.9 from the teal, let the ball reach the teal subject through the background and erase all of it, with no background gained. The 2% keeps the soft rim where a subject meets an edge of the frame (its blend with the background crossing the cut there) from being read as background the cut left; and a background whose tail past the cut is under 2% of the border keys as before the lean, the few pixels past the cut included. A second key-coloured colour on the border may be the subject's own (a leaf along an edge, another green); read as part of the background it would let the ball take a subject colour near the dominant one. `cutout`, the reference window `video-frames --spill auto` keys, and the YCbCr path's decontamination pass hand the detector the radius they key with, as the engine does. The painted key's erase ball, the spill judgment's subject window and the `video-frames` edge-contact split take the lean only from a painted colour that leans itself (`extract._painted_key_leans`). A colour found the first way never leans itself (magenta has no lean; for green the floor of the mean of one 8-wide bin of 2.45.2 candidates is always one of them), so they read it as 2.45.2 did. `cutout --key auto` and `video-canvas --key` classify the flat corner colour with the border rule, lean included (there the question is what the painted colour can be): a corner colour 2.45.2 took routes as before, and a leaning corner colour now routes to green. The magenta key is exactly as before (its one unkeyed channel is both the darkest and the brightest), so hot pink (250, 77, 150) and purple (213, 112, 246) are still refused. For green, nothing that was a candidate is dropped. Ivory, cyan, teal, sea green, a grey-green with both unkeyed channels lit and a green as near cyan as green are still refused. The interior rule `is_key_family` is unchanged. As a consequence, every image whose border the 2.45.2 rule recognised (its candidates at least 12% of the corner and border samples) keys byte for byte as in 2.45.2 under the same key, whatever leaning green is mixed into that border and in whatever share. Under the same key, every image is keyed either exactly as in 2.45.2 or exactly as with the leaning colour read. As in 2.45.2: wherever the 2.45.2 rule recognised the border (its candidates at least 12% of the corner and border samples), wherever the declared key's cut clears a leaning border by itself, and wherever the border holds a second key-coloured colour. With the leaning colour: where the key's cut leaves the border's one leaning background. Read together, a sample admitted only through the lean can share the 8-wide bin of a background 2.45.2 already found and move its mean, while leaning samples in a bin of their own that outnumber the background would take the mode. A leaning-green part of the subject on the corners and the border can be taken as the painted colour only where the 2.45.2 rule's candidates make up less than 12% of the samples, the key's cut leaves it and no other key-coloured colour holds 12% of the border, that is, only where the subject crowds the border. A leaning-green patch buried in the subject on such a background is kept. [chroma-alpha](docs/chroma-alpha.md), the 2026-10-21 paragraph.+- **Tests** - `tests/frames/test_chroma_key_relative.py` (the border table with the three leaning greens accepted and a grey-green and a cyan-midpoint green refused; the detector still refuses hot pink, purple, ivory, cyan, (30, 60, 30), teal, sea green and those two; over the whole RGB cube the lean adds nothing for magenta, drops nothing for either key, and adds for green only hues between 90 and 150 degrees; without the lean the candidate field is the old rule colour for colour over the whole RGB cube; the engine and `cutout --key green` key the leaning greens out with the subject byte-identical; `cutout --key auto` routes a leaning green to `extract:green`; a leaning-green patch ((0, 160, 75) or (10, 120, 50)) buried in the subject is kept byte for byte on (8, 162, 24) and keyed with the background on (0, 200, 90); the edge-contact split reads a leaning piece as residual when the frame was keyed from a leaning background and as the subject's when it was keyed from (8, 162, 24); on (0, 200, 64) with a leaning green, (0, 200, 71) in its bin or (0, 200, 90) in a bin of its own, over the top-left corner (20.5% of the samples) or everywhere but a 32 x 32 block of the background (77.3%), the detector returns (0, 200, 64) and the frame keys exactly as from that colour pinned, a teal subject (0, 154, 149) just outside the ball keeping every pixel; a leaning-green border on (0, 200, 90), past the cut, with no 2.45.2 candidate, or with a block of one under 12% of the samples, is found through the lean and keys out; and over every 8-wide bin of green, the floor of the mean of 2.45.2 candidates is one of them; on (0, 210, 80), inside the key's cut, with no 2.45.2 candidate on the border or with 11% of the samples an interior-family green, the detector keeps the declared key and the frame keys exactly as with the key pinned, a teal subject (0, 154, 149) losing no pixel; a leaning-green leaf of the subject along the bottom edge over a leaning background the key clears, a second leaning green in a corner, and a soft rim crossing the cut where the subject meets the side edges each keep the declared key; with 1.5% of the border a step past the cut the key is kept, and with 2.5% the leaning colour is read; (0, 200, 90) is read with a cut of 96 and not with a cut of 110; over a sweep of borders around the cut every answer is the 2.45.2 answer or the answer that reads the lean, and both occur, as do borders where the two differ and the key is kept), `tests/frames/test_key_detect_banded.py` (the whole-image reference now states this rule, and leaning-green borders (past, across and inside the cut, and two leaning greens on one border) join the images the banded detector is checked against), `tests/video/test_canvas_key_normalize.py` (`video-canvas` repaints a leaning-green still to the exact key and accepts `--key green` on it), and `tests/video/test_video_spill.py` (on a leaning green, `--spill auto` reads the reference as `full` with no key material, and the frame keys with no opaque background pixel and no edge contact, the subject byte-identical, with `--decontam off` and `palette`).+- **New: The Breathe layer adds `mode: "smooth"` for large illustrations and video frames.**+ Set per row: `states.<state>.breathe = {"mode": "smooth", "depth": ..., "breaths": ...}`.+ `pixel` stays the default.+ The head and everything above the measured neck line stays in place, byte for byte, in every cell.+ The figure's bottom stays put.+ It reuses the automatic anatomy: rigid row, body axis, torso half width, and basis rows.+ It also uses the neck's width, measured once on the row's first cell.+ The whole row uses that placement.+ The chest breathes from its centre.+ It uses a round (cos^2) weight on the body axis at `chest_y` of the body below the neck.+ The weight is `chest_rx` x torso half width wide, and `chest_ry` x the body below the neck tall.+ The chest centre rises by `depth` x basis rows at the in-breath and puffs out by `depth_x` from P (not from the ellipse centre).+ Two shoulder weights, on either side just below the neck, rise by `shoulder` x the chest's rise.+ They rise `shoulder_lag` of a breath later.+ The neck and the collar beside it hold still.+ Whole rows do not move.+ For a figure whose body axis is pulled to one side (for example by long hair), the chest is not on the axis: `chest_x` moves the chest ellipse's centre off the body axis, in torso half widths (-1 to 1).+ The shoulders stay where they were (relative to the body axis).+ For a turned body: `chest_tilt` (degrees, clockwise on screen) and `chest_dir` (degrees from straight up, negative = up-left).+ `chest_bias` moves the chest weight's peak P along the chest ellipse's long axis, as a share of its horizontal half width (-0.9 to 0.9, negative is the screen's left).+ `chest_bias_y` moves the peak P across the long axis, as a share of the vertical half height (-0.9 to 0.9, positive is down).+ The weight falls from P to the ellipse's rim along the ray from P through each point, so the near side falls off over a short distance and the far side over a long one.+ P must stay inside the ellipse: `chest_bias` and `chest_bias_y` together at most 0.9 of the radii (refused otherwise).+ `chest_flat` is the share of the way from the peak P to the rim that rises in full (0 to 0.9).+ These default to 0; at 0, nothing changes.+ One breath is a bump from rest (in-breath 40 %, out 60 %).+ A cell at phase 0 is the source byte for byte.+ Seams and joins between loops are untouched.+ `breaths` is a whole number.+ `breath_peaks` is a list of cells where each in-breath peaks, for timing the breath from outside (for example to keep the breath's peaks off a big hand movement in the clip).+ The breath count is the number of peaks (`breaths`, if given, must match).+ The first cell stays at rest and the loop closes at rest: breaths are separated by rests at cell 0, between two peaks where the out-breath has taken 60 % of the gap and the next in-breath 40 %, and at the loop's end.+ Refused, never silently clamped: `lag` on smooth (it would move the first cell), a stretch past the per-row strain cap (0.25) or a fold, opaque pixels pushed off the canvas, out-of-range values, `chest_bias` and `chest_bias_y` together past 0.9 of the radii, a peak at cell 0, peaks not increasing or closer than two cells, a last peak within one cell of the loop's end, mismatched `breaths`, and shape keys or `breath_peaks` on a pixel row.+ With the default shape nothing leaves the canvas.+ A figure cut by the frame at its sides or bottom is not refused.+ Defaults: `depth` 0.0085 (about 0.5 % of the frame height on a bust illustration), `depth_x` 0.028, `chest_y` 0.31, `chest_rx` 0.83, `chest_ry` 0.28, `shoulder` 0.5, `shoulder_lag` 0.08, and `chest_tilt`, `chest_bias`, `chest_bias_y`, `chest_dir`, `chest_x`, and `chest_flat` 0.+ Performance is about 0.2 s per 960 px frame.+- **New: `sprite-gen breathe <frames> <out>` lays the Breathe layer over a folder of loop frames outside curation.**+ This lays the Breathe layer (either mode) over a folder of loop frames that is not a curation run, such as a video loop's cells.+ It takes the sidecar's values through the same checks and the same bake: `--mode`, `--depth`, `--depth-x`, `--breaths`, `--breath-peaks` (for example `--breath-peaks 30,102`), `--lag`, and `--rigid-row`.+ It also takes the smooth shape flags: `--chest-y`, `--chest-rx`, `--chest-ry`, `--shoulder`, `--shoulder-lag`, `--chest-tilt`, `--chest-bias`, `--chest-bias-y`, `--chest-dir`, `--chest-x`, and `--chest-flat`.+ The same values give the same bytes as a curation bake.+ It writes the frames under their names and `breathe.json` (config, phases, the anatomy used) into a new folder all at once.+ Before creating or deleting anything, it refuses if `<out>` and `<frames>` are the same folder, if either lies inside the other based on real disk location (following symbolic links and treating two spellings on a case-insensitive disk as the same folder), or if `<out>` already exists and is not empty, while an existing empty folder is accepted.+ It never writes anything into `<frames>`, and it never changes or deletes any frames or other files there.+ It builds the result in a temporary folder of its own next to `<out>`, with a name no other folder has, and moves it into place in one step, deleting only that temporary folder if a run cannot finish while leaving alone folders it did not make, such as a leftover temporary folder of an earlier run.+ When `<out>` is a symbolic link to an empty folder, the result is placed in the folder the link points to, and the link stays.+- **Output change: The curation webview does not preview a smooth row.**+ The live preview mirrors the pixel warp only.+ It shows the original frame with a notice.+ Its row video export refuses.+ Saving keeps a smooth sidecar exactly as written instead of filling pixel defaults.+- **New: The follow-through is now the Sway layer, replacing `video-follow` with `video-sway`.**+ `video-sway` and `video-sway-inspect` replace `video-follow` and `video-follow-inspect`.+ Their Python modules are `sprite_gen.video.sway`, `sway_loop`, `sway_offsets`, and `sprite_gen.video.sway_inspect`.+ `video-follow` and `video-follow-inspect` remain as aliases with the same results and their own name in messages.+ A loop's record is read under `sway` or `follow`.+ Behaviour is unchanged.+- **New: `Anatomy` gains `origin` and `neck_span` values.**+ It does not put these two values in the sidecar or the manifest.+ `origin` records where the measured frame's figure sits.+ `neck_span` records the neck's span on the rigid row.+ Pixel Breathe does not use them.+- **Fix: every command prints on a Windows console or pipe in a legacy code page.** A line a command prints can hold an em dash, Korean or a path in any script; on cp949 (Korean Windows) or cp1252 Python could not encode it, and the command died at the print after its work was done (`background-tile` on Korean Windows). Each command's entry now reopens stdout and stderr as UTF-8 where they are not already (`sprite_gen.util.console.utf8_streams`, called first by every `main()` and by `sprite-gen`); importing sprite_gen leaves a program's streams alone. Test: `tests/util/test_console.py`.+## v2.45.3 - The seam check reads the frames that play when the body anchor spreads a sideways slide; such a cut passes again, as it did in 2.44.0**Upgrading from 2.45.2: Every cut 2.45.2 passed, and every `--anchor motion-auto` run, gives the same bytes as 2.45.2.** Only `--anchor body` cuts that 2.45.2 refused because of the walk sliding sideways before the anchor can now pass, read on the frames that play. Refused cuts print the same error line as before, the report's `producer` field names the new version, and there are no restoration schema changes.diff --cc docs/video-pipeline.mdindex 1a605cc,3c550bb..2a2478c--- a/docs/video-pipeline.md+++ b/docs/video-pipeline.md@@@ -374,18 -892,89 +374,16 @@@ the frames as filmed**A lead-in is left out of the search** (walk and run, `--cycle auto` or `periodic`). A videomodel may reframe a small subject in a clip's first frames: the body grows (or shrinks) by a third-or more in under half a second, then walks at its new size. Searched with those frames, the-motion analysis reads the reframing as the clip's motion and the walk's repeat is lost; the gait-fallback, which then scaled by a line through the clip, read the step as a steady growth and-shrank the walk. So the clip's sizes are read one cycle on (`gait_fallback.cycle_drift`, the-hold's model, a median over the whole clip). A clip opens on a lead-in when its first frame's-height and size (the square root of the frame's summed coverage) are both off that model by 10 % or-more, the same way (`LEAD_IN_MIN`): a reframing scales the whole body and moves both, a pose moves-one — an item held up from the second frame on makes the first frame shorter and no lighter, legs-spread in a side step add size and no height. The lead-in (`gait_fallback.lead_in`) runs on while-the height stays that far off, that way; a walk's own frames stray from the model by a few percent. The search — the size hold, the motion-analysis, the cycle search and the gait fallback — reads the clip after it as a clip of its own,-its window included. What it finds, and what it refuses, is said in the clip's own frame numbers:+or more in under half a second, then walks at its new size. What it finds, and what it refuses, is said in the clip's own frame numbers:every `start` and `context_pair_range` in the report's `cycle`, refused candidates too, so a cut-taken again from them (`--cycle fixed --start`) is the frames they name. The report records it on-every walk and run (`lead_in`: `frames`, 0 for none; `height_change`, the walk's height where the-lead-in ends over the first frame's, less 1; `first_off` and `first_off_size`; `search_from`, the-first frame the search read). A cut the caller names (`fixed`, `pinned`) is the caller's frames, lead-in or not. A clip-too short to read its size one cycle on has no lead-in (`why`). On a synthetic walker filmed at-0.63 of its size and reframed over 9 frames, the search as filmed found no cycle, nor did the-fallback; after its 5-frame lead-in it cuts the 24-frame walk (`tests/video/test_edge_speck_lead_in.py`).--**Nothing is cut when a frame is scaled up.** A clip that shrinks is scaled up about its feet,-and when the feet also rose in the frame (a back walk going away toward the horizon) the crown-lands above the frame. Every frame is first widened by the room the furthest one reaches past-each edge (`gait_fallback.undo_padding`, the same for every frame; `padding_ltrb` in the-report), so no part is lost. A frame that needs no room keeps its size and bytes. The gait-fallback's own scale-back (below) widens the same way. The foot point is a least-squares line-with exactly rounded sums (`sprite_gen.util.lsq`, as are the fallback's fitted heights), the same to-the last bit on every machine. With np.polyfit, whose last bit differs between LAPACK builds, feet-that stand on the frame's bottom edge read a hair past it or short of it, and whether the frames-got 2 px of room below — and so the frames the cut is searched on — turned on that bit.+taken again from them (`--cycle fixed --start`) is the frames they name. A cut the caller names (`fixed`, `pinned`) is the caller's frames, lead-in or not.- Gates, all fail-loud: no period (profile flat, below the recorded `periodicity_min`), loop seam ratio- above `--seam-max` (2.0), GIF/WebP re-opened and checked (frame count, `loop=0`,- transparent corners, no RGB under alpha 0 in the WebP).+ Gates, all fail loud: no period (profile flat, below the recorded `periodicity_min`), loop seam ratio above `--seam-max` (2.0), GIF/WebP reopened and checked (frame count, `loop=0`, transparent corners, no RGB under alpha 0 in the WebP). On every walk or run loop that plays round, the step gate reads cells between drawings and refuses the loop when its largest step that is not a pixel's jitter, divided by the mean of the other steps, exceeds `STEP_RATIO_MAX` (2.5); a step is a pixel's jitter when aligning its drawing with the previous drawing takes at most `STEP_JITTER_PX` (1.5) pixels of the frames as filmed, measured by coverage so colour has no effect, and the step with that move taken back is within 2.5 of the mean. A fixed cut of a walk or run reads clip foot crossings to judge the cut, refusing an odd step count that would swap legs at the wrap. Both checks are lifted by `--seam-max` past 2.5; see `docs/loop-repair.md` section 3, "The step gate".-A walk or run loop then has its jump frames repaired before the strip is built: one or two-drawings in a row that leave the loop's flow — 3× their region's usual step off the line between-the frames either side, by direction and speed, not by the size of a step — are taken out and-made again by RIFE between those frames, each at its own time so the loop keeps its length, at-most three calls and never made from or beside a frame made (`--repair auto`, the default;-`--repair off` cuts as filmed). A frame the ghost screen names a filmed ghost, read on-the cut as filmed, is replaced in the same stage first: by RIFE's frame between the two clean-frames beside it, else by the clean frame beside it, else kept and named (`ghost_given_way`,-`ghost_kept`) — a walk of one direction is delivered as cut and never meets the alignment that would-take a clean frame there. Then a part that keeps its way and rushes — a tail that runs short of-the cycle, rushing on at the wrap — has the three or four drawings either side of the rush made-again at times that spread it, made from the frames as filmed, the body's feet, torso (the head-and torso the motion anchor tracks; a part swaying on its own beat is not drift) and ground line-moving no further in a step, nor the rest of it faster, than they did there (the eased retime, up-to nine calls of its own) — played only where the rest of the body keeps its own beat on the frames-made, step by step; a frame made is the whole picture at one time, so the legs take the time the-tail is given, and the loop then keeps the flow repair. Before all of it, a cut two steps long whose wrap a part on its own beat-leaves open — a tail swinging round on a beat of its own, closing on no cut of two steps — has four-to twelve frames beside its wrap made again between the clip's frames a cycle apart and its own, so-the wrap plays a step the clip filmed, as far as the torso held to the stretch as the loop plays it-allows (the overlapped wrap, `wrap_overlap`; `--overlap-wrap off` turns it off alone, for a host whose-RIFE runs on a CPU, and the gate then refuses the cut as filmed).-The report's `jump_repair` names the frames. RIFE-is installed once with `sprite-gen rife install`; without it a loop that needs a frame is cut as-filmed with a warning, each filmed ghost given way to the clean frame beside it (`--repair on`-fails instead). A frame shown twice in a row is one frame of the GIF and WebP, checked so, and the seam gate reads a frame given way as filmed (`seam_as_filmed`). See [loop repair](loop-repair.md). The repaired loop's jolt index and the head's frame-to-frame-moves are reported (`jolt`); beyond the reference bounds that is a warning line, and a gate-(`video-loop: loop jolts — …`) only when `--jolt-max` / `--head-step-max` are passed.+See [loop repair](loop-repair.md).**Held drawings: recorded on every loop.** A video model may film a walk at 12 drawings a second-inside a 24 fps clip, each drawing shown for two frames ("on twos", or three: "on threes"). The-report's `drawings` says so, read over the whole clip as keyed, before any cut-(`sprite_gen/video/held.py`): `hold` (1 every frame a drawing, 2 or 3; `null` with a `why` for a-clip too short or still), `drawings` and `drawings_per_second`, `held_steps`, and `contrast` per-hold — the held steps over the change steps, the evidence. `cycle_drawings` is the same reading over-the cut alone, on the clip's steps from the cut's first frame into the frame after its last (`start`,-`length`, `steps`; `null` with a `why` under 12 steps, one window). `strip.json` carries both-(`drawings`: `hold`, `drawings_per_second`, `contrast`, `frames`; `cycle_drawings`: `start`,-`length`, `steps`, `hold`, `drawings_per_second`, `contrast`, `why`) for `video-cycle-align`, which-reads the cut's: a clip may hold its drawings for only part of its length. The second frame of a pair is rarely a-byte copy: the model redraws it a little, so its step is small, not zero, and a rule that calls a-step held under a fraction of the median step misses it (with half the steps held the median falls-between the two kinds). So the judgement reads the rhythm: for a hold of 2 or 3, in windows of 12-steps, the phase whose every second (or third) step is the change, its held steps' median over its-change steps' median; under 0.3 the clip is held, and each step is then held when it is under the-geometric midpoint of the two kinds' means. A motion filmed every frame has no such rhythm — its-steps swell and shrink with the stride over a dozen frames — and a clip whose steps alternate long-and short but move every frame reads above it; so does a frame repeated now and then (a 20 fps-clip carried at 24). Nothing is refused here: played at its own rate a held loop is ordinary+inside a 24 fps clip, each drawing shown for two frames ("on twos", or three: "on threes"). Nothing is refused here: played at its own rate a held loop is ordinarylimited animation. It matters when `video-cycle-align` stretches it ([loop repair](loop-repair.md)section 4, "Held drawings").diff --cc sprite_gen/video/loop.pyindex 327e71e,123ac7b..50c6ffc--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@@ -1104,68 -1086,66 +1123,124 @@@ def _overlap_refused(overlap: dict[strrest = ", the rest not made" if t["unmade"] else ""return f"{', '.join(t['rejected_for'])} ({', '.join(stopped['faults'])} at frame {stopped['frame']}{rest})"- refused = "; ".join(f"{t['width']} frames {t['side']} the wrap: {why(t)}" for t in overlap["tries"])- return [f"{said}, and the overlapped wrap was refused ({refused}): cut as filmed (docs/loop-repair.md section 2)"]+ return "; ".join(f"{t['width']} frames {t['side']} the wrap: {why(t)}" for t in overlap["tries"])+++ def _unfixed_lines(jump_repair: dict[str, Any]) -> list[str]:+ """Each drawing the jump repair left off the walk's flow (`jump_repair.unfixed`), in words."""+ lines = []+ for u in jump_repair.get("unfixed") or []:+ frames = u["frames"]+ why = (f"the group that would bring it back was refused ({', '.join(u['refused'])}), so it plays as filmed"+ if "refused" in u else f"no group of up to {jump_repair['span']} drawings brings it under {jump_repair['limit']:g}")+ lines.append(f"frame{'s' if len(frames) > 1 else ''} {', '.join(map(str, frames))} of the loop lie{'' if len(frames) > 1 else 's'} "+ f"{u['off']:.2f}x its window's usual step off the walk's flow after the jump repair: {why}")+ return lines+++ def _step_reason(jump_repair: dict[str, Any], frames: set[int]) -> dict[str, Any]:+ """Why a step between drawings jumps, where the jump repair says it: a drawing of it (`frames`) left off the walk's+ flow (`jump_repair.unfixed`) — the group that would bring it back refused (`repair-refused`, its faults), or none+ found (`unfixed`) — a refused group's drawing first: the drawings beside it read off the flow because it is; with the+ failure line's `words`. Elsewhere the reason is not known (`reason` None)."""+ for u in sorted(jump_repair.get("unfixed") or [], key=lambda u: "refused" not in u):+ if not frames & set(u["frames"]):+ continue+ at = f"frame{'s' if len(u['frames']) > 1 else ''} {', '.join(map(str, u['frames']))} lie{'' if len(u['frames']) > 1 else 's'} off the walk's flow"+ if "refused" in u:+ return {"reason": "repair-refused", "frames": u["frames"], "refused": u["refused"],+ "words": f": {at}, and the jump repair's frame there was refused ({', '.join(u['refused'])}), so it plays as filmed"}+ return {"reason": "unfixed", "frames": u["frames"],+ "words": f": {at}, and no group of up to {jump_repair['span']} drawings brings it back"}+ return {"reason": None}+++ def seam_reason(report: dict[str, Any], cycle: dict[str, Any]) -> dict[str, Any]:+ """Why the seam gate refuses a cut, where the warning lines say it: a cut of two steps by the clip's crossings whose+ wrap a part on a beat of its own leaves open (`own-beat`) — the overlapped wrap was asked (`wrap_overlap`,+ `_overlap_lines`), or no two-step cut closes (`local_cycle.step_verdict`). `overlap_wrap` says what became of the+ overlapped wrap (made, skipped, rife not installed, refused; None where it was not asked) and `words` the failure+ line's. Elsewhere the reason is not known (`reason` None)."""+ overlap = report.get("wrap_overlap")+ counted = cycle.get("step_count") or {}+ if overlap is None and not (counted.get("chosen_by") == "two steps" and not counted.get("gated")):+ return {"reason": None}+ words = "the cut covers two steps by the clip's crossings, and a part on a beat of its own (a tail, a held prop) closes on no cut of two steps"+ if overlap is None:+ outcome = None+ elif overlap["frames"]:+ outcome = "made"+ words += f": the overlapped wrap was made (frames {', '.join(map(str, overlap['frames']))}) and the wrap still does not close"+ elif "rife" in overlap:+ outcome = "rife not installed"+ words += ": RIFE is not installed, so the overlapped wrap was not made"+ elif "skipped" in overlap:+ outcome = "skipped"+ words += f": the overlapped wrap was not made ({overlap['skipped']})"+ else:+ outcome = "refused"+ words += f": the overlapped wrap was refused ({_overlap_refused(overlap)})"+ return {"reason": "own-beat", "overlap_wrap": outcome, "words": words}+def _bridge_seam(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, facing: str, required: bool,+ seam_max: float, hold: int | None, skip: str | None = None) -> tuple[list[Image.Image], dict[str, Any]]:+ """`repair_mod.seam_bridge` on a loop that is not a walk, with RIFE located only once a frame is to be made: a wrap+ that reads as a step of the loop needs no binary. The record names the interpolator that made the frames.++ A frame to make and no RIFE installed: `required` lets `RifeNotInstalled` through; otherwise the wrap is read again+ with no interpolator, cut as filmed, and the record says why (`rife`, `install`, the run it stopped at `unmade`)."""+ made_by: list[dict[str, str]] = []++ def lazy(a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ nonlocal interpolate+ if interpolate is None:+ found = rife_mod.Rife()+ made_by.append(found.describe())+ interpolate = found+ return interpolate(a, b, t)++ asked = partial(repair_mod.seam_bridge, limit=seam_max, hold=hold, facing=facing, skip=skip)+ try:+ frames, record = asked(frames, lazy)+ except rife_mod.RifeNotInstalled as exc:+ if required:+ raise+ frames, record = asked(frames, None)+ record.update(why="RIFE not installed — the wrap cut as filmed", rife=str(exc), install=rife_mod.INSTALL_COMMAND)+ record["applied"] = bool(record["replaced"])+ if record["calls"]:+ record["interpolator"] = ({"kind": "rife-ncnn-vulkan", **made_by[0], "binary_calls": interpolate.calls}+ if made_by else {"kind": "injected"})+ return frames, record+++def _bridge_lines(bridge: dict[str, Any]) -> list[str]:+ """What became of a wrap the seam bridge read as a jump (`repair.seam_bridge`), in words (`video-loop: warning:`+ lines): the frames made and the ones to look at, or why none was made. A wrap that reads as a step says nothing."""+ if "skipped" in bridge:+ return []+ said = (f"the loop's wrap jumps (its step {bridge['seam']:.2f}x the mean of the {bridge['around']} steps either side, "+ f"over {bridge['limit']:g})")+ if bridge["replaced"]:+ taken = bridge["tries"][-1]+ a, b = taken["anchors"]+ return [f"{said}: frames {', '.join(map(str, taken['frames']))} were made again by RIFE between frames {a} and {b} "+ "(cycle/), so the loop plays across it — look at them in the loop, or cut it with --repair off "+ "(docs/loop-repair.md section 2)",+ *(f"frame {m['frame']} was made at the wrap with RIFE's frame between frames {a} and {b}, which may "+ f"cross-fade two drawings inside its outline (crossfade {m['proposal']['crossfade']:.4f}); kept, a reading "+ "to look at (docs/loop-repair.md section 4)" for m in taken["made"] if m["look"])]+ if "unmade" in bridge:+ return [f"{said}, and RIFE is not installed, so no frame was made round it — run `{rife_mod.INSTALL_COMMAND}` "+ "and cut it again (docs/loop-repair.md section 2)"]+ reasons = {"line": "the straight line between its anchors does not close it", "fault": "a frame made has a fault",+ "seam": "the frames made do not close it"}+ refused = "; ".join(f"{t['width']}: {reasons[t['rejected_for']]}" + (f" ({', '.join(t['faults'])})" if t.get("faults") else "")+ for t in bridge["tries"])+ return [f"{said}, and no frames made round it close it ({refused}): cut as filmed (docs/loop-repair.md section 2)"]++def _shifts(analysis: dict[str, Any]) -> tuple[np.ndarray, int]:"""The analysis translation `auto_motion.analyse` measured, whole pixels a frame, and the room it needs."""shifts = np.rint(np.asarray(analysis["analysis_only_translation_xy"], dtype=np.float64)).astype(int)@@@ -1516,7 -1540,7 +1664,8 @@@ def run_loopsize_hold: str = "auto",steps: int | None = None,overlap_wrap: str = "on",+ wrap_blend: str = "auto",+ unfixed: str = "warn",) -> dict[str, Any]:state = state.strip().lower() if state else stateif state == effect.STATE:@@@ -1546,8 -1570,8 +1695,10 @@@raise SystemExit(f"video-loop: unknown --repair {repair!r}; expected one of {', '.join(REPAIR_MODES)}")if overlap_wrap not in OVERLAP_WRAP_MODES:raise SystemExit(f"video-loop: unknown --overlap-wrap {overlap_wrap!r}; expected one of {', '.join(OVERLAP_WRAP_MODES)}")+ if wrap_blend not in wrap_blend_mod.MODES:+ raise SystemExit(f"video-loop: unknown --wrap-blend {wrap_blend!r}; expected one of {', '.join(wrap_blend_mod.MODES)}")+ if unfixed not in UNFIXED_MODES:+ raise SystemExit(f"video-loop: unknown --unfixed {unfixed!r}; expected one of {', '.join(UNFIXED_MODES)}")if facing not in FACINGS:raise SystemExit(f"video-loop: unknown --facing {facing!r}; expected one of {', '.join(FACINGS)}")if anchor is None:@@@ -1926,8 -1943,19 +2095,17 @@@f"{', after repairing frames ' + str(report_base['jump_repair']['replaced']) if report_base['jump_repair'].get('replaced') else ''}); ""the motion does not play smoothly — regenerate the clip"f"{' (the jump repair did not run: RIFE is not installed — ' + rife_mod.INSTALL_COMMAND + ')' if 'rife' in report_base['jump_repair'] else ''}")- shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)- write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})raise SystemExit(error)+ left = _unfixed_lines(report_base["jump_repair"])+ if left and unfixed == "refuse":+ error = (f"video-loop: loop frames left off the flow — {'; '.join(left)} ({cycle.get('kind', 'periodic')} length {L} "+ f"frames from {i}); the motion does not play smoothly — regenerate the clip")- shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)- write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})++ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})+ raise SystemExit(error)+ for line in left:+ print(f"video-loop: warning: {line} — a jump played as filmed; --unfixed refuse refuses such a loop "+ "(docs/loop-repair.md section 2)", file=sys.stderr)for line in warnings:print(f"video-loop: warning: {line} (reference bound; the loop is kept — docs/loop-repair.md)", file=sys.stderr)if "ghost_given_way" not in report_base:@@@ -2068,23 -2087,63 +2246,65 @@@f"exceeds {cycle['pin_tolerance']:.4f}); {what} — regenerate the clip with ""--last-frame set to its first frame")- write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle,- "resampled_seam": resampled_seam,- "resampled_inner_mean_adjacent": resampled_adjacent,- "resampled_seam_ratio": seam_ratio})+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle,+ "resampled_seam": resampled_seam,+ "resampled_inner_mean_adjacent": resampled_adjacent,+ "resampled_seam_ratio": seam_ratio}, cut_written=True)raise SystemExit(error)elif not single_play and seam_ratio > seam_max:+ known = seam_reason(report_base, cycle)error = (f"video-loop: loop seam ratio {seam_ratio:.2f} exceeds {seam_max} "f"({cycle['kind']} length {L} frames from {i}); the cycle does not close — "- "regenerate with a complete return to the starting pose"+ + (f"{known['words']} — regenerate with that part moving on the walk's beat" if known["reason"] else+ "regenerate with a complete return to the starting pose"))- write_loop_report(target, {**report_base, "status": "failed", "error": error,- "cycle": cycle, "periodic_attempt": periodic_attempt,- "resampled_seam": resampled_seam,- "resampled_inner_mean_adjacent": resampled_adjacent,- "resampled_seam_ratio": seam_ratio,- "seam_refusal": {"reading": "wrap", "ratio": seam_ratio, "max": seam_max,- **{k: v for k, v in known.items() if k != "words"}}})+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error,+ "cycle": cycle, "periodic_attempt": periodic_attempt,+ "resampled_seam": resampled_seam,+ "resampled_inner_mean_adjacent": resampled_adjacent,- "resampled_seam_ratio": seam_ratio}, cut_written=True)++ "resampled_seam_ratio": seam_ratio,++ "seam_refusal": {"reading": "wrap", "ratio": seam_ratio, "max": seam_max,++ **{k: v for k, v in known.items() if k != "words"}}},++ cut_written=True)raise SystemExit(error)+ if prof.gait and not single_play:+ # Every step of the loop as it plays, read between its drawings: a frame that jumps inside the loop, which the+ # seam ratio at the wrap does not see. The bound is the step gate's, or the seam gate's where --seam-max lifts it;+ # a step its drawing moving a pixel of the frames as filmed makes is a pixel's jitter of a loop that barely moves,+ # and is not a jump (`step_jitter`, the cells' pixels of one of them the strip's scale).+ step_max = max(STEP_RATIO_MAX, seam_max)+ read = drawing_steps([strip.crop((k * strip_meta["w"], 0, (k + 1) * strip_meta["w"], strip_meta["h"]))+ for k in range(strip_meta["frames"])], pixel=strip_meta["scale"])+ if read is None:+ report_base["step_gate"] = {"read": "drawings", "skipped": "fewer than three drawings", "max": step_max}+ else:+ of = strip_meta["sample_indices"]+ read.update(largest_into=of[read["largest_into"]], largest_from=of[read["largest_from"]], max=step_max,+ lifted=seam_max > STEP_RATIO_MAX)+ for step in read.get("jitter", []):+ step.update({"from": of[step["from"]], "into": of[step["into"]]})+ report_base["step_gate"] = read+ ratio = read["largest_ratio"]+ if ratio is not None and ratio > step_max:+ known = _step_reason(report_base["jump_repair"], {read["largest_from"], read["largest_into"]})+ error = (f"video-loop: loop step ratio {ratio:.2f} exceeds {step_max:g} ({cycle['kind']} length {L} frames "+ f"from {i}, into frame {read['largest_into']}, read between its {read['drawings']} drawings); the loop "+ f"jumps inside{known.pop('words', '')} — regenerate the clip")- write_loop_report(target, {**report_base, "status": "failed", "error": error,- "cycle": cycle, "periodic_attempt": periodic_attempt,- "resampled_seam": resampled_seam,- "resampled_inner_mean_adjacent": resampled_adjacent,- "resampled_seam_ratio": seam_ratio,- "seam_refusal": {"reading": "steps", "ratio": ratio, "max": step_max,- "into": read["largest_into"], **known}})++ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error,++ "cycle": cycle, "periodic_attempt": periodic_attempt,++ "resampled_seam": resampled_seam,++ "resampled_inner_mean_adjacent": resampled_adjacent,++ "resampled_seam_ratio": seam_ratio,++ "seam_refusal": {"reading": "steps", "ratio": ratio, "max": step_max,++ "into": read["largest_into"], **known}},++ cut_written=True)+ raise SystemExit(error)+ if ratio is not None and ratio > STEP_RATIO_MAX:+ read["kept"] = f"--seam-max {seam_max:g} lifts the step gate"+ print(f"video-loop: warning: the loop's largest step between drawings is {ratio:.2f}x their mean (into frame "+ f"{read['largest_into']}), over {STEP_RATIO_MAX:g}: it jumps inside — kept, as --seam-max {seam_max:g} "+ "lifts the step gate", file=sys.stderr)# GIF has binary transparency. Bake the effect onto its declared black preview# background instead of turning its faint partial-alpha glow into opaque dark pixels.gif_background = "#000000" if cycle["kind"] == "lifetime" else None@@@ -2157,9 -2210,9 +2377,10 @@@ def add_arguments(parser: argparse.Arguparser.add_argument("--body-height", type=int, help="scale so the STANDING height (the subject in the clip's first frame, i.e. the base still's pose) is this many px — the same value across states gives the same character size; --strip-height stays the cap")parser.add_argument("--anchor", choices=ANCHOR_MODES, default=None, help="motion-auto: automatic stable regions, local repeat selection and XY ramp (walk/run); motion: fixed cut with explicit regions; body (default for walk/run): measure the last-to-first head-and-torso offset once and spread it as a ramp over the cycle; feet: remove in-canvas drift (a straight-line trend) so every cell stands on the mean foot line; none: leave placement as filmed (default for other states)")parser.add_argument("--anchor-region", type=motion_anchor.parse_region, action="append", help="motion anchor only: repeat twice with head then torso x0,y0,x1,y1 in the first selected frame; requires --cycle fixed and at least 6 frames")- parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): take out the frames off the walk's flow (one or two drawings that lie 3x their region's usual step off the line between the frames either side) and make them again with RIFE between those frames, each at its own time, so the loop keeps its length; adopt only without smear/outline faults, at most 3 calls and never made from or beside a frame made (docs/loop-repair.md section 2). A rejected group keeps its frames. Missing RIFE keeps the filmed loop with a warning (`sprite-gen rife install`); on: the same repair, but no RIFE fails the loop; off: cut as filmed")+ parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): take out the frames off the walk's flow (one or two drawings that lie 3x their region's usual step off the line between the frames either side) and make them again with RIFE between those frames, each at its own time, so the loop keeps its length; adopt only without smear/outline faults, at most 3 calls and never made from or beside a frame made (docs/loop-repair.md section 2). A rejected group keeps its frames. A loop that is not a walk or run is not read for its flow: where its wrap steps over --seam-max times the mean of the three steps either side, one, two or four frames round it are made again by RIFE between the frames either side, the fewest first, taken only without faults and where every step from one to the other then reads within that limit (docs/loop-repair.md section 2, \"The seam bridge\"). Missing RIFE keeps the filmed loop with a warning (`sprite-gen rife install`); on: the same repair, but no RIFE fails the loop; off: cut as filmed")parser.add_argument("--overlap-wrap", choices=OVERLAP_WRAP_MODES, default="on", help="--anchor motion-auto, under --repair auto or on: on (default): a cut two steps long whose wrap a part on its own beat leaves open (the seam gate refuses it) has four to twelve frames beside its wrap made again between the clip's frames a cycle apart and its own, each read with RIFE's single passes for a part torn — 34 calls of the binary a frame, up to forty frames (docs/loop-repair.md section 2, \"The overlapped wrap\"); off: not tried, recorded `wrap_overlap.skipped` with a warning line, and the gate refuses the cut as filmed — for a host whose RIFE runs on a CPU, where one frame of a 960 px clip takes minutes")+ parser.add_argument("--wrap-blend", choices=wrap_blend_mod.MODES, default="auto", help="--cycle pinned with --anchor none: auto (default): where the pinned last frame draws the first again (the first frame and it differ by more than --seam-max times the cut's median step, at full size), the last half second of the cut takes the first frame's drawing back in a ramp, only where the two ends differ by a redraw and the cell stands where the pin stands; a ramp that steps more than the cut already does, or does not shrink the wrap, is not used and a warning line says so (report `wrap_blend`, docs/loop-repair.md section 6); off: the cut as filmed")+ parser.add_argument("--unfixed", choices=UNFIXED_MODES, default="warn", help="walk/run, under --repair auto or on: a frame the jump repair leaves off the walk's flow — no group of up to two drawings brings it back, or the group that would was refused (its RIFE frame had a fault) — is recorded in jump_repair.unfixed; warn (default): a warning line, the loop kept; refuse: the loop fails")parser.add_argument("--jolt-max", type=float, default=None, help=f"walk/run: fail the repaired loop when its jolt index (how far each step strays from its neighbours' mean, over the median step) exceeds this. Default: no gate — the index is reported and a value over {repair_mod.JOLT_REFERENCE} is a warning line")parser.add_argument("--head-step-max", type=float, default=None, help=f"walk/run: fail the repaired loop when the head's largest sideways move in one frame exceeds this %% of the body height. Default: no gate — reported, and over {repair_mod.HEAD_STEP_REFERENCE} is a warning line")parser.add_argument("--facing", choices=FACINGS, default="right", help="which way the body faces in the frames (default right): the jolt index's hair, and the size reading video-loop-compare's jump guard reads, are behind it; the jump repair reads the flow either way")@@@ -2189,7 -2242,7 +2410,8 @@@ def run(**kwargs: object) -> intrepair=str(kwargs.get("repair") or "auto"), facing=str(kwargs.get("facing") or "right"),jolt_max=kwargs.get("jolt_max"), head_step_max=kwargs.get("head_step_max"), # type: ignore[arg-type]size_hold=str(kwargs.get("size_hold") or "auto"), steps=kwargs.get("steps"), # type: ignore[arg-type]- overlap_wrap=str(kwargs.get("overlap_wrap") or "on"), unfixed=str(kwargs.get("unfixed") or "warn"),+ overlap_wrap=str(kwargs.get("overlap_wrap") or "on"), wrap_blend=str(kwargs.get("wrap_blend") or "auto"),++ unfixed=str(kwargs.get("unfixed") or "warn"),)summary = {k: payload[k] for k in ("state", "frames_total", "window", "cycle_seconds", "n_out", "delay_ms", "resampled_seam_ratio", "specks_dropped", "report")}summary["cycle"] = {k: payload["cycle"].get(k) for k in ("kind", "start", "length", "period_global", "ratio", "review_recommended", "half_period_guard", "fundamental")}@@@ -2223,11 -2273,13 +2445,17 @@@if payload.get("wrap_overlap"):overlap = payload["wrap_overlap"]summary["wrap_overlap"] = {k: overlap[k] for k in ("seam", "frames", "side", "width", "seam_after", "skipped") if k in overlap}+ if payload.get("step_gate"):+ summary["step_gate"] = {k: payload["step_gate"][k] for k in ("drawings", "hold", "largest_ratio", "largest_into", "max",+ "skipped")+ if k in payload["step_gate"]}+ if payload["step_gate"].get("jitter"):+ summary["step_gate"]["jitter"] = [step["into"] for step in payload["step_gate"]["jitter"]]- if payload.get("jump_repair", {}).get("replaced"):+ if payload.get("jump_repair", {}).get("reading") == "seam":+ bridge = payload["jump_repair"]+ if "skipped" not in bridge:+ summary["jump_repair"] = {k: bridge[k] for k in ("reading", "seam", "replaced", "seam_after", "why") if k in bridge}+ elif payload.get("jump_repair", {}).get("replaced"):summary["jump_repair"] = {k: payload["jump_repair"][k] for k in ("replaced", "off_max_before", "off_max_after")}eased = [r for r in payload["jump_repair"]["rounds"] if r.get("why") == "ease" and r["outcome"] == "accepted"]if eased:diff --cc sprite_gen/video/repair.pyindex 6c57667,e54dd35..8c15a11--- a/sprite_gen/video/repair.py+++ b/sprite_gen/video/repair.py@@@ -1272,124 -1275,25 +1275,143 @@@ def repair_jumps(frames: list[Image.Imareturn out, record+ def _refused_left(frames: list[Image.Image], box: tuple[int, int, int, int], rounds: list[dict[str, Any]],+ limit: float) -> list[dict[str, Any]]:+ """The drawings of the flow groups the rounds refused that the loop as it now plays still reads at or over `limit` off+ its flow: a group refused keeps its frames as filmed, so a jump is left there. Each as `flow_targets` names a drawing+ `unfixed` — its frames and its reading (`off`, `turn`, `into`, `out`, `window`), here on the loop as it plays — and+ the faults that refused its group (`refused`)."""+ flow = _flow(frames, box)+ scores = _drawing_scores(flow)+ faults_of = {t: r["faults"] for r in rounds if r["why"] == "flow" and r["outcome"] == "rejected" for t in r["frames"]}+ left = []+ for d, run in enumerate(flow["runs"]):+ hit = [t for t in run if t in faults_of]+ if not hit or scores["off"][d] < limit:+ continue+ left.append({"frames": run, **{k: round(float(scores[k][d]), 4) for k in ("off", "turn", "into", "out")},+ "window": [round(v, 4) for v in flow["fractions"][int(scores["window"][d])]], "refused": faults_of[hit[0]]})+ return left+++# --- the seam bridge (docs/loop-repair.md section 2, "The seam bridge") -------------------------------------------++# A loop that is not a walk — an idle, an action cut whole — is not read for its flow: an idle's blinks and half-shut+# eyes leave the walk's flow, and the flow repair would make them again. Its wrap alone is read, on the frames as they+# play (`loop.cell_features`, the seam gate's own thumbnail): the step from its last frame to its first against the mean+# of the SURGE_AROUND steps either side of it. A wrap over the gate's limit there jumps, and the frames round it are made+# again by RIFE between the frames either side, the fewest first.+BRIDGE_WIDTHS = (1, 2, 4) # frames made round the wrap: ceil(m / 2) before it and floor(m / 2) after+BRIDGE_MIN_FRAMES = 2 * SURGE_AROUND + max(BRIDGE_WIDTHS) + 2 # the widest stretch and the steps either side, none shared+++def bridge_run(width: int, count: int) -> list[int]:+ """The frames a bridge `width` frames wide makes round the wrap of a loop `count` frames long, in play order."""+ return [*range(count - (width + 1) // 2, count), *range(width // 2)]+++def _ring(flat: np.ndarray) -> np.ndarray:+ """A loop's steps as it plays, on its frames' features: `ring[k]` from frame k to the next, the last into the first."""+ return np.abs(np.roll(flat, -1, axis=0) - flat).mean(axis=1)+++def _around(ring: np.ndarray, first: int, last: int) -> float:+ """The mean of the SURGE_AROUND steps before step `first` and after step `last` of a loop's steps (`_ring`)."""+ n = len(ring)+ near = [(first - 1 - i) % n for i in range(SURGE_AROUND)] + [(last + 1 + i) % n for i in range(SURGE_AROUND)]+ return max(float(ring[near].mean()), 1e-12)+++def seam_bridge(frames: list[Image.Image], interpolate: Interpolate | None, *, limit: float, hold: int | None,+ facing: str = "right", skip: str | None = None) -> tuple[list[Image.Image], dict[str, Any]]:+ """The seam bridge (docs/loop-repair.md section 2, "The seam bridge") of a loop that is not a walk.++ The wrap jumps where its step is over `limit` (the seam gate's) times the mean of the SURGE_AROUND steps either side+ of it, and over `loop.PIN_NOISE_MAX`, the re-render noise of a pinned first frame: a near-still loop moves so+ little a step that its ratios are large where nothing shows. Read on the frames as they play, cropped to their union+ box, on the seam gate's thumbnail (`loop.cell_features`). A loop drawn on twos or threes (`hold`, the cut's own,+ `held.measure_cycle`) is not bridged: a frame made round the wrap would split a drawing, and a loop that changes its+ drawing every other step reads the wrap against steps of nothing.++ A wrap that jumps is bridged BRIDGE_WIDTHS frames at a time, the fewest first (`bridge_run`): each frame made by+ `interpolate` between the frames either side of the run, at its own time (`between_time`), so the loop keeps its+ length. Before a frame is made the straight line between the two (their thumbnails, mixed in steps of one) is read:+ a run whose line leaves a step of the stretch from one to the other over `limit` times the mean of the steps+ either side is not made, a reading RIFE's frames have not brought under it on any loop measured. A run is taken+ where none of its frames carries an interpolation fault (`interpolation_quality.faults`, a ghost read where the+ ghost screen reads the stretch and the steps either side) and, read again with them, every step of the stretch is+ within `limit` times the mean of the steps either side; the first run taken ends the search. Where none is, the+ loop is kept as filmed for the seam gate to judge. At most 1 + 2 + 4 frames are made.++ `interpolate` None reads the wrap and stops at the first run to make (`unmade`). `skip` (why) reads nothing.+ `facing` reads nothing here: it is recorded for the jump guard of `video-loop-compare` (`restoration.jump`)."""+ from sprite_gen.video import loop as loop_mod # loop imports this module++ n = len(frames)+ record: dict[str, Any] = {"reading": "seam", "limit": limit, "floor": loop_mod.PIN_NOISE_MAX, "around": SURGE_AROUND,+ "widths": list(BRIDGE_WIDTHS), "facing": facing, "replaced": [], "tries": [], "calls": 0}+ if skip is not None:+ record["skipped"] = skip+ return frames, record+ if n < BRIDGE_MIN_FRAMES:+ record["skipped"] = f"a loop of {n} frames, under {BRIDGE_MIN_FRAMES}: no steps either side of the widest stretch"+ return frames, record+ box = loop_mod.cells_box(frames)+ flat = loop_mod.cell_features(frames, box)+ ring = _ring(flat)+ wrap = float(ring[-1])+ seam = wrap / _around(ring, n - 1, n - 1)+ record.update(seam=round(seam, 4), wrap=round(wrap, 5), hold=hold)+ if hold is not None and hold > 1:+ record["skipped"] = "drawn on twos or threes: a frame made round the wrap would split a drawing"+ return frames, record+ if seam <= limit or wrap <= loop_mod.PIN_NOISE_MAX:+ record["skipped"] = "the wrap reads as a step of the loop"+ return frames, record+ reads: bool | None = None+ for width in BRIDGE_WIDTHS:+ run = bridge_run(width, n)+ a, b = (run[0] - 1) % n, (run[-1] + 1) % n+ stretch = [(a + i) % n for i in range((b - a) % n)]+ line = float(np.abs(flat[b] - flat[a]).mean()) / len(stretch) / _around(ring, stretch[0], stretch[-1])+ tried: dict[str, Any] = {"width": width, "frames": run, "anchors": [a, b], "line": round(line, 4)}+ record["tries"].append(tried)+ if line > limit:+ tried.update(outcome="rejected", rejected_for="line")+ continue+ if interpolate is None:+ record["unmade"] = {k: tried[k] for k in ("frames", "anchors", "line")}+ break+ if reads is None:+ # the ghost screen on the stretch and the steps either side, read once a frame is to be made+ near = sorted({(a - SURGE_AROUND + i) % n for i in range(len(stretch) + 2 * SURGE_AROUND + 1)})+ reads = bool(ghost_screen([frames[k] for k in near])["reads"])+ out = list(frames)+ made = []+ for k in run:+ t = between_time(a, k, b, n)+ frame = interpolate(frames[a], frames[b], t)+ record["calls"] += 1+ if frame.mode != "RGBA" or frame.size != frames[k].size:+ raise ValueError("repair interpolator must return an RGBA frame of the original size")+ measure = {**smear(frame, frames[a], frames[b]), "outline_shift": outline_shift(frame, frames[a], frames[b]),+ "ghost": ghost(frame) if reads else None, "crossfade": crossfade(frame, frames[a], frames[b], t)}+ made.append({"frame": k, "t": round(t, 4), "proposal": measure, "look": looks(measure),+ "faults": faults(measure) + ([] if frame.getchannel("A").getbbox() else ["empty"])})+ out[k] = frame+ after_ring = _ring(loop_mod.cell_features(out, box))+ after = float(after_ring[stretch].max()) / _around(after_ring, stretch[0], stretch[-1])+ wrong = sorted({f for m in made for f in m["faults"]})+ tried.update(made=made, faults=wrong, look=sorted({w for m in made for w in m["look"]}), after=round(after, 4))+ if wrong or after > limit:+ tried.update(outcome="rejected", rejected_for="fault" if wrong else "seam")+ continue+ tried["outcome"] = "accepted"+ record.update(replaced=run, width=width, seam_after=tried["after"])+ return out, record+ return frames, record++# --- the jolt index (docs/loop-repair.md section 3) ------------------------------------------# Reference bounds, at the edge of what was kept on the 2026-10-03 takes (section 3): nothing keptdiff --cc tests/video/test_body_anchor_gate.pyindex 926ea27,bbfec83..6022d69--- a/tests/video/test_body_anchor_gate.py+++ b/tests/video/test_body_anchor_gate.py@@@ -178,13 -175,18 +179,19 @@@ def test_a_cut_the_source_frames_pass_iassert report["status"] == "passed" and report["seam_measurement"] == "source-frames"assert "seam_after_anchor" not in reportassert report["resampled_seam_ratio"] == plain["resampled_seam_ratio"]- assert reports[still]["strip"]["wrap_dx_px"] == 0- assert reports[sliding]["strip"]["wrap_dx_px"] != 0 and reports[nudged]["strip"]["wrap_dx_px"] != 0+ assert reports[still]["strip"]["wrap_dx_px"] == 0 and reports[sliding]["strip"]["wrap_dx_px"] != 0# the sliding walk's source frames read over the default limit: the forced limit passes them as they readassert reports[sliding]["resampled_seam_ratio"] > loop_mod.SEAM_RATIO_MAX+ message, report = _refused(tmp_path, nudged, "nudged-body")+ plain = _refused(tmp_path, nudged, "nudged-none", anchor="none")[1]+ assert report["seam_measurement"] == "source-frames" and "seam_after_anchor" not in report+ assert report["source_projection"]["wrap_dx_px"] != 0+ assert report["resampled_seam_ratio"] == plain["resampled_seam_ratio"] <= loop_mod.SEAM_RATIO_MAX+ assert message.startswith("video-loop: loop step ratio") and "into frame 1," in message+ assert report["seam_refusal"]["reading"] == plain["seam_refusal"]["reading"] == "steps"def test_a_pinned_walk_is_gated_by_its_pin_and_read_on_its_source_frames(tmp_path: Path):"""A clip pinned to end on its first frame: the cut is every frame but the last, and the gate is the pin. Thesliding walk's wrap reads over the seam limit on the source frames and the ramp moves its cells, but nothing is