@glassly/miniapp 0.1.0-dev.26

package/dist/modules/ui.d.ts

@@ -0,0 +1,186 @@
+/**
+ * session.ui — bus between a background JSContext miniapp and its
+ * on-demand UI WebView. Supports two interaction patterns:
+ *
+ *   1. **Broadcast** (fire-and-forget, either direction)
+ *      - background → UI: `session.ui.send(channel, payload)`
+ *      - UI → background: `glassly.send(channel, payload)`
+ *      - subscribe:        `session.ui.on(channel, cb)` / `glassly.on(channel, cb)`
+ *
+ *   2. **RPC** (request/response, UI → background only)
+ *      - UI side:          `await glassly.request(channel, payload, options?)`
+ *      - background side:  `session.ui.handle(channel, (payload, ctx?) => result)`
+ *      - single handler per channel; double-register throws synchronously.
+ *      - errors thrown in the handler reject the caller's promise.
+ *      - cancellation via `options.signal` aborts the handler's `ctx.signal`
+ *        and drops the eventual reply.
+ *
+ * Broadcast vs. RPC is declared at the channel level: wrap a channel's
+ * payload type in `Rpc<Req, Res>` in the shared registry to make it RPC.
+ * Wrong-API-for-channel is a compile-time error.
+ *
+ * Buffering:
+ *   - `glassly.send` BUFFERS until `glassly.ready()` acks. The WebView is
+ *     the short-lived side and shouldn't drop user input.
+ *   - `session.ui.send` silently DROPS when no WebView is bound.
+ *     Background is the source of truth; UI state shouldn't accumulate.
+ *   - Per-channel inbound buffering (up to 32 payloads) covers the
+ *     `controller pushed before React attached the listener` race — see
+ *     the WebView shim for details.
+ *
+ * Wire envelopes (internal — not part of the SDK surface):
+ *   - `UI_OPEN` — WebView posted `{type:"ready"}`.
+ *   - `UI_CLOSE` — host tore down the WebView.
+ *   - `UI_MESSAGE` — WebView → background. `requestId` set on RPC calls.
+ *   - `UI_SEND` — background → WebView. `requestId` set on RPC replies.
+ *   - `UI_CANCEL` — either direction. Carries only `requestId`; aborts
+ *     the in-flight handler's signal.
+ */
+import type { MiniappSession } from "../session";
+export type UIChannelHandler<T = unknown> = (payload: T) => void;
+export type UIUnsubscribe = () => void;
+/**
+ * Brand for declaring an RPC channel in the shared Channels registry.
+ *
+ * Wrap a channel's payload type in `Rpc<Req, Res>` to mark it as
+ * request/response. The SDK's `glassly.request` / `session.ui.handle`
+ * accept only `Rpc<...>` channels; `glassly.send` / `session.ui.on`
+ * accept only non-RPC channels. Using the wrong API for the wrong
+ * channel is a compile-time error.
+ *
+ *   export interface Channels {
+ *     "live-transcript": {text: string}                    // broadcast
+ *     "compute-route":   Rpc<RouteOpts, RouteResult>       // RPC
+ *   }
+ */
+declare const __rpc_brand: unique symbol;
+export type Rpc<Req, Res> = {
+    readonly [__rpc_brand]: true;
+    readonly req: Req;
+    readonly res: Res;
+};
+/** True if `T` is an `Rpc<...>` channel entry. */
+export type IsRpc<T> = T extends Rpc<unknown, unknown> ? true : false;
+/** Request payload type of an `Rpc<Req, Res>` entry. */
+export type RpcReq<T> = T extends Rpc<infer Req, unknown> ? Req : never;
+/** Response payload type of an `Rpc<Req, Res>` entry. */
+export type RpcRes<T> = T extends Rpc<unknown, infer Res> ? Res : never;
+/** Options accepted by `glassly.request`. */
+export interface RpcRequestOptions {
+    /** Abort the in-flight call. Sends UI_CANCEL to the handler. */
+    signal?: AbortSignal;
+    /** Reject with `RpcTimeoutError` after this many ms. No default. */
+    timeout?: number;
+}
+/** Context passed as the optional 2nd arg to an `ui.handle` handler. */
+export interface RpcHandlerContext {
+    /** Aborts when the UI side cancels the call (or its timeout fires). */
+    signal: AbortSignal;
+}
+/**
+ * Error thrown by `glassly.request` when the handler threw or returned an
+ * error envelope. Plain `Error` subclass — distinguished by `err.name`.
+ * `err.cause` is `{code?: string}` if the handler attached one.
+ */
+export declare class RpcError extends Error {
+    constructor(message: string, options?: {
+        cause?: {
+            code?: string;
+        };
+    });
+}
+/** Thrown by `glassly.request` when its `{timeout}` elapses. */
+export declare class RpcTimeoutError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Public surface mirrored on `session.ui`. Generic over a `Channels`
+ * type-map so miniapps importing the typed `shared/channels.ts` get
+ * compile-time enforcement on channel names + payload shapes.
+ *
+ * Broadcast vs. RPC channels are distinguished at the type level:
+ *   - Channel value `Rpc<Req, Res>` → only `handle()` accepts it on
+ *     background; only `glassly.request(...)` accepts it on UI.
+ *   - Channel value anything else   → only `send()`/`on()` accept it
+ *     on both sides.
+ *
+ * The default `Record<string, unknown>` mapping lets unannotated usage
+ * compile — the SDK doesn't impose a registry of its own.
+ */
+export interface UIModule<TChannels extends object = Record<string, unknown>> {
+    /** True iff a WebView is currently bound to this miniapp. */
+    isOpen(): boolean;
+    /**
+     * Subscribe to the "WebView mounted + ready()" lifecycle event. If
+     * a WebView is already mounted when subscribe() is called, the
+     * handler fires immediately for the current binding.
+     */
+    onOpen(cb: () => void): UIUnsubscribe;
+    /**
+     * Subscribe to the "WebView unmounted" lifecycle event. Fires once
+     * per close; if no WebView is bound at subscribe time the handler
+     * stays armed for the next mount → close cycle.
+     */
+    onClose(cb: () => void): UIUnsubscribe;
+    /**
+     * Broadcast a typed message to the bound WebView. Silently drops if
+     * no WebView is bound. Compile-error if `C` is an RPC channel.
+     */
+    send<C extends keyof TChannels & string>(channel: IsRpc<TChannels[C]> extends true ? never : C, payload: TChannels[C]): void;
+    /**
+     * Subscribe to broadcast messages from the bound WebView. Returns an
+     * unsubscribe fn. Compile-error if `C` is an RPC channel — use
+     * `handle()` for RPC channels.
+     */
+    on<C extends keyof TChannels & string>(channel: IsRpc<TChannels[C]> extends true ? never : C, cb: UIChannelHandler<TChannels[C]>): UIUnsubscribe;
+    /**
+     * Register the single handler for an RPC channel. The UI side calls
+     * `glassly.request(channel, payload, options?)`; this handler resolves
+     * the call.
+     *
+     * Throws synchronously if a handler is already registered for the
+     * channel. Returns a deregister fn that removes the handler.
+     *
+     * Compile-error if `C` is a broadcast (non-Rpc) channel.
+     */
+    handle<C extends keyof TChannels & string>(channel: IsRpc<TChannels[C]> extends true ? C : never, handler: (payload: RpcReq<TChannels[C]>, ctx?: RpcHandlerContext) => Promise<RpcRes<TChannels[C]>> | RpcRes<TChannels[C]>): UIUnsubscribe;
+}
+export interface RpcErrorEnvelope {
+    message: string;
+    code?: string;
+    stage?: string;
+    transport?: string;
+}
+export declare class UIModuleImpl<TChannels extends object = Record<string, unknown>> implements UIModule<TChannels> {
+    private readonly session;
+    /** True between UI_OPEN and the matching UI_CLOSE. */
+    private bound;
+    /** Monotonic outbound seq number. Reset on bind. */
+    private nextSeq;
+    /** Open-lifecycle handlers — fire on every UI_OPEN. */
+    private readonly openHandlers;
+    private readonly closeHandlers;
+    /** channel → set of subscribers. */
+    private readonly channelHandlers;
+    /** channel → single registered RPC handler. */
+    private readonly rpcHandlers;
+    /** requestId → AbortController for in-flight RPC handler invocations. */
+    private readonly inflightRpc;
+    constructor(session: MiniappSession);
+    isOpen: () => boolean;
+    onOpen: (cb: () => void) => UIUnsubscribe;
+    onClose: (cb: () => void) => UIUnsubscribe;
+    send: <C extends keyof TChannels & string>(channel: C, payload: TChannels[C]) => void;
+    on: <C extends keyof TChannels & string>(channel: C, cb: UIChannelHandler<TChannels[C]>) => UIUnsubscribe;
+    handle: <C extends keyof TChannels & string>(channel: IsRpc<TChannels[C]> extends true ? C : never, handler: (payload: RpcReq<TChannels[C]>, ctx?: RpcHandlerContext) => Promise<RpcRes<TChannels[C]>> | RpcRes<TChannels[C]>) => UIUnsubscribe;
+    /** Fire every registered open handler once. Guarded per-handler. */
+    private fireOpenHandlers;
+    /** @internal — handle UI_OPEN / UI_CLOSE / UI_MESSAGE envelopes from the host. */
+    private handleInbound;
+    /** @internal — invoke a registered RPC handler and send back the reply. */
+    private dispatchRpcCall;
+    /** @internal — send a UI_SEND envelope tagged with a requestId. */
+    private sendRpcReply;
+}
+export {};
+//# sourceMappingURL=ui.d.ts.map

