@hyprune/schema 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -434,3 +434,32 @@ Draft only; no version changes. `v0.10/object.schema.json` and the validator:
 ## @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.24), 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
 
@@ -212,6 +212,13 @@ raw value, condition (`fresh`, `stale`, `missing`, `error`) and `publishedAt`
 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

@@ -423,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}`); };
@@ -473,6 +475,14 @@ 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.9.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

@@ -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": {