@idle-screens/schema 3.9.1 → 3.10.0

package/dist/index.js

@@ -71,6 +71,20 @@ var LIMITS = {
   minTransitionDur: 200,
   minEmitEvery: 1e3,
   // ms — at most one event per second per entity (flash safety)
+  maxTimelineKeys: 256,
+  minTimelineKeyInterval: 200,
+  // ms — distinct key times on one path (flash safety; the timeline design's floor)
+  maxTimelineKeyDur: 3e4,
+  // ms — one key's glide
+  maxTimelineDuration: 864e5,
+  // ms — a looping timeline's lap (a day)
+  maxLayerTransformOffset: 2,
+  // min(w,h) units — transform x/y and position dx/dy
+  maxLayerTransformOffsetPx: 17280,
+  // px, under `units: 'px'` — twice the largest referenceViewport
+  maxLayerTransformScale: 8,
+  maxLayerTransformRotate: 3600,
+  // degrees
   maxEmitEvery: 6e5,
   // ms — ten minutes; longer silences than that are `life.enter`
   minEmitLife: 500,
@@ -121,6 +135,79 @@ function resolveSpecPath(spec, path) {
   const exists = Array.isArray(node) ? Number.isInteger(key) && key >= 0 && key < node.length : last in node;
   return exists ? { parent: node, key } : null;
 }
+function canonicalSpecPath(spec, path) {
+  if (!resolveSpecPath(spec, path)) return null;
+  const parts = path.split(".");
+  const s = spec;
+  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) parts.splice(0, 1, "layers", String(idx));
+  }
+  return parts.join(".");
+}
+function readSpecPath(spec, path) {
+  const loc = resolveSpecPath(spec, path);
+  return loc ? loc.parent[loc.key] : void 0;
+}
+var TRANSFORM_IDENTITY = { x: 0, y: 0, scale: 1, scaleX: 1, rotate: 0 };
+function alignTransform(a, b) {
+  const isObj2 = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+  if (!isObj2(a) || !isObj2(b)) return [a, b];
+  let fa = null;
+  let fb = null;
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])) {
+    const id = TRANSFORM_IDENTITY[key];
+    if (id === void 0) continue;
+    if (a[key] === void 0) (fa ??= { ...a })[key] = id;
+    if (b[key] === void 0) (fb ??= { ...b })[key] = id;
+  }
+  return [fa ?? a, fb ?? b];
+}
+function alignPaintFields(a, b) {
+  const la = a?.layers;
+  const lb = b?.layers;
+  if (!Array.isArray(la) || !Array.isArray(lb)) return [a, b];
+  let outA = null;
+  let outB = null;
+  const n = Math.min(la.length, lb.length);
+  for (let i = 0; i < n; i++) {
+    const x = la[i];
+    const y = lb[i];
+    if (!x || !y || typeof x !== "object" || typeof y !== "object") continue;
+    let nx = x;
+    let ny = y;
+    if (x.opacity === void 0 !== (y.opacity === void 0)) {
+      if (x.opacity === void 0) nx = { ...nx, opacity: 1 };
+      else ny = { ...ny, opacity: 1 };
+    }
+    const tx = x.transform;
+    const ty = y.transform;
+    if (tx || ty) {
+      const fx = { ...tx ?? {} };
+      const fy = { ...ty ?? {} };
+      let changed = !tx || !ty;
+      for (const key of /* @__PURE__ */ new Set([...Object.keys(fx), ...Object.keys(fy)])) {
+        const id = TRANSFORM_IDENTITY[key];
+        if (id === void 0) continue;
+        if (fx[key] === void 0) {
+          fx[key] = id;
+          changed = true;
+        }
+        if (fy[key] === void 0) {
+          fy[key] = id;
+          changed = true;
+        }
+      }
+      if (changed) {
+        nx = { ...nx, transform: fx };
+        ny = { ...ny, transform: fy };
+      }
+    }
+    if (nx !== x) (outA ??= la.slice())[i] = nx;
+    if (ny !== y) (outB ??= lb.slice())[i] = ny;
+  }
+  return [outA ? { ...a, layers: outA } : a, outB ? { ...b, layers: outB } : b];
+}
 function applyDeltasToSpec(spec, deltas) {
   const copy = JSON.parse(JSON.stringify(spec));
   for (const d of deltas) {
@@ -143,7 +230,14 @@ function lerpHex(a, b, k) {
 }
 function lerpSpec(from, to, k) {
   const kk = Math.max(0, Math.min(1, k));
-  const walk = (a, b, key) => {
+  const out = lerpValue(from, to, kk, true);
+  return out;
+}
+function lerpValue(from, to, k, specRoot = false, rootKey) {
+  if (specRoot) [from, to] = alignPaintFields(from, to);
+  if (rootKey === "transform") [from, to] = alignTransform(from, to);
+  const kk = Math.max(0, Math.min(1, k));
+  const walk = (a, b, key, root = false) => {
     if (typeof a === "number" && typeof b === "number") {
       const v = a + (b - a) * kk;
       return key === "count" ? Math.max(1, Math.round(v)) : v;
@@ -157,13 +251,15 @@ function lerpSpec(from, to, k) {
     if (a && b && typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b)) {
       const out = {};
       for (const kName of Object.keys(b)) {
-        out[kName] = walk(a[kName], b[kName], kName);
+        const av = a[kName];
+        const bv = b[kName];
+        out[kName] = root && kName === "timeline" ? kk > 0 ? bv : av : kName === "transform" ? walk(...alignTransform(av, bv), kName) : walk(av, bv, kName);
       }
       return out;
     }
     return kk > 0 ? b : a;
   };
-  return walk(from, to);
+  return walk(from, to, rootKey, specRoot);
 }
 function textStringsOf(sprite) {
   if (sprite.kind === "text") return sprite.strings;
@@ -301,13 +397,244 @@ function structuralSignature(spec) {
   ]);
 }
 
+// src/sequence.ts
+function segmentStart(seq, index) {
+  let t = 0;
+  const n = Math.max(0, Math.min(index, seq.segments.length - 1));
+  for (let i = 0; i < n; i++) t += seq.segments[i].duration ?? 0;
+  return t;
+}
+function resolveSegment(seq, T, opts = {}) {
+  const { segments, loop } = seq;
+  if (segments.length === 0) return { index: 0, localT: 0, startT: 0 };
+  let totalTimed = 0;
+  for (const seg of segments) {
+    if (seg.duration != null) totalTimed += seg.duration;
+    else break;
+  }
+  const t0 = Math.max(0, T);
+  const walk = (t, releasedBelow) => {
+    let cumulative = 0;
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+      if (seg.duration == null) {
+        return loop ? null : { index: i, localT: t - cumulative, startT: cumulative };
+      }
+      if (t < cumulative + seg.duration) {
+        return { index: i, localT: t - cumulative, startT: cumulative };
+      }
+      if (seg.advance === "input" && i >= releasedBelow) {
+        return { index: i, localT: t - cumulative, startT: cumulative, held: true };
+      }
+      cumulative += seg.duration;
+    }
+    return null;
+  };
+  const first = walk(t0, opts.releasedBelow ?? 0);
+  if (first) return first;
+  if (loop && totalTimed > 0) {
+    const wrapped = walk(t0 % totalTimed, 0);
+    if (wrapped) return wrapped;
+  }
+  const last = segments.length - 1;
+  const lastStart = totalTimed - (segments[last].duration ?? 0);
+  return { index: last, localT: t0 - lastStart, startT: lastStart };
+}
+function canMorph(seq, from) {
+  const seg = seq.segments[from];
+  if (!seg || seg.transition?.type !== "morph") return false;
+  const next = seq.segments[from + 1];
+  if (!next) return false;
+  return structuralSignature(seg.scene) === structuralSignature(next.scene);
+}
+function morphChainRoot(seq, index) {
+  let i = index;
+  while (i > 0 && canMorph(seq, i - 1)) i--;
+  return i;
+}
+function canWrapMorph(seq) {
+  if (seq.wrapMorph !== true || seq.loop !== true) return false;
+  const last = seq.segments.length - 1;
+  if (last < 1) return false;
+  const seg = seq.segments[last];
+  if (seg.transition?.type !== "morph" || seg.duration == null) return false;
+  if (morphChainRoot(seq, last) !== 0) return false;
+  return structuralSignature(seg.scene) === structuralSignature(seq.segments[0].scene);
+}
+function normalizeSeed(seed) {
+  return seed >>> 0 || 1;
+}
+function segmentRenderSeed(seq, index) {
+  const root = morphChainRoot(seq, index);
+  const scene = seq.segments[root]?.scene;
+  if (!scene) return void 0;
+  const raw = scene.seed ?? (seq.seed !== void 0 ? seq.seed + root : void 0);
+  return raw === void 0 ? void 0 : normalizeSeed(raw);
+}
+function bedRenderSeed(seq) {
+  if (!seq.bed) return void 0;
+  const raw = seq.bed.seed ?? (seq.seed !== void 0 ? seq.seed + LIMITS.maxSegments : void 0);
+  return raw === void 0 ? void 0 : normalizeSeed(raw);
+}
+function sequenceWantsFinish(seq) {
+  return seq.finish !== void 0 || seq.segments.some((s) => s.scene.finish !== void 0);
+}
+function sequenceSwapCompatible(prev, next) {
+  if (prev.segments.length !== next.segments.length) return false;
+  if (prev.finish !== void 0 || next.finish !== void 0) {
+    if (prev.seed === void 0 !== (next.seed === void 0)) return false;
+    if (prev.seed !== void 0 && next.seed !== void 0 && normalizeSeed(prev.seed) !== normalizeSeed(next.seed)) return false;
+  }
+  if (sequenceWantsFinish(prev) !== sequenceWantsFinish(next)) 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/timeline.ts
+var DEFAULT_KEY_DUR = 1e3;
+var tracksCache = /* @__PURE__ */ new WeakMap();
+function withoutTimeline(spec) {
+  if (!spec.timeline) return spec;
+  const rest = { ...spec };
+  delete rest.timeline;
+  return rest;
+}
+function timelineTracks(spec) {
+  const tl = spec.timeline;
+  if (!tl) return /* @__PURE__ */ new Map();
+  const hit = tracksCache.get(tl);
+  if (hit && hit.spec === spec) return hit.tracks;
+  const base = withoutTimeline(spec);
+  const tracks = /* @__PURE__ */ new Map();
+  for (const k of tl.keys ?? []) {
+    const cp = canonicalSpecPath(base, k.path);
+    if (!cp) continue;
+    const list = tracks.get(cp) ?? [];
+    list.push(k);
+    tracks.set(cp, list);
+  }
+  for (const list of tracks.values()) list.sort((a, b) => a.t - b.t);
+  tracksCache.set(tl, { spec, tracks });
+  return tracks;
+}
+function timelineLocalTime(tl, t) {
+  const d = tl.duration ?? 0;
+  if (tl.loop && d > 0) return (t % d + d) % d;
+  return t;
+}
+function ease(k, x) {
+  const c = x <= 0 ? 0 : x >= 1 ? 1 : x;
+  if (k.ease === "step") return c >= 1 ? 1 : 0;
+  if (k.ease === "linear") return c;
+  return easeSmooth(c);
+}
+function evalTrack(keys, start, tt, leaf) {
+  let from = start;
+  let key = null;
+  const at = (tau) => {
+    if (!key) return from;
+    const dur = key.dur ?? DEFAULT_KEY_DUR;
+    if (dur <= 0 || tau >= key.t + dur) return key.value;
+    return lerpValue(from, key.value, ease(key, (tau - key.t) / dur), false, leaf);
+  };
+  for (const k of keys) {
+    if (k.t > tt) break;
+    from = at(k.t);
+    key = k;
+  }
+  return at(tt);
+}
+function resolveTimelineAt(spec, t) {
+  const tl = spec.timeline;
+  if (!tl) return spec;
+  const base = withoutTimeline(spec);
+  const tracks = timelineTracks(spec);
+  if (tracks.size === 0) return base;
+  const tt = timelineLocalTime(tl, t);
+  const deltas = [];
+  for (const [path, keys] of tracks) {
+    const start = tl.loop ? keys[keys.length - 1].value : readSpecPath(base, path);
+    deltas.push({ t: 0, path, value: evalTrack(keys, start, tt, path.slice(path.lastIndexOf(".") + 1)) });
+  }
+  return applyDeltasToSpec(base, deltas);
+}
+function nextKeyAfter(spec, path, t) {
+  const tl = spec.timeline;
+  if (!tl) return null;
+  const cp = canonicalSpecPath(withoutTimeline(spec), path);
+  const keys = cp ? timelineTracks(spec).get(cp) : void 0;
+  if (!keys || keys.length === 0) return null;
+  const tt = timelineLocalTime(tl, t);
+  const next = keys.find((k) => k.t > tt);
+  if (next) return { at: t + (next.t - tt), dur: next.dur ?? DEFAULT_KEY_DUR };
+  if (tl.loop && (tl.duration ?? 0) > 0) {
+    const first = keys[0];
+    return { at: t + (tl.duration - tt) + first.t, dur: first.dur ?? DEFAULT_KEY_DUR };
+  }
+  return null;
+}
+function timelineSampleTimes(spec, dense = true, cap = 120, only) {
+  const tl = spec.timeline;
+  if (!tl) return [];
+  const d = tl.duration ?? 0;
+  const fold = (t) => tl.loop && d > 0 ? (t % d + d) % d : t;
+  const bounds = /* @__PURE__ */ new Set([0]);
+  const extras = /* @__PURE__ */ new Set();
+  const keys = [];
+  for (const [path, list] of timelineTracks(spec)) if (!only || only(path)) keys.push(...list);
+  for (const k of keys) {
+    if (!Number.isFinite(k.t)) continue;
+    const dur = k.dur ?? DEFAULT_KEY_DUR;
+    bounds.add(fold(k.t));
+    bounds.add(fold(k.t + dur));
+    if (dense) for (const f of [0.25, 0.5, 0.75]) extras.add(fold(k.t + dur * f));
+  }
+  let extra = [...extras].filter((t) => !bounds.has(t)).sort((a, b) => a - b);
+  if (extra.length > cap) {
+    const step = extra.length / cap;
+    extra = Array.from({ length: cap }, (_, i) => extra[Math.floor(i * step)]);
+  }
+  return [.../* @__PURE__ */ new Set([...bounds, ...extra])].filter(Number.isFinite).sort((a, b) => a - b);
+}
+function timelineSampleTimesAfter(spec, now, dense = false, only) {
+  const tl = spec.timeline;
+  if (!tl) return [];
+  const local = timelineSampleTimes(spec, dense, 120, only);
+  const d = tl.duration ?? 0;
+  if (tl.loop && d > 0) {
+    const phase = (now % d + d) % d;
+    return local.map((s) => now + ((s - phase) % d + d) % d).sort((a, b) => a - b);
+  }
+  return local.filter((s) => s > now);
+}
+
 // src/validate.ts
 var HEX2 = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
 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", "finish"]);
+var KNOWN_TOP = /* @__PURE__ */ new Set(["schemaVersion", "id", "label", "seed", "motionIntensity", "density", "units", "referenceViewport", "background", "layers", "ghosting", "finish", "timeline"]);
 var KNOWN_FINISH = /* @__PURE__ */ new Set(["grain", "dither", "animate"]);
 var KNOWN_LAYER = /* @__PURE__ */ new Set([
   "count",
@@ -330,8 +657,14 @@ var KNOWN_LAYER = /* @__PURE__ */ new Set([
   "life",
   "emit",
   "clock",
-  "rotate"
+  "rotate",
+  "opacity",
+  "transform"
 ]);
+var KNOWN_TRANSFORM = /* @__PURE__ */ new Set(["x", "y", "scale", "scaleX", "rotate"]);
+var KNOWN_POSITION = /* @__PURE__ */ new Set(["x", "y", "dx", "dy"]);
+var KNOWN_TIMELINE = /* @__PURE__ */ new Set(["loop", "duration", "keys"]);
+var KNOWN_TIMELINE_KEY = /* @__PURE__ */ new Set(["t", "path", "value", "ease", "dur"]);
 var KNOWN_CIRCLE = /* @__PURE__ */ new Set(["kind", "radius", "color", "soft", "colors", "colorWeights"]);
 var KNOWN_RING = /* @__PURE__ */ new Set(["kind", "radius", "color", "width", "colors", "colorWeights"]);
 var KNOWN_STREAK = /* @__PURE__ */ new Set(["kind", "length", "color", "width", "colors", "colorWeights"]);
@@ -366,6 +699,9 @@ function unknownKeys(obj, known) {
 function dimUnit(spec) {
   return isObj(spec) && spec.units === "px" ? "px" : "fractions of min(width, height)";
 }
+function offsetBound(spec) {
+  return isObj(spec) && spec.units === "px" ? [LIMITS.maxLayerTransformOffsetPx, "px"] : [LIMITS.maxLayerTransformOffset, "min(w, h) units"];
+}
 function rangeMsg(spec, note) {
   return `must be a [min,max] range of positive ${dimUnit(spec)}${note ? ` (${note})` : ""}`;
 }
@@ -393,6 +729,38 @@ function ignoredPropertyPaths(spec) {
   if (!isObj(spec)) return [];
   return (validateSpecCore(spec).warnings ?? []).filter((w) => w.code === "unknown-property" || w.code === "misplaced-property").map((w) => w.path.replace(/\[(\d+)\]/g, ".$1"));
 }
+function validateSpecPaths(spec, paths) {
+  const layers = /* @__PURE__ */ new Set();
+  let background = false;
+  let finish = false;
+  for (const p of paths) {
+    if (/^layers\.\d+(\.(key|count|motion)(\.|$)|$)/.test(p)) return validateSpec(spec).valid;
+    const [head, idx] = p.split(".");
+    if (head === "layers" && idx !== void 0 && /^\d+$/.test(idx)) layers.add(Number(idx));
+    else if (head === "background") background = true;
+    else if (head === "finish") finish = true;
+    else return validateSpec(spec).valid;
+  }
+  let ok = true;
+  const err = () => {
+    ok = false;
+  };
+  const warn = () => void 0;
+  if (!Array.isArray(spec.layers)) return false;
+  for (const i of layers) {
+    const layer = spec.layers[i];
+    if (layer === void 0) return false;
+    validateLayer(layer, `layers[${i}]`, err, warn, spec);
+    if (spec.units === "px" && isObj(layer) && isObj(layer.sprite) && layer.sprite.kind === "textBlock") ok = false;
+  }
+  if (background && spec.background !== void 0) validateBackground(spec.background, err, warn);
+  if (finish && spec.finish !== void 0) validateFinish(spec.finish, "finish", err, warn);
+  if (layers.size > 0) {
+    const total = spec.layers.reduce((n, l) => n + (isObj(l) && isNum(l.count) ? l.count : 0), 0);
+    if (total > LIMITS.maxTotal) ok = false;
+  }
+  return ok;
+}
 function validateSpecCore(spec) {
   const errors = [];
   const warnings = [];
@@ -444,8 +812,107 @@ function validateSpecCore(spec) {
     });
     if (total > LIMITS.maxTotal) err("layers", `total entities ${total} exceeds cap ${LIMITS.maxTotal}`);
   }
+  if (spec.timeline !== void 0 && errors.length === 0) validateTimeline(spec, err, warn);
   return { valid: errors.length === 0, errors, warnings };
 }
+function validateTimeline(spec, errOuter, warn) {
+  let failed = false;
+  const err = (p, m) => {
+    failed = true;
+    errOuter(p, m);
+  };
+  const tl = spec.timeline;
+  if (!isObj(tl)) return err("timeline", "must be an object {loop?, duration?, keys}");
+  for (const k of unknownKeys(tl, KNOWN_TIMELINE)) warn(`timeline.${k}`, "unknown-property", `unknown timeline property '${k}' \u2014 will be ignored`);
+  if (tl.loop !== void 0 && typeof tl.loop !== "boolean") err("timeline.loop", "must be a boolean");
+  if (tl.duration !== void 0 && (!isNum(tl.duration) || tl.duration <= 0 || tl.duration > LIMITS.maxTimelineDuration)) {
+    err("timeline.duration", `must be a number of ms, 0 < duration <= ${LIMITS.maxTimelineDuration}`);
+  }
+  if (tl.loop === true && tl.duration === void 0) err("timeline.duration", "loop: true needs a duration (the lap length in ms)");
+  if (!Array.isArray(tl.keys) || tl.keys.length === 0) return err("timeline.keys", "must be a non-empty array");
+  if (tl.keys.length > LIMITS.maxTimelineKeys) return err("timeline.keys", `at most ${LIMITS.maxTimelineKeys} keys`);
+  const base = withoutTimeline(spec);
+  const baseSig = structuralSignature(base);
+  const times = /* @__PURE__ */ new Map();
+  let latest = 0;
+  tl.keys.forEach((key, i) => {
+    const p = `timeline.keys[${i}]`;
+    if (!isObj(key)) return err(p, "must be an object {t, path, value, ease?, dur?}");
+    for (const k of unknownKeys(key, KNOWN_TIMELINE_KEY)) warn(`${p}.${k}`, "unknown-property", `unknown key property '${k}' \u2014 will be ignored`);
+    let ok = true;
+    if (!isNum(key.t) || key.t < 0) {
+      err(`${p}.t`, "must be a number of ms >= 0");
+      ok = false;
+    }
+    if (key.ease !== void 0 && key.ease !== "step" && key.ease !== "linear" && key.ease !== "smooth") err(`${p}.ease`, "must be 'step' | 'linear' | 'smooth'");
+    if (key.dur !== void 0 && (!isNum(key.dur) || key.dur < 0 || key.dur > LIMITS.maxTimelineKeyDur)) {
+      err(`${p}.dur`, `must be a number of ms, 0..${LIMITS.maxTimelineKeyDur}`);
+    }
+    if (!("value" in key)) {
+      err(`${p}.value`, "is required");
+      ok = false;
+    }
+    const cp = isStr(key.path) ? canonicalSpecPath(base, key.path) : null;
+    if (!isStr(key.path) || key.path.trim() === "") {
+      err(`${p}.path`, "must be a non-empty dot-path");
+      ok = false;
+    } else if (!cp) {
+      err(`${p}.path`, `'${key.path}' does not resolve on the spec \u2014 a key can only animate a field the spec already has`);
+      ok = false;
+    } else if (cp.split(".").includes("timeline") || cp === "schemaVersion" || cp === "id" || cp === "label" || cp === "seed") {
+      err(`${p}.path`, `'${key.path}' is not animatable`);
+      ok = false;
+    }
+    if (!ok || !cp) return;
+    const t = key.t;
+    latest = Math.max(latest, t);
+    const applied = applyDeltasToSpec(base, [{ t: 0, path: cp, value: key.value }]);
+    const r = validateSpecPaths(applied, [cp]) ? { valid: true, errors: [] } : validateSpec(applied);
+    if (!r.valid) {
+      for (const e of r.errors) err(`${p}.value`, `applied at '${key.path}' \u2192 ${e.path || "<root>"}: ${e.message}`);
+      return;
+    }
+    if (structuralSignature(applied) !== baseSig) {
+      warn(`${p}.path`, "timeline-structural-key", `'${key.path}' is structural (placement, count, motion, size\u2026): the scene rebuilds at this key and entities re-seed \u2014 a pop, not a glide. Animate paint (colour, opacity, transform, polygon points) instead`);
+    }
+    const list = times.get(cp) ?? [];
+    list.push(t);
+    times.set(cp, list);
+    const dur = isNum(key.dur) ? key.dur : DEFAULT_KEY_DUR;
+    if (tl.loop === true && isNum(tl.duration) && t + dur > tl.duration) {
+      warn(`${p}.dur`, "timeline-glide-overruns-lap", `this key's glide ends at ${t + dur} ms, after the ${tl.duration} ms lap \u2014 the wrap cuts it short`);
+    }
+  });
+  if (tl.loop === true && isNum(tl.duration) && latest >= tl.duration) {
+    err("timeline.duration", `must be greater than the latest key's t (${latest} ms) under loop`);
+  }
+  const minGap = LIMITS.minTimelineKeyInterval;
+  for (const [path, list] of times) {
+    const distinct = [...new Set(list)].sort((a, b) => a - b);
+    for (let i = 1; i < distinct.length; i++) {
+      if (distinct[i] - distinct[i - 1] < minGap) {
+        err("timeline.keys", `keys on '${path}' at ${distinct[i - 1]} and ${distinct[i]} ms are closer than ${minGap} ms (flash safety)`);
+      }
+    }
+    if (tl.loop === true && isNum(tl.duration) && distinct.length > 1) {
+      const wrapGap = tl.duration - distinct[distinct.length - 1] + distinct[0];
+      if (wrapGap < minGap) err("timeline.keys", `keys on '${path}' at ${distinct[distinct.length - 1]} ms and ${distinct[0]} ms (next lap) are closer than ${minGap} ms across the loop wrap (flash safety)`);
+    }
+  }
+  if (failed) return;
+  const keyed = [...timelineTracks(spec).keys()];
+  const seen = /* @__PURE__ */ new Set();
+  for (const t of timelineSampleTimes(spec, true, 120)) {
+    const r = resolveTimelineAt(spec, t);
+    const state = JSON.stringify(keyed.map((p) => readSpecPath(r, p)));
+    if (seen.has(state)) continue;
+    seen.add(state);
+    if (validateSpecPaths(r, keyed)) continue;
+    const e = validateSpec(r).errors[0];
+    err("timeline", `at t = ${Math.round(t)} ms the keys combine into an invalid scene \u2014 ${e ? `${e.path || "<root>"}: ${e.message}` : "invalid"}`);
+    return;
+  }
+}
 function color(v, path, err) {
   if (!isStr(v) || !HEX2.test(v)) err(path, "must be a hex colour like #0a3a52");
 }
@@ -569,12 +1036,40 @@ function validateLayer(layer, path, err, warn, spec) {
   if (layer.key !== void 0 && (!isStr(layer.key) || layer.key.trim() === "")) {
     err(`${path}.key`, "must be a non-empty string");
   }
+  if (layer.opacity !== void 0 && (!isNum(layer.opacity) || layer.opacity < 0 || layer.opacity > 1)) {
+    err(`${path}.opacity`, "must be a number 0..1");
+  }
+  if (layer.transform !== void 0) {
+    const tf = layer.transform;
+    if (!isObj(tf)) err(`${path}.transform`, "must be an object {x?, y?, scale?, scaleX?, rotate?}");
+    else {
+      for (const k of unknownKeys(tf, KNOWN_TRANSFORM)) warn(`${path}.transform.${k}`, "unknown-property", `unknown transform property '${k}' \u2014 will be ignored`);
+      const [off, unit] = offsetBound(spec);
+      const sc = LIMITS.maxLayerTransformScale;
+      for (const axis of ["x", "y"]) {
+        if (tf[axis] !== void 0 && (!isNum(tf[axis]) || Math.abs(tf[axis]) > off)) err(`${path}.transform.${axis}`, `must be a number within \xB1${off} (${unit})`);
+      }
+      if (tf.scale !== void 0 && (!isNum(tf.scale) || tf.scale < 0 || tf.scale > sc)) err(`${path}.transform.scale`, `must be a number 0..${sc}`);
+      if (tf.scaleX !== void 0 && (!isNum(tf.scaleX) || Math.abs(tf.scaleX) > sc)) err(`${path}.transform.scaleX`, `must be a number within \xB1${sc} (negative mirrors)`);
+      if (tf.rotate !== void 0 && (!isNum(tf.rotate) || Math.abs(tf.rotate) > LIMITS.maxLayerTransformRotate)) {
+        err(`${path}.transform.rotate`, `must be a number of degrees within \xB1${LIMITS.maxLayerTransformRotate}`);
+      }
+    }
+  }
   if (layer.position !== void 0) {
     if (!isObj(layer.position) || !isNum(layer.position.x) || !isNum(layer.position.y)) {
       err(`${path}.position`, "must be {x, y} with numbers 0..1");
     } else {
       if (layer.position.x < 0 || layer.position.x > 1) err(`${path}.position.x`, "must be 0..1");
       if (layer.position.y < 0 || layer.position.y > 1) err(`${path}.position.y`, "must be 0..1");
+      const [off, unit] = offsetBound(spec);
+      for (const axis of ["dx", "dy"]) {
+        const v = layer.position[axis];
+        if (v !== void 0 && (!isNum(v) || Math.abs(v) > off)) {
+          err(`${path}.position.${axis}`, `must be a number within \xB1${off} (${unit})`);
+        }
+      }
+      for (const k of unknownKeys(layer.position, KNOWN_POSITION)) warn(`${path}.position.${k}`, "unknown-property", `unknown position property '${k}' \u2014 will be ignored`);
       const dataLayout = isObj(layer.layout) && (layer.layout.type === "list" || layer.layout.type === "table");
       if (isNum(layer.count) && layer.count !== 1 && !dataLayout) {
         err(`${path}.position`, "position requires count: 1 \u2014 or a layout of type 'list' / 'table', where it anchors the whole block");
@@ -1161,14 +1656,14 @@ function validateShapePoints(points, path, min, err) {
     }
   }
 }
-function validateEase(ease, path, err, warn) {
-  if (ease === void 0) return;
-  if (!isObj(ease)) return err(path, "must be an object { type: 'settle' | 'buoyant', tau }");
-  if (ease.type !== "settle" && ease.type !== "buoyant") err(`${path}.type`, "must be 'settle' | 'buoyant'");
-  if (!isNum(ease.tau) || ease.tau < LIMITS.minEaseTau || ease.tau > LIMITS.maxEaseTau) {
+function validateEase(ease2, path, err, warn) {
+  if (ease2 === void 0) return;
+  if (!isObj(ease2)) return err(path, "must be an object { type: 'settle' | 'buoyant', tau }");
+  if (ease2.type !== "settle" && ease2.type !== "buoyant") err(`${path}.type`, "must be 'settle' | 'buoyant'");
+  if (!isNum(ease2.tau) || ease2.tau < LIMITS.minEaseTau || ease2.tau > LIMITS.maxEaseTau) {
     err(`${path}.tau`, `must be ${LIMITS.minEaseTau}..${LIMITS.maxEaseTau} ms`);
   }
-  for (const k of unknownKeys(ease, /* @__PURE__ */ new Set(["type", "tau"]))) {
+  for (const k of unknownKeys(ease2, /* @__PURE__ */ new Set(["type", "tau"]))) {
     warn(`${path}.${k}`, "unknown-property", `unknown ease property '${k}' \u2014 will be ignored`);
   }
 }
@@ -1200,6 +1695,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.wrapMorph !== void 0 && typeof seq.wrapMorph !== "boolean") err("wrapMorph", "must be a boolean");
   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");
@@ -1253,8 +1749,8 @@ function validateSequence(seq) {
       if (isObj(s.transition) && s.transition.text !== void 0) {
         if (s.transition.type !== "morph") {
           err(`${p}.transition.text`, "is a morph option (fade already cross-fades whole frames; cut has no window)");
-        } else if (s.transition.text !== "step" && s.transition.text !== "crossfade") {
-          err(`${p}.transition.text`, "must be 'step' | 'crossfade'");
+        } else if (s.transition.text !== "step" && s.transition.text !== "crossfade" && s.transition.text !== "dip") {
+          err(`${p}.transition.text`, "must be 'step' | 'crossfade' | 'dip'");
         }
       }
     }
@@ -1311,7 +1807,7 @@ function validateSequence(seq) {
           code: "morph-structural-mismatch",
           message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
         });
-      } else if (morphNothingMorphable(s.scene, next.scene, { textCrossfade: s.transition.text === "crossfade" })) {
+      } else if (s.scene.timeline === void 0 && next.scene.timeline === void 0 && morphNothingMorphable(s.scene, next.scene, { textCrossfade: s.transition.text === "crossfade" || s.transition.text === "dip" })) {
         warnings.push({
           path: `segments[${i}].transition`,
           code: "morph-nothing-morphable",
@@ -1320,6 +1816,20 @@ function validateSequence(seq) {
       }
     }
   }
+  if (errors.length === 0 && seq.wrapMorph === true) {
+    const sq = seq;
+    const last = sq.segments.length - 1;
+    const lastTr = sq.segments[last]?.transition;
+    let why = null;
+    if (sq.loop !== true) why = "the sequence does not loop";
+    else if (last < 1) why = "there is only one segment";
+    else if (lastTr?.type !== "morph") why = "the last segment declares no morph transition";
+    else if (structuralSignature(sq.segments[last].scene) !== structuralSignature(sq.segments[0].scene)) why = `segment ${last} and segment 0 differ structurally`;
+    else if (morphChainRoot(sq, last) !== 0) why = `the lap is not one morph chain (segment ${morphChainRoot(sq, last)} starts a new chain), so the wrap would jump seeds`;
+    if (why || !canWrapMorph(sq)) {
+      warnings.push({ path: "wrapMorph", code: "wrap-morph-inactive", message: `wrapMorph has no effect: ${why ?? "the wrap cannot morph"} \u2014 the wrap stays a cut` });
+    }
+  }
   return { valid: errors.length === 0, errors, warnings };
 }
 function assertValidSequence(seq) {
@@ -1511,7 +2021,7 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
   if (mSpec.type === "path") {
     pathPts = mSpec.points.map((p) => ({ x: p.x * w, y: p.y * h }));
   }
-  const ease = mSpec.type === "drift" || mSpec.type === "rise" || mSpec.type === "wander" ? mSpec.ease : void 0;
+  const ease2 = mSpec.type === "drift" || mSpec.type === "rise" || mSpec.type === "wander" ? mSpec.ease : void 0;
   const clockPhase = layer.clock ? (layer.clock.phase ?? 0) % 1 * Math.PI * 2 : 0;
   const layout = layer.layout;
   const ordered = layout?.type === "list" || layout?.type === "table";
@@ -1530,6 +2040,8 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
     if (layer.position) {
       listX0 = layer.position.x * w;
       listY0 = layer.position.y * h;
+      if (layer.position.dx) listX0 += layer.position.dx * scale;
+      if (layer.position.dy) listY0 += layer.position.dy * scale;
     } else {
       const [rx0, rx1] = layer.region?.x ?? [0, 1];
       const [ry0, ry1] = layer.region?.y ?? [0, 1];
@@ -1624,6 +2136,8 @@ function buildEntities(layer, rng, w, h, scale = 1, countScale = 1) {
     if (layer.position && layer.count === 1) {
       x0 = layer.position.x * w;
       y0 = layer.position.y * h;
+      if (layer.position.dx) x0 += layer.position.dx * scale;
+      if (layer.position.dy) y0 += layer.position.dy * scale;
     } else if (layout?.type === "list" || layout?.type === "table") {
       rng.next();
       rng.next();
@@ -1705,7 +2219,7 @@ 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 } } : {},
+      ...ease2 ? { ease: { type: ease2.type, tau: ease2.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 } : {}
@@ -2422,110 +2936,6 @@ function screen(fp, pat, alpha, off, w, h) {
   p.restore();
 }
 
-// src/sequence.ts
-function segmentStart(seq, index) {
-  let t = 0;
-  const n = Math.max(0, Math.min(index, seq.segments.length - 1));
-  for (let i = 0; i < n; i++) t += seq.segments[i].duration ?? 0;
-  return t;
-}
-function resolveSegment(seq, T, opts = {}) {
-  const { segments, loop } = seq;
-  if (segments.length === 0) return { index: 0, localT: 0, startT: 0 };
-  let totalTimed = 0;
-  for (const seg of segments) {
-    if (seg.duration != null) totalTimed += seg.duration;
-    else break;
-  }
-  const t0 = Math.max(0, T);
-  const walk = (t, releasedBelow) => {
-    let cumulative = 0;
-    for (let i = 0; i < segments.length; i++) {
-      const seg = segments[i];
-      if (seg.duration == null) {
-        return loop ? null : { index: i, localT: t - cumulative, startT: cumulative };
-      }
-      if (t < cumulative + seg.duration) {
-        return { index: i, localT: t - cumulative, startT: cumulative };
-      }
-      if (seg.advance === "input" && i >= releasedBelow) {
-        return { index: i, localT: t - cumulative, startT: cumulative, held: true };
-      }
-      cumulative += seg.duration;
-    }
-    return null;
-  };
-  const first = walk(t0, opts.releasedBelow ?? 0);
-  if (first) return first;
-  if (loop && totalTimed > 0) {
-    const wrapped = walk(t0 % totalTimed, 0);
-    if (wrapped) return wrapped;
-  }
-  const last = segments.length - 1;
-  const lastStart = totalTimed - (segments[last].duration ?? 0);
-  return { index: last, localT: t0 - lastStart, startT: lastStart };
-}
-function canMorph(seq, from) {
-  const seg = seq.segments[from];
-  if (!seg || seg.transition?.type !== "morph") return false;
-  const next = seq.segments[from + 1];
-  if (!next) return false;
-  return structuralSignature(seg.scene) === structuralSignature(next.scene);
-}
-function morphChainRoot(seq, index) {
-  let i = index;
-  while (i > 0 && canMorph(seq, i - 1)) i--;
-  return i;
-}
-function normalizeSeed(seed) {
-  return seed >>> 0 || 1;
-}
-function segmentRenderSeed(seq, index) {
-  const root = morphChainRoot(seq, index);
-  const scene = seq.segments[root]?.scene;
-  if (!scene) return void 0;
-  const raw = scene.seed ?? (seq.seed !== void 0 ? seq.seed + root : void 0);
-  return raw === void 0 ? void 0 : normalizeSeed(raw);
-}
-function bedRenderSeed(seq) {
-  if (!seq.bed) return void 0;
-  const raw = seq.bed.seed ?? (seq.seed !== void 0 ? seq.seed + LIMITS.maxSegments : void 0);
-  return raw === void 0 ? void 0 : normalizeSeed(raw);
-}
-function sequenceWantsFinish(seq) {
-  return seq.finish !== void 0 || seq.segments.some((s) => s.scene.finish !== void 0);
-}
-function sequenceSwapCompatible(prev, next) {
-  if (prev.segments.length !== next.segments.length) return false;
-  if (prev.finish !== void 0 || next.finish !== void 0) {
-    if (prev.seed === void 0 !== (next.seed === void 0)) return false;
-    if (prev.seed !== void 0 && next.seed !== void 0 && normalizeSeed(prev.seed) !== normalizeSeed(next.seed)) return false;
-  }
-  if (sequenceWantsFinish(prev) !== sequenceWantsFinish(next)) 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;
 function applyRetainedDeltas(spec, deltas) {
@@ -2573,10 +2983,62 @@ function manifestFor(spec) {
     workerReady: true
   };
 }
+var clamp013 = (v) => v <= 0 ? 0 : v >= 1 ? 1 : v;
+var EXPIRED = /* @__PURE__ */ Symbol("expired");
+function overrideHeldAt(o, t) {
+  const k = o.dur > 0 ? easeSmooth(clamp013((t - o.t0) / o.dur)) : 1;
+  return k >= 1 ? o.to : lerpValue(o.from, o.to, k, false, o.leaf);
+}
+function overrideValueAt(o, t, timelineValue) {
+  if (t < o.until) return overrideHeldAt(o, t);
+  if (o.outDur > 0 && t < o.until + o.outDur) return lerpValue(overrideHeldAt(o, o.until), timelineValue(), easeSmooth((t - o.until) / o.outDur), false, o.leaf);
+  return EXPIRED;
+}
+var steerId = (d) => `${d.t}|${JSON.stringify(d.value)}`;
+function armOverride(authored, path, from, to, now, glide) {
+  const next = nextKeyAfter(authored, path, now);
+  return { leaf: path.slice(path.lastIndexOf(".") + 1), from, to, t0: now, dur: glide, until: next ? next.at : Number.POSITIVE_INFINITY, outDur: next ? next.dur : 0 };
+}
+function applyOverridesAt(resolved, overrides, t, expired) {
+  if (overrides.size === 0) return resolved;
+  const deltas = [];
+  for (const [path, o] of overrides) {
+    const v = overrideValueAt(o, t, () => readSpecPath(resolved, path));
+    if (v === EXPIRED) {
+      expired?.push(path);
+      continue;
+    }
+    deltas.push({ t: 0, path, value: v });
+  }
+  return deltas.length > 0 ? applyDeltasToSpec(resolved, deltas) : resolved;
+}
+function overridesStayValid(authored, overrides, now) {
+  const paths = [...overrides.keys()];
+  if (paths.length === 0) return true;
+  const groupOf = (p) => p.split(".").slice(0, p.startsWith("layers.") ? 2 : 1).join(".");
+  const groups = [...new Set(paths.map(groupOf))];
+  const full = paths.some((p) => /^layers\.\d+(\.(key|count|motion)(\.|$)|$)/.test(p) || !/^(layers|background|finish)(\.|$)/.test(p));
+  const only = full ? void 0 : (p) => groups.includes(groupOf(p));
+  const seen = /* @__PURE__ */ new Set();
+  for (const t of [now, ...timelineSampleTimesAfter(authored, now, false, only)]) {
+    const held = /* @__PURE__ */ new Map();
+    for (const [p, o] of overrides) if (t < o.until) held.set(p, { ...o, t0: Number.NEGATIVE_INFINITY });
+    const r = applyOverridesAt(resolveTimelineAt(authored, t), held, t);
+    const state = JSON.stringify(groups.map((g) => readSpecPath(r, g))) + "|" + [...held.keys()].join(",");
+    if (seen.has(state)) continue;
+    seen.add(state);
+    if (!validateSpecPaths(r, paths)) return false;
+  }
+  return true;
+}
 var SpecInstance = class {
   constructor(spec, ctx, opts = {}) {
     this.spec = spec;
     this.effSpec = spec;
+    if (spec.timeline) {
+      this.authored = spec;
+      this.effSpec = resolveTimelineAt(spec, 0);
+    }
     this.saverCtx = ctx;
     this.transparent = opts.transparent === true;
     const tier = opts.capabilityTier;
@@ -2642,6 +3104,31 @@ var SpecInstance = class {
   lastStructural = "";
   /** See `LayerPaintOverride`; null (the default, and every plain mount) draws every layer once. */
   paintOverrides = null;
+  /**
+   * The authored spec when it carries a `timeline` (null for every other
+   * scene — which then never enters the timeline path). Each painted frame
+   * resolves it at that frame's own time, so ghosting's warm-up replay and
+   * any seek see the timeline exactly where it was.
+   */
+  authored = null;
+  /**
+   * Live steers on a timeline scene, by index-form path. A steer on a path no
+   * key animates holds forever (sticky, exactly as on a scene without a
+   * timeline); on an animated path it holds `until` that path's next key,
+   * then glides back to the timeline over `outDur`.
+   */
+  overrides = /* @__PURE__ */ new Map();
+  /**
+   * The last registered steer per path, as `t|value`. A host re-sends the
+   * whole channel track on every steer (idle-server broadcasts the full track
+   * so viewers converge), and a steer's `t` is the server's stamp — stable
+   * across re-sends. Without this, an unrelated later steer would re-arm a
+   * hold the timeline had already taken back. Keyed by path (not by the full
+   * `path|t|value` history) so a long-running instance re-steered thousands
+   * of times doesn't accumulate an unbounded set — only the most recent id
+   * per path can ever recur.
+   */
+  seenSteers = /* @__PURE__ */ new Map();
   /** 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. */
@@ -2666,12 +3153,14 @@ var SpecInstance = class {
   }
   sizeCanvas() {
     const dpr = Math.min(this.saverCtx.dpr, 2);
-    this.canvas.width = Math.max(1, Math.round(this.w * dpr));
-    this.canvas.height = Math.max(1, Math.round(this.h * dpr));
+    const cw = Math.max(1, Math.round(this.w * dpr));
+    const ch = Math.max(1, Math.round(this.h * dpr));
+    if (this.canvas.width !== cw) this.canvas.width = cw;
+    if (this.canvas.height !== ch) this.canvas.height = ch;
     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;
+      if (this.finishPass.canvas.width !== cw) this.finishPass.canvas.width = cw;
+      if (this.finishPass.canvas.height !== ch) this.finishPass.canvas.height = ch;
       this.finishPass.ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
     }
     this.lastRenderT = Number.NEGATIVE_INFINITY;
@@ -3124,6 +3613,12 @@ var SpecInstance = class {
    */
   applyTrack(track) {
     const deltas = track?.deltas ?? [];
+    if (this.authored) {
+      const glide = deltas.length ? deltas.reduce((m, d) => Math.max(m, d.dur ?? DEFAULT_STEER_DUR), 0) : DEFAULT_STEER_DUR;
+      if (!this.overrideAuthored(deltas, this.paused ? 0 : glide)) return;
+      if (this.paused) this.renderFrame(this.sceneNow(), this.seed);
+      return;
+    }
     const target = applyDeltasToSpec(this.effSpec, deltas);
     if (!validateSpec(target).valid) return;
     const dur = deltas.length ? deltas.reduce((m, d) => Math.max(m, d.dur ?? DEFAULT_STEER_DUR), 0) : DEFAULT_STEER_DUR;
@@ -3160,6 +3655,13 @@ var SpecInstance = class {
    * showing a ghost of the un-steered scene.
    */
   applyDeltasNow(deltas) {
+    if (this.authored) {
+      const all = [...deltas];
+      if (!this.overrideAuthored(all, 0)) for (const d of all) this.overrideAuthored([d], 0);
+      this.transition = null;
+      this.lastRenderT = Number.NEGATIVE_INFINITY;
+      return;
+    }
     const next = applyRetainedDeltas(this.effSpec, deltas);
     if (next === this.effSpec) return;
     this.transition = null;
@@ -3215,6 +3717,7 @@ var SpecInstance = class {
    *  showing through — the ghosting smear. */
   paintFrame(t, bgAlpha) {
     const { ctx } = this;
+    if (this.authored) this.resolveAuthored(t);
     if (!this.transparent) {
       ctx.globalAlpha = bgAlpha;
       ctx.globalCompositeOperation = "source-over";
@@ -3223,9 +3726,15 @@ var SpecInstance = class {
     ctx.globalAlpha = 1;
     for (let li = 0; li < this.layers.length; li++) {
       const built = this.layers[li];
-      const lifeA = lifeAlphaAt(built.layer.life, t);
+      const opacity = built.layer.opacity;
+      const lifeA = opacity === void 0 ? lifeAlphaAt(built.layer.life, t) : lifeAlphaAt(built.layer.life, t) * clamp013(opacity);
       if (lifeA <= 0) continue;
       const parentE = this.parentEntityFor(built);
+      const tf = built.layer.transform;
+      if (tf) {
+        ctx.save();
+        this.applyLayerTransform(tf);
+      }
       ctx.globalCompositeOperation = built.layer.blend ?? "source-over";
       this.drawLinks(built, t, lifeA, parentE);
       const override = this.paintOverrides?.get(li) ?? null;
@@ -3235,13 +3744,80 @@ var SpecInstance = class {
           this.drawEntity(built, e, t, lifeA, parentE);
           continue;
         }
-        if (override.k < 1) this.drawEntity(built, e, t, lifeA, parentE, { sprite: override.outgoing, alpha: 1 - override.k });
-        if (override.k > 0) this.drawEntity(built, e, t, lifeA, parentE, { alpha: override.k });
+        const [aOut, aIn] = override.mode === "dip" ? [Math.max(0, 1 - 2 * override.k), Math.max(0, 2 * override.k - 1)] : [1 - override.k, override.k];
+        if (aOut > 0) this.drawEntity(built, e, t, lifeA, parentE, { sprite: override.outgoing, alpha: aOut });
+        if (aIn > 0) this.drawEntity(built, e, t, lifeA, parentE, { alpha: aIn });
       }
+      if (tf) ctx.restore();
     }
     ctx.globalAlpha = 1;
     ctx.globalCompositeOperation = "source-over";
   }
+  /** A layer `transform`, about the viewport centre, in min(w,h) units (px under `units: 'px'`). */
+  applyLayerTransform(tf) {
+    const { ctx, w, h } = this;
+    const unit = this.effSpec.units === "px" ? 1 : Math.min(w, h);
+    const cx = w / 2;
+    const cy = h / 2;
+    ctx.translate(cx + (tf.x ?? 0) * unit, cy + (tf.y ?? 0) * unit);
+    if (tf.rotate) ctx.rotate(tf.rotate * Math.PI / 180);
+    const s = tf.scale ?? 1;
+    ctx.scale(s * (tf.scaleX ?? 1), s);
+    ctx.translate(-cx, -cy);
+  }
+  /** Scene time for a timeline decision: the last painted frame's, else the loop clock's. */
+  sceneNow() {
+    return this.lastRenderT !== Number.NEGATIVE_INFINITY ? this.lastRenderT : this.lastT;
+  }
+  /** Resolve the authored timeline at `t`, layer the live overrides on top, and adopt the result. */
+  resolveAuthored(t) {
+    const expired = [];
+    const spec = applyOverridesAt(resolveTimelineAt(this.authored, t), this.overrides, t, expired);
+    for (const p of expired) this.overrides.delete(p);
+    this.effSpec = spec;
+    const sig = structuralSignature(spec);
+    if (sig !== this.lastStructural) this.rebuild();
+    else this.layers.forEach((b, i) => {
+      b.layer = spec.layers[i] ?? b.layer;
+    });
+  }
+  /** Register live steers on a timeline scene under the steering rule (see `overrides`). */
+  overrideAuthored(deltas, glide) {
+    const now = this.sceneNow();
+    const shown = this.effSpec;
+    const latest = /* @__PURE__ */ new Map();
+    for (const d of deltas) {
+      const path = canonicalSpecPath(shown, d.path);
+      if (!path) continue;
+      latest.delete(path);
+      latest.set(path, d);
+    }
+    const next = new Map(this.overrides);
+    const armed = [];
+    for (const [path, d] of latest) {
+      const id = steerId(d);
+      if (this.seenSteers.get(path) === id) continue;
+      armed.push([path, id]);
+      next.set(path, armOverride(this.authored, path, glide > 0 ? readSpecPath(shown, path) : d.value, d.value, now, glide));
+    }
+    if (armed.length === 0) return true;
+    if (!overridesStayValid(this.authored, next, now)) return false;
+    for (const [p, id] of armed) this.seenSteers.set(p, id);
+    this.overrides = next;
+    return true;
+  }
+  /** A copy of the live overrides — a sequence carries them into a morph's outgoing endpoint. */
+  timelineOverrides() {
+    return this.authored ? new Map(this.overrides) : null;
+  }
+  /** A copy of which server steers this child already applied, per field (see `seenSteers`). */
+  timelineSeen() {
+    return new Map(this.seenSteers);
+  }
+  /** The spec painted by the last frame (timeline and overrides resolved). */
+  presentedSpec() {
+    return this.effSpec;
+  }
   /**
    * Deterministic, frame-addressable render (shared by the rAF loop).
    *
@@ -3294,6 +3870,11 @@ var SpecInstance = class {
    * already knows the signature is unchanged.
    */
   hotSwapSpec(spec) {
+    this.adoptAuthored(spec);
+    if (this.authored) {
+      this.resolveAuthored(this.sceneNow());
+      return;
+    }
     this.effSpec = spec;
     const sig = structuralSignature(this.effSpec);
     if (sig !== this.lastStructural) this.rebuild();
@@ -3301,8 +3882,68 @@ var SpecInstance = class {
       b.layer = this.effSpec.layers[i] ?? b.layer;
     });
   }
+  /**
+   * Track whether `spec` carries a timeline. Live overrides belong to the
+   * scene they were made on: a different spec (a new publish, a sequence's
+   * re-steered segment, a morph frame) drops them, as a plain hot-swap
+   * replaces `effSpec` wholesale; the host re-sends the live track.
+   */
+  adoptAuthored(spec, keepSteers = false) {
+    const next = spec.timeline ? spec : null;
+    if (next !== this.authored && !(keepSteers && next && this.authored)) {
+      this.overrides.clear();
+      this.seenSteers.clear();
+    }
+    this.authored = next;
+  }
+  /**
+   * A sequence's hot swap of a timeline segment: the new scene replaces the
+   * old, but the live steers (and which server steers were already applied)
+   * carry over — a steer the timeline already took back stays taken back —
+   * and only a steer this child has never seen is armed, now. Frame
+   * continuity is kept, so ghosting trails do not restart.
+   */
+  hotSwapKeepingSteers(spec, retained) {
+    if (!spec.timeline) {
+      this.hotSwapSpec(spec);
+      return;
+    }
+    if (!this.authored) {
+      this.hotSwapSpec(spec);
+      this.applyDeltasNow(retained);
+      return;
+    }
+    this.adoptAuthored(spec, true);
+    for (const d of retained) this.overrideAuthored([d], 0);
+    this.resolveAuthored(this.sceneNow());
+  }
+  /** Arm a steer made while a sequence was mid-morph, on the outgoing end's override set, at that end's scene time. */
+  static armInto(authored, overrides, seen, deltas, now) {
+    const at = resolveTimelineAt(authored, now);
+    const latest = /* @__PURE__ */ new Map();
+    for (const d of deltas) {
+      const path = canonicalSpecPath(at, d.path);
+      if (!path) continue;
+      latest.delete(path);
+      latest.set(path, d);
+    }
+    for (const [path, d] of latest) {
+      const id = steerId(d);
+      if (seen.get(path) === id) continue;
+      const trial = new Map(overrides).set(path, armOverride(authored, path, d.value, d.value, now, 0));
+      if (overridesStayValid(authored, trial, now)) {
+        overrides.set(path, trial.get(path));
+        seen.set(path, id);
+      }
+    }
+  }
   /** Paint-only hot-swap: skips structuralSignature (caller guarantees match). */
   hotSwapPaint(spec) {
+    this.adoptAuthored(spec);
+    if (this.authored) {
+      this.resolveAuthored(this.sceneNow());
+      return;
+    }
     this.effSpec = spec;
     this.layers.forEach((b, i) => {
       b.layer = this.effSpec.layers[i] ?? b.layer;
@@ -3378,6 +4019,8 @@ var SequenceInstance = class {
    * window (if any) has passed.
    */
   pendingWrapFade = false;
+  /** The morph in progress: its ends, and the override sets each end resolves with (see `morphEndpoint`). */
+  morphEnds = null;
   /**
    * Every non-`sequence.segment` delta this instance has been handed, last
    * wins per path, merged across `applyTrack` calls. Children are created
@@ -3502,10 +4145,15 @@ var SequenceInstance = class {
     const tr = this.seq.segments[from]?.transition;
     return tr?.type === "morph" ? tr.dur : 0;
   }
-  /** Whether the morph out of `from` cross-fades its text (default `step`: strings switch at k > 0). */
+  /** Whether the morph out of `from` paints its text in two passes — `crossfade` or `dip` (default `step`: strings switch at k > 0). */
   morphTextCrossfades(from) {
     const tr = this.seq.segments[from]?.transition;
-    return tr?.type === "morph" && tr.text === "crossfade";
+    return tr?.type === "morph" && (tr.text === "crossfade" || tr.text === "dip");
+  }
+  /** The morph out of `from`'s two-pass text mode, for `crossfadeOverrides`. */
+  morphTextMode(from) {
+    const tr = this.seq.segments[from]?.transition;
+    return tr?.type === "morph" && tr.text === "dip" ? "dip" : "crossfade";
   }
   /**
    * The paint overrides for one crossfade frame: every text layer whose
@@ -3514,7 +4162,7 @@ var SequenceInstance = class {
    * usual) at `1 − k` under the incoming at `k`. Null when nothing differs,
    * so a crossfade between same-worded twins is a plain morph frame.
    */
-  crossfadeOverrides(specA, specB, lerped, k) {
+  crossfadeOverrides(specA, specB, lerped, k, mode = "crossfade") {
     let map = null;
     for (let i = 0; i < lerped.layers.length; i++) {
       if (!textStringsDiffer(specA, specB, i)) continue;
@@ -3522,7 +4170,7 @@ var SequenceInstance = class {
       const now = lerped.layers[i].sprite;
       const outgoing = from.kind === "text" && now.kind === "text" ? { ...now, strings: from.strings } : from.kind === "textBlock" && now.kind === "textBlock" ? { ...now, text: from.text } : now;
       if (outgoing === now) continue;
-      (map ??= /* @__PURE__ */ new Map()).set(i, { outgoing, k });
+      (map ??= /* @__PURE__ */ new Map()).set(i, mode === "dip" ? { outgoing, k, mode } : { outgoing, k });
     }
     return map;
   }
@@ -3595,6 +4243,46 @@ var SequenceInstance = class {
     this.renderOffscreen(this.fading, outDur + localT, this.childSeed(this.morphChainRoot(from), seed));
     return this.fading;
   }
+  /**
+   * One end of a morph at segment time `t`. A scene without a timeline is its
+   * steered scene, as always. With a timeline, the retained track follows the
+   * same rule a child applies (held until the path's next key, sticky
+   * otherwise): the outgoing end uses its child's live overrides when the
+   * morph began from one, and otherwise — like the incoming end, whose child
+   * does not exist yet — arms the retained steers at segment time 0, as a
+   * freshly mounted child would.
+   */
+  morphEndpoint(index, t, side) {
+    const scene = this.childScene(index);
+    if (!scene.timeline) return this.steeredScene(scene);
+    const ends = this.morphEnds;
+    if (ends && side === "out") ends.outT = t;
+    let ov = side === "out" ? ends?.out ?? null : ends?.in ?? null;
+    if (!ov) {
+      ov = this.armRetained(scene, side === "out" ? ends?.seenOut : void 0);
+      if (ends) {
+        if (side === "out") ends.out = ov;
+        else ends.in = ov;
+      }
+    }
+    return applyOverridesAt(resolveTimelineAt(scene, t), ov, t);
+  }
+  /** The retained steers that resolve (and validate) on a timeline scene, armed at segment time 0. */
+  armRetained(scene, seen) {
+    const out = /* @__PURE__ */ new Map();
+    if (this.retainedDeltas.size === 0) return out;
+    const at0 = resolveTimelineAt(scene, 0);
+    for (const d of this.retainedDeltas.values()) {
+      const path = canonicalSpecPath(at0, d.path);
+      if (!path) continue;
+      const trial = new Map(out).set(path, armOverride(scene, path, d.value, d.value, 0, 0));
+      if (overridesStayValid(scene, trial, 0)) {
+        out.set(path, trial.get(path));
+        seen?.set(path, steerId(d));
+      }
+    }
+    return out;
+  }
   /** A segment's scene with the retained track applied — `scene` itself when nothing resolves on it. */
   steeredScene(scene) {
     return this.retainedDeltas.size === 0 ? scene : applyRetainedDeltas(scene, this.retainedDeltas.values());
@@ -3613,7 +4301,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, capabilityTier: this.capabilityTier, hostPresents: true });
+      child = new SpecInstance(rootScene ?? this.childScene(index), this.childCtx, { transparent: this.bed !== null, skipInitialPaint: skipInitialPaint || this.bed !== null, capabilityTier: this.capabilityTier, hostPresents: true });
       this.children[index] = child;
       child.setPaused(true);
       if (rootScene) child.hotSwapSpec(this.childScene(index));
@@ -3668,7 +4356,12 @@ var SequenceInstance = class {
   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;
+    const scene = this.childScene(this.activeIndex);
+    if (scene.timeline) {
+      const live = (this.fadingIn?.index === this.activeIndex ? this.fadingIn.child : null) ?? this.children[this.activeIndex] ?? this.children[this.morphChainRoot(this.activeIndex)];
+      if (live) return live.presentedSpec().finish;
+    }
+    return this.steeredScene(scene).finish;
   }
   /**
    * The seed `frameFinish()`'s grain resolves against — the sequence's own
@@ -3693,29 +4386,36 @@ var SequenceInstance = class {
     const resolved = resolveSegment(this.seq, T + this.clockOffset, { releasedBelow: this.releasedBelow });
     const { index, localT } = resolved;
     this.bed?.renderFrame(T, this.seq.bed?.seed ?? this.seq.seed ?? seed);
-    const prevIdx = index > 0 ? index - 1 : -1;
-    const morphActive = prevIdx >= 0 && this.canMorph(prevIdx) && localT < this.morphDur(prevIdx);
     const lastIdx = this.seq.segments.length - 1;
     const wrapped = this.seq.loop && index === 0 && lastIdx > 0 && (T + this.clockOffset >= this.timedTotal() || this.pendingWrapFade);
+    const naturalWrap = this.seq.loop && index === 0 && lastIdx > 0 && T + this.clockOffset >= this.timedTotal();
+    const prevIdx = index > 0 ? index - 1 : -1;
+    const morphFrom = prevIdx >= 0 ? prevIdx : naturalWrap && canWrapMorph(this.seq) ? lastIdx : -1;
+    const morphActive = morphFrom >= 0 && (morphFrom === prevIdx ? this.canMorph(prevIdx) : true) && localT < this.morphDur(morphFrom);
     const fadeFrom = prevIdx >= 0 ? prevIdx : wrapped ? lastIdx : -1;
     const fadeActive = fadeFrom >= 0 && localT < this.fadeDur(fadeFrom);
     if (!fadeActive && this.fading) this.releaseFading();
     if (this.pendingWrapFade && (index !== 0 || !fadeActive)) this.pendingWrapFade = false;
     if (morphActive) {
       const chainRoot = this.morphChainRoot(index);
-      this.morphFromIndex = prevIdx;
+      if (this.morphFromIndex !== morphFrom || this.morphEnds?.to !== index) {
+        const outChild = this.children[morphFrom];
+        this.morphEnds = { from: morphFrom, to: index, outT: 0, out: outChild?.timelineOverrides() ?? null, seenOut: outChild?.timelineSeen() ?? /* @__PURE__ */ new Map(), in: null };
+      }
+      this.morphFromIndex = morphFrom;
       this.activeIndex = index;
       for (let i = 0; i < this.children.length; i++) {
         if (i !== chainRoot) this.releaseChild(i);
       }
-      const child = this.ensureChild(chainRoot, void 0, this.morphTextCrossfades(prevIdx));
-      const dur = this.morphDur(prevIdx);
+      const child = this.ensureChild(chainRoot, void 0, this.morphTextCrossfades(morphFrom));
+      const dur = this.morphDur(morphFrom);
       const k = easeSmooth(localT / dur);
-      const specA = this.steeredScene(this.childScene(prevIdx));
-      const specB = this.steeredScene(this.childScene(index));
+      const outDur = this.seq.segments[morphFrom].duration ?? 0;
+      const specA = this.morphEndpoint(morphFrom, outDur + localT, "out");
+      const specB = this.morphEndpoint(index, localT, "in");
       const lerped = lerpSpec(specA, specB, k);
       child.hotSwapSpec(lerped);
-      child.setLayerPaintOverrides(this.morphTextCrossfades(prevIdx) ? this.crossfadeOverrides(specA, specB, lerped, k) : null);
+      child.setLayerPaintOverrides(this.morphTextCrossfades(morphFrom) ? this.crossfadeOverrides(specA, specB, lerped, k, this.morphTextMode(morphFrom)) : null);
       child.renderFrame(localT, this.childSeed(chainRoot, seed));
     } else {
       if (this.morphFromIndex >= 0) {
@@ -3723,6 +4423,7 @@ var SequenceInstance = class {
         this.releaseChild(oldRoot);
         if (oldRoot !== this.morphFromIndex) this.releaseChild(this.morphFromIndex);
         this.morphFromIndex = -1;
+        this.morphEnds = null;
       }
       if (index !== this.activeIndex) {
         for (let i = 0; i < this.children.length; i++) {
@@ -3802,6 +4503,12 @@ var SequenceInstance = class {
     const childDeltas = deltas.filter((d) => d.path !== "sequence.segment");
     if (childDeltas.length > 0) {
       if (this.morphFromIndex >= 0) {
+        const ends = this.morphEnds;
+        if (ends) {
+          const outScene = this.childScene(ends.from);
+          if (ends.out && outScene.timeline) SpecInstance.armInto(outScene, ends.out, ends.seenOut, childDeltas, ends.outT);
+          ends.in = null;
+        }
         if (!switchedSegment) this.renderFrame(this.renderedT, this.seed);
       } else if (this.activeIndex >= 0) {
         const child = this.children[this.activeIndex];
@@ -3831,11 +4538,19 @@ var SequenceInstance = class {
     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)));
+    const swap = (child, index) => {
+      if (!child) return;
+      const scene = this.childScene(index);
+      if (!scene.timeline) {
+        child.hotSwapSpec(this.steeredScene(scene));
+        return;
+      }
+      child.hotSwapKeepingSteers(scene, this.retainedDeltas.values());
+    };
+    for (let i = 0; i < this.children.length; i++) swap(this.children[i], i);
+    if (this.fading) swap(this.fading.child, this.fading.index);
+    if (this.fadingIn) swap(this.fadingIn.child, this.fadingIn.index);
+    this.morphEnds = null;
     if (this.paused) this.renderFrame(this.renderedT, this.seed);
     return true;
   }
@@ -4228,12 +4943,43 @@ function seamsWorthWarning(layer, c, entityCount) {
   return layer.blend !== "lighter" && layer.blend !== "screen";
 }
 
+// src/paint.ts
+function transformPoint(tf, p, w, h, unit) {
+  const s = tf.scale ?? 1;
+  const sx = s * (tf.scaleX ?? 1);
+  let x = (p.x - w / 2) * sx;
+  let y = (p.y - h / 2) * s;
+  if (tf.rotate) {
+    const r = tf.rotate * Math.PI / 180;
+    const c = Math.cos(r);
+    const n = Math.sin(r);
+    [x, y] = [x * c - y * n, x * n + y * c];
+  }
+  return { x: x + w / 2 + (tf.x ?? 0) * unit, y: y + h / 2 + (tf.y ?? 0) * unit };
+}
+function transformSize(tf) {
+  if (!tf) return 1;
+  const s = tf.scale ?? 1;
+  return s * Math.sqrt(Math.abs(tf.scaleX ?? 1));
+}
+var layerOpacity = (layer) => layer.opacity === void 0 ? 1 : Math.max(0, Math.min(1, layer.opacity));
+function transformBox(tf, box, w, h, unit) {
+  const pts = [[box.x0, box.y0], [box.x1, box.y0], [box.x0, box.y1], [box.x1, box.y1]].map(([x, y]) => transformPoint(tf, { x, y }, w, h, unit));
+  return {
+    x0: Math.min(...pts.map((p) => p.x)),
+    y0: Math.min(...pts.map((p) => p.y)),
+    x1: Math.max(...pts.map((p) => p.x)),
+    y1: Math.max(...pts.map((p) => p.y))
+  };
+}
+
 // src/advise.ts
 var LOW_CONTRAST_FLOOR = 0.05;
 var SPARSE_DECLARED_MAX_COVERAGE = 0.02;
 var READ_LEGIBILITY_FLOOR = 4.5;
 var READ_SAFE_AREA = 0.05;
 function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
+  spec = resolveTimelineAt(spec, opts.t ?? COHESION_T);
   const warnings = [];
   const w = viewport.width;
   const h = viewport.height;
@@ -4331,6 +5077,8 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       let pixArea;
       if (layer.sprite.kind === "circle") {
         pixArea = Math.PI * r * r;
+      } else if (layer.sprite.kind === "polygon") {
+        pixArea = polygonArea(polygonPoints(layer.sprite, r));
       } else if (layer.sprite.kind === "bar") {
         pixArea = e.size * barFraction(layer.sprite, e.barIndex ?? 0) * (e.size2 ?? e.size * 0.2);
       } else if (layer.sprite.kind === "textBlock") {
@@ -4457,8 +5205,10 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     const label = layer.key ? `\`${layer.key}\`` : `layers[${li}]`;
     for (const e of allEntities[li]) {
       const p = positionAt(e, 0, w, h);
-      const box = s.kind === "textBlock" ? textBlockBoxAt(s, p, w, h) : textBoxAt(s, e, p, spec, w, h);
-      const alpha = Math.max(0, Math.min(1, e.alpha - e.pulseAmp)) * (s.kind === "textBlock" ? s.opacity ?? 1 : 1);
+      const raw = s.kind === "textBlock" ? textBlockBoxAt(s, p, w, h) : textBoxAt(s, e, p, spec, w, h);
+      const box = layer.transform ? { ...raw, ...transformBox(layer.transform, raw, w, h, scale) } : raw;
+      const baseAlpha = Math.max(0, Math.min(1, e.alpha - e.pulseAmp)) * (s.kind === "textBlock" ? s.opacity ?? 1 : 1);
+      const alpha = layer.opacity === void 0 ? baseAlpha : baseAlpha * layerOpacity(layer);
       textBoxes.push({ li, label, alpha, ...box });
     }
   }
@@ -4587,8 +5337,8 @@ function brightestAdditivePlate(spec, allEntities, ground, box, w, h) {
       const growScale = (e.motion === "warp" ? WARP_MAX_SCALE : 1) * (e.emit ? Math.max(e.emit.growFrom, e.emit.growTo) : 1);
       const maxDim = Math.max(e.size, e.size2 ?? 0) * (1 + e.growAmp) * growScale;
       if (maxDim < box.fs) continue;
-      if (!entityReachesBox(e, maxDim / 2, box, w, h)) continue;
-      const a = Math.min(1, e.alpha + e.pulseAmp);
+      if (!layer.transform && !entityReachesBox(e, maxDim / 2, box, w, h)) continue;
+      const a = layer.opacity === void 0 ? Math.min(1, e.alpha + e.pulseAmp) : Math.min(1, e.alpha + e.pulseAmp) * layerOpacity(layer);
       if (a <= 0) continue;
       const plate = additivePlate(ground, hexRgb(hex), a, blend);
       const lum = relativeLuminance(plate);
@@ -4655,8 +5405,8 @@ function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
     });
   }
   for (let i = 0; i < seq.segments.length - 1; i++) {
-    const lumaA = backgroundLuma(seq.segments[i].scene);
-    const lumaB = backgroundLuma(seq.segments[i + 1].scene);
+    const lumaA = backgroundLuma(resolveTimelineAt(seq.segments[i].scene, seq.segments[i].duration ?? 0));
+    const lumaB = backgroundLuma(resolveTimelineAt(seq.segments[i + 1].scene, 0));
     const delta = Math.abs(lumaA - lumaB);
     if (delta > 0.5) {
       warnings.push({
@@ -4675,7 +5425,7 @@ function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
           code: "morph-structural-mismatch",
           message: `segments ${i}\u2192${i + 1} differ structurally: morph will fall back to cut`
         });
-      } else if (morphNothingMorphable(seq.segments[i].scene, seq.segments[i + 1].scene, { textCrossfade: tr.text === "crossfade" })) {
+      } else if (!seq.segments[i].scene.timeline && !seq.segments[i + 1].scene.timeline && morphNothingMorphable(seq.segments[i].scene, seq.segments[i + 1].scene, { textCrossfade: tr.text === "crossfade" || tr.text === "dip" })) {
         warnings.push({
           path: `segments[${i}].transition`,
           code: "morph-nothing-morphable",
@@ -4709,7 +5459,7 @@ function describeScene(spec, options = {}) {
       let pixArea = 0;
       for (const e of entities) {
         const r = e.size / 2;
-        pixArea += layer.sprite.kind === "circle" ? Math.PI * r * r : e.size * e.size;
+        pixArea += layer.sprite.kind === "circle" ? Math.PI * r * r : layer.sprite.kind === "polygon" ? polygonArea(polygonPoints(layer.sprite, r)) : e.size * e.size;
       }
       const coverage = pixArea / (w * h);
       const meanAlpha = entities.length > 0 ? entities.reduce((s, e) => s + e.alpha, 0) / entities.length : 0;
@@ -4785,6 +5535,8 @@ import { createRng as createRng4 } from "@idle-screens/core";
 var GLOW_SPREAD = 2.4;
 var LINE_SALIENCE = 3.5;
 var GHOST_TAPS = 12;
+var POLYGON_OUTLINE_CELLS = 3;
+var POLYGON_SCANLINES = 4;
 function buildScene(spec, opts) {
   const { width: w, height: h } = opts.viewport ?? { width: 1920, height: 1080 };
   const seed = normalizeSeed(opts.seed ?? spec.seed ?? 42);
@@ -4799,7 +5551,13 @@ function buildScene(spec, opts) {
   const layers = spec.layers.map((layer) => ({ layer, entities: buildEntities(layer, rng, w, h, scale, countScale) }));
   const byKey = /* @__PURE__ */ new Map();
   for (const { layer, entities } of layers) if (layer.key) byKey.set(layer.key, entities);
-  return { w, h, scale, seed, layers, byKey };
+  let transforms = null;
+  for (const { layer, entities } of layers) {
+    if (!layer.transform) continue;
+    transforms ??= /* @__PURE__ */ new Map();
+    for (const e of entities) transforms.set(e, layer.transform);
+  }
+  return { w, h, scale, seed, layers, byKey, transforms };
 }
 function posOf(scene, e, t) {
   const p = positionAt(e, t, scene.w, scene.h);
@@ -4811,7 +5569,8 @@ function posOf(scene, e, t) {
       p.y += pp.y;
     }
   }
-  return p;
+  const tf = scene.transforms?.get(e);
+  return tf ? transformPoint(tf, p, scene.w, scene.h, scene.scale) : p;
 }
 function textBox(s, e, p) {
   const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
@@ -4863,7 +5622,66 @@ function textBlockRevealFraction(s, w, h, t) {
   }
   return rs.progress;
 }
+function polygonCellCoverage(pts, cellW, cellH, c0, c1, r0, r1) {
+  const nc = c1 - c0 + 1;
+  const cov = new Float64Array(nc * (r1 - r0 + 1));
+  const xMin = c0 * cellW;
+  const xMax = (c1 + 1) * cellW;
+  const share = 1 / POLYGON_SCANLINES;
+  const hits = [];
+  const addSpan = (row, xa, xb) => {
+    const a = Math.max(xMin, xa);
+    const b = Math.min(xMax, xb);
+    if (!(b > a)) return;
+    const first = Math.max(c0, Math.floor(a / cellW));
+    const last = Math.min(c1, Math.floor(b / cellW));
+    for (let c = first; c <= last; c++) {
+      const len = Math.min(b, (c + 1) * cellW) - Math.max(a, c * cellW);
+      if (len > 0) cov[row * nc + (c - c0)] += len / cellW * share;
+    }
+  };
+  for (let r = r0; r <= r1; r++) {
+    for (let k = 0; k < POLYGON_SCANLINES; k++) {
+      const y = (r + (k + 0.5) / POLYGON_SCANLINES) * cellH;
+      hits.length = 0;
+      for (let i = 0; i < pts.length; i++) {
+        const p = pts[i];
+        const q = pts[(i + 1) % pts.length];
+        const down = p.y <= y && q.y > y;
+        if (!down && !(q.y <= y && p.y > y)) continue;
+        hits.push({ x: p.x + (y - p.y) / (q.y - p.y) * (q.x - p.x), dir: down ? 1 : -1 });
+      }
+      if (hits.length < 2) continue;
+      hits.sort((m, n) => m.x - n.x);
+      let wind = 0;
+      let start = 0;
+      for (const hit of hits) {
+        const before = wind;
+        wind += hit.dir;
+        if (before === 0 && wind !== 0) start = hit.x;
+        else if (before !== 0 && wind === 0) addSpan(r - r0, start, hit.x);
+      }
+    }
+  }
+  return cov;
+}
+function distanceToOutline(pts, x, y) {
+  let best = Infinity;
+  for (let i = 0; i < pts.length; i++) {
+    const p = pts[i];
+    const q = pts[(i + 1) % pts.length];
+    const ex = q.x - p.x;
+    const ey = q.y - p.y;
+    const len2 = ex * ex + ey * ey;
+    const u = len2 > 0 ? Math.max(0, Math.min(1, ((x - p.x) * ex + (y - p.y) * ey) / len2)) : 0;
+    const dx = x - (p.x + ex * u);
+    const dy = y - (p.y + ey * u);
+    best = Math.min(best, dx * dx + dy * dy);
+  }
+  return Math.sqrt(best);
+}
 function luminanceGrid(spec, opts = {}) {
+  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
   const cols = Math.max(8, Math.min(200, opts.cols ?? 80));
@@ -4962,9 +5780,66 @@ function luminanceGrid(spec, opts = {}) {
       }
     }
   };
+  const splatPolygonOutline = (layer, s, e, p, sz, a, lum, tPass) => {
+    const radius = sz / 2;
+    const rot = rotationAt(e, tPass);
+    const cr = Math.cos(rot);
+    const sr = Math.sin(rot);
+    const pts = polygonPoints(s, radius).map((q) => ({ x: p.x + q.x * cr - q.y * sr, y: p.y + q.x * sr + q.y * cr }));
+    const additive = layer.blend === "lighter" || layer.blend === "screen";
+    const glow = !!s.soft && additive;
+    let band = 0;
+    if (glow) {
+      const perimeter = pts.reduce((acc, q, i) => {
+        const n = pts[(i + 1) % pts.length];
+        return acc + Math.hypot(n.x - q.x, n.y - q.y);
+      }, 0);
+      band = perimeter > 0 ? (GLOW_SPREAD - 1) * (2 * polygonArea(pts) / perimeter) : 0;
+    }
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minY = Infinity;
+    let maxY = -Infinity;
+    for (const q of pts) {
+      minX = Math.min(minX, q.x);
+      maxX = Math.max(maxX, q.x);
+      minY = Math.min(minY, q.y);
+      maxY = Math.max(maxY, q.y);
+    }
+    const c0 = Math.max(0, Math.floor((minX - band) / cellW));
+    const c1 = Math.min(cols - 1, Math.floor((maxX + band) / cellW));
+    const r0 = Math.max(0, Math.floor((minY - band) / cellH));
+    const r1 = Math.min(rows - 1, Math.floor((maxY + band) / cellH));
+    if (c0 > c1 || r0 > r1) return;
+    const cov = polygonCellCoverage(pts, cellW, cellH, c0, c1, r0, r1);
+    const nc = c1 - c0 + 1;
+    for (let r = r0; r <= r1; r++) {
+      for (let c = c0; c <= c1; c++) {
+        const f = cov[(r - r0) * nc + (c - c0)];
+        const x = (c + 0.5) * cellW;
+        const y = (r + 0.5) * cellH;
+        let wgt;
+        if (glow) {
+          const outX = Math.max(0, minX - x, x - maxX);
+          const outY = Math.max(0, minY - y, y - maxY);
+          if (f >= 1) wgt = 1;
+          else if (outX * outX + outY * outY >= band * band) wgt = f;
+          else {
+            const k = band > 0 ? Math.max(0, 1 - distanceToOutline(pts, x, y) / band) : 0;
+            wgt = f + (1 - f) * k * k;
+          }
+        } else if (s.soft) {
+          wgt = f * Math.max(0.1, 1 - Math.hypot(x - p.x, y - p.y) / Math.max(radius, 1e-6));
+        } else {
+          wgt = f;
+        }
+        if (wgt > 0) compose(r * cols + c, lum, a * Math.min(1, wgt), layer.blend);
+      }
+    }
+  };
   const splatPass = (tPass, alphaScale) => {
     for (const { layer, entities } of scene.layers) {
-      const lifeA = lifeAlphaAt(layer.life, tPass);
+      const lifeA = layer.opacity === void 0 ? lifeAlphaAt(layer.life, tPass) : lifeAlphaAt(layer.life, tPass) * layerOpacity(layer);
       if (lifeA <= 0) continue;
       for (const e of entities) {
         splatTrail(layer, e, tPass, lifeA, alphaScale);
@@ -4972,8 +5847,12 @@ function luminanceGrid(spec, opts = {}) {
         if (a <= 4e-3) continue;
         const lum = spriteLuma(layer, e);
         const p = posOf(scene, e, tPass);
-        const sz = sizeAt(e, tPass);
+        const sz = layer.transform ? sizeAt(e, tPass) * transformSize(layer.transform) : sizeAt(e, tPass);
         const s = layer.sprite;
+        if (s.kind === "polygon" && sz >= POLYGON_OUTLINE_CELLS * Math.min(cellW, cellH)) {
+          splatPolygonOutline(layer, s, e, p, sz, a, lum, tPass);
+          continue;
+        }
         if (s.kind === "stroke") {
           const pts = strokeSamples(s, sz / 2);
           let angle = rotationAt(e, tPass);
@@ -5219,6 +6098,7 @@ function renderDensityMap(grid) {
   return lines.join("\n");
 }
 function textSprites(spec, opts = {}) {
+  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
   const out = [];
@@ -5256,6 +6136,7 @@ function rankDominance(raw) {
   }));
 }
 function rawDominance(spec, opts = {}) {
+  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
   const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
   const { w, h, scale } = scene;
@@ -5280,7 +6161,8 @@ function rawDominance(spec, opts = {}) {
     return Math.sqrt(dx * dx + dy * dy);
   };
   const raw = scene.layers.map(({ layer, entities }, layerIndex) => {
-    const lifeA = lifeAlphaAt(layer.life, t);
+    const lifeA = layer.opacity === void 0 ? lifeAlphaAt(layer.life, t) : lifeAlphaAt(layer.life, t) * layerOpacity(layer);
+    const areaScale = layer.transform ? transformSize(layer.transform) ** 2 : 1;
     let area = 0;
     let lumAcc = 0;
     for (const e of entities) {
@@ -5309,7 +6191,7 @@ function rawDominance(spec, opts = {}) {
         const box = textBlockBox(s, e, { x: 0, y: 0 }, w, h);
         entArea = box.halfX * 2 * box.halfY * 2 * 0.55 * textBlockRevealFraction(s, w, h, t) * (s.opacity ?? 1);
       } else entArea = sz * sz * 0.55;
-      area += entArea * a;
+      area += layer.transform ? entArea * areaScale * a : entArea * a;
       if (layer.trail) {
         const fade = layer.trail.fade ?? 1;
         const span = sweptDistance(e, layer.trail.length);
@@ -5339,29 +6221,32 @@ function rawDominance(spec, opts = {}) {
   return raw;
 }
 function layerCohesion(spec, opts = {}) {
+  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
   const scene = buildScene(spec, opts);
   return cohesionOf(scene.layers, opts.t ?? 5e3, scene.w, scene.h);
 }
 function motionStats(spec, opts = {}) {
-  const scene = buildScene(spec, opts);
   const t = opts.t ?? 5e3;
   const dt = opts.dt ?? 500;
-  const { w, h } = scene;
-  return scene.layers.map(({ layer, entities }, layerIndex) => {
+  const scene0 = buildScene(resolveTimelineAt(spec, t), opts);
+  const scene1 = spec.timeline ? buildScene(resolveTimelineAt(spec, t + dt), opts) : scene0;
+  const { w, h } = scene0;
+  return scene0.layers.map(({ layer, entities }, layerIndex) => {
+    const entities1 = scene1.layers[layerIndex]?.entities ?? entities;
     let acc = 0;
     let max = 0;
     let n = 0;
-    for (const e of entities) {
-      const p0 = posOf(scene, e, t);
-      const p1 = posOf(scene, e, t + dt);
+    entities.forEach((e, i) => {
+      const p0 = posOf(scene0, e, t);
+      const p1 = posOf(scene1, entities1[i] ?? e, t + dt);
       const dx = p1.x - p0.x;
       const dy = p1.y - p0.y;
-      if (Math.abs(dx) > w / 2 || Math.abs(dy) > h / 2) continue;
+      if (Math.abs(dx) > w / 2 || Math.abs(dy) > h / 2) return;
       const speed = Math.sqrt(dx * dx + dy * dy) / dt * 1e3;
       acc += speed;
       max = Math.max(max, speed);
       n++;
-    }
+    });
     const meanSpeed = n ? acc / n : 0;
     return { layerIndex, key: layer.key, meanSpeed, maxSpeed: max, moving: meanSpeed > 0.5 };
   });
@@ -5427,6 +6312,7 @@ function diffScenes(a, b, opts = {}) {
   };
 }
 function perceiveScene(spec, opts = {}) {
+  spec = resolveTimelineAt(spec, opts.t ?? 5e3);
   const grid = luminanceGrid(spec, opts);
   return {
     t: opts.t ?? 5e3,
@@ -7922,6 +8808,7 @@ export {
   COMETS_SPEC,
   CONSTELLATION_SPEC,
   DASHBOARD_SPEC,
+  DEFAULT_KEY_DUR,
   DITHER_ALPHA,
   DITHER_TILE,
   EXAMPLE_BY_ID,
@@ -7975,6 +8862,8 @@ export {
   breakTextBlock,
   buildEntities,
   canMorph,
+  canWrapMorph,
+  canonicalSpecPath,
   cohesionOf,
   compileSaver,
   compileSequence,
@@ -8002,6 +8891,7 @@ export {
   latticeHash,
   layerCohesion,
   lerpSpec,
+  lerpValue,
   lifeAlphaAt,
   linkEdges,
   linkPairs,
@@ -8010,16 +8900,19 @@ export {
   morphChainRoot,
   morphNothingMorphable,
   motionStats,
+  nextKeyAfter,
   normalizeSeed,
   perceiveScene,
   perceiveSequenceFrame,
   pickScreenOp,
   positionAt,
   presentWithFinish,
+  readSpecPath,
   renderBrailleMap,
   renderDensityMap,
   resolveSegment,
   resolveSpecPath,
+  resolveTimelineAt,
   revealState,
   rgb255Luma,
   rotationAt,
@@ -8041,7 +8934,13 @@ export {
   textStringsDiffer,
   textStringsOf,
   textWidthEm,
+  timelineLocalTime,
+  timelineSampleTimes,
+  timelineSampleTimesAfter,
+  timelineTracks,
   validateSequence,
-  validateSpec
+  validateSpec,
+  validateSpecPaths,
+  withoutTimeline
 };
 //# sourceMappingURL=index.js.map