@pyric/ui 0.1.0-alpha.7

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

@@ -0,0 +1,128 @@
+import { type FirebaseStorage, type StorageAuth, type StorageRules } from 'pyric/storage';
+export type StorageRulesGateStatus = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * Where the active ruleset came from:
+ * - `'option'` — the explicit `rules` option (string or pre-parsed).
+ * - `'sandbox'` — the ruleset deployed on the sandbox handle
+ *   (`getStorageSandbox(ctx, { rules })`), read off the handle's
+ *   `StorageService`.
+ * - `'none'` — no rules reachable. Every verdict allows
+ *   (open-by-default, the same semantics `pyric/storage`'s
+ *   enforcement layer applies when no rules are configured).
+ */
+export type StorageRulesSource = 'option' | 'sandbox' | 'none';
+/**
+ * Per-path verdict. `pyric/storage`'s rules subset has exactly two
+ * verbs (`read` | `write` — the granular get/list/create/update/
+ * delete forms are a parser follow-up), so `delete` and `upload` are
+ * DERIVED aliases of `write`: Firebase Storage's `write` permission
+ * governs create, overwrite, AND delete.
+ */
+export interface StorageGateVerdict {
+    read: boolean;
+    write: boolean;
+    /** Derived — always `=== write` under the two-verb subset. */
+    delete: boolean;
+    /** Derived — always `=== write` under the two-verb subset. */
+    upload: boolean;
+    /**
+     * Evaluator reason traces for DENIED verbs (`"no rule matches…"` /
+     * `"match /… : condition false"`); empty arrays when allowed.
+     * Feed into disabled-state tooltips and `data-*-reason` attributes.
+     */
+    reasons: {
+        read: string[];
+        write: string[];
+    };
+}
+export interface UseStorageRulesGateOptions {
+    /**
+     * Path (or paths) to pre-evaluate into `verdicts`, keyed by the
+     * normalized path. Ad-hoc paths (e.g. browser rows) go through
+     * `verdictFor` instead — the two are the same evaluation.
+     */
+    paths?: string | readonly string[];
+    /**
+     * Explicit rules source — raw rules text (parsed here; a malformed
+     * string surfaces as `status: 'error'`) or a pre-parsed
+     * `StorageRules` handle. Overrides the sandbox's deployed ruleset
+     * when both exist. REQUIRED for meaningful verdicts on prod
+     * handles: production rules live server-side and are not readable
+     * through the client SDK, so the gate cannot discover them.
+     */
+    rules?: string | StorageRules;
+    /**
+     * Identity override. `null` is anonymous; OMIT the field to use
+     * the handle's own identity (the sandbox context's `auth`). Prod
+     * handles carry no client-readable identity claims here, so prod
+     * callers pass the signed-in user's `{ uid, token }` explicitly.
+     */
+    identity?: StorageAuth | null;
+    /**
+     * The about-to-write payload bound to `request.resource` for the
+     * WRITE evaluation — pass `{ size, contentType }` when gating a
+     * specific upload so size/contentType-conditioned rules evaluate
+     * truthfully. When omitted, `request.resource` is unset, which is
+     * exactly DELETE semantics (deletes carry no inbound payload) —
+     * a rule like `request.resource.size < N` then denies, the
+     * conservative answer for uploads.
+     */
+    writeResource?: {
+        size: number;
+        contentType?: string;
+    };
+}
+export interface UseStorageRulesGateResult {
+    /** `'idle'` only when `storage` is null/undefined. */
+    status: StorageRulesGateStatus;
+    /** Where the active ruleset came from. */
+    source: StorageRulesSource;
+    /**
+     * True for prod handles: client-side evaluation is ADVISORY there
+     * — the server's evaluator is authoritative, and this gate only
+     * sees whatever the `rules` option mirrors (which can drift from
+     * what is deployed). Sandbox verdicts come from the same evaluator
+     * the sandbox enforces with, so they are truthful.
+     */
+    advisory: boolean;
+    /** The identity the verdicts evaluate under. */
+    identity: StorageAuth | null;
+    /** Pre-evaluated verdicts for `options.paths`, keyed by normalized path. */
+    verdicts: Record<string, StorageGateVerdict>;
+    /**
+     * Evaluate an arbitrary path under the current ruleset + identity.
+     * Pure and synchronous once `status` is `'ready'`; before that
+     * (and whenever no rules are reachable) it returns the allow-all
+     * verdict — the gate FAILS OPEN, because affordances are advisory
+     * and the real enforcement (sandbox throw / server denial) stays
+     * authoritative.
+     */
+    verdictFor: (path: string) => StorageGateVerdict;
+    /** Rules-resolution failure (e.g. a malformed `rules` string). */
+    error: Error | undefined;
+}
+/**
+ * Pre-flight rules evaluation — the M7 differentiator. Evaluates the
+ * current identity against paths BEFORE the click, so components can
+ * annotate denied affordances (`data-pyric-denied`, disabled-with-
+ * reason) instead of letting the user discover a denial via a thrown
+ * `storage/unauthorized`.
+ *
+ * Rules discovery: a sandbox handle carries its deployed ruleset
+ * (`getStorageSandbox(ctx, { rules })` parses it into the handle's
+ * `StorageService`) — the hook reads it through the handle's target,
+ * so sandbox callers pass nothing. Identity likewise defaults to the
+ * handle's `SandboxContext.auth`. Prod handles expose neither
+ * (rules + claims live server-side), so prod callers pass `rules` +
+ * `identity` explicitly and treat verdicts as advisory (`advisory:
+ * true` — the server is authoritative).
+ *
+ * Evaluation contract (mirrors `pyric/storage`'s own enforcement):
+ * `resource` (the existing object) is bound as `null` — the gate
+ * pre-evaluates without fetching per-path metadata, matching how the
+ * sandbox enforces `listAll`. Rules conditioned on existing-object
+ * state (`resource.*`) evaluate as if the object doesn't exist; the
+ * common identity/path/payload-shaped rules evaluate exactly.
+ */
+export declare function useStorageRulesGate(storage: FirebaseStorage | null | undefined, options?: UseStorageRulesGateOptions): UseStorageRulesGateResult;
+//# sourceMappingURL=useStorageRulesGate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useStorageRulesGate.d.ts","sourceRoot":"","sources":["../../../src/storage/hooks/useStorageRulesGate.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,WAAW,EAEhB,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAGvB,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5E;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC9B;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD;AAED,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,MAAM,EAAE,sBAAsB,CAAC;IAC/B,0CAA0C;IAC1C,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC7C;;;;;;;OAOG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,kBAAkB,CAAC;IACjD,kEAAkE;IAClE,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;CAC1B;AAqBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC3C,OAAO,GAAE,0BAA+B,GACvC,yBAAyB,CAiI3B"}

