@idle-screens/schema 3.7.0 → 3.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idle-screens/schema",
-  "version": "3.7.0",
+  "version": "3.9.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,
@@ -1409,6 +1523,9 @@
         "background": {
           "$ref": "#/definitions/background"
         },
+        "finish": {
+          "$ref": "#/definitions/finish"
+        },
         "layers": {
           "type": "array",
           "minItems": 1,
@@ -1473,6 +1590,10 @@
           "$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,