@mentra/miniapp 0.3.0-beta.0

package/dist/modules/camera.js

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview CameraModule — glasses camera control and photo capture.
+ */
+import { MiniappRequestType } from "../protocol";
+export class CameraModule {
+    constructor(session) {
+        this.session = session;
+    }
+    /** True iff `CAMERA` is declared in the miniapp's manifest. */
+    get hasPermission() {
+        return this.session._hasManifestPermission("CAMERA");
+    }
+    /**
+     * Apply a session-owned camera FOV/ROI override on the glasses.
+     *
+     * Resolves after the ASG client reports that the setting was applied to camera
+     * hardware after the restart cooldown. The host restores the prior override or persistent base
+     * when this miniapp closes. Requires CAMERA permission declared in miniapp.json.
+     */
+    async setFov(request) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.CAMERA_FOV,
+            ...request,
+        });
+    }
+    /**
+     * Take a photo via the glasses camera. Returns a URL to the captured image.
+     * Requires CAMERA permission declared in miniapp.json.
+     *
+     * The photo is uploaded to cloud storage; the returned URL is a short-TTL
+     * (~30 minute) signed download URL. If the glasses don't have a camera,
+     * the phone-side handler rejects with an error. Check
+     * `session.capabilities.hasCamera` before calling.
+    */
+    async takePhoto(options = {}) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.PHOTO,
+            size: options.size ?? "medium",
+            mode: options.mode ?? "photo",
+            compress: options.compress ?? "none",
+            sound: options.sound ?? true,
+            saveToGallery: options.saveToGallery ?? false,
+            exposureTimeNs: options.exposureTimeNs,
+            iso: options.iso,
+            aeExposureDivisor: options.aeExposureDivisor,
+            isoCap: options.isoCap,
+            noiseReduction: options.noiseReduction,
+            edgeEnhancement: options.edgeEnhancement,
+            mfnr: options.mfnr,
+            zsl: options.zsl,
+            ispDigitalGain: options.ispDigitalGain,
+            ispAnalogGain: options.ispAnalogGain,
+        }, options.timeoutMs != null ? { timeoutMs: options.timeoutMs } : undefined);
+    }
+    /**
+     * Pre-warm the glasses camera so the next takePhoto() is near-instant.
+     * The camera stays warm for ~durationMs (default 15s, maximum 60s); call warmUp() again to
+     * extend it. Warm with the same `size` you'll capture with — a mismatched size
+     * forces the camera to reconfigure and loses the speedup. Requires CAMERA
+     * permission in miniapp.json. Resolves once the camera reports ready. The host automatically
+     * releases this miniapp's request-owned lease when the miniapp closes.
+     *
+     * Warm-ups are serialized: only one runs at a time and none may start while a
+     * photo is being captured. If the camera is busy (a capture is in flight, or
+     * another warm-up is still opening) this rejects with `camera_busy` — retry
+     * shortly, or just call takePhoto() (it works regardless, only slower). The
+     * normal warmUp() → takePhoto() sequence never hits this.
+     */
+    async warmUp(options = {}) {
+        await this.session.sendRequest({
+            type: MiniappRequestType.CAMERA_WARM_UP,
+            size: options.size ?? "medium",
+            mode: options.mode ?? "photo",
+            exposureTimeNs: options.exposureTimeNs,
+            durationMs: options.durationMs ?? 15000,
+        });
+    }
+    /**
+     * Start recording video on the glasses camera. Returns a `recordingId` to pass
+     * to {@link stopVideoRecording} after the glasses report that recording
+     * started. Requires CAMERA permission declared in miniapp.json. Check
+     * `session.capabilities.hasCamera` before calling.
+     *
+     * Resolution and frame rate are optional — omit them to use the device's saved
+     * button-video settings. Lowering `fps` (e.g. to 5) keeps the glasses cooler
+     * during long recordings.
+     */
+    async startVideoRecording(options = {}) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.VIDEO_RECORDING_START,
+            width: options.width,
+            height: options.height,
+            fps: options.fps,
+            sound: options.sound ?? true,
+            save: options.save ?? false,
+        });
+    }
+    /**
+     * Stop an in-progress video recording started with {@link startVideoRecording}.
+     *
+     * By default the recording stays on the glasses. Pass `uploadUrl` to have the
+     * glasses upload the finished clip to your own endpoint.
+     *
+     * @param recordingId The id returned from `startVideoRecording`.
+     * @param options     Optional upload destination for the finished recording.
+     */
+    async stopVideoRecording(recordingId, options = {}) {
+        await this.session.sendRequest({
+            type: MiniappRequestType.VIDEO_RECORDING_STOP,
+            recordingId,
+            uploadUrl: options.uploadUrl,
+            uploadAuthToken: options.uploadAuthToken,
+        });
+    }
+}
+//# sourceMappingURL=camera.js.map

