cueframe 0.11.0 → 0.11.4

package/dist/skills/cueframe-cli/SKILL.md

@@ -5,13 +5,7 @@ description: Use when editing, clipping, or rendering video via the CueFrame CLI
 
 # CueFrame CLI
 
-## Scope and capability policy
-
-User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
-
-Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
-
-For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+Use the [project and capability policy](../composing-video/references/project-policy.md) for scope, current state and metered work.
 
 ## MCP is the primary surface — read this before using the CLI
 
@@ -65,6 +59,14 @@ Validate first, then use `preview_card` / `preview_component` for isolated graph
 MCP tools or the CLI's `api` escape hatch with the live request contract. Full `render` is for
 delivery, not checking each edit. CLI validation does not replace visual evidence.
 
+To compare a certified reference frame with an existing saved preview, use `compare`:
+
+```bash
+npx -y cueframe@0.11 compare <projectId> --reference-media <mediaId> --reference-representation <identity> --reference-frame 117 --candidate-job <jobId> --candidate-artifact <artifactId> --out ./comparison --json
+```
+
+The command calls the shared comparison operation; it does not rerender the composition. `--views overlay,difference` selects diagnostics and `--crop x,y,width,height` uses one common-coordinate crop. NDJSON contains source identities and image receipts, never base64 payloads. `--out` saves verified PNGs; without it, image receipts explicitly say `metadata_only`. Inspect those images and relevant motion before judging the film.
+
 ```bash
 # 0. Always use --json for agent-driven runs (NDJSON to stdout, no spinners).
 #    Commands run against production; auth is stored in ~/.cueframe/auth.json.

package/dist/skills/cueframe-component-authoring/SKILL.md

@@ -1,187 +1,38 @@
 ---
 name: cueframe-component-authoring
-description: Use when authoring, forking, or customizing a CueFrame motion-graphics component/primitive/graphic — e.g. "customize the parallax look", "make my own animated lower-third", "fork a CueFrame template and edit it", "author a custom graphic and render it". Covers cloud MCP, local desktop, and CLI project paths using complete versioned source snapshots. Use BEFORE hand-writing a component from scratch — forking a built-in is usually the faster start.
+description: "Use when authoring, forking or customizing CueFrame HTML cards, motion-graphics primitives or reusable native components, including a fork of an exact catalog source. Covers cloud MCP, local desktop and CLI project paths using complete versioned source snapshots. For scene-shot devices and cameras use cueframe-scene-shot. Triggers on \"customize the parallax look\", \"make my own animated lower-third\", \"fork a CueFrame template and edit it\", \"author a custom graphic and render it\". Use before hand-writing a component from scratch: forking a built-in is usually the faster start."
 ---
 
-# CueFrame component authoring (fork / customize / own)
+# CueFrame graphic authoring
 
-## Scope and capability policy
+Use the [project and capability policy](../composing-video/references/project-policy.md). Preserve the current project and source identities; make the intended visual behavior inspectable and editable.
 
-User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
+## Choose the representation
 
-Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
+- **HTML card:** authored typography, UI, diagrams and 2D motion with deterministic CSS. It can depict perspective, but does not provide the scene renderer's physical camera, lighting or occlusion.
+- **Whole-clip keyframes:** position, scale, rotation and opacity when the entire card or layer moves together. Read the current `clip.setKeyframes` schema; times are relative to the clip.
+- **Scene shot:** supported groups, devices, pages, world text, surfaces and cameras. Use `cueframe-scene-shot` and its current schema; author JSON, not the generated wrapper.
+- **Native component:** reusable version-4 media-tile scenes with declared inputs, assets and deterministic rendering. Discover a near-fit definition before writing one. Read the [native source contract](references/native-source-contract.md), then the applicable [MCP, CLI or desktop workflow](references/native-component-workflows.md). This is not an arbitrary browser application runtime.
 
-For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../cueframe-compose-loop/references/preview-workflow.md).
+A definition, preset and recipe are different catalog items. Preserve the selected item's exact scoped identity. A builtin source read needs `componentId`, `sourceVersionId` and `builtinCollection`; unavailable pins do not authorize a different source. Keep the complete template, manifest and definition when forking.
 
-Use `cueframe-compose-loop`'s [preview workflow](../cueframe-compose-loop/references/preview-workflow.md)
-to select hosted or local evidence and separate iteration from final delivery.
+## Cards: geometry, clock and controls
 
-CueFrame ships built-in motion-graphics definitions (titles, lower-thirds, captions,
-effects, transitions and layouts). Discover the current catalog; fork an exact definition, customize it,
-and render it on CueFrame — or author a brand-new component. This is shadcn-for-video: own the
-component code; CueFrame is the reliable engine that renders it.
+A card source is `{kind:"card", html, tokens}`. Each token key `x` becomes the CSS property `--cf-x`; read `var(--cf-x)`. Keys have no leading dashes. Missing variables silently invalidate CSS, so inspect returned warnings and actual output. Use literal or supported whole-string brand references and do not overwrite reserved motion variables.
 
-**Before you hand-write 3D:** a device mockup or a screenshot floating in a lit 3D scene is a
-**scene shot** — validated JSON with `scene.add` / `scene.update`, not a component you author.
-See the `cueframe-scene-shot` skill and `cueframe://scene-shot`. Author a component here when
-you need behaviour the scene contract does not express.
+The host injects a clip-local clock each frame: `--cf-frame`, `--cf-t` (seconds), `--cf-fps`, `--cf-duration` (frames), `--cf-progress`, `--cf-ease`, `--cf-enter` and `--cf-exit`. CSS animations, transitions and timers are not the render clock. The built-in entrance/exit ramps span up to 18 frames; use explicit event times when the brief needs other choreography.
 
