@idle-screens/schema 3.8.0 → 3.9.1

package/FORMAT.md

@@ -678,6 +678,9 @@ interpolation, and background drift is sampled at rest. These are documented
 trade-offs for a zero-dependency, renderer-free analysis tool.
 
 - `perceiveScene(spec, {t?, viewport?, seed?})` — one-call bundle: everything below.
+  **`t` is in milliseconds** (the MCP `previewScene` tool takes seconds and
+  converts; passing seconds here reads a self-typing block as one that never
+  finishes typing).
 - `perceiveSequenceFrame(seq, T, {viewport?, seed?, releasedBelow?})` — the
   same bundle for one frame of a **sequence** at global time `T`: resolves the
   segment (reported as `segment: {index, key, localT, held?}`) and, when the

package/dist/index.d.ts

@@ -843,6 +843,13 @@ interface IdleSequence {
 }
 
 declare function validateSpec(spec: unknown): ValidationResult;
+/**
+ * Dot-paths (numeric layer indices, as `steerablePaths` spells them) of every
+ * property the validator flags as unknown or misplaced — i.e. fields the
+ * renderer never reads, so steering them does nothing. Pure: unlike
+ * `validateSpec` it never normalises colours into the caller's spec.
+ */
+declare function ignoredPropertyPaths(spec: unknown): string[];
 /** Narrowing helper: validate + cast. Throws with a joined message when invalid. */
 declare function assertValidSpec(spec: unknown): SaverSpec;
 /**
@@ -1235,6 +1242,12 @@ declare function morphNothingMorphable(a: SaverSpec, b: SaverSpec, opts?: {
  * (id, label, schemaVersion, seed, units, kind, type, key) are excluded —
  * they describe structure, not tuneable values.
  *
+ * Properties the validator flags as unknown or misplaced (e.g. `angle` on a
+ * gradient background, `blend` inside a sprite) are excluded too: the
+ * renderer never reads them, so advertising them invites a steer that
+ * silently does nothing. Same source of truth as validateSpec's
+ * "will be ignored" warnings (`ignoredPropertyPaths`).
+ *
  * Layer keys are NOT substituted: paths always use numeric indices.
  * Consumers can map to key-based paths via resolveSpecPath if needed.
  */
@@ -1894,6 +1907,14 @@ declare function segmentRenderSeed(seq: IdleSequence, index: number): number | u
  * `SpecInstance`. `undefined` when there's no bed or no derivable seed.
  */
 declare function bedRenderSeed(seq: IdleSequence): number | undefined;
+/**
+ * Whether any scene in the sequence — the sequence itself or any segment —
+ * declares a `finish`. Mirrors `SequenceInstance`'s construction-time check:
+ * a finish anywhere allocates the presentation pass for the instance's whole
+ * lifetime, so this is also what `sequenceSwapCompatible` must agree on
+ * before and after a swap.
+ */
+declare function sequenceWantsFinish(seq: IdleSequence): boolean;
 /**
  * Whether a republished sequence can be swapped into a live
  * `SequenceInstance` in place of `prev` without a remount
@@ -1909,6 +1930,19 @@ declare function bedRenderSeed(seq: IdleSequence): number | undefined;
  *   the next boundary, leaving the room half-swapped;
  * - a `bed` on both sides or neither, structural twins with the same seed
  *   when present;
+ * - the same top-level `seq.seed`, compared normalized (like the mount-time
+ *   seed itself) so a change of an exact multiple of 2^32 isn't flagged —
+ *   but ONLY when either side has a sequence-level `finish`: that's the one
+ *   place `seq.seed` reaches rendering on its own (`frameFinishSeed` uses the
+ *   instance's mount-time seed for a sequence-level finish's grain, which a
+ *   swap cannot update). Without a sequence-level `finish`, every consumer of
+ *   `seq.seed` is a `segmentRenderSeed`/`bedRenderSeed` fallback, and those
+ *   are already compared per segment and for the bed below — so when every
+ *   segment and the bed carry their own seed, `seq.seed` is dead weight and
+ *   changing it is free;
+ * - the same finish presence (`sequenceWantsFinish`) — the presentation
+ *   pass is allocated once at construction, so a swap that adds or removes
+ *   every `finish` in the sequence cannot (de)allocate it;
  * - the same `loop` and `sync` (absent `sync` is `'mount'`);
  * - the same `duration`, `advance` (absent is `'auto'`) and `transition`
  *   (absent is `cut`; `text` on a morph defaults to `'step'`) on every
@@ -2114,6 +2148,164 @@ declare const WARP_TUNNEL_SPEC: SaverSpec;
  */
 declare const THERMAL_FIELD_SPEC: SaverSpec;
 
