@idle-screens/schema 3.6.1 → 3.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idle-screens/schema",
-  "version": "3.6.1",
+  "version": "3.8.0",
   "description": "Declarative, agent-authorable saver format for idle-screens: validate a data spec, then compile it into a runnable, seeded, flash-safe SaverPlugin.",
   "license": "MIT",
   "author": "Shawn Partridge",

package/saver-spec.schema.json

@@ -100,6 +100,26 @@
       },
       "description": "Animated reveal controls for a text block."
     },
+    "finish": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Print finish over the finished frame, applied last. grain (0..1): a seeded zero-mean noise tile screened at up to 35% alpha; dither (0..1): an 8x8 ordered Bayer tile at up to 25% - a stylistic screen, not per-pixel dithering. Both composite with a symmetric blend (overlay), so mean luminance is unchanged: flash-safe, and ignored by luminanceGrid. The grain tile is generated once per mount from the spec seed; animate: true steps its offset from the frame's time bucket (12 Hz, seeded), ignored on the basic/minimal tiers. Never fed back into ghosting. grain/dither are steerable paint paths (finish.grain). Native clients ignore finish.",
+      "properties": {
+        "grain": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "dither": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "animate": {
+          "type": "boolean"
+        }
+      }
+    },
     "background": {
       "oneOf": [
         {
@@ -193,6 +213,80 @@
               "description": "Slow oscillation of gradient stop positions \u2014 makes the background feel alive."
             }
           }
+        },
+        {
+          "type": "object",
+          "required": [
+            "type",
+            "scale",
+            "bands"
+          ],
+          "additionalProperties": false,
+          "description": "A scalar-field background: seeded, warped value noise quantised into bands (thermal maps, contour terrain, riso washes). Pure in (x, y, t, seed): rendered as a low-res raster (short side 96 px, 48 on basic/minimal tiers) scaled to the canvas, recomputed once per 100 ms while drifting; the perception grid samples the same function. Never touches the entity RNG. Native clients that ignore the field paint a vertical gradient through bands in order.",
+          "properties": {
+            "type": {
+              "const": "field"
+            },
+            "scale": {
+              "type": "number",
+              "minimum": 0.5,
+              "maximum": 8,
+              "description": "Noise features across the short side of the viewport."
+            },
+            "octaves": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 4,
+              "description": "Octaves of detail. Default 2."
+            },
+            "warp": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Domain-warp amount: 0 (default) round blobs, 1 smeared, folded contours."
+            },
+            "quantize": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 8,
+              "not": { "const": 1 },
+              "description": "Levels to posterise into (2..8; hard bands), or 0 for smooth interpolation between bands. Default bands.length."
+            },
+            "bands": {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 8,
+              "items": {
+                "$ref": "#/definitions/hexColor"
+              },
+              "description": "2..8 colours, read as a ramp from the field's low end to its high end."
+            },
+            "drift": {
+              "type": "object",
+              "required": [
+                "period"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "period": {
+                  "type": "number",
+                  "minimum": 10000,
+                  "description": "Full loop period in ms. Floor of 10 s (flash guard: drift is the only way a field changes over time)."
+                },
+                "amount": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 1,
+                  "description": "Radius of the sample domain's slow circle, in feature units. Default 0.3."
+                }
+              },
+              "description": "Slow travel of the sample domain \u2014 the field's animate. The field loops exactly every period."
+            },
+            "seed": {
+              "type": "number",
+              "description": "Field seed. Defaults to the spec seed; independent of the entity stream either way."
+            }
+          }
         }
       ]
     },
@@ -547,6 +641,26 @@
           },
           "description": "Sparse events: each entity appears, expands and fades in place for `life` ms every `every` ms, dark in between. The one-ping primitive; a pure function of t."
         },
+        "rotate": {
+          "description": "Static per-entity rotation in degrees (positive = clockwise). A scalar turns every entity the same way; a [min,max] range gives each entity a seeded angle. Composes with spin (added to its seeded start angle). spin: [0, 0] does NOT hold a seeded angle — a zero spin speed renders at 0. Native clients that read spin only render it as 0.",
+          "oneOf": [
+            {
+              "type": "number",
+              "minimum": -360,
+              "maximum": 360
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "number",
+                "minimum": -360,
+                "maximum": 360
+              },
+              "minItems": 2,
+              "maxItems": 2
+            }
+          ]
+        },
         "clock": {
           "type": "object",
           "additionalProperties": false,
@@ -682,6 +796,9 @@
             },
             "cycle": {
               "$ref": "#/definitions/cycle"
+            },
+            "role": {
+              "$ref": "#/definitions/textRole"
             }
           }
         },
