@hyprune/schema 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -390,3 +390,76 @@ Publishes IPC 0.21 (markers, personal quests, focus sessions) and IPC 0.22 (obje
 ## @hyprune/schema 0.8.0 (2026-10-12)
 
 Publishes IPC 0.23 and world format 0.9: characters and NPC instances, authored paths (route/track/generic) with stops, seats, keepClear volumes and NPC interactions.
+
+## Unreleased: object manifest 0.10 draft additions
+
+Draft only; no version changes. `v0.10/object.schema.json` and the validator:
+
+- Mappings take an `average` modifier `{windowS? (1–3600, default 60),
+  override?}`: the running average of a numeric value, alone or under `scale`,
+  `thresholds`, `cases` or `format`; never with `becomes` or `counter`. The
+  validator requires an `int` or `number` input, and in drives an `override`
+  that names another non-event input of the machine (recipes take no override).
+  A direct average of an `int` is fractional, so counts need a rounded scale.
+- New slot kind `levels` (at most 8): `{id, node, mode: fill|slide, axis?
+  (unit vector, default [0, 1, 0]), length (> 0, ≤ 10), surface? (fill only),
+  settle?: ease|spring}` and drive target `level:<id>` (outputs 0–1). With the
+  glTF: `node` and `surface` exist in the scene, the surface is not inside the
+  fill node's subtree, no node is moved by two slots, and the collision proxy
+  is never moved.
+- `stacks`: `cap` up to 100 (was 64) and an optional `rate` (copies per second,
+  0–1000). `layout.spacing` components may be negative (−10 to 10 m; copies fill
+  from the node towards the sign) and must be non-zero where that axis's grid is
+  above 1.
+
+## IPC 0.24: machine inputs in the catalog and live machine state (RFC-0013)
+
+- `objects.catalog` entries gain required `machine`: null for an entry without
+  the machine trait, else `{primary: input id|null, inputs[1..16]}`. Each input
+  is the object 0.10 declaration as authored: `{id, type (enum|int|number|bool|
+  text|event|items), label, explain, default?, values? (enum), min?/max?
+  (int, number), maxLength? (text), repeat? (2–16, not expanded), states?
+  (items)}`.
+- Required state key `live {instances[<=64]}`, published on change and never
+  per frame. An instance is `{id, asset, ref|null, source|null (the source
+  every bound input reads, null when they differ), status (ok|error|null, the
+  source's _status), error (<=256|null, its _error), stale, inputs}`; `inputs`
+  maps up to 16 input ids, repeated inputs expanded (`health.1`), to `{source|null,
+  key|null, value, raw, condition (fresh|stale|missing|error), publishedAt}`.
+  Values are scalars (strings <=256) or null; `publishedAt` is the wall-clock
+  Unix ms of the publication core holds, null when missing.
+- Everything else is inherited from 0.23 unchanged (no new method, grant or
+  event); `session.hello` reports `0.24`. Inheritance test included.
+
+## @hyprune/schema 0.9.0 (2026-10-13)
+
+Publishes IPC 0.24: `objects.catalog` entries carry a placed machine's declared inputs (`machine`), and a new `live` state key reports each placed machine's source, status and per-input values (published only on change). Inherited from 0.23 otherwise; no new grant. Also the object 0.10 draft additions for gauges: the `average` mapping modifier, `levels` slots (fill/slide with spring) and stack rate, cap 100 and signed spacing.
+
+## IPC 0.25 (draft): companions (RFC-0010 companions amendment)
+
+- Methods (grant `objects.control`): `companion.set {ref}` (a companion-capable
+  library or user catalog ref), `companion.clear {}` and `companion.mode {mode:
+  follow|stay}`; each returns `{revision}`. Existing methods take the reserved
+  object id `companion`: `npcs.bind` (a route or a standing spot), `paths.draw
+  {bind}` and `interaction.choose`. No new grant, no new event.
+- Required state key `companion {ref|null, name|null (<=32), state
+  (none|loading|unavailable|active|waiting|hidden), reason|null (<=64), mode
+  (follow|stay|route), path|null (qualified path ref), activity|null
+  (following|walking|running|idle|talking|sitting|waiting|carried),
+  position|null, carried}`.
+- `objects.catalog` entries gain required `companion`: null, or `{capable,
+  name, reason|null}`.
+- `npcs.aimed.interactions[].type` gains `companion` (Stay and Follow).
+- Everything else is inherited from 0.24 unchanged; `session.hello` reports
+  `0.25`. Inheritance test included.
+
+## Object format 0.10 (draft): companion block
+
+- Optional `companion {name? (1-32), followDistance? (1.5-2.5 m), idles?
+  (<=4 unique clip names), say? (<=8 lines of <=160 characters)}`, only on
+  characters; idle variants must be clips of `traits.character` and not
+  canonical RFC-0010 clip names (`talk` is a new canonical name).
+
+## @hyprune/schema 0.10.0 (2026-10-13)
+
+Publishes IPC 0.25: companions. `companion.set`, `companion.clear` and `companion.mode` (follow or stay), a required `companion` state key, a companion capability on catalog entries and the aimed interaction type `companion`; and the object 0.10 draft `companion` block (name, followDistance, idles, say). Inherits 0.24.

package/README.md

@@ -2,7 +2,7 @@
 
 > **Hyprune** is an explorable, world-driven desktop environment for Hyprland: your workspaces become places you can walk through, with live windows on the walls. This repository holds the versioned **schemas** for world packages, IPC and manifests, and their validator. Install Hyprune through the [hyprune](https://github.com/hyprune/hyprune) repository (starter kits, Nix, Arch); learn more at [hyprune.com](https://hyprune.com). Licence: MIT.
 
-Versioned contracts for Hyprune, a world-driven Hyprland desktop: world packages (formats 0.1–0.9), the IPC protocol (0.1–0.23), object and library manifests (0.9, draft 0.10), extension and screen-type manifests and the input keymap. JSON Schema dialect: **2020-12**. Every version is frozen once published; core, the shell and the SDK pin these exact files. Readable reference: [hyprune.com/reference/schema](https://hyprune.com/reference/schema/).
+Versioned contracts for Hyprune, a world-driven Hyprland desktop: world packages (formats 0.1–0.9), the IPC protocol (0.1–0.25, 0.25 draft), object and library manifests (0.9, draft 0.10), extension and screen-type manifests and the input keymap. JSON Schema dialect: **2020-12**. Every version is frozen once published; core, the shell and the SDK pin these exact files. Readable reference: [hyprune.com/reference/schema](https://hyprune.com/reference/schema/).
 
 ## Install
 
@@ -203,6 +203,22 @@ values, `use`/`name`/`speed`/`stops` on editor paths, the reticle action
 (objects.control), `paths.list` (state.read) and `interaction.choose`
 (world.control). Every other 0.22 definition is unchanged.
 
+IPC **0.24** adds live machine state (RFC-0013): `objects.catalog` entries gain
+a required `machine` (null, or the machine trait's `primary` and its input
+declarations as authored, repeat not expanded) and a required `live` state key
+lists at most 64 bound machine instances with each input's binding, mapped and
+raw value, condition (`fresh`, `stale`, `missing`, `error`) and `publishedAt`
+(wall-clock Unix ms of the held publication, or null). No new method, event or
+grant; every other 0.23 definition is unchanged. See the RFC-0013 amendment
+"Live state in IPC 0.24".
+
+IPC **0.25** (draft, the RFC-0010 companions amendment) adds the companion: a
+required `companion` state key (the chosen ref and name, its state, mode
+`follow`/`stay`/`route`, bound path, activity and position), a `companion`
+capability on catalog entries, the aimed interaction type `companion`, and
+`companion.set/clear/mode` (objects.control). Object format 0.10 (draft) gains
+the optional `companion` block. Every other 0.24 definition is unchanged.
+
 ## Objects and libraries (RFC-0011)
 
 Object manifests (`object.json`) and library manifests (`library.json`) use the

package/lib/validate.mjs

@@ -257,6 +257,17 @@ function validateObjectGltf(value, version, gltf, options, fail, warn) {
     }
   }
   for (const s of slots.stacks || []) node(s.node, `slots.stacks ${s.id}`);
+  const levelNodes = new Map();
+  for (const l of slots.levels || []) {
+    const where = `slots.levels ${l.id}`;
+    for (const name of [l.node, l.surface]) {
+      if (name === undefined) continue;
+      if (name === traits.collidable?.node) { fail(`${where}: the collision proxy can't be moved`); continue; }
+      if (levelNodes.has(name)) fail(`${where}: node "${name}" is also moved by levels slot ${levelNodes.get(name)}`); else levelNodes.set(name, l.id);
+    }
+    const i = node(l.node, where), j = l.surface === undefined ? undefined : node(l.surface, where);
+    if (i !== undefined && j !== undefined && subtree(i).includes(j)) fail(`${where}: surface "${l.surface}" must not be inside the fill node's subtree`);
+  }
   for (const t of slots.toggles || []) for (const name of t.nodes) {
     if (name === traits.collidable?.node) fail(`slots.toggles ${t.id}: the collision proxy can't be toggled`);
     node(name, `slots.toggles ${t.id}`);
@@ -328,7 +339,18 @@ function validateMachine(value, fail) {
     return input;
   };
   // What a mapping can produce from an input: a set of scalars, a numeric range, or a kind.
+  const numeric = input => input?.type === 'int' || input?.type === 'number';
   const outputs = (map, input) => {
+    if (map?.average) {
+      // The form applies to the running average (or the override's value): an int input's
+      // average is fractional, and an override widens a direct range.
+      const {average, ...form} = map, o = outputs(form, input);
+      if (Object.keys(form).length) return o;
+      const over = average.override === undefined ? undefined : inputs.get(average.override.split('.')[0]);
+      if (o.range && numeric(over)) o.range = [Math.min(o.range[0], over.min), Math.max(o.range[1], over.max)];
+      else if (over && !numeric(over)) return { kind: over.type };
+      return o.range ? { ...o, integer: false } : o;
+    }
     if (!map || !Object.keys(map).length) {
       if (input.type === 'enum') return { values: input.values };
       if (input.type === 'bool') return { values: [true, false] };
@@ -355,16 +377,25 @@ function validateMachine(value, fail) {
     const [kind, name] = [drive.target.slice(0, drive.target.indexOf(':')), drive.target.slice(drive.target.indexOf(':') + 1)];
     const known = { animation: () => animated.has(name), position: () => positions.has(name), state: () => palettes.has(name), emission: () => palettes.has(name),
       label: () => slotIds('labels').has(name), visible: () => slotIds('toggles').has(name), count: () => slotIds('stacks').has(name),
-      spawn: () => slotIds('spawns').has(name), effect: () => slotIds('effects').has(name) }[kind];
+      spawn: () => slotIds('spawns').has(name), effect: () => slotIds('effects').has(name), level: () => slotIds('levels').has(name) }[kind];
     if (!known()) { fail(`${where}: unknown ${kind} target "${name}"`); continue; }
     if (!input) continue;
+    if (drive.map?.average) {
+      const ref = drive.map.average.override;
+      if (!numeric(input)) { fail(`${where}: average needs an int or number input`); continue; }
+      if (ref !== undefined) {
+        const over = resolve(ref, `${where} average override`);
+        if (ref === drive.input) fail(`${where}: average override must name another input`);
+        else if (over && (over.type === 'event' || over.type === 'items')) fail(`${where}: average override ${ref} must be a value input, not ${over.type}`);
+      }
+    }
     const o = outputs(drive.map, input), event = o.kind === 'event' || (input.type === 'event' && !drive.map);
     if (kind === 'state') {
       if (!o.values) fail(`${where}: needs palette ids (an enum input or cases)`);
       else for (const v of o.values) if (!palettes.get(name).has(v)) fail(`${where}: "${v}" is not a palette id of ${name}`);
     } else if (kind === 'animation') within(o, 0, 10, where);
     else if (kind === 'emission') within(o, 0, 16, where);
-    else if (kind === 'position') within(o, 0, 1, where);
+    else if (kind === 'position' || kind === 'level') within(o, 0, 1, where);
     else if (kind === 'count') { within(o, 0, Infinity, where); if (o.range && !o.integer) fail(`${where}: counts need an int input or a rounded scale`); }
     else if (kind === 'visible') { if (!o.values || o.values.some(v => typeof v !== 'boolean')) fail(`${where}: needs boolean outputs`); }
     else if (kind === 'spawn' || kind === 'effect') { if (!event) fail(`${where}: needs an event (an event input, counter or becomes)`); }
@@ -378,6 +409,8 @@ function validateMachine(value, fail) {
     for (const ref of Object.keys(recipe.fields)) resolve(ref, `${label} recipe ${recipe.name}`);
     for (const [ref, map] of Object.entries(recipe.maps || {})) {
       const input = resolve(ref, `${label} recipe ${recipe.name}`);
+      if (map.average && input && !numeric(input)) fail(`${label} recipe ${recipe.name}: ${ref} average needs an int or number input`);
+      if (map.average?.override !== undefined) fail(`${label} recipe ${recipe.name}: ${ref} average override is for drives only`);
       if (input?.type === 'enum') for (const v of outputs(map, { type: 'text' }).values || [])
         if (!input.values.includes(v)) fail(`${label} recipe ${recipe.name}: ${ref} maps to "${v}", not a value of the input`);
     }
@@ -390,6 +423,8 @@ function validateMachine(value, fail) {
 function traitCombinations(names, fail) {
   for (const a of names) for (const c of names) if (a < c && !(traitPairs[a] || []).includes(c)) fail(`traits: ${a} and ${c} can't be combined`);
 }
+// RFC-0010 canonical character clip names (talk: the companions amendment).
+const canonicalClips = ['idle', 'idle_fidget', 'walk', 'run', 'turn_left', 'turn_right', 'look_around', 'wave', 'nod', 'sit', 'sit_idle', 'stand', 'talk'];
 function objectTraitRules(traits, slots, fail, inside = () => {}) {
   const quat = (q, where) => { if (Math.abs(Math.hypot(...q) - 1) > 0.002) fail(`${where}: quaternion must be normalized`); };
   const unique = (items, field, label) => { const ids = items.map(v => v[field]); if (new Set(ids).size !== ids.length) fail(`${label}: duplicate ${field}`); };
@@ -430,15 +465,24 @@ function objectTraitRules(traits, slots, fail, inside = () => {}) {
     if (!tr) fail(`slots.spawns ${s.id}: unknown track ${s.track}`);
     else for (const a of s.items || []) if (tr.items && !tr.items.assets.includes(a)) fail(`slots.spawns ${s.id}: item ${a} is not in track ${tr.id}'s items`);
   }
+  for (const l of slots.levels || []) if (l.axis && Math.abs(Math.hypot(...l.axis) - 1) > 0.001) fail(`slots.levels ${l.id}: axis must be a unit vector`);
   for (const s of slots.stacks || []) {
     if (s.cap > s.layout.grid.reduce((x, y) => x * y, 1)) fail(`slots.stacks ${s.id}: cap exceeds the layout grid`);
-    s.layout.grid.forEach((n, j) => { if (n > 1 && !(s.layout.spacing[j] > 0)) fail(`slots.stacks ${s.id}: spacing ${'xyz'[j]} must be positive for ${n} cells`); });
+    s.layout.grid.forEach((n, j) => { if (n > 1 && !(Number.isFinite(s.layout.spacing[j]) && s.layout.spacing[j] !== 0)) fail(`slots.stacks ${s.id}: spacing ${'xyz'[j]} must be non-zero for ${n} cells`); });
   }
 }
 function validateObjectManifest(value, version, options, fail, warn) {
   const traits = value.traits, slots = value.slots || {}, names = Object.keys(traits), b = value.bounds;
   if (options.directory !== undefined && options.directory !== value.id) fail(`id: "${value.id}" differs from its directory "${options.directory}"`);
   traitCombinations(names, fail);
+  // Companion block (object format 0.10 draft, RFC-0010 companions amendment).
+  if (value.companion) {
+    if (!traits.character) fail('companion: only characters can be companions');
+    else for (const clip of value.companion.idles || []) {
+      if (!(clip in traits.character.clips)) fail(`companion: idle variant "${clip}" is not a clip of traits.character`);
+      if (canonicalClips.includes(clip)) fail(`companion: "${clip}" is a canonical clip, not an idle variant`);
+    }
+  }
   for (let j = 0; j < 3; j++) if (b.min[j] >= b.max[j]) fail(`bounds: min ${'xyz'[j]} must be below max`);
   const t = objectLimits.boundsTolerance, surfaces = new Set(traits.movable ? traits.movable.surfaces || ['floor'] : []);
   const one = surfaces.size === 1 ? [...surfaces][0] : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyprune/schema",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Versioned JSON Schemas for Hyprune world packages and the IPC protocol, with a validator and CLI for world authors",
   "license": "MIT",
   "type": "module",

package/v0.10/object.schema.json

@@ -420,7 +420,7 @@
                   "target": {
                     "type": "string",
                     "maxLength": 160,
-                    "pattern": "^(animation|state|emission|label|visible|count|spawn|effect|position):[^:\\s]{1,128}$"
+                    "pattern": "^(animation|state|emission|label|visible|count|spawn|effect|position|level):[^:\\s]{1,128}$"
                   },
                   "map": {
                     "$ref": "#/$defs/mapping"
@@ -647,6 +647,45 @@
       "additionalProperties": false,
       "description": "Trait name to trait data. Unknown or reserved names reject the object."
     },
+    "companion": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 32,
+          "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
+        },
+        "followDistance": {
+          "type": "number",
+          "minimum": 1.5,
+          "maximum": 2.5
+        },
+        "idles": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64,
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "maxItems": 4,
+          "uniqueItems": true
+        },
+        "say": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 160,
+            "pattern": "^[^\\u0000-\\u001f\\u007f]+$"
+          },
+          "maxItems": 8
+        }
+      },
+      "additionalProperties": false,
+      "description": "Companion settings (RFC-0010 companions amendment, draft): display name, follow distance, idle variants (clips of traits.character) and Talk lines. Characters only."
+    },
     "slots": {
       "type": "object",
       "properties": {
@@ -1005,7 +1044,7 @@
               "cap": {
                 "type": "integer",
                 "minimum": 1,
-                "maximum": 64
+                "maximum": 100
               },
               "layout": {
                 "type": "object",
@@ -1025,10 +1064,11 @@
                     "items": {
                       "type": "number",
                       "maximum": 10,
-                      "minimum": 0
+                      "minimum": -10
                     },
                     "minItems": 3,
-                    "maxItems": 3
+                    "maxItems": 3,
+                    "description": "Metres between copies per axis; a negative component fills from the node towards -axis. Non-zero where that axis's grid is above 1."
                   },
                   "fill": {
                     "enum": [
@@ -1047,6 +1087,12 @@
                   "fill"
                 ],
                 "additionalProperties": false
+              },
+              "rate": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1000,
+                "description": "Copies per second the shown count moves toward the target; 0 or absent: at once."
               }
             },
             "required": [
@@ -1089,6 +1135,78 @@
           "minItems": 1,
           "maxItems": 8
         },
+        "levels": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "$ref": "../v0.8/common.schema.json#/$defs/slug"
+              },
+              "node": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "mode": {
+                "enum": [
+                  "fill",
+                  "slide"
+                ]
+              },
+              "axis": {
+                "type": "array",
+                "items": {
+                  "type": "number",
+                  "minimum": -1,
+                  "maximum": 1
+                },
+                "minItems": 3,
+                "maxItems": 3
+              },
+              "length": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "maximum": 10
+              },
+              "surface": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "settle": {
+                "enum": [
+                  "ease",
+                  "spring"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "node",
+              "mode",
+              "length"
+            ],
+            "additionalProperties": false,
+            "not": {
+              "properties": {
+                "mode": {
+                  "const": "slide"
+                },
+                "surface": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "mode",
+                "surface"
+              ]
+            },
+            "description": "A subtree scaled (fill) or moved (slide) by level:<id>, 0-1. axis: asset-space unit vector, default [0, 1, 0]; surface: fill only; settle default ease."
+          },
+          "minItems": 1,
+          "maxItems": 8
+        },
         "ports": {
           "type": "array",
           "items": {
@@ -1548,10 +1666,58 @@
             }
           },
           "additionalProperties": false
+        },
+        "average": {
+          "type": "object",
+          "properties": {
+            "windowS": {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 3600
+            },
+            "override": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 40,
+              "pattern": "^[a-z][A-Za-z0-9]*(\\.[1-9][0-9]?)?$"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Running average modifier: the time-weighted mean of the value over the last windowS seconds (default 60) of fresh data; the mapping's form applies to it. override (drives only): another non-event input whose value, while present, replaces the average."
         }
       },
       "additionalProperties": false,
-      "description": "RFC-0013 mapping language: direct ({}), cases, thresholds, scale, becomes, counter or format."
+      "description": "RFC-0013 mapping language: direct ({}), cases, thresholds, scale, becomes, counter or format; average modifies the value forms (not becomes or counter).",
+      "not": {
+        "anyOf": [
+          {
+            "properties": {
+              "average": {
+                "type": "object"
+              },
+              "becomes": {}
+            },
+            "required": [
+              "average",
+              "becomes"
+            ]
+          },
+          {
+            "properties": {
+              "average": {
+                "type": "object"
+              },
+              "counter": {
+                "const": true
+              }
+            },
+            "required": [
+              "average",
+              "counter"
+            ]
+          }
+        ]
+      }
     },
     "input": {
       "type": "object",