@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/play/creature.ts

@@ -0,0 +1,43 @@
+// How a creature moves that is not a person on two legs (a round eye, a frog, a teapot that lives): no legs to
+// walk, so its whole body hops, squashes as it lands, stretches as it rises, leans the way it goes, breathes
+// and now and then blinks (a quick squash). The 3D model (web/hero3d.ts) and the painted cut-out (web/main.ts)
+// both move this way. No Node imports: the browser bundles this file.
+
+/** lift: how high the feet are off the ground; stretch: height scale about the feet (width the inverse, so the
+ * volume stays); lean: forward tilt in radians, towards where it goes. lift is in body heights. */
+export type CreatureMotion = { lift: number; stretch: number; lean: number };
+
+/** One hop per walk cycle (src/play/rig.ts CYCLE), this high in body heights. */
+const HOP = 0.32;
+/** Share of the cycle on the ground: the squash as it lands and pushes off. */
+const CONTACT = 0.3;
+const BLINK_EVERY = 3.7;
+const BLINK = 0.16;
+
+/**
+ * phase: walk cycles (as the person's walk); time: seconds, for breathing and blinking; seed: so two creatures
+ * side by side do not breathe in step. talk: speaking bounces, listening leans in a little.
+ */
+export function creatureMotion({ phase = 0, walking = false, time = 0, talk, seed = 0 }: {
+  phase?: number; walking?: boolean; time?: number; talk?: 'speak' | 'listen'; seed?: number;
+}): CreatureMotion {
+  const breathe = 0.025 * Math.sin(time * 2.4 + seed);
+  if (walking) {
+    const p = ((phase % 1) + 1) % 1;
+    // On the ground (landing, then pushing off): squashed most in the middle of it.
+    if (p < CONTACT) return { lift: 0, stretch: 1 - 0.2 * Math.sin((Math.PI * p) / CONTACT), lean: 0.12 };
+    const u = (p - CONTACT) / (1 - CONTACT);
+    // In the air: up and down in an arc, stretched on the way up, round at the top, a little stretched falling.
+    return { lift: HOP * Math.sin(Math.PI * u), stretch: 1 + 0.12 * Math.cos(Math.PI * u) ** 2, lean: 0.12 + 0.08 * Math.cos(Math.PI * u) };
+  }
+  const t = time + seed;
+  // A blink: a quick squash and back.
+  const b = t % BLINK_EVERY;
+  const blink = b < BLINK ? 0.14 * Math.sin((Math.PI * b) / BLINK) : 0;
+  if (talk === 'speak') {
+    // Little bounces on the words.
+    const s = Math.abs(Math.sin(t * 7));
+    return { lift: 0.035 * s, stretch: 1 + 0.07 * s - blink + breathe, lean: 0.05 * Math.sin(t * 2.3) };
+  }
+  return { lift: 0, stretch: 1 + breathe - blink, lean: talk === 'listen' ? 0.06 : 0 };
+}

package/app/src/play/depth-occlusion.ts

