@moldable-ai/ui 0.2.18 → 0.2.20

package/dist/lib/native-hardware/usb-native.js

@@ -0,0 +1,217 @@
+import { NativeHardwareBridgeError } from './bridge';
+import { bytesFromNativeDeviceResult, bytesWrittenFromNativeDeviceResult, closeMoldableNativeDevice, executeMoldableNativeDeviceOperation, openMoldableNativeDevice, } from './native-device-io';
+import { NativeDeviceLifecycle, isNativeDeviceDisconnect, } from './native-device-lifecycle';
+const DEFAULT_TIMEOUT_MS = 10_000;
+export class NativeMoldableUsbDevice extends EventTarget {
+    descriptor;
+    vendorId;
+    productId;
+    productName;
+    manufacturerName = null;
+    serialNumber = null;
+    configuration = null;
+    handle;
+    closing;
+    lifecycle = new NativeDeviceLifecycle();
+    constructor(descriptor) {
+        super();
+        this.descriptor = descriptor;
+        this.vendorId = descriptor.vendorId ?? 0;
+        this.productId = descriptor.productId ?? 0;
+        this.productName = descriptor.label;
+    }
+    get opened() {
+        return this.lifecycle.opened;
+    }
+    async openWithOptions(options) {
+        if (this.closing)
+            await this.closing;
+        if (this.handle && this.lifecycle.disconnected)
+            await this.close();
+        if (this.opened)
+            return;
+        const opened = await openMoldableNativeDevice('usb', this.descriptor.selector, {
+            ...(options.configurationValue === undefined
+                ? {}
+                : { usbConfiguration: options.configurationValue }),
+            usbInterfaces: [...(options.claimInterfaces ?? [])],
+        });
+        if (opened.kind !== 'usb')
+            throw new Error('Native device kind mismatch.');
+        this.handle = opened.handle;
+        this.lifecycle.didOpen();
+        if (options.configurationValue !== undefined) {
+            this.configuration = { configurationValue: options.configurationValue };
+        }
+    }
+    async open() {
+        await this.openWithOptions({});
+    }
+    async close() {
+        if (this.closing)
+            return this.closing;
+        if (!this.handle)
+            return;
+        const handle = this.handle;
+        const closing = closeMoldableNativeDevice('usb', handle)
+            .then(() => {
+            if (this.handle === handle) {
+                this.handle = undefined;
+                this.configuration = null;
+                this.lifecycle.didClose();
+            }
+        })
+            .finally(() => {
+            if (this.closing === closing)
+                this.closing = undefined;
+        });
+        this.closing = closing;
+        return closing;
+    }
+    async forget() {
+        await this.close();
+    }
+    async selectConfiguration() {
+        throw this.reopenRequired('select a USB configuration');
+    }
+    async claimInterface() {
+        throw this.reopenRequired('claim a USB interface');
+    }
+    async releaseInterface() {
+        throw this.reopenRequired('release a USB interface');
+    }
+    async transferIn(endpointNumber, length) {
+        return this.transferInWithOptions(endpointNumber, length);
+    }
+    async transferInWithOptions(endpointNumber, length, options = {}) {
+        const result = await this.execute({
+            action: 'read',
+            endpoint: nativeUsbEndpointAddress(endpointNumber, 'in'),
+            length,
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            bulk: options.transferType === 'bulk',
+        }, options.signal);
+        const bytes = bytesFromNativeDeviceResult(result);
+        return {
+            status: 'ok',
+            data: new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+        };
+    }
+    async transferOut(endpointNumber, data) {
+        return this.transferOutWithOptions(endpointNumber, data);
+    }
+    async transferOutWithOptions(endpointNumber, data, options = {}) {
+        const result = await this.execute({
+            action: 'write',
+            endpoint: nativeUsbEndpointAddress(endpointNumber, 'out'),
+            data: [...asBytes(data)],
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+            bulk: options.transferType === 'bulk',
+        }, options.signal);
+        return {
+            status: 'ok',
+            bytesWritten: bytesWrittenFromNativeDeviceResult(result),
+        };
+    }
+    async controlTransferIn(setup, length) {
+        return this.controlTransferInWithOptions(setup, length);
+    }
+    async controlTransferInWithOptions(setup, length, options = {}) {
+        const result = await this.execute({
+            action: 'usbControlIn',
+            requestType: controlRequestType(setup, true),
+            request: setup.request,
+            value: setup.value,
+            index: setup.index,
+            length,
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        }, options.signal);
+        const bytes = bytesFromNativeDeviceResult(result);
+        return {
+            status: 'ok',
+            data: new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+        };
+    }
+    async controlTransferOut(setup, data = new Uint8Array()) {
+        return this.controlTransferOutWithOptions(setup, data);
+    }
+    async controlTransferOutWithOptions(setup, data = new Uint8Array(), options = {}) {
+        const result = await this.execute({
+            action: 'usbControlOut',
+            requestType: controlRequestType(setup, false),
+            request: setup.request,
+            value: setup.value,
+            index: setup.index,
+            data: [...asBytes(data)],
+            timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        }, options.signal);
+        return {
+            status: 'ok',
+            bytesWritten: bytesWrittenFromNativeDeviceResult(result),
+        };
+    }
+    async clearHalt(direction, endpointNumber) {
+        await this.execute({
+            action: 'clearUsbHalt',
+            endpoint: nativeUsbEndpointAddress(endpointNumber, direction),
+        });
+    }
+    async reset() {
+        await this.execute({ action: 'resetUsb' });
+    }
+    async execute(operation, signal) {
+        if (!this.handle) {
+            throw new NativeHardwareBridgeError({
+                code: 'invalid_request',
+                message: 'USB device is not open.',
+            });
+        }
+        if (this.lifecycle.disconnected) {
+            throw new NativeHardwareBridgeError({
+                code: 'unavailable',
+                message: 'USB device is disconnected.',
+                retryable: true,
+            });
+        }
+        try {
+            return await executeMoldableNativeDeviceOperation('usb', this.handle, operation, { signal });
+        }
+        catch (error) {
+            if (isNativeDeviceDisconnect(error)) {
+                this.lifecycle.didDisconnect(this, error);
+            }
+            throw error;
+        }
+    }
+    reopenRequired(action) {
+        return new NativeHardwareBridgeError({
+            code: 'invalid_request',
+            message: `Close and reopen the native USB device to ${action}.`,
+        });
+    }
+}
+export function isNativeMoldableUsbDevice(device) {
+    return device instanceof NativeMoldableUsbDevice;
+}
+function asBytes(data) {
+    return data instanceof ArrayBuffer
+        ? new Uint8Array(data)
+        : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+function nativeUsbEndpointAddress(endpointNumber, direction) {
+    if (!Number.isInteger(endpointNumber) ||
+        endpointNumber < 1 ||
+        endpointNumber > 15) {
+        throw new NativeHardwareBridgeError({
+            code: 'invalid_request',
+            message: 'USB endpointNumber must be an integer between 1 and 15.',
+            retryable: false,
+        });
+    }
+    return direction === 'in' ? endpointNumber | 0x80 : endpointNumber;
+}
+function controlRequestType(setup, input) {
+    const type = { standard: 0, class: 1, vendor: 2 }[setup.requestType] << 5;
+    const recipient = { device: 0, interface: 1, endpoint: 2, other: 3 }[setup.recipient];
+    return (input ? 0x80 : 0) | type | recipient;
+}

package/dist/lib/native-hardware/usb.d.ts

@@ -0,0 +1,85 @@
+export interface MoldableUsbOperationOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    transferType?: 'interrupt' | 'bulk';
+}
+export interface MoldableUsbDeviceFilter {
+    vendorId?: number;
+    productId?: number;
+    classCode?: number;
+    subclassCode?: number;
+    protocolCode?: number;
+    serialNumber?: string;
+}
+export interface MoldableUsbConfiguration {
+    configurationValue: number;
+}
+export interface MoldableUsbInTransferResult {
+    data?: DataView | null;
+    status: 'ok' | 'stall' | 'babble';
+}
+export interface MoldableUsbOutTransferResult {
+    bytesWritten?: number;
+    status: 'ok' | 'stall' | 'babble';
+}
+export interface MoldableUsbControlTransferParameters {
+    requestType: 'standard' | 'class' | 'vendor';
+    recipient: 'device' | 'interface' | 'endpoint' | 'other';
+    request: number;
+    value: number;
+    index: number;
+}
+/** Structural subset of the standard USBDevice interface used by the helpers. */
+export interface MoldableUsbDevice extends EventTarget {
+    readonly opened: boolean;
+    readonly vendorId: number;
+    readonly productId: number;
+    readonly productName?: string | null;
+    readonly manufacturerName?: string | null;
+    readonly serialNumber?: string | null;
+    readonly configuration?: MoldableUsbConfiguration | null;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    forget?(): Promise<void>;
+    selectConfiguration(configurationValue: number): Promise<void>;
+    claimInterface(interfaceNumber: number): Promise<void>;
+    releaseInterface(interfaceNumber: number): Promise<void>;
+    transferIn(endpointNumber: number, length: number): Promise<MoldableUsbInTransferResult>;
+    transferOut(endpointNumber: number, data: BufferSource): Promise<MoldableUsbOutTransferResult>;
+    controlTransferIn(setup: MoldableUsbControlTransferParameters, length: number): Promise<MoldableUsbInTransferResult>;
+    controlTransferOut(setup: MoldableUsbControlTransferParameters, data?: BufferSource): Promise<MoldableUsbOutTransferResult>;
+    clearHalt(direction: 'in' | 'out', endpointNumber: number): Promise<void>;
+    reset(): Promise<void>;
+}
+export interface MoldableUsbRequestOptions extends MoldableUsbOperationOptions {
+    filters: readonly MoldableUsbDeviceFilter[];
+    exclusionFilters?: readonly MoldableUsbDeviceFilter[];
+    /** Required when multiple native fallback devices match. Render a user choice. */
+    selectNativeDevice?: (devices: readonly MoldableUsbDevice[]) => MoldableUsbDevice | Promise<MoldableUsbDevice>;
+}
+export interface MoldableUsbOpenOptions {
+    configurationValue?: number;
+    claimInterfaces?: readonly number[];
+}
+/** Returns true only when this WebView exposes the WebUSB entry point. */
+export declare function isMoldableUsbSupported(): boolean;
+/** Lists devices previously authorized through WebUSB. */
+export declare function getMoldableUsbDevices(): Promise<MoldableUsbDevice[]>;
+/**
+ * Shows the browser's USB chooser. Call this directly from a user gesture.
+ * Aborting stops awaiting the result but cannot dismiss every browser chooser.
+ */
+export declare function requestMoldableUsbDevice(options: MoldableUsbRequestOptions): Promise<MoldableUsbDevice>;
+/** Opens, optionally configures, and claims interfaces on a USB device. */
+export declare function openMoldableUsbDevice(device: MoldableUsbDevice, options?: MoldableUsbOpenOptions): Promise<void>;
+/** Releases the selected interfaces and closes an open USB device. */
+export declare function closeMoldableUsbDevice(device: MoldableUsbDevice, releaseInterfaces?: readonly number[]): Promise<void>;
+/** Revokes the saved permission when the runtime supports USBDevice.forget(). */
+export declare function forgetMoldableUsbDevice(device: MoldableUsbDevice): Promise<void>;
+export declare function readMoldableUsbEndpoint(device: MoldableUsbDevice, endpointNumber: number, length: number, options?: MoldableUsbOperationOptions): Promise<MoldableUsbInTransferResult>;
+export declare function writeMoldableUsbEndpoint(device: MoldableUsbDevice, endpointNumber: number, data: BufferSource, options?: MoldableUsbOperationOptions): Promise<MoldableUsbOutTransferResult>;
+export declare function readMoldableUsbControlTransfer(device: MoldableUsbDevice, setup: MoldableUsbControlTransferParameters, length: number, options?: MoldableUsbOperationOptions): Promise<MoldableUsbInTransferResult>;
+export declare function writeMoldableUsbControlTransfer(device: MoldableUsbDevice, setup: MoldableUsbControlTransferParameters, data?: BufferSource, options?: MoldableUsbOperationOptions): Promise<MoldableUsbOutTransferResult>;
+export declare function clearMoldableUsbHalt(device: MoldableUsbDevice, direction: 'in' | 'out', endpointNumber: number): Promise<void>;
+export declare function resetMoldableUsbDevice(device: MoldableUsbDevice): Promise<void>;
+//# sourceMappingURL=usb.d.ts.map

