@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/commands/derive.ts

@@ -0,0 +1,167 @@
+// diorama derive <slug> [place...]: geometry.json (walk grid, scale, occluders, spots) and walk.png per place.
+import fs from 'node:fs';
+import { maskArea, maskFromPng, maskToPng, emptyMask } from '../image/mask.ts';
+import { PALETTE, svgLabel, tintOver } from '../image/overlay.ts';
+import { Geometry, personPx } from '../play/geometry.ts';
+import { defineCommand } from '../registry.ts';
+import { brush, placeNpcs, readCorrections, type Corrections } from '../scene/corrections.ts';
+import { cellsMask } from '../scene/locate.ts';
+import { derive, type ThingIn } from '../scene/derive.ts';
+import { depthMap, uprightTest } from '../scene/depthmap.ts';
+import { paintedGlows } from '../scene/glows.ts';
+import { carryFrom, ran, tilesLine } from '../scene/carry.ts';
+import { Layout, FRAME } from '../scene/layout.ts';
+import { CELL, nearestRoomy, reach, roomy } from '../scene/walk.ts';
+import { closeFaces, placeDepth } from '../scene/occlusion-check.ts';
+import { gridOf } from '../scene/verify.ts';
+import { unionAll } from '../image/raster.ts';
+import { WorldFiles } from '../world/files.ts';
+
+type MasksJson = { things: Record<string, Omit<ThingIn, 'key' | 'mask'>> };
+
+/** The review picture: walkable cells tinted by floor, footprints red, floor lines, spots and the hero's size. */
+async function walkPicture(painting: Buffer, g: Geometry, footprint: ThingIn['mask']): Promise<Buffer> {
+  const floors = Math.max(0, ...g.zone!.flatMap((row) => [...row].filter((ch) => ch !== '.').map(Number))) + 1;
+  const cells = Array.from({ length: floors }, () => emptyMask(FRAME.width, FRAME.height));
+  g.walk.forEach((row, r) => [...row].forEach((ch, c) => {
+    if (ch !== '#') return;
+    const m = cells[Number(g.zone![r][c])] ?? cells[0];
+    for (let y = r * CELL; y < Math.min(FRAME.height, (r + 1) * CELL); y++) m.bits.fill(1, y * FRAME.width + c * CELL, y * FRAME.width + Math.min(FRAME.width, (c + 1) * CELL));
+  }));
+  const tints = [...cells.map((mask, i) => ({ mask, rgb: PALETTE[(i + 4) % PALETTE.length], alpha: 0.3 })), { mask: footprint, rgb: [255, 40, 40] as [number, number, number], alpha: 0.55 }];
+  const svg: string[] = [];
+  for (const o of g.occluders) {
+    svg.push(`<polyline points="${(o.floor ?? []).map((p) => p.join(',')).join(' ')}" fill="none" stroke="#ffe600" stroke-width="3"/>`);
+  }
+  // Each painted thing is named on itself (over the top of its box), and the spot the hero walks to for it is a
+  // small dot joined to it by a thin line: names piled up where the hero stands read as things in the wrong place.
+  for (const t of g.things) {
+    if (t.role === 'npc' || !t.box) {
+      svg.push(`<circle cx="${t.stand[0]}" cy="${t.stand[1]}" r="6" fill="#fff" stroke="#000" stroke-width="2"/>`, svgLabel(t.stand[0] + 9, t.stand[1] + 5, t.role === 'npc' ? `${t.key} stands here (not painted)` : t.key));
+      continue;
+    }
+    const [x0, y0, x1, y1] = t.box;
+    const [cx, cy] = [(x0 + x1) / 2, (y0 + y1) / 2];
+    const lx = Math.max(4, Math.min(FRAME.width - 8 * t.key.length - 12, cx - 4 * t.key.length));
+    const ly = y0 > 30 ? y0 - 8 : Math.min(FRAME.height - 8, y0 + 22);
+    svg.push(
+      `<rect x="${x0}" y="${y0}" width="${x1 - x0}" height="${y1 - y0}" fill="none" stroke="#fff" stroke-opacity="0.55" stroke-width="2" stroke-dasharray="6 5"/>`,
+      `<line x1="${t.stand[0]}" y1="${t.stand[1]}" x2="${cx}" y2="${cy}" stroke="#fff" stroke-opacity="0.7" stroke-width="1.5"/>`,
+      `<circle cx="${t.stand[0]}" cy="${t.stand[1]}" r="4" fill="#fff" stroke="#000" stroke-width="1.5"/>`,
+      svgLabel(lx, ly, t.key),
+    );
+  }
+  // The hero's size at three depths, as little figures spread over the floor (far left, middle, near right):
+  // stacked boxes in one column read as a path, not as a person.
+  const rows = g.walk.map((row, r) => (row.includes('#') ? r : -1)).filter((r) => r >= 0);
+  for (const [q, across] of [[0.1, 0.2], [0.5, 0.5], [0.95, 0.8]] as const) {
+    const r = rows[Math.floor(q * (rows.length - 1))];
+    const cols = [...g.walk[r]].flatMap((ch, c) => (ch === '#' ? [c] : []));
+    // The walkable cell nearest to a quarter, the middle and three quarters of the frame, so they stand apart.
+    const want = (across * FRAME.width) / CELL;
+    const c = cols.reduce((best, col) => (Math.abs(col - want) < Math.abs(best - want) ? col : best));
+    const [x, y] = [(c + 0.5) * CELL, (r + 0.5) * CELL];
+    const h = personPx(g, y);
+    const head = h * 0.065;
+    svg.unshift(`<g fill="rgba(80,160,255,0.6)" stroke="#fff" stroke-width="2"><circle cx="${x}" cy="${y - h + head}" r="${head}"/><rect x="${x - h * 0.1}" y="${y - h + head * 2.2}" width="${h * 0.2}" height="${h - head * 2.2}" rx="${h * 0.05}"/></g>`);
+    if (q === 0.95) svg.push(svgLabel(x - h * 0.1, y - h - 8, 'hero size'));
+  }
+  // Each step's back edge on stairs, where the feet climb.
+  for (const st of g.steps ?? []) svg.push(`<polyline points="${st.top.flatMap((t, i) => (t >= 0 ? [`${st.x0 + i * st.every},${t}`] : [])).join(' ')}" fill="none" stroke="#3cf" stroke-width="3"/>`);
+  svg.push(`<circle cx="${g.start[0]}" cy="${g.start[1]}" r="9" fill="#3f6" stroke="#000" stroke-width="2"/>`, svgLabel(g.start[0] + 12, g.start[1] + 5, 'start'));
+  svg.push(`<line x1="0" y1="${g.scale.horizonY}" x2="${FRAME.width}" y2="${g.scale.horizonY}" stroke="#5af" stroke-width="2" stroke-dasharray="12 8"/>`, svgLabel(8, g.scale.horizonY - 6, 'horizon'));
+  return tintOver(painting, tints, svg.join(''));
+}
+
+/**
+ * The floor someone said is floor: each floor's strokes that add (the person's, the agent's, the free bridge's)
+ * and the cells the person added. Erase strokes after them take back what they cover.
+ */
+export function saidFloor(c: Corrections): ThingIn['mask'] | undefined {
+  const floors = Object.values(c.floors);
+  const strokes = floors.flatMap((f) => f.strokes);
+  const cells = floors.flatMap((f) => f.add);
+  if (!cells.length && !strokes.some((s) => s.mode === 'add')) return undefined;
+  const said = brush(cells.length ? cellsMask(cells) : emptyMask(FRAME.width, FRAME.height), strokes);
+  return maskArea(said) ? said : undefined;
+}
+
+defineCommand({
+  name: 'derive',
+  usage: 'derive <slug> [place...] measure walk grid, scale and occluders from the masks (geometry.json)',
+  async run([slug, ...only]) {
+    if (!slug) throw new Error('usage: diorama derive <slug> [place...]');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    const places = world.places.filter((p) => only.length === 0 || only.includes(p.key));
+    await Promise.all(places.map(async (place) => {
+      const at = (...parts: string[]) => files.place(place.key, ...parts);
+      // NPCs are drawn by the runtime, not painted: moving one only moves its box (and where the hero talks to it).
+      const layout = placeNpcs(Layout.parse(files.readJson(at('layout.json'))), new Set(place.things.filter((t) => t.role === 'npc').map((t) => t.key)), readCorrections(at()));
+      const made = files.readJson(at('masks.json')) as MasksJson;
+      const painting = fs.readFileSync(at('painting.png'));
+      const things = await Promise.all(Object.entries(made.things).map(async ([key, t]) => ({ ...t, key, mask: await maskFromPng(fs.readFileSync(at('masks', `${key}.png`))) })));
+      const floors = await Promise.all(layout.floors.map(async (f) => maskFromPng(fs.readFileSync(at('masks', 'floors', `${f.key}.png`)))));
+      const plates = fs.existsSync(at('plates')) ? fs.readdirSync(at('plates')).filter((f) => f.endsWith('.png')).map((f) => f.slice(0, -4)) : [];
+      const carry = await carryFrom(at(), 'derive', painting);
+      if (carry) console.log(`  ${place.key}: ${tilesLine(carry)}; questions it does not reach keep their answers`);
+      const before = fs.existsSync(at('geometry.json')) ? Geometry.safeParse(files.readJson(at('geometry.json'))).data?.scale : undefined;
+      const previousScale = before && { ...before, source: before.source ?? ('spark' as const) };
+      const lastScale = carry ? previousScale : undefined;
+      const start = readCorrections(at()).start;
+      const said = saidFloor(readCorrections(at()));
+      // The lights as painted: the layout's points are guesses made before the painting (a lighthouse lamp drawn
+      // 170 px above its point). The runtime glows sit on them, and the lamp that lights the ground is found by them.
+      const holders = things.filter((t) => t.kind !== 'walk-on' && t.kind !== 'flat').map((t) => t.mask);
+      const glows = await paintedGlows(painting, layout.lights, holders);
+      if (glows.line) console.log(`  ${place.key}: ${glows.line}`);
+      const asPainted = { ...layout, lights: glows.glows.map((g) => ({ ...layout.lights.find((l) => l.key === g.key)!, x: g.x, y: g.y })) };
+      // Upright surfaces from the depth model: no path joining the floors climbs a wall. Without the model, none.
+      const upright = await uprightTest(painting, unionAll(FRAME.width, FRAME.height, floors)).catch((e: Error) => {
+        console.log(`  ${place.key}: no depth model for walls (${e.message})`);
+        return undefined;
+      });
+      const out = await derive(files.memo, { place, layout: asPainted, things, floors, painting, plates, carry, lastScale, previousScale, ...(start && { start }), ...(upright && { upright }), ...(said && { said }) }, (line) => console.log(`  ${place.key}: ${line}`));
+      // Shadows only with a light: without one the runtime has nothing to darken by.
+      const lit = out.shadows.light && maskArea(out.shadows.mask) > 0;
+      if (lit) files.write(at('masks', 'shadows.png'), await maskToPng(out.shadows.mask));
+      else fs.rmSync(at('masks', 'shadows.png'), { force: true });
+      // Where the person said the hero should stand to use a thing.
+      const fixes = readCorrections(at());
+      const placed = out.geometry.things.map((t) => (fixes.things[t.key]?.stand ? { ...t, stand: fixes.things[t.key].stand! } : t));
+      const measured = { ...out.geometry, things: placed, ...(out.shadows.light && { light: out.shadows.light }), ...(lit && { shadows: 'masks/shadows.png' }) };
+      // Depth for shadows that follow the ground; without it (no fit, no model) they lie flat as before.
+      const depth = await depthMap(painting, measured).catch((e: Error) => ({ reason: e.message }));
+      if ('png' in depth) {
+        files.write(at('depth.png'), depth.png);
+        console.log(`  ${place.key}: depth fits the floor on ${Math.round(depth.inliers * 100)}% of ${depth.cells} walk cells`);
+      } else {
+        fs.rmSync(at('depth.png'), { force: true });
+        measured.flagged = [...(measured.flagged ?? []), `depth: ${depth.reason}, shadows stay flat`];
+      }
+      const geometry = Geometry.parse({ ...measured, ...('png' in depth && { depth: 'depth.png' }), ...(layout.lights.length && { glows: glows.glows }) });
+      // Walk cells on an upright face (the front of a bridge's planks) close, with the floor only they led to.
+      const read = await placeDepth(at(), geometry);
+      const faced = read && closeFaces(geometry, read.d, read.owned);
+      if (faced) {
+        Object.assign(geometry, { walk: faced.walk, zone: faced.zone, start: faced.start });
+        // A stand the closing left out of reach (on the face, or on a fringe too narrow to walk) moves to the nearest
+        // floor the start reaches.
+        const grid = gridOf(geometry);
+        const reached = reach(grid, grid.cellOf(...geometry.start), roomy(grid));
+        geometry.things = geometry.things.map((t) => {
+          if (reached[grid.cellOf(...t.stand)]) return t;
+          const i = nearestRoomy(grid, ...t.stand, reached);
+          return i === undefined ? t : { ...t, stand: grid.centre(i) };
+        });
+        console.log(`  ${place.key}: closed ${faced.closed} walk cells on an upright face (feet over thin air)${faced.beyond ? ` and ${faced.beyond} only they led to` : ''}`);
+      }
+      files.write(at('geometry.json'), geometry);
+      files.write(at('walk.png'), await walkPicture(painting, geometry, out.footprint));
+      ran(at(), 'derive', carry?.old ?? painting);
+      const open = geometry.walk.join('').split('#').length - 1;
+      console.log(`${place.key}: ${open} walk cells, ${geometry.occluders.length} occluders, person ${Math.round(personPx(geometry, FRAME.height - 20))} px at the front (${geometry.scale.source})`);
+    }));
+    console.log(`spark calls sent: ${files.memo.sent.spark}`);
+  },
+});