@@ -0,0 +1,150 @@
+// depth-occlusion: the painting hides whoever stands behind it, also where nothing was masked. Things the
+// story names get cards (geometry.occluders), but a painting is full of things nobody named: a lamp post,
+// a railing, a bridge's parapet. The depth map (depth.png, src/scene/depthmap.ts) knows how far every pixel
+// is, as the floor row at the same distance, so a pixel nearer than the person's feet stands in front of
+// them and is put back over them. Cards stay in charge of their own pixels.
+// No Node imports: the browser bundles this file.
+import { stepAt, type Geometry } from './geometry.ts';
+import { DEPTH_SCALE, type Depth } from './shadow.ts';
+
+/** Floor rows the painting must be nearer than the feet by, at least, before it hides anyone: the depth model's noise. */
+export const FRONT_MIN_ROWS = 6;
+/** ... and as a share of the feet's own row (rows bunch up toward the horizon, metres don't). The depth model reads a wall right behind someone ~10% too near. */
+export const FRONT_SHARE = 0.12;
+/** How much the depth must grow per screen row under the feet for them to stand on a floor (1 on flat ground, ~0.3 up stairs, ~0 on a wall). */
+export const FLOOR_SLOPE = 0.15;
+/**
+ * The most of a person's box the depth map may hide. Standing on visible floor, more than
+ * this in front of them means the feet are really on what seems in front (a stair's riser, a slope the model
+ * flattened): then it hides nothing, and the place's check (src/scene/occlusion-check.ts) lists the spot.
+ */
+export const MAX_HIDDEN = 0.75;
+
+/** Within this many floor rows (or this share of the row) of the floor plane, a pixel is floor: where things stand. */
+export const FLOOR_TOLERANCE = 6;
+export const FLOOR_TOLERANCE_SHARE = 0.1;
+
+const contacts = new WeakMap<Depth, Int16Array>();
+
+/**
+ * Per depth-map pixel, the frame row where what is painted there meets the floor: going down its column, the
+ * first pixel no nearer than the floor plane at its own row. A lamp post meets it at its foot, a wall at its
+ * base, a bridge's side where the water shows under it; a lamp's head where its post does. Only what meets the floor in front of someone's
+ * feet can stand in front of them, whatever the depth model thinks of a wall behind them.
+ */
+export function contactRows(g: Pick<Geometry, 'scale'>, d: Depth): Int16Array {
+  let out = contacts.get(d);
+  if (out) return out;
+  out = new Int16Array(d.w * d.h);
+  for (let c = 0; c < d.w; c++) {
+    let below = d.h * DEPTH_SCALE;
+    for (let r = d.h - 1; r >= 0; r--) {
+      const y = (r + 0.5) * DEPTH_SCALE;
+      const flat = y - g.scale.horizonY;
+      if (flat > 0 && d.rows[r * d.w + c] <= flat + Math.max(FLOOR_TOLERANCE, FLOOR_TOLERANCE_SHARE * flat)) below = Math.round(y);
+      out[r * d.w + c] = below;
+    }
+  }
+  // An overhang (a lamp's head wider than its post, a roof's eave) has nothing under its edge but what is behind:
+  // along the row, what stands at the same distance shares the lowest foot it reaches.
+  const standing = (i: number, y: number) => d.rows[i] > y - g.scale.horizonY + Math.max(FLOOR_TOLERANCE, FLOOR_TOLERANCE_SHARE * (y - g.scale.horizonY));
+  const near = (a: number, b: number) => Math.abs(d.rows[a] - d.rows[b]) <= Math.max(2, 0.02 * d.rows[a]);
+  for (let r = 0; r < d.h; r++) {
+    const y = (r + 0.5) * DEPTH_SCALE;
+    const at = r * d.w;
+    for (let c = 1; c < d.w; c++) if (standing(at + c, y) && standing(at + c - 1, y) && near(at + c, at + c - 1)) out[at + c] = Math.max(out[at + c], out[at + c - 1]);
+    for (let c = d.w - 2; c >= 0; c--) if (standing(at + c, y) && standing(at + c + 1, y) && near(at + c, at + c + 1)) out[at + c] = Math.max(out[at + c], out[at + c + 1]);
+  }
+  contacts.set(d, out);
+  return out;
+}
+
+/** The depth map's floor row at a frame pixel (nearest sample). */
+export function depthAt(d: Depth, x: number, y: number): number {
+  const c = Math.min(d.w - 1, Math.max(0, Math.floor(x / DEPTH_SCALE)));
+  const r = Math.min(d.h - 1, Math.max(0, Math.floor(y / DEPTH_SCALE)));
+  return d.rows[r * d.w + c];
+}
+
+/**
+ * How far the feet are, as a floor row below the horizon. On the floor that is their screen row. On a raised
+ * floor (a deck, a step) the depth map says more, and the surface there still runs away from the camera:
+ * the depth there wins. On an upright face (the side of a bridge a floor mask took in) the person is behind
+ * that face, not on it: their screen row stays, so the face hides them.
+ */
+export function standRow(g: Pick<Geometry, 'scale' | 'steps'>, d: Depth, x: number, feetY: number): number {
+  const row = feetY - g.scale.horizonY;
+  // Stairs read from the painting (geometry.steps) are a raised floor by definition, risers and all.
+  if (g.steps?.length && stepAt(g as Geometry, x, feetY)) return Math.max(row, depthAt(d, x, feetY - 1));
+  // What is painted at the feet may stand in front of them (a post they are behind): that is not their floor.
+  const c = Math.min(d.w - 1, Math.max(0, Math.floor(x / DEPTH_SCALE)));
+  const r = Math.min(d.h - 1, Math.max(0, Math.floor((feetY - 1) / DEPTH_SCALE)));
+  if (contactRows(g, d)[r * d.w + c] > feetY + 2) return row;
+  return floorSlope(g, d, x, feetY) >= FLOOR_SLOPE ? Math.max(row, depthAt(d, x, feetY - 1)) : row;
+}
+
+/**
+ * Depth gained per screen row over the ground just behind the feet: the least of a short look (a few px) and a
+ * long one (a third of a person's height), so a low face with the sky just above it still reads as a face.
+ */
+export function floorSlope(g: Pick<Geometry, 'scale'>, d: Depth, x: number, feetY: number): number {
+  const at = depthAt(d, x, feetY - 1);
+  const slope = (span: number) => (at - depthAt(d, x, feetY - 1 - span)) / span;
+  return Math.min(slope(4 * DEPTH_SCALE), slope(Math.max(12, 0.3 * g.scale.pxPerY * (feetY - g.scale.horizonY))));
+}
+
+/** Width of a person's box for a height (a standing figure's sheet is about this wide). */
+export const PERSON_WIDTH = 0.36;
+
+/** The share of a person's box, at (x, feetY), that the painting stands in front of where no card (`owned`) does. */
+export function hiddenShare(g: Pick<Geometry, 'scale' | 'steps'>, d: Depth, x: number, feetY: number, owned?: Uint8Array): number {
+  const h = Math.max(8, g.scale.pxPerY * (feetY - g.scale.horizonY));
+  const half = Math.max(2, (PERSON_WIDTH * h) / 2);
+  const limit = frontRow(standRow(g, d, x, feetY));
+  const contact = contactRows(g, d);
+  let hid = 0;
+  let n = 0;
+  for (let y = feetY - h; y < feetY - 2; y += DEPTH_SCALE) {
+    const r = Math.min(d.h - 1, Math.max(0, Math.floor(y / DEPTH_SCALE)));
+    for (let px = x - half; px <= x + half; px += DEPTH_SCALE) {
+      const i = r * d.w + Math.min(d.w - 1, Math.max(0, Math.floor(px / DEPTH_SCALE)));
+      if (owned?.[i]) continue;
+      n++;
+      if (d.rows[i] > limit && contact[i] > feetY + 2) hid++;
+    }
+  }
+  return n ? hid / n : 0;
+}
+
+/** The floor row nearer than which the painting stands in front of feet at `stand`. */
+export const frontRow = (stand: number) => stand + Math.max(FRONT_MIN_ROWS, FRONT_SHARE * stand);
+
+/**
+ * Pixels of the frame rect [x0, y0, x1, y1) (whole px) where the painting stands in front of someone whose
+ * feet are at (x, feetY): 1 per pixel, row by row. `owned` (at the depth map's size) marks pixels a card
+ * looks after; they are left to it. Null when nothing is in front.
+ */
+export function frontMask(g: Pick<Geometry, 'scale' | 'frame' | 'steps'>, d: Depth, rect: [number, number, number, number], x: number, feetY: number, owned?: Uint8Array): Uint8Array | null {
+  const [x0, y0, x1, y1] = rect;
+  const w = x1 - x0;
+  const h = y1 - y0;
+  if (w <= 0 || h <= 0) return null;
+  if (hiddenShare(g, d, x, feetY, owned) > MAX_HIDDEN) return null;
+  const limit = frontRow(standRow(g, d, x, feetY));
+  const contact = contactRows(g, d);
+  const out = new Uint8Array(w * h);
+  let any = false;
+  for (let y = y0; y < y1; y++) {
+    if (y < 0 || y >= g.frame.height) continue;
+    const r = Math.min(d.h - 1, Math.floor(y / DEPTH_SCALE));
+    for (let px = x0; px < x1; px++) {
+      if (px < 0 || px >= g.frame.width) continue;
+      const c = Math.min(d.w - 1, Math.floor(px / DEPTH_SCALE));
+      const i = r * d.w + c;
+      if (owned?.[i] || d.rows[i] <= limit || contact[i] <= feetY + 2) continue;
+      out[(y - y0) * w + (px - x0)] = 1;
+      any = true;
+    }
+  }
+  return any ? out : null;
+}

