@lotics/app-sdk 0.100.1 → 0.101.0

package/dist/src/upload/transport.js

@@ -1,128 +0,0 @@
-/**
- * Transport-layer helpers for the SDK upload pipeline.
- *
- * Two concerns this module owns:
- *
- * 1. **Per-request timeout.** A bare `fetch` hangs forever if the network is
- *    unreachable; we wrap it in an `AbortController` so a stuck request fails
- *    after `UPLOAD_TIMEOUT_MS` instead of leaving the user staring at a
- *    spinner.
- *
- * 2. **Retry with exponential backoff** for the presigned `PUT` to object
- *    storage — the single most failure-prone step on mobile networks. We
- *    retry on network errors / 5xx / timeouts up to `UPLOAD_PUT_MAX_ATTEMPTS`
- *    with 1s → 2s → 4s waits between attempts. We do NOT retry on 4xx
- *    (client error, retrying won't help) or on caller-initiated aborts.
- *
- * Mirrors the conventions in `frontend/lib/api_utils.ts` and
- * `frontend/lib/file_upload.ts`, simplified for the SDK (no logger, no
- * correlation headers).
- */
-export const UPLOAD_TIMEOUT_MS = 5 * 60 * 1000;
-const UPLOAD_PUT_MAX_ATTEMPTS = 3;
-const UPLOAD_PUT_BACKOFF_BASE_MS = 1000;
-export class UploadTimeoutError extends Error {
-    url;
-    timeoutMs;
-    name = "UploadTimeoutError";
-    constructor(url, timeoutMs) {
-        super(`Upload request to ${url} timed out after ${timeoutMs}ms`);
-        this.url = url;
-        this.timeoutMs = timeoutMs;
-    }
-}
-export class UploadAbortedError extends Error {
-    name = "UploadAbortedError";
-    constructor() {
-        super("Upload aborted");
-    }
-}
-/** `fetch` with timeout + optional external `AbortSignal`. */
-export async function fetchWithTimeout(url, init, timeoutMs) {
-    const controller = new AbortController();
-    let didTimeout = false;
-    const timeoutId = setTimeout(() => {
-        didTimeout = true;
-        controller.abort();
-    }, timeoutMs);
-    if (init.signal) {
-        if (init.signal.aborted) {
-            clearTimeout(timeoutId);
-            throw new UploadAbortedError();
-        }
-        init.signal.addEventListener("abort", () => controller.abort(), { once: true });
-    }
-    try {
-        return await fetch(url, { ...init, signal: controller.signal });
-    }
-    catch (err) {
-        if (didTimeout)
-            throw new UploadTimeoutError(url, timeoutMs);
-        if (init.signal?.aborted)
-            throw new UploadAbortedError();
-        throw err;
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-}
-/**
- * Presigned-PUT to object storage with retry + backoff.
- *
- * Retries network errors, timeouts, and 5xx responses up to
- * `UPLOAD_PUT_MAX_ATTEMPTS` times. A 4xx response is returned to the caller
- * unchanged (retrying a 403/400 won't help; the caller decides). Aborts
- * propagate immediately without retry.
- */
-export async function putToStorageWithRetry(uploadUrl, file, signal) {
-    let lastError;
-    for (let attempt = 1; attempt <= UPLOAD_PUT_MAX_ATTEMPTS; attempt += 1) {
-        try {
-            const response = await fetchWithTimeout(uploadUrl, {
-                method: "PUT",
-                headers: { "Content-Type": file.type },
-                body: file,
-                signal,
-            }, UPLOAD_TIMEOUT_MS);
-            if (response.ok)
-                return response;
-            // 4xx is terminal — retrying a malformed/expired URL is pointless.
-            if (response.status >= 400 && response.status < 500)
-                return response;
-            // 5xx — fall through to retry.
-            lastError = new Error(`Storage PUT returned ${response.status}`);
-        }
-        catch (err) {
-            // Caller-initiated abort: stop immediately.
-            if (err instanceof UploadAbortedError)
-                throw err;
-            lastError = err;
-        }
-        if (attempt < UPLOAD_PUT_MAX_ATTEMPTS) {
-            const delayMs = UPLOAD_PUT_BACKOFF_BASE_MS * 2 ** (attempt - 1);
-            await sleep(delayMs, signal);
-        }
-    }
-    throw lastError instanceof Error ? lastError : new Error("Storage PUT failed");
-}
-function sleep(ms, signal) {
-    return new Promise((resolve, reject) => {
-        if (signal?.aborted) {
-            reject(new UploadAbortedError());
-            return;
-        }
-        const timeoutId = setTimeout(() => {
-            cleanup();
-            resolve();
-        }, ms);
-        const cleanup = () => {
-            clearTimeout(timeoutId);
-            signal?.removeEventListener("abort", onAbort);
-        };
-        const onAbort = () => {
-            cleanup();
-            reject(new UploadAbortedError());
-        };
-        signal?.addEventListener("abort", onAbort, { once: true });
-    });
-}

package/dist/src/url_params.d.ts

@@ -1,93 +0,0 @@
-/**
- * Typed codecs that map URL query-string values (always strings, or string
- * arrays for repeated keys) to and from the typed view-state an app keeps in
- * the address bar — the engine behind `useUrlState`.
- *
- * Two properties make the URLs clean and the round-trip lossless:
- *
- *  - **Default-omission.** A codec built with `.withDefault(d)` encodes the
- *    default value to `undefined` — i.e. the key is dropped from the URL. So a
- *    filter at its default (`page=1`, `q=""`) never appears, and the shared
- *    link carries only what the user actually changed.
- *  - **Declared keys only.** `decodeAll`/`encodePatch` touch exactly the keys the
- *    app declared. Every other query param (`lotics_host`, `__mock`, a param a
- *    second `useUrlState` owns, a future host param) is read past and preserved
- *    on write — the merge is the namespace boundary, so no reserved-prefix rule
- *    is needed.
- *
- * Self-contained on purpose: the SDK publishes to npm as a bundle-free `dist/`,
- * so it carries no workspace deps (no `@lotics/shared`). These are plain pure
- * functions — a frontend that later wants the same value⇄query codec can import
- * them from here rather than growing a second copy.
- */
-/** A query value as it appears in the URL: a single string, or an array for a
- *  repeated key (`?tag=a&tag=b`). Absent keys are simply missing from the map. */
-export type UrlParamValue = string | string[];
-/** The current query string decoded to a map (present keys only). */
-export type UrlParams = Record<string, UrlParamValue>;
-/** A write: each key set to its encoded value, or `undefined` to clear it. Only
- *  the keys present are touched; others in the URL are preserved (a merge). */
-export type UrlParamsPatch = Record<string, UrlParamValue | undefined>;
-/**
- * A reversible mapping between a typed value `T` and its URL representation.
- * Methods (not function-typed properties) so a concrete `UrlParamCodec<string>`
- * stays assignable to `UrlParamCodec<unknown>` for the `useUrlState` codec map.
- */
-export interface UrlParamCodec<T> {
-    /** Raw query value (or `undefined` when the key is absent) → typed value. */
-    decode(raw: UrlParamValue | undefined): T;
-    /** Typed value → raw query value, or `undefined` to omit the key. */
-    encode(value: T): UrlParamValue | undefined;
-}
-/** A codec whose value is optional (absent key → `undefined`), refinable to a
- *  required codec with a fallback via `.withDefault`. */
-export interface OptionalUrlParamCodec<T> extends UrlParamCodec<T | undefined> {
-    /** Make the value required: an absent key decodes to `fallback`, and a value
-     *  equal to `fallback` encodes to nothing (kept out of the URL). */
-    withDefault(fallback: T): UrlParamCodec<T>;
-}
-declare function enumCodec<const V extends readonly string[]>(values: V): OptionalUrlParamCodec<V[number]>;
-declare function arrayOf<T>(inner: UrlParamCodec<T | undefined>): OptionalUrlParamCodec<T[]>;
-/**
- * The codec builders an app composes into a `useUrlState` shape. Each base
- * builder yields an optional codec (absent key → `undefined`); add
- * `.withDefault(v)` to make it required and keep the default out of the URL.
- *
- *   useUrlState({
- *     q:      urlParam.string.withDefault(""),
- *     status: urlParam.enum(["open", "won", "lost"]),       // optional
- *     tags:   urlParam.arrayOf(urlParam.string).withDefault([]),
- *     from:   urlParam.isoDate,                              // optional Date
- *     page:   urlParam.number.withDefault(1),
- *   })
- */
-export declare const urlParam: {
-    readonly string: OptionalUrlParamCodec<string>;
-    readonly number: OptionalUrlParamCodec<number>;
-    readonly boolean: OptionalUrlParamCodec<boolean>;
-    readonly isoDate: OptionalUrlParamCodec<Date>;
-    readonly enum: typeof enumCodec;
-    readonly arrayOf: typeof arrayOf;
-};
-/** Decode the declared keys out of a params map into typed values. */
-export declare function decodeAll<D extends Record<string, UrlParamCodec<unknown>>>(defs: D, params: UrlParams): {
-    [K in keyof D]: D[K] extends UrlParamCodec<infer T> ? T : never;
-};
-/** Encode a partial set of declared values into a patch (each key → value or
- *  `undefined` to clear). Only the keys present in `values` are emitted, so the
- *  write merges and leaves every other query param untouched. */
-export declare function encodePatch<D extends Record<string, UrlParamCodec<unknown>>>(defs: D, values: Partial<{
-    [K in keyof D]: D[K] extends UrlParamCodec<infer T> ? T : never;
-}>): UrlParamsPatch;
-/** Parse a `location.search` string into a params map (repeated keys → array). */
-export declare function parseSearch(search: string): UrlParams;
-/** Apply a patch to a `location.search` string and return the new query string
- *  (no leading `?`). Each patch key is replaced; `undefined` clears it; every
- *  other existing param is preserved. */
-export declare function serializeMerge(search: string, patch: UrlParamsPatch): string;
-/** Apply a patch to an in-memory params map (the optimistic local mirror). */
-export declare function applyPatch(params: UrlParams, patch: UrlParamsPatch): UrlParams;
-/** Shallow value-equality over two params maps — used to drop echoed updates so
- *  an app's own write doesn't re-render it a second time. */
-export declare function paramsEqual(a: UrlParams, b: UrlParams): boolean;
-export {};

package/dist/src/url_params.js

@@ -1,215 +0,0 @@
-/**
- * Typed codecs that map URL query-string values (always strings, or string
- * arrays for repeated keys) to and from the typed view-state an app keeps in
- * the address bar — the engine behind `useUrlState`.
- *
- * Two properties make the URLs clean and the round-trip lossless:
- *
- *  - **Default-omission.** A codec built with `.withDefault(d)` encodes the
- *    default value to `undefined` — i.e. the key is dropped from the URL. So a
- *    filter at its default (`page=1`, `q=""`) never appears, and the shared
- *    link carries only what the user actually changed.
- *  - **Declared keys only.** `decodeAll`/`encodePatch` touch exactly the keys the
- *    app declared. Every other query param (`lotics_host`, `__mock`, a param a
- *    second `useUrlState` owns, a future host param) is read past and preserved
- *    on write — the merge is the namespace boundary, so no reserved-prefix rule
- *    is needed.
- *
- * Self-contained on purpose: the SDK publishes to npm as a bundle-free `dist/`,
- * so it carries no workspace deps (no `@lotics/shared`). These are plain pure
- * functions — a frontend that later wants the same value⇄query codec can import
- * them from here rather than growing a second copy.
- */
-function first(raw) {
-    return Array.isArray(raw) ? raw[0] : raw;
-}
-function valueEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a instanceof Date && b instanceof Date)
-        return a.getTime() === b.getTime();
-    if (Array.isArray(a) && Array.isArray(b)) {
-        return a.length === b.length && a.every((x, i) => valueEqual(x, b[i]));
-    }
-    return false;
-}
-/** Wrap an optional base codec with `.withDefault`. */
-function optional(base) {
-    return {
-        decode: base.decode,
-        encode: base.encode,
-        withDefault(fallback) {
-            return {
-                decode: (raw) => {
-                    const v = base.decode(raw);
-                    return v === undefined ? fallback : v;
-                },
-                encode: (value) => (valueEqual(value, fallback) ? undefined : base.encode(value)),
-            };
-        },
-    };
-}
-const stringCodec = optional({
-    decode: (raw) => (raw === undefined ? undefined : first(raw)),
-    encode: (v) => v,
-});
-const numberCodec = optional({
-    decode: (raw) => {
-        const s = first(raw);
-        if (s === undefined || s === "")
-            return undefined;
-        const n = Number(s);
-        return Number.isFinite(n) ? n : undefined;
-    },
-    encode: (v) => (v === undefined ? undefined : String(v)),
-});
-const booleanCodec = optional({
-    decode: (raw) => {
-        const s = first(raw);
-        return s === "true" ? true : s === "false" ? false : undefined;
-    },
-    encode: (v) => (v === undefined ? undefined : v ? "true" : "false"),
-});
-const isoDateCodec = optional({
-    decode: (raw) => {
-        const s = first(raw);
-        if (s === undefined || !/^\d{4}-\d{2}-\d{2}$/.test(s))
-            return undefined;
-        const d = new Date(`${s}T00:00:00.000Z`);
-        return Number.isNaN(d.getTime()) ? undefined : d;
-    },
-    encode: (v) => (v === undefined ? undefined : v.toISOString().slice(0, 10)),
-});
-function enumCodec(values) {
-    return optional({
-        decode: (raw) => {
-            const s = first(raw);
-            return s === undefined ? undefined : values.find((v) => v === s);
-        },
-        encode: (v) => v,
-    });
-}
-function arrayOf(inner) {
-    return optional({
-        decode: (raw) => {
-            if (raw === undefined)
-                return undefined;
-            const items = Array.isArray(raw) ? raw : [raw];
-            return items.map((x) => inner.decode(x)).filter((x) => x !== undefined);
-        },
-        encode: (value) => {
-            if (value === undefined || value.length === 0)
-                return undefined;
-            const out = value
-                .map((x) => inner.encode(x))
-                .filter((x) => typeof x === "string");
-            return out.length > 0 ? out : undefined;
-        },
-    });
-}
-/**
- * The codec builders an app composes into a `useUrlState` shape. Each base
- * builder yields an optional codec (absent key → `undefined`); add
- * `.withDefault(v)` to make it required and keep the default out of the URL.
- *
- *   useUrlState({
- *     q:      urlParam.string.withDefault(""),
- *     status: urlParam.enum(["open", "won", "lost"]),       // optional
- *     tags:   urlParam.arrayOf(urlParam.string).withDefault([]),
- *     from:   urlParam.isoDate,                              // optional Date
- *     page:   urlParam.number.withDefault(1),
- *   })
- */
-export const urlParam = {
-    string: stringCodec,
-    number: numberCodec,
-    boolean: booleanCodec,
-    isoDate: isoDateCodec,
-    enum: enumCodec,
-    arrayOf,
-};
-/** Decode the declared keys out of a params map into typed values. */
-export function decodeAll(defs, params) {
-    const out = {};
-    for (const key of Object.keys(defs)) {
-        out[key] = defs[key].decode(params[key]);
-    }
-    // Boundary: a per-key loop can't be expressed as the mapped result type.
-    return out;
-}
-/** Encode a partial set of declared values into a patch (each key → value or
- *  `undefined` to clear). Only the keys present in `values` are emitted, so the
- *  write merges and leaves every other query param untouched. */
-export function encodePatch(defs, values) {
-    const out = {};
-    for (const key of Object.keys(values)) {
-        const codec = defs[key];
-        if (codec)
-            out[key] = codec.encode(values[key]);
-    }
-    return out;
-}
-/** Parse a `location.search` string into a params map (repeated keys → array). */
-export function parseSearch(search) {
-    const sp = new URLSearchParams(search);
-    const out = {};
-    for (const key of sp.keys()) {
-        if (key in out)
-            continue;
-        const all = sp.getAll(key);
-        out[key] = all.length > 1 ? all : all[0];
-    }
-    return out;
-}
-/** Apply a patch to a `location.search` string and return the new query string
- *  (no leading `?`). Each patch key is replaced; `undefined` clears it; every
- *  other existing param is preserved. */
-export function serializeMerge(search, patch) {
-    const sp = new URLSearchParams(search);
-    for (const [key, value] of Object.entries(patch)) {
-        sp.delete(key);
-        if (value === undefined)
-            continue;
-        if (Array.isArray(value)) {
-            for (const item of value)
-                sp.append(key, item);
-        }
-        else {
-            sp.append(key, value);
-        }
-    }
-    return sp.toString();
-}
-/** Apply a patch to an in-memory params map (the optimistic local mirror). */
-export function applyPatch(params, patch) {
-    const next = { ...params };
-    for (const [key, value] of Object.entries(patch)) {
-        if (value === undefined)
-            delete next[key];
-        else
-            next[key] = value;
-    }
-    return next;
-}
-/** Shallow value-equality over two params maps — used to drop echoed updates so
- *  an app's own write doesn't re-render it a second time. */
-export function paramsEqual(a, b) {
-    const ak = Object.keys(a);
-    const bk = Object.keys(b);
-    if (ak.length !== bk.length)
-        return false;
-    for (const key of ak) {
-        const av = a[key];
-        const bv = b[key];
-        if (Array.isArray(av) || Array.isArray(bv)) {
-            if (!Array.isArray(av) || !Array.isArray(bv))
-                return false;
-            if (av.length !== bv.length || !av.every((x, i) => x === bv[i]))
-                return false;
-        }
-        else if (av !== bv) {
-            return false;
-        }
-    }
-    return true;
-}

