@helix3/helix-cli 0.1.18-helix3.340 → 0.1.18-helix3.342

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) {