@pyric/ui 0.1.0-alpha.10

package/dist/storage/hooks/index.js

@@ -0,0 +1,9 @@
+export { useStorageList, } from './useStorageList.js';
+export { usePathState, normalizeStoragePath, } from './usePathState.js';
+export { useStorageObject, } from './useStorageObject.js';
+export { useMetadataEditor, metadataEditorReducer, initMetadataEditorState, } from './useMetadataEditor.js';
+export { useStorageSelection, } from './useStorageSelection.js';
+export { useStorageDelete, createListAllDeleteImpl, } from './useStorageDelete.js';
+export { useStorageRulesGate, } from './useStorageRulesGate.js';
+export { useObjectUpload, } from './useObjectUpload.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/storage/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAIf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,YAAY,EACZ,oBAAoB,GAGrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,GAGjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,GAMxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,mBAAmB,GAGpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,gBAAgB,EAChB,uBAAuB,GAOxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,GAMpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,eAAe,GAOhB,MAAM,sBAAsB,CAAC"}

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

@@ -0,0 +1,114 @@
+import { type FirebaseStorage, type FullMetadata, type SettableMetadata } from 'pyric/storage';
+/** One `customMetadata` row. `id` is a stable render key — keys are
+ *  user-editable, so they can't key the rows themselves. */
+export interface CustomMetadataEntry {
+    id: string;
+    key: string;
+    value: string;
+    /** Validation error (`'Key is required'` / `'Duplicate key'`). */
+    error?: string;
+}
+interface MetadataDraft {
+    contentType: string;
+    cacheControl: string;
+    custom: CustomMetadataEntry[];
+}
+export interface MetadataEditorState {
+    draft: MetadataDraft;
+    /** Snapshot for `isDirty` / `reset` — same reference-compare
+     *  semantics as the document editor's `tree !== initial`. */
+    initial: MetadataDraft;
+    errorCount: number;
+}
+export type MetadataEditorAction = {
+    type: 'setContentType';
+    value: string;
+} | {
+    type: 'setCacheControl';
+    value: string;
+} | {
+    type: 'setCustomKey';
+    id: string;
+    key: string;
+} | {
+    type: 'setCustomValue';
+    id: string;
+    value: string;
+} | {
+    type: 'addCustomEntry';
+    key?: string;
+    value?: string;
+} | {
+    type: 'removeCustomEntry';
+    id: string;
+} | {
+    type: 'reset';
+}
+/** Internal — a successful save makes the draft the new baseline. */
+ | {
+    type: 'commit';
+};
+/** Pure reducer — exported (with {@link initMetadataEditorState}) so
+ *  the edit state is testable without React, mirroring the document
+ *  editor's reducer/hook split. */
+export declare function metadataEditorReducer(state: MetadataEditorState, action: MetadataEditorAction): MetadataEditorState;
+/** Build the edit state from the metadata a `getMetadata` /
+ *  `useStorageObject` read returned. */
+export declare function initMetadataEditorState(initial: SettableMetadata | undefined): MetadataEditorState;
+export interface UseMetadataEditorOptions {
+    /** The metadata being edited — the same shape `useStorageObject`'s
+     *  `metadata` carries. Read once on mount (the editor is a
+     *  stateful workspace, like the document editor); `reset()` +
+     *  remount to re-initialize. */
+    initial?: SettableMetadata;
+}
+export interface UseMetadataEditorResult {
+    contentType: string;
+    cacheControl: string;
+    custom: CustomMetadataEntry[];
+    /** Convenience: `errorCount === 0`. */
+    isValid: boolean;
+    /** `true` once any modifying action fired since the last
+     *  `reset`/successful `save`. Reference-compare semantics — manual
+     *  re-entry of the original values does NOT clear it. */
+    isDirty: boolean;
+    errorCount: number;
+    /** Raw dispatch — prefer the named helpers. */
+    dispatch: (action: MetadataEditorAction) => void;
+    setContentType: (value: string) => void;
+    setCacheControl: (value: string) => void;
+    setCustomKey: (id: string, key: string) => void;
+    setCustomValue: (id: string, value: string) => void;
+    addCustomEntry: (key?: string, value?: string) => void;
+    removeCustomEntry: (id: string) => void;
+    /** Restore the initial values. Clears `isDirty`. */
+    reset: () => void;
+    /**
+     * Serialize the draft to an `updateMetadata` patch. Empty
+     * `contentType`/`cacheControl` become `undefined` — which LEAVES
+     * the previous value (the sandbox doesn't model null-clears; see
+     * `pyric/storage`'s `updateMetadata` doc). `customMetadata` is
+     * always included and replaces wholesale, so row removal works.
+     */
+    toPatch: () => SettableMetadata;
+    /**
+     * `updateMetadata(ref(storage, path), toPatch())`. Errors surface
+     * via `saveError` (typed `StorageError`), not throws — resolves
+     * `undefined` on failure or when the draft is invalid. On success
+     * the draft becomes the new baseline (`isDirty` clears) and the
+     * fresh `FullMetadata` is returned.
+     */
+    save: () => Promise<FullMetadata | undefined>;
+    isSaving: boolean;
+    saveError: Error | undefined;
+}
+/**
+ * Headless metadata editor — the `useDocumentEditor` reducer pattern
+ * over `updateMetadata`: a pure reducer owns the draft (contentType,
+ * cacheControl, customMetadata k/v rows with stable ids +
+ * empty/duplicate-key validation); the hook adds named dispatch
+ * helpers and the save half.
+ */
+export declare function useMetadataEditor(storage: FirebaseStorage | null | undefined, path: string | null | undefined, options?: UseMetadataEditorOptions): UseMetadataEditorResult;
+export {};
+//# sourceMappingURL=useMetadataEditor.d.ts.map

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

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

