@hyprune/schema 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -142,3 +142,46 @@ 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.

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.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/).
 
 ## 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,11 @@ 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.

package/bin/validate.mjs

@@ -1,10 +1,10 @@
 #!/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);
+if (!kind || !file || extra.length || ((worldFile || asset) && kind !== 'scene')) {
   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(in this repository: npm run validate -- ...)');
   process.exitCode = 2;
 } else {
   try {
@@ -12,7 +12,7 @@ if (!kind || !file || extra.length || (worldFile && kind !== 'scene')) {
     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 result = validate(kind, value, method === '-' ? undefined : method, version, { world, asset });
     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/extensions/blueprint.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hyprune.com/schema/extensions/blueprint.schema.json",
+  "title": "com.hyprune.blueprint 0.1 world manifest value",
+  "description": "Per-level blueprint SVGs in the frame of the package's com.hyprune.map 0.1 (RFC-0004 amendment). Levels are sorted by minY and must not overlap (maxY[i] <= minY[i+1]); each SVG is at most 65536 bytes, all levels together at most 262144 bytes, using the map SVG subset plus a class attribute from: grid floor wall stair opening screen mount area label route waypoint void outline. Consumers enforce those rules.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "levels"],
+  "properties": {
+    "version": {"const": "0.1"},
+    "levels": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 6,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "name", "minY", "maxY", "path"],
+        "properties": {
+          "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{0,31}$"},
+          "name": {"type": "string", "minLength": 1, "maxLength": 64},
+          "minY": {"type": "number"},
+          "maxY": {"type": "number"},
+          "path": {"type": "string", "minLength": 1, "maxLength": 200, "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[A-Za-z0-9_./-]+\\.svg$"}
+        }
+      }
+    }
+  }
+}

package/lib/validate.d.mts

