retiam 2.0.1 → 2.0.2

package/THIRD_PARTY_NOTICES.md

@@ -311,8 +311,8 @@ After dependency or asset changes, run `npm ci`, then
 for packages that omit license files, reviewed README excerpts, and asset provenance are recorded in
 `tools/third-party-sources.json` in the source repository. These internal maintenance records
 are not needed in distributions. Generation uses local files and checked-in originals;
-it does not execute package scripts or fetch new legal terms. Run
-`npm run licenses:check` to verify the committed input and file fingerprints.
-This command also runs before the library build.
+it does not execute package scripts or fetch new legal terms. This is a
+maintenance command for dependency, asset, or license changes; ordinary builds,
+publishing, and package-version changes do not require regenerating the inventory.
 
 <!-- retiam-third-party-packages: ["@babel/code-frame@7.27.1","@babel/helper-validator-identifier@7.28.5","@dimforge/rapier2d-compat@0.20.0","@dimforge/rapier3d-compat@0.20.0","@petamoriken/float16@3.9.3","@puppeteer/browsers@1.9.1","@tensorflow/tfjs-backend-cpu@4.20.0","@tensorflow/tfjs-backend-webgl@4.20.0","@tensorflow/tfjs-backend-webgpu@4.20.0","@tensorflow/tfjs-converter@4.20.0","@tensorflow/tfjs-core@4.20.0","@tensorflow/tfjs-data@4.20.0","@tensorflow/tfjs-layers@4.20.0","@tensorflow/tfjs@4.20.0","@tootallnate/quickjs-emscripten@0.23.0","@types/dom-webcodecs@0.1.18","@types/estree@1.0.7","@types/libtess@1.2.0","@types/long@4.0.2","@types/node-fetch@2.6.13","@types/node@22.7.4","@types/offscreencanvas@2019.3.0","@types/offscreencanvas@2019.7.3","@types/prismjs@1.26.6","@types/seedrandom@2.4.34","@types/wicg-file-system-access@2020.9.8","@webgpu/types@0.1.38","@webgpu/types@0.1.40","@zappar/msdf-generator@1.2.4","agent-base@6.0.2","agent-base@7.1.3","ansi-regex@5.0.1","ansi-styles@4.3.0","argparse@1.0.10","argparse@2.0.1","as-number@1.0.0","ast-types@0.13.4","asynckit@0.4.0","axios@1.20.0","b4a@1.6.7","base64-js@1.5.1","basic-ftp@5.0.5","box3d-wasm@0.2.0","buffer-crc32@0.2.13","buffer@5.7.1","buffer@6.0.3","call-bind-apply-helpers@1.0.2","callsites@3.1.0","chalk@4.1.2","chromium-bidi@0.5.8","cli-progress@3.12.0","cliui@7.0.4","cliui@8.0.1","color-convert@2.0.1","color-name@1.1.4","combined-stream@1.0.8","comlink@4.4.2","commander@9.2.0","core-js@3.29.1","cosmiconfig@9.0.0","cross-fetch@4.0.0","data-uri-to-buffer@6.0.2","debug@4.3.4","degenerator@5.0.1","delayed-stream@1.0.0","devtools-protocol@0.0.1232444","dunder-proto@1.0.1","earcut@3.0.2","emoji-regex@8.0.0","end-of-stream@1.4.4","env-paths@2.2.1","error-ex@1.3.2","es-define-property@1.0.1","es-errors@1.3.0","es-object-atoms@1.1.2","es-set-tostringtag@2.1.0","esbuild@0.25.5","esbuild@0.28.1","escalade@3.2.0","escodegen@2.1.0","esm@3.2.25","esprima@4.0.1","estraverse@5.3.0","esutils@2.0.3","events@3.3.0","extract-zip@2.0.1","extrude-polyline@1.0.6","fast-fifo@1.3.2","fd-slicer@1.1.0","fdir@6.4.5","fdir@6.5.0","follow-redirects@1.16.0","form-data@4.0.6","function-bind@1.1.2","get-caller-file@2.0.5","get-intrinsic@1.3.0","get-proto@1.0.1","get-stream@5.2.0","get-uri@6.0.4","gl-vec2@1.3.0","gopd@1.2.0","hachure-fill@0.5.2","has-flag@4.0.0","has-symbols@1.1.0","has-tostringtag@1.0.2","hasown@2.0.4","http-proxy-agent@7.0.2","https-proxy-agent@5.0.1","https-proxy-agent@7.0.6","ieee754@1.2.1","import-fresh@3.3.1","inherits@2.0.4","ip-address@9.0.5","is-arrayish@0.2.1","is-fullwidth-code-point@3.0.0","isomorphic-ws@5.0.0","jolt-physics@1.1.0","js-tokens@4.0.0","js-yaml@4.1.0","jsbn@1.1.0","json-parse-even-better-errors@2.3.1","libtess@1.2.2","lines-and-columns@1.2.4","long@4.0.0","lru-cache@7.18.3","math-intrinsics@1.1.0","mathjax-full@3.2.2","matter-js@0.20.0","mhchemparser@4.2.1","mime-db@1.52.0","mime-types@2.1.35","mitt@3.0.1","mj-context-menu@0.6.1","mkdirp-classic@0.5.3","monaco-editor@0.45.0","mp4-muxer@5.2.2","ms@2.1.2","msedge-tts@2.0.8","nanoid@3.3.11","netmask@2.0.2","node-fetch@2.6.13","node-fetch@2.7.0","oidn-web@0.3.5","once@1.4.0","opentype.js@1.3.4","pac-proxy-agent@7.2.0","pac-resolver@7.0.1","pako@1.0.11","parent-module@1.0.1","parse-json@5.2.0","path-data-parser@0.1.0","pend@1.2.0","picocolors@1.1.1","picomatch@4.0.2","picomatch@4.0.3","planck@1.5.0","points-on-curve@0.2.0","points-on-path@0.2.1","polygon-clipping@0.15.7","polyline-miter-util@1.0.1","postcss@8.5.6","prismjs@1.30.0","progress@2.0.3","proxy-agent@6.3.1","proxy-from-env@1.1.0","proxy-from-env@2.1.0","pump@3.0.2","puppeteer-core@21.11.0","puppeteer@21.11.0","readable-stream@3.6.2","regenerator-runtime@0.13.11","require-directory@2.1.1","resolve-from@4.0.0","robust-predicates@3.0.3","rollup@4.41.1","roughjs@4.6.6","safe-buffer@5.2.1","seedrandom@3.0.5","smart-buffer@4.2.0","socks-proxy-agent@8.0.5","socks@2.8.5","source-map-js@1.2.1","source-map@0.6.1","speech-rule-engine@4.0.7","splaytree@3.2.3","sprintf-js@1.0.3","sprintf-js@1.1.3","stage-js@1.0.2","stream-browserify@3.0.0","streamx@2.22.1","string-width@4.2.3","string.prototype.codepointat@0.2.1","string_decoder@1.3.0","strip-ansi@6.0.1","supports-color@7.2.0","svg-parser@2.0.4","svg-pathdata@7.1.0","tar-fs@3.0.4","tar-stream@3.1.7","text-decoder@1.2.3","through@2.3.8","tiny-inflate@1.0.3","tinyglobby@0.2.15","tr46@0.0.3","tslib@2.8.1","tsx@4.22.4","typescript@5.4.5","unbzip2-stream@1.4.3","undici-types@6.19.8","urlpattern-polyfill@10.0.0","utif@2.0.1","util-deprecate@1.0.2","vite@6.3.6","webidl-conversions@3.0.1","webm-muxer@5.1.4","wgsl_reflect@1.2.3","whatwg-url@5.0.0","wicked-good-xpath@1.3.0","woff2-encoder@2.0.0","wrap-ansi@7.0.0","wrappy@1.0.2","ws@8.16.0","ws@8.22.0","xmldom-sre@0.1.31","y18n@5.0.8","yargs-parser@20.2.9","yargs-parser@21.1.1","yargs@16.2.0","yargs@17.7.2","yauzl@2.10.0","yerror@8.0.0"] -->

