@pyric/ui 0.1.0-alpha.10

package/dist/storage/hooks/usePathState.js

@@ -0,0 +1,42 @@
+import { useCallback, useMemo, useState } from 'react';
+/** Strip leading/trailing slashes and collapse repeats — mirrors
+ *  `pyric/storage`'s reference normalization so `usePathState` and
+ *  `useStorageList` always agree on what a path is. */
+export function normalizeStoragePath(path) {
+    return path.split('/').filter(Boolean).join('/');
+}
+/**
+ * Path navigation state for the storage browser. Controlled when
+ * `path` is provided (the owner re-renders with the next value),
+ * uncontrolled otherwise — standard React value/defaultValue
+ * semantics. All emitted paths are normalized (`normalizeStoragePath`).
+ */
+export function usePathState(options = {}) {
+    const { path: controlled, onPathChange, defaultPath = '' } = options;
+    const isControlled = controlled !== undefined;
+    const [internal, setInternal] = useState(() => normalizeStoragePath(defaultPath));
+    const path = isControlled ? normalizeStoragePath(controlled) : internal;
+    const setPath = useCallback((next) => {
+        const normalized = normalizeStoragePath(next);
+        if (!isControlled)
+            setInternal(normalized);
+        onPathChange?.(normalized);
+    }, [isControlled, onPathChange]);
+    const segments = useMemo(() => (path === '' ? [] : path.split('/')), [path]);
+    const enter = useCallback((nameOrPath) => {
+        const target = normalizeStoragePath(nameOrPath);
+        // An absolute descendant path (a prefix ref's fullPath) is used
+        // as-is; a bare name appends to the current path.
+        setPath(target.includes('/') || path === '' ? target : `${path}/${target}`);
+    }, [path, setPath]);
+    const up = useCallback(() => {
+        if (segments.length === 0)
+            return;
+        setPath(segments.slice(0, -1).join('/'));
+    }, [segments, setPath]);
+    const navigateToIndex = useCallback((index) => {
+        setPath(index < 0 ? '' : segments.slice(0, index + 1).join('/'));
+    }, [segments, setPath]);
+    return { path, segments, setPath, enter, up, navigateToIndex };
+}
+//# sourceMappingURL=usePathState.js.map

package/dist/storage/hooks/usePathState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePathState.js","sourceRoot":"","sources":["../../../src/storage/hooks/usePathState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEvD;;uDAEuD;AACvD,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACnD,CAAC;AAmCD;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,UAA+B,EAAE;IAEjC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IACrE,MAAM,YAAY,GAAG,UAAU,KAAK,SAAS,CAAC;IAC9C,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAAC;IAClF,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAExE,MAAM,OAAO,GAAG,WAAW,CACzB,CAAC,IAAY,EAAE,EAAE;QACf,MAAM,UAAU,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,CAAC,YAAY;YAAE,WAAW,CAAC,UAAU,CAAC,CAAC;QAC3C,YAAY,EAAE,CAAC,UAAU,CAAC,CAAC;IAC7B,CAAC,EACD,CAAC,YAAY,EAAE,YAAY,CAAC,CAC7B,CAAC;IAEF,MAAM,QAAQ,GAAG,OAAO,CACtB,GAAG,EAAE,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAC1C,CAAC,IAAI,CAAC,CACP,CAAC;IAEF,MAAM,KAAK,GAAG,WAAW,CACvB,CAAC,UAAkB,EAAE,EAAE;QACrB,MAAM,MAAM,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAChD,gEAAgE;QAChE,kDAAkD;QAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC,CAAC;IAC9E,CAAC,EACD,CAAC,IAAI,EAAE,OAAO,CAAC,CAChB,CAAC;IAEF,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE;QAC1B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAExB,MAAM,eAAe,GAAG,WAAW,CACjC,CAAC,KAAa,EAAE,EAAE;QAChB,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACnE,CAAC,EACD,CAAC,QAAQ,EAAE,OAAO,CAAC,CACpB,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC;AACjE,CAAC"}

package/dist/storage/hooks/useStorageDelete.d.ts

