@hyprune/schema 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -298,3 +298,139 @@ Object manifests use the world format numbering: a world may use objects whose
 ## @hyprune/schema 0.7.0 (2026-10-12)
 
 Publishes IPC 0.21 (markers, personal quests, focus sessions) and IPC 0.22 (object catalog, user placements, libraries), plus the object manifest (`object.json` 0.9 and the 0.10 draft), library and library release-record schemas.
+
+## World 0.9: characters, paths, seats and keepClear (RFC-0011 P2)
+
+- `objectAssets[]` (at most 32, ids unique) take exactly one source: inline
+  `{id, scene, animations?, collision?, lighting?, traits?, slots?}` (the 0.8
+  asset plus object.json 0.9 `traits` and `slots`; `decorative`, `collidable`,
+  `movable`, `character` and `seat` are allowed, `mover`, `mount`, `machine` and
+  `interactive` rejected), `dir {id, dir}` (a package directory holding
+  `object.json`, object format at most the world's) or `library {id, library,
+  object}` (`library` is `<reverse-domain id>@<semver>`, `object` a slug).
+  `animations` is shorthand for `traits.decorative.animations` and `collision`
+  for `traits.collidable`; giving both forms of one is invalid.
+- `objects[]` gain `path` (a `route` path; replaces `pose`), `reverse` (only
+  with `path`), `seat` (a `seats[]` id, `<objectId>/<anchorId>` or
+  `<objectId>`; characters without a path), `accent` (linear RGB 0..1),
+  `interactions` (1..8, replacing the asset's list) and `locked` (movable
+  assets). `pose` is required unless `path` is set and forbidden with it. A
+  character's `scale` must be 1; at most 16 character instances and 8 per path.
+- Instance interactions `{id, label (1..32), prompt? (1..64), action}` with
+  `say {lines[1..8]}`, `waypoint {target: {zoneId}|{position}|{anchor}|{object}}`,
+  `guide {path}` (a route) or `panel {panel}`. `travel` and `quest` are
+  reserved and rejected. Asset-level interactions stay `say`/`panel`.
+- `paths[]` (at most 64, 1,024 points in total): `{id, name?, use?
+  (route|track|generic, default generic), closed?, points[2..256] {position,
+  type: line|curve|arc}, speed? (0.1..30), stops?[<=32]}`. A stop is `{point,
+  seconds? (0.5..600), clip? (look_around|wave|nod|idle_fidget), face?
+  ({position}|{anchor}|{object}), seat?}` with at most one of clip, face and
+  seat, one stop per point and the point below the point count. Track stops
+  take only `point` and `seconds`; generic paths have no stops. An `arc` needs
+  a horizontal chord of at least 0.1 m.
+- `seats[]` (at most 64): `{id, pose, height (0.2..1), use? (["sit"]),
+  approach? (0.3..2)}`. `keepClear[]` (at most 64): `{id, min, max}`, min
+  below max on every axis.
+- `validate('world', manifest, undefined, '0.9', {assets})` adds unique ids,
+  asset, path, seat, waypoint and face references, route-only bindings,
+  character-only and movable-only fields, pose/path exclusivity, normalised
+  seat poses, arc chords, the point total, keepClear ordering and the
+  character limits. `assets` maps a dir or library asset id to its parsed
+  `object.json`, so its traits are checked like an inline asset's; without it
+  those checks skip the asset. Reserved traits and actions are reported with a
+  plain reason. `worldLimits` exports the limits.
+- `validate('scene', gltf, undefined, '0.9', {world, asset})` reads an inline
+  asset's animations and proxy from either form and checks an inline
+  character's skin and clips; dir and library assets are checked as objects.
+- `v0.9/common.schema.json` is the 0.8 common definitions under the 0.9 `$id`
+  (the directory's IPC, input, object and library schemas are untouched).
+  `examples/world-npcs.json` is a synthetic 0.9 manifest. Everything else is
+  inherited from 0.8 unchanged. Inheritance test included.
+
+## IPC 0.23: characters, paths and interactions (RFC-0011 P2)
+
+- Required state key `npcs {motion (auto|always|still|off), state
+  (none|animating|paused|still|off), reason (null or up to 64 characters, e.g.
+  battery), usage {authored, user}, limits {authored (<=16), user (<=8)},
+  drawing, aimed, interaction}`. `drawing` is null or `{pathId, use, spawn:
+  null|{ref}, bind: null|objectId}` (a `paths.draw` in progress); `aimed` is null
+  or `{objectId, name, prompt, interactions[<=8] {id, label, type}}`;
+  `interaction` is null or `{objectId, interactionId|null, type
+  (choose|say|waypoint|guide|panel), label, choices[<=8] {id, label},
+  line|null, lineIndex, lineCount, panel|null}`.
+- `objects.instances[]` gain required `character` (boolean) and `accent`
+  (null or linear RGB); `path` is null or a qualified path ref
+  (`package/<id>`, `user/<id>`), `activity` null or
+  `idle|walking|running|stopped|sitting|guiding|interacting|suspended`, `seat`
+  null or a seat ref (up to 192 characters).
+- `editor.paths[]` gain required `use` (route|track|generic), `name`
+  (string|null), `speed` (number|null) and `stops` (at most 32, the world 0.9
+  stop shape).
+- `interaction.reticle.action` gains `interact`. `graphicsConfig` and
+  `graphicsPatch` gain `npc_motion` (`auto`, `always`, `still`, `off`).
+- Methods: `npcs.spawn {ref, path?, pose?, phase?, speed? (0.25..2), accent?,
+  reverse?}` (`{revision, id}`; path and pose exclusive, reverse needs a path);
+  `npcs.bind {id, path?, pose?, phase?, speed?, accent?, reverse?}` (at least one
+  setting); `npcs.disable {id, disabled}`; `npcs.remove {id}|{all:true}`;
+  `paths.list {}` (`{paths[<=192]}`: `{ref, source (package|user), id, name,
+  use, closed, points, speed, stops, walkable (null for non-routes),
+  problems[<=8], bound[<=8]}`); `paths.set {path: {id?, name?, use, closed,
+  points[2..256], speed?, stops?}}` (`{revision, id}`); `paths.remove {id,
+  unbind?}`; `paths.draw {use?, name?, spawn? {ref, phase?, speed?, accent?},
+  bind?}` (`{revision, id}`; spawn and bind exclusive); `paths.finish {}`
+  (`{revision, id|null, bound|null}`); `interaction.choose {objectId,
+  interactionId|null}`. Path params take a qualified ref or a bare id
+  (`package/<id>`); `paths.set/remove/draw/finish` ids are user path ids.
+  Grants: `npcs.*` and `paths.set/remove/draw/finish` need `objects.control`,
+  `paths.list` needs `state.read`, `interaction.choose` needs `world.control`.
+- Everything else is inherited from 0.22 unchanged (no new grant or event);
+  `session.hello` reports `0.23` and lists the ten methods. Inheritance test
+  included.
+
+## @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.

package/README.md

@@ -2,19 +2,19 @@
 
 > **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.8), the IPC protocol (0.1–0.22), 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.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/).
 
 ## Install
 
 ```sh
 npm i -D @hyprune/schema