package/agent/AGENTS.md

@@ -0,0 +1,67 @@
+# Retiam animation project
+
+Read [.agents/skills/retiam/SKILL.md](.agents/skills/retiam/SKILL.md) when creating,
+editing, reviewing, or rendering scenes. It links to the API notes, an executable
+example, and the visual review criteria. This project uses Retiam's TypeScript
+and WebGPU APIs.
+
+- Author default-exported `Scene` subclasses in `src/scenes/` with `async run()`.
+- Read the existing scene and `package.json` first. Honor the requested duration,
+  aspect ratio, and technical project conventions. A requested visual redesign
+  takes precedence over the previous scene's layout.
+- The default creative direction is a **3Blue1Brown-inspired mathematical
+  explainer**, matching the Dijkstra reference: dark navy, vivid stable object
+  colors, smooth path drawing and value transfers, readable LaTeX, conversational
+  questions, thinking pauses, and one attention target at a time. Keep the
+  implementation in Retiam TypeScript/WebGPU.
+- Educational projects include `lesson/lesson.json`. Read it before creating an
+  explainer, then replace the square-area reference with the user's topic,
+  audience, objective, sources, narration and visible events. Use the packaged
+  skill's `references/explainers.md` for the production workflow and public API.
+- Style is independent of subject and pedagogy. Honor an explicit prompt style
+  over the saved profile, and persist it in the lesson: mathematical (default),
+  excalidraw, minimal, cinematic, or custom overrides extending a profile. Read
+  `references/styles.md` for the selected look. A biology video need not contain
+  code or a table; choose representations that explain its mechanism.
+- For a new video, read the skill's `references/quality.md` before planning.
+  Explain through evolving geometry, simulations, and visible cause and effect.
+  Avoid a default layout of persistent text panels, chapter slides, page counters,
+  and repeated fade-ins. Plan what changes on screen and where attention moves.
+  The small setup examples demonstrate APIs; `examples/SecantToTangent.ts` shows
+  a more substantial visual explanation. Follow a slide/deck layout only when requested.
+- Use Retiam's built-in libraries for their supported features. For generated
+  narration, use `retiam/tts`; read the skill's `references/tts.md` and
+  `examples/NarratedMotion.ts`. Use another speech generator only when the user
+  requests it. Diagnose native TTS failures instead of silently installing Python
+  TTS tools or replacing the narration pipeline.
+- Use `retiam/explainer` for prepared speech, named cues, explicit silent pauses
+  and synchronized beats. `npm run lesson:check` validates the contract;
+  `npm run lesson:prepare` caches enabled native narration. Prepare audio before
+  locking timings. Scene handlers must animate or schedule state changes, since
+  they are built before playback. Capture prediction pauses as well as reveals.
+- Include narration for an explainer unless the brief requests a silent video.
+  The sample disables narration only for an offline first preview; enable it and
+  prepare the requested lesson's speech as part of producing the video.
+- Separate automated checks from observed visual and factual review. Record
+  evidence in `lesson/review.json`; a valid plan or passing lint does not establish
+  teaching quality. Keep approved audio files so visual revisions can reuse them.
+- Use the installed version's declarations as the API authority. Run
+  `npx retiam context --json` to locate its guidance, examples, and declarations.
+  The local skill is supplied by the generator; the installed engine may be newer.
+- Type-check with `npm run check`, then lint each changed scene with
+  `npx retiam lint src/scenes/YourScene.ts --json`. Lint is a heuristic check,
+  not proof of runtime or visual correctness. Review its warnings.
+- Capture representative moments with
+  `npx retiam snapshot src/scenes/YourScene.ts --times 0,1,3 --json`.
+  Choose times from the actual scene, open the resulting PNGs, and fix clipping,
+  overlap, readability, and pacing before final rendering.
+- Preview with `npm run dev`. Projects with Studio discover scenes automatically;
+  the standalone page uses the scene imported by `src/main.ts`.
+- Render a requested video with `npx retiam render src/scenes/YourScene.ts`.
+  Check `config.js` or `retiam.config.js` and command help for output settings.
+- Report the scene and output paths, checks performed, and any unavailable visual
+  or render checks. If WebGPU/Chrome or FFmpeg is missing, report that limitation;
+  a passing type check does not establish visual quality.
+
+Use the project's package manager and lockfile. Keep generated outputs in
+`outputs/`. Change Studio, build tooling, and dependencies when the task needs it.

