@idle-screens/schema 3.5.0 → 3.6.0

package/FORMAT.md

@@ -32,7 +32,11 @@ sprites, `colorWeights`, `pulse.wave`, `layout` (grid), `life`,
 `links.mode/falloff/closed`, `blend: screen|multiply`, orbit layer-parents
 (2026-07-21 — "the v1 ceiling");
 `textBlock` sprite — deterministic multi-line text with viewport-unit sizing;
-`textBlock.reveal` — animated typing/deleting via one steerable paint param.
+`textBlock.reveal` — animated typing/deleting via one steerable paint param;
+`emit` (sparse events), `clock` (phase-lock), `motion.ease` (settle / buoyant)
+(2026-09-05 — time structure); `polygon` / `stroke` sprites and `rect.feather`
+(2026-09-05 — shape glyphs); `layout: list | table` and the `bar` sprite
+(2026-09-05 — data layout).
 
 ## Safety invariants
 
@@ -48,7 +52,10 @@ These hold **by construction** — no spec can violate them:
    so a layer will generally not pulse in unison (edge case: if spawn positions
    alias the wavelength, phases may coincide). `ghosting` only *smooths* luminance
    changes (it composites frames over a faded copy of the last), never sharpens
-   them.
+   them. `clock` deliberately removes the per-entity phase, so the validator
+   floors a clocked layer's periods at 1000 ms (1 Hz) instead — a layer in
+   unison breathes, it never flashes. `emit` events are floored at one per
+   second per entity and always ride a smooth envelope, never a cut.
 3. **Motion is bounded.** Speeds are capped (4000 px/sec; warp at 1.5
    depth-units/sec; orbit at 180 deg/sec; path laps at ≥ 2 s).
 4. **Work is bounded.** ≤ 36 layers, ≤ 400 entities per layer, ≤ 800 total,
@@ -72,7 +79,10 @@ Author against the JSON Schema; ship through the runtime validator.
 
 Rules the JSON Schema cannot fully express (the runtime enforces them):
 total entities across all layers ≤ 800; every `[min, max]` range must satisfy
-`min ≤ max`; `colorWeights` length must match `colors`; orbit layer-parents
+`min ≤ max`; `colorWeights` length must match `colors`; `emit.life ≤
+emit.every`; a `clock`ed layer's `pulse`/`grow`/`cycle` period must satisfy
+`period / rate ≥ 1000`; a `polygon` takes `sides` or `points`, not both (the
+JSON Schema enforces this one too); orbit layer-parents
 must exist, have `count: 1`, and not themselves orbit a layer.
 
 ## Structure
@@ -84,6 +94,7 @@ must exist, have `count: 1`, and not themselves orbit a layer.
   "label": "Snowfall",
   "seed": 42,                    // optional; falls back to the host's seed
   "motionIntensity": "calm",     // optional: calm | moderate | energetic
+  "density": "normal",           // optional: sparse | normal | dense — declared intent, see below
   "units": "viewport",           // optional: viewport (default) | px
   "referenceViewport": 1080,     // optional; design resolution for density scaling
   "ghosting": 0.9,               // optional 0..0.95; frame-persistence smear
@@ -102,6 +113,16 @@ use that CSS font verbatim and do not scale with the viewport.
 clearing: moving entities leave decaying after-images (Mystify smears, Matrix
 trails, long-exposure light). 0.85–0.95 is the useful range; 0 (default) is off.
 
+`density` declares what the emptiness or the crowding means. `sparse` says
+the scene is *meant* to be almost empty — one faint mark on a dark ground,
+long silences — so `adviseSpec` withholds `sparse-scene` and a scorer that
+gates on coverage should read the declaration before calling a faithful
+scene broken. `dense` withholds `dense-scene` the same way. The declaration
+is checked, not trusted: a `sparse` scene whose alpha-weighted coverage
+exceeds 2 %, or a `dense` one that would have tripped `sparse-scene`, gets a
+`density-mismatch` advisory instead. Omitted means `normal`. Like
+`motionIntensity`, it is a hint — it changes no pixel.
+
 ### `background`
 
 - `{ "type": "solid", "color": "#06060c" }`
@@ -129,10 +150,12 @@ trails, long-exposure light). 0.85–0.95 is the useful range; 0 (default) is of
 | `grow` | `{amp ≤ 0.8, period ≥ 500}` | none | size breathing (seeded phase) |
 | `trail` | `{length ≤ 5000, fade?}` | none | analytic afterglow trail; `length` is **milliseconds** of history (max 5000), `fade` a number 0..1 (not a boolean — `links.falloff` in the next row is the boolean) |
 | `links` | see below | none | inter-entity lines |