-**Source format matters:**
-- New and changed components are native (source version 4): `{version:4, componentId, template,
-  manifest, definition}`. `template` is one HyperFrames sub-composition whose script ends in one
-  `__cfScene.mount(...)`; the manifest is `{version:4, runtime:'hyperframes', hfContract:1,
-  kind:'scene', assets, graphics, alphaPolicy}`. The definition declares input schema, defaults,
-  timing, brand/media bindings and capabilities. The server instructions' Component Contract has
-  the full rules. Version-3 TSX sources are retired and refused as `component_source_retired`.
-- Neither renderer runs authored source in the editor process. Local and hosted execution
-  use isolated render processes and exact immutable source revisions.
+Use flex/grid for text and UI reflow, and coordinate-based nested transforms for spatial animation. Parent mounted contents to their object: a moving phone should carry its bezel, screen mask and controls. Use a separate local transform only when that part really moves relative to the object. The [parented motion recipe](references/parented-motion.md) includes a complete editable card with a shared pose and named pointer-contact/response times.
 
-## Path A — MCP agent (no filesystem; source lives server-side)
+Expose likely revisions as meaningful inputs rather than unrelated constants. A card's text token used by CSS `content` needs a quoted CSS string. Preserve the current token values when changing its HTML. The native component definition declares defaults and input controls; its placement binds media in `execution.assets`, separately from `params`.
 
-Use the live tool schema for request envelopes; hosted write fields are normally under `body`.
+## Iterate on the saved result
 
-1. **Discover and read a built-in:** call `list_catalog` with
-   `projection: "component-library", origin: "builtin", libraryKind: "definition"`.
-   Select the intended card and preserve its complete scoped source reference. Call
-   `get_component_source` with that reference's `componentId`, `sourceVersionId`,
-   `builtinCollection` (its scope collection).
-   ID-only builtin reads are unsupported. An unavailable exact pin is a refusal; never
-   retry another scope or an unpinned head.
-2. **Author/own it:** edit the complete native `sourceSnapshot`; use your chosen owned ID
-   consistently in its `componentId` and the request. Send it as `body.source` to
-   `create_component`, with required metadata. Preserve its definition, capability
-   declarations, manifest and source format. For an existing component, keep its ID and
-   use `update_component` with the complete source. Do not send an old pin as the identity
-   of changed source: saving produces a new immutable source version.
-3. **Iterate (author→preview→fix):** `preview_component({ componentId, params })` queues a durable
-   preview and returns a `jobId`; call `wait_job(kind:"preview")`. The typed terminal result is a
-   verified artifact produced by the same bundle contract used by final render. A failed
-   `component_does_not_compile` job carries the compiler error — read it, fix via `update_component`
-   (same id, in place), and preview again.
-   **Repin only the requested scope:** for all matching placements in one composition, use
-   `update_component({ componentId, body: { source: editedSnapshot, projectId, compositionId? } })`
-   with the observed revision and dependency guards. A placed clip
-   renders the exact version it pins; only the composition you name moves to the new version in the
-   same write (`repinned` says what moved). Without `projectId` your clips keep rendering the old
-   version, and `placementsPinnedToPrevious` counts them. For a single placement, update the
-   source without `projectId`, then change only that clip to the returned exact source pin
-   using the observed concurrency guards.
-   Set preview duration deliberately: `durationInFrames` is not a trim window and can retime
-   duration-dependent motion. Preserve production timing; inspect the live tool's request shape.
-4. **Check integration:** add it as a `{kind:'component', componentId, props:{},
-   execution:{version:4,componentId,sourceVersionId,params,seed,assets}, placement:{version:3,kind:'clip'}}` clip
-   (`apply_composition`), then inspect saved-composition stills or a scoped `preview_clip` for
-   placement and motion. Use `create_render` → `wait_job kind:"render"` when delivering a
-   finished MP4, not per tweak.
+Keep the same owned component ID while updating its complete source. Saving creates a new immutable source version; existing placements keep their old pins unless explicitly repinned in the intended composition. An isolated preview is not a saved timeline edit. The workflow reference explains scoped repinning and local preview commits.
 
-## Path B — CLI / coding agent (customer-owned source under git)
+Use [cueframe-compose-loop](../cueframe-compose-loop/SKILL.md) for isolated, integrated and final evidence. Preserve production duration when previewing duration-dependent motion. Check the relationship that could fail, including screen corners, overlap, pointer contact and the complete ending, rather than only a pleasing middle still. For `needsUpgrade`, use [retired-source recovery](references/retired-projects.md) and replace only the reported clips.
 
-Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edit the native
-template locally, push to render.
+## Detailed guidance
 
