@pyric/cli 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/serve/docs-ui/docs/pyric-ui-storage-hooks-reference-api.md

@@ -1,1029 +1,345 @@
+<!-- Generated from published package declarations via TypeDoc. Rendered by the api-reference content loader. -->
 
-<!-- Generated from published package declarations via TypeDoc. Do not edit by hand; run bun run docs:api:generate. -->
+## References
 
-## Interfaces
-
-<a id="custommetadataentry"></a>
-
-### CustomMetadataEntry
-
-One `customMetadata` row. `id` is a stable render key — keys are
- user-editable, so they can't key the rows themselves.
+<a id="createlistalldeleteimpl"></a>
 
-#### Properties
+### createListAllDeleteImpl
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="error"></a> `error?` | `string` | Validation error (`'Key is required'` / `'Duplicate key'`). |
-| <a id="id"></a> `id` | `string` | - |
-| <a id="key"></a> `key` | `string` | - |
-| <a id="value"></a> `value` | `string` | - |
+Re-exports [createListAllDeleteImpl](pyric-ui-storage-reference-api.md#createlistalldeleteimpl)
 
 ***
 
-<a id="metadataeditorstate"></a>
-
-### MetadataEditorState
+<a id="custommetadataentry"></a>
 
-#### Properties
+### CustomMetadataEntry
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="draft"></a> `draft` | `MetadataDraft` | - |
-| <a id="errorcount"></a> `errorCount` | `number` | - |
-| <a id="initial"></a> `initial` | `MetadataDraft` | Snapshot for `isDirty` / `reset` — same reference-compare semantics as the document editor's `tree !== initial`. |
+Re-exports [CustomMetadataEntry](pyric-ui-storage-reference-api.md#custommetadataentry)
 
 ***
 
-<a id="storagedeletefailure"></a>
-
-### StorageDeleteFailure
-
-One entry's failure in a bulk run. `error` is the typed
- `StorageError` (`.code` e.g. `storage/unauthorized`).
+<a id="initmetadataeditorstate"></a>
 
-#### Properties
+### initMetadataEditorState
 
-| Property | Type |
-| :------ | :------ |
-| <a id="error-1"></a> `error` | `Error` |
-| <a id="fullpath"></a> `fullPath` | `string` |
+Re-exports [initMetadataEditorState](pyric-ui-storage-reference-api.md#initmetadataeditorstate)
 
 ***
 
-<a id="storagedeleteoutcome"></a>
-
-### StorageDeleteOutcome
+<a id="metadataeditoraction"></a>
 
-#### Properties
+### MetadataEditorAction
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="deleted"></a> `deleted` | `string`[] | fullPaths of entries fully deleted. |
-| <a id="failed"></a> `failed` | [`StorageDeleteFailure`](#storagedeletefailure)[] | - |
+Re-exports [MetadataEditorAction](pyric-ui-storage-reference-api.md#metadataeditoraction)
 
 ***
 
-<a id="storagedeleteprogress"></a>
-
-### StorageDeleteProgress
+<a id="metadataeditorreducer"></a>
 
-#### Properties
+### metadataEditorReducer
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="deletedcount"></a> `deletedCount` | `number` | Objects deleted so far in this folder walk. |
-| <a id="done"></a> `done` | `boolean` | True for the final emission. |
+Re-exports [metadataEditorReducer](pyric-ui-storage-reference-api.md#metadataeditorreducer)
 
 ***
 
-<a id="storagegateverdict"></a>
-
-### StorageGateVerdict
-
-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.
+<a id="metadataeditorstate"></a>
 
-#### Properties
+### MetadataEditorState
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="delete"></a> `delete` | `boolean` | Derived — always `=== write` under the two-verb subset. |
-| <a id="read"></a> `read` | `boolean` | - |
-| <a id="reasons"></a> `reasons` | \{ `read`: `string`[]; `write`: `string`[]; \} | 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`[] | - |
-| `reasons.write` | `string`[] | - |
-| <a id="upload"></a> `upload` | `boolean` | Derived — always `=== write` under the two-verb subset. |
-| <a id="write"></a> `write` | `boolean` | - |
+Re-exports [MetadataEditorState](pyric-ui-storage-reference-api.md#metadataeditorstate)
 
 ***
 
-<a id="storagelistentry"></a>
-
-### StorageListEntry
-
-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.
+<a id="normalizestoragepath"></a>
 
-#### Properties
+### normalizeStoragePath
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="fullpath-1"></a> `fullPath` | `string` | Bucket-rooted path (no trailing slash, even for folders). |
-| <a id="kind"></a> `kind` | `"object"` \| `"folder"` | - |
-| <a id="name"></a> `name` | `string` | Last path segment, display name. |
-| <a id="ref"></a> `ref` | `StorageReference` | - |
+Re-exports [normalizeStoragePath](pyric-ui-storage-reference-api.md#normalizestoragepath)
 
 ***
 
-<a id="storagerecursivedeleteimpl"></a>
-
-### StorageRecursiveDeleteImpl
-
-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 [createListAllDeleteImpl](#createlistalldeleteimpl) as the default;
-inject your own for server-driven deletes.
+<a id="storagedeletefailure"></a>
 
-#### Properties
+### StorageDeleteFailure
 
-| Property | Type |
-| :------ | :------ |
-| <a id="start"></a> `start` | (`target`: `StorageReference`) => `AsyncIterableIterator`\<[`StorageDeleteProgress`](#storagedeleteprogress)\> |
+Re-exports [StorageDeleteFailure](pyric-ui-storage-reference-api.md#storagedeletefailure)
 
 ***
 
-<a id="storageselectionentry"></a>
-
-### StorageSelectionEntry
-
-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).
+<a id="storagedeleteoutcome"></a>
 
-#### Properties
+### StorageDeleteOutcome
 
-| Property | Type |
-| :------ | :------ |
-| <a id="fullpath-2"></a> `fullPath` | `string` |
-| <a id="kind-1"></a> `kind` | `"object"` \| `"folder"` |
+Re-exports [StorageDeleteOutcome](pyric-ui-storage-reference-api.md#storagedeleteoutcome)
 
 ***
 
-<a id="uploadentry"></a>
-
-### UploadEntry
-
-Explicit-path upload input. `path` is relative to the hook's
- `path` option (the destination folder).
+<a id="storagedeleteprogress"></a>
 
-#### Properties
+### StorageDeleteProgress
 
-| Property | Type |
-| :------ | :------ |
-| <a id="data"></a> `data` | `Blob` \| `ArrayBuffer` \| `Uint8Array`\<`ArrayBufferLike`\> |
-| <a id="metadata"></a> `metadata?` | `SettableMetadata` |
-| <a id="path"></a> `path` | `string` |
+Re-exports [StorageDeleteProgress](pyric-ui-storage-reference-api.md#storagedeleteprogress)
 
 ***
 
-<a id="uploadtask"></a>
+<a id="storagegateverdict"></a>
 
-### UploadTask
+### StorageGateVerdict
 
-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`.
-
-#### Properties
-
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="bytestransferred"></a> `bytesTransferred` | `number` | - |
-| <a id="error-2"></a> `error?` | `Error` | Populated on `'error'` — a typed `StorageError` from the sandbox (`.code` is `storage/<code>`, e.g. `storage/unauthorized` for a rules-denied write). |
-| <a id="fullpath-3"></a> `fullPath` | `string` | Bucket-rooted destination path. |
-| <a id="id-1"></a> `id` | `string` | Stable id — key task rows on this, not on `fullPath` (two uploads can target the same path). |
-| <a id="metadata-1"></a> `metadata?` | `FullMetadata` | Populated on `'success'`. |
-| <a id="status"></a> `status` | [`UploadTaskStatus`](#uploadtaskstatus-1) | - |
-| <a id="totalbytes"></a> `totalBytes` | `number` | - |
+Re-exports [StorageGateVerdict](pyric-ui-storage-reference-api.md#storagegateverdict)
 
 ***
 
-<a id="usemetadataeditoroptions"></a>
-
-### UseMetadataEditorOptions
+<a id="storagelistentry"></a>
 
-#### Properties
+### StorageListEntry
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="initial-1"></a> `initial?` | `SettableMetadata` | 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. |
+Re-exports [StorageListEntry](pyric-ui-storage-reference-api.md#storagelistentry)
 
 ***
 
-<a id="usemetadataeditorresult"></a>
+<a id="storageliststatus"></a>
 
-### UseMetadataEditorResult
+### StorageListStatus
 
-#### Properties
-
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="addcustomentry"></a> `addCustomEntry` | (`key?`: `string`, `value?`: `string`) => `void` | - |
-| <a id="cachecontrol"></a> `cacheControl` | `string` | - |
-| <a id="contenttype"></a> `contentType` | `string` | - |
-| <a id="custom"></a> `custom` | [`CustomMetadataEntry`](#custommetadataentry)[] | - |
-| <a id="dispatch"></a> `dispatch` | (`action`: [`MetadataEditorAction`](#metadataeditoraction)) => `void` | Raw dispatch — prefer the named helpers. |
-| <a id="errorcount-1"></a> `errorCount` | `number` | - |
-| <a id="isdirty"></a> `isDirty` | `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. |
-| <a id="issaving"></a> `isSaving` | `boolean` | - |
-| <a id="isvalid"></a> `isValid` | `boolean` | Convenience: `errorCount === 0`. |
-| <a id="removecustomentry"></a> `removeCustomEntry` | (`id`: `string`) => `void` | - |
-| <a id="reset"></a> `reset` | () => `void` | Restore the initial values. Clears `isDirty`. |
-| <a id="save"></a> `save` | () => `Promise`\<`any`\> | `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. |
-| <a id="saveerror"></a> `saveError` | `Error` | - |
-| <a id="setcachecontrol"></a> `setCacheControl` | (`value`: `string`) => `void` | - |
-| <a id="setcontenttype"></a> `setContentType` | (`value`: `string`) => `void` | - |
-| <a id="setcustomkey"></a> `setCustomKey` | (`id`: `string`, `key`: `string`) => `void` | - |
-| <a id="setcustomvalue"></a> `setCustomValue` | (`id`: `string`, `value`: `string`) => `void` | - |
-| <a id="topatch"></a> `toPatch` | () => `SettableMetadata` | 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. |
+Re-exports [StorageListStatus](pyric-ui-storage-reference-api.md#storageliststatus)
 
 ***
 
-<a id="useobjectuploadoptions"></a>
-
-### UseObjectUploadOptions
+<a id="storageobjectstatus"></a>
 
-#### Properties
+### StorageObjectStatus
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="list"></a> `list?` | `Pick`\<[`UseStorageListResult`](#usestoragelistresult), `"insertItem"` \| `"removeItem"`\> | 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. |
-| <a id="oncomplete"></a> `onComplete?` | (`task`: [`UploadTask`](#uploadtask)) => `void` | Fired once per task reaching `'success'`. |
-| <a id="onerror"></a> `onError?` | (`task`: [`UploadTask`](#uploadtask)) => `void` | Fired once per task reaching `'error'`. |
-| <a id="onprogress"></a> `onProgress?` | (`task`: [`UploadTask`](#uploadtask)) => `void` | Task-shaped progress callback (see [UploadTask](#uploadtask)). |
-| <a id="path-1"></a> `path?` | `string` | Destination folder, bucket-rooted. Default `''` (root). Wire to `usePathState().path` so uploads land in the browsed folder. |
+Re-exports [StorageObjectStatus](pyric-ui-storage-reference-api.md#storageobjectstatus)
 
 ***
 
-<a id="useobjectuploadresult"></a>
-
-### UseObjectUploadResult
+<a id="storagerecursivedeleteimpl"></a>
 
-#### Properties
+### StorageRecursiveDeleteImpl
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="clearcompleted"></a> `clearCompleted` | () => `void` | Drop settled (`success`/`error`) tasks from `tasks`. |
-| <a id="createfolder"></a> `createFolder` | (`name`: `string`) => `Promise`\<`void`\> | 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. |
-| <a id="isuploading"></a> `isUploading` | `boolean` | `true` while any task is `'running'`. |
-| <a id="tasks"></a> `tasks` | [`UploadTask`](#uploadtask)[] | Every task started by this hook instance, oldest first. |
-| <a id="upload-1"></a> `upload` | (`input`: [`UploadInput`](#uploadinput) \| [`UploadInput`](#uploadinput)[]) => `Promise`\<[`UploadTask`](#uploadtask)[]\> | 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. |
+Re-exports [StorageRecursiveDeleteImpl](pyric-ui-storage-reference-api.md#storagerecursivedeleteimpl)
 
 ***
 
-<a id="usepathstateoptions"></a>
-
-### UsePathStateOptions
+<a id="storagerulesgatestatus"></a>
 
-#### Properties
+### StorageRulesGateStatus
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="defaultpath"></a> `defaultPath?` | `string` | Uncontrolled initial value. Default `''` (bucket root). |
-| <a id="onpathchange"></a> `onPathChange?` | (`path`: `string`) => `void` | Fired with the normalized next path on every navigation. Called in both modes. |
-| <a id="path-2"></a> `path?` | `string` | 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=`). |
+Re-exports [StorageRulesGateStatus](pyric-ui-storage-reference-api.md#storagerulesgatestatus)
 
 ***
 
-<a id="usepathstateresult"></a>
-
-### UsePathStateResult
+<a id="storagerulessource"></a>
 
-#### Properties
+### StorageRulesSource
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="enter"></a> `enter` | (`nameOrPath`: `string`) => `void` | Descend into a child folder — accepts a bare name (`'sub'`) or an absolute path (`'docs/sub'`, e.g. a prefix's `fullPath`). |
-| <a id="navigatetoindex"></a> `navigateToIndex` | (`index`: `number`) => `void` | Jump to the ancestor ending at `segments[index]` — the breadcrumb click. `navigateToIndex(-1)` (or any negative) is the root. |
-| <a id="path-3"></a> `path` | `string` | Current normalized path. `''` is the bucket root. |
-| <a id="segments"></a> `segments` | `string`[] | Path split into segments. `[]` at root. |
-| <a id="setpath"></a> `setPath` | (`path`: `string`) => `void` | Jump to an absolute path (normalized). |
-| <a id="up"></a> `up` | () => `void` | Ascend one level. No-op at root. |
+Re-exports [StorageRulesSource](pyric-ui-storage-reference-api.md#storagerulessource)
 
 ***
 
-<a id="usestoragedeleteoptions"></a>
-
-### UseStorageDeleteOptions
+<a id="storageselectionentry"></a>
 
-#### Properties
+### StorageSelectionEntry
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="impl"></a> `impl?` | [`StorageRecursiveDeleteImpl`](#storagerecursivedeleteimpl) | Folder-walk implementation. Default [createListAllDeleteImpl](#createlistalldeleteimpl). |
-| <a id="list-1"></a> `list?` | `Pick`\<[`UseStorageListResult`](#usestoragelistresult), `"insertItem"` \| `"removeItem"`\> | Optimistic seam from `useStorageList`: entries vanish from the local list immediately and roll back (object → item, folder → trailing-slash prefix insert) on failure. |
+Re-exports [StorageSelectionEntry](pyric-ui-storage-reference-api.md#storageselectionentry)
 
 ***
 
-<a id="usestoragedeleteresult"></a>
-
-### UseStorageDeleteResult
+<a id="uploadentry"></a>
 
-#### Properties
+### UploadEntry
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="deleteentries"></a> `deleteEntries` | (`entries`: [`StorageSelectionEntry`](#storageselectionentry)[]) => `Promise`\<[`StorageDeleteOutcome`](#storagedeleteoutcome)\> | 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). |
-| <a id="error-3"></a> `error` | `Error` | First failure of the current/last run. Cleared on the next call. |
-| <a id="isrunning"></a> `isRunning` | `boolean` | - |
-| <a id="progress"></a> `progress` | `number` | Objects deleted in the current/last run (folder walks included). |
+Re-exports [UploadEntry](pyric-ui-storage-reference-api.md#uploadentry)
 
 ***
 
-<a id="usestoragelistresult"></a>
-
-### UseStorageListResult
+<a id="uploadinput"></a>
 
-#### Properties
+### UploadInput
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="entries"></a> `entries` | [`StorageListEntry`](#storagelistentry)[] | Folders-first merged row model. Derived from `prefixes` + `items`. |
-| <a id="error-4"></a> `error` | `Error` | `StorageError` (with a typed `storage/<code>` on `.code`) from the sandbox. A denied list is `error.code === 'storage/unauthorized'` (ST-B2). |
-| <a id="insertitem"></a> `insertItem` | (`fullPath`: `string`) => `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`. |
-| <a id="items"></a> `items` | `StorageReference`[] | Direct child objects under `path`. Sorted by `fullPath`. |
-| <a id="prefixes"></a> `prefixes` | `StorageReference`[] | Synthetic folder prefixes under `path`. Sorted by `fullPath`. |
-| <a id="refresh"></a> `refresh` | () => `void` | Re-run `listAll` for the current path. |
-| <a id="removeitem"></a> `removeItem` | (`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`. |
-| <a id="status-1"></a> `status` | [`StorageListStatus`](#storageliststatus) | `'idle'` only when `storage` is null/undefined. |
+Re-exports [UploadInput](pyric-ui-storage-reference-api.md#uploadinput)
 
 ***
 
-<a id="usestorageobjectresult"></a>
-
-### UseStorageObjectResult
+<a id="uploadtask"></a>
 
-#### Properties
+### UploadTask
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="blob"></a> `blob` | `Blob` | - |
-| <a id="bloberror"></a> `blobError` | `Error` | - |
-| <a id="blobstatus"></a> `blobStatus` | [`StorageObjectStatus`](#storageobjectstatus) | Blob read state. Stays `'idle'` until `loadBlob()`, the blob is LAZY; metadata alone never downloads bytes. |
-| <a id="bloburl"></a> `blobUrl` | `string` | `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. |
-| <a id="error-5"></a> `error` | `Error` | Typed `StorageError` (`storage/object-not-found`, `storage/unauthorized`, …). |
-| <a id="loadblob"></a> `loadBlob` | () => `void` | Fetch the bytes via `getBlob`. Subsequent calls re-fetch. |
-| <a id="metadata-2"></a> `metadata` | `any` | - |
-| <a id="refresh-1"></a> `refresh` | () => `void` | Re-read the metadata (also resets the blob, the object may have been overwritten). |
-| <a id="status-2"></a> `status` | [`StorageObjectStatus`](#storageobjectstatus) | Metadata read state. `'idle'` when `storage` or `path` is null. |
+Re-exports [UploadTask](pyric-ui-storage-reference-api.md#uploadtask)
 
 ***
 
-<a id="usestoragerulesgateoptions"></a>
+<a id="uploadtaskstatus"></a>
 
-### UseStorageRulesGateOptions
-
-#### Properties
+### UploadTaskStatus
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="identity"></a> `identity?` | `any` | Identity override. `null` is anonymous; OMIT the field to use the handle's own identity (the sandbox context's `auth`). |
-| <a id="paths"></a> `paths?` | `string` \| readonly `string`[] | 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. |
-| <a id="rules"></a> `rules?` | `any` | 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. |
-| <a id="writeresource"></a> `writeResource?` | \{ `contentType?`: `string`; `size`: `number`; \} | 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.contentType?` | `string` | - |
-| `writeResource.size` | `number` | - |
+Re-exports [UploadTaskStatus](pyric-ui-storage-reference-api.md#uploadtaskstatus-1)
 
 ***
 
-<a id="usestoragerulesgateresult"></a>
-
-### UseStorageRulesGateResult
+<a id="usemetadataeditor"></a>
 
-#### Properties
+### useMetadataEditor
 
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="advisory"></a> `advisory` | `boolean` | Always false: `pyric/storage` handles are sandbox mirrors. |
-| <a id="error-6"></a> `error` | `Error` | Rules-resolution failure (e.g. a malformed `rules` string). |
-| <a id="identity-1"></a> `identity` | `any` | The identity the verdicts evaluate under. |
-| <a id="source"></a> `source` | [`StorageRulesSource`](#storagerulessource) | Where the active ruleset came from. |
-| <a id="status-3"></a> `status` | [`StorageRulesGateStatus`](#storagerulesgatestatus) | `'idle'` only when `storage` is null/undefined. |
-| <a id="verdictfor"></a> `verdictFor` | (`path`: `string`) => [`StorageGateVerdict`](#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. |
-| <a id="verdicts"></a> `verdicts` | `Record`\<`string`, [`StorageGateVerdict`](#storagegateverdict)\> | Pre-evaluated verdicts for `options.paths`, keyed by normalized path. |
+Re-exports [useMetadataEditor](pyric-ui-storage-reference-api.md#usemetadataeditor)
 
 ***
 
-<a id="usestorageselectionresult"></a>
-
-### UseStorageSelectionResult
-
-#### Properties
-
-| Property | Type | Description |
-| :------ | :------ | :------ |
-| <a id="clear"></a> `clear` | () => `void` | - |
-| <a id="deselect"></a> `deselect` | (`fullPath`: `string`) => `void` | - |
-| <a id="isselected"></a> `isSelected` | (`fullPath`: `string`) => `boolean` | - |
-| <a id="select"></a> `select` | (`entry`: [`StorageSelectionEntry`](#storageselectionentry)) => `void` | - |
-| <a id="selectall"></a> `selectAll` | (`entries`: [`StorageSelectionEntry`](#storageselectionentry)[]) => `void` | Replace the selection (e.g. a "select all" over `list.entries`). |
-| <a id="selected"></a> `selected` | [`StorageSelectionEntry`](#storageselectionentry)[] | Selected entries in selection order. |
-| <a id="size"></a> `size` | `number` | - |
-| <a id="toggle"></a> `toggle` | (`entry`: [`StorageSelectionEntry`](#storageselectionentry)) => `void` | Add/remove — the checkbox verb. |
-
-## Type Aliases
-
-<a id="metadataeditoraction"></a>
-
-### MetadataEditorAction
-
-```ts
-type MetadataEditorAction =
-  | {
-  type: "setContentType";
-  value: string;
-}
-  | {
-  type: "setCacheControl";
-  value: string;
-}
-  | {
-  id: string;
-  key: string;
-  type: "setCustomKey";
-}
-  | {
-  id: string;
-  type: "setCustomValue";
-  value: string;
-}
-  | {
-  key?: string;
-  type: "addCustomEntry";
-  value?: string;
-}
-  | {
-  id: string;
-  type: "removeCustomEntry";
-}
-  | {
-  type: "reset";
-}
-  | {
-  type: "commit";
-};
-```
-
-#### Type Declaration
-
-```ts
-{
-  type: "setContentType";
-  value: string;
-}
-```
-
-##### type
-
-```ts
-type: "setContentType";
-```
-
-##### value
-
-```ts
-value: string;
-```
-
-```ts
-{
-  type: "setCacheControl";
-  value: string;
-}
-```
-
-##### type
-
-```ts
-type: "setCacheControl";
-```
-
-##### value
-
-```ts
-value: string;
-```
-
-```ts
-{
-  id: string;
-  key: string;
-  type: "setCustomKey";
-}
-```
-
-##### id
-
-```ts
-id: string;
-```
-
-##### key
-
-```ts
-key: string;
-```
-
-##### type
-
-```ts
-type: "setCustomKey";
-```
-
-```ts
-{
-  id: string;
-  type: "setCustomValue";
-  value: string;
-}
-```
-
-##### id
-
-```ts
-id: string;
-```
-
-##### type
-
-```ts
-type: "setCustomValue";
-```
-
-##### value
-
-```ts
-value: string;
-```
-
-```ts
-{
-  key?: string;
-  type: "addCustomEntry";
-  value?: string;
-}
-```
-
-##### key?
-
-```ts
-optional key: string;
-```
-
-##### type
-
-```ts
-type: "addCustomEntry";
-```
-
-##### value?
-
-```ts
-optional value: string;
-```
-
-```ts
-{
-  id: string;
-  type: "removeCustomEntry";
-}
-```
-
-##### id
-
-```ts
-id: string;
-```
-
-##### type
-
-```ts
-type: "removeCustomEntry";
-```
-
-```ts
-{
-  type: "reset";
-}
-```
-
-##### type
-
-```ts
-type: "reset";
-```
-
-```ts
-{
-  type: "commit";
-}
-```
-
-##### type
+<a id="usemetadataeditoroptions"></a>
 
-```ts
-type: "commit";
-```
+### UseMetadataEditorOptions
 
-Internal — a successful save makes the draft the new baseline.
+Re-exports [UseMetadataEditorOptions](pyric-ui-storage-reference-api.md#usemetadataeditoroptions)
 
 ***
 
-<a id="storageliststatus"></a>
+<a id="usemetadataeditorresult"></a>
 
-### StorageListStatus
+### UseMetadataEditorResult
 
-```ts
-type StorageListStatus = "idle" | "loading" | "success" | "error";
-```
+Re-exports [UseMetadataEditorResult](pyric-ui-storage-reference-api.md#usemetadataeditorresult)
 
 ***
 
-<a id="storageobjectstatus"></a>
+<a id="useobjectupload"></a>
 
-### StorageObjectStatus
+### useObjectUpload
 
-```ts
-type StorageObjectStatus = "idle" | "loading" | "success" | "error";
-```
+Re-exports [useObjectUpload](pyric-ui-storage-reference-api.md#useobjectupload)
 
 ***
 
-<a id="storagerulesgatestatus"></a>
+<a id="useobjectuploadoptions"></a>
 
-### StorageRulesGateStatus
+### UseObjectUploadOptions
 
-```ts
-type StorageRulesGateStatus = "idle" | "loading" | "ready" | "error";
-```
+Re-exports [UseObjectUploadOptions](pyric-ui-storage-reference-api.md#useobjectuploadoptions)
 
 ***
 
-<a id="storagerulessource"></a>
-
-### StorageRulesSource
+<a id="useobjectuploadresult"></a>
 
-```ts
-type StorageRulesSource = "option" | "sandbox" | "none";
-```
+### UseObjectUploadResult
 
-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).
+Re-exports [UseObjectUploadResult](pyric-ui-storage-reference-api.md#useobjectuploadresult)
 
 ***
 
-<a id="uploadinput"></a>
-
-### UploadInput
+<a id="usepathstate"></a>
 
-```ts
-type UploadInput = File | UploadEntry;
-```
+### usePathState
 
-`upload()` accepts plain `File`s (destination = the file's
-`webkitRelativePath` when present — folder drops keep their
-structure — else its `name`) or explicit [UploadEntry](#uploadentry)s.
+Re-exports [usePathState](pyric-ui-storage-reference-api.md#usepathstate)
 
 ***
 
-<a id="uploadtaskstatus-1"></a>
-
-### UploadTaskStatus
-
-```ts
-type UploadTaskStatus = "running" | "success" | "error";
-```
-
-## Functions
-
-<a id="createlistalldeleteimpl"></a>
-
-### createListAllDeleteImpl()
-
-```ts
-function createListAllDeleteImpl(api?: Pick<StorageApi, "listAll" | "deleteObject">): StorageRecursiveDeleteImpl;
-```
-
-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.
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `api?` | `Pick`\<`StorageApi`, `"listAll"` \| `"deleteObject"`\> |
+<a id="usepathstateoptions"></a>
 
-#### Returns
+### UsePathStateOptions
 
-[`StorageRecursiveDeleteImpl`](#storagerecursivedeleteimpl)
+Re-exports [UsePathStateOptions](pyric-ui-storage-reference-api.md#usepathstateoptions)
 
 ***
 
-<a id="initmetadataeditorstate"></a>
-
-### initMetadataEditorState()
-
-```ts
-function initMetadataEditorState(initial: any): MetadataEditorState;
-```
-
-Build the edit state from the metadata a `getMetadata` /
- `useStorageObject` read returned.
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `initial` | `any` |
+<a id="usepathstateresult"></a>
 
-#### Returns
+### UsePathStateResult
 
-[`MetadataEditorState`](#metadataeditorstate)
+Re-exports [UsePathStateResult](pyric-ui-storage-reference-api.md#usepathstateresult)
 
 ***
 
-<a id="metadataeditorreducer"></a>
-
-### metadataEditorReducer()
-
-```ts
-function metadataEditorReducer(state: MetadataEditorState, action: MetadataEditorAction): MetadataEditorState;
-```
-
-Pure reducer — exported (with [initMetadataEditorState](#initmetadataeditorstate)) so
- the edit state is testable without React, mirroring the document
- editor's reducer/hook split.
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `state` | [`MetadataEditorState`](#metadataeditorstate) |
-| `action` | [`MetadataEditorAction`](#metadataeditoraction) |
+<a id="usestoragedelete"></a>
 
-#### Returns
+### useStorageDelete
 
-[`MetadataEditorState`](#metadataeditorstate)
+Re-exports [useStorageDelete](pyric-ui-storage-reference-api.md#usestoragedelete)
 
 ***
 
-<a id="normalizestoragepath"></a>
-
-### normalizeStoragePath()
-
-```ts
-function normalizeStoragePath(path: string): string;
-```
-
-Strip leading/trailing slashes and collapse repeats — mirrors
- `pyric/storage`'s reference normalization so `usePathState` and
- `useStorageList` always agree on what a path is.
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `path` | `string` |
+<a id="usestoragedeleteoptions"></a>
 
-#### Returns
+### UseStorageDeleteOptions
 
-`string`
+Re-exports [UseStorageDeleteOptions](pyric-ui-storage-reference-api.md#usestoragedeleteoptions)
 
 ***
 
-<a id="usemetadataeditor"></a>
-
-### useMetadataEditor()
-
-```ts
-function useMetadataEditor(
-   storage: any,
-   path: string,
-   options?: UseMetadataEditorOptions): UseMetadataEditorResult;
-```
-
-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.
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `storage` | `any` |
-| `path` | `string` |
-| `options?` | [`UseMetadataEditorOptions`](#usemetadataeditoroptions) |
+<a id="usestoragedeleteresult"></a>
 
-#### Returns
+### UseStorageDeleteResult
 
-[`UseMetadataEditorResult`](#usemetadataeditorresult)
+Re-exports [UseStorageDeleteResult](pyric-ui-storage-reference-api.md#usestoragedeleteresult)
 
 ***
 
-<a id="useobjectupload"></a>
-
-### useObjectUpload()
-
-```ts
-function useObjectUpload(storage: any, options?: UseObjectUploadOptions): UseObjectUploadResult;
-```
-
-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`).
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `storage` | `any` |
-| `options?` | [`UseObjectUploadOptions`](#useobjectuploadoptions) |
+<a id="usestoragelist"></a>
 
-#### Returns
+### useStorageList
 
-[`UseObjectUploadResult`](#useobjectuploadresult)
+Re-exports [useStorageList](pyric-ui-storage-reference-api.md#usestoragelist)
 
 ***
 
-<a id="usepathstate"></a>
-
-### usePathState()
-
-```ts
-function usePathState(options?: UsePathStateOptions): UsePathStateResult;
-```
-
-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`).
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `options?` | [`UsePathStateOptions`](#usepathstateoptions) |
+<a id="usestoragelistresult"></a>
 
-#### Returns
+### UseStorageListResult
 
-[`UsePathStateResult`](#usepathstateresult)
+Re-exports [UseStorageListResult](pyric-ui-storage-reference-api.md#usestoragelistresult)
 
 ***
 
-<a id="usestoragedelete"></a>
-
-### useStorageDelete()
-
-```ts
-function useStorageDelete(storage: any, options?: UseStorageDeleteOptions): UseStorageDeleteResult;
-```
-
-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.
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `storage` | `any` |
-| `options?` | [`UseStorageDeleteOptions`](#usestoragedeleteoptions) |
+<a id="usestorageobject"></a>
 
-#### Returns
+### useStorageObject
 
-[`UseStorageDeleteResult`](#usestoragedeleteresult)
+Re-exports [useStorageObject](pyric-ui-storage-reference-api.md#usestorageobject)
 
 ***
 
-<a id="usestoragelist"></a>
-
-### useStorageList()
-
-```ts
-function useStorageList(storage: any, path: string): UseStorageListResult;
-```
-
-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).
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `storage` | `any` |
-| `path` | `string` |
+<a id="usestorageobjectresult"></a>
 
-#### Returns
+### UseStorageObjectResult
 
-[`UseStorageListResult`](#usestoragelistresult)
+Re-exports [UseStorageObjectResult](pyric-ui-storage-reference-api.md#usestorageobjectresult)
 
 ***
 
-<a id="usestorageobject"></a>
-
-### useStorageObject()
-
-```ts
-function useStorageObject(storage: any, path: string): UseStorageObjectResult;
-```
-
-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`.
-
-#### Parameters
-
-| Parameter | Type |
-| :------ | :------ |
-| `storage` | `any` |
-| `path` | `string` |
+<a id="usestoragerulesgate"></a>
 
-#### Returns
+### useStorageRulesGate
 
-[`UseStorageObjectResult`](#usestorageobjectresult)
+Re-exports [useStorageRulesGate](pyric-ui-storage-reference-api.md#usestoragerulesgate)
 
 ***
 
-<a id="usestoragerulesgate"></a>
-
-### useStorageRulesGate()
-
-```ts
-function useStorageRulesGate(storage: any, options?: UseStorageRulesGateOptions): UseStorageRulesGateResult;
-```
-
-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`.
+<a id="usestoragerulesgateoptions"></a>
 
-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`. An explicit `rules` or `identity`
-option overrides the handle when evaluating a what-if scenario.
+### UseStorageRulesGateOptions
 
-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.
+Re-exports [UseStorageRulesGateOptions](pyric-ui-storage-reference-api.md#usestoragerulesgateoptions)
 
-#### Parameters
+***
 
-| Parameter | Type |
-| :------ | :------ |
-| `storage` | `any` |
-| `options?` | [`UseStorageRulesGateOptions`](#usestoragerulesgateoptions) |
+<a id="usestoragerulesgateresult"></a>
 
-#### Returns
+### UseStorageRulesGateResult
 
-[`UseStorageRulesGateResult`](#usestoragerulesgateresult)
+Re-exports [UseStorageRulesGateResult](pyric-ui-storage-reference-api.md#usestoragerulesgateresult)
 
 ***
 
 <a id="usestorageselection"></a>
 
-### useStorageSelection()
+### useStorageSelection
 
-```ts
-function useStorageSelection(): UseStorageSelectionResult;
-```
+Re-exports [useStorageSelection](pyric-ui-storage-reference-api.md#usestorageselection)
 
-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.
+***
+
+<a id="usestorageselectionresult"></a>
 
-#### Returns
+### UseStorageSelectionResult
 
-[`UseStorageSelectionResult`](#usestorageselectionresult)
+Re-exports [UseStorageSelectionResult](pyric-ui-storage-reference-api.md#usestorageselectionresult)