-| `layout` | `{type: "grid", columns?, jitter?}` | scatter | grid placement; `jitter` scalar or `{x?, y?}` 0..1 per axis |
+| `layout` | `{type: "grid", columns?, jitter?}` \| `{type: "list", gap?}` \| `{type: "table", columns, gap?}` | scatter | `grid`: cells fill `region`, `jitter` scalar or `{x?, y?}` 0..1 per axis. **`list` / `table`: data layouts** — entities in reading order from `position` (any count) or centred in `region`, `gap` apart (viewport units of `min(w,h)`, default 0.06); text/emoji take `strings[i]` / `glyphs[i]` and palettes `colors[i]` **in order**, so N labels are one layer |
 | `life` | `{enter?, exit?, fade?}` ms | always on | act structure: fade the layer in at `enter`, out at `exit` |
+| `emit` | `{every ≥ 1000, life ≥ 500, jitter?, grow?}` (`life ≤ every`) | always lit | **sparse events**: each entity is dark except a `life`-ms window every `every` ms, fading in fast and out slow; `jitter` 0 staggers entities evenly (one event at a time while `life ≤ every / count`), 1 scatters the offsets (a fixed sequence, not seeded — declaring `emit` disturbs no other draw); `grow: [from, to]` scales size across the window — expansion rather than travel |
+| `clock` | `{phase?, rate?}` | seeded phases | **phase-lock**: `pulse`, `grow` and `cycle` share one phase (turns, 0..1) and run at `rate` × time; two layers with the same clock breathe in step. Clocked periods must satisfy `period / rate ≥ 1000` |
 | `key` | string | none | addressable name → `setParam("key.field", …)` |
-| `position` | `{x, y}` 0..1 | none | exact placement; **requires `count: 1`**; overrides `region`/`layout` |
+| `position` | `{x, y}` 0..1 | none | exact placement; **requires `count: 1`** — except with a `list`/`table` layout, where it anchors the block's top-left; overrides `region` |
 
 `links`: `{ k: 1..8, maxDist, color?, alpha?, width?, mode?, falloff?, closed? }`.
 `mode: "nearest"` (default) wires each entity to its k nearest neighbors within
@@ -155,8 +178,31 @@ with distance, removing pop-in at the cutoff.
 - `{ "kind": "streak", "length": [0.01, 0.03], "color": "#cfd8ff", "width": 0.002 }` —
   a line oriented along the entity's analytic heading with a faded tail
   (rain that reads as rain, shooting stars, warp stars)
-- `{ "kind": "rect", "width": [0.012, 0.02], "aspect": [1.3, 1.7], "color": "#ffb347" }` —
-  rectangle; `aspect` is the height/width ratio range (rotates with `spin`)
+- `{ "kind": "rect", "width": [0.012, 0.02], "aspect": [1.3, 1.7], "color": "#ffb347", "feather": 0.6 }` —
+  rectangle; `aspect` is the height/width ratio range (rotates with `spin`);
+  `feather` 0..1 softens the edges — that fraction of the half-size fades out
+  toward the border (Rothko's block at 0.5–0.8)
+- `{ "kind": "bar", "values": [82, 64, 91], "max": 100, "length": 0.5, "thickness": 0.02, "color": "#17e8c8", "direction": "right" }` —
+  a data bar: entity *i* draws `length × values[i] / max` (viewport units),
+  `thickness` thick, growing from its position toward `direction` (`right`
+  default, `left`, `up`, `down`). `values` are **paint**: `setParam("bars.values", […])`
+  glides every bar. With `layout: { type: "list" }` a chart is one layer and
+  its labels another — the dashboard genre stops needing one layer per number
+- `{ "kind": "polygon", "radius": [0.02, 0.05], "sides": 3, "color": "#f2e8c9", "soft": false }` —
+  regular n-gon of the seeded circumradius, point up (`sides` 3..12, default
+  6); or `"points": [[-1, 0.9], [0.2, -1], [1, 0.4]]` — 3..24 unit
+  coordinates in −1..1 scaled by the radius — for any facet (a Picasso shard,
+  a Kandinsky triangle, a Mondrian plane). `soft` feathers the fill from the
+  centre. Rotates with `spin`. `points` are paint, so two polygons with the
+  same point count `morph` into each other
+- `{ "kind": "stroke", "length": [0.08, 0.18], "points": [[-1, 0.3], [-0.5, -0.6], [0.3, -0.7], [1, 0.1]], "width": 0.004, "taper": true, "color": "#f2e8c9" }` —
+  a freehand mark: a path through 2..24 unit-coordinate points, scaled so the
+  unit box spans the seeded `length`, stroked `width` wide with round joins.
+  `curve: "smooth"` (default) is a Catmull-Rom spline, `"linear"` a polyline;
+  `taper` thins the mark to almost nothing at both ends (a brush stroke rather
+  than a line); `orient: true` turns the path's +x along the entity's heading,
+  like `streak`. Rotates with `spin`. Van Gogh's stroke, Hokusai's contour,
+  O'Keeffe's petal, Basquiat's scrawl
 - `{ "kind": "textBlock", "text": "Multi-line text with wrapping.", "maxWidth": 0.8, "fontSize": 0.04, "lineHeight": 1.4, "align": "left", "color": "#e6e8ef" }` —
   multi-line text block with deterministic line-breaking. All dimensions are
   viewport fractions (of `min(w,h)`), not px — `units: "px"` specs reject
@@ -196,9 +242,20 @@ with distance, removing pop-in at the cutoff.
   glide `reveal.progress` to 0, swap `text` while nothing is visible, glide
   back to 1.
 
-`circle`, `ring`, `streak`, and `rect` all accept `colors: [...]` (seeded
-per-entity palette pick) and `colorWeights: [...]` (relative weights, same
-length — "mostly cool tones, occasional ember").
+`circle`, `ring`, `streak`, `rect`, `bar`, `polygon` and `stroke` all accept
+`colors: [...]` (seeded per-entity palette pick) and `colorWeights: [...]`
+(relative weights, same length — "mostly cool tones, occasional ember").
+
+**Drawing a shape out of sprites.** Overlapping sprites merge into one seamless
+silhouette under exactly one set of conditions: a single flat colour, `alpha`
+of `[1, 1]`, no `blend`, no `pulse`, and hard edges (no `soft`, no
+`rect.feather`). Anything else leaves every overlap visible as an internal edge,
+so the layer reads as a pile of sprites rather than a form — `soft` in
+particular reads as smoke, not mass. Depth then comes from *layer order* and a
+different flat colour per layer, painting back to front, and a later layer can
+be used to cut a clean edge across an earlier one. `layerCohesion` measures
+which of the two you got; `overlap-seams` warns when you asked for the first
+and configured the second.
 
 ### `motion` (one of)
 
@@ -228,6 +285,26 @@ length — "mostly cool tones, occasional ember").
 
 All speeds are ranges; each entity draws its own value (seeded).
 
