@helix3/helix-cli 0.1.18-helix3.339 → 0.1.18-helix3.341

package/README.md

@@ -49,7 +49,8 @@ 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 item visual-qa <item-id> [--submit] [--local-critic] [--storage-state <file>] [--host <id…>]` | Render the item's current package version headless in the real runtime (test-grounds world for vehicles and whole avatars, the customiser for add-ons and wearables on every declared host/base, the item viewer for props), measure it, and with `--submit` record the backend's verdict (numeric asserts + vision critic) against that exact version. **Marketplace/Vault listing, distributions and version moves on a public item require a pass.** See [docs/visual-qa.md](docs/visual-qa.md). |
-| `helix item visual-qa <item-id> --package-version <v> [--vehicle-package <file>]` | Render a version the item is **not pinned to yet**, so a refused version move can pass the gate before the pointer moves. Vehicles and avatars go through Try Now (vehicles also need the move's vehicle package), add-ons and wearables through the customiser; the bundle names the candidate, and the vehicle checksum is the one the server minted for that trial. Never falls back to the current version. See [docs/visual-qa-candidate-versions.md](docs/visual-qa-candidate-versions.md). |
+| `helix item visual-qa <item-id> --package-version <v> [--vehicle-package <file>]` | Render a version the item is **not pinned to yet**, so a refused version move can pass the gate before the pointer moves. Vehicles and avatars go through Try Now (vehicles also need the move's vehicle package), add-ons and wearables through the customiser; the bundle names the candidate, and the vehicle checksum is the one the server minted for that trial. Never falls back to the current version. See [docs/visual-qa-candidate-versions.md](docs/visual-qa-candidate-versions.md). With `--submit`, a PASS prints the next command (`helix item set-version …`); a 403 for a non-creator says so on the first line; `--status` also lists the item's pending (sealed, not current) versions. |
+| `helix item set-version <item-id> --package-version <v> --reason <text> [--vehicle-package <file>] [--expected-current-version-id <uuid>] [--json]` | Move an item to a sealed Package Version of its own package (pin resolved from the public Package API; `POST /api/v1/universal-items/<id>/versions`). The flow for a **listed** item: `item publish-version` seals vN and the move is refused → `item visual-qa <id> --package-version vN --submit` → `item set-version`. A refusal prints the server's message first (it names the next command), then the remedy and any hosted render it queued. An unknown version lists the sealed ones. |
 | `helix device create <dir> --id <slug> --title <t> --model <mesh.glb> --template standing-desk\|clock\|television` | Scaffold a GLB-backed `helix.device/1` definition, including the interactive TV/media-player template. There is intentionally no website Device editor. |
 | `helix device validate [dir] [--json]` | Validate the definition, GLB bytes and named-node bindings, typed state/controls, capabilities, and Home+World compatibility, including [declarative character hand reach](docs/device-hand-reach.md). |
 | `helix device test [dir] [--mode single\|multiplayer\|both] [--json]` | Exercise every interaction, persistence remount, and deterministic one-/two-client authority convergence. |

package/dist/device.d.ts

@@ -23,7 +23,7 @@ export declare const DEVICE_INTERACTION_VERB_LIST: string;
  * fail `helix device validate` while the client loaded it happily. Add
  * capabilities to both lists, never to one.
  */
-export declare const DEVICE_CAPABILITIES: readonly ["model.glb", "presentation.nodeMotion", "clock.serverTime", "state.typed", "state.durable", "room.authority", "audio.playback", "presentation.light", "presentation.vfx", "character.posture", "character.animate", "character.hand", "signals.local", "screen.render", "screen.input", "app.web.local", "app.web.remote", "app.image.remote", "app.image.owner", "app.canvas", "device.ports", "physics.solid"];
+export declare const DEVICE_CAPABILITIES: readonly ["model.glb", "presentation.nodeMotion", "clock.serverTime", "state.typed", "state.durable", "room.authority", "audio.playback", "presentation.light", "presentation.vfx", "character.posture", "character.animate", "character.hand", "signals.local", "screen.render", "screen.input", "app.web.local", "app.web.remote", "app.web.panel", "app.image.remote", "app.image.owner", "app.canvas", "device.ports", "physics.solid"];
 /**
  * The closed component vocabulary.
  *

package/dist/device.js

@@ -75,6 +75,7 @@ exports.DEVICE_CAPABILITIES = [
     'screen.input',
     'app.web.local',
     'app.web.remote',
+    'app.web.panel',
     'app.image.remote',
     'app.image.owner',
     'app.canvas',
@@ -1232,6 +1233,80 @@ function exerciseValue(interaction, state) {
     }
     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 = [];
@@ -1444,6 +1519,9 @@ function validateDeviceProject(input) {
         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');
@@ -2177,6 +2255,8 @@ function validateDeviceProject(input) {
             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)}"`);
             }
@@ -2308,6 +2388,10 @@ function validateDeviceProject(input) {
             '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) {