@moldable-ai/ui 0.2.17 → 0.2.19

package/dist/lib/commands.js

@@ -211,6 +211,103 @@ export function callMoldableApp(targetAppId, method, params, options = {}) {
             method,
             params,
             scopes: options.scopes ?? [method],
+            timeoutMs: options.timeoutMs,
+            requestAccess: options.requestAccess ?? true,
+        });
+    });
+}
+/**
+ * Ask the Moldable desktop host to enter, exit, or toggle native window fullscreen.
+ *
+ * This avoids iframe Fullscreen API permissions policy issues inside the desktop
+ * shell. Outside Moldable, it falls back to the browser Fullscreen API.
+ */
+export async function setMoldableWindowFullscreen(fullscreen = true, options = {}) {
+    if (!isInMoldable()) {
+        const requested = fullscreen === 'toggle' ? !document.fullscreenElement : fullscreen;
+        if (requested) {
+            await document.documentElement.requestFullscreen();
+        }
+        else if (document.fullscreenElement && document.exitFullscreen) {
+            await document.exitFullscreen();
+        }
+        return { fullscreen: Boolean(document.fullscreenElement) };
+    }
+    return new Promise((resolve, reject) => {
+        const requestId = makeRequestId('window-fullscreen');
+        const timeoutMs = options.timeoutMs ?? 10_000;
+        const timeout = window.setTimeout(() => {
+            window.removeEventListener('message', handleResponse);
+            reject(new Error('Fullscreen request timed out.'));
+        }, timeoutMs);
+        function handleResponse(event) {
+            if (event.data?.type !== 'moldable:set-window-fullscreen-result')
+                return;
+            if (event.data?.requestId !== requestId)
+                return;
+            window.clearTimeout(timeout);
+            window.removeEventListener('message', handleResponse);
+            const response = event.data;
+            if (response.ok && response.result) {
+                resolve(response.result);
+                return;
+            }
+            reject(new Error(response.error?.message ||
+                response.error?.code ||
+                'Fullscreen request failed.'));
+        }
+        window.addEventListener('message', handleResponse);
+        sendToMoldable({
+            type: 'moldable:set-window-fullscreen',
+            requestId,
+            fullscreen,
+        });
+    });
+}
+/**
+ * Publish a static artifact through the Moldable desktop host.
+ *
+ * Apps provide source file paths; Moldable owns the publishing key and turns the bundle
+ * into signed manifest, file upload, and commit requests. The returned URL is
+ * public but unlisted.
+ */
+export async function publishMoldableArtifact(options) {
+    if (!isInMoldable()) {
+        throw new Error('Artifact publishing is only available inside Moldable.');
+    }
+    return new Promise((resolve, reject) => {
+        const requestId = makeRequestId('artifact-publish');
+        const timeoutMs = options.timeoutMs ?? 300_000;
+        const timeout = window.setTimeout(() => {
+            window.removeEventListener('message', handleResponse);
+            reject(new Error('Artifact publish timed out.'));
+        }, timeoutMs);
+        function handleResponse(event) {
+            if (event.data?.type !== 'moldable:artifact-publish-result')
+                return;
+            if (event.data?.requestId !== requestId)
+                return;
+            window.clearTimeout(timeout);
+            window.removeEventListener('message', handleResponse);
+            if (event.data.ok) {
+                resolve(event.data.result);
+                return;
+            }
+            reject(new Error(event.data.error?.message || 'Artifact publish failed.'));
+        }
+        window.addEventListener('message', handleResponse);
+        sendToMoldable({
+            type: 'moldable:artifact-publish',
+            requestId,
+            kind: options.kind,
+            title: options.title,
+            entrypoint: options.entrypoint,
+            metadata: options.metadata ?? {},
+            files: options.files.map((file) => ({
+                path: file.path,
+                contentType: file.contentType,
+                sourcePath: file.sourcePath,
+            })),
             requestAccess: options.requestAccess ?? true,
         });
     });

package/dist/lib/native-hardware/bluetooth-access.d.ts

@@ -0,0 +1,14 @@
+import type { MoldableBluetoothAvailability, MoldableBluetoothDevice, MoldableBluetoothOperationOptions, MoldableBluetoothRequestDeviceOptions, MoldableBluetoothRequestOptions } from './bluetooth-types';
+/** Checks only for the standards-based Web Bluetooth entry point. */
+export declare function isMoldableBluetoothSupported(): boolean;
+/**
+ * Returns adapter availability when the runtime exposes it. `unknown` means the
+ * API exists but cannot report adapter state, not that Bluetooth is available.
+ */
+export declare function getMoldableBluetoothAvailability(options?: MoldableBluetoothOperationOptions): Promise<MoldableBluetoothAvailability>;
+/**
+ * Opens the browser's device chooser. This must be called directly from a
+ * trusted user action; it never silently scans for or selects devices.
+ */
+export declare function requestMoldableBluetoothDevice(deviceOptions: MoldableBluetoothRequestDeviceOptions, options?: MoldableBluetoothRequestOptions): Promise<MoldableBluetoothDevice>;
+//# sourceMappingURL=bluetooth-access.d.ts.map

package/dist/lib/native-hardware/bluetooth-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluetooth-access.d.ts","sourceRoot":"","sources":["../../../src/lib/native-hardware/bluetooth-access.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,iCAAiC,EACjC,qCAAqC,EACrC,+BAA+B,EAChC,MAAM,mBAAmB,CAAA;AAE1B,qEAAqE;AACrE,wBAAgB,4BAA4B,IAAI,OAAO,CAGtD;AAED;;;GAGG;AACH,wBAAsB,gCAAgC,CACpD,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,6BAA6B,CAAC,CAexC;AAED;;;GAGG;AACH,wBAAsB,8BAA8B,CAClD,aAAa,EAAE,qCAAqC,EACpD,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,uBAAuB,CAAC,CAelC"}

package/dist/lib/native-hardware/bluetooth-access.js

@@ -0,0 +1,40 @@
+import { abortableBluetooth, assertBluetoothUserGesture, bluetoothError, getBluetoothAPI, getBluetoothNavigator, validateBluetoothRequestOptions, } from './bluetooth-internal';
+/** Checks only for the standards-based Web Bluetooth entry point. */
+export function isMoldableBluetoothSupported() {
+    const api = getBluetoothNavigator()?.bluetooth;
+    return Boolean(api && typeof api.requestDevice === 'function');
+}
+/**
+ * Returns adapter availability when the runtime exposes it. `unknown` means the
+ * API exists but cannot report adapter state, not that Bluetooth is available.
+ */
+export async function getMoldableBluetoothAvailability(options = {}) {
+    const operation = 'check Bluetooth availability';
+    const api = getBluetoothAPI(operation);
+    if (typeof api.getAvailability !== 'function')
+        return 'unknown';
+    try {
+        return (await abortableBluetooth(api.getAvailability(), options.signal, operation))
+            ? 'available'
+            : 'unavailable';
+    }
+    catch (error) {
+        throw bluetoothError(error, operation);
+    }
+}
+/**
+ * Opens the browser's device chooser. This must be called directly from a
+ * trusted user action; it never silently scans for or selects devices.
+ */
+export async function requestMoldableBluetoothDevice(deviceOptions, options = {}) {
+    const operation = 'request a Bluetooth device';
+    const api = getBluetoothAPI(operation);
+    validateBluetoothRequestOptions(deviceOptions);
+    assertBluetoothUserGesture();
+    try {
+        return await abortableBluetooth(api.requestDevice(deviceOptions), options.signal, operation, (device) => device.gatt?.disconnect());
+    }
+    catch (error) {
+        throw bluetoothError(error, operation);
+    }
+}

package/dist/lib/native-hardware/bluetooth-connection.d.ts

@@ -0,0 +1,19 @@
+import type { MoldableBluetoothConnectionOptions, MoldableBluetoothDevice, MoldableBluetoothOperationOptions, MoldableBluetoothRemoteGATTServer, MoldableBluetoothRemoteGATTService, MoldableBluetoothUUID } from './bluetooth-types';
+export declare class MoldableBluetoothConnection {
+    readonly device: MoldableBluetoothDevice;
+    readonly server: MoldableBluetoothRemoteGATTServer;
+    private readonly abortSignal?;
+    private readonly disconnectListeners;
+    private isClosed;
+    constructor(device: MoldableBluetoothDevice, server: MoldableBluetoothRemoteGATTServer, options?: MoldableBluetoothConnectionOptions);
+    get connected(): boolean;
+    onDisconnected(listener: () => void, signal?: AbortSignal): () => void;
+    getPrimaryService(service: MoldableBluetoothUUID, options?: MoldableBluetoothOperationOptions): Promise<MoldableBluetoothRemoteGATTService>;
+    disconnect(): void;
+    private readonly handleAbort;
+    private readonly handleDisconnected;
+    private finish;
+}
+/** Connects a previously user-selected device and owns disconnect cleanup. */
+export declare function connectMoldableBluetoothDevice(device: MoldableBluetoothDevice, options?: MoldableBluetoothConnectionOptions): Promise<MoldableBluetoothConnection>;
+//# sourceMappingURL=bluetooth-connection.d.ts.map

package/dist/lib/native-hardware/bluetooth-connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluetooth-connection.d.ts","sourceRoot":"","sources":["../../../src/lib/native-hardware/bluetooth-connection.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,kCAAkC,EAClC,uBAAuB,EACvB,iCAAiC,EACjC,iCAAiC,EACjC,kCAAkC,EAClC,qBAAqB,EACtB,MAAM,mBAAmB,CAAA;AAE1B,qBAAa,2BAA2B;IACtC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAA;IACxC,QAAQ,CAAC,MAAM,EAAE,iCAAiC,CAAA;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAa;IAC1C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAwB;IAC5D,OAAO,CAAC,QAAQ,CAAQ;gBAGtB,MAAM,EAAE,uBAAuB,EAC/B,MAAM,EAAE,iCAAiC,EACzC,OAAO,GAAE,kCAAuC;IASlD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,IAAI;IAWhE,iBAAiB,CACrB,OAAO,EAAE,qBAAqB,EAC9B,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,kCAAkC,CAAC;IAmB9C,UAAU,IAAI,IAAI;IAMlB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA0B;IAE7D,OAAO,CAAC,MAAM;CAqBf;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,uBAAuB,EAC/B,OAAO,GAAE,kCAAuC,GAC/C,OAAO,CAAC,2BAA2B,CAAC,CA0BtC"}

package/dist/lib/native-hardware/bluetooth-connection.js

@@ -0,0 +1,88 @@
+import { abortableBluetooth, bluetoothAborted, bluetoothError, } from './bluetooth-internal';
+export class MoldableBluetoothConnection {
+    device;
+    server;
+    abortSignal;
+    disconnectListeners = new Set();
+    isClosed = false;
+    constructor(device, server, options = {}) {
+        this.device = device;
+        this.server = server;
+        this.abortSignal = options.signal;
+        device.addEventListener('gattserverdisconnected', this.handleDisconnected);
+        options.signal?.addEventListener('abort', this.handleAbort, { once: true });
+    }
+    get connected() {
+        return !this.isClosed && this.server.connected;
+    }
+    onDisconnected(listener, signal) {
+        if (signal?.aborted || this.isClosed)
+            return () => undefined;
+        this.disconnectListeners.add(listener);
+        const cleanup = () => {
+            this.disconnectListeners.delete(listener);
+            signal?.removeEventListener('abort', cleanup);
+        };
+        signal?.addEventListener('abort', cleanup, { once: true });
+        return cleanup;
+    }
+    async getPrimaryService(service, options = {}) {
+        const operation = `get Bluetooth service ${String(service)}`;
+        if (!this.connected) {
+            throw bluetoothError(new DOMException('Bluetooth device is disconnected', 'NetworkError'), operation);
+        }
+        try {
+            return await abortableBluetooth(this.server.getPrimaryService(service), options.signal, operation);
+        }
+        catch (error) {
+            throw bluetoothError(error, operation);
+        }
+    }
+    disconnect() {
+        if (this.isClosed)
+            return;
+        this.finish(false);
+        if (this.server.connected)
+            this.server.disconnect();
+    }
+    handleAbort = () => this.disconnect();
+    handleDisconnected = () => this.finish(true);
+    finish(notify) {
+        if (this.isClosed)
+            return;
+        this.isClosed = true;
+        this.device.removeEventListener('gattserverdisconnected', this.handleDisconnected);
+        this.abortSignal?.removeEventListener('abort', this.handleAbort);
+        if (notify) {
+            const listeners = [...this.disconnectListeners];
+            this.disconnectListeners.clear();
+            for (const listener of listeners) {
+                try {
+                    listener();
+                }
+                catch {
+                    // A consumer callback must not prevent connection cleanup.
+                }
+            }
+        }
+        this.disconnectListeners.clear();
+    }
+}
+/** Connects a previously user-selected device and owns disconnect cleanup. */
+export async function connectMoldableBluetoothDevice(device, options = {}) {
+    const operation = `connect to Bluetooth device ${device.id}`;
+    if (!device.gatt) {
+        throw bluetoothError(new DOMException('Device does not expose a GATT server', 'NotSupportedError'), operation);
+    }
+    try {
+        const server = await abortableBluetooth(device.gatt.connect(), options.signal, operation, (lateServer) => lateServer.disconnect());
+        if (options.signal?.aborted) {
+            server.disconnect();
+            throw bluetoothAborted(operation);
+        }
+        return new MoldableBluetoothConnection(device, server, options);
+    }
+    catch (error) {
+        throw bluetoothError(error, operation);
+    }
+}

package/dist/lib/native-hardware/bluetooth-gatt.d.ts

@@ -0,0 +1,7 @@
+import type { MoldableBluetoothOperationOptions, MoldableBluetoothRemoteGATTCharacteristic, MoldableBluetoothRemoteGATTService, MoldableBluetoothUUID, MoldableBluetoothWriteMode } from './bluetooth-types';
+export declare function getMoldableBluetoothCharacteristic(service: MoldableBluetoothRemoteGATTService, characteristic: MoldableBluetoothUUID, options?: MoldableBluetoothOperationOptions): Promise<MoldableBluetoothRemoteGATTCharacteristic>;
+export declare function readMoldableBluetoothValue(characteristic: MoldableBluetoothRemoteGATTCharacteristic, options?: MoldableBluetoothOperationOptions): Promise<DataView>;
+/** Starts notifications and returns async, idempotent subscription cleanup. */
+export declare function observeMoldableBluetoothNotifications(characteristic: MoldableBluetoothRemoteGATTCharacteristic, listener: (event: Event) => void, options?: MoldableBluetoothOperationOptions): Promise<() => Promise<void>>;
+export declare function writeMoldableBluetoothValue(characteristic: MoldableBluetoothRemoteGATTCharacteristic, value: BufferSource, mode?: MoldableBluetoothWriteMode, options?: MoldableBluetoothOperationOptions): Promise<void>;
+//# sourceMappingURL=bluetooth-gatt.d.ts.map

package/dist/lib/native-hardware/bluetooth-gatt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluetooth-gatt.d.ts","sourceRoot":"","sources":["../../../src/lib/native-hardware/bluetooth-gatt.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,iCAAiC,EACjC,yCAAyC,EACzC,kCAAkC,EAClC,qBAAqB,EACrB,0BAA0B,EAC3B,MAAM,mBAAmB,CAAA;AAE1B,wBAAsB,kCAAkC,CACtD,OAAO,EAAE,kCAAkC,EAC3C,cAAc,EAAE,qBAAqB,EACrC,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,yCAAyC,CAAC,CAWpD;AAED,wBAAsB,0BAA0B,CAC9C,cAAc,EAAE,yCAAyC,EACzD,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,QAAQ,CAAC,CAWnB;AAED,+EAA+E;AAC/E,wBAAsB,qCAAqC,CACzD,cAAc,EAAE,yCAAyC,EACzD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAChC,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAmC9B;AAED,wBAAsB,2BAA2B,CAC/C,cAAc,EAAE,yCAAyC,EACzD,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE,0BAAwC,EAC9C,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,IAAI,CAAC,CA0Bf"}

package/dist/lib/native-hardware/bluetooth-gatt.js

@@ -0,0 +1,77 @@
+import { abortableBluetooth, bluetoothAborted, bluetoothError, } from './bluetooth-internal';
+export async function getMoldableBluetoothCharacteristic(service, characteristic, options = {}) {
+    const operation = `get Bluetooth characteristic ${String(characteristic)}`;
+    try {
+        return await abortableBluetooth(service.getCharacteristic(characteristic), options.signal, operation);
+    }
+    catch (error) {
+        throw bluetoothError(error, operation);
+    }
+}
+export async function readMoldableBluetoothValue(characteristic, options = {}) {
+    const operation = `read Bluetooth characteristic ${characteristic.uuid}`;
+    try {
+        return await abortableBluetooth(characteristic.readValue(), options.signal, operation);
+    }
+    catch (error) {
+        throw bluetoothError(error, operation);
+    }
+}
+/** Starts notifications and returns async, idempotent subscription cleanup. */
+export async function observeMoldableBluetoothNotifications(characteristic, listener, options = {}) {
+    const operation = `observe Bluetooth characteristic ${characteristic.uuid}`;
+    try {
+        await abortableBluetooth(characteristic.startNotifications(), options.signal, operation, (lateCharacteristic) => {
+            void lateCharacteristic.stopNotifications();
+        });
+        if (options.signal?.aborted) {
+            await characteristic.stopNotifications();
+            throw bluetoothAborted(operation);
+        }
+    }
+    catch (error) {
+        throw bluetoothError(error, operation);
+    }
+    let active = true;
+    const cleanup = async () => {
+        if (!active)
+            return;
+        active = false;
+        characteristic.removeEventListener('characteristicvaluechanged', listener);
+        options.signal?.removeEventListener('abort', onAbort);
+        try {
+            await characteristic.stopNotifications();
+        }
+        catch (error) {
+            throw bluetoothError(error, `stop ${operation}`);
+        }
+    };
+    const onAbort = () => void cleanup().catch(() => undefined);
+    characteristic.addEventListener('characteristicvaluechanged', listener);
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    return cleanup;
+}
+export async function writeMoldableBluetoothValue(characteristic, value, mode = 'automatic', options = {}) {
+    const operation = `write Bluetooth characteristic ${characteristic.uuid}`;
+    let write;
+    if (mode === 'with-response') {
+        write = characteristic.writeValueWithResponse?.bind(characteristic);
+    }
+    else if (mode === 'without-response') {
+        write = characteristic.writeValueWithoutResponse?.bind(characteristic);
+    }
+    else {
+        write =
+            characteristic.writeValueWithResponse?.bind(characteristic) ??
+                characteristic.writeValue.bind(characteristic);
+    }
+    if (!write) {
+        throw bluetoothError(new DOMException(`Bluetooth write mode ${mode} is unavailable`, 'NotSupportedError'), operation);
+    }
+    try {
+        await abortableBluetooth(write(value), options.signal, operation);
+    }
+    catch (error) {
+        throw bluetoothError(error, operation);
+    }
+}

package/dist/lib/native-hardware/bluetooth-internal.d.ts

@@ -0,0 +1,10 @@
+import type { MoldableBluetoothAPI, MoldableBluetoothNavigator, MoldableBluetoothRequestDeviceOptions } from './bluetooth-types';
+import { NativeHardwareBridgeError } from './bridge';
+export declare function bluetoothError(error: unknown, operation: string): NativeHardwareBridgeError;
+export declare function bluetoothAborted(operation: string): NativeHardwareBridgeError;
+export declare function getBluetoothNavigator(): MoldableBluetoothNavigator | undefined;
+export declare function getBluetoothAPI(operation: string): MoldableBluetoothAPI;
+export declare function assertBluetoothUserGesture(): void;
+export declare function validateBluetoothRequestOptions(options: MoldableBluetoothRequestDeviceOptions): void;
+export declare function abortableBluetooth<T>(promise: Promise<T>, signal: AbortSignal | undefined, operation: string, onLateResolution?: (value: T) => void): Promise<T>;
+//# sourceMappingURL=bluetooth-internal.d.ts.map

package/dist/lib/native-hardware/bluetooth-internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluetooth-internal.d.ts","sourceRoot":"","sources":["../../../src/lib/native-hardware/bluetooth-internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,qCAAqC,EACtC,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,yBAAyB,EAE1B,MAAM,UAAU,CAAA;AAGjB,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,yBAAyB,CAsC3B;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,yBAAyB,CAK7E;AAED,wBAAgB,qBAAqB,IACjC,0BAA0B,GAC1B,SAAS,CAIZ;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB,CASvE;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAWjD;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,qCAAqC,GAC7C,IAAI,CAiBN;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,SAAS,EAAE,MAAM,EACjB,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GACpC,OAAO,CAAC,CAAC,CAAC,CA+BZ"}

package/dist/lib/native-hardware/bluetooth-internal.js

@@ -0,0 +1,105 @@
+import { NativeHardwareBridgeError, toNativeHardwareBridgeError, } from './bridge';
+export function bluetoothError(error, operation) {
+    if (error instanceof NativeHardwareBridgeError)
+        return error;
+    const name = error instanceof DOMException ? error.name : undefined;
+    let code = 'host_error';
+    let retryable = false;
+    if (name === 'NotSupportedError')
+        code = 'unsupported';
+    else if (name === 'NotAllowedError' || name === 'SecurityError') {
+        code = 'permission_denied';
+    }
+    else if (name === 'AbortError')
+        code = 'aborted';
+    else if (name === 'NotFoundError')
+        code = 'cancelled';
+    else if (name === 'NetworkError' ||
+        name === 'InvalidStateError' ||
+        name === 'OperationError') {
+        code = 'unavailable';
+        retryable = true;
+    }
+    else if (error instanceof TypeError)
+        code = 'invalid_request';
+    const fallbackMessage = `Unable to ${operation}`;
+    return toNativeHardwareBridgeError({
+        code,
+        message: error instanceof Error
+            ? error.message || fallbackMessage
+            : fallbackMessage,
+        details: {
+            capability: 'bluetooth',
+            operation,
+            ...(name ? { cause: name } : {}),
+        },
+        retryable,
+    }, fallbackMessage);
+}
+export function bluetoothAborted(operation) {
+    return bluetoothError(new DOMException(`Bluetooth ${operation} was aborted`, 'AbortError'), operation);
+}
+export function getBluetoothNavigator() {
+    return typeof navigator === 'undefined'
+        ? undefined
+        : navigator;
+}
+export function getBluetoothAPI(operation) {
+    const api = getBluetoothNavigator()?.bluetooth;
+    if (!api || typeof api.requestDevice !== 'function') {
+        throw bluetoothError(new DOMException('Web Bluetooth is unavailable', 'NotSupportedError'), operation);
+    }
+    return api;
+}
+export function assertBluetoothUserGesture() {
+    const activation = getBluetoothNavigator()?.userActivation;
+    if (activation && !activation.isActive) {
+        throw toNativeHardwareBridgeError({
+            code: 'invalid_request',
+            message: 'Bluetooth device selection must be requested from a user-initiated action.',
+            details: { capability: 'bluetooth', cause: 'user_gesture_required' },
+            retryable: true,
+        });
+    }
+}
+export function validateBluetoothRequestOptions(options) {
+    const hasFilters = 'filters' in options && options.filters !== undefined;
+    const acceptsAll = options.acceptAllDevices === true;
+    if (hasFilters === acceptsAll) {
+        throw bluetoothError(new TypeError('Specify either a non-empty filters array or acceptAllDevices: true'), 'request a Bluetooth device');
+    }
+    if (hasFilters && options.filters.length === 0) {
+        throw bluetoothError(new TypeError('Bluetooth filters must not be empty'), 'request a Bluetooth device');
+    }
+}
+export function abortableBluetooth(promise, signal, operation, onLateResolution) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(bluetoothAborted(operation));
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(bluetoothAborted(operation));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        void promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            if (settled) {
+                onLateResolution?.(value);
+                return;
+            }
+            settled = true;
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        });
+    });
+}

