@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/studio/camera.tsx

@@ -0,0 +1,59 @@
+// Pictures for the agent: a photo or a drawing shrunk to travel light, and the webcam held up to the paper.
+import { useEffect, useRef, useState } from 'preact/hooks';
+
+/** A photo shrunk to 1600 px as JPEG, so a phone picture travels light; what the browser cannot read goes as it is. */
+export async function shrink(file: Blob): Promise<string> {
+  try {
+    const bitmap = await createImageBitmap(file);
+    const scale = Math.min(1, 1600 / Math.max(bitmap.width, bitmap.height));
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.round(bitmap.width * scale);
+    canvas.height = Math.round(bitmap.height * scale);
+    canvas.getContext('2d')!.drawImage(bitmap, 0, 0, canvas.width, canvas.height);
+    return canvas.toDataURL('image/jpeg', 0.88);
+  } catch {
+    return base64(file);
+  }
+}
+
+export function base64(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(blob);
+  });
+}
+
+/** The webcam held up to a drawing: a live preview and a button that keeps one frame. */
+export function Camera({ onSnap, onClose, tip = 'Hold the drawing up to the camera, flat and filling the picture.', words = { snap: 'Take the photo', done: 'Done', none: 'No camera' } }: { onSnap: (jpeg: string) => void; onClose: () => void; tip?: string; words?: { snap: string; done: string; none: string } }) {
+  const video = useRef<HTMLVideoElement>(null);
+  const [error, setError] = useState('');
+  useEffect(() => {
+    let stream: MediaStream | null = null;
+    navigator.mediaDevices.getUserMedia({ video: { width: { ideal: 1920 }, height: { ideal: 1080 } } }).then((s) => {
+      stream = s;
+      if (video.current) video.current.srcObject = s;
+    }).catch((e) => setError(`${words.none}: ${e.message}`));
+    return () => stream?.getTracks().forEach((t) => t.stop());
+  }, []);
+  const snap = () => {
+    const v = video.current;
+    if (!v || !v.videoWidth) return;
+    const canvas = document.createElement('canvas');
+    canvas.width = v.videoWidth;
+    canvas.height = v.videoHeight;
+    canvas.getContext('2d')!.drawImage(v, 0, 0);
+    onSnap(canvas.toDataURL('image/jpeg', 0.9));
+  };
+  return (
+    <div class="camera">
+      {error ? <p class="error">{error}</p> : <video ref={video} autoPlay playsInline muted />}
+      <div class="row">
+        <button type="button" class="primary" onClick={snap} disabled={!!error}>{words.snap}</button>
+        <button type="button" class="ghost" onClick={onClose}>{words.done}</button>
+        <span class="detail">{tip}</span>
+      </div>
+    </div>
+  );
+}

package/app/studio/cast-work.tsx