package/dist/lib/native-hardware/usb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usb.d.ts","sourceRoot":"","sources":["../../../src/lib/native-hardware/usb.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,2BAA2B;IAC1C,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;CACpC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;IACtB,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAA;CAClC;AAED,MAAM,WAAW,4BAA4B;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAA;CAClC;AAED,MAAM,WAAW,oCAAoC;IACnD,WAAW,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC5C,SAAS,EAAE,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,CAAA;IACxD,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAA;IACxD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,mBAAmB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9D,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,gBAAgB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,UAAU,CACR,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,2BAA2B,CAAC,CAAA;IACvC,WAAW,CACT,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,4BAA4B,CAAC,CAAA;IACxC,iBAAiB,CACf,KAAK,EAAE,oCAAoC,EAC3C,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,2BAA2B,CAAC,CAAA;IACvC,kBAAkB,CAChB,KAAK,EAAE,oCAAoC,EAC3C,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC,4BAA4B,CAAC,CAAA;IACxC,SAAS,CAAC,SAAS,EAAE,IAAI,GAAG,KAAK,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAcD,MAAM,WAAW,yBAA0B,SAAQ,2BAA2B;IAC5E,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAA;IAC3C,gBAAgB,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAA;IACrD,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,CACnB,OAAO,EAAE,SAAS,iBAAiB,EAAE,KAClC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;CACpD;AAED,MAAM,WAAW,sBAAsB;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAiCD,0EAA0E;AAC1E,wBAAgB,sBAAsB,IAAI,OAAO,CAIhD;AAED,0DAA0D;AAC1D,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAS1E;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,iBAAiB,CAAC,CAsF5B;AAED,2EAA2E;AAC3E,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CA6Bf;AAED,sEAAsE;AACtE,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,iBAAiB,EACzB,iBAAiB,GAAE,SAAS,MAAM,EAAO,GACxC,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,iFAAiF;AACjF,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,iBAAiB,EACzB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,2BAA2B,CAAC,CActC;AAED,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,iBAAiB,EACzB,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,YAAY,EAClB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,4BAA4B,CAAC,CAcvC;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,oCAAoC,EAC3C,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,2BAA2B,CAAC,CActC;AAED,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,oCAAoC,EAC3C,IAAI,CAAC,EAAE,YAAY,EACnB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,4BAA4B,CAAC,CAcvC;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,iBAAiB,EACzB,SAAS,EAAE,IAAI,GAAG,KAAK,EACvB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/lib/native-hardware/usb.js