package/dist/modules/camera.js.map

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

package/dist/modules/cloud.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview CloudModule — local miniapp view of the phone-owned cloud client.
+ *
+ * Miniapps do not own or configure the cloud connection. The phone owns one
+ * cloud-client instance and pushes status snapshots here so miniapps can render
+ * honest UX such as online/offline captions indicators.
+ */
+import { MiniappSession } from "../session";
+import type { UnsubscribeFn } from "./events";
+export type CloudClientConnectionStatus = "connected" | "connecting" | "reconnecting" | "disconnected";
+export type CloudClientAudioTransport = "udp" | "ws" | "offline" | "none";
+export interface CloudClientStatus {
+    status: CloudClientConnectionStatus;
+    audioTransport: CloudClientAudioTransport;
+}
+export declare const CLOUD_STATUS_STREAM = "_cloud_status";
+export declare class CloudModule {
+    private readonly session;
+    private readonly emitter;
+    private current;
+    constructor(session: MiniappSession);
+    /** Latest status snapshot pushed by the phone runtime. */
+    get status(): CloudClientStatus;
+    /** True when the phone's cloud-client runtime handshake is complete. */
+    get connected(): boolean;
+    /** Method alias for callers who prefer function-style state reads. */
+    isConnected(): boolean;
+    /**
+     * Subscribe to cloud-client status updates. The current value is delivered
+     * immediately so UI code can hydrate without waiting for the next transition.
+     */
+    onStatusChanged(handler: (status: CloudClientStatus) => void): UnsubscribeFn;
+}
+//# sourceMappingURL=cloud.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../../src/modules/cloud.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AACzC,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,UAAU,CAAA;AAE3C,MAAM,MAAM,2BAA2B,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,cAAc,CAAA;AACtG,MAAM,MAAM,yBAAyB,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAA;AAEzE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,2BAA2B,CAAA;IACnC,cAAc,EAAE,yBAAyB,CAAA;CAC1C;AAMD,eAAO,MAAM,mBAAmB,kBAAkB,CAAA;AA4BlD,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,OAAO,CAAC,OAAO,CAAyC;gBAE3B,OAAO,EAAE,cAAc;IAUpD,0DAA0D;IAC1D,IAAI,MAAM,IAAI,iBAAiB,CAE9B;IAED,wEAAwE;IACxE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,sEAAsE;IACtE,WAAW,IAAI,OAAO;IAItB;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAAG,aAAa;CAO7E"}