package/app/src/commands/doctor.ts

@@ -0,0 +1,74 @@
+// diorama doctor: one live call per model, so a bad key or a changed API shows up before a build.
+import fs from 'node:fs';
+import path from 'node:path';
+import { maskArea, maskToPng } from '../image/mask.ts';
+import { Memo } from '../meta/memo.ts';
+import { museEdit, musePaint } from '../meta/muse.ts';
+import { samFind } from '../meta/sam.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import { defineCommand } from '../registry.ts';
+
+defineCommand({
+  name: 'doctor',
+  usage: 'doctor [dir] [--now]    check the API key with one call to Spark, Muse paint, Muse edit and SAM 3.1; --now skips the memo and says if the network and Meta are fast enough for a live build',
+  async run(args) {
+    const nowAt = args.indexOf('--now');
+    if (nowAt >= 0) args.splice(nowAt, 1);
+    const [dir = '.diorama/doctor'] = args;
+    const out = path.resolve(dir);
+    fs.mkdirSync(out, { recursive: true });
+    // A memo hit takes no time, so --now asks afresh to measure this network and Meta as they are.
+    const memo = new Memo(path.join(out, nowAt >= 0 ? `memo-${Date.now()}` : 'memo'));
+    let failed = 0;
+    const took: Record<string, number> = {};
+    async function check<T>(name: string, run: () => Promise<T>, describe: (v: T) => string): Promise<T | undefined> {
+      const started = Date.now();
+      try {
+        const value = await run();
+        took[name] = Date.now() - started;
+        console.log(`  ok    ${name.padEnd(11)}${`${Date.now() - started} ms`.padStart(9)}  ${describe(value)}`);
+        return value;
+      } catch (error) {
+        failed++;
+        console.log(`  FAIL  ${name.padEnd(11)}${error instanceof Error ? error.message : error}`);
+      }
+    }
+
+    await check('spark', () => askSparkJson<{ thing: string }>(memo, {
+      label: 'doctor',
+      prompt: 'Name one thing a traveller might find at a crossroads inn. Reply as JSON: {"thing": "..."}',
+    }), (a) => `"${a.thing}"`);
+
+    const painting = await check('muse paint', () => musePaint(memo, {
+      label: 'doctor',
+      prompt: 'A painted background for a 2D adventure game: the yard of a crossroads inn at dusk, a cart with a wooden barrel, a well, lanterns on the porch. Gouache, no people, no text.',
+    }), (png) => `${Math.round(png.length / 1024)} KB`);
+    if (!painting) return void process.exit(1);
+    fs.writeFileSync(path.join(out, 'paint.png'), painting);
+
+    const edited = await check('muse edit', () => museEdit(memo, {
+      label: 'doctor',
+      images: [painting],
+      prompt: 'The same yard on a snowy winter night. Keep the composition exactly.',
+    }), (png) => `${Math.round(png.length / 1024)} KB`);
+    if (edited) fs.writeFileSync(path.join(out, 'edit.png'), edited);
+
+    const found = await check('sam', () => samFind(memo, { label: 'doctor', image: painting, prompt: 'barrel' }),
+      (f) => `${f.length} barrel(s), ${f.reduce((s, x) => s + maskArea(x.mask), 0)} px`);
+    if (found?.[0]) fs.writeFileSync(path.join(out, 'sam-barrel.png'), await maskToPng(found[0].mask));
+
+    if (nowAt >= 0) console.log(`\n  ${liveVerdict(took)}`);
+    console.log(`\n  sent: spark ${memo.sent.spark}, muse ${memo.sent.muse}, sam ${memo.sent.sam} · files in ${out}`);
+    if (failed) process.exit(1);
+  },
+});
+
+/** Slower than this, one call is a sign of a slow network or a busy Meta: a 25-drawing build took 45 min at 3x these. */
+const SLOW_MS: Record<string, number> = { spark: 30_000, 'muse paint': 60_000, 'muse edit': 60_000, sam: 20_000 };
+
+/** Whether a build in front of people will finish in time, from one call to each model. */
+export function liveVerdict(took: Record<string, number>): string {
+  const slow = Object.entries(SLOW_MS).filter(([name, limit]) => (took[name] ?? Infinity) > limit).map(([name]) => name);
+  if (!slow.length) return 'fast enough for a live build (3 places in about 15 min)';
+  return `SLOW: ${slow.join(', ')}. A live build may take 30+ min: play a world built beforehand, or build with fewer drawings and places`;
+}