package/dist/storage/hooks/useStorageRulesGate.js

@@ -0,0 +1,158 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { TARGET_SYMBOL, parseStorageRules, evaluateStorageRules, } from 'pyric/storage';
+import { normalizeStoragePath } from './usePathState.js';
+/** Shared allow-all verdict — idle/loading/error and rules-less states. */
+const ALLOW_ALL = Object.freeze({
+    read: true,
+    write: true,
+    delete: true,
+    upload: true,
+    reasons: Object.freeze({
+        read: [],
+        write: [],
+    }),
+});
+/**
+ * Pre-flight rules evaluation — the M7 differentiator. Evaluates the
+ * current identity against paths BEFORE the click, so components can
+ * annotate denied affordances (`data-pyric-denied`, disabled-with-
+ * reason) instead of letting the user discover a denial via a thrown
+ * `storage/unauthorized`.
+ *
+ * Rules discovery: a sandbox handle carries its deployed ruleset
+ * (`getStorageSandbox(ctx, { rules })` parses it into the handle's
+ * `StorageService`) — the hook reads it through the handle's target,
+ * so sandbox callers pass nothing. Identity likewise defaults to the
+ * handle's `SandboxContext.auth`. Prod handles expose neither
+ * (rules + claims live server-side), so prod callers pass `rules` +
+ * `identity` explicitly and treat verdicts as advisory (`advisory:
+ * true` — the server is authoritative).
+ *
+ * Evaluation contract (mirrors `pyric/storage`'s own enforcement):
+ * `resource` (the existing object) is bound as `null` — the gate
+ * pre-evaluates without fetching per-path metadata, matching how the
+ * sandbox enforces `listAll`. Rules conditioned on existing-object
+ * state (`resource.*`) evaluate as if the object doesn't exist; the
+ * common identity/path/payload-shaped rules evaluate exactly.
+ */
+export function useStorageRulesGate(storage, options = {}) {
+    const { paths, rules: rulesOption, identity: identityOption, writeResource } = options;
+    const target = storage == null ? null : storage[TARGET_SYMBOL];
+    const [state, setState] = useState(() => ({
+        status: storage == null ? 'idle' : 'loading',
+        rules: null,
+        source: 'none',
+        error: undefined,
+    }));
+    useEffect(() => {
+        if (target == null) {
+            setState({ status: 'idle', rules: null, source: 'none', error: undefined });
+            return;
+        }
+        // Explicit option wins — and is the only channel for prod.
+        if (rulesOption != null) {
+            try {
+                const parsed = typeof rulesOption === 'string' ? parseStorageRules(rulesOption) : rulesOption;
+                setState({ status: 'ready', rules: parsed, source: 'option', error: undefined });
+            }
+            catch (e) {
+                setState({
+                    status: 'error',
+                    rules: null,
+                    source: 'none',
+                    error: e instanceof Error ? e : new Error(String(e)),
+                });
+            }
+            return;
+        }
+        if (target.kind === 'sandbox') {
+            let cancelled = false;
+            setState({ status: 'loading', rules: null, source: 'none', error: undefined });
+            target.servicePromise
+                .then((service) => {
+                if (cancelled)
+                    return;
+                setState({
+                    status: 'ready',
+                    rules: service.rules,
+                    source: service.rules ? 'sandbox' : 'none',
+                    error: undefined,
+                });
+            })
+                .catch((e) => {
+                if (cancelled)
+                    return;
+                setState({
+                    status: 'error',
+                    rules: null,
+                    source: 'none',
+                    error: e instanceof Error ? e : new Error(String(e)),
+                });
+            });
+            return () => {
+                cancelled = true;
+            };
+        }
+        // Prod handle without an explicit ruleset: nothing to evaluate —
+        // open verdicts, advisory.
+        setState({ status: 'ready', rules: null, source: 'none', error: undefined });
+    }, [target, rulesOption]);
+    // `undefined` means "derive from the handle"; an explicit `null`
+    // means anonymous.
+    const identity = identityOption !== undefined
+        ? identityOption
+        : target?.kind === 'sandbox'
+            ? target.context.auth
+            : null;
+    const { rules, status } = state;
+    const writeSize = writeResource?.size;
+    const writeContentType = writeResource?.contentType;
+    const verdictFor = useCallback((path) => {
+        if (rules == null)
+            return ALLOW_ALL;
+        const evaluate = (method) => evaluateStorageRules(rules, {
+            request: {
+                auth: identity,
+                method,
+                path: normalizeStoragePath(path),
+                ...(method === 'write' && writeSize !== undefined
+                    ? { resource: { size: writeSize, contentType: writeContentType } }
+                    : {}),
+            },
+            resource: null,
+        });
+        const read = evaluate('read');
+        const write = evaluate('write');
+        return {
+            read: read.allowed,
+            write: write.allowed,
+            delete: write.allowed,
+            upload: write.allowed,
+            reasons: {
+                read: read.allowed ? [] : read.reasons,
+                write: write.allowed ? [] : write.reasons,
+            },
+        };
+    }, [rules, identity, writeSize, writeContentType]);
+    const pathsKey = typeof paths === 'string' ? paths : (paths ?? []).join('\n');
+    const verdicts = useMemo(() => {
+        const list = typeof paths === 'string' ? [paths] : (paths ?? []);
+        const out = {};
+        for (const p of list) {
+            out[normalizeStoragePath(p)] = verdictFor(p);
+        }
+        return out;
+        // `pathsKey` stands in for the (possibly inline) array identity,
+        // so a fresh-but-equal `paths` array doesn't churn the record.
+    }, [pathsKey, verdictFor]);
+    return {
+        status,
+        source: state.source,
+        advisory: target?.kind === 'prod',
+        identity,
+        verdicts,
+        verdictFor,
+        error: state.error,
+    };
+}
+//# sourceMappingURL=useStorageRulesGate.js.map

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * What the selection tracks per row — a structural subset of
+ * `StorageListEntry`, so `useStorageList`'s entries pass straight
+ * in. The `kind` decides the delete verb later (object →
+ * `deleteObject`, folder → recursive).
+ */
+export interface StorageSelectionEntry {
+    kind: 'folder' | 'object';
+    fullPath: string;
+}
+export interface UseStorageSelectionResult {
+    /** Selected entries in selection order. */
+    selected: StorageSelectionEntry[];
+    size: number;
+    isSelected: (fullPath: string) => boolean;
+    /** Add/remove — the checkbox verb. */
+    toggle: (entry: StorageSelectionEntry) => void;
+    select: (entry: StorageSelectionEntry) => void;
+    deselect: (fullPath: string) => void;
+    /** Replace the selection (e.g. a "select all" over
+     *  `list.entries`). */
+    selectAll: (entries: StorageSelectionEntry[]) => void;
+    clear: () => void;
+}
+/**
+ * Multi-select state over storage rows, keyed by `fullPath`.
+ * Deliberately dumb: it doesn't watch the list, so clear it on path
+ * change (or after a bulk op via the delete hook's outcome) — the
+ * consumer owns that policy.
+ */
+export declare function useStorageSelection(): UseStorageSelectionResult;
+//# sourceMappingURL=useStorageSelection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useStorageSelection.d.ts","sourceRoot":"","sources":["../../../src/storage/hooks/useStorageSelection.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,2CAA2C;IAC3C,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C,sCAAsC;IACtC,MAAM,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC/C,MAAM,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC/C,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;2BACuB;IACvB,SAAS,EAAE,CAAC,OAAO,EAAE,qBAAqB,EAAE,KAAK,IAAI,CAAC;IACtD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,yBAAyB,CAuD/D"}