package/dist/modules/cloud.js

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview CloudModule — local miniapp view of the phone-owned cloud client.
+ *
+ * Miniapps do not own or configure the cloud connection. The phone owns one
+ * cloud-client instance and pushes status snapshots here so miniapps can render
+ * honest UX such as online/offline captions indicators.
+ */
+import { EventEmitter } from "eventemitter3";
+export const CLOUD_STATUS_STREAM = "_cloud_status";
+const DEFAULT_STATUS = {
+    status: "disconnected",
+    audioTransport: "none",
+};
+function normalizeCloudStatus(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const raw = data;
+    const status = raw.status;
+    const audioTransport = raw.audioTransport;
+    if (status !== "connected" && status !== "connecting" && status !== "reconnecting" && status !== "disconnected") {
+        return null;
+    }
+    if (audioTransport !== "udp" &&
+        audioTransport !== "ws" &&
+        audioTransport !== "offline" &&
+        audioTransport !== "none") {
+        return null;
+    }
+    return { status, audioTransport };
+}
+export class CloudModule {
+    constructor(session) {
+        this.session = session;
+        this.emitter = new EventEmitter();
+        this.current = { ...DEFAULT_STATUS };
+        this.session._subscribe(CLOUD_STATUS_STREAM, (data) => {
+            const next = normalizeCloudStatus(data);
+            if (!next)
+                return;
+            if (next.status === this.current.status && next.audioTransport === this.current.audioTransport)
+                return;
+            this.current = next;
+            this.emitter.emit("status", { ...this.current });
+        });
+    }
+    /** Latest status snapshot pushed by the phone runtime. */
+    get status() {
+        return { ...this.current };
+    }
+    /** True when the phone's cloud-client runtime handshake is complete. */
+    get connected() {
+        return this.current.status === "connected";
+    }
+    /** Method alias for callers who prefer function-style state reads. */
+    isConnected() {
+        return this.connected;
+    }
+    /**
+     * Subscribe to cloud-client status updates. The current value is delivered
+     * immediately so UI code can hydrate without waiting for the next transition.
+     */
+    onStatusChanged(handler) {
+        handler({ ...this.current });
+        this.emitter.on("status", handler);
+        return () => {
+            this.emitter.off("status", handler);
+        };
+    }
+}
+//# sourceMappingURL=cloud.js.map

package/dist/modules/cloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.js","sourceRoot":"","sources":["../../src/modules/cloud.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAC,YAAY,EAAC,MAAM,eAAe,CAAA;AAiB1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAA;AAElD,MAAM,cAAc,GAAsB;IACxC,MAAM,EAAE,cAAc;IACtB,cAAc,EAAE,MAAM;CACvB,CAAA;AAED,SAAS,oBAAoB,CAAC,IAAa;IACzC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAClD,MAAM,GAAG,GAAG,IAA+B,CAAA;IAC3C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAA;IACzB,MAAM,cAAc,GAAG,GAAG,CAAC,cAAc,CAAA;IAEzC,IAAI,MAAM,KAAK,WAAW,IAAI,MAAM,KAAK,YAAY,IAAI,MAAM,KAAK,cAAc,IAAI,MAAM,KAAK,cAAc,EAAE,CAAC;QAChH,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IACE,cAAc,KAAK,KAAK;QACxB,cAAc,KAAK,IAAI;QACvB,cAAc,KAAK,SAAS;QAC5B,cAAc,KAAK,MAAM,EACzB,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,OAAO,EAAC,MAAM,EAAE,cAAc,EAAC,CAAA;AACjC,CAAC;AAED,MAAM,OAAO,WAAW;IAItB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;QAHnC,YAAO,GAAG,IAAI,YAAY,EAAsB,CAAA;QACzD,YAAO,GAAsB,EAAC,GAAG,cAAc,EAAC,CAAA;QAGtD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,IAAI,EAAE,EAAE;YACpD,MAAM,IAAI,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAA;YACvC,IAAI,CAAC,IAAI;gBAAE,OAAM;YACjB,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,cAAc,KAAK,IAAI,CAAC,OAAO,CAAC,cAAc;gBAAE,OAAM;YACtG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;YACnB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAC,GAAG,IAAI,CAAC,OAAO,EAAC,CAAC,CAAA;QAChD,CAAC,CAAC,CAAA;IACJ,CAAC;IAED,0DAA0D;IAC1D,IAAI,MAAM;QACR,OAAO,EAAC,GAAG,IAAI,CAAC,OAAO,EAAC,CAAA;IAC1B,CAAC;IAED,wEAAwE;IACxE,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,WAAW,CAAA;IAC5C,CAAC;IAED,sEAAsE;IACtE,WAAW;QACT,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,OAA4C;QAC1D,OAAO,CAAC,EAAC,GAAG,IAAI,CAAC,OAAO,EAAC,CAAC,CAAA;QAC1B,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QAClC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QACrC,CAAC,CAAA;IACH,CAAC;CACF"}