package/dist/src/use_optimistic.d.ts

@@ -1,27 +0,0 @@
-export interface OptimisticApi<T> {
-    /** `base` with any pending optimistic patches applied. */
-    items: T[];
-    /**
-     * Optimistically merge `next` into the item keyed `id`, then run `persist`.
-     * On resolve → `onSettled?.()`; the patch is kept (it should already match
-     * what the write persisted, so the re-read lands underneath it without a
-     * flicker). On reject → the patch is reverted.
-     *
-     * `onSettled` is NOT for refetching the query this patch came from — a
-     * successful `useWorkflow` inside `persist` re-reads every mounted query on
-     * its own. Use it for what the write cannot know about: a total the app
-     * computed itself, an indicator to clear.
-     */
-    patch: (id: string, next: Partial<T>, persist: () => Promise<unknown>, opts?: {
-        onSettled?: () => void;
-    }) => void;
-}
-/**
- * Optimistic list overrides for a `useQuery` result feeding an interactive view
- * (calendar drag, gantt resize, kanban move). Pure React state: it takes the
- * already-mapped items + a key function + a caller-supplied `persist` thunk, so
- * it has no coupling to any specific mutation transport (the app threads its own
- * `useWorkflow` call + `refetch`). It lives in app-sdk as the *reconcile* leg of
- * the read (`useQuery`) → mutate (`useWorkflow`) → reconcile loop.
- */
-export declare function useOptimistic<T>(base: T[], keyOf: (item: T) => string): OptimisticApi<T>;