package/dist/storage/hooks/useStorageSelection.js

@@ -0,0 +1,55 @@
+import { useCallback, useMemo, useState } from 'react';
+/**
+ * Multi-select state over storage rows, keyed by `fullPath`.
+ * Deliberately dumb: it doesn't watch the list, so clear it on path
+ * change (or after a bulk op via the delete hook's outcome) — the
+ * consumer owns that policy.
+ */
+export function useStorageSelection() {
+    const [map, setMap] = useState(() => new Map());
+    const isSelected = useCallback((fullPath) => map.has(fullPath), [map]);
+    const select = useCallback((entry) => {
+        setMap((prev) => {
+            if (prev.has(entry.fullPath))
+                return prev;
+            const next = new Map(prev);
+            next.set(entry.fullPath, entry);
+            return next;
+        });
+    }, []);
+    const deselect = useCallback((fullPath) => {
+        setMap((prev) => {
+            if (!prev.has(fullPath))
+                return prev;
+            const next = new Map(prev);
+            next.delete(fullPath);
+            return next;
+        });
+    }, []);
+    const toggle = useCallback((entry) => {
+        setMap((prev) => {
+            const next = new Map(prev);
+            if (next.has(entry.fullPath))
+                next.delete(entry.fullPath);
+            else
+                next.set(entry.fullPath, entry);
+            return next;
+        });
+    }, []);
+    const selectAll = useCallback((entries) => {
+        setMap(new Map(entries.map((e) => [e.fullPath, e])));
+    }, []);
+    const clear = useCallback(() => setMap(new Map()), []);
+    const selected = useMemo(() => [...map.values()], [map]);
+    return {
+        selected,
+        size: map.size,
+        isSelected,
+        toggle,
+        select,
+        deselect,
+        selectAll,
+        clear,
+    };
+}
+//# sourceMappingURL=useStorageSelection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useStorageSelection.js","sourceRoot":"","sources":["../../../src/storage/hooks/useStorageSelection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AA4BvD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,QAAQ,CAC5B,GAAG,EAAE,CAAC,IAAI,GAAG,EAAE,CAChB,CAAC;IAEF,MAAM,UAAU,GAAG,WAAW,CAC5B,CAAC,QAAgB,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EACvC,CAAC,GAAG,CAAC,CACN,CAAC;IAEF,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,KAA4B,EAAE,EAAE;QAC1D,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;YACd,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC1C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,QAAgB,EAAE,EAAE;QAChD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;YACd,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAAE,OAAO,IAAI,CAAC;YACrC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,MAAM,GAAG,WAAW,CAAC,CAAC,KAA4B,EAAE,EAAE;QAC1D,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;YACd,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC;gBAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;;gBACrD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,OAAgC,EAAE,EAAE;QACjE,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAEvD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEzD,OAAO;QACL,QAAQ;QACR,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,UAAU;QACV,MAAM;QACN,MAAM;QACN,QAAQ;QACR,SAAS;QACT,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/storage/index.d.ts

