@hypersoniclabs/helix-cli 0.1.25-helix3.518 → 0.1.25-helix3.520

package/README.md

@@ -78,7 +78,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix item thumbnail set <item-id> <image> [--json]` | Upload your own thumbnail (png/jpg/webp, up to 10 MiB, checked locally) for a published item (`PUT /api/v1/universal-items/<id>/thumbnail`, moderated). A creator upload stays in place across version moves until you run `thumbnail refresh --force`. 403 = you are not the item's owner. |
 | `helix item lods <packageId>[@version] \| --item <id> \| --glb <file> [--out <dir>] [--variant <id>] [--profile prop\|vehicle] [--api-url <url>] [--json]` | Compile the `helix.item-lod/1` Runtime Artifact for a published prop, Device or vehicle Package Version: up to two levels, LOD1 (props at most 25% of the triangles, vehicles max(5000, 10%), textures at most 512 px) and LOD2 (at most 300 triangles, textures at most 256 px), each its own GLB drawn in one primitive per render state (usually 1 or 2, via a baked material atlas) with its own textures (never larger than what they replace) and a measured `maxErrorM`, plus an 8-view 512 px octahedral impostor atlas. A level that does not cut half the triangles, or cannot be made strictly smaller in bytes (a vehicle LOD2 also: one over 25% of the extent from the source), is omitted. Content-addressed and deterministic; skinned input (avatars, add-ons) is refused. Local preview; the backend worker is the catalogue's source of truth. See [docs/item-lod.md](docs/item-lod.md). |
 | `helix device create <dir> --id <slug> --title <t> --model <mesh.glb> --template standing-desk\|clock\|television` | Scaffold a GLB-backed `helix.device/1` definition, including the interactive TV/media-player template. There is intentionally no website Device editor. |
-| `helix device validate [dir] [--json]` | Validate the definition, GLB bytes and named-node bindings, typed state/controls, capabilities, and Home+World compatibility, including [declarative character hand reach](docs/device-hand-reach.md). |
+| `helix device validate [dir] [--json] [--room]` | Validate the definition, GLB bytes and named-node bindings, typed state/controls, capabilities, the runtime 512-step graph budget, `deadline` triggers, `fill` action args, and Home+World compatibility, including [declarative character hand reach](docs/device-hand-reach.md). `--room` also refuses state writes the room cannot run: any write reachable from an `interact` trigger through `emitSignal` handlers, `delay` or `branch` (the rule the backend applies when sealing a new publish). |
 | `helix device test [dir] [--mode single\|multiplayer\|both] [--json]` | Exercise every interaction, persistence remount, and deterministic one-/two-client authority convergence. |
 | `helix world scene-elements compile <input> --output <scene>` | Compile typed Scene v2 authoring, including exact Continuum Device pins, instances, and locally validated typed links. See [`examples/scene-elements-devices.json`](examples/scene-elements-devices.json). |
 | `helix preview-video <slug> <youtube-url>` | Set or clear a published world's YouTube preview. |

package/dist/device.d.ts

@@ -23,7 +23,7 @@ export declare const DEVICE_INTERACTION_VERB_LIST: string;
  * fail `helix device validate` while the client loaded it happily. Add
  * capabilities to both lists, never to one.
  */
-export declare const DEVICE_CAPABILITIES: readonly ["model.glb", "presentation.nodeMotion", "clock.serverTime", "state.typed", "state.durable", "room.authority", "audio.playback", "presentation.light", "presentation.vfx", "character.posture", "character.animate", "character.hand", "signals.local", "screen.render", "screen.input", "app.web.local", "app.web.remote", "app.web.panel", "app.image.remote", "app.image.owner", "app.canvas", "device.ports", "physics.solid"];
+export declare const DEVICE_CAPABILITIES: readonly ["model.glb", "presentation.nodeMotion", "clock.serverTime", "clock.deadline", "state.typed", "state.durable", "room.authority", "audio.playback", "presentation.light", "presentation.vfx", "character.posture", "character.animate", "character.hand", "signals.local", "screen.render", "screen.input", "app.web.local", "app.web.remote", "app.web.panel", "app.image.remote", "app.image.owner", "app.canvas", "device.ports", "physics.solid"];
 /**
  * The closed component vocabulary.
  *
@@ -56,8 +56,12 @@ export declare const DEVICE_GRAPH_STEP_KINDS: readonly ["setState", "toggleState
 export declare const DEVICE_HAND_SOCKETS: readonly ["hand_r.grip", "hand_l.grip"];
 /** The same vocabulary rendered as one readable list for error messages. */
 export declare const DEVICE_HAND_SOCKET_LIST: string;
-/** The closed trigger vocabulary (`validate.ts:224-243`). */
-export declare const DEVICE_TRIGGER_KINDS: readonly ["init", "interact", "stateChanged", "signal", "playerNear"];
+/**
+ * The closed trigger vocabulary (`validate.ts:224-243`), plus `deadline`: an
+ * epoch-ms instant held in numeric state that fires once when the clock reaches
+ * it. Its `do` is the server-evaluable subset (see `validateDeadlineTrigger`).
+ */
+export declare const DEVICE_TRIGGER_KINDS: readonly ["init", "interact", "stateChanged", "signal", "playerNear", "deadline"];
 /** The closed host vocabulary for `compatibility.hosts` (`validate.ts:555-560`). */
 export declare const DEVICE_HOSTS: readonly ["home", "world"];
 /** The same vocabulary rendered as one readable list for error messages. */
@@ -88,7 +92,15 @@ export interface DeviceTestReport {
     errors: string[];
 }
 export declare function readDeviceGlbNodeNames(file: string): string[];
-export declare function validateDeviceProject(input: string): DeviceValidationReport;
+export interface DeviceValidateOptions {
+    /**
+     * Also apply the room (server) authority rule: refuse state writes reachable
+     * from an `interact` trigger through `emitSignal` handlers, `delay`, or
+     * `branch`. The backend applies the same rule when sealing a new publish.
+     */
+    room?: boolean;
+}
+export declare function validateDeviceProject(input: string, options?: DeviceValidateOptions): DeviceValidationReport;
 export declare function testDeviceProject(input: string, mode: 'single' | 'multiplayer'): DeviceTestReport;
 export declare function createDeviceProject(input: {
     directory: string;

package/dist/device.js

@@ -8,6 +8,7 @@ exports.createDeviceProject = createDeviceProject;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const deviceActionValidation_1 = require("./deviceActionValidation");
+const deviceGraphChecks_1 = require("./deviceGraphChecks");
 var deviceActionValidation_2 = require("./deviceActionValidation");
 Object.defineProperty(exports, "deviceActionAstBudgetError", { enumerable: true, get: function () { return deviceActionValidation_2.deviceActionAstBudgetError; } });
 exports.DEVICE_FILENAME = 'device.json';
@@ -61,6 +62,7 @@ exports.DEVICE_CAPABILITIES = [
     'model.glb',
     'presentation.nodeMotion',
     'clock.serverTime',
+    'clock.deadline',
     'state.typed',
     'state.durable',
     'room.authority',
@@ -142,13 +144,18 @@ exports.DEVICE_GRAPH_STEP_KINDS = [
 exports.DEVICE_HAND_SOCKETS = ['hand_r.grip', 'hand_l.grip'];
 /** The same vocabulary rendered as one readable list for error messages. */
 exports.DEVICE_HAND_SOCKET_LIST = exports.DEVICE_HAND_SOCKETS.join('|');
-/** The closed trigger vocabulary (`validate.ts:224-243`). */
+/**
+ * The closed trigger vocabulary (`validate.ts:224-243`), plus `deadline`: an
+ * epoch-ms instant held in numeric state that fires once when the clock reaches
+ * it. Its `do` is the server-evaluable subset (see `validateDeadlineTrigger`).
+ */
 exports.DEVICE_TRIGGER_KINDS = [
     'init',
     'interact',
     'stateChanged',
     'signal',
     'playerNear',
+    'deadline',
 ];
 /** The closed host vocabulary for `compatibility.hosts` (`validate.ts:555-560`). */
 exports.DEVICE_HOSTS = ['home', 'world'];
@@ -353,6 +360,39 @@ function validateGraphCondition(raw, context, path) {
     validateGraphExpr(node.right, context, `${path}.right`);
 }
 const DEVICE_GRAPH_MAX_BRANCH_DEPTH = 8;
+/**
+ * The interaction `display` hint: `{ kind: 'time', stateKey }` renders an
+ * epoch-millisecond state value in the VIEWER's local time ("rings 7:00 AM"),
+ * and "Off" when it is 0 or absent. The hint is presentation only.
+ */
+function validateInteractionDisplay(raw, id, state, errors) {
+    const path = `interaction ${id} display`;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        errors.push(`${path} must be an object`);
+        return;
+    }
+    const display = object(raw);
+    if (display.kind !== 'time') {
+        errors.push(`${path}.kind must be "time"`);
+    }
+    for (const key of Object.keys(display)) {
+        if (key !== 'kind' && key !== 'stateKey') {
+            errors.push(`${path}: unknown field "${key}"`);
+        }
+    }
+    if (!isNonEmptyName(display.stateKey)) {
+        errors.push(`${path}.stateKey must be a non-empty state key`);
+    }
+    else {
+        const spec = object(state[String(display.stateKey)]);
+        if (state[String(display.stateKey)] === undefined) {
+            errors.push(`${path}.stateKey "${String(display.stateKey)}" is not declared in state`);
+        }
+        else if (spec.type !== 'float' && spec.type !== 'integer') {
+            errors.push(`${path}.stateKey "${String(display.stateKey)}" must be a float or integer state holding epoch milliseconds`);
+        }
+    }
+}
 /**
  * Validate one behavior-graph step list, recursing into every nested list.
  *
@@ -1307,7 +1347,7 @@ function deviceWebPanelInteractionError(definition, interaction) {
     }
     return null;
 }
-function validateDeviceProject(input) {
+function validateDeviceProject(input, options = {}) {
     const target = readDefinitionPath(input);
     const errors = [];
     const warnings = [];
@@ -1537,6 +1577,9 @@ function validateDeviceProject(input) {
             errors.push(`interaction ${id} requires a label`);
         else if (interaction.label.length > 40)
             errors.push(`interaction ${id} label must be 40 characters or fewer`);
+        if (interaction.display !== undefined) {
+            validateInteractionDisplay(interaction.display, id, state, errors);
+        }
         if (interaction.maxDistanceM !== undefined) {
             if (!isFiniteNumber(interaction.maxDistanceM) ||
                 interaction.maxDistanceM <= 0 ||
@@ -2242,6 +2285,8 @@ function validateDeviceProject(input) {
         errors,
         usage: graphUsage,
     };
+    let deadlineTriggerUsed = false;
+    const deadlineKeys = new Set();
     triggers.forEach((raw, index) => {
         const triggerPath = `graph.triggers.${index}`;
         if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
@@ -2265,6 +2310,15 @@ function validateDeviceProject(input) {
             if (!isNonEmptyName(trigger.key))
                 errors.push(`${triggerPath}: stateChanged requires a non-empty key`);
         }
+        else if (on === 'deadline') {
+            if (typeof trigger.key === 'string' && deadlineKeys.has(trigger.key)) {
+                errors.push(`${triggerPath}: deadline key "${trigger.key}" is declared by more than one deadline trigger`);
+            }
+            if (typeof trigger.key === 'string')
+                deadlineKeys.add(trigger.key);
+            deadlineTriggerUsed = true;
+            errors.push(...(0, deviceGraphChecks_1.deviceDeadlineTriggerErrors)(trigger, triggerPath, state));
+        }
         else if (on === 'signal') {
             if (!isNonEmptyName(trigger.name))
                 errors.push(`${triggerPath}: signal requires a non-empty name`);
@@ -2309,6 +2363,12 @@ function validateDeviceProject(input) {
             }
         }
     });
+    // The engine charges one counter for every step of every trigger, nested
+    // steps included (`PortableDeviceSupport.unsupportedStep`); the per-action AST
+    // budget above does not see the graph at all.
+    errors.push(...(0, deviceGraphChecks_1.deviceGraphBudgetErrors)(triggers));
+    if (options.room)
+        errors.push(...(0, deviceGraphChecks_1.deviceRoomAuthorityErrors)(definition));
     // `compatibility` itself is optional on the host, and its `hosts` array is a
     // `min(1)` enum — NOT "both home and world". Demanding both here rejected a
     // world-only Device the host loads happily.
@@ -2366,6 +2426,7 @@ function validateDeviceProject(input) {
             Object.values(state).some((spec) => object(spec).persist === true),
         ],
         ['presentation.nodeMotion', graphUsage.nodeMotion],
+        ['clock.deadline', deadlineTriggerUsed],
         [
             'clock.serverTime',
             components.some((component) => component.type === 'clockHands'),