package/app/src/commands/explore.ts

@@ -0,0 +1,123 @@
+// diorama explore <slug> [place...]: walks the hero over every place in the real play page and
+// reports what looks wrong (explore/ per place: report.json, heatmap.png, sheet.png).
+// --fix closes the cells around bad spots in geometry.json; --no-judge skips the Spark juror.
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { Geometry } from '../play/geometry.ts';
+import { classify, contactSheet, fixGrid, heatmap, ISSUES, judge, positions, type Checked } from '../qa/explore.ts';
+import { CROP_JS, PROBE_JS, type ProbeHit } from '../qa/probe.ts';
+import { defineCommand, takeOption } from '../registry.ts';
+import { WorldFiles } from '../world/files.ts';
+import { serveWorld } from './play.ts';
+
+export type Browser = { newPage(o?: object): Promise<Page>; close(): Promise<void> };
+export type Page = {
+  goto(url: string): Promise<unknown>;
+  waitForFunction(js: string, arg?: unknown, o?: object): Promise<unknown>;
+  evaluate<T>(js: string, arg?: unknown): Promise<T>;
+  on(event: 'pageerror' | 'console', fn: (e: { message?: string; text?: () => string; type?: () => string }) => void): void;
+};
+
+/** Playwright ships with diorama; its Chromium is a separate download (diorama browsers). */
+export async function chromium(): Promise<{ launch(o?: object): Promise<Browser> }> {
+  try {
+    return ((await import('playwright' as string)) as { chromium: never }).chromium;
+  } catch {
+    try {
+      return (createRequire(import.meta.url)('playwright') as { chromium: never }).chromium;
+    } catch {
+      throw new Error('this command needs Playwright with Chromium: diorama browsers');
+    }
+  }
+}
+
+/** Runs a page function given as source text, so the bundler adds nothing it can't see. */
+const call = <T>(page: Page, fn: string, arg: unknown) => page.evaluate<T>(`(${fn})(${JSON.stringify(arg)})`);
+
+defineCommand({
+  name: 'explore',
+  usage: 'explore <slug> [place...] walk the hero over each place and check every frame [--fix] [--no-judge] [--port N]',
+  async run(args) {
+    const fix = args.includes('--fix');
+    const noJudge = args.includes('--no-judge');
+    const port = Number(takeOption(args, 'port', '4183'));
+    const [slug, ...only] = args.filter((a) => !a.startsWith('--'));
+    if (!slug) throw new Error('usage: diorama explore <slug> [place...] [--fix] [--no-judge]');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    const places = world.places.filter((p) => only.length === 0 || only.includes(p.key));
+
+    const server = await serveWorld(files, port);
+    const browser = await (await chromium()).launch();
+    try {
+      const page = await browser.newPage({ viewport: { width: 1280, height: 960 } });
+      page.on('pageerror', (e) => console.log(`  page error: ${e.message}`));
+      for (const place of places) {
+        const at = (...parts: string[]) => files.place(place.key, ...parts);
+        if (!fs.existsSync(at('geometry.json'))) {
+          console.log(`${place.key}: no geometry.json, skipped`);
+          continue;
+        }
+        const g = Geometry.parse(files.readJson(at('geometry.json')));
+        await page.goto(`http://localhost:${port}/?capture=1&place=${place.key}`);
+        await page.waitForFunction(`window.diorama && window.diorama.place && window.diorama.place.key === ${JSON.stringify(place.key)}`, undefined, { timeout: 30000 });
+
+        const spots = positions(g);
+        const started = Date.now();
+        const hits: ProbeHit[] = [];
+        for (let i = 0; i < spots.length; i += 100) hits.push(...(await call<ProbeHit[]>(page, PROBE_JS, { placeKey: place.key, positions: spots.slice(i, i + 100) })));
+        const checked = hits.map(classify);
+        const bad = checked.filter((h) => h.issues.length);
+        const counts = Object.fromEntries(ISSUES.map((k) => [k, checked.filter((h) => h.issues.includes(k)).length]));
+        console.log(`${place.key}: ${checked.length} spots in ${((Date.now() - started) / 1000).toFixed(1)} s, ${bad.length} with issues ${JSON.stringify(counts)}`);
+
+        fs.rmSync(at('explore'), { recursive: true, force: true });
+        const painting = fs.readFileSync(at('painting.png'));
+        files.write(at('explore', 'heatmap.png'), await heatmap(painting, g, checked));
+
+        // The juror: the worst spots first, the rest random clean ones, so it also says when all is fine.
+        let jury: { tiles: Checked[]; wrong: { id: number; why: string }[] } | undefined;
+        if (!noJudge) {
+          const severity = (h: Checked) => h.issues.length * 1000 + h.drawn - h.hidden;
+          const worst = [...bad].sort((a, b) => severity(b) - severity(a)).slice(0, 10);
+          const clean = checked.filter((h) => !h.issues.length);
+          const random = Array.from({ length: Math.min(16 - worst.length, clean.length) }, (_, i) => clean[Math.floor(((i + 0.5) * clean.length) / Math.min(16 - worst.length, clean.length))]);
+          const tiles = [...worst, ...random];
+          const crops = await Promise.all(tiles.map(async (t) => {
+            const url = await call<string>(page, CROP_JS, { placeKey: place.key, x: t.x, y: t.y, size: 256 });
+            return Buffer.from(url.slice(url.indexOf(',') + 1), 'base64');
+          }));
+          const sheet = await contactSheet(crops, 256);
+          files.write(at('explore', 'sheet.png'), sheet);
+          const wrong = await judge(files.memo, `explore:${place.key}`, sheet, tiles.length);
+          jury = { tiles, wrong };
+          const agree = wrong.filter((w) => tiles[w.id - 1].issues.length).length;
+          console.log(`  juror: ${wrong.length} of ${tiles.length} tiles look wrong (${agree} also failed a code check)${wrong.map((w) => `\n    #${w.id} ${tiles[w.id - 1].issues.join('+') || 'clean'}: ${w.why}`).join('')}`);
+        }
+
+        let fixed: { closed: number; undone: string[] } | undefined;
+        if (fix && bad.length) {
+          const result = fixGrid(g, checked);
+          fixed = { closed: result.closed, undone: result.undone };
+          if (result.closed) {
+            const flagged = [...(g.flagged ?? []), `explorer closed ${result.closed} cells where the hero looked wrong`];
+            files.write(at('geometry.json'), Geometry.parse({ ...result.geometry, flagged }));
+          }
+          console.log(`  fix: closed ${result.closed} cells${result.undone.map((u) => `; not fixed: ${u}`).join('')}`);
+        }
+
+        files.write(at('explore', 'report.json'), {
+          spots: checked.length,
+          counts,
+          bad: bad.map(({ x, y, issues, worst, drawn, hidden }) => ({ x, y, issues, worst, drawn, hidden })),
+          ...(jury && { juror: jury.wrong.map((w) => ({ ...w, x: jury.tiles[w.id - 1].x, y: jury.tiles[w.id - 1].y, codeIssues: jury.tiles[w.id - 1].issues })) }),
+          ...(fixed && { fixed }),
+        });
+      }
+    } finally {
+      await browser.close();
+      server.close();
+    }
+    console.log(`spark calls sent: ${files.memo.sent.spark}`);
+  },
+});

package/app/src/commands/export.ts

@@ -0,0 +1,158 @@
+// diorama export <slug> [dir]: the world as a static folder (index.html, main.js, world-data.json, files/) any web host can serve.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { defineCommand } from '../registry.ts';
+import { WorldFiles } from '../world/files.ts';
+import { bundle, WEB, worldData } from './play.ts';
+
+/** A language name ("Polish", "polski") or code ("pl", "pt-BR") as a BCP 47 code, when Intl knows it. */
+function langCode(language?: string): string | undefined {
+  if (!language) return undefined;
+  const t = language.trim();
+  if (/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/i.test(t)) return t;
+  const names = new Intl.DisplayNames(['en'], { type: 'language' });
+  for (const code of ['en', 'pl', 'de', 'fr', 'es', 'it', 'pt', 'nl', 'cs', 'sk', 'uk', 'ru', 'sv', 'no', 'da', 'fi', 'hu', 'ro', 'el', 'tr', 'ja', 'ko', 'zh', 'ar', 'he', 'hi']) {
+    const own = new Intl.DisplayNames([code], { type: 'language' }).of(code);
+    if ([names.of(code), own].some((n) => n?.toLowerCase() === t.toLowerCase())) return code;
+  }
+  return undefined;
+}
+
+const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/** The link preview (X, Facebook, chats): the world's title and pitch, and a 1200x630 picture: the world's own og.jpg when it has one, else its first painted place. */
+async function sharePreview(files: WorldFiles, out: string, url?: string): Promise<string> {
+  const world = files.world();
+  const title = `${world.title} · Diorama`;
+  const pitch = world.pitch.length > 200 ? `${world.pitch.slice(0, 197).replace(/\s+\S*$/, '')}…` : world.pitch;
+  const own = files.path('og.jpg');
+  const painted = [world.start, ...world.places.map((p) => p.key)].map((key) => files.place(key, 'painting.png')).find((f) => fs.existsSync(f));
+  const source = fs.existsSync(own) ? own : painted;
+  const base = url ? (url.endsWith('/') ? url : `${url}/`) : '';
+  const tags = [`<title>${esc(title)}</title>`, `<meta name="description" content="${esc(pitch)}">`, `<meta property="og:type" content="website">`, `<meta property="og:title" content="${esc(title)}">`, `<meta property="og:description" content="${esc(pitch)}">`];
+  if (base) tags.push(`<meta property="og:url" content="${esc(base)}">`);
+  if (source) {
+    await sharp(source).resize(1200, 630, { fit: 'cover', position: 'attention' }).jpeg({ quality: 85, mozjpeg: true }).toFile(path.join(out, 'og.jpg'));
+    // Crawlers want an absolute address; the stamp makes X fetch a new picture after a re-export.
+    const image = `${base}og.jpg?v=${Date.now().toString(36)}`;
+    tags.push(`<meta property="og:image" content="${esc(image)}">`, '<meta property="og:image:width" content="1200">', '<meta property="og:image:height" content="630">', `<meta property="og:image:alt" content="${esc(world.title)}, a playable paper diorama world">`, '<meta name="twitter:card" content="summary_large_image">', `<meta name="twitter:image" content="${esc(image)}">`);
+  } else tags.push('<meta name="twitter:card" content="summary">');
+  tags.push(`<meta name="twitter:title" content="${esc(title)}">`, `<meta name="twitter:description" content="${esc(pitch)}">`);
+  return tags.join('\n');
+}
+
+/** Writes the playable copy of world `slug` to `out`, replacing whatever was there; `home` adds a link back to the page it is shared from; `url` is where the copy will be served, so its link preview has absolute addresses. */
+export async function exportWorld(slug: string, out: string, home?: string, url?: string): Promise<void> {
+  const files = new WorldFiles(slug);
+  const data = worldData(files);
+  fs.rmSync(out, { recursive: true, force: true });
+  fs.mkdirSync(out, { recursive: true });
+  const copy = async (rel: string, asJpeg = false): Promise<string> => {
+    const target = asJpeg ? rel.replace(/\.png$/, '.jpg') : rel;
+    const dest = path.join(out, 'files', target);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    // Paintings are opaque, so JPEG keeps them a fraction of the size; masks and figures stay PNG.
+    if (asJpeg) await sharp(files.path(rel)).jpeg({ quality: 88, mozjpeg: true }).toFile(dest);
+    else fs.copyFileSync(files.path(rel), dest);
+    return target;
+  };
+  // Cut-outs, sprite sheets and icons only need their look and an exact edge: WebP with lossless alpha is a
+  // fraction of the PNG, and those files are most of what a player waits for. A file is changed only when it gets smaller.
+  const done = new Map<string, string>();
+  const art = async (rel: string): Promise<string> => {
+    if (done.has(rel)) return done.get(rel)!;
+    let target = rel;
+    const webp = /\.png$/i.test(rel) ? await sharp(files.path(rel)).webp({ quality: 90, alphaQuality: 100, effort: 5 }).toBuffer() : undefined;
+    if (webp && webp.length < fs.statSync(files.path(rel)).size * 0.9) {
+      target = rel.replace(/\.png$/i, '.webp');
+      const dest = path.join(out, 'files', target);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, webp);
+    } else await copy(rel);
+    done.set(rel, target);
+    return target;
+  };
+  /** `file` inside `dir`, as art; its new name, still inside `dir`. */
+  const artIn = async (dir: string, file: string) => path.posix.relative(dir, await art(`${dir}/${file}`));
+  for (const [key, entry] of Object.entries(data.places)) {
+    if (entry.painting) entry.painting = await copy(entry.painting, true);
+    if (entry.backdrop) entry.backdrop = await copy(entry.backdrop, true);
+    if (entry.layers) {
+      if (entry.layers.sky) entry.layers.sky = await copy(entry.layers.sky, true);
+      if (entry.layers.water) {
+        entry.layers.water.tex = await copy(entry.layers.water.tex);
+        entry.layers.water.mask = await copy(entry.layers.water.mask);
+      }
+      if (entry.layers.mist) {
+        entry.layers.mist.tex = await copy(entry.layers.mist.tex);
+        entry.layers.mist.mask = await copy(entry.layers.mist.mask);
+      }
+      for (const f of entry.layers.flats) f.file = await art(f.file); // transparent around the flat
+      for (const f of [...(entry.layers.smoke ?? []), ...(entry.layers.floats ?? []), ...(entry.layers.falls ?? []), ...(entry.layers.critters ?? []), ...(entry.layers.clouds?.bands ?? [])]) f.file = await art(f.file);
+      if (entry.layers.clouds) {
+        entry.layers.clouds.clip = await copy(entry.layers.clouds.clip);
+        if (entry.layers.clouds.keep) entry.layers.clouds.keep = await copy(entry.layers.clouds.keep);
+      }
+    }
+    for (const thing of entry.geometry?.things ?? []) {
+      if (thing.mask) await copy(`places/${key}/${thing.mask}`);
+      // A plate is the patch where the thing was, transparent elsewhere.
+      if (thing.plate) thing.plate = await artIn(`places/${key}`, thing.plate);
+    }
+    for (const occ of entry.geometry?.occluders ?? []) if (occ.mask) await copy(`places/${key}/${occ.mask}`);
+    if (entry.geometry?.shadows) await copy(`places/${key}/${entry.geometry.shadows}`);
+    if (entry.geometry?.depth) await copy(`places/${key}/${entry.geometry.depth}`);
+    if (entry.weather?.ripples) entry.weather.ripples = await copy(entry.weather.ripples);
+  }
+  for (const [i, rel] of Object.entries(data.changes)) data.changes[i] = await art(rel); // transparent around the thing
+  for (const [i, rel] of Object.entries(data.changeShapes)) data.changeShapes[i] = await copy(rel);
+  for (const figure of Object.values(data.cast)) {
+    figure.image = await art(figure.image);
+    if (figure.face) await copy(`${figure.face.dir}/${figure.face.info.image}`); // the face atlas is read cell by cell, so as is
+    for (const part of figure.rig?.parts ?? []) part.file = await artIn(figure.parts!, part.file);
+    if (figure.rig?.sheet) figure.rig.sheet.file = await artIn(figure.parts!, figure.rig.sheet.file);
+    if (figure.sprites) for (const f of [...Object.values(figure.sprites.info.facings), ...Object.values(figure.sprites.info.talk ?? {})]) f.sheet = await artIn(figure.sprites.dir, f.sheet);
+    // The page draws sprites when it has them; the 3D model behind them (a glb and four big views) is only for ?model=1.
+    if (figure.sprites) delete figure.model;
+    if (figure.model) for (const file of [figure.model.info.glb, ...Object.values(figure.model.info.views).map((v) => v.image)]) await copy(`${figure.model.dir}/${file}`);
+  }
+  for (const item of Object.values(data.items ?? {})) item.icon = await art(item.icon); // transparent
+  const recordings = Object.values(data.sound?.bySpeaker ?? {}).flatMap(lines => Object.values(lines));
+  const audioFiles = new Set([...Object.values(data.sound?.files ?? {}), ...Object.values(data.sound?.lines ?? {}), ...recordings].map(sound => sound.file));
+  for (const file of audioFiles) await copy(file);
+  fs.writeFileSync(path.join(out, 'world-data.json'), JSON.stringify(data));
+  fs.writeFileSync(path.join(out, 'main.js'), await bundle(true));
+  let page = fs.readFileSync(path.join(WEB, 'index.html'), 'utf8');
+  page = page.replace('<body>', '<body data-shipped>');
+  if (home) page = page.replace('<div id="soundless"', `<a id="home" href="${esc(home)}">← Diorama</a>\n<div id="soundless"`);
+  page = page.replace('<title>Diorama</title>', await sharePreview(files, out, url));
+  // The page's language follows the world's, so browsers and screen readers read a Polish world as Polish.
+  const lang = langCode(files.world().language);
+  if (lang) page = page.replace('<html lang="en">', `<html lang="${lang}">`);
+  fs.writeFileSync(path.join(out, 'index.html'), page);
+}
+
+defineCommand({
+  name: 'export',
+  usage: 'export <slug> [dir] [--zip] [--home <url>] [--url <url>]   write a static, playable copy of the world (default exports/<slug>); --zip also packs it for itch.io or e-mail; --home puts a "← Diorama" link to <url> in the corner; --url is where it will be served, for the X/Facebook link preview (title, pitch, og.jpg: worlds/<slug>/og.jpg if you made one, else the first place)',
+  async run(args) {
+    const zip = args.includes('--zip');
+    const flag = (name: string) => { const i = args.indexOf(name); if (i >= 0 && !args[i + 1]) throw new Error(`${name} needs a url`); return i; };
+    const h = flag('--home'), u = flag('--url');
+    const home = h >= 0 ? args[h + 1] : undefined;
+    const url = u >= 0 ? args[u + 1] : undefined;
+    const [slug, dir = path.join('exports', slug ?? '')] = args.filter((a, i) => a !== '--zip' && ![h, u].some((f) => f >= 0 && (i === f || i === f + 1)));
+    if (!slug) throw new Error('usage: diorama export <slug> [dir] [--zip] [--home <url>] [--url <url>]');
+    const out = path.resolve(dir);
+    await exportWorld(slug, out, home, url);
+    console.log(`export ${slug}: ${out}`);
+    if (zip) {
+      // index.html at the zip's root, which is what itch.io wants for an HTML5 upload.
+      fs.rmSync(`${out}.zip`, { force: true });
+      execFileSync('zip', ['-qr', `${out}.zip`, '.'], { cwd: out });
+      console.log(`zip: ${out}.zip`);
+    }
+  },
+});