@@ -0,0 +1,74 @@
+import { type FirebaseStorage, type StorageReference } from 'pyric/storage';
+import type { StorageSelectionEntry } from './useStorageSelection.js';
+import type { UseStorageListResult } from './useStorageList.js';
+import { type StorageApi } from '../storageApi.js';
+export interface StorageDeleteProgress {
+    /** Objects deleted so far in this folder walk. */
+    deletedCount: number;
+    /** True for the final emission. */
+    done: boolean;
+}
+/**
+ * Recursive folder delete implementation — the same injection seam
+ * as the Firestore half's `RecursiveDeleteImpl`. Unlike Firestore
+ * (where tree-walking needs sandbox introspection or a Cloud
+ * Function), the public storage surface CAN walk a prefix, so the
+ * package ships {@link createListAllDeleteImpl} as the default;
+ * inject your own for server-driven deletes.
+ */
+export interface StorageRecursiveDeleteImpl {
+    start: (target: StorageReference) => AsyncIterableIterator<StorageDeleteProgress>;
+}
+/**
+ * The default, `listAll`-driven impl: walks the prefix tree,
+ * `deleteObject`s every item (yielding progress per object), then
+ * sweeps each visited folder's `<path>/` placeholder so emptied
+ * create-folder folders disappear too (`listAll` hides placeholders,
+ * so the walk alone would leave ghost folders). Placeholder sweeps
+ * are best-effort — `deletedCount` counts listed objects only.
+ */
+export declare function createListAllDeleteImpl(api?: Pick<StorageApi, 'listAll' | 'deleteObject'>): StorageRecursiveDeleteImpl;
+/** One entry's failure in a bulk run. `error` is the typed
+ *  `StorageError` (`.code` e.g. `storage/unauthorized`). */
+export interface StorageDeleteFailure {
+    fullPath: string;
+    error: Error;
+}
+export interface StorageDeleteOutcome {
+    /** fullPaths of entries fully deleted. */
+    deleted: string[];
+    failed: StorageDeleteFailure[];
+}
+export interface UseStorageDeleteOptions {
+    /** Folder-walk implementation. Default {@link createListAllDeleteImpl}. */
+    impl?: StorageRecursiveDeleteImpl;
+    /**
+     * Optimistic seam from `useStorageList`: entries vanish from the
+     * local list immediately and roll back (object → item, folder →
+     * trailing-slash prefix insert) on failure.
+     */
+    list?: Pick<UseStorageListResult, 'insertItem' | 'removeItem'>;
+}
+export interface UseStorageDeleteResult {
+    /**
+     * Delete a mixed object/folder selection (objects via
+     * `deleteObject`, folders via the recursive impl), sequentially in
+     * selection order. Resolves with the outcome and never rejects —
+     * per-entry failures land in `outcome.failed` (and `error` keeps
+     * the first one for simple renders).
+     */
+    deleteEntries: (entries: StorageSelectionEntry[]) => Promise<StorageDeleteOutcome>;
+    /** Objects deleted in the current/last run (folder walks included). */
+    progress: number;
+    isRunning: boolean;
+    /** First failure of the current/last run. Cleared on the next call. */
+    error: Error | undefined;
+}
+/**
+ * Drive bulk + recursive deletes from a React component — the
+ * storage counterpart of `useRecursiveDelete` (same progress /
+ * isRunning / error shape, same stale-run generation token), bulk
+ * because storage selections are flat multi-row affairs.
+ */
+export declare function useStorageDelete(storage: FirebaseStorage | null | undefined, options?: UseStorageDeleteOptions): UseStorageDeleteResult;
+//# sourceMappingURL=useStorageDelete.d.ts.map

package/dist/storage/hooks/useStorageDelete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStorageDelete.d.ts","sourceRoot":"","sources":["../../../src/storage/hooks/useStorageDelete.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGlE,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,CACL,MAAM,EAAE,gBAAgB,KACrB,qBAAqB,CAAC,qBAAqB,CAAC,CAAC;CACnD;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,GAAG,cAAc,CAAC,GACjD,0BAA0B,CAiC5B;AAED;4DAC4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,IAAI,CAAC,EAAE,0BAA0B,CAAC;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,YAAY,GAAG,YAAY,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,aAAa,EAAE,CACb,OAAO,EAAE,qBAAqB,EAAE,KAC7B,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC3C,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAiExB"}

package/dist/storage/hooks/useStorageDelete.js