-```bash
-npx -y cueframe@0.11 init --json                       # scaffold cueframe.json + cueframe/components/
-npx -y cueframe@0.11 new component my-badge --category ui-blocks --json   # scaffold a component in the workspace
-#   New scaffolds contain template.html and definition.json (native source, version 4).
-# …edit cueframe/components/<id>/template.html and definition.json in your editor…
-npx -y cueframe@0.11 push my-badge --json              # send the native source; the server admits it
-#   or: npx -y cueframe@0.11 sync --json               # push every component in the workspace
-# reference the component id in your composition, then render:
-npx -y cueframe@0.11 render <projectId> -o ./out.mp4 --json
-```
-
-The CLI writes `template.html` and `definition.json` (input schema, defaults, timing and
-capabilities). `cueframe.json` → `components.<id>` holds the version-4 `manifest` and the catalog
-`name` and `category`, which `push` requires; it refuses a component missing either.
-`push`/`sync` send these as one native `source`, checked against the contract's source schema;
-the server's admission (template lint, determinism, declarations) refuses with a named rule.
-For a builtin fork, copy **all three parts** from the selected `sourceSnapshot`: template,
-definition and manifest. A workspace component that still has a version-3 `index.tsx` is
-refused as `component_source_retired` before any API call; author it again as a native template. To preview before
-a full render, push it and use the appropriate component preview loop.
-
-## Path C — Director editing a local desktop project (project-embedded source)
-
-When `get_context` reports the project lane as local, motion does not need an account or an org
-component. Components here are native (source version 4) too:
-- **New component:** open a draft with `open_component_preview`, passing `template`,
-  `component_manifest` (`{version:4, runtime:'hyperframes', hfContract:1, kind:'scene', assets,
-  graphics, alphaPolicy}`) and `component_definition`.
-- **Existing component:** pass `component_id` instead, to start from the clip's pinned version or
-  the library version.
-
-The draft is admitted in full: template lint, determinism and the variable declaration.
-`data-composition-variables` must equal the definition's projection (its scalar inputSchema
-properties, then the manifest's slots).
-
-Edit the draft with `update_component_preview` (exact-text `{oldText, newText, replaceAll?}`
-edits). Check exact frames with `render_component_preview_frame`, and inspect playback for motion.
-`commit_component_preview` publishes the checked source to the library and pins the clip, and
-returns the project's new ETag. `read_component` and `edit_component` read and edit the library
-directly. Close the preview when finished.
-
-Media slots are image or video, declared in `component_manifest.assets` and bound to project
-media ids in `component_assets`. The template passes them to `MediaTileScene` as
-`streams: { hero: { asset: assets.hero } }`. Declare `alphaPolicy` explicitly:
-`requires-transparency` for overlays, `allows-opaque` for full-frame plates.
-
-Every frame must be a pure function of `render.frame`, params and `render.seed`. Timers, `Date`,
-network, imports, other globals and CSS animation are refused at admission. The timeline and final
-export render the exact committed version. Use `create_component` only for a reusable org-catalog
-component on a reachable cloud lane.
-
-## Upgrading an old project
-
-`get_composition` returns `needsUpgrade` only when clips from before the native cutover remain:
-`[{clipId, kind, componentId?, sourceVersionId?, primitiveId?, successorComponentId?,
-successorSourceVersionId?}]`. Saves and renders refuse those clips. A retired component is
-refused with `component_source_retired`, and a retired
-primitive with `render_unknown_primitive`. Upgrade only the listed clips. Keep every other clip,
-timing, track and brand-kit binding as it is.
-
-- **Any entry with a `successorSourceVersionId`:** call `repin_component` with its clip ids. It
-  moves them to the native successor and keeps their saved inputs.
-- **`v3-component` with no successor** (a custom pre-cutover component): read its source, params,
-  timing and placement, and author a native replacement with `create_component` as a version-4
-  template following the server instructions' Component Contract.
-- **`unpinned-component`:** the clip carries a `retired` record (what was stored before the cutover), with its
-  props preserved. Re-author it from those props the same way.
-- **`retired-primitive`:** rebuild what `primitiveId` drew from the clip's params, as a card or
-  a native component.
-
-For each replacement, use `apply_composition` to replace only that clip at the same start,
-duration, track and placement, pinned to the new exact `sourceVersionId`. Map the old params
-onto the new inputs; do not invent new content. Verify each clip with `preview_frame` at a time
-inside its window and confirm `needsUpgrade` is gone. Only then render (`create_render`).
-
-## Choosing what to fork
-Use the `component-library` projection to choose a definition, inspect its input schema and
-capabilities, then fetch its exact scoped source as described in Path A. Presets and recipes
-are different card kinds: follow their exact definition/document references rather than treating
-those IDs as source IDs. Inspect appropriate previews before judging visual behavior.
-
-## Layout inside a component — CSS flex/grid
-
-When several cells must share space (a feature grid, a fixed rail beside fluid content, a cast of
-objects next to type), lay them out with CSS flex or grid in the HTML, not hand-placed pixels.
-Use the template of a native component, or a `card`:
-
-```html
-<div style="display:grid; grid-template-columns: 520px 1fr 3fr; gap:16px; width:100%; height:100%">
-  <div class="rail"></div><div class="type"></div><div class="art"></div>
-</div>
-```
-
-- Fixed tracks (`520px`) hold content-sized cells. Fractions (`1fr`, `3fr`) share what is left.
-- Animate a reflow from the frame, never from time: in a card, drive `grid-template-columns`
-  or `flex-basis` from `var(--cf-progress)` (or `--cf-enter`/`--cf-exit`); in a native template,
-  derive it from `render.frame`.
-- Size the container to its region instead of CSS-`scale()`-ing the layout, which resamples.
-  Use `object-fit` for media in a cell.
-
-## Don't
-- Don't expect a forked primitive to use rich named props — read `params` inside and use the explicit
-  `assets` and `render` bags for media and frame state.
-- When a built-in fits the request, fork its exact snapshot using Path A. Never discard its
-  definition by copying only its template; preserve the definition and manifest too.
-- Don't `create_component` a fresh id each fix iteration — `update_component` (same id) is the loop.
+- [Authoring paths](references/authoring-paths.md): the MCP path step by step, when no filesystem is available.
+- [Forking and layout](references/forking-and-layout.md): what to fork, flex and grid inside a component, and what to avoid.

package/dist/skills/cueframe-component-authoring/references/authoring-paths.md