package/dist/src/use_optimistic.js

@@ -1,27 +0,0 @@
-import { useCallback, useMemo, useState } from "react";
-/**
- * Optimistic list overrides for a `useQuery` result feeding an interactive view
- * (calendar drag, gantt resize, kanban move). Pure React state: it takes the
- * already-mapped items + a key function + a caller-supplied `persist` thunk, so
- * it has no coupling to any specific mutation transport (the app threads its own
- * `useWorkflow` call + `refetch`). It lives in app-sdk as the *reconcile* leg of
- * the read (`useQuery`) → mutate (`useWorkflow`) → reconcile loop.
- */
-export function useOptimistic(base, keyOf) {
-    const [overrides, setOverrides] = useState({});
-    const items = useMemo(() => base.map((item) => {
-        const o = overrides[keyOf(item)];
-        return o ? { ...item, ...o } : item;
-    }), [base, overrides, keyOf]);
-    const patch = useCallback((id, next, persist, opts) => {
-        setOverrides((m) => ({ ...m, [id]: { ...m[id], ...next } }));
-        persist().then(() => opts?.onSettled?.(), () => setOverrides((m) => {
-            if (!(id in m))
-                return m;
-            const cleared = { ...m };
-            delete cleared[id];
-            return cleared;
-        }));
-    }, []);
-    return { items, patch };
-}