+`drift`, `rise` and `wander` also accept **`ease`** — closed-form velocity
+shaping, no integration state:
+`{ "ease": { "type": "settle", "tau": 2500 } }` starts at the entity's speed
+and decelerates to rest with time constant `tau` ms (it travels `speed × tau`
+and stops — a mark flung and coming to rest); `"buoyant"` starts at rest and
+approaches the speed over `tau` (a bubble reaching terminal velocity). With
+`emit`, the eased travel restarts from the spawn point on every event. For
+`wander` only the base velocity eases — the harmonic meander keeps breathing,
+so a settled wanderer hovers rather than freezes.
+
+**Time structure, composed.** `emit` is how a scene does *almost nothing,
+almost never*: one ring every twelve seconds that expands and fades
+(`emit: { every: 12000, life: 5000, jitter: 0, grow: [0.15, 2.4] }`) reads as
+an event, where the same ring pulsing forever reads as wallpaper. Long
+`every`, low `count`, `jitter: 0` for a metronome, `1` for weather; pair with
+`ease: settle` so a mark is flung and comes to rest before it fades ("expand,
+drift a little, settle, fade" is one layer). `clock` is the other half: two
+layers on the same clock are a duet, not a coincidence. The shipped `pings`
+example is the whole idea in two layers.
+
 ## Determinism contract
 
 Entity construction consumes the seeded RNG in a **fixed draw order** per layer.
@@ -293,6 +370,17 @@ trade-offs for a zero-dependency, renderer-free analysis tool.
   line-salience boost so they aren't crushed by filled discs.
 - `motionStats(spec, opts)` — per-layer mean/max on-screen speed from analytic
   displacement — choreography as numbers.
+- `layerCohesion(spec, opts)` — **does a layer read as one form or as N marks?**
+  The luminance maps measure ink, not edges, so a layer whose sprites merged
+  into a silhouette and one that stayed a pile of discs are identical in every
+  other channel. Two independent facts, both reported (also on
+  `perceiveScene().form`): `overlap` is geometry — the mean fraction of an
+  entity's outline buried inside a sibling (shipped particle fields measure
+  ≤ 0.154; a packed silhouette measures 0.79–0.85; `null` for lines, glyphs and
+  text, where a merged silhouette is not a meaningful idea). `seamless` is
+  paint — whether those overlaps vanish or draw an internal edge, with
+  `seamCause` naming the field to change. `reads` combines them into `mass`,
+  `seamed` or `marks`.
 - `textSprites(spec, opts)` — the literal strings and rendered sizes of every
   text layer. Glyphs are invisible in the luminance maps, so this is the only
   way to confirm *what words* are on screen and how big. (Also on
@@ -305,6 +393,16 @@ trade-offs for a zero-dependency, renderer-free analysis tool.
   textBlock line-breaker uses, so they are estimates of the renderer's own
   layout — a caption that fails these will look wrong on the wall; one that
   passes may still sit a few px off.
+  `overlap-seams` catches the trap the other channels are blind to: a layer
+  whose entities bury each other (so it was drawn as one shape) but whose paint
+  settings make every overlap visible. It is gated to stay off deliberate
+  washes — it needs at least 6 entities and a mean base alpha of 0.45, and
+  never fires under `blend: lighter` / `screen`. No shipped example trips it.
+  The two density advisories read the spec's declared `density` first:
+  `sparse-scene` is withheld under `density: "sparse"` and `dense-scene`
+  under `"dense"`, and `density-mismatch` fires instead when the measured
+  coverage contradicts the declaration (a "sparse" scene covering more than
+  2 % of the frame, a "dense" one that would have read as empty).
 - `diffScenes(a, b, opts)` — **relative sight**: coverage/luminance deltas,
   visual-balance shift, 3×3 region deltas, dominance-rank movement, and
   advisory codes added/removed. Agents judge "is B better than A" far more
@@ -400,6 +498,9 @@ Shipped working specs (also exposed as `EXAMPLE_SPECS` /
 showcases — `aurora` (wander + coherence + ghosting + pulse.wave),
 `warp-tunnel` (warp + streaks), `polygons` (chain links + heavy ghosting),
 `matrix-rain` (grid layout + glyph cycle + ghosting), and `procession`
-(path + layer-parented orbit + life staging + ring/rect sprites). See
-[`src/examples/`](./src/examples/). The dashboard exercises the static/HUD
-subset at scale (34 layers of keyed, positioned text).
+(path + layer-parented orbit + life staging + ring/rect sprites);
+`nostalghia-candle` and `haiku` (restraint and text); and the 2026-09 trio —
+`pings` (emit + grow + ease: one event at a time), `facets` (polygon, stroke
+and feathered rect) and `relay-board` (list layout + bar: a chart in five
+layers). See [`src/examples/`](./src/examples/). The dashboard exercises the
+static/HUD subset at scale (34 layers of keyed, positioned text).

package/dist/index.d.ts

@@ -22,6 +22,16 @@ interface SaverSpec {
     background?: BackgroundSpec;
     layers: LayerSpec[];
     motionIntensity?: 'calm' | 'moderate' | 'energetic';
+    /**
+     * Declared density intent. `sparse` says the emptiness is the point (one
+     * mark on a dark ground, long silences): `adviseSpec` withholds
+     * `sparse-scene`, and scorers that gate on coverage should read this before
+     * calling a faithful scene broken. `dense` withholds `dense-scene` the same
+     * way. Either declaration is checked against the measured coverage and a
+     * `density-mismatch` advisory fires when the scene contradicts it. Omitted
+     * means `normal`. A hint only — it changes no pixel.
+     */
+    density?: 'sparse' | 'normal' | 'dense';
     /**
      * Frame persistence (0..1, capped at LIMITS.maxGhosting). Instead of fully clearing,
      * each frame the background is painted at reduced alpha so moving entities leave
@@ -137,7 +147,8 @@ interface LayerSpec {
     key?: string;
     /**
      * Exact fractional position {x, y} for a single entity (0 = left/top, 1 = right/bottom).
-     * Only valid when `count` is 1. Overrides `region` scatter placement.
+     * Only valid when `count` is 1 — or, with a `list` / `table` layout, as the
+     * top-left anchor of the whole block. Overrides `region` scatter placement.
      */
     position?: {
         x: number;
@@ -185,6 +196,26 @@ interface LayerSpec {
             x?: number;
             y?: number;
         };
+    }
+    /**
+     * Data layouts — entities in READING ORDER, no scatter. `list` stacks them
+     * in one column `gap` apart (viewport units of min(w,h), default 0.06);
+     * `table` fills `columns` row-major with `gap` `{x, y}` (one number = both).
+     * Text and emoji sprites take `strings[i]` / `glyphs[i]` in order instead of
+     * a seeded pick, and palette `colors[i]` likewise, so N labels or N bars are
+     * ONE layer. `position` (with any count) is the block's top-left anchor;
+     * without it the block is centred in `region`.
+     */
+     | {
+        type: 'list';
+        gap?: number;
+    } | {
+        type: 'table';
+        columns: number;
+        gap?: number | {
+            x?: number;
+            y?: number;
+        };
     };
     /**
      * Layer lifecycle for act structure — a pure function of t, no state. Alpha is 0
@@ -196,6 +227,56 @@ interface LayerSpec {
         exit?: number;
         fade?: number;
     };
+    /**
+     * Sparse events — marks that appear, expand and fade in place, one at a time,
+     * with long silences between (the "one ping" primitive). Each entity is dark
+     * except for a window of `life` ms that recurs every `every` ms at a
+     * per-entity offset: `jitter` 1 (default) scatters the offsets (a fixed
+     * low-discrepancy sequence — not seeded, so declaring `emit` disturbs no
+     * other draw and the same spec times its events identically under every
+     * seed), 0 spreads the entities evenly across the period — a metronome, one
+     * event at a time as long as `life ≤ every / count`.
+     * Inside a window the entity fades in over the first quarter and out over
+     * the rest; `grow` scales its size from `grow[0]` to `grow[1]` across the
+     * window — expansion rather than travel. A pure function of t. Flash safety:
+     * `every` ≥ 1000 ms and `life` ≥ 500 ms, so no entity fires more than once a
+     * second and never as a hard cut. Composes with `pulse`, `life`, `trail` and
+     * every motion; with `motion.ease` the eased travel restarts on every event.
+     */
+    emit?: {
+        every: number;
+        life: number;
+        jitter?: number;
+        grow?: [number, number];
+    };
+    /**
+     * Phase-lock. Replaces the seeded per-entity phases of `pulse`, `grow` and
+     * `cycle` with one shared phase (`phase` in turns, 0..1, default 0) and runs
+     * those three at `rate` × scene time (default 1). Two layers declaring the
+     * same clock breathe in step; different phases give a fixed offset (call and
+     * response). `pulse.wave` still adds its position-derived phase on top, so a
+     * clocked wave stays a wave. Because a clocked layer moves in unison, its
+     * `pulse`/`grow` periods must satisfy `period / rate ≥ 1000 ms` (1 Hz).
+     */
+    clock?: {
+        phase?: number;
+        rate?: number;
+    };
+}
+/**
+ * Closed-form velocity easing for `drift`, `rise` and `wander`. `settle`
+ * starts at the entity's speed and decelerates to rest with time constant
+ * `tau` ms — it travels `speed × tau` and stops, a mark flung and coming to
+ * rest. `buoyant` starts at rest and approaches the speed over `tau` — a
+ * bubble reaching terminal velocity. Position stays an analytic function of
+ * t (no integration state). With `emit`, the eased travel restarts from the
+ * spawn point on every event. For `wander` only the base velocity eases —
+ * the harmonic meander keeps breathing, so a settled wanderer hovers rather
+ * than freezes.
+ */
+interface MotionEase {
+    type: 'settle' | 'buoyant';
+    tau: number;
 }
 type SpriteSpec = {
     kind: 'emoji';
@@ -248,6 +329,8 @@ type SpriteSpec = {
 /**
  * Axis-aligned rectangle (rotates with `spin`). `width` is the horizontal size
  * range; `aspect` the height/width ratio range (default [1,1] = squares).
+ * `feather` (0..1) softens the edges: that fraction of the half-size fades
+ * out toward the border — Rothko's soft-edged block at 0.5–0.8.
  * Mondrian blocks, confetti, city lights.
  */
  | {
@@ -255,6 +338,63 @@ type SpriteSpec = {
     width: [number, number];
     aspect?: [number, number];
     color: string;
+    feather?: number;
+    colors?: string[];
+    colorWeights?: number[];
+}
+/**
+ * A data bar. Entity i draws a bar `length × values[i] / max` long (viewport
+ * units of min(w,h)), `thickness` thick, growing from its position toward
+ * `direction` (default 'right'). `values` are PAINT — steer
+ * `layers.N.sprite.values` and the bars glide; `max` defaults to the largest
+ * value. Pair with a `list` layout: a chart is one layer, labels another.
+ */
+ | {
+    kind: 'bar';
+    values: number[];
+    length: number;
+    thickness: number;
+    color: string;
+    max?: number;
+    direction?: 'right' | 'left' | 'up' | 'down';
+    colors?: string[];
+    colorWeights?: number[];
+}
+/**
+ * Regular or custom polygon. `sides` (3..12, default 6) draws a regular
+ * n-gon of the seeded `radius` (circumradius), point up; `points` (3..24
+ * unit coordinates in −1..1, scaled by the radius) draws any facet — a
+ * Picasso shard, a Kandinsky triangle, a Mondrian plane. `soft` feathers
+ * the fill from the centre like a soft circle. Rotates with `spin`.
+ */
+ | {
+    kind: 'polygon';
+    radius: [number, number];
+    color: string;
+    sides?: number;
+    points?: Array<[number, number]>;
+    soft?: boolean;
+    colors?: string[];
+    colorWeights?: number[];
+}
+/**
+ * A freehand mark: a path through `points` (2..24 unit coordinates in
+ * −1..1, scaled by the seeded `length`) stroked `width` wide with round
+ * joins. `curve: 'smooth'` (default) runs a Catmull-Rom spline through the
+ * points, `'linear'` a polyline. `taper` thins the mark to almost nothing at
+ * both ends — a brush stroke rather than a line. `orient` turns the path's
+ * +x along the entity's heading (like `streak`). Rotates with `spin`. Van
+ * Gogh's stroke, Hokusai's contour, O'Keeffe's petal, Basquiat's scrawl.
+ */
+ | {
+    kind: 'stroke';
+    length: [number, number];
+    points: Array<[number, number]>;
+    color: string;
+    width?: number;
+    curve?: 'smooth' | 'linear';
+    taper?: boolean;
+    orient?: boolean;
     colors?: string[];
     colorWeights?: number[];
 }
@@ -338,12 +478,14 @@ type MotionSpec =
     angle?: number;
     bidirectional?: boolean;
     bob?: number;
+    ease?: MotionEase;
 }
 /** Rise upward (px/sec) with an optional horizontal sway amplitude (px) — bubbles. */
  | {
     type: 'rise';
     speed: [number, number];
     sway?: number;
+    ease?: MotionEase;
 }
 /** Bounce diagonally at a per-entity speed, reflecting off the edges (px/sec). */
  | {
@@ -388,6 +530,7 @@ type MotionSpec =
     angle?: number;
     meander?: number;
     coherence?: number;
+    ease?: MotionEase;
 }
 /**
  * Perspective starfield: entities live on a depth axis and stream toward the
@@ -477,6 +620,20 @@ declare const LIMITS: {
     readonly minSegmentDuration: 1000;
     readonly maxTransitionDur: 5000;
     readonly minTransitionDur: 200;
+    readonly minEmitEvery: 1000;
+    readonly maxEmitEvery: 600000;
+    readonly minEmitLife: 500;
+    readonly maxEmitGrow: 8;
+    readonly minClockedPeriod: 1000;
+    readonly minClockRate: 0.1;
+    readonly maxClockRate: 4;
+    readonly defaultListGap: 0.06;
+    readonly defaultListGapPx: 40;
+    readonly minPolygonSides: 3;
+    readonly maxPolygonSides: 12;
+    readonly maxShapePoints: 24;
+    readonly minEaseTau: 100;
+    readonly maxEaseTau: 120000;
 };
 type SequenceTransition = {
     type: 'cut';
@@ -554,8 +711,12 @@ interface Entity {
     orbitCy: number;
     colorIndex: number;
     cyclePeriod: number;
-    /** Rect sprite second dimension (height px). Only set for rect sprites. */
+    /** Rect sprite second dimension (height px), or bar thickness. Only set for rect / bar sprites. */
     size2?: number;
+    /** Reading-order index into `bar.values`. Only set for bar sprites. */
+    barIndex?: number;
+    /** Placed by a list/table layout: variants cycle from the ordered base index, in step. Only set for data layouts. */
+    ordered?: true;
     /** Orbit parent layer key (motion.center = { layer }). Center resolved at render time. */
     orbitParent?: string;
     /** Harmonic drift params. Only set for wander motion. */
@@ -574,6 +735,23 @@ interface Entity {
         cx: number;
         cy: number;
     };
+    /** Sparse-event window. Only set when `layer.emit` is declared. `phase` ms offset. */
+    emit?: {
+        every: number;
+        life: number;
+        phase: number;
+        growFrom: number;
+        growTo: number;
+    };
+    /** Shared-clock time multiplier for pulse/grow/cycle. Only set when `layer.clock` is declared. */
+    clockRate?: number;
+    /** Shared cycle phase (radians). Only set when `layer.clock` is declared. */
+    cyclePhase?: number;
+    /** Velocity easing. Only set when the motion declares `ease`. */
+    ease?: {
+        type: 'settle' | 'buoyant';
+        tau: number;
+    };
     /** Spline params (pts in px, shared per layer). Only set for path motion. */
     path?: {
         pts: Array<{
@@ -598,6 +776,14 @@ declare function spriteVariants(sprite: SpriteSpec): number;
  *  `scale` multiplies every dimensional draw (default 1). Used for viewport units.
  *  `countScale` multiplies entity count for density-aware scaling (default 1). */
 declare function buildEntities(layer: LayerSpec, rng: Rng, w: number, h: number, scale?: number, countScale?: number): Entity[];
+/**
+ * Where entity `e` sits in its current emit window at time `t`: 0..1 across
+ * the visible `life` ms, or null while dark (or when the layer has no `emit`).
+ * Pure — the window index is `floor((t - phase) / every)`, no state.
+ */
+declare function emitWindow(e: Entity, t: number): number | null;
+/** Alpha envelope across an emit window: fast smooth attack, slow smooth decay. */
+declare function emitEnvelope(u: number): number;
 /** Analytic opacity of an entity at logical time `t` (ms). Pure, clamped to 0..1. */
 declare function alphaAt(e: Entity, t: number): number;
 /** Analytic size multiplier at time `t` (ms). Pure, clamped to > 0. */
@@ -762,6 +948,16 @@ declare function structuralSignature(spec: SaverSpec): string;
 declare function adviseSpec(spec: SaverSpec, viewport?: {
     width: number;
     height: number;
+}, 
+/**
+ * Sample point. `perceiveScene` forwards its own `t`/`seed` so the advisories
+ * describe the same scene its other channels do — without them a caller
+ * perceiving at t = 30 s would get `form` for that instant beside an
+ * `overlap-seams` advisory computed for a different one.
+ */
+opts?: {
+    t?: number;
+    seed?: number;
 }): SpecWarning[];
 /**
  * Non-blocking advisory warnings for a validated sequence envelope.
@@ -772,6 +968,82 @@ declare function adviseSequence(seq: IdleSequence, viewport?: {
     height: number;
 }): SpecWarning[];
 
+/**
+ * Layer cohesion — does a layer read as ONE form, or as N separate marks?
+ *
+ * The gap this closes: every other perception channel reports a heavily
+ * overlapping layer identically whether its sprites merge into a silhouette or
+ * stay legible as individual discs. Luminance, coverage, dominance and the
+ * braille map are all blind to it, because they measure ink, not edges. An
+ * agent drawing a *shape* out of sprites therefore cannot tell success from
+ * failure without publishing and looking at real pixels.
+ *
+ * Two independent facts decide it, so both are reported:
+ *
+ * - `overlap` — geometry. What fraction of a typical entity's outline is buried
+ *   inside a sibling. Scattered fields sit near 0; a deliberate mass sits high.
+ * - `seamless` — paint. Whether an overlap between two of this layer's entities
+ *   paints as an invisible join. Only a hard-edged, fully opaque, single-colour,
+ *   un-blended layer merges; anything else shows every internal edge.
+ *
+ * Both are analytic, deterministic and renderer-free, like the rest of
+ * `perceive.ts`.
+ */
+
+/**
+ * Sample time for a spec-level cohesion read, matching `perceiveScene`'s own
+ * default so the advisory and the reported numbers agree on the usual call.
+ * Past all typical `life.enter` staging; `grow` has had time to breathe.
+ */
+declare const COHESION_T = 5000;
+/** What a layer will read as on the wall. */
+type CohesionRead = 
+/** Entities merge into a single silhouette — the layer draws a shape. */
+'mass'
+/** Entities overlap heavily but every overlap paints a visible edge. */
+ | 'seamed'
+/** Entities stand alone — a field of marks, which most layers are. */
+ | 'marks';
+interface LayerCohesion {
+    layerIndex: number;
+    key: string | undefined;
+    /**
+     * Mean fraction of an entity's outline covered by a same-layer sibling, 0..1.
+     * `null` for sprite kinds where a merged silhouette is not a meaningful idea
+     * (lines, glyphs and text: ring, streak, stroke, bar, emoji, text, textBlock).
+     */
+    overlap: number | null;
+    /** Do this layer's overlaps paint as invisible joins? */
+    seamless: boolean;
+    /** Why not, when not — the field to act on. `null` when seamless. */
+    seamCause: string | null;
+    /** The verdict. `null` when `overlap` is null. */
+    reads: CohesionRead | null;
+}
+/**
+ * Why this layer's overlaps paint a visible edge, or null when they vanish.
+ *
+ * Opacity is judged over the whole timeline, not this instant: a layer that
+ * breathes with `pulse` is translucent at some point in every cycle, so its
+ * seams appear even if the sampled frame happens to catch it at full alpha.
+ */
+declare function seamCauseOf(layer: LayerSpec): string | null;
+/**
+ * Per-layer cohesion for an already-built scene. Takes entities rather than a
+ * spec so `perceiveScene` and `adviseSpec` can each pass the scene they already
+ * built instead of building a third one.
+ */
+declare function cohesionOf(layers: Array<{
+    layer: LayerSpec;
+    entities: Entity[];
+}>, t: number, w: number, h: number): LayerCohesion[];
+/**
+ * True when a `seamed` layer is worth warning about: dense enough to be
+ * deliberate, and opaque enough that it cannot be an atmospheric wash. Keeps
+ * the advisory off the soft low-alpha glow fields the playbook recommends.
+ */
+declare function seamsWorthWarning(layer: LayerSpec, c: LayerCohesion, entityCount: number): boolean;
+
 interface LayerSnapshot {
     key: string | undefined;
     count: number;
@@ -918,6 +1190,13 @@ interface DominanceEntry {
  * ribbons, so a comet layer is ranked by its comet, not just its head.
  */
 declare function dominanceRanking(spec: SaverSpec, opts?: PerceiveOptions): DominanceEntry[];
+/**
+ * Does each layer read as one merged form or as separate marks? The one thing
+ * the luminance maps cannot answer — they measure ink, not edges, so a layer
+ * that merged into a silhouette and one that stayed a pile of discs look
+ * identical in every other channel. See `cohesion.ts`.
+ */
+declare function layerCohesion(spec: SaverSpec, opts?: PerceiveOptions): LayerCohesion[];
 interface LayerMotionStats {
     layerIndex: number;
     key: string | undefined;
@@ -995,6 +1274,8 @@ interface ScenePerception {
     colProfile: number[];
     dominance: DominanceEntry[];
     motion: LayerMotionStats[];
+    /** Per layer: merged silhouette, seamed overlap, or separate marks. */
+    form: LayerCohesion[];
     /** Literal strings + sizes of any text layers (glyphs don't show in the maps). */
     text: TextSpriteInfo[];
     advisories: ReturnType<typeof adviseSpec>;
@@ -1157,6 +1438,38 @@ declare const MATRIX_RAIN_SPEC: SaverSpec;
  */
 declare const NOSTALGHIA_CANDLE_SPEC: SaverSpec;
 
+/**
+ * Pings — almost nothing, almost never.
+ * A near-black ground and one teal hue. Three rings take turns: each one
+ * appears, grows sixteenfold (0.15× → 2.4× its radius) and fades over four
+ * seconds, then the frame is empty until the next — `emit` with `jitter: 0`
+ * spaces them evenly, one event every four seconds, and `life` is kept at
+ * the stagger so no two rings are ever lit together. Underneath, a few motes rise,
+ * `settle` to rest and fade on their own, longer, seeded schedule. Nothing
+ * travels; everything grows and goes. The house style Fathom describes this
+ * exactly and, before `emit`, could not be authored.
+ */
+declare const PINGS_SPEC: SaverSpec;
+
+/**
+ * Facets — a composition in the manner of the early abstractionists: three
+ * soft-edged colour planes (feathered `rect`) breathing slowly behind a field
+ * of tumbling triangular facets (custom `polygon`), tapered brush arcs
+ * (`stroke`) drifting across, and a few glowing hexagons (soft regular
+ * `polygon`). Every glyph here is a path, not a disc — the shape family nine
+ * of the fifteen style profiles asked for.
+ */
+declare const FACETS_SPEC: SaverSpec;
+
+/**
+ * Relay Board — a six-row status chart in five layers instead of twenty-five.
+ * One `list` of labels, one `list` of `bar`s whose lengths are the numbers,
+ * one `list` of readouts, a title block, and a slow dust field behind so the
+ * board reads as a live wall, not a document. Steer `bars.values` and the
+ * bars glide to the new figures; the labels never move.
+ */
+declare const RELAY_BOARD_SPEC: SaverSpec;
+
 /**
  * Polygons: the classic Mystify-style bouncing-polygon saver, expressed as chain links + heavy
  * ghosting. Showcases `links.mode: 'chain'` with `closed` (vertices wired in order
@@ -1193,4 +1506,4 @@ declare const EXAMPLE_SPECS: SaverSpec[];
 /** Lookup by saver id. */
 declare const EXAMPLE_BY_ID: Readonly<Record<string, SaverSpec>>;
 
-export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COMETS_SPEC, CONSTELLATION_SPEC, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, type ResolveOptions, type ResolvedSegment, type RevealState, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SequenceSegment, type SequenceTransition, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextBlockLine, type TextRevealInput, type TextRevealSpec, type TextSpriteInfo, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, breakTextBlock, buildEntities, compileSaver, compileSequence, describeScene, diffScenes, dominanceRanking, easeSmooth, graphemeClusters, headingAt, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rotationAt, segmentStart, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, textWidthEm, validateSequence, validateSpec };
+export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, type CohesionRead, type CycleSpec, DASHBOARD_SPEC, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, FACETS_SPEC, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, type LayerCohesion, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, type MotionEase, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type Placed, RAIN_SPEC, RELAY_BOARD_SPEC, type ResolveOptions, type ResolvedSegment, type RevealState, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SNOWFALL_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type SequenceSegment, type SequenceTransition, type SpecError, type SpecWarning, type SpriteSpec, type SteerDelta, type TextBlockLine, type TextRevealInput, type TextRevealSpec, type TextSpriteInfo, type ValidationResult, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, breakTextBlock, buildEntities, cohesionOf, compileSaver, compileSequence, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, graphemeClusters, headingAt, layerCohesion, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, motionStats, perceiveScene, positionAt, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rotationAt, seamCauseOf, seamsWorthWarning, segmentStart, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textSprites, textWidthEm, validateSequence, validateSpec };