@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/talking-head-video-pipeline/references/workflows/doctor.md

@@ -0,0 +1,51 @@
+# Naive Video Doctor
+
+Diagnose before changing anything.
+
+Resolve `<skill_root>` by locating the installed `talking-head-video-pipeline/SKILL.md`; do not assume the user's current directory is the skill directory.
+
+## Commands
+
+Environment:
+
+```bash
+bash <skill_root>/scripts/doctor.sh
+```
+
+Project:
+
+```bash
+python3 <skill_root>/tools/video_doctor.py --project <project_dir>
+```
+
+Captions:
+
+```bash
+python3 <skill_root>/tools/caption_check.py <srt> [<csv>]
+```
+
+Design contract:
+
+```bash
+python3 <skill_root>/tools/design_check.py <project_dir>/DESIGN.md
+```
+
+## Diagnosis Order
+
+1. Missing required tools.
+2. Missing or invalid state.
+3. Missing source or outputs referenced by state.
+4. Failed caption, typography, component, or other quality gate.
+5. Renderer process or port state.
+6. Codec/browser compatibility.
+7. Timeline or asset-duration mismatch.
+
+## Output
+
+List findings by severity:
+
+- `BLOCKER`: work cannot continue.
+- `WARNING`: work can continue with risk.
+- `INFO`: current verified state.
+
+Give the smallest repair order. Do not edit files, kill processes, delete outputs, or migrate state in doctor mode.

package/skills/talking-head-video-pipeline/references/workflows/export.md

@@ -0,0 +1,50 @@
+# Naive Video Export
+
+Render the approved composition with original-quality media and master audio.
+
+Resolve `<skill_root>` by locating the installed `talking-head-video-pipeline/SKILL.md`; do not assume the user's current directory is the skill directory.
+
+## Preconditions
+
+1. Read state and G4 approval.
+2. If approval is pending, stop and request preview confirmation unless state records `skipped_by_user`.
+3. Re-run G0 and confirm the original `main_video` still exists. Resolve the timeline base as `working_video` when present, otherwise `main_video`.
+4. Determine final target resolution from the request or source; do not infer true 4K from a 1080p proxy.
+
+## Stable Strategy
+
+Prefer:
+
+1. Render transparent motion overlays at final resolution.
+2. Use the approved full-quality timeline base (`working_video` after rough cutting, otherwise `main_video`) as the ffmpeg base.
+3. Composite inserted demos and overlays at their timeline positions.
+4. Map audio from that same intended timeline base.
+
+Use this strategy for 4K HEVC/Main10 or whenever preserving the locked base is important. Read `references/export-recipes.md`.
+
+## Rendering
+
+- Write long render output to a log file.
+- Poll progress without killing the process.
+- If frames advance, wait.
+- Resume only when the renderer supports a safe resume contract.
+- Replace damaged partial output only after the full rerender starts successfully.
+- Set state to `rendering` with output path and log path.
+
+## Final Gate
+
+Verify with `ffprobe`:
+
+- file exists and is non-empty
+- duration
+- resolution
+- frame rate
+- video codec
+- audio codec and stream presence
+- intended timeline-base audio packet count or equivalent synchronization evidence
+
+Perform visual frame checks unless the user explicitly declines them. Set `final_ready` only after G5 passes.
+
+## Completion
+
+Return the final file path, containing folder path, duration, resolution, and audio confirmation. State clearly if visual QA was skipped at the user's request.

package/skills/talking-head-video-pipeline/references/workflows/init.md

