@glassly/engine 0.3.4-dev.704 → 0.3.5-dev.705

package/build/services/LocalMiniappRuntime.js

@@ -51,6 +51,9 @@ import { MiniappIcons } from "./MiniappIcons";
 import { pairedControllersFrom, readyControllersKey } from "./controllers";
 import { DERIVED_SETTINGS_KEYS, SETTINGS_BRIDGE_KEYS, controllersSettingFrom, isDerivedSettingsKey, selectSettingsBridgeKeys, validateSettingsSet, } from "./settingsBridge";
 import { mayUsePermission } from "./miniappPermissions";
+import { miniappRunningRegistry } from "./MiniappRunningRegistry";
+import { miniappWidgetMode } from "./MiniappWidgetMode";
+import { dropHost as dropWidgetHost, dropProvider as dropWidgetProvider, emptyWidgetPlacements, frameOf as widgetFrameOf, hostsOf as widgetHostsOf, isProviderPlaced, placedProviders, placementOf, placeWidget, setFrame as setWidgetFrame, unplaceWidget, } from "./widgetPlacements";
 import { activeDashboard, addDashboardApp, displayViewsFor, isDashboardApp, isOverlayApp, onOverlayAppsChange, removeDashboardApp, setOverlayViewer, } from "./pages/overlayApps";
 import { pagesEligible } from "./pages/pageEligibility";
 import nativeNavigationService from "./NativeNavigationService";
