@idle-screens/schema 3.7.0 → 3.8.0

package/dist/index.js

@@ -12,6 +12,8 @@ var LIMITS = {
   // ms — caps pulse at 2 Hz (WCAG flash threshold is 3 Hz)
   maxSpin: 360,
   // degrees/sec — one full revolution per second
+  maxRotate: 360,
+  // degrees — static per-entity rotation, one turn either way
   maxGrowAmp: 0.8,
   // size breathing amplitude cap (fraction of base size)
   maxOrbitSpeed: 180,
@@ -27,9 +29,19 @@ var LIMITS = {
   maxTrailSamples: 24,
   // dots per trail
   minDriftPeriod: 1e4,
-  // ms — background drift floor (10 s)
+  // ms — background drift floor (10 s), gradient and field alike
   maxDriftAmount: 0.3,
   // fraction of gradient stop shift
+  minFieldScale: 0.5,
+  // features per short side — below this the field is one flat blob
+  maxFieldScale: 8,
+  // above this a 96 px raster cell spans more than one feature
+  maxFieldOctaves: 4,
+  minFieldBands: 2,
+  maxFieldBands: 8,
+  maxFieldQuantize: 8,
+  maxFieldDriftAmount: 1,
+  // feature units of domain travel
   maxGhosting: 0.95,
   // frame persistence cap — bounds the seek warm-up replay
   maxGhostReplayFrames: 120,
@@ -84,16 +96,19 @@ var LIMITS = {
 
 // src/steer.ts
 var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-var STEERABLE_ROOT_KEYS = /* @__PURE__ */ new Set(["ghosting", "referenceViewport"]);
+var STEERABLE_ROOT_KEYS = /* @__PURE__ */ new Set(["ghosting", "referenceViewport", "finish"]);
 function resolveSpecPath(spec, path) {
   if (!spec || typeof spec !== "object" || !path) return null;
   const parts = path.split(".");
   if (parts.some((p) => UNSAFE_KEYS.has(p))) return null;
   const s = spec;
-  if (parts[0] !== "layers" && parts[0] !== "background" && !STEERABLE_ROOT_KEYS.has(parts[0]) && Array.isArray(s.layers)) {
+  if (parts[0] !== "layers" && parts[0] !== "background" && Array.isArray(s.layers)) {
     const idx = s.layers.findIndex((l) => l && l.key === parts[0]);
-    if (idx === -1) return null;
-    parts.splice(0, 1, "layers", String(idx));
+    if (idx !== -1) {
+      parts.splice(0, 1, "layers", String(idx));
+    } else if (!STEERABLE_ROOT_KEYS.has(parts[0])) {
+      return null;
+    }
   }
   let node = spec;
   for (let i = 0; i < parts.length - 1; i++) {
@@ -205,7 +220,11 @@ function morphNothingMorphable(a, b, opts = {}) {
 function steerablePaths(spec) {
   if (!spec || typeof spec !== "object") return [];
   const SKIP = /* @__PURE__ */ new Set(["kind", "type", "key", "schemaVersion", "id", "label", "seed", "units", "motionIntensity", "mode", "curve", "layer"]);
-  const INDEXED = /* @__PURE__ */ new Set(["layers", "stops"]);
+  const INDEXED = /* @__PURE__ */ new Set(["layers", "stops", "bands"]);
+  const layers = spec.layers;
+  const shadowedRootKeys = new Set(
+    Array.isArray(layers) ? layers.map((l) => l && typeof l === "object" ? l.key : void 0).filter((k) => typeof k === "string" && STEERABLE_ROOT_KEYS.has(k)) : []
+  );
   const out = [];
   const walk = (node, prefix, key) => {
     if (Array.isArray(node) && INDEXED.has(key)) {
@@ -219,6 +238,7 @@ function steerablePaths(spec) {
     if (node && typeof node === "object") {
       for (const [k, v] of Object.entries(node)) {
         if (SKIP.has(k)) continue;
+        if (!prefix && shadowedRootKeys.has(k)) continue;
         walk(v, prefix ? `${prefix}.${k}` : k, k);
       }
       return;
@@ -241,7 +261,10 @@ function easeSmooth(k) {
 function structuralSignature(spec) {
   return JSON.stringify([
     spec.units,
-    spec.referenceViewport,
+    // Normalized against the same default every renderer uses — an omitted
+    // referenceViewport and an explicit 1080 render identically, so they must
+    // hash identically or a same-sizing morph gets rejected as structural.
+    spec.referenceViewport ?? LIMITS.referenceViewport,
     spec.layers.map((l) => {
       const s = l.sprite;
       return [
@@ -267,7 +290,10 @@ function structuralSignature(spec) {
         l.sprite.kind === "rect" ? [s.width, s.aspect] : l.sprite.kind === "bar" ? [s.length, s.thickness] : void 0,
         Array.isArray(s.colors) ? s.colors.length : void 0,
         s.colorWeights,
-        l.sprite.kind === "emoji" ? [l.sprite.glyphs.length, l.sprite.cycle?.period] : l.sprite.kind === "text" ? [l.sprite.strings.length, l.sprite.cycle?.period] : l.sprite.kind === "textBlock" ? l.sprite.anchor ? [l.sprite.fontSize, l.sprite.anchor] : [l.sprite.fontSize] : void 0
+        l.sprite.kind === "emoji" ? [l.sprite.glyphs.length, l.sprite.cycle?.period] : l.sprite.kind === "text" ? [l.sprite.strings.length, l.sprite.cycle?.period] : l.sprite.kind === "textBlock" ? l.sprite.anchor ? [l.sprite.fontSize, l.sprite.anchor] : [l.sprite.fontSize] : void 0,
+        // Static rotation is baked into entities (a range draws a seeded
+        // angle). Appended only when set — same rule as `anchor` above.
+        ...l.rotate !== void 0 ? [l.rotate] : []
       ];
     })
   ]);
@@ -279,7 +305,8 @@ var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isStr = (v) => typeof v === "string";
 var isNum = (v) => typeof v === "number" && Number.isFinite(v);
 var isRange = (v) => Array.isArray(v) && v.length === 2 && isNum(v[0]) && isNum(v[1]) && v[0] <= v[1];
-var KNOWN_TOP = /* @__PURE__ */ new Set(["schemaVersion", "id", "label", "seed", "motionIntensity", "density", "units", "referenceViewport", "background", "layers", "ghosting"]);
+var KNOWN_TOP = /* @__PURE__ */ new Set(["schemaVersion", "id", "label", "seed", "motionIntensity", "density", "units", "referenceViewport", "background", "layers", "ghosting", "finish"]);
+var KNOWN_FINISH = /* @__PURE__ */ new Set(["grain", "dither", "animate"]);
 var KNOWN_LAYER = /* @__PURE__ */ new Set([
   "count",
   "sprite",
@@ -300,7 +327,8 @@ var KNOWN_LAYER = /* @__PURE__ */ new Set([
   "layout",
   "life",
   "emit",
-  "clock"
+  "clock",
+  "rotate"
 ]);
 var KNOWN_CIRCLE = /* @__PURE__ */ new Set(["kind", "radius", "color", "soft", "colors", "colorWeights"]);
 var KNOWN_RING = /* @__PURE__ */ new Set(["kind", "radius", "color", "width", "colors", "colorWeights"]);
@@ -327,7 +355,9 @@ var KNOWN_WARP = /* @__PURE__ */ new Set(["type", "speed", "center"]);
 var KNOWN_PATH = /* @__PURE__ */ new Set(["type", "points", "duration", "curve", "closed", "scatter"]);
 var KNOWN_BG_SOLID = /* @__PURE__ */ new Set(["type", "color"]);
 var KNOWN_BG_GRADIENT = /* @__PURE__ */ new Set(["type", "stops", "band", "drift"]);
-var LAYER_PROPS_ON_SPRITE = /* @__PURE__ */ new Set(["blend", "trail", "alpha", "pulse", "spin", "grow", "region", "links", "flip", "wrap", "key", "emit", "clock", "life", "layout"]);
+var KNOWN_BG_FIELD = /* @__PURE__ */ new Set(["type", "scale", "octaves", "warp", "quantize", "bands", "drift", "seed"]);
+var KNOWN_FIELD_DRIFT = /* @__PURE__ */ new Set(["period", "amount"]);
+var LAYER_PROPS_ON_SPRITE = /* @__PURE__ */ new Set(["blend", "trail", "alpha", "pulse", "spin", "grow", "region", "links", "flip", "wrap", "key", "emit", "clock", "life", "layout", "rotate"]);
 function unknownKeys(obj, known) {
   return Object.keys(obj).filter((k) => !known.has(k));
 }
@@ -383,6 +413,7 @@ function validateSpec(spec) {
     warn(k, "unknown-property", `unknown top-level property '${k}' \u2014 will be ignored`);
   }
   if (spec.background !== void 0) validateBackground(spec.background, err, warn);
+  if (spec.finish !== void 0) validateFinish(spec.finish, "finish", err, warn);
   if (!Array.isArray(spec.layers) || spec.layers.length === 0) {
     err("layers", "must be a non-empty array");
   } else {
@@ -399,6 +430,16 @@ function validateSpec(spec) {
 function color(v, path, err) {
   if (!isStr(v) || !HEX2.test(v)) err(path, "must be a hex colour like #0a3a52");
 }
+function validateFinish(f, path, err, warn) {
+  if (!isObj(f)) return err(path, "must be an object");
+  for (const k of ["grain", "dither"]) {
+    if (f[k] !== void 0 && (!isNum(f[k]) || f[k] < 0 || f[k] > 1)) err(`${path}.${k}`, "must be a number 0..1");
+  }
+  if (f.animate !== void 0 && typeof f.animate !== "boolean") err(`${path}.animate`, "must be a boolean");
+  for (const k of unknownKeys(f, KNOWN_FINISH)) {
+    warn(`${path}.${k}`, "unknown-property", `unknown finish property '${k}' \u2014 will be ignored`);
+  }
+}
 function validateBackground(bg, err, warn) {
   if (!isObj(bg)) return err("background", "must be an object");
   if (bg.type === "solid") {
@@ -436,8 +477,47 @@ function validateBackground(bg, err, warn) {
     for (const k of unknownKeys(bg, KNOWN_BG_GRADIENT)) {
       warn(`background.${k}`, "unknown-property", `unknown background property '${k}' \u2014 will be ignored`);
     }
+  } else if (bg.type === "field") {
+    validateFieldBackground(bg, err, warn);
   } else {
-    err("background.type", "must be solid | gradient");
+    err("background.type", "must be solid | gradient | field");
+  }
+}
+function validateFieldBackground(bg, err, warn) {
+  if (!isNum(bg.scale) || bg.scale < LIMITS.minFieldScale || bg.scale > LIMITS.maxFieldScale) {
+    err("background.scale", `must be a number ${LIMITS.minFieldScale}..${LIMITS.maxFieldScale} (features across the short side)`);
+  }
+  if (bg.octaves !== void 0 && (!isNum(bg.octaves) || !Number.isInteger(bg.octaves) || bg.octaves < 1 || bg.octaves > LIMITS.maxFieldOctaves)) {
+    err("background.octaves", `must be an integer 1..${LIMITS.maxFieldOctaves}`);
+  }
+  if (bg.warp !== void 0 && (!isNum(bg.warp) || bg.warp < 0 || bg.warp > 1)) {
+    err("background.warp", "must be a number 0..1");
+  }
+  if (bg.quantize !== void 0 && (!isNum(bg.quantize) || !Number.isInteger(bg.quantize) || bg.quantize < 0 || bg.quantize === 1 || bg.quantize > LIMITS.maxFieldQuantize)) {
+    err("background.quantize", `must be 0 (smooth) or an integer 2..${LIMITS.maxFieldQuantize}`);
+  }
+  if (!Array.isArray(bg.bands) || bg.bands.length < LIMITS.minFieldBands || bg.bands.length > LIMITS.maxFieldBands) {
+    err("background.bands", `must be ${LIMITS.minFieldBands}..${LIMITS.maxFieldBands} hex colours`);
+  } else {
+    for (let i = 0; i < bg.bands.length; i++) color(bg.bands[i], `background.bands[${i}]`, err);
+  }
+  if (bg.drift !== void 0) {
+    if (!isObj(bg.drift)) err("background.drift", "must be an object");
+    else {
+      if (!isNum(bg.drift.period) || bg.drift.period < LIMITS.minDriftPeriod) {
+        err("background.drift.period", `must be >= ${LIMITS.minDriftPeriod} ms`);
+      }
+      if (bg.drift.amount !== void 0 && (!isNum(bg.drift.amount) || bg.drift.amount < 0 || bg.drift.amount > LIMITS.maxFieldDriftAmount)) {
+        err("background.drift.amount", `must be a number 0..${LIMITS.maxFieldDriftAmount}`);
+      }
+      for (const k of unknownKeys(bg.drift, KNOWN_FIELD_DRIFT)) {
+        warn(`background.drift.${k}`, "unknown-property", `unknown drift property '${k}' \u2014 will be ignored`);
+      }
+    }
+  }
+  if (bg.seed !== void 0 && !isNum(bg.seed)) err("background.seed", "must be a number");
+  for (const k of unknownKeys(bg, KNOWN_BG_FIELD)) {
+    warn(`background.${k}`, "unknown-property", `unknown background property '${k}' \u2014 will be ignored`);
   }
 }
 function validateLayer(layer, path, err, warn, spec) {
@@ -526,6 +606,17 @@ function validateLayer(layer, path, err, warn, spec) {
       err(`${path}.spin`, `must be within \xB1${LIMITS.maxSpin} deg/sec`);
     }
   }
+  if (layer.rotate !== void 0) {
+    if (isRange(layer.rotate)) {
+      if (Math.abs(layer.rotate[0]) > LIMITS.maxRotate || Math.abs(layer.rotate[1]) > LIMITS.maxRotate) {
+        err(`${path}.rotate`, `each end of the range must be within \xB1${LIMITS.maxRotate} degrees`);
+      }
+    } else if (!isNum(layer.rotate)) {
+      err(`${path}.rotate`, "must be a number or a [min,max] range (degrees)");
+    } else if (Math.abs(layer.rotate) > LIMITS.maxRotate) {
+      err(`${path}.rotate`, `must be within \xB1${LIMITS.maxRotate} degrees`);
+    }
+  }
   if (layer.grow !== void 0) {
     if (!isObj(layer.grow)) err(`${path}.grow`, "must be an object");
     else {
@@ -1092,6 +1183,7 @@ function validateSequence(seq) {
   if (seq.seed !== void 0 && !isNum(seq.seed)) err("seed", "must be a number");
   if (typeof seq.loop !== "boolean") err("loop", "must be a boolean");
   if (seq.sync !== void 0 && seq.sync !== "mount" && seq.sync !== "epoch") err("sync", "must be 'mount' | 'epoch'");
+  if (seq.finish !== void 0) validateFinish(seq.finish, "finish", err, (p, code, message) => void warnings.push({ path: p, code, message }));
   if (!Array.isArray(seq.segments) || seq.segments.length === 0) {
     err("segments", "must be a non-empty array");
     return { valid: false, errors, warnings };
@@ -1596,7 +1688,10 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
       } : {},
       // Time-structure fields (2026-09): ease draws nothing; emit's one draw
       // per entity happens in a pass AFTER this loop (see below).
-      ...ease ? { ease: { type: ease.type, tau: ease.tau } } : {}
+      ...ease ? { ease: { type: ease.type, tau: ease.tau } } : {},
+      // Static rotation (2026-09-10): a scalar draws nothing; the range form
+      // draws one value here, last, only when declared.
+      ...typeof layer.rotate === "number" ? { rotate: layer.rotate * Math.PI / 180 } : Array.isArray(layer.rotate) ? { rotate: rng.range(layer.rotate[0], layer.rotate[1]) * Math.PI / 180 } : {}
     });
     if (layer.clock) {
       const ent = out[out.length - 1];
@@ -1670,8 +1765,9 @@ function sizeAt(e, t) {
   return s > 0 ? s : 0.1;
 }
 function rotationAt(e, t) {
-  if (!e.spinSpeed) return 0;
-  return e.spinPhase + e.spinSpeed * (t / 1e3);
+  const base = e.rotate ?? 0;
+  if (!e.spinSpeed) return base;
+  return base + e.spinPhase + e.spinSpeed * (t / 1e3);
 }
 function lifeAlphaAt(life, t) {
   if (!life) return 1;
@@ -2061,6 +2157,254 @@ import {
   createRng
 } from "@idle-screens/core";
 
+// src/field.ts
+var TWO_PI = Math.PI * 2;
+var FIELD_BUCKET_MS = 100;
+var FIELD_RASTER_SHORT_SIDE = 96;
+var FIELD_RASTER_SHORT_SIDE_LOW = 48;
+var WARP_GAIN = 2;
+var DRIFT_GAIN = 1;
+var FIELD_DRIFT_DEFAULT_AMOUNT = 0.3;
+var CONTRAST = [1, 1.45, 1.8, 1.95, 2];
+var clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
+function latticeHash(ix, iy, seed) {
+  let h = Math.imul(ix | 0, 668265261) ^ Math.imul(iy | 0, 374761393) ^ Math.imul(seed | 0, 2654435761);
+  h = Math.imul(h ^ h >>> 15, 2246822507);
+  h = Math.imul(h ^ h >>> 13, 3266489909);
+  h ^= h >>> 16;
+  return (h >>> 0) / 4294967296;
+}
+var smoothstep2 = (k) => k * k * (3 - 2 * k);
+function valueNoise(x, y, seed) {
+  const x0 = Math.floor(x);
+  const y0 = Math.floor(y);
+  const fx = smoothstep2(x - x0);
+  const fy = smoothstep2(y - y0);
+  const a = latticeHash(x0, y0, seed);
+  const b = latticeHash(x0 + 1, y0, seed);
+  const c = latticeHash(x0, y0 + 1, seed);
+  const d = latticeHash(x0 + 1, y0 + 1, seed);
+  const top = a + (b - a) * fx;
+  const bottom = c + (d - c) * fx;
+  return top + (bottom - top) * fy;
+}
+function fbm(x, y, seed, octaves) {
+  let sum = 0;
+  let amp = 1;
+  let norm = 0;
+  let f = 1;
+  for (let i = 0; i < octaves; i++) {
+    sum += amp * valueNoise(x * f + i * 17.3, y * f + i * 31.7, seed + i * 101);
+    norm += amp;
+    amp *= 0.5;
+    f *= 2;
+  }
+  return sum / norm;
+}
+function fieldOctaves(cfg) {
+  const o = Math.round(cfg.octaves ?? 2);
+  return o < 1 ? 1 : o > 4 ? 4 : o;
+}
+function fieldSampleTime(cfg, t) {
+  return cfg.drift && cfg.drift.amount !== 0 ? Math.floor(t / FIELD_BUCKET_MS) * FIELD_BUCKET_MS : 0;
+}
+function fieldAt(u, v, t, cfg, seed) {
+  const scale = cfg.scale;
+  const octaves = fieldOctaves(cfg);
+  const s = (cfg.seed ?? seed) >>> 0;
+  let x = u * scale;
+  let y = v * scale;
+  const drift = cfg.drift;
+  if (drift) {
+    const phase = TWO_PI * t / drift.period;
+    const r = (drift.amount ?? FIELD_DRIFT_DEFAULT_AMOUNT) * DRIFT_GAIN;
+    x += r * Math.sin(phase);
+    y += r * Math.cos(phase);
+  }
+  const warp = cfg.warp ?? 0;
+  if (warp > 0) {
+    const qx = fbm(x + 5.2, y + 1.3, s + 7919, octaves) - 0.5;
+    const qy = fbm(x + 1.7, y + 9.2, s + 104729, octaves) - 0.5;
+    x += warp * WARP_GAIN * qx;
+    y += warp * WARP_GAIN * qy;
+  }
+  const raw = fbm(x, y, s, octaves);
+  return clamp01(0.5 + (raw - 0.5) * CONTRAST[octaves]);
+}
+function hexToRgb255(hex) {
+  const h = hex.length === 4 ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}` : hex;
+  const n = parseInt(h.slice(1), 16);
+  if (Number.isNaN(n)) return [128, 128, 128];
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function rgb255Luma(rgb) {
+  return (0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]) / 255;
+}
+function fieldRgb(value, bands, quantize) {
+  const n = bands.length;
+  const q = Math.round(quantize ?? n);
+  let f;
+  if (q >= 2) {
+    const level = Math.min(q - 1, Math.floor(clamp01(value) * q));
+    f = level * (n - 1) / (q - 1);
+  } else {
+    f = clamp01(value) * (n - 1);
+  }
+  const i = Math.min(n - 2, Math.floor(f));
+  const k = f - i;
+  const a = hexToRgb255(bands[i]);
+  if (k === 0) return a;
+  const b = hexToRgb255(bands[i + 1]);
+  return [
+    Math.round(a[0] + (b[0] - a[0]) * k),
+    Math.round(a[1] + (b[1] - a[1]) * k),
+    Math.round(a[2] + (b[2] - a[2]) * k)
+  ];
+}
+function fieldRgbAt(u, v, t, cfg, seed) {
+  return fieldRgb(fieldAt(u, v, t, cfg, seed), cfg.bands, cfg.quantize);
+}
+
+// src/finish.ts
+var GRAIN_TILE = 256;
+var DITHER_TILE = 8;
+var GRAIN_ALPHA = 0.35;
+var DITHER_ALPHA = 0.25;
+var FINISH_ANIMATE_HZ = 12;
+var clamp012 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
+function finishStrength(f) {
+  return { grain: clamp012(f?.grain ?? 0), dither: clamp012(f?.dither ?? 0) };
+}
+function grainTilePixels(seed) {
+  const px = new Uint8ClampedArray(GRAIN_TILE * GRAIN_TILE * 4);
+  const s = seed >>> 0;
+  let i = 0;
+  for (let y = 0; y < GRAIN_TILE; y++) {
+    for (let x = 0; x < GRAIN_TILE; x++) {
+      const v = (latticeHash(x, y, s) + latticeHash(x, y, s + 1540483477)) / 2;
+      const g = Math.round(128 + (v - 0.5) * 255);
+      px[i++] = g;
+      px[i++] = g;
+      px[i++] = g;
+      px[i++] = 255;
+    }
+  }
+  return px;
+}
+function bayerMatrix() {
+  let m = [[0]];
+  for (let n = 1; n < DITHER_TILE; n *= 2) {
+    const next = [];
+    for (let y = 0; y < n * 2; y++) {
+      const row = [];
+      for (let x = 0; x < n * 2; x++) {
+        const base = m[y % n][x % n] * 4;
+        const quadrant = (y >= n ? 2 : 0) + (x >= n ? 1 : 0);
+        row.push(base + [0, 2, 3, 1][quadrant]);
+      }
+      next.push(row);
+    }
+    m = next;
+  }
+  return m;
+}
+function bayerTilePixels() {
+  const m = bayerMatrix();
+  const px = new Uint8ClampedArray(DITHER_TILE * DITHER_TILE * 4);
+  let i = 0;
+  for (let y = 0; y < DITHER_TILE; y++) {
+    for (let x = 0; x < DITHER_TILE; x++) {
+      const g = Math.round((m[y][x] + 0.5) / (DITHER_TILE * DITHER_TILE) * 255);
+      px[i++] = g;
+      px[i++] = g;
+      px[i++] = g;
+      px[i++] = 255;
+    }
+  }
+  return px;
+}
+function grainOffset(t, seed, animate) {
+  if (!animate) return { x: 0, y: 0 };
+  const bucket = Math.floor(t * FINISH_ANIMATE_HZ / 1e3);
+  const s = seed >>> 0;
+  return {
+    x: Math.floor(latticeHash(bucket, 1, s) * GRAIN_TILE),
+    y: Math.floor(latticeHash(bucket, 2, s) * GRAIN_TILE)
+  };
+}
+function pickScreenOp(ctx) {
+  const prev = ctx.globalCompositeOperation;
+  let op = "multiply";
+  for (const candidate of ["overlay", "soft-light"]) {
+    ctx.globalCompositeOperation = candidate;
+    if (ctx.globalCompositeOperation === candidate) {
+      op = candidate;
+      break;
+    }
+  }
+  ctx.globalCompositeOperation = prev;
+  return op;
+}
+function tileCanvas(size, pixels) {
+  const canvas = typeof document !== "undefined" ? document.createElement("canvas") : new OffscreenCanvas(size, size);
+  canvas.width = size;
+  canvas.height = size;
+  const ctx = canvas.getContext("2d");
+  if (!ctx || typeof ctx.createImageData !== "function") return null;
+  const img = ctx.createImageData(size, size);
+  img.data.set(pixels);
+  ctx.putImageData(img, 0, 0);
+  return canvas;
+}
+function createFinishPass(visible, seed) {
+  const ctx = visible.getContext("2d", { alpha: false });
+  if (!ctx) return null;
+  return { canvas: visible, ctx, op: pickScreenOp(ctx), grain: null, dither: null, seed };
+}
+function createSceneCanvas(width, height) {
+  if (typeof document === "undefined") return new OffscreenCanvas(Math.max(1, width), Math.max(1, height));
+  const canvas = document.createElement("canvas");
+  canvas.width = Math.max(1, width);
+  canvas.height = Math.max(1, height);
+  return canvas;
+}
+function pattern(fp, size, pixels) {
+  const tile = tileCanvas(size, pixels);
+  if (!tile || typeof fp.ctx.createPattern !== "function") return null;
+  return fp.ctx.createPattern(tile, "repeat");
+}
+function presentWithFinish(fp, scene, w, h, t, finish, animateAllowed, seed = fp.seed) {
+  const p = fp.ctx;
+  p.globalAlpha = 1;
+  p.globalCompositeOperation = "source-over";
+  p.drawImage(scene, 0, 0, w, h);
+  const normalizedSeed = seed >>> 0 || 1;
+  if (normalizedSeed !== fp.seed) {
+    fp.seed = normalizedSeed;
+    fp.grain = null;
+  }
+  const { grain, dither } = finishStrength(finish);
+  if (grain > 0) {
+    fp.grain ??= pattern(fp, GRAIN_TILE, grainTilePixels(fp.seed));
+    if (fp.grain) screen(fp, fp.grain, grain * GRAIN_ALPHA, grainOffset(t, fp.seed, animateAllowed && finish?.animate === true), w, h);
+  }
+  if (dither > 0) {
+    fp.dither ??= pattern(fp, DITHER_TILE, bayerTilePixels());
+    if (fp.dither) screen(fp, fp.dither, dither * DITHER_ALPHA, { x: 0, y: 0 }, w, h);
+  }
+}
+function screen(fp, pat, alpha, off, w, h) {
+  const p = fp.ctx;
+  p.save();
+  p.globalCompositeOperation = fp.op;
+  p.globalAlpha = alpha;
+  p.imageSmoothingEnabled = false;
+  p.fillStyle = pat;
+  p.translate(-off.x, -off.y);
+  p.fillRect(off.x, off.y, w, h);
+  p.restore();
+}
+
 // src/sequence.ts
 function segmentStart(seq, index) {
   let t = 0;
@@ -2131,6 +2475,31 @@ function bedRenderSeed(seq) {
   const raw = seq.bed.seed ?? (seq.seed !== void 0 ? seq.seed + LIMITS.maxSegments : void 0);
   return raw === void 0 ? void 0 : normalizeSeed(raw);
 }
+function sequenceSwapCompatible(prev, next) {
+  if (prev.segments.length !== next.segments.length) return false;
+  if (prev.loop !== next.loop) return false;
+  if ((prev.sync ?? "mount") !== (next.sync ?? "mount")) return false;
+  if (!!prev.bed !== !!next.bed) return false;
+  if (prev.bed && next.bed) {
+    if (structuralSignature(prev.bed) !== structuralSignature(next.bed)) return false;
+    if (bedRenderSeed(prev) !== bedRenderSeed(next)) return false;
+  }
+  for (let i = 0; i < prev.segments.length; i++) {
+    const a = prev.segments[i];
+    const b = next.segments[i];
+    if (a.duration !== b.duration) return false;
+    if ((a.advance ?? "auto") !== (b.advance ?? "auto")) return false;
+    if (transitionKey(a.transition) !== transitionKey(b.transition)) return false;
+    if (structuralSignature(a.scene) !== structuralSignature(b.scene)) return false;
+    if (segmentRenderSeed(prev, i) !== segmentRenderSeed(next, i)) return false;
+  }
+  return true;
+}
+function transitionKey(tr) {
+  if (!tr || tr.type === "cut") return "cut";
+  if (tr.type === "morph") return `morph:${tr.dur}:${tr.text ?? "step"}`;
+  return `fade:${tr.dur}`;
+}
 
 // src/compile.ts
 var DEFAULT_STEER_DUR = 1e3;
@@ -2185,6 +2554,9 @@ var SpecInstance = class {
     this.effSpec = spec;
     this.saverCtx = ctx;
     this.transparent = opts.transparent === true;
+    const tier = opts.capabilityTier;
+    this.fieldShortSide = tier === "basic" || tier === "minimal" ? FIELD_RASTER_SHORT_SIDE_LOW : FIELD_RASTER_SHORT_SIDE;
+    this.animateFinish = tier !== "basic" && tier !== "minimal";
     this.seed = normalizeSeed(spec.seed ?? ctx.seed);
     let canvas;
     if (ctx.surface) {
@@ -2198,6 +2570,13 @@ var SpecInstance = class {
       canvas = el;
       this.ownsCanvas = true;
     }
+    if (spec.finish !== void 0 && !this.transparent && !opts.hostPresents) {
+      const pass = createFinishPass(canvas, this.seed);
+      if (pass) {
+        this.finishPass = pass;
+        canvas = createSceneCanvas(ctx.width, ctx.height);
+      }
+    }
     this.canvas = canvas;
     const c2d = canvas.getContext("2d", { alpha: this.transparent });
     if (!c2d) throw new Error("schema saver: no 2d context");
@@ -2238,6 +2617,23 @@ var SpecInstance = class {
   lastStructural = "";
   /** See `LayerPaintOverride`; null (the default, and every plain mount) draws every layer once. */
   paintOverrides = null;
+  /** Raster short side for a `field` background — halved on the low tiers. */
+  fieldShortSide;
+  /** The `field` background's cached raster; null until a field is first painted. */
+  field = null;
+  /**
+   * The presentation pass when this instance applies a `finish`: the
+   * visible canvas plus the cached screen tiles. When set, `this.canvas` is
+   * an offscreen SCENE canvas — the surface every layer (and `ghosting`'s
+   * persistence) draws into — and each frame ends by copying it to the
+   * visible canvas and screening the finish over the copy. The finish thus
+   * never enters the persistence loop. Null (every plain mount without a
+   * finish, every sequence child) draws straight onto the visible canvas,
+   * exactly as before the field existed.
+   */
+  finishPass = null;
+  /** False on the `basic`/`minimal` tiers — `finish.animate` renders as a static tile. */
+  animateFinish;
   /** Viewport factor for absolute px sizes — 1 for `units: 'px'` specs. */
   fontScale() {
     if (this.effSpec.units === "px") return 1;
@@ -2248,6 +2644,11 @@ var SpecInstance = class {
     this.canvas.width = Math.max(1, Math.round(this.w * dpr));
     this.canvas.height = Math.max(1, Math.round(this.h * dpr));
     this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    if (this.finishPass) {
+      this.finishPass.canvas.width = this.canvas.width;
+      this.finishPass.canvas.height = this.canvas.height;
+      this.finishPass.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    }
     this.lastRenderT = Number.NEGATIVE_INFINITY;
   }
   /** (Re)seed and place all entities — deterministic for the seed + viewport. */
@@ -2289,6 +2690,10 @@ var SpecInstance = class {
       ctx.fillRect(0, 0, w, h);
       return;
     }
+    if (bg.type === "field") {
+      this.drawField(bg, t);
+      return;
+    }
     const g = ctx.createLinearGradient(0, 0, 0, h);
     const drift = bg.drift;
     for (let i = 0; i < bg.stops.length; i++) {
@@ -2309,6 +2714,58 @@ var SpecInstance = class {
       ctx.fillRect(0, h - bh, w, bh);
     }
   }
+  /**
+   * Paint a `field` background: sample the field into a low-res raster (short
+   * side `fieldShortSide`, the long side by aspect) and draw it scaled to the
+   * canvas — nearest-neighbour for quantised bands so contours stay crisp,
+   * smoothed for `quantize: 0`. The raster is recomputed only when its key
+   * changes: the config (steering glides it), the canvas size, or — while
+   * drifting — the 100 ms bucket `t` falls in (`fieldSampleTime`); a static
+   * field is sampled exactly once per mount. `luminanceGrid` samples the same
+   * function at the same bucketed time, so perception and paint agree.
+   */
+  drawField(bg, t) {
+    const { ctx, w, h } = this;
+    const short = Math.max(1, Math.min(w, h));
+    const cols = Math.max(1, Math.round(this.fieldShortSide * w / short));
+    const rows = Math.max(1, Math.round(this.fieldShortSide * h / short));
+    const ft = fieldSampleTime(bg, t);
+    const key = `${JSON.stringify(bg)}|${w}x${h}|${cols}x${rows}|${ft}`;
+    let raster = this.field;
+    if (!raster || raster.key !== key) {
+      if (!raster || raster.cols !== cols || raster.rows !== rows) {
+        const canvas = typeof document !== "undefined" ? document.createElement("canvas") : new OffscreenCanvas(cols, rows);
+        canvas.width = cols;
+        canvas.height = rows;
+        const rctx = canvas.getContext("2d");
+        if (!rctx) return;
+        raster = { canvas, ctx: rctx, cols, rows, key: "" };
+      }
+      const img = raster.ctx.createImageData(cols, rows);
+      const data = img.data;
+      const seed = this.seed;
+      let i = 0;
+      for (let r = 0; r < rows; r++) {
+        const v = (r + 0.5) * h / rows / short;
+        for (let c = 0; c < cols; c++) {
+          const u = (c + 0.5) * w / cols / short;
+          const rgb = fieldRgbAt(u, v, ft, bg, seed);
+          data[i++] = rgb[0];
+          data[i++] = rgb[1];
+          data[i++] = rgb[2];
+          data[i++] = 255;
+        }
+      }
+      raster.ctx.putImageData(img, 0, 0);
+      raster.key = key;
+      this.field = raster;
+    }
+    const smooth = Math.round(bg.quantize ?? bg.bands.length) < 2;
+    const prev = ctx.imageSmoothingEnabled;
+    ctx.imageSmoothingEnabled = smooth;
+    ctx.drawImage(raster.canvas, 0, 0, w, h);
+    ctx.imageSmoothingEnabled = prev;
+  }
   /** Position with parent-orbit resolution: a layer-parented orbit entity's
    *  positionAt is an offset around (0,0); add the parent's own analytic position. */
   entityPos(e, t, parentE) {
@@ -2788,6 +3245,7 @@ var SpecInstance = class {
       this.paintFrame(t, 1);
     }
     this.lastRenderT = t;
+    if (this.finishPass) presentWithFinish(this.finishPass, this.canvas, this.w, this.h, t, this.effSpec.finish, this.animateFinish);
   }
   setPaused(paused) {
     this.paused = paused;
@@ -2836,19 +3294,26 @@ var SpecInstance = class {
   }
   dispose() {
     this.stop();
-    if (this.ownsCanvas && typeof HTMLCanvasElement !== "undefined" && this.canvas instanceof HTMLCanvasElement) this.canvas.remove();
+    this.field = null;
+    const visible = this.finishPass?.canvas ?? this.canvas;
+    this.finishPass = null;
+    if (this.ownsCanvas && typeof HTMLCanvasElement !== "undefined" && visible instanceof HTMLCanvasElement) visible.remove();
   }
 };
 function compileSaver(spec) {
   const valid = assertValidSpec(spec);
   return {
     manifest: manifestFor(valid),
-    mount: (ctx) => new SpecInstance(valid, ctx),
+    mount: (ctx) => new SpecInstance(valid, ctx, { capabilityTier: ctx.capabilityTier }),
     spec: valid
   };
 }
 var BED_PREFIX = "bed.";
+function hasHotSwapSequence(inst) {
+  return typeof inst.hotSwapSequence === "function";
+}
 var SequenceInstance = class {
+  /** Replaced wholesale by `hotSwapSequence`; every per-segment lookup (`segmentStart`, `canMorph`, `childScene`) reads it live, so there are no derived tables to refresh. */
   seq;
   childCtx;
   canvas;
@@ -2899,6 +3364,13 @@ var SequenceInstance = class {
    * resolve on it (see `applyRetainedDeltas`).
    */
   retainedDeltas = /* @__PURE__ */ new Map();
+  /**
+   * Every `bed.<path>` delta (prefix stripped, last wins per path). The bed
+   * is never re-created, so these are applied to it once on arrival — the
+   * map exists only so `hotSwapSequence` can put a steered bed colour back
+   * after the bed takes its republished scene. Absent a swap it is never read.
+   */
+  retainedBedDeltas = /* @__PURE__ */ new Map();
   /** The outgoing segment while a `fade` runs; null otherwise. */
   fading = null;
   /**
@@ -2911,6 +3383,19 @@ var SequenceInstance = class {
   fadingIn = null;
   /** False on the `basic`/`minimal` capability tiers — fade renders as cut. */
   fadeEnabled;
+  /** The mount's tier, handed to every child and the bed. */
+  capabilityTier;
+  /**
+   * The sequence's presentation pass when it — or any segment — declares a
+   * `finish`: children and the bed draw into an offscreen scene canvas
+   * (`childCtx.surface`), and every frame ends by copying it to the visible
+   * surface with the finish screened over the copy — once per composed
+   * frame, bed + segment + fade together. Null when no finish is declared
+   * anywhere: children draw straight onto the visible surface, as before.
+   */
+  finishPass = null;
+  /** False on the `basic`/`minimal` tiers — `finish.animate` renders as a static tile. */
+  animateFinish;
   /**
    * The sequence's `bed`: one scene on the shared surface, drawn first every
    * frame at the sequence clock — WITHOUT `clockOffset`, so a
@@ -2921,6 +3406,7 @@ var SequenceInstance = class {
   constructor(seq, ctx) {
     this.seq = seq;
     const { sequenceBaseT, capabilityTier, ...plainCtx } = ctx;
+    this.capabilityTier = capabilityTier;
     this.fadeEnabled = capabilityTier !== "basic" && capabilityTier !== "minimal";
     if (seq.sync === "epoch" && typeof sequenceBaseT === "number" && Number.isFinite(sequenceBaseT)) {
       this.baseT = Math.max(0, sequenceBaseT);
@@ -2938,10 +3424,20 @@ var SequenceInstance = class {
     }
     this.canvas = canvas;
     this.seed = (seq.seed ?? ctx.seed ?? 0) >>> 0 || 1;
+    this.animateFinish = capabilityTier !== "basic" && capabilityTier !== "minimal";
+    const wantsFinish = seq.finish !== void 0 || seq.segments.some((s) => s.scene.finish !== void 0);
+    if (wantsFinish && surface) {
+      const pass = createFinishPass(surface, this.seed);
+      if (pass) {
+        this.finishPass = pass;
+        surface = createSceneCanvas(ctx.width, ctx.height);
+      }
+    }
     this.childCtx = { ...plainCtx, surface, reducedMotion: true };
+    this.sizeVisible();
     this.children = new Array(seq.segments.length).fill(null);
     if (seq.bed) {
-      this.bed = new SpecInstance(this.bedScene(seq.bed), this.childCtx);
+      this.bed = new SpecInstance(this.bedScene(seq.bed), this.childCtx, { capabilityTier, hostPresents: true });
       this.bed.setPaused(true);
     } else {
       this.bed = null;
@@ -3034,7 +3530,7 @@ var SequenceInstance = class {
    */
   offscreenChild(index, root) {
     const canvas = typeof document !== "undefined" ? document.createElement("canvas") : new OffscreenCanvas(Math.max(1, this.childCtx.width), Math.max(1, this.childCtx.height));
-    const child = new SpecInstance(this.childScene(root), { ...this.childCtx, surface: canvas }, { transparent: this.bed !== null });
+    const child = new SpecInstance(this.childScene(root), { ...this.childCtx, surface: canvas }, { transparent: this.bed !== null, capabilityTier: this.capabilityTier, hostPresents: true });
     child.setPaused(true);
     if (root !== index) child.hotSwapSpec(this.childScene(index));
     if (this.retainedDeltas.size > 0) child.applyDeltasNow(this.retainedDeltas.values());
@@ -3093,7 +3589,7 @@ var SequenceInstance = class {
     if (index < 0 || index >= this.seq.segments.length) index = 0;
     let child = this.children[index];
     if (!child) {
-      child = new SpecInstance(rootScene ?? this.childScene(index), this.childCtx, { transparent: this.bed !== null, skipInitialPaint });
+      child = new SpecInstance(rootScene ?? this.childScene(index), this.childCtx, { transparent: this.bed !== null, skipInitialPaint, capabilityTier: this.capabilityTier, hostPresents: true });
       this.children[index] = child;
       child.setPaused(true);
       if (rootScene) child.hotSwapSpec(this.childScene(index));
@@ -3126,7 +3622,49 @@ var SequenceInstance = class {
     this.lastT = now - this.startT + this.baseT;
     this.renderFrame(this.lastT, this.seed);
   }
+  /**
+   * With a presentation pass, size the visible surface like a child sizes
+   * the scene canvas (children never touch the visible surface then).
+   */
+  sizeVisible() {
+    const fp = this.finishPass;
+    if (!fp) return;
+    const dpr = Math.min(this.childCtx.dpr, 2);
+    fp.canvas.width = Math.max(1, Math.round(this.childCtx.width * dpr));
+    fp.canvas.height = Math.max(1, Math.round(this.childCtx.height * dpr));
+    fp.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  }
+  /**
+   * The finish this frame applies: the sequence's own overrides; else the
+   * active segment's (the incoming one during a fade) — read through
+   * `steeredScene` so a retained steer to `finish.grain`/`finish.dither`
+   * takes effect immediately instead of the authored value; a bed's is
+   * ignored.
+   */
+  frameFinish() {
+    if (this.seq.finish !== void 0) return this.seq.finish;
+    if (this.activeIndex < 0) return void 0;
+    return this.steeredScene(this.childScene(this.activeIndex)).finish;
+  }
+  /**
+   * The seed `frameFinish()`'s grain resolves against — the sequence's own
+   * for a sequence-level finish, else the active segment's actual render
+   * seed (`segmentRenderSeed`: chain-root-aware and normalized exactly like
+   * `SpecInstance`, so it agrees with what that segment's entities render
+   * with, morph or not).
+   */
+  frameFinishSeed() {
+    if (this.seq.finish !== void 0) return this.seed;
+    if (this.activeIndex < 0) return this.seed;
+    return segmentRenderSeed(this.seq, this.activeIndex) ?? this.seed;
+  }
   renderFrame(T, seed) {
+    this.renderScene(T, seed);
+    if (this.finishPass) {
+      presentWithFinish(this.finishPass, this.childCtx.surface, this.childCtx.width, this.childCtx.height, T, this.frameFinish(), this.animateFinish, this.frameFinishSeed());
+    }
+  }
+  renderScene(T, seed) {
     this.renderedT = T;
     const resolved = resolveSegment(this.seq, T + this.clockOffset, { releasedBelow: this.releasedBelow });
     const { index, localT } = resolved;
@@ -3207,6 +3745,7 @@ var SequenceInstance = class {
     this.childCtx.width = width;
     this.childCtx.height = height;
     if (dpr !== void 0) this.childCtx.dpr = dpr;
+    this.sizeVisible();
     for (const child of this.children) {
       child?.resize(width, height, dpr);
     }
@@ -3218,7 +3757,10 @@ var SequenceInstance = class {
     const all = track?.deltas ?? [];
     const isBedPath = (d) => this.bed !== null && typeof d.path === "string" && d.path.startsWith(BED_PREFIX);
     const bedDeltas = all.filter(isBedPath).map((d) => ({ ...d, path: d.path.slice(BED_PREFIX.length) }));
-    if (bedDeltas.length > 0) this.bed.applyTrack({ ...track, deltas: bedDeltas });
+    if (bedDeltas.length > 0) {
+      for (const d of bedDeltas) this.retainedBedDeltas.set(d.path, d);
+      this.bed.applyTrack({ ...track, deltas: bedDeltas });
+    }
     const deltas = all.filter((d) => !isBedPath(d));
     for (const d of deltas) {
       if (d.path !== "sequence.segment" && typeof d.path === "string") this.retainedDeltas.set(d.path, d);
@@ -3245,6 +3787,34 @@ var SequenceInstance = class {
       this.fadingIn?.child.applyTrack({ ...track, deltas: childDeltas });
     }
   }
+  /**
+   * See `SequenceSaverInstance.hotSwapSequence`. Nothing that positions the
+   * show is touched: `clockOffset`, `releasedBelow`, `activeIndex`,
+   * `morphFromIndex`, `pendingWrapFade`, `renderedT` and the retained deltas
+   * all keep their values, and the timing terms `sequenceSwapCompatible`
+   * pins (durations, advance, transitions, loop) are the same on both sides,
+   * so `resolveSegment` at the next frame lands where it would have anyway.
+   * Each live child takes its new scene with the retained track re-applied
+   * (`steeredScene` — the same routing a fresh child gets), so steered paint
+   * survives the swap; `hotSwapSpec` keeps the entities (the signatures
+   * match) and does not reset ghosting contiguity, so a drifting entity is
+   * where it was 1 ms ago. Children are always paused, so none of them has a
+   * glide in flight for the swap to interrupt (`SpecInstance.applyTrack`
+   * snaps when paused). A morph in progress is untouched here: its chain-root
+   * child is re-lerped from the new endpoints on the very next frame.
+   */
+  hotSwapSequence(next) {
+    if (!sequenceSwapCompatible(this.seq, next)) return false;
+    this.seq = next;
+    if (this.bed && next.bed) this.bed.hotSwapSpec(applyRetainedDeltas(this.bedScene(next.bed), this.retainedBedDeltas.values()));
+    for (let i = 0; i < this.children.length; i++) {
+      this.children[i]?.hotSwapSpec(this.steeredScene(this.childScene(i)));
+    }
+    if (this.fading) this.fading.child.hotSwapSpec(this.steeredScene(this.childScene(this.fading.index)));
+    if (this.fadingIn) this.fadingIn.child.hotSwapSpec(this.steeredScene(this.childScene(this.fadingIn.index)));
+    if (this.paused) this.renderFrame(this.renderedT, this.seed);
+    return true;
+  }
   dispose() {
     this.stop();
     this.releaseFading();
@@ -3252,6 +3822,10 @@ var SequenceInstance = class {
       this.releaseChild(i);
     }
     this.bed?.dispose();
+    if (this.finishPass) {
+      this.finishPass.grain = null;
+      this.finishPass.dither = null;
+    }
     if (this.canvas) this.canvas.remove();
   }
 };
@@ -3289,6 +3863,14 @@ function compileSequence(spec) {
 import { createRng as createRng2 } from "@idle-screens/core";
 
 // src/luma.ts
+function fieldRenderedRgbs(bg) {
+  const n = bg.bands.length;
+  const q = Math.round(bg.quantize ?? n);
+  if (q < 2) return bg.bands.map((hex) => hexToRgb255(hex));
+  const out = [];
+  for (let level = 0; level < q; level++) out.push(fieldRgb((level + 0.5) / q, bg.bands, q));
+  return out;
+}
 function hexLuma(hex) {
   const h = hex.length === 4 ? `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}` : hex;
   const n = parseInt(h.slice(1), 16);
@@ -3317,6 +3899,10 @@ function spriteHex(layer, e) {
 function backgroundLuma(spec) {
   const bg = spec.background;
   if (!bg || bg.type === "solid") return hexLuma(bg?.color ?? "#05050a");
+  if (bg.type === "field") {
+    const rgbs = fieldRenderedRgbs(bg);
+    return rgbs.reduce((s, c) => s + rgb255Luma(c), 0) / rgbs.length;
+  }
   return bg.stops.reduce((s, st) => s + hexLuma(st.color), 0) / bg.stops.length;
 }
 function hexRgb(hex) {
@@ -3328,14 +3914,20 @@ function hexRgb(hex) {
 function backgroundRgb(spec) {
   const bg = spec.background;
   if (!bg || bg.type === "solid") return hexRgb(bg?.color ?? "#05050a");
-  const acc = bg.stops.reduce(
-    (s, st) => {
-      const c = hexRgb(st.color);
+  if (bg.type === "field") {
+    const rgbs = fieldRenderedRgbs(bg);
+    const acc2 = rgbs.reduce((s, c) => ({ r: s.r + c[0], g: s.g + c[1], b: s.b + c[2] }), { r: 0, g: 0, b: 0 });
+    return { r: acc2.r / rgbs.length / 255, g: acc2.g / rgbs.length / 255, b: acc2.b / rgbs.length / 255 };
+  }
+  const colours = bg.stops.map((st) => st.color);
+  const acc = colours.reduce(
+    (s, hex) => {
+      const c = hexRgb(hex);
       return { r: s.r + c.r, g: s.g + c.g, b: s.b + c.b };
     },
     { r: 0, g: 0, b: 0 }
   );
-  const n = bg.stops.length || 1;
+  const n = colours.length || 1;
   return { r: acc.r / n, g: acc.g / n, b: acc.b / n };
 }
 function colourSeparation(layer, sprite, bg) {
@@ -3358,9 +3950,15 @@ function legibilityRatio(a, b) {
   const lo = Math.min(la, lb);
   return (hi + 0.05) / (lo + 0.05);
 }
-function backgroundRgbAt(spec, yPx, h, unit) {
+function backgroundRgbAt(spec, yPx, h, unit, xPx, w, seed) {
   const bg = spec.background;
   if (!bg || bg.type === "solid") return hexRgb(bg?.color ?? "#05050a");
+  if (bg.type === "field") {
+    if (xPx === void 0 || w === void 0) return backgroundRgb(spec);
+    const short = Math.max(1, Math.min(w, h));
+    const c = fieldRgbAt(xPx / short, yPx / short, 0, bg, seed ?? spec.seed ?? 42);
+    return { r: c[0] / 255, g: c[1] / 255, b: c[2] / 255 };
+  }
   if (bg.band) {
     const bh = bg.band.height * unit;
     if (yPx >= h - bh) return hexRgb(bg.band.color);
@@ -3913,7 +4511,8 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     let worst = null;
     for (const box of boxes) {
       const cy = (box.y0 + box.y1) / 2;
-      const groundRgb = backgroundRgbAt(spec, cy, h, scale);
+      const cx = (box.x0 + box.x1) / 2;
+      const groundRgb = backgroundRgbAt(spec, cy, h, scale, cx, w, opts.backgroundSeed ?? opts.seed);
       const ground = legibilityRatio(textPlate(groundRgb, box.alpha), groundRgb);
       const lit = brightestAdditivePlate(spec, allEntities, groundRgb, box, w, h);
       const plate = lit ? legibilityRatio(textPlate(lit.rgb, box.alpha), lit.rgb) : Infinity;
@@ -4151,7 +4750,7 @@ function describeScene(spec, options = {}) {
     return { t, viewport: { w, h }, layers: layerSnapshots, warnings };
   });
   return {
-    spec: { id: spec.id, label: spec.label, units: spec.units ?? "px" },
+    spec: { id: spec.id, label: spec.label, units: spec.units ?? "px", ...spec.finish ? { finish: spec.finish } : {} },
     snapshots
   };
 }
@@ -4249,8 +4848,23 @@ function luminanceGrid(spec, opts = {}) {
   const cellH = h / rows;
   const bg = spec.background;
   const bgRow = new Array(rows).fill(0);
+  let bgCells;
   if (!bg || bg.type === "solid") {
     bgRow.fill(hexLuma(bg?.color ?? "#05050a"));
+  } else if (bg.type === "field") {
+    bgCells = new Array(cols * rows);
+    const short = Math.max(1, Math.min(w, h));
+    const seed = opts.seed ?? spec.seed ?? 42;
+    const ft = fieldSampleTime(bg, t);
+    for (let r = 0; r < rows; r++) {
+      let rowSum = 0;
+      for (let c = 0; c < cols; c++) {
+        const lum = rgb255Luma(fieldRgbAt((c + 0.5) * cellW / short, (r + 0.5) * cellH / short, ft, bg, seed));
+        bgCells[r * cols + c] = lum;
+        rowSum += lum;
+      }
+      bgRow[r] = rowSum / cols;
+    }
   } else {
     const stops = [...bg.stops].sort((a, b) => a.at - b.at);
     for (let r = 0; r < rows; r++) {
@@ -4275,7 +4889,7 @@ function luminanceGrid(spec, opts = {}) {
     }
   }
   const cells = new Array(cols * rows);
-  for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) cells[r * cols + c] = bgRow[r];
+  for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) cells[r * cols + c] = bgCells ? bgCells[r * cols + c] : bgRow[r];
   const compose = (idx, lum, a, blend) => {
     const cur = cells[idx];
     if (blend === "lighter" || blend === "screen") cells[idx] = Math.min(1, cur + lum * a);
@@ -4489,9 +5103,9 @@ function luminanceGrid(spec, opts = {}) {
     }
   }
   splatPass(t, 1);
-  return finishGrid(cols, rows, cells, bgRow);
+  return finishGrid(cols, rows, cells, bgRow, bgCells);
 }
-function finishGrid(cols, rows, cells, bgRow) {
+function finishGrid(cols, rows, cells, bgRow, bgCells) {
   let sum = 0;
   let covered = 0;
   let devSum = 0;
@@ -4503,7 +5117,7 @@ function finishGrid(cols, rows, cells, bgRow) {
     for (let c = 0; c < cols; c++) {
       const v = cells[r * cols + c];
       sum += v;
-      const dev = Math.abs(v - bgRow[r]);
+      const dev = Math.abs(v - (bgCells ? bgCells[r * cols + c] : bgRow[r]));
       if (dev > 0.03) covered++;
       devSum += dev;
       cxAcc += dev * (c + 0.5);
@@ -4519,6 +5133,7 @@ function finishGrid(cols, rows, cells, bgRow) {
     rows,
     cells,
     background: bgRow,
+    ...bgCells ? { backgroundCells: bgCells } : {},
     meanLuminance: sum / (cols * rows),
     coverage: covered / (cols * rows),
     centroid: devSum > 1e-6 ? { x: cxAcc / devSum / cols, y: cyAcc / devSum / rows } : null,
@@ -4742,8 +5357,9 @@ function regionMeans(grid) {
   const cnt = new Array(9).fill(0);
   for (let r = 0; r < grid.rows; r++) {
     for (let c = 0; c < grid.cols; c++) {
+      const idx = r * grid.cols + c;
       const region = Math.min(2, Math.floor(r / grid.rows * 3)) * 3 + Math.min(2, Math.floor(c / grid.cols * 3));
-      out[region] += Math.abs(grid.cells[r * grid.cols + c] - grid.background[r]);
+      out[region] += Math.abs(grid.cells[idx] - (grid.backgroundCells ? grid.backgroundCells[idx] : grid.background[r]));
       cnt[region]++;
     }
   }
@@ -4819,7 +5435,7 @@ function perceiveSequenceFrame(seq, T, opts = {}) {
   const bedGrid = luminanceGrid(seq.bed, bedOpts);
   const inkGrid = luminanceGrid(ink, segOpts);
   const cells = bedGrid.cells.map((v, i) => Math.min(1, v + inkGrid.cells[i]));
-  const grid = finishGrid(bedGrid.cols, bedGrid.rows, cells, bedGrid.background);
+  const grid = finishGrid(bedGrid.cols, bedGrid.rows, cells, bedGrid.background, bedGrid.backgroundCells);
   const bedLayers = seq.bed.layers.length;
   const dominance = rankDominance([
     ...rawDominance(seq.bed, bedOpts).map((d) => ({ ...d, key: bedKey(d.key, d.layerIndex) })),
@@ -4842,7 +5458,16 @@ function perceiveSequenceFrame(seq, T, opts = {}) {
     text: [...textSprites(seq.bed, bedOpts).map(prefix), ...textSprites(ink, segOpts).map(shift)],
     advisories: [
       ...adviseSpec(seq.bed, viewport, { t: T, seed: bedOpts.seed }).map((w) => ({ ...w, path: `bed.${w.path}` })),
-      ...adviseSpec(inkOverBed, viewport, { t: r.localT, seed: segOpts.seed })
+      // inkOverBed's layers are the segment's (seed: segOpts.seed) but its
+      // background is the bed's (seq.bed.background) — a field there must be
+      // sampled with the bed's own seed, or a `role: 'read'` legibility
+      // advisory checks terrain that isn't what's actually behind the ink.
+      // `?? 42`: inkOverBed.seed is the SEGMENT's raw seed field (it's `ink`
+      // spread first), so adviseSpec's own `backgroundSeed ?? seed` fallback
+      // would substitute the segment's seed, not the bed's, if bedOpts.seed
+      // were left undefined — 42 is the same default `luminanceGrid` (and
+      // every other field seed fallback) converges on.
+      ...adviseSpec(inkOverBed, viewport, { t: r.localT, seed: segOpts.seed, backgroundSeed: bedOpts.seed ?? 42 })
     ],
     segment,
     bed: true
@@ -6467,6 +7092,38 @@ var SNOWFALL_SPEC = {
   ]
 };
 
+// src/examples/thermal-field.ts
+var THERMAL_FIELD_SPEC = {
+  schemaVersion: 1,
+  id: "thermal-field",
+  label: "Thermal Field",
+  seed: 71,
+  motionIntensity: "calm",
+  // The riso print: grain at half strength, a light dither screen — the
+  // finish that makes the flat inks read as paper rather than pixels.
+  finish: { grain: 0.5, dither: 0.3 },
+  background: {
+    type: "field",
+    scale: 2.2,
+    octaves: 3,
+    warp: 0.4,
+    quantize: 6,
+    bands: ["#1b1a3a", "#0078bf", "#00a99d", "#ffe800", "#ff6c2f", "#ff48b0"],
+    drift: { period: 4e4, amount: 0.3 }
+  },
+  layers: [
+    {
+      key: "motes",
+      count: 14,
+      sprite: { kind: "circle", radius: [0.012, 0.028], color: "#fff6e0", soft: true },
+      motion: { type: "wander", speed: [3e-3, 8e-3], meander: 0.04, coherence: 0.3 },
+      alpha: [0.18, 0.4],
+      blend: "screen",
+      pulse: { amp: 0.15, period: 9e3 }
+    }
+  ]
+};
+
 // src/examples/warp-tunnel.ts
 var WARP_TUNNEL_SPEC = {
   schemaVersion: 1,
@@ -6541,7 +7198,8 @@ var SCHEMA_EXAMPLES = [
   { id: "pings", label: "Pings", spec: PINGS_SPEC },
   { id: "facets", label: "Facets", spec: FACETS_SPEC },
   { id: "relay-board", label: "Relay Board", spec: RELAY_BOARD_SPEC },
-  { id: "lobby-talk", label: "Lobby Talk", spec: LOBBY_TALK_SPEC }
+  { id: "lobby-talk", label: "Lobby Talk", spec: LOBBY_TALK_SPEC },
+  { id: "thermal-field", label: "Thermal Field", spec: THERMAL_FIELD_SPEC }
 ];
 var EXAMPLE_SPECS = SCHEMA_EXAMPLES.map((e) => e.spec);
 var EXAMPLE_BY_ID = Object.fromEntries(
@@ -6554,9 +7212,18 @@ export {
   COMETS_SPEC,
   CONSTELLATION_SPEC,
   DASHBOARD_SPEC,
+  DITHER_ALPHA,
+  DITHER_TILE,
   EXAMPLE_BY_ID,
   EXAMPLE_SPECS,
   FACETS_SPEC,
+  FIELD_BUCKET_MS,
+  FIELD_DRIFT_DEFAULT_AMOUNT,
+  FIELD_RASTER_SHORT_SIDE,
+  FIELD_RASTER_SHORT_SIDE_LOW,
+  FINISH_ANIMATE_HZ,
+  GRAIN_ALPHA,
+  GRAIN_TILE,
   HAIKU_SPEC,
   LANTERNS_SPEC,
   LIMITS,
@@ -6573,6 +7240,7 @@ export {
   SCHEMA_EXAMPLES,
   SCHEMA_VERSION,
   SNOWFALL_SPEC,
+  THERMAL_FIELD_SPEC,
   WARP_MAX_SCALE,
   WARP_NEAR,
   WARP_TUNNEL_SPEC,
@@ -6582,6 +7250,8 @@ export {
   applyDeltasToSpec,
   assertValidSequence,
   assertValidSpec,
+  bayerMatrix,
+  bayerTilePixels,
   bedRenderSeed,
   breakTextBlock,
   buildEntities,
@@ -6589,14 +7259,27 @@ export {
   cohesionOf,
   compileSaver,
   compileSequence,
+  createFinishPass,
+  createSceneCanvas,
   describeScene,
   diffScenes,
   dominanceRanking,
   easeSmooth,
   emitEnvelope,
   emitWindow,
+  fieldAt,
+  fieldOctaves,
+  fieldRgb,
+  fieldRgbAt,
+  fieldSampleTime,
+  finishStrength,
+  grainOffset,
+  grainTilePixels,
   graphemeClusters,
+  hasHotSwapSequence,
   headingAt,
+  hexToRgb255,
+  latticeHash,
   layerCohesion,
   lerpSpec,
   lifeAlphaAt,
@@ -6610,18 +7293,22 @@ export {
   normalizeSeed,
   perceiveScene,
   perceiveSequenceFrame,
+  pickScreenOp,
   positionAt,
+  presentWithFinish,
   renderBrailleMap,
   renderDensityMap,
   resolveSegment,
   resolveSpecPath,
   revealState,
+  rgb255Luma,
   rotationAt,
   seamCauseOf,
   seamsWorthWarning,
   segmentRenderSeed,
   segmentStart,
   sequenceSteerablePaths,
+  sequenceSwapCompatible,
   sizeAt,
   spriteIndexAt,
   spriteVariants,