package/dist/modules/dashboard.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview DashboardAPI — noop surface in v1.
+ *
+ * The cloud DashboardManager owns widget rendering in OS-ranked
+ * rotation. Keeping the API shape so miniapps compile, but calls are
+ * noop + console.warn.
+ */
+import { MiniappSession } from "../session";
+export type DashboardMode = "main" | "expanded" | "always_on";
+export declare class DashboardAPI {
+    private readonly session;
+    private warned;
+    constructor(session: MiniappSession);
+    setContent(mode: DashboardMode, content: string): void;
+}
+//# sourceMappingURL=dashboard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../../src/modules/dashboard.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AAEzC,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,CAAA;AAE7D,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,MAAM,CAAQ;gBAEO,OAAO,EAAE,cAAc;IAEpD,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;CAYvD"}

package/dist/modules/dashboard.js

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview DashboardAPI — noop surface in v1.
+ *
+ * The cloud DashboardManager owns widget rendering in OS-ranked
+ * rotation. Keeping the API shape so miniapps compile, but calls are
+ * noop + console.warn.
+ */
+import { MiniappRequestType } from "../protocol";
+export class DashboardAPI {
+    constructor(session) {
+        this.session = session;
+        this.warned = false;
+    }
+    setContent(mode, content) {
+        if (!this.warned) {
+            console.warn("[@mentra/miniapp] dashboard.setContent() is deferred in v1.");
+            this.warned = true;
+        }
+        // Still forward so the phone can log/ignore consistently.
+        this.session.sendOneShot({
+            type: MiniappRequestType.DASHBOARD_CONTENT_UPDATE,
+            mode,
+            content,
+        });
+    }
+}
+//# sourceMappingURL=dashboard.js.map

package/dist/modules/dashboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.js","sourceRoot":"","sources":["../../src/modules/dashboard.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAC,kBAAkB,EAAC,MAAM,aAAa,CAAA;AAK9C,MAAM,OAAO,YAAY;IAGvB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;QAF5C,WAAM,GAAG,KAAK,CAAA;IAEiC,CAAC;IAExD,UAAU,CAAC,IAAmB,EAAE,OAAe;QAC7C,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAA;YAC3E,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QACpB,CAAC;QACD,0DAA0D;QAC1D,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;YACvB,IAAI,EAAE,kBAAkB,CAAC,wBAAwB;YACjD,IAAI;YACJ,OAAO;SACR,CAAC,CAAA;IACJ,CAAC;CACF"}

