@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/remotion-code-motion-explainer/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: remotion-code-motion-explainer
+description: "Create polished, code-driven AICUT motion explainers from scripts, narration, subtitles, product specifications, reference videos, UI recordings, diagrams, or abstract concepts. Use for product launches, AI demonstrations, UI interactions, algorithms, scientific principles, electrical systems, data flows, architecture, charts, equations, and concepts best expressed with React, SVG, Canvas, WebGL, or Three.js. Prioritize continuous spatial logic, visible cause and effect, precise interaction states, editable parameters, deterministic rendering, and evidence-backed visual QA. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "vibe-motion/remotion-code-motion-explainer"
+---
+
+# AICUT Code Motion Explainer
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+Build an abstract explanation as one continuous, editable visual system. Show how each concept
+changes instead of decorating narration with unrelated motion.
+
+Created by Bingo (`@DWCD-Bingo`) and maintained under the Vibe Motion organization.
+
+## Load the relevant guidance
+
+- Read `references/code-motion-design.md` for every production.
+- Read `references/motion-production-patterns.md` for every production.
+- Read `references/production-and-qc.md` before implementation and final delivery.
+- Read `references/ui-motion-shot-library.md` for UI, product, AI workflow, neon focus, waveform,
+  dashboard, design-tool, or high-fidelity interface work.
+- Read `references/reference-reconstruction.md` when studying or reproducing a reference video,
+  After Effects render, prototype, or screen recording.
+- Use `assets/shot-library` as the bundled editable starter library. Search
+  `assets/shot-library/shot-library.json` before designing a new shot. Copy the library into the
+  target project when a reusable component matches the semantic job; do not edit the installed
+  Skill in place.
+- Consult the installed Remotion documentation or best-practices skill before using unfamiliar APIs.
+
+## Establish the production contract
+
+1. Resolve the approved script or explanation, narration status, subtitle authority, aspect ratio,
+   frame rate, duration, brand system, technical facts, and delivery format.
+2. Treat human-verified subtitles as timing authority when narration exists. If there is no
+   narration, create an explicit beat timeline and design the video to remain understandable muted.
+3. Use only user-provided, licensed, public-domain, or clearly redistributable assets.
+4. Never invent product behavior, numerical data, scientific relationships, or interaction results.
+5. Prefer a parameterized visual system over one-off hard-coded scenes.
+
+## Execute the workflow
+
+### 1. Convert language into visual states
+
+- Split the explanation into clause-level semantic beats.
+- For every beat, record:
+  - narration or on-screen statement;
+  - narrative purpose;
+  - input state;
+  - dominant verb;
+  - visible transformation;
+  - output state;
+  - viewer focus;
+  - handoff to the next beat.
+- Compile nouns, actions, numbers, relationships, and state changes into independent visual actors.
+- Identify persistent objects that survive across beats.
+- Choose the simplest accurate representation: UI, flow, diagram, waveform, formula, chart,
+  spatial model, or 3D.
+- Write the plan to `src/data/choreography-plan.json`.
+
+Gate: every statement has a visible reasoning job, performer, result, and handoff.
+
+### 2. Lock the visual system
+
+- Define the grid, safe area, spacing, typography, color semantics, depth, camera, and motion curves.
+- Write one concept-angle sentence describing the visual world.
+- Design representative static frames for the hook, most complex mechanism, and ending.
+- Build the maximum-information hero frame before designing entrances.
+- Create a persistent-object registry and world-coordinate plan.
+- Decompose complex objects into meaningful moving parts rather than animating flat screenshots.
+- Keep identical concepts visually consistent throughout.
+
+Gate: the static frames read as one system and the complex frame can be assembled from editable
+components.
+
+### 3. Implement deterministic Remotion motion
+
+- Drive animation from `useCurrentFrame()`, `interpolate()`, `spring()`, and explicit frame ranges.
+- Do not use CSS transitions, CSS keyframes, random values without seeded determinism, or
+  independently timed browser animation.
+- Keep values parameterized through props and Zod schemas where useful.
+- Prefer React, SVG, and HTML. Use Canvas, WebGL, or Three.js only when the concept needs them.
+- Measure text, clamp ranges, validate numerical inputs, and avoid frame-dependent side effects.
+- Keep persistent objects mounted and mutate their state across beats.
+- Compose two to four compatible motion atoms in each four-to-six-second review window.
+- Give each window setup, action, visible result, and handoff phases.
+- Freeze every time-dependent child from the same display frame when the ending must hold.
+
+Gate: rendering is deterministic, editable, technically accurate, and stable at arbitrary frames.
+
+### 4. Preserve continuity and causality
+
+- Reuse position, object identity, scale, masks, direction, and audio motifs across transitions.
+- Transform or hand off one meaningful element before introducing the next.
+- Use camera moves only to reveal hierarchy or relationship.
+- Avoid repeated full-screen fade-and-scale resets.
+- Maintain at least one visual invariant across adjacent beats unless a chapter reset is deliberate.
+- Make cause and effect legible: input moves, process reacts, output becomes visible, and the camera
+  reveals the larger system.
+
+Gate: the silent video remains understandable as one continuous explanation.
+
+### 5. Bind narration, labels, and sound
+
+- Trigger labels, values, states, and interaction feedback on exact subtitle cues.
+- Keep narration clearly dominant over music and effects.
+- Use restrained ticks, impacts, sweeps, and tonal accents only for visible events.
+- Create an audio-event map alongside the motion plan.
+- End music and motion with an intentional resolution instead of a hard cut.
+
+### 6. Review, render, and learn
+
+- Render the hook, the most complex mechanism, equations/data states, transitions, and ending first.
+- Inspect entry, midpoint, maximum-information, handoff, and hold frames.
+- Review contiguous motion windows and their overlaps, not only isolated screenshots.
+- Create a contact sheet covering the full timeline.
+- Verify the final frame hold by comparing two late frames pixel-for-pixel.
+- Check text clipping, safe areas, color contrast, waveform/data correctness, missing assets, audio
+  peaks, duration, frame rate, and codec.
+- Save review evidence in `qc/workflow-evidence.json`.
+- Record fixes and reusable components in `qc/production-learning.json`.
+
+Gate: the complete render passes semantic, continuity, causality, composition, timing, technical,
+and licensing checks.
+
+## Reject
+
+Reject inaccurate interactions, invented data, arbitrary movement, unreadable labels, flattened
+process diagrams, generic slide resets, narration/subtitle mismatch, unlicensed assets, hard-coded
+personal paths, non-deterministic rendering, missing motion-window review, skipped final-frame hold
+checks, or branded reference copies presented as reusable templates.
+
+## Deliver
+
+Return the final video, editable Remotion project, timeline, component parameters, approved input
+assets, audio stems when used, contact sheet, QC evidence, and a short list of reusable components.
+
+## Bundled examples
+
+- `assets/showcase/code-motion-promo-30s.mp4`: 30-second capability trailer.
+- `assets/showcase/ac-to-dc-explainer.mp4`: scientific explainer example.
+- `assets/shot-library`: editable Remotion shot library and searchable catalog.
+
+## Source
+
+Rewritten for AICUT from [`vibe-motion/remotion-code-motion-explainer`](https://github.com/vibe-motion/remotion-code-motion-explainer)
+(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/remotion-code-motion-explainer/references/code-motion-design.md

@@ -0,0 +1,86 @@
+# Code Motion Design
+
+## Semantic compilation
+
+Turn each clause into a state transition:
+
+`input state → action → physical or logical consequence → visible result → handoff`
+
+Do not assign one generic illustration to an entire paragraph. Spoken buttons must be pressed,
+spoken values must change, and spoken relationships must become visible.
+
+Create a choreography entry for every beat:
+
+```json
+{
+  "id": "rectification",
+  "startFrame": 360,
+  "endFrame": 540,
+  "statement": "The bridge flips the negative half-cycle.",
+  "actors": ["waveform", "diodes", "current-path"],
+  "setup": "AC enters the bridge",
+  "action": "alternate diode pairs conduct",
+  "result": "both half-cycles appear positive",
+  "handoff": "pulsating DC enters the capacitor"
+}
+```
+
+## Persistent object registry
+
+Assign stable identities to objects that continue across scenes. Keep them mounted whenever
+possible and animate state, position, scale, path, or camera framing. This creates continuity and
+prevents the presentation from feeling like unrelated slides.
+
+Useful registry fields:
+
+- semantic name;
+- component;
+- world position;
+- visual state by beat;
+- entry and exit ownership;
+- transition handoff;
+- audio cue;
+- accessibility label.
+
+## Representation selection
+
+- Use UI simulation for software actions and product state.
+- Use diagrams for relationships, architecture, and cause-and-effect systems.
+- Use waveforms and charts for continuous values and comparisons.
+- Use equations when symbol manipulation is the meaning.
+- Use spatial models or 3D only when depth materially clarifies the explanation.
+
+## Composition
+
+- Establish one dominant focal object per beat.
+- Keep labels close to the object they explain.
+- Reserve saturated colors for semantic states, not decoration.
+- Use foreground and background depth to reinforce hierarchy.
+- Keep safe margins proportional to the output aspect ratio.
+- Design maximum-information frames first; entrances should reveal an already sound composition.
+
+## Motion
+
+Use motion to communicate:
+
+- causality;
+- direction;
+- hierarchy;
+- comparison;
+- continuity;
+- state change.
+
+Assign different easing families to different masses. Light UI elements may use a crisp spring;
+large panels require slower acceleration and settling. Do not start three unrelated animations on
+the same frame. Offset actions so the eye can follow cause and effect.
+
+## Scientific and technical explainers
+
+- Distinguish measured values, peak values, averages, and illustrative normalization.
+- Label conceptual particles or energy markers so viewers do not mistake them for literal scale or
+  velocity.
+- Preserve conservation relationships and topology.
+- Show intermediate conversion stages rather than jumping from input to output.
+- Put safety caveats in the visual when the subject involves hazardous voltage, heat, pressure,
+  chemicals, or machinery.
+

package/skills/remotion-code-motion-explainer/references/motion-production-patterns.md

@@ -0,0 +1,93 @@
+# Motion Production Patterns
+
+## Concept angle
+
+Write a single sentence that names the visual world and its logic. Examples:
+
+- A live circuit bench where energy travels through every conversion stage.
+- A product workspace that expands from one command into a coordinated agent system.
+- A city of data blocks whose roads reveal an algorithm's decisions.
+
+The concept angle constrains choices without forcing every scene into the same layout.
+
+## Hero-frame-first construction
+
+For each motion window:
+
+1. Compose the frame with the maximum meaningful information.
+2. Verify hierarchy, spacing, labels, and evidence.
+3. Decompose it into independent actors.
+4. Design setup and entrance motion.
+5. Design the visible result and handoff.
+
+Do not begin with entrance animations and hope they assemble into a good frame.
+
+## Motion atoms
+
+Combine a small number of compatible atoms:
+
+- reveal along path;
+- follow-path transfer;
+- state morph;
+- value count or interpolation;
+- focus pulse;
+- mask wipe;
+- camera push or pull;
+- staggered assembly;
+- graph trace;
+- particle flow;
+- orbit or field response;
+- UI press, type, drag, select, confirm.
+
+Give every atom a semantic owner, active interval, easing family, result, and handoff velocity.
+
+## Rhythm signature
+
+Avoid uniform timing. A useful explanatory rhythm is:
+
+`orient → anticipate → transform → inspect → handoff`
+
+Reserve short pauses for comprehension after visible results. Avoid long dead zones unless the
+narration requires reflection.
+
+## Parameterized scenes
+
+Expose meaningful parameters instead of cosmetic trivia:
+
+- data values and units;
+- topology or number of stages;
+- labels and language;
+- colors by semantic role;
+- timing and frame rate;
+- camera framing;
+- waveform frequency and amplitude;
+- product states;
+- output aspect ratio.
+
+Keep parameters validated and deterministic. A reusable component must work with at least two
+fixtures before being promoted as a general template.
+
+## UI interaction
+
+Render the complete interaction:
+
+`idle → pointer/focus → action → immediate feedback → system response → settled result`
+
+Do not show a cursor moving without a state change. Do not replace product evidence with ornamental
+glow. Use realistic hit areas, typing cadence, selection states, loading behavior, and success
+feedback.
+
+## Audio event map
+
+Create audio cues from visible events rather than adding effects after rendering:
+
+```json
+[
+  {"frame": 96, "event": "panel-lock", "sound": "soft-click"},
+  {"frame": 184, "event": "data-transfer", "sound": "short-sweep"},
+  {"frame": 268, "event": "result-confirmed", "sound": "tonal-resolve"}
+]
+```
+
+Keep sound effects sparse and subordinate to narration.
+

package/skills/remotion-code-motion-explainer/references/production-and-qc.md

@@ -0,0 +1,99 @@
+# Production and QC
+
+## Required project artifacts
+
+Recommended layout:
+
+```text
+project/
+├── src/
+│   ├── components/
+│   ├── data/choreography-plan.json
+│   ├── Root.tsx
+│   └── index.ts
+├── public/
+├── out/
+└── qc/
+    ├── stills/
+    ├── contact-sheet.jpg
+    ├── workflow-evidence.json
+    └── production-learning.json
+```
+
+## Deterministic rendering
+
+- Derive visual state only from frame, fps, props, and seeded data.
+- Do not fetch unstable network content during render.
+- Copy approved remote assets locally before final rendering.
+- Validate that every asset resolves from a relative project path.
+- Use one display frame for all children that must freeze together.
+- Render representative frames twice when randomness or simulation is involved.
+
+## Layered production
+
+For complex work, preserve separate outputs for:
+
+- base visual;
+- transparent overlays;
+- narration;
+- music;
+- sound effects;
+- final mix.
+
+Layered outputs make local repairs possible without re-rendering or degrading unaffected material.
+
+## Visual checks
+
+- no clipping, overflow, missing glyphs, or unsafe title placement;
+- readable smallest text at delivery resolution;
+- consistent semantic colors and object identities;
+- no accidental blank frames;
+- correct z-order and transparency;
+- charts, formulas, waveforms, and UI results match the source facts;
+- transitions preserve a visible invariant;
+- the ending resolves and holds.
+
+## Technical checks
+
+Verify with a media probe:
+
+- exact dimensions;
+- expected frame rate;
+- duration;
+- video codec;
+- audio codec and channel layout when audio exists;
+- no unintended audio stream;
+- file size suitable for the publishing destination.
+
+## Evidence schema
+
+`qc/workflow-evidence.json` should record:
+
+```json
+{
+  "semanticActionResult": "pass",
+  "persistentObjectHandoff": "pass",
+  "motionWindowReview": "pass",
+  "cueSync": "pass",
+  "finalHold": {
+    "frameA": 1045,
+    "frameB": 1079,
+    "identical": true
+  },
+  "notes": []
+}
+```
+
+`qc/production-learning.json` should record each issue, root cause, fix, prevention rule,
+verification, and reusable candidate. Promote a candidate only after validation in multiple
+projects.
+
+## Licensing and privacy
+
+- Scan all text and metadata for usernames, home paths, tokens, internal domains, private contacts,
+  client names, and unreleased products.
+- Treat reference videos and After Effects projects as study material unless their license permits
+  redistribution.
+- Publish extracted, brand-neutral motion systems—not third-party footage or source projects.
+- Keep attribution required by licenses near the relevant asset.
+

package/skills/remotion-code-motion-explainer/references/reference-reconstruction.md

@@ -0,0 +1,48 @@
+# Reference Reconstruction
+
+## Declare fidelity
+
+Choose one level before implementation:
+
+- **inspired**: preserve principles and rhythm, not geometry;
+- **structural**: preserve layout, topology, phases, and camera logic;
+- **high fidelity**: reproduce measured geometry and timing with authorized assets;
+- **exact**: reproduce pixels, audio, and timing only when the user owns or has licensed the source.
+
+## Build an evidence ledger
+
+Record:
+
+- source dimensions, frame rate, duration, and checksum;
+- semantic phase boundaries;
+- object count and topology;
+- bounding boxes and centers;
+- path endpoints;
+- camera scale and translation;
+- color samples;
+- text anchors;
+- transition peaks;
+- motion direction and easing observations.
+
+A prose description is not enough for high-fidelity work.
+
+## Reconstruction loop
+
+1. Extract a fixed comparison frame set.
+2. Segment the source into semantic phases.
+3. Rebuild independent components.
+4. Match topology and large geometry before styling.
+5. Match typography, color, depth, and effects.
+6. Match motion timing and transition peaks.
+7. Render the identical frame set.
+8. Compare overlays, crops, and numerical geometry.
+9. Keep the previous best and merge only improvements.
+
+Do not change the scorer, frame set, or weights during iteration.
+
+## Generalization rule
+
+Separate research evidence from reusable output. Remove logos, copy, proprietary audio, and
+product-specific geometry before promoting a system. Expose semantic parameters and validate the
+neutralized component in a second project.
+

package/skills/remotion-code-motion-explainer/references/ui-motion-shot-library.md

@@ -0,0 +1,62 @@
+# UI Motion Shot Library
+
+This public catalog contains brand-neutral systems extracted from original UI and After Effects
+studies. Implement them as parameterized Remotion components; do not depend on private paths or
+source projects.
+
+## Catalog
+
+### Neon path focus
+
+- Purpose: route attention through a dark interface or AI workflow.
+- Actors: path, glow field, focus node, labels, background grid.
+- Parameters: path points, progress, glow radius, focus color, labels, camera scale.
+- Motion: trace path, energize destination, settle glow, hand off destination as next scene anchor.
+- Reject: decorative neon with no semantic destination.
+
+### Responsive UI stage
+
+- Purpose: show the same product state across landscape and portrait layouts.
+- Actors: navigation, workspace, inspector, floating actions, safe-area mask.
+- Parameters: aspect ratio, breakpoint, panel widths, content density, active tool.
+- Motion: reflow independent regions instead of cropping one layout.
+- Reject: scaling a 16:9 screenshot to impersonate a mobile layout.
+
+### Command-to-result workflow
+
+- Purpose: show a prompt or command producing coordinated product actions.
+- Actors: command input, task nodes, connectors, status indicators, result panel.
+- Parameters: command, node count, labels, task states, connection topology.
+- Motion: type, submit, dispatch, execute, converge, reveal result.
+- Reject: results appearing without an observable system response.
+
+### Audio waveform transformation
+
+- Purpose: explain recording, filtering, synthesis, transcription, or signal conversion.
+- Actors: waveform, playhead, frequency bands, state labels, output trace.
+- Parameters: samples, amplitude, frequency, smoothing, color, duration.
+- Motion: trace input, transform the signal, compare output, hold the measured result.
+- Reject: random waveforms that do not correspond to the stated transformation.
+
+### Data pipeline
+
+- Purpose: explain ingestion, processing, branching, aggregation, and output.
+- Actors: packets, nodes, queues, filters, counters, output cards.
+- Parameters: topology, throughput, failure state, branch rules, labels.
+- Motion: inject, route, react, aggregate, confirm.
+- Reject: particles moving without nodes visibly responding.
+
+### Layered design-tool transformation
+
+- Purpose: demonstrate editing, compositing, layout, or design-system changes.
+- Actors: canvas, layers, selection box, handles, inspector values, result comparison.
+- Parameters: layer tree, selected layer, bounds, property values, before/after states.
+- Motion: select, manipulate, update inspector, reveal resulting composition.
+- Reject: cursor theater without editable-state evidence.
+
+## Selection record
+
+For each candidate, record whether it was reused, adapted, or rejected and why. Preserve object
+identity and responsive evidence. Validate a system in two projects before calling it a reusable
+shot template.
+