+/**
+ * Sparse Night — emptiness, declared as intent.
+ * A star-grain field (radius under 0.001 — the rung FORMAT.md's ladder calls
+ * texture, never the subject) over near-black, one faint linked pentagon as
+ * the only figure, and a single satellite that flares for three seconds out of
+ * every eighteen. Measured coverage sits around one percent, which `adviseSpec`
+ * would flag as `sparse-scene` at every legal count — the spec's
+ * `density: 'sparse'` declaration is the point of this example: it withholds
+ * that advisory AND opts the scene into `density-mismatch` instead, so the
+ * emptiness is a claim the perception API checks rather than a gap it nags
+ * about. Before `density` shipped, restraint like this could not pass advise
+ * clean; the one-mark house style sat at the suite floor for exactly this
+ * reason.
+ */
+declare const SPARSE_NIGHT_SPEC: SaverSpec;
+
+/**
+ * Typed Cue — textBlock.reveal, both moods.
+ * Two self-typing captions over near-black. The upper one types at ten
+ * graphemes a second with a blinking caret (`mode: 'typewriter'` — the classic
+ * terminal reveal; `speed` makes progress a pure function of scene time, so
+ * every viewer types the same line on the same clock from its own mount). The
+ * lower one arrives as a wave of overlapping fades (`mode: 'glyphFade'`,
+ * `fade: 0.4` — each glyph ramps in over 40% of the progress window, which
+ * reads as a soft dissolve rather than typing) and carries no caret. Both
+ * blocks declare `opacity` so the path is steerable, and layout always runs on
+ * the FULL text — reveal only masks glyphs, so lines never reflow mid-type.
+ *
+ * Trap, documented in the playbook and true here too: at t = 0 a self-typing
+ * block has typed nothing, so `previewScene` at the default instant looks
+ * empty — preview at t ≥ 10 s to see the words. To swap the line live, glide
+ * `reveal.progress` to 0, step the `text`, glide back (one `setTrack` call).
+ *
+ * The scan band is the one non-text layer, and it is load-bearing twice over:
+ * a screensaver of two static text blocks is a document, not a screensaver
+ * (`text-heavy`), and the band gives the words something to sit on — a slow
+ * refresh sweep passing under the type. Note the units: `perceiveScene` takes
+ * `t` in MILLISECONDS while the MCP `previewScene` tool takes seconds (the
+ * worker converts); passing seconds to the library reads as a block that
+ * never finishes typing.
+ */
+declare const TYPED_CUE_SPEC: SaverSpec;
+
+/**
+ * Signal Board — the instrument panel, laid out by the format.
+ * A 3×3 table of data bars with their labels in a matching table, one
+ * monospace caption, and a phosphor sweep crossing the frame every ~90
+ * seconds. The teaching layer is `layout: { type: 'table', columns: 3 }`:
+ * nine bars and nine labels are TWO layers, not eighteen positioned blocks —
+ * entity i reads `values[i]` / `strings[i]` in reading order, and each bar
+ * draws `length × values[i] / max` from its cell. `values` are paint, so
+ * `setParam("readout.sprite.values", [...])` glides every bar at once, which
+ * is the whole point of the shape: a live readout that never re-publishes.
+ */
+declare const SIGNAL_BOARD_SPEC: SaverSpec;
+
+/**
+ * Phase Duet — three layers on one clock.
+ * A grid of sixty dots ripples as a traveling wave (`pulse.wave`), three rings
+ * swell, and one soft heart breathes — and none of them drift apart, because
+ * all three declare the same `clock`. `clock` is the format's answer to
+ * coincidence: without it, `pulse`, `grow` and `cycle` run on per-entity
+ * seeded phases, so two layers with the same period never line up (they are
+ * a room full of people, not a duet). With one shared `clock: { phase: 0,
+ * rate: 1 }` they breathe in step and stay there — period ÷ rate must stay
+ * ≥ 1000 ms, which is why every layer here runs a 6000 ms cycle.
+ */
+declare const PHASE_DUET_SPEC: SaverSpec;
+
+/**
+ * Web Work — a randomised graph that fades with distance.
+ * Forty-four drifting nodes wired `mode: 'random'` (a fixed deterministic
+ * wiring, not k-nearest — the difference is topology: nearest gives
+ * crystalline clusters, random gives a web that crosses itself) with
+ * `falloff: true`, so an edge's alpha fades toward `maxDist` instead of
+ * popping in at the cutoff. The second layer is a row of `orient: true`
+ * strokes: the mark's +x axis turns to follow the entity's heading, so each
+ * one reads as a wind tick rather than a stamp. Both are the difference
+ * between "lines between dots" and a drawing.
+ */
+declare const WEB_WORK_SPEC: SaverSpec;
+
+/**
+ * Shard Fall — tumbling shapes and a passing shadow.
+ * Two features nothing else here uses. `rotate` is STATIC per-entity rotation
+ * (a range seeded per entity), which is not the same as `spin: [0, 0]` — a
+ * zero spin speed renders the seeded start angle as 0, so "tilted but not
+ * turning" was previously inexpressible; here the shards are thrown at
+ * `rotate: [-180, 180]` AND tumbling on their own `spin` range, so no two
+ * facets agree on an angle. The shadow layer demonstrates `blend:
+ * 'multiply'`: two large soft discs darkening a pale plate as they wander,
+ * which is how the format does shadow and silhouette — `lighter` adds light,
+ * `multiply` removes it, and neither needs a sprite that looks like darkness.
+ * The polygons use `points` (unit coordinates scaled by `radius`), which are
+ * paint, so two shards with the same point count will morph into each other.
+ */
+declare const SHARD_FALL_SPEC: SaverSpec;
+
+/**
+ * Murmur — a flock with no birds in it.
+ * Six hundred and twenty entities: two registers of streaks (260 each) on
+ * harmonic `wander` with `coherence` near 1, so each layer folds and wheels as
+ * one body, and a static grain layer behind them. Nothing here
+ * interacts — no entity reads another's position — which is the trick the
+ * format is built on: a shared harmonic set plus a wide speed range reads as
+ * a murmuration while staying a pure function of (seed, t), so it replays
+ * identically and seeks instantly. `density: 'dense'` is doing real work:
+ * past 500 entities `adviseSpec` raises `dense-scene`, and the declaration
+ * says the crowding is the subject rather than a mistake — while still opting
+ * into `density-mismatch` if the scene ever measures as empty instead.
+ */
+declare const MURMUR_SPEC: SaverSpec;
+
+/**
+ * Three Movements — one ground, three scenes, two kinds of transition.
+ *
+ * The sequence envelope, exercised end to end:
+ *
+ * - **bed.** A drifting field with a few motes, drawn under every segment on
+ *   the SEQUENCE clock — it does not reset at a boundary and a
+ *   `sequence.segment` steer cannot rewind it. That is the fix for the
+ *   boundary rewind every ambient sequence suffers: put the motion that must
+ *   be continuous in the bed, the slide content in the segments. (Segments
+ *   deliberately declare no `background`: over a bed it is never painted on
+ *   the web, and the validator warns `bed-hides-segment-background` — the
+ *   native tvOS player, which ignores the bed, will show them over black
+ *   until it learns the field. Prefer a bed the piece can survive without.)
+ * - **morph + text crossfade.** Segments 1 → 2 are structural twins differing
+ *   only in colour and words, so the transition can MORPH: every numeric and
+ *   hex value glides over 2500 ms, and because the words differ and the
+ *   transition declares `text: 'crossfade'`, the outgoing caption fades under
+ *   the incoming one instead of switching whole-frame. Without the crossfade
+ *   declaration the morph would still glide — colour alone gives it a
+ *   `hasGlide` — just with the caption stepping on the first frame instead of
+ *   fading; the validator only says `morph-nothing-morphable` for a pair
+ *   whose differences are all values morph cannot glide — strings
+ *   (`textBlock.text` above all), booleans, mismatched arrays — which this
+ *   one isn't.
+ * - **fade.** Segments 2 → 3 have nothing structurally in common, so a morph
+ *   is impossible and a `fade` is the honest transition: the outgoing scene
+ *   keeps animating on its own canvas for 3000 ms while the incoming one
+ *   fades up. The cost is two live segments during the window, which is why
+ *   the lowest capability tier degrades a fade to a cut
+ *   (`fade-degrades-on-low-tier` — informational, and this sequence keeps the
+ *   fade because the web and native players both honour it).
+ * - **finish.** One grain-and-dither pass over the composed frame — bed,
+ *   segment and any fade together — the sequence-level screen no segment can
+ *   override.
+ *
+ * The final segment carries no duration, so it holds indefinitely; `loop` is
+ * therefore false (`loop: true` is incompatible with a durationless segment).
+ * `sync: 'mount'` is the default and the reason a joiner always sees movement
+ * one: pre-roll semantics. An `epoch` sequence would instead start every
+ * viewer at the room's shared clock — right for a wall of screens, wrong for
+ * a piece that should start when you look at it.
+ */
+declare const THREE_MOVEMENTS_SEQUENCE: IdleSequence;
+
 /** Catalog entry for a bundled schema example. */
 interface SchemaExample {
     id: string;
@@ -2122,9 +2314,24 @@ interface SchemaExample {
 }
 /** Ordered catalog of bundled schema examples. Add new specs as standalone files, then register here. */
 declare const SCHEMA_EXAMPLES: readonly SchemaExample[];
+/** Catalog entry for a bundled idle-sequence example. */
+interface SequenceExample {
+    id: string;
+    label: string;
+    sequence: IdleSequence;
+}
+/**
+ * Ordered catalog of bundled idle-sequence examples.
+ *
+ * Deliberately separate from SCHEMA_EXAMPLES: that catalog is typed
+ * `SaverSpec[]` and its consumers (manifests, batch compile, the MCP examples
+ * resource) rely on that. A sequence is a different top-level format, so it
+ * gets its own list rather than widening theirs.
+ */
+declare const EXAMPLE_SEQUENCES: readonly SequenceExample[];
 /** All example specs in catalog order (tests, batch compile). */
 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, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, type CapabilityTier, type CohesionRead, type CycleSpec, DASHBOARD_SPEC, DITHER_ALPHA, DITHER_TILE, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SPECS, type Entity, FACETS_SPEC, FIELD_BUCKET_MS, FIELD_DRIFT_DEFAULT_AMOUNT, FIELD_RASTER_SHORT_SIDE, FIELD_RASTER_SHORT_SIDE_LOW, FINISH_ANIMATE_HZ, type FieldBackground, type FieldDrift, type FinishPass, type FinishSpec, GRAIN_ALPHA, GRAIN_TILE, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, 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 PerceiveSequenceOptions, 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 ScreenOp, type SequenceFramePerception, type SequenceMountContext, type SequenceSaverInstance, type SequenceSaverPlugin, type SequenceSegment, type SequenceTransition, type SpecError, type SpecMountContext, type SpecWarning, type SpriteSpec, type SteerDelta, THERMAL_FIELD_SPEC, type TextBlockAnchor, type TextBlockLine, type TextMetricsClass, type TextRevealInput, type TextRevealSpec, type TextRole, type TextSpriteInfo, type ValidationResult, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, type WanderOsc, type WarningBox, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, bayerMatrix, bayerTilePixels, bedRenderSeed, breakTextBlock, buildEntities, canMorph, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, latticeHash, layerCohesion, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, normalizeSeed, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rgb255Luma, rotationAt, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, validateSequence, validateSpec };