package/dist/modules/display.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview DisplayManager — the glasses display, via `render()`.
+ *
+ * render(elements) is replace-the-frame scene rendering: each call describes
+ * everything that should be on screen, the host diffs it against the previous
+ * frame per device, and `render([])` clears. The legacy one-shot `show*`
+ * layout methods were removed once nothing first-party or known-external
+ * called them; hosts still accept the historical `miniapp_display` wire shape
+ * from bundles packed with older SDKs.
+ */
+import { MiniappSession } from "../session";
+export type ViewType = "main" | "dashboard";
+export type DisplayBreakMode = "character" | "character-no-hyphen" | "word" | "strict-word";
+/** Pixel-space bounding box on the device's drawable canvas (see `capabilities.display`). */
+export interface RenderBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface RenderTextStyle {
+    /** Border width in px (0/absent = none). */
+    border?: number;
+    /** Border corner radius in px. */
+    radius?: number;
+    /** What happens to text that doesn't fit the box after wrapping. Default "clip". */
+    overflow?: "clip" | "ellipsis";
+    /** Line-break policy for wrapping (host wraps; the box carries pre-wrapped text). */
+    breakMode?: DisplayBreakMode;
+}
+export interface RenderRectStyle {
+    border?: number;
+    radius?: number;
+}
+/**
+ * One element of a rendered scene. `id` is optional but recommended for
+ * anything that updates over time: elements with a stable id update in place on
+ * the glasses (no flicker); the host matches unnamed elements by geometry.
+ */
+export type RenderElement = {
+    type: "text";
+    id?: string;
+    box: RenderBox;
+    text: string;
+    style?: RenderTextStyle;
+} | {
+    type: "image";
+    id?: string;
+    box: RenderBox;
+    data: string;
+} | {
+    type: "rect";
+    id?: string;
+    box: RenderBox;
+    style?: RenderRectStyle;
+};
+export interface RenderOptions {
+    view?: ViewType;
+    /** Auto-clear after this many ms (same semantics as legacy display options). */
+    durationMs?: number;
+}
+/**
+ * Outcome of a render request, resolved when the host's display arbitration
+ * settles it. "displayed" = accepted and sent to the device — NOT a
+ * render confirmation. "blocked" = another app owns the display (or the
+ * request failed); `reason` says why.
+ */
+export interface RenderResult {
+    status: "displayed" | "blocked";
+    /** True when the host adjusted the scene (clamped boxes, dropped elements, degraded for the device). */
+    degraded?: boolean;
+    /** Ids of elements the host dropped (budget/bounds/device limits) — dropped is never silent. */
+    dropped?: string[];
+    reason?: string;
+}
+export declare class DisplayManager {
+    private readonly session;
+    constructor(session: MiniappSession);
+    /**
+     * Render a whole scene of positioned elements — replace-the-frame.
+     *
+     * Each call describes everything that should be on screen; the host diffs it
+     * against the previous frame per device (elements with a stable `id` update
+     * in place; elements you stop sending are removed). There is no lifecycle to
+     * manage and no remove calls — `render([])` clears.
+     *
+     * Coordinates are raw pixels on the device's drawable canvas — read
+     * `session.capabilities.display` (populated on the "ready" event) for the
+     * real width/height and element budgets. Out-of-bounds boxes are clamped and
+     * over-budget elements are dropped tail-first; both are reported via the
+     * result, never silently.
+     *
+     * Awaiting is OPT-IN — a plain fire-and-forget call is fine. The returned
+     * promise never rejects.
+     *
+     * @example
+     * const result = await session.display.render([
+     *   {type: "text",  id: "stats", box: {x: 12, y: 9, w: 200, h: 28}, text: "863 m  11 min"},
+     *   {type: "image", id: "map",   box: {x: 335, y: 14, w: 150, h: 150}, data: mapPng},
+     *   {type: "rect",  box: {x: 0, y: 0, w: 500, h: 220}, style: {radius: 4}},
+     * ])
+     * if (result.degraded) console.warn("dropped:", result.dropped)
+     */
+    render(elements: RenderElement[], options?: RenderOptions): Promise<RenderResult>;
+}
+//# sourceMappingURL=display.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../../src/modules/display.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAA;AAEzC,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAA;AAE3C,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,qBAAqB,GAAG,MAAM,GAAG,aAAa,CAAA;AAM3F,6FAA6F;AAC7F,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IAC9B,qFAAqF;IACrF,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,CAAA;CAAC,GAClF;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAC1D;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,eAAe,CAAA;CAAC,CAAA;AAExE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,GAAG,SAAS,CAAA;IAC/B,wGAAwG;IACxG,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;CAgBtF"}

package/dist/modules/display.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview DisplayManager — the glasses display, via `render()`.
+ *
+ * render(elements) is replace-the-frame scene rendering: each call describes
+ * everything that should be on screen, the host diffs it against the previous
+ * frame per device, and `render([])` clears. The legacy one-shot `show*`
+ * layout methods were removed once nothing first-party or known-external
+ * called them; hosts still accept the historical `miniapp_display` wire shape
+ * from bundles packed with older SDKs.
+ */
+import { MiniappRequestType } from "../protocol";
+export class DisplayManager {
+    constructor(session) {
+        this.session = session;
+    }
+    /**
+     * Render a whole scene of positioned elements — replace-the-frame.
+     *
+     * Each call describes everything that should be on screen; the host diffs it
+     * against the previous frame per device (elements with a stable `id` update
+     * in place; elements you stop sending are removed). There is no lifecycle to
+     * manage and no remove calls — `render([])` clears.
+     *
+     * Coordinates are raw pixels on the device's drawable canvas — read
+     * `session.capabilities.display` (populated on the "ready" event) for the
+     * real width/height and element budgets. Out-of-bounds boxes are clamped and
+     * over-budget elements are dropped tail-first; both are reported via the
+     * result, never silently.
+     *
+     * Awaiting is OPT-IN — a plain fire-and-forget call is fine. The returned
+     * promise never rejects.
+     *
+     * @example
+     * const result = await session.display.render([
+     *   {type: "text",  id: "stats", box: {x: 12, y: 9, w: 200, h: 28}, text: "863 m  11 min"},
+     *   {type: "image", id: "map",   box: {x: 335, y: 14, w: 150, h: 150}, data: mapPng},
+     *   {type: "rect",  box: {x: 0, y: 0, w: 500, h: 220}, style: {radius: 4}},
+     * ])
+     * if (result.degraded) console.warn("dropped:", result.dropped)
+     */
+    render(elements, options = {}) {
+        return this.session
+            .sendRequest({
+            type: MiniappRequestType.RENDER,
+            view: options.view ?? "main",
+            elements,
+            durationMs: options.durationMs,
+        })
+            .catch((err) => ({
+            status: "blocked",
+            reason: typeof err === "object" && err !== null && "message" in err
+                ? String(err.message)
+                : String(err),
+        }));
+    }
+}
+//# sourceMappingURL=display.js.map

