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

package/src/services/LocalMiniappRuntime.ts

@@ -93,6 +93,23 @@ import {
   type DerivedSettingsKey,
 } 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,
+  type WidgetBox,
+  type WidgetPlacements,
+} from "./widgetPlacements"
 import {
   activeDashboard,
   addDashboardApp,
@@ -149,7 +166,7 @@ import {toLanguageHint} from "@glassly/cloud-protocol/languages"
 import {buildMiniappManifestSnapshot, type MiniappRuntimeDiagnosticSnapshot} from "../utils/miniappDiagnostics"
 import ttsModelManager from "./TTSModelManager"
 import {NavigationHandlers} from "./NavigationHandlers"
-import type {ClientApp} from "../types/applet"
+import type {ClientApp, DeclaredWidget} from "../types/applet"
 import {useAppStatusStore} from "../stores/apps"
 import {isSystemMiniapp} from "../stores/appVisibility"
 import {getDevAppAttestation, getDevAppSourcePackage} from "./AppRegistry"
@@ -178,6 +195,8 @@ export interface InstalledMiniappManifest {
   permissions?: Array<{type: string; required?: boolean; description?: string}>
   hardwareRequirements?: Array<{type: string; level: string; description?: string}>
   actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown; outputSchema?: unknown}>
+  /** Manifest `widgets`, normalized by the runtime when a host asks. */
+  widgets?: unknown
 }
 
 type SpeakerStateValue = "idle" | "loading" | "playing" | "stopped" | "error"