-npx hyprune-validate world world.json - 0.8             # a world package manifest
-npx hyprune-validate scene scene.gltf - 0.8 world.json   # its glTF against the world format
+npx hyprune-validate world world.json - 0.9             # a world package manifest
+npx hyprune-validate scene scene.gltf - 0.9 world.json   # its glTF against the world format
 ```
 
 ```js
 import { validate, worldFormats } from '@hyprune/schema';
-import schema from '@hyprune/schema/v0.8/world.schema.json' with { type: 'json' };
+import schema from '@hyprune/schema/v0.9/world.schema.json' with { type: 'json' };
 
 const result = validate('world', manifest, undefined, worldFormats.at(-1));
 if (!result.valid) console.error(result.errors.join('\n'));
@@ -127,6 +127,17 @@ from the proxy. Check an asset's glTF with
 `npm run validate -- scene objects/armillary.gltf - 0.8 world.json armillary`).
 See RFC-0004 "world 0.8 placed world objects".
 
+World format **0.9** adds characters, paths, seats and keep-clear volumes
+(RFC-0011 P2). An object asset is an inline package glTF (now with optional
+object.json `traits` and `slots`), a package object directory (`dir`) or a
+library object (`library` + `object`). Instances gain `path` (a `route`; it
+replaces `pose`), `reverse`, `seat`, `accent`, `interactions` (`say`,
+`waypoint`, `guide`, `panel`) and `locked`. New top-level `paths` (route,
+track or generic; stops with a clip, facing or seat), `seats` and `keepClear`.
+Pass the object.json of dir and library assets to check their traits too:
+`validate('world', manifest, undefined, '0.9', {assets: {resident: objectJson}})`.
+`examples/world-npcs.json` is a synthetic example. See RFC-0011 "World format 0.9".
+
 IPC **0.16** adds the `upscaler` graphics key (`"fsr1"`, `"bilinear"` or `null` to
 inherit the preset) to `graphicsConfig`/`graphicsPatch`. Every 0.15 definition is
 otherwise unchanged; earlier schemas stay frozen. See RFC-0003/0008 amendments.
