@moldable-ai/ui 0.2.18 → 0.2.20

package/dist/components/hardware/usb-panel.js

@@ -0,0 +1,363 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { RefreshCw, RotateCcw, Trash2, Usb } from 'lucide-react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { NativeHardwareBridgeError, clearMoldableUsbHalt, closeMoldableUsbDevice, forgetMoldableUsbDevice, getMoldableUsbDevices, openMoldableUsbDevice, readMoldableUsbControlTransfer, readMoldableUsbEndpoint, requestMoldableUsbDevice, resetMoldableUsbDevice, writeMoldableUsbControlTransfer, writeMoldableUsbEndpoint, } from '../../lib/native-hardware';
+import { Button } from '../ui/button';
+import { Input } from '../ui/input';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from '../ui/select';
+import { Spinner } from '../ui/spinner';
+import { CapabilityBadge } from './capability-badge';
+import { formatHexBytes, parseHexBytes, parseIntegerInput, } from './device-io-controls';
+import { DeviceList, DeviceListEmpty, DeviceListItem } from './device-list';
+import { HardwarePanel, HardwarePanelAction, HardwarePanelContent, HardwarePanelFooter, HardwarePanelHeader, HardwarePanelIcon, HardwarePanelTitle, } from './hardware-panel';
+import { Readout, ReadoutItem } from './readout';
+function toError(cause) {
+    return cause instanceof Error ? cause : new Error(String(cause));
+}
+function formatHexId(value) {
+    return `0x${value.toString(16).padStart(4, '0')}`;
+}
+function usbDeviceDescriptionId(device) {
+    return [
+        device.vendorId,
+        device.productId,
+        device.serialNumber ?? '',
+        device.productName ?? '',
+    ].join(':');
+}
+/**
+ * USB state machine behind `UsbDevicePanel`: granted-device enumeration,
+ * chooser requests, minimal-claim open/close tracking. Use directly to build
+ * custom USB UI on the same best-effort error handling.
+ */
+export function useMoldableUsb(options = {}) {
+    const [devices, setDevices] = useState([]);
+    const [status, setStatus] = useState('idle');
+    const [error, setError] = useState(null);
+    const [openDeviceIds, setOpenDeviceIds] = useState([]);
+    const [nativeDeviceChoices, setNativeDeviceChoices] = useState([]);
+    const openDevicesRef = useRef(new Map());
+    const idsRef = useRef(new WeakMap());
+    const idCounterRef = useRef(0);
+    const pendingSelectionRef = useRef(null);
+    const generationRef = useRef(0);
+    const unmountedRef = useRef(false);
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const deviceId = useCallback((device) => {
+        let id = idsRef.current.get(device);
+        if (!id) {
+            id = `usb-${++idCounterRef.current}`;
+            idsRef.current.set(device, id);
+        }
+        return id;
+    }, []);
+    const refresh = useCallback(async () => {
+        const generation = ++generationRef.current;
+        setStatus('loading');
+        setError(null);
+        try {
+            const known = await getMoldableUsbDevices();
+            if (generationRef.current !== generation)
+                return;
+            setDevices((previous) => [
+                ...known,
+                ...previous.filter((device) => openDevicesRef.current.has(deviceId(device)) &&
+                    !known.includes(device)),
+            ]);
+            setStatus('idle');
+        }
+        catch (cause) {
+            if (generationRef.current !== generation)
+                return;
+            if (cause instanceof NativeHardwareBridgeError &&
+                cause.code === 'unsupported') {
+                // No WebUSB enumeration here (native fallback runtime). Devices
+                // granted through `request` stay listed; this is not an error.
+                setStatus('idle');
+                return;
+            }
+            setError(toError(cause));
+            setStatus('error');
+        }
+    }, [deviceId]);
+    const handleDisconnect = useCallback((device) => {
+        if (unmountedRef.current)
+            return;
+        const id = deviceId(device);
+        const record = openDevicesRef.current.get(id);
+        if (record) {
+            device.removeEventListener('disconnect', record.onDisconnect);
+        }
+        openDevicesRef.current.delete(id);
+        setOpenDeviceIds((previous) => previous.filter((existing) => existing !== id));
+        setDevices((previous) => previous.filter((existing) => existing !== device));
+    }, [deviceId]);
+    const chooseNativeDevice = useCallback((devices) => new Promise((resolve, reject) => {
+        pendingSelectionRef.current = { devices, resolve, reject };
+        setNativeDeviceChoices(devices);
+    }), []);
+    const selectNativeDevice = useCallback((device) => {
+        const pending = pendingSelectionRef.current;
+        if (!pending || !pending.devices.includes(device))
+            return;
+        pendingSelectionRef.current = null;
+        setNativeDeviceChoices([]);
+        pending.resolve(device);
+    }, []);
+    const cancelNativeSelection = useCallback(() => {
+        const pending = pendingSelectionRef.current;
+        if (!pending)
+            return;
+        pendingSelectionRef.current = null;
+        setNativeDeviceChoices([]);
+        pending.reject(new NativeHardwareBridgeError({
+            code: 'cancelled',
+            message: 'USB device selection was cancelled.',
+            retryable: true,
+        }));
+    }, []);
+    const request = useCallback(async (filters) => {
+        const generation = ++generationRef.current;
+        setStatus('requesting');
+        setError(null);
+        try {
+            const device = await requestMoldableUsbDevice({
+                filters: filters ?? optionsRef.current.filters ?? [],
+                selectNativeDevice: optionsRef.current.selectNativeDevice ?? chooseNativeDevice,
+            });
+            if (generationRef.current !== generation)
+                return;
+            setDevices((previous) => previous.includes(device) ? previous : [...previous, device]);
+            setStatus('idle');
+            return device;
+        }
+        catch (cause) {
+            if (generationRef.current !== generation)
+                return;
+            if (cause instanceof NativeHardwareBridgeError &&
+                (cause.code === 'cancelled' || cause.code === 'aborted')) {
+                // The user dismissed the chooser; that is not an error state.
+                setStatus('idle');
+                return;
+            }
+            setError(toError(cause));
+            setStatus('error');
+        }
+    }, [chooseNativeDevice]);
+    const open = useCallback(async (device) => {
+        const id = deviceId(device);
+        if (openDevicesRef.current.has(id))
+            return;
+        try {
+            await openMoldableUsbDevice(device, optionsRef.current.openOptions);
+            if (unmountedRef.current) {
+                void closeMoldableUsbDevice(device, optionsRef.current.openOptions?.claimInterfaces).catch(() => undefined);
+                return;
+            }
+            const onDisconnect = () => handleDisconnect(device);
+            device.addEventListener('disconnect', onDisconnect, { once: true });
+            openDevicesRef.current.set(id, {
+                device,
+                onDisconnect,
+                releaseInterfaces: optionsRef.current.openOptions?.claimInterfaces ?? [],
+            });
+            setOpenDeviceIds((previous) => previous.includes(id) ? previous : [...previous, id]);
+            setError(null);
+            setStatus('idle');
+            optionsRef.current.onDeviceOpen?.(device);
+        }
+        catch (cause) {
+            if (unmountedRef.current)
+                return;
+            setError(toError(cause));
+            setStatus('error');
+        }
+    }, [deviceId, handleDisconnect]);
+    const close = useCallback(async (device) => {
+        const id = deviceId(device);
+        const record = openDevicesRef.current.get(id);
+        try {
+            await closeMoldableUsbDevice(device, record?.releaseInterfaces);
+            if (record) {
+                device.removeEventListener('disconnect', record.onDisconnect);
+            }
+            openDevicesRef.current.delete(id);
+            setOpenDeviceIds((previous) => previous.filter((existing) => existing !== id));
+            setError(null);
+            setStatus('idle');
+            return true;
+        }
+        catch (cause) {
+            if (record)
+                record.releaseInterfaces = [];
+            if (unmountedRef.current)
+                return false;
+            setError(toError(cause));
+            setStatus('error');
+            return false;
+        }
+    }, [deviceId]);
+    const runOperation = useCallback(async (operation) => {
+        setError(null);
+        try {
+            const result = await operation();
+            if (!unmountedRef.current)
+                setStatus('idle');
+            return result;
+        }
+        catch (cause) {
+            if (!unmountedRef.current) {
+                setError(toError(cause));
+                setStatus('error');
+            }
+            throw cause;
+        }
+    }, []);
+    const forget = useCallback(async (device) => {
+        const id = deviceId(device);
+        if ((openDevicesRef.current.has(id) || device.opened) &&
+            !(await close(device))) {
+            return false;
+        }
+        try {
+            await runOperation(() => forgetMoldableUsbDevice(device));
+            if (unmountedRef.current)
+                return false;
+            setDevices((previous) => previous.filter((known) => known !== device));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, [close, deviceId, runOperation]);
+    useEffect(() => {
+        unmountedRef.current = false;
+        void refresh();
+        const liveGeneration = generationRef;
+        const openDevices = openDevicesRef.current;
+        return () => {
+            unmountedRef.current = true;
+            liveGeneration.current++;
+            const pending = pendingSelectionRef.current;
+            pendingSelectionRef.current = null;
+            pending?.reject(new NativeHardwareBridgeError({
+                code: 'aborted',
+                message: 'USB device selection was interrupted.',
+                retryable: true,
+            }));
+            const stillOpen = [...openDevices.values()];
+            openDevices.clear();
+            for (const { device, onDisconnect, releaseInterfaces } of stillOpen) {
+                device.removeEventListener('disconnect', onDisconnect);
+                void closeMoldableUsbDevice(device, releaseInterfaces).catch(() => undefined);
+            }
+        };
+    }, [refresh]);
+    return {
+        devices,
+        status,
+        error,
+        openDeviceIds,
+        nativeDeviceChoices,
+        deviceId,
+        refresh,
+        request,
+        selectNativeDevice,
+        cancelNativeSelection,
+        open,
+        close,
+        forget,
+        readEndpoint: (device, endpoint, length) => runOperation(() => readMoldableUsbEndpoint(device, endpoint, length)),
+        writeEndpoint: (device, endpoint, data) => runOperation(() => writeMoldableUsbEndpoint(device, endpoint, data)),
+        readControl: (device, setup, length) => runOperation(() => readMoldableUsbControlTransfer(device, setup, length)),
+        writeControl: (device, setup, data) => runOperation(() => writeMoldableUsbControlTransfer(device, setup, data)),
+        clearHalt: (device, direction, endpoint) => runOperation(() => clearMoldableUsbHalt(device, direction, endpoint)),
+        reset: (device) => runOperation(() => resetMoldableUsbDevice(device)),
+    };
+}
+function UsbDeviceControls({ device, usb }) {
+    const [endpoint, setEndpoint] = useState('1');
+    const [length, setLength] = useState('64');
+    const [payload, setPayload] = useState('');
+    const [requestType, setRequestType] = useState('vendor');
+    const [recipient, setRecipient] = useState('device');
+    const [request, setRequest] = useState('0');
+    const [value, setValue] = useState('0');
+    const [index, setIndex] = useState('0');
+    const [result, setResult] = useState('Ready');
+    const [busy, setBusy] = useState(false);
+    const run = async (operation) => {
+        setBusy(true);
+        try {
+            setResult(await operation());
+        }
+        catch (cause) {
+            setResult(toError(cause).message);
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    const endpointNumber = () => parseIntegerInput(endpoint, 'Endpoint', 1, 15);
+    const transferLength = () => parseIntegerInput(length, 'Length', 1, 65_535);
+    const setup = () => ({
+        requestType,
+        recipient,
+        request: parseIntegerInput(request, 'Request', 0, 255),
+        value: parseIntegerInput(value, 'Value', 0, 65_535),
+        index: parseIntegerInput(index, 'Index', 0, 65_535),
+    });
+    return (_jsxs("div", { "data-slot": "usb-device-controls", className: "bg-muted/30 mt-2 space-y-3 rounded-md border p-2.5", children: [_jsxs("div", { className: "grid gap-2 sm:grid-cols-3", children: [_jsx(Input, { "aria-label": "USB endpoint number", value: endpoint, onChange: (event) => setEndpoint(event.target.value), placeholder: "Endpoint", className: "h-8 font-mono text-xs" }), _jsx(Input, { "aria-label": "USB transfer length", value: length, onChange: (event) => setLength(event.target.value), placeholder: "Length", className: "h-8 font-mono text-xs" }), _jsx(Input, { "aria-label": "USB endpoint payload", value: payload, onChange: (event) => setPayload(event.target.value), placeholder: "Hex payload", className: "h-8 font-mono text-xs" })] }), _jsxs("div", { className: "flex flex-wrap gap-1.5", children: [_jsx(Button, { size: "xs", variant: "outline", disabled: busy, onClick: () => void run(async () => {
+                            const transfer = await usb.readEndpoint(device, endpointNumber(), transferLength());
+                            return `Endpoint IN · ${transfer.status} · ${formatHexBytes(transfer.data)}`;
+                        }), children: "Endpoint IN" }), _jsx(Button, { size: "xs", variant: "outline", disabled: busy, onClick: () => void run(async () => {
+                            const transfer = await usb.writeEndpoint(device, endpointNumber(), parseHexBytes(payload));
+                            return `Endpoint OUT · ${transfer.status} · ${transfer.bytesWritten ?? 0} bytes`;
+                        }), children: "Endpoint OUT" }), _jsx(Button, { size: "xs", variant: "ghost", disabled: busy, onClick: () => void run(async () => {
+                            await usb.clearHalt(device, 'in', endpointNumber());
+                            return 'IN halt cleared';
+                        }), children: "Clear IN halt" }), _jsx(Button, { size: "xs", variant: "ghost", disabled: busy, onClick: () => void run(async () => {
+                            await usb.clearHalt(device, 'out', endpointNumber());
+                            return 'OUT halt cleared';
+                        }), children: "Clear OUT halt" })] }), _jsxs("div", { className: "grid gap-2 sm:grid-cols-5", children: [_jsxs(Select, { value: requestType, onValueChange: (next) => setRequestType(next), children: [_jsx(SelectTrigger, { size: "sm", "aria-label": "USB control request type", children: _jsx(SelectValue, {}) }), _jsxs(SelectContent, { children: [_jsx(SelectItem, { value: "standard", children: "Standard" }), _jsx(SelectItem, { value: "class", children: "Class" }), _jsx(SelectItem, { value: "vendor", children: "Vendor" })] })] }), _jsxs(Select, { value: recipient, onValueChange: (next) => setRecipient(next), children: [_jsx(SelectTrigger, { size: "sm", "aria-label": "USB control recipient", children: _jsx(SelectValue, {}) }), _jsxs(SelectContent, { children: [_jsx(SelectItem, { value: "device", children: "Device" }), _jsx(SelectItem, { value: "interface", children: "Interface" }), _jsx(SelectItem, { value: "endpoint", children: "Endpoint" }), _jsx(SelectItem, { value: "other", children: "Other" })] })] }), [
+                        ['Request', request, setRequest],
+                        ['Value', value, setValue],
+                        ['Index', index, setIndex],
+                    ].map(([label, current, update]) => (_jsx(Input, { "aria-label": `USB control ${String(label).toLowerCase()}`, value: current, onChange: (event) => update(event.target.value), placeholder: label, className: "h-8 font-mono text-xs" }, label)))] }), _jsxs("div", { className: "flex flex-wrap items-center gap-1.5", children: [_jsx(Button, { size: "xs", variant: "outline", disabled: busy, onClick: () => void run(async () => {
+                            const transfer = await usb.readControl(device, setup(), transferLength());
+                            return `Control IN · ${transfer.status} · ${formatHexBytes(transfer.data)}`;
+                        }), children: "Control IN" }), _jsx(Button, { size: "xs", variant: "outline", disabled: busy, onClick: () => void run(async () => {
+                            const transfer = await usb.writeControl(device, setup(), parseHexBytes(payload));
+                            return `Control OUT · ${transfer.status} · ${transfer.bytesWritten ?? 0} bytes`;
+                        }), children: "Control OUT" }), _jsxs(Button, { size: "xs", variant: "ghost", disabled: busy, onClick: () => void run(async () => {
+                            await usb.reset(device);
+                            return 'Device reset';
+                        }), children: [_jsx(RotateCcw, {}), "Reset"] }), _jsx("span", { className: "text-muted-foreground ml-auto truncate font-mono text-[10px]", children: busy ? 'Working…' : result })] })] }));
+}
+/**
+ * USB device panel: request access, list granted devices, open/close each
+ * with minimal claims, and read out live device details while open.
+ */
+function UsbDevicePanel({ className, filters, selectNativeDevice, openOptions, onDeviceOpen, ...props }) {
+    const usb = useMoldableUsb({
+        filters,
+        selectNativeDevice,
+        openOptions,
+        onDeviceOpen,
+    });
+    const requesting = usb.status === 'requesting';
+    const loading = usb.status === 'loading';
+    return (_jsxs(HardwarePanel, { "data-slot": "usb-device-panel", "data-status": usb.status, className: className, ...props, children: [_jsxs(HardwarePanelHeader, { children: [_jsx(HardwarePanelIcon, { children: _jsx(Usb, {}) }), _jsx(HardwarePanelTitle, { children: "USB" }), _jsx(CapabilityBadge, { capability: "usb" }), _jsxs(HardwarePanelAction, { children: [_jsxs(Button, { size: "sm", disabled: requesting, onClick: () => void usb.request(), children: [requesting ? _jsx(Spinner, {}) : _jsx(Usb, {}), requesting ? 'Requesting…' : 'Request device'] }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Refresh devices", disabled: loading || requesting, onClick: () => void usb.refresh(), children: _jsx(RefreshCw, { className: loading ? 'animate-spin motion-reduce:animate-none' : undefined }) })] })] }), _jsxs(HardwarePanelContent, { children: [usb.nativeDeviceChoices.length > 0 ? (_jsxs("div", { "data-slot": "usb-native-device-picker", className: "bg-muted/30 mb-4 space-y-2 rounded-lg border p-3", children: [_jsx("p", { className: "text-sm font-medium", children: "Choose a USB device" }), _jsx("p", { className: "text-muted-foreground text-xs", children: "More than one native device matched. Select the device explicitly." }), _jsxs("div", { className: "flex flex-wrap gap-2", children: [usb.nativeDeviceChoices.map((device, index) => (_jsxs(Button, { size: "xs", variant: "outline", onClick: () => usb.selectNativeDevice(device), children: [device.productName || 'USB device', " \u00B7", ' ', formatHexId(device.vendorId), ":", formatHexId(device.productId)] }, `${usbDeviceDescriptionId(device)}:${index}`))), _jsx(Button, { size: "xs", variant: "ghost", onClick: usb.cancelNativeSelection, children: "Cancel" })] })] })) : null, _jsx(DeviceList, { children: usb.devices.length === 0 ? (_jsxs(DeviceListEmpty, { icon: _jsx(Usb, {}), children: [_jsx("span", { className: "font-medium", children: "No devices yet" }), _jsx("span", { className: "text-muted-foreground/70 text-xs", children: "Request access to a USB device to get started." })] })) : (usb.devices.map((device, index) => {
+                            const id = usb.deviceId(device);
+                            const open = usb.openDeviceIds.includes(id) || device.opened;
+                            return (_jsx(DeviceListItem, { icon: _jsx(Usb, {}), name: device.productName || 'USB device', description: `${formatHexId(device.vendorId)}:${formatHexId(device.productId)}` +
+                                    (device.manufacturerName
+                                        ? ` · ${device.manufacturerName}`
+                                        : ''), connected: open, action: _jsxs("div", { className: "flex items-center gap-1", children: [_jsx(Button, { size: "xs", variant: "outline", onClick: () => void (open ? usb.close(device) : usb.open(device)), children: open ? 'Close' : 'Open' }), _jsx(Button, { size: "icon-xs", variant: "ghost", "aria-label": `Forget ${device.productName || 'USB device'}`, onClick: () => void usb.forget(device), children: _jsx(Trash2, {}) })] }), children: open ? (_jsxs("div", { "data-slot": "usb-device-details", className: "animate-in fade-in slide-in-from-top-1 bg-muted/30 mt-2 rounded-md border p-2.5 duration-200 motion-reduce:animate-none", children: [_jsxs(Readout, { className: "gap-y-2 sm:grid-cols-4", children: [_jsx(ReadoutItem, { label: "Configuration", value: device.configuration?.configurationValue ?? null }), _jsx(ReadoutItem, { label: "Vendor ID", value: formatHexId(device.vendorId) }), _jsx(ReadoutItem, { label: "Product ID", value: formatHexId(device.productId) }), _jsx(ReadoutItem, { label: "Serial", value: device.serialNumber ?? null })] }), _jsx(UsbDeviceControls, { device: device, usb: usb })] })) : null }, `${id}:${index}`));
+                        })) })] }), _jsxs(HardwarePanelFooter, { children: [usb.error ? (_jsx("span", { className: "text-status-error truncate", children: usb.error.message })) : (_jsx("span", { className: "truncate", children: usb.devices.length === 0
+                            ? 'No devices authorized'
+                            : `${usb.devices.length} device${usb.devices.length === 1 ? '' : 's'} known` })), _jsxs("span", { className: "ml-auto shrink-0 font-mono tabular-nums", children: [usb.openDeviceIds.length, " open"] })] })] }));
+}
+export { UsbDevicePanel };

package/dist/components/hardware/use-capability.d.ts

@@ -0,0 +1,20 @@
+import { type NativeHardwareCapabilityDescriptor, type NativeHardwareCapabilityId, type NativeHardwareCapabilityManifest } from '../../lib/native-hardware';
+export type MoldableCapabilityStatus = 'checking' | 'supported' | 'partial' | 'unsupported' | 'unavailable';
+/**
+ * Loads the native capability manifest once per page and shares it across all
+ * hardware components. Pass `force` to bypass the cache (e.g. after a grant).
+ */
+export declare function loadMoldableCapabilities(force?: boolean): Promise<NativeHardwareCapabilityManifest>;
+export interface MoldableCapability {
+    status: MoldableCapabilityStatus;
+    descriptor: NativeHardwareCapabilityDescriptor | null;
+    manifest: NativeHardwareCapabilityManifest | null;
+    error: Error | null;
+    refresh: () => void;
+}
+/**
+ * Reads the support level for one native capability. `unavailable` means the
+ * manifest could not be loaded at all (typically: not running inside Moldable).
+ */
+export declare function useMoldableCapability(id: NativeHardwareCapabilityId): MoldableCapability;
+//# sourceMappingURL=use-capability.d.ts.map

package/dist/components/hardware/use-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-capability.d.ts","sourceRoot":"","sources":["../../../src/components/hardware/use-capability.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,kCAAkC,EACvC,KAAK,0BAA0B,EAC/B,KAAK,gCAAgC,EAEtC,MAAM,2BAA2B,CAAA;AAElC,MAAM,MAAM,wBAAwB,GAChC,UAAU,GACV,WAAW,GACX,SAAS,GACT,aAAa,GACb,aAAa,CAAA;AAIjB;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,UAAQ,GACZ,OAAO,CAAC,gCAAgC,CAAC,CAU3C;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,wBAAwB,CAAA;IAChC,UAAU,EAAE,kCAAkC,GAAG,IAAI,CAAA;IACrD,QAAQ,EAAE,gCAAgC,GAAG,IAAI,CAAA;IACjD,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,0BAA0B,GAC7B,kBAAkB,CA2CpB"}

package/dist/components/hardware/use-capability.js

@@ -0,0 +1,61 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getMoldableNativeCapabilities, } from '../../lib/native-hardware';
+let manifestPromise = null;
+/**
+ * Loads the native capability manifest once per page and shares it across all
+ * hardware components. Pass `force` to bypass the cache (e.g. after a grant).
+ */
+export function loadMoldableCapabilities(force = false) {
+    if (force || !manifestPromise) {
+        manifestPromise = getMoldableNativeCapabilities().catch((error) => {
+            manifestPromise = null;
+            throw error;
+        });
+    }
+    return manifestPromise;
+}
+/**
+ * Reads the support level for one native capability. `unavailable` means the
+ * manifest could not be loaded at all (typically: not running inside Moldable).
+ */
+export function useMoldableCapability(id) {
+    const [manifest, setManifest] = useState(null);
+    const [error, setError] = useState(null);
+    const [checking, setChecking] = useState(true);
+    const generation = useRef(0);
+    const load = useCallback((force) => {
+        const current = ++generation.current;
+        setChecking(true);
+        setError(null);
+        loadMoldableCapabilities(force)
+            .then((value) => {
+            if (generation.current !== current)
+                return;
+            setManifest(value);
+            setChecking(false);
+        })
+            .catch((cause) => {
+            if (generation.current !== current)
+                return;
+            setManifest(null);
+            setError(cause instanceof Error ? cause : new Error(String(cause)));
+            setChecking(false);
+        });
+    }, []);
+    useEffect(() => {
+        load(false);
+        const liveGeneration = generation;
+        return () => {
+            liveGeneration.current++;
+        };
+    }, [load]);
+    const refresh = useCallback(() => load(true), [load]);
+    const descriptor = manifest ? manifest.capabilities[id] : null;
+    const status = checking
+        ? 'checking'
+        : descriptor
+            ? descriptor.support
+            : 'unavailable';
+    return { status, descriptor, manifest, error, refresh };
+}

package/dist/components/native-capabilities/bluetooth-panel-helpers.d.ts

@@ -0,0 +1,9 @@
+export type BluetoothSubscriptionCleanup = () => Promise<void>;
+/**
+ * Stops every active observer before returning. Successful entries are removed,
+ * while failed entries stay registered so the caller can retry cleanup.
+ */
+export declare function cleanupBluetoothSubscriptions(subscriptions: Map<string, BluetoothSubscriptionCleanup>): Promise<void>;
+/** Parses a compact or separator-delimited hexadecimal Bluetooth value. */
+export declare function parseBluetoothHexBytes(value: string): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=bluetooth-panel-helpers.d.ts.map

package/dist/components/native-capabilities/bluetooth-panel-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluetooth-panel-helpers.d.ts","sourceRoot":"","sources":["../../../src/components/native-capabilities/bluetooth-panel-helpers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,4BAA4B,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;AAE9D;;;GAGG;AACH,wBAAsB,6BAA6B,CACjD,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,4BAA4B,CAAC,GACvD,OAAO,CAAC,IAAI,CAAC,CAef;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAqB7E"}

package/dist/components/native-capabilities/bluetooth-panel-helpers.js

@@ -0,0 +1,37 @@
+/**
+ * Stops every active observer before returning. Successful entries are removed,
+ * while failed entries stay registered so the caller can retry cleanup.
+ */
+export async function cleanupBluetoothSubscriptions(subscriptions) {
+    const failures = [];
+    await Promise.all([...subscriptions].map(async ([key, stop]) => {
+        try {
+            await stop();
+            if (subscriptions.get(key) === stop)
+                subscriptions.delete(key);
+        }
+        catch (cause) {
+            failures.push(cause);
+        }
+    }));
+    if (failures.length > 0)
+        throw failures[0];
+}
+/** Parses a compact or separator-delimited hexadecimal Bluetooth value. */
+export function parseBluetoothHexBytes(value) {
+    const normalized = value
+        .trim()
+        .replace(/0x/gi, '')
+        .replace(/[\s,:-]+/g, '');
+    if (normalized.length === 0) {
+        throw new TypeError('Enter at least one hexadecimal byte.');
+    }
+    if (normalized.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(normalized)) {
+        throw new TypeError('Use complete hexadecimal bytes, such as 01 A0 FF.');
+    }
+    const bytes = new Uint8Array(new ArrayBuffer(normalized.length / 2));
+    for (let index = 0; index < bytes.length; index++) {
+        bytes[index] = Number.parseInt(normalized.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+}

package/dist/components/native-capabilities/bluetooth-panel.d.ts

@@ -0,0 +1,56 @@
+import * as React from 'react';
+import { type MoldableBluetoothConnection, type MoldableBluetoothDevice, type MoldableBluetoothRemoteGATTCharacteristic, type MoldableNativeBluetoothDevice } from '../../lib/native-capabilities';
+export type MoldableBluetoothStatus = 'idle' | 'requesting' | 'connecting' | 'connected' | 'error';
+export interface MoldableBluetoothCharacteristicInfo {
+    serviceUuid: string;
+    uuid: string;
+    /** Property names when the runtime exposes them; empty when unknown. */
+    properties: string[];
+    /** Web Bluetooth handle; null on the desktop bridge (UUIDs drive I/O). */
+    characteristic: MoldableBluetoothRemoteGATTCharacteristic | null;
+}
+export interface MoldableBluetoothServiceInfo {
+    uuid: string;
+    characteristics: MoldableBluetoothCharacteristicInfo[];
+}
+export interface UseMoldableBluetoothOptions {
+    onValue?: (characteristic: MoldableBluetoothCharacteristicInfo, value: DataView) => void;
+}
+/**
+ * Bluetooth LE state machine behind `BluetoothPanel`. Handles both transports
+ * returned by `requestMoldableBluetoothWithFallback`: Web Bluetooth (GATT
+ * connection + service discovery) and the desktop bridge (UUID-addressed I/O
+ * on an already-connected device).
+ */
+export declare function useMoldableBluetooth(options?: UseMoldableBluetoothOptions): {
+    status: MoldableBluetoothStatus;
+    device: MoldableBluetoothDevice | MoldableNativeBluetoothDevice | null;
+    connection: MoldableBluetoothConnection | null;
+    disconnecting: boolean;
+    services: MoldableBluetoothServiceInfo[];
+    subscribedUuids: string[];
+    error: Error | null;
+    entries: import("./stream-log").StreamLogEntry[];
+    request: (serviceUuid?: string) => Promise<void>;
+    connect: () => Promise<void>;
+    disconnect: () => Promise<void>;
+    read: (characteristic: MoldableBluetoothCharacteristicInfo) => Promise<void>;
+    subscribe: (characteristic: MoldableBluetoothCharacteristicInfo) => Promise<void>;
+    unsubscribe: (characteristic: MoldableBluetoothCharacteristicInfo) => Promise<void>;
+    write: (characteristic: MoldableBluetoothCharacteristicInfo, bytes: BufferSource) => Promise<void>;
+    writeHex: (characteristic: MoldableBluetoothCharacteristicInfo, value: string) => Promise<void>;
+    clearEntries: () => void;
+};
+export interface BluetoothPanelProps extends React.ComponentProps<'div'> {
+    /** Prefill and scope scanning/discovery to one GATT service UUID. */
+    serviceUuid?: string;
+    onValue?: (characteristic: MoldableBluetoothCharacteristicInfo, value: DataView) => void;
+}
+/**
+ * Bluetooth LE panel: scan (optionally scoped to a service UUID), connect,
+ * browse discovered characteristics, and read, write, or subscribe to values
+ * with a live hex log.
+ */
+declare function BluetoothPanel({ className, serviceUuid, onValue, ...props }: BluetoothPanelProps): import("react/jsx-runtime").JSX.Element;
+export { BluetoothPanel };
+//# sourceMappingURL=bluetooth-panel.d.ts.map

package/dist/components/native-capabilities/bluetooth-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bluetooth-panel.d.ts","sourceRoot":"","sources":["../../../src/components/native-capabilities/bluetooth-panel.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EACL,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,EAC5B,KAAK,yCAAyC,EAG9C,KAAK,6BAA6B,EAQnC,MAAM,+BAA+B,CAAA;AAqBtC,MAAM,MAAM,uBAAuB,GAC/B,MAAM,GACN,YAAY,GACZ,YAAY,GACZ,WAAW,GACX,OAAO,CAAA;AAgDX,MAAM,WAAW,mCAAmC;IAClD,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,0EAA0E;IAC1E,cAAc,EAAE,yCAAyC,GAAG,IAAI,CAAA;CACjE;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,eAAe,EAAE,mCAAmC,EAAE,CAAA;CACvD;AA+ED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,CAAC,EAAE,CACR,cAAc,EAAE,mCAAmC,EACnD,KAAK,EAAE,QAAQ,KACZ,IAAI,CAAA;CACV;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC;;;;;;;;;4BAkJlB,MAAM;;;2BAiDJ,mCAAmC;gCA0BnC,mCAAmC;kCAqCnC,mCAAmC;4BAqBxC,mCAAmC,SAC5C,YAAY;+BAmCH,mCAAmC,SAC5C,MAAM;;EAsClB;AAED,MAAM,WAAW,mBAAoB,SAAQ,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC;IACtE,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,CACR,cAAc,EAAE,mCAAmC,EACnD,KAAK,EAAE,QAAQ,KACZ,IAAI,CAAA;CACV;AAED;;;;GAIG;AACH,iBAAS,cAAc,CAAC,EACtB,SAAS,EACT,WAAW,EACX,OAAO,EACP,GAAG,KAAK,EACT,EAAE,mBAAmB,2CAiPrB;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}