@idle-screens/schema 3.4.5 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idle-screens/schema",
-  "version": "3.4.5",
+  "version": "3.6.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",
@@ -42,11 +42,11 @@
     "FORMAT.md"
   ],
   "peerDependencies": {
-    "@idle-screens/core": "^0.4.5"
+    "@idle-screens/core": "^0.4.7"
   },
   "devDependencies": {
     "ajv": "^8.17.1",
-    "@idle-screens/core": "0.4.5"
+    "@idle-screens/core": "0.4.7"
   },
   "scripts": {
     "build": "tsup",

package/saver-spec.schema.json

@@ -389,49 +389,131 @@
           "description": "Draw lines between entities. The layer's entity count (count field) must be <= 200 for performance."
         },
         "layout": {
-          "type": "object",
-          "required": [
-            "type"
-          ],
-          "additionalProperties": false,
-          "properties": {
-            "type": {
-              "const": "grid"
-            },
-            "columns": {
-              "type": "integer",
-              "minimum": 1,
-              "maximum": 100,
-              "description": "Grid columns. Default: aspect-fit square-ish grid."
-            },
-            "jitter": {
-              "oneOf": [
-                {
-                  "type": "number",
-                  "minimum": 0,
-                  "maximum": 1
+          "oneOf": [
+        {
+              "type": "object",
+              "required": [
+                "type"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "type": {
+                  "const": "grid"
                 },
-                {
-                  "type": "object",
-                  "additionalProperties": false,
-                  "properties": {
-                    "x": {
+                "columns": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 100,
+                  "description": "Grid columns. Default: aspect-fit square-ish grid."
+                },
+                "jitter": {
+                  "oneOf": [
+                    {
                       "type": "number",
                       "minimum": 0,
                       "maximum": 1
                     },
-                    "y": {
-                      "type": "number",
-                      "minimum": 0,
-                      "maximum": 1
+                    {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "properties": {
+                        "x": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1
+                        },
+                        "y": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1
+                        }
+                      }
                     }
-                  }
+                  ],
+                  "description": "Seeded per-entity offset as a fraction of cell size (scalar or per-axis). { y: 1 } keeps columns crisp while scattering vertically (Matrix rain). Default 0."
                 }
-              ],
-              "description": "Seeded per-entity offset as a fraction of cell size (scalar or per-axis). { y: 1 } keeps columns crisp while scattering vertically (Matrix rain). Default 0."
+              },
+              "description": "Place entities on a grid (row-major, within region) instead of random scatter \u2014 Matrix columns, LED walls, uniform dot fields."
+            },
+            {
+              "type": "object",
+              "required": ["type"],
+              "additionalProperties": false,
+              "properties": {
+                "type": { "const": "list" },
+                "gap": { "type": "number", "exclusiveMinimum": 0, "description": "Row pitch in viewport units of min(w,h) (px in px specs). Default 0.06 / 40 px." }
+              },
+              "description": "Data layout: entities stacked in one column in reading order; strings[i], glyphs[i] and colors[i] are taken in order. position (any count) anchors the block's top-left; otherwise centred in region."
+            },
+            {
+              "type": "object",
+              "required": ["type", "columns"],
+              "additionalProperties": false,
+              "properties": {
+                "type": { "const": "table" },
+                "columns": { "type": "integer", "minimum": 1, "maximum": 100 },
+                "gap": {
+                  "oneOf": [
+                    { "type": "number", "exclusiveMinimum": 0 },
+                    { "type": "object", "additionalProperties": false, "properties": { "x": { "type": "number", "exclusiveMinimum": 0 }, "y": { "type": "number", "exclusiveMinimum": 0 } } }
+                  ],
+                  "description": "Cell pitch, one number or {x, y}, in viewport units of min(w,h). Default 0.06."
+                }
+              },
+              "description": "Data layout: entities fill columns row-major in reading order (see list)."
+            }
+          ]
+        },
+        "emit": {
+          "type": "object",
+          "required": ["every", "life"],
+          "additionalProperties": false,
+          "properties": {
+            "every": {
+              "type": "number",
+              "minimum": 1000,
+              "maximum": 600000,
+              "description": "Event period in ms per entity (floor 1000: at most one event per second per entity)."
+            },
+            "life": {
+              "type": "number",
+              "minimum": 500,
+              "description": "Visible window per event in ms (floor 500; must be <= every). Fades in over the first quarter, out over the rest."
+            },
+            "jitter": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "0 = entities evenly staggered across the period (one event at a time while life <= every / count); 1 (default) = scattered offsets from a fixed low-discrepancy sequence (not seeded)."
+            },
+            "grow": {
+              "type": "array",
+              "items": { "type": "number", "minimum": 0, "maximum": 8 },
+              "minItems": 2,
+              "maxItems": 2,
+              "description": "[from, to] size multipliers across the window \u2014 expansion rather than travel."
             }
           },
-          "description": "Place entities on a grid (row-major, within region) instead of random scatter \u2014 Matrix columns, LED walls, uniform dot fields."
+          "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."
+        },
+        "clock": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "phase": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Shared phase in turns (0..1). Default 0."
+            },
+            "rate": {
+              "type": "number",
+              "minimum": 0.1,
+              "maximum": 4,
+              "description": "Time multiplier for pulse/grow/cycle. Default 1. Their periods must satisfy period / rate >= 1000 ms."
+            }
+          },
+          "description": "Phase-lock: replaces the seeded per-entity phases of pulse, grow and cycle with one shared phase so layers can breathe in step."
         },
         "life": {
           "type": "object",
@@ -459,7 +541,16 @@
       "if": {
         "required": [
           "position"
-        ]
+        ],
+        "not": {
+          "required": ["layout"],
+          "properties": {
+            "layout": {
+              "required": ["type"],
+              "properties": { "type": { "enum": ["list", "table"] } }
+            }
+          }
+        }
       },
       "then": {
         "properties": {
@@ -676,6 +767,12 @@
             "color": {
               "$ref": "#/definitions/hexColor"
             },
+            "feather": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Soft edge: the fraction of the half-size that fades out toward the border (Rothko's block at 0.5\u20130.8). Default 0 = hard."
+            },
             "colors": {
               "type": "array",
               "minItems": 1,
@@ -690,6 +787,70 @@
           },
           "description": "Axis-aligned rectangle (rotates with spin) \u2014 Mondrian blocks, confetti, city lights."
         },
+        {
+          "type": "object",
+          "required": ["kind", "values", "length", "thickness", "color"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "bar" },
+            "values": { "type": "array", "minItems": 1, "maxItems": 400, "items": { "type": "number", "minimum": 0 }, "description": "One value per entity in reading order; bar i is length x values[i] / max. Paint: steer layers.N.sprite.values and the bars glide." },
+            "length": { "type": "number", "exclusiveMinimum": 0, "description": "Full-scale bar length (px or viewport-units of min(w,h))." },
+            "thickness": { "type": "number", "exclusiveMinimum": 0, "description": "Bar thickness (px or viewport-units)." },
+            "color": { "$ref": "#/definitions/hexColor" },
+            "max": { "type": "number", "exclusiveMinimum": 0, "description": "Full-scale value. Default: the largest value." },
+            "direction": { "enum": ["right", "left", "up", "down"], "description": "Growth direction from the entity's position. Default right." },
+            "colors": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/hexColor" }, "description": "Per-entity color palette (in order under a list/table layout, seeded otherwise)." },
+            "colorWeights": { "$ref": "#/definitions/colorWeights" }
+          },
+          "description": "A data bar whose length is a number. Pair with a list layout for a chart that is one layer."
+        },
+        {
+          "type": "object",
+          "required": ["kind", "radius", "color"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "polygon" },
+            "radius": { "$ref": "#/definitions/positiveRange", "description": "Circumradius range (px or viewport-units)." },
+            "color": { "$ref": "#/definitions/hexColor" },
+            "sides": { "type": "integer", "minimum": 3, "maximum": 12, "description": "Regular n-gon, point up. Default 6. Not with points." },
+            "points": {
+              "type": "array",
+              "minItems": 3,
+              "maxItems": 24,
+              "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "minimum": -1, "maximum": 1 } },
+              "description": "Custom vertices in unit coordinates (-1..1), scaled by the radius. Not with sides."
+            },
+            "soft": { "type": "boolean", "description": "Feather the fill from the centre, like a soft circle." },
+            "colors": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/hexColor" }, "description": "Per-entity color palette (seeded pick)." },
+            "colorWeights": { "$ref": "#/definitions/colorWeights" }
+          },
+          "not": { "required": ["sides", "points"] },
+          "description": "Regular or custom polygon (rotates with spin) \u2014 a facet, a triangle, a plane, a mosaic tile."
+        },
+        {
+          "type": "object",
+          "required": ["kind", "length", "points", "color"],
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "const": "stroke" },
+            "length": { "$ref": "#/definitions/positiveRange", "description": "Bounding size range of the mark (px or viewport-units); the unit box is scaled to it." },
+            "points": {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 24,
+              "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "minimum": -1, "maximum": 1 } },
+              "description": "Path control points in unit coordinates (-1..1)."
+            },
+            "color": { "$ref": "#/definitions/hexColor" },
+            "width": { "type": "number", "exclusiveMinimum": 0, "description": "Stroke width (px or viewport-units). Default 0.002 viewport-units / 2 px." },
+            "curve": { "enum": ["smooth", "linear"], "description": "Catmull-Rom spline through the points (default) or a polyline." },
+            "taper": { "type": "boolean", "description": "Thin the mark to almost nothing at both ends \u2014 a brush stroke rather than a line." },
+            "orient": { "type": "boolean", "description": "Turn the path's +x along the entity's heading (like streak)." },
+            "colors": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/hexColor" }, "description": "Per-entity color palette (seeded pick)." },
+            "colorWeights": { "$ref": "#/definitions/colorWeights" }
+          },
+          "description": "A freehand mark: a path stroked with round joins, optionally tapered and heading-oriented. Rotates with spin."
+        },
         {
           "type": "object",
           "required": [
@@ -795,6 +956,16 @@
               "type": "boolean",
               "description": "Randomly flip horizontal direction per entity (fish)."
             },
+            "ease": {
+              "type": "object",
+              "required": ["type", "tau"],
+              "additionalProperties": false,
+              "properties": {
+                "type": { "enum": ["settle", "buoyant"] },
+                "tau": { "type": "number", "minimum": 100, "maximum": 120000, "description": "Time constant in ms." }
+              },
+              "description": "Closed-form velocity easing: settle decelerates from speed to rest (travels speed x tau); buoyant accelerates from rest to speed. With emit, restarts every event."
+            },
             "bob": {
               "type": "number",
               "description": "Vertical wobble amplitude in px."
@@ -815,6 +986,16 @@
             "speed": {
               "$ref": "#/definitions/speedRange"
             },
+            "ease": {
+              "type": "object",
+              "required": ["type", "tau"],
+              "additionalProperties": false,
+              "properties": {
+                "type": { "enum": ["settle", "buoyant"] },
+                "tau": { "type": "number", "minimum": 100, "maximum": 120000, "description": "Time constant in ms." }
+              },
+              "description": "Closed-form velocity easing: settle decelerates from speed to rest (travels speed x tau); buoyant accelerates from rest to speed. With emit, restarts every event."
+            },
             "sway": {
               "type": "number",
               "description": "Horizontal sway amplitude in px (bubbles)."
@@ -942,6 +1123,16 @@
               "exclusiveMinimum": 0,
               "description": "Harmonic amplitude (px or viewport-units). Default ~0.05 viewport-units. How far paths curve away from the base line."
             },
+            "ease": {
+              "type": "object",
+              "required": ["type", "tau"],
+              "additionalProperties": false,
+              "properties": {
+                "type": { "enum": ["settle", "buoyant"] },
+                "tau": { "type": "number", "minimum": 100, "maximum": 120000, "description": "Time constant in ms." }
+              },
+              "description": "Closed-form velocity easing: settle decelerates from speed to rest (travels speed x tau); buoyant accelerates from rest to speed. With emit, restarts every event."
+            },
             "coherence": {
               "type": "number",
               "minimum": 0,
@@ -1099,6 +1290,10 @@
           ],
           "description": "Advisory intensity for capability/reduced-motion gating."
         },
+        "density": {
+          "enum": ["sparse", "normal", "dense"],
+          "description": "Declared density intent. sparse withholds the sparse-scene advisory (the emptiness is the point); dense withholds dense-scene. Checked against measured coverage (density-mismatch). A hint only — changes no pixel."
+        },
         "units": {
           "enum": [
             "px",