@idle-screens/schema 3.10.0 → 3.11.0

package/FORMAT.md

@@ -45,7 +45,8 @@ the `fade` transition, `role` on text sprites, and `text: 'crossfade'` on
 sequence-level) (2026-09-10 — the print look); `timeline` (keyframes on the
 scene's own clock), paint-level layer `opacity` and `transform`,
 `position.dx` / `dy`, `wrapMorph` on the sequence envelope and
-`text: 'dip'` on `morph` (2026-09-25 — timed scenes).
+`text: 'dip'` on `morph` (2026-09-25 — timed scenes); layer `groups` and
+`transform.origin` (2026-09-26 — groups and origin).
 
 ## Safety invariants
 
@@ -111,7 +112,8 @@ must exist, have `count: 1`, and not themselves orbit a layer.
   "finish": { "grain": 0.5, "dither": 0.3 },  // optional; print screen over the finished frame
   "background": { ... },         // optional; defaults to black
   "layers": [ { ... }, ... ],    // 1..36, rendered back-to-front
-  "timeline": { ... }            // optional; authored keyframes — see **Timeline**
+  "timeline": { ... },           // optional; authored keyframes — see **Timeline**
+  "groups": { "moon": { ... } }  // optional; named paint groups — see **Groups**
 }
 ```
 
@@ -289,7 +291,8 @@ own `finish` is not steerable; steer a segment's, or republish.
 | `key` | string | none | addressable name → `setParam("key.count", …)` for a layer field, `setParam("key.sprite.color", …)` for a sprite field (the path mirrors the JSON: sprite fields sit under `sprite`) |
 | `position` | `{x, y, dx?, dy?}` — `x`/`y` 0..1, `dx`/`dy` ±2 (±17280 px under `units: "px"`) | none | exact placement; **requires `count: 1`** — except with a `list`/`table` layout, where it anchors the block's top-left; overrides `region`. `dx`/`dy` offset the point in **`min(w, h)` units** (px under `units: "px"`): `x`/`y` are fractions of width and height while every size is a fraction of `min(w, h)`, so parts placed at computed fractions only register at the aspect they were computed for — anchor a compound form's parts on one shared fraction (the centre is the only aspect-safe one) and offset each with `dx`/`dy`. Placement (structural). **Native:** tvOS ignores the offset |
 | `opacity` | number 0..1 | `1` | **paint-level** layer opacity: multiplies every entity's `alpha` and the `life` envelope at draw time. Unlike `alpha` (a range baked into each entity), it is outside the structural signature, so `setParam`, a `timeline` key or a `morph` **glides** it instead of re-seeding the layer. `0` skips the layer. **Native:** ignored ⇒ 1 |
-| `transform` | `{x?, y?, scale?, scaleX?, rotate?}` | identity | **paint-level** transform of the whole layer about the viewport centre: translate `x`/`y` (±2 in `min(w, h)` units; px under `units: "px"`, ±17280), `rotate` (degrees, ±3600), `scale` (0..8) and `scaleX` (±8, × `scale` horizontally — toward 0 reads as a turn about the vertical axis, negative mirrors). Outside the structural signature: a camera for a timed piece, a slow drift for an ambient one, and it glides under steering. Sprites are not re-rasterised, so a large `scale` enlarges pixels of soft sprites, not detail. **Native:** ignored ⇒ identity |
+| `transform` | `{x?, y?, scale?, scaleX?, rotate?, origin?}` | identity | **paint-level** transform of the whole layer, about the viewport centre — or, with `origin: "anchor"`, about the layer's own anchor (its `position` point with `dx`/`dy`; a `list`/`table` block's anchor; without `position`, the centre of its `region`), so a word scales **in place** on every aspect (`origin` is an enum: not a steer or key target, and it steps across a morph — keep one origin per layer): translate `x`/`y` (±2 in `min(w, h)` units; px under `units: "px"`, ±17280), `rotate` (degrees, ±3600), `scale` (0..8) and `scaleX` (±8, × `scale` horizontally — toward 0 reads as a turn about the vertical axis, negative mirrors). Outside the structural signature: a camera for a timed piece, a slow drift for an ambient one, and it glides under steering. Sprites are not re-rasterised, so a large `scale` enlarges pixels of soft sprites, not detail. **Native:** ignored ⇒ identity |
+| `group` | string | none | the name of a `groups` entry this layer paints through — see **Groups**. **Native:** ignored |
 
 `links`: `{ k: 1..8, maxDist, color?, alpha?, width?, mode?, falloff?, closed? }`.
 `mode: "nearest"` (default) wires each entity to its k nearest neighbors within
@@ -754,6 +757,34 @@ it genuinely cuts to a different set of layers.
 base as the piece's rest state** (its end card), and a timed piece degrades
 to a valid ambient scene.
 
+## Groups — one handle for a multi-layer subject
+
+A subject drawn from several layers (a character's body, eyes and mouth; a
+record's grooves and label) can be moved, scaled and faded as one thing:
+
+```jsonc
+"groups": { "moon": { "transform": { "scale": 1, "y": 0 }, "opacity": 1 } },
+"layers": [ { "key": "face", "group": "moon", ... }, { "key": "eyes", "group": "moon", ... } ]
+```
+
+- A member paints through its group: the group's `transform` wraps the
+  layer's own (a point lands at *group(layer(p))*), and the group's `opacity`
+  multiplies the layer's. A group's transform always turns about the viewport
+  centre — it is a camera; `origin: "anchor"` is for a layer's own transform.
+- Up to 16 groups; names are 1–32 letters, digits, `-` or `_`, starting with a
+  letter. A layer's `group` must name one of them.
+- **Paint**, outside the structural signature: `setParam("groups.moon.opacity", 0)`,
+  a `timeline` key on `groups.moon.transform.scale`, or a sequence `morph`
+  glides the whole subject — one path instead of one per layer. A group present
+  on only one end of a morph glides from the identity (no transform, opacity 1).
+- Membership is fixed per scene: `layers.N.group` is not a steer or `timeline`
+  target. A sequence `morph` where a layer joins or leaves a group glides (the
+  end without the group paints it at the identity); moving a layer from one
+  group to another steps on the morph's first frame.
+
+**Native:** ignored ⇒ identity transform, opacity 1 — author the base so the
+subject reads without the group's paint.
+
 ## Seeing without eyes — the perception API
 
 `src/perceive.ts` translates a spec into modalities a **non-vision agent** can
@@ -818,7 +849,10 @@ moves and scales its positions and sizes (sprite rotation is not modelled).
   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
   `perceiveScene().text`.)
-- `adviseSpec(spec)` — non-blocking advisories (also on
+- `adviseSpec(spec)` — non-blocking advisories (a layer whose paint opacity —
+  its own × its group's — is 0 in the base scene and at every key boundary of
+  its `timeline` never shows, so it is not judged and its entities do not count
+  toward `dense-scene`; coverage is weighed by paint opacity) (also on
   `perceiveScene().advisories`). Two of them are **spatial**, for static text:
   `text-off-screen` (a text/textBlock box crosses the viewport edge by more
   than 1%) and `text-overlap` (two static text layers share more than 10% of

package/dist/index.d.ts

@@ -52,6 +52,8 @@ interface SaverSpec {
      * ignored ⇒ the base spec (author it as the piece's rest state).
      */
     timeline?: Timeline;
+    /** Named layer groups — see `LayerGroup`. Absent ⇒ no layer is grouped (today's behaviour). */
+    groups?: Record<string, LayerGroup>;
     /** Dimensional unit system. 'viewport' (default) = all sizes/speeds/distances are fractions of min(w,h). */
     units?: 'viewport' | 'px';
     /**
@@ -161,6 +163,28 @@ interface LayerTransform {
     scale?: number;
     scaleX?: number;
     rotate?: number;
+    /**
+     * What `scale` / `scaleX` / `rotate` turn about. `'viewport'` (default) is
+     * the viewport centre — a camera move. `'anchor'` is the layer's own
+     * `position` point (with `dx`/`dy`; for a `list`/`table` layout, the block's
+     * anchor; without `position`, the centre of its `region`) — a slam word
+     * punches in place, on every aspect. Group transforms always turn about the
+     * viewport centre. **Native:** ignored with the rest of `transform`.
+     */
+    origin?: 'viewport' | 'anchor';
+}
+/**
+ * A named set of layers painted through one shared `transform` and
+ * `opacity` (`SaverSpec.groups`, joined by `LayerSpec.group`): the group's
+ * transform wraps each member's own (it turns about the viewport centre, a
+ * camera), and its opacity multiplies theirs. Paint — outside the structural
+ * signature — so a steer (`groups.<name>.transform.scale`), a `timeline` key
+ * or a `morph` glides a whole multi-layer subject as one thing. **Native:**
+ * ignored ⇒ identity, opacity 1.
+ */
+interface LayerGroup {
+    transform?: LayerTransform;
+    opacity?: number;
 }
 /** One authored key of a `Timeline`: at scene time `t` (ms), glide `path` to `value` over `dur` ms. */
 interface TimelineKey {
@@ -300,6 +324,8 @@ interface LayerSpec {
     opacity?: number;
     /** Paint-level transform of the whole layer — see `LayerTransform`. */
     transform?: LayerTransform;
+    /** The name of a `SaverSpec.groups` entry this layer is painted through (see `LayerGroup`). */
+    group?: string;
     /**
      * Inter-entity links. `mode` picks the wiring:
      * - 'nearest' (default): each entity's k nearest neighbors within maxDist.
@@ -835,6 +861,7 @@ declare const LIMITS: {
     readonly maxLayerTransformOffsetPx: 17280;
     readonly maxLayerTransformScale: 8;
     readonly maxLayerTransformRotate: 3600;
+    readonly maxGroups: 16;
     readonly maxEmitEvery: 600000;
     readonly minEmitLife: 500;
     readonly maxEmitGrow: 8;
@@ -2541,4 +2568,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, 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, 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 LayerTransform, 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 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, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, latticeHash, layerCohesion, lerpSpec, lerpValue, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, readSpecPath, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, resolveTimelineAt, revealState, rgb255Luma, rotationAt, 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, 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, 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, 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 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, fieldAt, fieldOctaves, fieldRgb, fieldRgbAt, fieldSampleTime, finishStrength, grainOffset, grainTilePixels, graphemeClusters, hasHotSwapSequence, headingAt, hexToRgb255, ignoredPropertyPaths, latticeHash, layerCohesion, lerpSpec, lerpValue, lifeAlphaAt, linkEdges, linkPairs, luminanceGrid, manifestFor, morphChainRoot, morphNothingMorphable, motionStats, nextKeyAfter, normalizeSeed, perceiveScene, perceiveSequenceFrame, pickScreenOp, positionAt, presentWithFinish, readSpecPath, renderBrailleMap, renderDensityMap, resolveSegment, resolveSpecPath, resolveTimelineAt, revealState, rgb255Luma, rotationAt, 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 };