@hyprune/schema 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -142,3 +142,159 @@ definition exists in 0.16 and the graphics properties differ only by the new key
   action it would take (`""|click|grab|pocket|place|mount|select|path|drop`).
 - Everything else is inherited from 0.18 unchanged, including the offload cap
   and device keys; `session.hello` reports `0.19`.
+
+## IPC 0.20: pocket actions and blueprint map levels
+
+- `surface.pocket {surfaceId}` and `surface.unpocket {surfaceId}` (surface.control).
+  Pocket: the window leaves the world for the Placement queue, its placement kept;
+  idempotent. Unpocket: placed at a free spot in front of the player
+  (`placed: true`) or left in the pocket, selected for the Placement tool
+  (`placed: false`). Results `{revision}` / `{revision, placed}`.
+- `map.levels` (optional, 1..6): `{id, name, minY, maxY, svg, sha256}` per
+  blueprint level, sorted by `minY`, in the frame of the map (`worldToMap`).
+- New `extensions/blueprint.schema.json`: the `com.hyprune.blueprint` 0.1 world
+  extension (levels with package-relative SVG paths; byte budgets, ordering and
+  the `class` vocabulary are stated in its description and enforced by consumers).
+- Everything else is inherited from 0.19 unchanged; `session.hello` reports
+  `0.20` and lists the two methods. Inheritance test included.
+
+## World 0.8: placed world objects
+
+- World format **0.8** adds `objectAssets` (at most 32) and `objects` (at most
+  256). An asset is a package-relative glTF (`scene`, same extension rules as the
+  world's scene.gltf; never lightmapped) with optional declarative node animation
+  (at most 16: `spin` or `orbit` about `pivot`/`axis` in asset space, or `bob`
+  along `axis` by `amplitude` metres; `period` 0.5–3600 s, optional `phase`), an
+  optional static `collision` proxy node and `lighting.mode` (`probe` default, or
+  `unlit`). Nodes are referenced by unique glTF node name. `library` (`id@version`)
+  is reserved for shared object libraries and rejected in 0.8. An object places an
+  asset with a `pose`, uniform `scale` (0.01–100), animation `speed` (0–10, default
+  1), `phase` (0–1) and an optional `ambient` RGB override (0–16).
+- `validate('world')` (from 0.8): unique asset and object ids, known asset
+  references, normalised poses, unit axes, per-type fields (spin/orbit need a
+  pivot and take no amplitude; bob the reverse), one animation per node, collision
+  node not animated, library references rejected. `validate('scene', gltf,
+  undefined, '0.8', {world, asset: id})` checks an asset's glTF: extension rules,
+  referenced node names exist exactly once, no animated node inside another
+  animated subtree, the collision node has a mesh and is outside every animated
+  subtree.
+- `v0.8/common.schema.json` is the 0.7 common definitions under the 0.8 `$id`
+  (the directory already held IPC 0.8, which keeps its own references).
+  Everything else is inherited from 0.7 unchanged. Inheritance test included.
+
+## @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,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.7), 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
 
 ```sh
 npm i -D @hyprune/schema
-npx hyprune-validate world world.json - 0.7             # a world package manifest
-npx hyprune-validate scene scene.gltf - 0.7 world.json   # its glTF against the world format
+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
 ```
 
 ```js
 import { validate, worldFormats } from '@hyprune/schema';
-import schema from '@hyprune/schema/v0.7/world.schema.json' with { type: 'json' };
+import schema from '@hyprune/schema/v0.8/world.schema.json' with { type: 'json' };
 
 const result = validate('world', manifest, undefined, worldFormats.at(-1));
 if (!result.valid) console.error(result.errors.join('\n'));
@@ -118,6 +118,15 @@ optimised scene assets: `KHR_texture_basisu` (KTX2, material textures only),
 `extensionsRequired` and lightmap textures against the world format. Version
 gates use `atLeast()`; see RFC-0004 "world 0.7".
 
+World format **0.8** adds placed world objects: `objectAssets` (package glTF
+assets with optional `spin`/`orbit`/`bob` node animation, a static collision
+proxy and `probe`/`unlit` lighting) and `objects` (instances with pose, scale,
+speed, phase and an optional ambient override). Objects are render-only apart
+from the proxy. Check an asset's glTF with
+`validate('scene', gltf, undefined, '0.8', {world, asset: 'armillary'})` (CLI:
+`npm run validate -- scene objects/armillary.gltf - 0.8 world.json armillary`).
+See RFC-0004 "world 0.8 placed world objects".
+
 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.
@@ -139,3 +148,63 @@ bob, reticle style/size/colour and reach limits), widens graphics `fov` to 30-12
 adds `reticleColor`/`validColor`/`invalidColor` to the overlay style and the
 required `interaction.reticle {state, action}`. Every other 0.18 definition is
 unchanged. See the RFC-0006 amendment "IPC 0.19 player settings and reticle".
+
+IPC **0.20** adds `surface.pocket`/`surface.unpocket` (surface.control): put a
+world window into the pocket (the Placement queue) and take it out again, placed
+in front of the player or selected for the Placement tool (`placed`). Pocket state
+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

@@ -1,18 +1,28 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
 import { validate } from '../lib/validate.mjs';
-const [kind, file, method, version, worldFile, ...extra] = process.argv.slice(2);
-if (!kind || !file || extra.length || (worldFile && kind !== 'scene')) {
+const [kind, file, method, version, worldFile, asset, ...extra] = process.argv.slice(2);
+// 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>\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 });
+    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"
+          }
+        }
+      ]
+    }
+  }
+}