@@ -0,0 +1,72 @@
+# Authoring paths
+
+Defaults, examples and detail for this topic. The [skill](../SKILL.md) and the [project and capability policy](../../composing-video/references/project-policy.md) take precedence where they differ, and the current tool schemas are authoritative.
+
+## Scope and capability policy
+
+User intent and acceptance criteria override this recipe's aesthetic defaults. Silent, typography-only, uncaptioned and slow work are valid; no universal narration, footage, CTA, beat count or score target. Contracts, factual fidelity, media bindings and current source revisions remain mandatory.
+
+Read available tools and current project; preserve the chosen local/hosted lane. Supported local work needs no hosted registration. Do not silently install, authenticate, switch projects or upload local content. Before metered hosted work, check `get_account`, entitlements, balance and quotes. Desktop setup: https://docs.cueframe.ai.
+
+For scoped revisions, preserve unrelated timing, media, audio and shared brand-kit state. Edit affected content; inspect relevant frames, continuous motion and affected audio. No restarted intake, new approval pause, paid judge or final export by default. Judge only when useful; scores never override acceptance failures. Stop/report after two no-improvement passes. See [preview workflow](../../cueframe-compose-loop/references/preview-workflow.md).
+
+Use `cueframe-compose-loop`'s [preview workflow](../../cueframe-compose-loop/references/preview-workflow.md)
+to select hosted or local evidence and separate iteration from final delivery.
+
+CueFrame ships built-in motion-graphics definitions (titles, lower-thirds, captions,
+effects, transitions and layouts). Discover the current catalog; fork an exact definition, customize it,
+and render it on CueFrame — or author a brand-new component. This is shadcn-for-video: own the
+component code; CueFrame is the reliable engine that renders it.
+
+**Before you hand-write 3D:** a device mockup or a screenshot floating in a lit 3D scene is a
+**scene shot** — validated JSON with `scene.add` / `scene.update`, not a component you author.
+See the `cueframe-scene-shot` skill and `cueframe://scene-shot`. Author a component here when
+you need behaviour the scene contract does not express.
+
+**Source format matters:**
+- New and changed components are native (source version 4): `{version:4, componentId, template,
+  manifest, definition}`. `template` is one HyperFrames sub-composition whose script ends in one
+  `__cfScene.mount(...)`; the manifest is `{version:4, runtime:'hyperframes', hfContract:1,
+  kind:'scene', assets, graphics, alphaPolicy}`. The definition declares input schema, defaults,
+  timing, brand/media bindings and capabilities. The server instructions' Component Contract has
+  the full rules. Version-3 TSX sources are retired and refused as `component_source_retired`.
+- Neither renderer runs authored source in the editor process. Local and hosted execution
+  use isolated render processes and exact immutable source revisions.
+
+## Path A — MCP agent (no filesystem; source lives server-side)
+
+Use the live tool schema for request envelopes; hosted write fields are normally under `body`.
+
+1. **Discover and read a built-in:** call `list_catalog` with
+   `projection: "component-library", origin: "builtin", libraryKind: "definition"`.
+   Select the intended card and preserve its complete scoped source reference. Call
+   `get_component_source` with that reference's `componentId`, `sourceVersionId`,
+   `builtinCollection` (its scope collection).
+   ID-only builtin reads are unsupported. An unavailable exact pin is a refusal; never
+   retry another scope or an unpinned head.
+2. **Author/own it:** edit the complete native `sourceSnapshot`; use your chosen owned ID
+   consistently in its `componentId` and the request. Send it as `body.source` to
+   `create_component`, with required metadata. Preserve its definition, capability
+   declarations, manifest and source format. For an existing component, keep its ID and
+   use `update_component` with the complete source. Do not send an old pin as the identity
+   of changed source: saving produces a new immutable source version.
+3. **Iterate (author→preview→fix):** `preview_component({ componentId, params })` queues a durable
+   preview and returns a `jobId`; call `wait_job(kind:"preview")`. The typed terminal result is a
+   verified artifact produced by the same bundle contract used by final render. A failed
+   `component_does_not_compile` job carries the compiler error — read it, fix via `update_component`
+   (same id, in place), and preview again.
+   **Repin only the requested scope:** for all matching placements in one composition, use
+   `update_component({ componentId, body: { source: editedSnapshot, projectId, compositionId? } })`
+   with the observed revision and dependency guards. A placed clip
+   renders the exact version it pins; only the composition you name moves to the new version in the
+   same write (`repinned` says what moved). Without `projectId` your clips keep rendering the old
+   version, and `placementsPinnedToPrevious` counts them. For a single placement, update the
+   source without `projectId`, then change only that clip to the returned exact source pin
+   using the observed concurrency guards.
+   Set preview duration deliberately: `durationInFrames` is not a trim window and can retime
+   duration-dependent motion. Preserve production timing; inspect the live tool's request shape.
+4. **Check integration:** add it as a `{kind:'component', componentId, props:{},
+   execution:{version:4,componentId,sourceVersionId,params,seed,assets}, placement:{version:3,kind:'clip'}}` clip
+   (`apply_composition`), then inspect saved-composition stills or a scoped `preview_clip` for
+   placement and motion. Use `create_render` → `wait_job kind:"render"` when delivering a
+   finished MP4, not per tweak.

package/dist/skills/cueframe-component-authoring/references/forking-and-layout.md

@@ -0,0 +1,35 @@
+# Forking and layout
+
+Defaults, examples and detail for this topic. The [skill](../SKILL.md) and the [project and capability policy](../../composing-video/references/project-policy.md) take precedence where they differ, and the current tool schemas are authoritative.
+
+## Choosing what to fork
+Use the `component-library` projection to choose a definition, inspect its input schema and
+capabilities, then fetch its exact scoped source as described in Path A. Presets and recipes
+are different card kinds: follow their exact definition/document references rather than treating
+those IDs as source IDs. Inspect appropriate previews before judging visual behavior.
+
+## Layout inside a component — CSS flex/grid
+
+When several cells must share space (a feature grid, a fixed rail beside fluid content, a cast of
+objects next to type), lay them out with CSS flex or grid in the HTML, not hand-placed pixels.
+Use the template of a native component, or a `card`:
+
+```html
+<div style="display:grid; grid-template-columns: 520px 1fr 3fr; gap:16px; width:100%; height:100%">
+  <div class="rail"></div><div class="type"></div><div class="art"></div>
+</div>
+```
+
+- Fixed tracks (`520px`) hold content-sized cells. Fractions (`1fr`, `3fr`) share what is left.
+- Animate a reflow from the frame, never from time: in a card, drive `grid-template-columns`
+  or `flex-basis` from `var(--cf-progress)` (or `--cf-enter`/`--cf-exit`); in a native template,
+  derive it from `render.frame`.
+- Size the container to its region instead of CSS-`scale()`-ing the layout, which resamples.
+  Use `object-fit` for media in a cell.
+
+## Don't
+- Don't expect a forked primitive to use rich named props — read `params` inside and use the explicit
+  `assets` and `render` bags for media and frame state.
+- When a built-in fits the request, fork its exact snapshot using Path A. Never discard its
+  definition by copying only its template; preserve the definition and manifest too.
+- Don't `create_component` a fresh id each fix iteration — `update_component` (same id) is the loop.

