@aura3d/engine 1.1.0 → 1.3.0

package/dist/engine/agent-api/product-viewer-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"product-viewer-runtime.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/product-viewer-runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,OAAO,EACP,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACrB,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CAC7C;AAED,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAClD,MAAM,MAAM,qBAAqB,GAAG,YAAY,CAAC;AACjD,MAAM,MAAM,wBAAwB,GAAG,UAAU,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;AAE1E,eAAO,MAAM,OAAO;;;sBAWyh6S,CAAC;;;;;;CAX5g6S,CAAC;AAEnC,eAAO,MAAM,SAAS;oCACC,YAAY,CAAC,OAAO,CAAC,YAAW,oBAAoB,KAAQ,qBAAqB;CAG9F,CAAC;AAEX,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,OAAO,GAAE,oBAAyB,GAAG,qBAAqB,CAErH"}
+{"version":3,"file":"product-viewer-runtime.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/agent-api/product-viewer-runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,OAAO,EACP,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACrB,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CAC7C;AAED,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAClD,MAAM,MAAM,qBAAqB,GAAG,YAAY,CAAC;AACjD,MAAM,MAAM,wBAAwB,GAAG,UAAU,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;AAE1E,eAAO,MAAM,OAAO;;;sBAWsv6S,CAAC;;;;;;CAXzu6S,CAAC;AAEnC,eAAO,MAAM,SAAS;oCACC,YAAY,CAAC,OAAO,CAAC,YAAW,oBAAoB,KAAQ,qBAAqB;CAG9F,CAAC;AAEX,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,OAAO,GAAE,oBAAyB,GAAG,qBAAqB,CAErH"}

package/dist/engine/animation-studio/animation-episode-validator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * animation-episode-validator.ts — the scene-coherence gate.
+ *
+ * Proves a generated/edited EpisodeDocument is VALID + COHERENT before it is rendered or
+ * shipped: characters + props stay on the walkable set, cameras frame near the action,
+ * every scheduled clip exists on the asset, every shot is covered, plus the structural
+ * checks from `validateEpisodeDocumentShape`.
+ *
+ * HONEST CAVEAT (design doc): this proves a scene is *valid/coherent*, NOT that it is
+ * *well-directed or watchable*. "Good" needs the human-review rubric — automation can
+ * only keep a scene from being broken, not make it good.
+ */
+import { type EpisodeDocument } from "./episode-document";
+export interface EpisodeDocumentValidation {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+}
+export interface ValidateOptions {
+    /** GLB clip lists per character, so scheduled clips can be checked to exist. */
+    readonly availableClipsByCharacter?: Record<string, readonly string[]>;
+}
+export declare function validateEpisodeDocument(doc: EpisodeDocument, opts?: ValidateOptions): EpisodeDocumentValidation;
+//# sourceMappingURL=animation-episode-validator.d.ts.map

package/dist/engine/animation-studio/animation-episode-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-episode-validator.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/animation-studio/animation-episode-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAgC,KAAK,eAAe,EAAa,MAAM,oBAAoB,CAAC;AAEnG,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CACxE;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,GAAE,eAAoB,GAAG,yBAAyB,CAgEnH"}

package/dist/engine/animation-studio/animation-episode-validator.js