@@ -924,8 +1041,8 @@
             "maxWidth": {
               "type": "number",
               "exclusiveMinimum": 0,
-              "maximum": 1.0,
-              "description": "Block width as a viewport fraction of min(w,h)."
+              "maximum": 2.0,
+              "description": "Wrap width as a viewport fraction of min(w,h), up to 2.0 (wider than the frame is legal; the text-off-screen advisory reports overflow)."
             },
             "fontSize": {
               "type": "number",
@@ -952,12 +1069,48 @@
             },
             "reveal": {
               "$ref": "#/definitions/textReveal"
+            },
+            "anchor": {
+              "enum": [
+                "top-left",
+                "top",
+                "top-right",
+                "left",
+                "center",
+                "right",
+                "bottom-left",
+                "bottom",
+                "bottom-right"
+              ],
+              "description": "Which point of the rendered text (widest line × lines·lineHeight, as align lays it out) position names. Absent: position is the top-left of the maxWidth layout box (today's behaviour). 'center' centres the block at position on every aspect ratio. Placement (structural). Native clients without anchor render as absent."
+            },
+            "font": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?!.*\\d(?:px|pt|pc|em|rem|ex|ch|vw|vh|vmin|vmax|%)).*$",
+              "description": "CSS font family and/or weight/style only, e.g. 'bold monospace' or \"300 'Inter', sans-serif\" — a size inside it is rejected (fontSize owns size). A monospace family switches the line-breaker to a uniform advance. Default 'system-ui, sans-serif'; native clients fall back to the system face."
+            },
+            "opacity": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Paint-level alpha multiplier for the block (default 1). Not structural — steer it with dur to fade the block in or out without a rebuild. Declare it to make the path steerable. Native clients without it render at 1."
+            },
+            "role": {
+              "$ref": "#/definitions/textRole"
             }
           },
-          "description": "Multi-line text block with deterministic line-breaking. All dimensions are viewport fractions. Use with count: 1, static motion, and position."
+          "description": "Multi-line text block with deterministic line-breaking. All dimensions are viewport fractions. Use with count: 1, static motion, and position; add anchor: 'center' to centre the block at position."
         }
       ]
     },
+    "textRole": {
+      "enum": [
+        "read",
+        "atmosphere"
+      ],
+      "description": "What the text is for. 'read' opts the layer into the legibility advisories (text-legibility: WCAG ratio below 4.5:1 against the background at the box centre or against the brightest additive layer over it; text-safe-area: box within 5% of an edge). 'atmosphere' (or absent) keeps it silent. A declaration only — changes no pixel on any client."
+    },
     "colorWeights": {
       "type": "array",
       "minItems": 1,
@@ -1370,6 +1523,9 @@
         "background": {
           "$ref": "#/definitions/background"
         },
+        "finish": {
+          "$ref": "#/definitions/finish"
+        },
         "layers": {
           "type": "array",
           "minItems": 1,
@@ -1423,6 +1579,21 @@
           "type": "boolean",
           "description": "When true, global time wraps over the sum of segment durations. Requires every segment to have a duration."
         },
+        "sync": {
+          "enum": [
+            "mount",
+            "epoch"
+          ],
+          "description": "What the sequence clock is anchored to. 'mount' (default): every viewer starts at T = 0 when it mounts — a joiner sees segment 0 (pre-roll semantics). 'epoch': a viewer handed sequenceBaseT on its mount context (the host's Date.now() − epoch) starts its clock there, so every screen shows the same segment; a late joiner lands mid-loop. advance: 'input' holds stay armed under either. Native clients that anchor at their own mount behave as 'mount'."
+        },
+        "bed": {
+          "$ref": "#/definitions/saverSpec",
+          "description": "A scene drawn under every segment on the sequence's global clock — the ground that does not reset at a boundary or under a sequence.segment steer. Segments render over it transparently (their background and ghosting are ignored; validateSequence warns bed-hides-segment-background). Its entities plus the largest segment's must stay within the 800 cap (enforced by validateSequence). Steer it with bed.<path>. Native clients that ignore it render segments with their own backgrounds."
+        },
+        "finish": {
+          "$ref": "#/definitions/finish",
+          "description": "A print finish applied once per composed frame (bed + segment + fade) on the sequence's presentation canvas. Overrides every segment's own finish while set; absent, the active segment's finish applies. A bed's finish is ignored. Native clients ignore it."
+        },
         "segments": {
           "type": "array",
           "minItems": 1,
@@ -1463,7 +1634,7 @@
             "input",
             "either"
           ],
-          "description": "How the segment advances. Validated; runtime drivers planned for a follow-up."
+          "description": "How the segment advances. 'auto' (default) and 'either' advance on the timer; 'input' holds a timed segment at the end of its duration (the scene keeps animating) until a sequence.segment steer releases it — the clicker. A durationless final segment holds regardless."
         },
         "transition": {
           "type": "object",
@@ -1485,6 +1656,23 @@
                   "minimum": 200,
                   "maximum": 5000,
                   "description": "Morph glide duration in ms. Requires structurally identical adjacent segments."
+                },
+                "text": {
+                  "enum": ["step", "crossfade"],
+                  "description": "How text / textBlock strings change during the morph. 'step' (default, today's behaviour): the incoming string shows from the first frame. 'crossfade': each text layer whose string(s) differ is drawn twice for dur — the outgoing words at 1 − k, the incoming at k (k = the eased progress). Native clients step (tvOS already cross-fades whole frames on a segment change)."
+                }
+              },
+              "required": ["type", "dur"],
+              "additionalProperties": false
+            },
+            {
+              "properties": {
+                "type": { "const": "fade" },
+                "dur": {
+                  "type": "number",
+                  "minimum": 200,
+                  "maximum": 5000,
+                  "description": "Cross-fade duration in ms: the outgoing segment keeps animating on its own canvas and is composited over the incoming one at 1 − easeSmooth(localT / dur). No structural requirement. Hosts on the 'basic' or 'minimal' capability tier render it as cut."
                 }
               },
               "required": ["type", "dur"],