@@ -227,6 +230,7 @@ const PERMISSION_TYPE_TO_CANONICAL = {
     SPEAKERS: "speakers",
     MANAGE_MINIAPPS: "manageMiniapps",
     PLATFORM_SETTINGS: "platformSettings",
+    HOST_WIDGETS: "hostWidgets",
 };
 /**
  * User API keys (Settings > API Keys) a miniapp may read via
@@ -329,6 +333,7 @@ const ALL_CANONICAL_PERMISSIONS = [
     "displayMirror",
     "manageMiniapps",
     "platformSettings",
+    "hostWidgets",
 ];
 /**
  * Build the {location, microphone, camera, notifications, calendar, apiKeys}
@@ -1075,6 +1080,8 @@ class LocalMiniappRuntime {
         // current on-glasses frame, this clears the glasses (or restores the
         // core app's saved frame).
         localDisplayManager.onUnmount(packageName);
+        // As a widget host its placements go; as a provider its boxes are forgotten.
+        this.onWidgetPartyGone(packageName);
         this.connectedApps.delete(packageName);
         this.recomputeMicRequirements();
         if (releasedMicGateOverride) {
@@ -1466,6 +1473,24 @@ class LocalMiniappRuntime {
             case MiniappRequestType.ACTION_RESULT:
                 this.handleActionResult(packageName, payload);
                 break;
+            case MiniappRequestType.WIDGETS_LIST:
+                this.handleWidgetsList(packageName, requestId);
+                break;
+            case MiniappRequestType.WIDGET_PLACE:
+                void this.handleWidgetPlace(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.WIDGET_UNPLACE:
+                void this.handleWidgetUnplace(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.WIDGET_SEND:
+                void this.handleWidgetSend(packageName, payload, requestId);
+                break;
+            case MiniappRequestType.WIDGET_UPDATE:
+                this.handleWidgetUpdate(packageName, payload);
+                break;
+            case MiniappRequestType.WIDGET_RESULT:
+                this.handleWidgetResult(packageName, payload);
+                break;
             case MiniappRequestType.SYSTEM_EXIT:
                 void this.handleSystemExit(packageName, requestId);
                 break;
@@ -1791,7 +1816,9 @@ class LocalMiniappRuntime {
     }
     /** The app holding `gesture` (the most recent claimer), or null when it is unclaimed. */
     gestureClaimant(gesture) {
-        return gestureClaimant(this.gestureClaims, gesture);
+        const claimant = gestureClaimant(this.gestureClaims, gesture);
+        // A widget-only app hears no touch input; its claim waits until the wearer opens it.
+        return claimant !== null && miniappWidgetMode.isWidgetOnly(claimant) ? null : claimant;
     }
     /** Has this app registered the gesture, even if a later claimant currently receives it? */
     hasGestureClaim(packageName, gesture) {
@@ -2055,6 +2082,10 @@ class LocalMiniappRuntime {
                 console.log(`${LOG_TAG}: dropping display from unmounted app ${packageName}`);
                 return;
             }
+            if (miniappWidgetMode.isWidgetOnly(packageName)) {
+                this.sendResult(packageName, requestId, true);
+                return;
+            }
             if (!payload.layout || typeof payload.layout !== "object") {
                 this.sendResult(packageName, requestId, false, undefined, {
                     code: MiniappErrorCode.INTERNAL,
@@ -2093,6 +2124,11 @@ class LocalMiniappRuntime {
                 this.sendResult(packageName, requestId, true, { status: "blocked", reason: "app stopped" });
                 return;
             }
+            // A widget-only app draws through its widget alone.
+            if (miniappWidgetMode.isWidgetOnly(packageName)) {
+                this.sendResult(packageName, requestId, true, { status: "blocked", reason: "widget mode" });
+                return;
+            }
             if (!Array.isArray(payload.elements)) {
                 this.sendResult(packageName, requestId, false, undefined, {
                     code: MiniappErrorCode.INTERNAL,
@@ -4971,6 +5007,9 @@ class LocalMiniappRuntime {
         for (const packageName of matchedSubs) {
             if (only !== undefined && packageName !== only)
                 continue;
+            // The wearer's touches reach a widget-only app through its host's widget events alone.
+            if (normalizedStream === MiniappStreamType.TOUCH_EVENT && miniappWidgetMode.isWidgetOnly(packageName))
+                continue;
             let transcriptionRoute;
             if (normalizedStream.startsWith("transcription:") && transcriptionSource) {
                 const routes = this.appTranscriptionRoutesForEvent(packageName, normalizedStream);
@@ -5413,6 +5452,298 @@ class LocalMiniappRuntime {
             // Best-effort: a failed stop leaves the app running, which is safe.
         }
     }
+    // ---------------------------------------------------------------------------
+    // Dashboard widgets (session.widgets): a provider serves widgets it declares,
+    // a host with HOST_WIDGETS places them. The provider runs in widget mode
+    // while anything of it is placed and stops once nothing is.
+    // ---------------------------------------------------------------------------
+    widgetPlacements = emptyWidgetPlacements();
+    /** Outstanding widget event calls, keyed by host-generated callId. */
+    widgetCalls = new Map();
+    widgetCallSeq = 0;
+    /** Elements per widget frame; a card is small, and the link is slow. */
+    static WIDGET_FRAME_ELEMENT_CAP = 64;
+    requireWidgetHost(packageName, requestId, op) {
+        return this.requirePermission(packageName, requestId, "HOST_WIDGETS", `to ${op} widgets`);
+    }
+    declaredWidget(app, widgetId) {
+        return (app.widgets ?? []).find((widget) => widget.id === widgetId);
+    }
+    /** The target app and its declared widget, or a reply to the host saying why not. */
+    widgetTarget(hostPackageName, payload, requestId) {
+        const target = payload.packageName;
+        const widgetId = payload.widgetId;
+        const app = target ? this.interopApps().find((a) => a.packageName === target) : undefined;
+        if (!target || !app) {
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.APP_NOT_FOUND,
+                message: `Miniapp not found: ${target ?? "(missing packageName)"}`,
+            });
+            return null;
+        }
+        if (!widgetId || !this.declaredWidget(app, widgetId)) {
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.WIDGET_NOT_FOUND,
+                message: `${target} does not declare widget "${widgetId ?? "(missing widgetId)"}"`,
+            });
+            return null;
+        }
+        return { app, widgetId };
+    }
+    handleWidgetsList(hostPackageName, requestId) {
+        if (!this.requireWidgetHost(hostPackageName, requestId, "list"))
+            return;
+        const rows = [];
+        for (const app of this.interopApps()) {
+            if (!app.packageName || app.packageName === hostPackageName || app.packageName.includes("@empty"))
+                continue;
+            for (const widget of app.widgets ?? []) {
+                rows.push({
+                    packageName: app.packageName,
+                    appName: app.name,
+                    id: widget.id,
+                    name: widget.name,
+                    sizes: widget.sizes,
+                    defaultSize: widget.defaultSize,
+                    running: app.running,
+                    compatible: app.compatibility?.isCompatible !== false,
+                });
+            }
+        }
+        this.sendResult(hostPackageName, requestId, true, rows);
+    }
+    parseWidgetBox(raw) {
+        const box = raw;
+        if (!box || typeof box !== "object")
+            return null;
+        if (box.size !== "XS" && box.size !== "SM" && box.size !== "MD" && box.size !== "LG")
+            return null;
+        const width = Number(box.width);
+        const height = Number(box.height);
+        if (!(width > 0) || !(height > 0))
+            return null;
+        return { size: box.size, width: Math.round(width), height: Math.round(height) };
+    }
+    sendWidgetCall(providerPackageName, widgetId, call) {
+        const callId = `wdg-${Date.now().toString(36)}-${this.widgetCallSeq++}`;
+        this.sendToMiniapp(providerPackageName, {
+            type: MiniappResponseType.WIDGET_CALL,
+            callId,
+            widgetId,
+            kind: call.kind,
+            ...(call.kind === "box" ? { box: call.box } : { event: call.event }),
+        });
+        return callId;
+    }
+    /**
+     * session.widgets.place: record the host's box, wake the provider in widget
+     * mode when it is not running, hand it the box, and answer with the last
+     * frame the provider pushed for the widget.
+     */
+    async handleWidgetPlace(hostPackageName, payload, requestId) {
+        if (!this.requireWidgetHost(hostPackageName, requestId, "place"))
+            return;
+        const target = this.widgetTarget(hostPackageName, payload, requestId);
+        if (!target)
+            return;
+        const { app, widgetId } = target;
+        const box = this.parseWidgetBox(payload.box);
+        if (!box) {
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INVALID_ARGUMENT,
+                message: "place needs a box {size, width, height}",
+            });
+            return;
+        }
+        if (app.compatibility && app.compatibility.isCompatible === false) {
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.APP_NOT_COMPATIBLE,
+                message: `${app.packageName} is not compatible with the connected glasses`,
+            });
+            return;
+        }
+        const provider = app.packageName;
+        // Record the placement before the wake so the spawn lands in widget mode
+        // and an unplace racing it cannot stop the provider early.
+        this.widgetPlacements = placeWidget(this.widgetPlacements, { hostPackageName, providerPackageName: provider, widgetId, box });
+        miniappWidgetMode.setPlaced(provider, true);
+        if (!miniappRunningRegistry.has(provider))
+            miniappWidgetMode.setWidgetOnly(provider, true);
+        try {
+            await this.wakeInteropApp(provider);
+        }
+        catch (e) {
+            this.widgetPlacements = unplaceWidget(this.widgetPlacements, hostPackageName, provider, widgetId);
+            void this.settleWidgetProvider(provider);
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.WAKE_FAILED,
+                message: e?.message ?? `failed to wake ${provider}`,
+            });
+            return;
+        }
+        // The host may have unplaced it during the wake.
+        if (placementOf(this.widgetPlacements, hostPackageName, provider, widgetId) && this.connectedApps.has(provider)) {
+            this.sendWidgetCall(provider, widgetId, { kind: "box", box });
+        }
+        this.sendResult(hostPackageName, requestId, true, { frame: widgetFrameOf(this.widgetPlacements, provider, widgetId) });
+    }
+    async handleWidgetUnplace(hostPackageName, payload, requestId) {
+        if (!this.requireWidgetHost(hostPackageName, requestId, "unplace"))
+            return;
+        const target = this.widgetTarget(hostPackageName, payload, requestId);
+        if (!target)
+            return;
+        const provider = target.app.packageName;
+        const had = placementOf(this.widgetPlacements, hostPackageName, provider, target.widgetId);
+        this.widgetPlacements = unplaceWidget(this.widgetPlacements, hostPackageName, provider, target.widgetId);
+        this.sendResult(hostPackageName, requestId, true);
+        if (!had)
+            return;
+        if (this.connectedApps.has(provider) && widgetHostsOf(this.widgetPlacements, provider, target.widgetId).length === 0) {
+            this.sendWidgetCall(provider, target.widgetId, { kind: "box", box: null });
+        }
+        await this.settleWidgetProvider(provider);
+    }
+    /** A provider with nothing placed and no wearer-opened run of its own stops. */
+    async settleWidgetProvider(providerPackageName) {
+        if (isProviderPlaced(this.widgetPlacements, providerPackageName))
+            return;
+        miniappWidgetMode.setPlaced(providerPackageName, false);
+        if (!miniappWidgetMode.isWidgetOnly(providerPackageName))
+            return;
+        // Widget mode stays set until the context is gone, so the tray never
+        // sees the stopping app as a normal one.
+        try {
+            await this.stopInteropApp(providerPackageName);
+        }
+        catch (err) {
+            console.warn(`${LOG_TAG}: stopping widget provider ${providerPackageName} failed`, err);
+        }
+    }
+    /** session.widgets.send: forward input to a placed widget and relay the provider's answer. */
+    async handleWidgetSend(hostPackageName, payload, requestId) {
+        if (!this.requireWidgetHost(hostPackageName, requestId, "send"))
+            return;
+        const target = this.widgetTarget(hostPackageName, payload, requestId);
+        if (!target)
+            return;
+        const provider = target.app.packageName;
+        const event = payload.event;
+        if (!event || typeof event !== "object" || typeof event.type !== "string") {
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.INVALID_ARGUMENT,
+                message: "send needs an event with a string type",
+            });
+            return;
+        }
+        if (!placementOf(this.widgetPlacements, hostPackageName, provider, target.widgetId)) {
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.WIDGET_NOT_PLACED,
+                message: `${hostPackageName} has not placed ${provider}/${target.widgetId}`,
+            });
+            return;
+        }
+        // Floored at 6 s for the same reason as actions: a provider just woken
+        // buffers the call for 5 s while it registers.
+        const timeoutMs = Math.min(Math.max(Number(payload.timeoutMs) || 5_000, 6_000), 30_000);
+        try {
+            await this.wakeInteropApp(provider);
+        }
+        catch (e) {
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.WAKE_FAILED,
+                message: e?.message ?? `failed to wake ${provider}`,
+            });
+            return;
+        }
+        if (!this.connectedApps.has(provider)) {
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.WAKE_FAILED,
+                message: `${provider} disconnected before the event could be delivered`,
+            });
+            return;
+        }
+        const callId = this.sendWidgetCall(provider, target.widgetId, { kind: "event", event });
+        const timer = BgTimer.setTimeout(() => {
+            this.widgetCalls.delete(callId);
+            this.sendResult(hostPackageName, requestId, false, undefined, {
+                code: MiniappErrorCode.ACTION_TIMEOUT,
+                message: `widget event "${event.type}" timed out after ${timeoutMs}ms`,
+            });
+        }, timeoutMs);
+        this.widgetCalls.set(callId, { hostPackageName, providerPackageName: provider, hostRequestId: requestId, timer });
+    }
+    /** Provider → host: a WIDGET_RESULT for a pending send; box acknowledgements have no pending call and are dropped. */
+    handleWidgetResult(providerPackageName, payload) {
+        const callId = payload.callId;
+        if (!callId)
+            return;
+        const pending = this.widgetCalls.get(callId);
+        if (!pending || pending.providerPackageName !== providerPackageName)
+            return;
+        this.widgetCalls.delete(callId);
+        BgTimer.clearTimeout(pending.timer);
+        if (payload.ok === true) {
+            const result = payload.result;
+            if (this.actionPayloadTooLarge(result)) {
+                this.sendResult(pending.hostPackageName, pending.hostRequestId, false, undefined, {
+                    code: MiniappErrorCode.PAYLOAD_TOO_LARGE,
+                    message: "widget event result exceeded the 256 KB cap",
+                });
+                return;
+            }
+            this.sendResult(pending.hostPackageName, pending.hostRequestId, true, result ?? null);
+        }
+        else {
+            const error = payload.error ?? {
+                code: MiniappErrorCode.INTERNAL,
+                message: "widget event handler error",
+            };
+            this.sendResult(pending.hostPackageName, pending.hostRequestId, false, undefined, error);
+        }
+    }
+    /** Provider → host, one-shot: cache the frame and push it to every host holding the widget. */
+    handleWidgetUpdate(providerPackageName, payload) {
+        const widgetId = payload.widgetId;
+        const elements = payload.elements;
+        if (!widgetId || !Array.isArray(elements))
+            return;
+        const app = this.interopApps().find((a) => a.packageName === providerPackageName);
+        if (!app || !this.declaredWidget(app, widgetId))
+            return;
+        if (elements.length > LocalMiniappRuntime.WIDGET_FRAME_ELEMENT_CAP || this.actionPayloadTooLarge(elements)) {
+            console.warn(`${LOG_TAG}: dropping oversized widget frame from ${providerPackageName}/${widgetId}`);
+            return;
+        }
+        this.widgetPlacements = setWidgetFrame(this.widgetPlacements, providerPackageName, widgetId, elements);
+        for (const host of widgetHostsOf(this.widgetPlacements, providerPackageName, widgetId)) {
+            this.sendToMiniapp(host, { type: MiniappResponseType.WIDGET_FRAME, packageName: providerPackageName, widgetId, elements });
+        }
+    }
+    /** A miniapp disconnected: as a host its placements go, as a provider its boxes are forgotten and its frames kept. */
+    onWidgetPartyGone(packageName) {
+        const providersBefore = placedProviders(this.widgetPlacements);
+        this.widgetPlacements = dropWidgetHost(this.widgetPlacements, packageName);
+        this.widgetPlacements = dropWidgetProvider(this.widgetPlacements, packageName);
+        miniappWidgetMode.setPlaced(packageName, false);
+        miniappWidgetMode.setWidgetOnly(packageName, false);
+        for (const [callId, pending] of Array.from(this.widgetCalls)) {
+            if (pending.hostPackageName !== packageName && pending.providerPackageName !== packageName)
+                continue;
+            this.widgetCalls.delete(callId);
+            BgTimer.clearTimeout(pending.timer);
+            if (pending.providerPackageName === packageName) {
+                this.sendResult(pending.hostPackageName, pending.hostRequestId, false, undefined, {
+                    code: MiniappErrorCode.WAKE_FAILED,
+                    message: `${packageName} stopped before answering`,
+                });
+            }
+        }
+        for (const provider of providersBefore) {
+            if (provider !== packageName)
+                void this.settleWidgetProvider(provider);
+        }
+    }
     /** True iff `value` serializes larger than the action payload cap. */
     actionPayloadTooLarge(value) {
         try {