+export { AQUARIUM_SPEC, AURORA_SPEC, type BackgroundDrift, type BackgroundSpec, type BandSpec, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, type CapabilityTier, type CohesionRead, type CycleSpec, DASHBOARD_SPEC, DITHER_ALPHA, DITHER_TILE, type DominanceEntry, EXAMPLE_BY_ID, EXAMPLE_SEQUENCES, EXAMPLE_SPECS, type Entity, FACETS_SPEC, FIELD_BUCKET_MS, FIELD_DRIFT_DEFAULT_AMOUNT, FIELD_RASTER_SHORT_SIDE, FIELD_RASTER_SHORT_SIDE_LOW, FINISH_ANIMATE_HZ, type FieldBackground, type FieldDrift, type FinishPass, type FinishSpec, GRAIN_ALPHA, GRAIN_TILE, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, type LayerCohesion, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, MURMUR_SPEC, type MotionEase, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PerceiveOptions, type PerceiveSequenceOptions, type Placed, RAIN_SPEC, RELAY_BOARD_SPEC, type ResolveOptions, type ResolvedSegment, type RevealState, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SHARD_FALL_SPEC, SIGNAL_BOARD_SPEC, SNOWFALL_SPEC, SPARSE_NIGHT_SPEC, type SaverSpec, type SceneDescription, type SceneDiff, type ScenePerception, type SceneSnapshot, type SchemaExample, type ScreenOp, type SequenceExample, type SequenceFramePerception, type SequenceMountContext, type SequenceSaverInstance, type SequenceSaverPlugin, type SequenceSegment, type SequenceTransition, type SpecError, type SpecMountContext, type SpecWarning, type SpriteSpec, type SteerDelta, THERMAL_FIELD_SPEC, THREE_MOVEMENTS_SEQUENCE, TYPED_CUE_SPEC, type TextBlockAnchor, type TextBlockLine, type TextMetricsClass, type TextRevealInput, type TextRevealSpec, type TextRole, type TextSpriteInfo, type ValidationResult, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, WEB_WORK_SPEC, type WanderOsc, type WarningBox, adviseSequence, adviseSpec, alphaAt, applyDeltasToSpec, assertValidSequence, assertValidSpec, bayerMatrix, bayerTilePixels, bedRenderSeed, breakTextBlock, buildEntities, canMorph, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, latticeHash, layerCohesion, lerpSpec, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, normalizeSeed, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, revealState, rgb255Luma, rotationAt, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, validateSequence, validateSpec };