solid-drift 0.26.0 → 0.28.0

package/README.md

@@ -1571,6 +1571,52 @@ const prompt = createPrompt({
 - `createThinking(options?)` cycles `"Thinking"`, `"Thinking."`, ... through `phrases` at `interval` ms: `{ text, running, start, stop }`.
 - `createPrompt(options?)` is the voice-enabled input: `{ value, setValue, listening, interim, supported, toggleMic, submit, clear }`. Mic finals are appended to the value as they arrive; `submit()` fires `onSubmit` and clears by default. Everything is SSR-safe: unsupported primitives report `supported: false` and their actions no-op on the server.
 
+### Mobile hardware
+
+```tsx
+import { createBattery, createShare, createScanline } from "solid-drift";
+
+const battery = createBattery();
+const share = createShare();
+const scanline = createScanline({ duration: 1800 });
+
+scanline.start();
+// in your scanner viewfinder:
+// <div class="line" style={{ top: `${scanline.progress() * 100}%` }} />
+
+<p>Battery: {Math.round(battery.level() * 100)}% {battery.charging() ? "(charging)" : ""}</p>
+<button onClick={() => share.share({ title: "solid-drift", url: location.href })}>Share</button>
+```
+
+- `createBattery()` wraps `navigator.getBattery()`: `{ supported, charging, level, chargingTime, dischargingTime, error }`. Level is 0..1; times are seconds (`Infinity` when unknown). Listeners detach on cleanup.
+- `createNetwork()` tracks `navigator.onLine` plus the Network Information API: `{ online, effectiveType, downlink, rtt, saveData, supported }`. Updates on `online`/`offline` events and the connection `change` event.
+- `createWakeLock()` keeps the screen awake: `{ supported, active, error, request, release }`. Re-acquires automatically when the tab becomes visible again if the lock was still wanted.
+- `createContactPick()` wraps the Contact Picker API: `{ supported, contacts, error, pick }`. `pick({ multiple })` resolves with normalized `{ name, tel, email }` arrays, or an empty array when the user cancels.
+- `createOTP()` wraps the WebOTP API: `{ supported, code, error, wait, abort }`. `wait({ transport })` resolves with the SMS code (or `null` when aborted). Requires a secure origin and an origin-bound SMS format.
+- `createShare()` wraps the Web Share API: `{ supported, canShare, error, share }`. `share({ title, text, url, files })` opens the native sheet; user dismissal is not an error.
+- `createNFC()` wraps Web NFC (Chrome on Android, secure context, needs a user gesture): `{ supported, scanning, message, error, scan, write, abort }`. Scanned tags land in `message()` with decoded `text`/`url` records plus `serialNumber`; `write()` takes a string or `{ records }`.
+- `createTorch()` drives the camera flashlight: `{ supported, on, error, attach, set, toggle }`. `attach(trackOrStream)` checks the `torch` capability, then `set(true/false)` applies it via `applyConstraints`.
+- `createGyro()` wraps `deviceorientation`: `{ supported, needsPermission, alpha, beta, gamma, absolute, listening, error, requestPermission, start, stop }`. On iOS, call `requestPermission()` from a tap handler before `start()`; `start()` also requests it if needed.
+- `createShake(options?)` detects shake gestures from `devicemotion`: `{ supported, needsPermission, listening, shakes, error, requestPermission, start, stop }`. A shake counts when the acceleration delta exceeds `threshold` (default 15 m/s^2), rate-limited by `cooldown` (default 800ms); `onShake` fires per shake.
+- `createScanline(options?)` is the animated line of a QR/barcode viewfinder: `{ progress, running, start, stop }`. `progress()` sweeps 0..1 on the shared clock (`direction: "down" | "up" | "alternate"`); bind it to the line's position. Under reduced motion it freezes mid-frame. Every primitive is SSR-safe: server renders get `supported: false` and safe no-op actions.
+
+### Optimistic updates
+
+```tsx
+import { createOptimistic } from "solid-drift";
+
+const feed = createOptimistic<Bid[], Bid>([], (bids, bid) =>
+  bids.some((b) => b.id === bid.id) ? bids : [...bids, bid],
+);
+
+// in an event handler:
+await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
+  // already rolled back; read feed.error() for a toast
+});
+```
+
+`createOptimistic(initial, apply)` gives `{ value, setBase, pending, pendingCount, error, commit, reset }`. `commit(update, task)` applies the update instantly, then runs the task; on success the update is promoted into the base truth (no flicker while the server catches up), and on failure it is rolled back, `error()` is set, and the error is rethrown. `setBase()` folds fresh server truth in (after a refetch); write `apply` idempotently, for example upsert by id, so truth that already includes an optimistic update does not duplicate it. `reset()` drops in-flight updates. Pure signals, SSR-safe.
+
 ### Easings
 
 Named easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeOutExpo`, `easeOutBack`, plus the cartoon set: `easeInBack` (anticipation dip before movement), `easeInOutBack` (wind-up, overshoot, settle), `easeOutElastic` (decaying rubber-band oscillation), `easeOutBounce` (shrinking cartoon bounces). Also `cubicBezier(x1, y1, x2, y2)` for CSS-style curves. Pass a name or a custom `(t) => number` function anywhere an easing is accepted.

package/dist/hardware.d.ts

@@ -0,0 +1,207 @@
+export interface BatteryState {
+    supported: boolean;
+    charging: () => boolean;
+    level: () => number;
+    chargingTime: () => number;
+    dischargingTime: () => number;
+    error: () => Error | null;
+}
+/**
+ * createBattery
+ *
+ * Reactive wrapper around the Battery Status API (`navigator.getBattery`).
+ * Tracks charging state, level (0..1), and charge/discharge time in seconds.
+ */
+export declare function createBattery(): BatteryState;
+export interface NetworkState {
+    online: () => boolean;
+    effectiveType: () => string | undefined;
+    downlink: () => number | undefined;
+    rtt: () => number | undefined;
+    saveData: () => boolean;
+    supported: boolean;
+}
+/**
+ * createNetwork
+ *
+ * Reactive network status: `navigator.onLine` plus the Network Information
+ * API (`navigator.connection`) for effective type, downlink, RTT, and
+ * data-saver preference.
+ */
+export declare function createNetwork(): NetworkState;
+export interface WakeLockState {
+    supported: boolean;
+    active: () => boolean;
+    error: () => Error | null;
+    request: () => Promise<void>;
+    release: () => Promise<void>;
+}
+/**
+ * createWakeLock
+ *
+ * Keeps the screen awake with the Screen Wake Lock API. Re-acquires the lock
+ * automatically when the tab becomes visible again after a release.
+ */
+export declare function createWakeLock(): WakeLockState;
+export interface PickedContact {
+    name: string[];
+    tel: string[];
+    email: string[];
+}
+export interface ContactPickState {
+    supported: boolean;
+    contacts: () => PickedContact[];
+    error: () => Error | null;
+    pick: (options?: {
+        multiple?: boolean;
+    }) => Promise<PickedContact[]>;
+}
+/**
+ * createContactPick
+ *
+ * Contact Picker API (`navigator.contacts.select`). Resolves with the chosen
+ * contacts; empty array when the user cancels.
+ */
+export declare function createContactPick(): ContactPickState;
+export interface OTPState {
+    supported: boolean;
+    code: () => string | null;
+    error: () => Error | null;
+    wait: (options?: {
+        transport?: string[];
+    }) => Promise<string | null>;
+    abort: () => void;
+}
+/**
+ * createOTP
+ *
+ * WebOTP API: reads a one-time code from an incoming SMS without leaving the
+ * page. `wait()` resolves with the code (or null when aborted). Works only on
+ * secure origins where the SMS matches the site's origin-bound format.
+ */
+export declare function createOTP(): OTPState;
+export interface ShareState {
+    supported: boolean;
+    canShare: (data: ShareData) => boolean;
+    error: () => Error | null;
+    share: (data: ShareData) => Promise<void>;
+}
+/**
+ * createShare
+ *
+ * Web Share API: opens the native share sheet. `share()` resolves when the
+ * user completes or dismisses the sheet (dismissal is not an error).
+ */
+export declare function createShare(): ShareState;
+export interface NFCRecord {
+    recordType: string;
+    mediaType?: string;
+    text?: string;
+    url?: string;
+}
+export interface NFCMessage {
+    records: NFCRecord[];
+    serialNumber: string;
+}
+export interface NFCState {
+    supported: boolean;
+    scanning: () => boolean;
+    message: () => NFCMessage | null;
+    error: () => Error | null;
+    scan: () => Promise<void>;
+    write: (content: string | {
+        records: Array<Record<string, unknown>>;
+    }) => Promise<void>;
+    abort: () => void;
+}
+/**
+ * createNFC
+ *
+ * Web NFC (Chrome on Android, secure context): scan tags with `scan()` and
+ * read decoded records from `message`; write text or records with `write()`.
+ * Scanning needs a user gesture.
+ */
+export declare function createNFC(): NFCState;
+export interface TorchState {
+    supported: () => boolean;
+    on: () => boolean;
+    error: () => Error | null;
+    attach: (input: MediaStreamTrack | MediaStream) => void;
+    set: (value: boolean) => Promise<void>;
+    toggle: () => Promise<void>;
+}
+/**
+ * createTorch
+ *
+ * Camera flashlight for devices that expose the `torch` capability.
+ * Attach a video track (or stream) from `getUserMedia`, then `set()` or
+ * `toggle()` the flashlight.
+ */
+export declare function createTorch(): TorchState;
+export interface GyroState {
+    supported: boolean;
+    needsPermission: boolean;
+    alpha: () => number | null;
+    beta: () => number | null;
+    gamma: () => number | null;
+    absolute: () => boolean;
+    listening: () => boolean;
+    error: () => Error | null;
+    requestPermission: () => Promise<"granted" | "denied">;
+    start: () => Promise<void>;
+    stop: () => void;
+}
+/**
+ * createGyro
+ *
+ * Device orientation (alpha/beta/gamma in degrees). On iOS the motion
+ * permission prompt must come from a user gesture: call `requestPermission()`
+ * from a tap handler, then `start()`.
+ */
+export declare function createGyro(): GyroState;
+export interface ShakeOptions {
+    /** Acceleration delta (m/s^2) that counts as a shake. Default 15. */
+    threshold?: number;
+    /** Minimum milliseconds between shakes. Default 800. */
+    cooldown?: number;
+    onShake?: () => void;
+}
+export interface ShakeState {
+    supported: boolean;
+    needsPermission: boolean;
+    listening: () => boolean;
+    shakes: () => number;
+    error: () => Error | null;
+    requestPermission: () => Promise<"granted" | "denied">;
+    start: () => Promise<void>;
+    stop: () => void;
+}
+/**
+ * createShake
+ *
+ * Shake-to-undo style detection from `devicemotion`. Counts a shake when the
+ * acceleration delta exceeds `threshold`, rate-limited by `cooldown`.
+ */
+export declare function createShake(options?: ShakeOptions): ShakeState;
+export interface ScanlineOptions {
+    /** Milliseconds per sweep. Default 1800. */
+    duration?: number;
+    /** Sweep pattern. Default "alternate" (ping-pong). */
+    direction?: "down" | "up" | "alternate";
+}
+export interface ScanlineState {
+    /** Line position, 0 at the top edge and 1 at the bottom edge. */
+    progress: () => number;
+    running: () => boolean;
+    start: () => void;
+    stop: () => void;
+}
+/**
+ * createScanline
+ *
+ * The animated line of a camera viewfinder (QR/barcode scanning UI). Bind
+ * `progress()` to the line position, for example
+ * `style={{ top: `${progress() * 100}%` }}`. Runs on the shared clock and
+ * freezes mid-frame under reduced motion.
+ */
+export declare function createScanline(options?: ScanlineOptions): ScanlineState;

package/dist/hardware.js

@@ -0,0 +1,631 @@
+import { createSignal, onCleanup } from "solid-js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+import { schedule } from "./engine.js";
+const g = globalThis;
+function isClient() {
+    return typeof globalThis.window !== "undefined";
+}
+function getNavigator() {
+    return g["navigator"];
+}
+/** Attach a listener to the global scope (window in browsers). No-op on the server. */
+function onGlobalEvent(type, fn) {
+    const add = g["addEventListener"];
+    const remove = g["removeEventListener"];
+    if (!isClient() || typeof add !== "function" || typeof remove !== "function") {
+        return () => { };
+    }
+    add.call(globalThis, type, fn);
+    return () => remove.call(globalThis, type, fn);
+}
+function documentHidden() {
+    const doc = g["document"];
+    return doc?.hidden ?? false;
+}
+/**
+ * createBattery
+ *
+ * Reactive wrapper around the Battery Status API (`navigator.getBattery`).
+ * Tracks charging state, level (0..1), and charge/discharge time in seconds.
+ */
+export function createBattery() {
+    const nav = getNavigator();
+    const hasApi = isClient() && typeof nav?.getBattery === "function";
+    const [charging, setCharging] = createSignal(false);
+    const [level, setLevel] = createSignal(1);
+    const [chargingTime, setChargingTime] = createSignal(Infinity);
+    const [dischargingTime, setDischargingTime] = createSignal(Infinity);
+    const [error, setError] = createSignal(null);
+    if (hasApi) {
+        let manager = null;
+        const sync = () => {
+            if (!manager)
+                return;
+            setCharging(manager.charging);
+            setLevel(manager.level);
+            setChargingTime(manager.chargingTime);
+            setDischargingTime(manager.dischargingTime);
+        };
+        nav
+            .getBattery()
+            .then((m) => {
+            manager = m;
+            sync();
+            manager.addEventListener("chargingchange", sync);
+            manager.addEventListener("levelchange", sync);
+            manager.addEventListener("chargingtimechange", sync);
+            manager.addEventListener("dischargingtimechange", sync);
+        })
+            .catch((e) => {
+            setError(e instanceof Error ? e : new Error(String(e)));
+        });
+        onCleanup(() => {
+            manager?.removeEventListener("chargingchange", sync);
+            manager?.removeEventListener("levelchange", sync);
+            manager?.removeEventListener("chargingtimechange", sync);
+            manager?.removeEventListener("dischargingtimechange", sync);
+        });
+    }
+    return {
+        supported: hasApi,
+        charging,
+        level,
+        chargingTime,
+        dischargingTime,
+        error,
+    };
+}
+/**
+ * createNetwork
+ *
+ * Reactive network status: `navigator.onLine` plus the Network Information
+ * API (`navigator.connection`) for effective type, downlink, RTT, and
+ * data-saver preference.
+ */
+export function createNetwork() {
+    const nav = getNavigator();
+    const conn = nav?.connection;
+    const [online, setOnline] = createSignal(typeof nav?.onLine === "boolean" ? nav.onLine : true);
+    const [effectiveType, setEffectiveType] = createSignal(conn?.effectiveType);
+    const [downlink, setDownlink] = createSignal(conn?.downlink);
+    const [rtt, setRtt] = createSignal(conn?.rtt);
+    const [saveData, setSaveData] = createSignal(conn?.saveData ?? false);
+    const syncConnection = () => {
+        setEffectiveType(conn?.effectiveType);
+        setDownlink(conn?.downlink);
+        setRtt(conn?.rtt);
+        setSaveData(conn?.saveData ?? false);
+    };
+    const off1 = onGlobalEvent("online", () => setOnline(true));
+    const off2 = onGlobalEvent("offline", () => setOnline(false));
+    if (typeof conn?.addEventListener === "function") {
+        conn.addEventListener("change", syncConnection);
+    }
+    onCleanup(() => {
+        off1();
+        off2();
+        if (typeof conn?.removeEventListener === "function") {
+            conn.removeEventListener("change", syncConnection);
+        }
+    });
+    return {
+        online,
+        effectiveType,
+        downlink,
+        rtt,
+        saveData,
+        supported: conn != null,
+    };
+}
+/**
+ * createWakeLock
+ *
+ * Keeps the screen awake with the Screen Wake Lock API. Re-acquires the lock
+ * automatically when the tab becomes visible again after a release.
+ */
+export function createWakeLock() {
+    const nav = getNavigator();
+    const hasApi = isClient() && typeof nav?.wakeLock?.request === "function";
+    const [active, setActive] = createSignal(false);
+    const [error, setError] = createSignal(null);
+    let sentinel = null;
+    let wanted = false;
+    const acquire = async () => {
+        if (!hasApi) {
+            throw new Error("Screen Wake Lock API is not supported.");
+        }
+        setError(null);
+        try {
+            const next = (await nav.wakeLock.request("screen"));
+            sentinel = next;
+            setActive(true);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+    };
+    const request = async () => {
+        wanted = true;
+        await acquire();
+    };
+    const release = async () => {
+        wanted = false;
+        const current = sentinel;
+        sentinel = null;
+        setActive(false);
+        if (current) {
+            try {
+                await current.release();
+            }
+            catch {
+                // Releasing an already-released lock is harmless.
+            }
+        }
+    };
+    const off = onGlobalEvent("visibilitychange", () => {
+        if (!documentHidden() && wanted && !active()) {
+            void acquire().catch(() => { });
+        }
+    });
+    onCleanup(() => {
+        off();
+        wanted = false;
+        void sentinel?.release().catch(() => { });
+        sentinel = null;
+    });
+    return { supported: hasApi, active, error, request, release };
+}
+/**
+ * createContactPick
+ *
+ * Contact Picker API (`navigator.contacts.select`). Resolves with the chosen
+ * contacts; empty array when the user cancels.
+ */
+export function createContactPick() {
+    const nav = getNavigator();
+    const hasApi = isClient() && typeof nav?.contacts?.select === "function";
+    const [contacts, setContacts] = createSignal([]);
+    const [error, setError] = createSignal(null);
+    const pick = async (options = {}) => {
+        if (!hasApi) {
+            throw new Error("Contact Picker API is not supported.");
+        }
+        setError(null);
+        try {
+            const selected = (await nav.contacts.select(["name", "tel", "email"], { multiple: options.multiple ?? false }));
+            const normalized = (selected ?? []).map((c) => ({
+                name: c.name ?? [],
+                tel: c.tel ?? [],
+                email: c.email ?? [],
+            }));
+            setContacts(normalized);
+            return normalized;
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+    };
+    return { supported: hasApi, contacts, error, pick };
+}
+/**
+ * createOTP
+ *
+ * WebOTP API: reads a one-time code from an incoming SMS without leaving the
+ * page. `wait()` resolves with the code (or null when aborted). Works only on
+ * secure origins where the SMS matches the site's origin-bound format.
+ */
+export function createOTP() {
+    const nav = getNavigator();
+    const hasApi = isClient() && typeof nav?.credentials?.get === "function";
+    const [code, setCode] = createSignal(null);
+    const [error, setError] = createSignal(null);
+    let controller = null;
+    const abort = () => {
+        controller?.abort();
+        controller = null;
+    };
+    const wait = async (options = {}) => {
+        if (!hasApi) {
+            throw new Error("WebOTP API is not supported.");
+        }
+        abort();
+        setError(null);
+        controller = new AbortController();
+        const current = controller;
+        try {
+            const credential = (await nav.credentials.get({
+                otp: { transport: options.transport ?? ["sms"] },
+                signal: current.signal,
+            }));
+            const value = credential?.code ?? null;
+            setCode(value);
+            return value;
+        }
+        catch (e) {
+            if (e?.name === "AbortError")
+                return null;
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+        finally {
+            if (controller === current)
+                controller = null;
+        }
+    };
+    onCleanup(abort);
+    return { supported: hasApi, code, error, wait, abort };
+}
+/**
+ * createShare
+ *
+ * Web Share API: opens the native share sheet. `share()` resolves when the
+ * user completes or dismisses the sheet (dismissal is not an error).
+ */
+export function createShare() {
+    const nav = getNavigator();
+    const hasApi = isClient() && typeof nav?.share === "function";
+    const [error, setError] = createSignal(null);
+    const canShare = (data) => {
+        const canShareFn = nav?.canShare;
+        if (typeof canShareFn === "function") {
+            try {
+                return canShareFn.call(nav, data);
+            }
+            catch {
+                return false;
+            }
+        }
+        return hasApi;
+    };
+    const share = async (data) => {
+        if (!hasApi) {
+            throw new Error("Web Share API is not supported.");
+        }
+        setError(null);
+        try {
+            await nav.share.call(nav, data);
+        }
+        catch (e) {
+            if (e?.name === "AbortError")
+                return;
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+    };
+    return { supported: hasApi, canShare, error, share };
+}
+function decodeNFCRecord(record) {
+    const out = { recordType: record.recordType };
+    if (record.mediaType)
+        out.mediaType = record.mediaType;
+    if (!record.data)
+        return out;
+    const bytes = new Uint8Array(record.data.buffer, record.data.byteOffset, record.data.byteLength);
+    if (record.recordType === "text" && bytes.length > 1) {
+        const status = bytes[0];
+        const utf16 = (status & 0x80) !== 0;
+        const langLength = status & 0x3f;
+        const textBytes = bytes.slice(1 + langLength);
+        out.text = new TextDecoder(utf16 ? "utf-16" : "utf-8").decode(textBytes);
+    }
+    else if (record.recordType === "url") {
+        out.url = new TextDecoder().decode(bytes);
+    }
+    return out;
+}
+/**
+ * createNFC
+ *
+ * Web NFC (Chrome on Android, secure context): scan tags with `scan()` and
+ * read decoded records from `message`; write text or records with `write()`.
+ * Scanning needs a user gesture.
+ */
+export function createNFC() {
+    const readerCtor = g["NDEFReader"];
+    const supported = isClient() && typeof readerCtor === "function";
+    const [scanning, setScanning] = createSignal(false);
+    const [message, setMessage] = createSignal(null);
+    const [error, setError] = createSignal(null);
+    let controller = null;
+    const abort = () => {
+        controller?.abort();
+        controller = null;
+        setScanning(false);
+    };
+    const scan = async () => {
+        if (!supported || !readerCtor) {
+            throw new Error("Web NFC is not supported.");
+        }
+        abort();
+        setError(null);
+        const reader = new readerCtor();
+        controller = new AbortController();
+        const current = controller;
+        reader.onreading = (event) => {
+            const raw = event.message;
+            setMessage({
+                records: (raw.records ?? []).map(decodeNFCRecord),
+                serialNumber: event.serialNumber ?? "",
+            });
+        };
+        reader.onreadingerror = () => {
+            const err = new Error("Could not read the NFC tag. Try another one.");
+            setError(err);
+        };
+        try {
+            setScanning(true);
+            await reader.scan({ signal: current.signal });
+        }
+        catch (e) {
+            setScanning(false);
+            if (controller === current)
+                controller = null;
+            if (e?.name === "AbortError")
+                return;
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+    };
+    const write = async (content) => {
+        if (!supported || !readerCtor) {
+            throw new Error("Web NFC is not supported.");
+        }
+        setError(null);
+        const reader = new readerCtor();
+        try {
+            await reader.write(content);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+    };
+    onCleanup(abort);
+    return { supported, scanning, message, error, scan, write, abort };
+}
+/**
+ * createTorch
+ *
+ * Camera flashlight for devices that expose the `torch` capability.
+ * Attach a video track (or stream) from `getUserMedia`, then `set()` or
+ * `toggle()` the flashlight.
+ */
+export function createTorch() {
+    const [supported, setSupported] = createSignal(false);
+    const [on, setOn] = createSignal(false);
+    const [error, setError] = createSignal(null);
+    let track = null;
+    const attach = (input) => {
+        const next = typeof input.getVideoTracks === "function"
+            ? input.getVideoTracks()[0] ?? null
+            : input;
+        track = next;
+        const capabilities = (next?.getCapabilities?.() ?? {});
+        setSupported(!!capabilities.torch);
+        setError(null);
+    };
+    const set = async (value) => {
+        if (!track) {
+            throw new Error("No camera track attached. Call attach() first.");
+        }
+        setError(null);
+        try {
+            await track.applyConstraints({ advanced: [{ torch: value }] });
+            setOn(value);
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+    };
+    const toggle = async () => {
+        await set(!on());
+    };
+    return { supported, on, error, attach, set, toggle };
+}
+async function requestDevicePermission(ctor) {
+    const request = ctor
+        ?.requestPermission;
+    if (typeof request !== "function")
+        return "granted";
+    try {
+        return (await request.call(ctor)) === "granted" ? "granted" : "denied";
+    }
+    catch {
+        return "denied";
+    }
+}
+/**
+ * createGyro
+ *
+ * Device orientation (alpha/beta/gamma in degrees). On iOS the motion
+ * permission prompt must come from a user gesture: call `requestPermission()`
+ * from a tap handler, then `start()`.
+ */
+export function createGyro() {
+    const ctor = g["DeviceOrientationEvent"];
+    const supported = isClient() && typeof ctor !== "undefined";
+    const needsPermission = typeof ctor?.requestPermission ===
+        "function";
+    const [alpha, setAlpha] = createSignal(null);
+    const [beta, setBeta] = createSignal(null);
+    const [gamma, setGamma] = createSignal(null);
+    const [absolute, setAbsolute] = createSignal(false);
+    const [listening, setListening] = createSignal(false);
+    const [error, setError] = createSignal(null);
+    let detach = null;
+    const requestPermission = () => requestDevicePermission(ctor);
+    const start = async () => {
+        if (!supported) {
+            throw new Error("Device orientation is not supported.");
+        }
+        if (listening())
+            return;
+        setError(null);
+        const verdict = await requestDevicePermission(ctor);
+        if (verdict !== "granted") {
+            const err = new Error("Motion permission was denied.");
+            setError(err);
+            throw err;
+        }
+        const handler = (event) => {
+            const e = event;
+            setAlpha(typeof e.alpha === "number" ? e.alpha : null);
+            setBeta(typeof e.beta === "number" ? e.beta : null);
+            setGamma(typeof e.gamma === "number" ? e.gamma : null);
+            setAbsolute(!!e.absolute);
+        };
+        detach = onGlobalEvent("deviceorientation", handler);
+        setListening(true);
+    };
+    const stop = () => {
+        detach?.();
+        detach = null;
+        setListening(false);
+    };
+    onCleanup(stop);
+    return {
+        supported,
+        needsPermission,
+        alpha,
+        beta,
+        gamma,
+        absolute,
+        listening,
+        error,
+        requestPermission,
+        start,
+        stop,
+    };
+}
+/**
+ * createShake
+ *
+ * Shake-to-undo style detection from `devicemotion`. Counts a shake when the
+ * acceleration delta exceeds `threshold`, rate-limited by `cooldown`.
+ */
+export function createShake(options = {}) {
+    const { threshold = 15, cooldown = 800, onShake } = options;
+    const ctor = g["DeviceMotionEvent"];
+    const supported = isClient() && typeof ctor !== "undefined";
+    const needsPermission = typeof ctor?.requestPermission ===
+        "function";
+    const [listening, setListening] = createSignal(false);
+    const [shakes, setShakes] = createSignal(0);
+    const [error, setError] = createSignal(null);
+    let detach = null;
+    let last = null;
+    let lastSample = 0;
+    let lastShake = 0;
+    const requestPermission = () => requestDevicePermission(ctor);
+    const start = async () => {
+        if (!supported) {
+            throw new Error("Device motion is not supported.");
+        }
+        if (listening())
+            return;
+        setError(null);
+        const verdict = await requestDevicePermission(ctor);
+        if (verdict !== "granted") {
+            const err = new Error("Motion permission was denied.");
+            setError(err);
+            throw err;
+        }
+        const handler = (event) => {
+            const accel = event.accelerationIncludingGravity;
+            if (!accel)
+                return;
+            const now = Date.now();
+            const x = accel.x ?? 0;
+            const y = accel.y ?? 0;
+            const z = accel.z ?? 0;
+            if (last && now - lastSample > 40) {
+                const dx = x - last.x;
+                const dy = y - last.y;
+                const dz = z - last.z;
+                const delta = Math.sqrt(dx * dx + dy * dy + dz * dz);
+                if (delta > threshold && now - lastShake > cooldown) {
+                    lastShake = now;
+                    setShakes((n) => n + 1);
+                    onShake?.();
+                }
+            }
+            last = { x, y, z };
+            lastSample = now;
+        };
+        detach = onGlobalEvent("devicemotion", handler);
+        setListening(true);
+    };
+    const stop = () => {
+        detach?.();
+        detach = null;
+        last = null;
+        setListening(false);
+    };
+    onCleanup(stop);
+    return {
+        supported,
+        needsPermission,
+        listening,
+        shakes,
+        error,
+        requestPermission,
+        start,
+        stop,
+    };
+}
+/**
+ * createScanline
+ *
+ * The animated line of a camera viewfinder (QR/barcode scanning UI). Bind
+ * `progress()` to the line position, for example
+ * `style={{ top: `${progress() * 100}%` }}`. Runs on the shared clock and
+ * freezes mid-frame under reduced motion.
+ */
+export function createScanline(options = {}) {
+    const { duration = 1800, direction = "alternate" } = options;
+    const [progress, setProgress] = createSignal(0);
+    const [running, setRunning] = createSignal(false);
+    let stopClock = null;
+    const start = () => {
+        if (running())
+            return;
+        setRunning(true);
+        if (prefersReducedMotion() || duration <= 0) {
+            setProgress(0.5);
+            return;
+        }
+        let startTime = 0;
+        let first = true;
+        stopClock = schedule((t) => {
+            if (first) {
+                startTime = t;
+                first = false;
+            }
+            const phase = ((t - startTime) % duration) / duration;
+            let value = phase;
+            if (direction === "up")
+                value = 1 - phase;
+            else if (direction === "alternate")
+                value = phase < 0.5 ? phase * 2 : 2 - phase * 2;
+            setProgress(value);
+            return true;
+        });
+    };
+    const stop = () => {
+        stopClock?.();
+        stopClock = null;
+        setRunning(false);
+    };
+    onCleanup(stop);
+    return { progress, running, start, stop };
+}

package/dist/index.d.ts

@@ -44,3 +44,7 @@ export { createSSEParser, createSSE, createChatModel, } from "./stream.js";
 export type { SSEEvent, StreamStatus, SSEOptions, SSEControls, ChatMessage, ChatProviderKind, CustomChatProvider, ChatModelOptions, ChatModelControls, } from "./stream.js";
 export { createVoiceState, createMicLevel, createSpeech, createWaveform, createTTS, createThinking, createPrompt, } from "./voice.js";
 export type { VoiceStatus, VoiceStateControls, MicLevelOptions, MicLevelControls, SpeechOptions, SpeechControls, WaveformOptions, WaveformControls, TTSProvider, TTSOptions, TTSControls, ThinkingOptions, ThinkingControls, PromptOptions, PromptControls, } from "./voice.js";
+export { createBattery, createNetwork, createWakeLock, createContactPick, createOTP, createShare, createNFC, createTorch, createGyro, createShake, createScanline, } from "./hardware.js";
+export type { BatteryState, NetworkState, WakeLockState, PickedContact, ContactPickState, OTPState, ShareState, NFCRecord, NFCMessage, NFCState, TorchState, GyroState, ShakeOptions, ShakeState, ScanlineOptions, ScanlineState, } from "./hardware.js";
+export { createOptimistic } from "./optimistic.js";
+export type { OptimisticControls } from "./optimistic.js";

package/dist/index.js

@@ -38,3 +38,5 @@ export { createTxLifecycle, createTicker, createMintReveal, createConnectButton,
 export { createPoll, shortenAddress, isAddress, formatUnits, parseUnits, CHAINS, createChain, createTokenPrice, createPriceChange, createPriceCompare, createGasPrice, createBalance, createTxReceipt, createBlockNumber, createChainlinkPrice, createNFTMetadata, createENS, createIdenticon, } from "./web3data.js";
 export { createSSEParser, createSSE, createChatModel, } from "./stream.js";
 export { createVoiceState, createMicLevel, createSpeech, createWaveform, createTTS, createThinking, createPrompt, } from "./voice.js";
+export { createBattery, createNetwork, createWakeLock, createContactPick, createOTP, createShare, createNFC, createTorch, createGyro, createShake, createScanline, } from "./hardware.js";
+export { createOptimistic } from "./optimistic.js";

package/dist/optimistic.d.ts

@@ -0,0 +1,44 @@
+export interface OptimisticControls<T, U> {
+    /** Server truth plus every in-flight optimistic update, in commit order. */
+    value: () => T;
+    /** Replace the server truth (for example after a refetch). */
+    setBase: (next: T | ((prev: T) => T)) => void;
+    /** True while at least one commit is in flight. */
+    pending: () => boolean;
+    /** Number of commits currently in flight. */
+    pendingCount: () => number;
+    /** Last commit failure, cleared when the next commit starts. */
+    error: () => Error | null;
+    /**
+     * Apply `update` immediately, then run `task`. On success the update is
+     * promoted into the base truth (so the value stays stable while the
+     * server catches up); on failure it is rolled back, `error()` is set,
+     * and the error is rethrown so callers can react (toast, retry).
+     */
+    commit: (update: U, task: (update: U) => Promise<unknown>) => Promise<void>;
+    /** Drop every in-flight optimistic update without running their tasks. */
+    reset: () => void;
+}
+/**
+ * createOptimistic
+ *
+ * Optimistic updates with rollback, in the spirit of React's `useOptimistic`.
+ * The UI reflects `update` the moment `commit()` is called; if the backing
+ * task (a transaction, a POST, a stream send) fails, that update is rolled
+ * back and the error surfaces on `error()`.
+ *
+ * Write `apply` idempotently (upsert by id rather than blind append) when
+ * the server truth delivered through `setBase` may already include an
+ * optimistic update.
+ *
+ * ```ts
+ * const feed = createOptimistic<Bid[], Bid>([], (bids, bid) =>
+ *   bids.some((b) => b.id === bid.id) ? bids : [...bids, bid],
+ * );
+ *
+ * await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
+ *   // already rolled back; show a toast from feed.error()
+ * });
+ * ```
+ */
+export declare function createOptimistic<T, U>(initial: T, apply: (state: T, update: U) => T): OptimisticControls<T, U>;

package/dist/optimistic.js

@@ -0,0 +1,76 @@
+import { createSignal } from "solid-js";
+/**
+ * createOptimistic
+ *
+ * Optimistic updates with rollback, in the spirit of React's `useOptimistic`.
+ * The UI reflects `update` the moment `commit()` is called; if the backing
+ * task (a transaction, a POST, a stream send) fails, that update is rolled
+ * back and the error surfaces on `error()`.
+ *
+ * Write `apply` idempotently (upsert by id rather than blind append) when
+ * the server truth delivered through `setBase` may already include an
+ * optimistic update.
+ *
+ * ```ts
+ * const feed = createOptimistic<Bid[], Bid>([], (bids, bid) =>
+ *   bids.some((b) => b.id === bid.id) ? bids : [...bids, bid],
+ * );
+ *
+ * await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
+ *   // already rolled back; show a toast from feed.error()
+ * });
+ * ```
+ */
+export function createOptimistic(initial, apply) {
+    const [base, setBaseSignal] = createSignal(initial);
+    const [queue, setQueue] = createSignal([]);
+    const [error, setError] = createSignal(null);
+    let nextId = 0;
+    const value = () => {
+        const truth = base();
+        const pending = queue();
+        if (pending.length === 0)
+            return truth;
+        return pending.reduce((state, entry) => apply(state, entry.update), truth);
+    };
+    const setBase = (next) => {
+        if (typeof next === "function") {
+            setBaseSignal(next);
+        }
+        else {
+            setBaseSignal(() => next);
+        }
+    };
+    const commit = async (update, task) => {
+        const id = nextId++;
+        setError(null);
+        setQueue((q) => [...q, { id, update }]);
+        try {
+            await task(update);
+            // Promote the confirmed update into the base truth so the value
+            // stays stable while the server truth catches up via setBase.
+            setBaseSignal((prev) => apply(prev, update));
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+        finally {
+            setQueue((q) => q.filter((entry) => entry.id !== id));
+        }
+    };
+    const reset = () => {
+        setQueue([]);
+        setError(null);
+    };
+    return {
+        value,
+        setBase,
+        pending: () => queue().length > 0,
+        pendingCount: () => queue().length,
+        error,
+        commit,
+        reset,
+    };
+}

package/dist/voice.d.ts

@@ -235,7 +235,7 @@ export interface ThinkingControls {
     stop: () => void;
 }
 /**
- * An animated "thinking" indicator for voice/AI latency: cycles
+ * An animated "thinking" indicator for voice reply latency: cycles
  * trailing dots, then moves through phrases.
  *
  * ```ts

package/dist/voice.js

@@ -464,7 +464,7 @@ export function createTTS(options = {}) {
     return { supported, speaking, voices, speak, cancel };
 }
 /**
- * An animated "thinking" indicator for voice/AI latency: cycles
+ * An animated "thinking" indicator for voice reply latency: cycles
  * trailing dots, then moves through phrases.
  *
  * ```ts

package/package.json

@@ -43,5 +43,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.26.0"
+  "version": "0.28.0"
 }