@anvpx/motion 0.0.0-stage → 0.1.0

package/plugins/motion-kit/skills/motion-kit/references/storyboard-json.md

@@ -0,0 +1,121 @@
+# Storyboard JSON: the one file you write
+
+`mk validate` checks schema, scene props, timing and lint. It is strict: an unknown key is an error, not a warning. Read the pointer in the error, fix that one thing, and use `references/patching.md` after the first write.
+
+## Smallest valid shape
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "How a request reaches the data",
+    "width": 1920,
+    "height": 1080,
+    "fps": 30,
+    "theme": "default"
+  },
+  "scenes": [
+    {
+      "id": "intro",
+      "type": "title",
+      "duration": 4,
+      "move": "push-in",
+      "props": { "title": "How a request reaches the data" }
+    },
+    {
+      "id": "end",
+      "type": "outro",
+      "duration": 4,
+      "move": "push-in",
+      "props": { "title": "One public door" }
+    }
+  ]
+}
+```
+
+`version` is literally `1`. There is no version 2 and no migration command; a board with another version is invalid.
+
+## meta
+
+| Key        | Rule                                                                                                                                                                                                      |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`    | required, non-empty                                                                                                                                                                                       |
+| `width`    | pixels; default 1920. There is no `aspect` key: 16:9 = 1920x1080, 9:16 = 1080x1920, 1:1 = 1080x1080                                                                                                       |
+| `height`   | pixels; default 1080                                                                                                                                                                                      |
+| `fps`      | integer; default 30                                                                                                                                                                                       |
+| `theme`    | default `default`. Built-ins: `default`, `dark`, `tech-dark`, `calm-dark`. A template theme must be vendored into `themes/` (a `mk new` project does this; copying only the JSON elsewhere loses it)      |
+| `lang`     | optional language code                                                                                                                                                                                    |
+| `platform` | optional delivery-platform id: `facebook`, `linkedin`, `tiktok`, `youtube`, `podcast`, `reels`, `shorts`, `x`; adds that platform's safe margins. An unknown slug still validates, so pick from this list |
+| `approval` | optional `auto` or `confirm`; absent means auto                                                                                                                                                           |
+
+`mk validate` does not resolve `theme`; `mk build` and `mk preview` do. A board can validate and still fail at preview with `unknown theme "..."`. Check the theme before preview when you wrote the board by hand.
+
+## Scene keys
+
+| Key              | Rule                                                                                      |
+| ---------------- | ----------------------------------------------------------------------------------------- |
+| `id`             | required, unique, lowercase slug (`a-z`, `0-9`, hyphens)                                  |
+| `type`           | required; exactly a name from `mk catalog`                                                |
+| `duration`       | optional positive seconds; omitted = automatic from the text. Lint enforces reading time  |
+| `props`          | required object; strict. Only fields shown by `mk catalog <type>`, unlisted keys rejected |
+| `narration`      | optional spoken text for the voice path                                                   |
+| `words`          | optional voice word timings, normally written by the voice tool                           |
+| `shot`           | optional `wide`, `medium`, `close`, `overhead`                                            |
+| `move`           | optional `static`, `push-in`, `pull-out`, `pan-l`, `pan-r`, `tilt`, `orbit`, `reveal`     |
+| `ease`           | optional `linear`, `in`, `out`, `in-out`, `spring-soft`, `spring-snappy`                  |
+| `transition`     | optional `cut`, `crossfade`, `wipe`, `push`, `zoom-through`; base scenes only             |
+| `focus`          | optional label used by review                                                             |
+| `layer`          | optional `base` or `overlay`; omit for base                                               |
+| `over`, `offset` | overlays only: the base scene id they cover, and seconds into it (default 0)              |
+
+Defaults belong to the renderer; do not invent direction values. `mk catalog` lists prop defaults, not direction defaults.
+
+## Base and overlay
+
+- A base scene advances the timeline. An overlay stacks above it and does not advance it.
+- The overlay types are `lower-third`, `bug`, `progress`, `countdown`, `chapter`, `caption`.
+- Every overlay needs `layer: "overlay"`, `over: "<base id>"` and its own `duration` that fits inside the base scene. It does not take `transition`.
+- `offset` is seconds after the base scene starts.
+- A board with no base scene is invalid.
+- A base scene never takes `over` or `offset`.
+
+## Timing
+
+- Durations are seconds. A base scene's total is its own `duration`; overlays sit inside their base scene.
+- Transitions overlap adjacent base scenes, so the total is not simply the sum of durations. The worked example's four durations (4+6+4+4) plus three crossfades total 16.5 s.
+- `mk validate` reports errors and warnings, not the total. The total is printed by `mk patch`, `mk scene add`, `mk fit` and `mk preview`; use one of those (or read `preview.json`'s `totalSec`).
+- Lint enforces minimum hold and reading time (about 3 words per second of visible text, including the title and lines, not narration). A 6 s scene with only a short list still warns if nothing changes; add a `move`, shorten it, or split it.
+- About one new scene per 7 s is a useful planning number; `mk fit` can move the total only about 1.4x.
+
+## Props
+
+- Use the exact example shape from `mk catalog <type>`. Copy the example's key names, then replace values; do not rename keys or add explanatory fields.
+- Text limits are per field and are hard at validation (`<=70` means 70 characters, not words).
+- `[x]` marks an accent word in types that document it; do not use it as HTML.
+- Icons are names, not URLs: `mk icon search <word>` or `mk icon list [--tag group]`.
+- Images are local paths inside the project, with an `assets.json` ledger row. Remote URLs fail closed. Import with `mk assets import`, then pass the same `--assets` and `--ledger` to build, preview, approve and render; the image path is relative to `--assets`.
+- `highlight` is not uniform: `chart` and `table` use a 0-based item index; `code` uses an array of 1-based line numbers, for example `[1,3]`. The catalog currently prints the code field as a scalar, but the schema and validator require the array.
+- `chart`: `bar` and `donut` need `data`; `line` needs `x` and `series`; `highlight` is 0-based. `kpi-grid`: `trend` (`up|down|flat`) needs `delta`; `good` (`up|down`) needs `trend`.
+- `media-frame.callouts`: `x` and `y` are percentages 0-100, and each `label` is at most 24 characters.
+- An empty required text field is an error. Keep the copy short enough to read at phone width.
+
+## Decode these errors
+
+| Message                                                                    | Fix                                                           |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `unknown key(s): typo -> remove typo (check spelling against the catalog)` | remove the key or `mk catalog <type>` for the real field      |
+| `must be a lowercase slug (a-z, 0-9, hyphens)`                             | rename the scene id                                           |
+| `overlay needs over: <base scene id>`                                      | add `over` pointing at an existing base id                    |
+| `duplicate scene id "x"`                                                   | give every scene a unique id                                  |
+| `unknown theme "x"; use one of: ...` (at build/preview)                    | use a built-in theme, a vendored `themes/x.json`, or `mk new` |
+| `parent "/scenes/9" does not exist` (patch)                                | add the parent first, or use a path that exists               |
+
+## Writing checklist
+
+1. `version` is 1; `meta.title`, `width`, `height`, `fps`, `theme` are present.
+2. Every scene id is unique and a slug; every `type` came from `mk catalog`.
+3. Every base scene has a `move` and a `duration`.
+4. Every overlay has `layer`, `over`, `duration` and no `transition`; it fits its base.
+5. Every prop key came from `mk catalog <type>`; every text is within its limit.
+6. Every image exists locally and has a ledger row.
+7. `mk validate` prints `0 errors`; read warnings, do not ignore them.

package/plugins/motion-kit/skills/motion-kit/references/troubleshooting.md

@@ -0,0 +1,55 @@
+# Troubleshooting and exit codes
+
+Read the first `E` line, not the whole log. It names a pointer and usually a suggestion. Fix that one thing, re-run, then read the next.
+
+## First response
+
+1. `mk validate` / `mk preview`: read the pointer, compare that scene with `mk catalog <type>`, patch only that scene.
+2. Same error twice: stop changing flags. Rewrite the named scene from its catalog example via `mk patch`, or choose a different type.
+3. Third failure: stop. Tell the user the exact error and the two routes you tried; do not loop.
+4. Never disable lint, raise a limit by editing the output, or hand-edit the JSON to get past a gate.
+
+## Exit codes
+
+| Exit | Meaning                                                                    | Do                                                           |
+| ---- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| 0    | success (warnings allowed)                                                 | continue; read the warnings                                  |
+| 1    | tool, build or render failure                                              | `mk doctor`; read the last lines and `render-log.txt`        |
+| 2    | bad flags, unreadable file, validation errors, no preview for `mk approve` | fix the named pointer; run `mk preview` before approve       |
+| 4    | AWAITING_APPROVAL (`--gated`)                                              | not an error: show the pack, ask, `mk approve` only on a yes |
+| 5    | QA failed (`mk verify`)                                                    | fix the named scene or param, re-render once, then report    |
+| 127  | required program missing                                                   | give the install hint from `mk doctor`; do not retry blindly |
+
+## Named failures
+
+| Symptom                                    | Cause / fix                                                                                                                                                  |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `unknown key(s): typo`                     | prop not in the catalog: remove it or `mk catalog <type>`                                                                                                    |
+| `must be a lowercase slug`                 | scene id has spaces or capitals; rename to `a-z`, `0-9`, hyphens                                                                                             |
+| `overlay needs over: <base scene id>`      | add `"over": "<existing base id>"` and a fitting `duration`                                                                                                  |
+| `duplicate scene id "x"`                   | every id must be unique                                                                                                                                      |
+| `unknown theme "x"; use one of: ...`       | built-in theme, vendored `themes/x.json`, or `mk new`; `mk validate` does not catch this. If the theme is not built-in, preview before calling stage 5 done  |
+| `mk approve` exits 2 after a preview       | the preview used `--out`/`--assets`/`--ledger`/audio flags; repeat those exact flags. The printed `approve:` hint may omit `--out`, so do not trust it alone |
+| `no ledger row` or `no assetsDir`          | run `mk assets import` for each file, then pass the same `--assets d --ledger f` to build/preview/approve/render; `image` is relative to `--assets`          |
+| `parent "/scenes/9" does not exist`        | patch path skips a level; add the parent first or target an existing path                                                                                    |
+| `mk new` slot error (`max 5`, `text<=...`) | shorten or merge; never edit the generated board past the slot limit                                                                                         |
+| `mk fit` refuses "over the X s"            | the scenes cannot stretch that far: `mk scene add`, then fit; never pad or stretch past the range                                                            |
+| `mk approve` exits 2                       | no preview for the current inputs, or a flag differs from preview; re-preview                                                                                |
+| `mk render --gated` exits 4                | no approval or the inputs changed; preview again and ask again                                                                                               |
+| Preview exits 2                            | lint or validation failed; read the still/scene it names                                                                                                     |
+| `verify` exit 5                            | read the report line: streams, duration, fps or frame count; fix the named scene, render once                                                                |
+| `mk captions` asks for `--storyboard`      | ops need scene-relative paths; add the board                                                                                                                 |
+| `mk voice` fails closed                    | Python 3.12 venv or voice extras missing; `mk doctor`; ship silent if unavailable                                                                            |
+| Preview says the clip was skipped          | budget ran out; stills are still valid; offer `--budget-sec`                                                                                                 |
+| `mk state` exits 1                         | an artifact claims more than its inputs prove; fix the overclaim, do not re-preview blindly                                                                  |
+| No vision / cannot open the image          | say so; read `preview.json`; ask the user to open the pack and approve                                                                                       |
+
+## Recover without a rewrite
+
+- Wrong wording or number: `mk patch` replace the leaf.
+- Wrong pacing: `mk patch` replace `duration`, or `mk fit --seconds N`.
+- Wrong structure: `mk scene remove|move|add`, then validate.
+- Wrong look: change the theme or the direction fields, not the copy.
+- Wrong route: restart from `mk new` or `mk scene new`; do not bolt a second route onto a broken board.
+
+After any successful edit the approval is stale. Preview again, then ask.

package/plugins/motion-kit/skills/motion-kit/references/voice.md

@@ -0,0 +1,40 @@
+# Voice and captions (opt-in)
+
+The engine renders silent by default. Add narration only when the user asked for it or approved it. Never imply sound that is not in the preview.
+
+## Setup
+
+Needs Python 3.12, espeak-ng and the voice extras; see `references/setup.md`. `mk doctor` prints the voice rows, and missing voice tools never fail the overall exit code. If the venv is missing, say so and ship silent; do not fake timings or substitute a different voice.
+
+## Narration
+
+1. Add `"narration": "..."` to each base scene that speaks. Overlays are skipped. Write the words as they should be spoken, not as slide copy.
+2. Keep the words final before synthesis: `mk voice` needs the final script, and a later text edit invalidates the timing.
+3. `mk voice storyboard.json --voice <id>` writes a voice TimingManifest; the stdout line names it. Use a voice the user approved; do not hardcode one silently.
+4. The command preflights the narration against the scene duration and refuses before synthesis when it cannot fit; the silence gate can also refuse words that land inside silence. Fix the script or the scene duration; never edit the manifest to hide it.
+5. `mk qc` gates the manifest plus audio and reports PASS, WARN, FAIL or UNKNOWN. Quote its result; a synthetic file is not human-quality proof.
+
+## Captions
+
+- `mk captions <manifest> --storyboard storyboard.json --out ops.json` turns voice word timings into one karaoke `caption` overlay per narrated scene, already shifted to scene-relative time.
+- Apply the ops with `mk patch storyboard.json --ops ops.json`. Words past the scene duration are omitted and reported; do not silently keep them.
+- Keep each cue readable: about 20 characters/second, at most 2 lines and 42 characters per line. Shorten the text or split the cue rather than shrinking the type.
+- Export subtitles with `--srt file.srt` or `--vtt file.vtt`. Import existing cues with `--from-srt` or `--from-vtt`; import still needs `--storyboard` because the overlays need scene positions.
+- Preview again after adding captions. The approval covers the captions as part of the storyboard.
+
+## Audio and approval
+
+- `mk preview` accepts `--audio <manifest>`; `mk approve` infers it from the pack. Pass the same `--audio` to preview, approve and render.
+- The approval binds the storyboard, themes, assets, ledger, audio manifest and wavs. Any later wav, manifest or scene edit exits 4 at render; preview and ask again.
+- Optional music uses `--music`, `--music-volume` and `--music-license` on all three commands. A visual-only receipt never authorizes audio; narration-only never authorizes music.
+- If the preview clip is silent, say so in the ask. Do not describe the film as narrated until the audible preview exists.
+
+## Failure paths
+
+| Symptom                             | Do                                                                      |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| `mk voice` not installed / exit 127 | `mk doctor`; give the install hint; ship silent only if the user agrees |
+| narration refused before synthesis  | shorten the words or lengthen that scene; never edit timings            |
+| `mk qc` WARN or UNKNOWN             | report the exact state; do not call it PASS                             |
+| `mk captions` omits words           | tell the user which scene and how many; adjust the script or duration   |
+| render exit 4 after audio work      | the audio inputs drifted from approval; re-preview and re-approve       |

package/plugins/motion-kit/skills/motion-kit/references/worked-example.md

@@ -0,0 +1,170 @@
+# Worked example: brief to an approved preview
+
+A complete direct-storyboard run. Copy the shape, not the words. The numbers below are the ones this board actually produced.
+
+## Brief
+
+- Topic: how a request reaches the data.
+- Audience: colleagues who know the basics.
+- Length: about 18 s. Aspect: 16:9.
+- Facts: client calls the API gateway; the gateway authenticates; the gateway queries the database; median response last quarter was 120 ms.
+- Route: direct storyboard. No blueprint matched the exact three-service path, and the board is short enough to write.
+
+## Outline (sent before building)
+
+```text
+Plan: How a request reaches the data
+Audience: colleagues who know the basics | Length: ~18 s | Aspect: 16:9
+Route: direct storyboard, theme default - the path is the point
+Scenes:
+1. title - the question
+2. flow - client, gateway, database
+3. caption - the gateway checks every request
+4. stat - 120 ms median
+5. outro - one public door
+Assumed: silent, no brand colours, numbers from the last quarterly report
+Go, or what should change?
+```
+
+## The board
+
+```json
+{
+  "version": 1,
+  "meta": {
+    "title": "How a request reaches the data",
+    "width": 1920,
+    "height": 1080,
+    "fps": 30,
+    "theme": "default"
+  },
+  "scenes": [
+    {
+      "id": "intro",
+      "type": "title",
+      "duration": 4,
+      "move": "push-in",
+      "ease": "out",
+      "props": { "kicker": "Architecture", "title": "How a request reaches the data" }
+    },
+    {
+      "id": "path",
+      "type": "flow",
+      "duration": 6,
+      "move": "push-in",
+      "ease": "out",
+      "transition": "crossfade",
+      "props": {
+        "nodes": [
+          { "id": "client", "label": "Client" },
+          { "id": "api", "label": "API gateway" },
+          { "id": "db", "label": "Database" }
+        ],
+        "edges": [
+          { "from": "client", "to": "api", "label": "request" },
+          { "from": "api", "to": "db", "label": "query" }
+        ]
+      }
+    },
+    {
+      "id": "cap-path",
+      "type": "caption",
+      "layer": "overlay",
+      "over": "path",
+      "offset": 0.2,
+      "duration": 5.5,
+      "props": { "text": "The gateway checks every request." }
+    },
+    {
+      "id": "result",
+      "type": "stat",
+      "duration": 4,
+      "move": "push-in",
+      "ease": "out",
+      "transition": "crossfade",
+      "props": {
+        "value": 120,
+        "unit": "ms",
+        "label": "median response",
+        "context": "measured last quarter"
+      }
+    },
+    {
+      "id": "end",
+      "type": "outro",
+      "duration": 4,
+      "move": "push-in",
+      "ease": "out",
+      "transition": "crossfade",
+      "props": { "title": "One public door, checked every time" }
+    }
+  ]
+}
+```
+
+## Run it
+
+```bash
+mk validate storyboard.json
+# 0 errors, 0 warnings
+
+mk preview storyboard.json
+# preview ok | free storyboard | 4 scenes + 1 overlays 16.5s 1920x1080
+# pack out/storyboard.preview | contact.png 4 stills (+0 paired) clip 6.5s
+# est render ~1m (estimate) | lint 0 err 0 warn | approve: mk approve storyboard.json
+```
+
+Open `out/storyboard.preview/contact.png` and look at all four stills. Then ask. Only after an explicit yes:
+
+```bash
+mk approve storyboard.json --note "the user's exact words"
+mk render storyboard.json --gated --verify
+```
+
+The preview's 6.5 s clip caps each scene and is silent; the 16.5 s total includes three overlapping crossfades, so it is less than the 18 s sum. The final render is the only thing that proves the full duration, sound and motion. It was not run for this example; on a real task it is the step after the user's yes.
+
+## One feedback round
+
+Change the number:
+
+```json
+[{ "op": "replace", "path": "/scenes/3/props/value", "value": 95 }]
+```
+
+```bash
+mk patch storyboard.json --ops fixes.json
+# patch ok | 1 op | changed /scenes/3/props/value
+# scenes 5 | total 16.5s | 0 errors, 0 warnings
+```
+
+Add a closing rule:
+
+```bash
+mk scene add storyboard.json callout --after result --set text="[Fewer] hops, same answer" --duration 4
+# scene add ok | callout-1 (callout) at 5/6 | total 20.5s | 0 errors, 0 warnings
+```
+
+Bring it back to 20 s:
+
+```bash
+mk fit storyboard.json --seconds 20
+# fit ok | 20.5s -> 20s (target 20s) | 5 scenes | fallback range (no template pacing)
+```
+
+Every one of those edits re-arms approval. Preview again and ask again; do not reuse the old yes.
+
+## Ask in three lines
+
+```text
+Preview: 4 base scenes + 1 caption overlay, 16.5 s, silent, 16:9.
+Shown: contact.png and the 6.5 s clip. Not shown: voice, motion between stills, and scenes without a still.
+If this works, say "yes" and I will render; otherwise tell me which frame or line to change.
+```
+
+## What this example teaches
+
+- The base scenes carry the timeline; the caption overlay does not add duration.
+- `move` on every base scene keeps the film out of the flat-static lint.
+- The direct route needs no template, but it does need a theme that resolves (`default` here).
+- Preview is cheap and silent; render is the expensive, gated step.
+- A hash or a lint pass is not a quality review. The stills are.

package/shared/themes/README.md

@@ -0,0 +1,5 @@
+# Shared themes
+
+Theme files referenced by templates as `"file": "@shared/<name>.json"`. The loader reads them from this folder; a theme id is its file name without `.json`.
+
+Sixteen files: nine families (`calm`, `bold`, `data`, `editorial`, `tech`, `playful`, `pop`, `warm`) in `-light` and `-dark`. Family table, fonts and guarantees: `../README.md`; motion presets: `../styles-guide.md`.