package/app/src/play/exit-outline.ts

@@ -0,0 +1,48 @@
+// Visual coverage for a walkable exit. Never used as a collision or interaction mask.
+import type { Geometry, GeoThing } from './geometry.ts';
+export type OutlineMask = { bits: Uint8Array; area: number };
+export function exitOutline(mask: OutlineMask, thing: GeoThing, g: Geometry): { mask: OutlineMask; box: [number,number,number,number] } | undefined {
+  if (thing.role !== 'exit' || !['walk-on','flat'].includes(thing.kind ?? '')) return;
+  const {width:W,height:H}=g.frame;
+  const left=new Int32Array(H).fill(W),right=new Int32Array(H).fill(-1);
+  for(let y=0;y<H;y++)for(let x=0;x<W;x++)if(mask.bits[y*W+x]){left[y]=Math.min(left[y],x);right[y]=x;}
+  // Steps are measured independently of the exit's object mask. Only include bands
+  // that overlap its painted pixels, then follow that same run through neighbouring bands.
+  const bands=(g.steps ?? []).map(step=>{
+    const rows:Array<[number,number,number]>=[]; let overlap=0,total=0;
+    for(let i=0;i<step.top.length;i++) {
+      const top=step.top[i],bottom=step.bottom[i];if(top<0||bottom<top)continue;
+      for(let x=Math.max(0,Math.round(step.x0+i*step.every));x<Math.min(W,Math.round(step.x0+(i+1)*step.every));x++) {
+        const a=Math.max(0,Math.floor(top)),b=Math.min(H-1,Math.ceil(bottom));
+        rows.push([x,a,b]);for(let y=a;y<=b;y++){total++;if(mask.bits[y*W+x])overlap++;}
+      }
+    }
+    const box = rows.length ? [Math.min(...rows.map(r=>r[0])),Math.min(...rows.map(r=>r[1])),Math.max(...rows.map(r=>r[0]))+1,Math.max(...rows.map(r=>r[2]))+1] : [0,0,0,0];
+    return {rows,overlap,total,box};
+  });
+  // Seed from observed steps and follow adjacent bands with substantial horizontal
+  // overlap. This reaches an edge tread outside the object's truncated box.
+  const selected=new Set(bands.filter(b=>b.total && b.overlap/b.total>.1));
+  let added=true;
+  while(added){added=false;for(const band of bands)if(band.total&&!selected.has(band))for(const near of selected){
+    const a=band.box,b=near.box;
+    const overlap=Math.min(a[2],b[2])-Math.max(a[0],b[0]);
+    const gap=Math.max(0,a[1]-b[3],b[1]-a[3]);
+    if(overlap/Math.max(1,Math.min(a[2]-a[0],b[2]-b[0]))>.6 && gap<=Math.max(8,H*.03)) {selected.add(band);added=true;break;}
+  }}
+  for(const band of selected)for(const [x,a,b]of band.rows)for(let y=a;y<=b;y++){left[y]=Math.min(left[y],x);right[y]=Math.max(right[y],x);}
+  const rows=Array.from({length:H},(_,y)=>y).filter(y=>right[y]>=left[y]);
+  if(!rows.length)return;
+  // Bridge missing risers between observed rows, rather than outlining each tread.
+  for(let i=1;i<rows.length;i++) {
+    const a=rows[i-1],b=rows[i];
+    if(b-a>Math.max(32,H*.15))continue;
+    for(let y=a+1;y<b;y++){const t=(y-a)/(b-a);left[y]=Math.round(left[a]*(1-t)+left[b]*t);right[y]=Math.round(right[a]*(1-t)+right[b]*t);}
+  }
+  const bits=new Uint8Array(W*H);let area=0,x0=W,y0=H,x1=0,y1=0;
+  for(let y=0;y<H;y++)if(right[y]>=left[y]){
+    bits.fill(1,y*W+left[y],y*W+right[y]+1);area+=right[y]-left[y]+1;
+    x0=Math.min(x0,left[y]);x1=Math.max(x1,right[y]+1);y0=Math.min(y0,y);y1=y+1;
+  }
+  return {mask:{bits,area},box:[x0,y0,x1,y1]};
+}

