@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/world/language.ts

@@ -0,0 +1,116 @@
+// A world told in another language: every word the player reads or hears (title, pitch, names, the whole story)
+// translated in one Spark pass, so names stay the same everywhere they appear. What the painters read (style,
+// shows, mood, looks, a change's looks) is English already and stays; keys and flags never change, so the
+// puzzles, masks, paintings and sounds all still fit. The voices are cast again for the new language afterwards.
+import fs from 'node:fs';
+import { z } from 'zod';
+import { askSparkJson } from '../meta/spark.ts';
+import type { Memo } from '../meta/memo.ts';
+import { soundQuality } from '../sound/cost.ts';
+import { languageKey } from '../sound/language.ts';
+import { needsDesign, storyLines, Voices } from '../sound/voices.ts';
+import type { Story } from '../story/schema.ts';
+import type { WorldFiles } from './files.ts';
+import type { World } from './schema.ts';
+
+/** Story fields the player reads or hears. A change's `looks` is for the painter: it stays English. */
+const STORY_TEXT = new Set(['intro', 'say', 'says', 'text', 'title', 'name', 'nope']);
+
+/** Every player-facing text of a world and its story, by an id that says where it lives. */
+export function worldTexts(world: World, story: Story | null): Record<string, string> {
+  const out: Record<string, string> = { 'world.title': world.title, 'world.pitch': world.pitch };
+  for (const [key, name] of Object.entries(world.names ?? {})) out[`names.${key}`] = name;
+  const walk = (node: unknown, path: string[]) => {
+    if (Array.isArray(node)) node.forEach((n, i) => walk(n, [...path, String(i)]));
+    else if (node && typeof node === 'object') {
+      for (const [k, v] of Object.entries(node)) {
+        if (typeof v === 'string') {
+          if (STORY_TEXT.has(k) && !(path[0] === 'changes')) out[`story.${[...path, k].join('.')}`] = v;
+        } else walk(v, [...path, k]);
+      }
+    }
+  };
+  if (story) walk(story, []);
+  return out;
+}
+
+/** The world and story with the translated texts put back at their ids. */
+export function applyWorldTexts(world: World, story: Story | null, texts: Record<string, string>, language: string): { world: World; story: Story | null } {
+  const w: World = structuredClone(world);
+  const s: Story | null = story && structuredClone(story);
+  for (const [id, text] of Object.entries(texts)) {
+    const [head, ...rest] = id.split('.');
+    if (head === 'world') (w as Record<string, unknown>)[rest[0]] = text;
+    else if (head === 'names') w.names = { ...w.names, [rest.join('.')]: text };
+    else if (head === 'story' && s) {
+      let at: unknown = s;
+      const last = rest.pop()!;
+      for (const p of rest) at = Array.isArray(at) ? at[Number(p)] : (at as Record<string, unknown>)[p];
+      if (at && typeof at === 'object') (at as Record<string, unknown>)[last] = text;
+    }
+  }
+  if (languageKey(language) === 'en') delete w.language;
+  else w.language = language;
+  return { world: w, story: s };
+}
+
+const Answer = z.object({ texts: z.record(z.string(), z.string()) });
+
+/**
+ * One Spark pass over all the texts, so a name reads the same in the title, the dialogue and the inventory.
+ * Ids missing from the answer are asked for once more, with the names already chosen; an empty answer throws.
+ */
+export async function translateTexts(memo: Memo, texts: Record<string, string>, from: string, to: string, kids: boolean): Promise<Record<string, string>> {
+  const ask = (todo: Record<string, string>, names: Record<string, string>) => askSparkJson(memo, {
+    label: `language:${languageKey(to)}`,
+    schema: Answer,
+    prompt: `Translate the player-facing text of a point-and-click adventure game from ${from} to ${to}.
+Write it as a native ${to} game writer would${kids ? ' for children aged 5 to 7, who hear every line read aloud' : ''}: natural, idiomatic and warm, not word for word. Keep each line's meaning, mood and humour, and keep it about as short (never longer by more than a few words).
+- Names of characters, places and items ("names.*", items' "name"): give each a natural ${to} name that keeps the idea or pun of the original (a cat named after butter keeps a buttery name). Use exactly the same name every time it appears in any line, with the same capitalisation style as the original (a lowercase item name stays lowercase).
+- A line that is a statement stays a statement; a question stays a question. Keep sound tags in square brackets ([laughs], [whispers]) exactly as they are, untranslated.
+- Numbers, riddles and wordplay must still work in ${to}: adapt them, keep the answer the same.
+- Every text must be fully in ${to}: no ${from} words left, except a name that is the same in both languages.
+${Object.keys(names).length ? `Names already chosen (use them): ${JSON.stringify(names)}\n` : ''}Texts (id: text): ${JSON.stringify(todo)}
+Reply with JSON only: {"texts": {"<the same id>": "<${to} text>", ...}} with every id above exactly once.`,
+  });
+  const first = (await ask(texts, {})).texts;
+  const done = Object.fromEntries(Object.keys(texts).filter((id) => first[id]?.trim()).map((id) => [id, first[id].trim()]));
+  const missing = Object.fromEntries(Object.entries(texts).filter(([id]) => !done[id]));
+  if (Object.keys(missing).length) {
+    const names = Object.fromEntries(Object.entries(done).filter(([id]) => id.startsWith('names.') || /\.name$/.test(id)));
+    const again = (await ask(missing, names)).texts;
+    for (const id of Object.keys(missing)) if (again[id]?.trim()) done[id] = again[id].trim();
+  }
+  const still = Object.keys(texts).filter((id) => !done[id]);
+  if (still.length) throw new Error(`Spark left ${still.length} text(s) untranslated: ${still.slice(0, 5).join(', ')}`);
+  return done;
+}
+
+/** A person's voice wish written for the old language ("Native Polish speaker…") says the new one instead. */
+export function relanguage(text: string, from: string, to: string): string {
+  return text.replace(new RegExp(`\\b${from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'gi'), to);
+}
+
+export type LanguagePlan = { from: string; to: string; same: boolean; texts: number; lines: number; characters: number; credits: number; designs: string[]; quality: 'draft' | 'final' };
+
+/**
+ * What a change of language redoes: one Spark pass over the texts, then every spoken line read again (about one
+ * ElevenLabs credit a character in final quality, half in draft) and a Voice Design for each child, teen or old speaker.
+ * The lines are counted in the old language: a translation is about as long.
+ */
+export function languagePlan(files: WorldFiles, world: World, story: Story | null, language: string): LanguagePlan {
+  const from = world.language ?? 'English';
+  const same = languageKey(from) === languageKey(language);
+  const kids = world.audience === 'kids';
+  const lines = story ? storyLines(world, story, kids) : [];
+  const characters = lines.reduce((n, l) => n + l.text.length, 0);
+  const quality = soundQuality();
+  const voices = fs.existsSync(files.path('voices.json')) ? Voices.safeParse(files.readJson(files.path('voices.json'))) : undefined;
+  const designs = voices?.success ? Object.entries(voices.data.cast).filter(([, c]) => c.profile && needsDesign(c.profile)).map(([k]) => k) : [];
+  return { from, to: language, same, texts: Object.keys(worldTexts(world, story)).length, lines: lines.length, characters, credits: Math.round(characters * (quality === 'final' ? 1 : 0.5)), designs, quality };
+}
+
+export const planLine = (p: LanguagePlan) => (p.same
+  ? `already in ${p.to}: the texts stay; the voices are read again only where they are not in ${p.to} yet`
+  : `${p.texts} texts translated from ${p.from} to ${p.to} in one Spark pass (cents); then ${p.lines} spoken lines read again, about ${p.characters} characters, ~${p.credits} ElevenLabs credits (${p.quality})`
+    + `${p.designs.length ? `, plus a new designed voice for ${p.designs.join(', ')}` : ''}; paintings, masks, sounds and puzzles stay`);

package/app/src/world/photo-limits.ts

@@ -0,0 +1,2 @@
+/** Shared by the start form and world_new: enough for a classroom's drawings. */
+export const MAX_WORLD_PHOTOS = 32;

package/app/src/world/pool.ts

@@ -0,0 +1,41 @@
+// Work that may run side by side, a few at a time: the cast's 3D bodies and faces, each character on its own.
+
+/** Runs `work` on every item, at most `limit` at once; results keep the items' order. Errors are kept per item. */
+export async function mapLimit<T, R>(items: readonly T[], limit: number, work: (item: T, index: number) => Promise<R>): Promise<PromiseSettledResult<R>[]> {
+  const results: PromiseSettledResult<R>[] = new Array(items.length);
+  let next = 0;
+  const runner = async () => {
+    while (next < items.length) {
+      const i = next++;
+      try {
+        results[i] = { status: 'fulfilled', value: await work(items[i], i) };
+      } catch (reason) {
+        results[i] = { status: 'rejected', reason };
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, runner));
+  return results;
+}
+
+const open = new Map<string, number>();
+const waiting = new Map<string, Array<() => void>>();
+
+/** At most `limit` of `lane`'s work at once in this process (a Hugging Face Space queue, a local GPU). */
+export async function inLane<T>(lane: string, limit: number, work: () => Promise<T>): Promise<T> {
+  if ((open.get(lane) ?? 0) >= limit) await new Promise<void>((go) => (waiting.get(lane) ?? waiting.set(lane, []).get(lane)!).push(go));
+  else open.set(lane, (open.get(lane) ?? 0) + 1);
+  try {
+    return await work();
+  } finally {
+    const go = waiting.get(lane)?.shift();
+    if (go) go();
+    else open.set(lane, (open.get(lane) ?? 1) - 1);
+  }
+}
+
+/** How many characters are worked on at once: DIORAMA_CAST_LANES, default 3. */
+export function castLanes(): number {
+  const n = Number(process.env.DIORAMA_CAST_LANES);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : 3;
+}

package/app/src/world/schedule.ts

@@ -0,0 +1,64 @@
+// What each build step waits for. The build is not a line of steps but a web: every place goes through its own
+// steps as fast as it can, and the world's steps (cast, voices, sound...) start as soon as what they read is there.
+// Plain data, so the Studio can work out the time left from the same web the build runs.
+
+export const STEPS = ['world', 'story', 'layout', 'paint', 'masks', 'plates', 'icons', 'derive', 'backdrop', 'weather', 'reactions', 'cast', 'model', 'sprites', 'sound', 'voices', 'faces', 'verify'] as const;
+export type Step = (typeof STEPS)[number];
+/** The steps that work place by place; `--place` runs only these, for that one place. */
+export const PLACE_STEPS: readonly Step[] = ['layout', 'paint', 'masks', 'plates', 'derive', 'backdrop', 'weather', 'reactions', 'verify'];
+
+/**
+ * What a step reads, as steps. A place step needs the same place's step before it (PLACE_STEPS order) plus these;
+ * a place step named in a world step's list means every place has finished it (or was set aside).
+ * - layout and paint read world.json only: places are painted while Spark still writes the story.
+ * - plates takes the story's carried-off things out of the painting.
+ * - icons: an item is cut from the painting of the place it is picked up in, once that place has masks
+ *   (the build runs it per place; items picked up nowhere are painted once the story is there).
+ * - cast reads the looks in world.json, so the figures are painted alongside the places.
+ * - model needs the story (who speaks, patrols or travels); sprites need that plan and every place's geometry.
+ *   NPC stage flags/conditions travel with story.json; they need no separate build step.
+ * - sound plans from every place's painting brief and floors; voices from the story's lines.
+ */
+export const NEEDS: Record<Step, readonly Step[]> = {
+  world: [],
+  story: ['world'],
+  layout: ['world'],
+  paint: [],
+  masks: [],
+  plates: ['story'],
+  icons: ['story', 'masks'],
+  derive: [],
+  backdrop: [],
+  weather: [],
+  reactions: ['story'],
+  cast: ['world'],
+  model: ['story', 'cast'],
+  sprites: ['model', 'derive'],
+  sound: ['story', 'paint'],
+  voices: ['story'],
+  // Last: talking mouths are polish. They start once every place is verified, so they never hold up a playable game.
+  faces: ['cast', 'sprites', 'voices', 'verify'],
+  verify: [],
+};
+
+/** Every step `step` waits for: its own list, plus the place step before it. */
+export function needs(step: Step): Step[] {
+  const i = PLACE_STEPS.indexOf(step);
+  return [...(i > 0 ? [PLACE_STEPS[i - 1]] : []), ...NEEDS[step]];
+}
+
+/**
+ * Seconds until every step in `plan` is done, when each starts as soon as what it needs is: the longest chain,
+ * not the sum. `left(step)` is what a step still takes (0 when done); steps outside the plan count as done.
+ */
+export function timeLeft(plan: readonly string[], left: (step: Step) => number): number {
+  const end = new Map<Step, number>();
+  const finish = (step: Step): number => {
+    if (end.has(step)) return end.get(step)!;
+    const after = Math.max(0, ...needs(step).filter((s) => plan.includes(s)).map(finish));
+    const at = after + (plan.includes(step) ? left(step) : 0);
+    end.set(step, at);
+    return at;
+  };
+  return Math.max(0, ...STEPS.filter((s) => plan.includes(s)).map(finish));
+}

package/app/src/world/schema.ts

@@ -0,0 +1,74 @@
+// world.json: the places of a world and how they connect. Spark writes it, people may edit it.
+import { z } from 'zod';
+
+export const Slug = z.string().regex(/^[a-z][a-z0-9-]*$/, 'lowercase-kebab key');
+
+export const Thing = z.object({
+  key: Slug,
+  role: z.enum(['prop', 'exit', 'item', 'npc']),
+  looks: z.string().min(3),
+});
+
+export const Place = z.object({
+  key: Slug,
+  shows: z.string().min(10),
+  mood: z.string().min(3),
+  things: z.array(Thing).min(1).max(10),
+  exits: z.array(z.object({ to: Slug, via: Slug })),
+  /** Props the person took off the list (corrections.json, not world.json): the story's look lines on them are never clicked. */
+  taken: z.array(Slug).optional(),
+});
+
+export const World = z.object({
+  title: z.string().min(1),
+  pitch: z.string().min(10),
+  style: z.string().min(10),
+  start: Slug,
+  hero: z.object({ key: Slug, looks: z.string().min(10) }),
+  places: z.array(Place).min(1).max(8),
+  /** The language the game's text is written and voiced in, as a name ("Polish"); English when left out. */
+  language: z.string().min(2).optional(),
+  /** Who plays: "kids" are 5 to 7 and cannot read yet, so the story is gentler, simpler and heard. */
+  audience: z.enum(['kids']).optional(),
+  /** What the players call the hero and each npc, in the world's language ("Smok Zielek" in a Polish world); else a name made from the key. */
+  names: z.record(z.string(), z.string().min(1).max(40)).optional(),
+});
+
+export type World = z.infer<typeof World>;
+export type Place = z.infer<typeof Place>;
+
+/** What a schema can't say: exits must lead somewhere and back, and every place must be reachable. */
+export function worldIssues(world: World): string[] {
+  const issues: string[] = [];
+  const byKey = new Map(world.places.map((p) => [p.key, p]));
+  if (byKey.size < world.places.length) issues.push('place keys repeat');
+  if (!byKey.has(world.start)) issues.push(`start "${world.start}" is not a place`);
+  for (const place of world.places) {
+    const keys = place.things.map((t) => t.key);
+    if (new Set(keys).size < keys.length) issues.push(`${place.key}: thing keys repeat`);
+    for (const exit of place.exits) {
+      const target = byKey.get(exit.to);
+      const via = place.things.find((t) => t.key === exit.via);
+      if (!target) issues.push(`${place.key}: exit leads to unknown place "${exit.to}"`);
+      if (!via) issues.push(`${place.key}: exit uses "${exit.via}", which is not one of its things`);
+      else if (via.role !== 'exit') issues.push(`${place.key}: "${exit.via}" is used as an exit, so its role must be "exit"`);
+      if (target && !target.exits.some((back) => back.to === place.key)) issues.push(`${exit.to} has no exit back to ${place.key}`);
+    }
+  }
+  const reached = new Set<string>();
+  const visit = (key: string) => {
+    if (reached.has(key) || !byKey.has(key)) return;
+    reached.add(key);
+    byKey.get(key)!.exits.forEach((e) => visit(e.to));
+  };
+  visit(world.start);
+  for (const place of world.places) if (!reached.has(place.key)) issues.push(`${place.key} cannot be reached from ${world.start}`);
+  return issues;
+}
+
+export function checkWorld(raw: unknown): { world?: World; issues: string[] } {
+  const parsed = World.safeParse(raw);
+  if (!parsed.success) return { issues: parsed.error.issues.map((i) => `${i.path.join('.') || 'world'}: ${i.message}`) };
+  const issues = worldIssues(parsed.data);
+  return issues.length ? { issues } : { world: parsed.data, issues };
+}

package/app/src/world/sketch.ts

@@ -0,0 +1,81 @@
+// A reviewed world plan is immutable. Only its selected visual takes vary before publication.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { inputHash } from '../meta/memo.ts';
+import { ActionError, type ActionContext } from '../actions/registry.ts';
+import { WorldFiles } from './files.ts';
+import { type World, Slug } from './schema.ts';
+import { type CreativeChoices, refinedIdea } from './idea-review.ts';
+import { videoDir } from './video.ts';
+
+export const SketchId = z.string().regex(/^[a-f0-9]{32}$/);
+export const SketchApproval = z.object({ id: SketchId, selections: z.record(z.number().int().min(0).max(9)) });
+export type SketchApproval = z.infer<typeof SketchApproval>;
+export type SketchInput = { idea: string; choices?: CreativeChoices; photos?: Array<{ name: string; data: string }>; videos?: string[]; places?: number; language?: string; slug?: string };
+export type SketchAsset = { key: string; kind: 'character' | 'place'; label: string; role: 'hero' | 'npc' | 'place'; looks: string };
+export type Sketch = { id: string; title: string; pitch: string; assets: SketchAsset[] };
+export type SketchRecord = { fingerprint: string; slug: string; worldHash: string; publication?: { slug: string; selections: string; result?: unknown } };
+export const sketchFiles = (root: string, id: string) => new WorldFiles(SketchId.parse(id), path.join(root, '.start', 'sketches'));
+export const sketchFingerprint = (input: SketchInput) => inputHash(JSON.stringify({ idea: input.idea, choices: input.choices ?? null, photos: input.photos ?? [], videos: input.videos ?? [], places: input.places ?? null, language: input.language ?? null }));
+
+export function sketchAssets(world: World): SketchAsset[] {
+  const people = [world.hero, ...world.places.flatMap(p => p.things.filter(t => t.role === 'npc'))];
+  return [
+    ...[...new Map(people.map(p => [p.key, p])).values()].map(p => ({ key: p.key, kind: 'character' as const, label: world.names?.[p.key] ?? p.key.replace(/-/g, ' '), role: p.key === world.hero.key ? 'hero' as const : 'npc' as const, looks: p.looks })),
+    ...world.places.map(p => ({ key: p.key, kind: 'place' as const, label: world.names?.[p.key] ?? p.key.replace(/-/g, ' '), role: 'place' as const, looks: `${p.shows}. ${p.mood}` })),
+  ];
+}
+export const assetId = (asset: Pick<SketchAsset, 'kind' | 'key'>) => `${asset.kind}:${asset.key}`;
+export const sketchImagePath = (files: WorldFiles, asset: Pick<SketchAsset, 'kind' | 'key'>, take: number) => files.path('concepts', asset.kind, `${Slug.parse(asset.key)}-${take}.png`);
+
+/** Clean, unwatermarked reference. The PREVIEW label belongs to the UI, never to the painting. */
+export function approvedConcept(files: WorldFiles, kind: SketchAsset['kind'], key: string): Buffer | undefined {
+  const file = files.path('concepts', kind, `${Slug.parse(key)}.png`);
+  return fs.existsSync(file) ? fs.readFileSync(file) : undefined;
+}
+
+const publishing = new Map<string, Promise<unknown>>();
+export async function publishSketch(ctx: ActionContext, input: SketchInput, approval: SketchApproval): Promise<unknown> {
+  const files = sketchFiles(ctx.root, approval.id), lock = files.dir;
+  // Serialize conflicting submissions as well as double clicks; only one world can own this approval.
+  const previous = publishing.get(lock);
+  if (previous) { await previous.catch(() => {}); return publishSketch(ctx, input, approval); }
+  const task = (async () => {
+    const record = files.readJson(files.path('sketch.json')) as SketchRecord;
+    if (record.fingerprint !== sketchFingerprint(input)) throw new ActionError(409, 'Your idea changed. Preview it again before building this version.');
+    const worldBytes = fs.readFileSync(files.path('world.json'));
+    if (record.worldHash !== inputHash(worldBytes)) throw new ActionError(409, 'The world plan changed. Preview it again.');
+    const world = files.world(), assets = sketchAssets(world);
+    if (Object.keys(approval.selections).length !== assets.length || assets.some(a => !Number.isInteger(approval.selections[assetId(a)]))) throw new ActionError(409, 'Choose a preview for every character and place, or skip the preview.');
+    for (const a of assets) if (!fs.existsSync(sketchImagePath(files, a, approval.selections[assetId(a)]))) throw new ActionError(409, `The preview for ${a.label} is not ready yet.`);
+    const selectionHash = inputHash(JSON.stringify(assets.map(a => [assetId(a), approval.selections[assetId(a)]])));
+    if (record.publication) {
+      if (record.publication.selections !== selectionHash || input.slug && input.slug !== record.publication.slug) throw new ActionError(409, 'This preview has already been used to build a different selection.');
+      if (record.publication.result) return record.publication.result;
+    } else {
+      const base = Slug.safeParse(input.slug ?? record.slug);
+      let name = base.success ? base.data : 'my-world', n = 2;
+      const first = name;
+      if (input.slug && fs.existsSync(path.join(ctx.root, name))) throw new ActionError(409, `${name} already exists: pick another name`);
+      while (fs.existsSync(path.join(ctx.root, name))) name = `${first}-${n++}`;
+      const dest = new WorldFiles(`publish-${approval.id}`, path.join(ctx.root, '.start'));
+      // Retain all paid concepts and source drawings, but never make the temporary folder a visible world.
+      fs.cpSync(files.dir, dest.dir, { recursive: true });
+      for (const a of assets) dest.write(dest.path('concepts', a.kind, `${a.key}.png`), fs.readFileSync(sketchImagePath(files, a, approval.selections[assetId(a)])));
+      dest.write(dest.path('approved-sketch.json'), { ...approval, approvedAt: new Date().toISOString() });
+      for (const id of input.videos ?? []) fs.cpSync(videoDir(ctx.root, id), dest.path('videos', id), { recursive: true });
+      fs.renameSync(dest.dir, path.join(ctx.root, name));
+      record.publication = { slug: name, selections: selectionHash };
+      files.write(files.path('sketch.json'), record);
+    }
+    const name = record.publication.slug;
+    const job = await ctx.jobs.start(name, ['build', name, refinedIdea(input.idea, input.choices), '--from', 'story'], 'build approved world > verify', ctx.by);
+    const result = { slug: name, title: world.title, places: world.places.length, language: world.language ?? 'English', job };
+    record.publication.result = result;
+    files.write(files.path('sketch.json'), record);
+    return result;
+  })();
+  publishing.set(lock, task);
+  try { return await task; } finally { if (publishing.get(lock) === task) publishing.delete(lock); }
+}

package/app/src/world/style-plan.ts

@@ -0,0 +1,90 @@
+// What changing a world's style redoes, and what that costs: the steps per scope, and an estimate of the model
+// calls from what those steps sent when this world was built (a rough table when it has no record yet).
+import fs from 'node:fs';
+import { readBudget } from '../actions/budget.ts';
+import { players } from './drawings.ts';
+import type { WorldFiles } from './files.ts';
+import type { World } from './schema.ts';
+
+export const SCOPES = ['world', 'place', 'cast'] as const;
+export type Scope = (typeof SCOPES)[number];
+
+/** The place steps a new painting runs again; the restyle edit takes paint's place. Sound and voices stay as they are. */
+export const PLACE_REDO = ['paint', 'masks', 'plates', 'icons', 'derive', 'backdrop', 'weather', 'reactions', 'verify'] as const;
+/** The character steps; model and sprites only for those who had them. */
+export const CAST_REDO = ['cast', 'model', 'sprites', 'faces'] as const;
+
+type Calls = Record<string, number>;
+/** Calls one place (or one character) costs per step when the world has no record of its own. */
+const ROUGH: Record<string, Calls> = {
+  paint: { spark: 2, muse: 2 }, masks: { spark: 1, sam: 8 }, plates: { muse: 1 }, icons: { muse: 1 }, derive: { spark: 3 },
+  backdrop: { muse: 1, sam: 2 }, weather: { spark: 1 }, reactions: { spark: 1 }, verify: {},
+  cast: { muse: 1, sam: 1 }, model: { muse: 3 }, sprites: { muse: 5 }, faces: { spark: 4, muse: 2 },
+};
+
+/** Everyone the cast step paints: the hero, each NPC and the heroes for more gamepads. */
+export const castKeys = (world: World, files: WorldFiles) => [...new Set([world.hero.key, ...world.places.flatMap((p) => p.things.filter((t) => t.role === 'npc').map((t) => t.key)), ...players(files).map((p) => p.key)])];
+
+export type StylePlan = {
+  scope: Scope;
+  places: string[];
+  cast: string[];
+  /** Of the cast, who has a 3D model and sprite sheets to make again. */
+  models: string[];
+  sprites: string[];
+  faces: string[];
+  calls: Calls;
+  usd: number | null;
+  minutes: number;
+};
+
+export function stylePlan(files: WorldFiles, world: World, scope: Scope, key?: string): StylePlan {
+  const places = scope === 'world' ? world.places.map((p) => p.key) : scope === 'place' ? [key!] : [];
+  const cast = scope === 'place' ? [] : scope === 'cast' && key ? [key] : castKeys(world, files);
+  const painted = places.filter((p) => fs.existsSync(files.place(p, 'painting.png')));
+  const figures = cast.filter((k) => fs.existsSync(files.path('cast', `${k}-painting.png`)));
+  const models = figures.filter((k) => fs.existsSync(files.path('cast', k, 'model', 'model.json')));
+  const sprites = models.filter((k) => fs.existsSync(files.path('cast', k, 'sprites', 'sprites.json')));
+  const faces = figures.filter((k) => fs.existsSync(files.path('cast', k, 'face.json')));
+  let log: { steps?: Record<string, { seconds?: number; sent?: Calls }> } = {};
+  try {
+    log = JSON.parse(fs.readFileSync(files.path('build.json'), 'utf8'));
+  } catch {}
+  const calls: Calls = {};
+  let seconds = 0;
+  // What a step sent for the whole world, shared out over the `of` it made then; the rough table is per place or character.
+  const add = (step: string, count: number, of: number) => {
+    const sent = log.steps?.[step]?.sent;
+    const own = !!sent && Object.values(sent).some((n) => n > 0);
+    const share = own ? count / Math.max(1, of) : count;
+    for (const [m, n] of Object.entries(own ? sent : ROUGH[step] ?? {})) calls[m] = (calls[m] ?? 0) + n * share;
+    // Places and characters are made side by side: a step takes about as long for one as for all.
+    seconds += log.steps?.[step]?.seconds ?? 60;
+  };
+  if (painted.length) for (const step of PLACE_REDO) add(step, painted.length, world.places.length);
+  if (figures.length) add('cast', figures.length, castKeys(world, files).length);
+  // Model and sprites ran for fewer characters than the cast (those who walk and talk): shared out over theirs.
+  const had = (part: string) => castKeys(world, files).filter((k) => fs.existsSync(files.path('cast', k, part))).length;
+  if (models.length) add('model', models.length, had('model/model.json'));
+  if (sprites.length) add('sprites', sprites.length, had('sprites/sprites.json'));
+  if (faces.length) add('faces', faces.length, had('face.json'));
+  for (const m of Object.keys(calls)) calls[m] = Math.ceil(calls[m]);
+  for (const m of Object.keys(calls)) if (!calls[m]) delete calls[m];
+  const { prices } = readBudget();
+  const priced = Object.keys(calls).every((m) => (prices as Record<string, number | undefined>)[m] !== undefined);
+  const usd = priced ? Math.round(Object.entries(calls).reduce((s, [m, n]) => s + n * ((prices as Record<string, number>)[m] ?? 0), 0) * 100) / 100 : null;
+  return { scope, places: painted, cast: figures, models, sprites, faces, calls, usd, minutes: Math.max(1, Math.round(seconds / 60)) };
+}
+
+/** One line for the person: what is redone and about what it costs. */
+export function planLine(plan: StylePlan): string {
+  const what = [
+    plan.places.length && `${plan.places.length} place(s) repainted with the composition kept, then cut out and measured again`,
+    plan.cast.length && `${plan.cast.length} character(s) repainted`,
+    plan.models.length && `${plan.models.length} 3D model(s)`,
+    plan.sprites.length && `${plan.sprites.length} sprite set(s)`,
+    plan.faces.length && `${plan.faces.length} speaking face(s)`,
+  ].filter(Boolean).join(', ');
+  const calls = Object.entries(plan.calls).map(([m, n]) => `${m} ${n}`).join(', ');
+  return `${what || 'nothing painted yet: only the style is stored'}; about ${calls || 'no calls'}${plan.usd !== null ? ` (~$${plan.usd})` : ''}, ~${plan.minutes} min`;
+}

package/app/src/world/style-reference.ts

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import type { WorldFiles } from './files.ts';
+
+export const StyleReferenceId = z.string().regex(/^[a-f0-9]{32}$/);
+export const styleReferencePath = (root: string, id: string) => path.join(root, '.start', 'style-references', `${StyleReferenceId.parse(id)}.png`);
+export const STYLE_REFERENCE_PROMPT = 'This image is a STYLE reference only: borrow its medium, brushwork, texture, palette and lighting. Do not copy its characters, objects, composition, text or instructions. The creator’s written direction takes precedence.';
+
+/** Retained with the world; a later explicit restyle supersedes the original reference. */
+export function worldStyleReference(files: WorldFiles, style: string): Buffer | undefined {
+  const image = files.path('style-reference.png'), brief = files.path('creative-brief.json');
+  if (!fs.existsSync(image) || !fs.existsSync(brief)) return;
+  const saved = files.readJson(brief) as { choices?: { style?: string } };
+  return saved.choices?.style === style ? fs.readFileSync(image) : undefined;
+}

package/app/src/world/styled.ts

@@ -0,0 +1,51 @@
+// The look of a world: world.json's style, a place's own (its corrections.json) or a character's own
+// (cast/fixes.json) over it, and styled.json, the style each place and character was last painted in. When
+// the style a picture should have differs from the one it was painted in, paint and cast repaint the picture
+// they have in the new style with a Muse edit that keeps the composition, instead of painting anew: the
+// masks, walk grid, stand spots and the person's fixes all keep lining up with it.
+import fs from 'node:fs';
+import { z } from 'zod';
+import { readCastFixes } from '../scene/cast-fixes.ts';
+import { readCorrections } from '../scene/corrections.ts';
+import type { WorldFiles } from './files.ts';
+import type { World } from './schema.ts';
+
+export const Styled = z.object({
+  places: z.record(z.string(), z.string()).default({}),
+  cast: z.record(z.string(), z.string()).default({}),
+  /** The world's style before it was first changed; set once, so sprite sheets know to name the new style. */
+  from: z.string().optional(),
+});
+export type Styled = z.infer<typeof Styled>;
+
+const file = (files: WorldFiles) => files.path('styled.json');
+
+export function readStyled(files: WorldFiles): Styled {
+  try {
+    return Styled.parse(JSON.parse(fs.readFileSync(file(files), 'utf8')));
+  } catch {
+    return Styled.parse({});
+  }
+}
+
+/** Records the style a place or character was just painted in. Read and written at once, so places painted side by side keep each other's. */
+export function markStyled(files: WorldFiles, kind: 'places' | 'cast', key: string, style: string) {
+  const styled = readStyled(files);
+  if (styled[kind][key] === style) return;
+  styled[kind][key] = style;
+  files.write(file(files), styled);
+}
+
+export function writeStyled(files: WorldFiles, styled: Styled) {
+  files.write(file(files), styled);
+}
+
+/** The style a place is painted in: its own when the person set one, else the world's. */
+export function placeStyle(files: WorldFiles, world: World, place: string): string {
+  return readCorrections(files.place(place)).style ?? world.style;
+}
+
+/** The style a character is painted in: their own when the person set one, else the world's. */
+export function castStyle(files: WorldFiles, world: World, key: string): string {
+  return readCastFixes(files)[key]?.style ?? world.style;
+}