package/dist/modules/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/modules/ui.ts"],"names":[],"mappings":"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"}

package/dist/modules/ui.js

@@ -0,0 +1,289 @@
+/**
+ * Error thrown by `glassly.request` when the handler threw or returned an
+ * error envelope. Plain `Error` subclass — distinguished by `err.name`.
+ * `err.cause` is `{code?: string}` if the handler attached one.
+ */
+export class RpcError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "RpcError";
+        // Assign `cause` directly: the package's tsconfig targets ES2020 lib
+        // where `Error`'s ctor is typed as 1-arity (no `ErrorOptions`).
+        // Modern JS engines still allow setting `cause` as a plain property.
+        if (options?.cause !== undefined) {
+            ;
+            this.cause = options.cause;
+        }
+    }
+}
+/** Thrown by `glassly.request` when its `{timeout}` elapses. */
+export class RpcTimeoutError extends Error {
+    constructor(message = "RPC timed out") {
+        super(message);
+        this.name = "RpcTimeoutError";
+    }
+}
+function rpcErrorFromUnknown(e) {
+    if (e instanceof Error) {
+        // `cause` is ES2022; this package's lib targets ES2020 where Error
+        // has no `cause` field. Read it via a structural cast. Diagnostic fields
+        // (code/stage/transport) may live as own props (PhotoError-style) or on
+        // the cause — own props win.
+        const own = e;
+        const cause = own.cause;
+        return compactEnvelope({
+            message: e.message,
+            code: own.code ?? cause?.code,
+            stage: own.stage,
+            transport: own.transport,
+        });
+    }
+    if (e && typeof e === "object") {
+        // Hosts reject RPCs with plain structured objects ({code, message, stage,
+        // transport}); stringifying them produced the infamous "[object Object]".
+        const o = e;
+        return compactEnvelope({
+            message: typeof o.message === "string" ? o.message : JSON.stringify(e),
+            code: typeof o.code === "string" ? o.code : undefined,
+            stage: typeof o.stage === "string" ? o.stage : undefined,
+            transport: typeof o.transport === "string" ? o.transport : undefined,
+        });
+    }
+    return { message: String(e) };
+}
+function compactEnvelope(env) {
+    const out = { message: env.message };
+    if (env.code)
+        out.code = env.code;
+    if (env.stage)
+        out.stage = env.stage;
+    if (env.transport)
+        out.transport = env.transport;
+    return out;
+}
+export class UIModuleImpl {
+    constructor(session) {
+        this.session = session;
+        /** True between UI_OPEN and the matching UI_CLOSE. */
+        this.bound = false;
+        /** Monotonic outbound seq number. Reset on bind. */
+        this.nextSeq = 1;
+        /** Open-lifecycle handlers — fire on every UI_OPEN. */
+        this.openHandlers = new Set();
+        this.closeHandlers = new Set();
+        /** channel → set of subscribers. */
+        this.channelHandlers = new Map();
+        /** channel → single registered RPC handler. */
+        this.rpcHandlers = new Map();
+        /** requestId → AbortController for in-flight RPC handler invocations. */
+        this.inflightRpc = new Map();
+        // Arrow-property bindings make every public method safe to destructure
+        // (`const {send} = session.ui`) or pass as a bare callback — a plain
+        // method loses `this` and crashes on `this.bound`.
+        this.isOpen = () => {
+            return this.bound;
+        };
+        this.onOpen = (cb) => {
+            this.openHandlers.add(cb);
+            if (this.bound) {
+                // Late subscriber — fire once for the current binding so callers
+                // that wire onOpen *after* the WebView mounted don't miss it.
+                // Gate on session readiness for the same reason handleInbound does:
+                // a late onOpen must still observe populated capabilities, not the
+                // pre-CONNECT_ACK null snapshot. If not yet ready, the "ready"
+                // listener registered in handleInbound's UI_OPEN branch will fan
+                // out to every openHandler (this one included), so we don't wire a
+                // second listener here.
+                if (this.session.ready) {
+                    try {
+                        cb();
+                    }
+                    catch (e) {
+                        console.warn("session.ui.onOpen late-fire threw:", e);
+                    }
+                }
+            }
+            return () => {
+                this.openHandlers.delete(cb);
+            };
+        };
+        this.onClose = (cb) => {
+            this.closeHandlers.add(cb);
+            return () => {
+                this.closeHandlers.delete(cb);
+            };
+        };
+        this.send = (channel, payload) => {
+            if (!this.bound) {
+                // Per spec: drop silently when no WebView is bound. Background
+                // is the source of truth — the WebView re-fetches state on next
+                // open via session.ui.onOpen.
+                return;
+            }
+            const seq = this.nextSeq++;
+            const envelope = { type: "UI_SEND", channel, payload, seq };
+            this.session.sendOneShot(envelope);
+        };
+        this.on = (channel, cb) => {
+            let set = this.channelHandlers.get(channel);
+            if (!set) {
+                set = new Set();
+                this.channelHandlers.set(channel, set);
+            }
+            set.add(cb);
+            return () => {
+                set.delete(cb);
+            };
+        };
+        this.handle = (channel, handler) => {
+            const key = channel;
+            if (this.rpcHandlers.has(key)) {
+                throw new Error(`session.ui.handle: a handler is already registered for "${key}"`);
+            }
+            this.rpcHandlers.set(key, handler);
+            return () => {
+                this.rpcHandlers.delete(key);
+            };
+        };
+        // The session forwards UI_OPEN / UI_CLOSE / UI_MESSAGE envelopes via
+        // its internal stream subscriber surface. The UIModule registers
+        // once via session._subscribe to receive them. The "_ui" stream
+        // name is internal — not exposed in the public stream list — so
+        // the host router knows to route lifecycle frames here without
+        // bumping any existing stream type.
+        this.session._subscribe("_ui", (env) => this.handleInbound(env));
+    }
+    /** Fire every registered open handler once. Guarded per-handler. */
+    fireOpenHandlers() {
+        for (const h of this.openHandlers) {
+            try {
+                h();
+            }
+            catch (e) {
+                console.warn("session.ui.onOpen handler threw", e);
+            }
+        }
+    }
+    /** @internal — handle UI_OPEN / UI_CLOSE / UI_MESSAGE envelopes from the host. */
+    handleInbound(env) {
+        if (env.type === "UI_OPEN") {
+            this.bound = true;
+            this.nextSeq = 1;
+            // onOpen handlers almost always read session.capabilities /
+            // session.ready to hydrate the fresh WebView. The WebView's
+            // `glassly.ready()` (which produces this UI_OPEN) races the
+            // background session's CONNECT_ACK — on a fast bridge UI_OPEN can
+            // arrive first, leaving capabilities null and the UI rendering a
+            // "no glasses" snapshot that never self-corrects. Gate the open
+            // fan-out on session readiness so handlers always observe a
+            // populated session. The WebView is marked bound immediately
+            // (send/isOpen work, inbound stays buffered) — only the open
+            // callbacks wait.
+            if (this.session.ready) {
+                this.fireOpenHandlers();
+            }
+            else {
+                const off = this.session.on("ready", () => {
+                    off();
+                    // If the WebView closed during the connect window, don't fire
+                    // stale open handlers — a later UI_OPEN will re-trigger them.
+                    if (this.bound)
+                        this.fireOpenHandlers();
+                });
+            }
+            return;
+        }
+        if (env.type === "UI_CLOSE") {
+            this.bound = false;
+            for (const h of this.closeHandlers) {
+                try {
+                    h();
+                }
+                catch (e) {
+                    console.warn("session.ui.onClose handler threw", e);
+                }
+            }
+            return;
+        }
+        if (env.type === "UI_MESSAGE") {
+            // RPC call: requestId set → dispatch to handle() handler.
+            if (typeof env.requestId === "string") {
+                this.dispatchRpcCall(env.channel, env.payload, env.requestId);
+                return;
+            }
+            // Broadcast: fan out to on() subscribers.
+            const set = this.channelHandlers.get(env.channel);
+            if (!set || set.size === 0)
+                return;
+            for (const h of set) {
+                try {
+                    h(env.payload);
+                }
+                catch (e) {
+                    console.warn(`session.ui.on(${env.channel}) threw`, e);
+                }
+            }
+            return;
+        }
+        if (env.type === "UI_CANCEL") {
+            const ctrl = this.inflightRpc.get(env.requestId);
+            if (ctrl) {
+                try {
+                    ctrl.abort();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            return;
+        }
+    }
+    /** @internal — invoke a registered RPC handler and send back the reply. */
+    dispatchRpcCall(channel, payload, requestId) {
+        const handler = this.rpcHandlers.get(channel);
+        if (!handler) {
+            // No handler registered. Reply with a structured error so the
+            // UI's request promise rejects with a useful message.
+            this.sendRpcReply(channel, requestId, {
+                ok: false,
+                error: { message: `no handler registered for "${channel}"` },
+            });
+            return;
+        }
+        const ctrl = new AbortController();
+        this.inflightRpc.set(requestId, ctrl);
+        const ctx = { signal: ctrl.signal };
+        const finish = (envelope) => {
+            this.inflightRpc.delete(requestId);
+            // If the controller already aborted (UI cancelled), drop the
+            // reply — the UI side has already removed its listener.
+            if (ctrl.signal.aborted)
+                return;
+            this.sendRpcReply(channel, requestId, envelope);
+        };
+        let result;
+        try {
+            result = handler(payload, ctx);
+        }
+        catch (e) {
+            finish({ ok: false, error: rpcErrorFromUnknown(e) });
+            return;
+        }
+        if (result && typeof result.then === "function") {
+            ;
+            result.then((v) => finish({ ok: true, result: v }), (e) => finish({ ok: false, error: rpcErrorFromUnknown(e) }));
+        }
+        else {
+            finish({ ok: true, result });
+        }
+    }
+    /** @internal — send a UI_SEND envelope tagged with a requestId. */
+    sendRpcReply(channel, requestId, payload) {
+        if (!this.bound)
+            return;
+        const seq = this.nextSeq++;
+        const envelope = { type: "UI_SEND", channel, payload, seq, requestId };
+        this.session.sendOneShot(envelope);
+    }
+}
+//# sourceMappingURL=ui.js.map

package/dist/modules/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../../src/modules/ui.ts"],"names":[],"mappings":"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"}