package/app/src/play/face3d.ts

@@ -0,0 +1,34 @@
+// Named facial poses shared by the GLB capability report and its browser renderer.
+import { mouthOpening, mouthRoundness, type FaceState, type Mouth } from './lipsync.ts';
+export type FaceControl = 'jaw' | 'blink' | 'blinkLeft' | 'blinkRight' | 'brow' | 'funnel' | 'pucker' | 'sil' | 'mbp' | 'ih' | 'eh' | 'aa' | 'oh' | 'ou' | 'fv' | 'l';
+const aliases: Record<string, FaceControl> = {
+  jawopen: 'jaw', mouthopen: 'jaw', eyeblink: 'blink', blink: 'blink', eyeblinkleft: 'blinkLeft', blinkleft: 'blinkLeft', eyeblinkright: 'blinkRight', blinkright: 'blinkRight',
+  browinnerup: 'brow', browouterupleft: 'brow', browouterupright: 'brow', mouthfunnel: 'funnel', mouthpucker: 'pucker',
+  visemesil: 'sil', vrcvsil: 'sil', visemepp: 'mbp', vrcvpp: 'mbp', visemembp: 'mbp',
+  visemess: 'ih', vrcvss: 'ih', visemekk: 'ih', vrcvkk: 'ih', visemett: 'ih', vrcvtt: 'ih', visemech: 'ih', vrcvch: 'ih', visemeih: 'ih', visemei: 'ih', vrcvih: 'ih', vrcvi: 'ih', visemedd: 'ih', vrcvdd: 'ih', visemeth: 'ih', vrcvth: 'ih', visemerr: 'ih', vrcvrr: 'ih', i: 'ih', ih: 'ih',
+  visemee: 'eh', vrcve: 'eh', visemeeh: 'eh', e: 'eh', eh: 'eh',
+  visemeaa: 'aa', vrcvaa: 'aa', a: 'aa', aa: 'aa',
+  visemeo: 'oh', visemeoh: 'oh', vrcvoh: 'oh', vrcvo: 'oh', o: 'oh', oh: 'oh',
+  visemeu: 'ou', visemeou: 'ou', vrcvou: 'ou', vrcvu: 'ou', u: 'ou', ou: 'ou',
+  visemeff: 'fv', vrcvff: 'fv', visemefv: 'fv', visemenn: 'l', vrcvnn: 'l', visemel: 'l',
+};
+export const facialControl = (name: string): FaceControl | undefined => aliases[name.toLowerCase().replace(/[^a-z]/g, '')];
+const viseme: Record<Mouth, FaceControl> = { X: 'sil', A: 'mbp', B: 'ih', C: 'eh', D: 'aa', E: 'oh', F: 'ou', G: 'fv', H: 'l' };
+export const isViseme = (control: FaceControl) => ['sil', 'mbp', 'ih', 'eh', 'aa', 'oh', 'ou', 'fv', 'l'].includes(control);
+export function faceWeight(control: FaceControl, state: FaceState, nativeVisemes: boolean | ReadonlySet<FaceControl> = false): number {
+  if (control.startsWith('blink')) return state.blink;
+  if (control === 'brow') return state.brow;
+  const native = (mouth: Mouth) => typeof nativeVisemes === 'boolean' ? nativeVisemes : nativeVisemes.has(viseme[mouth]);
+  const fallback = (amount: (mouth: Mouth) => number) => (native(state.previous) ? 0 : amount(state.previous) * (1 - state.mix)) + (native(state.mouth) ? 0 : amount(state.mouth) * state.mix);
+  if (control === 'jaw') return fallback(mouth => mouthOpening[mouth]);
+  if (control === 'funnel') return fallback(mouthRoundness) * 0.65;
+  if (control === 'pucker') return fallback(mouthRoundness) * 0.4;
+  return (viseme[state.previous] === control ? 1 - state.mix : 0) + (viseme[state.mouth] === control ? state.mix : 0);
+}
+
+/** Rhubarb groups consonants; choose one representative pose instead of adding SS, KK and CH together. */
+export function facialPriority(name: string): number {
+  const normal = name.toLowerCase().replace(/[^a-z]/g, '');
+  if (facialControl(name) !== 'ih') return 0;
+  return /(?:ih|visemei|vrcvi)$/.test(normal) || normal === 'i' ? 0 : /ss$/.test(normal) ? 1 : 2;
+}

package/app/src/play/focus.ts