package/agent/CLAUDE.md

@@ -0,0 +1,2 @@
+Read and follow [AGENTS.md](AGENTS.md) for this Retiam project. The scene authoring
+skill is [.agents/skills/retiam/SKILL.md](.agents/skills/retiam/SKILL.md).

package/agent/skill/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: retiam
+description: Create, direct, review, and render Retiam TypeScript animations and narrated explainers, with selectable visual styles and version-matched WebGPU APIs.
+---
+
+# Retiam scene authoring
+
+The default creative direction is a **3Blue1Brown-inspired mathematical
+explainer**. Lead with visual intuition: ask a concrete question, construct an
+example, reveal why it works, then connect the geometry to notation and a wider
+principle. Use a clean dark stage, readable mathematics, a small purposeful
+palette, continuous transformations, and carefully timed explanation. Honor an
+explicitly different style or palette in the user's brief. Implement this with
+Retiam's public TypeScript/WebGPU APIs and native libraries.
+
+Start from the user's intended explanation or visual result. Read the existing
+scene and identify its subject, audience, duration, aspect ratio, and style.
+For a new animation, read [references/quality.md](references/quality.md) first.
+Sketch the visible state change, the motion revealing it, and the attention target
+for each beat. A narration paragraph with a title is not a visual beat. Scale this
+planning to the task; a small edit does not need a new storyboard.
+
+## Find the API before authoring
+
+Read [references/api.md](references/api.md) for scene lifecycle, units, styling,
+camera framing, and common mistakes. Use
+[examples/ExplainMotion.ts](examples/ExplainMotion.ts) only for a small API smoke
+test. For a new explainer, study [examples/SecantToTangent.ts](examples/SecantToTangent.ts):
+one diagram evolves through comparison, convergence, a mathematical transition,
+and a moving generalization. Adapt its directing principles to the subject; do
+not reuse its mathematics or visual layout for unrelated briefs. Copy an example
+into `src/scenes/` to run it in Studio.
+
+For an educational video, read [references/explainers.md](references/explainers.md).
+Fresh projects include a lesson contract, native narration commands, cue timing,
+and review evidence. The default style matches the Dijkstra reference: navy,
+vivid stable colors, continuous drawing and transfers, conversational prediction
+and discovery. For Excalidraw, minimal, cinematic or custom styling, read only the
+relevant profile in [references/styles.md](references/styles.md). An explicit
+user style overrides the saved profile; retain the teaching workflow.
+`AreaLesson.ts` in the examples is a complete small construction using
+`retiam/explainer`; adapt its mechanism to the actual subject.
+
+Run `npx retiam context --json` to find documentation and TypeScript declarations
+belonging to the engine actually executing this command. Follow exports and
+constructor signatures there before using an unfamiliar feature. When an API
+example differs from the installed version, follow the installed declarations
+and release-specific setup requirements. Use the project brief and local directing
+guide for creative decisions. Prefer public imports from `retiam` and `retiam/*`.
+
+Choose Retiam's matching sublibrary before introducing an external implementation:
+`retiam/tts` for generated narration and subtitles, `retiam/physics` for rigid-body
+simulation, `retiam/charts` for charts, `retiam/graphs` for graphs and automata,
+`retiam/shapes` for procedural shapes, `retiam/highlights` for attention effects,
+and `retiam/rough` for sketch styling.
+
+For voiceover, speech, or narration, read [references/tts.md](references/tts.md)
+and [examples/NarratedMotion.ts](examples/NarratedMotion.ts) before authoring.
+That example isolates speech integration; it is not a finished video's visual standard.
+Use `retiam/tts` for synthesis, timing, subtitles, and the scene audio bus. Use a
+different speech generator only when the user requests it. If Retiam TTS fails,
+check its Vite middleware, endpoint, network access, and audio unlock; report the
+actual blocker instead of silently installing Python TTS tools or switching providers.
+
+## Author for the requested result
+
+Use a default-exported class extending `Scene` with `async run()` and add visible
+entities to the scene. Await timeline operations; use Retiam animation groups
+for intentional concurrency. Durations and waits use milliseconds; snapshot
+timestamps use seconds. Animate with the engine timeline, not wall-clock timers.
+
+Build the explanation around objects that change: paths being explored, a shape
+being decomposed, a parameter altering a field, or a construction reaching its
+limit. Keep object identity and color meaning through transformations. Put short
+labels near the relationship they explain; use mathematical notation for formulas.
+Use framing, emphasis, and deliberate pauses to direct attention. Use camera moves
+when they reveal a useful scale or relationship. Follow the default direction in
+`references/quality.md` while honoring the brief. The construction and its timing
+carry the explanation; extra glow, constant zooming, and decorative effects do
+not establish this style.
+
+Unless the user asks for slides or a dashboard, avoid a persistent title/body
+template, a large explanatory sidebar, page counters, and screen-wide fade-out /
+fade-in chapter changes. A table can be useful when the changing entries are the
+subject; show it when needed and keep the visual mechanism primary. Narration
+should explain why the visible event matters, not replace missing visual action.
+
+## Close the feedback loop
+
+1. Run the project's type check (`npm run check`) and
+   `npx retiam lint src/scenes/YourScene.ts --json`. Fix errors and assess warnings.
+   The linter does not replace TypeScript, execution, or image review.
+2. Snapshot the beginning, a transition, the main explanatory moment, and the
+   resolved state using `npx retiam snapshot src/scenes/YourScene.ts --times ... --json`.
+   Use timestamps from the actual storyboard. Open the returned image paths.
+3. Fix composition issues visible in those images. Watch playback in Studio
+   (`npm run dev`) to assess motion and pacing; still images cannot establish those.
+   Review against the presentation-pattern checks in `references/quality.md`.
+   If the middle of a beat is essentially a static slide with narration, revise
+   the visual mechanism before calling the animation finished. Intentional reading
+   holds and the resolved final frame are useful exceptions.
+4. Render when requested with `npx retiam render src/scenes/YourScene.ts`.
+   Return artifact paths and the verification performed. State missing checks
+   explicitly when the environment cannot run them.
+
+Snapshot requires headless Chrome with WebGPU; video rendering also requires
+FFmpeg. `--json` returns one JSON result on stdout and diagnostics on stderr.
+Snapshot runs the specified scene directly and advances its timeline at a fixed
+step. Wall-clock time, unseeded randomness, live network data, and external media
+can still make user scenes nondeterministic; use local assets and seeded data
+when repeatable output matters.