@@ -0,0 +1,11 @@
+export * from './hooks/index.js';
+export { StorageApiProvider, useStorageApi, type StorageApi } from './storageApi.js';
+export { PathBreadcrumb, type PathBreadcrumbProps, } from './components/PathBreadcrumb.js';
+export { ObjectBrowser, type ObjectBrowserProps, } from './components/ObjectBrowser.js';
+export { UploadDropzone, type UploadDropzoneProps, type DroppedFile, } from './components/UploadDropzone.js';
+export { splitStorageName, parseCopyCounter, resolveCollision, planBatchNames, } from './collisionRename.js';
+export { expandPathChain, initialPendingPrefixes, pendingPrefixReducer, pendingChildFolders, isPendingPrefix, folderInputError, type PendingPrefixState, type PendingPrefixAction, } from './pendingPrefixes.js';
+export { defaultStoragePreviews, imagePreview, textPreview, selectStoragePreview, TEXT_PREVIEW_MAX_BYTES, type StoragePreview, type StoragePreviewContext, } from './previews.js';
+export { ObjectInspector, type ObjectInspectorProps, } from './components/ObjectInspector.js';
+export { DeleteSelectionWithConfirm, type DeleteSelectionWithConfirmProps, } from './components/DeleteSelectionWithConfirm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AAIjC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,GACxB,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,GAC1B,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EACL,0BAA0B,EAC1B,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC"}