@@ -0,0 +1,51 @@
+# Naive Video Init
+
+Create a resumable project without modifying source media.
+
+Resolve `<skill_root>` by locating the installed `talking-head-video-pipeline/SKILL.md`; do not assume the user's current directory is the skill directory.
+
+## Workflow
+
+1. Resolve `project_dir` and `main_video` from the user's message and attachments.
+2. If `.naive-video-state.json` exists, do not reinitialize. Run project doctor and route to status or the requested stage.
+3. Run environment checks:
+
+   ```bash
+   bash <skill_root>/scripts/doctor.sh
+   ```
+
+4. Inspect the source with `ffprobe`. Record duration, resolution, frame rate, codecs, pixel format, and audio stream.
+5. When it is unclear whether the source is raw, ask one question: `这段视频已经粗剪好了吗？` If no, read `references/video-use-integration.md` and load `references/workflows/rough-cut.md` before captions. Do not ask about transcription services when the video is already rough-cut.
+6. Ask whether the user wants `quick` or `guided` setup only when they did not already request speed or provide a style reference.
+7. Run:
+
+   ```bash
+   python3 <skill_root>/tools/bootstrap.py \
+     --project <project_dir> \
+     --video <main_video> \
+     --mode <quick-or-guided>
+   ```
+
+8. If a private default profile exists, tell the user it was loaded. Use `--profile none` when the user wants a clean project without prior preferences.
+9. In guided mode, ask one question at a time using `references/style-onboarding.md`, then update `DESIGN.md` and the state style profile.
+10. Read `references/asset-onboarding.md`. Ask whether screenshots, recordings, product images, charts, or demo videos should appear. If yes, record whether placement will be `semantic`, `exact`, or `hybrid`; explain that user-supplied seconds or spoken-sentence anchors are more precise.
+11. Add all supplied assets and known anchors to `EDIT_PLAN.md`. Do not load the media into the public skill.
+12. Run:
+
+   ```bash
+   python3 <skill_root>/tools/video_doctor.py --project <project_dir>
+   ```
+
+## Adoption
+
+For an older project with existing files, use `--adopt-existing`. Detect files but do not move or rename them. Set the stage only to the last quality gate that passes.
+
+## Completion
+
+Report:
+
+- project directory
+- source duration and resolution
+- files created
+- missing optional tools
+- next phrase: `先帮我粗剪` when raw footage needs it, otherwise `抽字幕轴` or `用现有字幕做预览`

package/skills/talking-head-video-pipeline/references/workflows/learn.md

@@ -0,0 +1,36 @@
+# Naive Video Learn
+
+Turn explicit feedback into a testable project-local rule.
+
+Resolve `<skill_root>` by locating the installed `talking-head-video-pipeline/SKILL.md`; do not assume the user's current directory is the skill directory.
+
+## Preconditions
+
+- The user must clearly confirm the preference.
+- The rule must be observable and testable.
+- Read `references/self-iteration.md`.
+
+## Workflow
+
+1. Capture a short faithful quote or paraphrase.
+2. Classify scope as `project`, `profile`, or `product-candidate`.
+3. Default ambiguous feedback to `project`.
+4. Write the lesson to `VIDEO_LESSONS.md` using the protocol format.
+5. If the lesson is an active style rule, update only the matching field in `DESIGN.md` and state.
+6. For `profile` scope, initialize the private local profile when needed and add only the sanitized confirmed rule:
+
+   ```bash
+   python3 <skill_root>/tools/profile.py init
+   python3 <skill_root>/tools/profile.py add-rule --stage <stage> --rule <sanitized_rule>
+   ```
+
+7. If it supersedes an older rule, mark the older lesson as superseded and keep only the active rule in `DESIGN.md`.
+8. Never copy private context into this skill repository or GitHub automatically.
+
+## Product Candidates
+
+For a generic hard correctness issue, record only a sanitized description in the user's project and tell the maintainer it is eligible for review. Publication remains a separate maintainer action.
+
+## Completion
+
+Show the exact confirmed rule, its scope, and the file updated.