@@ -12,6 +12,12 @@ export interface ValidationResult {
 export interface ValidateOptions {
   /** For kind `scene`: the package's parsed world.json (lightmap checks). */
   world?: unknown;
+  /**
+   * For kind `scene` from world 0.8: validate `value` as the glTF of this
+   * `world.objectAssets[].id` (extension rules, animation and collision node
+   * names, nesting) instead of the world's scene.gltf.
+   */
+  asset?: string;
 }
 
 /**

package/lib/validate.mjs

@@ -36,9 +36,35 @@ export function sceneExtensions(version) {
   const base = ['KHR_materials_unlit','KHR_texture_transform','KHR_materials_emissive_strength'];
   return atLeast(version, '0.7') ? [...base,'KHR_texture_basisu','EXT_meshopt_compression','KHR_mesh_quantization'] : base;
 }
+// World 0.8 object asset rules that need the asset's glTF (RFC-0004 "world 0.8"):
+// referenced node names exist once, animated subtrees do not nest, and the
+// collision proxy has a mesh and lies outside every animated subtree.
+function validateObjectAsset(gltf, asset, fail) {
+  const nodes = gltf.nodes || [], parents = new Map(), label = `objectAssets ${asset.id}`;
+  nodes.forEach((n, i) => { for (const c of n.children || []) parents.set(c, i); });
+  const find = name => {
+    const hits = nodes.flatMap((n, i) => n.name === name ? [i] : []);
+    if (hits.length !== 1) fail(`${label}: node "${name}" ${hits.length ? 'is not unique' : 'not found'} in the asset`);
+    return hits.length === 1 ? hits[0] : undefined;
+  };
+  const ancestors = node => { const out = []; for (let p = parents.get(node), n = 0; p !== undefined && n <= nodes.length; p = parents.get(p), n++) out.push(p); return out; };
+  const targets = new Map();
+  for (const a of asset.animations || []) { const i = find(a.node); if (i !== undefined) targets.set(i, a.node); }
+  for (const [node, name] of targets) for (const p of ancestors(node))
+    if (targets.has(p)) fail(`${label}: animation "${name}" is inside animated node "${targets.get(p)}"`);
+  if (asset.collision) {
+    const i = find(asset.collision.node);
+    if (i !== undefined) {
+      if (nodes[i].mesh === undefined) fail(`${label}: collision node "${asset.collision.node}" has no mesh`);
+      for (const p of [i, ...ancestors(i)]) if (targets.has(p)) fail(`${label}: collision node "${asset.collision.node}" is inside animated node "${targets.get(p)}"`);
+    }
+  }
+}
 // scene.gltf rules that depend on the world format: extensionsRequired, and
 // lightmap textures (world.lightmaps[].texture) stay PNG in every v0 format.
-function validateScene(gltf, version, world) {
+// With options.asset, `gltf` is that world 0.8 object asset's glTF instead: the
+// same extension rules, the asset rules above, and no lightmaps (assets are never baked).
+function validateScene(gltf, version, world, assetId) {
   const errors = [], fail = m => errors.push(m);
   if (!worldFormats.includes(version)) throw new Error(`Unknown world format: ${version}`);
   const allowed = new Set(sceneExtensions(version)), required = new Set(gltf.extensionsRequired || []);
@@ -55,6 +81,12 @@ function validateScene(gltf, version, world) {
   if ((gltf.bufferViews || []).some(v => v.extensions?.EXT_meshopt_compression) && !required.has('EXT_meshopt_compression'))
     fail(allowed.has('EXT_meshopt_compression') ? 'extensionsRequired: EXT_meshopt_compression must be listed when buffer views use it'
                                                 : 'bufferViews: EXT_meshopt_compression needs world 0.7');
+  if (assetId !== undefined) {
+    const asset = atLeast(version, '0.8') ? (world?.objectAssets || []).find(a => a.id === assetId) : undefined;
+    if (!asset) fail(`objectAssets: unknown asset ${assetId} for world ${version}`);
+    else validateObjectAsset(gltf, asset, fail);
+    return { valid: errors.length === 0, errors };
+  }
   for (const lightmap of world?.lightmaps || []) {
     const texture = textures[lightmap.texture];
     if (!texture) { fail(`lightmaps: texture ${lightmap.texture} missing from scene`); continue; }
@@ -70,7 +102,7 @@ function validateScene(gltf, version, world) {
 export function validate(kind, value, method, version = '0.1', options = {}) {
   if (kind === 'scene') {
     if (method) throw new Error('Method context is only valid for IPC');
-    return validateScene(value, version, options.world);
+    return validateScene(value, version, options.world, options.asset);
   }
   if (!names.includes(kind) || kind === 'common') throw new Error(`Unknown schema: ${kind}`);
   if (!contractVersions.includes(version)) throw new Error(`Unknown contract: ${version}`);
@@ -172,6 +204,26 @@ export function validate(kind, value, method, version = '0.1', options = {}) {
       if (Math.abs(Math.hypot(...c.facing)-1) > .001 || Math.abs(axis.reduce((v,n,i)=>v+n*c.facing[i],0)/length) > .001) fail(`${c.id}: facing must be unit and perpendicular to segment`);
       for (const end of ['top','bottom']) if (Math.hypot(...c.exits[end].map((v,i)=>v-c[end][i])) > 3) fail(`${c.id}: exit too far from segment`);
     }
+    if (atLeast(value.formatVersion, '0.8')) {
+      const assets = value.objectAssets || [], objects = value.objects || [];
+      unique(assets, 'id', 'objectAssets'); unique(objects, 'id', 'objects');
+      const ids = new Set(assets.map(a => a.id));
+      for (const a of assets) {
+        const label = `objectAssets ${a.id}`, animations = a.animations || [];
+        if (a.library !== undefined) fail(`${label}: library references are reserved for a later world format; use a package scene`);
+        unique(animations, 'node', `${label} animations`);
+        for (const n of animations) {
+          if (Math.abs(Math.hypot(...n.axis) - 1) > 0.001) fail(`${label}: animation "${n.node}" axis must be a unit vector`);
+          if (n.type === 'bob' ? n.amplitude === undefined : n.pivot === undefined) fail(`${label}: ${n.type} animation "${n.node}" needs ${n.type === 'bob' ? 'an amplitude' : 'a pivot'}`);
+          if (n.type === 'bob' ? n.pivot !== undefined : n.amplitude !== undefined) fail(`${label}: ${n.type} animation "${n.node}" takes no ${n.type === 'bob' ? 'pivot' : 'amplitude'}`);
+        }
+        if (a.collision && animations.some(n => n.node === a.collision.node)) fail(`${label}: collision node "${a.collision.node}" is animated`);
+      }
+      for (const o of objects) {
+        if (!ids.has(o.asset)) fail(`objects ${o.id}: unknown asset ${o.asset}`);
+        quat(o.pose.rotation, `objects ${o.id}`);
+      }
+    }
     unique(value.attribution, 'path', 'attribution');
     for (const a of value.attribution) license(a.license, `attribution ${a.path}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyprune/schema",
-  "version": "0.5.2",
+  "version": "0.6.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",