package/dist/skills/cueframe-component-authoring/references/native-component-workflows.md

@@ -0,0 +1,98 @@
+# Native component workflows
+
+Choose the path exposed by the current host. Request schemas and the Component Contract own exact fields; these examples explain source and placement identity.
+
+## Path A — MCP agent (no filesystem; source lives server-side)
+
+Use the live tool schema for request envelopes; hosted write fields are normally under `body`. When `get_composition` advertises `clipIds` and `response`, use selected clip IDs with `response:"full"` to retrieve the complete sources you need without pulling every large HTML body. Treat a projection as a partial read, never a replacement composition. Compact apply receipts retain the saved revision and warnings; reread relevant state before a dependent edit. Desktop surfaces may expose different fields.
+
+1. **Discover and read a built-in:** call `list_catalog` with
+   `projection: "component-library", origin: "builtin", libraryKind: "definition"`.
+   Select the intended card and preserve its complete scoped source reference. Call
+   `get_component_source` with that reference's `componentId`, `sourceVersionId`,
+   `builtinCollection` (its scope collection).
+   ID-only builtin reads are unsupported. An unavailable exact pin is a refusal; never
+   retry another scope or an unpinned head.
+2. **Author/own it:** edit the complete native `sourceSnapshot`; use your chosen owned ID
+   consistently in its `componentId` and the request. Send it as `body.source` to
+   `create_component`, with required metadata. Preserve its definition, capability
+   declarations, manifest and source format. For an existing component, keep its ID and
+   use `update_component` with the complete source. Do not send an old pin as the identity
+   of changed source: saving produces a new immutable source version.
+3. **Iterate (author→preview→fix):** `preview_component({ componentId, params })` queues a durable
+   preview and returns a `jobId`; call `wait_job(kind:"preview")`. The typed terminal result is a
+   verified artifact produced by the same bundle contract used by final render. A failed
+   `component_does_not_compile` job carries the compiler error — read it, fix via `update_component`
+   (same id, in place), and preview again.
+   **Adopt the source in the requested scope:** publication leaves existing placements pinned
+   to their previous versions; `placementsPinnedToPrevious` reports those uses. Source publication
+   plus placement adoption is not an atomic source-write operation. Read the current composition
+   and `describe_composition_ops`, then use the admitted `component.repin-v3` operation with complete
+   before/after execution references and the observed exact composition revision. Its historical
+   name also covers supported version-4 execution references. Preserve unrelated placements and
+   parameters. An unavailable placement capability is a refusal, not permission to bypass source
+   admission or substitute an unpinned head. Reinspect the adopted source in the saved timeline.
+   Set preview duration deliberately: `durationInFrames` is not a trim window and can retime
+   duration-dependent motion. Preserve production timing; inspect the live tool's request shape.
+4. **Check integration:** add it as a `{kind:'component', componentId, props:{},
+   execution:{version:4,componentId,sourceVersionId,params,seed,assets}, placement:{version:3,kind:'clip'}}` clip
+   (`apply_composition`), then inspect saved-composition stills or a scoped `preview_clip` for
+   placement and motion. Use `create_render` → `wait_job kind:"render"` when delivering a
+   finished MP4, not per tweak.
+
+## Path B — CLI / coding agent (customer-owned source under git)
+
+Source lives in `cueframe/components/<id>/` (the `cueframe.json` workspace); edit the native
+template locally, push to render.
+
+```bash
+npx -y cueframe@0.11 init --json                       # scaffold cueframe.json + cueframe/components/
+npx -y cueframe@0.11 new component my-badge --category ui-blocks --json   # scaffold a component in the workspace
+#   New scaffolds contain template.html and definition.json (native source, version 4).
+# …edit cueframe/components/<id>/template.html and definition.json in your editor…
+npx -y cueframe@0.11 push my-badge --json              # send the native source; the server admits it
+#   or: npx -y cueframe@0.11 sync --json               # push every component in the workspace
+# reference the component id in your composition, then render:
+npx -y cueframe@0.11 render <projectId> -o ./out.mp4 --json
+```
+
+The CLI writes `template.html` and `definition.json` (input schema, defaults, timing and
+capabilities). `cueframe.json` → `components.<id>` holds the version-4 `manifest` and the catalog
+`name` and `category`, which `push` requires; it refuses a component missing either.
+`push`/`sync` send these as one native `source`, checked against the contract's source schema;
+the server's admission (template lint, determinism, declarations) refuses with a named rule.
+For a builtin fork, copy **all three parts** from the selected `sourceSnapshot`: template,
+definition and manifest. A workspace component that still has a version-3 `index.tsx` is
+refused as `component_source_retired` before any API call; author it again as a native template. To preview before
+a full render, push it and use the appropriate component preview loop.
+
+## Path C — Director editing a local desktop project (project-embedded source)
+
+When `get_context` reports the project lane as local, motion does not need an account or an org
+component. Components here are native (source version 4) too:
+- **New component:** open a draft with `open_component_preview`, passing `template`,
+  `component_manifest` (`{version:4, runtime:'hyperframes', hfContract:1, kind:'scene', assets,
+  graphics, alphaPolicy}`) and `component_definition`.
+- **Existing component:** pass `component_id` instead, to start from the clip's pinned version or
+  the library version.
+
+The draft is admitted in full: template lint, determinism and the variable declaration.
+`data-composition-variables` must equal the definition's projection (its scalar inputSchema
+properties, then the manifest's slots).
+
+Edit the draft with `update_component_preview` (exact-text `{oldText, newText, replaceAll?}`
+edits). Check exact frames with `render_component_preview_frame`, and inspect playback for motion.
+`commit_component_preview` publishes the checked source to the library and pins the clip, and
+returns the project's new ETag. `read_component` and `edit_component` read and edit the library
+directly. Close the preview when finished.
+
+Media slots are image or video, declared in `component_manifest.assets` and bound to project
+media ids in `component_assets`. The template passes them to `MediaTileScene` as
+`streams: { hero: { asset: assets.hero } }`. Declare `alphaPolicy` explicitly:
+`requires-transparency` for overlays, `allows-opaque` for full-frame plates.
+
+Every frame must be a pure function of `render.frame`, params and `render.seed`. Timers, `Date`,
+network, imports, other globals and CSS animation are refused at admission. The timeline and final
+export render the exact committed version. Use `create_component` only for a reusable org-catalog
+component on a reachable cloud lane.
+