@@ -0,0 +1,78 @@
+// focus: what sets a person apart from the painted thing at their back. Both are painted equally sharp and
+// equally lit, so the runtime adds the cues: a rim of light on the person's lit edge, a soft shade they throw
+// on what stands just behind them (only there, by the depth map), and, opt-in, the camera's focus on the hero
+// softening what is far behind.
+// No Node imports: the browser bundles this file.
+import type { Depth } from './shadow.ts';
+
+/** Frame px of blur at full defocus (the sky, the far sea when the hero is near). */
+export const FOCUS_BLUR = 1.4;
+/** Behind the focus by this share of its depth, a thing is fully soft (five times as far as the hero). */
+const FULL = 0.8;
+/** The first few % behind the feet stay sharp: the floor the hero stands on. */
+const SHARP = 0.03;
+
+/**
+ * How soft each depth pixel is, 0..1, with the focus on a floor row `focus` px below the horizon. Depth rows
+ * are inverse distance, so the defocus of a pixel grows with how far its rows fall short of the focus (a thin
+ * lens's blur circle is linear in 1/z - 1/z_focus); scaled by the focus itself, so the look is the same whether
+ * the hero stands near or far. Nearer than the focus stays sharp: those things are drawn over the hero anyway.
+ * A pixel with no depth (rows 0, the sky) counts as far.
+ */
+export function softness(rows: number, focus: number): number {
+  if (focus <= 0) return 0;
+  const t = (focus * (1 - SHARP) - Math.max(0, rows)) / (focus * FULL);
+  if (t <= 0) return 0;
+  // Linear: just behind the hero it barely shows, only the far view goes really soft.
+  return Math.min(1, t);
+}
+
+/** The softness of every depth pixel as an alpha mask (RGBA, white), for compositing the soft frame. */
+export function focusMask(d: Depth, focus: number, out: Uint8ClampedArray = new Uint8ClampedArray(d.w * d.h * 4)): Uint8ClampedArray {
+  for (let i = 0; i < d.w * d.h; i++) {
+    out[i * 4] = out[i * 4 + 1] = out[i * 4 + 2] = 255;
+    out[i * 4 + 3] = Math.round(255 * softness(d.rows[i], focus));
+  }
+  return out;
+}
+
+/**
+ * A stand-in depth map for a place without depth.png (no fit, or built before it existed): the floor plane
+ * below the horizon, and above each column's back edge whatever stands there (a wall, a railing) as far as
+ * that edge. Above the horizon is the far view. Cards stamp their own floor row over it (see the runtime).
+ */
+export function planeDepth(frame: { width: number; height: number }, horizonY: number, cell: number, edge: ArrayLike<number>, scale: number): Depth {
+  const [w, h] = [Math.ceil(frame.width / scale), Math.ceil(frame.height / scale)];
+  const rows = new Float32Array(w * h);
+  for (let r = 0; r < h; r++) {
+    const y = r * scale + scale / 2;
+    for (let c = 0; c < w; c++) {
+      const e = edge[Math.min(edge.length - 1, Math.floor((c * scale) / cell))] ?? horizonY;
+      rows[r * w + c] = y <= horizonY ? 0 : Math.max(0, (y < e ? e : y) - horizonY);
+    }
+  }
+  return { w, h, rows };
+}
+
+/** The separation shade: its darkness, blur and push away from the light, per person height. */
+export const SEPARATE_ALPHA = 0.8;
+export const SEPARATE_BLUR = 0.05;
+export const SEPARATE_SHIFT = 0.12;
+/** Things up to this share of the feet's depth farther still take the shade, fading to none there. */
+const BEHIND = 0.3;
+
+/**
+ * How much of a person's separation shade lands on a depth pixel, for feet `feet` rows below the horizon:
+ * full on what stands right at or just behind them (the plinth at their back, the floor at their heels),
+ * fading over BEHIND of their depth, none on what is nearer (it is drawn over them) or has no depth (the sky).
+ */
+export function behindWeight(rows: number, feet: number): number {
+  if (rows <= 0 || feet <= 0 || rows > feet * 1.03) return 0;
+  const t = (feet - rows) / (feet * BEHIND);
+  return Math.max(0, 1 - Math.max(0, t));
+}
+
+/** The rim light on a person's lit edge: how wide per height, its colour and how strong. */
+export const RIM_WIDTH = 0.022;
+export const RIM_COLOUR = '#ffe9c8';
+export const RIM_ALPHA = 0.85;

package/app/src/play/geometry.ts