@@ -0,0 +1,120 @@
+import { useCallback, useRef, useState } from 'react';
+import { deleteObject as defaultDeleteObject, listAll as defaultListAll, } from 'pyric/storage';
+import { useStorageApi } from '../storageApi.js';
+import { asFolderPlaceholder } from '../folderPlaceholder.js';
+/**
+ * The default, `listAll`-driven impl: walks the prefix tree,
+ * `deleteObject`s every item (yielding progress per object), then
+ * sweeps each visited folder's `<path>/` placeholder so emptied
+ * create-folder folders disappear too (`listAll` hides placeholders,
+ * so the walk alone would leave ghost folders). Placeholder sweeps
+ * are best-effort — `deletedCount` counts listed objects only.
+ */
+export function createListAllDeleteImpl(api) {
+    return {
+        async *start(target) {
+            const operations = api ?? {
+                listAll: defaultListAll,
+                deleteObject: defaultDeleteObject,
+            };
+            let deletedCount = 0;
+            const stack = [target];
+            const visited = [];
+            while (stack.length > 0) {
+                const folder = stack.pop();
+                visited.push(folder);
+                const result = await operations.listAll(folder);
+                stack.push(...result.prefixes);
+                for (const item of result.items) {
+                    await operations.deleteObject(item);
+                    deletedCount++;
+                    yield { deletedCount, done: false };
+                }
+            }
+            for (const folder of visited) {
+                try {
+                    await operations.deleteObject(asFolderPlaceholder(folder));
+                }
+                catch {
+                    // Best-effort: a strict backend may reject the structural
+                    // placeholder or throw not-found. Neither should fail the
+                    // recursive delete that already succeeded.
+                }
+            }
+            yield { deletedCount, done: true };
+        },
+    };
+}
+/**
+ * Drive bulk + recursive deletes from a React component — the
+ * storage counterpart of `useRecursiveDelete` (same progress /
+ * isRunning / error shape, same stale-run generation token), bulk
+ * because storage selections are flat multi-row affairs.
+ */
+export function useStorageDelete(storage, options = {}) {
+    const api = useStorageApi();
+    const [progress, setProgress] = useState(0);
+    const [isRunning, setIsRunning] = useState(false);
+    const [error, setError] = useState(undefined);
+    const generationRef = useRef(0);
+    // Latest-value ref so `deleteEntries` stays stable across option
+    // identity changes (house pattern).
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const deleteEntries = useCallback(async (entries) => {
+        const myGen = ++generationRef.current;
+        setProgress(0);
+        setError(undefined);
+        const outcome = { deleted: [], failed: [] };
+        if (storage == null || entries.length === 0)
+            return outcome;
+        setIsRunning(true);
+        const impl = optionsRef.current.impl ?? createListAllDeleteImpl(api);
+        let count = 0;
+        try {
+            for (const entry of entries) {
+                // Optimistic removal — the row vanishes immediately.
+                optionsRef.current.list?.removeItem(entry.fullPath);
+                try {
+                    if (entry.kind === 'object') {
+                        await api.deleteObject(api.ref(storage, entry.fullPath));
+                        count++;
+                    }
+                    else {
+                        for await (const evt of impl.start(api.ref(storage, entry.fullPath))) {
+                            if (myGen !== generationRef.current)
+                                return outcome;
+                            // The impl reports counts local to its walk; add the
+                            // objects already deleted by earlier entries.
+                            setProgress(count + evt.deletedCount);
+                            if (evt.done) {
+                                count += evt.deletedCount;
+                                break;
+                            }
+                        }
+                    }
+                    outcome.deleted.push(entry.fullPath);
+                    if (myGen === generationRef.current)
+                        setProgress(count);
+                }
+                catch (e) {
+                    const err = e instanceof Error ? e : new Error(String(e));
+                    outcome.failed.push({ fullPath: entry.fullPath, error: err });
+                    // Roll the optimistic removal back: objects re-insert as
+                    // items, folders as trailing-slash prefixes.
+                    optionsRef.current.list?.insertItem(entry.kind === 'folder' ? `${entry.fullPath}/` : entry.fullPath);
+                    if (myGen === generationRef.current && outcome.failed.length === 1) {
+                        setError(err);
+                    }
+                }
+            }
+            return outcome;
+        }
+        finally {
+            if (myGen === generationRef.current)
+                setIsRunning(false);
+        }
+    }, [api, storage]);
+    return { deleteEntries, progress, isRunning, error };
+}
+//# sourceMappingURL=useStorageDelete.js.map

package/dist/storage/hooks/useStorageDelete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStorageDelete.js","sourceRoot":"","sources":["../../../src/storage/hooks/useStorageDelete.ts"],"names":[],"mappings":"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"}

