create-aura3d 1.3.1 → 1.3.3

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

@@ -0,0 +1,66 @@
+/**
+ * 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;
+}
+
+// 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: "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: "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 {
+  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", "prop"].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])) };
+}

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

@@ -0,0 +1,173 @@
+/**
+ * UI-side view model for the Animation Studio shell.
+ *
+ * The single source of truth is the REAL runtime EpisodeDocument fetched from
+ * `GET /api/document`; it is mapped into the types below by `mapDocument.ts`.
+ * There is no seed / fixture — when no document exists the UI renders empty.
+ */
+
+import type { CharacterFidelity, SceneFidelity } from "./fidelity";
+
+export type SelectionType = "shot" | "cast" | "set" | "prop";
+export type ViewMode = "Render" | "Wireframe" | "Storyboard";
+export type ComposerMode = "Prompt" | "Command";
+export type IconName = string;
+
+export interface Selection {
+  type: SelectionType;
+  id: string;
+}
+
+/**
+ * Where a cast member came from — kept honest and visible (Phase E3):
+ *  - `authored-fallback` — a built-in authored/placeholder character (NOT catalog evidence).
+ *  - `catalog-resolved`  — resolved from the federated catalog (carries source/license/url).
+ *  - `user-uploaded`     — a GLB the user dropped in (`cast add --file`).
+ */
+export type CastSource = "authored-fallback" | "catalog-resolved" | "user-uploaded";
+
+export interface CastMember {
+  id: string;
+  name: string;
+  kind: string;
+  color: string;
+  glyph: string;
+  lines: number;
+  /** Provenance class — drives the Outliner source label so fallback is never sold as catalog. */
+  source: CastSource;
+  /** Short human label for the source (e.g. catalog title / "authored" / "uploaded"). */
+  sourceLabel: string;
+  /** M7 — honest fidelity tier (A/B/C). C is "previz" — never presented as finished. */
+  fidelity: CharacterFidelity;
+  /** Default performance clip id (e.g. "idle"). */
+  defaultClip?: string;
+  /** Mouth morph target index for lip-sync; -1 when absent. */
+  mouthMorphIndex?: number;
+  /** Whether foot IK is enabled for this cast member. */
+  footIk?: boolean;
+  /** Read-only grade-aware performance intent label. */
+  gradeAwareIntent?: string;
+}
+
+export interface SetEntity {
+  id: string;
+  name: string;
+  meta: string;
+  icon: IconName;
+}
+
+export interface PropEntity {
+  id: string;
+  name: string;
+  meta: string;
+  icon: IconName;
+}
+
+export interface Shot {
+  id: string;
+  name: string;
+  start: number;
+  dur: number;
+  /** Real render thumbnail (/preview/frames/*.png) once a render exists, else "". */
+  frame: string;
+  cam: string;
+  who: string[];
+  color: string;
+}
+
+export interface Beat {
+  id: string;
+  shot: string;
+  who: string;
+  start: number;
+  dur: number;
+  text: string;
+  /* ---- Director per-beat acting plan (F1) — inspectable in the UI ---- */
+  /** Who the speaker is addressing (the other party), or "" when solo. */
+  listener: string;
+  /** What the speaker DOES (talk / gesture / point / nod / walk / run) — the real director clip. */
+  speakingIntent: string;
+  /** What the listener DOES in response (react / nod / idle) — never frozen. */
+  listenerIntent: string;
+  /** The camera framing for this beat (establishing / two-shot / medium / close-up). */
+  camera: string;
+}
+
+export interface TimelineSpan {
+  id: string;
+  start: number;
+  dur: number;
+  text: string;
+  color: string;
+}
+
+/** The UI view model derived from the real working document. */
+export interface EpisodeDocument {
+  title: string;
+  cast: CastMember[];
+  sets: SetEntity[];
+  props: PropEntity[];
+  shots: Shot[];
+  beats: Beat[];
+  camera: TimelineSpan[];
+  /** Per-character gesture/reaction windows (gesture/point/nod/react/wave) for the timeline. */
+  gestures: TimelineSpan[];
+  fx: TimelineSpan[];
+  DUR: number;
+  /** M7 — scene-level fidelity tier (floor of the cast). C scene is labeled "previz". */
+  fidelity: SceneFidelity;
+}
+
+/* ---- Director Console transcript model ---- */
+
+export type DiffOp = "+" | "~" | "!";
+export type DiffKind = "add" | "mod" | "del";
+
+export interface Diff {
+  op: DiffOp;
+  k: DiffKind;
+  /** May contain <b>…</b> emphasis (rendered as bold). */
+  t: string;
+}
+
+export type CmdState = "run" | "ok" | "bad";
+
+export interface YouTurn {
+  type: "you";
+  id: string;
+  text: string;
+}
+
+export interface DirTurn {
+  type: "dir";
+  id: string;
+  /** Markdown-ish: **bold** emphasis is supported. */
+  think: string;
+}
+
+export interface CmdTurn {
+  type: "cmd";
+  id: string;
+  verb: string;
+  args: string;
+  state: CmdState;
+  diffs?: Diff[];
+  dur?: string;
+  hash?: string;
+}
+
+export interface RenderTurn {
+  type: "render";
+  id: string;
+  frame: string;
+  label: string;
+  shot: string;
+  meta: string;
+}
+
+export type Turn = YouTurn | DirTurn | CmdTurn | RenderTurn;
+
+export interface Toast {
+  msg: string;
+  kind: "ok" | "tip";
+}

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

@@ -0,0 +1,46 @@
+/* Shared formatting + small text helpers (ported from the design source). */
+
+/** mm:ss from seconds. */
+export function fmt(s: number): string {
+  const m = Math.floor(s / 60);
+  const ss = Math.floor(s % 60);
+  return m + ":" + String(ss).padStart(2, "0");
+}
+
+/** Capitalise first letter. */
+export function cap(s: string): string {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+/** **bold** -> <span class="hl"> for AURA reasoning. */
+export function boldHtml(s: string): string {
+  return (s || "").replace(/\*\*([^*]+)\*\*/g, '<span class="hl">$1</span>');
+}
+
+/** Highlight command args: --flags (blue) and "quoted strings" (green). */
+export function highlightArgs(s: string): string {
+  // Sentinels guard quoted strings from the --flag pass, then become .str spans.
+  const OPEN = String.fromCharCode(1);
+  const CLOSE = String.fromCharCode(2);
+  return s
+    .replace(/("[^"]*")/g, OPEN + '$1' + CLOSE)
+    .replace(/(--[a-z]+)/g, '<span class="flag">$1</span>')
+    .replace(new RegExp(OPEN + '([^' + CLOSE + ']*)' + CLOSE, 'g'), '<span class="str">$1</span>');
+}
+
+/** Short hex revision hash. */
+export function hash(): string {
+  return Math.random().toString(16).slice(2, 8);
+}
+
+/** Darken a hex color (for avatar gradients). */
+export function shade(hex: string): string {
+  const n = parseInt(hex.slice(1), 16);
+  let r = (n >> 16) & 255;
+  let g = (n >> 8) & 255;
+  let b = n & 255;
+  r = Math.round(r * 0.55);
+  g = Math.round(g * 0.55);
+  b = Math.round(b * 0.62);
+  return "#" + ((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1);
+}