package/dist/src/use_recents.d.ts

@@ -1,19 +0,0 @@
-export interface RecentsApi<T> {
-    /** Remembered items, most-recent first (deduped by `keyOf`, capped at `max`). */
-    recents: T[];
-    /** Record `item` as most-recent: moves an existing match to the front, caps,
-     *  and persists. Call this on select. */
-    remember: (item: T) => void;
-    /** Drop one remembered item (matched by `keyOf`). */
-    forget: (item: T) => void;
-    /** Clear the whole list. */
-    clear: () => void;
-}
-export interface RecentsOptions<T> {
-    /** Stable identity per item — used to dedup and to match `forget`. Default:
-     *  `JSON.stringify`. Pass the item's id for objects you'll re-create. */
-    keyOf?: (item: T) => string;
-    /** Maximum items kept. Default 5. */
-    max?: number;
-}
-export declare function useRecents<T>(key: string, options?: RecentsOptions<T>): RecentsApi<T>;

package/dist/src/use_recents.js

@@ -1,71 +0,0 @@
-/**
- * Remember a small, most-recent-first list of items across sessions — the
- * "recently used" affordance a search box shows when focused but empty.
- *
- * Persistence is `localStorage`, namespaced per `key`, so two comboboxes on one
- * page keep separate lists and a deployed app's recents survive reloads. The
- * SDK is the right home (not `@lotics/ui`): `localStorage` is web-only, and
- * `@lotics/ui` also builds for native, where it doesn't exist. The list is
- * always state-backed, so the hook keeps working in-memory if storage is
- * unavailable (private mode / quota) — recents is an enhancement, never a
- * reason to crash the app.
- */
-import { useCallback, useEffect, useRef, useState } from "react";
-const PREFIX = "lotics.recents.";
-function read(storageKey) {
-    try {
-        const raw = localStorage.getItem(storageKey);
-        if (raw == null)
-            return [];
-        const parsed = JSON.parse(raw);
-        return Array.isArray(parsed) ? parsed : [];
-    }
-    catch {
-        // Storage unavailable or corrupt JSON: start empty, keep working in-memory.
-        return [];
-    }
-}
-function write(storageKey, items) {
-    try {
-        localStorage.setItem(storageKey, JSON.stringify(items));
-    }
-    catch {
-        // Storage unavailable (private mode / quota): the in-memory list still
-        // updates; only cross-reload persistence is lost.
-    }
-}
-export function useRecents(key, options = {}) {
-    const storageKey = PREFIX + key;
-    // Config is captured in refs so the returned callbacks stay referentially
-    // stable across renders even when the caller passes an inline `keyOf`.
-    const keyOfRef = useRef(options.keyOf ?? ((item) => JSON.stringify(item)));
-    keyOfRef.current = options.keyOf ?? ((item) => JSON.stringify(item));
-    const maxRef = useRef(options.max ?? 5);
-    maxRef.current = options.max ?? 5;
-    const [recents, setRecents] = useState(() => read(storageKey).slice(0, maxRef.current));
-    // Re-hydrate when the namespace changes (a different list on the same screen).
-    useEffect(() => {
-        setRecents(read(storageKey).slice(0, maxRef.current));
-    }, [storageKey]);
-    const remember = useCallback((item) => {
-        setRecents((prev) => {
-            const k = keyOfRef.current(item);
-            const next = [item, ...prev.filter((p) => keyOfRef.current(p) !== k)].slice(0, maxRef.current);
-            write(storageKey, next);
-            return next;
-        });
-    }, [storageKey]);
-    const forget = useCallback((item) => {
-        setRecents((prev) => {
-            const k = keyOfRef.current(item);
-            const next = prev.filter((p) => keyOfRef.current(p) !== k);
-            write(storageKey, next);
-            return next;
-        });
-    }, [storageKey]);
-    const clear = useCallback(() => {
-        write(storageKey, []);
-        setRecents([]);
-    }, [storageKey]);
-    return { recents, remember, forget, clear };
-}

