@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/device.js

@@ -0,0 +1,2744 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEVICE_TEXT_INPUT_MODES = exports.DEVICE_THUMBNAIL_POLICIES = exports.DEVICE_HOSTS_LIST = exports.DEVICE_HOSTS = exports.DEVICE_TRIGGER_KINDS = exports.DEVICE_HAND_SOCKET_LIST = exports.DEVICE_HAND_SOCKETS = exports.DEVICE_GRAPH_STEP_KINDS = exports.DEVICE_COMPONENT_TYPES = exports.DEVICE_CAPABILITIES = exports.DEVICE_INTERACTION_VERB_LIST = exports.DEVICE_INTERACTION_VERBS = exports.DEVICE_FILENAME = exports.deviceActionAstBudgetError = void 0;
+exports.readDeviceGlbNodeNames = readDeviceGlbNodeNames;
+exports.validateDeviceProject = validateDeviceProject;
+exports.testDeviceProject = testDeviceProject;
+exports.createDeviceProject = createDeviceProject;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const deviceActionValidation_1 = require("./deviceActionValidation");
+var deviceActionValidation_2 = require("./deviceActionValidation");
+Object.defineProperty(exports, "deviceActionAstBudgetError", { enumerable: true, get: function () { return deviceActionValidation_2.deviceActionAstBudgetError; } });
+exports.DEVICE_FILENAME = 'device.json';
+/**
+ * First-party canvas renderers the web host ships.
+ *
+ * A `canvas` app is drawn by HOST code into an offscreen 2D context and bound
+ * as a texture on the mesh, so the screen is depth-tested and lit like any
+ * other surface instead of being composited over the scene. `entry` therefore
+ * names one of these ids, never a URL: a package selects first-party drawing
+ * code exactly as `localWeb` selects a first-party app path, and can never
+ * ship the code itself.
+ *
+ * Mirrors `DEVICE_CANVAS_APP_IDS` in the web runtime
+ * (`helixgame.com/lib/devices/canvas-apps.ts`). The CLI validates offline, so
+ * the list is duplicated deliberately; add ids to both.
+ */
+const DEVICE_CANVAS_APPS = new Set(['helix.whiteboard/1']);
+/**
+ * The closed interaction verb vocabulary the web host enforces.
+ *
+ * Mirrors the `verb` enum on `DeviceInteraction` in the first-party Device
+ * schema (`helixgame.com/lib/devices/validate.ts`). The host REJECTS anything
+ * else when the package loads, so validating it only in the host let a package
+ * pass `helix device validate` offline and then fail in the client —
+ * `continuum-soju` shipped `"verb": "drink"` that way. The list is duplicated
+ * deliberately; add verbs to both.
+ */
+exports.DEVICE_INTERACTION_VERBS = [
+    'use',
+    'open',
+    'close',
+    'toggle',
+    'play',
+    'sit',
+    'custom',
+];
+/** The same vocabulary rendered as one readable list for error messages. */
+exports.DEVICE_INTERACTION_VERB_LIST = exports.DEVICE_INTERACTION_VERBS.join('|');
+/**
+ * The closed capability vocabulary a package may declare.
+ *
+ * Mirrors `DEVICE_CAPABILITIES` in `helixgame.com/lib/devices/types.ts`. A
+ * capability the client accepts and this list omits is a FALSE REJECTION —
+ * `physics.solid` was exactly that, and it made the shipped
+ * `continuum-garage-door` example (which needs it for its `collision` block)
+ * fail `helix device validate` while the client loaded it happily. Add
+ * capabilities to both lists, never to one.
+ */
+exports.DEVICE_CAPABILITIES = [
+    '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',
+];
+/**
+ * The closed component vocabulary.
+ *
+ * Mirrors the discriminated union on `components` in the client schema
+ * (`validate.ts:423-527`). Branching on an unknown `type` used to fall through
+ * with no check at all, so a component kind this list does not name is rejected
+ * here rather than validated as an empty object.
+ */
+exports.DEVICE_COMPONENT_TYPES = [
+    'slider',
+    'clockHands',
+    'pointLight',
+    'audioReactiveLight',
+    'characterSpot',
+    'screen',
+];
+/**
+ * The closed behavior-graph step vocabulary.
+ *
+ * Mirrors the `step` union in the client schema (`validate.ts:133-222`). Every
+ * kind is validated to the client's depth, including the ones the shipped
+ * examples never use (`moveNode`, `setVfx`, `emitSignal`, `sequence`, `delay`,
+ * `repeat`, `stopAudio`) — their absence from the examples is why the gap went
+ * unnoticed for so long.
+ */
+exports.DEVICE_GRAPH_STEP_KINDS = [
+    'setState',
+    'toggleState',
+    'moveNode',
+    'rotateNode',
+    'playAudio',
+    'stopAudio',
+    'setVfx',
+    'attachCharacter',
+    'playCharacterAnimation',
+    'releaseCharacter',
+    'enterCharacterSpot',
+    'reachCharacterHand',
+    'releaseCharacterHand',
+    'attachItem',
+    'releaseItem',
+    'emitSignal',
+    'branch',
+    'sequence',
+    'delay',
+    'repeat',
+];
+/**
+ * The closed CHARACTER socket set an `attachItem` step may target.
+ *
+ * These are sockets on the acting character, never the Device's own `sockets`:
+ * the two namespaces are unrelated, and a Device that mounts on a wall has no
+ * hand to put anything in. Mirrors `DEVICE_HAND_SOCKETS` in the first-party
+ * host (`helixgame.com/lib/devices/types.ts`) and in the portable engine. The
+ * CLI validates offline, so the list is duplicated deliberately; add sockets
+ * to both.
+ */
+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`). */
+exports.DEVICE_TRIGGER_KINDS = [
+    'init',
+    'interact',
+    'stateChanged',
+    'signal',
+    'playerNear',
+];
+/** The closed host vocabulary for `compatibility.hosts` (`validate.ts:555-560`). */
+exports.DEVICE_HOSTS = ['home', 'world'];
+/** The same vocabulary rendered as one readable list for error messages. */
+exports.DEVICE_HOSTS_LIST = exports.DEVICE_HOSTS.join('|');
+/** The closed `thumbnail.policy` vocabulary (`validate.ts:563-567`). */
+exports.DEVICE_THUMBNAIL_POLICIES = [
+    'catalog',
+    'discreteState',
+    'never',
+];
+const INTERACTION_VERBS = new Set(exports.DEVICE_INTERACTION_VERBS);
+const CAPABILITIES = new Set(exports.DEVICE_CAPABILITIES);
+const COMPONENT_TYPES = new Set(exports.DEVICE_COMPONENT_TYPES);
+const GRAPH_STEP_KINDS = new Set(exports.DEVICE_GRAPH_STEP_KINDS);
+const TRIGGER_KINDS = new Set(exports.DEVICE_TRIGGER_KINDS);
+const HAND_SOCKETS = new Set(exports.DEVICE_HAND_SOCKETS);
+const CHARACTER_HANDS = new Set(['left', 'right']);
+const CHARACTER_HAND_ELBOWS = new Set(['down', 'out', 'up']);
+const DEVICE_HOST_SET = new Set(exports.DEVICE_HOSTS);
+const THUMBNAIL_POLICIES = new Set(exports.DEVICE_THUMBNAIL_POLICIES);
+/**
+ * Device budgets, mirrored from `DEVICE_BUDGETS` in the client's
+ * `types.ts:752-764`. The client enforces every one of these post-parse, so a
+ * definition over budget is CLI-green and load-rejected.
+ */
+const DEVICE_BUDGETS = {
+    maxStateVars: 32,
+    maxPersistentVars: 16,
+    maxEnumValues: 16,
+    maxInteractions: 12,
+    maxTriggers: 64,
+    maxComponents: 32,
+    maxPorts: 32,
+    maxInterfaces: 16,
+    maxCollisionNodes: 8,
+    maxCapabilities: 16,
+    maxThumbnailStateKeys: 16,
+    maxScreens: 4,
+    maxPointLights: 4,
+    maxStepsPerFire: 256,
+    maxConcurrentDelays: 8,
+};
+const DEVICE_EASINGS = new Set(['linear', 'easeOutCubic', 'easeInOutCubic']);
+const DEVICE_GRAPH_EXPR_KINDS = new Set([
+    'lit',
+    'state',
+    'add',
+    'sub',
+    'mul',
+    'min',
+    'max',
+]);
+const DEVICE_GRAPH_CONDITION_OPS = new Set([
+    'true',
+    'false',
+    'and',
+    'or',
+    'not',
+    'eq',
+    'ne',
+    'gt',
+    'lt',
+    'gte',
+    'lte',
+    'inRange',
+]);
+const DEVICE_FFT_SIZES = new Set([32, 64, 128, 256, 512, 1024, 2048]);
+/** The host's `inputMode` vocabulary for a text control (`validate.ts:414-419`). */
+exports.DEVICE_TEXT_INPUT_MODES = [
+    'text',
+    'tel',
+    'url',
+    'email',
+    'numeric',
+    'decimal',
+    'search',
+];
+const TEXT_INPUT_MODES = new Set(exports.DEVICE_TEXT_INPUT_MODES);
+const DEVICE_APP_PERMISSIONS = new Set([
+    'web.content',
+    'network.fetch',
+    'web.externalNavigation',
+    'audio.media',
+]);
+const DEVICE_PORT_DIRECTIONS = new Set(['input', 'output', 'bidirectional']);
+const DEVICE_PORT_AUTHORITIES = new Set(['local', 'server']);
+const DEVICE_STREAM_ROUTABILITY = new Set([
+    'routable',
+    'embedded-only',
+    'unavailable',
+]);
+function object(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function scalar(value) {
+    return (typeof value === 'number' ||
+        typeof value === 'string' ||
+        typeof value === 'boolean');
+}
+function isVec3(value) {
+    return (Array.isArray(value) &&
+        value.length === 3 &&
+        value.every((part) => typeof part === 'number' && Number.isFinite(part)));
+}
+/**
+ * The looser triple the host writes inline on a procedural part
+ * (`z.tuple([z.number(), z.number(), z.number()])`) — no `.finite()`
+ * refinement, unlike its `vec3` alias. Mirrored exactly so a part transform
+ * the host accepts is never refused here.
+ */
+function isNumberTriple(value) {
+    return (Array.isArray(value) &&
+        value.length === 3 &&
+        value.every((part) => typeof part === 'number' && !Number.isNaN(part)));
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isNonEmptyName(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/** A node reference resolved through `model.nodeBindings`, as the host does. */
+function graphNode(context, raw, path) {
+    const semantic = String(raw ?? '');
+    const authored = String(context.bindings[semantic] ?? semantic);
+    if (context.nodesKnown && !context.nodes.has(authored)) {
+        context.errors.push(`${path} resolves to missing GLB node "${authored}"`);
+    }
+}
+function checkEasing(value, path, errors) {
+    if (value !== undefined && !DEVICE_EASINGS.has(String(value))) {
+        errors.push(`${path}: easing "${String(value)}" is unsupported; expected one of ${[...DEVICE_EASINGS].join('|')}`);
+    }
+}
+function validateGraphExpr(raw, context, path) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        context.errors.push(`${path}: expression must be an object`);
+        return;
+    }
+    const node = object(raw);
+    const kind = String(node.kind ?? '');
+    if (!DEVICE_GRAPH_EXPR_KINDS.has(kind)) {
+        context.errors.push(`${path}: unsupported expression kind "${kind}" (one of ${[...DEVICE_GRAPH_EXPR_KINDS].join('|')})`);
+        return;
+    }
+    if (kind === 'lit') {
+        if (!scalar(node.value) || (typeof node.value === 'number' && !Number.isFinite(node.value))) {
+            context.errors.push(`${path}: lit requires a finite scalar value`);
+        }
+        return;
+    }
+    if (kind === 'state') {
+        if (!isNonEmptyName(node.key)) {
+            context.errors.push(`${path}: state expression requires a non-empty key`);
+        }
+        return;
+    }
+    const args = Array.isArray(node.args) ? node.args : [];
+    if (args.length < 1) {
+        context.errors.push(`${path}: ${kind} requires at least one argument`);
+    }
+    args.forEach((arg, index) => validateGraphExpr(arg, context, `${path}.args.${index}`));
+}
+function validateGraphCondition(raw, context, path) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        context.errors.push(`${path}: condition must be an object`);
+        return;
+    }
+    const node = object(raw);
+    const op = String(node.op ?? '');
+    if (!DEVICE_GRAPH_CONDITION_OPS.has(op)) {
+        context.errors.push(`${path}: unsupported condition op "${op}" (one of ${[...DEVICE_GRAPH_CONDITION_OPS].join('|')})`);
+        return;
+    }
+    if (op === 'true' || op === 'false')
+        return;
+    if (op === 'and' || op === 'or') {
+        const parts = Array.isArray(node.of) ? node.of : [];
+        if (parts.length < 1) {
+            context.errors.push(`${path}: ${op} requires at least one condition`);
+        }
+        parts.forEach((part, index) => validateGraphCondition(part, context, `${path}.of.${index}`));
+        return;
+    }
+    if (op === 'not') {
+        validateGraphCondition(node.of, context, `${path}.of`);
+        return;
+    }
+    if (op === 'inRange') {
+        validateGraphExpr(node.value, context, `${path}.value`);
+        validateGraphExpr(node.min, context, `${path}.min`);
+        validateGraphExpr(node.max, context, `${path}.max`);
+        return;
+    }
+    validateGraphExpr(node.left, context, `${path}.left`);
+    validateGraphExpr(node.right, context, `${path}.right`);
+}
+const DEVICE_GRAPH_MAX_BRANCH_DEPTH = 8;
+/**
+ * Validate one behavior-graph step list, recursing into every nested list.
+ *
+ * The client's `stepSchema` (`validate.ts:133-222`) is a closed union and
+ * this walks all of them; validating only the four character steps let ten
+ * kinds — including `moveNode`, `setVfx`, `emitSignal` and `delay` — ship
+ * entirely unchecked, so a missing `durationMs` or a `seconds: 4000` delay
+ * passed `helix device validate` and was rejected when the package loaded.
+ */
+function validateGraphSteps(steps, context, path, depth) {
+    if (!Array.isArray(steps)) {
+        context.errors.push(`${path}: graph steps must be an array`);
+        return;
+    }
+    if (depth > DEVICE_GRAPH_MAX_BRANCH_DEPTH) {
+        context.errors.push(`${path}: graph nesting exceeds ${DEVICE_GRAPH_MAX_BRANCH_DEPTH} levels`);
+        return;
+    }
+    steps.forEach((raw, index) => {
+        const stepPath = `${path}.${index}`;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            context.errors.push(`${stepPath}: graph step must be an object`);
+            return;
+        }
+        const step = object(raw);
+        const kind = String(step.step ?? '');
+        if (!GRAPH_STEP_KINDS.has(kind)) {
+            context.errors.push(`${stepPath}: unsupported graph step "${kind}" (one of ${exports.DEVICE_GRAPH_STEP_KINDS.join('|')})`);
+            return;
+        }
+        const requireName = (field) => {
+            if (!isNonEmptyName(step[field])) {
+                context.errors.push(`${stepPath}: ${kind} requires a non-empty ${field}`);
+                return false;
+            }
+            return true;
+        };
+        switch (kind) {
+            case 'setState':
+            case 'toggleState': {
+                requireName('key');
+                for (const field of ['value', 'delta']) {
+                    if (step[field] !== undefined)
+                        validateGraphExpr(step[field], context, `${stepPath}.${field}`);
+                }
+                return;
+            }
+            case 'moveNode': {
+                requireName('node');
+                graphNode(context, step.node, stepPath);
+                if (!['x', 'y', 'z'].includes(String(step.property)))
+                    context.errors.push(`${stepPath}: moveNode property must be x, y or z`);
+                if (!isFiniteNumber(step.durationMs)) {
+                    context.errors.push(`${stepPath}: moveNode requires a finite durationMs`);
+                }
+                for (const field of ['to', 'by']) {
+                    if (step[field] !== undefined)
+                        validateGraphExpr(step[field], context, `${stepPath}.${field}`);
+                }
+                checkEasing(step.easing, stepPath, context.errors);
+                context.usage.nodeMotion = true;
+                return;
+            }
+            case 'rotateNode': {
+                requireName('node');
+                graphNode(context, step.node, stepPath);
+                if (!['x', 'y', 'z'].includes(String(step.axis)))
+                    context.errors.push(`${stepPath}: rotateNode axis must be x, y or z`);
+                if (!['toAngle', 'stop'].includes(String(step.mode)))
+                    context.errors.push(`${stepPath}: rotateNode mode must be toAngle or stop`);
+                if (step.targetDeg !== undefined)
+                    validateGraphExpr(step.targetDeg, context, `${stepPath}.targetDeg`);
+                if (step.durationMs !== undefined && !isFiniteNumber(step.durationMs))
+                    context.errors.push(`${stepPath}: rotateNode durationMs must be a finite number`);
+                checkEasing(step.easing, stepPath, context.errors);
+                context.usage.nodeMotion = true;
+                return;
+            }
+            case 'playAudio':
+            case 'stopAudio': {
+                const hasAsset = isNonEmptyName(step.asset);
+                const hasUrlStateKey = isNonEmptyName(step.urlStateKey);
+                if (step.asset !== undefined && !hasAsset)
+                    context.errors.push(`${stepPath}: playAudio asset must be non-empty`);
+                if (step.urlStateKey !== undefined && !hasUrlStateKey)
+                    context.errors.push(`${stepPath}: audio urlStateKey must be non-empty`);
+                if (hasAsset === hasUrlStateKey) {
+                    context.errors.push('graph: audio step must declare exactly one of asset or urlStateKey');
+                }
+                if (hasAsset && !context.audio.has(String(step.asset)))
+                    context.errors.push(`graph: unknown audio asset "${String(step.asset)}"`);
+                if (hasUrlStateKey) {
+                    const spec = object(context.state[String(step.urlStateKey)]);
+                    if (spec.type !== 'string') {
+                        context.errors.push(`graph: audio urlStateKey "${String(step.urlStateKey)}" must name string state`);
+                    }
+                    else if (spec.maxLen === undefined || Number(spec.maxLen) > 1024) {
+                        context.errors.push(`graph: audio urlStateKey "${String(step.urlStateKey)}" must be bounded to 1024 characters`);
+                    }
+                }
+                if (step.at !== undefined) {
+                    if (!isNonEmptyName(step.at))
+                        context.errors.push(`${stepPath}: audio at must be non-empty`);
+                    else if (!context.sockets.has(String(step.at)))
+                        context.errors.push(`graph: unknown audio socket "${String(step.at)}"`);
+                }
+                if (step.loop !== undefined && typeof step.loop !== 'boolean')
+                    context.errors.push(`${stepPath}: playAudio loop must be boolean`);
+                if (step.volume !== undefined &&
+                    (!isFiniteNumber(step.volume) || step.volume < 0 || step.volume > 1)) {
+                    context.errors.push(`${stepPath}: playAudio volume must be between 0 and 1`);
+                }
+                context.usage.audioPlayback = true;
+                return;
+            }
+            case 'setVfx': {
+                requireName('effect');
+                if (typeof step.on !== 'boolean') {
+                    context.errors.push(`${stepPath}: setVfx requires a boolean on`);
+                }
+                if (isNonEmptyName(step.effect) && !context.effects.has(String(step.effect)))
+                    context.errors.push(`graph: unknown VFX "${String(step.effect)}"`);
+                if (step.at !== undefined) {
+                    if (!isNonEmptyName(step.at))
+                        context.errors.push(`${stepPath}: setVfx at must be non-empty`);
+                    else if (!context.sockets.has(String(step.at)))
+                        context.errors.push(`graph: unknown VFX socket "${String(step.at)}"`);
+                }
+                if (step.durationSeconds !== undefined &&
+                    (!isFiniteNumber(step.durationSeconds) ||
+                        step.durationSeconds < 0 ||
+                        step.durationSeconds > 3600)) {
+                    context.errors.push(`${stepPath}: setVfx durationSeconds must be between 0 and 3600`);
+                }
+                context.usage.vfx = true;
+                return;
+            }
+            case 'attachCharacter': {
+                requireName('socket');
+                if (isNonEmptyName(step.socket) && !context.sockets.has(String(step.socket)))
+                    context.errors.push(`graph: unknown character socket "${String(step.socket)}"`);
+                context.usage.animation = true;
+                return;
+            }
+            case 'playCharacterAnimation': {
+                requireName('asset');
+                if (isNonEmptyName(step.asset) &&
+                    !context.animations.has(String(step.asset))) {
+                    context.errors.push(`graph: unknown animation asset "${String(step.asset)}"`);
+                }
+                if (step.loop !== undefined && typeof step.loop !== 'boolean')
+                    context.errors.push(`${stepPath}: playCharacterAnimation loop must be boolean`);
+                context.usage.animation = true;
+                return;
+            }
+            case 'releaseCharacter': {
+                if (step.exitSocket !== undefined) {
+                    if (!isNonEmptyName(step.exitSocket)) {
+                        context.errors.push(`graph releaseCharacter exitSocket must be a non-empty name`);
+                    }
+                    else if (!context.sockets.has(String(step.exitSocket))) {
+                        context.errors.push(`graph: unknown exit socket "${String(step.exitSocket)}"`);
+                    }
+                }
+                context.usage.animation = true;
+                return;
+            }
+            case 'enterCharacterSpot': {
+                context.usage.posture = true;
+                const component = String(step.component ?? '');
+                if (!context.characterSpots.has(component)) {
+                    context.errors.push(`graph enterCharacterSpot references unknown character spot "${component}"`);
+                }
+                return;
+            }
+            case 'reachCharacterHand': {
+                context.usage.hand = true;
+                const hand = String(step.hand ?? '');
+                if (!CHARACTER_HANDS.has(hand)) {
+                    context.errors.push(`${stepPath}: reachCharacterHand hand must be left or right`);
+                }
+                if (!step.target ||
+                    typeof step.target !== 'object' ||
+                    Array.isArray(step.target)) {
+                    context.errors.push(`${stepPath}: reachCharacterHand target must be an object with exactly one of node or socket`);
+                }
+                else {
+                    const target = object(step.target);
+                    const keys = Object.keys(target);
+                    const hasNode = Object.prototype.hasOwnProperty.call(target, 'node');
+                    const hasSocket = Object.prototype.hasOwnProperty.call(target, 'socket');
+                    if (hasNode === hasSocket ||
+                        keys.some((key) => key !== 'node' && key !== 'socket')) {
+                        context.errors.push(`${stepPath}: reachCharacterHand target must declare exactly one of node or socket`);
+                    }
+                    else if (hasNode) {
+                        if (!isNonEmptyName(target.node)) {
+                            context.errors.push(`${stepPath}: reachCharacterHand target.node must be a non-empty name`);
+                        }
+                        else {
+                            const semantic = String(target.node);
+                            if (!context.nodesKnown &&
+                                !Object.prototype.hasOwnProperty.call(context.bindings, semantic)) {
+                                context.errors.push(`${stepPath}.target.node must name an authored model.nodeBindings entry when GLB bytes are unavailable`);
+                            }
+                            else {
+                                graphNode(context, target.node, `${stepPath}.target.node`);
+                            }
+                        }
+                    }
+                    else if (!isNonEmptyName(target.socket)) {
+                        context.errors.push(`${stepPath}: reachCharacterHand target.socket must be a non-empty name`);
+                    }
+                    else if (!context.sockets.has(String(target.socket))) {
+                        context.errors.push(`${stepPath}: reachCharacterHand references unknown Device socket "${String(target.socket)}"`);
+                    }
+                }
+                if (!isFiniteNumber(step.engageDistanceM) ||
+                    step.engageDistanceM < 0.1 ||
+                    step.engageDistanceM > 2) {
+                    context.errors.push(`${stepPath}: reachCharacterHand engageDistanceM must be between 0.1 and 2`);
+                }
+                if (!isFiniteNumber(step.releaseDistanceM) ||
+                    step.releaseDistanceM > 3 ||
+                    (isFiniteNumber(step.engageDistanceM) &&
+                        step.releaseDistanceM < step.engageDistanceM)) {
+                    context.errors.push(`${stepPath}: reachCharacterHand releaseDistanceM must be at least engageDistanceM and no more than 3`);
+                }
+                if (step.maxAngleDeg !== undefined &&
+                    (!isFiniteNumber(step.maxAngleDeg) ||
+                        step.maxAngleDeg < 1 ||
+                        step.maxAngleDeg > 180)) {
+                    context.errors.push(`${stepPath}: reachCharacterHand maxAngleDeg must be between 1 and 180`);
+                }
+                if (step.elbow !== undefined &&
+                    !CHARACTER_HAND_ELBOWS.has(String(step.elbow))) {
+                    context.errors.push(`${stepPath}: reachCharacterHand elbow must be down, out or up`);
+                }
+                if (step.orientMatch !== undefined &&
+                    typeof step.orientMatch !== 'boolean') {
+                    context.errors.push(`${stepPath}: reachCharacterHand orientMatch must be boolean`);
+                }
+                return;
+            }
+            case 'releaseCharacterHand': {
+                context.usage.hand = true;
+                const hand = String(step.hand ?? '');
+                if (!CHARACTER_HANDS.has(hand)) {
+                    context.errors.push(`${stepPath}: releaseCharacterHand hand must be left or right`);
+                }
+                return;
+            }
+            case 'attachItem': {
+                // `attachItem` puts the Device's OWN model on the acting character's
+                // hand, so it is a hand power rather than an animation one. Its
+                // `socket` is a CHARACTER socket from the closed hand set — never one of
+                // the Device's own `sockets`, which are a different namespace. `preset`
+                // stays free-form: the engine's held-item registry resolves it, and an
+                // unknown name degrades to the socket's default frame.
+                context.usage.hand = true;
+                if (!isNonEmptyName(step.socket)) {
+                    context.errors.push('graph attachItem requires a non-empty socket');
+                }
+                else if (!HAND_SOCKETS.has(String(step.socket))) {
+                    context.errors.push(`graph attachItem socket "${String(step.socket)}" is unsupported; expected one of ${exports.DEVICE_HAND_SOCKET_LIST}`);
+                }
+                if (step.preset !== undefined && !isNonEmptyName(step.preset))
+                    context.errors.push('graph attachItem preset must be a non-empty name');
+                return;
+            }
+            case 'releaseItem': {
+                context.usage.hand = true;
+                if (step.socket !== undefined && !isNonEmptyName(step.socket))
+                    context.errors.push('graph releaseItem socket must be a non-empty name');
+                return;
+            }
+            case 'emitSignal': {
+                if (!isNonEmptyName(step.name) || String(step.name).length > 64) {
+                    context.errors.push(`${stepPath}: emitSignal name must be 1..64 characters`);
+                }
+                if (step.payload !== undefined) {
+                    if (!step.payload || typeof step.payload !== 'object' || Array.isArray(step.payload)) {
+                        context.errors.push(`${stepPath}: emitSignal payload must be an object`);
+                    }
+                    else {
+                        for (const [key, value] of Object.entries(object(step.payload))) {
+                            if (!key.trim() || !scalar(value)) {
+                                context.errors.push(`${stepPath}.payload.${key}: payload values must be scalar`);
+                            }
+                        }
+                    }
+                }
+                return;
+            }
+            case 'branch': {
+                if (step.when === undefined) {
+                    context.errors.push(`${stepPath}: branch requires when`);
+                }
+                else {
+                    validateGraphCondition(step.when, context, `${stepPath}.when`);
+                }
+                if (step.then === undefined) {
+                    context.errors.push(`${stepPath}: branch requires then`);
+                }
+                else {
+                    validateGraphSteps(step.then, context, `${stepPath}.then`, depth + 1);
+                }
+                if (step.else !== undefined)
+                    validateGraphSteps(step.else, context, `${stepPath}.else`, depth + 1);
+                return;
+            }
+            case 'sequence': {
+                if (step.do === undefined) {
+                    context.errors.push(`${stepPath}: sequence requires do`);
+                }
+                else {
+                    validateGraphSteps(step.do, context, `${stepPath}.do`, depth + 1);
+                }
+                return;
+            }
+            case 'delay': {
+                if (!isFiniteNumber(step.seconds) || step.seconds < 0 || step.seconds > 3600) {
+                    context.errors.push(`${stepPath}: delay seconds must be between 0 and 3600`);
+                }
+                if (step.then === undefined) {
+                    context.errors.push(`${stepPath}: delay requires then`);
+                }
+                else {
+                    validateGraphSteps(step.then, context, `${stepPath}.then`, depth + 1);
+                }
+                return;
+            }
+            case 'repeat': {
+                if (!Number.isInteger(step.times) || Number(step.times) < 0) {
+                    context.errors.push(`${stepPath}: repeat times must be a non-negative integer`);
+                }
+                else if (Number(step.times) > 64) {
+                    context.errors.push(`${stepPath}: repeat times must not exceed 64`);
+                }
+                if (step.do === undefined) {
+                    context.errors.push(`${stepPath}: repeat requires do`);
+                }
+                else {
+                    validateGraphSteps(step.do, context, `${stepPath}.do`, depth + 1);
+                }
+                return;
+            }
+            default:
+                return;
+        }
+    });
+}
+/**
+ * Follow every bounded graph branch to prove that a reach cannot outlive the
+ * trigger execution path that created it. A later, unrelated trigger is not a
+ * release guarantee: it may never fire. An orphan release is intentionally a
+ * no-op so cleanup steps remain idempotent.
+ */
+function handReachPathEnds(steps, starts = [new Set()], depth = 0) {
+    const context = {
+        nextRelationId: 1,
+        relations: new WeakMap(),
+    };
+    const endings = handUnitEnds(steps, starts.map(handSetToMask), depth, context);
+    return endings.map(handMaskToSet);
+}
+function handUnitEnds(steps, starts, depth, context) {
+    const paths = walkHandSteps(steps, starts.map((state) => ({ state, delays: [] })), depth, context);
+    return dedupeHandMasks(paths.flatMap((path) => finishHandDelays(path.state, path.delays)));
+}
+function walkHandSteps(steps, starts, depth, context) {
+    if (!Array.isArray(steps) || depth > DEVICE_GRAPH_MAX_BRANCH_DEPTH) {
+        return starts.map(cloneHandPath);
+    }
+    let paths = starts.map(cloneHandPath);
+    for (const raw of steps) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const step = object(raw);
+        const kind = String(step.step ?? '');
+        if (kind === 'reachCharacterHand') {
+            const bit = handBit(step.hand);
+            if (bit !== 0)
+                for (const path of paths)
+                    path.state |= bit;
+        }
+        else if (kind === 'releaseCharacterHand') {
+            const bit = handBit(step.hand);
+            if (bit !== 0)
+                for (const path of paths)
+                    path.state &= ~bit;
+        }
+        else if (kind === 'branch') {
+            const branched = [];
+            const condition = object(step.when);
+            const arms = condition.op === 'true'
+                ? [step.then]
+                : condition.op === 'false'
+                    ? [step.else ?? []]
+                    : [step.then, step.else ?? []];
+            for (const path of paths) {
+                for (const arm of arms) {
+                    branched.push(...walkHandSteps(arm, [path], depth + 1, context));
+                }
+            }
+            paths = dedupeHandPaths(branched);
+        }
+        else if (kind === 'sequence') {
+            paths = walkHandSteps(step.do, paths, depth + 1, context);
+        }
+        else if (kind === 'delay') {
+            const relation = handRelation(step.then, depth + 1, context);
+            for (const path of paths) {
+                // The runtime silently drops delay nine while eight are pending. The
+                // metric validator rejects that shape; mirroring the drop here keeps
+                // path analysis faithful even for an already-invalid graph.
+                if (path.delays.length < DEVICE_BUDGETS.maxConcurrentDelays) {
+                    path.delays.push(relation);
+                }
+            }
+        }
+        else if (kind === 'repeat' &&
+            Number.isInteger(step.times) &&
+            Number(step.times) > 0) {
+            for (let index = 0; index < Number(step.times); index += 1) {
+                paths = walkHandSteps(step.do, paths, depth + 1, context);
+            }
+        }
+    }
+    return dedupeHandPaths(paths);
+}
+function dedupeHandPaths(paths) {
+    const unique = new Map();
+    for (const path of paths) {
+        const key = `${path.state}:${path.delays.map((delay) => delay.id).join(',')}`;
+        if (!unique.has(key))
+            unique.set(key, cloneHandPath(path));
+    }
+    return [...unique.values()];
+}
+function handRelation(steps, depth, context) {
+    if (steps && typeof steps === 'object') {
+        const cached = context.relations.get(steps);
+        if (cached)
+            return cached;
+    }
+    const relation = {
+        id: context.nextRelationId++,
+        outputs: [new Set(), new Set(), new Set(), new Set()],
+    };
+    if (steps && typeof steps === 'object')
+        context.relations.set(steps, relation);
+    for (let state = 0; state < 4; state += 1) {
+        relation.outputs[state] = new Set(handUnitEnds(steps, [state], depth, context));
+    }
+    return relation;
+}
+function finishHandDelays(state, delays) {
+    if (delays.length === 0)
+        return [state];
+    const full = (1 << delays.length) - 1;
+    const seen = new Set();
+    const endings = new Set();
+    const visit = (mask, current) => {
+        const key = `${mask}:${current}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        if (mask === full) {
+            endings.add(current);
+            return;
+        }
+        delays.forEach((relation, index) => {
+            const bit = 1 << index;
+            if (mask & bit)
+                return;
+            for (const next of relation.outputs[current] ?? []) {
+                visit(mask | bit, next);
+            }
+        });
+    };
+    visit(0, state);
+    return [...endings];
+}
+function handBit(hand) {
+    return hand === 'left' ? 1 : hand === 'right' ? 2 : 0;
+}
+function handSetToMask(hands) {
+    let mask = 0;
+    for (const hand of hands)
+        mask |= handBit(hand);
+    return mask;
+}
+function handMaskToSet(mask) {
+    const hands = new Set();
+    if (mask & 1)
+        hands.add('left');
+    if (mask & 2)
+        hands.add('right');
+    return hands;
+}
+function dedupeHandMasks(states) {
+    return [...new Set(states)];
+}
+function cloneHandPath(path) {
+    return { state: path.state, delays: [...path.delays] };
+}
+function handGraphExecutionMetrics(steps, depth = 0) {
+    const current = { steps: 0 };
+    const delayed = [];
+    if (!Array.isArray(steps) || depth > DEVICE_GRAPH_MAX_BRANCH_DEPTH) {
+        return [current];
+    }
+    for (const raw of steps) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const step = object(raw);
+        const kind = String(step.step ?? '');
+        current.steps = Math.min(DEVICE_BUDGETS.maxStepsPerFire, current.steps + 1);
+        if (kind === 'delay') {
+            delayed.push(...handGraphExecutionMetrics(step.then, depth + 1));
+        }
+        else if (kind === 'sequence') {
+            const [body, ...children] = handGraphExecutionMetrics(step.do, depth + 1);
+            current.steps = cappedStepSum(current.steps, body.steps);
+            delayed.push(...children);
+        }
+        else if (kind === 'repeat' && Number.isInteger(step.times)) {
+            const times = Math.max(0, Number(step.times));
+            const [body, ...children] = handGraphExecutionMetrics(step.do, depth + 1);
+            current.steps = cappedStepSum(current.steps, times * (1 + body.steps));
+            delayed.push(...children);
+        }
+        else if (kind === 'branch') {
+            const condition = object(step.when);
+            const arms = condition.op === 'true'
+                ? [step.then]
+                : condition.op === 'false'
+                    ? [step.else ?? []]
+                    : [step.then, step.else ?? []];
+            const armMetrics = arms.map((arm) => handGraphExecutionMetrics(arm, depth + 1));
+            current.steps = cappedStepSum(current.steps, Math.max(0, ...armMetrics.map(([arm]) => arm.steps)));
+            for (const [, ...children] of armMetrics)
+                delayed.push(...children);
+        }
+    }
+    return [current, ...delayed];
+}
+/**
+ * Maximum delay-queue width reachable from one execution unit. A queued delay
+ * occupies one slot until it fires; its continuation can replace that slot
+ * with every delay it schedules while unrelated siblings remain pending.
+ * Taking the widest reachable replacement forest catches nested overflow
+ * without rejecting a long chain that still occupies only one slot at a time.
+ */
+function handGraphMaxPendingDelays(steps, depth = 0) {
+    if (!Array.isArray(steps) || depth > DEVICE_GRAPH_MAX_BRANCH_DEPTH)
+        return 0;
+    let width = 0;
+    for (const raw of steps) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const step = object(raw);
+        const kind = String(step.step ?? '');
+        if (kind === 'delay') {
+            width += Math.max(1, handGraphMaxPendingDelays(step.then, depth + 1));
+        }
+        else if (kind === 'sequence') {
+            width += handGraphMaxPendingDelays(step.do, depth + 1);
+        }
+        else if (kind === 'repeat' && Number.isInteger(step.times)) {
+            width += Math.max(0, Number(step.times)) *
+                handGraphMaxPendingDelays(step.do, depth + 1);
+        }
+        else if (kind === 'branch') {
+            const condition = object(step.when);
+            const arms = condition.op === 'true'
+                ? [step.then]
+                : condition.op === 'false'
+                    ? [step.else ?? []]
+                    : [step.then, step.else ?? []];
+            width += Math.max(0, ...arms.map((arm) => handGraphMaxPendingDelays(arm, depth + 1)));
+        }
+        if (width > DEVICE_BUDGETS.maxConcurrentDelays)
+            return width;
+    }
+    return width;
+}
+function cappedStepSum(left, right) {
+    return Math.min(DEVICE_BUDGETS.maxStepsPerFire, left + right);
+}
+function graphHasHandStep(steps) {
+    if (!Array.isArray(steps))
+        return false;
+    return steps.some((raw) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return false;
+        const step = object(raw);
+        if (step.step === 'reachCharacterHand' ||
+            step.step === 'releaseCharacterHand') {
+            return true;
+        }
+        if (step.step === 'branch') {
+            return graphHasHandStep(step.then) || graphHasHandStep(step.else);
+        }
+        if (step.step === 'delay')
+            return graphHasHandStep(step.then);
+        if (step.step === 'sequence' || step.step === 'repeat') {
+            return graphHasHandStep(step.do);
+        }
+        return false;
+    });
+}
+const DEVICE_VFX_TYPES = new Set(['particles', 'glow']);
+const DEVICE_VFX_SHAPES = new Set(['cone', 'sphere', 'disc']);
+/**
+ * The host's `vfxSpec` (`validate.ts:283-296`) in full. `effects` was entirely
+ * unread offline, so a `setVfx` step could name an effect and the effect itself
+ * could be shapeless and still validate.
+ */
+function validateDeviceVfxSpec(raw, sockets, path, errors) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        errors.push(`${path}: effect must be an object`);
+        return;
+    }
+    const spec = object(raw);
+    if (!DEVICE_VFX_TYPES.has(String(spec.type)))
+        errors.push(`${path}: unsupported effect type "${String(spec.type)}" (one of ${[...DEVICE_VFX_TYPES].join('|')})`);
+    if (!DEVICE_VFX_SHAPES.has(String(spec.shape)))
+        errors.push(`${path}: unsupported effect shape "${String(spec.shape)}" (one of ${[...DEVICE_VFX_SHAPES].join('|')})`);
+    if (spec.at !== undefined) {
+        if (!isNonEmptyName(spec.at))
+            errors.push(`${path}.at: must be a non-empty name`);
+        else if (!sockets.has(String(spec.at)))
+            errors.push(`${path}: unknown socket "${String(spec.at)}"`);
+    }
+    const bounded = [
+        ['radius', 0, 10],
+        ['rate', 0, 2_000],
+        ['spread', 0, 20],
+    ];
+    for (const [field, min, max] of bounded) {
+        const value = spec[field];
+        if (value === undefined)
+            continue;
+        if (!isFiniteNumber(value) || value < min || value > max)
+            errors.push(`${path}.${field}: must be between ${min} and ${max}`);
+    }
+    if (spec.lifetime !== undefined) {
+        if (!isFiniteNumber(spec.lifetime) ||
+            spec.lifetime <= 0 ||
+            spec.lifetime > 30) {
+            errors.push(`${path}.lifetime: must be > 0 and <= 30`);
+        }
+    }
+    if (spec.velocity !== undefined && !isVec3(spec.velocity))
+        errors.push(`${path}.velocity: must be [x, y, z]`);
+    if (spec.size !== undefined) {
+        if (!Array.isArray(spec.size) ||
+            spec.size.length !== 2 ||
+            spec.size.some((value) => !isFiniteNumber(value) || value < 0 || value > 10)) {
+            errors.push(`${path}.size: must be two numbers between 0 and 10`);
+        }
+    }
+    if (spec.color !== undefined && !/^#[0-9a-f]{6}$/i.test(String(spec.color)))
+        errors.push(`${path}.color: must be #RRGGBB`);
+    if (spec.opacity !== undefined) {
+        if (!Array.isArray(spec.opacity) ||
+            spec.opacity.length !== 2 ||
+            spec.opacity.some((value) => !isFiniteNumber(value) || value < 0 || value > 1)) {
+            errors.push(`${path}.opacity: must be two numbers between 0 and 1`);
+        }
+    }
+    if (spec.gravity !== undefined && typeof spec.gravity !== 'boolean')
+        errors.push(`${path}.gravity: must be boolean`);
+}
+function readDefinitionPath(input) {
+    const target = (0, node_path_1.resolve)(input);
+    if (target.endsWith('.json')) {
+        return { directory: (0, node_path_1.dirname)(target), path: target };
+    }
+    return { directory: target, path: (0, node_path_1.join)(target, exports.DEVICE_FILENAME) };
+}
+function glbJson(file) {
+    const bytes = (0, node_fs_1.readFileSync)(file);
+    if (bytes.length < 20 || bytes.readUInt32LE(0) !== 0x46546c67) {
+        throw new Error(`${(0, node_path_1.basename)(file)} is not a binary glTF (.glb)`);
+    }
+    if (bytes.readUInt32LE(4) !== 2) {
+        throw new Error(`${(0, node_path_1.basename)(file)} must use glTF 2`);
+    }
+    const declaredLength = bytes.readUInt32LE(8);
+    if (declaredLength !== bytes.length) {
+        throw new Error(`${(0, node_path_1.basename)(file)} length header is ${declaredLength}, actual ${bytes.length}`);
+    }
+    const jsonLength = bytes.readUInt32LE(12);
+    if (bytes.readUInt32LE(16) !== 0x4e4f534a || 20 + jsonLength > bytes.length) {
+        throw new Error(`${(0, node_path_1.basename)(file)} has no valid JSON chunk`);
+    }
+    return JSON.parse(bytes.subarray(20, 20 + jsonLength).toString('utf8'));
+}
+function readDeviceGlbNodeNames(file) {
+    const parsed = glbJson(file);
+    return [
+        ...new Set((Array.isArray(parsed.nodes) ? parsed.nodes : [])
+            .map((node) => String(object(node).name ?? '').trim())
+            .filter(Boolean)),
+    ].sort();
+}
+function stateDefault(spec) {
+    if (scalar(spec.default))
+        return spec.default;
+    const type = String(spec.type ?? '');
+    if (type === 'boolean')
+        return false;
+    if (type === 'enum')
+        return String((Array.isArray(spec.values) ? spec.values : [])[0] ?? '');
+    if (type === 'string')
+        return '';
+    return typeof spec.min === 'number' ? spec.min : 0;
+}
+function coerce(spec, value) {
+    const type = String(spec.type ?? '');
+    if (type === 'boolean')
+        return value === true;
+    if (type === 'string') {
+        const text = String(value ?? '');
+        return typeof spec.maxLen === 'number' ? text.slice(0, spec.maxLen) : text;
+    }
+    if (type === 'enum') {
+        const next = String(value ?? '');
+        const values = Array.isArray(spec.values) ? spec.values.map(String) : [];
+        return values.includes(next) ? next : String(values[0] ?? '');
+    }
+    let number = Number(value);
+    if (!Number.isFinite(number))
+        number = Number(stateDefault(spec));
+    if (type === 'integer')
+        number = Math.round(number);
+    if (typeof spec.min === 'number')
+        number = Math.max(spec.min, number);
+    if (typeof spec.max === 'number')
+        number = Math.min(spec.max, number);
+    return number;
+}
+function initialState(definition) {
+    return Object.fromEntries(Object.entries(object(definition.state)).map(([key, raw]) => [
+        key,
+        stateDefault(object(raw)),
+    ]));
+}
+function expr(value, state) {
+    const node = object(value);
+    if (node.kind === 'lit' && scalar(node.value))
+        return node.value;
+    if (node.kind === 'state')
+        return state[String(node.key)] ?? 0;
+    const args = Array.isArray(node.args)
+        ? node.args.map((part) => Number(expr(part, state)))
+        : [];
+    if (node.kind === 'add')
+        return args.reduce((a, b) => a + b, 0);
+    if (node.kind === 'sub')
+        return args.slice(1).reduce((a, b) => a - b, args[0] ?? 0);
+    if (node.kind === 'mul')
+        return args.reduce((a, b) => a * b, 1);
+    if (node.kind === 'min')
+        return Math.min(...args);
+    if (node.kind === 'max')
+        return Math.max(...args);
+    return 0;
+}
+function condition(value, state) {
+    const node = object(value);
+    if (node.op === 'true')
+        return true;
+    if (node.op === 'false')
+        return false;
+    if (node.op === 'not')
+        return !condition(node.of, state);
+    const list = Array.isArray(node.of) ? node.of : [];
+    if (node.op === 'and')
+        return list.every((part) => condition(part, state));
+    if (node.op === 'or')
+        return list.some((part) => condition(part, state));
+    const left = expr(node.left, state);
+    const right = expr(node.right, state);
+    if (node.op === 'eq')
+        return left === right;
+    if (node.op === 'ne')
+        return left !== right;
+    if (node.op === 'gt')
+        return left > right;
+    if (node.op === 'lt')
+        return left < right;
+    if (node.op === 'gte')
+        return left >= right;
+    if (node.op === 'lte')
+        return left <= right;
+    if (node.op === 'inRange') {
+        const number = Number(expr(node.value, state));
+        return (number >= Number(expr(node.min, state)) &&
+            number <= Number(expr(node.max, state)));
+    }
+    return false;
+}
+function applySteps(steps, definition, state, budget) {
+    if (!Array.isArray(steps))
+        return;
+    for (const raw of steps) {
+        if (--budget.remaining < 0)
+            throw new Error('behavior graph exceeded 2048 simulated steps');
+        const step = object(raw);
+        const kind = String(step.step ?? '');
+        if (kind === 'setState') {
+            const key = String(step.key ?? '');
+            const spec = object(object(definition.state)[key]);
+            if (!Object.keys(spec).length)
+                continue;
+            const value = step.value !== undefined
+                ? expr(step.value, state)
+                : Number(state[key] ?? 0) + Number(expr(step.delta, state));
+            state[key] = coerce(spec, value);
+        }
+        else if (kind === 'toggleState') {
+            const key = String(step.key ?? '');
+            state[key] = !Boolean(state[key]);
+        }
+        else if (kind === 'branch') {
+            applySteps(condition(step.when, state) ? step.then : step.else, definition, state, budget);
+        }
+        else if (kind === 'sequence') {
+            applySteps(step.do, definition, state, budget);
+        }
+        else if (kind === 'repeat') {
+            const times = Math.max(0, Math.min(64, Number(step.times) || 0));
+            for (let index = 0; index < times; index += 1) {
+                applySteps(step.do, definition, state, budget);
+            }
+        }
+        else if (kind === 'delay') {
+            applySteps(step.then, definition, state, budget);
+        }
+    }
+}
+function invoke(definition, state, interaction, value) {
+    const control = object(interaction.control);
+    if (control.stateKey && value !== undefined) {
+        const key = String(control.stateKey);
+        state[key] = coerce(object(object(definition.state)[key]), value);
+    }
+    const triggers = Array.isArray(object(definition.graph).triggers)
+        ? object(definition.graph).triggers
+        : [];
+    for (const raw of triggers) {
+        const trigger = object(raw);
+        if (trigger.on === 'interact' && trigger.interaction === interaction.id) {
+            applySteps(trigger.do, definition, state, { remaining: 2048 });
+        }
+    }
+}
+function exerciseValue(interaction, state) {
+    const control = object(interaction.control);
+    if (control.kind === 'number')
+        return Number(control.max ?? control.min ?? 1);
+    if (control.kind === 'choice') {
+        const options = Array.isArray(control.options)
+            ? control.options.map(object)
+            : [];
+        const current = state[String(control.stateKey)];
+        return String(options.find((option) => !option.disabled && option.value !== current)
+            ?.value ??
+            options.find((option) => !option.disabled)?.value ??
+            '');
+    }
+    if (control.kind === 'text') {
+        return 'https://www.youtube.com/watch?v=M7lc1UVf-VE';
+    }
+    return undefined;
+}
+/** Viewer-local declarations never become room actions or state writes. */
+function deviceWebPanelInteractionError(definition, interaction) {
+    const plainRecord = (value) => isRecord(value) ? value : null;
+    if (interaction.presentation === undefined)
+        return null;
+    const presentation = plainRecord(interaction.presentation);
+    if (!presentation ||
+        presentation.kind !== 'webPanel' ||
+        Object.keys(presentation).some((key) => key !== 'kind' && key !== 'app') ||
+        typeof presentation.app !== 'string' ||
+        !presentation.app.trim() ||
+        presentation.app.length > 64)
+        return 'presentation must be {kind:webPanel,app:<declared app id>}';
+    if (interaction.action !== undefined || interaction.control !== undefined)
+        return 'webPanel presentation cannot include action or control';
+    if (interaction.surface === 'internal')
+        return 'webPanel presentation cannot use an internal interaction';
+    const capabilities = definition.capabilities;
+    if (!Array.isArray(capabilities) || !capabilities.includes('app.web.panel'))
+        return 'webPanel presentation requires capability app.web.panel';
+    const apps = plainRecord(definition.apps);
+    const app = apps && Object.prototype.hasOwnProperty.call(apps, presentation.app)
+        ? plainRecord(apps[presentation.app])
+        : null;
+    if (!app || (app.type !== 'remoteWeb' && app.type !== 'localWeb'))
+        return 'webPanel presentation must target a declared remoteWeb or localWeb app';
+    if (!capabilities.includes(app.type === 'remoteWeb' ? 'app.web.remote' : 'app.web.local'))
+        return `webPanel app requires capability ${app.type === 'remoteWeb' ? 'app.web.remote' : 'app.web.local'}`;
+    if (typeof app.entry !== 'string' ||
+        !app.entry.trim() ||
+        app.entry.length > 2048)
+        return 'webPanel app entry must be a non-empty string of at most 2048 characters';
+    if (app.type === 'localWeb') {
+        if (app.allowedOrigins !== undefined)
+            return 'webPanel localWeb app cannot declare allowedOrigins';
+        try {
+            const url = new URL(app.entry, 'https://helix.invalid');
+            if (!app.entry.startsWith('/device-apps/') ||
+                app.entry.includes('\\') ||
+                app.entry.split(/[/?#]/).includes('..') ||
+                url.origin !== 'https://helix.invalid' ||
+                !/^\/device-apps\/[A-Za-z0-9][A-Za-z0-9/_.-]*$/.test(url.pathname) ||
+                decodeURIComponent(url.pathname) !== url.pathname)
+                return 'webPanel localWeb entry must use a safe /device-apps/ path';
+        }
+        catch {
+            return 'webPanel localWeb entry must use a safe /device-apps/ path';
+        }
+    }
+    else {
+        try {
+            const url = new URL(app.entry);
+            const origins = app.allowedOrigins;
+            if (url.protocol !== 'https:' ||
+                url.username ||
+                url.password ||
+                !Array.isArray(origins) ||
+                origins.length < 1 ||
+                origins.length > 16 ||
+                !origins.every((origin) => {
+                    if (typeof origin !== 'string')
+                        return false;
+                    const allowed = new URL(origin);
+                    return allowed.protocol === 'https:' && allowed.origin === origin;
+                }) ||
+                !origins.includes(url.origin))
+                return 'webPanel remoteWeb entry must use HTTPS and a declared allowedOrigins origin';
+        }
+        catch {
+            return 'webPanel remoteWeb entry must use HTTPS and a declared allowedOrigins origin';
+        }
+    }
+    return null;
+}
+function validateDeviceProject(input) {
+    const target = readDefinitionPath(input);
+    const errors = [];
+    const warnings = [];
+    let definition = {};
+    if (!(0, node_fs_1.existsSync)(target.path)) {
+        return {
+            ok: false,
+            directory: target.directory,
+            definitionPath: target.path,
+            modelPath: null,
+            nodeNames: [],
+            errors: [`Missing ${target.path}`],
+            warnings,
+        };
+    }
+    try {
+        definition = object(JSON.parse((0, node_fs_1.readFileSync)(target.path, 'utf8')));
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+    }
+    const actionAstError = (0, deviceActionValidation_1.deviceActionAstBudgetError)(definition);
+    if (actionAstError)
+        errors.push(`interactions: ${actionAstError}`);
+    if (definition.format !== 'helix.device' || definition.formatVersion !== 1) {
+        errors.push('format must be helix.device/1');
+    }
+    if (!/^[a-z0-9][a-z0-9-]{1,48}[a-z0-9]$/.test(String(definition.id ?? ''))) {
+        errors.push('id must be a 3-50 character lowercase slug');
+    }
+    if (!/^\d+\.\d+\.\d+$/.test(String(definition.version ?? ''))) {
+        errors.push('version must be semver (for example 1.0.0)');
+    }
+    // The host's schema marks these four non-optional, so a package that omits
+    // one is rejected at load. Reading them through `object()` alone turned a
+    // missing block into an empty one and hid the rejection.
+    for (const key of ['state', 'interactions', 'components', 'graph']) {
+        if (definition[key] === undefined || definition[key] === null)
+            errors.push(`${key} is required`);
+    }
+    const title = String(definition.title ?? '');
+    if (!title.trim())
+        errors.push('title is required');
+    else if (title.length > 80)
+        errors.push('title must be 80 characters or fewer');
+    if (definition.description !== undefined) {
+        if (typeof definition.description !== 'string')
+            errors.push('description must be a string');
+        else if (definition.description.length > 400)
+            errors.push('description must be 400 characters or fewer');
+    }
+    if (definition.stateVersion !== undefined &&
+        (!Number.isInteger(definition.stateVersion) ||
+            Number(definition.stateVersion) < 1)) {
+        errors.push('stateVersion must be a positive integer');
+    }
+    if (definition.script !== null)
+        errors.push('script must be null; Devices are declarative');
+    const authorityModes = [
+        'presentationOnly',
+        'clientPredicted',
+        'clientAuthoritative',
+        'serverValidated',
+        'serverAuthoritative',
+    ];
+    if (!authorityModes.includes(String(definition.authority))) {
+        errors.push(`authority "${String(definition.authority)}" is unsupported`);
+    }
+    if (!['tiny', 'room', 'nearby', 'building', 'world'].includes(String(definition.activationPreset))) {
+        errors.push(`activationPreset "${String(definition.activationPreset)}" is unsupported`);
+    }
+    const model = object(definition.model);
+    let modelPath = null;
+    let nodeNames = [];
+    if (model.kind === 'procedural') {
+        const parts = object(model.parts);
+        if (Object.keys(parts).length === 0) {
+            errors.push('model.parts must define at least one procedural part');
+        }
+        if (Object.keys(parts).length > 64) {
+            errors.push('model.parts exceeds the 64-part Device budget');
+        }
+        nodeNames = Object.keys(parts);
+        for (const [name, rawPart] of Object.entries(parts)) {
+            const part = object(rawPart);
+            const shape = object(part.shape);
+            const partPath = `model.parts.${name}`;
+            if (!name.trim())
+                errors.push('procedural part names must not be empty');
+            const kind = String(shape.kind);
+            if (!['box', 'cylinder', 'sphere'].includes(kind)) {
+                errors.push(`${partPath}.shape.kind is unsupported`);
+            }
+            else if (kind === 'box') {
+                if (!isNumberTriple(shape.size)) {
+                    errors.push(`${partPath}.shape.size must be three numbers`);
+                }
+            }
+            else if (kind === 'cylinder') {
+                for (const field of ['radiusTop', 'radiusBottom', 'height']) {
+                    if (typeof shape[field] !== 'number' || !(Number(shape[field]) > 0)) {
+                        errors.push(`${partPath}.shape.${field} must be a positive number`);
+                    }
+                }
+                if (shape.segments !== undefined &&
+                    (!Number.isInteger(shape.segments) ||
+                        Number(shape.segments) < 3 ||
+                        Number(shape.segments) > 64)) {
+                    errors.push(`${partPath}.shape.segments must be an integer 3..64`);
+                }
+            }
+            else if (typeof shape.radius !== 'number' || !(Number(shape.radius) > 0)) {
+                errors.push(`${partPath}.shape.radius must be a positive number`);
+            }
+            for (const field of ['position', 'rotationDeg']) {
+                if (part[field] !== undefined && !isNumberTriple(part[field])) {
+                    errors.push(`${partPath}.${field} must be three numbers`);
+                }
+            }
+            if (part.pivot !== undefined && part.pivot !== 'bottom') {
+                errors.push(`${partPath}.pivot must be bottom`);
+            }
+            if (part.color !== undefined && !Number.isInteger(part.color)) {
+                errors.push(`${partPath}.color must be an integer`);
+            }
+            for (const field of ['metalness', 'roughness', 'emissive']) {
+                const value = part[field];
+                if (value !== undefined &&
+                    (typeof value !== 'number' || value < 0 || value > 1)) {
+                    errors.push(`${partPath}.${field} must be between 0 and 1`);
+                }
+            }
+        }
+    }
+    else if (model.kind !== 'glb' || !String(model.url ?? '').trim()) {
+        errors.push('model.kind must be procedural or glb with a url');
+    }
+    else if (/^https?:\/\//.test(String(model.url))) {
+        warnings.push('remote model URL cannot be byte-verified locally; prefer a project GLB');
+    }
+    else {
+        modelPath = (0, node_path_1.resolve)(target.directory, String(model.url));
+        if (!(0, node_fs_1.existsSync)(modelPath))
+            errors.push(`model GLB does not exist: ${modelPath}`);
+        else {
+            try {
+                nodeNames = readDeviceGlbNodeNames(modelPath);
+            }
+            catch (error) {
+                errors.push(error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    const nodes = new Set(nodeNames);
+    for (const [semantic, authored] of Object.entries(object(model.nodeBindings))) {
+        if (nodeNames.length > 0 && !nodes.has(String(authored))) {
+            errors.push(`model.nodeBindings.${semantic} references missing GLB node "${String(authored)}"`);
+        }
+    }
+    const state = object(definition.state);
+    const stateKeys = Object.keys(state);
+    if (stateKeys.length > DEVICE_BUDGETS.maxStateVars) {
+        errors.push(`state: ${stateKeys.length} vars exceeds budget ${DEVICE_BUDGETS.maxStateVars}`);
+    }
+    const persistentCount = stateKeys.filter((key) => object(state[key]).persist === true).length;
+    if (persistentCount > DEVICE_BUDGETS.maxPersistentVars) {
+        errors.push(`state: ${persistentCount} persistent vars exceeds budget ${DEVICE_BUDGETS.maxPersistentVars}`);
+    }
+    for (const [key, raw] of Object.entries(state)) {
+        const spec = object(raw);
+        if (!['boolean', 'integer', 'float', 'string', 'enum'].includes(String(spec.type))) {
+            errors.push(`state.${key}.type "${String(spec.type)}" is unsupported`);
+        }
+        if (typeof spec.min === 'number' &&
+            typeof spec.max === 'number' &&
+            spec.max < spec.min) {
+            errors.push(`state.${key} has min > max`);
+        }
+        if (spec.type === 'enum' &&
+            (!Array.isArray(spec.values) || spec.values.length === 0)) {
+            errors.push(`state.${key} enum requires values`);
+        }
+        if (Array.isArray(spec.values) &&
+            spec.values.length > DEVICE_BUDGETS.maxEnumValues) {
+            errors.push(`state.${key}: ${spec.values.length} enum values exceeds budget ${DEVICE_BUDGETS.maxEnumValues}`);
+        }
+        if (spec.maxLen !== undefined) {
+            // The room IR accepts 1..1024 and clips writes to it. Anything wider
+            // validates here and is then refused when a Home compiles its room
+            // config — which fails every Device in that Home, not just this one.
+            if (!Number.isInteger(spec.maxLen) ||
+                Number(spec.maxLen) < 1 ||
+                Number(spec.maxLen) > 1024) {
+                errors.push(`state.${key} maxLen must be 1..1024`);
+            }
+            if (!['string', 'enum'].includes(String(spec.type))) {
+                errors.push(`state.${key} maxLen applies to string state only`);
+            }
+            if (typeof spec.default === 'string' &&
+                spec.default.length > Number(spec.maxLen)) {
+                errors.push(`state.${key} default is longer than maxLen`);
+            }
+        }
+    }
+    const interactions = Array.isArray(definition.interactions)
+        ? definition.interactions.map(object)
+        : [];
+    if (interactions.length > DEVICE_BUDGETS.maxInteractions)
+        errors.push(`interactions: ${interactions.length} exceeds budget ${DEVICE_BUDGETS.maxInteractions}`);
+    const interactionIds = new Set();
+    for (const interaction of interactions) {
+        const presentationError = deviceWebPanelInteractionError(definition, interaction);
+        if (presentationError)
+            errors.push(`interaction ${String(interaction.id)}: ${presentationError}`);
+        const id = typeof interaction.id === 'string' ? interaction.id : '';
+        if (!id)
+            errors.push('interaction id must be a non-empty string');
+        else if (id.length > 48)
+            errors.push(`interaction id "${id}" must be 48 characters or fewer`);
+        else if (interactionIds.has(id))
+            errors.push(`interactions: duplicate id "${id}"`);
+        interactionIds.add(id);
+        // The host's schema makes `label` required and bounds it to 40 characters.
+        // Every interaction the CLI's own emitter templates write already carries
+        // one, which is why only hand-authored packages ever met this rejection.
+        if (typeof interaction.label !== 'string' || !interaction.label.length)
+            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.maxDistanceM !== undefined) {
+            if (!isFiniteNumber(interaction.maxDistanceM) ||
+                interaction.maxDistanceM <= 0 ||
+                interaction.maxDistanceM > 20) {
+                errors.push(`interaction ${id} maxDistanceM must be > 0 and <= 20`);
+            }
+        }
+        if (interaction.surface !== undefined &&
+            !['menu', 'internal'].includes(String(interaction.surface))) {
+            errors.push(`interaction ${id} has unsupported surface "${String(interaction.surface)}"`);
+        }
+        // The host's schema makes `verb` REQUIRED, so an absent verb is rejected
+        // there exactly as an unknown one is; matching that here is the whole point.
+        if (interaction.verb === undefined)
+            errors.push(`interaction ${id} requires a verb (one of ${exports.DEVICE_INTERACTION_VERB_LIST})`);
+        else if (typeof interaction.verb !== 'string' ||
+            !INTERACTION_VERBS.has(interaction.verb))
+            errors.push(`interaction ${id} verb "${String(interaction.verb)}" is unsupported; expected one of ${exports.DEVICE_INTERACTION_VERB_LIST}`);
+        // The host's `control` union is discriminated on `kind` (`validate.ts:385-420`).
+        // Guarding on `control.kind` skipped the whole block when the key was absent,
+        // so a control with no `kind` — or none of the three kinds — passed offline
+        // and was rejected at load with `interactions.N.control: Invalid input`.
+        const control = object(interaction.control);
+        if (interaction.control !== undefined && !isRecord(interaction.control)) {
+            errors.push(`interaction ${id} control must be an object`);
+        }
+        else if (interaction.control !== undefined) {
+            const key = String(control.stateKey ?? '');
+            const spec = object(state[key]);
+            if (!Object.keys(spec).length)
+                errors.push(`interaction ${id} references unknown state "${key}"`);
+            if (control.kind === 'number') {
+                if (!['float', 'integer'].includes(String(spec.type)))
+                    errors.push(`interaction ${id} number control must target numeric state`);
+                const min = Number(control.min ?? spec.min);
+                const max = Number(control.max ?? spec.max);
+                if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min)
+                    errors.push(`interaction ${id} requires finite max > min`);
+                if (control.step !== undefined &&
+                    (!isFiniteNumber(control.step) || control.step <= 0)) {
+                    errors.push(`interaction ${id} number step must be > 0`);
+                }
+                if (control.unit !== undefined && String(control.unit).length > 12)
+                    errors.push(`interaction ${id} unit must be 12 characters or fewer`);
+            }
+            else if (control.kind === 'choice') {
+                if (!['enum', 'string'].includes(String(spec.type)))
+                    errors.push(`interaction ${id} choice control must target enum or string state`);
+                const options = Array.isArray(control.options)
+                    ? control.options.map(object)
+                    : [];
+                if (!options.length || options.length > 64)
+                    errors.push(`interaction ${id} choice requires options (1..64)`);
+                const optionValues = new Set();
+                for (const option of options) {
+                    const value = String(option.value ?? '');
+                    if (!value || value.length > 80)
+                        errors.push(`interaction ${id} choice option value must be 1..80 characters`);
+                    else if (optionValues.has(value))
+                        errors.push(`interaction ${id} duplicate option "${value}"`);
+                    optionValues.add(value);
+                    const optionLabel = String(option.label ?? '');
+                    if (!optionLabel || optionLabel.length > 80)
+                        errors.push(`interaction ${id} choice option "${value}" requires a label of 1..80 characters`);
+                    if (option.reason !== undefined && String(option.reason).length > 160)
+                        errors.push(`interaction ${id} choice option "${value}" reason must be 160 characters or fewer`);
+                    if (option.disabled && !String(option.reason ?? '').trim())
+                        errors.push(`interaction ${id} disabled choice "${String(option.value)}" needs a reason`);
+                }
+            }
+            else if (control.kind === 'text') {
+                if (spec.type !== 'string')
+                    errors.push(`interaction ${id} text control must target string state`);
+                const maxLength = Number(control.maxLength ?? spec.maxLen ?? 512);
+                if (!Number.isInteger(maxLength) || maxLength < 1 || maxLength > 4096)
+                    errors.push(`interaction ${id} text maxLength must be 1..4096`);
+                if (typeof spec.maxLen === 'number' && maxLength > Number(spec.maxLen))
+                    errors.push(`interaction ${id} text maxLength cannot exceed state.${key} maxLen ${String(spec.maxLen)}`);
+                if (control.placeholder !== undefined &&
+                    String(control.placeholder).length > 160) {
+                    errors.push(`interaction ${id} text placeholder must be 160 characters or fewer`);
+                }
+                if (control.inputMode !== undefined &&
+                    !TEXT_INPUT_MODES.has(String(control.inputMode))) {
+                    errors.push(`interaction ${id} has unsupported text inputMode "${String(control.inputMode)}"`);
+                }
+            }
+            else if (control.kind === undefined) {
+                errors.push(`interaction ${id} control requires a kind (number|choice|text)`);
+            }
+            else {
+                errors.push(`interaction ${id} uses unsupported control kind "${String(control.kind)}"`);
+            }
+        }
+        if (!actionAstError)
+            (0, deviceActionValidation_1.validateDeviceInteractionAction)(interaction, state, errors);
+        (0, deviceActionValidation_1.validateDeviceInteractionDisabledWhen)(interaction, state, errors);
+    }
+    const interactionsById = new Map();
+    for (const interaction of interactions) {
+        if (typeof interaction.id === 'string' && interaction.id.length > 0) {
+            interactionsById.set(interaction.id, interaction);
+        }
+    }
+    const components = Array.isArray(definition.components)
+        ? definition.components.map(object)
+        : [];
+    if (components.length > 32)
+        errors.push('components exceed the 32-component Device budget');
+    const bindings = object(model.nodeBindings);
+    const apps = object(definition.apps);
+    const sockets = new Set(Object.keys(object(definition.sockets)));
+    const effects = new Set(Object.keys(object(definition.effects)));
+    const assets = object(definition.assets);
+    const audio = new Set(Object.keys(object(assets.audio)));
+    const animations = new Set(Object.keys(object(assets.animations)));
+    // `assets`, `sockets` and `effects` were entirely unread, so a character step
+    // could name an animation that does not exist and still validate offline.
+    for (const [kind, raw] of [
+        ['audio', assets.audio],
+        ['animations', assets.animations],
+    ]) {
+        if (raw === undefined)
+            continue;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            errors.push(`assets.${kind} must map a name to a source`);
+            continue;
+        }
+        for (const [name, source] of Object.entries(raw)) {
+            if (!name.trim() || typeof source !== 'string' || !source.trim())
+                errors.push(`assets.${kind}.${name} must name a non-empty source`);
+        }
+    }
+    for (const [name, raw] of Object.entries(object(definition.sockets))) {
+        const socket = object(raw);
+        if (!isVec3(socket.position))
+            errors.push(`socket ${name} requires a position [x, y, z]`);
+        if (socket.rotationDeg !== undefined && !isVec3(socket.rotationDeg))
+            errors.push(`socket ${name} rotationDeg must be [x, y, z]`);
+    }
+    for (const [name, raw] of Object.entries(object(definition.effects))) {
+        validateDeviceVfxSpec(raw, sockets, `effects.${name}`, errors);
+    }
+    const collision = Array.isArray(definition.collision)
+        ? definition.collision.map(object)
+        : [];
+    if (collision.length > DEVICE_BUDGETS.maxCollisionNodes)
+        errors.push(`collision: ${collision.length} nodes exceeds budget ${DEVICE_BUDGETS.maxCollisionNodes}`);
+    const collisionIds = new Set();
+    for (const solid of collision) {
+        const solidId = String(solid.id ?? '');
+        if (!solidId)
+            errors.push('collision id must be a non-empty string');
+        else if (collisionIds.has(solidId))
+            errors.push(`collision: duplicate id "${solidId}"`);
+        collisionIds.add(solidId);
+        const node = String(solid.node ?? '');
+        if (!node)
+            errors.push(`collision ${solidId} requires a non-empty node`);
+        else if (model.kind === 'procedural' && !nodes.has(node))
+            errors.push(`collision.${solidId}: unknown node "${node}"`);
+    }
+    for (const [appId, raw] of Object.entries(apps)) {
+        const app = object(raw);
+        if (!['localWeb', 'remoteWeb', 'youtube', 'canvas', 'remoteImage', 'ownerImage'].includes(String(app.type)))
+            errors.push(`app ${appId} has unsupported type "${String(app.type)}"`);
+        if (app.type === 'canvas') {
+            if (!DEVICE_CANVAS_APPS.has(String(app.entry)))
+                errors.push(`app ${appId} names unknown canvas renderer "${String(app.entry)}" (known: ${[...DEVICE_CANVAS_APPS].join(', ')})`);
+            if (Array.isArray(app.allowedOrigins) && app.allowedOrigins.length)
+                errors.push(`app ${appId} is a canvas app and loads no web origin`);
+            if (Array.isArray(app.permissions) && app.permissions.length)
+                errors.push(`app ${appId} is a canvas app and needs no web permissions`);
+        }
+        if (app.type === 'remoteImage') {
+            const imagePermissions = Array.isArray(app.permissions)
+                ? app.permissions.map(String)
+                : [];
+            if (!imagePermissions.includes('network.fetch'))
+                errors.push(`app ${appId} is a remote image app and must declare network.fetch`);
+            if (imagePermissions.some((permission) => permission !== 'network.fetch'))
+                errors.push(`app ${appId} remote image apps only accept permission network.fetch`);
+        }
+        if (app.type === 'ownerImage') {
+            // The owned copy's own image, moderated at upload and delivered by the
+            // host through the placement. A package can neither point it anywhere
+            // nor widen it.
+            if (app.entry !== undefined)
+                errors.push(`app ${appId} is an owner image app and takes no entry`);
+            if (Array.isArray(app.allowedOrigins) && app.allowedOrigins.length)
+                errors.push(`app ${appId} is an owner image app and loads from no origin`);
+            if (Array.isArray(app.permissions) && app.permissions.length)
+                errors.push(`app ${appId} is an owner image app and declares no permissions`);
+        }
+        if (app.type !== 'remoteImage' && app.type !== 'ownerImage' && !String(app.entry ?? '').trim())
+            errors.push(`app ${appId} entry is required`);
+        if (app.entry !== undefined && String(app.entry).length > 2048)
+            errors.push(`app ${appId} entry must be 2048 characters or fewer`);
+        if (app.permissions !== undefined && !Array.isArray(app.permissions)) {
+            errors.push(`app ${appId} permissions must be an array`);
+        }
+        else {
+            const permissions = Array.isArray(app.permissions) ? app.permissions.map(String) : [];
+            if (permissions.length > 8)
+                errors.push(`app ${appId} permissions exceed the 8-permission budget`);
+            for (const permission of permissions) {
+                if (!DEVICE_APP_PERMISSIONS.has(permission))
+                    errors.push(`app ${appId} has unsupported permission "${permission}"`);
+            }
+        }
+        if (app.type !== 'localWeb' && app.type !== 'canvas' && app.type !== 'ownerImage') {
+            const origins = Array.isArray(app.allowedOrigins)
+                ? app.allowedOrigins.map(String)
+                : [];
+            if (origins.length === 0)
+                errors.push(`app ${appId} requires allowedOrigins`);
+            if (origins.length > 16)
+                errors.push(`app ${appId} allowedOrigins exceeds the 16-origin budget`);
+            for (const origin of origins) {
+                try {
+                    if (new URL(origin).origin !== origin)
+                        errors.push(`app ${appId} allowed origin must not contain a path: ${origin}`);
+                }
+                catch {
+                    errors.push(`app ${appId} has invalid allowed origin: ${origin}`);
+                }
+            }
+        }
+    }
+    const canvasScreenNodes = new Set();
+    const audioReactiveLightIds = new Set();
+    const audioReactiveStreamPorts = new Set();
+    const componentIds = new Set();
+    let screenComponents = 0;
+    let pointLightComponents = 0;
+    const pointLightNodes = new Set();
+    for (const component of components) {
+        const componentId = String(component.id ?? '');
+        if (!componentId)
+            errors.push('component id must be a non-empty string');
+        else if (componentIds.has(componentId))
+            errors.push(`components: duplicate id "${componentId}"`);
+        componentIds.add(componentId);
+        // The host's `components` is a discriminated union over six kinds. Without
+        // an allowlist an unrecognized `type` fell through every branch below and
+        // was validated not at all — which is how `audioReactiveLight` shipped with
+        // required fields nobody read.
+        if (!COMPONENT_TYPES.has(String(component.type))) {
+            errors.push(`component ${componentId} has unsupported type "${String(component.type)}" (one of ${exports.DEVICE_COMPONENT_TYPES.join('|')})`);
+        }
+        // `node` is required on the host's `slider`, `pointLight` and `screen`
+        // variants (`validate.ts:423-527`); `clockHands`, `audioReactiveLight` and
+        // `characterSpot` have no such field. The loop below only resolves a node
+        // reference when one is present, so a component with none passed here and
+        // was rejected at load with `components.N: Invalid input`.
+        if (['slider', 'pointLight', 'screen'].includes(String(component.type)) &&
+            !isNonEmptyName(component.node)) {
+            errors.push(`component ${componentId} (${String(component.type)}) requires a non-empty node`);
+        }
+        const semanticNodes = [
+            'node',
+            'hourNode',
+            'minuteNode',
+            'secondNode',
+            'secondCounterweightNode',
+        ];
+        for (const field of semanticNodes) {
+            if (!component[field])
+                continue;
+            const semantic = String(component[field]);
+            const authored = String(bindings[semantic] ?? semantic);
+            if (nodeNames.length && !nodes.has(authored))
+                errors.push(`component ${String(component.id)} ${field} resolves to missing GLB node "${authored}"`);
+        }
+        if (component.type === 'screen') {
+            screenComponents += 1;
+            if (object(apps[String(component.app ?? '')]).type === 'canvas') {
+                const node = String(component.node ?? '');
+                if (canvasScreenNodes.has(node))
+                    errors.push(`screen ${String(component.id)} has duplicate canvas screen node "${node}"`);
+                canvasScreenNodes.add(node);
+                for (const field of ['sourceStateKey', 'playbackStateKey', 'volumeStateKey', 'powerStateKey']) {
+                    if (component[field])
+                        errors.push(`screen ${String(component.id)} canvas screens do not accept media controls (${field})`);
+                }
+                if (component.interactive)
+                    errors.push(`screen ${String(component.id)} canvas screens take input through declared interactions`);
+            }
+            if (object(apps[String(component.app ?? '')]).type === 'ownerImage') {
+                if (component.interactive)
+                    errors.push(`screen ${String(component.id)} owner image screens take input through the host's Set image action`);
+                for (const field of ['sourceStateKey', 'playbackStateKey', 'volumeStateKey', 'powerStateKey']) {
+                    if (component[field])
+                        errors.push(`screen ${String(component.id)} owner image screens show the copy's own image, not state (${field})`);
+                }
+                if (component.timeline)
+                    errors.push(`screen ${String(component.id)} owner image screens do not accept a media timeline`);
+            }
+            if (object(apps[String(component.app ?? '')]).type === 'remoteImage') {
+                if (component.interactive)
+                    errors.push(`screen ${String(component.id)} remote image screens take input through declared interactions`);
+                for (const field of ['playbackStateKey', 'volumeStateKey']) {
+                    if (component[field])
+                        errors.push(`screen ${String(component.id)} remote image screens do not accept media controls (${field})`);
+                }
+                if (component.timeline)
+                    errors.push(`screen ${String(component.id)} remote image screens do not accept a media timeline`);
+                const sourceKey = String(component.sourceStateKey ?? '');
+                if (!sourceKey)
+                    errors.push(`screen ${String(component.id)} remote image screens require sourceStateKey (the image URL)`);
+                else if (object(state[sourceKey]).type !== 'string')
+                    errors.push(`screen ${String(component.id)} sourceStateKey "${sourceKey}" must reference string state`);
+                if (component.powerStateKey && object(state[String(component.powerStateKey)]).type !== 'boolean')
+                    errors.push(`screen ${String(component.id)} powerStateKey "${String(component.powerStateKey)}" must be boolean`);
+            }
+            if (!apps[String(component.app ?? '')])
+                errors.push(`screen ${String(component.id)} references unknown app "${String(component.app)}"`);
+            for (const field of [
+                'powerStateKey',
+                'sourceStateKey',
+                'playbackStateKey',
+                'volumeStateKey',
+            ]) {
+                if (component[field] && !state[String(component[field])])
+                    errors.push(`screen ${String(component.id)} references unknown state "${String(component[field])}"`);
+            }
+            if (!(Number(component.widthM) > 0) || !(Number(component.heightM) > 0))
+                errors.push(`screen ${String(component.id)} requires positive widthM and heightM`);
+            if (Number(component.widthM) > 20)
+                errors.push(`screen ${String(component.id)} widthM must be <= 20`);
+            if (Number(component.heightM) > 20)
+                errors.push(`screen ${String(component.id)} heightM must be <= 20`);
+            if (component.suspendDistanceM !== undefined &&
+                (!isFiniteNumber(component.suspendDistanceM) ||
+                    component.suspendDistanceM <= 0 ||
+                    component.suspendDistanceM > 200)) {
+                errors.push(`screen ${String(component.id)} suspendDistanceM must be > 0 and <= 200`);
+            }
+            (0, deviceActionValidation_1.validateDeviceScreenTimeline)(component, state, interactionsById, errors);
+        }
+        if (component.type === 'pointLight') {
+            pointLightComponents += 1;
+            const node = typeof component.node === 'string' ? component.node : '';
+            if (node.length === 0) {
+                errors.push(`point light ${String(component.id)} requires a non-empty node`);
+            }
+            else if (pointLightNodes.has(node)) {
+                errors.push(`point light ${String(component.id)} duplicates node "${node}"`);
+            }
+            if (node.length > 0)
+                pointLightNodes.add(node);
+            const stateKey = String(component.stateKey ?? '');
+            if (object(state[stateKey]).type !== 'boolean') {
+                errors.push(`point light ${String(component.id)} stateKey "${stateKey}" must be boolean`);
+            }
+            if (component.colorStateKey !== undefined) {
+                const colorStateKey = String(component.colorStateKey ?? '');
+                const colorState = object(state[colorStateKey]);
+                const values = Array.isArray(colorState.values)
+                    ? colorState.values.map(String)
+                    : [];
+                if (colorState.type !== 'enum') {
+                    errors.push(`point light ${String(component.id)} colorStateKey "${colorStateKey}" must reference enum state`);
+                }
+                else if (values.length === 0 ||
+                    values.some((value) => !/^#[0-9a-fA-F]{6}$/.test(value))) {
+                    errors.push(`point light ${String(component.id)} colorStateKey "${colorStateKey}" enum values must all be #RRGGBB`);
+                }
+            }
+            if (component.brightnessStateKey !== undefined) {
+                const brightnessStateKey = String(component.brightnessStateKey ?? '');
+                const brightnessState = object(state[brightnessStateKey]);
+                if (!['integer', 'float'].includes(String(brightnessState.type))) {
+                    errors.push(`point light ${String(component.id)} brightnessStateKey "${brightnessStateKey}" must reference numeric state`);
+                }
+                else if (brightnessState.min !== 0 ||
+                    brightnessState.max !== 100) {
+                    errors.push(`point light ${String(component.id)} brightnessStateKey "${brightnessStateKey}" must declare min 0 and max 100`);
+                }
+            }
+            const color = component.color;
+            if (!((typeof color === 'number' &&
+                Number.isInteger(color) &&
+                color >= 0 &&
+                color <= 0xffffff) ||
+                (typeof color === 'string' && /^#[0-9a-fA-F]{6}$/.test(color)))) {
+                errors.push(`point light ${String(component.id)} color must be #RRGGBB or a 24-bit integer`);
+            }
+            if (typeof component.intensityCandela !== 'number' ||
+                !Number.isFinite(component.intensityCandela) ||
+                component.intensityCandela <= 0 ||
+                component.intensityCandela > 5_000) {
+                errors.push(`point light ${String(component.id)} intensityCandela must be > 0 and <= 5000`);
+            }
+            if (typeof component.distanceM !== 'number' ||
+                !Number.isFinite(component.distanceM) ||
+                component.distanceM <= 0 ||
+                component.distanceM > 25) {
+                errors.push(`point light ${String(component.id)} distanceM must be > 0 and <= 25`);
+            }
+            if (component.decay !== undefined &&
+                (typeof component.decay !== 'number' ||
+                    !Number.isFinite(component.decay) ||
+                    component.decay < 0 ||
+                    component.decay > 4)) {
+                errors.push(`point light ${String(component.id)} decay must be between 0 and 4`);
+            }
+            if (component.emissiveIntensity !== undefined &&
+                (typeof component.emissiveIntensity !== 'number' ||
+                    !Number.isFinite(component.emissiveIntensity) ||
+                    component.emissiveIntensity < 0 ||
+                    component.emissiveIntensity > 10)) {
+                errors.push(`point light ${String(component.id)} emissiveIntensity must be between 0 and 10`);
+            }
+        }
+        if (component.type === 'slider') {
+            const label = `slider ${componentId}`;
+            if (!['integer', 'float'].includes(String(object(state[String(component.stateKey ?? '')]).type))) {
+                errors.push(`${label} stateKey "${String(component.stateKey)}" must be numeric`);
+            }
+            if (!['x', 'y', 'z'].includes(String(component.axis)))
+                errors.push(`${label} axis must be x, y or z`);
+            if (!isFiniteNumber(component.minOffsetM))
+                errors.push(`${label} requires a finite minOffsetM`);
+            if (!isFiniteNumber(component.maxOffsetM))
+                errors.push(`${label} requires a finite maxOffsetM`);
+            if (!isFiniteNumber(component.durationMs) ||
+                component.durationMs < 16 ||
+                component.durationMs > 60_000) {
+                errors.push(`${label} durationMs must be between 16 and 60000`);
+            }
+            checkEasing(component.easing, label, errors);
+        }
+        if (component.type === 'clockHands') {
+            const label = `clock hands ${componentId}`;
+            const handNodes = [
+                'hourNode',
+                'minuteNode',
+                'secondNode',
+                'secondCounterweightNode',
+            ].filter((field) => String(component[field] ?? '').length > 0);
+            if (handNodes.length === 0)
+                errors.push(`${label} requires at least one hand node`);
+            if (component.timeZone !== undefined &&
+                !['local', 'utc'].includes(String(component.timeZone))) {
+                errors.push(`${label} timeZone must be local or utc`);
+            }
+            if (component.utcOffsetHours !== undefined) {
+                if (!isFiniteNumber(component.utcOffsetHours) ||
+                    component.utcOffsetHours < -12 ||
+                    component.utcOffsetHours > 14) {
+                    errors.push(`${label} utcOffsetHours must be between -12 and 14`);
+                }
+            }
+        }
+        if (component.type === 'audioReactiveLight') {
+            const label = `audio reactive light ${componentId}`;
+            const lightComponent = String(component.lightComponent ?? '');
+            if (!lightComponent) {
+                errors.push(`${label} requires a non-empty lightComponent`);
+            }
+            else if (audioReactiveLightIds.has(lightComponent)) {
+                errors.push(`${label} duplicates audio-reactive light "${lightComponent}"`);
+            }
+            audioReactiveLightIds.add(lightComponent);
+            const streamPort = String(component.streamPort ?? '');
+            if (!streamPort) {
+                errors.push(`${label} requires a non-empty streamPort`);
+            }
+            else if (audioReactiveStreamPorts.has(streamPort)) {
+                errors.push(`${label} duplicates audio-reactive stream port "${streamPort}"`);
+            }
+            audioReactiveStreamPorts.add(streamPort);
+            const enabledStateKey = String(component.enabledStateKey ?? '');
+            const enabledState = object(state[enabledStateKey]);
+            if (enabledState.type !== 'boolean') {
+                errors.push(`${label} enabledStateKey "${enabledStateKey}" must be boolean`);
+            }
+            else if (enabledState.default !== false) {
+                // An audio-reactive light that starts enabled would drive a light the
+                // creator never switched on, so the host demands a false default.
+                errors.push(`${label} enabledStateKey "${enabledStateKey}" must default to false`);
+            }
+            else if (enabledState.persist !== true) {
+                errors.push(`${label} enabledStateKey "${enabledStateKey}" must be durable`);
+            }
+            if (!components.some((candidate) => candidate.type === 'pointLight' &&
+                String(candidate.id ?? '') === lightComponent)) {
+                errors.push(`${label} references unknown point light "${lightComponent}"`);
+            }
+            const ranges = [
+                ['floor', 0, 1, true],
+                ['sensitivity', 0, 20, false],
+                ['attackMs', 16, 2_000, true],
+                ['releaseMs', 16, 5_000, true],
+            ];
+            for (const [field, min, max, inclusiveMin] of ranges) {
+                const value = component[field];
+                if (value === undefined)
+                    continue;
+                if (!isFiniteNumber(value) ||
+                    (inclusiveMin ? value < min : value <= min) ||
+                    value > max) {
+                    errors.push(`${label} ${field} must be ${inclusiveMin ? '>=' : '>'} ${min} and <= ${max}`);
+                }
+            }
+            if (component.fftSize !== undefined &&
+                (typeof component.fftSize !== 'number' ||
+                    !DEVICE_FFT_SIZES.has(component.fftSize))) {
+                errors.push(`${label} fftSize must be one of ${[...DEVICE_FFT_SIZES].join('|')}`);
+            }
+        }
+        if (component.type === 'characterSpot') {
+            if (!['sit', 'lie'].includes(String(component.pose)))
+                errors.push(`character spot ${String(component.id)} pose must be sit or lie`);
+            if (!isVec3(component.position))
+                errors.push(`character spot ${String(component.id)} requires position [x, y, z]`);
+            if (typeof component.facingYawDeg !== 'number' ||
+                !Number.isFinite(component.facingYawDeg)) {
+                errors.push(`character spot ${String(component.id)} requires finite facingYawDeg`);
+            }
+            if (component.clearanceM !== undefined &&
+                (typeof component.clearanceM !== 'number' ||
+                    !Number.isFinite(component.clearanceM) ||
+                    component.clearanceM < 0 ||
+                    component.clearanceM > 2)) {
+                errors.push(`character spot ${String(component.id)} clearanceM must be between 0 and 2`);
+            }
+            if (component.exitPosition !== undefined && !isVec3(component.exitPosition))
+                errors.push(`character spot ${String(component.id)} exitPosition must be [x, y, z]`);
+            if (component.label !== undefined &&
+                (typeof component.label !== 'string' ||
+                    component.label.trim().length === 0 ||
+                    component.label.length > 40)) {
+                errors.push(`character spot ${String(component.id)} label must be 1..40 characters`);
+            }
+            for (const field of ['fallbackAnimation', 'fallbackSocket']) {
+                if (component[field] !== undefined && !String(component[field]).trim())
+                    errors.push(`character spot ${String(component.id)} ${field} must be a non-empty name`);
+            }
+            // Field names matching is not enough: the host resolves both of these
+            // against the package's own declarations, so a dangling name that reads
+            // correctly still fails to load.
+            if (isNonEmptyName(component.fallbackAnimation) &&
+                !animations.has(String(component.fallbackAnimation))) {
+                errors.push(`character spot ${String(component.id)} references unknown fallback animation "${String(component.fallbackAnimation)}"`);
+            }
+            if (isNonEmptyName(component.fallbackSocket) &&
+                !sockets.has(String(component.fallbackSocket))) {
+                errors.push(`character spot ${String(component.id)} references unknown fallback socket "${String(component.fallbackSocket)}"`);
+            }
+        }
+    }
+    if (pointLightComponents > 4) {
+        errors.push(`components contain ${pointLightComponents} point lights, exceeding the 4-light Device budget`);
+    }
+    if (screenComponents > DEVICE_BUDGETS.maxScreens) {
+        errors.push(`components contain ${screenComponents} screens, exceeding the ${DEVICE_BUDGETS.maxScreens}-screen Device budget`);
+    }
+    const ports = Array.isArray(definition.ports)
+        ? definition.ports.map(object)
+        : [];
+    if (ports.length > DEVICE_BUDGETS.maxPorts)
+        errors.push(`ports: ${ports.length} exceeds budget ${DEVICE_BUDGETS.maxPorts}`);
+    const declaredInterfaces = Array.isArray(definition.interfaces)
+        ? definition.interfaces
+        : [];
+    if (declaredInterfaces.length > DEVICE_BUDGETS.maxInterfaces)
+        errors.push(`interfaces: ${declaredInterfaces.length} exceeds budget ${DEVICE_BUDGETS.maxInterfaces}`);
+    const portIds = new Set();
+    for (const port of ports) {
+        const id = String(port.id ?? '');
+        if (!id || portIds.has(id))
+            errors.push(`port id "${id}" is missing or duplicated`);
+        portIds.add(id);
+        if (id.length > 64)
+            errors.push(`port ${id} id must be 64 characters or fewer`);
+        if (!DEVICE_PORT_DIRECTIONS.has(String(port.direction)))
+            errors.push(`port ${id} has unsupported direction`);
+        if (!['value', 'event', 'command', 'stream'].includes(String(port.kind)))
+            errors.push(`port ${id} has unsupported kind`);
+        if (!['boolean', 'number', 'string', 'media.audio', 'media.video'].includes(String(port.dataType)))
+            errors.push(`port ${id} has unsupported dataType`);
+        // The host makes `interface` optional and bounds it to `min(1).max(128)`
+        // when present, so an absent interface is legal and a blank one is not.
+        // Requiring it here rejected ports the client loads without complaint.
+        if (port.interface !== undefined &&
+            (typeof port.interface !== 'string' || !port.interface.trim())) {
+            errors.push(`port ${id} requires interface`);
+        }
+        if (typeof port.interface === 'string' && port.interface.length > 128)
+            errors.push(`port ${id} interface must be 128 characters or fewer`);
+        if (port.semantic !== undefined && !String(port.semantic).trim())
+            errors.push(`port ${id} semantic must be a non-empty name`);
+        if (typeof port.semantic === 'string' && port.semantic.length > 128)
+            errors.push(`port ${id} semantic must be 128 characters or fewer`);
+        if (port.authority !== undefined &&
+            !DEVICE_PORT_AUTHORITIES.has(String(port.authority))) {
+            errors.push(`port ${id} has unsupported authority`);
+        }
+        if (port.maxLinks !== undefined &&
+            (!Number.isInteger(port.maxLinks) || Number(port.maxLinks) < 1 || Number(port.maxLinks) > 64)) {
+            errors.push(`port ${id} maxLinks must be 1..64`);
+        }
+        if (port.stateKey) {
+            const stateKey = String(port.stateKey);
+            const spec = object(state[stateKey]);
+            if (!Object.keys(spec).length) {
+                errors.push(`port ${id} references unknown state "${stateKey}"`);
+            }
+            else {
+                // A value port carries the state's own type across the bus; declaring
+                // `string` over numeric state is accepted offline and refused at load.
+                const expected = spec.type === 'boolean'
+                    ? 'boolean'
+                    : spec.type === 'integer' || spec.type === 'float'
+                        ? 'number'
+                        : 'string';
+                if (String(port.dataType) !== expected) {
+                    errors.push(`port ${id} dataType "${String(port.dataType)}" does not match ${String(spec.type)} state`);
+                }
+            }
+        }
+        if (port.kind === 'value' && !port.stateKey)
+            errors.push(`value port ${id} requires stateKey`);
+        if (port.kind !== 'value' && port.stateKey)
+            errors.push(`non-value port ${id} must not declare stateKey`);
+        if (port.kind === 'stream' &&
+            !['media.audio', 'media.video'].includes(String(port.dataType))) {
+            errors.push(`stream port ${id} requires media.audio or media.video dataType`);
+        }
+        // `routability` is stream-only on the host (`validate.ts:1466-1467`) and
+        // its vocabulary is exactly the host's three-member enum
+        // (`validate.ts:330`). `embedded-only` is a legal declaration, not an
+        // error: the host links it and carries the status on the envelope
+        // (`links.ts` `publishStream`), so only a non-stream port or an unknown
+        // member is refused here.
+        if (port.routability !== undefined) {
+            if (port.kind !== 'stream')
+                errors.push(`port ${id} routability is stream-only`);
+            else if (!DEVICE_STREAM_ROUTABILITY.has(String(port.routability)))
+                errors.push(`port ${id} has unsupported stream routability`);
+        }
+    }
+    // An audio-reactive light listens on a bus port, and the host refuses a port
+    // that is not the local routable `helix.audio/1` input it expects.
+    for (const component of components) {
+        if (component.type !== 'audioReactiveLight')
+            continue;
+        const streamPort = String(component.streamPort ?? '');
+        if (!streamPort)
+            continue;
+        const port = ports.find((candidate) => String(candidate.id ?? '') === streamPort);
+        if (!port ||
+            port.direction === 'output' ||
+            port.kind !== 'stream' ||
+            port.dataType !== 'media.audio' ||
+            port.interface !== 'helix.audio/1' ||
+            port.authority !== 'local' ||
+            (port.routability ?? 'routable') !== 'routable') {
+            errors.push(`audio reactive light ${String(component.id)} streamPort "${streamPort}" must be a local routable helix.audio/1 media.audio input`);
+        }
+    }
+    const graph = object(definition.graph);
+    const rawTriggers = graph.triggers;
+    // `triggers` is a non-optional key on the host's `graph` object
+    // (`validate.ts:528-530`), so `graph: {}` is rejected at load — and it is
+    // also the one shape that would otherwise read as "a graph that does
+    // nothing" and pass here.
+    if (rawTriggers === undefined)
+        errors.push('graph.triggers is required');
+    else if (!Array.isArray(rawTriggers))
+        errors.push('graph.triggers must be an array');
+    const triggers = Array.isArray(rawTriggers) ? rawTriggers : [];
+    if (triggers.length > DEVICE_BUDGETS.maxTriggers)
+        errors.push(`graph: ${triggers.length} triggers exceeds budget ${DEVICE_BUDGETS.maxTriggers}`);
+    const characterSpotIds = new Set(components
+        .filter((component) => component.type === 'characterSpot')
+        .map((component) => String(component.id ?? '')));
+    // Capability requirements driven by what the graph *does*, collected while
+    // the steps are walked — so a character step nested inside a branch counts
+    // exactly as a top-level one does, instead of being missed by a scan that
+    // only looked at the four character kinds.
+    const graphUsage = {
+        nodeMotion: components.some((component) => component.type === 'slider'),
+        audioPlayback: components.some((component) => component.type === 'audioReactiveLight'),
+        vfx: false,
+        posture: characterSpotIds.size > 0,
+        hand: false,
+        animation: components.some((component) => component.type === 'characterSpot' &&
+            component.fallbackAnimation !== undefined),
+    };
+    const graphContext = {
+        state,
+        nodes,
+        nodesKnown: nodeNames.length > 0,
+        bindings,
+        sockets,
+        effects,
+        audio,
+        animations,
+        characterSpots: characterSpotIds,
+        errors,
+        usage: graphUsage,
+    };
+    triggers.forEach((raw, index) => {
+        const triggerPath = `graph.triggers.${index}`;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            errors.push(`${triggerPath}: trigger must be an object`);
+            return;
+        }
+        const trigger = object(raw);
+        const on = String(trigger.on ?? '');
+        if (!TRIGGER_KINDS.has(on)) {
+            errors.push(`${triggerPath}: unsupported trigger "${on}" (one of ${exports.DEVICE_TRIGGER_KINDS.join('|')})`);
+            return;
+        }
+        if (on === 'interact') {
+            if (interactionsById.get(String(trigger.interaction))?.presentation !== undefined)
+                errors.push(`${triggerPath}: webPanel presentation cannot be a graph interaction trigger`);
+            if (!interactionIds.has(String(trigger.interaction))) {
+                errors.push(`graph references undeclared interaction "${String(trigger.interaction)}"`);
+            }
+        }
+        else if (on === 'stateChanged') {
+            if (!isNonEmptyName(trigger.key))
+                errors.push(`${triggerPath}: stateChanged requires a non-empty key`);
+        }
+        else if (on === 'signal') {
+            if (!isNonEmptyName(trigger.name))
+                errors.push(`${triggerPath}: signal requires a non-empty name`);
+        }
+        else if (on === 'playerNear') {
+            if (!isFiniteNumber(trigger.distanceM) ||
+                trigger.distanceM <= 0 ||
+                trigger.distanceM > 100) {
+                errors.push(`${triggerPath}: playerNear distanceM must be > 0 and <= 100`);
+            }
+            if (!['enter', 'exit'].includes(String(trigger.phase)))
+                errors.push(`${triggerPath}: playerNear phase must be enter or exit`);
+        }
+        // The host's `do` array is non-optional on every trigger variant.
+        if (trigger.do === undefined)
+            errors.push(`${triggerPath}: every trigger requires a do array`);
+        else {
+            validateGraphSteps(trigger.do, graphContext, `${triggerPath}.do`, 0);
+            let handBudgetInvalid = false;
+            if (graphHasHandStep(trigger.do)) {
+                const metrics = handGraphExecutionMetrics(trigger.do);
+                for (const metric of metrics) {
+                    if (metric.steps >= DEVICE_BUDGETS.maxStepsPerFire) {
+                        errors.push(`${triggerPath}: a hand reach/release execution path can exhaust the ${DEVICE_BUDGETS.maxStepsPerFire}-step runtime budget`);
+                        handBudgetInvalid = true;
+                        break;
+                    }
+                }
+                if (handGraphMaxPendingDelays(trigger.do) >
+                    DEVICE_BUDGETS.maxConcurrentDelays) {
+                    errors.push(`${triggerPath}: a hand reach/release execution path can exceed the ${DEVICE_BUDGETS.maxConcurrentDelays}-delay runtime limit`);
+                }
+            }
+            // Do not enumerate a graph the runtime cannot finish. In particular,
+            // nested 64-repeat bodies have an exponential concrete path count even
+            // though the structural metric above proves they abort at 256 steps.
+            const endings = handBudgetInvalid ? [] : handReachPathEnds(trigger.do);
+            for (const hand of ['left', 'right']) {
+                if (endings.some((path) => path.has(hand))) {
+                    errors.push(`${triggerPath}: a reachable path leaves ${hand} reachCharacterHand without releaseCharacterHand`);
+                }
+            }
+        }
+    });
+    // `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.
+    if (definition.compatibility !== undefined) {
+        const rawHosts = object(definition.compatibility).hosts;
+        // The block is optional; the key inside it is not. `{ requiredCapabilities }`
+        // with no `hosts` was accepted here and rejected at load with
+        // `compatibility.hosts: Invalid input: expected array, received undefined`.
+        if (rawHosts === undefined) {
+            errors.push('compatibility.hosts is required');
+        }
+        else if (!Array.isArray(rawHosts)) {
+            errors.push('compatibility.hosts must be an array');
+        }
+        const hosts = Array.isArray(rawHosts) ? rawHosts : [];
+        if (Array.isArray(rawHosts) && hosts.length === 0) {
+            errors.push('compatibility.hosts must name at least one host');
+        }
+        for (const host of hosts) {
+            if (!DEVICE_HOST_SET.has(String(host))) {
+                errors.push(`compatibility.hosts has unsupported host "${String(host)}" (one of ${exports.DEVICE_HOSTS_LIST})`);
+            }
+        }
+    }
+    const rawCapabilities = definition.capabilities;
+    if (rawCapabilities !== undefined && !Array.isArray(rawCapabilities)) {
+        errors.push('capabilities must be an array');
+    }
+    const capabilities = new Set(Array.isArray(rawCapabilities) ? rawCapabilities.map(String) : []);
+    if (Array.isArray(rawCapabilities) &&
+        rawCapabilities.length > DEVICE_BUDGETS.maxCapabilities) {
+        errors.push(`capabilities: ${rawCapabilities.length} entries exceeds budget ${DEVICE_BUDGETS.maxCapabilities}`);
+    }
+    for (const capability of capabilities) {
+        if (!CAPABILITIES.has(capability)) {
+            errors.push(`capability "${capability}" is unsupported`);
+        }
+    }
+    if (components.some((component) => component.type === 'pointLight') &&
+        !capabilities.has('presentation.light')) {
+        errors.push('a point light requires capability presentation.light');
+    }
+    if (Object.values(object(definition.apps)).some((raw) => object(raw).type === 'canvas') &&
+        !capabilities.has('app.canvas')) {
+        errors.push('a canvas app requires capability app.canvas');
+    }
+    // The remainder of the host's `requiredByContent` list (`validate.ts:1496-1553`)
+    // — the entries above do not cover. Each one is a thing the definition *uses*,
+    // and the host refuses a definition that uses a surface it never declared, so
+    // leaving any of these out is the audited bug class in its purest form: the
+    // package is CLI-green and load-rejected.
+    const requiresByContent = [
+        [
+            'state.durable',
+            Object.values(state).some((spec) => object(spec).persist === true),
+        ],
+        ['presentation.nodeMotion', graphUsage.nodeMotion],
+        [
+            'clock.serverTime',
+            components.some((component) => component.type === 'clockHands'),
+        ],
+        ['audio.playback', graphUsage.audioPlayback],
+        ['presentation.vfx', graphUsage.vfx],
+        [
+            'screen.render',
+            components.some((component) => component.type === 'screen'),
+        ],
+        [
+            'screen.input',
+            components.some((component) => component.type === 'screen' && component.interactive),
+        ],
+        [
+            'app.web.local',
+            Object.values(apps).some((raw) => object(raw).type === 'localWeb'),
+        ],
+        [
+            'app.web.remote',
+            Object.values(apps).some((raw) => ['remoteWeb', 'youtube'].includes(String(object(raw).type))),
+        ],
+        [
+            'app.web.panel',
+            interactions.some((interaction) => interaction.presentation !== undefined),
+        ],
+        ['device.ports', ports.length > 0],
+    ];
+    for (const [capability, used] of requiresByContent) {
+        if (used && !capabilities.has(capability)) {
+            errors.push(`capabilities: definition uses but does not declare ${capability}`);
+        }
+    }
+    if (Object.values(object(definition.apps)).some((raw) => object(raw).type === 'remoteImage') &&
+        !capabilities.has('app.image.remote')) {
+        errors.push('a remote image app requires capability app.image.remote');
+    }
+    if (Object.values(object(definition.apps)).some((raw) => object(raw).type === 'ownerImage') &&
+        !capabilities.has('app.image.owner')) {
+        errors.push('an owner image app requires capability app.image.owner');
+    }
+    if (graphUsage.posture && !capabilities.has('character.posture'))
+        errors.push('a character spot requires capability character.posture');
+    if (graphUsage.animation && !capabilities.has('character.animate'))
+        errors.push('character animation requires capability character.animate');
+    if (graphUsage.hand && !capabilities.has('character.hand'))
+        errors.push('hand attachment requires capability character.hand');
+    // The host refuses any `collision` block on a Device that has not declared
+    // `physics.solid` (`validate.ts` collision -> capability cross-check). Note
+    // `model.glb` is deliberately NOT cross-checked here: the host has no such
+    // rule, and enforcing it rejected valid packages.
+    if (collision.length > 0 && !capabilities.has('physics.solid')) {
+        errors.push('collision requires the physics.solid capability');
+    }
+    if (['serverValidated', 'serverAuthoritative'].includes(String(definition.authority)) &&
+        !capabilities.has('room.authority')) {
+        errors.push('server authority requires capability room.authority');
+    }
+    for (const required of Array.isArray(object(definition.compatibility).requiredCapabilities)
+        ? object(definition.compatibility).requiredCapabilities
+        : []) {
+        if (!capabilities.has(String(required))) {
+            errors.push(`compatibility requires undeclared capability "${String(required)}"`);
+        }
+    }
+    const migrationStarts = new Set();
+    for (const raw of Array.isArray(definition.stateMigrations)
+        ? definition.stateMigrations
+        : []) {
+        const migration = object(raw);
+        const from = Number(migration.from);
+        const to = Number(migration.to);
+        if (!Number.isInteger(from) || to !== from + 1) {
+            errors.push(`state migration ${from}->${to} must advance by one`);
+        }
+        if (migrationStarts.has(from)) {
+            errors.push(`state migrations duplicate from=${from}`);
+        }
+        migrationStarts.add(from);
+    }
+    if (definition.thumbnail !== undefined) {
+        const thumbnail = object(definition.thumbnail);
+        if (!THUMBNAIL_POLICIES.has(String(thumbnail.policy))) {
+            errors.push(`thumbnail.policy must be one of ${exports.DEVICE_THUMBNAIL_POLICIES.join('|')}`);
+        }
+        const stateKeys = thumbnail.stateKeys;
+        if (stateKeys !== undefined && !Array.isArray(stateKeys)) {
+            errors.push('thumbnail.stateKeys must be an array');
+        }
+        const keys = Array.isArray(stateKeys) ? stateKeys : [];
+        if (keys.length > DEVICE_BUDGETS.maxThumbnailStateKeys) {
+            errors.push(`thumbnail.stateKeys: ${keys.length} entries exceeds budget ${DEVICE_BUDGETS.maxThumbnailStateKeys}`);
+        }
+        for (const key of keys) {
+            if (!isNonEmptyName(key)) {
+                errors.push('thumbnail.stateKeys entries must be non-empty names');
+            }
+            else if (!state[String(key)]) {
+                errors.push(`thumbnail references unknown state "${String(key)}"`);
+            }
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        directory: target.directory,
+        definitionPath: target.path,
+        modelPath,
+        nodeNames,
+        errors,
+        warnings,
+        definition: errors.length === 0 ? definition : undefined,
+    };
+}
+function testDeviceProject(input, mode) {
+    const validation = validateDeviceProject(input);
+    if (!validation.ok || !validation.definition) {
+        return {
+            ok: false,
+            mode,
+            clients: mode === 'multiplayer' ? 2 : 1,
+            actionsExercised: [],
+            finalState: {},
+            persistentState: {},
+            errors: validation.errors,
+        };
+    }
+    const definition = validation.definition;
+    const authority = initialState(definition);
+    const clientA = { ...authority };
+    const clientB = { ...authority };
+    const actions = Array.isArray(definition.interactions)
+        ? definition.interactions.map(object)
+        : [];
+    const exercised = [];
+    const errors = [];
+    for (const interaction of actions) {
+        const value = exerciseValue(interaction, authority);
+        invoke(definition, authority, interaction, value);
+        Object.assign(clientA, authority);
+        if (mode === 'multiplayer')
+            Object.assign(clientB, authority);
+        exercised.push(String(interaction.id));
+        if (JSON.stringify(clientA) !== JSON.stringify(authority))
+            errors.push(`client A diverged after ${String(interaction.id)}`);
+        if (mode === 'multiplayer' &&
+            JSON.stringify(clientB) !== JSON.stringify(authority))
+            errors.push(`client B diverged after ${String(interaction.id)}`);
+    }
+    const stateSchema = object(definition.state);
+    const persistentState = Object.fromEntries(Object.entries(authority).filter(([key]) => object(stateSchema[key]).persist === true));
+    const remounted = initialState(definition);
+    for (const [key, value] of Object.entries(persistentState))
+        remounted[key] = coerce(object(stateSchema[key]), value);
+    for (const [key, value] of Object.entries(persistentState)) {
+        if (remounted[key] !== value)
+            errors.push(`persistent state ${key} did not round-trip`);
+    }
+    return {
+        ok: errors.length === 0,
+        mode,
+        clients: mode === 'multiplayer' ? 2 : 1,
+        actionsExercised: exercised,
+        finalState: authority,
+        persistentState,
+        errors,
+    };
+}
+function clockDefinition(id, title) {
+    return {
+        format: 'helix.device',
+        formatVersion: 1,
+        id,
+        version: '1.0.0',
+        title,
+        model: {
+            kind: 'glb',
+            url: './model.glb',
+            nodeBindings: {
+                hourHand: 'hourHand',
+                minuteHand: 'minuteHand',
+                secondHand: 'secondHand',
+                secondCounterweight: 'secondCounterweight',
+            },
+        },
+        state: {},
+        interactions: [],
+        components: [
+            {
+                id: 'hands',
+                type: 'clockHands',
+                hourNode: 'hourHand',
+                minuteNode: 'minuteHand',
+                secondNode: 'secondHand',
+                secondCounterweightNode: 'secondCounterweight',
+                timeZone: 'local',
+            },
+        ],
+        graph: { triggers: [] },
+        script: null,
+        activationPreset: 'room',
+        authority: 'presentationOnly',
+        capabilities: ['model.glb', 'state.typed', 'clock.serverTime'],
+        stateVersion: 1,
+        compatibility: {
+            hosts: ['home', 'world'],
+            requiredCapabilities: ['model.glb', 'clock.serverTime'],
+        },
+        thumbnail: { policy: 'never' },
+    };
+}
+function deskDefinition(id, title) {
+    return {
+        format: 'helix.device',
+        formatVersion: 1,
+        id,
+        version: '1.0.0',
+        title,
+        model: { kind: 'glb', url: './model.glb', nodeBindings: { top: 'top' } },
+        state: {
+            height: {
+                type: 'float',
+                min: 0.62,
+                max: 1.25,
+                default: 0.74,
+                persist: true,
+            },
+        },
+        interactions: [
+            {
+                id: 'setHeight',
+                label: 'Adjust height',
+                verb: 'use',
+                control: {
+                    kind: 'number',
+                    stateKey: 'height',
+                    min: 0.62,
+                    max: 1.25,
+                    step: 0.01,
+                    unit: 'm',
+                },
+            },
+        ],
+        components: [
+            {
+                id: 'topLift',
+                type: 'slider',
+                node: 'top',
+                axis: 'y',
+                stateKey: 'height',
+                minOffsetM: 0.62,
+                maxOffsetM: 1.25,
+                durationMs: 900,
+                easing: 'easeOutCubic',
+            },
+        ],
+        graph: { triggers: [] },
+        script: null,
+        activationPreset: 'room',
+        authority: 'serverValidated',
+        capabilities: [
+            'model.glb',
+            'state.typed',
+            'state.durable',
+            'presentation.nodeMotion',
+            'room.authority',
+        ],
+        stateVersion: 1,
+        compatibility: {
+            hosts: ['home', 'world'],
+            requiredCapabilities: [
+                'model.glb',
+                'state.typed',
+                'presentation.nodeMotion',
+                'room.authority',
+            ],
+        },
+        thumbnail: { policy: 'discreteState', stateKeys: ['height'] },
+    };
+}
+function televisionDefinition(id, title) {
+    return {
+        format: 'helix.device',
+        formatVersion: 1,
+        id,
+        version: '1.0.0',
+        title,
+        model: { kind: 'glb', url: './model.glb', nodeBindings: { screen: 'screen' } },
+        apps: {
+            player: {
+                type: 'youtube',
+                entry: 'M7lc1UVf-VE',
+                allowedOrigins: [
+                    'https://www.youtube.com',
+                    'https://www.youtube-nocookie.com',
+                ],
+                permissions: ['web.content', 'network.fetch', 'audio.media'],
+            },
+        },
+        state: {
+            powered: { type: 'boolean', default: true, persist: true },
+            video: { type: 'string', default: 'M7lc1UVf-VE', persist: true },
+            playback: { type: 'enum', values: ['pause', 'play'], default: 'pause', persist: true },
+            volume: { type: 'integer', min: 0, max: 100, default: 55, persist: true },
+        },
+        interactions: [
+            { id: 'power', label: 'Power', verb: 'use' },
+            {
+                id: 'queueVideo',
+                label: 'Queue YouTube video',
+                verb: 'use',
+                control: { kind: 'text', stateKey: 'video', placeholder: 'YouTube URL or video ID', maxLength: 512, inputMode: 'url' },
+            },
+            {
+                id: 'playback',
+                label: 'Playback',
+                verb: 'use',
+                control: { kind: 'choice', stateKey: 'playback', options: [{ value: 'play', label: 'Play' }, { value: 'pause', label: 'Pause' }] },
+            },
+            {
+                id: 'volume',
+                label: 'Volume',
+                verb: 'use',
+                control: { kind: 'number', stateKey: 'volume', min: 0, max: 100, step: 1, unit: '%' },
+            },
+        ],
+        components: [
+            {
+                id: 'display', type: 'screen', node: 'screen', app: 'player', widthM: 1.28,
+                heightM: 0.72, interactive: true, powerStateKey: 'powered', sourceStateKey: 'video',
+                playbackStateKey: 'playback', volumeStateKey: 'volume', suspendDistanceM: 24,
+            },
+        ],
+        ports: [
+            { id: 'power', direction: 'bidirectional', kind: 'value', dataType: 'boolean', interface: 'helix.power/1', semantic: 'power.state', authority: 'server', stateKey: 'powered', autoPair: true, maxLinks: 1 },
+            { id: 'volume', direction: 'bidirectional', kind: 'value', dataType: 'number', interface: 'helix.volume/1', semantic: 'media.volume', authority: 'server', stateKey: 'volume', autoPair: true, maxLinks: 4 },
+            // The template's audio output is the port a creator links to a speaker
+            // or an audio-reactive light, so it must be `routable`. It shipped as
+            // `embedded-only`, which contradicted the sibling example
+            // (`examples/continuum-media-television/device.json`) and the host's own
+            // television fixture (`lib/devices/fixtures.ts`), and produced a link
+            // that connected and then never carried audio.
+            { id: 'audio', direction: 'output', kind: 'stream', dataType: 'media.audio', interface: 'helix.audio/1', semantic: 'audio.main', authority: 'local', routability: 'routable', autoPair: true, maxLinks: 8 },
+        ],
+        interfaces: ['helix.television/1', 'helix.media-player/1'],
+        graph: { triggers: [{ on: 'interact', interaction: 'power', do: [{ step: 'toggleState', key: 'powered' }] }] },
+        script: null,
+        activationPreset: 'room',
+        authority: 'serverValidated',
+        capabilities: ['model.glb', 'state.typed', 'state.durable', 'room.authority', 'screen.render', 'screen.input', 'app.web.remote', 'audio.playback', 'device.ports'],
+        stateVersion: 1,
+        compatibility: { hosts: ['home', 'world'], requiredCapabilities: ['model.glb', 'state.typed', 'screen.render', 'screen.input', 'app.web.remote', 'audio.playback', 'device.ports', 'room.authority'] },
+        thumbnail: { policy: 'discreteState', stateKeys: ['powered'] },
+    };
+}
+function createDeviceProject(input) {
+    const directory = (0, node_path_1.resolve)(input.directory);
+    const sourceModel = (0, node_path_1.resolve)(input.modelPath);
+    if (!(0, node_fs_1.existsSync)(sourceModel))
+        throw new Error(`Model does not exist: ${sourceModel}`);
+    const nodeNames = readDeviceGlbNodeNames(sourceModel);
+    (0, node_fs_1.mkdirSync)(directory, { recursive: true });
+    const definitionPath = (0, node_path_1.join)(directory, exports.DEVICE_FILENAME);
+    const modelPath = (0, node_path_1.join)(directory, 'model.glb');
+    if ((0, node_fs_1.existsSync)(definitionPath) || (0, node_fs_1.existsSync)(modelPath)) {
+        throw new Error(`Refusing to overwrite an existing Device project in ${directory}`);
+    }
+    const definition = input.template === 'clock'
+        ? clockDefinition(input.id, input.title)
+        : input.template === 'television'
+            ? televisionDefinition(input.id, input.title)
+            : deskDefinition(input.id, input.title);
+    (0, node_fs_1.copyFileSync)(sourceModel, modelPath);
+    (0, node_fs_1.writeFileSync)(definitionPath, `${JSON.stringify(definition, null, 2)}\n`);
+    return { directory, definitionPath, modelPath, nodeNames };
+}
+//# sourceMappingURL=device.js.map