package/app/src/commands/extend.ts

@@ -0,0 +1,75 @@
+// One Studio job: plan and validate first, then build only the anchor and additions.
+import fs from 'node:fs';
+import { defineCommand, emit, registry } from '../registry.ts';
+import { readDrawn } from '../world/drawings.ts';
+import { designExtension } from '../world/extend.ts';
+import { stagedExtension } from '../world/extend-stage.ts';
+import { WorldFiles, withThingEdits } from '../world/files.ts';
+import { World } from '../world/schema.ts';
+import { Story } from '../story/schema.ts';
+import { checkStory } from '../story/check.ts';
+
+export async function extendWorld(slug: string, selected: string[], wish: string) {
+  const files = new WorldFiles(slug);
+  const oldWorld = World.parse(files.readJson(files.path('world.json')));
+  const oldStory = Story.parse(files.readJson(files.path('story.json')));
+  const drawings = selected.map(file => {
+    const d = readDrawn(files).find(x => `drawings/${x.file}` === file);
+    if (!d || !fs.existsSync(files.path(file))) throw new Error(`${file} is not a saved, read drawing`);
+    return d;
+  });
+  // The story uses effective props (including manual edits), while only the base world is persisted.
+  const effective = withThingEdits(oldWorld, files.dir);
+  const designed = await designExtension(files.memo, effective, oldStory, drawings, wish);
+  // Preserve the corrections layer: use each unchanged original place and add only new things to the anchor.
+  const oldByKey = new Map(oldWorld.places.map(p => [p.key, p]));
+  const effectiveByKey = new Map(effective.places.map(p => [p.key, p]));
+  const world = { ...designed.world, places: designed.world.places.map(p => {
+    const old = oldByKey.get(p.key);
+    if (!old) return p;
+    if (!designed.changed.includes(p.key)) return old;
+    const before = effectiveByKey.get(p.key)!;
+    return { ...old, things: [...old.things, ...p.things.filter(t => !before.things.some(x => x.key === t.key))], exits: p.exits };
+  }) };
+  const checked = checkStory(withThingEdits(World.parse(world), files.dir), designed.story);
+  if (checked.issues.length) throw new Error(`story does not fit the corrected world: ${checked.issues.join('; ')}`);
+  const oldNpc = new Set(oldWorld.places.flatMap(p => p.things.filter(t => t.role === 'npc').map(t => t.key)));
+  const newNpc = [...new Set(world.places.flatMap(p => p.things.filter(t => t.role === 'npc' && !oldNpc.has(t.key)).map(t => t.key)))];
+  const newItems = designed.story.items.filter(i => !oldStory.items.some(o => o.key === i.key)).map(i => i.key);
+  files.write(files.path('world.json'), world);
+  files.write(files.path('story.json'), designed.story);
+  files.write(files.path('routes.json'), checked.routes);
+  console.log(`extension planned: ${designed.changed.join(', ')}; ${checked.states} story states checked`);
+  const newPlaces = designed.changed.filter(key => !oldWorld.places.some(place => place.key === key));
+  emit('extension.progress', { phase: 'places', total: designed.changed.length, newPlaces, ...(newNpc.length && { task: 'characters' }) });
+  // Builds run in the private copy; the original remains playable until the whole job succeeds.
+  if (newNpc.length) {
+    await registry.get('cast')!.run([slug, ...newNpc]);
+    const missing = newNpc.filter(key => !fs.existsSync(files.path('cast', `${key}.png`)));
+    if (missing.length) throw new Error(`characters could not be painted: ${missing.join(', ')}`);
+  }
+  for (const [index, place] of designed.changed.entries()) {
+    emit('extension.progress', { phase: 'places', place, index: index + 1, total: designed.changed.length });
+    console.log(`building ${place}`);
+    process.exitCode = 0;
+    await registry.get('build')!.run([slug, '--from', 'layout', '--to', 'verify', '--place', place]);
+    if (process.exitCode) throw new Error(`${place} is not playable; extension was not installed`);
+  }
+  emit('extension.progress', { phase: 'audio' });
+  if (newItems.length) await registry.get('icons')!.run([slug, ...newItems]);
+  await registry.get('voices')!.run([slug]);
+  await registry.get('sound')!.run([slug]);
+  console.log(`extension complete: ${designed.changed.join(', ')}; new characters: ${newNpc.join(', ') || 'none'}`);
+}
+
+defineCommand({
+  name: 'extend',
+  usage: 'extend <slug> <JSON drawing paths> <wish>  extend a built world from saved drawings',
+  async run([slug, json, wish]) {
+    if (!slug || !json || !wish) throw new Error('usage: diorama extend <slug> <JSON drawing paths> <wish>');
+    const selected: unknown = JSON.parse(json);
+    if (!Array.isArray(selected) || !selected.length || !selected.every(f => typeof f === 'string' && /^drawings\/[a-z0-9-]+\.png$/.test(f))) throw new Error('drawings must be an array of drawings/*.png paths');
+    emit('extension.progress', { phase: 'plan' });
+    await stagedExtension(slug, () => extendWorld(slug, selected, wish));
+  },
+});