package/agent/skill/examples/AreaLesson.ts

@@ -0,0 +1,48 @@
+import { Scene, CameraModel, CENTER, Rect, Text, Tex, CustomAnimation, Rate, hex } from 'retiam';
+import { createExampleLesson, prepareLesson, resolveStyle, styleGeometry, drawGeometry, type LessonPlan, type PreparedSpeech } from 'retiam/explainer';
+// lesson-config:start
+const plan: LessonPlan = createExampleLesson();
+const prepared: PreparedSpeech | undefined = undefined;
+// lesson-config:end
+/** One construction evolves through a prediction, growth, decomposition and notation. */
+export default class AreaLesson extends Scene {
+    async run() {
+        const style = resolveStyle(plan.style);
+        this.clearColor(hex(style.background));
+        this.camera.model = CameraModel.ORTHOGRAPHIC;
+        this.camera.position.set([0, 0, 20]);
+        this.camera.orthoScale = 10;
+        const side = 2, factor = 2, total = factor * factor;
+        const cells = Array.from({ length: total }, (_, i) => {
+            const cell = styleGeometry(new Rect(side, side, { position: [-1 + (i % factor) * side, -0.8 + Math.floor(i / factor) * side, 0] }), style, i ? 'secondary' : 'primary', true);
+            if (i)
+                cell.setOpacity(0);
+            else
+                cell.setT2(0);
+            this.add(cell);
+            return cell;
+        });
+        const outline = styleGeometry(new Rect(side * factor, side * factor, { position: [0, 0.2, 0], opacity: 0 }), style, 'ink');
+        this.add(outline);
+        const question = new Text('What happens when we double a side?', { font: style.font, fontSize: 0.48, anchor: CENTER, fill: hex(style.ink), position: [0, 3.5, 0] });
+        const sideLabel = new Tex('s', { fontSize: 0.45, anchor: CENTER, fill: hex(style.primary), position: [-1, -2.25, 0] });
+        const doubled = new Tex(`${factor}s`, { fontSize: 0.45, anchor: CENTER, fill: hex(style.secondary), position: [0, -2.25, 0], opacity: 0 });
+        const equation = new Tex(`A=(${factor}s)^2=${total}s^2`, { fontSize: 0.65, anchor: CENTER, fill: hex(style.ink), position: [0, -3.25, 0], opacity: 0 });
+        const takeaway = new Text('Two growing directions, multiplied together.', { font: style.font, fontSize: 0.33, anchor: CENTER, fill: hex(style.muted), position: [0, -4.15, 0], opacity: 0 });
+        this.add(question, sideLabel, doubled, equation, takeaway);
+        const numbers = cells.map((cell, i) => { const p = cell.transform.position; const number = new Tex(String(i + 1), { fontSize: 0.48, anchor: CENTER, fill: hex(style.ink), position: [p.x, p.y, 0], opacity: 0 }); this.add(number); return number; });
+        const lesson = await prepareLesson(this, plan, { prepared });
+        await lesson.run({
+            predict: b => [drawGeometry(cells[0], style, b.cue('show'), Math.min(1800, b.durationMs - 500))],
+            grow: b => [new CustomAnimation(t => {
+                    outline.setOpacity(t);
+                    outline.transform.setScale([0.5 + 0.5 * t, 0.5 + 0.5 * t, 1]);
+                    outline.transform.position.set([-1 + t, -0.8 + t, 0]);
+                    sideLabel.setOpacity(1 - t);
+                    doubled.setOpacity(t);
+                }, { delay: b.cue('expand'), duration: Math.min(2200, b.durationMs - 600), rate_func: Rate.smooth() })],
+            count: b => [new CustomAnimation(t => numbers[0].setOpacity(t), { delay: b.cue('reveal'), duration: 600 }), ...cells.slice(1).map((cell, i) => new CustomAnimation(t => { cell.setOpacity(t); numbers[i + 1].setOpacity(t); }, { delay: b.cue('reveal') + 300 + i * 850, duration: 800, rate_func: Rate.smooth() }))],
+            connect: b => [new CustomAnimation(t => { question.setOpacity(1 - t); equation.setOpacity(t); }, { delay: b.cue('equation'), duration: 1100 }), new CustomAnimation(t => takeaway.setOpacity(t), { delay: b.cue('equation') + 1600, duration: 900 })],
+        });
+    }
+}

