@hyprune/schema 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -185,3 +185,116 @@ definition exists in 0.16 and the graphics properties differ only by the new key
 ## @hyprune/schema 0.6.0 (2026-10-11)
 
 Publishes IPC 0.20 and world format 0.8 to npm.
+
+## Object manifests 0.9, libraries and the library release record (RFC-0011)
+
+New contract files; no IPC or world format change (world formats stay 0.1–0.8).
+Object manifests use the world format numbering: a world may use objects whose
+`formatVersion` is at most its own.
+
+- `v0.9/object.schema.json` (`object.json`): `id` (slug, equals the directory
+  name), SemVer `version`, `name`, `category`, `tags`, a directory-relative
+  `scene`, `license` + `attribution`, rest-pose `bounds`, optional `thumbnail`
+  and `lighting`, `traits` and optional `slots`. Traits: `decorative` (0.8 node
+  animations), `collidable` (0.8 proxy), `movable` (`surfaces`, `upright`,
+  `scale`), `character` (measured `clips` with `walk` and `idle`, `height`,
+  `radius`, `accent`, asset-level `say`/`panel` interactions) and `seat`
+  (anchors, `capacity`). `mover`, `machine`, `mount` and `interactive` are
+  reserved and rejected with a reason. Slots `states`, `labels`, `spawns` and
+  `effects` (at most 8 each) are validated and inert.
+- `v0.9/library.schema.json` (`library.json`): reverse-domain `id`, `version`,
+  `name`, `license` + `attribution` and 1–256 listed `objects`.
+- `v0.9/library-releases.schema.json`: the meta repository's
+  `libraries/releases.json`, one record per `id@version` (`id`, `version`,
+  `formatVersion`, `url`, `sha256`, `nixHash`, `published`).
+- **Draft** `v0.10/object.schema.json` and `v0.10/library.schema.json`: 0.9 plus
+  the `mover` trait, RFC-0013's `machine` trait (typed `inputs` with `repeat`,
+  `drives` in the mapping language, `primary`, `positions`, `recipes`) and the
+  slot additions (`labels` font/align/colour/plate, `spawns` track/items/maxRate,
+  `effects` kind/colour/durationMs, new `tracks`, `stacks`, `toggles`, `ports`).
+  It may change until world format 0.10 is defined.
+- `validate('object', manifest, undefined, format?, options)`: trait
+  combinations, origin conventions (floor, wall and ceiling within 1 cm; a
+  character's rest-pose feet within 5 cm), slot
+  ids, poses inside the bounds grown by 0.5 m, palettes, seat anchors, track
+  points and arcs, stack layouts, machine input references, drive targets and
+  output domains. With `options.gltf`: the format's glTF extension rules, node
+  names (unique, in the scene; the proxy may sit outside it), the 0.8 animation
+  and proxy rules, states-slot materials and nodes (one slot each),
+  `KHR_materials_variants` mappings (variant names of a states slot are palette
+  ids), character skins, clips and `extras.speed` (2%), triangle budgets
+  (50,000; characters 16,000; items 2,000; proxy 2,000) and bounds (exact for
+  axis-aligned meshes, else a containing box). `options.files`, `thumbnail`,
+  `measured` and `directory` add the directory limits, attribution coverage, the
+  256 x 256 thumbnail, the 1 cm bounds check and texture and GPU budgets.
+  Results carry `warnings`.
+- `validate('library', manifest, undefined, format?, {objects, files})` and
+  `validate('library-releases', record)`. `objectFormats` and `objectLimits` are
+  exported. The CLI accepts `object` (with an optional glTF/GLB), `library` and
+  `library-releases`.
+
+## IPC 0.21: markers, personal quests and focus sessions
+
+- New grant `quest.control` (hello capabilities): every quest and focus mutation
+  and `guidance.set`.
+- Required state keys: `markers {reveal, persistent, calm, coreDraw, list}`
+  (reveal `holdMs` 0 = toggle or 1000..15000, `fadeMs` 0..600; at most 64
+  markers with tier 1..4, labels up to 48 characters, one target of position,
+  zone, area, place or workspace), `quests {enabled, tracked, active[<=16],
+  counts, world: null}` and `focus {state, pausedState, sessionId,
+  phaseStartedAtMs, phaseEndsAtMs, phaseMs, remainingMs, creditedMs, crediting,
+  cycle, cycles, breakKind, countMode, target, calm}`. Times are monotonic ms.
+- Methods: `markers.reveal {durationMs?}` (shell.control); `guidance.get`,
+  `guidance.set {patch}` returning `{config, defaults, overrides, ranges,
+  options, path, error}` over 21 flat dotted keys; `quests.list {states?,
+  sources?}`, `quests.get {questRef}`, `quests.track {questRef|null}`,
+  `quests.accept/abandon/resume/delete {questRef}`, `quests.create {quest}`
+  (`{revision, questRef}`), `quests.update {questRef, quest}`, `quests.mark
+  {questRef, stepId, objectiveId}`; `focus.start {target?, questRef?,
+  objectiveId?, overrides?}` (`{revision, sessionId}`),
+  `focus.pause/resume/skip/stop {}`, `focus.history {days?}` (at most 512
+  intervals). Personal quests: 1..16 steps, 1..8 `manual`, `reach` or `focus`
+  objectives per step.
+- Events: `quest.progress` and `focus.phase` (`focusSessionId`; every event
+  carries the IPC `sessionId` and `revision`).
+- `inputConfig` world mode gains `markers.reveal`; `overlayStyle` gains
+  required `questColor` (optional in the patch); `spatial.projection` markers
+  gain optional `markerId`.
+- File schemas: `v0.21/quests-personal.schema.json`,
+  `v0.21/guidance.schema.json`, `v0.21/focus-history.schema.json`.
+- Everything else is inherited from 0.20 unchanged; `session.hello` reports
+  `0.21`. Inheritance test included.
+
+## IPC 0.22: object catalog, user placements and libraries (RFC-0011 P1)
+
+- New grant `objects.control` (hello capabilities): every overlay change and
+  library install/remove.
+- Required state key `objects {catalogRevision, instances[<=512], pocket[<=16],
+  usage, limits}`. An instance is `{id, source (authored|user), ref, name,
+  areaId, pose, scale, state (active|hidden|missing|blocked|loading|suspended),
+  movable, locked, rule, path, activity, seat}`; `path`, `activity` and `seat`
+  are always null until P2. `usage`/`limits` count this world's user
+  placements (placements, assets, triangles, gpuBytes, collisionTriangles).
+- Methods: `objects.catalog {}` (`{revision, entries[<=1024]}`; an entry carries
+  ref, source, id, version, formatVersion, name, description, category, tags,
+  traits, surfaces, scale range, bounds, triangles, gpuBytes,
+  collisionTriangles, an absolute thumbnail path, license, library, other
+  versions, state, placeable, reason and up to 8 errors);
+  `objects.pocket {ref}` (`{revision, itemId}`); `objects.place {ref, pose?,
+  scale?}` (`{revision, id}`); `objects.transform {id, pose, scale?}`;
+  `objects.remove {id}|{all:true}`; `objects.hide {id, hidden}`;
+  `objects.reset {id}|{all:true}`; `objects.configure {id, patch:{locked}}`;
+  `libraries.list {}`; `libraries.install {archive, sha256}` (`{revision, id,
+  version}`); `libraries.remove {id, version}`. Refs are
+  `package/<asset>`, `library/<id>@<semver>/<object>` or `user/<object>`.
+- `editor.selectedKind` gains `node`; `editor.submode` gains `universal`;
+  `editor.unplaced` gains `objects` (pocket items, `count` up to 32); new
+  required `editor.gizmo {space, pivot, snap}`.
+- Error `data` may carry `rule` (the placement rule or limit that refused a
+  method).
+- Everything else is inherited from 0.21 unchanged; `session.hello` reports
+  `0.22`. Inheritance test included.
+
+## @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.

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.8), the IPC protocol (0.1–0.19), 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.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/).
 
 ## Install
 