@@ -182,6 +193,25 @@ new `editor.gizmo` carries the tool 4 axis space, pivot and snapping. Error
 `data` may name the refusing placement `rule`. Every other 0.21 definition is
 unchanged. See the RFC-0011 amendment "P1 in IPC 0.22".
 
+IPC **0.23** adds characters, paths and interactions (RFC-0011 P2): a required
+`npcs` state key (motion setting and effective state, character budgets, the
+path being drawn, the aimed character and the running interaction),
+`character` and `accent` on object instances with path, activity and seat
+values, `use`/`name`/`speed`/`stops` on editor paths, the reticle action
+`interact` and the graphics key `npc_motion`. New methods
+`npcs.spawn/bind/disable/remove` and `paths.set/remove/draw/finish`
+(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".
+
 ## Objects and libraries (RFC-0011)
 
 Object manifests (`object.json`) and library manifests (`library.json`) use the

package/examples/world-npcs.json

@@ -0,0 +1,493 @@
+{
+  "formatVersion": "0.9",
+  "id": "com.hyprune.example.courtyard",
+  "version": "0.1.0",
+  "name": "Courtyard",
+  "description": "Synthetic world 0.9 manifest: characters on routes, seats, interactions and keep-clear volumes. Referenced files are not supplied.",
+  "license": "CC-BY-4.0",
+  "scene": "scene.gltf",
+  "defaultSpawn": "arrival",
+  "spawns": [
+    {
+      "id": "arrival",
+      "pose": {
+        "position": [
+          0,
+          1,
+          0
+        ],
+        "rotation": [
+          0,
+          0,
+          0,
+          1
+        ]
+      }
+    }
+  ],
+  "attribution": [
+    {
+      "path": ".",
+      "author": "Hyprune contributors",
+      "license": "CC-BY-4.0"
+    }
+  ],
+  "zones": [
+    {
+      "id": "work",
+      "name": "Work",
+      "bounds": {
+        "min": [
+          -4,
+          0,
+          -4
+        ],
+        "max": [
+          4,
+          4,
+          4
+        ]
+      }
+    }
+  ],
+  "anchors": [
+    {
+      "id": "desk",
+      "pose": {
+        "position": [
+          0,
+          1.4,
+          -3
+        ],
+        "rotation": [
+          0,
+          0,
+          0,
+          1
+        ]
+      },
+      "size": [
+        1.6,
+        0.9
+      ],
+      "screenType": "com.hyprune.window"
+    }
+  ],
+  "collision": [
+    {
+      "node": 0,
+      "shape": "mesh",
+      "layer": "static"
+    }
+  ],
+  "navigation": {
+    "kind": "mesh",
+    "node": 1,
+    "agentRadius": 0.3,
+    "agentHeight": 1.8
+  },
+  "lightmaps": [
+    {
+      "material": 0,
+      "texture": 1,
+      "texCoord": 1,
+      "encoding": "linear",
+      "intensity": 1
+    }
+  ],
+  "audio": [
+    {
+      "id": "air",
+      "path": "audio/air.ogg",
+      "position": [
+        0,
+        2,
+        0
+      ],
+      "radius": 10,
+      "gain": 0.2,
+      "loop": true
+    }
+  ],
+  "objectAssets": [
+    {
+      "id": "resident",
+      "dir": "characters/resident-blue"
+    },
+    {
+      "id": "porter",
+      "library": "com.hyprune.starter@0.1.0",
+      "object": "porter"
+    },
+    {
+      "id": "guide",
+      "scene": "characters/guide.glb",
+      "traits": {
+        "character": {
+          "clips": {
+            "walk": {
+              "speed": 1.1
+            },
+            "idle": {},
+            "wave": {},
+            "nod": {},
+            "sit": {
+              "seatHeight": 0.46
+            },
+            "sit_idle": {}
+          },
+          "height": 1.72,
+          "radius": 0.3,
+          "accent": true,
+          "interactions": [
+            {
+              "id": "talk",
+              "label": "Talk",
+              "action": {
+                "type": "say",
+                "lines": [
+                  "Welcome to the courtyard."
+                ]
+              }
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "court-bench",
+      "scene": "objects/bench.glb",
+      "collision": {
+        "node": "proxy"
+      },
+      "traits": {
+        "movable": {},
+        "seat": {
+          "capacity": 2,
+          "anchors": [
+            {
+              "id": "left",
+              "position": [
+                -0.4,
+                0,
+                0.55
+              ],
+              "yaw": 0,
+              "height": 0.45
+            },
+            {
+              "id": "right",
+              "position": [
+                0.4,
+                0,
+                0.55
+              ],
+              "yaw": 0,
+              "height": 0.45
+            }
+          ]
+        }
+      }
+    },
+    {
+      "id": "fountain",
+      "scene": "objects/fountain.glb",
+      "animations": [
+        {
+          "node": "spray",
+          "type": "spin",
+          "axis": [
+            0,
+            1,
+            0
+          ],
+          "pivot": [
+            0,
+            0,
+            0
+          ],
+          "period": 12
+        }
+      ],
+      "lighting": {
+        "mode": "probe"
+      }
+    }
+  ],
+  "objects": [
+    {
+      "id": "fountain-1",
+      "asset": "fountain",
+      "pose": {
+        "position": [
+          1.5,
+          0,
+          0
+        ],
+        "rotation": [
+          0,
+          0,
+          0,
+          1
+        ]
+      }
+    },
+    {
+      "id": "bench-east",
+      "asset": "court-bench",
+      "pose": {
+        "position": [
+          3.6,
+          0,
+          -2
+        ],
+        "rotation": [
+          0,
+          -0.7071068,
+          0,
+          0.7071068
+        ]
+      },
+      "locked": true
+    },
+    {
+      "id": "porter-1",
+      "asset": "porter",
+      "path": "court-loop",
+      "phase": 0.25,
+      "speed": 1,
+      "accent": [
+        0.9,
+        0.5,
+        0.1
+      ],
+      "interactions": [
+        {
+          "id": "talk",
+          "label": "Talk",
+          "action": {
+            "type": "say",
+            "lines": [
+              "The desk is on the north side.",
+              "Mind the fountain."
+            ]
+          }
+        },
+        {
+          "id": "where",
+          "label": "Where is work?",
+          "prompt": "Mark it",
+          "action": {
+            "type": "waypoint",
+            "target": {
+              "zoneId": "work"
+            }
+          }
+        },
+        {
+          "id": "show-desk",
+          "label": "Show me the desk",
+          "prompt": "Follow me",
+          "action": {
+            "type": "guide",
+            "path": "to-desk"
+          }
+        },
+        {
+          "id": "map",
+          "label": "Open the map",
+          "action": {
+            "type": "panel",
+            "panel": "map"
+          }
+        }
+      ]
+    },
+    {
+      "id": "guide-1",
+      "asset": "guide",
+      "path": "court-loop",
+      "phase": 0.75,
+      "reverse": true,
+      "accent": [
+        0.2,
+        0.4,
+        0.9
+      ]
+    },
+    {
+      "id": "reader",
+      "asset": "resident",
+      "pose": {
+        "position": [
+          1.5,
+          0,
+          1.8
+        ],
+        "rotation": [
+          0,
+          1,
+          0,
+          0
+        ]
+      },
+      "seat": "fountain-ledge",
+      "interactions": [
+        {
+          "id": "fountain",
+          "label": "The fountain?",
+          "action": {
+            "type": "waypoint",
+            "target": {
+              "object": "fountain-1"
+            }
+          }
+        }
+      ]
+    }
+  ],
+  "paths": [
+    {
+      "id": "court-loop",
+      "name": "Court loop",
+      "use": "route",
+      "closed": true,
+      "speed": 1.1,
+      "points": [
+        {
+          "position": [
+            -3.5,
+            0,
+            3
+          ],
+          "type": "line"
+        },
+        {
+          "position": [
+            -3.5,
+            0,
+            -2
+          ],
+          "type": "line"
+        },
+        {
+          "position": [
+            3,
+            0,
+            -2
+          ],
+          "type": "curve"
+        },
+        {
+          "position": [
+            3,
+            0,
+            3
+          ],
+          "type": "arc"
+        }
+      ],
+      "stops": [
+        {
+          "point": 1,
+          "seconds": 3,
+          "clip": "look_around"
+        },
+        {
+          "point": 2,
+          "seconds": 20,
+          "seat": "bench-east/left"
+        },
+        {
+          "point": 3,
+          "seconds": 4,
+          "face": {
+            "anchor": "desk"
+          }
+        }
+      ]
+    },
+    {
+      "id": "to-desk",
+      "name": "To the desk",
+      "use": "route",
+      "points": [
+        {
+          "position": [
+            0,
+            0,
+            3
+          ],
+          "type": "line"
+        },
+        {
+          "position": [
+            0,
+            0,
+            -2
+          ],
+          "type": "line"
+        }
+      ]
+    },
+    {
+      "id": "garden-walk",
+      "points": [
+        {
+          "position": [
+            -2,
+            0,
+            2
+          ],
+          "type": "line"
+        },
+        {
+          "position": [
+            2,
+            0,
+            2
+          ],
+          "type": "curve"
+        }
+      ]
+    }
+  ],
+  "seats": [
+    {
+      "id": "fountain-ledge",
+      "pose": {
+        "position": [
+          1.5,
+          0,
+          1.2
+        ],
+        "rotation": [
+          0,
+          1,
+          0,
+          0
+        ]
+      },
+      "height": 0.5,
+      "use": [
+        "sit"
+      ],
+      "approach": 0.6
+    }
+  ],
+  "keepClear": [
+    {
+      "id": "north-door",
+      "min": [
+        -0.8,
+        0,
+        -4.2
+      ],
+      "max": [
+        0.8,
+        2.4,
+        -3.6
+      ]
+    }
+  ]
+}