package/agent/skill/examples/ExplainMotion.ts

@@ -0,0 +1,32 @@
+import {
+  CENTER, Circle, Concurrent, Create, CustomAnimation, Line, Scene, Text, Write, hex,
+} from 'retiam';
+
+/** A 7-second example: set the stage, move a marker, then hold the result. */
+export default class ExplainMotion extends Scene {
+  async run() {
+    this.clearColor(hex('#080C14'));
+    this.camera.position.set([0, 0, 14]);
+
+    const title = new Text('Position changes over time', {
+      fontSize: 0.6, anchor: CENTER, fill: hex('#F8FAFC'), position: [0, 2, 0],
+    });
+    const path = new Line([[-3, 0, 0], [3, 0, 0]], {
+      stroke: hex('#64748B'), strokeWidth: 0.04,
+    });
+    const marker = new Circle(0.18, { fill: hex('#38BDF8'), position: [-3, 0, 0] });
+    this.add(title, path, marker);
+    // Include the whole path so the moving marker stays within the shot.
+    this.camera.frame([title, path, marker], { padding: 0.3 });
+
+    await this.play(new Concurrent([
+      new Write(title, { duration: 1000 }),
+      new Create(path, { duration: 1000 }),
+    ]));
+    await this.wait(500);
+    await this.play(new CustomAnimation(progress => {
+      marker.transform.position.set([-3 + 6 * progress, 0, 0]);
+    }, { duration: 3500 }));
+    await this.wait(2000);
+  }
+}

package/agent/skill/examples/NarratedMotion.ts

@@ -0,0 +1,42 @@
+import {
+  CENTER, Circle, Concurrent, Create, CustomAnimation, Line, Scene, Text, Write, hex,
+} from 'retiam';
+import { Speak, Subtitles } from 'retiam/tts';
+
+export default class NarratedMotion extends Scene {
+  async run() {
+    this.clearColor(hex('#080C14'));
+    this.camera.position.set([0, 0, 14]);
+    const title = new Text('Follow the motion', {
+      fontSize: 0.6, anchor: CENTER, fill: hex('#F8FAFC'), position: [0, 2, 0],
+    });
+    const path = new Line([[-3, 0, 0], [3, 0, 0]], {
+      stroke: hex('#64748B'), strokeWidth: 0.04,
+    });
+    const marker = new Circle(0.18, { fill: hex('#38BDF8'), position: [-3, 0, 0] });
+    const subtitles = new Subtitles({ fontSize: 0.3, bottomOffset: -1.7, maxWidth: 8 });
+    this.add(title, path, marker, subtitles);
+    this.camera.frame([[-4.5, -2.5, 0], [4.5, 3, 0]], { padding: 0.25 });
+
+    const narration = new Speak('Watch the marker move from left to right.', {
+      voice: 'en-US-JennyNeural', speed: 1, subtitles, entity: marker,
+      pulseAmplitude: 0, volume: 1,
+    });
+    // Headless tools must wait for synthesis, not a promise requiring timeline steps.
+    const loading = narration.prepareAudio();
+    this.composer?.pendingTasks.push(loading);
+    await loading;
+
+    await this.play(new Concurrent([
+      new Write(title, { duration: 800 }),
+      new Create(path, { duration: 800 }),
+    ], { duration: 800 }));
+    await this.play(new Concurrent([
+      narration,
+      new CustomAnimation(progress => {
+        marker.transform.position.set([-3 + 6 * progress, 0, 0]);
+      }, { duration: narration.duration }),
+    ], { duration: narration.duration }));
+    await this.wait(800);
+  }
+}

