@idle-screens/schema 2.0.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idle-screens/schema",
-  "version": "2.0.0",
+  "version": "2.2.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

@@ -12,6 +12,7 @@
     "label": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Human-readable name." },
     "seed": { "type": "number", "description": "Deterministic RNG seed. Same spec + same seed = identical frames. Falls back to the host's seed." },
     "motionIntensity": { "enum": ["calm", "moderate", "energetic"], "description": "Advisory intensity for capability/reduced-motion gating." },
+    "units": { "enum": ["px", "viewport"], "description": "Dimensional unit system. 'viewport' = all sizes/speeds/distances are fractions of min(w,h)." },
     "background": { "$ref": "#/definitions/background" },
     "layers": {
       "type": "array",
@@ -87,6 +88,16 @@
                 "color": { "$ref": "#/definitions/hexColor" },
                 "height": { "type": "number", "exclusiveMinimum": 0, "description": "Band height in px (e.g. an aquarium seafloor)." }
               }
+            },
+            "drift": {
+              "type": "object",
+              "required": ["period"],
+              "additionalProperties": false,
+              "properties": {
+                "period": { "type": "number", "minimum": 10000, "description": "Full cycle period in ms. Floor of 10 s." },
+                "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 0.3, "description": "How far stops shift (fraction of 0..1 range). Default 0.15, max 0.3." }
+              },
+              "description": "Slow oscillation of gradient stop positions — makes the background feel alive."
             }
           }
         }
@@ -124,6 +135,17 @@
           },
           "description": "Sinusoidal opacity breathing. Per-entity seeded phase — a layer can never strobe in unison."
         },
+        "spin": { "type": "number", "minimum": -360, "maximum": 360, "description": "Per-entity rotation speed in degrees/sec (positive = clockwise). Each entity gets a seeded starting angle." },
+        "grow": {
+          "type": "object",
+          "required": ["amp", "period"],
+          "additionalProperties": false,
+          "properties": {
+            "amp": { "type": "number", "exclusiveMinimum": 0, "maximum": 0.8, "description": "Size breathing amplitude as fraction of base size (0.3 = ±30%)." },
+            "period": { "type": "number", "minimum": 500, "description": "Breathing period in ms; same flash-safety floor as pulse." }
+          },
+          "description": "Sinusoidal size breathing. Per-entity seeded phase. Composes with any sprite kind."
+        },
         "key": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Addressable name so setParam can use key.field paths." },
         "position": {
           "type": "object",
@@ -134,6 +156,29 @@
             "y": { "type": "number", "minimum": 0, "maximum": 1 }
           },
           "description": "Exact fractional position for a single entity. Requires count: 1. Overrides region scatter."
+        },
+        "trail": {
+          "type": "object",
+          "required": ["length"],
+          "additionalProperties": false,
+          "properties": {
+            "length": { "type": "number", "exclusiveMinimum": 0, "maximum": 5000, "description": "Trail duration in ms. How far back the afterglow extends." },
+            "fade": { "type": "number", "minimum": 0, "maximum": 1, "description": "Opacity fade factor along the trail. 1 = full fade to 0 (default), 0 = uniform opacity." }
+          },
+          "description": "Afterglow trail behind moving entities. Sampled analytically — no state, fully deterministic."
+        },
+        "links": {
+          "type": "object",
+          "required": ["k", "maxDist"],
+          "additionalProperties": false,
+          "properties": {
+            "k": { "type": "integer", "minimum": 1, "maximum": 8, "description": "Connect to the k nearest neighbors." },
+            "maxDist": { "type": "number", "exclusiveMinimum": 0, "description": "Maximum link distance (px or viewport-units)." },
+            "color": { "$ref": "#/definitions/hexColor", "description": "Link color. Defaults to per-entity color." },
+            "alpha": { "type": "number", "minimum": 0, "maximum": 1, "description": "Link opacity. Defaults to entity alpha." },
+            "width": { "type": "number", "exclusiveMinimum": 0, "description": "Stroke width (px or viewport-units). Default 1." }
+          },
+          "description": "Draw lines to each entity's k nearest neighbors within maxDist. The layer's entity count (count field) must be <= 200 for performance."
         }
       },
       "if": { "required": ["position"] },
@@ -147,7 +192,8 @@
           "additionalProperties": false,
           "properties": {
             "kind": { "const": "emoji" },
-            "glyphs": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Emoji picked per entity (seeded)." }
+            "glyphs": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Emoji picked per entity (seeded)." },
+            "cycle": { "$ref": "#/definitions/cycle" }
           }
         },
         {
@@ -161,7 +207,8 @@
             "font": { "type": "string", "description": "CSS font shorthand, e.g. 'bold 24px monospace'." },
             "align": { "enum": ["left", "center", "right"] },
             "baseline": { "enum": ["top", "middle", "bottom"] },
-            "maxWidth": { "type": "number", "exclusiveMinimum": 0 }
+            "maxWidth": { "type": "number", "exclusiveMinimum": 0 },
+            "cycle": { "$ref": "#/definitions/cycle" }
           }
         },
         {
@@ -172,11 +219,21 @@
             "kind": { "const": "circle" },
             "radius": { "$ref": "#/definitions/positiveRange" },
             "color": { "$ref": "#/definitions/hexColor" },
-            "soft": { "type": "boolean", "description": "Radial falloff (glow orb) instead of a hard disc." }
+            "soft": { "type": "boolean", "description": "Radial falloff (glow orb) instead of a hard disc." },
+            "colors": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/hexColor" }, "description": "Per-entity color palette (seeded pick). Falls back to color." }
           }
         }
       ]
     },
+    "cycle": {
+      "type": "object",
+      "required": ["period"],
+      "additionalProperties": false,
+      "properties": {
+        "period": { "type": "number", "minimum": 500, "description": "Cycling period in ms; floor of 500 (flash-safety)." }
+      },
+      "description": "Rotate through sprite variants over time. Each entity offsets by its seeded phase."
+    },
     "motion": {
       "oneOf": [
         {
@@ -217,6 +274,32 @@
           "properties": {
             "type": { "const": "static", "description": "Entity stays exactly where placed. Use with position for pinned elements." }
           }
+        },
+        {
+          "type": "object",
+          "required": ["type", "speed", "radius"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "orbit" },
+            "speed": {
+              "type": "array",
+              "items": { "type": "number", "minimum": 0, "maximum": 180 },
+              "minItems": 2,
+              "maxItems": 2,
+              "description": "[min, max] angular velocity in degrees/sec, capped at 180."
+            },
+            "radius": { "$ref": "#/definitions/positiveRange", "description": "[min, max] orbit radius in px." },
+            "center": {
+              "type": "object",
+              "required": ["x", "y"],
+              "additionalProperties": false,
+              "properties": {
+                "x": { "type": "number", "minimum": 0, "maximum": 1 },
+                "y": { "type": "number", "minimum": 0, "maximum": 1 }
+              },
+              "description": "Orbit center as fractional viewport position. Default {0.5, 0.5}."
+            }
+          }
         }
       ]
     }