@@ -0,0 +1,272 @@
+// geometry.json: what the game needs to know about a painted place to walk in it.
+// derive writes it from the masks; the runtime only reads it. No Node imports: the browser bundles this file.
+import { z } from 'zod';
+
+const XY = z.tuple([z.number(), z.number()]);
+const Box = z.tuple([z.number(), z.number(), z.number(), z.number()]).describe('x0, y0, x1, y1');
+
+export const Geometry = z.object({
+  frame: z.object({ width: z.number().int().positive(), height: z.number().int().positive() }),
+  cell: z.number().int().positive(),
+  /** Grid rows from the top; '#' is walkable, anything else is not. */
+  walk: z.array(z.string()).min(1),
+  /** Same shape as walk; a digit is the floor's index in layout order, '.' is no floor. */
+  zone: z.array(z.string()).optional(),
+  /** A 1.62 m person standing with feet at y is pxPerY * (y - horizonY) px tall. */
+  scale: z.object({ horizonY: z.number(), pxPerY: z.number().positive(), source: z.enum(['spark', 'anchors', 'layout']).optional() }),
+  start: XY,
+  things: z.array(z.object({
+    key: z.string(),
+    role: z.enum(['prop', 'exit', 'item', 'npc']).optional(),
+    kind: z.enum(['standing', 'wall', 'on-top', 'walk-on', 'flat']).optional(),
+    box: Box,
+    mask: z.string().optional().describe('path relative to the place folder; npcs have none'),
+    stand: XY.describe('walkable spot to stand at when using it'),
+    coarse: z.boolean().optional(),
+    /** Where this thing was, painted empty (plates/<thing>.png: the patch only, transparent elsewhere), drawn once the story carries it off. */
+    plate: z.string().optional(),
+  })),
+  /** One per connected blob of a thing's mask; it hides the mask's pixels inside its box. */
+  occluders: z.array(z.object({
+    key: z.string().describe('"barrel#1"'),
+    thing: z.string().optional(),
+    box: Box,
+    mask: z.string().optional(),
+    /** Always drawn over the hero (a framing tree, an arch). */
+    front: z.boolean().optional(),
+    baseY: z.number(),
+    /** Where it meets the floor, per column, x ascending. Falls back to baseY. */
+    floor: z.array(XY).optional(),
+    /** Key of the occluder it sits on (a pot on a table): it hides exactly when that one does. */
+    on: z.string().optional(),
+    /** Floor footprint rows [x, back, front], for QA; derive already blocks those cells. */
+    foot: z.array(z.tuple([z.number(), z.number(), z.number()])).optional(),
+  })),
+  /**
+   * How the painting is lit, so people cast and catch shadows like the things around them.
+   * dir: the way shadows fall across the floor in screen px (unit-ish; +x right, +y towards the viewer).
+   * length: a shadow's floor length as a share of the caster's height (0.3 high sun, 1.5+ low sun).
+   * strength: how dark painted shadows are, 0..1 (fog ~0.15, hard sun ~0.5). Omitted: no cast shadow.
+   */
+  /**
+   * The light the painting is lit by. dir/length: how shadows run on screen per height (the sun). With `at`
+   * the light is a fire or a lamp standing on the floor there: shadows run away from it, each its own way.
+   * flame: that light is a living flame (a fire, a torch, a candle): it flickers, and the shadows with it.
+   * also: where its twins stand (a row of the same lamp posts): no one of them is the key light, so a person
+   * casts no long shadow one way, only the soft one under the feet; the nearest lamp still rims them.
+   */
+  light: z.object({ dir: XY, length: z.number().nonnegative(), strength: z.number().min(0).max(1), at: XY.optional(), flame: z.boolean().optional(), also: z.array(XY).optional() }).optional(),
+  /** Mask (relative to the place folder) of painted shadows on floors: a person standing in one is darkened. */
+  shadows: z.string().optional(),
+  /**
+   * How far every pixel is (depth.png, half the frame): as the floor row at the same distance, rows below
+   * horizonY * 16 in R (high byte) and G (low byte). With it a cast shadow follows steps, walls and drops.
+   */
+  depth: z.string().optional(),
+  /**
+   * Stair steps, top to bottom: each one's band (its tread and the riser below it) per column, sampled every
+   * `every` px from x0 (-1 where the step doesn't reach). People's feet stay on a tread and step between them.
+   */
+  steps: z.array(z.object({ x0: z.number(), every: z.number().positive(), top: z.array(z.number()), bottom: z.array(z.number()) })).optional(),
+  /**
+   * Where layout.lights were painted (src/scene/glows.ts): the runtime glows sit here, not on the planned
+   * points. A light missing from the list was painted nowhere near its point and gets no glow.
+   */
+  glows: z.array(z.object({ key: z.string(), x: z.number(), y: z.number() })).optional(),
+  flagged: z.array(z.string()).optional(),
+  /** Made from layout.json, not measured from the painting. */
+  preview: z.boolean().optional(),
+});
+export type Geometry = z.infer<typeof Geometry>;
+export type Occluder = Geometry['occluders'][number];
+export type GeoThing = Geometry['things'][number];
+
+/** A person's height in px with feet at y; never below a few px so far spots stay visible. */
+export function personPx(g: Geometry, feetY: number): number {
+  return Math.max(8, g.scale.pxPerY * (feetY - g.scale.horizonY));
+}
+
+/**
+ * How much more floor one screen pixel up or down covers than one sideways, at feet y: the floor is foreshortened,
+ * so a step into the picture moves the feet fewer pixels than a step across it. A ~50° lens (focal ≈ the frame's
+ * width) over the place's horizon; held to 1..3 so a far horizon cannot freeze anyone.
+ */
+export function depthStretch(g: Geometry, feetY: number): number {
+  const below = feetY - g.scale.horizonY;
+  return below > 0 ? Math.min(3, Math.max(1, 1100 / below)) : 3;
+}
+
+/** The occluder's floor line at column x: interpolated, flat past either end, baseY without a line. */
+export function floorYAt(o: Occluder, x: number): number {
+  const line = o.floor;
+  if (!line?.length) return o.baseY;
+  if (x <= line[0][0]) return line[0][1];
+  for (let i = 1; i < line.length; i++) {
+    const [x1, y1] = line[i];
+    if (x <= x1) {
+      const [x0, y0] = line[i - 1];
+      return x1 === x0 ? y1 : y0 + ((y1 - y0) * (x - x0)) / (x1 - x0);
+    }
+  }
+  return line[line.length - 1][1];
+}
+
+/** Feet this close in front of a floor line still count as standing at it, not behind it. */
+export const BEHIND_MARGIN = 6;
+
+/** Whether the occluder hides a person whose feet are at feetY, in column x. `support` resolves `on`. */
+export function hides(o: Occluder, x: number, feetY: number, support?: (key: string) => Occluder | undefined): boolean {
+  if (o.front) return true;
+  const under = o.on ? support?.(o.on) : undefined;
+  if (under && under !== o) return hides(under, x, feetY);
+  return feetY < floorYAt(o, x) - BEHIND_MARGIN;
+}
+
+/** Column runs [x0, x1) inside [left, right) where the occluder hides the person; a few runs per occluder. */
+export function hiddenRuns(o: Occluder, left: number, right: number, feetY: number, support?: (key: string) => Occluder | undefined): Array<[number, number]> {
+  const runs: Array<[number, number]> = [];
+  const x0 = Math.max(Math.floor(left), Math.floor(o.box[0]));
+  const x1 = Math.min(Math.ceil(right), Math.ceil(o.box[2]));
+  let start = -1;
+  for (let x = x0; x < x1; x++) {
+    const hid = hides(o, x + 0.5, feetY, support);
+    if (hid && start < 0) start = x;
+    if (!hid && start >= 0) {
+      runs.push([start, x]);
+      start = -1;
+    }
+  }
+  if (start >= 0) runs.push([start, x1]);
+  return runs;
+}
+
+/** Where a tread puts the feet, as a share of the step's band from its top. */
+const TREAD = 0.35;
+
+/** The step bands [top, bottom] under column x, top first. */
+export function stepBands(g: Geometry, x: number): Array<[number, number]> {
+  const out: Array<[number, number]> = [];
+  for (const s of g.steps ?? []) {
+    const i = Math.round((x - s.x0) / s.every);
+    if (i < 0 || i >= s.top.length || s.top[i] < 0 || s.bottom[i] <= s.top[i]) continue;
+    out.push([s.top[i], s.bottom[i]]);
+  }
+  return out.sort((a, b) => a[0] - b[0]);
+}
+
+/** The step of g.steps a walker at (x, y) stands on, and how far down its band (0 top, 1 bottom). */
+export function stepAt(g: Geometry, x: number, y: number): { step: number; at: number } | undefined {
+  let best: { step: number; at: number } | undefined;
+  (g.steps ?? []).forEach((s, step) => {
+    const i = Math.round((x - s.x0) / s.every);
+    if (i < 0 || i >= s.top.length || s.top[i] < 0 || s.bottom[i] <= s.top[i]) return;
+    const at = (y - s.top[i]) / (s.bottom[i] - s.top[i]);
+    // Neighbouring bands overlap a little: the one the walker is deeper inside wins.
+    if (at >= 0 && at <= 1 && (!best || Math.abs(at - 0.5) < Math.abs(best.at - 0.5))) best = { step, at };
+  });
+  return best;
+}
+
+/** The y at column x that is `at` of the way down step `step`'s band; undefined where the step isn't. */
+export function onStep(g: Geometry, step: number, x: number, at: number): number | undefined {
+  const s = g.steps?.[step];
+  const i = s ? Math.round((x - s.x0) / s.every) : -1;
+  if (!s || i < 0 || i >= s.top.length || s.top[i] < 0 || s.bottom[i] <= s.top[i]) return undefined;
+  return s.top[i] + at * (s.bottom[i] - s.top[i]);
+}
+
+/** Where feet stand on step `step` at column x: the same tread height stepFootY holds them at. */
+export function treadY(g: Geometry, step: number, x: number): number | undefined {
+  return onStep(g, step, x, TREAD);
+}
+
+const smooth = (u: number) => u * u * (3 - 2 * u);
+
+/**
+ * Where the feet are drawn for a walker at (x, y) on stairs: held on each tread, then a quick step over the
+ * riser to the next, instead of gliding up a ramp. Off the stairs it is y. Size and depth still follow y.
+ */
+export function stepFootY(g: Geometry, x: number, y: number): number {
+  const bands = stepBands(g, x);
+  if (!bands.length || y <= bands[0][0] || y >= bands[bands.length - 1][1]) return y;
+  // Control points (walker y -> foot y): flat on each tread's middle half, eased between.
+  const pts: Array<[number, number]> = [[bands[0][0], bands[0][0]]];
+  for (const [t, b] of bands) {
+    const h = b - t;
+    const foot = t + TREAD * h;
+    const a = Math.max(t + 0.25 * h, pts[pts.length - 1][0]);
+    pts.push([a, foot], [Math.max(a, b - 0.25 * h), foot]);
+  }
+  const last = bands[bands.length - 1][1];
+  pts.push([last, last]);
+  for (let k = 1; k < pts.length; k++) {
+    const [y0, f0] = pts[k - 1];
+    const [y1, f1] = pts[k];
+    if (y > y1) continue;
+    return y1 > y0 ? f0 + (f1 - f0) * smooth((y - y0) / (y1 - y0)) : f1;
+  }
+  return y;
+}
+
+/**
+ * A walker's resting y on stairs: where it is when the feet stand on a tread, otherwise the next spot
+ * ahead (`dir` -1 walking up the picture, 1 down) where they do, so nobody stops mid-step or steps back.
+ */
+export function stepRestY(g: Geometry, x: number, y: number, dir = 1): number {
+  const flat = (v: number) => Math.abs(stepFootY(g, x, v + 1) - stepFootY(g, x, v - 1)) < 0.01;
+  const bands = stepBands(g, x);
+  if (!bands.length || flat(y)) return y;
+  const step = dir < 0 ? -1 : 1;
+  for (let v = y + step; v > bands[0][0] - 2 && v < bands[bands.length - 1][1] + 2; v += step) if (flat(v)) return v;
+  return y;
+}
+
+/**
+ * The light on a person standing at (x, y), px tall: the sun as it is, or for a fire or a lamp (light.at)
+ * a shadow running straight away from it, longer the farther they stand, fading out a few heights away.
+ * Undefined when the person is too far from the fire for it to throw a shadow.
+ */
+export function lightFor(g: Geometry, x: number, y: number, px: number, t?: number): Geometry['light'] {
+  const light = g.light;
+  if (!light?.at) return light;
+  // A row of alike lamps: the one lighting this person most.
+  return [flameAt(g, t), ...(light.also ?? [])].map((at) => lampLight(light, at, x, y, px, t)).reduce((a, b) => (!a || (b && b.strength > a.strength) ? b : a), undefined);
+}
+
+/** Whether a person's shadow is cast one way: not under a row of alike lamps, where no one of them is the key light. */
+export function castsShadow(g: Geometry): boolean {
+  return !!g.light && !g.light.also?.length;
+}
+
+/** The light of a lamp or a fire standing at `at` on a person at (x, y), px tall; undefined out of its reach. */
+function lampLight(light: NonNullable<Geometry['light']>, at: [number, number], x: number, y: number, px: number, t?: number): Geometry['light'] {
+  const [dx, dy] = [x - at[0], y - at[1]];
+  const d = Math.hypot(dx, dy);
+  const reach = 4 * px;
+  if (d >= reach) return undefined;
+  // Right at the fire the shadow still has a way: toward the viewer.
+  const dir: [number, number] = d > 1 ? [dx / d, dy / d] : [0, 1];
+  // A flame lower than the head throws a long shadow, longer the farther away the person is.
+  const length = Math.min(3, 0.9 + (1.2 * d) / px);
+  return { dir, length, strength: light.strength * (1 - d / reach) * (t === undefined || !light.flame ? 1 : 1 + FLAME_GLOW * flicker(t).glow), at, flame: light.flame };
+}
+
+/** How far a flame sways (metres to either side) and how much its light breathes (share of its strength). */
+export const FLAME_SWAY_M = 0.1;
+export const FLAME_GLOW = 0.12;
+
+/** A flame's flicker at time t (s): sway side to side and glow, each -1..1, smooth and never quite repeating. */
+export function flicker(t: number): { sway: number; glow: number } {
+  return {
+    sway: 0.55 * Math.sin(t * 2.1) + 0.3 * Math.sin(t * 5.3 + 1.7) + 0.15 * Math.sin(t * 11.9 + 0.4),
+    glow: 0.5 * Math.sin(t * 7.7 + 0.9) + 0.3 * Math.sin(t * 13.1 + 2.3) + 0.2 * Math.sin(t * 3.1),
+  };
+}
+
+/** Where the light stands at time t: a flame sways a little side to side; any other light stays put. */
+export function flameAt(g: Geometry, t?: number): [number, number] {
+  const light = g.light!;
+  const at = light.at!;
+  if (t === undefined || !light.flame) return at;
+  return [at[0] + flicker(t).sway * personPx(g, at[1]) * (FLAME_SWAY_M / 1.62), at[1]];
+}

