editorbrain 0.12.0 → 0.26.0

package/skill/editorbrain-motion/references/code-motion.md

@@ -0,0 +1,54 @@
+# Motion with code and compositing
+
+Read for scenes implemented with code or editable compositing. Use the current project's effective tokens, shot plan and approved direction; this guide defines production properties, not a new tool API.
+
+Start from the shot's specific visual action. Consult the compact [component library](component-library.md) when an existing mechanism fits it; select one pinned recipe rather than loading every implementation. Reuse useful utilities without inheriting an unrelated title/list layout or fixed stage timing. Custom composition is the normal route when the message needs different objects, relationships or choreography.
+
+## Make the idea visible
+
+A scene needs a meaningful state change: reveal a relationship, assemble a process, isolate evidence, compare alternatives or resolve a question. Decide what the viewer should notice before selecting a transition. A moving card is useful only when its change of position, scale or emphasis communicates that intention.
+
+Use short text as part of the action where appropriate: a request can become a constraint, a duration can become a calendar interval, or a word can become a visible boundary. Preserve object identity and show the consequence of each action. Design anticipation, action and a perceptible hold around the beat, rather than dividing every scene into equal steps. Camera moves, masks, deformation and light/dark changes are options, not a required effects checklist.
+
+Use a compact shot record when the existing plan lacks this detail:
+
+| Field | What to record |
+|---|---|
+| Intention and evidence | Message; verified source or explicitly designed illustration |
+| Entry → action → exit | Visible states, object identities and continuity into adjacent shots |
+| Time | Voice/action cue, motion interval, readable hold and exit |
+| Layers | Authentic assets, controlled text/data/UI, masks and background |
+| Layout | Hierarchy, safe areas and changes needed for each requested ratio |
+| Check | The specific failure that would break understanding or the chosen mechanism |
+
+This is an optional local planning format, not an EditorBrain schema. Do not place unsupported fields into `project.json`, `media.json` or API payloads.
+
+Keep exact words, values, logos and demonstrated interface states editable. Obtain authentic UI/assets when the scene claims to demonstrate a real product. Mark invented interface states as illustrative; a logo or mockup does not prove a capability. Required fonts need verified available font files or an authorized exception, never an unnoticed renderer fallback.
+
+## Make time explicit
+
+Choose the available engine and inspect its current documentation/skill before implementation. Frame-based rendering, seek APIs and resource readiness differ by engine/version. Record the actual implementation; do not claim compatibility with a renderer that was not used.
+
+When the engine supports deterministic access, calculate visual state from an explicit frame/time and immutable shot data. Keep global versus shot-local time explicit. Conceptually:
+
+```text
+globalTime = frame / fps
+localTime = max(0, globalTime - shot.start)
+state = sceneAt(localTime, resolvedTokens, loadedAssets, layout, seed)
+```
+
+This is pseudocode, not a command or available function. Adapt it to the real renderer. Avoid playback history, wall-clock timers, unseeded randomness and incremental position updates as the source of render state. Preload assets and fonts before captures. Pin environment/dependency versions when exact image comparison matters; reproducible time alone does not ensure identical pixels across machines.
+
+Use one timeline for visual cues and any chosen audio cues. Recompute dependent timing when voice or source action changes. Sound remains optional; a shared cue aligns intent but does not establish perceived synchronization. Respect the effective music/SFX exclusions.
+
+For a new temporal implementation, sample the same important state directly and after out-of-order seeks in the same environment. Compare the output, not only whether the API returned successfully. Skip repeating this check for an unrelated copy change when the temporal implementation remains valid.
+
+## Review the mechanism, then the export
+
+Use sparse beat frames to inspect composition and dense transition strips around risky intervals to inspect state changes, occlusion, overlap, easing and object persistence. Choose times from the actual motion; a universal sampling count can miss a fast defect. Check sufficient readable hold at the intended viewing size. Automated bounds can detect some clipping; they cannot establish legibility or editorial meaning.
+
+Recompose each requested ratio: adjust hierarchy, line breaks, staging, asset crop and trajectory as necessary. Generate evidence from each output, since a horizontal pass does not validate a vertical crop. Watch the final export for continuity, pace and closure; listen if audio is present and the modality is available. Follow the shared [production review](../../editorbrain/references/production-and-review.md) for delivery checks.
+
+Keep localized findings concise: `output hash/version → time/interval → observed defect → evidence → correction`. A contact sheet plus transition strips and playable output can be a local review artifact; no particular HTML format or helper is required. Preserve editable sources, asset hashes, engine details and final timing locally. Recheck the modified interval and final delivery without reopening approved unrelated scenes.
+
+For frame boundaries and supplied geometry, read [targeted motion review](../../editorbrain/references/motion-review.md). It provides an optional CLI sampling plan and collision candidates; it does not replace watching motion.