@@ -382,6 +401,7 @@ const PERMISSION_TYPE_TO_CANONICAL: Record<string, string> = {
   SPEAKERS: "speakers",
   MANAGE_MINIAPPS: "manageMiniapps",
   PLATFORM_SETTINGS: "platformSettings",
+  HOST_WIDGETS: "hostWidgets",
 }
 
 /**
@@ -501,6 +521,7 @@ const ALL_CANONICAL_PERMISSIONS = [
   "displayMirror",
   "manageMiniapps",
   "platformSettings",
+  "hostWidgets",
 ] as const
 
 /**
@@ -1321,6 +1342,9 @@ class LocalMiniappRuntime {
     // 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) {
@@ -1755,6 +1779,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
@@ -2117,7 +2159,9 @@ class LocalMiniappRuntime {
 
   /** The app holding `gesture` (the most recent claimer), or null when it is unclaimed. */
   public gestureClaimant(gesture: string): string | null {
-    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? */
@@ -2401,6 +2445,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,
@@ -2441,6 +2489,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,
@@ -5704,6 +5757,8 @@ 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: TranscriptionDeliveryRoute | undefined
       if (normalizedStream.startsWith("transcription:") && transcriptionSource) {
         const routes = this.appTranscriptionRoutesForEvent(packageName, normalizedStream)
@@ -6198,6 +6253,311 @@ class LocalMiniappRuntime {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // 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.
+  // ---------------------------------------------------------------------------
+
+  private widgetPlacements: WidgetPlacements = emptyWidgetPlacements()
+  /** Outstanding widget event calls, keyed by host-generated callId. */
+  private widgetCalls = new Map<
+    string,
+    {hostPackageName: string; providerPackageName: string; hostRequestId?: string; timer: number}
+  >()
+  private widgetCallSeq = 0
+  /** Elements per widget frame; a card is small, and the link is slow. */
+  private static readonly WIDGET_FRAME_ELEMENT_CAP = 64
+
+  private requireWidgetHost(packageName: string, requestId: string | undefined, op: string): boolean {
+    return this.requirePermission(packageName, requestId, "HOST_WIDGETS", `to ${op} widgets`)
+  }
+
+  private declaredWidget(app: ClientApp, widgetId: string): DeclaredWidget | undefined {
+    return (app.widgets ?? []).find((widget) => widget.id === widgetId)
+  }
+
+  /** The target app and its declared widget, or a reply to the host saying why not. */
+  private widgetTarget(
+    hostPackageName: string,
+    payload: Record<string, unknown>,
+    requestId: string | undefined,
+  ): {app: ClientApp; widgetId: string} | null {
+    const target = payload.packageName as string | undefined
+    const widgetId = payload.widgetId as string | undefined
+    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}
+  }
+
+  private handleWidgetsList(hostPackageName: string, requestId?: string): void {
+    if (!this.requireWidgetHost(hostPackageName, requestId, "list")) return
+    const rows: Record<string, unknown>[] = []
+    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)
+  }
+
+  private parseWidgetBox(raw: unknown): WidgetBox | null {
+    const box = raw as {size?: unknown; width?: unknown; height?: unknown} | null
+    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)}
+  }
+
+  private sendWidgetCall(
+    providerPackageName: string,
+    widgetId: string,
+    call: {kind: "box"; box: WidgetBox | null} | {kind: "event"; event: Record<string, unknown>},
+  ): string {
+    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.
+   */
+  private async handleWidgetPlace(
+    hostPackageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    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 as Error)?.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)})
+  }
+
+  private async handleWidgetUnplace(
+    hostPackageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    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. */
+  private async settleWidgetProvider(providerPackageName: string): Promise<void> {
+    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. */
+  private async handleWidgetSend(
+    hostPackageName: string,
+    payload: Record<string, unknown>,
+    requestId?: string,
+  ): Promise<void> {
+    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 as Record<string, unknown> | undefined
+    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 as Error)?.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. */
+  private handleWidgetResult(providerPackageName: string, payload: Record<string, unknown>): void {
+    const callId = payload.callId as string | undefined
+    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 as ({code: string; message: string} & Record<string, unknown>) | undefined) ?? {
+        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. */
+  private handleWidgetUpdate(providerPackageName: string, payload: Record<string, unknown>): void {
+    const widgetId = payload.widgetId as string | undefined
+    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. */
+  private onWidgetPartyGone(packageName: string): void {
+    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. */
   private actionPayloadTooLarge(value: unknown): boolean {
     try {

package/src/services/MiniappLauncher.ts

@@ -136,6 +136,7 @@ class MiniappLauncher {
         permissions: manifest.permissions as InstalledMiniappManifest["permissions"],
         hardwareRequirements: manifest.hardwareRequirements as InstalledMiniappManifest["hardwareRequirements"],
         actions: manifest.actions as InstalledMiniappManifest["actions"],
+        widgets: manifest.widgets,
       }
 
       let bgSource: string
@@ -175,6 +176,7 @@ class MiniappLauncher {
       permissions?: Array<{type: string; required?: boolean; description?: string}>
       hardwareRequirements?: Array<{type: string; level: string; description?: string}>
       actions?: Array<{id?: unknown; description?: unknown; parameters?: unknown; outputSchema?: unknown}>
+      widgets?: unknown
     } | null
     const declaredPermissions = (manifest?.permissions ?? [])
       .map((p) => p.type)
@@ -191,6 +193,7 @@ class MiniappLauncher {
           permissions: manifest.permissions,
           hardwareRequirements: manifest.hardwareRequirements,
           actions: manifest.actions,
+          widgets: manifest.widgets,
         }
       : undefined
 

package/src/services/MiniappWidgetMode.ts

@@ -0,0 +1,62 @@
+/**
+ * Widget mode: a miniapp whose background context runs only because a host
+ * (the dashboard) placed one of its widgets. It is running, but it has no
+ * card in the app switcher, draws nothing of its own on the glasses and
+ * hears no touch input; the Widgets pill lists it. Opening the app from the
+ * home screen promotes it to a normal run; closing a placed app from the
+ * tray demotes it back here instead of stopping it.
+ *
+ * The runtime is the writer (placements come and go through it); the apps
+ * store projects `widgetOnly` from here beside `running`.
+ */
+
+type Listener = () => void
+
+const widgetOnly = new Set<string>()
+/** Providers with at least one widget placed by some host. */
+const placed = new Set<string>()
+const listeners = new Set<Listener>()
+
+function notify(): void {
+  for (const fn of listeners) {
+    try {
+      fn()
+    } catch (e) {
+      console.warn("MiniappWidgetMode: listener threw", e)
+    }
+  }
+}
+
+export const miniappWidgetMode = {
+  /** Mark (or clear) widget mode. Clearing promotes: the app keeps running as a normal app. */
+  setWidgetOnly(packageName: string, on: boolean): void {
+    const changed = on ? !widgetOnly.has(packageName) : widgetOnly.delete(packageName)
+    if (on) widgetOnly.add(packageName)
+    if (changed) notify()
+  },
+
+  isWidgetOnly(packageName: string): boolean {
+    return widgetOnly.has(packageName)
+  },
+
+  /** Record whether any host has a widget of this provider placed. */
+  setPlaced(packageName: string, on: boolean): void {
+    if (on) placed.add(packageName)
+    else placed.delete(packageName)
+  },
+
+  isPlaced(packageName: string): boolean {
+    return placed.has(packageName)
+  },
+
+  getAll(): string[] {
+    return Array.from(widgetOnly)
+  },
+
+  subscribe(fn: Listener): () => void {
+    listeners.add(fn)
+    return () => {
+      listeners.delete(fn)
+    }
+  },
+}

package/src/services/manifestActions.ts

@@ -1,4 +1,4 @@
-import type {DeclaredAction} from "../types/applet"
+import type {DeclaredAction, DeclaredWidget, DeclaredWidgetSize} from "../types/applet"
 
 /** The subset of ClientApp that action-listing needs (structural, no cycle on applet types). */
 export interface ActionListApp {
@@ -78,3 +78,31 @@ export function normalizeManifestActions(raw: unknown): DeclaredAction[] {
   }
   return out
 }
+
+const WIDGET_SIZES: readonly DeclaredWidgetSize[] = ["XS", "SM", "MD", "LG"]
+const isWidgetSize = (value: unknown): value is DeclaredWidgetSize => (WIDGET_SIZES as readonly unknown[]).includes(value)
+
+/**
+ * Normalize manifest widgets for installed and dev-sideloaded bundles: an
+ * entry without an id, a name or a usable size is dropped, repeats of a
+ * size are folded, and a default size the widget does not offer becomes
+ * its first size.
+ */
+export function normalizeManifestWidgets(raw: unknown): DeclaredWidget[] {
+  if (!Array.isArray(raw)) return []
+  const out: DeclaredWidget[] = []
+  const seen = new Set<string>()
+  for (const w of raw as Array<{id?: unknown; name?: unknown; sizes?: unknown; defaultSize?: unknown}>) {
+    if (!w || typeof w.id !== "string" || !w.id || typeof w.name !== "string" || !w.name || seen.has(w.id)) continue
+    const sizes = Array.isArray(w.sizes) ? Array.from(new Set(w.sizes.filter(isWidgetSize))) : []
+    if (sizes.length === 0) continue
+    seen.add(w.id)
+    out.push({
+      id: w.id,
+      name: w.name,
+      sizes,
+      defaultSize: isWidgetSize(w.defaultSize) && sizes.includes(w.defaultSize) ? w.defaultSize : sizes[0],
+    })
+  }
+  return out
+}

package/src/services/widgetPlacements.ts

@@ -0,0 +1,121 @@
+/**
+ * Who placed which widget where: the pure bookkeeping behind the runtime's
+ * widget routing. A placement is one host's box for one provider widget;
+ * a provider is placed while any host holds one of its widgets. Frames are
+ * kept per widget so a host that places one again gets the last frame
+ * at once.
+ */
+
+export interface WidgetBox {
+  size: "XS" | "SM" | "MD" | "LG"
+  width: number
+  height: number
+}
+
+export interface Placement {
+  hostPackageName: string
+  providerPackageName: string
+  widgetId: string
+  box: WidgetBox
+}
+
+export interface WidgetPlacements {
+  /** Keyed by `${host}|${provider}/${widgetId}`. */
+  placements: ReadonlyMap<string, Placement>
+  /** The latest frame per `${provider}/${widgetId}`. */
+  frames: ReadonlyMap<string, unknown[]>
+}
+
+export const widgetKey = (providerPackageName: string, widgetId: string): string => `${providerPackageName}/${widgetId}`
+const placementKey = (hostPackageName: string, providerPackageName: string, widgetId: string): string =>
+  `${hostPackageName}|${widgetKey(providerPackageName, widgetId)}`
+
+export function emptyWidgetPlacements(): WidgetPlacements {
+  return {placements: new Map(), frames: new Map()}
+}
+
+export function placeWidget(state: WidgetPlacements, placement: Placement): WidgetPlacements {
+  const placements = new Map(state.placements)
+  placements.set(placementKey(placement.hostPackageName, placement.providerPackageName, placement.widgetId), placement)
+  return {...state, placements}
+}
+
+export function unplaceWidget(
+  state: WidgetPlacements,
+  hostPackageName: string,
+  providerPackageName: string,
+  widgetId: string,
+): WidgetPlacements {
+  const key = placementKey(hostPackageName, providerPackageName, widgetId)
+  if (!state.placements.has(key)) return state
+  const placements = new Map(state.placements)
+  placements.delete(key)
+  return {...state, placements}
+}
+
+/** A host went away: drop everything it placed. */
+export function dropHost(state: WidgetPlacements, hostPackageName: string): WidgetPlacements {
+  const placements = new Map(state.placements)
+  for (const [key, placement] of state.placements) {
+    if (placement.hostPackageName === hostPackageName) placements.delete(key)
+  }
+  return placements.size === state.placements.size ? state : {...state, placements}
+}
+
+/** A provider went away: drop its placements, keep its frames for the placeholder. */
+export function dropProvider(state: WidgetPlacements, providerPackageName: string): WidgetPlacements {
+  const placements = new Map(state.placements)
+  for (const [key, placement] of state.placements) {
+    if (placement.providerPackageName === providerPackageName) placements.delete(key)
+  }
+  return placements.size === state.placements.size ? state : {...state, placements}
+}
+
+export function setFrame(state: WidgetPlacements, providerPackageName: string, widgetId: string, elements: unknown[]): WidgetPlacements {
+  const frames = new Map(state.frames)
+  frames.set(widgetKey(providerPackageName, widgetId), elements)
+  return {...state, frames}
+}
+
+export function frameOf(state: WidgetPlacements, providerPackageName: string, widgetId: string): unknown[] | null {
+  return state.frames.get(widgetKey(providerPackageName, widgetId)) ?? null
+}
+
+export function placementOf(
+  state: WidgetPlacements,
+  hostPackageName: string,
+  providerPackageName: string,
+  widgetId: string,
+): Placement | null {
+  return state.placements.get(placementKey(hostPackageName, providerPackageName, widgetId)) ?? null
+}
+
+/** Hosts holding this widget, each once. */
+export function hostsOf(state: WidgetPlacements, providerPackageName: string, widgetId: string): string[] {
+  const hosts = new Set<string>()
+  for (const placement of state.placements.values()) {
+    if (placement.providerPackageName === providerPackageName && placement.widgetId === widgetId) {
+      hosts.add(placement.hostPackageName)
+    }
+  }
+  return Array.from(hosts)
+}
+
+/** Providers with at least one widget placed. */
+export function placedProviders(state: WidgetPlacements): Set<string> {
+  const providers = new Set<string>()
+  for (const placement of state.placements.values()) providers.add(placement.providerPackageName)
+  return providers
+}
+
+export function isProviderPlaced(state: WidgetPlacements, providerPackageName: string): boolean {
+  for (const placement of state.placements.values()) {
+    if (placement.providerPackageName === providerPackageName) return true
+  }
+  return false
+}
+
+/** The placements a host holds on a provider, for re-delivering boxes. */
+export function placementsBy(state: WidgetPlacements, hostPackageName: string): Placement[] {
+  return Array.from(state.placements.values()).filter((placement) => placement.hostPackageName === hostPackageName)
+}