package/agent/skill/examples/SecantToTangent.ts

@@ -0,0 +1,142 @@
+import {
+  CameraModel, CENTER, Circle, Concurrent, Create, CustomAnimation, FadeIn, FadeOut,
+  Line, Rate, Scene, SDFText, Tex, Text, TransformMatchingTex, Write, hex,
+} from 'retiam';
+
+/** 21.5 seconds of one evolving construction; see references/quality.md for its beat map. */
+export default class SecantToTangent extends Scene {
+  async run() {
+    const cyan = hex('#5DD9F5');
+    const amber = hex('#FFCB77');
+    const ink = hex('#EDF5FF');
+    const muted = hex('#8497AD');
+    this.clearColor(hex('#07101B'));
+    this.camera.model = CameraModel.ORTHOGRAPHIC;
+    this.camera.position.set([0, 0, 20]);
+    this.camera.orthoScale = 10.8;
+
+    const point = (x: number, y = x * x): [number, number, number] => [-2 + x * 1.2, -3 + y * 1.2, 0];
+    const curve = new Line(Array.from({ length: 181 }, (_, i) => point(-1.8 + i * 4 / 180)), {
+      stroke: cyan, strokeWidth: 0.055,
+    });
+    const axes = new Line([point(-2, 0), point(2.45, 0)], { stroke: muted, strokeWidth: 0.018 });
+    const vertical = new Line([point(0, -0.3), point(0, 4.9)], { stroke: muted, strokeWidth: 0.018 });
+    this.add(axes, vertical, curve);
+    for (const y of [1, 2, 3, 4]) {
+      const guide = new Line([point(-1.8, y), point(2.3, y)], {
+        stroke: hex('#26364A'), strokeWidth: 0.009, opacity: 0.55,
+      });
+      this.add(guide);
+    }
+
+    const question = new Text('How can one point have a slope?', {
+      fontSize: 0.56, anchor: CENTER, fill: ink, position: [0, 4.15, 0],
+    });
+    const functionLabel = new Tex('f(x)=x^2', { fontSize: 0.48, anchor: CENTER, fill: cyan, position: [-4.1, 2.2, 0] });
+    const p = new Circle(0.095, { fill: cyan });
+    const q = new Circle(0.095, { fill: amber });
+    const pLabel = new Text('P', { fontSize: 0.28, anchor: CENTER, fill: cyan });
+    const qLabel = new Text('Q', { fontSize: 0.28, anchor: CENTER, fill: amber });
+    const secant = new Line([point(0), point(1)], { stroke: amber, strokeWidth: 0.036 });
+    const dx = new Line([point(0), point(1)], { stroke: amber, strokeWidth: 0.025 });
+    const dy = new Line([point(0), point(1)], { stroke: cyan, strokeWidth: 0.025 });
+    const dxLabel = new Tex('\\Delta x=h', { fontSize: 0.27, anchor: CENTER, fill: amber });
+    const dyLabel = new Tex('\\Delta y', { fontSize: 0.27, anchor: CENTER, fill: cyan });
+    const formula = new Tex('m(a,h)=2a+h', {
+      fontSize: 0.65, anchor: CENTER, fill: ink, position: [4, 1.5, 0],
+    });
+    const readoutTitle = new SDFText('gap between the points', {
+      fontSize: 0.27, anchor: CENTER, fill: muted, position: [4, -0.35, 0],
+    });
+    const readout = new SDFText('1.40', {
+      fontSize: 0.85, anchor: CENTER, fill: amber, position: [4, -1.2, 0],
+    });
+    this.add(question, functionLabel, secant, dx, dy, p, q, pLabel, qLabel, dxLabel, dyLabel, formula, readoutTitle, readout);
+
+    const a = 0.6;
+    const setGap = (h: number) => {
+      const b = a + h;
+      const from = point(a);
+      const to = point(b);
+      const slope = a + b;
+      p.transform.position.set(from);
+      q.transform.position.set(to);
+      pLabel.transform.position.set([from[0] - 0.26, from[1] + 0.23, 0]);
+      qLabel.transform.position.set([to[0] + 0.25, to[1] + 0.23, 0]);
+      secant.setVertices([point(a - 0.55, a * a - slope * 0.55), point(b + 0.32, b * b + slope * 0.32)]);
+      dx.setVertices([from, point(b, a * a)]);
+      dy.setVertices([point(b, a * a), to]);
+      dxLabel.transform.position.set([(from[0] + to[0]) / 2, from[1] - 0.36, 0]);
+      dyLabel.transform.position.set([to[0] + 0.42, (from[1] + to[1]) / 2, 0]);
+      readout.setText(h.toFixed(2));
+    };
+    setGap(1.4);
+
+    // 0–3.1 s: establish the curve, then reveal the two-point measurement.
+    for (const entity of [p, q, pLabel, qLabel, secant, dx, dy, dxLabel, dyLabel, formula, readoutTitle, readout]) entity.setOpacity(0);
+    await this.play(new Concurrent([
+      new Create(curve), new Write(question), new Write(functionLabel),
+    ], { duration: 1400 }));
+    for (const entity of [p, q, pLabel, qLabel, secant, dx, dy, dxLabel, dyLabel, formula, readoutTitle, readout]) entity.setOpacity(1);
+    await this.play(new Concurrent([
+      new FadeIn(p), new FadeIn(q), new FadeIn(pLabel), new FadeIn(qLabel),
+      new Create(secant), new Create(dx), new Create(dy), new Write(formula),
+      new FadeIn(dxLabel), new FadeIn(dyLabel), new FadeIn(readoutTitle), new FadeIn(readout),
+    ], { duration: 900 }));
+    await this.wait(800);
+
+    // 3.1–6.3 s: the point follows the function; the line and its legs follow the data.
+    await this.play(new CustomAnimation(t => setGap(1.4 - 0.85 * t), {
+      duration: 3200, rate_func: Rate.smooth(),
+    }));
+
+    // 6.3–11.1 s: remove spent context, move closer, then expose the limit.
+    await this.play(new Concurrent([
+      new FadeOut(question), new FadeOut(functionLabel), new FadeOut(pLabel), new FadeOut(qLabel),
+      new CustomAnimation(t => {
+        this.camera.position.set([-0.55 * t, -0.55 * t, 20]);
+        this.camera.orthoScale = 10.8 - 1.6 * t;
+      }),
+    ], { duration: 800 }));
+    await this.play(new CustomAnimation(t => {
+      const h = 0.55 - 0.515 * t;
+      setGap(h);
+      for (const entity of [dx, dy, dxLabel, dyLabel]) entity.setOpacity(1 - t);
+      q.setOpacity(1 - 0.8 * t);
+    }, { duration: 3400, rate_func: Rate.smooth() }));
+    await this.wait(600);
+
+    // 11.1–13.1 s: preserve the construction while the secant resolves to a tangent.
+    const tangent = new Line([point(a - 0.78, a * a - 2 * a * 0.78), point(a + 0.78, a * a + 2 * a * 0.78)], {
+      stroke: amber, strokeWidth: 0.065,
+    });
+    this.add(tangent);
+    const derivative = new Tex("f'(a)=2a", { fontSize: 0.85, anchor: CENTER, fill: amber });
+    derivative.transform.position.set(formula.transform.position);
+    await this.play(new Concurrent([
+      new Create(tangent), new FadeOut(secant), new FadeOut(q),
+      new FadeOut(readoutTitle), new FadeOut(readout),
+      new CustomAnimation(t => setGap(0.035 * (1 - t))),
+      new TransformMatchingTex(formula, derivative, { morphUnmatched: false, keyMap: { m: 'f' } }),
+    ], { duration: 1200 }));
+    this.remove(secant, q, pLabel, qLabel, dx, dy, dxLabel, dyLabel, functionLabel);
+    readoutTitle.setText('instantaneous slope').setOpacity(1);
+    readout.setText('1.20').setOpacity(1);
+    await this.play(new Concurrent([new FadeIn(readoutTitle), new FadeIn(readout)], { duration: 800 }));
+
+    const setTangent = (x: number) => {
+      p.transform.position.set(point(x));
+      tangent.setVertices([point(x - 0.78, x * x - 2 * x * 0.78), point(x + 0.78, x * x + 2 * x * 0.78)]);
+      readout.setText((2 * x).toFixed(2));
+    };
+    // 13.1–19.5 s: generalize across negative, zero, and positive slopes.
+    await this.play(new CustomAnimation(t => {
+      setTangent(0.6 - 1.75 * t);
+      this.camera.position.set([-0.55 * (1 - t), -0.55 * (1 - t), 20]);
+      this.camera.orthoScale = 9.2 + 1.6 * t;
+    }, { duration: 2300, rate_func: Rate.smooth() }));
+    await this.play(new CustomAnimation(t => setTangent(-1.15 + 2.65 * t), { duration: 3200, rate_func: Rate.smooth() }));
+    await this.play(new CustomAnimation(t => setTangent(1.5 - 0.4 * t), { duration: 900, rate_func: Rate.smooth() }));
+    await this.wait(2000);
+  }
+}

