@mentra/miniapp 0.3.0-beta.0

package/dist/modules/blob.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview BlobModule — phone-local persistent BINARY storage, keyed and
+ * scoped to (userId, packageName). The binary sibling of `session.storage`:
+ * where storage holds small strings, blob holds arbitrary bytes (PDFs, EPUBs,
+ * audio, video, model files, caches) as files on the phone.
+ *
+ * It deliberately mirrors `session.storage`'s shape — `set` / `get` / `delete` /
+ * `keys` / `has` / `clear` — so it's instantly familiar, plus the things files
+ * (and not strings) need:
+ *   - `setFromUrl(key, url)` — the host downloads a URL straight to disk
+ *     (like the web Cache API's `cache.add`, iOS `URLSession` download task, or
+ *     Android `DownloadManager`). Bytes never cross the bridge.
+ *   - `importFile()` — opens the OS file picker and stores the chosen file.
+ *     Bytes never cross the bridge.
+ *   - `share(key)` — hands the file to the OS share sheet.
+ *   - `createWriteStream` / `createReadStream` — for streaming huge payloads
+ *     (named like Node's `fs.createWriteStream`).
+ *
+ * BACKGROUND-ONLY. Binary doesn't belong in the WebView. A blob's `uri` is a
+ * `file://` path in the app's private storage — fine for `session.speaker.play`,
+ * `blob.share`, or another host capability, but a WebView generally can't load
+ * it directly (route rendering through a host viewer for now).
+ *
+ * Transfer model: the bridge moves JSON strings through a per-miniapp JS engine
+ * (JSC/QuickJS) with a watchdog, so in-JS writes/reads are CHUNKED (≤ ~1 MB raw
+ * per call). Prefer `setFromUrl` / `importFile` when you can — they keep the
+ * bytes entirely host-side.
+ */
+import { MiniappSession } from "../session";
+/** Metadata for one stored blob. `uri` is a `file://` path. */
+export interface BlobMeta {
+    /** The key it's stored under (caller-chosen). */
+    key: string;
+    /** Optional display/file name (e.g. the original filename for an import). */
+    name?: string;
+    /** MIME type, e.g. "application/pdf". */
+    mimeType: string;
+    /** Size on disk in bytes. */
+    bytes: number;
+    /** Epoch ms first written. */
+    createdAt: number;
+    /** Epoch ms last written. */
+    updatedAt: number;
+    /** Content md5 (lowercase hex), computed host-side (skipped for very large blobs). */
+    md5?: string;
+    /** `file://` URI. Feed to `session.speaker.play`, `blob.share`, etc. */
+    uri: string;
+    /** App-defined metadata persisted with the blob. */
+    meta?: Record<string, string | number | boolean>;
+}
+export interface BlobSetOptions {
+    /** Default "application/octet-stream". */
+    mimeType?: string;
+    name?: string;
+    meta?: Record<string, string | number | boolean>;
+}
+export interface BlobSetFromUrlOptions extends BlobSetOptions {
+    /** Request headers (e.g. an Authorization token) for the download. */
+    headers?: Record<string, string>;
+}
+export interface BlobImportOptions {
+    /** Key to store under. Default: a generated key. */
+    key?: string;
+    /** Restrict the picker to a MIME type, e.g. "application/pdf". */
+    mimeType?: string;
+    meta?: Record<string, string | number | boolean>;
+}
+/** Raw bytes per chunked write. ~1 MB raw → ~1.34 MB base64, under the watchdog. */
+export declare const BLOB_WRITE_CHUNK_BYTES: number;
+/** Max bytes `bytes()` will buffer before throwing — read large blobs as a stream. */
+export declare const BLOB_READ_ALL_MAX_BYTES: number;
+/**
+ * Streaming writer (`fs.createWriteStream`-like). Call `write`/`writeBase64` as
+ * many times as you like (each is auto-split into bridge-safe chunks), then
+ * `close()` to publish, or `abort()` to discard the partial blob.
+ */
+export declare class BlobWriter {
+    private readonly session;
+    readonly key: string;
+    private settled;
+    constructor(session: MiniappSession, key: string);
+    /** Append raw bytes. Auto-chunked. */
+    write(chunk: Uint8Array | ArrayBuffer): Promise<void>;
+    /** Append already-base64-encoded bytes (e.g. straight from `mic.onAudioChunk`). */
+    writeBase64(b64: string): Promise<void>;
+    /**
+     * Overwrite bytes at a fixed offset within the not-yet-closed blob (a seek
+     * write). Must stay within already-written bytes; does not grow the blob.
+     * Advanced — used e.g. to patch a container header on finalize.
+     */
+    writeAt(offset: number, chunk: Uint8Array | ArrayBuffer): Promise<void>;
+    /** Finalize and return the blob's metadata. Optional `meta` merges into the record. */
+    close(meta?: Record<string, string | number | boolean>): Promise<BlobMeta>;
+    /** Discard the partial blob. Idempotent. */
+    abort(): Promise<void>;
+    private assertOpen;
+    private send;
+}
+/** Streaming reader (`fs.createReadStream`-like). */
+export declare class BlobReader {
+    private readonly session;
+    readonly handle: string;
+    readonly meta: BlobMeta;
+    private closed;
+    constructor(session: MiniappSession, handle: string, meta: BlobMeta);
+    /** Read up to `maxBytes` (default one chunk). `done` is true at end of file. */
+    read(maxBytes?: number): Promise<{
+        bytes: Uint8Array;
+        done: boolean;
+    }>;
+    close(): Promise<void>;
+}
+export declare class BlobModule {
+    private readonly session;
+    constructor(session: MiniappSession);
+    /** Store bytes under `key`. `data` may be a Uint8Array/ArrayBuffer or a base64 string. */
+    set(key: string, data: Uint8Array | ArrayBuffer | string, opts?: BlobSetOptions): Promise<BlobMeta>;
+    /**
+     * Download `url` straight into a blob under `key`, host-side. The bytes never
+     * cross the bridge (like the web Cache API's `cache.add`). `opts.headers` lets
+     * you pass auth. Resolves to the stored blob's metadata.
+     */
+    setFromUrl(key: string, url: string, opts?: BlobSetFromUrlOptions): Promise<BlobMeta>;
+    /**
+     * Open the OS file picker and store the chosen file as a blob, host-side.
+     * Resolves to the blob's metadata, or `null` if the user cancelled.
+     */
+    importFile(opts?: BlobImportOptions): Promise<BlobMeta | null>;
+    /** Open a streaming writer for `key` (for large/streamed payloads). */
+    createWriteStream(key: string, opts?: BlobSetOptions): Promise<BlobWriter>;
+    /** Metadata (incl. the `file://` uri) for `key`, or null if absent. */
+    get(key: string): Promise<BlobMeta | null>;
+    /** Alias of `get` — the file-stat verb. */
+    stat(key: string): Promise<BlobMeta | null>;
+    /** True iff a blob is stored under `key`. */
+    has(key: string): Promise<boolean>;
+    /** Every key this miniapp has stored, newest first. */
+    keys(): Promise<string[]>;
+    /** Every blob this miniapp owns, newest first. */
+    list(): Promise<BlobMeta[]>;
+    /** Open a streaming reader. Prefer `get(key).uri` when you just need to play/share it. */
+    createReadStream(key: string): Promise<BlobReader>;
+    /** Read a whole blob into memory as bytes, or null if absent. Throws past the cap — stream big ones. */
+    bytes(key: string): Promise<Uint8Array | null>;
+    /** Per-app usage + the quota ceiling, in bytes. */
+    usage(): Promise<{
+        bytes: number;
+        count: number;
+        quotaBytes: number;
+    }>;
+    /** Delete the blob under `key`. No-op if absent. */
+    delete(key: string): Promise<void>;
+    /** Delete every blob this miniapp owns. */
+    clear(): Promise<void>;
+    /** Share the blob via the OS share sheet (host shares from disk — no bytes cross the bridge). */
+    share(key: string): Promise<{
+        success: boolean;
+        cancelled?: boolean;
+    }>;
+}
+//# sourceMappingURL=blob.d.ts.map

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

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

package/dist/modules/blob.js

@@ -0,0 +1,277 @@
+/**
+ * @fileoverview BlobModule — phone-local persistent BINARY storage, keyed and
+ * scoped to (userId, packageName). The binary sibling of `session.storage`:
+ * where storage holds small strings, blob holds arbitrary bytes (PDFs, EPUBs,
+ * audio, video, model files, caches) as files on the phone.
+ *
+ * It deliberately mirrors `session.storage`'s shape — `set` / `get` / `delete` /
+ * `keys` / `has` / `clear` — so it's instantly familiar, plus the things files
+ * (and not strings) need:
+ *   - `setFromUrl(key, url)` — the host downloads a URL straight to disk
+ *     (like the web Cache API's `cache.add`, iOS `URLSession` download task, or
+ *     Android `DownloadManager`). Bytes never cross the bridge.
+ *   - `importFile()` — opens the OS file picker and stores the chosen file.
+ *     Bytes never cross the bridge.
+ *   - `share(key)` — hands the file to the OS share sheet.
+ *   - `createWriteStream` / `createReadStream` — for streaming huge payloads
+ *     (named like Node's `fs.createWriteStream`).
+ *
+ * BACKGROUND-ONLY. Binary doesn't belong in the WebView. A blob's `uri` is a
+ * `file://` path in the app's private storage — fine for `session.speaker.play`,
+ * `blob.share`, or another host capability, but a WebView generally can't load
+ * it directly (route rendering through a host viewer for now).
+ *
+ * Transfer model: the bridge moves JSON strings through a per-miniapp JS engine
+ * (JSC/QuickJS) with a watchdog, so in-JS writes/reads are CHUNKED (≤ ~1 MB raw
+ * per call). Prefer `setFromUrl` / `importFile` when you can — they keep the
+ * bytes entirely host-side.
+ */
+import { MiniappRequestType } from "../protocol";
+import { base64ToBytes, bytesToBase64, toUint8Array } from "./base64";
+/** Raw bytes per chunked write. ~1 MB raw → ~1.34 MB base64, under the watchdog. */
+export const BLOB_WRITE_CHUNK_BYTES = 1024 * 1024;
+const BLOB_WRITE_CHUNK_B64 = Math.floor(BLOB_WRITE_CHUNK_BYTES / 3) * 4;
+/** Max bytes `bytes()` will buffer before throwing — read large blobs as a stream. */
+export const BLOB_READ_ALL_MAX_BYTES = 32 * 1024 * 1024;
+/**
+ * Streaming writer (`fs.createWriteStream`-like). Call `write`/`writeBase64` as
+ * many times as you like (each is auto-split into bridge-safe chunks), then
+ * `close()` to publish, or `abort()` to discard the partial blob.
+ */
+export class BlobWriter {
+    constructor(session, key) {
+        this.session = session;
+        this.key = key;
+        this.settled = false;
+    }
+    /** Append raw bytes. Auto-chunked. */
+    async write(chunk) {
+        this.assertOpen();
+        const bytes = toUint8Array(chunk);
+        for (let off = 0; off < bytes.length; off += BLOB_WRITE_CHUNK_BYTES) {
+            await this.send(bytesToBase64(bytes.subarray(off, off + BLOB_WRITE_CHUNK_BYTES)));
+        }
+    }
+    /** Append already-base64-encoded bytes (e.g. straight from `mic.onAudioChunk`). */
+    async writeBase64(b64) {
+        this.assertOpen();
+        // Slice on 4-char boundaries so each chunk is whole base64 groups.
+        for (let off = 0; off < b64.length; off += BLOB_WRITE_CHUNK_B64) {
+            await this.send(b64.slice(off, off + BLOB_WRITE_CHUNK_B64));
+        }
+    }
+    /**
+     * Overwrite bytes at a fixed offset within the not-yet-closed blob (a seek
+     * write). Must stay within already-written bytes; does not grow the blob.
+     * Advanced — used e.g. to patch a container header on finalize.
+     */
+    async writeAt(offset, chunk) {
+        this.assertOpen();
+        await this.session.sendRequest({
+            type: MiniappRequestType.BLOB_WRITE,
+            key: this.key,
+            offset,
+            base64: bytesToBase64(toUint8Array(chunk)),
+        });
+    }
+    /** Finalize and return the blob's metadata. Optional `meta` merges into the record. */
+    async close(meta) {
+        this.assertOpen();
+        this.settled = true;
+        return this.session.sendRequest({ type: MiniappRequestType.BLOB_COMMIT, key: this.key, meta });
+    }
+    /** Discard the partial blob. Idempotent. */
+    async abort() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        await this.session.sendRequest({ type: MiniappRequestType.BLOB_ABORT, key: this.key });
+    }
+    assertOpen() {
+        if (this.settled)
+            throw new Error("BlobWriter is already closed/aborted");
+    }
+    send(base64) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.BLOB_WRITE,
+            key: this.key,
+            base64,
+        });
+    }
+}
+/** Streaming reader (`fs.createReadStream`-like). */
+export class BlobReader {
+    constructor(session, handle, meta) {
+        this.session = session;
+        this.handle = handle;
+        this.meta = meta;
+        this.closed = false;
+    }
+    /** Read up to `maxBytes` (default one chunk). `done` is true at end of file. */
+    async read(maxBytes = BLOB_WRITE_CHUNK_BYTES) {
+        if (this.closed)
+            throw new Error("BlobReader is closed");
+        const res = await this.session.sendRequest({
+            type: MiniappRequestType.BLOB_READ,
+            handle: this.handle,
+            maxBytes,
+        });
+        return { bytes: base64ToBytes(res?.base64 ?? ""), done: !!res?.done };
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.session.sendRequest({ type: MiniappRequestType.BLOB_CLOSE_READ, handle: this.handle });
+    }
+}
+export class BlobModule {
+    constructor(session) {
+        this.session = session;
+    }
+    // ── write ────────────────────────────────────────────────────────────────
+    /** Store bytes under `key`. `data` may be a Uint8Array/ArrayBuffer or a base64 string. */
+    async set(key, data, opts = {}) {
+        const writer = await this.createWriteStream(key, opts);
+        try {
+            if (typeof data === "string")
+                await writer.writeBase64(data);
+            else
+                await writer.write(data);
+            return await writer.close();
+        }
+        catch (err) {
+            await writer.abort().catch(() => { });
+            throw err;
+        }
+    }
+    /**
+     * Download `url` straight into a blob under `key`, host-side. The bytes never
+     * cross the bridge (like the web Cache API's `cache.add`). `opts.headers` lets
+     * you pass auth. Resolves to the stored blob's metadata.
+     */
+    setFromUrl(key, url, opts = {}) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.BLOB_SET_FROM_URL,
+            key,
+            url,
+            mimeType: opts.mimeType,
+            name: opts.name,
+            headers: opts.headers,
+            meta: opts.meta,
+        });
+    }
+    /**
+     * Open the OS file picker and store the chosen file as a blob, host-side.
+     * Resolves to the blob's metadata, or `null` if the user cancelled.
+     */
+    importFile(opts = {}) {
+        return this.session.sendRequest({
+            type: MiniappRequestType.BLOB_IMPORT,
+            key: opts.key,
+            mimeType: opts.mimeType,
+            meta: opts.meta,
+        });
+    }
+    /** Open a streaming writer for `key` (for large/streamed payloads). */
+    async createWriteStream(key, opts = {}) {
+        const res = await this.session.sendRequest({
+            type: MiniappRequestType.BLOB_CREATE,
+            key,
+            mimeType: opts.mimeType,
+            name: opts.name,
+            meta: opts.meta,
+        });
+        return new BlobWriter(this.session, res.key);
+    }
+    // ── read ─────────────────────────────────────────────────────────────────
+    /** Metadata (incl. the `file://` uri) for `key`, or null if absent. */
+    get(key) {
+        return this.session.sendRequest({ type: MiniappRequestType.BLOB_GET, key });
+    }
+    /** Alias of `get` — the file-stat verb. */
+    stat(key) {
+        return this.get(key);
+    }
+    /** True iff a blob is stored under `key`. */
+    async has(key) {
+        return (await this.get(key)) !== null;
+    }
+    /** Every key this miniapp has stored, newest first. */
+    async keys() {
+        return (await this.list()).map((m) => m.key);
+    }
+    /** Every blob this miniapp owns, newest first. */
+    async list() {
+        const res = await this.session.sendRequest({ type: MiniappRequestType.BLOB_LIST });
+        return res?.blobs ?? [];
+    }
+    /** Open a streaming reader. Prefer `get(key).uri` when you just need to play/share it. */
+    async createReadStream(key) {
+        const res = await this.session.sendRequest({
+            type: MiniappRequestType.BLOB_OPEN_READ,
+            key,
+        });
+        return new BlobReader(this.session, res.handle, res.meta);
+    }
+    /** Read a whole blob into memory as bytes, or null if absent. Throws past the cap — stream big ones. */
+    async bytes(key) {
+        let reader;
+        try {
+            reader = await this.createReadStream(key);
+        }
+        catch {
+            return null;
+        }
+        const parts = [];
+        let total = 0;
+        try {
+            for (;;) {
+                const { bytes, done } = await reader.read();
+                if (bytes.length) {
+                    total += bytes.length;
+                    if (total > BLOB_READ_ALL_MAX_BYTES) {
+                        throw new Error(`Blob "${key}" exceeds the in-memory read cap — stream it with createReadStream()`);
+                    }
+                    parts.push(bytes);
+                }
+                if (done)
+                    break;
+            }
+        }
+        finally {
+            await reader.close().catch(() => { });
+        }
+        const out = new Uint8Array(total);
+        let at = 0;
+        for (const p of parts) {
+            out.set(p, at);
+            at += p.length;
+        }
+        return out;
+    }
+    // ── manage ───────────────────────────────────────────────────────────────
+    /** Per-app usage + the quota ceiling, in bytes. */
+    usage() {
+        return this.session.sendRequest({
+            type: MiniappRequestType.BLOB_USAGE,
+        });
+    }
+    /** Delete the blob under `key`. No-op if absent. */
+    async delete(key) {
+        await this.session.sendRequest({ type: MiniappRequestType.BLOB_DELETE, key });
+    }
+    /** Delete every blob this miniapp owns. */
+    async clear() {
+        await this.session.sendRequest({ type: MiniappRequestType.BLOB_CLEAR });
+    }
+    /** Share the blob via the OS share sheet (host shares from disk — no bytes cross the bridge). */
+    async share(key) {
+        const res = await this.session.sendRequest({
+            type: MiniappRequestType.BLOB_SHARE,
+            key,
+        });
+        return res ?? { success: false };
+    }
+}
+//# sourceMappingURL=blob.js.map