package/dist/storage/hooks/useMetadataEditor.js

@@ -0,0 +1,193 @@
+import { useCallback, useMemo, useReducer, useRef, useState } from 'react';
+import { ref as refFn, updateMetadata, } from 'pyric/storage';
+import { normalizeStoragePath } from './usePathState.js';
+/** Re-validate the k/v rows: empty keys and duplicate keys error. */
+function validateCustom(custom) {
+    const counts = new Map();
+    for (const entry of custom) {
+        counts.set(entry.key, (counts.get(entry.key) ?? 0) + 1);
+    }
+    let errorCount = 0;
+    const next = custom.map((entry) => {
+        let error;
+        if (entry.key.trim() === '')
+            error = 'Key is required';
+        else if ((counts.get(entry.key) ?? 0) > 1)
+            error = 'Duplicate key';
+        if (error)
+            errorCount++;
+        if (error === entry.error)
+            return entry;
+        return { ...entry, error };
+    });
+    return { custom: next, errorCount };
+}
+function applyDraft(state, mutate) {
+    const mutated = mutate(state.draft);
+    const { custom, errorCount } = validateCustom(mutated.custom);
+    return { ...state, draft: { ...mutated, custom }, errorCount };
+}
+/** Pure reducer — exported (with {@link initMetadataEditorState}) so
+ *  the edit state is testable without React, mirroring the document
+ *  editor's reducer/hook split. */
+export function metadataEditorReducer(state, action) {
+    switch (action.type) {
+        case 'setContentType':
+            return applyDraft(state, (d) => ({ ...d, contentType: action.value }));
+        case 'setCacheControl':
+            return applyDraft(state, (d) => ({ ...d, cacheControl: action.value }));
+        case 'setCustomKey':
+            return applyDraft(state, (d) => ({
+                ...d,
+                custom: d.custom.map((e) => (e.id === action.id ? { ...e, key: action.key } : e)),
+            }));
+        case 'setCustomValue':
+            return applyDraft(state, (d) => ({
+                ...d,
+                custom: d.custom.map((e) => e.id === action.id ? { ...e, value: action.value } : e),
+            }));
+        case 'addCustomEntry':
+            return applyDraft(state, (d) => ({
+                ...d,
+                custom: [
+                    ...d.custom,
+                    { id: crypto.randomUUID(), key: action.key ?? '', value: action.value ?? '' },
+                ],
+            }));
+        case 'removeCustomEntry':
+            return applyDraft(state, (d) => ({
+                ...d,
+                custom: d.custom.filter((e) => e.id !== action.id),
+            }));
+        case 'reset':
+            return {
+                draft: state.initial,
+                initial: state.initial,
+                errorCount: validateCustom(state.initial.custom).errorCount,
+            };
+        case 'commit':
+            return { ...state, initial: state.draft };
+    }
+}
+/** Build the edit state from the metadata a `getMetadata` /
+ *  `useStorageObject` read returned. */
+export function initMetadataEditorState(initial) {
+    const draft = {
+        contentType: initial?.contentType ?? '',
+        cacheControl: initial?.cacheControl ?? '',
+        custom: Object.entries(initial?.customMetadata ?? {}).map(([key, value]) => ({
+            id: crypto.randomUUID(),
+            key,
+            value,
+        })),
+    };
+    const { custom, errorCount } = validateCustom(draft.custom);
+    // One shared object: `isDirty` is `draft !== initial` by reference.
+    const validated = { ...draft, custom };
+    return { draft: validated, initial: validated, errorCount };
+}
+/**
+ * Headless metadata editor — the `useDocumentEditor` reducer pattern
+ * over `updateMetadata`: a pure reducer owns the draft (contentType,
+ * cacheControl, customMetadata k/v rows with stable ids +
+ * empty/duplicate-key validation); the hook adds named dispatch
+ * helpers and the save half.
+ */
+export function useMetadataEditor(storage, path, options = {}) {
+    // Computed once — the reducer owns the live draft from here on
+    // (same `useRef` seed as `useDocumentEditor`).
+    const initialRef = useRef(null);
+    if (initialRef.current == null) {
+        initialRef.current = initMetadataEditorState(options.initial);
+    }
+    const [state, dispatch] = useReducer(metadataEditorReducer, initialRef.current);
+    const [isSaving, setIsSaving] = useState(false);
+    const [saveError, setSaveError] = useState(undefined);
+    // Stale-run protection for overlapping saves (generation token,
+    // house style).
+    const generationRef = useRef(0);
+    const setContentType = useCallback((value) => dispatch({ type: 'setContentType', value }), []);
+    const setCacheControl = useCallback((value) => dispatch({ type: 'setCacheControl', value }), []);
+    const setCustomKey = useCallback((id, key) => dispatch({ type: 'setCustomKey', id, key }), []);
+    const setCustomValue = useCallback((id, value) => dispatch({ type: 'setCustomValue', id, value }), []);
+    const addCustomEntry = useCallback((key, value) => dispatch({ type: 'addCustomEntry', key, value }), []);
+    const removeCustomEntry = useCallback((id) => dispatch({ type: 'removeCustomEntry', id }), []);
+    const reset = useCallback(() => dispatch({ type: 'reset' }), []);
+    const { draft, initial, errorCount } = state;
+    const toPatch = useCallback(() => {
+        return {
+            contentType: draft.contentType.trim() === '' ? undefined : draft.contentType,
+            cacheControl: draft.cacheControl.trim() === '' ? undefined : draft.cacheControl,
+            customMetadata: Object.fromEntries(draft.custom.filter((e) => e.key.trim() !== '').map((e) => [e.key, e.value])),
+        };
+    }, [draft]);
+    const save = useCallback(async () => {
+        const myGen = ++generationRef.current;
+        if (storage == null || path == null) {
+            setSaveError(new Error('useMetadataEditor: storage or path is null'));
+            return undefined;
+        }
+        if (errorCount > 0) {
+            setSaveError(new Error('useMetadataEditor: draft has validation errors'));
+            return undefined;
+        }
+        setSaveError(undefined);
+        setIsSaving(true);
+        try {
+            const next = await updateMetadata(refFn(storage, normalizeStoragePath(path)), toPatch());
+            if (myGen === generationRef.current) {
+                dispatch({ type: 'commit' });
+            }
+            return next;
+        }
+        catch (e) {
+            if (myGen === generationRef.current) {
+                setSaveError(e instanceof Error ? e : new Error(String(e)));
+            }
+            return undefined;
+        }
+        finally {
+            if (myGen === generationRef.current)
+                setIsSaving(false);
+        }
+    }, [storage, path, errorCount, toPatch]);
+    const isDirty = draft !== initial;
+    const isValid = errorCount === 0;
+    return useMemo(() => ({
+        contentType: draft.contentType,
+        cacheControl: draft.cacheControl,
+        custom: draft.custom,
+        isValid,
+        isDirty,
+        errorCount,
+        dispatch,
+        setContentType,
+        setCacheControl,
+        setCustomKey,
+        setCustomValue,
+        addCustomEntry,
+        removeCustomEntry,
+        reset,
+        toPatch,
+        save,
+        isSaving,
+        saveError,
+    }), [
+        draft,
+        isValid,
+        isDirty,
+        errorCount,
+        setContentType,
+        setCacheControl,
+        setCustomKey,
+        setCustomValue,
+        addCustomEntry,
+        removeCustomEntry,
+        reset,
+        toPatch,
+        save,
+        isSaving,
+        saveError,
+    ]);
+}
+//# sourceMappingURL=useMetadataEditor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useMetadataEditor.js","sourceRoot":"","sources":["../../../src/storage/hooks/useMetadataEditor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC3E,OAAO,EACL,GAAG,IAAI,KAAK,EACZ,cAAc,GAIf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAqCzD,qEAAqE;AACrE,SAAS,cAAc,CAAC,MAA6B;IAInD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAChC,IAAI,KAAyB,CAAC;QAC9B,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,KAAK,GAAG,iBAAiB,CAAC;aAClD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC;YAAE,KAAK,GAAG,eAAe,CAAC;QACnE,IAAI,KAAK;YAAE,UAAU,EAAE,CAAC;QACxB,IAAI,KAAK,KAAK,KAAK,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACxC,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,CAAC;IAC7B,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,UAAU,CACjB,KAA0B,EAC1B,MAA+C;IAE/C,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,CAAC;AACjE,CAAC;AAED;;mCAEmC;AACnC,MAAM,UAAU,qBAAqB,CACnC,KAA0B,EAC1B,MAA4B;IAE5B,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,gBAAgB;YACnB,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACzE,KAAK,iBAAiB;YACpB,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC1E,KAAK,cAAc;YACjB,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/B,GAAG,CAAC;gBACJ,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAClF,CAAC,CAAC,CAAC;QACN,KAAK,gBAAgB;YACnB,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/B,GAAG,CAAC;gBACJ,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACzB,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CACvD;aACF,CAAC,CAAC,CAAC;QACN,KAAK,gBAAgB;YACnB,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/B,GAAG,CAAC;gBACJ,MAAM,EAAE;oBACN,GAAG,CAAC,CAAC,MAAM;oBACX,EAAE,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE;iBAC9E;aACF,CAAC,CAAC,CAAC;QACN,KAAK,mBAAmB;YACtB,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/B,GAAG,CAAC;gBACJ,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC;aACnD,CAAC,CAAC,CAAC;QACN,KAAK,OAAO;YACV,OAAO;gBACL,KAAK,EAAE,KAAK,CAAC,OAAO;gBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,UAAU,EAAE,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,UAAU;aAC5D,CAAC;QACJ,KAAK,QAAQ;YACX,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IAC9C,CAAC;AACH,CAAC;AAED;wCACwC;AACxC,MAAM,UAAU,uBAAuB,CACrC,OAAqC;IAErC,MAAM,KAAK,GAAkB;QAC3B,WAAW,EAAE,OAAO,EAAE,WAAW,IAAI,EAAE;QACvC,YAAY,EAAE,OAAO,EAAE,YAAY,IAAI,EAAE;QACzC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3E,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;YACvB,GAAG;YACH,KAAK;SACN,CAAC,CAAC;KACJ,CAAC;IACF,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5D,oEAAoE;IACpE,MAAM,SAAS,GAAkB,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,CAAC;IACtD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AAC9D,CAAC;AAmDD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA2C,EAC3C,IAA+B,EAC/B,UAAoC,EAAE;IAEtC,+DAA+D;IAC/D,+CAA+C;IAC/C,MAAM,UAAU,GAAG,MAAM,CAA6B,IAAI,CAAC,CAAC;IAC5D,IAAI,UAAU,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;QAC/B,UAAU,CAAC,OAAO,GAAG,uBAAuB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,UAAU,CAAC,qBAAqB,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;IAChF,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAoB,SAAS,CAAC,CAAC;IACzE,gEAAgE;IAChE,gBAAgB;IAChB,MAAM,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAEhC,MAAM,cAAc,GAAG,WAAW,CAChC,CAAC,KAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC,EAC9D,EAAE,CACH,CAAC;IACF,MAAM,eAAe,GAAG,WAAW,CACjC,CAAC,KAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,EAC/D,EAAE,CACH,CAAC;IACF,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,EAAU,EAAE,GAAW,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EACxE,EAAE,CACH,CAAC;IACF,MAAM,cAAc,GAAG,WAAW,CAChC,CAAC,EAAU,EAAE,KAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAC9E,EAAE,CACH,CAAC;IACF,MAAM,cAAc,GAAG,WAAW,CAChC,CAAC,GAAY,EAAE,KAAc,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAClF,EAAE,CACH,CAAC;IACF,MAAM,iBAAiB,GAAG,WAAW,CACnC,CAAC,EAAU,EAAE,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,EAAE,EAAE,CAAC,EAC3D,EAAE,CACH,CAAC;IACF,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAEjE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IAE7C,MAAM,OAAO,GAAG,WAAW,CAAC,GAAqB,EAAE;QACjD,OAAO;YACL,WAAW,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW;YAC5E,YAAY,EAAE,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY;YAC/E,cAAc,EAAE,MAAM,CAAC,WAAW,CAChC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAC7E;SACF,CAAC;IACJ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAEZ,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,IAAuC,EAAE;QACrE,MAAM,KAAK,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC;QACtC,IAAI,OAAO,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACpC,YAAY,CAAC,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC,CAAC;YACtE,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACnB,YAAY,CAAC,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC,CAAC;YAC1E,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,YAAY,CAAC,SAAS,CAAC,CAAC;QACxB,WAAW,CAAC,IAAI,CAAC,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,cAAc,CAC/B,KAAK,CAAC,OAAO,EAAE,oBAAoB,CAAC,IAAI,CAAC,CAAC,EAC1C,OAAO,EAAE,CACV,CAAC;YACF,IAAI,KAAK,KAAK,aAAa,CAAC,OAAO,EAAE,CAAC;gBACpC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,KAAK,KAAK,aAAa,CAAC,OAAO,EAAE,CAAC;gBACpC,YAAY,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9D,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;gBAAS,CAAC;YACT,IAAI,KAAK,KAAK,aAAa,CAAC,OAAO;gBAAE,WAAW,CAAC,KAAK,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAEzC,MAAM,OAAO,GAAG,KAAK,KAAK,OAAO,CAAC;IAClC,MAAM,OAAO,GAAG,UAAU,KAAK,CAAC,CAAC;IAEjC,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO;QACP,OAAO;QACP,UAAU;QACV,QAAQ;QACR,cAAc;QACd,eAAe;QACf,YAAY;QACZ,cAAc;QACd,cAAc;QACd,iBAAiB;QACjB,KAAK;QACL,OAAO;QACP,IAAI;QACJ,QAAQ;QACR,SAAS;KACV,CAAC,EACF;QACE,KAAK;QACL,OAAO;QACP,OAAO;QACP,UAAU;QACV,cAAc;QACd,eAAe;QACf,YAAY;QACZ,cAAc;QACd,cAAc;QACd,iBAAiB;QACjB,KAAK;QACL,OAAO;QACP,IAAI;QACJ,QAAQ;QACR,SAAS;KACV,CACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,105 @@
+import type { FirebaseStorage, FullMetadata, SettableMetadata } from 'pyric/storage';
+import type { UseStorageListResult } from './useStorageList.js';
+export type UploadTaskStatus = 'running' | 'success' | 'error';
+/**
+ * One file's upload, TASK-SHAPED for resumable forward-compat: the
+ * byte counters and the `onProgress` callback are in the type NOW so
+ * a future `uploadBytesResumable`-backed implementation emits real
+ * intermediate snapshots without a breaking change. Today
+ * (`pyric/storage` has no resumable uploads — COMPAT) a task
+ * completes in one tick: `onProgress` fires once at 0 bytes and once
+ * at `totalBytes`.
+ */
+export interface UploadTask {
+    /** Stable id — key task rows on this, not on `fullPath` (two
+     *  uploads can target the same path). */
+    id: string;
+    /** Bucket-rooted destination path. */
+    fullPath: string;
+    status: UploadTaskStatus;
+    bytesTransferred: number;
+    totalBytes: number;
+    /** Populated on `'success'`. */
+    metadata?: FullMetadata;
+    /** Populated on `'error'` — a typed `StorageError` from the
+     *  sandbox (`.code` is `storage/<code>`, e.g.
+     *  `storage/unauthorized` for a rules-denied write). */
+    error?: Error;
+}
+/** Explicit-path upload input. `path` is relative to the hook's
+ *  `path` option (the destination folder). */
+export interface UploadEntry {
+    path: string;
+    data: Blob | Uint8Array | ArrayBuffer;
+    metadata?: SettableMetadata;
+}
+/**
+ * `upload()` accepts plain `File`s (destination = the file's
+ * `webkitRelativePath` when present — folder drops keep their
+ * structure — else its `name`) or explicit {@link UploadEntry}s.
+ */
+export type UploadInput = File | UploadEntry;
+export interface UseObjectUploadOptions {
+    /** Destination folder, bucket-rooted. Default `''` (root). Wire to
+     *  `usePathState().path` so uploads land in the browsed folder. */
+    path?: string;
+    /**
+     * Optimistic seam from `useStorageList`: each upload inserts its
+     * path immediately and rolls back via `removeItem` on failure.
+     * Caveat: rolling back an upload that was OVERWRITING an existing
+     * object drops that object's row locally (the seam can't tell an
+     * optimistic row from a listed one) — `refresh()` restores server
+     * truth.
+     */
+    list?: Pick<UseStorageListResult, 'insertItem' | 'removeItem'>;
+    /** Task-shaped progress callback (see {@link UploadTask}). */
+    onProgress?: (task: UploadTask) => void;
+    /** Fired once per task reaching `'success'`. */
+    onComplete?: (task: UploadTask) => void;
+    /** Fired once per task reaching `'error'`. */
+    onError?: (task: UploadTask) => void;
+}
+export interface UseObjectUploadResult {
+    /** Every task started by this hook instance, oldest first. */
+    tasks: UploadTask[];
+    /** `true` while any task is `'running'`. */
+    isUploading: boolean;
+    /**
+     * Upload one or many files. Tasks run concurrently; the promise
+     * resolves with the settled tasks once ALL finish and never
+     * rejects — per-file failures land on `task.error` (and
+     * `onError`), so one bad file doesn't mask the others.
+     */
+    upload: (input: UploadInput | UploadInput[]) => Promise<UploadTask[]>;
+    /**
+     * Create an empty folder under the hook's `path`: writes the GCS
+     * placeholder convention — a zero-byte object named `<path>/`
+     * (trailing slash). `listAll` hides the placeholder from `items`
+     * at every level (it only surfaces as a prefix), so the folder
+     * appears in the browser with no phantom file inside.
+     *
+     * `ref()` normalizes the trailing slash away, so the placeholder is
+     * written through a structural value-object reference the sandbox
+     * accepts. Throws the underlying error after rolling back the
+     * optimistic prefix insert.
+     *
+     * ALTERNATIVE: when the store must stay free of placeholder
+     * objects (Pyric Studio's choice), use the client-side
+     * pending-prefix mechanism instead — see `pendingPrefixes.ts`
+     * for the reducer and the recorded tradeoff.
+     */
+    createFolder: (name: string) => Promise<void>;
+    /** Drop settled (`success`/`error`) tasks from `tasks`. */
+    clearCompleted: () => void;
+}
+/**
+ * Multi-file upload over the package's single Storage handle prop.
+ * Headless: returns task state; render it however you like (the
+ * `<UploadDropzone>` component is one producer of `upload()` calls).
+ *
+ * Optimistic-with-rollback: with the `list` seam wired, each upload's
+ * row appears in `useStorageList` immediately and disappears again if
+ * the write fails (typed `StorageError` on `task.error`).
+ */
+export declare function useObjectUpload(storage: FirebaseStorage | null | undefined, options?: UseObjectUploadOptions): UseObjectUploadResult;
+//# sourceMappingURL=useObjectUpload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useObjectUpload.d.ts","sourceRoot":"","sources":["../../../src/storage/hooks/useObjectUpload.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAIvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/D;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB;6CACyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;4DAEwD;IACxD,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED;8CAC8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,GAAG,UAAU,GAAG,WAAW,CAAC;IACtC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,WAAW,CAAC;AAE7C,MAAM,WAAW,sBAAsB;IACrC;uEACmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,YAAY,GAAG,YAAY,CAAC,CAAC;IAC/D,8DAA8D;IAC9D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACxC,gDAAgD;IAChD,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACxC,8CAA8C;IAC9C,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,4CAA4C;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,EAAE,KAAK,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACtE;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,2DAA2D;IAC3D,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAwBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC3C,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAsHvB"}