@@ -0,0 +1,207 @@
+// A cast step at work, live: who is being painted, modelled or drawn as sprites, each picture as it lands, the
+// stage it is at (TRELLIS, skeleton) and the time left; when one is done, it moves right there.
+import { useEffect, useState } from 'preact/hooks';
+import { call, fileUrl } from './api.ts';
+import { FigurePreview, MouthShapes, Sides } from './figure.tsx';
+import { nice } from './world.tsx';
+import { named, nowBy } from './build.tsx';
+import { Icon } from './icons.tsx';
+
+/** Per character: the files the running job wrote (world path → when), what the build last said about them, and
+ * when each cast step first touched them (a build paints the whole cast long before it models the last one). */
+export type CastWork = Record<string, { files: Record<string, number>; said: string; at: number; began: Record<string, number> }>;
+export const CAST_STEPS = ['cast', 'model', 'sprites', 'faces'];
+
+const FILE = /^cast\/([a-z0-9][\w-]*)(-painting\.png|\.png|\/model\/[\w-]+\.(?:png|json)|\/sprites\/[\w-]+\.(?:png|json)|\/face-[\w-]+\.(?:png|json)|\/face-work\/[\w-]+\.png)$/;
+/** A file the cast steps write, as [character, step]. */
+export function castFile(file: string): [string, string] | null {
+  const m = FILE.exec(file);
+  if (!m) return null;
+  return [m[1], m[2].startsWith('/model/') ? 'model' : m[2].startsWith('/sprites/') ? 'sprites' : m[2].startsWith('/face') ? 'faces' : 'cast'];
+}
+/** A build line about one character ("hero: TRELLIS builds the body", "hero walk right: take 2 …"), as [character, words]. */
+export function castLine(line: string): [string, string] | null {
+  const m = /^([a-z0-9][\w-]*)((?: (?:walk|talk) [\w-]+(?: \[[^\]]*\])?)?): (.+)$/.exec(line.trim());
+  return m ? [m[1], `${m[2].trim() ? `${m[2].trim()}: ` : ''}${m[3]}`] : null;
+}
+
+/** The cast step a build line belongs to ("<key>: TRELLIS builds the body" is the model step). */
+export function lineStep(words: string): string {
+  return /4 sides|TRELLIS|rigging|3D model|auto-rig/.test(words) ? 'model' : /face (?:prepared|unchanged)|mouth|facial|lips/.test(words) ? 'faces' : /^(?:walk|talk) |sprite/.test(words) ? 'sprites' : 'cast';
+}
+
+/** One character's work with a build line or a landed file added, the step's start kept from the first touch. */
+export function castTouched(w: CastWork[string] | undefined, step: string, change: { said?: string; file?: string }, now = Date.now()): CastWork[string] {
+  return {
+    said: change.said ?? w?.said ?? '',
+    files: change.file ? { ...w?.files, [change.file]: now } : w?.files ?? {},
+    began: w?.began[step] ? w.began : { ...w?.began, [step]: now },
+    at: now,
+  };
+}
+
+const VIEWS = ['front', 'back', 'left', 'right'];
+const STAGES = [
+  { word: '4 sides', by: 'Muse Image', tip: 'Muse Image paints the character from the front, back and both sides', s: 40 },
+  { word: 'Body', by: 'TRELLIS', tip: 'TRELLIS builds a 3D body from the four sides (Hugging Face GPU)', s: 30 },
+  { word: 'Skeleton', by: 'auto-rig', tip: 'A skeleton is fitted into the body so it can walk', s: 25 },
+];
+const WHAT: Record<string, string> = { cast: 'Painting the cast', model: 'Building 3D models', sprites: 'Painting sprites', faces: 'Preparing talking faces' };
+/** The newest face picture the faces step wrote for one character: the mouth shapes so far. */
+const newestFace = (key: string, w: CastWork[string]) => Object.entries(w.files).filter(([f]) => f.startsWith(`cast/${key}/face`) && f.endsWith('.png') && !f.endsWith('-reference.png')).sort((a, b) => b[1] - a[1])[0];
+
+type Who = { key: string; role: string; looksNow: string; figure: { file: string; v: number } | null; painting: { file: string; v: number } | null; stamps: { rig: number | null; model: number | null; sprites: number | null }; body: { upright: boolean } | null;
+  face?: { ready: boolean; attempt?: { state?: string; reason?: string; at?: string; skipped?: string[] } | null } };
+
+const clock = (s: number) => (s < 60 ? `${Math.max(1, Math.round(s))} s` : `${Math.floor(s / 60)} min ${String(Math.round(s % 60)).padStart(2, '0')} s`);
+
+/** Where one character is in this step: the stage index (STAGES for a model), done, or failed. */
+function where(step: string, key: string, w: CastWork[string]) {
+  const has = (f: string) => w.files[f] !== undefined;
+  if (step === 'model') {
+    if (has(`cast/${key}/model/model.json`)) return { at: STAGES.length, done: true };
+    if (/no 3D model/.test(w.said)) return { at: STAGES.length, done: true, failed: w.said.replace(/^no 3D model: /, '') };
+    return { at: /rigging/.test(w.said) ? 2 : /TRELLIS/.test(w.said) ? 1 : 0, done: false };
+  }
+  if (step === 'sprites') return { at: 0, done: has(`cast/${key}/sprites/sprites.json`) };
+  if (step === 'faces') return { at: 0, done: has(`cast/${key}/face-attempt.json`) || /face (prepared|unchanged)/.test(w.said) };
+  return { at: 0, done: has(`cast/${key}.png`) && /\.png · /.test(w.said) };
+}
+
+/** The pictures of this step for one character, landed or still to come. */
+function slots(step: string, key: string, w: CastWork[string]): Array<{ name: string; file?: string; v?: number }> {
+  if (step === 'model') return VIEWS.map((v) => ({ name: v, file: w.files[`cast/${key}/model/${v}.png`] ? `cast/${key}/model/${v}.png` : undefined, v: w.files[`cast/${key}/model/${v}.png`] }));
+  if (step === 'sprites') {
+    const painted = Object.keys(w.files).filter((f) => /\/sprites\/(?:talk-)?painted-[\w-]+\.png$/.test(f));
+    return painted.length ? painted.map((f) => ({ name: f.split('/').at(-1)!.replace(/\.png$/, '').replace('painted-', ''), file: f, v: w.files[f] })) : [{ name: 'walk' }];
+  }
+  if (step === 'faces') {
+    // What it works from (the painted figure) and the mouth shapes as they are painted and checked.
+    const atlas = newestFace(key, w);
+    return [{ name: 'works from', file: `cast/${key}.png`, v: 0 }, { name: 'mouth shapes', file: atlas?.[0], v: atlas?.[1] }];
+  }
+  return [`cast/${key}-painting.png`, `cast/${key}.png`].map((f, i) => ({ name: i ? 'cut out' : 'painted', file: w.files[f] ? f : undefined, v: w.files[f] }));
+}
+
+export function CastWorkStage({ slug, step, work, running, failed, since, took, version, only, onOpen }: {
+  slug: string; step: string; work: CastWork; running: boolean; since?: number; took: number; version: number;
+  /** Why the step stopped, in plain words, when it failed. */
+  failed?: string;
+  /** The character a job of one was started for (cast_animate, cast_redo). */
+  only?: string;
+  onOpen: (key: string) => void;
+}) {
+  const [cast, setCast] = useState<Who[] | null>(null);
+  useEffect(() => void call<Who[]>('cast_status', { slug }).then(setCast).catch(() => setCast([])), [slug, version]);
+  const [now, setNow] = useState(Date.now());
+  useEffect(() => {
+    if (!running) return;
+    const t = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(t);
+  }, [running]);
+  const known = new Set((cast ?? []).map((c) => c.key));
+  // Who this step touched, newest first; a job for one character shows that one from the start.
+  const keys = Object.entries(work)
+    .filter(([k, w]) => known.has(k) && (Object.keys(w.files).some((f) => castFile(f)?.[1] === step) || (step === 'model' && /sides|TRELLIS|rigging|3D model/.test(w.said)) || (step === 'faces' && /face|mouth|facial|lips/.test(w.said))))
+    .sort((a, b) => b[1].at - a[1].at).map(([k]) => k);
+  if (only && known.has(only) && !keys.includes(only)) keys.unshift(only);
+  const [pick, setPick] = useState<string | null>(null);
+  // A finished faces step shows everyone's outcome at once rather than the last one it touched.
+  const focus = step === 'faces' && !running ? undefined : pick && keys.includes(pick) ? pick : keys[0];
+  const empty = { files: {}, said: '', at: 0, began: {} };
+  const elapsed = since ? (now - since) / 1000 : 0;
+  // A job for one character takes about one character's time, not the build's whole model step.
+  const left = Math.max(0, (only && step === 'model' ? STAGES.reduce((sum, x) => sum + x.s, 0) : took) - elapsed);
+
+  return (
+    <div class="cast-work" data-lightbox-group>
+      <div class="cw-head">
+        <strong>{WHAT[step] ?? step}</strong>
+        <span class="detail">
+          {running ? (since ? `${clock(elapsed)} so far · ${left > 5 ? `about ${clock(left)} left` : 'a little longer than usual'}` : 'starting…') : failed ? `stopped: ${failed}` : 'done'}
+          {keys.length > 1 ? ` · ${keys.length} characters` : ''}
+        </span>
+      </div>
+      {!focus && step === 'faces' && cast && cast.some((c) => c.figure) && (
+        // Who gets a talking face, from the figure it is painted from: ready (its mouth shapes), failed and why, or still to come.
+        <ul class="cw-faces">
+          {cast.filter((c) => c.figure).map((c) => {
+            const failedWhy = c.face?.attempt?.state === 'failed' ? c.face.attempt.reason : undefined;
+            return (
+              <li class={c.face?.ready ? 'ok' : failedWhy ? 'fail' : ''}>
+                <img src={fileUrl(slug, c.figure!.file, c.figure!.v)} data-lightbox={fileUrl(slug, c.figure!.file, c.figure!.v)} title={`${nice(c.key)}: its mouth shapes are painted from this figure. Click: large`} alt={c.key} />
+                <div>
+                  <strong>{nice(c.key)}</strong>{' '}
+                  <span class="detail">{c.face?.ready ? '✓ speaks with moving lips' : failedWhy ? `✕ not yet: ${failedWhy}` : running ? '○ waiting its turn' : '○ no talking face yet'}</span>
+                  {c.face?.ready && <MouthShapes slug={slug} who={c.key} v={Date.parse(c.face.attempt?.at ?? '') || null} />}
+                  {!c.face?.ready && <div class="row"><button type="button" class="ghost small" title="Its card: Refresh speech animation tries again (Muse Image, a few calls)" onClick={() => onOpen(c.key)}><Icon name="pencil" /> Details</button></div>}
+                </div>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+      {!focus && (step !== 'faces' || !cast?.some((c) => c.figure)) && <div class="cw-wait"><span>{cast === null ? 'Reading the cast…' : named(step === 'model' ? 'Muse Image is about to paint the first character from four sides…' : step === 'sprites' ? 'Muse Image is about to paint the first sprite sheet…' : step === 'faces' ? 'Muse Image is about to paint the first mouth shapes…' : 'Muse Image is painting the cast…')}</span></div>}
+      {focus && (() => {
+        const w = work[focus] ?? empty;
+        const c = cast?.find((x) => x.key === focus);
+        const st = { ...where(step, focus, w), ...(failed && !where(step, focus, w).done && { stopped: true }) } as ReturnType<typeof where> & { stopped?: boolean };
+        // This character's time in this step: in a whole build it was painted with the cast half an hour before.
+        const mine = w.began[step] ? (now - w.began[step]) / 1000 : 0;
+        return (
+          <section class={`cw-focus${st.done ? ' done' : ''}`}>
+            <div class="cw-who">
+              {c?.figure ? <img src={fileUrl(slug, c.figure.file, w.files[c.figure.file] ?? c.figure.v)} data-lightbox={fileUrl(slug, c.figure.file, w.files[c.figure.file] ?? c.figure.v)} title="Click: large" alt="" /> : <div class="noimg" />}
+              <div class="cw-text">
+                <h3>{nice(focus)}{c?.role === 'hero' ? ' · hero' : ''}</h3>
+                <span class="detail">{st.stopped ? `Stopped at: ${w.said || 'the start'}` : st.failed ? `No 3D model: ${st.failed}` : st.done ? (step === 'model' ? 'The 3D model is ready' : 'Done') : w.said || 'waiting for the first picture…'}{!st.done && !st.stopped && mine > 1 ? ` · ${clock(mine)}` : ''}</span>
+                {step === 'model' && (
+                  <ol class="cw-stages">
+                    {STAGES.map((s, i) => <li class={i < st.at ? 'ok' : i === st.at && !st.done ? (st.stopped ? 'stop' : 'on') : ''} title={named(s.tip)}>{i < st.at ? '✓' : i === st.at && !st.done ? (st.stopped ? '✕' : '●') : '○'} {s.word} <small>{nowBy(s.by)}</small></li>)}
+                  </ol>
+                )}
+                <div class="row">
+                  {st.done && c && (c.stamps.model || c.stamps.rig || c.stamps.sprites) && <button type="button" class="ghost small" title="Looks, voice, 3D model and sprites of this character. Free to look" onClick={() => onOpen(focus)}><Icon name="pencil" /> Details</button>}
+                </div>
+              </div>
+            </div>
+            {step !== 'faces' && st.done && c && (c.stamps.model || c.stamps.sprites || c.stamps.rig)
+              ? <>
+                  {/* The sides stay in sight after the step: what TRELLIS built the body from. */}
+                  {step === 'model' && c.stamps.model && <Sides slug={slug} dir={`cast/${focus}/model`} v={c.stamps.model} />}
+                  <FigurePreview key={`${focus}-${c.stamps.model}-${c.stamps.sprites}`} slug={slug} who={focus} stamps={c.stamps} sides={step !== 'model'} />
+                </>
+              : (
+                <div class="cw-slots">
+                  {slots(step, focus, w).map((s) => s.name === 'works from' && c?.figure ? { ...s, file: c.figure.file, v: c.figure.v } : s).map((s) => (
+                    <figure class={s.file ? 'in' : ''}>
+                      {s.file ? <img src={fileUrl(slug, s.file, s.v)} data-lightbox={fileUrl(slug, s.file, s.v)} title="Click: large" alt={s.name} /> : <div class={`to-come${failed ? ' still' : ''}`} />}
+                      <figcaption>{s.name}</figcaption>
+                    </figure>
+                  ))}
+                </div>
+              )}
+          </section>
+        );
+      })()}
+      {keys.length > 1 && focus && (
+        <ul class="cw-others" aria-label="Others in this step">
+          {keys.filter((k) => k !== focus).map((k) => {
+            const w = work[k] ?? empty;
+            const c = cast?.find((x) => x.key === k);
+            const st = where(step, k, w);
+            return (
+              <li>
+                <button type="button" class="ghost" title={`Watch ${nice(k)}`} onClick={() => setPick(k)}>
+                  {c?.figure ? <img src={fileUrl(slug, c.figure.file, w.files[c.figure.file] ?? c.figure.v)} alt="" /> : <span class="noimg" />}
+                  <span>{nice(k)}</span>
+                  <small>{st.failed ? '✕ no model' : st.done ? '✓ done' : step === 'model' ? `● ${STAGES[st.at].word}` : '● working'}</small>
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+}

package/app/studio/cast.tsx

@@ -0,0 +1,178 @@
+// The cast: one card per character with their figure, how they look, what the runtime has for them and
+// their voice. Every change is an action (cast_redo, voice_set) kept in cast/fixes.json.
+import { useEffect, useState } from 'preact/hooks';
+import { call, fileUrl } from './api.ts';
+import { named } from './build.tsx';
+import { FigurePreview, MouthShapes } from './figure.tsx';
+import { Icon, type IconName } from './icons.tsx';
+
+type Pic = { file: string; v: number | null } | null;
+type Character = {
+  key: string; role: 'hero' | 'npc' | 'player' | 'narrator'; place: string | null; looks: string; looksNow: string;
+  fix: { looks?: string; take?: number; voice?: { voice: string } } | null;
+  figure: Pic; painting: Pic; rig: boolean; model: boolean; sprites: boolean; modelIssue: string | null;
+  rigIssue?: string | null; spriteIssues?: string[]; moves?: string;
+  modelJob: { id: string; state: 'queued' | 'running' } | null;
+  modelAttempt: { state: 'ready' | 'fallback' | 'failed'; reason: string | null; at: string } | null;
+  body: { height: number; upright: boolean } | null;
+  stamps: { rig: number | null; model: number | null; sprites: number | null };
+  voice: { voice: string; why: string; stability: number; style: number } | null;
+  face?: { ready: boolean; image: boolean; rig: boolean; spriteViews: number; model3d?: {mouth:boolean;method?:string|null;views?:string[]} | null; attempt?: { state?: string; reason?: string; at?: string } | null };
+  lines: number; flagged: number; sample: { text: string; file: string } | null;
+  voiceFailures?: Array<{ text: string; reason: string }>;
+  voiceWarnings?: string[];
+};
+type Voice = { id: string; name: string; sounds: string; fits?: boolean };
+
+export function CastView({ slug, version, onError, focus }: { slug: string; version: number; onError: (m: string) => void; focus?: string }) {
+  const [cast, setCast] = useState<Character[] | null>(null);
+  useEffect(() => void call<Character[]>('cast_status', { slug }).then(setCast).catch((e) => onError(e.message)), [slug, version]);
+  // Opened on one character: scroll to their card once it is there.
+  // Pictures above it load late and push it down: scroll again once they have.
+  useEffect(() => {
+    if (!cast || !focus) return;
+    const go = () => document.getElementById(`cast-${focus}`)?.scrollIntoView({ block: 'start', behavior: 'smooth' });
+    go();
+    const again = setTimeout(go, 450);
+    return () => clearTimeout(again);
+  }, [!!cast, focus]);
+  if (!cast) return <p class="detail">Reading the cast…</p>;
+  return (
+    <div class="cast-view">
+      <ul class="cast">
+        {cast.map((c) => <Card key={c.key} slug={slug} c={c} onError={onError} focused={c.key === focus} />)}
+      </ul>
+      <Items slug={slug} version={version} onError={onError} focus={focus?.startsWith('item-') ? focus.slice(5) : undefined} />
+    </div>
+  );
+}
+
+type Item = { key: string; name: string; from: { place: string; thing: string } | null; how: 'cut' | 'redraw' | 'paint' | null; icon: Pic; fix: { how?: string; hint?: string; take?: number } | null };
+const HOW = { cut: 'cut from the painting', redraw: 'redrawn by Muse', paint: 'painted by Muse' };
+
+/** The inventory: one icon per story item, with where it comes from; a hint or another take is icon_redo. */
+function Items({ slug, version, onError, focus }: { slug: string; version: number; onError: (m: string) => void; focus?: string }) {
+  const [items, setItems] = useState<Item[] | null>(null);
+  const [hints, setHints] = useState<Record<string, string>>({});
+  useEffect(() => void call<Item[]>('icons_status', { slug }).then(setItems).catch(() => setItems([])), [slug, version]);
+  // Opened on one item (a click on the shelf): scroll to it once the list is there, again once pictures above loaded.
+  useEffect(() => {
+    if (!items || !focus) return;
+    const go = () => document.getElementById(`item-${focus}`)?.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    go();
+    const again = setTimeout(go, 600);
+    return () => clearTimeout(again);
+  }, [!!items, focus]);
+  if (!items?.length) return null;
+  const act = (name: string, input: object) => call(name, { slug, ...input }).catch((e) => onError((e as Error).message));
+  return (
+    <section class="items">
+      <h3>Inventory</h3>
+      <ul>
+        {items.map((it) => (
+          <li key={it.key} id={`item-${it.key}`} class={it.key === focus ? 'focus' : undefined}>
+            {it.icon ? <img src={fileUrl(slug, it.icon.file, it.icon.v)} alt={it.name} /> : <div class="noimg">no icon yet</div>}
+            <div class="body">
+              <strong>{it.name}</strong>
+              <span class="detail">{it.from ? `picked up: ${it.from.place} / ${it.from.thing}` : 'handed over'}{it.how ? ` · ${named(HOW[it.how])}` : ''}</span>
+              <form class="row" onSubmit={(e) => (e.preventDefault(), (hints[it.key] ?? '').trim().length >= 3 && void act('icon_redo', { item: it.key, hint: hints[it.key].trim() }))}>
+                <input value={hints[it.key] ?? it.fix?.hint ?? ''} placeholder="How it should look" title="Your words for the icon, e.g. 'a rusty brass key'. Press Redraw to use them" aria-label={`How ${it.name} should look`} onInput={(e) => setHints({ ...hints, [it.key]: e.currentTarget.value })} />
+                <button type="button" class="ghost small" title={named(it.how === 'cut' ? 'This icon is cut from the painting, so another take comes out the same. Write how it should look and press Redraw.' : `Muse ${it.how === 'paint' ? 'paints' : 'redraws'} the icon again, a new version of the same thing. 1 Muse Image call`)} onClick={() => act('icon_redo', { item: it.key, anotherTake: true })}>Another take</button>
+                <button type="submit" class={`${(hints[it.key] ?? '').trim().length >= 3 ? 'primary' : 'ghost'} small`} title={named('Muse redraws the icon the way you wrote, kept across rebuilds. 1 Muse Image call')}>Redraw</button>
+              </form>
+            </div>
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+function Card({ slug, c, onError, focused }: { slug: string; c: Character; onError: (m: string) => void; focused?: boolean }) {
+  // The voices that fit this character (gender and age seen in the figure) come first; the rest are marked.
+  const [voices, setVoices] = useState<Voice[] | null>(null);
+  const loadVoices = () => voices ?? call<{ voices: Voice[] } | Voice[]>('voice_list', { slug, key: c.key })
+    .then((r) => setVoices(Array.isArray(r) ? r : r.voices)).catch((e) => onError(e.message));
+  const [looks, setLooks] = useState(c.looksNow);
+  const [busy, setBusy] = useState(false);
+  // Opened on this character: it moves right away.
+  const [moving, setMoving] = useState(!!focused && !!(c.rig || c.model || c.sprites));
+  useEffect(() => setLooks(c.looksNow), [c.looksNow]);
+  const act = async (name: string, input: object) => {
+    setBusy(true);
+    try {
+      await call(name, { slug, key: c.key, ...input });
+    } catch (e) {
+      onError((e as Error).message);
+    }
+    setBusy(false);
+  };
+  const changed = looks.trim() !== c.looksNow && looks.trim().length >= 10;
+  const creature = c.body?.upright === false;
+  // What the game has of this character, as small signs; each says what it is on hover.
+  const parts = ([
+    creature && ['paw', 'A creature: moves as one body (hops, squashes, leans), no skeleton'],
+    c.figure && ['figure', `Figure: painted by Muse Image and cut out by SAM${c.moves ? `. In the game it ${c.moves.replace(/^the /, 'is the ')}` : ''}`],
+    c.rig && ['bone', '2D rig: the figure cut into parts that walk; used when there is no 3D model or sprites'],
+    c.model && ['cube', '3D model: built by TRELLIS from four painted sides'],
+    c.sprites && ['film', 'Sprites: painted walk and talk frames, what the game draws first'],
+  ].filter(Boolean)) as Array<[IconName, string]>;
+  return (
+    <li id={`cast-${c.key}`} class={`who ${c.role}${focused ? ' focus' : ''}`}>
+      {c.role !== 'narrator' && (c.figure ? <img src={fileUrl(slug, c.figure.file, c.figure.v)} alt={c.key} loading="lazy" /> : <div class="noimg">not painted yet</div>)}
+      <div class="body">
+        <div class="row">
+          <strong>{c.key}</strong>
+          <span class="badge">{c.role === 'hero' ? 'hero' : c.role === 'player' ? 'hero for another gamepad' : c.role === 'narrator' ? 'narrator' : `NPC · ${c.place}`}</span>
+          <span class="grow" />
+          {parts.length > 0 && <span class="has">{parts.map(([sign, what]) => <span class="sign" title={named(what)}><Icon name={sign} /></span>)}</span>}
+          {c.modelIssue && <span class="detail">Using 2D: {c.modelIssue}</span>}
+          {c.rigIssue && !c.model && !c.sprites && <span class="detail">No 2D walk: {c.rigIssue}</span>}
+          {!!c.spriteIssues?.length && <button type="button" class="ghost small" disabled={busy} title={named(`${c.spriteIssues.join('; ')}. Muse paints new walk and talk sheets over the 3D model, the character stays as painted. Kept across rebuilds. About 2-10 Muse Image calls per direction`)} onClick={() => act('sprites_redo', {})}>New walk sheets</button>}
+          {c.model && c.modelAttempt?.state === 'failed' && <span class="detail">Keeping previous model: {c.modelAttempt.reason}</span>}
+          {c.role !== 'narrator' && c.figure && !c.model && <button type="button" class="ghost small" disabled={busy || !!c.modelJob} title={named(`Muse paints ${c.key} from 4 sides and TRELLIS builds a 3D model${creature ? ': no skeleton, in the game it hops, squashes, leans and blinks as one body' : ''}. Animation settings are chosen automatically and kept across rebuilds.`)} onClick={() => act('cast_animate', {})}>{c.modelJob ? c.modelJob.state === 'queued' ? '3D queued…' : 'Building 3D…' : c.modelIssue ? 'Retry 3D' : 'Animate in 3D'}</button>}
+          {(c.rig || c.model || c.sprites) && <button type="button" class={`ghost small round${moving ? ' on' : ''}`} aria-label={moving ? 'Close the preview' : 'See it move'} title={moving ? 'Close the preview' : 'See it move: walk, stand and talk as the game draws it. Free'} onClick={() => setMoving(!moving)}>{moving ? '■' : '▶'}</button>}
+        </div>
+        {c.role !== 'narrator' && (<>
+          <div class="row" style="margin-bottom:8px">
+            <button type="button" class="ghost small" disabled={busy || !c.figure} onClick={() => void act('faces_prepare', {})}>{c.face?.ready ? 'Refresh speech animation' : 'Prepare speech animation'}</button>
+            {c.face?.ready && <small>{c.face.model3d?.mouth ? `2D + 3D speech ready (${c.face.model3d.method === 'morphs' ? 'facial morphs' : 'painted surfaces'})` : '2D speaking face ready'}</small>}
+            {c.face?.ready && <details class="detail"><summary title="The mouth shapes this character speaks with, cut from its face atlas. Free to look">Mouth shapes</summary><MouthShapes slug={slug} who={c.key} v={Date.parse(c.face.attempt?.at ?? '') || null} /></details>}
+            {c.face?.attempt?.state === 'failed' && <details class="detail"><summary>Speech animation incomplete · previous appearance kept</summary><p>{c.face.attempt.reason}</p></details>}
+          </div>
+          <form class="say" onSubmit={(e) => (e.preventDefault(), changed && void act('cast_redo', { looks: looks.trim() }))}>
+            <textarea rows={3} value={looks} title="How the character looks. Change it and press Repaint" onInput={(e) => setLooks(e.currentTarget.value)} aria-label={`How ${c.key} looks`} />
+            <div class="row">
+              {c.fix?.looks && <span class="detail">your description{c.fix.take ? ` · take ${c.fix.take + 1}` : ''}</span>}
+              <span class="grow" />
+              <button type="button" class="ghost small" disabled={busy} title={named('Muse paints this character again from the same description and SAM cuts the figure out. 1 Muse Image + 1 SAM call. Sprites and the 3D model are not remade')} onClick={() => act('cast_redo', { anotherTake: true })}>Another take</button>
+              <button type="submit" class="primary small" disabled={busy || !changed} title={named(changed ? 'Muse paints the character from your new description, kept across rebuilds. 1 Muse Image + 1 SAM call' : 'Change the description first (at least 10 letters)')}>Repaint</button>
+            </div>
+          </form>
+        </>)}
+        <div class="row voice">
+          {c.voice
+            ? <>
+                <label title="Pick another voice. Their lines are spoken again: ElevenLabs, one call per line of this character">Voice <select onFocus={loadVoices} onMouseDown={loadVoices} disabled={busy} value={c.voice.voice} onChange={(e) => act('voice_set', { voice: e.currentTarget.value })}>
+                  {(voices ?? [{ id: c.voice.voice, name: c.voice.why, sounds: '' }]).map((v) => <option value={v.id} title={[v.name, v.sounds].filter(Boolean).join(' · ')}>{v.fits === false ? '(does not fit) ' : ''}{short(v.name, 32)}{v.sounds ? ` · ${short(v.sounds, 40)}` : ''}</option>)}
+                </select></label>
+                <span class="detail">{c.lines} line{c.lines === 1 ? '' : 's'}{c.flagged ? `, ${c.flagged} misheard` : ''}</span>
+              </>
+            : <span class="detail">{c.lines ? `${c.lines} lines, no voice yet` : 'no spoken lines'}</span>}
+        </div>
+        {c.sample && <div class="sample"><audio controls preload="none" src={fileUrl(slug, c.sample.file)} /><span class="detail">“{c.sample.text}”</span></div>}
+        {!!c.voiceFailures?.length && <p class="detail" role="status">{c.voiceFailures.length} spoken lines unavailable: {c.voiceFailures[0].reason}</p>}
+        {c.voiceWarnings?.map((w) => <p class="detail" role="status">{w}</p>)}
+      </div>
+      {moving && <FigurePreview slug={slug} who={c.key} stamps={c.stamps} />}
+    </li>
+  );
+}
+
+// A designed voice is named by its description; keep the select readable and the whole text in the tooltip.
+function short(text: string, max: number): string {
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max);
+  const stop = Math.max(cut.lastIndexOf(','), cut.lastIndexOf(' '));
+  return `${(stop > max / 2 ? cut.slice(0, stop) : cut).replace(/[,\s]+$/, '')}…`;
+}

package/app/studio/concept-edit.tsx

@@ -0,0 +1,47 @@
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { shrink } from './camera.tsx';
+
+export type ConceptChange = { change?: string; reference?: { name: string; data: string } };
+
+/** A small conversation beside the picture, rather than another setup form. */
+export function ConceptEdit({ label, disabled, onGenerate, onClose, onDraftChange, purpose = 'change' }: {
+  label: string; disabled: boolean; purpose?: 'change' | 'style'; onGenerate: (change: ConceptChange) => void; onClose: () => void; onDraftChange?: () => void;
+}) {
+  const [words, setWords] = useState('');
+  const [reference, setReference] = useState<ConceptChange['reference']>();
+  const [reading, setReading] = useState(false);
+  const [error, setError] = useState('');
+  const picker = useRef<HTMLInputElement>(null);
+  const form = useRef<HTMLFormElement>(null);
+  const uploading = useRef(false);
+  useEffect(() => { onDraftChange?.(); }, [words, reference]);
+  useEffect(() => {
+    form.current?.querySelector('textarea')?.focus({ preventScroll: true });
+    form.current?.scrollIntoView({ block: 'center', behavior: 'instant' });
+  }, []);
+  const add = async (file?: File) => {
+    if (!file || disabled || uploading.current) return;
+    if (!file.type.startsWith('image/')) { setError('Choose an image for this reference.'); return; }
+    uploading.current = true; setReading(true); setError('');
+    try {
+      const data = await shrink(file);
+      if (data.length > 8_000_000) throw new Error('This picture is too large. Try a smaller image.');
+      setReference({ name: (file.name || 'pasted-image').slice(0, 120), data });
+    } catch (e) { setError((e as Error).message); }
+    finally { uploading.current = false; setReading(false); }
+  };
+  return <form ref={form} class="concept-edit" aria-label={`Change ${label}`} onSubmit={e => {
+    e.preventDefault();
+    if (!disabled && !reading && (words.trim() || reference)) onGenerate({ ...(words.trim() && { change: words.trim() }), ...(reference && { reference }) });
+  }} onPaste={e => {
+    const file = [...(e.clipboardData?.files ?? [])].find(f => f.type.startsWith('image/'));
+    if (file) { e.preventDefault(); void add(file); }
+  }}>
+    <label>{purpose === 'style' ? 'What should your world look like?' : 'What would you change?'}<textarea autoFocus aria-label={`Changes for ${label}`} value={words} maxLength={purpose === 'style' ? 500 : 1200} rows={3} disabled={disabled} placeholder={purpose === 'style' ? 'Blue ink, grainy paper, warm lantern light…' : 'A bigger hat, warmer colours…'} onInput={e => setWords(e.currentTarget.value)} /></label>
+    <p>{purpose === 'style' ? 'Describe a look, or paste a picture for its colours and textures.' : 'Describe the picture, or paste a reference here.'}</p>
+    {reference && <div class="concept-reference"><button type="button" class="ghost bare" data-lightbox={reference.data} aria-label="Enlarge reference"><img src={reference.data} alt="Your reference" /></button><button type="button" class="ghost small" disabled={disabled || reading} onClick={() => setReference(undefined)}>Remove</button></div>}
+    <input hidden ref={picker} type="file" accept="image/*" aria-label={`Reference for ${label}`} onChange={e => { void add(e.currentTarget.files?.[0]); e.currentTarget.value = ''; }} />
+    <div class="concept-edit-tools"><button type="button" class="ghost small" disabled={disabled || reading} onClick={() => picker.current?.click()}>{reading ? 'Reading picture…' : '+ Picture'}</button><button type="button" class="ghost small" disabled={disabled || reading} onClick={onClose}>Cancel</button><button type="submit" class="primary small" disabled={disabled || reading || !words.trim() && !reference}>{purpose === 'style' ? disabled ? 'Preparing your style…' : 'Preview my style' : 'Regenerate'}</button></div>
+    {error && <p class="error" role="alert">{error}</p>}
+  </form>;
+}

package/app/studio/creator-idea.tsx

@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'preact/hooks';
+import { CreativeChoices } from '../src/world/idea-review.ts';
+import { fileUrl } from './api.ts';
+
+type CreatorBrief = { idea: string; choices?: CreativeChoices };
+
+/** The build keeps its full instructions; the conversation shows what the person actually wrote. */
+export function useCreatorBrief(slug: string): CreatorBrief | null {
+  const [saved, setSaved] = useState<{ slug: string; brief: CreatorBrief } | null>(null);
+  useEffect(() => {
+    const controller = new AbortController();
+    const options = { cache: 'no-store' as const, signal: controller.signal };
+    const version = Date.now();
+    void (async () => {
+      const source = await fetch(fileUrl(slug, 'creative-brief.json', version), options)
+        .then(r => r.ok ? r.json() : null).catch(() => null);
+      let brief: CreatorBrief;
+      if (source && typeof source.idea === 'string' && source.idea.trim()) {
+        const choices = CreativeChoices.safeParse(source.choices);
+        brief = { idea: source.idea.trim(), ...(choices.success && { choices: choices.data }) };
+      } else {
+        const idea = await fetch(fileUrl(slug, 'idea.txt', version), options)
+          .then(r => r.ok ? r.text() : '').catch(() => '');
+        brief = { idea: idea.trim() };
+      }
+      if (!controller.signal.aborted) setSaved({ slug, brief });
+    })();
+    return () => controller.abort();
+  }, [slug]);
+  return saved?.slug === slug ? saved.brief : null;
+}
+
+export function CreatorIdea({ brief }: { brief: CreatorBrief }) {
+  const choices = brief.choices;
+  const hasChoices = choices && (choices.answers.length > 0 || choices.style || choices.note);
+  return <div class="creator-idea">
+    <div class="idea-bubble">{brief.idea}</div>
+    {hasChoices && <details class="creator-choices">
+      <summary>Your choices{choices.answers.length > 0 && <span> · {choices.answers.length} {choices.answers.length === 1 ? 'answer' : 'answers'}</span>}{choices.style && <span> · visual style</span>}</summary>
+      <dl>{choices.answers.map(a => <div><dt>{a.question}</dt><dd>{a.answer}</dd></div>)}
+        {choices.style && <div><dt>Visual style</dt><dd>{choices.style}</dd></div>}
+        {choices.note && <div><dt>Your note</dt><dd>{choices.note}</dd></div>}
+      </dl>
+    </details>}
+  </div>;
+}

package/app/studio/custom-look.tsx

@@ -0,0 +1,36 @@
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { call } from './api.ts';
+import { ConceptEdit, type ConceptChange } from './concept-edit.tsx';
+import type { ReviewInput } from './idea-review.tsx';
+
+export type Look = { title: string; description: string; reference?: string };
+
+export function CustomLook({ input, scene, busy, onChoose, onClose }: {
+  input: ReviewInput; scene: string; busy: boolean; onChoose: (look: Look) => void; onClose: () => void;
+}) {
+  const [draft, setDraft] = useState<{ look: Look; image: string }>();
+  const [working, setWorking] = useState(false);
+  const [error, setError] = useState('');
+  const active = useRef(true), pending = useRef(false);
+  useEffect(() => () => { active.current = false; }, []);
+  const preview = async ({ change, reference }: ConceptChange) => {
+    if (pending.current || busy) return;
+    pending.current = true; setWorking(true); setError('');
+    try {
+      const look = await call<Look>('idea_style', { words: change ?? '', ...(reference && { reference }) });
+      const { image } = await call<{ image: string }>('idea_preview', { idea: input.idea, scene, style: look.description, ...(look.reference && { styleReference: look.reference }), references: input.photos.slice(0, 4).map(p => p.data) });
+      if (active.current) setDraft({ look, image });
+    } catch (e) { if (active.current) setError((e as Error).message); }
+    finally { pending.current = false; if (active.current) setWorking(false); }
+  };
+  return <section class="custom-look" aria-label="Your own style" aria-busy={working}>
+    <ConceptEdit label="your style" purpose="style" disabled={busy || working} onGenerate={preview} onClose={onClose} onDraftChange={() => setDraft(undefined)} />
+    {error && <p class="error" role="alert">{error}</p>}
+    {working && <p role="status"><span class="review-spinner" aria-hidden="true" /> Sketching your style…</p>}
+    {draft && <div class="custom-look-preview">
+      <button type="button" class="ghost bare" data-lightbox={draft.image} aria-label="Enlarge your style preview"><img src={draft.image} alt={draft.look.title} /></button>
+      <p>{draft.look.description}</p>
+      <button type="button" class="amber" disabled={busy || working} onClick={() => onChoose(draft.look)}>Use this style</button>
+    </div>}
+  </section>;
+}

package/app/studio/faces-setup.tsx

@@ -0,0 +1,28 @@
+import { useEffect, useState } from 'preact/hooks';
+import { call } from './api.ts';
+
+type FacesState = { enabled: boolean; env: string | null };
+
+/** Setup: talking mouths on or off. Off by default: barely visible in play, costly in calls and build time. */
+export function FacesSetup() {
+  const [state, setState] = useState<FacesState | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState('');
+  useEffect(() => { void call<FacesState>('faces_get').then(setState).catch((e) => setError(e.message)); }, []);
+  const toggle = async (enabled: boolean) => {
+    setBusy(true); setError('');
+    try { setState(await call<FacesState>('faces_set', { enabled })); }
+    catch (e) { setError((e as Error).message); }
+    finally { setBusy(false); }
+  };
+  return <section class="budget blender" aria-label="Talking mouths">
+    <h2>Talking mouths</h2>
+    <label class="switch-row" title="Muse paints mouth shapes for each character's portrait and Spark checks them: about $0.20 and a few minutes a character">
+      <span>Animate lips when characters speak</span>
+      <input type="checkbox" role="switch" checked={!!state?.enabled} disabled={!state || busy || state.env !== null} onChange={(e) => void toggle(e.currentTarget.checked)} />
+    </label>
+    <p class="note">{state?.enabled ? 'On: after every place plays, each speaking character gets mouth shapes on its portrait (Muse Image, Spark).' : 'Off: characters speak with voice and gestures; builds skip the faces step. Mouths made earlier still play.'}</p>
+    {state?.env != null && <p class="note">Set by DIORAMA_FACES={state.env}. Unset it and restart Studio to switch it here.</p>}
+    {error && <p class="error" role="alert">{error}</p>}
+  </section>;
+}

package/app/studio/favicon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="7" fill="#f2ece1"/>
+  <defs><clipPath id="a"><path d="M8.6 27.4V15.2a7.4 7.4 0 0 1 14.8 0v12.2Z"/></clipPath></defs>
+  <g clip-path="url(#a)">
+    <rect width="32" height="32" fill="#3d4b7c"/>
+    <circle cx="19.2" cy="13.2" r="2.6" fill="#e0a050"/>
+    <path d="M6 22 C10 18.5 14 18.5 18 21 C21 23 24 22 27 19.5 V29 H6Z" fill="#f2ece1" opacity=".45"/>
+    <path d="M6 25.6 C11 22.4 16 22.6 21 24.8 C23 25.8 25 25.4 27 24.8 V29 H6Z" fill="#f2ece1"/>
+  </g>
+  <path d="M6.4 28.2V15.2a9.6 9.6 0 0 1 19.2 0v13Z" fill="none" stroke="#2b2723" stroke-width="2.6" stroke-linejoin="round"/>
+</svg>