package/dist/modules/blob.js.map

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

package/dist/modules/camera.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @fileoverview CameraModule — glasses camera control and photo capture.
+ */
+import { MiniappSession } from "../session";
+export type CameraRoiPosition = "center" | "bottom" | "top";
+export type CameraFovPreset = "narrow" | "standard" | "wide";
+export type CameraFovRequest = {
+    /** Horizontal FOV, degrees. */
+    fov: number;
+    /** Crop/region position: center, bottom, or top. Defaults to center. */
+    roiPosition?: CameraRoiPosition;
+} | {
+    /** Named FOV preset. Presets use center ROI. */
+    preset: CameraFovPreset;
+};
+export type SetCameraFovOptions = CameraFovRequest;
+export interface CameraFovResult {
+    requestId: string;
+    fov: number;
+    roiPosition: CameraRoiPosition;
+    timestamp: number;
+}
+export interface TakePhotoOptions {
+    size?: "low" | "medium" | "high" | "max";
+    /** Capture at maximum source quality and optimize BLE delivery for readable text. */
+    mode?: "photo" | "text";
+    compress?: "none" | "low" | "medium" | "high";
+    sound?: boolean;
+    saveToGallery?: boolean;
+    /**
+     * Manual shutter / exposure time in nanoseconds. Omit (or pass undefined)
+     * to let the glasses auto-expose. Honored only on cameras that support
+     * manual exposure; ignored otherwise.
+    */
+    exposureTimeNs?: number;
+    /** Sensor ISO for this capture only. Only used when `exposureTimeNs` enables manual exposure. */
+    iso?: number | null;
+    /** After AE convergence, divide the metered exposure by this factor (scan mode). */
+    aeExposureDivisor?: number;
+    /** Cap ISO after AE metering (scan mode). */
+    isoCap?: number;
+    /** Request per-capture noise reduction. Sent on the wire; glasses may log `not_implemented`. */
+    noiseReduction?: boolean;
+    /** Request per-capture edge enhancement. Sent on the wire; glasses may log `not_implemented`. */
+    edgeEnhancement?: boolean;
+    /** Multi-frame noise reduction preference. */
+    mfnr?: boolean;
+    /** Zero-shutter-lag preference. */
+    zsl?: boolean;
+    /** ISP digital gain hint. */
+    ispDigitalGain?: number;
+    /** ISP analog gain hint. */
+    ispAnalogGain?: string;
+    /**
+     * Override the SDK's default 60s request timeout for this capture only.
+     * Leave unset for a normal user-triggered capture (the full 60s ceiling is
+     * appropriate there). Callers that speculatively fire a capture and may
+     * abandon it if the result isn't needed (e.g. a short-lived non-visual
+     * assistant turn racing a capture against a ~1s latency cap) should pass a
+     * short value here so the abandoned `takePhoto()` promise settles quickly
+     * instead of sitting on the default 60s ceiling.
+     */
+    timeoutMs?: number;
+}
+export interface PhotoTaken {
+    /** Request id that correlates ASG status, upload, and phone/cloud logs. */
+    requestId: string;
+    photoUrl: string;
+    mimeType: string;
+    size: number;
+}
+export interface WarmUpCameraOptions {
+    size?: "low" | "medium" | "high" | "max";
+    /** Match the upcoming capture mode so warm-up and capture share one ASG camera session. */
+    mode?: "photo" | "text";
+    exposureTimeNs?: number;
+    /** Ready-state hold in milliseconds. Defaults to 15 seconds and is capped at 60 seconds. */
+    durationMs?: number;
+}
+export interface StartVideoRecordingOptions {
+    /** Video width in pixels. Omit to use the device's saved button-video default. */
+    width?: number;
+    /** Video height in pixels. Omit to use the device's saved button-video default. */
+    height?: number;
+    /**
+     * Frames per second. Lower frame rates keep the glasses cooler and produce
+     * smaller files — useful for long recordings where smooth motion isn't needed.
+     * Omit to use the device default.
+     */
+    fps?: number;
+    /** Play start/stop capture sounds. Defaults to true. */
+    sound?: boolean;
+    /** Keep the recording on the glasses after it finishes. Defaults to false. */
+    save?: boolean;
+}
+export interface VideoRecordingStarted {
+    /** Identifier for this recording session; pass to {@link stopVideoRecording}. */
+    recordingId: string;
+}
+export interface StopVideoRecordingOptions {
+    /**
+     * Upload the finished recording to this URL with a multipart POST (the file is
+     * the `video` part). The glasses upload it directly. Omit to keep the recording
+     * on the glasses instead.
+     */
+    uploadUrl?: string;
+    /** Bearer token sent as the `Authorization` header on the upload, if your endpoint needs one. */
+    uploadAuthToken?: string;
+}
+export declare class CameraModule {
+    private readonly session;
+    constructor(session: MiniappSession);
+    /** True iff `CAMERA` is declared in the miniapp's manifest. */
+    get hasPermission(): boolean;
+    /**
+     * 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.
+     */
+    setFov(request: CameraFovRequest): Promise<CameraFovResult>;
+    /**
+     * 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.
+    */
+    takePhoto(options?: TakePhotoOptions): Promise<PhotoTaken>;
+    /**
+     * 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.
+     */
+    warmUp(options?: WarmUpCameraOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    startVideoRecording(options?: StartVideoRecordingOptions): Promise<VideoRecordingStarted>;
+    /**
+     * 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.
+     */
+    stopVideoRecording(recordingId: string, options?: StopVideoRecordingOptions): Promise<void>;
+}
+//# sourceMappingURL=camera.d.ts.map

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

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