create-aura3d 1.3.0 → 1.3.2

package/templates/animation-studio/studio/src/state/backend.ts

@@ -0,0 +1,108 @@
+/**
+ * Dev backend client — the LOCAL studio control surface.
+ *
+ * Talks to the Vite dev-server middleware (see `vite.config.ts`) which shells the
+ * REAL agent-native Scene-Tool CLI (`animation-scene.ts`) and the render pipeline
+ * against the shared working document. This is dev-only: the user's own coding agent
+ * remains the director. Command mode runs raw scene-tool commands here; Prompt mode
+ * only displays the intent (the agent drives the actual commands).
+ */
+
+export interface SceneResult {
+  ok: boolean;
+  /** Raw CLI stdout/stderr — "ok …" on commit, "REJECTED — …" on validator rejection. */
+  output: string;
+  rejected?: boolean;
+  ms?: number;
+  /** Short content hash of the resulting working document ("doc @ xxx"). */
+  hash?: string;
+  error?: string;
+}
+
+export interface RenderResult {
+  ok: boolean;
+  output?: string;
+  ms?: number;
+  /** Served under /preview/* by the dev middleware (null if not produced). */
+  video?: string | null;
+  poster?: string | null;
+  hash?: string;
+  error?: string;
+}
+
+/** Fetch the REAL working document (or { exists:false } when none has been authored). */
+export async function fetchDocument(): Promise<Record<string, unknown>> {
+  const r = await fetch("/api/document");
+  return (await r.json()) as Record<string, unknown>;
+}
+
+/** Fetch the REAL command/result history (array; [] when none). */
+export async function fetchHistory(): Promise<unknown[]> {
+  const r = await fetch("/api/history");
+  const v = (await r.json()) as unknown;
+  return Array.isArray(v) ? v : [];
+}
+
+/** Fetch the EXISTING render (if any) so the Stage shows it on load without re-rendering. */
+export async function fetchExistingRender(): Promise<{ video?: string | null; poster?: string | null; exists?: boolean }> {
+  try {
+    const r = await fetch("/api/render");
+    return (await r.json()) as { video?: string | null; poster?: string | null; exists?: boolean };
+  } catch {
+    return { exists: false };
+  }
+}
+
+/** Run one validated Scene-Tool command against the working document. */
+export async function runSceneCommand(command: string): Promise<SceneResult> {
+  try {
+    const r = await fetch("/api/scene", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ command })
+    });
+    return (await r.json()) as SceneResult;
+  } catch (e) {
+    return { ok: false, output: e instanceof Error ? e.message : String(e), rejected: true };
+  }
+}
+
+/** Render the working document (low-fi by default) via the real pipeline. */
+export async function runRender(opts: { lowFi?: boolean; range?: string } = {}): Promise<RenderResult> {
+  try {
+    const r = await fetch("/api/render", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(opts)
+    });
+    return (await r.json()) as RenderResult;
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+/** Parse a committed/rejected CLI result into a card header verb + args + diff lines. */
+export function parseCliResult(command: string, res: SceneResult): {
+  diffs: { op: "+" | "~" | "!"; k: "add" | "mod" | "del"; t: string }[];
+} {
+  if (!res.ok || res.rejected) {
+    // The CLI prints "REJECTED — edit would break the scene:\n - reason\n - reason".
+    const lines = res.output
+      .split("\n")
+      .map((l) => l.replace(/^\s*-\s*/, "").trim())
+      .filter((l) => l && !/^REJECTED/i.test(l) && !/break the scene/i.test(l));
+    const reasons = lines.length ? lines : [res.output.replace(/^REJECTED[^:]*:?/i, "").trim() || "rejected"];
+    return { diffs: reasons.map((r) => ({ op: "!", k: "del", t: escapeHtml(r) })) };
+  }
+  // On success the CLI prints "ok" / "cast … ← …" / "set → …" plus warnings.
+  const lines = res.output.split("\n").map((l) => l.trim()).filter(Boolean);
+  const diffs = lines
+    .filter((l) => l !== "ok")
+    .map((l) => ({ op: "~" as const, k: "mod" as const, t: escapeHtml(l) }));
+  if (!diffs.length) diffs.push({ op: "~", k: "mod", t: escapeHtml(command) });
+  return { diffs };
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/templates/animation-studio/studio/src/state/fidelity.ts

@@ -0,0 +1,110 @@
+/**
+ * fidelity.ts (UI) — PRD Phase M7: honest quality tiering, surfaced in the studio shell.
+ *
+ * Mirrors the render-side rules in
+ * `packages/create-aura3d/templates/animation-studio/src/fidelity.ts` so the badge the
+ * user sees in the Outliner / scene header ALWAYS agrees with the resolver's fidelity
+ * report. A grade-C character/scene is "previz" — the UI labels it as such and never
+ * presents it as finished.
+ *
+ * The UI cannot import across the package boundary, so the (small, pure) grading rules
+ * are duplicated here; a unit test pins the two copies to identical verdicts.
+ */
+
+export type FidelityGrade = "A" | "B" | "C";
+export type FidelityRigGrade = "A" | "B" | "C" | "D";
+export type FidelityProvenance = "curated" | "user-uploaded" | "catalog-resolved" | "authored-fallback";
+export type FidelityMotionSource =
+  | "mocap"
+  | "extracted"
+  | "embedded"
+  | "procedural"
+  | "idle"
+  | "talk"
+  | "fallback"
+  | "unknown";
+
+export interface CharacterFidelityInput {
+  id: string;
+  rigGrade?: FidelityRigGrade;
+  provenance: FidelityProvenance;
+  motionSource?: FidelityMotionSource;
+  shading?: "cel" | "pbr" | "none";
+  shadows?: boolean;
+}
+
+export interface CharacterFidelity {
+  id: string;
+  grade: FidelityGrade;
+  previz: boolean;
+  reason: string;
+}
+
+export interface SceneFidelity {
+  grade: FidelityGrade;
+  previz: boolean;
+  characters: CharacterFidelity[];
+  reason: string;
+}
+
+const MASCOT_PROVENANCE = new Set<FidelityProvenance>(["authored-fallback"]);
+const REAL_MOTION = new Set<FidelityMotionSource>(["mocap", "extracted", "embedded"]);
+const CURATED_PROVENANCE = new Set<FidelityProvenance>(["curated", "user-uploaded"]);
+
+export function gradeCharacterFidelity(input: CharacterFidelityInput): CharacterFidelity {
+  const rig = input.rigGrade ?? "D";
+  const provenance = input.provenance;
+  const motion = input.motionSource ?? "unknown";
+  const shading = input.shading ?? "none";
+  const shadows = input.shadows ?? false;
+
+  if (MASCOT_PROVENANCE.has(provenance) || rig === "C" || rig === "D") {
+    const why = MASCOT_PROVENANCE.has(provenance)
+      ? "authored placeholder / mascot rig"
+      : `sparse rig (grade ${rig}) — crude retarget only`;
+    return { id: input.id, grade: "C", previz: true, reason: `previz: ${why}` };
+  }
+
+  const realMotion = REAL_MOTION.has(motion);
+  const shaded = shading === "cel" || shading === "pbr";
+  if (CURATED_PROVENANCE.has(provenance) && rig === "A" && realMotion && shaded && shadows) {
+    return {
+      id: input.id,
+      grade: "A",
+      previz: false,
+      reason: "curated/uploaded grade-A rig with real motion, shading and shadows"
+    };
+  }
+
+  const missing: string[] = [];
+  if (!realMotion) missing.push("procedural motion");
+  if (!shaded) missing.push("no cel/PBR shading");
+  if (!shadows) missing.push("shadows off");
+  if (!CURATED_PROVENANCE.has(provenance)) missing.push("catalog rig");
+  return {
+    id: input.id,
+    grade: "B",
+    previz: false,
+    reason: missing.length ? `catalog-grade: ${missing.join(", ")}` : "graded-ok rig"
+  };
+}
+
+export function gradeSceneFidelity(characters: CharacterFidelityInput[]): SceneFidelity {
+  const graded = characters.map(gradeCharacterFidelity);
+  if (graded.length === 0) {
+    return { grade: "C", previz: true, characters: graded, reason: "previz: no characters in the scene" };
+  }
+  const order: Record<FidelityGrade, number> = { A: 3, B: 2, C: 1 };
+  let worst: FidelityGrade = "A";
+  for (const g of graded) if (order[g.grade] < order[worst]) worst = g.grade;
+  const previz = worst === "C";
+  const reason = previz
+    ? `previz: lowest character grade is C (${graded.filter((g) => g.grade === "C").map((g) => g.id).join(", ")})`
+    : `scene grade ${worst} (floor of ${graded.length} character grade(s))`;
+  return { grade: worst, previz, characters: graded, reason };
+}
+
+/** Human one-word tier label for the badge. C is "Previz" — never "finished". */
+export function fidelityLabel(grade: FidelityGrade): string {
+  return grade === "C" ? "Previz" : `Grade ${grade}`;
+}

package/templates/animation-studio/studio/src/state/mapDocument.ts

@@ -0,0 +1,419 @@
+/**
+ * Maps the REAL runtime EpisodeDocument (as persisted to
+ * `dist/scene/working.document.json` by the Scene-Tool CLI) into the UI model
+ * (`types.ts`) that drives the Outliner / Stage / Inspector / Timeline.
+ *
+ * There is NO seed / fixture: the only source of truth is the live document
+ * fetched from `GET /api/document`. When no document exists the UI shows an
+ * empty state (see `App.tsx`).
+ */
+
+import type {
+  Beat,
+  CastMember,
+  CastSource,
+  EpisodeDocument,
+  PropEntity,
+  SetEntity,
+  Shot,
+  TimelineSpan,
+  Turn
+} from "./types";
+import {
+  gradeSceneFidelity,
+  type CharacterFidelityInput,
+  type FidelityProvenance,
+  type FidelityRigGrade
+} from "./fidelity";
+
+/* ---- Runtime EpisodeDocument shape (subset the UI reads) ---- */
+
+export interface RuntimeShot {
+  shotId: string;
+  presetId: string;
+  startTime: number;
+  endTime: number;
+}
+
+export interface RuntimeDialogueLine {
+  lineId: string;
+  speakerId: string;
+  startTime: number;
+  endTime: number;
+  text: string;
+}
+
+export interface RuntimeCharacter {
+  id: string;
+  role?: string;
+  /** Catalog/source URL when this cast member was resolved from the federated catalog. */
+  sourceUrl?: string;
+  /** Source title / attribution string the resolver persisted (catalog or upload). */
+  attribution?: string;
+  /** License string for catalog/uploaded assets. */
+  license?: string;
+  /**
+   * Explicit provenance class when the resolver/CLI recorded one. When absent it is INFERRED:
+   * a sourceUrl/attribution → catalog-resolved; otherwise authored-fallback.
+   */
+  source?: "authored-fallback" | "catalog-resolved" | "user-uploaded" | "curated";
+  /** M7 — rig grade (A/B/C/D) the resolver recorded, when available; drives the fidelity tier. */
+  rigGrade?: "A" | "B" | "C" | "D";
+  /** M7 — dominant motion source the render played (mocap/extracted/procedural…), when recorded. */
+  motionSource?: string;
+}
+
+export interface RuntimeShotBlocking {
+  shotId: string;
+  /** Standard performance clip the director assigned this beat (idle/talk/gesture/point/nod/walk/run/react). */
+  clip: string;
+}
+
+export interface RuntimeCharacterBlocking {
+  characterId: string;
+  shots?: RuntimeShotBlocking[];
+}
+
+export interface RuntimeProp {
+  id: string;
+  url?: string;
+  attribution?: string;
+}
+
+export interface RuntimeDocument {
+  id?: string;
+  duration?: number;
+  assets?: {
+    characters?: RuntimeCharacter[];
+    props?: RuntimeProp[];
+  };
+  set?: unknown;
+  shots?: RuntimeShot[];
+  blocking?: RuntimeCharacterBlocking[];
+  dialogue?: { language?: string; lines?: RuntimeDialogueLine[] };
+}
+
+export interface DocumentResponse {
+  exists?: boolean;
+}
+
+/** Human label for a shot from its camera preset id. */
+const PRESET_LABELS: Record<string, string> = {
+  establishing: "Establishing",
+  "two-shot": "Two-shot",
+  medium: "Medium",
+  "close-up": "Close-up",
+  closeup: "Close-up",
+  wide: "Wide",
+  reverse: "Reverse",
+  "over-shoulder": "Over-shoulder"
+};
+
+export function presetLabel(presetId: string): string {
+  return PRESET_LABELS[presetId] ?? cap(presetId.replace(/[-_]/g, " "));
+}
+
+/* ---- Director acting-intent inference (F1) — mirrors src/director/director-heuristics.ts ----
+ * Used only as a FALLBACK when a beat has no real director clip in `blocking`, so the per-beat
+ * preview always shows a meaningful speaking/listener intent rather than a blank. The canonical
+ * rules live in the template's director; these match them for a question/emphasis/disagreement/
+ * movement line. */
+const NEGATIONS = ["no", "not", "never", "wrong", "don't", "won't", "can't", "stop", "refuse", "disagree"];
+const MOVEMENTS = ["walk", "go", "going", "run", "running", "cross", "leave", "come", "coming", "move", "follow"];
+
+function lineWords(text: string): Set<string> {
+  return new Set(text.toLowerCase().replace(/[^a-z' ]+/g, " ").split(/\s+/).filter(Boolean));
+}
+
+export function inferSpeakingIntent(text: string): string {
+  const w = lineWords(text);
+  if (MOVEMENTS.some((m) => w.has(m))) return /\b(run|running)\b/i.test(text) ? "run" : "walk";
+  if (text.includes("!") || /\b[A-Z]{2,}\b/.test(text)) return "gesture";
+  return "talk";
+}
+
+export function inferListenerIntent(text: string): string {
+  const w = lineWords(text);
+  if (NEGATIONS.some((n) => w.has(n)) || text.includes("!") || /\b[A-Z]{2,}\b/.test(text)) return "react";
+  if (text.includes("?")) return "nod";
+  return "nod";
+}
+
+/** A small, stable accent palette assigned per id (shots + cast). */
+const PALETTE = ["#6b6bff", "#5b6bd6", "#4f8fd6", "#7b6bd6", "#ff8a5b", "#4fc2ff", "#9a7bff", "#2dd4a7", "#ffb020"];
+
+/** Deterministic accent for an id — stable across reloads. */
+export function stableAccent(id: string): string {
+  let h = 0;
+  for (let i = 0; i < id.length; i++) h = (h * 31 + id.charCodeAt(i)) >>> 0;
+  return PALETTE[h % PALETTE.length]!;
+}
+
+function cap(s: string): string {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+/**
+ * Phase E3 — classify a cast member's PROVENANCE so the Outliner can label it honestly and never
+ * sell an authored fallback as catalog evidence. Trust an explicit `source` the resolver recorded;
+ * otherwise INFER: a catalog/source URL or attribution → catalog-resolved; a local-file upload
+ * marker → user-uploaded; nothing → authored-fallback (built-in/placeholder).
+ */
+export function castProvenance(c: RuntimeCharacter): { source: CastSource; sourceLabel: string } {
+  // An explicit `source` the resolver/CLI recorded always wins. (A `curated` cast member is a
+  // catalog-class asset for the Outliner badge; its higher fidelity tier is computed separately.)
+  if (c.source === "user-uploaded" || /^file:/i.test(c.sourceUrl ?? "")) {
+    return { source: "user-uploaded", sourceLabel: c.attribution ?? "user-uploaded GLB" };
+  }
+  if (c.source === "curated") {
+    return { source: "catalog-resolved", sourceLabel: c.attribution ?? "curated cast" };
+  }
+  if (c.source === "catalog-resolved" || c.sourceUrl || c.attribution) {
+    return { source: "catalog-resolved", sourceLabel: c.attribution ?? "catalog" };
+  }
+  return { source: "authored-fallback", sourceLabel: "authored fallback" };
+}
+
+/**
+ * M7 — map a runtime character to the fidelity-grading provenance enum. Unlike the Outliner
+ * badge (`castProvenance`) this keeps `curated` distinct, because a curated/uploaded rig is the
+ * only provenance that can reach grade A.
+ */
+export function fidelityProvenance(c: RuntimeCharacter): FidelityProvenance {
+  if (c.source === "curated") return "curated";
+  if (c.source === "user-uploaded" || /^file:/i.test(c.sourceUrl ?? "")) return "user-uploaded";
+  if (c.source === "catalog-resolved" || c.sourceUrl || c.attribution) return "catalog-resolved";
+  return "authored-fallback";
+}
+
+function asRigGrade(value: unknown): FidelityRigGrade | undefined {
+  return value === "A" || value === "B" || value === "C" || value === "D" ? value : undefined;
+}
+
+/**
+ * Performance clips that read as a GESTURE / REACTION window on the timeline (Phase C2)
+ * — as opposed to ambient holds (idle/talk) or locomotion (walk/run). The director emits
+ * these per beat (gesture on emphasis, react/nod when another character speaks), so a
+ * blocking beat carrying one of these is a real gesture window the timeline surfaces.
+ */
+const GESTURE_CLIPS = new Set<string>(["gesture", "point", "nod", "react", "wave"]);
+
+/** Human label for a gesture clip id. */
+function gestureLabel(clip: string): string {
+  return cap(clip);
+}
+
+/** True when the document response is a real authored document. */
+export function documentExists(doc: RuntimeDocument & DocumentResponse): boolean {
+  return doc.exists !== false && Array.isArray(doc.shots);
+}
+
+/** Map the runtime EpisodeDocument → the UI model. */
+export function mapDocument(doc: RuntimeDocument): EpisodeDocument {
+  const rShots = doc.shots ?? [];
+  const rLines = doc.dialogue?.lines ?? [];
+  const rChars = doc.assets?.characters ?? [];
+  const rProps = doc.assets?.props ?? [];
+  const rBlocking = doc.blocking ?? [];
+  const DUR = doc.duration ?? (rShots.length ? Math.max(...rShots.map((s) => s.endTime)) : 0);
+
+  // Lines spoken in a shot's [start,end) window — drives `who` + the inspector beat count.
+  const speakersInWindow = (start: number, end: number): string[] => {
+    const ids = new Set<string>();
+    for (const l of rLines) {
+      if (l.startTime < end && l.endTime > start) ids.add(l.speakerId);
+    }
+    return [...ids];
+  };
+
+  const shots: Shot[] = rShots.map((s) => ({
+    id: s.shotId,
+    name: presetLabel(s.presetId),
+    start: s.startTime,
+    dur: s.endTime - s.startTime,
+    cam: s.presetId,
+    // A real render thumbnail if one has been produced; else undefined (empty stage).
+    frame: "",
+    who: speakersInWindow(s.startTime, s.endTime),
+    color: stableAccent(s.shotId)
+  }));
+
+  const linesPerSpeaker = (id: string): number => rLines.filter((l) => l.speakerId === id).length;
+
+  // M7 — fidelity inputs per character (rig grade + provenance + motion source). Shading/shadows
+  // are scene-render properties the document does not carry, so the document-only UI grades on the
+  // rig+provenance+motion axes; the render-side `fidelity.ts` adds shading/shadows when present.
+  const fidelityInputs: CharacterFidelityInput[] = rChars.map((c) => ({
+    id: c.id,
+    rigGrade: asRigGrade(c.rigGrade),
+    provenance: fidelityProvenance(c),
+    motionSource: (c.motionSource as CharacterFidelityInput["motionSource"]) ?? undefined
+  }));
+  const sceneFidelity = gradeSceneFidelity(fidelityInputs);
+  const fidelityById = new Map(sceneFidelity.characters.map((f) => [f.id, f]));
+
+  const cast: CastMember[] = rChars.map((c) => {
+    const { source, sourceLabel } = castProvenance(c);
+    return {
+      id: c.id,
+      name: cap(c.id),
+      kind: c.role || "character",
+      color: stableAccent(c.id),
+      glyph: (c.id[0] ?? "?").toUpperCase(),
+      lines: linesPerSpeaker(c.id),
+      source,
+      sourceLabel,
+      fidelity:
+        fidelityById.get(c.id) ?? { id: c.id, grade: "C", previz: true, reason: "previz: ungraded" }
+    };
+  });
+
+  // The set is a single spec on the document — surface it as one outliner entry.
+  const sets: SetEntity[] = doc.set
+    ? [{ id: doc.id ? doc.id + "-set" : "set", name: doc.id ? cap(doc.id) + " — Set" : "Set", meta: "scene set", icon: "globe" }]
+    : [];
+
+  const props: PropEntity[] = dedupeProps(rProps);
+
+  const shotForTime = (t: number): string => {
+    const hit = rShots.find((s) => t >= s.startTime && t < s.endTime);
+    return hit ? hit.shotId : rShots.length ? rShots[0]!.shotId : "";
+  };
+  const presetForShot = (shotId: string): string => {
+    const hit = rShots.find((s) => s.shotId === shotId);
+    return hit ? presetLabel(hit.presetId) : "";
+  };
+  // The director's REAL per-beat clip for a character in a shot (from blocking), if present.
+  const clipFor = (characterId: string, shotId: string): string | undefined => {
+    const cb = (doc.blocking ?? []).find((b) => b.characterId === characterId);
+    return cb?.shots?.find((s) => s.shotId === shotId)?.clip;
+  };
+  const castIds = rChars.map((c) => c.id);
+
+  const beats: Beat[] = rLines.map((l) => {
+    const shot = shotForTime(l.startTime);
+    // The addressed party: the other cast member (1:1), else the first non-speaker.
+    const listener = castIds.find((id) => id !== l.speakerId) ?? "";
+    // Prefer the director's real assigned clip; else infer the intent from the line text (F1 rules).
+    const speakingIntent = clipFor(l.speakerId, shot) ?? inferSpeakingIntent(l.text);
+    const listenerIntent = listener ? clipFor(listener, shot) ?? inferListenerIntent(l.text) : "idle";
+    return {
+      id: l.lineId,
+      shot,
+      who: l.speakerId,
+      start: l.startTime,
+      dur: l.endTime - l.startTime,
+      text: l.text,
+      listener,
+      speakingIntent,
+      listenerIntent,
+      camera: presetForShot(shot)
+    };
+  });
+
+  // Camera track: one clip per shot, derived from its preset. FX: empty (no fx in the doc).
+  const camera: TimelineSpan[] = rShots.map((s) => ({
+    id: "cam-" + s.shotId,
+    start: s.startTime,
+    dur: s.endTime - s.startTime,
+    text: presetLabel(s.presetId),
+    color: "#2dd4a7"
+  }));
+  const fx: TimelineSpan[] = [];
+
+  // Gesture track (Phase C2): every blocking beat whose director-assigned clip is a
+  // gesture/reaction (gesture/point/nod/react/wave) becomes a window spanning the shot it
+  // plays in. These are REAL beat timings — the same shot windows the player schedules the
+  // clip over — so the timeline shows where gestures/reactions land, alongside speech.
+  const shotWindow = (shotId: string): RuntimeShot | undefined => rShots.find((s) => s.shotId === shotId);
+  const gestures: TimelineSpan[] = [];
+  for (const cb of rBlocking) {
+    for (const sb of cb.shots ?? []) {
+      if (!GESTURE_CLIPS.has(sb.clip)) continue;
+      const win = shotWindow(sb.shotId);
+      if (!win) continue;
+      gestures.push({
+        id: "gst-" + cb.characterId + "-" + sb.shotId,
+        start: win.startTime,
+        dur: win.endTime - win.startTime,
+        text: cap(cb.characterId) + " · " + gestureLabel(sb.clip),
+        color: stableAccent(cb.characterId)
+      });
+    }
+  }
+
+  return {
+    title: doc.id ? cap(doc.id) : "Untitled scene",
+    cast,
+    sets,
+    props,
+    shots,
+    beats,
+    camera,
+    gestures,
+    fx,
+    DUR,
+    fidelity: sceneFidelity
+  };
+}
+
+/** Collapse duplicate prop ids (e.g. set dressing instances) into one outliner row with a count. */
+function dedupeProps(rProps: RuntimeProp[]): PropEntity[] {
+  const counts = new Map<string, { p: RuntimeProp; n: number }>();
+  for (const p of rProps) {
+    const e = counts.get(p.id);
+    if (e) e.n += 1;
+    else counts.set(p.id, { p, n: 1 });
+  }
+  return [...counts.values()].map(({ p, n }) => ({
+    id: p.id,
+    name: cap(p.id),
+    meta: n > 1 ? n + "×" : "prop",
+    icon: "cube"
+  }));
+}
+
+/* ---- History → Director Console transcript ---- */
+
+interface RuntimeHistoryEntry {
+  verb?: string;
+  command?: string;
+  args?: string;
+  ok?: boolean;
+  rejected?: boolean;
+  output?: string;
+  diff?: string[];
+  ms?: number;
+  time?: number;
+  hash?: string;
+}
+
+/** Map the REAL command history into Director Console command cards. Empty array → no cards. */
+export function mapHistory(hist: unknown): Turn[] {
+  if (!Array.isArray(hist)) return [];
+  return (hist as RuntimeHistoryEntry[]).map((h, i) => {
+    const raw = (h.command ?? h.verb ?? "").trim();
+    const verb = h.verb ?? raw.split(/\s+/)[0] ?? "—";
+    const args = h.args ?? (raw.startsWith(verb) ? raw.slice(verb.length).trim() : raw);
+    const bad = h.rejected === true || h.ok === false;
+    const diffLines = Array.isArray(h.diff) ? h.diff : h.output ? h.output.split("\n").filter(Boolean) : [];
+    return {
+      type: "cmd",
+      id: "h" + i,
+      verb,
+      args,
+      state: bad ? "bad" : "ok",
+      diffs: diffLines.map((t) => ({
+        op: bad ? "!" : "~",
+        k: bad ? "del" : "mod",
+        t: escapeHtml(t)
+      })),
+      dur: h.ms != null ? (h.ms / 1000).toFixed(1) + "s" : "—",
+      hash: h.hash ?? "—"
+    };
+  });
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/templates/animation-studio/studio/src/state/sceneTool.ts

@@ -0,0 +1,55 @@
+/**
+ * Scene-Tool command metadata + parser (autocomplete only).
+ *
+ * The Director Console no longer simulates mutations locally — Command mode runs the
+ * REAL agent-native Scene-Tool CLI (`animation-scene.ts`) via `POST /api/scene` (see
+ * `state/backend.ts`), and each committed/rejected card reflects the actual validated
+ * result + the resulting working-document revision. This module now only provides:
+ *   - `VERBS`  — the command catalog for the composer autocomplete + suggestion chips.
+ *   - `parse`  — a light tokenizer used to detect the verb (e.g. `render`) and flags.
+ * No mock mutations remain in the production path.
+ */
+
+export interface VerbSpec {
+  verb: string;
+  tail: string;
+  desc: string;
+}
+
+export const VERBS: VerbSpec[] = [
+  { verb: "set", tail: "<name> --hdr <mood>", desc: "Define / re-light the active set" },
+  { verb: "cast add", tail: "<name>", desc: "Cast a character into the scene" },
+  { verb: "cast remove", tail: "<name>", desc: "Remove a character" },
+  { verb: "shot add", tail: "--after <id>", desc: "Block a new shot" },
+  { verb: "shot retime", tail: "--id <id> --duration <s>", desc: "Change a shot's duration" },
+  { verb: "cam", tail: "<wide|medium|close|orbit>", desc: "Set the active shot camera" },
+  { verb: "light add", tail: "--type rim", desc: "Add a light to the set" },
+  { verb: "fx add", tail: "<name>", desc: "Add an effect to the timeline" },
+  { verb: "render", tail: "[--shot <id>]", desc: "Render a low-fi preview" }
+];
+
+export interface ParsedCommand {
+  verb: string;
+  rest: string[];
+  flags: Record<string, string>;
+  raw: string;
+  isCommand: boolean;
+}
+
+/** Naive command parser — extracts the (possibly two-word) verb + flags for routing. */
+export function parse(raw: string): ParsedCommand {
+  const t = raw.trim();
+  const flags: Record<string, string> = {};
+  const fre = /--([a-z]+)\s+("[^"]*"|\S+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = fre.exec(t))) flags[m[1]] = m[2].replace(/^"|"$/g, "");
+  const head = t.replace(/--[a-z]+\s+("[^"]*"|\S+)/g, "").trim();
+  const toks = head.split(/\s+/).filter(Boolean);
+  let verb = toks[0] || "";
+  let rest = toks.slice(1);
+  if (["cast", "shot", "light", "fx"].includes(verb) && rest[0]) {
+    verb += " " + rest[0];
+    rest = rest.slice(1);
+  }
+  return { verb, rest, flags, raw: t, isCommand: VERBS.some((v) => t.startsWith(v.verb.split(" ")[0])) };
+}