@@ -0,0 +1,222 @@
+import { NativeHardwareBridgeError } from './bridge';
+import { awaitDeviceIoWithAbort, deviceIoError, unsupportedDeviceIoError, } from './device-io-errors';
+import { listMoldableNativeDevices } from './native-device-io';
+import { NativeMoldableUsbDevice, isNativeMoldableUsbDevice, } from './usb-native';
+function assertNativeUsbFiltersSupported(filters) {
+    if (filters?.some((filter) => filter.classCode !== undefined ||
+        filter.subclassCode !== undefined ||
+        filter.protocolCode !== undefined ||
+        filter.serialNumber !== undefined)) {
+        throw new NativeHardwareBridgeError({
+            code: 'unsupported',
+            message: 'The native USB fallback can only match vendorId and productId filters on this platform.',
+            retryable: false,
+        });
+    }
+}
+function usbApi() {
+    const api = typeof navigator === 'undefined'
+        ? undefined
+        : navigator.usb;
+    if (!api)
+        throw unsupportedDeviceIoError('usb');
+    return api;
+}
+/** Returns true only when this WebView exposes the WebUSB entry point. */
+export function isMoldableUsbSupported() {
+    return (typeof navigator !== 'undefined' && !!navigator.usb);
+}
+/** Lists devices previously authorized through WebUSB. */
+export async function getMoldableUsbDevices() {
+    if (!isMoldableUsbSupported()) {
+        throw unsupportedDeviceIoError('usb');
+    }
+    try {
+        return await usbApi().getDevices();
+    }
+    catch (error) {
+        throw deviceIoError('usb', 'enumerate', error);
+    }
+}
+/**
+ * Shows the browser's USB chooser. Call this directly from a user gesture.
+ * Aborting stops awaiting the result but cannot dismiss every browser chooser.
+ */
+export async function requestMoldableUsbDevice(options) {
+    if (!isMoldableUsbSupported()) {
+        assertNativeUsbFiltersSupported(options.filters);
+        assertNativeUsbFiltersSupported(options.exclusionFilters);
+        const descriptors = await listMoldableNativeDevices('usb', {
+            signal: options.signal,
+            filters: options.filters.map(({ vendorId, productId }) => ({
+                vendorId,
+                productId,
+            })),
+            ...(options.exclusionFilters
+                ? {
+                    exclusionFilters: options.exclusionFilters.map(({ vendorId, productId }) => ({ vendorId, productId })),
+                }
+                : {}),
+        });
+        const devices = descriptors
+            .filter((descriptor) => options.filters.length === 0
+            ? true
+            : options.filters.some((filter) => (filter.vendorId === undefined ||
+                filter.vendorId === descriptor.vendorId) &&
+                (filter.productId === undefined ||
+                    filter.productId === descriptor.productId)))
+            .filter((descriptor) => !options.exclusionFilters?.some((filter) => (filter.vendorId === undefined ||
+            filter.vendorId === descriptor.vendorId) &&
+            (filter.productId === undefined ||
+                filter.productId === descriptor.productId)))
+            .map((descriptor) => new NativeMoldableUsbDevice(descriptor));
+        if (devices.length === 0) {
+            throw deviceIoError('usb', 'request', new DOMException('No matching USB device is available.', 'NotFoundError'));
+        }
+        if (devices.length === 1)
+            return devices[0];
+        if (!options.selectNativeDevice) {
+            throw deviceIoError('usb', 'request', new TypeError('A native device selector is required when multiple USB devices match.'));
+        }
+        const selected = await options.selectNativeDevice(devices);
+        if (!devices.includes(selected)) {
+            throw deviceIoError('usb', 'request', new TypeError('Invalid native USB selection.'));
+        }
+        return selected;
+    }
+    try {
+        return await awaitDeviceIoWithAbort(usbApi().requestDevice({
+            filters: [...options.filters],
+            ...(options.exclusionFilters
+                ? { exclusionFilters: [...options.exclusionFilters] }
+                : {}),
+        }), 'usb', 'request', options.signal);
+    }
+    catch (error) {
+        throw deviceIoError('usb', 'request', error);
+    }
+}
+/** Opens, optionally configures, and claims interfaces on a USB device. */
+export async function openMoldableUsbDevice(device, options = {}) {
+    if (isNativeMoldableUsbDevice(device)) {
+        await device.openWithOptions(options);
+        return;
+    }
+    const openedHere = !device.opened;
+    const claimed = [];
+    try {
+        if (openedHere)
+            await device.open();
+        if (options.configurationValue !== undefined &&
+            device.configuration?.configurationValue !== options.configurationValue) {
+            await device.selectConfiguration(options.configurationValue);
+        }
+        for (const interfaceNumber of options.claimInterfaces ?? []) {
+            await device.claimInterface(interfaceNumber);
+            claimed.push(interfaceNumber);
+        }
+    }
+    catch (error) {
+        await Promise.allSettled(claimed.map((interfaceNumber) => device.releaseInterface(interfaceNumber)));
+        if (openedHere)
+            await device.close().catch(() => undefined);
+        throw deviceIoError('usb', 'open', error);
+    }
+}
+/** Releases the selected interfaces and closes an open USB device. */
+export async function closeMoldableUsbDevice(device, releaseInterfaces = []) {
+    if (isNativeMoldableUsbDevice(device)) {
+        await device.close();
+        return;
+    }
+    let firstError;
+    for (const interfaceNumber of releaseInterfaces) {
+        try {
+            await device.releaseInterface(interfaceNumber);
+        }
+        catch (error) {
+            firstError ??= error;
+        }
+    }
+    try {
+        if (device.opened)
+            await device.close();
+    }
+    catch (error) {
+        firstError ??= error;
+    }
+    if (firstError)
+        throw deviceIoError('usb', 'close', firstError);
+}
+/** Revokes the saved permission when the runtime supports USBDevice.forget(). */
+export async function forgetMoldableUsbDevice(device) {
+    if (typeof device.forget !== 'function') {
+        throw unsupportedDeviceIoError('usb');
+    }
+    try {
+        await device.forget();
+    }
+    catch (error) {
+        throw deviceIoError('usb', 'close', error);
+    }
+}
+export async function readMoldableUsbEndpoint(device, endpointNumber, length, options = {}) {
+    if (isNativeMoldableUsbDevice(device)) {
+        return device.transferInWithOptions(endpointNumber, length, options);
+    }
+    try {
+        return await awaitDeviceIoWithAbort(device.transferIn(endpointNumber, length), 'usb', 'read', options.signal);
+    }
+    catch (error) {
+        throw deviceIoError('usb', 'read', error);
+    }
+}
+export async function writeMoldableUsbEndpoint(device, endpointNumber, data, options = {}) {
+    if (isNativeMoldableUsbDevice(device)) {
+        return device.transferOutWithOptions(endpointNumber, data, options);
+    }
+    try {
+        return await awaitDeviceIoWithAbort(device.transferOut(endpointNumber, data), 'usb', 'write', options.signal);
+    }
+    catch (error) {
+        throw deviceIoError('usb', 'write', error);
+    }
+}
+export async function readMoldableUsbControlTransfer(device, setup, length, options = {}) {
+    if (isNativeMoldableUsbDevice(device)) {
+        return device.controlTransferInWithOptions(setup, length, options);
+    }
+    try {
+        return await awaitDeviceIoWithAbort(device.controlTransferIn(setup, length), 'usb', 'read', options.signal);
+    }
+    catch (error) {
+        throw deviceIoError('usb', 'read', error);
+    }
+}
+export async function writeMoldableUsbControlTransfer(device, setup, data, options = {}) {
+    if (isNativeMoldableUsbDevice(device)) {
+        return device.controlTransferOutWithOptions(setup, data, options);
+    }
+    try {
+        return await awaitDeviceIoWithAbort(device.controlTransferOut(setup, data), 'usb', 'write', options.signal);
+    }
+    catch (error) {
+        throw deviceIoError('usb', 'write', error);
+    }
+}
+export async function clearMoldableUsbHalt(device, direction, endpointNumber) {
+    try {
+        await device.clearHalt(direction, endpointNumber);
+    }
+    catch (error) {
+        throw deviceIoError('usb', 'write', error);
+    }
+}
+export async function resetMoldableUsbDevice(device) {
+    try {
+        await device.reset();
+    }
+    catch (error) {
+        throw deviceIoError('usb', 'close', error);
+    }
+}