package/dist/storage/hooks/useStorageList.d.ts

@@ -0,0 +1,72 @@
+import type { FirebaseStorage, StorageReference } from 'pyric/storage';
+export type StorageListStatus = 'idle' | 'loading' | 'success' | 'error';
+/**
+ * One row of the merged folder/object model, the prefix→folder
+ * synthesis ported (as an idea, not code) from the emulator UI's
+ * `useStorageFiles`: `listAll`'s `prefixes` become `kind: 'folder'`
+ * rows, its `items` become `kind: 'object'` rows, folders first.
+ */
+export interface StorageListEntry {
+    kind: 'folder' | 'object';
+    /** Last path segment, display name. */
+    name: string;
+    /** Bucket-rooted path (no trailing slash, even for folders). */
+    fullPath: string;
+    ref: StorageReference;
+}
+export interface UseStorageListResult {
+    /** `'idle'` only when `storage` is null/undefined. */
+    status: StorageListStatus;
+    /** Direct child objects under `path`. Sorted by `fullPath`. */
+    items: StorageReference[];
+    /** Synthetic folder prefixes under `path`. Sorted by `fullPath`. */
+    prefixes: StorageReference[];
+    /** Folders-first merged row model. Derived from `prefixes` + `items`. */
+    entries: StorageListEntry[];
+    /**
+     * `StorageError` (with a typed `storage/<code>` on `.code`) from the
+     * sandbox. A denied list is `error.code === 'storage/unauthorized'`
+     * (ST-B2).
+     */
+    error: Error | undefined;
+    /** Re-run `listAll` for the current path. */
+    refresh: () => void;
+    /**
+     * Optimistic seam (consumed by M3 upload / M6 bulk ops, exposed
+     * now so those hooks layer on without reshaping this one). Inserts
+     * `fullPath` into the local list immediately, applying the same
+     * prefix→folder synthesis `listAll` would: a direct child becomes
+     * an item, a deeper descendant surfaces as its first-segment
+     * folder. A trailing slash declares a folder (the GCS placeholder
+     * convention `useObjectUpload.createFolder` writes): a direct
+     * trailing-slash child inserts a prefix, not an item. No-op for
+     * paths outside the listed path, duplicates, or when `status` is
+     * `'idle'`. What each call ACTUALLY inserted is recorded (keyed by
+     * the given `fullPath`) so `removeItem` can reverse it precisely.
+     * Rollback = `removeItem` or `refresh`.
+     */
+    insertItem: (fullPath: string) => void;
+    /**
+     * Optimistic counterpart. When `fullPath` was previously given to
+     * `insertItem`, this reverses EXACTLY what that call inserted: a
+     * deep upload that synthesized a first-segment folder row removes
+     * that folder row, and an insert that was a no-op (the row already
+     * existed — e.g. a real, listed folder) removes NOTHING, so a
+     * failed upload can never delete server-truth rows. For paths never
+     * seen by `insertItem` it removes the matching item/folder row
+     * directly (the optimistic-delete use). Rollback = `refresh`.
+     */
+    removeItem: (fullPath: string) => void;
+}
+/**
+ * List the objects + synthetic folders directly under `path` :
+ * `listAll` over the package's sandbox Storage handle. Read-via-get,
+ * not realtime: the list updates on `refresh`, path change, or the
+ * optimistic seam. Pass `''` (or the result of `usePathState`) for
+ * the bucket root.
+ *
+ * `listAll` has no pagination; a very large prefix arrives as one flat
+ * result (virtualize the rendering, which `<ObjectBrowser>` does).
+ */
+export declare function useStorageList(storage: FirebaseStorage | null | undefined, path: string): UseStorageListResult;
+//# sourceMappingURL=useStorageList.d.ts.map

package/dist/storage/hooks/useStorageList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStorageList.d.ts","sourceRoot":"","sources":["../../../src/storage/hooks/useStorageList.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAGvB,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,gBAAgB,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,+DAA+D;IAC/D,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,yEAAyE;IACzE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B;;;;OAIG;IACH,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IACzB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;;;;;;;;;;;OAaG;IACH,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;;;;;;;OASG;IACH,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AA0BD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,GACX,oBAAoB,CA0JtB"}

package/dist/storage/hooks/useStorageList.js

