@helix3/helix-cli 0.1.16-helix3.249 → 0.1.16-helix3.250

package/README.md

@@ -49,7 +49,7 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix item publish <mesh.glb> --title <t> [--collectible-supply <n>] [initial distribution flags] [--dry-run\|--quote]` | Publish a Standard item by default, or one fixed-supply Collectible. The item definition is separate from acquisition routes. |
 | `helix item distribution create\|list\|update\|disable …` | Manage Marketplace/World Claim or Buy routes without republishing the item or paying another publish fee. |
 | `helix device create <dir> --id <slug> --title <t> --model <mesh.glb> --template standing-desk\|clock\|television` | Scaffold a GLB-backed `helix.device/1` definition, including the interactive TV/media-player template. There is intentionally no website Device editor. |
-| `helix device validate [dir] [--json]` | Validate the definition, GLB bytes and named-node bindings, typed state/controls, capabilities, and Home+World compatibility. |
+| `helix device validate [dir] [--json]` | Validate the definition, GLB bytes and named-node bindings, typed state/controls, capabilities, and Home+World compatibility, including [declarative character hand reach](docs/device-hand-reach.md). |
 | `helix device test [dir] [--mode single\|multiplayer\|both] [--json]` | Exercise every interaction, persistence remount, and deterministic one-/two-client authority convergence. |
 | `helix world scene-elements compile <input> --output <scene>` | Compile typed Scene v2 authoring, including exact Continuum Device pins, instances, and locally validated typed links. See [`examples/scene-elements-devices.json`](examples/scene-elements-devices.json). |
 | `helix preview-video <slug> <youtube-url>` | Set or clear a published world's YouTube preview. |

package/dist/device.d.ts

@@ -42,7 +42,7 @@ export declare const DEVICE_COMPONENT_TYPES: readonly ["slider", "clockHands", "
  * `repeat`, `stopAudio`) — their absence from the examples is why the gap went
  * unnoticed for so long.
  */
-export declare const DEVICE_GRAPH_STEP_KINDS: readonly ["setState", "toggleState", "moveNode", "rotateNode", "playAudio", "stopAudio", "setVfx", "attachCharacter", "playCharacterAnimation", "releaseCharacter", "enterCharacterSpot", "attachItem", "releaseItem", "emitSignal", "branch", "sequence", "delay", "repeat"];
+export declare const DEVICE_GRAPH_STEP_KINDS: readonly ["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.
  *

package/dist/device.js

@@ -117,6 +117,8 @@ exports.DEVICE_GRAPH_STEP_KINDS = [
     'playCharacterAnimation',
     'releaseCharacter',
     'enterCharacterSpot',
+    'reachCharacterHand',
+    'releaseCharacterHand',
     'attachItem',
     'releaseItem',
     'emitSignal',
@@ -162,6 +164,8 @@ 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);
 /**
@@ -183,6 +187,8 @@ const DEVICE_BUDGETS = {
     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([
@@ -348,7 +354,7 @@ 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 union of 16 kinds and
+ * 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
@@ -520,6 +526,83 @@ function validateGraphSteps(steps, context, path, depth) {
                 }
                 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
@@ -620,6 +703,267 @@ function validateGraphSteps(steps, context, path, depth) {
         }
     });
 }
+/**
+ * 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']);
 /**
@@ -1835,8 +2179,33 @@ function validateDeviceProject(input) {
         // 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
+        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