package/docs/README.md

@@ -0,0 +1,37 @@
+# Moldable UI design system
+
+`@moldable-ai/ui` is the shared renderer UI for Moldable desktop and generated
+apps. Its design goal is a quiet, information-dense personal instrument that
+feels at home on macOS without imitating private platform implementation.
+
+## Start here
+
+- [Foundations](./foundations.md)
+- [Design tokens](./design-tokens.md)
+- [App anatomy](./app-anatomy.md)
+- [Standalone app windows](./standalone-app-windows.md)
+- [Component catalog](./component-catalog.md)
+- [Accessibility](./accessibility.md)
+- [Native integration](./native-integration.md)
+- [Component guide template](./component-guide-template.md)
+
+Component-specific guides live beside their source in `src/components/ui`.
+Read the guide for every component family used in a new or substantially
+changed view.
+
+## Product rules
+
+1. Choose one app archetype and one primary object or workflow.
+2. Start standalone-capable apps with `AppFrame`; use `Panel`, `SplitView`,
+   `Toolbar`, and `Inspector` inside the app-owned canvas.
+3. Use `Text` and semantic theme colors for hierarchy.
+4. Prefer shared interactive controls over raw `button`, `input`, or `select`
+   elements.
+5. Keep chrome compact and give working content the available space.
+6. Install the shared frame lifecycle once. Put `--chat-safe-padding` on the
+   element that actually scrolls; it defaults to zero outside the embedded
+   host.
+7. Design loading, empty, error, disabled, and permission states with the main
+   view, not afterward.
+8. Review component work in the catalog across theme, density, width, and
+   interaction states.