package/dist/src/use_url_state.js

@@ -1,73 +0,0 @@
-/**
- * Save a declared slice of an app's view-state — filters, search, sort, the
- * active tab — into the host's address bar, so a filtered view survives refresh
- * and is shareable/bookmarkable as a link. Writes always *replace* in place: the
- * host owns no in-app history, and in-app navigation (and the browser back
- * button) belong to the app's own router, not to this hook.
- *
- *   const [filters, setFilters] = useUrlState({
- *     q:      urlParam.string.withDefault(""),
- *     status: urlParam.enum(["open", "won", "lost"]),        // optional
- *     tags:   urlParam.arrayOf(urlParam.string).withDefault([]),
- *     page:   urlParam.number.withDefault(1),
- *   });
- *   // filters → { q: string; status?: "open"|"won"|"lost"; tags: string[]; page: number }
- *   setFilters({ q: "acme" });                  // merge into the address bar (replace)
- *
- * The app declares only the keys it owns; every other query param (a param a
- * second `useUrlState` owns, the framework's `lotics_host`/`__mock`, a future
- * host param) is read past and preserved on write. For a search box, keep the
- * live input in local state and commit to `setFilters` on a debounce — each
- * call is a cross-frame write in an embedded app.
- *
- * The address bar is the only store: nothing is persisted server-side. Values
- * are decoded fresh from the current params each render; standalone reads the
- * URL directly, while an embedded app keeps a local mirror seeded from the host
- * (`urlState.get` on mount) and updated optimistically on its own writes — so
- * there's no independently-mutable second copy to drift.
- */
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { getUrlParams, peekUrlParams, setUrlParams, subscribeUrlParams } from "./rpc.js";
-import { applyPatch, decodeAll, encodePatch, paramsEqual, } from "./url_params.js";
-export function useUrlState(defs) {
-    // `defs` is expected stable (declared inline once); read through a ref so the
-    // decoded values and `setValues` stay referentially stable across renders.
-    const defsRef = useRef(defs);
-    defsRef.current = defs;
-    const [params, setParams] = useState(peekUrlParams);
-    // Once the user edits, a late initial hydration (bridged `getUrlParams`
-    // resolves a tick after mount) must not clobber their write.
-    const editedRef = useRef(false);
-    useEffect(() => {
-        let active = true;
-        const apply = (next) => {
-            if (active)
-                setParams((prev) => (paramsEqual(prev, next) ? prev : next));
-        };
-        void getUrlParams().then((p) => {
-            if (active && !editedRef.current)
-                apply(p);
-        });
-        const unsubscribe = subscribeUrlParams(apply);
-        return () => {
-            active = false;
-            unsubscribe();
-        };
-    }, []);
-    const values = useMemo(() => decodeAll(defsRef.current, params), [params]);
-    const setValues = useCallback((patch) => {
-        editedRef.current = true;
-        const encoded = encodePatch(defsRef.current, patch);
-        // Optimistic local mirror so the UI is responsive even before the write
-        // round-trips (and the only update path in standalone, where the history
-        // write fires no event).
-        setParams((prev) => applyPatch(prev, encoded));
-        // The optimistic mirror already reflects the change, so a failed write
-        // only loses cross-refresh persistence, never the session — keep the
-        // optimistic state, but surface the failure instead of swallowing it.
-        void setUrlParams(encoded).catch((err) => {
-            console.error("useUrlState: failed to write state to the address bar", err);
-        });
-    }, []);
-    return [values, setValues];
-}