package/app/src/play/gestures.ts

@@ -0,0 +1,23 @@
+// Talking gestures: what a character does with the hands and head while a line is spoken. The story picks
+// one per line; `diorama sprites` draws only those the story uses. No Node imports: the browser bundles this.
+
+/**
+ * A standing pose: where each upper arm points (world, the figure facing +z, its left at +x), how far
+ * the elbow bends, and the head's nod and tilt. Elbows stay near the body: a long coat is skinned to
+ * the upper arms and flares into a cape otherwise.
+ */
+export type Pose = { left?: [number, number, number, number]; right?: [number, number, number, number]; nod?: number; tilt?: number; lean?: number };
+
+export const GESTURES = [
+  { name: 'listen', means: 'hands down, listening or saying something plain', pose: {} },
+  { name: 'open-hand', means: 'one hand raised, palm open: offering, greeting, a friendly point', pose: { right: [-0.2, -0.9, 0.35, 1.7] } },
+  { name: 'explain', means: 'both hands forward: explaining, describing, reasoning', pose: { left: [0.25, -0.92, 0.3, 1.3], right: [-0.25, -0.92, 0.3, 1.3] } },
+  { name: 'point', means: 'pointing ahead: directions, "over there", "that one"', pose: { right: [-0.1, -0.75, 0.65, 0.9], lean: 0.04 } },
+  { name: 'shrug', means: 'shrug, forearms out: not knowing, doubt, "who knows"', pose: { left: [0.2, -0.95, 0.15, 1.4], right: [-0.2, -0.95, 0.15, 1.4], tilt: 0.15 } },
+  { name: 'chest', means: 'hand on the chest: about oneself, a promise, feeling', pose: { left: [0.1, -0.95, 0.3, 2.1], nod: 0.1 } },
+  { name: 'nod', means: 'nodding: yes, agreeing, thanks', pose: { right: [-0.2, -0.92, 0.3, 1.2], nod: 0.25 } },
+  { name: 'together', means: 'hands together: asking, pleading, worried', pose: { left: [0.08, -0.92, 0.38, 1.5], right: [-0.08, -0.92, 0.38, 1.5] } },
+] as const satisfies readonly { name: string; means: string; pose: Pose }[];
+
+export type GestureName = (typeof GESTURES)[number]['name'];
+export const gestureIndex = (name: string) => GESTURES.findIndex((g) => g.name === name);