@glassly/engine 0.3.5-beta.710 → 0.3.5-beta.760

package/src/services/LocalMiniappRuntime.ts

@@ -162,6 +162,13 @@ import {invokeScanQrSeam} from "../runtime/scanQrSeam"
 import {invokeWebLoginSeam} from "../runtime/webLoginSeam"
 import {normalizeStreamAudioConfig, normalizeStreamVideoConfig} from "../runtime/streamConfig"
 import {visibleActionRows} from "./manifestActions"
+import {
+  actionFailure,
+  appDeclaresAction,
+  checkActionAccess,
+  PendingActionCalls,
+  type ActionOutcome,
+} from "./actionInvoke"
 import {toLanguageHint} from "@glassly/cloud-protocol/languages"
 import {buildMiniappManifestSnapshot, type MiniappRuntimeDiagnosticSnapshot} from "../utils/miniappDiagnostics"
 import ttsModelManager from "./TTSModelManager"
@@ -641,6 +648,10 @@ class LocalMiniappRuntime {
   private connectedApps: Map<string, ConnectedMiniapp> = new Map()
   /** Claimed gestures (CLAIM_GESTURES): a stack per gesture, the most recent claimer holding it. */
   private gestureClaims: GestureClaimState = emptyGestureClaims()
+  // The last main-view frame each app asked to render. Widget mode refuses
+  // frames and demotion clears them, and an app that has drawn once may not
+  // draw again on its own, so promotion replays this.
+  private retainedRenders = new Map<string, Record<string, unknown>>()
 
   /**
    * Packages that have completed their CONNECT handshake (sent
@@ -705,7 +716,13 @@ class LocalMiniappRuntime {
   private localSecret = `miniapp_${Date.now()}_${Math.random().toString(36).slice(2, 14)}`
   private usedTokens = new Set<string>()
 
-  private constructor() {}
+  private constructor() {
+    miniappWidgetMode.subscribe((packageName, widgetOnly) => {
+      // Promotion happens inside the apps store's start(); the core-app slot
+      // settles with that store write, so replay once it has.
+      if (!widgetOnly) queueMicrotask(() => this.replayRetainedRender(packageName))
+    })
+  }
 
   /** Snapshot of miniapps actively subscribed to hardware button events. */
   public getButtonPressSubscribers(): string[] {
@@ -1122,7 +1139,11 @@ class LocalMiniappRuntime {
     // window ends early once this app pushes its first display (see
     // LocalDisplayManager.request), or after ~1.5s. Fires once per spawn —
     // including a crash-respawn, since each spawn is a fresh "app is starting".
-    localDisplayManager.onMount(packageName, installedManifest?.name ?? packageName)
+    // A spawn for a dashboard widget is not the wearer starting the app: it draws
+    // nothing of its own, so it shows no boot text either.
+    if (!miniappWidgetMode.isWidgetOnly(packageName)) {
+      localDisplayManager.onMount(packageName, installedManifest?.name ?? packageName)
+    }
   }
 
   /**
@@ -1244,6 +1265,7 @@ class LocalMiniappRuntime {
     }
     // Its gesture claims go back to whoever claimed them before.
     this.applyGestureClaimChanges(dropGestureClaims(this.gestureClaims, packageName))
+    this.retainedRenders.delete(packageName)
 
     // Warm-up is a request-owned camera lease. Cancel it even if the app record was already
     // removed so a close racing the camera-open promise cannot leave the sensor running.
@@ -2489,11 +2511,6 @@ 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,
@@ -2501,6 +2518,15 @@ class LocalMiniappRuntime {
         })
         return
       }
+      if (payload.view !== "dashboard") {
+        if (payload.elements.length === 0) this.retainedRenders.delete(packageName)
+        else this.retainedRenders.set(packageName, payload)
+      }
+      // A widget-only app draws through its widget alone; the frame waits for promotion.
+      if (miniappWidgetMode.isWidgetOnly(packageName)) {
+        this.sendResult(packageName, requestId, true, {status: "blocked", reason: "widget mode"})
+        return
+      }
       // The dashboard view is the overlay app's alone; anyone else's frame
       // is dropped, reported rather than silently lost.
       if (payload.view === "dashboard" && !isOverlayApp(packageName)) {
@@ -2530,6 +2556,13 @@ class LocalMiniappRuntime {
     }
   }
 
+  /** Put a promoted app's last main-view frame on the glasses; widget mode had refused it. */
+  private replayRetainedRender(packageName: string): void {
+    const payload = this.retainedRenders.get(packageName)
+    if (!payload || !this.connectedApps.has(packageName) || miniappWidgetMode.isWidgetOnly(packageName)) return
+    this.handleRender(packageName, payload)
+  }
+
   /**
    * display.showView: the active dashboard takes or releases the overlay
    * slot. Refused (NOT_PERMITTED) for an app that is not a dashboard;
@@ -5995,10 +6028,7 @@ class LocalMiniappRuntime {
   private static readonly ACTION_PAYLOAD_CAP = 256 * 1024
 
   /** Outstanding action invocations, keyed by host-generated callId. */
-  private actionCalls = new Map<
-    string,
-    {callerPackageName: string; targetPackageName: string; callerRequestId?: string; timer: number}
-  >()
+  private actionCalls = new PendingActionCalls(BgTimer, (value) => this.actionPayloadTooLarge(value))
   private actionCallSeq = 0
 
   private interopApps(): ClientApp[] {
@@ -6381,10 +6411,12 @@ class LocalMiniappRuntime {
     }
     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.
+    // and an unplace racing it cannot stop the provider early. A provider the
+    // store already runs (a wearer's launch still spawning, say) stays a
+    // normal run; the registry alone lags that launch.
     this.widgetPlacements = placeWidget(this.widgetPlacements, {hostPackageName, providerPackageName: provider, widgetId, box})
     miniappWidgetMode.setPlaced(provider, true)
-    if (!miniappRunningRegistry.has(provider)) miniappWidgetMode.setWidgetOnly(provider, true)
+    if (!app.running && !miniappRunningRegistry.has(provider)) miniappWidgetMode.setWidgetOnly(provider, true)
     try {
       await this.wakeInteropApp(provider)
     } catch (e) {
@@ -6568,111 +6600,118 @@ class LocalMiniappRuntime {
     }
   }
 
+  /** Floored at 6s: a freshly-woken target buffers an undelivered ACTION_CALL for 5s (HANDLER_WAIT_MS in @glassly/miniapp's actions module) + 1s for the reply. Keep in sync. */
+  private static clampActionTimeout(raw: unknown): number {
+    return Math.min(Math.max(Number(raw) || 30_000, 6_000), 120_000)
+  }
+
+  /** Caller identity the host presents for host-initiated actions (a system caller). */
+  private static readonly HOST_ACTION_CALLER = "host"
+
+  /** Installed, compatible, and declares the action — the same gates `invokeActionFromHost` applies up front. */
+  public hostActionAvailable(targetPackageName: string, actionId: string): boolean {
+    return appDeclaresAction(
+      this.interopApps().find((a) => a.packageName === targetPackageName),
+      actionId,
+    )
+  }
+
   /**
-   * session.actions.invoke → wake the target headlessly, deliver an ACTION_CALL,
-   * and correlate its ACTION_RESULT back to the caller's pending request.
+   * Host-initiated action call (e.g. the watch remote): same gates, headless
+   * wake and ACTION_CALL/ACTION_RESULT correlation as a miniapp's
+   * session.actions.invoke, with the host as a system caller.
+   * Rejects with an Error whose `code` is a MiniappErrorCode.
    */
+  public async invokeActionFromHost(
+    targetPackageName: string,
+    actionId: string,
+    params: Record<string, unknown> = {},
+    timeoutMs?: number,
+  ): Promise<unknown> {
+    const outcome = await this.runActionInvoke(
+      LocalMiniappRuntime.HOST_ACTION_CALLER,
+      true,
+      targetPackageName,
+      actionId,
+      params,
+      LocalMiniappRuntime.clampActionTimeout(timeoutMs),
+    )
+    if (outcome.ok) return outcome.data
+    throw Object.assign(new Error(outcome.error.message), {code: outcome.error.code})
+  }
+
+  /** session.actions.invoke → run the call, then relay the outcome to the caller's pending request. */
   private async handleActionInvoke(
     callerPackageName: string,
     payload: Record<string, unknown>,
     requestId?: string,
   ): Promise<void> {
-    const target = payload.targetPackageName as string | undefined
-    const actionId = payload.actionId as string | undefined
-    const params = (payload.params as Record<string, unknown> | undefined) ?? {}
-    // Floor the timeout at 6s so the host never rejects with ACTION_TIMEOUT before
-    // the target SDK's handler-registration window closes. A freshly-woken miniapp
-    // buffers an undelivered ACTION_CALL for HANDLER_WAIT_MS (5s in @glassly/miniapp's
-    // actions module) waiting for session.actions.handle; a shorter host timeout
-    // could fire while the target is still registering, then the action would run
-    // with no caller left to receive its result. 6s = that 5s buffer + 1s for the
-    // ACTION_RESULT/NO_ACTION_HANDLER reply to travel back. Keep these in sync.
-    const timeoutMs = Math.min(Math.max(Number(payload.timeoutMs) || 30_000, 6_000), 120_000)
+    const outcome = await this.runActionInvoke(
+      callerPackageName,
+      this.isSystemPackage(callerPackageName),
+      payload.targetPackageName as string | undefined,
+      payload.actionId as string | undefined,
+      (payload.params as Record<string, unknown> | undefined) ?? {},
+      LocalMiniappRuntime.clampActionTimeout(payload.timeoutMs),
+    )
+    if (outcome.ok) this.sendResult(callerPackageName, requestId, true, outcome.data)
+    else this.sendResult(callerPackageName, requestId, false, undefined, outcome.error)
+  }
+
+  /**
+   * Gate, wake the target headlessly, deliver an ACTION_CALL, and resolve when
+   * its ACTION_RESULT (or the timeout) arrives. Never rejects.
+   */
+  private async runActionInvoke(
+    callerPackageName: string,
+    callerIsSystem: boolean,
+    target: string | undefined,
+    actionId: string | undefined,
+    params: Record<string, unknown>,
+    timeoutMs: number,
+  ): Promise<ActionOutcome> {
+    const fail = actionFailure
 
     if (this.actionPayloadTooLarge(params)) {
-      this.sendResult(callerPackageName, requestId, false, undefined, {
-        code: MiniappErrorCode.PAYLOAD_TOO_LARGE,
-        message: "action params exceeded the 256 KB cap",
-      })
-      return
+      return fail(MiniappErrorCode.PAYLOAD_TOO_LARGE, "action params exceeded the 256 KB cap")
     }
 
     const app = target ? this.interopApps().find((a) => a.packageName === target) : undefined
-    if (!target || !app) {
-      this.sendResult(callerPackageName, requestId, false, undefined, {
-        code: MiniappErrorCode.APP_NOT_FOUND,
-        message: `Miniapp not found: ${target ?? "(missing targetPackageName)"}`,
-      })
-      return
-    }
-    if (!actionId) {
-      this.sendResult(callerPackageName, requestId, false, undefined, {
-        code: MiniappErrorCode.ACTION_NOT_FOUND,
-        message: "invoke requires an actionId",
-      })
-      return
-    }
-    if (app.compatibility && app.compatibility.isCompatible === false) {
-      this.sendResult(callerPackageName, requestId, false, undefined, {
-        code: MiniappErrorCode.APP_NOT_COMPATIBLE,
-        message: `${target} is not compatible with the connected glasses`,
-      })
-      islandNotifications.emit({
-        kind: "version_incompatible",
-        packageName: target,
-        reason: `${target} is not compatible with the connected glasses`,
-        metadata: {missingRequired: app.compatibility.missingRequired ?? [], via: "miniapps.invoke"},
-        timestamp: Date.now(),
-      })
-      return
-    }
-    // Declared-action gate: the target must declare the action in its manifest.
-    const declared = (app.actions ?? []).find((a) => a.id === actionId)
-    if (!declared) {
-      this.sendResult(callerPackageName, requestId, false, undefined, {
-        code: MiniappErrorCode.ACTION_NOT_FOUND,
-        message: `${target} does not declare action "${actionId}"`,
-      })
-      return
-    }
-    // Visibility gate: declared actions are public by default; ones marked
-    // `visibility: "system"` stay restricted to system/dev callers.
-    if (declared.visibility === "system" && !this.isSystemPackage(callerPackageName)) {
-      this.auditInterop({
-        caller: callerPackageName,
-        op: "invoke",
-        target,
-        actionId,
-        ok: false,
-        errorCode: MiniappErrorCode.NOT_PERMITTED,
-      })
-      this.sendResult(callerPackageName, requestId, false, undefined, {
-        code: MiniappErrorCode.NOT_PERMITTED,
-        message: `Action "${actionId}" on ${target} is restricted to system apps`,
-      })
-      return
+    const denied = checkActionAccess(app, target, actionId, callerIsSystem)
+    if (denied) {
+      if (denied.code === MiniappErrorCode.APP_NOT_COMPATIBLE && target && app) {
+        islandNotifications.emit({
+          kind: "version_incompatible",
+          packageName: target,
+          reason: denied.message,
+          metadata: {missingRequired: app.compatibility?.missingRequired ?? [], via: "miniapps.invoke"},
+          timestamp: Date.now(),
+        })
+      } else if (denied.code === MiniappErrorCode.NOT_PERMITTED) {
+        this.auditInterop({
+          caller: callerPackageName,
+          op: "invoke",
+          target,
+          actionId,
+          ok: false,
+          errorCode: MiniappErrorCode.NOT_PERMITTED,
+        })
+      }
+      return {ok: false, error: denied}
     }
+    if (!target || !actionId) return fail(MiniappErrorCode.INTERNAL, "unreachable")
 
     // Headless wake + wait for CONNECT (idempotent / fast if already connected).
     try {
       await this.wakeInteropApp(target)
     } catch (e) {
-      this.sendResult(callerPackageName, requestId, false, undefined, {
-        code: MiniappErrorCode.WAKE_FAILED,
-        message: (e as Error)?.message ?? `failed to wake ${target}`,
-      })
-      return
+      return fail(MiniappErrorCode.WAKE_FAILED, (e as Error)?.message ?? `failed to wake ${target}`)
     }
 
     // The wake waited for CONNECT, but the target could have dropped in the gap
     // before delivery — fail fast rather than arming a timer for a call that
-    // sendToMiniapp would silently drop (the caller would otherwise wait the
-    // full invoke timeout for an ACTION_CALL that was never delivered).
+    // sendToMiniapp would silently drop.
     if (!this.connectedApps.has(target)) {
-      this.sendResult(callerPackageName, requestId, false, undefined, {
-        code: MiniappErrorCode.WAKE_FAILED,
-        message: `${target} disconnected before the action could be delivered`,
-      })
       this.auditInterop({
         caller: callerPackageName,
         op: "invoke",
@@ -6681,19 +6720,12 @@ class LocalMiniappRuntime {
         ok: false,
         errorCode: MiniappErrorCode.WAKE_FAILED,
       })
-      return
+      return fail(MiniappErrorCode.WAKE_FAILED, `${target} disconnected before the action could be delivered`)
     }
 
-    // Deliver the call and arm the handler timeout; ACTION_RESULT resolves it.
+    // Deliver the call and arm the handler timeout; ACTION_RESULT settles it.
     const callId = `act-${Date.now().toString(36)}-${this.actionCallSeq++}`
-    const timer = BgTimer.setTimeout(() => {
-      this.actionCalls.delete(callId)
-      this.sendResult(callerPackageName, requestId, false, undefined, {
-        code: MiniappErrorCode.ACTION_TIMEOUT,
-        message: `action "${actionId}" timed out after ${timeoutMs}ms`,
-      })
-    }, timeoutMs)
-    this.actionCalls.set(callId, {callerPackageName, targetPackageName: target, callerRequestId: requestId, timer})
+    const outcome = this.actionCalls.register(callId, target, actionId, timeoutMs)
     this.sendToMiniapp(target, {
       type: MiniappResponseType.ACTION_CALL,
       callId,
@@ -6702,38 +6734,12 @@ class LocalMiniappRuntime {
       callerPackageName,
     })
     this.auditInterop({caller: callerPackageName, op: "invoke", target, actionId, ok: true})
+    return outcome
   }
 
-  /** Target → host: forward an ACTION_RESULT back to the caller's pending invoke. */
+  /** Target → host: settle the pending invoke for this ACTION_RESULT. */
   private handleActionResult(targetPackageName: string, payload: Record<string, unknown>): void {
-    const callId = payload.callId as string | undefined
-    if (!callId) return
-    const pending = this.actionCalls.get(callId)
-    if (!pending) return
-    // Only the invoked target may resolve this call. callIds are guessable
-    // (timestamp + seq), so a different connected miniapp must not be able to
-    // spoof a result/error for someone else's invoke.
-    if (pending.targetPackageName !== targetPackageName) return
-    this.actionCalls.delete(callId)
-    BgTimer.clearTimeout(pending.timer)
-
-    if (payload.ok === true) {
-      const result = payload.result
-      if (this.actionPayloadTooLarge(result)) {
-        this.sendResult(pending.callerPackageName, pending.callerRequestId, false, undefined, {
-          code: MiniappErrorCode.PAYLOAD_TOO_LARGE,
-          message: "action result exceeded the 256 KB cap",
-        })
-        return
-      }
-      this.sendResult(pending.callerPackageName, pending.callerRequestId, true, result ?? null)
-    } else {
-      const error = (payload.error as ({code: string; message: string} & Record<string, unknown>) | undefined) ?? {
-        code: MiniappErrorCode.INTERNAL,
-        message: "action handler error",
-      }
-      this.sendResult(pending.callerPackageName, pending.callerRequestId, false, undefined, error)
-    }
+    this.actionCalls.handleResult(targetPackageName, payload)
   }
 
   private sendResult(

package/src/services/MiniappExitGesture.ts

@@ -4,6 +4,8 @@ interface ExitGestureApp {
   packageName: string
   name: string
   running: boolean
+  /** Running only for a placed widget: the wearer is not in it, so there is nothing to leave. */
+  widgetOnly?: boolean
 }
 
 interface ExitGestureState {
@@ -15,7 +17,8 @@ interface ExitGestureState {
 
 export interface ExitGestureDependencies {
   getState: () => ExitGestureState
-  getVisiblePackageName: () => string | null
+  /** The miniapp a double tap leaves right now, or null when the tap is the system's. */
+  getTargetPackageName: () => string | null
   beginExitNotice: (packageName: string, text: string) => boolean
   finishExitNotice: (packageName: string) => void
   cancelExitNotice: (packageName: string) => void
@@ -29,16 +32,16 @@ export class MiniappExitGesture {
 
   public constructor(private readonly deps: ExitGestureDependencies) {}
 
-  /** Returns true when the system gesture was consumed by a visible miniapp exit. */
-  public tryExitVisibleMiniapp(): boolean {
+  /** Returns true when the system gesture was consumed by a miniapp exit. */
+  public tryExitMiniapp(): boolean {
     // Swallow repeat taps while the notice is already counting down.
     if (this.pending) return true
 
-    const packageName = this.deps.getVisiblePackageName()
+    const packageName = this.deps.getTargetPackageName()
     if (!packageName) return false
 
     const app = this.deps.getState().apps.find((candidate) => candidate.packageName === packageName)
-    if (!app?.running) return false
+    if (!app?.running || app.widgetOnly) return false
 
     const name = app.name.trim() || packageName
     if (!this.deps.beginExitNotice(packageName, `Exiting ${name}…`)) return false

package/src/services/MiniappWidgetMode.ts

@@ -2,25 +2,27 @@
  * 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.
+ * hears no touch input; the Widgets pill lists it. Foregrounding the app on
+ * the phone promotes it to a normal run (the store's start/setForeground);
+ * 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
+/** Called with the app whose mode changed and whether it is now widget-only. */
+type Listener = (packageName: string, widgetOnly: boolean) => 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 {
+function notify(packageName: string, on: boolean): void {
   for (const fn of listeners) {
     try {
-      fn()
+      fn(packageName, on)
     } catch (e) {
       console.warn("MiniappWidgetMode: listener threw", e)
     }
@@ -32,7 +34,7 @@ export const miniappWidgetMode = {
   setWidgetOnly(packageName: string, on: boolean): void {
     const changed = on ? !widgetOnly.has(packageName) : widgetOnly.delete(packageName)
     if (on) widgetOnly.add(packageName)
-    if (changed) notify()
+    if (changed) notify(packageName, on)
   },
 
   isWidgetOnly(packageName: string): boolean {

package/src/services/SceneRenderer.ts

@@ -66,7 +66,9 @@ const MAX_SETTLE_MS = 255 * 33
 function settleTimeOf(elements: FrameElement[]): number {
   let ms = 0
   for (const el of elements) {
-    if (el.change !== "updated" && el.change !== "moved") continue
+    // Entering and leaving elements tween too, from or to their offset.
+    const edge = el.transition?.exit !== undefined || (el.change === "created" && el.transition?.enter !== undefined)
+    if (el.change !== "updated" && el.change !== "moved" && !edge) continue
     const t = el.transition?.durationMs ?? 0
     // Rotation has its own millisecond clock, beyond the geometry frame limit.
     const duration = Math.min(t, el.rotation !== undefined ? 65535 : MAX_SETTLE_MS)

package/src/services/actionInvoke.ts

@@ -0,0 +1,105 @@
+import {MiniappErrorCode} from "@glassly/miniapp"
+
+import type {ClientApp} from "../types/applet"
+
+export type ActionError = {code: string; message: string} & Record<string, unknown>
+export type ActionOutcome = {ok: true; data: unknown} | {ok: false; error: ActionError}
+
+export const actionFailure = (code: string, message: string): ActionOutcome => ({ok: false, error: {code, message}})
+
+/** Installed, compatible, and declares the action. */
+export function appDeclaresAction(app: ClientApp | undefined, actionId: string): boolean {
+  if (!app) return false
+  if (app.compatibility && app.compatibility.isCompatible === false) return false
+  return (app.actions ?? []).some((a) => a.id === actionId)
+}
+
+/**
+ * Gates shared by miniapp->miniapp invoke and host invoke. Declared actions are
+ * public by default; `visibility: "system"` ones need a system caller.
+ */
+export function checkActionAccess(
+  app: ClientApp | undefined,
+  target: string | undefined,
+  actionId: string | undefined,
+  callerIsSystem: boolean,
+): ActionError | null {
+  if (!target || !app) {
+    return {
+      code: MiniappErrorCode.APP_NOT_FOUND,
+      message: `Miniapp not found: ${target ?? "(missing targetPackageName)"}`,
+    }
+  }
+  if (!actionId) return {code: MiniappErrorCode.ACTION_NOT_FOUND, message: "invoke requires an actionId"}
+  if (app.compatibility && app.compatibility.isCompatible === false) {
+    return {
+      code: MiniappErrorCode.APP_NOT_COMPATIBLE,
+      message: `${target} is not compatible with the connected glasses`,
+    }
+  }
+  const declared = (app.actions ?? []).find((a) => a.id === actionId)
+  if (!declared) {
+    return {code: MiniappErrorCode.ACTION_NOT_FOUND, message: `${target} does not declare action "${actionId}"`}
+  }
+  if (declared.visibility === "system" && !callerIsSystem) {
+    return {
+      code: MiniappErrorCode.NOT_PERMITTED,
+      message: `Action "${actionId}" on ${target} is restricted to system apps`,
+    }
+  }
+  return null
+}
+
+/** BgTimer's shape; passed in so this module stays loadable without the native timer. */
+export interface ActionTimers {
+  setTimeout: (cb: () => void, ms: number) => number
+  clearTimeout: (id: number) => void
+}
+
+/** Outstanding ACTION_CALLs awaiting an ACTION_RESULT, keyed by host-generated callId. */
+export class PendingActionCalls {
+  private readonly calls = new Map<string, {target: string; settle: (o: ActionOutcome) => void; timer: number}>()
+
+  constructor(
+    private readonly timers: ActionTimers,
+    private readonly payloadTooLarge: (value: unknown) => boolean,
+  ) {}
+
+  /** Register a call; resolves with its outcome, or ACTION_TIMEOUT. */
+  register(callId: string, target: string, actionId: string, timeoutMs: number): Promise<ActionOutcome> {
+    return new Promise((resolve) => {
+      const timer = this.timers.setTimeout(() => {
+        this.calls.delete(callId)
+        resolve(actionFailure(MiniappErrorCode.ACTION_TIMEOUT, `action "${actionId}" timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+      this.calls.set(callId, {target, settle: resolve, timer})
+    })
+  }
+
+  /** Settle from a target's ACTION_RESULT payload. Only the invoked target may resolve a call. */
+  handleResult(targetPackageName: string, payload: Record<string, unknown>): void {
+    const callId = payload.callId as string | undefined
+    if (!callId) return
+    const pending = this.calls.get(callId)
+    // callIds are guessable (timestamp + seq): a different miniapp must not spoof someone else's result.
+    if (!pending || pending.target !== targetPackageName) return
+    this.calls.delete(callId)
+    this.timers.clearTimeout(pending.timer)
+
+    if (payload.ok === true) {
+      if (this.payloadTooLarge(payload.result)) {
+        pending.settle(actionFailure(MiniappErrorCode.PAYLOAD_TOO_LARGE, "action result exceeded the 256 KB cap"))
+        return
+      }
+      pending.settle({ok: true, data: payload.result ?? null})
+      return
+    }
+    pending.settle({
+      ok: false,
+      error: (payload.error as ActionError | undefined) ?? {
+        code: MiniappErrorCode.INTERNAL,
+        message: "action handler error",
+      },
+    })
+  }
+}