package/dist/lib/native-hardware/bluetooth-native-fallback.d.ts

@@ -0,0 +1,33 @@
+import type { MoldableBluetoothDevice, MoldableBluetoothRequestDeviceOptions } from './bluetooth-types';
+import { type NativeHardwareBridgeOptions } from './bridge';
+export type MoldableBluetoothTransport = {
+    kind: 'web-bluetooth';
+    device: MoldableBluetoothDevice;
+} | {
+    kind: 'desktop-bridge';
+    device: MoldableNativeBluetoothDevice;
+};
+export interface MoldableNativeBluetoothService {
+    uuid: string;
+    characteristicUuids: string[];
+}
+export interface MoldableNativeBluetoothDevice {
+    readonly id: string;
+    readonly name: string | null;
+    readonly connected: boolean;
+    addEventListener(type: 'gattserverdisconnected', listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: 'gattserverdisconnected', listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    getServices(options?: NativeHardwareBridgeOptions): Promise<MoldableNativeBluetoothService[]>;
+    read(serviceUuid: string, characteristicUuid: string, options?: NativeHardwareBridgeOptions): Promise<DataView>;
+    write(serviceUuid: string, characteristicUuid: string, data: BufferSource, options?: NativeHardwareBridgeOptions & {
+        withResponse?: boolean;
+    }): Promise<void>;
+    observe(serviceUuid: string, characteristicUuid: string, listener: (value: DataView) => void, options?: NativeHardwareBridgeOptions): Promise<() => Promise<void>>;
+    disconnect(options?: NativeHardwareBridgeOptions): Promise<void>;
+}
+/**
+ * Uses Web Bluetooth first, with a restrictive desktop BLE chooser fallback.
+ * The native branch mirrors physical disconnect and adapter-loss events.
+ */
+export declare function requestMoldableBluetoothWithFallback(options: MoldableBluetoothRequestDeviceOptions, bridgeOptions?: NativeHardwareBridgeOptions): Promise<MoldableBluetoothTransport>;
+//# sourceMappingURL=bluetooth-native-fallback.d.ts.map

package/dist/lib/native-hardware/bluetooth-native-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluetooth-native-fallback.d.ts","sourceRoot":"","sources":["../../../src/lib/native-hardware/bluetooth-native-fallback.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,uBAAuB,EACvB,qCAAqC,EACtC,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,KAAK,2BAA2B,EAEjC,MAAM,UAAU,CAAA;AAMjB,MAAM,MAAM,0BAA0B,GAClC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,6BAA6B,CAAA;CAAE,CAAA;AAErE,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,mBAAmB,EAAE,MAAM,EAAE,CAAA;CAC9B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,gBAAgB,CACd,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,EAAE,kCAAkC,EAC5C,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAA;IACP,mBAAmB,CACjB,IAAI,EAAE,wBAAwB,EAC9B,QAAQ,EAAE,kCAAkC,EAC5C,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,GACvC,IAAI,CAAA;IACP,WAAW,CACT,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,8BAA8B,EAAE,CAAC,CAAA;IAC5C,IAAI,CACF,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAC1B,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpB,KAAK,CACH,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAC1B,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,2BAA2B,GAAG;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,GACjE,OAAO,CAAC,IAAI,CAAC,CAAA;IAChB,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,EAC1B,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,EACnC,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/B,UAAU,CAAC,OAAO,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjE;AA2PD;;;GAGG;AACH,wBAAsB,oCAAoC,CACxD,OAAO,EAAE,qCAAqC,EAC9C,aAAa,GAAE,2BAAgC,GAC9C,OAAO,CAAC,0BAA0B,CAAC,CAsCrC"}