@idle-screens/schema 3.10.0 → 3.11.1

package/dist/index.js

@@ -85,6 +85,7 @@ var LIMITS = {
   maxLayerTransformScale: 8,
   maxLayerTransformRotate: 3600,
   // degrees
+  maxGroups: 16,
   maxEmitEvery: 6e5,
   // ms — ten minutes; longer silences than that are `life.enter`
   minEmitLife: 500,
@@ -110,7 +111,7 @@ var LIMITS = {
 
 // src/steer.ts
 var UNSAFE_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
-var STEERABLE_ROOT_KEYS = /* @__PURE__ */ new Set(["ghosting", "referenceViewport", "finish"]);
+var STEERABLE_ROOT_KEYS = /* @__PURE__ */ new Set(["ghosting", "referenceViewport", "finish", "groups"]);
 function resolveSpecPath(spec, path) {
   if (!spec || typeof spec !== "object" || !path) return null;
   const parts = path.split(".");
@@ -124,6 +125,8 @@ function resolveSpecPath(spec, path) {
       return null;
     }
   }
+  if (parts[0] === "layers" && parts.length === 3 && parts[2] === "group") return null;
+  if (parts.length >= 2 && parts[parts.length - 1] === "origin" && parts[parts.length - 2] === "transform") return null;
   let node = spec;
   for (let i = 0; i < parts.length - 1; i++) {
     if (node === null || typeof node !== "object") return null;
@@ -176,6 +179,10 @@ function alignPaintFields(a, b) {
     if (!x || !y || typeof x !== "object" || typeof y !== "object") continue;
     let nx = x;
     let ny = y;
+    if (x.group === void 0 !== (y.group === void 0)) {
+      if (x.group === void 0) nx = { ...nx, group: y.group };
+      else ny = { ...ny, group: x.group };
+    }
     if (x.opacity === void 0 !== (y.opacity === void 0)) {
       if (x.opacity === void 0) nx = { ...nx, opacity: 1 };
       else ny = { ...ny, opacity: 1 };
@@ -206,7 +213,39 @@ function alignPaintFields(a, b) {
     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];
+  let ra = outA ? { ...a, layers: outA } : a;
+  let rb = outB ? { ...b, layers: outB } : b;
+  const ga = a.groups;
+  const gb = b.groups;
+  if (ga || gb) {
+    const na = { ...ga ?? {} };
+    const nb = { ...gb ?? {} };
+    let changed = !ga || !gb;
+    for (const name of /* @__PURE__ */ new Set([...Object.keys(na), ...Object.keys(nb)])) {
+      const x = na[name] ?? {};
+      const y = nb[name] ?? {};
+      if (!na[name] || !nb[name]) changed = true;
+      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 };
+        changed = true;
+      }
+      if (!x.transform !== !y.transform) {
+        if (!x.transform) nx = { ...nx, transform: {} };
+        else ny = { ...ny, transform: {} };
+        changed = true;
+      }
+      na[name] = nx;
+      nb[name] = ny;
+    }
+    if (changed) {
+      ra = { ...ra, groups: na };
+      rb = { ...rb, groups: nb };
+    }
+  }
+  return [ra, rb];
 }
 function applyDeltasToSpec(spec, deltas) {
   const copy = JSON.parse(JSON.stringify(spec));
@@ -315,7 +354,8 @@ 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 SKIP = /* @__PURE__ */ new Set(["kind", "type", "key", "schemaVersion", "id", "label", "seed", "units", "motionIntensity", "mode", "curve", "layer", "group", "origin"]);
+  const SKIP_ROOT = /* @__PURE__ */ new Set(["timeline"]);
   const INDEXED = /* @__PURE__ */ new Set(["layers", "stops", "bands"]);
   const layers = spec.layers;
   const shadowedRootKeys = new Set(
@@ -333,8 +373,8 @@ 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;
+        if (SKIP.has(k) && prefix !== "groups") continue;
+        if (!prefix && (shadowedRootKeys.has(k) || SKIP_ROOT.has(k))) continue;
         walk(v, prefix ? `${prefix}.${k}` : k, k);
       }
       return;
@@ -634,7 +674,7 @@ 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", "timeline"]);
+var KNOWN_TOP = /* @__PURE__ */ new Set(["schemaVersion", "id", "label", "seed", "motionIntensity", "density", "units", "referenceViewport", "background", "layers", "ghosting", "finish", "timeline", "groups"]);
 var KNOWN_FINISH = /* @__PURE__ */ new Set(["grain", "dither", "animate"]);
 var KNOWN_LAYER = /* @__PURE__ */ new Set([
   "count",
@@ -659,9 +699,12 @@ var KNOWN_LAYER = /* @__PURE__ */ new Set([
   "clock",
   "rotate",
   "opacity",
-  "transform"
+  "transform",
+  "group"
 ]);
-var KNOWN_TRANSFORM = /* @__PURE__ */ new Set(["x", "y", "scale", "scaleX", "rotate"]);
+var KNOWN_TRANSFORM = /* @__PURE__ */ new Set(["x", "y", "scale", "scaleX", "rotate", "origin"]);
+var KNOWN_GROUP = /* @__PURE__ */ new Set(["transform", "opacity"]);
+var GROUP_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
 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"]);
@@ -733,12 +776,15 @@ function validateSpecPaths(spec, paths) {
   const layers = /* @__PURE__ */ new Set();
   let background = false;
   let finish = false;
+  let groups = false;
   for (const p of paths) {
     if (/^layers\.\d+(\.(key|count|motion)(\.|$)|$)/.test(p)) return validateSpec(spec).valid;
+    if (p === "groups") 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 if (head === "groups") groups = true;
     else return validateSpec(spec).valid;
   }
   let ok = true;
@@ -755,6 +801,7 @@ function validateSpecPaths(spec, paths) {
   }
   if (background && spec.background !== void 0) validateBackground(spec.background, err, warn);
   if (finish && spec.finish !== void 0) validateFinish(spec.finish, "finish", err, warn);
+  if (groups && spec.groups !== void 0) validateGroups(spec.groups, err, warn, spec);
   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;
@@ -801,6 +848,7 @@ function validateSpecCore(spec) {
   }
   if (spec.background !== void 0) validateBackground(spec.background, err, warn);
   if (spec.finish !== void 0) validateFinish(spec.finish, "finish", err, warn);
+  if (spec.groups !== void 0) validateGroups(spec.groups, err, warn, spec);
   if (!Array.isArray(spec.layers) || spec.layers.length === 0) {
     err("layers", "must be a non-empty array");
   } else {
@@ -815,6 +863,41 @@ function validateSpecCore(spec) {
   if (spec.timeline !== void 0 && errors.length === 0) validateTimeline(spec, err, warn);
   return { valid: errors.length === 0, errors, warnings };
 }
+function validateTransform(tf, path, err, warn, spec, anchorOk) {
+  if (!isObj(tf)) return err(path, "must be an object {x?, y?, scale?, scaleX?, rotate?, origin?}");
+  for (const k of unknownKeys(tf, KNOWN_TRANSFORM)) warn(`${path}.${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}.${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}.scale`, `must be a number 0..${sc}`);
+  if (tf.scaleX !== void 0 && (!isNum(tf.scaleX) || Math.abs(tf.scaleX) > sc)) err(`${path}.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}.rotate`, `must be a number of degrees within \xB1${LIMITS.maxLayerTransformRotate}`);
+  }
+  if (tf.origin !== void 0) {
+    if (tf.origin !== "viewport" && tf.origin !== "anchor") err(`${path}.origin`, "must be 'viewport' | 'anchor'");
+    else if (tf.origin === "anchor" && !anchorOk) err(`${path}.origin`, "a group transform always turns about the viewport centre \u2014 'anchor' is for a layer's own transform");
+  }
+}
+function validateGroups(groups, err, warn, spec) {
+  if (!isObj(groups)) return err("groups", "must be an object of named groups {name: {transform?, opacity?}}");
+  const names = Object.keys(groups);
+  if (names.length > LIMITS.maxGroups) err("groups", `at most ${LIMITS.maxGroups} groups`);
+  for (const name of names) {
+    const p = `groups.${name}`;
+    if (!GROUP_NAME.test(name)) err(p, "group names are 1\u201332 letters, digits, - or _, starting with a letter");
+    const g = groups[name];
+    if (!isObj(g)) {
+      err(p, "must be an object {transform?, opacity?}");
+      continue;
+    }
+    for (const k of unknownKeys(g, KNOWN_GROUP)) warn(`${p}.${k}`, "unknown-property", `unknown group property '${k}' \u2014 will be ignored`);
+    if (g.opacity !== void 0 && (!isNum(g.opacity) || g.opacity < 0 || g.opacity > 1)) err(`${p}.opacity`, "must be a number 0..1");
+    if (g.transform !== void 0) validateTransform(g.transform, `${p}.transform`, err, warn, spec, false);
+  }
+}
 function validateTimeline(spec, errOuter, warn) {
   let failed = false;
   const err = (p, m) => {
@@ -856,10 +939,13 @@ function validateTimeline(spec, errOuter, warn) {
     if (!isStr(key.path) || key.path.trim() === "") {
       err(`${p}.path`, "must be a non-empty dot-path");
       ok = false;
+    } else if (/\.group$/.test(key.path) || /\.transform\.origin$/.test(key.path)) {
+      err(`${p}.path`, `'${key.path}' is an enum that can only step \u2014 group membership and a transform's origin are fixed per scene`);
+      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") {
+    } else if (cp === "timeline" || cp.startsWith("timeline.") || cp === "schemaVersion" || cp === "id" || cp === "label" || cp === "seed") {
       err(`${p}.path`, `'${key.path}' is not animatable`);
       ok = false;
     }
@@ -872,6 +958,12 @@ function validateTimeline(spec, errOuter, warn) {
       for (const e of r.errors) err(`${p}.value`, `applied at '${key.path}' \u2192 ${e.path || "<root>"}: ${e.message}`);
       return;
     }
+    if (isObj(key.value) && cp.endsWith("transform")) {
+      const before = readSpecPath(base, cp);
+      const o0 = isObj(before) ? before.origin ?? "viewport" : "viewport";
+      const o1 = key.value.origin ?? "viewport";
+      if (o0 !== o1) warn(`${p}.value`, "timeline-origin-steps", `this key changes the transform's origin (${String(o0)} \u2192 ${String(o1)}): the pivot switches on the key's first frame, so the layer jumps \u2014 keep one origin per layer`);
+    }
     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`);
     }
@@ -1039,22 +1131,11 @@ function validateLayer(layer, path, err, warn, spec) {
   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.transform !== void 0) validateTransform(layer.transform, `${path}.transform`, err, warn, spec, true);
+  if (layer.group !== void 0) {
+    const groups = isObj(spec) && isObj(spec.groups) ? spec.groups : void 0;
+    if (!isStr(layer.group)) err(`${path}.group`, "must be the name of a `groups` entry");
+    else if (!groups || !Object.prototype.hasOwnProperty.call(groups, layer.group) || !isObj(groups[layer.group])) err(`${path}.group`, `'${layer.group}' is not in \`groups\` \u2014 declare it there first`);
   }
   if (layer.position !== void 0) {
     if (!isObj(layer.position) || !isNum(layer.position.x) || !isNum(layer.position.y)) {
@@ -2688,6 +2769,67 @@ import {
   createRng
 } from "@idle-screens/core";
 
+// src/paint.ts
+function layerAnchor(layer, w, h, unit) {
+  const p = layer.position;
+  if (p) return { x: p.x * w + (p.dx ?? 0) * unit, y: p.y * h + (p.dy ?? 0) * unit };
+  const rx = layer.region?.x ?? [0, 1];
+  const ry = layer.region?.y ?? [0, 1];
+  return { x: (rx[0] + rx[1]) / 2 * w, y: (ry[0] + ry[1]) / 2 * h };
+}
+function transformOrigin(tf, layer, w, h, unit) {
+  return tf.origin === "anchor" && layer ? layerAnchor(layer, w, h, unit) : { x: w / 2, y: h / 2 };
+}
+function transformPoint(tf, p, w, h, unit, origin = { x: w / 2, y: h / 2 }) {
+  const s = tf.scale ?? 1;
+  const sx = s * (tf.scaleX ?? 1);
+  let x = (p.x - origin.x) * sx;
+  let y = (p.y - origin.y) * 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 + origin.x + (tf.x ?? 0) * unit, y: y + origin.y + (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));
+}
+function groupOf(spec, layer) {
+  return layer.group === void 0 ? void 0 : spec.groups?.[layer.group];
+}
+var clamp01 = (v) => v <= 0 ? 0 : v >= 1 ? 1 : v;
+function paintOpacity(spec, layer) {
+  const own = layer.opacity === void 0 ? 1 : clamp01(layer.opacity);
+  const g = groupOf(spec, layer);
+  return g?.opacity === void 0 ? own : own * clamp01(g.opacity);
+}
+function paintSize(spec, layer) {
+  return transformSize(layer.transform) * transformSize(groupOf(spec, layer)?.transform);
+}
+function paintMap(spec, layer, w, h, unit) {
+  const tf = layer.transform;
+  const gtf = groupOf(spec, layer)?.transform;
+  if (!tf && !gtf) return null;
+  const o = tf ? transformOrigin(tf, layer, w, h, unit) : null;
+  return (p) => {
+    const q = tf ? transformPoint(tf, p, w, h, unit, o) : p;
+    return gtf ? transformPoint(gtf, q, w, h, unit) : q;
+  };
+}
+function mapBox(map, box) {
+  const pts = [[box.x0, box.y0], [box.x1, box.y0], [box.x0, box.y1], [box.x1, box.y1]].map(([x, y]) => map({ x, y }));
+  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/field.ts
 var TWO_PI = Math.PI * 2;
 var FIELD_BUCKET_MS = 100;
@@ -2697,7 +2839,7 @@ 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;
+var clamp012 = (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);
@@ -2760,7 +2902,7 @@ function fieldAt(u, v, t, cfg, seed) {
     y += warp * WARP_GAIN * qy;
   }
   const raw = fbm(x, y, s, octaves);
-  return clamp01(0.5 + (raw - 0.5) * CONTRAST[octaves]);
+  return clamp012(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;
@@ -2776,10 +2918,10 @@ function fieldRgb(value, bands, quantize) {
   const q = Math.round(quantize ?? n);
   let f;
   if (q >= 2) {
-    const level = Math.min(q - 1, Math.floor(clamp01(value) * q));
+    const level = Math.min(q - 1, Math.floor(clamp012(value) * q));
     f = level * (n - 1) / (q - 1);
   } else {
-    f = clamp01(value) * (n - 1);
+    f = clamp012(value) * (n - 1);
   }
   const i = Math.min(n - 2, Math.floor(f));
   const k = f - i;
@@ -2802,9 +2944,9 @@ 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;
+var clamp013 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
 function finishStrength(f) {
-  return { grain: clamp012(f?.grain ?? 0), dither: clamp012(f?.dither ?? 0) };
+  return { grain: clamp013(f?.grain ?? 0), dither: clamp013(f?.dither ?? 0) };
 }
 function grainTilePixels(seed) {
   const px = new Uint8ClampedArray(GRAIN_TILE * GRAIN_TILE * 4);
@@ -2983,10 +3125,10 @@ function manifestFor(spec) {
     workerReady: true
   };
 }
-var clamp013 = (v) => v <= 0 ? 0 : v >= 1 ? 1 : v;
+var clamp014 = (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;
+  const k = o.dur > 0 ? easeSmooth(clamp014((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) {
@@ -3015,10 +3157,10 @@ function applyOverridesAt(resolved, overrides, t, expired) {
 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 groupOf2 = (p) => p.split(".").slice(0, p.startsWith("layers.") ? 2 : 1).join(".");
+  const groups = [...new Set(paths.map(groupOf2))];
+  const full = paths.some((p) => /^layers\.\d+(\.(key|count|motion)(\.|$)|$)/.test(p) || p === "groups" || !/^(layers|background|finish|groups)(\.|$)/.test(p));
+  const only = full ? void 0 : (p) => groups.includes(groupOf2(p));
   const seen = /* @__PURE__ */ new Set();
   for (const t of [now, ...timelineSampleTimesAfter(authored, now, false, only)]) {
     const held = /* @__PURE__ */ new Map();
@@ -3727,13 +3869,17 @@ var SpecInstance = class {
     for (let li = 0; li < this.layers.length; li++) {
       const built = this.layers[li];
       const opacity = built.layer.opacity;
-      const lifeA = opacity === void 0 ? lifeAlphaAt(built.layer.life, t) : lifeAlphaAt(built.layer.life, t) * clamp013(opacity);
+      const group = built.layer.group === void 0 ? void 0 : this.effSpec.groups?.[built.layer.group];
+      let lifeA = opacity === void 0 ? lifeAlphaAt(built.layer.life, t) : lifeAlphaAt(built.layer.life, t) * clamp014(opacity);
+      if (group?.opacity !== void 0) lifeA *= clamp014(group.opacity);
       if (lifeA <= 0) continue;
       const parentE = this.parentEntityFor(built);
       const tf = built.layer.transform;
-      if (tf) {
+      const gtf = group?.transform;
+      if (tf || gtf) {
         ctx.save();
-        this.applyLayerTransform(tf);
+        if (gtf) this.applyLayerTransform(gtf, null);
+        if (tf) this.applyLayerTransform(tf, built.layer);
       }
       ctx.globalCompositeOperation = built.layer.blend ?? "source-over";
       this.drawLinks(built, t, lifeA, parentE);
@@ -3748,17 +3894,20 @@ var SpecInstance = class {
         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();
+      if (tf || gtf) 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) {
+  /**
+   * A `transform`, in min(w,h) units (px under `units: 'px'`), about the
+   * viewport centre — or, with `origin: 'anchor'`, about `layer`'s own anchor
+   * (a group's transform passes no layer: always the viewport centre).
+   */
+  applyLayerTransform(tf, layer) {
     const { ctx, w, h } = this;
     const unit = this.effSpec.units === "px" ? 1 : Math.min(w, h);
-    const cx = w / 2;
-    const cy = h / 2;
+    const { x: cx, y: cy } = transformOrigin(tf, layer, w, h, unit);
     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;
@@ -4943,42 +5092,13 @@ 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 = {}) {
+  const hidden = hiddenLayers(spec);
   spec = resolveTimelineAt(spec, opts.t ?? COHESION_T);
   const warnings = [];
   const w = viewport.width;
@@ -5004,6 +5124,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
   let textLayerCount = 0;
   let motionLayerCount = 0;
   for (let li = 0; li < spec.layers.length; li++) {
+    if (hidden?.[li]) continue;
     const layer = spec.layers[li];
     const entities = allEntities[li];
     totalEntities += entities.length;
@@ -5070,8 +5191,10 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
   }
   let totalCoverage = 0;
   for (let li = 0; li < spec.layers.length; li++) {
+    if (hidden?.[li]) continue;
     const layer = spec.layers[li];
     const entities = allEntities[li];
+    const paintA = layer.opacity === void 0 && layer.group === void 0 ? 1 : paintOpacity(spec, layer);
     for (const e of entities) {
       const r = e.size / 2;
       let pixArea;
@@ -5096,7 +5219,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
         const g2 = (ga * ga + ga * gb + gb * gb) / 3;
         duty = Math.min(layer.emit.life, layer.emit.every) / layer.emit.every * 0.5 * g2;
       }
-      totalCoverage += pixArea * e.alpha * duty / (w * h);
+      totalCoverage += paintA === 1 ? pixArea * e.alpha * duty / (w * h) : pixArea * e.alpha * duty * paintA / (w * h);
     }
     if (layer.links) {
       const positions = entities.map((e) => positionAt(e, 0, w, h));
@@ -5105,7 +5228,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       const defaultWidth = scale === 1 ? 1 : 1 / LIMITS.referenceViewport;
       const lwPx = (layer.links.width ?? defaultWidth) * scale;
       const la = layer.links.alpha ?? 1;
-      for (const edge of edges) totalCoverage += edge.dist * lwPx * la / (w * h);
+      for (const edge of edges) totalCoverage += paintA === 1 ? edge.dist * lwPx * la / (w * h) : edge.dist * lwPx * la * paintA / (w * h);
     }
   }
   const density = spec.density ?? "normal";
@@ -5148,6 +5271,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     }
   }
   for (let li = 0; li < spec.layers.length; li++) {
+    if (hidden?.[li]) continue;
     const layer = spec.layers[li];
     if (!layer.links || layer.links.mode === "chain") continue;
     const entities = allEntities[li];
@@ -5164,6 +5288,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     }
   }
   for (let li = 0; li < spec.layers.length; li++) {
+    if (hidden?.[li]) continue;
     const layer = spec.layers[li];
     if (layer.motion.type === "static") continue;
     const entities = allEntities[li];
@@ -5180,7 +5305,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
       });
     }
   }
-  const composed = spec.layers.map((l, li) => ({ l, ents: allEntities[li] })).filter(({ l }) => !["bounce", "warp", "path"].includes(l.motion.type)).filter(({ l }) => !(l.motion.type === "orbit" && l.motion.center && "layer" in l.motion.center));
+  const composed = spec.layers.map((l, li) => ({ l, li, ents: allEntities[li] })).filter(({ li }) => !hidden?.[li]).filter(({ l }) => !["bounce", "warp", "path"].includes(l.motion.type)).filter(({ l }) => !(l.motion.type === "orbit" && l.motion.center && "layer" in l.motion.center));
   const composedCount = composed.reduce((s, c) => s + c.ents.length, 0);
   if (composedCount >= 8) {
     const positions = composed.flatMap(({ ents }) => ents.map((e) => positionAt(e, 0, w, h)));
@@ -5198,6 +5323,7 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
   }
   const textBoxes = [];
   for (let li = 0; li < spec.layers.length; li++) {
+    if (hidden?.[li]) continue;
     const layer = spec.layers[li];
     const s = layer.sprite;
     if (layer.motion.type !== "static") continue;
@@ -5206,9 +5332,10 @@ function adviseSpec(spec, viewport = { width: 1920, height: 1080 }, opts = {}) {
     for (const e of allEntities[li]) {
       const p = positionAt(e, 0, w, h);
       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 map = paintMap(spec, layer, w, h, scale);
+      const box = map ? { ...raw, ...mapBox(map, raw) } : 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);
+      const alpha = layer.opacity === void 0 && layer.group === void 0 ? baseAlpha : baseAlpha * paintOpacity(spec, layer);
       textBoxes.push({ li, label, alpha, ...box });
     }
   }
@@ -5331,14 +5458,15 @@ function brightestAdditivePlate(spec, allEntities, ground, box, w, h) {
     if (blend !== "lighter" && blend !== "screen") continue;
     if (lj === box.li) continue;
     const entities = allEntities[lj];
+    const moved = layer.transform !== void 0 || groupOf(spec, layer)?.transform !== void 0;
     for (const e of entities) {
       const hex = spriteHex(layer, e);
       if (hex === null) continue;
       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 (!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 (!moved && !entityReachesBox(e, maxDim / 2, box, w, h)) continue;
+      const a = layer.opacity === void 0 && layer.group === void 0 ? Math.min(1, e.alpha + e.pulseAmp) : Math.min(1, e.alpha + e.pulseAmp) * paintOpacity(spec, layer);
       if (a <= 0) continue;
       const plate = additivePlate(ground, hexRgb(hex), a, blend);
       const lum = relativeLuminance(plate);
@@ -5386,6 +5514,26 @@ function textBlockBoxAt(s, p, w, h) {
   const { dx, dy } = textBlockAnchorOffset(s, maxWPx, maxLineW, totalH);
   return { x0: x0 + dx, y0: p.y + dy, x1: x0 + dx + maxLineW, y1: p.y + dy + totalH, fs: fsPx };
 }
+function hiddenLayers(spec) {
+  if (!spec.groups && !spec.layers.some((l) => l.opacity !== void 0)) return null;
+  const tracks = spec.timeline ? timelineTracks(spec) : null;
+  const pinnedZero = (path, base, ancestors) => {
+    if (base !== 0) return false;
+    if (!tracks) return true;
+    for (const [p, keys] of tracks) {
+      if (p === path && keys.some((k) => k.value !== 0)) return false;
+      if (ancestors.includes(p)) return false;
+    }
+    return true;
+  };
+  const out = spec.layers.map((l, i) => {
+    const lp = `layers.${i}`;
+    if (pinnedZero(`${lp}.opacity`, l.opacity, ["layers", lp])) return true;
+    const g = l.group !== void 0 && spec.groups && Object.prototype.hasOwnProperty.call(spec.groups, l.group) ? spec.groups[l.group] : void 0;
+    return !!g && pinnedZero(`groups.${l.group}.opacity`, g.opacity, ["groups", `groups.${l.group}`]);
+  });
+  return out.some(Boolean) ? out : null;
+}
 function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
   const warnings = [];
   for (let i = 0; i < seq.segments.length; i++) {
@@ -5405,17 +5553,17 @@ function adviseSequence(seq, viewport = { width: 1920, height: 1080 }) {
     });
   }
   for (let i = 0; i < seq.segments.length - 1; i++) {
+    const tr = seq.segments[i].transition;
     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) {
+    if (delta > 0.5 && tr?.type !== "fade") {
       warnings.push({
         path: `segments[${i}]`,
         code: "boundary-luminance-jump",
-        message: `background luminance jumps ${delta.toFixed(2)} at boundary ${i}\u2192${i + 1} \u2014 may flash on cut`
+        message: `background luminance jumps ${delta.toFixed(2)} at boundary ${i}\u2192${i + 1} \u2014 may flash on cut${tr === void 0 || tr.type === "cut" ? `; declare transition: { type: 'fade', dur } on segments[${i}] to ramp it` : ""}`
       });
     }
-    const tr = seq.segments[i].transition;
     if (tr?.type === "morph") {
       const sigA = structuralSignature(seq.segments[i].scene);
       const sigB = structuralSignature(seq.segments[i + 1].scene);
@@ -5553,9 +5701,10 @@ function buildScene(spec, opts) {
   for (const { layer, entities } of layers) if (layer.key) byKey.set(layer.key, entities);
   let transforms = null;
   for (const { layer, entities } of layers) {
-    if (!layer.transform) continue;
+    const map = paintMap(spec, layer, w, h, scale);
+    if (!map) continue;
     transforms ??= /* @__PURE__ */ new Map();
-    for (const e of entities) transforms.set(e, layer.transform);
+    for (const e of entities) transforms.set(e, map);
   }
   return { w, h, scale, seed, layers, byKey, transforms };
 }
@@ -5569,8 +5718,8 @@ function posOf(scene, e, t) {
       p.y += pp.y;
     }
   }
-  const tf = scene.transforms?.get(e);
-  return tf ? transformPoint(tf, p, scene.w, scene.h, scene.scale) : p;
+  const map = scene.transforms?.get(e);
+  return map ? map(p) : p;
 }
 function textBox(s, e, p) {
   const m = s.font ? /(\d+(?:\.\d+)?)px/.exec(s.font) : null;
@@ -5680,6 +5829,37 @@ function distanceToOutline(pts, x, y) {
   }
   return Math.sqrt(best);
 }
+function rotatedBoxCoverage(cx, cy, hx, hy, rot, x0, y0, x1, y1) {
+  const cr = Math.cos(rot), sr = Math.sin(rot);
+  let poly = [[-hx, -hy], [hx, -hy], [hx, hy], [-hx, hy]].map(([x, y]) => [cx + x * cr - y * sr, cy + x * sr + y * cr]);
+  const clip = (inside, cut) => {
+    const out = [];
+    for (let i = 0; i < poly.length; i++) {
+      const a = poly[i], b = poly[(i + 1) % poly.length];
+      if (inside(a)) {
+        out.push(a);
+        if (!inside(b)) out.push(cut(a, b));
+      } else if (inside(b)) out.push(cut(a, b));
+    }
+    poly = out;
+  };
+  const atX = (x) => (a, b) => [x, a[1] + (x - a[0]) / (b[0] - a[0]) * (b[1] - a[1])];
+  const atY = (y) => (a, b) => [a[0] + (y - a[1]) / (b[1] - a[1]) * (b[0] - a[0]), y];
+  clip((p) => p[0] >= x0, atX(x0));
+  if (!poly.length) return 0;
+  clip((p) => p[0] <= x1, atX(x1));
+  if (!poly.length) return 0;
+  clip((p) => p[1] >= y0, atY(y0));
+  if (!poly.length) return 0;
+  clip((p) => p[1] <= y1, atY(y1));
+  if (!poly.length) return 0;
+  let area = 0;
+  for (let i = 0; i < poly.length; i++) {
+    const a = poly[i], b = poly[(i + 1) % poly.length];
+    area += a[0] * b[1] - b[0] * a[1];
+  }
+  return Math.abs(area) / 2 / ((x1 - x0) * (y1 - y0));
+}
 function luminanceGrid(spec, opts = {}) {
   spec = resolveTimelineAt(spec, opts.t ?? 5e3);
   const scene = buildScene(spec, opts);
@@ -5839,7 +6019,7 @@ function luminanceGrid(spec, opts = {}) {
   };
   const splatPass = (tPass, alphaScale) => {
     for (const { layer, entities } of scene.layers) {
-      const lifeA = layer.opacity === void 0 ? lifeAlphaAt(layer.life, tPass) : lifeAlphaAt(layer.life, tPass) * layerOpacity(layer);
+      const lifeA = layer.opacity === void 0 && layer.group === void 0 ? lifeAlphaAt(layer.life, tPass) : lifeAlphaAt(layer.life, tPass) * paintOpacity(spec, layer);
       if (lifeA <= 0) continue;
       for (const e of entities) {
         splatTrail(layer, e, tPass, lifeA, alphaScale);
@@ -5847,7 +6027,7 @@ function luminanceGrid(spec, opts = {}) {
         if (a <= 4e-3) continue;
         const lum = spriteLuma(layer, e);
         const p = posOf(scene, e, tPass);
-        const sz = layer.transform ? sizeAt(e, tPass) * transformSize(layer.transform) : sizeAt(e, tPass);
+        const sz = layer.transform || layer.group !== void 0 ? sizeAt(e, tPass) * paintSize(spec, layer) : 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);
@@ -5902,6 +6082,7 @@ function luminanceGrid(spec, opts = {}) {
         let centerY = p.y;
         let halfX = sz / 2;
         let halfY = s.kind === "rect" ? (e.size2 ?? sz) * (e.size > 0 ? sz / e.size : 1) / 2 : sz / 2;
+        let boxRot = 0, boxHx = 0, boxHy = 0;
         if (s.kind === "text") {
           const box = textBox(s, e, p);
           centerX = box.cx;
@@ -5924,8 +6105,23 @@ function luminanceGrid(spec, opts = {}) {
           const sr = Math.sin(rot);
           centerX = p.x + box.cx * cr - box.cy * sr;
           centerY = p.y + box.cx * sr + box.cy * cr;
+          boxRot = rot;
+          boxHx = box.halfX;
+          boxHy = box.halfY;
           halfX = Math.abs(box.halfX * cr) + Math.abs(box.halfY * sr);
           halfY = Math.abs(box.halfX * sr) + Math.abs(box.halfY * cr);
+        } else if (s.kind === "rect") {
+          const rot = rotationAt(e, tPass);
+          if (rot) {
+            boxRot = rot;
+            boxHx = halfX;
+            boxHy = halfY;
+            const cr = Math.abs(Math.cos(rot));
+            const sr = Math.abs(Math.sin(rot));
+            const hx = halfX * cr + halfY * sr;
+            halfY = halfX * sr + halfY * cr;
+            halfX = hx;
+          }
         }
         const circular = s.kind === "circle" || s.kind === "ring" || s.kind === "polygon";
         const soft = (s.kind === "circle" || s.kind === "polygon") && !!s.soft;
@@ -5939,7 +6135,10 @@ function luminanceGrid(spec, opts = {}) {
         const r0 = Math.max(0, Math.floor((centerY - reachY) / cellH));
         const r1 = Math.min(rows - 1, Math.floor((centerY + reachY) / cellH));
         const inkWeight = (s.kind === "text" || s.kind === "emoji" || s.kind === "textBlock" ? 0.55 : 1) * (s.kind === "textBlock" ? textBlockRevealFraction(s, w, h, t) * (s.opacity ?? 1) : 1);
+        const byArea = s.kind === "rect" || s.kind === "bar";
         for (let r = r0; r <= r1; r++) {
+          const fy = byArea ? Math.max(0, Math.min((r + 1) * cellH, centerY + halfY) - Math.max(r * cellH, centerY - halfY)) / cellH : 1;
+          if (fy <= 0) continue;
           for (let c = c0; c <= c1; c++) {
             const dx = (c + 0.5) * cellW - centerX;
             const dy = (r + 0.5) * cellH - centerY;
@@ -5963,6 +6162,14 @@ function luminanceGrid(spec, opts = {}) {
                 wgt = soft ? Math.max(0.1, 1 - d / Math.max(halfX, 1e-6)) : 1;
               }
               compose(r * cols + c, lum, a * wgt * shapeWeight, layer.blend);
+            } else if (byArea) {
+              if (boxRot) {
+                const cov = rotatedBoxCoverage(centerX, centerY, boxHx, boxHy, boxRot, c * cellW, r * cellH, (c + 1) * cellW, (r + 1) * cellH);
+                if (cov > 0) compose(r * cols + c, lum, a * shapeWeight * cov, layer.blend);
+              } else {
+                const fx = Math.max(0, Math.min((c + 1) * cellW, centerX + halfX) - Math.max(c * cellW, centerX - halfX)) / cellW;
+                if (fx > 0) compose(r * cols + c, lum, a * shapeWeight * fx * fy, layer.blend);
+              }
             } else {
               compose(r * cols + c, lum, a * inkWeight * shapeWeight, layer.blend);
             }
@@ -6161,8 +6368,9 @@ function rawDominance(spec, opts = {}) {
     return Math.sqrt(dx * dx + dy * dy);
   };
   const raw = scene.layers.map(({ layer, entities }, layerIndex) => {
-    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;
+    const lifeA = layer.opacity === void 0 && layer.group === void 0 ? lifeAlphaAt(layer.life, t) : lifeAlphaAt(layer.life, t) * paintOpacity(spec, layer);
+    const painted = layer.transform !== void 0 || layer.group !== void 0;
+    const areaScale = painted ? paintSize(spec, layer) ** 2 : 1;
     let area = 0;
     let lumAcc = 0;
     for (const e of entities) {
@@ -6191,7 +6399,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 += layer.transform ? entArea * areaScale * a : entArea * a;
+      area += painted ? entArea * areaScale * a : entArea * a;
       if (layer.trail) {
         const fade = layer.trail.fade ?? 1;
         const span = sweptDistance(e, layer.trail.length);