package/dist/modules/display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.js","sourceRoot":"","sources":["../../src/modules/display.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAC,kBAAkB,EAAC,MAAM,aAAa,CAAA;AAkE9C,MAAM,OAAO,cAAc;IACzB,YAA6B,OAAuB;QAAvB,YAAO,GAAP,OAAO,CAAgB;IAAG,CAAC;IAExD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,QAAyB,EAAE,UAAyB,EAAE;QAC3D,OAAO,IAAI,CAAC,OAAO;aAChB,WAAW,CAAe;YACzB,IAAI,EAAE,kBAAkB,CAAC,MAAM;YAC/B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,MAAM;YAC5B,QAAQ;YACR,UAAU,EAAE,OAAO,CAAC,UAAU;SAC/B,CAAC;aACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACf,MAAM,EAAE,SAAkB;YAC1B,MAAM,EACJ,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,SAAS,IAAI,GAAG;gBACzD,CAAC,CAAC,MAAM,CAAE,GAA0B,CAAC,OAAO,CAAC;gBAC7C,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SAClB,CAAC,CAAC,CAAA;IACP,CAAC;CACF"}

package/dist/modules/events.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview EventManager — internal subscription registry + escape hatch.
+ *
+ * Most miniapp authors should NOT touch this directly. Use the typed methods
+ * on domain modules instead:
+ *   - session.transcription.on(...)
+ *   - session.mic.onAudioChunk(...) / onVoiceActivity(...)
+ *   - session.input.onButtonPress(...)
+ *   - session.imu.onHeadPosition(...)
+ *   - session.location.onUpdate(...)
+ *   - session.glasses.onBattery(...) / onConnection(...)
+ *   - session.phone.notifications.on(...) / session.phone.onBattery(...)
+ *
+ * This module's only public method is `subscribe(rawStreamType, handler)` —
+ * a forward-compat escape hatch for new event types not yet wrapped on a
+ * domain module. Officially undocumented; the typed methods on domain
+ * modules are the canonical surface.
+ *
+ * Internally, EventManager owns:
+ *   1. The ref-count map. Outbound SUBSCRIBE is only sent when a stream's
+ *      ref count transitions 0↔1, so multiple components listening for the
+ *      same stream issue one wire-level subscribe.
+ *   2. Inbound event fan-out via `_forwardEvent(streamType, data)`, called
+ *      by MiniappSession.handleIncoming when an EVENT envelope arrives.
+ *
+ * Domain modules call back into the session via session._subscribe(...) which
+ * in turn delegates to this class — the session is the integration point;
+ * domain modules don't see this class directly.
+ */
+import { MiniappSession } from "../session";
+export type UnsubscribeFn = () => void;
+/** @internal Host-selected delivery target for a transcription event. */
+export type TranscriptionEventRoute = "default" | "forceLocal" | "all";
+export interface TranscriptionData {
+    text: string;
+    isFinal: boolean;
+    language?: string;
+}
+export interface TranslationData {
+    text: string;
+    isFinal: boolean;
+    sourceLanguage: string;
+    targetLanguage: string;
+    /** Source-language text of the same utterance, when the provider supplies it. */
+    originalText?: string;
+    /** Stable id correlating interim + final results of one utterance. */
+    utteranceId?: string;
+    /** Speaker id when the provider reports diarization. */
+    speakerId?: string;
+}
+export interface ButtonPressData {
+    buttonId: string;
+    pressType: "short" | "long";
+}
+export interface HeadPositionData {
+    position: "up" | "down";
+}
+export interface AccelData {
+    /** Accelerometer axes in g (gravity-normalized). */
+    x: number;
+    y: number;
+    z: number;
+    /** Unix ms timestamp of the reading. */
+    timestamp: number;
+}
+export interface LocationData {
+    lat: number;
+    lng: number;
+    /** Accuracy in meters, if the platform reported it. */
+    accuracy?: number;
+    /** Unix ms timestamp of the fix. */
+    timestamp?: number;
+    /** Set when this event is a response to a single-location request. */
+    correlationId?: string;
+}
+export interface HeadingData {
+    /** Compass heading in degrees, 0 = north, 90 = east. */
+    degrees: number;
+}
+export interface BatteryData {
+    level: number;
+    charging: boolean;
+}
+export interface ConnectionData {
+    connected: boolean;
+    modelName?: string;
+}
+/** Glasses Wi-Fi state. `connected` is false on glasses without Wi-Fi or when offline. */
+export interface WifiData {
+    connected: boolean;
+    ssid?: string;
+    localIp?: string;
+}
+export interface PhoneNotificationData {
+    /** Stable id from the phone's notification listener. */
+    notificationId: string;
+    /** Human app name (e.g. "Messages"). */
+    app: string;
+    title: string;
+    content: string;
+    /** Android priority string; empty on iOS. */
+    priority: string;
+    timestamp: number;
+    /** Reverse-DNS package/bundle id of the originating app. */
+    packageName: string;
+}
+export interface NotificationDismissedData {
+    /** Same id as the matching post event from `notifications.on(...)`. */
+    notificationId: string;
+    /** Android NotificationKey. More stable than notificationId across reposts. */
+    notificationKey?: string;
+    /** Reverse-DNS package/bundle id of the originating app. */
+    packageName?: string;
+    /** Unix ms timestamp of the dismissal. */
+    timestamp: number;
+}
+export interface VadData {
+    /** True while the user is speaking (voice detected), false when silent. */
+    status: boolean;
+}
+export interface TouchData {
+    /** The gesture: single_tap, double_tap, triple_tap, long_press, swipe_up, or swipe_down. */
+    kind: "single_tap" | "double_tap" | "triple_tap" | "long_press" | "swipe_up" | "swipe_down" | string;
+}
+export interface AudioChunkData {
+    /** PCM or LC3, base64-encoded. Format depends on phone's mic mode. */
+    data: string;
+    sampleRate?: number;
+    format?: string;
+}
+export declare class EventManager {
+    private readonly session;
+    private readonly emitter;
+    /** Stream -> ref count. Outbound SUBSCRIBE tracks active streams and routing changes. */
+    private readonly refCounts;
+    /** Transcription stream -> refs that require on-device-only processing. */
+    private readonly forceLocalRefCounts;
+    constructor(session: MiniappSession);
+    /**
+     * Generic subscribe. `stream` is the raw wire value, including any language
+     * suffix like `"transcription:en-US"`. Forward-compat escape hatch for new
+     * event types not yet wrapped on a domain module. Most authors should use
+     * typed methods on domain modules instead.
+     *
+     * Stream names beginning with `_` (e.g. `_ui` for the session.ui bus) are
+     * INTERNAL — they ride the local _forwardEvent fan-out and never appear in
+     * the outbound SUBSCRIBE list. Native already knows to deliver UI envelopes
+     * via a separate envelope `type`; the EventManager only routes them
+     * locally.
+     */
+    subscribe(stream: string, handler: (data: unknown) => void, options?: {
+        forceLocal?: boolean;
+    }): UnsubscribeFn;
+    /** Unsubscribe every handler on every stream this EventManager owns. */
+    unsubscribeAll(): void;
+    /** @internal */
+    _forwardEvent(stream: string, data: unknown, transcriptionRoute?: TranscriptionEventRoute): void;
+    private sendSubscriptionUpdate;
+}
+//# sourceMappingURL=events.d.ts.map

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

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