package/skill/editorbrain-motion/references/component-library.md

@@ -0,0 +1,52 @@
+# Reusable motion components
+
+Use only when a component fits the scene's message. A component is executable source; a media-style recipe is visual guidance. Neither is a universal guarantee of quality.
+
+These are bounded scene templates, not the default structure for every motion graphic. Their title and labels/details contract does not represent arbitrary choreography. Use custom composition when a scene needs different objects, relationships, staging or timing; do not force its message into the available template fields.
+
+## Discover one, prepare locally
+
+1. Reuse the active resolved project and workflow checkpoint. Query `list_motion_components(query?)` or `editorbrain motion list [query]` for compact metadata; fetch only `get_motion_component(componentId, version)` / `editorbrain motion get <id> --component-version 1.0.0` for the selected recipe. These queries contain no implementation source or private reference assets.
+2. Map background, foreground, accent and fontFamily to **actual keys in resolved.tokens**. Names differ by account. Use the declared local font file for that family and verify it visually. No demo palette is a fallback. Respect required tokens, exclusions and disabled motion. Output size/fps come from the selected project.
+3. Write a small scene input under `.editorbrain-local/<project>/`. Example structure below; replace placeholders with selected project values. Font/image paths are local, absolute or relative to this JSON. Keep assets within this local folder for portability.
+
+```json
+{
+  "componentId": "sticker-explainer",
+  "componentVersion": "1.0.0",
+  "bindings": {
+    "background": "YOUR_BACKGROUND_TOKEN",
+    "foreground": "YOUR_TEXT_TOKEN",
+    "accent": "YOUR_ACCENT_TOKEN",
+    "fontFamily": "YOUR_FONT_TOKEN"
+  },
+  "fontFile": "assets/approved-font.woff2",
+  "title": "A clear scene title",
+  "duration": 12,
+  "motion": "full",
+  "items": [
+    {"label": "First decision", "detail": "Why it matters.", "imageFile": "assets/first.png"},
+    {"label": "Next decision", "detail": "What changes.", "imageFile": "assets/second.png"}
+  ]
+}
+```
+
+Choose the mechanism, not a new skill: `sticker-explainer` for cutouts; `shape-morph` for geometric progression; `isometric-system` for spatial processes; `sketch-diagram` for traced explanations; `bauhaus-type` for modular typography. The last three require CLI 0.21+ and accept no `imageFile`. Use 2–4 concise labels/details; `sketch-diagram` optionally uses the same shape vocabulary. Keep content truthful: moving signals illustrate the declared process, not a live execution. Fetch only the selected component's detail.
+
+CLI 0.22+ also adds `liquid-flow` (fluid fusion/separation), `aurora-glass` (gentle luminous layers) and `pixel-journey` (stepped sprite milestones). These accept labels/details, not `imageFile`; pixel graphics keep the customer font for text. Liquid and glass are illustrative treatments, not physical simulations.
+
+For `shape-morph`, use meaningful `shape` values instead of `imageFile`: circle, capsule, diamond, heart, shield, chat or star. Arbitrary logos and contours with holes are not supported. Do not imply business causality from a geometric transition. Transparent cutouts work best for stickers; supplied photography and logos keep their original colors.
+
+```sh
+editorbrain motion prepare --file .editorbrain-local/PROJECT/scene.json --project PROJECT --out .editorbrain-local/PROJECT/scene-v1
+```
+
+The output directory must be new. Preparation validates input before writing; it does not call models, upload media or modify brand documents. It saves `index.html`, embedded scene data and a receipt with source/context hashes. A changed project requires preparing a new version; the generated scene does not auto-sync later brand edits. Review conflicts rather than overwriting files.
+
+## Review and render
+
+Open the HTML preview. For external frame capture use `?capture=1`, wait for `window.__ready`, fail on `window.__motionError`, and call `window.renderAt(seconds)` explicitly. Query `window.getMotionDiagnostics()` for measured text overflow and readiness. Capture `#stage` only at the project's actual dimensions; encode with the available renderer. `prepare` alone does not create an MP4.
+
+Read title, captions and transitions at final display size. Inspect meaning, pacing and hierarchy, not only bounds. Test actual requested ratios, long text and selected brand colors. A foreground/background contrast failure requires an intentional project decision, never silent recoloring. `motion: "reduced"` uses static states/cuts. The standalone preview starts paused; a custom autoplay wrapper must honor the viewer's reduced-motion preference.
+
+Scenes are silent. Integrate approved voice, music or SFX separately on a shared timeline and review audible output. Save only the chosen component id/version, relevant bindings and continuation notes in the portable direction; keep code, embedded assets, frame strips and detailed QA local. Do not send embedded files or implementation source back through model context.