package/dist/storage/hooks/useObjectUpload.js

@@ -0,0 +1,134 @@
+import { useCallback, useRef, useState } from 'react';
+import { folderPlaceholderRef } from '../folderPlaceholder.js';
+import { useStorageApi } from '../storageApi.js';
+import { normalizeStoragePath } from './usePathState.js';
+function joinPath(base, child) {
+    if (base === '')
+        return child;
+    if (child === '')
+        return base;
+    return `${base}/${child}`;
+}
+function sizeOf(data) {
+    if (data instanceof Blob)
+        return data.size;
+    return data.byteLength;
+}
+function toEntry(input) {
+    if (input instanceof Blob) {
+        // File (the only Blob subtype `UploadInput` admits). Folder
+        // drops carry `webkitRelativePath`; plain picks carry `name`.
+        const file = input;
+        const rel = file.webkitRelativePath;
+        return { path: rel || file.name, data: file };
+    }
+    return input;
+}
+/**
+ * Multi-file upload over the package's single Storage handle prop.
+ * Headless: returns task state; render it however you like (the
+ * `<UploadDropzone>` component is one producer of `upload()` calls).
+ *
+ * Optimistic-with-rollback: with the `list` seam wired, each upload's
+ * row appears in `useStorageList` immediately and disappears again if
+ * the write fails (typed `StorageError` on `task.error`).
+ */
+export function useObjectUpload(storage, options = {}) {
+    // Injected backend (in-process `pyric/storage` by default, the
+    // SharedWorker client bundle in Studio served mode) — uploads follow
+    // the same seam the browse hooks read through. The worker leg caps a
+    // payload at 8 MiB (base64 `storage.putBytes`); in-process writes are
+    // uncapped. An over-cap file fails as a normal per-file task error.
+    const { ref: refFn, uploadBytes } = useStorageApi();
+    const base = normalizeStoragePath(options.path ?? '');
+    const [tasks, setTasks] = useState([]);
+    // Latest-value refs so `upload`/`createFolder` stay referentially
+    // stable across option changes (same pattern as the house hooks'
+    // generation tokens — the callbacks read current options at call
+    // time).
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const patchTask = useCallback((next) => {
+        setTasks((prev) => prev.map((t) => (t.id === next.id ? next : t)));
+    }, []);
+    const upload = useCallback(async (input) => {
+        if (storage == null) {
+            throw new Error('useObjectUpload: storage handle is null');
+        }
+        const inputs = Array.isArray(input) ? input : [input];
+        const started = inputs.map((raw) => {
+            const entry = toEntry(raw);
+            const task = {
+                id: crypto.randomUUID(),
+                fullPath: joinPath(base, normalizeStoragePath(entry.path)),
+                status: 'running',
+                bytesTransferred: 0,
+                totalBytes: sizeOf(entry.data),
+            };
+            return { task, entry };
+        });
+        setTasks((prev) => [...prev, ...started.map((s) => s.task)]);
+        for (const { task } of started) {
+            optionsRef.current.list?.insertItem(task.fullPath);
+            optionsRef.current.onProgress?.(task);
+        }
+        return Promise.all(started.map(async ({ task, entry }) => {
+            try {
+                const result = await uploadBytes(refFn(storage, task.fullPath), entry.data, entry.metadata);
+                const done = {
+                    ...task,
+                    status: 'success',
+                    bytesTransferred: task.totalBytes,
+                    metadata: result.metadata,
+                };
+                patchTask(done);
+                optionsRef.current.onProgress?.(done);
+                optionsRef.current.onComplete?.(done);
+                return done;
+            }
+            catch (e) {
+                const failed = {
+                    ...task,
+                    status: 'error',
+                    error: e instanceof Error ? e : new Error(String(e)),
+                };
+                // Roll the optimistic row back before surfacing.
+                optionsRef.current.list?.removeItem(task.fullPath);
+                patchTask(failed);
+                optionsRef.current.onError?.(failed);
+                return failed;
+            }
+        }));
+    }, [storage, base, patchTask, refFn, uploadBytes]);
+    const createFolder = useCallback(async (name) => {
+        if (storage == null) {
+            throw new Error('useObjectUpload: storage handle is null');
+        }
+        const folderPath = joinPath(base, normalizeStoragePath(name));
+        if (folderPath === '') {
+            throw new Error('createFolder: folder name is empty');
+        }
+        // Trailing slash → the seam inserts a prefix, not an item.
+        optionsRef.current.list?.insertItem(`${folderPath}/`);
+        try {
+            await uploadBytes(folderPlaceholderRef(storage, folderPath), new Blob([]), 
+            // Matches the emulator UI's placeholder content type.
+            { contentType: 'text/plain' });
+        }
+        catch (e) {
+            optionsRef.current.list?.removeItem(folderPath);
+            throw e;
+        }
+    }, [storage, base, uploadBytes]);
+    const clearCompleted = useCallback(() => {
+        setTasks((prev) => prev.filter((t) => t.status === 'running'));
+    }, []);
+    return {
+        tasks,
+        isUploading: tasks.some((t) => t.status === 'running'),
+        upload,
+        createFolder,
+        clearCompleted,
+    };
+}
+//# sourceMappingURL=useObjectUpload.js.map

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

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

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