package/dist/storage/index.js

@@ -0,0 +1,17 @@
+export * from './hooks/index.js';
+// Injectable Storage API bundle (Pyric Studio data-backend swap): defaults to
+// in-process `pyric/storage`; a consumer can provide the SharedWorker client.
+export { StorageApiProvider, useStorageApi } from './storageApi.js';
+// M2: navigation shell
+export { PathBreadcrumb, } from './components/PathBreadcrumb.js';
+export { ObjectBrowser, } from './components/ObjectBrowser.js';
+// M3: upload
+export { UploadDropzone, } from './components/UploadDropzone.js';
+export { splitStorageName, parseCopyCounter, resolveCollision, planBatchNames, } from './collisionRename.js';
+export { expandPathChain, initialPendingPrefixes, pendingPrefixReducer, pendingChildFolders, isPendingPrefix, folderInputError, } from './pendingPrefixes.js';
+// M4: inspection, content-type preview registry + inspector
+export { defaultStoragePreviews, imagePreview, textPreview, selectStoragePreview, TEXT_PREVIEW_MAX_BYTES, } from './previews.js';
+export { ObjectInspector, } from './components/ObjectInspector.js';
+// M6: bulk ops
+export { DeleteSelectionWithConfirm, } from './components/DeleteSelectionWithConfirm.js';
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AAEjC,8EAA8E;AAC9E,8EAA8E;AAC9E,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAmB,MAAM,iBAAiB,CAAC;AAErF,uBAAuB;AACvB,OAAO,EACL,cAAc,GAEf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,aAAa,GAEd,MAAM,+BAA+B,CAAC;AAEvC,aAAa;AACb,OAAO,EACL,cAAc,GAGf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,GAGjB,MAAM,sBAAsB,CAAC;AAE9B,4DAA4D;AAC5D,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,sBAAsB,GAGvB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,GAEhB,MAAM,iCAAiC,CAAC;AAEzC,eAAe;AACf,OAAO,EACL,0BAA0B,GAE3B,MAAM,4CAA4C,CAAC"}