@@ -0,0 +1,164 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useStorageApi } from '../storageApi.js';
+/** Strip leading/trailing slashes so `'a/b/'`, `'/a/b'`, `'a/b'` agree. */
+function normalizePath(path) {
+    return path.replace(/^\/+|\/+$/g, '');
+}
+function byFullPath(a, b) {
+    return a.fullPath < b.fullPath ? -1 : a.fullPath > b.fullPath ? 1 : 0;
+}
+function insertSorted(list, next) {
+    if (list.some((r) => r.fullPath === next.fullPath))
+        return list;
+    return [...list, next].sort(byFullPath);
+}
+/**
+ * List the objects + synthetic folders directly under `path` :
+ * `listAll` over the package's sandbox Storage handle. Read-via-get,
+ * not realtime: the list updates on `refresh`, path change, or the
+ * optimistic seam. Pass `''` (or the result of `usePathState`) for
+ * the bucket root.
+ *
+ * `listAll` has no pagination; a very large prefix arrives as one flat
+ * result (virtualize the rendering, which `<ObjectBrowser>` does).
+ */
+export function useStorageList(storage, path) {
+    // Injected: in-process `pyric/storage` by default, or the SharedWorker client
+    // bundle in Studio served mode (via StorageApiProvider).
+    const { listAll, ref: refFn } = useStorageApi();
+    const normalized = normalizePath(path);
+    const [state, setState] = useState(() => ({
+        status: storage == null ? 'idle' : 'loading',
+        items: [],
+        prefixes: [],
+        error: undefined,
+    }));
+    const [tick, setTick] = useState(0);
+    // What each `insertItem(fullPath)` call ACTUALLY inserted, keyed by the
+    // normalized argument: the inserted row's fullPath, or null when the call
+    // was a no-op (row already present). `removeItem` consults this to reverse
+    // precisely; a fresh listing (server truth) clears the ledger.
+    const optimisticInserts = useRef(new Map());
+    useEffect(() => {
+        optimisticInserts.current.clear();
+        if (storage == null) {
+            setState({ status: 'idle', items: [], prefixes: [], error: undefined });
+            return;
+        }
+        let cancelled = false;
+        setState({ status: 'loading', items: [], prefixes: [], error: undefined });
+        listAll(refFn(storage, normalized))
+            .then((result) => {
+            if (cancelled)
+                return;
+            setState({
+                status: 'success',
+                // Defensive copy + sort pins the invariant the optimistic seam
+                // relies on even if the backing implementation changes.
+                items: [...result.items].sort(byFullPath),
+                prefixes: [...result.prefixes].sort(byFullPath),
+                error: undefined,
+            });
+        })
+            .catch((e) => {
+            if (cancelled)
+                return;
+            setState({
+                status: 'error',
+                items: [],
+                prefixes: [],
+                error: e instanceof Error ? e : new Error(String(e)),
+            });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [storage, normalized, tick]);
+    const refresh = useCallback(() => setTick((n) => n + 1), []);
+    const insertItem = useCallback((fullPath) => {
+        if (storage == null)
+            return;
+        // Trailing slash = folder declaration (a `<path>/` placeholder
+        // object surfaces as a prefix, never an item, same synthesis
+        // `listAll` applies).
+        const isFolder = fullPath.endsWith('/');
+        const target = normalizePath(fullPath);
+        const scanPrefix = normalized === '' ? '' : `${normalized}/`;
+        if (!target.startsWith(scanPrefix) || target === normalized)
+            return;
+        const relative = target.slice(scanPrefix.length);
+        const slashIdx = relative.indexOf('/');
+        setState((prev) => {
+            if (prev.status === 'idle')
+                return prev;
+            // Record what this call really adds (null = no-op) so removeItem can
+            // reverse it precisely. Idempotent under StrictMode's double-invoke:
+            // the same prev yields the same record.
+            if (slashIdx === -1) {
+                if (isFolder) {
+                    // Direct child folder.
+                    optimisticInserts.current.set(target, prev.prefixes.some((r) => r.fullPath === target) ? null : target);
+                    return {
+                        ...prev,
+                        prefixes: insertSorted(prev.prefixes, refFn(storage, target)),
+                    };
+                }
+                // Direct child object.
+                optimisticInserts.current.set(target, prev.items.some((r) => r.fullPath === target) ? null : target);
+                return { ...prev, items: insertSorted(prev.items, refFn(storage, target)) };
+            }
+            // Deeper descendant, surface its first segment as a folder,
+            // exactly like listAll's synthesis.
+            const folderPath = `${scanPrefix}${relative.slice(0, slashIdx)}`;
+            optimisticInserts.current.set(target, prev.prefixes.some((r) => r.fullPath === folderPath) ? null : folderPath);
+            return {
+                ...prev,
+                prefixes: insertSorted(prev.prefixes, refFn(storage, folderPath)),
+            };
+        });
+    }, [storage, normalized]);
+    const removeItem = useCallback((fullPath) => {
+        const target = normalizePath(fullPath);
+        const record = optimisticInserts.current.get(target);
+        optimisticInserts.current.delete(target);
+        // This path was optimistically inserted and the insert added nothing
+        // (the row pre-existed) — there is nothing of ours to remove, and
+        // removing by path would delete a server-truth row.
+        if (record === null)
+            return;
+        // Reverse the exact row the insert created (a deep upload's synthesized
+        // first-segment folder differs from the upload's own fullPath); fall
+        // back to the path itself for plain optimistic deletes.
+        const rowPath = record ?? target;
+        setState((prev) => ({
+            ...prev,
+            items: prev.items.filter((r) => r.fullPath !== rowPath),
+            prefixes: prev.prefixes.filter((r) => r.fullPath !== rowPath),
+        }));
+    }, []);
+    const entries = useMemo(() => [
+        ...state.prefixes.map((p) => ({
+            kind: 'folder',
+            name: p.name,
+            fullPath: p.fullPath,
+            ref: p,
+        })),
+        ...state.items.map((i) => ({
+            kind: 'object',
+            name: i.name,
+            fullPath: i.fullPath,
+            ref: i,
+        })),
+    ], [state.prefixes, state.items]);
+    return {
+        status: state.status,
+        items: state.items,
+        prefixes: state.prefixes,
+        entries,
+        error: state.error,
+        refresh,
+        insertItem,
+        removeItem,
+    };
+}
+//# sourceMappingURL=useStorageList.js.map

package/dist/storage/hooks/useStorageList.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStorageList.js","sourceRoot":"","sources":["../../../src/storage/hooks/useStorageList.ts"],"names":[],"mappings":"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"}

package/dist/storage/hooks/useStorageObject.d.ts

@@ -0,0 +1,33 @@
+import type { FirebaseStorage, FullMetadata } from 'pyric/storage';
+export type StorageObjectStatus = 'idle' | 'loading' | 'success' | 'error';
+export interface UseStorageObjectResult {
+    /** Metadata read state. `'idle'` when `storage` or `path` is null. */
+    status: StorageObjectStatus;
+    metadata: FullMetadata | undefined;
+    /** Typed `StorageError` (`storage/object-not-found`,
+     *  `storage/unauthorized`, …). */
+    error: Error | undefined;
+    /** Re-read the metadata (also resets the blob, the object may
+     *  have been overwritten). */
+    refresh: () => void;
+    /** Blob read state. Stays `'idle'` until `loadBlob()`, the blob
+     *  is LAZY; metadata alone never downloads bytes. */
+    blobStatus: StorageObjectStatus;
+    blob: Blob | undefined;
+    /**
+     * `URL.createObjectURL` handle for the loaded blob, used as the local
+     * preview channel. Revoked automatically when the blob is replaced,
+     * the path changes, or the hook unmounts.
+     */
+    blobUrl: string | undefined;
+    blobError: Error | undefined;
+    /** Fetch the bytes via `getBlob`. Subsequent calls re-fetch. */
+    loadBlob: () => void;
+}
+/**
+ * One object's metadata + lazily-loaded bytes, the data source for
+ * `<ObjectInspector>`. Read-via-get like the rest of the storage
+ * half: updates on `refresh`, `path` change, or `loadBlob`.
+ */
+export declare function useStorageObject(storage: FirebaseStorage | null | undefined, path: string | null | undefined): UseStorageObjectResult;
+//# sourceMappingURL=useStorageObject.d.ts.map

package/dist/storage/hooks/useStorageObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStorageObject.d.ts","sourceRoot":"","sources":["../../../src/storage/hooks/useStorageObject.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACb,MAAM,eAAe,CAAC;AAIvB,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE3E,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAC;IACnC;sCACkC;IAClC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IACzB;kCAC8B;IAC9B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;yDACqD;IACrD,UAAU,EAAE,mBAAmB,CAAC;IAChC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC;IACvB;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,EAAE,KAAK,GAAG,SAAS,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB;AAsBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC3C,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,sBAAsB,CAkGxB"}