package/skill/editorbrain-motion/references/generated-motion.md

@@ -0,0 +1,48 @@
+# Generated motion with consistent material and identity
+
+Read when a shot needs generated motion or assets. Start from the current member's verified tool/model access, effective media preferences and the task's authorized spending. Follow the provider's actual skill/schema; this guide adds no generation command or implicit permission.
+
+## Separate the controls
+
+Use four distinct layers of intent:
+
+1. **Graphic identity:** resolved customer colors, fonts and brand restrictions for authored graphic layers.
+2. **Representation:** the selected material, surface, dimensionality, edges, lighting, depth and permitted physical behavior of generated assets.
+3. **Asset identity:** stable person/object/location attributes, approved references and continuity-critical details.
+4. **Shot direction:** the scene's action, camera, staging, entry/exit state and timing.
+
+Reference images can inform representation without donating their palette, face, subject or branding. Preserve authentic footage/product/logo colors unless intentionally changed by the approved direction. Do not force all customers into the material treatment of a demonstration. If references conflict, narrow the treatment or state the conflict; do not invent a professional style name to imply coherence.
+
+For scenes sharing a treatment, save a compact, versioned representation block locally. Include only consequential constraints:
+
+```text
+Treatment version and relevant project/style IDs:
+Material, surface and dimensionality:
+Edges, lighting, depth and rendering behavior:
+Permitted deformation and movement:
+Identity references and stable attributes:
+Continuity constraints / forbidden changes:
+Graphic layers reserved for controlled composition:
+```
+
+This is a planning/prompt aid, not a new portable schema. Reuse the same block within that version while changing each shot's action and composition. Revise it deliberately when evidence shows a defect; preserve the prior version. Save reusable treatment rules into the user's style only when the task requests that scope, following [style creator](../../editorbrain/references/style-creator.md).
+
+Inspect the actual reference assets before generating motion. A video model may inherit unwanted volume, texture, colors or anatomy already present in its inputs. Correct the input or account for it in the plan; prompt wording alone cannot guarantee removal.
+
+## Give the shot a testable action
+
+Describe the message, visible start, essential action, expected finish, camera behavior and usable hold. Include constraints needed for overlays, continuity and the requested ratio. Use the provider's supported reference roles and controls; verify model/format availability instead of assuming it from the provider's name.
+
+Prefer controlled composition for exact text, data, logos and interface states. When named objects must persist, move to exact positions or follow a strict sequence, retain their identities and positions in editable layers, tracked composites or another verified control mechanism. Generative scenery/character movement can support those layers. If generation cannot meet the required action, redesign that shot or use a feasible controlled method; an attractive final pose cannot compensate for an incorrect intermediate step.
+
+A short representative test is useful when material, identity or action is uncertain. Its size follows the risk and available evidence, not a required reference count, duration or provider. Reuse task approval. Do not multiply failed generations indefinitely: after a demonstrated repeated failure, change the input, simplify the shot or choose a different feasible mechanism within authorization.
+
+## Inspect the generated result
+
+Review the output itself, not the submitted prompt or provider's success status. Check that identity, material and required props persist through movement, including occlusion, handoffs, crossings, cuts and fast changes. Inspect dense neighboring states around suspect intervals; matching start/end frames do not establish continuity.
+
+Compare the actual usable duration and action with the shot plan. Trim only when the retained interval still communicates the intended event; do not label a still-image fallback as inspected footage. Keep provider-generated audio separate from verified sound decisions, and listen before judging it. Report audio unverified when unavailable.
+
+Then review the assembled export and every delivered ratio with the shared [production review](../../editorbrain/references/production-and-review.md). Record output hash, relevant source/reference hashes, model and settings actually used, prompt/block version, accepted interval and localized deviations. Keep complete prompts and review samples private locally; carry only the necessary decisions into `direction.md`.
+
+A stable block guides generation but does not guarantee object persistence, identity fidelity or physical continuity. Describe observed success and remaining defects with time evidence; distinguish this generation's review from transfer testing on other scenes and human approval.