@idle-screens/schema 3.13.0 → 3.14.0

package/FORMAT.md

@@ -490,7 +490,9 @@ for `"nearest"` and `"random"`; a `"chain"` may omit both, except that
   across the room, and opts that layer into two advisories:
   `text-legibility` fires when the text colour's WCAG ratio falls below
   **4.5:1** against the background sampled at the box centre (gradient stops
-  interpolated at rest, `band` honoured) **or** against the brightest
+  interpolated at rest, `band` honoured) — or, where an earlier static,
+  hard-edged, unblended layer covers the whole box (a backing chip), against
+  that layer composited over the page — **or** against the brightest
   additive layer (`blend: lighter` / `screen`) whose entities can reach the
   box and are at least a glyph tall, taken at its peak alpha (base + pulse)
   composited over that background — a glow parked under a caption is
@@ -809,7 +811,16 @@ its drift, orbit and pulse run on (from mount; a sequence segment's `localT`):
   Keys are also checked **together**: two keys that are each valid can
   combine past a floor (a `clock.rate` and a `pulse.period` share one), so
   the validator resolves the scene at every key's start, end and glide
-  quarter-points and rejects it there.
+  quarter-points and rejects it there. Paint keys on different paths can
+  also combine into a faster flicker than any one path allows: a top
+  layer's `opacity` switching between its own colour and the colour
+  beneath, each keyed at the floor and out of step, flickers the whole
+  frame 5 times a second. So where any one second holds 7 or more key
+  boundaries on paint paths (opacity, alpha, colours, stops, gradients,
+  strokes), publishing resolves the frame there and refuses more than 3
+  flashes a second over a quarter of the screen (WCAG 2.3.1,
+  `timelineFlashReport`). Keep big brightness changes at least ~170 ms
+  apart across the whole frame, not just per path.
 - A key on a **structural** path rebuilds the scene at that key — a pop, and
   the validator warns `timeline-structural-key`. Animate paint: colours,
   `opacity`, `transform`, polygon `points` (a whole equal-length array
@@ -962,14 +973,25 @@ moves and scales its positions and sizes (sprite rotation is not modelled).
   will look wrong on the wall; one that passes may still sit a few px off.
   Two more are **opt-in** through the text sprite's `role: "read"` (see the
   `textBlock` sprite): `text-legibility` (WCAG ratio below 4.5:1 against the
-  background at the box centre or under the brightest additive layer that can
-  sit beneath the line) and `text-safe-area` (the box within 5 % of an edge,
+  background at the box centre, or the solid chip painted under the whole box,
+  or under the brightest additive layer that can sit beneath the line) and `text-safe-area` (the box within 5 % of an edge,
   with its box in `boxes`). Undeclared text is never measured for either.
   `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.
+  never fires under `blend: lighter` / `screen`. Nor does it fire when the
+  only seam is a multi-colour palette and the shapes bury their neighbours'
+  outlines but under 15 % of their area — rows or tiles butted edge to edge
+  (overlapping by a hairline to hide the gap) are banding, not a pile. No
+  shipped example trips it.
+  `motion-intensity-mismatch` fires when a scene declares
+  `motionIntensity: "calm"` but a layer of shapes, glyphs or text spins
+  faster than 90°/s on average (shipped calm spins stay at or under 32°/s).
+  `flash-near-limit` fires when a timeline's luminance keys, resolved over
+  their densest one-second window, flicker at least 2 times a second over a
+  quarter of the frame — a full-frame step at the 200 ms key floor is 2.5, which
+  the publish-time WCAG gate (more than 3) lets through.
   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

package/dist/index.d.ts

@@ -1444,6 +1444,16 @@ interface SteerDelta {
 }
 /** Apply deltas to a deep copy of the spec (last-wins, target values). */
 declare function applyDeltasToSpec(spec: SaverSpec, deltas: SteerDelta[]): SaverSpec;
+/**
+ * `applyDeltasToSpec` for read-only callers: the same result, but every
+ * subtree a delta does not touch is shared with `spec` — only the containers
+ * on each delta's path are copied. The validator checks a timeline by applying
+ * each key, and the composed keys at every sample time, to the whole spec; a
+ * full deep copy per check was most of the cost of validating a long timeline
+ * (a 132 KB scene spent ~60% of its CPU in JSON round-trips). The result
+ * aliases `spec`, so it must never be mutated.
+ */
+declare function applyDeltasShared(spec: SaverSpec, deltas: SteerDelta[]): SaverSpec;
 /**
  * Interpolate between two structurally-similar specs at progress k (0..1).
  * Numbers lerp, hex colours lerp per channel, everything else steps to the
@@ -1616,12 +1626,25 @@ declare function cohesionOf(layers: Array<{
     layer: LayerSpec;
     entities: Entity[];
 }>, t: number, w: number, h: number): LayerCohesion[];
+/**
+ * Mean fraction of an entity's filled AREA covered by a same-layer sibling,
+ * 0..1 — the counterpart of `overlap`, which measures outline. Edge contact
+ * buries outline and no area; a real pile buries both. `null` where
+ * `cohesionOf` reports no overlap.
+ */
+declare function buriedAreaOf(layer: LayerSpec, entities: Entity[], t: number, w: number, h: number): number | null;
 /**
  * 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.
+ *
+ * `buriedArea` (lazy, from {@link buriedAreaOf}) lets it also stay off a
+ * TILING whose only seam is its palette: opaque hard tiles of unlike colour
+ * that butt edge to edge show one clean colour boundary per join, which is
+ * the banding the author drew (X574). A translucent tiling is still warned
+ * about — each hairline overlap paints a darker line.
  */
-declare function seamsWorthWarning(layer: LayerSpec, c: LayerCohesion, entityCount: number): boolean;
+declare function seamsWorthWarning(layer: LayerSpec, c: LayerCohesion, entityCount: number, buriedArea?: () => number | null): boolean;
 
 interface LayerSnapshot {
     key: string | undefined;
@@ -2027,6 +2050,20 @@ interface PerceiveSequenceOptions extends Omit<LuminanceGridOptions, 't'> {
  */
 declare function perceiveSequenceFrame(seq: IdleSequence, T: number, opts?: PerceiveSequenceOptions): SequenceFramePerception;
 
+interface TimelineFlashReport {
+    /** More than 3 flashes in some one-second window over at least a quarter of the frame (WCAG 2.3.1). */
+    fails: boolean;
+    /** Worst flashes per second any part of the frame reaches (0 when nothing was dense enough to check). */
+    flashesPerSecond: number;
+    /** Fraction of the frame flashing more than 3 times a second. */
+    flashingArea: number;
+    /** Start (scene ms, within the lap) of the worst window checked, or null when none was checked. */
+    at: number | null;
+    /** Set (with `fails`) when dense sections remained beyond the {@link MAX_TOTAL_SAMPLES} budget: unchecked is never reported as safe. */
+    incomplete?: true;
+}
+declare function timelineFlashReport(spec: SaverSpec): TimelineFlashReport;
+
 /**
  * The `field` background sampler — seeded, dependency-free value noise that
  * is a PURE function of `(u, v, t, config, seed)`.
@@ -2352,8 +2389,9 @@ declare function timelineLocalTime(tl: Timeline, t: number): number;
  * The scene at time `t` with every key applied — and without its `timeline`,
  * so the result can be rendered, perceived, lerped or steered like any plain
  * spec. A spec without a timeline comes back as the same object.
+ * `shared` (read-only callers): untouched subtrees alias `spec` — never mutate the result.
  */
-declare function resolveTimelineAt(spec: SaverSpec, t: number): SaverSpec;
+declare function resolveTimelineAt(spec: SaverSpec, t: number, shared?: boolean): SaverSpec;
 /**
  * When the timeline next takes a path back: the scene time of that path's
  * next key after `t`, and that key's glide length — or null when no key will
@@ -2838,4 +2876,5 @@ declare function pathFrame(s: PolygonSprite, r: number, w: number, h: number): {
     uniform: boolean;
 };
 
-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, DEFAULT_KEY_DUR, 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, type FlattenedPath, GRAIN_ALPHA, GRAIN_TILE, type GradientStop, HAIKU_SPEC, type IdleSequence, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, type LayerCohesion, type LayerGroup, type LayerMotionStats, type LayerSnapshot, type LayerSpec, type LayerTransform, type LinkEdge, type LuminanceGrid, type LuminanceGridOptions, MATRIX_RAIN_SPEC, MAX_PATH_POINTS, MURMUR_SPEC, type MotionEase, type MotionSpec, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, type PathGradient, type PathGradientStop, type PathPart, type PathStroke, type PerceiveOptions, type PerceiveSequenceOptions, type Placed, RAIN_SPEC, RELAY_BOARD_SPEC, type ResolveOptions, type ResolvedPart, type ResolvedSegment, type RevealState, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SHARD_FALL_SPEC, SIGNAL_BOARD_SPEC, SNOWFALL_SPEC, SPARSE_NIGHT_SPEC, type SaverSpec, type SceneColour, 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 Timeline, type TimelineKey, 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, canWrapMorph, canonicalSpecPath, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, entityScales, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, flattenPath, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, isPathPolygon, latticeHash, layerCohesion, lerpPathD, lerpSpec, lerpValue, lifeAlphaAt, linkEdges, linkMaxDistPx, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, pathFrame, pathParts, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, readSpecPath, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, resolveTimelineAt, revealState, rgb255Luma, rotationAt, sceneColour, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, timelineLocalTime, timelineSampleTimes, timelineSampleTimesAfter, timelineTracks, validateSequence, validateSpec, validateSpecPaths, withoutTimeline };
+export { AQUARIUM_SPEC, AURORA_SPEC, COHESION_T, COMETS_SPEC, CONSTELLATION_SPEC, DASHBOARD_SPEC, DEFAULT_KEY_DUR, DITHER_ALPHA, DITHER_TILE, EXAMPLE_BY_ID, EXAMPLE_SEQUENCES, EXAMPLE_SPECS, FACETS_SPEC, FIELD_BUCKET_MS, FIELD_DRIFT_DEFAULT_AMOUNT, FIELD_RASTER_SHORT_SIDE, FIELD_RASTER_SHORT_SIDE_LOW, FINISH_ANIMATE_HZ, GRAIN_ALPHA, GRAIN_TILE, HAIKU_SPEC, LANTERNS_SPEC, LIMITS, LOBBY_TALK_SPEC, MATRIX_RAIN_SPEC, MAX_PATH_POINTS, MURMUR_SPEC, NOSTALGHIA_CANDLE_SPEC, ORRERY_SPEC, PHASE_DUET_SPEC, PINGS_SPEC, POLYGONS_SPEC, PROCESSION_SPEC, RAIN_SPEC, RELAY_BOARD_SPEC, SAKURA_SPEC, SCHEMA_EXAMPLES, SCHEMA_VERSION, SHARD_FALL_SPEC, SIGNAL_BOARD_SPEC, SNOWFALL_SPEC, SPARSE_NIGHT_SPEC, THERMAL_FIELD_SPEC, THREE_MOVEMENTS_SEQUENCE, TYPED_CUE_SPEC, WARP_MAX_SCALE, WARP_NEAR, WARP_TUNNEL_SPEC, WEB_WORK_SPEC, adviseSequence, adviseSpec, alphaAt, applyDeltasShared, applyDeltasToSpec, assertValidSequence, assertValidSpec, bayerMatrix, bayerTilePixels, bedRenderSeed, breakTextBlock, buildEntities, buriedAreaOf, canMorph, canWrapMorph, canonicalSpecPath, cohesionOf, compileSaver, compileSequence, createFinishPass, createSceneCanvas, describeScene, diffScenes, dominanceRanking, easeSmooth, emitEnvelope, emitWindow, entityScales, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, flattenPath, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, isPathPolygon, latticeHash, layerCohesion, lerpPathD, lerpSpec, lerpValue, lifeAlphaAt, linkEdges, linkMaxDistPx, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, pathFrame, pathParts, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, readSpecPath, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, resolveTimelineAt, revealState, rgb255Luma, rotationAt, sceneColour, seamCauseOf, seamsWorthWarning, segmentRenderSeed, segmentStart, sequenceSteerablePaths, sequenceSwapCompatible, sequenceWantsFinish, sizeAt, spriteIndexAt, spriteVariants, steerablePaths, structuralSignature, textBlockAnchorOffset, textMetricsClassFor, textSprites, textStringsDiffer, textStringsOf, textWidthEm, timelineFlashReport, timelineLocalTime, timelineSampleTimes, timelineSampleTimesAfter, timelineTracks, validateSequence, validateSpec, validateSpecPaths, withoutTimeline };
+export type { BackgroundDrift, BackgroundSpec, BandSpec, CapabilityTier, CohesionRead, CycleSpec, DominanceEntry, Entity, FieldBackground, FieldDrift, FinishPass, FinishSpec, FlattenedPath, GradientStop, IdleSequence, LayerCohesion, LayerGroup, LayerMotionStats, LayerSnapshot, LayerSpec, LayerTransform, LinkEdge, LuminanceGrid, LuminanceGridOptions, MotionEase, MotionSpec, PathGradient, PathGradientStop, PathPart, PathStroke, PerceiveOptions, PerceiveSequenceOptions, Placed, ResolveOptions, ResolvedPart, ResolvedSegment, RevealState, SaverSpec, SceneColour, SceneDescription, SceneDiff, ScenePerception, SceneSnapshot, SchemaExample, ScreenOp, SequenceExample, SequenceFramePerception, SequenceMountContext, SequenceSaverInstance, SequenceSaverPlugin, SequenceSegment, SequenceTransition, SpecError, SpecMountContext, SpecWarning, SpriteSpec, SteerDelta, TextBlockAnchor, TextBlockLine, TextMetricsClass, TextRevealInput, TextRevealSpec, TextRole, TextSpriteInfo, Timeline, TimelineFlashReport, TimelineKey, ValidationResult, WanderOsc, WarningBox };