package/dist/storage/pendingPrefixes.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Pending (not-yet-materialized) folder prefixes — pure reducer, no React.
+ *
+ * MECHANISM DECISION (create-folder). GCS has no real folders: a
+ * "folder" exists only as a shared prefix of object names. Two honest
+ * ways to let a user create one before it contains anything:
+ *
+ *  a) write a zero-byte `<path>/` placeholder object (the emulator-UI
+ *     convention — `useObjectUpload.createFolder` does this): the
+ *     folder survives reloads, but every created folder deposits a
+ *     phantom object in the sandbox store, and the trailing-slash ref
+ *     is sandbox-only (prod `ref()` rejects it, and the Studio worker
+ *     `StorageApi` path has no channel for it at all);
+ *
+ *  b) hold the created prefix as CLIENT-SIDE PENDING STATE and let the
+ *     first upload into it materialize it for real. The store stays
+ *     byte-for-byte clean — nothing is written until a file is — at
+ *     the cost that a created-then-abandoned empty folder disappears
+ *     on reload.
+ *
+ * Studio's create-folder flow uses (b): the sandbox store is the
+ * user's actual data and must not accrue placeholder objects, and the
+ * disappearing-empty-folder tradeoff is acceptable BECAUSE the UI
+ * labels pending rows as session-only ("empty" badge + empty-state
+ * copy in `StoragePane`). (a) remains available to consumers who want
+ * persistent empty folders in sandbox-only setups.
+ *
+ * State is a sorted list of normalized bucket-rooted prefix paths (no
+ * trailing slashes). Creating `stuff/things/cool` expands the whole
+ * chain — `stuff`, `stuff/things`, `stuff/things/cool` — so every
+ * ancestor level shows the folder while browsing (VS Code-style nested
+ * create). A successful upload MATERIALIZES its destination folder:
+ * the chain up to that folder leaves pending state (the real listing
+ * now surfaces those prefixes); pending descendants of other branches
+ * stay.
+ */
+/** Sorted, deduped, normalized pending prefix paths. */
+export type PendingPrefixState = readonly string[];
+export type PendingPrefixAction = 
+/** Create a folder at `path` (absolute, bucket-rooted; nested paths
+ *  allowed) — adds the full ancestor chain. */
+{
+    type: 'create';
+    path: string;
+}
+/** An object now exists directly under `path`: drop `path` and its
+ *  ancestors from pending (they are real prefixes now). */
+ | {
+    type: 'materialize';
+    path: string;
+} | {
+    type: 'clear';
+};
+/** `'a/b/c'` → `['a', 'a/b', 'a/b/c']`; `''` → `[]`. */
+export declare function expandPathChain(path: string): string[];
+export declare const initialPendingPrefixes: PendingPrefixState;
+export declare function pendingPrefixReducer(state: PendingPrefixState, action: PendingPrefixAction): PendingPrefixState;
+/** Direct-child folder NAMES pending under `parentPath` (`''` = root),
+ *  sorted. The chain expansion guarantees every level is present, so a
+ *  simple parent match is exact. */
+export declare function pendingChildFolders(state: PendingPrefixState, parentPath: string): string[];
+/** Whether `path` itself is a pending (session-only) folder. */
+export declare function isPendingPrefix(state: PendingPrefixState, path: string): boolean;
+/**
+ * Validate a create-folder input (relative to the current folder;
+ * nested `a/b/c` allowed — VS Code semantics). Returns an error
+ * message or `null` when valid. Normalization tolerates stray/repeat
+ * slashes; `.`/`..` segments are rejected (GCS object names have no
+ * dot-segment semantics — accepting them would create unreachable
+ * names).
+ */
+export declare function folderInputError(input: string): string | null;
+//# sourceMappingURL=pendingPrefixes.d.ts.map

package/dist/storage/pendingPrefixes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pendingPrefixes.d.ts","sourceRoot":"","sources":["../../src/storage/pendingPrefixes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,wDAAwD;AACxD,MAAM,MAAM,kBAAkB,GAAG,SAAS,MAAM,EAAE,CAAC;AAEnD,MAAM,MAAM,mBAAmB;AAC7B;+CAC+C;AAC7C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAClC;2DAC2D;GACzD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAKtD;AAED,eAAO,MAAM,sBAAsB,EAAE,kBAAuB,CAAC;AAE7D,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,mBAAmB,GAC1B,kBAAkB,CAgBpB;AAED;;oCAEoC;AACpC,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAMV;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ7D"}

package/dist/storage/pendingPrefixes.js