@@ -0,0 +1,74 @@
+/**
+ * animation-episode-validator.ts — the scene-coherence gate.
+ *
+ * Proves a generated/edited EpisodeDocument is VALID + COHERENT before it is rendered or
+ * shipped: characters + props stay on the walkable set, cameras frame near the action,
+ * every scheduled clip exists on the asset, every shot is covered, plus the structural
+ * checks from `validateEpisodeDocumentShape`.
+ *
+ * HONEST CAVEAT (design doc): this proves a scene is *valid/coherent*, NOT that it is
+ * *well-directed or watchable*. "Good" needs the human-review rubric — automation can
+ * only keep a scene from being broken, not make it good.
+ */
+import { validateEpisodeDocumentShape } from "./episode-document.js";
+export function validateEpisodeDocument(doc, opts = {}) {
+    const shape = validateEpisodeDocumentShape(doc);
+    const errors = [...shape.errors];
+    const warnings = [];
+    const bounds = doc.walkableBounds;
+    const margin = 0.6;
+    const inBounds = (p) => !bounds ||
+        (p[0] >= bounds.min[0] - margin &&
+            p[0] <= bounds.max[0] + margin &&
+            p[2] >= bounds.min[2] - margin &&
+            p[2] <= bounds.max[2] + margin);
+    // 1. Blocking stays on the walkable set (hard error — a character off the set is broken).
+    for (const b of doc.blocking) {
+        for (const s of b.shots) {
+            for (const w of s.waypoints) {
+                if (!inBounds(w.position)) {
+                    errors.push(`${b.characterId} blocking in ${s.shotId} leaves the walkable set at [${w.position.map((n) => n.toFixed(2)).join(",")}]`);
+                }
+            }
+        }
+    }
+    // 2. Props on the walkable set (warning — off-set props are ugly, not fatal).
+    for (const d of doc.setDressing) {
+        if (!inBounds(d.position))
+            warnings.push(`prop ${d.propId} placed off the walkable set`);
+    }
+    // 3. Camera frames near the action.
+    for (const shot of doc.shots) {
+        if (!inBounds([shot.cameraSubject[0], 0, shot.cameraSubject[2]])) {
+            warnings.push(`shot ${shot.shotId} camera subject is far from the walkable set`);
+        }
+    }
+    // 4. Every scheduled clip exists on the asset (fuzzy match; warn + note fallback).
+    if (opts.availableClipsByCharacter) {
+        for (const b of doc.blocking) {
+            const clips = opts.availableClipsByCharacter[b.characterId];
+            if (!clips || clips.length === 0)
+                continue;
+            for (const s of b.shots) {
+                const want = s.clip.toLowerCase();
+                const has = clips.some((c) => {
+                    const lc = c.toLowerCase();
+                    return lc === want || lc.includes(want) || want.includes(lc);
+                });
+                if (!has)
+                    warnings.push(`${b.characterId} clip "${s.clip}" in ${s.shotId} not found; falls back to "${clips[0]}"`);
+            }
+        }
+    }
+    // 5. Every character has blocking for every shot.
+    for (const c of doc.assets.characters) {
+        const cb = doc.blocking.find((b) => b.characterId === c.id);
+        for (const shot of doc.shots) {
+            if (!cb?.shots.find((s) => s.shotId === shot.shotId)) {
+                warnings.push(`${c.id} has no blocking for ${shot.shotId} (will hold a fallback mark)`);
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+//# sourceMappingURL=animation-episode-validator.js.map

package/dist/engine/animation-studio/animation-episode-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation-episode-validator.js","sourceRoot":"","sources":["../../../../../packages/engine/src/animation-studio/animation-episode-validator.ts"],"names":[],"mappings":"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"}

package/dist/engine/animation-studio/director-heuristics.d.ts

@@ -0,0 +1,73 @@
+/**
+ * director-heuristics.ts — the DETERMINISTIC tier of the Director.
+ *
+ * Given a scene's shots + dialogue + cast + walkable bounds + available props, it
+ * GENERATES the blocking / camera / performance / set-dressing / world-state of an
+ * EpisodeDocument — the parts that used to be hand-authored constants. No LLM, no
+ * randomness beyond a seeded scatter, fully deterministic.
+ *
+ * HONEST SCOPE (see docs/animation-studio/quality-and-limitations.md): these rules target
+ * the constrained genre the MVP targets — **1–2 characters, dialogue-driven, single
+ * walkable set**. They reliably stage conversation: characters at conversation distance
+ * facing each other, establishing→two-shot→close-up framing, the speaker emphasised in
+ * close-ups, props scattered over the walkable area, world-state ramped across the act.
+ * They do NOT handle action, crowds, complex choreography, or non-dialogue beats — those
+ * are the LLM director's job (and remain unproven). The output is always a *valid*
+ * document; "valid" is not "well-directed" — that needs the human rubric (the watchability gate).
+ */
+import type { CharacterBlocking, PropPlacement, ShotSpec, Vec3 } from "./episode-document";
+export interface DirectorCharacter {
+    readonly id: string;
+    /** Where the character starts the scene (drives a walk-in on the opening shot). */
+    readonly entersFrom?: "left" | "right" | "none";
+}
+export interface DirectorShot {
+    readonly shotId: string;
+    readonly startTime: number;
+    readonly endTime: number;
+}
+export interface DirectorDialogueLine {
+    readonly lineId: string;
+    readonly speakerId: string;
+    readonly startTime: number;
+    readonly endTime: number;
+}
+export interface DirectorPropSpec {
+    readonly propId: string;
+    readonly count: number;
+    readonly scaleRange: readonly [number, number];
+    readonly feetOffset: number;
+}
+export interface DirectorSceneInput {
+    readonly duration: number;
+    readonly characters: readonly DirectorCharacter[];
+    readonly shots: readonly DirectorShot[];
+    readonly dialogue: readonly DirectorDialogueLine[];
+    /** Walkable area characters and props stay inside. */
+    readonly walkableBounds: {
+        readonly min: Vec3;
+        readonly max: Vec3;
+    };
+    readonly props: readonly DirectorPropSpec[];
+    /** Default clips on the cast (resolved fuzzily by the player). */
+    readonly clips?: {
+        readonly idle?: string;
+        readonly walk?: string;
+        readonly gesture?: string;
+    };
+}
+export interface DirectedScene {
+    readonly shots: readonly ShotSpec[];
+    readonly blocking: readonly CharacterBlocking[];
+    readonly setDressing: readonly PropPlacement[];
+    readonly worldState: {
+        readonly glowSpanSeconds: number;
+    };
+}
+/**
+ * Stage a 1–2 character dialogue scene. Characters take base marks at conversation
+ * distance facing each other; cameras cycle establishing → two-shot → close-up (the
+ * close-up frames the active speaker); props scatter over the walkable bounds.
+ */
+export declare function directScene(sceneId: string, input: DirectorSceneInput): DirectedScene;
+//# sourceMappingURL=director-heuristics.d.ts.map

package/dist/engine/animation-studio/director-heuristics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-heuristics.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/animation-studio/director-heuristics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAgB,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEzG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CACjD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,sDAAsD;IACtD,QAAQ,CAAC,cAAc,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAA;KAAE,CAAC;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,kEAAkE;IAClE,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChG;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D;AAmCD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,aAAa,CA4FrF"}

package/dist/engine/animation-studio/director-heuristics.js

@@ -0,0 +1,149 @@
+/**
+ * director-heuristics.ts — the DETERMINISTIC tier of the Director.
+ *
+ * Given a scene's shots + dialogue + cast + walkable bounds + available props, it
+ * GENERATES the blocking / camera / performance / set-dressing / world-state of an
+ * EpisodeDocument — the parts that used to be hand-authored constants. No LLM, no
+ * randomness beyond a seeded scatter, fully deterministic.
+ *
+ * HONEST SCOPE (see docs/animation-studio/quality-and-limitations.md): these rules target
+ * the constrained genre the MVP targets — **1–2 characters, dialogue-driven, single
+ * walkable set**. They reliably stage conversation: characters at conversation distance
+ * facing each other, establishing→two-shot→close-up framing, the speaker emphasised in
+ * close-ups, props scattered over the walkable area, world-state ramped across the act.
+ * They do NOT handle action, crowds, complex choreography, or non-dialogue beats — those
+ * are the LLM director's job (and remain unproven). The output is always a *valid*
+ * document; "valid" is not "well-directed" — that needs the human rubric (the watchability gate).
+ */
+// --- small deterministic helpers ---
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function hashSeed(s) {
+    let h = 2166136261;
+    for (let i = 0; i < s.length; i += 1)
+        h = Math.imul(h ^ s.charCodeAt(i), 16777619);
+    return h >>> 0;
+}
+function yawFacing(from, to) {
+    return Math.atan2(to[0] - from[0], to[2] - from[2]);
+}
+/** The character who speaks most during a shot (the shot's focus), or the first cast member. */
+function shotSpeaker(input, shot) {
+    const tally = new Map();
+    for (const line of input.dialogue) {
+        const overlap = Math.min(line.endTime, shot.endTime) - Math.max(line.startTime, shot.startTime);
+        if (overlap > 0)
+            tally.set(line.speakerId, (tally.get(line.speakerId) ?? 0) + overlap);
+    }
+    let best = input.characters[0]?.id ?? "";
+    let bestV = -1;
+    for (const [id, v] of tally)
+        if (v > bestV) {
+            bestV = v;
+            best = id;
+        }
+    return best;
+}
+/**
+ * Stage a 1–2 character dialogue scene. Characters take base marks at conversation
+ * distance facing each other; cameras cycle establishing → two-shot → close-up (the
+ * close-up frames the active speaker); props scatter over the walkable bounds.
+ */
+export function directScene(sceneId, input) {
+    const cast = input.characters;
+    const { min, max } = input.walkableBounds;
+    const cx = (min[0] + max[0]) / 2;
+    const cz = (min[2] + max[2]) / 2;
+    const idle = input.clips?.idle ?? "idle";
+    const walk = input.clips?.walk ?? "walk";
+    // Base marks: spread the cast left→right across ~40% of the walkable width, facing center.
+    const span = (max[0] - min[0]) * 0.4;
+    const baseMark = (i) => {
+        if (cast.length === 1)
+            return [cx, 0, cz];
+        const t = cast.length === 1 ? 0.5 : i / (cast.length - 1);
+        return [cx + (t - 0.5) * span, 0, cz];
+    };
+    const center = [cx, 0, cz];
+    const presets = ["establishing", "two-shot", "close-up"];
+    const shots = input.shots.map((shot, index) => {
+        const speaker = shotSpeaker(input, shot);
+        const presetId = presets[Math.min(index, presets.length - 1)];
+        let cameraSubject;
+        if (presetId === "close-up") {
+            const i = Math.max(0, cast.findIndex((c) => c.id === speaker));
+            const m = baseMark(i < 0 ? 0 : i);
+            cameraSubject = [m[0], -0.2, m[2]]; // head-ish focus on the speaker
+        }
+        else {
+            cameraSubject = [cx, 0.75, cz]; // frame the conversation midpoint
+        }
+        return { shotId: shot.shotId, presetId, startTime: shot.startTime, endTime: shot.endTime, cameraSubject };
+    });
+    const blocking = cast.map((character, i) => {
+        const mark = baseMark(i);
+        const faceCenter = yawFacing(mark, center);
+        const beats = input.shots.map((shot, index) => {
+            // Opening shot: optional walk-in from the side the character enters from.
+            if (index === 0 && character.entersFrom && character.entersFrom !== "none") {
+                const offX = character.entersFrom === "left" ? min[0] - 0.5 : max[0] + 0.5;
+                const enterDur = Math.min(shot.endTime - shot.startTime, (input.duration) * 0.12);
+                return {
+                    shotId: shot.shotId,
+                    clip: walk,
+                    waypoints: [
+                        { time: shot.startTime, position: [offX, 0, mark[2]], yaw: yawFacing([offX, 0, mark[2]], mark) },
+                        { time: shot.startTime + enterDur, position: mark, yaw: faceCenter }
+                    ]
+                };
+            }
+            // Middle beats TRAVERSE: walk from the mark toward the shared focus across the shot
+            // (a real 2-waypoint path, so characters move instead of looping in place).
+            const isMiddle = index > 0 && index < input.shots.length - 1;
+            if (isMiddle) {
+                const converge = [mark[0] + (cx - mark[0]) * (index === 1 ? 0.45 : 0.25), 0, mark[2] + 0.25];
+                return {
+                    shotId: shot.shotId,
+                    clip: walk,
+                    sweeping: i === 0,
+                    waypoints: [
+                        { time: shot.startTime, position: mark, yaw: yawFacing(mark, converge) },
+                        { time: shot.endTime, position: converge, yaw: yawFacing(converge, center) }
+                    ]
+                };
+            }
+            // First/last beats: hold the mark, but FACE the active speaker (look-at / reaction),
+            // and the speaker GESTURES in the close-up — breadth beyond a static two-shot.
+            const speaker = shotSpeaker(input, input.shots[index]);
+            const spkIdx = Math.max(0, cast.findIndex((c) => c.id === speaker));
+            const spkMark = baseMark(spkIdx);
+            const facing = i === spkIdx ? faceCenter : yawFacing(mark, spkMark);
+            const isClose = index === input.shots.length - 1;
+            const gesture = input.clips?.gesture ?? "wave";
+            const beatClip = isClose && i === spkIdx ? gesture : idle;
+            return { shotId: shot.shotId, clip: beatClip, waypoints: [{ time: shot.startTime, position: mark, yaw: facing }] };
+        });
+        return { characterId: character.id, shots: beats };
+    });
+    // Deterministic prop scatter over the walkable bounds (seeded by scene id).
+    const rand = mulberry32(hashSeed(sceneId));
+    const setDressing = [];
+    for (const prop of input.props) {
+        for (let n = 0; n < prop.count; n += 1) {
+            const x = min[0] + rand() * (max[0] - min[0]);
+            const z = min[2] + rand() * (max[2] - min[2]);
+            const scale = prop.scaleRange[0] + rand() * (prop.scaleRange[1] - prop.scaleRange[0]);
+            setDressing.push({ propId: prop.propId, position: [x, 0, z], scale, feetOffset: prop.feetOffset });
+        }
+    }
+    return { shots, blocking, setDressing, worldState: { glowSpanSeconds: input.duration } };
+}
+//# sourceMappingURL=director-heuristics.js.map

package/dist/engine/animation-studio/director-heuristics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-heuristics.js","sourceRoot":"","sources":["../../../../../packages/engine/src/animation-studio/director-heuristics.ts"],"names":[],"mappings":"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"}

package/dist/engine/animation-studio/episode-document.d.ts

@@ -0,0 +1,214 @@
+/**
+ * episode-document.ts — the Episode Document schema + deterministic sampling.
+ *
+ * This is the data-driven contract that makes the animation renderer GENERIC: every
+ * scene-specific decision that used to be a constant in `render-live-route.ts`
+ * (blocking marks, camera framing, the clip per shot, prop layout, the dim→sparkle
+ * world-state, even the primitive set + lights) is now DATA in an EpisodeDocument.
+ * The generic player (`scene-player.ts`) reads this document and renders it; it
+ * contains no scene-specific constants. A Director GENERATES documents
+ * from a prompt; the same player plays them.
+ *
+ * Placement note: this lives in the template for fast iteration (no engine dist
+ * rebuild). The design doc promotes these contracts into
+ * `packages/engine/src/animation-studio/*` once stable.
+ */
+import type { CameraPresetId } from "../agent-api/CameraPresetLibrary";
+export type Vec3 = readonly [number, number, number];
+export type Vec4 = readonly [number, number, number, number];
+/** Provenance for a catalog-resolved asset (CC-BY attribution + source + hash). */
+export interface AssetProvenance {
+    readonly attribution?: string;
+    readonly license?: string;
+    readonly sourceUrl?: string;
+    readonly hash?: string;
+}
+export interface CharacterAsset extends AssetProvenance {
+    readonly id: string;
+    readonly url: string;
+    /** Uniform scale applied to the loaded GLB so it reads at the intended height. */
+    readonly scale: number;
+    /** Fallback clip name (resolved against the GLB's real clip list by the player). */
+    readonly defaultClip: string;
+    /** Morph-target index that drives mouth-open, or -1 when the GLB has no face morph. */
+    readonly mouthMorphIndex?: number;
+}
+export interface PropAsset extends AssetProvenance {
+    readonly id: string;
+    readonly url: string;
+}
+export type GeometryKind = "cube" | "sphere" | "cylinder";
+/** Dim→full emissive strengths a glow piece ramps between as the world-state advances. */
+export interface GlowSpec {
+    readonly dim: number;
+    readonly full: number;
+}
+export interface SetPiece {
+    readonly id: string;
+    readonly geometry: GeometryKind;
+    readonly position: Vec3;
+    readonly scale: Vec3;
+    readonly baseColor: Vec4;
+    readonly metallic?: number;
+    readonly roughness?: number;
+    readonly emissiveColor?: Vec3;
+    readonly emissiveStrength?: number;
+    /** When present, the world-state drives emissiveStrength from dim→full over the act. */
+    readonly glow?: GlowSpec;
+    /** Optional z-roll (radians) for tilted props like the broom handle. */
+    readonly roll?: number;
+    readonly includeInAutoFrame?: boolean;
+}
+export interface LightSpec {
+    readonly id: string;
+    readonly kind: "point";
+    readonly color: Vec3;
+    readonly position: Vec3;
+    readonly intensity: number;
+    readonly range: number;
+}
+export interface EnvironmentSpec {
+    readonly color: Vec3;
+    readonly intensity: number;
+    readonly proceduralMap: {
+        readonly skyColor: Vec3;
+        readonly horizonColor: Vec3;
+        readonly groundColor: Vec3;
+        readonly specularColor: Vec3;
+        readonly intensity: number;
+        readonly specularIntensity: number;
+    };
+}
+export interface SetSpec {
+    readonly clearColor: Vec4;
+    /** Scale on the studio softbox rig (the directional key/fill/rim come from `lights`). */
+    readonly studioLightingScale: number;
+    readonly environment: EnvironmentSpec;
+    readonly pieces: readonly SetPiece[];
+    readonly lights: readonly LightSpec[];
+    /**
+     * High-fidelity rendering toggles (#12). Default OFF so the standard render
+     * path stays stable; the Director or scene tools can opt a document in.
+     *  - inShaderCel: non-glow set pieces use the engine's REAL AnimationToonMaterial
+     *    (GPU-side banded N·L + Fresnel rim), in addition to the CPU toon post-pass.
+     *  - realShadows: enable the studio rig's shadow maps (cast/receive) instead of only
+     *    the cheap contact-shadow blobs.
+     */
+    readonly inShaderCel?: boolean;
+    readonly realShadows?: boolean;
+}
+export interface ShotSpec {
+    readonly shotId: string;
+    readonly presetId: CameraPresetId;
+    /** Episode-time window (seconds) this shot is on screen. */
+    readonly startTime: number;
+    readonly endTime: number;
+    /** World point the camera frames for this shot (auto-framed or directed). */
+    readonly cameraSubject: Vec3;
+}
+export interface BlockingWaypoint {
+    /** Absolute episode time (seconds). */
+    readonly time: number;
+    readonly position: Vec3;
+    readonly yaw: number;
+}
+export interface ShotBlocking {
+    readonly shotId: string;
+    /** Clip to play during this beat (resolved against the GLB's real clips by the player). */
+    readonly clip: string;
+    readonly sweeping?: boolean;
+    /** 1+ waypoints; the player lerps position/yaw across them within the shot window. */
+    readonly waypoints: readonly BlockingWaypoint[];
+}
+export interface CharacterBlocking {
+    readonly characterId: string;
+    readonly shots: readonly ShotBlocking[];
+}
+export interface PropPlacement {
+    readonly propId: string;
+    readonly position: Vec3;
+    readonly scale: number;
+    /** |minY| of the prop geometry (pre-scale) so it sits on the ground (y=0). */
+    readonly feetOffset: number;
+}
+export interface WorldStateTrack {
+    /** Seconds over which glow pieces ramp dim→full (the dim→sparkle world-state). */
+    readonly glowSpanSeconds: number;
+}
+export interface DialogueLine {
+    readonly lineId: string;
+    readonly speakerId: string;
+    readonly text: string;
+    readonly startTime: number;
+    readonly endTime: number;
+}
+export interface DialogueTrack {
+    readonly language: string;
+    readonly lines: readonly DialogueLine[];
+}
+export interface EpisodeDocument {
+    readonly id: string;
+    readonly duration: number;
+    readonly assets: {
+        readonly characters: readonly CharacterAsset[];
+        readonly props: readonly PropAsset[];
+    };
+    readonly set: SetSpec;
+    /** Area characters + props must stay within (used by the Director + coherence gate). */
+    readonly walkableBounds?: {
+        readonly min: Vec3;
+        readonly max: Vec3;
+    };
+    readonly shots: readonly ShotSpec[];
+    readonly blocking: readonly CharacterBlocking[];
+    readonly setDressing: readonly PropPlacement[];
+    readonly worldState: WorldStateTrack;
+    /** The script + captions + lip-sync source — the AuraVoice contract for THIS scene. */
+    readonly dialogue?: DialogueTrack;
+}
+/** The shot on screen at episode time `t`. */
+export declare function shotAtTime(doc: EpisodeDocument, t: number): ShotSpec;
+export interface SampledBlocking {
+    readonly position: Vec3;
+    readonly yaw: number;
+    readonly clip: string;
+    readonly sweeping: boolean;
+    /** True when the character is translating between distinct waypoints (→ walk clip). */
+    readonly moving: boolean;
+}
+/**
+ * Sample a character's blocking at episode time `t`: find the active shot's blocking,
+ * then lerp position/yaw across its waypoints by time. Single-waypoint beats hold a
+ * static mark (the original staging behaviour); multi-waypoint beats traverse.
+ */
+export declare function sampleBlocking(doc: EpisodeDocument, characterId: string, t: number, fallback: {
+    readonly position: Vec3;
+    readonly yaw: number;
+    readonly clip: string;
+}): SampledBlocking;
+/** Eased dim→sparkle world-state at episode time `t` (0 = dim, 1 = full twinkle). */
+export declare function sampleWorldStateGlow(doc: EpisodeDocument, t: number): number;
+/** The active caption at episode time `t`, from the document's dialogue. */
+export declare function sampleCaption(doc: EpisodeDocument, t: number): {
+    text: string;
+    speakerId: string;
+    lineId: string;
+};
+/**
+ * Lip-sync mouth-openness for `speakerId` at `t`, derived deterministically from the
+ * document's dialogue (a speaking mouth pulse). Drives the GLB mouth morph for rigs that
+ * have one; 0 when the speaker isn't talking. (The full per-phoneme viseme track is
+ * AuraVoice's; this is the engine-side fallback driver.)
+ */
+export declare function sampleVisemeOpenness(doc: EpisodeDocument, t: number, speakerId: string): {
+    mouthOpenness: number;
+    visemeId: string;
+};
+export interface DocumentValidationResult {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+}
+export declare function validateEpisodeDocumentShape(doc: EpisodeDocument): DocumentValidationResult;
+/** One-line-per-fact summary of a document (for CLI output / agent grounding). */
+export declare function summarizeDocument(doc: EpisodeDocument): string;
+//# sourceMappingURL=episode-document.d.ts.map

package/dist/engine/animation-studio/episode-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episode-document.d.ts","sourceRoot":"","sources":["../../../../../packages/engine/src/animation-studio/episode-document.ts"],"names":[],"mappings":"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"}