package/dist/skills/cueframe-component-authoring/references/native-source-contract.md

@@ -0,0 +1,54 @@
+# Native version-4 source contract
+
+Read this when authoring or changing a custom native component. Scene-shot JSON is a different contract served by `cueframe://scene-shot` or desktop `get_scene_contract`; it does not describe a custom component source. Live schemas and named admission errors govern supported fields.
+
+Create and update components with a complete `source` object: `{version:4, componentId, template, manifest, definition}`. TSX (version 3) sources are retired: writing one is refused as `component_source_retired`. The definition declares input schema, defaults, timing, brand/media bindings and placement capabilities. The manifest is `{version:4, runtime:'hyperframes', hfContract:1, kind:'scene', assets, graphics, alphaPolicy}`: `assets` declares the media slots (only `image` and `video` slots), `graphics.api` is `webgl2` (or `webgl`), and `alphaPolicy` is `requires-transparency` or `allows-opaque`.
+
+The `template` is one sub-composition. Every source is admitted before it is stored or rendered, and a refusal names the broken rule:
+- `<template>` holds one root `<div id="root" data-composition-id="<componentId>" data-width="1920" data-height="1080" data-no-timeline data-composition-variables='…'>` containing one empty `<div data-cf-scene></div>` (and any static DOM of your own beside it), and one classic inline `<script>`.
+- The script finds its root with `document.getElementById('root')`. The runtime scopes that lookup to each placed instance; a global `[data-composition-id]` selector is refused, because a component placed twice would find no root.
+- `data-composition-variables` is the definition's projection: each scalar `inputSchema` property in schema order, then each manifest slot. `number`/`integer` → `{"id","type":"number","label","default","min","max"}` (min/max from minimum/maximum, omitted when absent); a property with `enum` → `{"type":"enum","default":"<as string>","options":[{"value","label"}]}`; `boolean` → `"boolean"`; a string whose `pattern` admits exactly `#RRGGBB` → `"color"`; any other string → `"string"`; an image slot → `{"id","type":"image","label":"<id>","default":""}`; a video slot → the same with `"type":"string"`. `label` is the property's `title`, else its id; `default` is `definition.defaults[id]`, else the schema default. Any difference is refused as `component_api_mismatch`.
+- The script ends with exactly one `__cfScene.mount({ root: document.getElementById('root'), component: Name, variables: __hyperframes.getVariables() })`. `Name({ params, assets, render, durationInFrames })` returns `h(MediaTileScene, { streams, tiles, camera, fog, background })`, taken from `const { h, MediaTileScene, three } = __cfScene`: a description, not React. `render` is `{ frame, fps, width, height, seed }`. `params` holds only the keys the placement's `execution.params` sets, so read every param with its default as a fallback.
+- Pass a declared slot as `streams: { hero: { asset: assets.hero } }` and place it with `tiles: [{ stream: 'hero', x, y, width, height }]` (pixels; x/y are the tile centre's offset from the frame centre, y down). Tiles also take `z`, `rotation`, `rotationX`, `rotationY` (degrees), `opacity`, `crop` and `renderOrder`; the camera takes `x`, `y`, `z`, `zoom` and `perspective`. Video streams take `trimBeforeFrames`, `trimAfterFrames`, `playbackRate` and `loop`. Audio belongs on composition audio tracks.
+- The template lays out at its declared `data-width` × `data-height`, and the host scales that whole box to the rendered size: DOM beside the scene keeps its place and proportion at every size. The scene draws at the rendered size (`render.width` × `render.height`). A component without media passes `streams: {}` and no tiles; its scene presents its `background`.
+- Every frame is a pure function of `render.frame`, `params` and `render.seed`. The script reads only its own declarations, `__cfScene`, `__hyperframes`, `document` and JavaScript built-ins such as `Math` and `JSON`. Timers, `Date`, `requestAnimationFrame`, `fetch`, `eval`, imports, `window` and other globals are refused (`component_v4_nondeterministic`, `component_import_denied`). The template has no `<img>`, `<video>`, `<link>` or `<iframe>`, no external or `data:` URL, and no CSS `transition`, `animation` or `@keyframes`. The template linter runs in sub-composition mode, and its errors refuse the source (`component_v4_lint_failed`).
+
+Example: one image swinging flat over the clip. Its definition and manifest:
+
+```json
+{
+  "definition": {
+    "inputSchema": { "type": "object", "additionalProperties": false, "properties": {
+      "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#101014" },
+      "tilt": { "type": "number", "minimum": 0, "maximum": 60, "default": 35 }
+    } },
+    "defaults": {}, "brandBindings": [], "timing": { "defaultDuration": { "frames": 90, "fps": 30 } }, "capabilities": [{ "kind": "clip" }]
+  },
+  "manifest": { "version": 4, "runtime": "hyperframes", "hfContract": 1, "kind": "scene",
+    "assets": { "hero": { "kind": "image", "required": true } },
+    "graphics": { "api": "webgl2", "required": true, "accelerationPreference": "hardware-preferred" }, "alphaPolicy": "allows-opaque" }
+}
+```
+
+Its template, with `componentId` `swing-hero`:
+
+```html
+<template><div id="root" data-composition-id="swing-hero" data-width="1920" data-height="1080" data-no-timeline data-composition-variables='[{"id":"background","type":"color","label":"background","default":"#101014"},{"id":"tilt","type":"number","label":"tilt","default":35,"min":0,"max":60},{"id":"hero","type":"image","label":"hero","default":""}]'><div data-cf-scene></div></div><script>
+const { h, MediaTileScene } = __cfScene;
+function SwingHero({ params, assets, render, durationInFrames }) {
+  const t = Math.min(1, render.frame / Math.max(1, durationInFrames - 1));
+  const ease = 1 - Math.pow(1 - t, 3);
+  const tilt = Number.isFinite(params.tilt) ? params.tilt : 35;
+  return h(MediaTileScene, {
+    streams: { hero: { asset: assets.hero } },
+    tiles: [{ stream: 'hero', x: 0, y: 0, width: 1280, height: 720, rotationY: tilt * (1 - ease) }],
+    camera: { x: 0, y: 0, z: 0, zoom: 1, perspective: 1200 },
+    background: params.background ?? '#101014',
+  });
+}
+__cfScene.mount({ root: document.getElementById('root'), component: SwingHero, variables: __hyperframes.getVariables() });
+</script></template>
+```
+
+Place a component as a `{kind:'component', componentId, props:{}, execution:{version:4, componentId, sourceVersionId, params, seed, assets:{hero:'<mediaId>'}}, placement:{version:3, kind:'clip'}}` clip. Bind each slot to a project media id in `execution.assets`; a slot never travels in `params`.
+

package/dist/skills/cueframe-component-authoring/references/parented-device-card.json

@@ -0,0 +1,13 @@
+{
+  "kind": "card",
+  "html": "<style>\n.cf-mounted-demo{position:relative;width:100%;height:100%;overflow:hidden;background:#e9edf5;font-family:Arial,sans-serif;color:#162033;--settle:clamp(0,calc(var(--cf-t)/var(--cf-settleSec)),1);--pose:calc(1 - (1 - var(--settle))*(1 - var(--settle))*(1 - var(--settle)));--approach:clamp(0,calc((var(--cf-t) - var(--cf-contactSec) + var(--cf-approachSec))/var(--cf-approachSec)),1);--response:clamp(0,calc((var(--cf-t) - var(--cf-contactSec))/var(--cf-responseSec)),1)}\n.cf-mounted-demo .stage{position:absolute;left:50%;top:50%;width:380px;height:720px;transform:translate(-50%,-50%);perspective:1400px}\n.cf-mounted-demo .phone{position:absolute;inset:0;border:10px solid #172032;border-radius:52px;background:#172032;box-sizing:border-box;box-shadow:18px 30px 45px #15263a30;transform:translateY(calc((1 - var(--pose))*120px)) rotateY(calc((1 - var(--pose))*var(--cf-tiltDeg)*1deg)) rotateZ(calc((1 - var(--pose))*-5deg))}\n.cf-mounted-demo .screen{position:absolute;inset:0;border-radius:40px;overflow:hidden;background:#fbfcff}\n.cf-mounted-demo .top{position:absolute;left:28px;right:28px;top:38px;font-size:24px;font-weight:700}\n.cf-mounted-demo .card{position:absolute;left:28px;right:28px;top:110px;height:182px;border-radius:18px;background:var(--cf-accent);color:white;box-shadow:0 9px 18px #16203328}\n.cf-mounted-demo .card:before{content:\"NORTH\";position:absolute;left:22px;top:24px;font-size:21px;font-weight:700;letter-spacing:3px}\n.cf-mounted-demo .holder:after{content:var(--cf-holder)}\n.cf-mounted-demo .holder{position:absolute;left:22px;bottom:24px;font-size:18px;letter-spacing:2px}\n.cf-mounted-demo .label{position:absolute;top:330px;left:28px;font-size:20px}\n.cf-mounted-demo .control{position:absolute;left:100px;top:400px;width:160px;height:70px;border:2px solid #b5bfd1;border-radius:18px;box-sizing:border-box;background:#eef2f9;display:grid;place-items:center;font-size:22px;font-weight:700}\n.cf-mounted-demo .frozen{position:absolute;inset:0;border-radius:16px;background:var(--cf-accent);color:white;display:grid;place-items:center;opacity:var(--response)}\n.cf-mounted-demo .pointer{position:absolute;left:180px;top:435px;width:36px;height:48px;background:#162033;clip-path:polygon(0 0,100% 65%,58% 68%,43% 100%);filter:drop-shadow(1px 3px 2px #15263a99);transform:translate(calc((1 - var(--approach))*95px),calc((1 - var(--approach))*80px));transform-origin:0 0}\n.cf-mounted-demo .status{position:absolute;left:28px;right:28px;top:530px;font-size:20px;line-height:1.4;opacity:var(--response)}\n</style><div class=\"cf-mounted-demo\"><div class=\"stage\"><div class=\"phone\"><div class=\"screen\"><div class=\"top\">Your card</div><div class=\"card\"><div class=\"holder\"></div></div><div class=\"label\">Card controls</div><div class=\"control\">Freeze<div class=\"frozen\">Frozen</div></div><div class=\"pointer\"></div><div class=\"status\">Payments are paused.<br>Your card is still here.</div></div></div></div></div>",
+  "tokens": {
+    "accent": "#4265d5",
+    "holder": "\"MAYA\"",
+    "settleSec": "1.0",
+    "tiltDeg": "28",
+    "contactSec": "2.0",
+    "approachSec": "0.65",
+    "responseSec": "0.2"
+  }
+}

package/dist/skills/cueframe-component-authoring/references/parented-motion.md

@@ -0,0 +1,25 @@
+# Parented motion with an editable event clock
+
+Use this example to keep mounted UI on one projected plane and make a cursor action retimeable. It is original CueFrame sample artwork under this repository's Apache-2.0 license, with no external assets. It is not a Cardly reproduction or a real app capture. For physical lighting, depth intersections or a moving 3D camera, use the scene-shot contract instead.
+
+[Complete card source](parented-device-card.json) is a `kind:"card"` source object. Put it on an overlay clip at full-frame 1920×1080, 30 fps, duration 4 seconds; use the live `clip.add` schema for the surrounding operation. It includes an opaque full-duration background, so it is a complete scene plate. When using it over other content, remove that background intentionally rather than hoping it is transparent.
+
+The `.phone` applies the pose once. Its `.screen` clips the card, text, control and pointer as mounted children. Their coordinates stay in phone space. No child independently counter-rotates to approximate the parent's pose. The pointer's top-left tip arrives at the control center `(180,435)` in screen coordinates.
+
+The host supplies `--cf-t` in clip-local seconds. Tokens `settleSec`, `contactSec`, `approachSec` and `responseSec` determine arrival, pointer contact and response; the status and control use the same response phase. The sample keeps its readable state after settling and after contact. Changing `contactSec` shifts the approach and response together. Positive travel/response durations are required by its CSS divisions; keep contact after the approach and allow a readable hold before the clip ends.
+
+`holder` is a CSS string token, so its value includes quote characters. Preserve it when editing the pose or timing. `accent` and `tiltDeg` control visible style and geometry. They are ordinary card tokens; built-in clock keys are not authored tokens.
+
+For the initial proof, inspect the pose in travel, the settled plane, the frame before contact, the contact frame, the response and the last frame. Also inspect a motion preview across arrival and contact. After changing `contactSec`, check that the cursor and response move together, the holder remains, and the full scene still covers its duration. These are tests of this recipe's mechanism; use the reference's actual landmarks for a real film.
+
+This CSS uses a fixed design-space phone inside a full-size card. Recompose for a different aspect/size instead of assuming this sample is responsive. Static layout fidelity, sampled motion and actual playback are distinct evidence. The validation record belongs with the produced preview artifact, not inside this reusable skill.
+
+## Fit and reuse the same object
+
+For a reference-led device, compare the outer silhouette, screen corners and inset, then the mounted card and its typography. A correct bounding width can still hide the wrong perspective. Parenting keeps transforms together, but a child rendered on a different apparent plane can still contradict the device. Inspect a moving pose as well as the settled one before reusing the object across scenes.
+
+Use a small set of editable properties for likely corrections: screen inset, card size, text scale, internal gap, pose and event times. A CSS font-size is not a measurement of visible cap height or text width. Calibrate those relationships from the rendered glyphs and preserve intentional copy adaptations. Do not turn every measured pixel into a global design token.
+
+Publish a reusable native source once, then pass its exact version and relevant parameters to coauthors. Editing its source creates a new version; placed clips remain pinned to the old version. Explicitly adopt the fitted version in the intended placements through the available admitted composition operation, and inspect those uses. Source publication and placement adoption are separate operations; an isolated preview alone does not prove the timeline changed.
+
+When several authors work on one project, existing clip guards cover the whole clip and its structural dependencies, not independent CSS fields. A shared source adoption or dependent timing revision needs current composition state. If another author or the user changed the target, reread and reconcile the intended edit; preserve their copy, timing and unrelated placements rather than replacing a stale document with a fresh token.

package/dist/skills/cueframe-component-authoring/references/retired-projects.md

@@ -0,0 +1,26 @@
+# Retired project sources
+
+## Upgrading an old project
+
+`get_composition` returns `needsUpgrade` only when clips from before the native cutover remain:
+`[{clipId, kind, componentId?, sourceVersionId?, primitiveId?, successorComponentId?,
+successorSourceVersionId?}]`. Saves and renders refuse those clips. A retired component is
+refused with `component_source_retired`, and a retired
+primitive with `render_unknown_primitive`. Upgrade only the listed clips. Keep every other clip,
+timing, track and brand-kit binding as it is.
+
+- **Any entry with a `successorSourceVersionId`:** call `repin_component` with its clip ids. It
+  moves them to the native successor and keeps their saved inputs.
+- **`v3-component` with no successor** (a custom pre-cutover component): read its source, params,
+  timing and placement, and author a native replacement with `create_component` as a version-4
+  template following the server instructions' Component Contract.
+- **`unpinned-component`:** the clip carries a `retired` record (what was stored before the cutover), with its
+  props preserved. Re-author it from those props the same way.
+- **`retired-primitive`:** rebuild what `primitiveId` drew from the clip's params, as a card or
+  a native component.
+
+For each replacement, use `apply_composition` to replace only that clip at the same start,
+duration, track and placement, pinned to the new exact `sourceVersionId`. Map the old params
+onto the new inputs; do not invent new content. Verify each clip with `preview_frame` at a time
+inside its window and confirm `needsUpgrade` is gone. Only then render (`create_render`).
+