@glassly/miniapp 0.3.5 → 0.3.6-dev.848

package/src/modules/widgets.ts

@@ -6,9 +6,14 @@
  *     The host hands it a box; the provider pushes a frame for that box with
  *     `update()` whenever its state changes and takes the wearer's input
  *     through `onEvent` while the widget is active: a tap on the selected
- *     card activates it, a double tap hands input back. A provider runs in
- *     widget mode while a host has its widget placed: no card in the app
- *     switcher, no frame of its own on the glasses, no touch input of its own.
+ *     card activates it, a double tap hands input back. A widget that lists
+ *     the `EX` size is expanded by that tap instead while the wearer leaves
+ *     expansion on (the miniapp's settings page, or `setExpandable`): the
+ *     host gives it the full screen, the provider draws it with
+ *     `update(elements, {view: "expanded"})`, and a double tap collapses it
+ *     back to the card. A provider runs in widget mode while a host has its
+ *     widget placed: no card in the app switcher, no frame of its own on the
+ *     glasses, no touch input of its own.
  *   - Host (HOST_WIDGETS): `list()` the declared widgets, `place()` one in a
  *     box, hear its frames through `onFrame()`, forward input with `send()`
  *     and `unplace()` it. A provider with nothing placed stops.
@@ -21,7 +26,10 @@ import type {RenderElement} from "./display"
 import {MiniappErrorCode, MiniappRequestType} from "../protocol"
 import {MiniappSession} from "../session"
 
-export type WidgetSize = "XS" | "SM" | "MD" | "LG"
+export type WidgetSize = "XS" | "XSM" | "SM" | "MD" | "LG"
+
+/** Which surface a frame draws: the card in its box, or the full-screen expanded view. */
+export type WidgetView = "card" | "expanded"
 
 /** The box a widget draws into: its size name and its pixel extent. Frames use box-local coordinates. */
 export interface WidgetBox {
@@ -30,16 +38,35 @@ export interface WidgetBox {
   height: number
 }
 
+/** The full-screen box an expanded widget draws into, in its own local coordinates. */
+export interface WidgetExpandedBox {
+  width: number
+  height: number
+}
+
 /** The wearer's input, forwarded by the host while the widget is active. */
 export type WidgetEvent =
   /** The wearer tapped the selected widget: it owns every swipe and tap until it is deactivated. */
   | {type: "activate"}
   /** The wearer double-tapped out, or the dashboard closed: show no selection. */
   | {type: "deactivate"}
-  /** A swipe while active. */
-  | {type: "swipe"; direction: "left" | "right" | "up" | "down"}
-  /** A tap while active. */
+  /**
+   * The wearer tapped the selected widget and the host gave it the full
+   * screen: draw the expanded view for this box with `update(elements,
+   * {view: "expanded"})`. Like activate, it owns every swipe and tap until
+   * collapsed. Only sent to widgets that list `EX` with expansion on.
+   */
+  | {type: "expand"; width: number; height: number}
+  /** The wearer double-tapped back to the card, or the dashboard closed: back to the card, show no selection. */
+  | {type: "collapse"}
+  /** A swipe while active or expanded. `input2d` is set when it came from a 2D controller such as a Neural Band. */
+  | {type: "swipe"; direction: "left" | "right" | "up" | "down"; input2d?: boolean}
+  /** A tap while active or expanded. */
   | {type: "tap"}
+  /** The wearer pressed and held while active or expanded. */
+  | {type: "hold"}
+  /** The held press ended. Some controllers report a hold without a release. */
+  | {type: "release"}
   /** The host is about to show the widget: refresh what it draws, then return. */
   | {type: "beforeShow"}
 
@@ -57,10 +84,23 @@ export interface WidgetHandle {
   readonly id: string
   /** The box the host assigned, or null while unplaced. */
   readonly box: WidgetBox | null
-  /** Push the frame for the current box. Coalesced by the host; drawn while the dashboard shows. */
-  update(elements: RenderElement[]): void
+  /** The full-screen box while the host has the widget expanded, else null. */
+  readonly expanded: WidgetExpandedBox | null
+  /**
+   * Push the frame for the current box, or with `{view: "expanded"}` for the
+   * expanded box. Coalesced by the host; drawn while the dashboard shows.
+   */
+  update(elements: RenderElement[], opts?: {view?: WidgetView}): void
   /** Stop serving the widget. Calls still arrive until the host unplaces it. */
   release(): void
+  /** Whether a tap expands the widget; false when it does not list `EX`. */
+  getExpandable(): Promise<boolean>
+  /**
+   * Turn tap-to-expand on or off, the same choice the wearer makes on the
+   * miniapp's settings page; resolves with the setting now in force. Rejects
+   * for a widget that does not list `EX`.
+   */
+  setExpandable(expandable: boolean): Promise<boolean>
 }
 
 /** One declared widget, as a host lists it. */
@@ -71,6 +111,8 @@ export interface WidgetInfo {
   name: string
   sizes: WidgetSize[]
   defaultSize: WidgetSize
+  /** A tap on the selected widget expands it to the full screen instead of activating the card. */
+  expandable: boolean
   /** The provider's background context is up (in widget mode or opened by the wearer). */
   running: boolean
   /** The provider can run on the connected glasses. */
@@ -81,6 +123,7 @@ export interface WidgetFrame {
   packageName: string
   widgetId: string
   elements: RenderElement[]
+  view: WidgetView
 }
 
 export interface SendOptions {
@@ -106,6 +149,7 @@ const widgetKey = (packageName: string, widgetId: string): string => `${packageN
 
 class Handle implements WidgetHandle {
   box: WidgetBox | null = null
+  expanded: WidgetExpandedBox | null = null
 
   constructor(
     readonly id: string,
@@ -113,13 +157,21 @@ class Handle implements WidgetHandle {
     private readonly module: WidgetsModule,
   ) {}
 
-  update(elements: RenderElement[]): void {
-    this.module._update(this.id, elements)
+  update(elements: RenderElement[], opts?: {view?: WidgetView}): void {
+    this.module._update(this.id, elements, opts?.view ?? "card")
   }
 
   release(): void {
     this.module._release(this.id, this)
   }
+
+  getExpandable(): Promise<boolean> {
+    return this.module._expandable(this.id)
+  }
+
+  setExpandable(expandable: boolean): Promise<boolean> {
+    return this.module._expandable(this.id, expandable)
+  }
 }
 
 export class WidgetsModule {
@@ -154,8 +206,23 @@ export class WidgetsModule {
   }
 
   /** @internal */
-  _update(widgetId: string, elements: RenderElement[]): void {
-    this.session.sendOneShot({type: MiniappRequestType.WIDGET_UPDATE, widgetId, elements})
+  _update(widgetId: string, elements: RenderElement[], view: WidgetView): void {
+    this.session.sendOneShot({
+      type: MiniappRequestType.WIDGET_UPDATE,
+      widgetId,
+      elements,
+      ...(view === "expanded" ? {view} : {}),
+    })
+  }
+
+  /** @internal */
+  async _expandable(widgetId: string, expandable?: boolean): Promise<boolean> {
+    const result = await this.session.sendRequest<{expandable?: boolean}>({
+      type: MiniappRequestType.WIDGET_EXPANDABLE,
+      widgetId,
+      ...(expandable === undefined ? {} : {expandable}),
+    })
+    return result?.expandable === true
   }
 
   /** @internal */
@@ -200,10 +267,13 @@ export class WidgetsModule {
     try {
       if (kind === "box") {
         handle.box = box
+        if (!box) handle.expanded = null
         handle.hooks.onBox?.(box)
         this.reply(callId, true, null)
         return
       }
+      if (event?.type === "expand") handle.expanded = {width: event.width, height: event.height}
+      else if (event?.type === "collapse") handle.expanded = null
       const result = event && handle.hooks.onEvent ? await handle.hooks.onEvent(event) : undefined
       this.reply(callId, true, result ?? null)
     } catch (err) {
@@ -237,16 +307,23 @@ export class WidgetsModule {
   /**
    * Place a widget in a box. Starts the provider in widget mode when it is
    * not running, hands it the box, and resolves with the provider's last
-   * frame for the widget, or null when it has not drawn yet. Placing again
-   * with a new box resizes.
+   * card frame for the widget, or null when it has not drawn yet. A cached
+   * expanded frame is delivered to the `onFrame` listeners (with `view:
+   * "expanded"`) before it resolves. Placing again with a new box resizes.
    */
   async place(packageName: string, widgetId: string, box: WidgetBox): Promise<RenderElement[] | null> {
-    const result = await this.session.sendRequest<{frame: RenderElement[] | null}>({
+    const result = await this.session.sendRequest<{
+      frame: RenderElement[] | null
+      expandedFrame?: RenderElement[] | null
+    }>({
       type: MiniappRequestType.WIDGET_PLACE,
       packageName,
       widgetId,
       box,
     })
+    if (Array.isArray(result?.expandedFrame)) {
+      this._deliverFrame({packageName, widgetId, elements: result.expandedFrame, view: "expanded"})
+    }
     return result?.frame ?? null
   }
 

package/src/protocol.ts

@@ -183,6 +183,8 @@ export enum MiniappRequestType {
   MEMORY_QUERY = "miniapp_memory_query",
   MEMORY_WINDOW = "miniapp_memory_window",
   MEMORY_EXPORT_TEXT = "miniapp_memory_export_text",
+  MEMORY_EXPORT_FILE = "miniapp_memory_export_file",
+  MEMORY_IMPORT_FILE = "miniapp_memory_import_file",
   MEMORY_SUMMARY_ADD = "miniapp_memory_summary_add",
   MEMORY_SUMMARY_LIST = "miniapp_memory_summary_list",
   MEMORY_PENDING_SUMMARY_HOUR = "miniapp_memory_pending_summary_hour",
@@ -321,18 +323,20 @@ export enum MiniappRequestType {
   // A provider declares widgets in its manifest and serves them through
   // session.widgets.provide; a host (HOST_WIDGETS) places them and forwards
   // the wearer's input. The host routes every call; neither side names the other.
-  /** Provider → host, one-shot: the latest frame for one of its widgets. */
+  /** Provider → host, one-shot: the latest frame for one of its widgets; `view: "expanded"` for the expanded view. */
   WIDGET_UPDATE = "miniapp_widget_update",
   /** Provider → host: the result of a delivered WIDGET_CALL, correlated by callId. */
   WIDGET_RESULT = "miniapp_widget_result",
   /** Every widget the installed miniapps declare. HOST_WIDGETS. */
   WIDGETS_LIST = "miniapp_widgets_list",
-  /** Place a widget in a box: starts the provider in widget mode and hands it the box. HOST_WIDGETS. */
+  /** Place a widget in a box: starts the provider in widget mode and hands it the box. Answers {frame, expandedFrame}. HOST_WIDGETS. */
   WIDGET_PLACE = "miniapp_widget_place",
   /** Take a widget off: the provider stops once nothing of it is placed. HOST_WIDGETS. */
   WIDGET_UNPLACE = "miniapp_widget_unplace",
   /** Forward an input event to a placed widget and wait for its answer. HOST_WIDGETS. */
   WIDGET_SEND = "miniapp_widget_send",
+  /** Provider: read, or set with `expandable`, whether a tap expands one of its `EX` widgets. Answers {expandable}. */
+  WIDGET_EXPANDABLE = "miniapp_widget_expandable",
 }
 
 // ============================================================================
@@ -410,7 +414,7 @@ export enum MiniappResponseType {
    * expects a WIDGET_RESULT keyed by callId.
    */
   WIDGET_CALL = "miniapp_widget_call",
-  /** Host → widget host: a provider pushed a new frame for a widget this app placed. */
+  /** Host → widget host: a provider pushed a new frame for a widget this app placed; `view: "expanded"` for the expanded view. */
   WIDGET_FRAME = "miniapp_widget_frame",
 
   /**

package/src/session.ts

@@ -338,7 +338,7 @@ export class MiniappSession<TChannels extends object = any> {
   /**
    * User-supplied provider API keys (Settings > API Keys). Requires the
    * API_KEYS manifest permission; only an allowlisted provider set is
-   * readable (anthropic / gemini / elevenlabs / mapbox — never soniox).
+   * readable (anthropic / gemini / openai / deepseek / elevenlabs / mapbox — never soniox).
    */
   /**
    * Platform LLM completions. Requires the AI manifest permission. The
@@ -957,7 +957,12 @@ export class MiniappSession<TChannels extends object = any> {
         const packageName = payload.packageName as string | undefined
         const widgetId = payload.widgetId as string | undefined
         if (!packageName || !widgetId || !Array.isArray(payload.elements)) return
-        this.widgets._deliverFrame({packageName, widgetId, elements: payload.elements} as WidgetFrame)
+        this.widgets._deliverFrame({
+          packageName,
+          widgetId,
+          elements: payload.elements,
+          view: payload.view === "expanded" ? "expanded" : "card",
+        } as WidgetFrame)
         return
       }