package/skills/text-to-lottie/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: text-to-lottie
+description: "Create, edit, or fix Lottie/Bodymovin JSON animations for the local Skia Skottie player. Use for text-to-Lottie, SVG/logo/type animation, loaders/icons, state feedback, UI microinteractions, lower thirds, diagrams, data/stat/chart animations, product promos, scene/camera motion, visual effects, scene edits, slots/controls, and Skottie debugging. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "diffusionstudio/lottie"
+---
+
+# Text To Lottie
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+Author production-ready Lottie JSON for the official local Skia Skottie player.
+The deliverable is a renderable scene in the player, not isolated JSON.
+
+## Operating Model
+
+- Use the official player project and verify in Skia Skottie. Do not hand-roll a
+  custom viewer or switch renderers for verification.
+- Keep the skill portable across Agent Skills clients. Avoid host-specific
+  commands, command modes, or orchestration conventions in skill instructions.
+- Prefer fewer questions and stronger defaults. Ask only when a decision changes
+  the output materially, such as transparent vs full-frame background, brand
+  constraints, target format, or supplied source assets.
+- Prioritize clean, intentional, professional motion over merely satisfying the
+  literal prompt.
+
+## Reference Loading
+
+This `SKILL.md` is the thin control plane. Load only one-level references that
+match the task. Do not open the whole reference library.
+
+Always read `references/player-contract.md` before creating, editing, fixing, or
+verifying a scene. If a routed reference is unavailable, continue using the
+inline rules in this file.
+
+| User intent | References to read when present |
+| --- | --- |
+| Any new/edit/fix Lottie scene | `references/player-contract.md` |
+| JSON structure, keyframes, slots, shapes, assets | `references/lottie-spec-map.md` |
+| Logo animation | `references/recipe-logo.md`, `references/motion-taste.md`, `references/design-taste.md` |
+| Typography, title, quote, text reveal | `references/recipe-typography.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| Lower third, name tag, caption bar, overlay | `references/recipe-lower-thirds.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| Loader, icon, spinner, badge animation | `references/recipe-loaders-icons.md`, `references/motion-taste.md` |
+| Success, error, warning, completion, empty state | `references/recipe-loaders-icons.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| UI microinteraction | `references/recipe-ui-microinteractions.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| Generic "animate this SVG" or SVG-to-Lottie | `references/recipe-svg-animation.md`, `references/svg-compatibility.md`, `references/motion-taste.md` |
+| Camera follow, pan, zoom, parallax, scene motion | `references/recipe-camera-scene-motion.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| Diagram, technical line animation, callout, flow trace | `references/recipe-diagram-technical.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| Data, stats, KPIs, charts, metrics, dashboard figures | `references/recipe-data-stats.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| Product launch, feature announcement, social promo | `references/recipe-product-promo.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| Long text, multiple ideas, list/features/steps, timeline, before/after, problem/solution, quote+proof, recap/story, product walkthrough, multi-language variations, chapters, multi-beat sequence, episode, jump/hard cuts, transition grammar | `references/chapterization-transition-grammar.md`, `references/motion-taste.md` |
+| Glow, glass, metal, gradient, fill, bubble/burst effects | `references/recipe-visual-effects.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| SVG input inside logo/icon/UI/lower-third work | The task recipe plus `references/svg-compatibility.md` |
+| Starter brief or reusable project direction | `references/recipe-starter-projects.md`, `references/design-taste.md`, `references/motion-taste.md` |
+| Any "premium", "clean", "minimal", "modern", "sleek", or "polished" qualifier | `references/design-taste.md` (restraint defaults), plus the routed recipe |
+
+For mixed prompts, choose one primary recipe from the main deliverable, then add
+secondary references for source format or visual treatment. Examples: SVG logo
+with glow uses logo as primary plus SVG compatibility and visual effects;
+product launch with pan/zoom uses product promo plus camera scene motion;
+technical SVG diagram tracing uses diagram/technical plus SVG compatibility;
+kinetic title with glass sweep uses typography plus visual effects.
+
+## Workflow
+
+1. Route the task using the table above. Read only the relevant references that
+   exist.
+2. Locate the official player project and resolve the target scene using the
+   target precedence below. Before editing, verify the resolved path is
+   `public/projects/<project>/<scene-N>/lottie.json`; re-read that current file
+   immediately before overwriting because the UI can write slot edits back to
+   source.
+3. Decide the background policy before authoring.
+4. Write or update `public/projects/<project>/<scene-N>/lottie.json` and, when
+   useful, `controls.json`.
+5. Validate JSON, run or reuse the dev server, inspect exact frames with
+   `?frame=N`, and fix render/design/motion issues before finishing.
+
+## Inline Rules
+
+### Design Defaults (always apply)
+
+These few defaults are non-negotiable and apply to every designed scene. Load
+`references/design-taste.md` for the full reasoning, especially for any
+"premium", "clean", "minimal", "modern", or "card" prompt.
+
+- Premium means subtract, not add. When a prompt says premium, clean, minimal,
+  modern, sleek, or sophisticated, default to restraint: remove chrome before
+  adding it. Premium is carried by scale, weight, brightness, spacing, and
+  timing, never by cards, borders, dividers, shadows, glow, or stacked tints.
+- Chrome/container budget is `0` by default. Do not add a framing card,
+  container, border, or divider unless it does a job that whitespace and
+  alignment cannot. Separate grids and columns with negative space and alignment
+  first, a single hairline second, and a filled or bordered card last and only
+  when explicitly warranted.
+- One surface tone. Use one background tone. Do not stack two near-black or two
+  near-white tints to fake a "surface"; it reads muddy. If a card surface must
+  differ from the background, make it one deliberate step with a clear purpose.
+- One divider treatment, one color. If dividers are truly needed, use one weight
+  and one color for all of them, title rule and column rules included. Never use
+  slightly different colors or weights per divider.
+
+### Scene Rules
+
+- Scene files live at `public/projects/<project>/<scene-N>/lottie.json`.
+- Resolve target scenes by authority: an explicit file path wins; a browser URL
+  route like `/<project>/<scene>` wins next; an already-known project/scene for
+  the task wins next; otherwise create a new safe scene. Use `/__context` only
+  for discovery, verification, or playback state unless the task explicitly says
+  to edit what is currently on screen and no more specific target exists. Do not
+  let `/__context.live` override a known file path, URL, or project/scene.
+  Overwrite `main-project/scene-1` only if it is still the untouched placeholder;
+  otherwise create a new scene.
+- Full-frame standalone compositions should include a visible background layer
+  with a `bgColor` slot and `controls.json` entry.
+- Transparent-by-default outputs include logos, icons, loaders, overlays, lower
+  thirds, and SVG-derived assets unless the user asks for a background.
+- Include top-level `v`, `fr`, `ip`, `op`, `w`, `h`, `nm`, `assets`, and
+  `layers`. Treat `op` as exclusive.
+- Use purposeful easing and staging. Avoid defaulting to linear motion. Derive
+  easing from the behavior-based anchors in `motion-taste.md` (chosen by motion
+  behavior, focal element strongest); do not fall back to one uniform ease for
+  every layer.
+- Use slots for important editable values and add `controls.json` labels/ranges
+  when they improve the properties panel.
+- For SVG input, preserve the viewBox, normalize styling, watch fill rules and
+  intersections, and verify the result in Skottie.
+- Native Lottie text/text slots (`ty:5`) render in this player when the scene
+  ships its font: drop a `.ttf`/`.otf`/`.ttc` next to `lottie.json`, declare it in
+  `fonts.list` with `fFamily` matching the font's embedded family name, and
+  reference it from text documents. The loader passes every scene font to Skottie.
+  Prefer native text; reach for vector/shape text only for deliberate path effects
+  (stroke-on, glyph morphs, handwriting). See the player-contract "Native Text"
+  reference.
+
+## Verification
+
+Before finishing:
+
+1. Confirm the intended target file path is
+   `public/projects/<project>/<scene-N>/lottie.json`.
+2. Validate JSON:
+
+   ```bash
+node -e "JSON.parse(require('fs').readFileSync('public/projects/<project>/<scene-N>/lottie.json','utf8'))"
+```
+```
+3. Confirm the official player is running and the scene appears in
+   `GET /__context`.
+4. Inspect pinned frames in the browser. For new scenes, check frame `0`,
+   midpoint, and `op - 1`.
+5. Confirm the background policy matches the use case.
+6. Check for blank canvas, missing assets, unstyled shapes, wrong layer order,
+   bad easing, awkward timing, cropped content, text overflow, and visible SVG
+   artifacts.
+7. Finish only when the animation renders cleanly and feels intentional.
+```
+
+## Maintenance Evals
+
+Do not read eval files during normal animation work. Use them only when testing
+or changing this skill:
+
+- `evals/trigger-prompts.json`
+- `evals/routing-prompts.json`
+- `evals/reference-loading-prompts.json`
+- `evals/output-rubric.md`
+
+## Source
+
+Rewritten for AICUT from [`diffusionstudio/lottie`](https://github.com/diffusionstudio/lottie)
+(MIT), skills/text-to-lottie/SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/text-to-lottie/references/chapterization-transition-grammar.md

@@ -0,0 +1,132 @@
+# Chapterization And Transition Grammar
+
+Use this when a prompt is dense or naturally multi-part. It decides whether to
+split into chapters, what each chapter does, and how to move between them.
+Easing anchors (see `motion-taste.md` → "Easing Anchors") are supporting tools
+here, not the transition itself.
+
+## When To Chapter
+
+Split into chapters when the prompt carries more than one idea: long text,
+multiple claims, feature list, multiple stats, timeline, before/after,
+problem/solution, quote+proof, setup/payoff, product walkthrough, recap/social
+story, or multi-language / repeating content variations. One readable idea per
+chapter.
+
+## When Not To Chapter
+
+Keep one beat for a single logo lockup, one CTA, one icon animation, one simple
+stat card, one UI microinteraction, a legal/read-critical block, or a calm hero
+moment whose final settle is the payoff. Let it land and settle.
+
+## Chapter Roles
+
+Give each chapter one readable job: hook, setup, claim, proof, contrast, detail,
+payoff, CTA / final lockup, or loop bridge.
+
+## Split By Meaning, Not Length
+
+Rewrite long text into short authored beats or reveal it progressively. Never
+place a paragraph at once, and do not just chop it into smaller paragraph blocks.
+Each chapter carries one idea.
+
+## Structure Modes
+
+- Repeated armature: same layout and motion path, content changes. Best for
+  lists, stats, languages, recaps, supercuts.
+- Evolving story layout: objects/text carry into new positions and the
+  composition changes across chapters. Best for product walkthroughs, explainers,
+  process, setup/payoff, and narrative motion.
+
+## Readable Window
+
+Each chapter's main message gets a coast, hold, or stable moment before the seam.
+Fast transitions are fine, but never at the cost of the read.
+
+## Transition Grammar (pick one per seam)
+
+- hard cut on action: cut while the focal motion is still moving.
+- jump cut: hard cut with matched direction/velocity across the seam.
+- motion-masked swap: outgoing motion becomes the next beat's reveal/mask.
+- continuous carry: an object/text travels into its next location across chapters.
+- occlusion wipe: a large shape covers frame, then reveals the next chapter.
+- hold/settle cut: only when the beat must land clearly first.
+- loop reset: when the cadence intentionally repeats.
+
+## Choosing Transitions (message + tone)
+
+- Energetic list/supercut/recap → repeated armature + hard cut / jump cut on motion.
+- Narrative / product walkthrough → continuous carry or motion-masked swap.
+- Contrast or palette/world change → occlusion wipe or hard cut.
+- Premium / stat / proof → restrained mask or hold/settle cut.
+- Read-critical → hold longer; never cut before it is understood.
+- Every seam needs a reason — preserve continuity, create contrast, reset rhythm,
+  or land a point. Do not vary transition types randomly.
+
+## Seam Mechanics
+
+A transition is chapter role + timing + direction + cut point + masking +
+easing — not easing alone; anchors only support it. Carry across seams: cut
+during motion for cut-on-action (never after a settle); match direction and
+perceived velocity across jump cuts; a readable coast/hold must precede any fast
+exit; and interrupted motion only reads as intentional under repeated rhythm (an
+armature of ~3–4+ beats), not as a one-off.
+
+Author cut-on-motion exits so the natural endpoint lives beyond the visible cut:
+the visible chapter is a window into a longer arc (e.g. it ends at frame 100 but
+the move would resolve toward ~120–140), and the seam interrupts the move while
+velocity is still active, often rising, before the motion settles. The core rule
+is active continuation, not necessarily acceleration: velocity may be rising
+(kinetic exit), steady (a constant pan), or already high and steady (a fast
+object pass) — what matters is it is not settled and would continue if the
+chapter were extended.
+
+| method | why the seam works | outgoing last frame | incoming first frame | anchors | switch when |
+|---|---|---|---|---|---|
+| hard cut on action | eye is mid-move, so motion continuity hides the content jump | focal element still moving (velocity active, often rising) toward a beyond-window/offscreen endpoint; not arriving at its final authored target on the cut frame | new content already in motion, compatible direction; no static hold | out `exit-accelerate`/`travel-cut`; in `entrance-sharp` | beat must be read at rest → hold/settle cut |
+| jump cut | as hard cut, but the match across the seam sells continuity | moving toward a beyond-window endpoint (velocity active, often rising); note direction + perceived speed; not arriving at the final target on the cut frame | enters same direction at similar speed; position may reset | out `exit-accelerate`/`travel-cut`; in `travel-balanced`/`entrance-sharp` | single beat / no rhythm → looks broken; use hold/settle or carry |
+| motion-masked swap | outgoing motion (or the shape it leaves) becomes the matte that reveals the next beat — no visible cut; the content change happens entirely while the mask hides it | the moving element fully covers the swap region / mask filled | next content already composed under the mask, revealed as it clears | `entrance-sharp` for the reveal; out `travel-balanced` | nothing shared to mask with → hard cut or occlusion wipe |
+| continuous carry | one persistent element travels between chapters; identity continuity, often no cut | carried element mid-travel toward its next position | same element, or clearly related element, continues from matching position/velocity or preserved motion logic (not a fresh unrelated entrance); surroundings may change | `travel-balanced`; `settle-soft` if it lands | chapters share no element / need a clean reset → hard cut or occlusion wipe |
+| occlusion wipe | a large shape covers the frame, hiding the swap, then uncovers the new chapter | covering shape fully occludes the frame (or swap region) | new chapter already fully composed behind the cover before it exits; revealed as the shape leaves | `entrance-sharp` for cover-on + reveal; `travel-balanced` for the sweep | want energy/continuity, not a full cover → hard cut or carry |
+| hold/settle cut | the beat fully lands and is read, then changes — clarity over pace (opposite of cut-on-motion: the move completes and holds before the seam) | motion settled; message readable and at rest (a hold of N frames) | clean start of the next beat (an entrance, not mid-motion) | `settle-soft` to land; `entrance-sharp` to start next | pace/energy matters more than the settle → hard cut on action |
+| loop reset | last frame matches first (position, color, velocity) so the wrap is invisible; or a deliberate visible reset beat | state equals the first frame's state (seamless), or a deliberate exit for a visible reset | identical to the loop start; perceived velocity continuous | match in/out velocity (often `travel-balanced`/linear); `exit-accelerate`+cut for a visible reset | one-shot, not a loop → normal ending (settle) |
+
+## Seam Plan (before authoring)
+
+Decide, per seam, before keyframing:
+
+- chapter role — what this beat does
+- readable window — where the message coasts/holds
+- outgoing motion — what's moving at the end (direction + speed)
+- transition type — from the grammar
+- incoming motion — what's moving at the start
+- easing anchor — the supporting curve
+- cut/hold frame — the exact seam frame; in-motion vs at-rest
+- reason for the seam — continuity / contrast / rhythm reset / land a point
+
+## Seam Verification
+
+Inspect the two boundary frames per seam:
+
+- Render the outgoing last frame and the incoming first frame; confirm each meets
+  its row's two frame conditions above.
+- Cut-on-action / jump cut: outgoing last frame is still moving (not settled);
+  direction + perceived velocity match on the incoming first frame. Check the
+  outgoing motion would continue if the chapter were extended — if the object
+  reaches its final target on the seam, it is a settle cut, not cut-on-motion.
+- Masked swap / occlusion wipe: no gap frame where neither chapter is composed;
+  the mask/cover fully occludes at the swap.
+- Continuous carry: the carried element's position + velocity match across the
+  seam, or the motion logic is visibly continuous enough that the eye can follow
+  it (related element / transform is fine).
+- Hold/settle cut: the message is readable and at rest before the cut.
+- Loop reset: first and last frames match (position, color, velocity) unless the
+  reset is intentional.
+
+## Guardrails
+
+- Jump/hard cuts need repeated rhythm or a clear editorial reason; one isolated
+  interrupted move can look broken.
+- Cut-on-motion should usually match direction/velocity across the cut.
+- Avoid high-energy chapter cuts for calm luxury/institutional tone, final logo
+  lockups, legal text, or anything that must settle to be understood.