@@ -0,0 +1,43 @@
+/** 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 declare function normalizeStoragePath(path: string): string;
+export interface UsePathStateOptions {
+    /**
+     * Controlled value. When provided, the hook derives everything
+     * from it and navigation calls only fire `onPathChange` — the
+     * owner owns the state (e.g. a router binding `?path=`).
+     */
+    path?: string;
+    /** Fired with the normalized next path on every navigation. Called
+     *  in both modes. */
+    onPathChange?: (path: string) => void;
+    /** Uncontrolled initial value. Default `''` (bucket root). */
+    defaultPath?: string;
+}
+export interface UsePathStateResult {
+    /** Current normalized path. `''` is the bucket root. */
+    path: string;
+    /** Path split into segments. `[]` at root. */
+    segments: string[];
+    /** Jump to an absolute path (normalized). */
+    setPath: (path: string) => void;
+    /** Descend into a child folder — accepts a bare name (`'sub'`) or
+     *  an absolute path (`'docs/sub'`, e.g. a prefix's `fullPath`). */
+    enter: (nameOrPath: string) => void;
+    /** Ascend one level. No-op at root. */
+    up: () => void;
+    /**
+     * Jump to the ancestor ending at `segments[index]` — the breadcrumb
+     * click. `navigateToIndex(-1)` (or any negative) is the root.
+     */
+    navigateToIndex: (index: number) => void;
+}
+/**
+ * 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 declare function usePathState(options?: UsePathStateOptions): UsePathStateResult;
+//# sourceMappingURL=usePathState.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePathState.d.ts","sourceRoot":"","sources":["../../../src/storage/hooks/usePathState.ts"],"names":[],"mappings":"AAEA;;uDAEuD;AACvD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;yBACqB;IACrB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC;uEACmE;IACnE,KAAK,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,uCAAuC;IACvC,EAAE,EAAE,MAAM,IAAI,CAAC;IACf;;;OAGG;IACH,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,GAAE,mBAAwB,GAChC,kBAAkB,CA2CpB"}