package/docs/accessibility.md

@@ -0,0 +1,32 @@
+# Accessibility
+
+## Baseline
+
+- Give every icon-only action an accessible label and a short tooltip.
+- Use semantic headings in order. Visual typography does not determine heading
+  level.
+- Associate every field label, description, and error with its control.
+- Preserve native keyboard behavior unless the component documents a custom
+  interaction model.
+- Do not communicate status through color alone.
+
+## Keyboard
+
+Tab reaches controls in reading order. Arrow-key navigation belongs only to
+composite widgets that implement the complete expected pattern. Escape closes
+temporary surfaces and returns focus to their trigger.
+
+App-wide shortcuts should be registered through Moldable commands when they
+represent user actions. Do not hide essential behavior behind a shortcut.
+
+## Motion and transparency
+
+Animations must remain understandable with reduced motion. Translucent surfaces
+need an opaque semantic-color fallback for environments that reduce
+transparency.
+
+## State coverage
+
+Test the normal, hover, focus-visible, pressed, selected, disabled, loading,
+empty, invalid, permission-denied, and error states that apply. Check light and
+dark themes, keyboard-only operation, and a narrow pane.

package/docs/app-anatomy.md

@@ -0,0 +1,72 @@
+# App anatomy
+
+## Recommended window shell
+
+Apps should be able to own a dedicated window without changing their internal
+layout. `AppFrame` consumes host-owned safe-area variables and keeps the app
+canvas independent of the desktop shell.
+
+```tsx
+<AppFrame>
+  <AppFrameTitlebar>
+    <AppFrameToolbar>{/* title, view controls, primary actions */}</AppFrameToolbar>
+  </AppFrameTitlebar>
+  <AppFrameContent scrollable={false}>
+    {/* app-owned canvas and panes */}
+  </AppFrameContent>
+</AppFrame>
+```
+
+The host renders native window controls and drag regions. Do not draw those
+inside app UI.
+
+## Recommended pane shell
+
+```tsx
+<PanelGroup>
+  <Panel surface="sidebar" className="w-64">
+    <Toolbar>{/* navigation and search */}</Toolbar>
+    <PanelContent>{/* selectable list */}</PanelContent>
+  </Panel>
+  <Panel>
+    <Toolbar>{/* title and primary actions */}</Toolbar>
+    <PanelContent>{/* primary work */}</PanelContent>
+  </Panel>
+</PanelGroup>
+```
+
+Use `SplitView` when the user benefits from resizing panes. Use `PanelGroup`
+for fixed or responsive layouts. Do not nest both merely for styling.
+
+## Pane responsibilities
+
+- Sidebar: sources, navigation, saved views, and compact search.
+- Main pane: the user's primary object and dominant workflow.
+- Inspector: properties and secondary controls for the current selection.
+- Toolbar: current context and actions, never a second page header.
+
+Every pane must use `min-h-0 min-w-0`. The element containing long content owns
+`overflow-auto`; headers and footers remain fixed.
+
+## Chat clearance
+
+`installMoldableFrameLifecycle()` applies the embedded host's chat state to the
+shared token. `AppFrameContent` consumes it by default. In layouts that own
+their own scroll region, set `chatSafe={false}` on `AppFrameContent` and add
+`pb-[var(--chat-safe-padding)]` or an equivalent `calc()` only to that region.
+Do not pad every ancestor.
+
+The token is `0px` in a standalone app window. Chat belongs to the central
+orchestrator rather than being recreated inside every app.
+
+## Narrow widths
+
+Collapse optional inspectors before truncating the primary task. At narrow
+widths, preserve action reachability, focus order, and readable labels.
+
+## Multiwindow ownership
+
+Each app window owns its local navigation, selection, loading, empty, error,
+and save feedback. Workspace identity, app process lifecycle, native
+permissions, and orchestration remain host-owned. Never assume another visible
+window can supply a missing app state.