create-aura3d 1.3.2 → 1.3.3

package/templates/animation-studio/studio/src/App.tsx

@@ -75,6 +75,12 @@ export function App() {
   const [continuing, setContinuing] = useState(false);
   const consoleApi = useRef<ConsoleApi>({});
   const raf = useRef(0);
+  // The live render-progress EventSource — kept in a ref so unmount can close it
+  // (otherwise an in-flight render leaves a perpetually reconnecting connection).
+  const progressEs = useRef<EventSource | null>(null);
+  // The active toast-dismiss timer — cleared before each new toast so an earlier
+  // timer can't dismiss a later toast early.
+  const toastTimer = useRef(0);
 
   const DUR = data.DUR;
   const hasShots = data.shots.length > 0;
@@ -83,8 +89,10 @@ export function App() {
     : null;
 
   // Hydrate the UI from the REAL working document (and command history). Called on mount and
-  // after each /api/scene or /api/render so the panels reflect the live document.
-  const hydrate = useCallback(async () => {
+  // after each /api/scene or /api/render so the panels reflect the live document. Returns the
+  // freshly mapped document (or null when none exists) so callers can read post-hydrate values
+  // (e.g. the NEW scene's duration) without waiting for a React state round-trip.
+  const hydrate = useCallback(async (): Promise<EpisodeDocument | null> => {
     const [doc, hist, render] = await Promise.all([fetchDocument(), fetchHistory(), fetchExistingRender()]);
     const exists = documentExists(doc as RuntimeDocument & { exists?: boolean });
     setDocExists(exists);
@@ -98,7 +106,7 @@ export function App() {
     if (!exists) {
       setData(EMPTY_DOC);
       setSel(null);
-      return;
+      return null;
     }
     const mapped = mapDocument(doc as RuntimeDocument);
     setData(mapped);
@@ -106,12 +114,22 @@ export function App() {
       if (prev && mapped[selKey(prev.type)].some((e: { id: string }) => e.id === prev.id)) return prev;
       return mapped.shots[0] ? { type: "shot", id: mapped.shots[0].id } : null;
     });
+    return mapped;
   }, []);
 
   useEffect(() => {
     void hydrate();
   }, [hydrate]);
 
+  // Close the render-progress EventSource on unmount (it is opened per-render in doRender).
+  useEffect(
+    () => () => {
+      progressEs.current?.close();
+      progressEs.current = null;
+    },
+    []
+  );
+
   useEffect(() => {
     localStorage.setItem("aura.time", time.toFixed(2));
   }, [time]);
@@ -159,7 +177,8 @@ export function App() {
 
   const showToast = (msg: string, kind: Toast["kind"]) => {
     setToast({ msg, kind });
-    window.setTimeout(() => setToast(null), 2600);
+    window.clearTimeout(toastTimer.current);
+    toastTimer.current = window.setTimeout(() => setToast(null), 2600);
   };
 
   const selectShot = (id: string) => {
@@ -190,54 +209,62 @@ export function App() {
 
   // Outliner Cast "+" — run a REAL `cast add` command through the same path the Console
   // uses (forceCommand bypasses Prompt mode), so it actually mutates the working document,
-  // appends a committed/rejected card, and re-hydrates. A unique default name avoids
-  // colliding with existing cast (the user renames via the Inspector / a follow-up command).
+  // appends a committed/rejected card, and re-hydrates. The CLI grammar is
+  // `cast add --id <id> --query "…"`; a unique default id avoids colliding with existing
+  // cast (the user swaps the look with a follow-up `cast add --id <id> --query "…"`).
   const addCast = () => {
     const run = consoleApi.current.run;
     if (!run) {
       showToast("Console not ready — try again", "tip");
       return;
     }
-    const taken = new Set(data.cast.map((c) => c.name.toLowerCase()));
+    const taken = new Set(data.cast.map((c) => c.id.toLowerCase()));
     let n = data.cast.length + 1;
-    let name = `Cast ${n}`;
-    while (taken.has(name.toLowerCase())) name = `Cast ${++n}`;
-    run(`cast add ${name}`, true);
+    let id = `cast-${n}`;
+    while (taken.has(id)) id = `cast-${++n}`;
+    run(`cast add --id ${id} --query "friendly cartoon character"`, true);
   };
 
   // Generate a brand-new scene from a plain-English sentence. This is the headline action:
   // it runs `new --prompt "…" --full` (the deterministic Director — parses cast, keyword-routes
-  // the set, lays out shots/dialogue), replacing the working document, then re-hydrates the UI.
+  // the set, lays out shots/dialogue), replacing the working document, then re-hydrates the UI
+  // and auto-renders a preview so the Stage shows the new scene — not stale captions.
   const generateScene = async () => {
     const p = newScenePrompt.trim();
-    if (!p || generating) return;
+    // No generate while a render is in flight: the in-flight render is of the OLD document
+    // and would put the old scene's video on the Stage (the buttons are disabled too).
+    if (!p || generating || rendering) return;
     setGenerating(true);
     setPlaying(false);
-    // Strip quotes/backslashes so the prompt can't break the command tokenizer.
-    const safe = p.replace(/["\\]/g, "");
-    const res = await runSceneCommand(`new --prompt "${safe}" --full`);
-    if (!res.ok) {
+    try {
+      // Strip quotes/backslashes so the prompt can't break the command tokenizer.
+      const safe = p.replace(/["\\]/g, "");
+      const res = await runSceneCommand(`new --prompt "${safe}" --full`);
+      if (!res.ok) {
+        showToast("Couldn't generate that scene — try rewording it", "tip");
+        return;
+      }
+      await hydrate();        // panels (cast/set/props/shots/dialogue) now reflect the NEW scene
+      setNewScenePrompt("");
+      setTime(0);
+      // CRITICAL: the render on disk is the OLD scene. Drop it so the stale video can't masquerade
+      // as the new one, then auto-render the new document.
+      setRenderVideo(null);
+      setRenderPoster(null);
+      const rendered = await doRender("sequence");   // ← awaited so the spinner stays until the video is ready
+      // doRender already toasts on failure — only celebrate when the render actually succeeded.
+      if (rendered) showToast("Scene ready — click Play on the transport to watch", "ok");
+    } catch (e) {
+      showToast(`Scene generation failed — ${e instanceof Error ? e.message : "try again"}`, "tip");
+    } finally {
       setGenerating(false);
-      showToast("Couldn't generate that scene — try rewording it", "tip");
-      return;
     }
-    await hydrate();        // panels (cast/set/props/shots/dialogue) now reflect the NEW scene
-    setNewScenePrompt("");
-    setTime(0);
-    setGenerating(false);
-    // CRITICAL: the render on disk is the OLD scene. Drop it (so the stale video can't masquerade
-    // as the new one) and auto-render the new document, so the big preview ACTUALLY changes — not
-    // just the captions. Without this, the Stage keeps showing the previous render.
-    setRenderVideo(null);
-    setRenderPoster(null);
-    showToast("New scene built — rendering a preview so you can see it…", "ok");
-    doRender("sequence");
   };
 
   // "Continue scene" — add another shot to the CURRENT scene (same cast & set) so you can
   // build a longer video without regenerating. Appends a medium shot; the user directs it next.
   const continueScene = async () => {
-    if (continuing || generating || !docExists) return;
+    if (continuing || generating || rendering || !docExists) return;
     setContinuing(true);
     setPlaying(false);
     const existing = new Set(data.shots.map((s) => s.id));
@@ -250,66 +277,105 @@ export function App() {
       showToast("Couldn't add a shot — try again", "tip");
       return;
     }
-    await hydrate();
+    try {
+      await hydrate();
+    } catch {
+      // The shot committed but the re-fetch failed — recover instead of an unhandled rejection.
+      showToast("Shot added, but refreshing the scene failed — reload to see it", "tip");
+      return;
+    }
     setSel({ type: "shot", id });
     showToast("Shot added — same cast & set. Direct it, or tell the AI what happens next.", "ok");
   };
 
+  // Drag-retime from the Timeline's Shots track: issues the real `shot retime` CLI
+  // command and re-hydrates so every consumer (stage, inspector, totals) updates.
+  const retimeShot = async (shotId: string, newDuration: number) => {
+    if (generating || rendering) return;
+    const duration = Math.max(1, Math.round(newDuration));
+    const res = await runSceneCommand(`shot retime --id ${shotId} --duration ${duration}`);
+    if (!res.ok) {
+      showToast("Couldn't retime the shot — try again", "tip");
+      return;
+    }
+    try {
+      await hydrate();
+    } catch {
+      showToast("Shot retimed, but refreshing the scene failed — reload to see it", "tip");
+    }
+  };
+
   // Render hits the REAL pipeline via POST /api/render (dev middleware -> render-live /
   // warm render server). Progress easing runs while the request is in flight (renders are
   // not streamed); on success the rendered webm/poster is loaded into the Stage and a
   // render card is appended. Low-fi is the default for the fast studio iteration loop.
-  const doRender = (scope: "shot" | "sequence") => {
-    if (rendering) return;
+  // Resolves true only when the render actually succeeded, so callers (e.g. generateScene)
+  // can branch their own toasts on the real outcome.
+  const doRender = async (scope: "shot" | "sequence"): Promise<boolean> => {
+    if (rendering) {
+      showToast("Render already in progress", "tip");
+      return false;
+    }
     const isShot = scope === "shot";
-    if (isShot && !currentShot) return;
+    if (isShot && !currentShot) return false;
     setRendering(true);
-    setRenderPct(0);
+    setRenderPct(-1);
     setPlaying(false);
-    // Ease the progress ring toward ~92% while we await the real render; snap to 100% on done.
-    const started = performance.now();
-    let live = true;
-    const ease = () => {
-      if (!live) return;
-      const t = (performance.now() - started) / 1000;
-      // Asymptotic approach so the ring never claims completion before the server returns.
-      setRenderPct(Math.min(92, 92 * (1 - Math.exp(-t / 9))));
-      requestAnimationFrame(ease);
+    // Subscribe to real render-progress SSE from the render pipeline. The EventSource lives
+    // in a ref so the unmount effect can close it if the user leaves mid-render.
+    progressEs.current?.close();
+    const es = new EventSource("/api/render-progress");
+    progressEs.current = es;
+    es.onmessage = (e) => {
+      try {
+        const d = JSON.parse(e.data) as { current: number; total: number; label: string; pct: number };
+        // "waiting" = the render process hasn't written progress yet — keep the intentional
+        // indeterminate state (-1) instead of snapping the bar to a determinate 0%.
+        if (d.label === "waiting") return;
+        setRenderPct(d.pct);
+      } catch {}
     };
-    requestAnimationFrame(ease);
+    es.onerror = () => { /* normal on close */ };
 
     // Render the current shot's time-range when scope is "shot", else the whole sequence.
     const range = isShot && currentShot ? `${Math.floor(currentShot.start)}-${Math.ceil(currentShot.start + currentShot.dur)}` : undefined;
-    void runRender({ lowFi: true, range }).then((res) => {
-      live = false;
-      setRenderPct(100);
-      setRendering(false);
-      if (!res.ok) {
-        showToast("Render failed — see console", "tip");
-        return;
+    const res = await runRender({ lowFi: true, range });
+    es.close();
+    if (progressEs.current === es) progressEs.current = null;
+    setRendering(false);
+    if (!res.ok) {
+      showToast("Render failed — see console", "tip");
+      return false;
+    }
+    // Re-sync the panels with the real document FIRST so the render card's duration reflects
+    // the document that was actually rendered (not a closure-captured pre-hydrate DUR).
+    let freshDur = DUR;
+    try {
+      const fresh = await hydrate();
+      if (fresh) freshDur = fresh.DUR;
+    } catch {
+      // Panels stay stale but the render itself succeeded — don't fail the whole render.
+    }
+    // Cache-bust so the Stage reloads the freshly rendered media.
+    const bust = "?t=" + Date.now();
+    if (res.video) setRenderVideo(res.video + bust);
+    if (res.poster) setRenderPoster(res.poster + bust);
+    setTranscript((tr) => [
+      ...tr,
+      {
+        type: "render",
+        id: "r" + Date.now(),
+        frame: res.poster ? res.poster + bust : "",
+        label: "low-fi preview · " + (isShot && currentShot ? fmt(currentShot.dur) : fmt(freshDur)),
+        shot: isShot && currentShot ? currentShot.name : "Full sequence",
+        meta: res.ms ? "rendered in " + (res.ms / 1000).toFixed(1) + "s" : "just now"
       }
-      // Cache-bust so the Stage reloads the freshly rendered media.
-      const bust = "?t=" + Date.now();
-      if (res.video) setRenderVideo(res.video + bust);
-      if (res.poster) setRenderPoster(res.poster + bust);
-      setTranscript((tr) => [
-        ...tr,
-        {
-          type: "render",
-          id: "r" + Date.now(),
-          frame: res.poster ? res.poster + bust : "",
-          label: "low-fi preview · " + (isShot && currentShot ? fmt(currentShot.dur) : fmt(DUR)),
-          shot: isShot && currentShot ? currentShot.name : "Full sequence",
-          meta: res.ms ? "rendered in " + (res.ms / 1000).toFixed(1) + "s" : "just now"
-        }
-      ]);
-      showToast(
-        isShot && currentShot ? "Shot render complete · " + currentShot.name : "Render complete · full sequence",
-        "ok"
-      );
-      // Re-sync the panels with the real document (shot frames may now exist).
-      void hydrate();
-    });
+    ]);
+    showToast(
+      isShot && currentShot ? "Shot render complete · " + currentShot.name : "Render complete · full sequence",
+      "ok"
+    );
+    return true;
   };
 
   return (
@@ -330,7 +396,7 @@ export function App() {
         {generating ? (
           <span className="newscene-status">
             <span className="newscene-spinner" />
-            Building your scene — cast, set, shots &amp; dialogue… (a few seconds)
+            Building your scene — this takes ~25 seconds (generating cast, set, shots, then rendering a preview)
           </span>
         ) : (
           <input
@@ -346,7 +412,9 @@ export function App() {
         )}
         <button
           className={"newscene-btn" + (generating ? " busy" : "")}
-          disabled={generating || !newScenePrompt.trim()}
+          // Also disabled while a render is in flight: generating then would race the
+          // in-flight render of the OLD document (stale video lands on the Stage).
+          disabled={generating || rendering || !newScenePrompt.trim()}
           onClick={() => void generateScene()}
         >
           {generating ? "Generating…" : "Generate scene"}
@@ -354,7 +422,7 @@ export function App() {
         <span className="newscene-div" />
         <button
           className="newscene-btn newscene-continue"
-          disabled={generating || continuing || !docExists}
+          disabled={generating || continuing || rendering || !docExists}
           onClick={() => void continueScene()}
           title="Add a shot to this scene — keeps the same characters & set"
         >
@@ -390,7 +458,7 @@ export function App() {
             renderPoster={renderPoster}
             empty={!docExists}
           />
-          <Timeline data={data} time={time} onScrub={setTime} selShot={currentShot?.id ?? null} onSelShot={selectShot} />
+          <Timeline data={data} time={time} onScrub={setTime} selShot={currentShot?.id ?? null} onSelShot={selectShot} onRetime={(shotId, newDuration) => void retimeShot(shotId, newDuration)} />
         </div>
         <div className="col">
           <Console

package/templates/animation-studio/studio/src/components/Console.tsx

@@ -12,7 +12,13 @@ export interface ConsoleApi {
   run?: (text: string, forceCommand?: boolean) => void;
 }
 
-const CHIPS = ["cast add Pip", "shot retime --id shot-2 --duration 30", "cam orbit", "fx add rim light"];
+// Quick-insert examples — each one is the REAL CLI grammar (animation-scene.ts) and runs as-is.
+const CHIPS = [
+  'cast add --id pip --query "robot kid"',
+  "shot retime --id shot-2 --duration 30",
+  "camera --shot shot-1 --preset close-up",
+  "gesture --character pip --shot shot-1 --clip wave"
+];
 
 /** The portion of a command after its (possibly two-word) verb — the card's args line. */
 function argTail(raw: string, verb: string): string {
@@ -332,7 +338,7 @@ export function Console({ transcript, setTranscript, selShot, onRender, onSceneC
             placeholder={
               mode === "Prompt"
                 ? "Tell your AI agent what to change — e.g. “make the second line angrier and cut to a close-up” (it writes this down; your agent does it)"
-                : "Type an exact command — e.g. set space · cast add robot --name Pip · shot retime …"
+                : 'Type an exact command — e.g. set garage · cast add --id pip --query "robot kid" · shot retime …'
             }
             onChange={(e) => {
               setVal(e.target.value);

package/templates/animation-studio/studio/src/components/Inspector.tsx

@@ -4,6 +4,12 @@ import { Icon } from "./Icon";
 import { cap, fmt, shade } from "../state/util";
 import type { EpisodeDocument, Selection } from "../state/types";
 
+const STANDARD_CLIP_IDS = [
+  "idle", "talk", "gesture", "point", "nod", "wave",
+  "walk", "run", "react",
+  "sit", "shrug", "cross_arms", "salute", "shake_head"
+];
+
 function Field({
   label,
   icon,
@@ -160,8 +166,58 @@ export function Inspector({ data, sel }: InspectorProps) {
             }
           />
         </div>
+        <div className="prop-grid one">
+          <Field
+            label="Default clip"
+            icon="film"
+            value={
+              <select
+                disabled
+                value={c.defaultClip ?? "idle"}
+                style={{
+                  width: "100%",
+                  background: "transparent",
+                  color: "inherit",
+                  border: "none",
+                  fontFamily: "var(--mono)",
+                  fontSize: 12,
+                  cursor: "not-allowed"
+                }}
+              >
+                {STANDARD_CLIP_IDS.map((id) => (
+                  <option key={id} value={id}>{id}</option>
+                ))}
+              </select>
+            }
+          />
+        </div>
+        <div className="prop-grid">
+          <Field label="Mouth morph" icon="mic" value={c.mouthMorphIndex ?? -1} mono />
+          <Field
+            label="Foot IK"
+            icon="zap"
+            value={
+              <input
+                type="checkbox"
+                disabled
+                checked={!!c.footIk}
+                style={{ cursor: "not-allowed" }}
+              />
+            }
+          />
+        </div>
+        <div className="prop-grid one">
+          <Field
+            label="Grade intent"
+            value={
+              <span className="beat-chip cam" style={{ fontSize: 10 }}>
+                {c.gradeAwareIntent ?? "—"}
+              </span>
+            }
+          />
+        </div>
         <div className="insp-note">
-          {c.name + " is rigged and assignable to any beat. Type “cast” commands in the console to re-pose or re-cast."}
+          {c.name + " is rigged and assignable to any beat. Type \"cast\" commands in the console to re-pose or re-cast."}
         </div>
       </Fragment>
     );

package/templates/animation-studio/studio/src/components/Stage.tsx

@@ -7,6 +7,7 @@ import type { EpisodeDocument, Shot, ViewMode } from "../state/types";
 function RenderOverlay({ pct }: { pct: number }) {
   const r = 32;
   const c = 2 * Math.PI * r;
+  const indeterminate = pct < 0;
   return (
     <div className="render-ov">
       <div className="render-ring">
@@ -20,17 +21,21 @@ function RenderOverlay({ pct }: { pct: number }) {
             stroke="var(--warm)"
             strokeWidth={5}
             strokeLinecap="round"
-            strokeDasharray={c}
-            strokeDashoffset={c * (1 - pct / 100)}
-            style={{ transition: "stroke-dashoffset .25s" }}
+            strokeDasharray={indeterminate ? `${c * 0.25} ${c * 0.75}` : c}
+            strokeDashoffset={indeterminate ? undefined : c * (1 - pct / 100)}
+            style={
+              indeterminate
+                ? { animation: "sp 1.2s linear infinite", transformOrigin: "37px 37px" }
+                : { transition: "stroke-dashoffset .25s" }
+            }
           />
         </svg>
-        <div className="render-pct">{Math.round(pct) + "%"}</div>
+        <div className="render-pct">{indeterminate ? "···" : Math.round(pct) + "%"}</div>
       </div>
       <div style={{ textAlign: "center" }}>
         <div className="ttl">Rendering preview</div>
         <div className="sub">
-          {pct < 40 ? "aura · rigging cast…" : pct < 75 ? "aura · simulating lighting…" : "aura · compositing frames…"}
+          {indeterminate ? "aura · working…" : pct < 40 ? "aura · rigging cast…" : pct < 75 ? "aura · simulating lighting…" : "aura · compositing frames…"}
         </div>
       </div>
     </div>

package/templates/animation-studio/studio/src/components/Timeline.tsx

@@ -23,15 +23,43 @@ function Clip({
   clip,
   DUR,
   sel,
-  onClick
+  onClick,
+  trackRef,
+  zoom,
+  onRetime
 }: {
   clip: ClipModel;
   DUR: number;
   sel: boolean;
   onClick: (e: React.MouseEvent) => void;
+  trackRef: React.RefObject<HTMLDivElement>;
+  zoom: number;
+  onRetime?: (clipId: string, newDuration: number) => void;
 }) {
   const left = (clip.start / DUR) * 100;
   const width = (clip.dur / DUR) * 100;
+
+  const handleDown = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (!onRetime || !trackRef.current) return;
+    const initialDur = clip.dur;
+    const startX = e.clientX;
+    const trackWidth = trackRef.current.getBoundingClientRect().width;
+    const pxPerSecond = (trackWidth * zoom) / DUR;
+
+    const onMove = (ev: MouseEvent) => {
+      const delta = ev.clientX - startX;
+      const newDur = Math.max(1, initialDur + delta / pxPerSecond);
+      onRetime(clip.id, newDur);
+    };
+    const onUp = () => {
+      window.removeEventListener("mousemove", onMove);
+      window.removeEventListener("mouseup", onUp);
+    };
+    window.addEventListener("mousemove", onMove);
+    window.addEventListener("mouseup", onUp);
+  };
+
   return (
     <div
       className={"clip" + (sel ? " sel" : "")}
@@ -43,6 +71,21 @@ function Clip({
       }}
     >
       <span className="clab">{clip.label}</span>
+      {onRetime && (
+        <div
+          onMouseDown={handleDown}
+          title="Drag to retime"
+          style={{
+            position: "absolute",
+            right: 0,
+            top: 0,
+            bottom: 0,
+            width: 6,
+            cursor: "e-resize",
+            zIndex: 2
+          }}
+        />
+      )}
     </div>
   );
 }
@@ -53,9 +96,10 @@ export interface TimelineProps {
   onScrub: (t: number) => void;
   selShot: string | null;
   onSelShot: (id: string) => void;
+  onRetime?: (clipId: string, newDuration: number) => void;
 }
 
-export function Timeline({ data, time, onScrub, selShot, onSelShot }: TimelineProps) {
+export function Timeline({ data, time, onScrub, selShot, onSelShot, onRetime }: TimelineProps) {
   const DUR = data.DUR;
   const [zoom, setZoom] = useState(1);
   const ref = useRef<HTMLDivElement>(null);
@@ -170,6 +214,9 @@ export function Timeline({ data, time, onScrub, selShot, onSelShot }: TimelinePr
                       onScrub(r.start);
                       if (t.name === "Shots") onSelShot(r.id);
                     }}
+                    trackRef={ref}
+                    zoom={zoom}
+                    onRetime={t.name === "Shots" ? onRetime : undefined}
                   />
                 ))}
               </div>

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

@@ -61,6 +61,12 @@ export interface RuntimeCharacter {
   rigGrade?: "A" | "B" | "C" | "D";
   /** M7 — dominant motion source the render played (mocap/extracted/procedural…), when recorded. */
   motionSource?: string;
+  /** Default performance clip id. */
+  defaultClip?: string;
+  /** Mouth morph target index for lip-sync. */
+  mouthMorphIndex?: number;
+  /** Foot IK configuration (truthy when enabled). */
+  footIk?: unknown;
 }
 
 export interface RuntimeShotBlocking {
@@ -254,6 +260,8 @@ export function mapDocument(doc: RuntimeDocument): EpisodeDocument {
 
   const cast: CastMember[] = rChars.map((c) => {
     const { source, sourceLabel } = castProvenance(c);
+    const fidelity =
+      fidelityById.get(c.id) ?? { id: c.id, grade: "C", previz: true, reason: "previz: ungraded" };
     return {
       id: c.id,
       name: cap(c.id),
@@ -263,8 +271,11 @@ export function mapDocument(doc: RuntimeDocument): EpisodeDocument {
       lines: linesPerSpeaker(c.id),
       source,
       sourceLabel,
-      fidelity:
-        fidelityById.get(c.id) ?? { id: c.id, grade: "C", previz: true, reason: "previz: ungraded" }
+      fidelity,
+      defaultClip: c.defaultClip,
+      mouthMorphIndex: c.mouthMorphIndex,
+      footIk: !!c.footIk,
+      gradeAwareIntent: `${fidelity.grade}-grade`
     };
   });
 

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

@@ -16,16 +16,27 @@ export interface VerbSpec {
   desc: string;
 }
 
+// The REAL CLI grammar (animation-scene.ts) — every entry here, inserted verbatim with its
+// placeholders filled, is accepted by the CLI's switch/flag parser. These strings are also
+// surfaced verbatim to LLMs, so they must never advertise a syntax the validator rejects.
 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: "new", tail: '--prompt "<scene>" [--full]', desc: "Start a new working scene from a prompt" },
+  { verb: "set", tail: '<studio|garage|office|kitchen|moon-garden|space-station|meadow> | --query "<setting>"', desc: "Choose the active set template" },
+  { verb: "cast add", tail: '--id <id> --query "<look>" [--scale <s>]', desc: "Cast a character (catalog resolve)" },
+  { verb: "prop add", tail: '--id <id> --query "<look>"', desc: "Register a prop from the catalog" },
+  { verb: "shot add", tail: "--id <id> --preset <preset> --duration <s>", desc: "Block a new shot" },
+  { verb: "shot remove", tail: "--id <id>", desc: "Remove a 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" }
+  { verb: "camera", tail: "--shot <id> --preset <establishing|medium|two-shot|close-up>", desc: "Set a shot's camera" },
+  { verb: "dialogue", tail: '--line <id> --speaker <id> --text "<line>" --start <s>', desc: "Write a dialogue line" },
+  { verb: "block", tail: "--character <id> --shot <id> --to <x,z> [--clip <clip>]", desc: "Move a character in a shot" },
+  { verb: "gesture", tail: "--character <id> --shot <id> --clip <clip>", desc: "Queue a gesture clip for a character" },
+  { verb: "dress", tail: "--prop <id> --at <x,z> [--scale <s>]", desc: "Place a registered prop on the set" },
+  { verb: "scale", tail: "--character <id> --to <s>", desc: "Rescale a character" },
+  { verb: "show", tail: "", desc: "Print the scene summary" },
+  { verb: "validate", tail: "", desc: "Check scene coherence" },
+  { verb: "undo", tail: "", desc: "Undo the last committed edit" },
+  { verb: "render", tail: "[--shot <id>]", desc: "Render a low-fi preview (shot or full sequence)" }
 ];
 
 export interface ParsedCommand {
@@ -47,7 +58,7 @@ export function parse(raw: string): ParsedCommand {
   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]) {
+  if (["cast", "shot", "prop"].includes(verb) && rest[0]) {
     verb += " " + rest[0];
     rest = rest.slice(1);
   }