package/agent/skill/references/api.md

@@ -0,0 +1,109 @@
+# Retiam API notes
+
+These notes accompany the package release. The installed `.d.ts` files are the
+authority for exact signatures. `npx retiam context --json` locates them without
+requiring an engine source checkout or online documentation.
+
+## Scene lifecycle and timing
+
+```ts
+import { Scene, Circle, Create, hex } from 'retiam';
+
+export default class MyScene extends Scene {
+  async run() {
+    this.clearColor(hex('#080C14'));
+    this.camera.position.set([0, 0, 14]);
+    const circle = new Circle(1, { stroke: hex('#38BDF8'), strokeWidth: 0.05 });
+    this.add(circle);
+    this.camera.frame(circle, { padding: 0.25 });
+    await this.play(new Create(circle, { duration: 1000 }));
+    await this.wait(800);
+  }
+}
+```
+
+`run()` schedules the animation. `scene.start(canvas)` mounts a standalone scene;
+Studio and the snapshot CLI mount it themselves. Do not bootstrap another canvas
+inside `run()`. Scene files default-export the class, not an instance.
+
+`this.play(...)`, `this.wait(...)`, animation `duration`, and render CLI `-d` are
+in **milliseconds**. Snapshot `--times` is in **seconds**.
+For parallel animations, await `this.play(new Concurrent([animationA, animationB]))`.
+Use `Sequential` or chained awaits for successive actions. `CustomAnimation`
+accepts `(progress) => { ... }` and `{ duration, rate_func }`; progress is eased
+from 0 to 1. `scene.always` callbacks receive `(time, dt)`, both in milliseconds.
+Prefer absolute values derived from progress over accumulating per-frame offsets.
+
+## Geometry, style, and layout
+
+- Coordinates, radii, `strokeWidth`, and `fontSize` use world units, not CSS pixels.
+  The visible range depends on projection, camera, and aspect ratio. Explicitly
+  set text size and frame the content; text defaults may be much larger than a
+  small mathematical scene needs.
+- `new Circle(radius, options)`, `new Rect(width, height, options)`,
+  `new Line([[x1, y1, z1], [x2, y2, z2]], options)`.
+- `new Dot(position?, { radius, ...options })`; the first argument is a position.
+- `new Text('Label', { fontSize: 0.5, anchor: CENTER, fill: hex('#F8FAFC') })`
+  creates vector text. `SDFText` is another text implementation. Use `Tex` for
+  LaTeX and inspect `TexOptions` for mathematical text configuration.
+- Entity options use **`strokeWidth`** and **`zIndex`**, not `stroke_width` or
+  `z_index`. Use `fill`, `stroke`, and `opacity` for 2D paint. Use material and
+  shading APIs for 3D objects.
+- Prefer automatic scene ordering for flat diagrams. Explicit `zIndex` values
+  affect GPU depth; inspect the output rather than assuming CSS-style layer
+  numbers will work with every projection.
+- Position with `entity.transform.position.set([x, y, z])`; use `nextTo`, `alignTo`,
+  `VBox`, or `HBox` for related objects. Add objects or their parent group to the
+  scene. Layout alone is not scene registration.
+- `this.camera.frame(entityOrArray, { padding: 0.25 })` fits content to the viewport.
+  Frame the planned motion envelope as well as the starting geometry. Camera
+  projection uses `camera.model` and `CameraModel`, not `projectionType` strings.
+- The root package exports `Box`, not `Box3D`. Check constructor options for mesh
+  resolution; do not assume signatures from Three.js or Python Manim.
+
+## Import map
+
+| Import | Use |
+| --- | --- |
+| `retiam` | Scene, entities, text, cameras, animation, layout, materials, math |
+| `retiam/shapes` | Additional procedural 2D/3D shapes |
+| `retiam/highlights` | Circumscribe, Underline, and attention animations |
+| `retiam/charts` | Chart entities |
+| `retiam/graphs` | Graph and automata entities |
+| `retiam/physics` | Physics worlds, bodies, joints, backend adapters |
+| `retiam/tts` | Speech, narration, and subtitles |
+| `retiam/rough` | Rough styling utilities |
+| `retiam/vite` | Node-side Vite middleware for Retiam TTS; import in Vite config |
+
+Follow the installed sublibrary's index declarations to its options and examples
+before using it. Optional features can have their own asset or environment needs.
+
+For narration, follow [tts.md](tts.md) and the checked
+[NarratedMotion.ts](../examples/NarratedMotion.ts) example. The native TTS route is
+already enabled by new project Vite configurations. Existing projects can add
+`msEdgeTTSPlugin` from `retiam/vite`; see the TTS guide for the configuration and
+failure checks. Never import the Vite plugin in browser scene code.
+
+## Commands and failure interpretation
+
+```bash
+npm run check
+npx retiam lint src/scenes/YourScene.ts --json
+npx retiam snapshot src/scenes/YourScene.ts --times 0,1.5,3 --json
+npx retiam render src/scenes/YourScene.ts -w 1920 -h 1080 -f 60 -o outputs/video
+```
+
+Lint exits nonzero on errors; warnings need review even when `valid` is true.
+It checks common AST patterns, not complete program semantics. A successful
+snapshot contains the requested scene path and absolute PNG paths. Failure
+returns `status: "error"` and a nonzero exit code. Keep stdout as JSON when
+automating; stderr may contain browser or build diagnostics.
+
+Render `-o` is an **output directory**, not a video filename. Check `--help` for
+supported options; snapshot produces PNGs and has no `--format` option. Render
+reads `config.js`, with `retiam.config.js` taking precedence; CLI flags override
+file settings. Snapshot dimensions are controlled by its own width/height flags.
+
+Studio discovers default-exported scenes under `src/scenes/`; reload after adding
+a file. The standalone page at `/` follows `src/main.ts` imports. Snapshot mounts
+the named scene directly, independent of either entrypoint.