@@ -156,3 +156,55 @@ stays `editor.unplaced.windows`. `spatial.map` gains optional `levels` (1-6
 per-level blueprint SVGs). `extensions/blueprint.schema.json` defines the world
 extension `com.hyprune.blueprint` 0.1 that supplies them. Every other 0.19
 definition is unchanged. See the RFC-0004 and RFC-0005 amendments for IPC 0.20.
+
+IPC **0.21** adds markers, personal quests and focus sessions (RFC-0012 P1). Three
+new required state keys: `markers` (the marker reveal, the persistent-marker mode
+and up to 64 resolved markers), `quests` (tracked and up to 16 active quests,
+counts) and `focus` (the focus session phase, monotonic phase times, credited
+time, cycles and target). New methods `markers.reveal` (shell.control),
+`guidance.get`/`guidance.set` (marker, quest and focus settings, the `player.get`
+pattern), `quests.list/get/track/accept/abandon/resume/create/update/delete/mark`
+and `focus.start/pause/resume/skip/stop/history`; mutations need the new
+`quest.control` grant. Events `quest.progress` and `focus.phase`. The world keymap
+gains `markers.reveal`, the overlay style a required `questColor`, and
+`spatial.projection` markers an optional `markerId`. File schemas in `v0.21/`:
+`quests-personal.schema.json` (`quests/personal.json`), `guidance.schema.json`
+(`guidance.json`) and `focus-history.schema.json` (one `focus/history.jsonl`
+line). Every other 0.20 definition is unchanged. See RFC-0012.
+
+IPC **0.22** adds the object catalog and user placements (RFC-0011 P1): the
+`objects.control` grant, a required `objects` state key (this world's authored
+and user instances, object pocket items, user-object usage and limits),
+`objects.catalog/pocket/place/transform/remove/hide/reset/configure` and
+`libraries.list/install/remove`. `editor.selectedKind` gains `node`,
+`editor.submode` gains `universal`, `editor.unplaced` gains `objects` and the
+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".
+
+## Objects and libraries (RFC-0011)
+
+Object manifests (`object.json`) and library manifests (`library.json`) use the
+world format numbering and start at **0.9** (`v0.9/object.schema.json`,
+`v0.9/library.schema.json`); `v0.9/library-releases.schema.json` describes the
+meta repository's `libraries/releases.json`. `v0.10/` holds a **draft** that adds
+the `mover` trait, RFC-0013's `machine` trait and the extra slot kinds; it may
+change until world format 0.10 is defined.
+
+```js
+import { validate, objectFormats } from '@hyprune/schema';
+const result = validate('object', manifest, undefined, undefined, { gltf, directory: 'street-lantern' });
+// result.errors, result.warnings, result.triangles
+```
+
+```sh
+npm run validate -- object examples/object.json
+npm run validate -- object objects/bench/object.json - 0.9 objects/bench/object.glb
+npm run validate -- library examples/library.json
+npm run validate -- library-releases examples/library-releases.json
+```
+
+The validator is pure: it never reads files. Pass `gltf` (the parsed glTF or a
+GLB's JSON chunk) for the scene cross-checks, and `files`, `thumbnail` and
+`measured` (exact rest bounds, largest texture, GPU bytes) when you have them;
+`@hyprune/sdk`'s `hyprune object check <dir>` gathers all of them for a directory.

package/bin/validate.mjs

@@ -2,17 +2,27 @@
 import { readFileSync } from 'node:fs';
 import { validate } from '../lib/validate.mjs';
 const [kind, file, method, version, worldFile, asset, ...extra] = process.argv.slice(2);
-if (!kind || !file || extra.length || ((worldFile || asset) && kind !== 'scene')) {
+// For kind `object` the fifth argument is the object's glTF (.gltf or .glb) for the cross-checks.
+const gltfJson = path => {
+  const bytes = readFileSync(path);
+  if (!/\.glb$/i.test(path)) return JSON.parse(bytes.toString('utf8'));
+  if (bytes.length < 20 || bytes.readUInt32LE(0) !== 0x46546c67 || bytes.readUInt32LE(16) !== 0x4e4f534a) throw new Error('Invalid GLB header/JSON chunk');
+  return JSON.parse(bytes.subarray(20, 20 + bytes.readUInt32LE(12)).toString('utf8'));
+};
+if (!kind || !file || extra.length || ((worldFile || asset) && kind !== 'scene' && kind !== 'object') || (asset && kind === 'object')) {
   console.error('Usage: hyprune-validate <world|extension|screen-type|ipc> <file.json|-> [response-method|-] [contract-version]\n' +
-                '       hyprune-validate scene <scene.gltf> - <world-format> <world.json> [object-asset-id]\n(in this repository: npm run validate -- ...)');
+                '       hyprune-validate scene <scene.gltf> - <world-format> <world.json> [object-asset-id]\n' +
+                '       hyprune-validate <object|library|library-releases> <file.json|-> [-] [format] [object scene.gltf|.glb]\n(in this repository: npm run validate -- ...)');
   process.exitCode = 2;
 } else {
   try {
     const bytes = readFileSync(file === '-' ? 0 : file);
     if (bytes.length > 1_048_576) throw new Error('Document exceeds 1 MiB');
     const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
-    const world = worldFile ? JSON.parse(readFileSync(worldFile, 'utf8')) : undefined;
-    const result = validate(kind, value, method === '-' ? undefined : method, version, { world, asset });
+    const options = kind === 'object' ? { gltf: worldFile ? gltfJson(worldFile) : undefined }
+      : { world: worldFile ? JSON.parse(readFileSync(worldFile, 'utf8')) : undefined, asset };
+    const result = validate(kind, value, method === '-' ? undefined : method, version || undefined, options);
+    for (const warning of result.warnings || []) console.error(`warning: ${warning}`);
     if (result.valid) console.log(`VALID ${kind}: ${file}`);
     else { console.error(result.errors.join('\n')); process.exitCode = 1; }
   } catch (error) { console.error(error.message); process.exitCode = 2; }

package/examples/library-releases.json

@@ -0,0 +1,11 @@
+{
+  "com.example.street@1.2.0": {
+    "id": "com.example.street",
+    "version": "1.2.0",
+    "formatVersion": "0.9",
+    "url": "https://example.com/releases/street-v1.2.0/com.example.street-1.2.0.tar.zst",
+    "sha256": "f06838d7b0725080016c84ae4f47aa01367ee665e3844637b14ed7f23706c894",
+    "nixHash": "sha256-8Gg417ByUIABbISuT0eqATZ+5mXjhEY3sU7X8jcGyJQ=",
+    "published": false
+  }
+}

package/examples/library.json

@@ -0,0 +1,18 @@
+{
+  "formatVersion": "0.9",
+  "id": "com.example.street",
+  "version": "1.2.0",
+  "name": "Street kit",
+  "license": "CC-BY-4.0",
+  "attribution": [
+    {
+      "path": ".",
+      "author": "Example Author",
+      "license": "CC-BY-4.0"
+    }
+  ],
+  "objects": [
+    "street-lantern",
+    "bench"
+  ]
+}

package/examples/object-character.json

@@ -0,0 +1,69 @@
+{
+  "formatVersion": "0.9",
+  "id": "resident",
+  "version": "1.0.0",
+  "name": "Resident",
+  "category": "characters",
+  "scene": "object.glb",
+  "license": "CC-BY-4.0",
+  "attribution": [
+    {
+      "path": ".",
+      "author": "Example Author",
+      "license": "CC-BY-4.0"
+    }
+  ],
+  "bounds": {
+    "min": [
+      -0.45,
+      0,
+      -0.2
+    ],
+    "max": [
+      0.45,
+      1.69,
+      0.22
+    ]
+  },
+  "thumbnail": "thumbnail.png",
+  "traits": {
+    "character": {
+      "clips": {
+        "walk": {
+          "speed": 1.12
+        },
+        "run": {
+          "speed": 2.9
+        },
+        "idle": {},
+        "sit": {
+          "seatHeight": 0.46
+        },
+        "sit_idle": {}
+      },
+      "height": 1.69,
+      "radius": 0.3,
+      "accent": false,
+      "interactions": [
+        {
+          "id": "talk",
+          "label": "Talk",
+          "action": {
+            "type": "say",
+            "lines": [
+              "The lifts run every few minutes."
+            ]
+          }
+        },
+        {
+          "id": "where",
+          "label": "Where am I?",
+          "action": {
+            "type": "panel",
+            "panel": "map"
+          }
+        }
+      ]
+    }
+  }
+}

package/examples/object-machine.json

@@ -0,0 +1,338 @@
+{
+  "formatVersion": "0.10",
+  "id": "conveyor",
+  "version": "1.0.0",
+  "name": "Conveyor",
+  "category": "machines",
+  "tags": [
+    "ci",
+    "pipeline"
+  ],
+  "scene": "object.glb",
+  "license": "CC-BY-4.0",
+  "attribution": [
+    {
+      "path": ".",
+      "author": "Example Author",
+      "license": "CC-BY-4.0"
+    }
+  ],
+  "bounds": {
+    "min": [
+      -2.2,
+      0,
+      -0.8
+    ],
+    "max": [
+      2.2,
+      1.9,
+      0.8
+    ]
+  },
+  "traits": {
+    "decorative": {
+      "animations": [
+        {
+          "node": "belt-rollers",
+          "type": "spin",
+          "axis": [
+            1,
+            0,
+            0
+          ],
+          "pivot": [
+            0,
+            0.6,
+            0
+          ],
+          "period": 1.2
+        }
+      ]
+    },
+    "collidable": {
+      "node": "proxy"
+    },
+    "movable": {
+      "surfaces": [
+        "floor"
+      ]
+    },
+    "machine": {
+      "primary": "status",
+      "inputs": [
+        {
+          "id": "status",
+          "type": "enum",
+          "values": [
+            "idle",
+            "running",
+            "ok",
+            "fail"
+          ],
+          "default": "idle",
+          "label": "Pipeline status",
+          "explain": "Lamp colour and belt motion: the belt runs while the pipeline runs."
+        },
+        {
+          "id": "jobStarted",
+          "type": "event",
+          "label": "Job started",
+          "explain": "Each started job drops a crate onto the belt."
+        },
+        {
+          "id": "queued",
+          "type": "int",
+          "min": 0,
+          "max": 64,
+          "default": 0,
+          "label": "Queued jobs",
+          "explain": "Crates waiting beside the entry, one per queued job."
+        },
+        {
+          "id": "lastJob",
+          "type": "text",
+          "maxLength": 24,
+          "label": "Last job",
+          "explain": "The most recent job's name."
+        }
+      ],
+      "drives": [
+        {
+          "input": "status",
+          "target": "state:lamp"
+        },
+        {
+          "input": "status",
+          "target": "animation:belt-rollers",
+          "map": {
+            "cases": [
+              {
+                "equals": "running",
+                "to": 1
+              }
+            ],
+            "else": 0
+          }
+        },
+        {
+          "input": "queued",
+          "target": "count:waiting"
+        },
+        {
+          "input": "lastJob",
+          "target": "label:sign"
+        },
+        {
+          "input": "jobStarted",
+          "target": "spawn:belt-in"
+        },
+        {
+          "input": "status",
+          "target": "effect:confetti",
+          "map": {
+            "becomes": "ok",
+            "from": "running"
+          }
+        }
+      ],
+      "recipes": [
+        {
+          "name": "Pipeline summary JSON",
+          "fields": {
+            "status": "/pipelines/0/status",
+            "jobStarted": "/pipelines/0/jobs_started",
+            "queued": {
+              "countWhere": {
+                "array": "/jobs",
+                "pointer": "/status",
+                "equals": "queued"
+              }
+            },
+            "lastJob": "/pipelines/0/last_job/name"
+          }
+        }
+      ]
+    }
+  },
+  "slots": {
+    "states": [
+      {
+        "id": "lamp",
+        "materials": [
+          "lamp-glass"
+        ],
+        "palette": [
+          {
+            "id": "idle",
+            "colour": [
+              0.35,
+              0.45,
+              0.6
+            ],
+            "emission": 0.5
+          },
+          {
+            "id": "running",
+            "colour": [
+              1.0,
+              0.7,
+              0.2
+            ],
+            "emission": 2
+          },
+          {
+            "id": "ok",
+            "colour": [
+              0.3,
+              1.0,
+              0.45
+            ],
+            "emission": 2
+          },
+          {
+            "id": "fail",
+            "colour": [
+              1.0,
+              0.2,
+              0.15
+            ],
+            "emission": 3
+          },
+          {
+            "id": "stale",
+            "colour": [
+              0.4,
+              0.4,
+              0.4
+            ],
+            "emission": 0.2
+          }
+        ]
+      }
+    ],
+    "labels": [
+      {
+        "id": "sign",
+        "pose": {
+          "position": [
+            0,
+            1.75,
+            0.81
+          ],
+          "rotation": [
+            0,
+            0,
+            0,
+            1
+          ]
+        },
+        "size": [
+          1.2,
+          0.3
+        ],
+        "maxChars": 24,
+        "font": "mono"
+      }
+    ],
+    "tracks": [
+      {
+        "id": "belt",
+        "speed": 0.6,
+        "points": [
+          {
+            "position": [
+              -2,
+              0.8,
+              0
+            ],
+            "type": "line"
+          },
+          {
+            "position": [
+              2,
+              0.8,
+              0
+            ],
+            "type": "line"
+          }
+        ],
+        "items": {
+          "assets": [
+            "job-crate"
+          ],
+          "max": 24,
+          "spacing": 0.45
+        },
+        "sink": true
+      }
+    ],
+    "spawns": [
+      {
+        "id": "belt-in",
+        "pose": {
+          "position": [
+            -2,
+            0.8,
+            0
+          ],
+          "rotation": [
+            0,
+            0.707,
+            0,
+            0.707
+          ]
+        },
+        "track": "belt",
+        "items": [
+          "job-crate"
+        ],
+        "maxRate": 2
+      }
+    ],
+    "stacks": [
+      {
+        "id": "waiting",
+        "node": "crate",
+        "cap": 64,
+        "layout": {
+          "grid": [
+            4,
+            4,
+            4
+          ],
+          "spacing": [
+            0.35,
+            0.35,
+            0.35
+          ],
+          "fill": "xzy"
+        }
+      }
+    ],
+    "effects": [
+      {
+        "id": "confetti",
+        "pose": {
+          "position": [
+            0,
+            2.0,
+            0
+          ],
+          "rotation": [
+            0,
+            0,
+            0,
+            1
+          ]
+        },
+        "kind": "burst",
+        "colour": [
+          1.0,
+          0.8,
+          0.2
+        ],
+        "durationMs": 1500
+      }
+    ]
+  }
+}