@@ -0,0 +1,98 @@
+/**
+ * Pending (not-yet-materialized) folder prefixes — pure reducer, no React.
+ *
+ * MECHANISM DECISION (create-folder). GCS has no real folders: a
+ * "folder" exists only as a shared prefix of object names. Two honest
+ * ways to let a user create one before it contains anything:
+ *
+ *  a) write a zero-byte `<path>/` placeholder object (the emulator-UI
+ *     convention — `useObjectUpload.createFolder` does this): the
+ *     folder survives reloads, but every created folder deposits a
+ *     phantom object in the sandbox store, and the trailing-slash ref
+ *     is sandbox-only (prod `ref()` rejects it, and the Studio worker
+ *     `StorageApi` path has no channel for it at all);
+ *
+ *  b) hold the created prefix as CLIENT-SIDE PENDING STATE and let the
+ *     first upload into it materialize it for real. The store stays
+ *     byte-for-byte clean — nothing is written until a file is — at
+ *     the cost that a created-then-abandoned empty folder disappears
+ *     on reload.
+ *
+ * Studio's create-folder flow uses (b): the sandbox store is the
+ * user's actual data and must not accrue placeholder objects, and the
+ * disappearing-empty-folder tradeoff is acceptable BECAUSE the UI
+ * labels pending rows as session-only ("empty" badge + empty-state
+ * copy in `StoragePane`). (a) remains available to consumers who want
+ * persistent empty folders in sandbox-only setups.
+ *
+ * State is a sorted list of normalized bucket-rooted prefix paths (no
+ * trailing slashes). Creating `stuff/things/cool` expands the whole
+ * chain — `stuff`, `stuff/things`, `stuff/things/cool` — so every
+ * ancestor level shows the folder while browsing (VS Code-style nested
+ * create). A successful upload MATERIALIZES its destination folder:
+ * the chain up to that folder leaves pending state (the real listing
+ * now surfaces those prefixes); pending descendants of other branches
+ * stay.
+ */
+import { normalizeStoragePath } from './hooks/usePathState.js';
+/** `'a/b/c'` → `['a', 'a/b', 'a/b/c']`; `''` → `[]`. */
+export function expandPathChain(path) {
+    const normalized = normalizeStoragePath(path);
+    if (normalized === '')
+        return [];
+    const segments = normalized.split('/');
+    return segments.map((_, i) => segments.slice(0, i + 1).join('/'));
+}
+export const initialPendingPrefixes = [];
+export function pendingPrefixReducer(state, action) {
+    switch (action.type) {
+        case 'create': {
+            const chain = expandPathChain(action.path).filter((p) => !state.includes(p));
+            if (chain.length === 0)
+                return state;
+            return [...state, ...chain].sort();
+        }
+        case 'materialize': {
+            const real = new Set(expandPathChain(action.path));
+            if (real.size === 0)
+                return state;
+            const next = state.filter((p) => !real.has(p));
+            return next.length === state.length ? state : next;
+        }
+        case 'clear':
+            return state.length === 0 ? state : initialPendingPrefixes;
+    }
+}
+/** Direct-child folder NAMES pending under `parentPath` (`''` = root),
+ *  sorted. The chain expansion guarantees every level is present, so a
+ *  simple parent match is exact. */
+export function pendingChildFolders(state, parentPath) {
+    const parent = normalizeStoragePath(parentPath);
+    const prefix = parent === '' ? '' : `${parent}/`;
+    return state
+        .filter((p) => p.startsWith(prefix) && p !== parent && !p.slice(prefix.length).includes('/'))
+        .map((p) => p.slice(prefix.length));
+}
+/** Whether `path` itself is a pending (session-only) folder. */
+export function isPendingPrefix(state, path) {
+    return state.includes(normalizeStoragePath(path));
+}
+/**
+ * Validate a create-folder input (relative to the current folder;
+ * nested `a/b/c` allowed — VS Code semantics). Returns an error
+ * message or `null` when valid. Normalization tolerates stray/repeat
+ * slashes; `.`/`..` segments are rejected (GCS object names have no
+ * dot-segment semantics — accepting them would create unreachable
+ * names).
+ */
+export function folderInputError(input) {
+    const normalized = normalizeStoragePath(input);
+    if (normalized === '')
+        return 'Enter a folder name.';
+    const segments = normalized.split('/');
+    if (segments.some((s) => s === '.' || s === '..')) {
+        return 'Folder names may not be "." or "..".';
+    }
+    return null;
+}
+//# sourceMappingURL=pendingPrefixes.js.map

package/dist/storage/pendingPrefixes.js.map

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