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

package/src/storage/components/ObjectBrowser.tsx

@@ -0,0 +1,219 @@
+import type { ReactNode } from 'react';
+import type { StorageReference } from 'pyric/storage';
+import { VirtualList } from '../../primitives/VirtualList.js';
+import { useContainerSize } from '../../primitives/hooks/useContainerSize.js';
+import type {
+  StorageListEntry,
+  StorageListStatus,
+} from '../hooks/useStorageList.js';
+import type { UseStorageRulesGateResult } from '../hooks/useStorageRulesGate.js';
+
+export interface ObjectBrowserProps {
+  /** The folders-first row model from `useStorageList`. */
+  entries: StorageListEntry[];
+  /** Drives the loading state (`'loading'` with no rows yet) and the
+   *  idle short-circuit. Default `'success'` for static usage. */
+  status?: StorageListStatus;
+  /** Renders a `role="alert"` container with the message. Pair with
+   *  the hook's typed `StorageError` for code-driven copy. */
+  error?: Error;
+  /** Folder row click — fired with the prefix's `fullPath`. Wire to
+   *  `usePathState.enter` (or `setPath`). */
+  onNavigate?: (path: string) => void;
+  /** Object row click — fired with the object's reference. */
+  onSelect?: (ref: StorageReference) => void;
+  /** Marks the matching object row `data-pyric-selected` +
+   *  `aria-selected`. */
+  selectedPath?: string;
+  /**
+   * Rules-aware affordances — pass `useStorageRulesGate(storage)`.
+   * Rows whose READ verdict denies are stamped `data-pyric-denied`
+   * (with the evaluator's reason trace on
+   * `data-pyric-denied-reason`). A denied folder row would throw
+   * `storage/unauthorized` on `listAll`; the stamp warns BEFORE the
+   * click. Rows stay clickable — the affordance is advisory and the
+   * sandbox enforcement layer remains authoritative.
+   */
+  gate?: Pick<UseStorageRulesGateResult, 'verdictFor'>;
+  /**
+   * Row-label slot. Default renders the entry name. The row button,
+   * its click wiring, and the `data-*` states stay with the
+   * component — the slot only owns the label content.
+   */
+  renderEntry?: (entry: StorageListEntry) => ReactNode;
+  /** Optional per-row action rendered as a sibling of the navigation/select
+   *  button. Use this for independent controls such as selection checkboxes. */
+  renderRowAction?: (entry: StorageListEntry) => ReactNode;
+  emptyState?: ReactNode;
+  className?: string;
+  /**
+   * Above this row count, the list switches to virtualization via
+   * `<VirtualList>` — `listAll` has no pagination, so a big prefix
+   * arrives as one flat result and virtualization is the only
+   * defense. Default 100 (same as `<DocumentList>`). `Infinity`
+   * disables.
+   */
+  virtualizeThreshold?: number;
+  /** Estimated row height when virtualizing. Default 36. */
+  rowHeight?: number | ((index: number) => number);
+  /** Scroll-container height when virtualized. Default `'60vh'`. */
+  virtualizedHeight?: number | string;
+}
+
+/**
+ * Headless storage browser shell — renders `useStorageList`'s merged
+ * folder/object rows. Folder rows navigate (`onNavigate` with the
+ * prefix path), object rows select (`onSelect` with the ref). Below
+ * `virtualizeThreshold` renders a plain `<ul>`; above it, composes
+ * the package's `<VirtualList>`.
+ *
+ * Ships no visual styling. Consumers style via:
+ * - `[data-pyric-ui="object-browser"]` — the root (stamps `data-size`)
+ * - `…[data-pyric-loading]` / `[data-pyric-empty]` / `[data-pyric-error]`
+ * - `…[data-pyric-virtualized]` — virtualized mode
+ * - `[data-pyric-object-browser-items]` — the `<ul>` in plain mode
+ * - `[data-pyric-storage-entry]` — each row
+ * - `[data-pyric-storage-entry][data-pyric-entry-kind="folder"|"object"]`
+ * - `[data-pyric-storage-entry][data-pyric-entry-path="docs/a.txt"]`
+ * - `[data-pyric-storage-entry][data-pyric-denied]` — read-denied row
+ *   (rules gate; reason on `data-pyric-denied-reason`)
+ * - `[data-pyric-entry-select]` — the row button
+ * - `[data-pyric-entry-select][data-pyric-selected]` — the selected object
+ * - `[data-pyric-storage-action]` — optional sibling row action
+ */
+export function ObjectBrowser({
+  entries,
+  status = 'success',
+  error,
+  onNavigate,
+  onSelect,
+  selectedPath,
+  gate,
+  renderEntry,
+  renderRowAction,
+  emptyState,
+  className,
+  virtualizeThreshold = 100,
+  rowHeight = 36,
+  virtualizedHeight = '60vh',
+}: ObjectBrowserProps) {
+  const { ref: rootRef, size } = useContainerSize<HTMLDivElement>();
+
+  if (error) {
+    return (
+      <div
+        className={className}
+        data-pyric-ui="object-browser"
+        data-pyric-error=""
+        role="alert"
+      >
+        {error.message}
+      </div>
+    );
+  }
+  if ((status === 'loading' || status === 'idle') && entries.length === 0) {
+    return (
+      <div
+        className={className}
+        data-pyric-ui="object-browser"
+        data-pyric-loading={status === 'loading' ? '' : undefined}
+        data-pyric-idle={status === 'idle' ? '' : undefined}
+      />
+    );
+  }
+  if (entries.length === 0) {
+    return (
+      <div className={className} data-pyric-ui="object-browser" data-pyric-empty="">
+        {emptyState}
+      </div>
+    );
+  }
+
+  // Pre-flight read verdict per row (advisory — see the `gate` prop).
+  const denialFor = (
+    entry: StorageListEntry,
+  ): { denied: true; reason: string } | { denied: false; reason?: undefined } => {
+    if (!gate) return { denied: false };
+    const verdict = gate.verdictFor(entry.fullPath);
+    return verdict.read
+      ? { denied: false }
+      : { denied: true, reason: verdict.reasons.read.join('; ') };
+  };
+
+  const renderRow = (entry: StorageListEntry) => {
+    const selected = entry.kind === 'object' && entry.fullPath === selectedPath;
+    return (
+      <>
+        <button
+          type="button"
+          onClick={() =>
+            entry.kind === 'folder'
+              ? onNavigate?.(entry.fullPath)
+              : onSelect?.(entry.ref)
+          }
+          data-pyric-entry-select
+          data-pyric-selected={selected ? '' : undefined}
+          aria-selected={selected || undefined}
+        >
+          {renderEntry ? renderEntry(entry) : entry.name}
+        </button>
+        {renderRowAction ? (
+          <span data-pyric-storage-action>{renderRowAction(entry)}</span>
+        ) : null}
+      </>
+    );
+  };
+
+  const virtualized = entries.length > virtualizeThreshold;
+
+  return (
+    <div
+      ref={rootRef}
+      className={className}
+      data-pyric-ui="object-browser"
+      data-size={size}
+      data-pyric-virtualized={virtualized ? '' : undefined}
+    >
+      {virtualized ? (
+        <VirtualList
+          items={entries}
+          estimateSize={rowHeight}
+          height={virtualizedHeight}
+          getItemKey={(entry) => `${entry.kind}:${entry.fullPath}`}
+          renderItem={(entry) => {
+            const denial = denialFor(entry);
+            return (
+              <div
+                data-pyric-storage-entry
+                data-pyric-entry-kind={entry.kind}
+                data-pyric-entry-path={entry.fullPath}
+                data-pyric-denied={denial.denied ? '' : undefined}
+                data-pyric-denied-reason={denial.reason}
+              >
+                {renderRow(entry)}
+              </div>
+            );
+          }}
+        />
+      ) : (
+        <ul data-pyric-object-browser-items>
+          {entries.map((entry) => {
+            const denial = denialFor(entry);
+            return (
+              <li
+                key={`${entry.kind}:${entry.fullPath}`}
+                data-pyric-storage-entry
+                data-pyric-entry-kind={entry.kind}
+                data-pyric-entry-path={entry.fullPath}
+                data-pyric-denied={denial.denied ? '' : undefined}
+                data-pyric-denied-reason={denial.reason}
+              >
+                {renderRow(entry)}
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/storage/components/ObjectInspector.tsx

@@ -0,0 +1,169 @@
+import { useEffect, type ReactNode } from 'react';
+import type { FirebaseStorage, FullMetadata } from 'pyric/storage';
+import { useContainerSize } from '../../primitives/hooks/useContainerSize.js';
+import { useStorageObject } from '../hooks/useStorageObject.js';
+import { selectStoragePreview, type StoragePreview } from '../previews.js';
+
+export interface ObjectInspectorProps {
+  /** The package's sandbox Storage handle. */
+  storage: FirebaseStorage | null | undefined;
+  /** Object path to inspect. `null` renders the idle shell — keep
+   *  the inspector mounted and swap paths as the user selects rows. */
+  path: string | null;
+  /** Consumer previews, tried BEFORE the built-ins (first match
+   *  wins) — the extension channel of the preview registry. */
+  previews?: StoragePreview[];
+  /** Metadata-section slot. Default renders the standard field list.
+   *  The header, preview, and state wiring stay with the component. */
+  renderMetadata?: (metadata: FullMetadata) => ReactNode;
+  /** Extra content below the preview (metadata editor, delete
+   *  button, …). */
+  children?: ReactNode;
+  className?: string;
+}
+
+const METADATA_FIELDS: ReadonlyArray<{
+  key: string;
+  label: string;
+  value: (md: FullMetadata) => string | undefined;
+}> = [
+  { key: 'fullPath', label: 'Path', value: (md) => md.fullPath },
+  { key: 'size', label: 'Size', value: (md) => `${md.size}` },
+  { key: 'contentType', label: 'Content type', value: (md) => md.contentType },
+  { key: 'cacheControl', label: 'Cache control', value: (md) => md.cacheControl },
+  { key: 'timeCreated', label: 'Created', value: (md) => md.timeCreated },
+  { key: 'updated', label: 'Updated', value: (md) => md.updated },
+];
+
+function DefaultMetadata({ metadata }: { metadata: FullMetadata }) {
+  return (
+    <dl data-pyric-object-metadata>
+      {METADATA_FIELDS.map(({ key, label, value }) => {
+        const v = value(metadata);
+        if (v === undefined) return null;
+        return (
+          <div key={key} data-pyric-metadata-field={key}>
+            <dt>{label}</dt>
+            <dd>{v}</dd>
+          </div>
+        );
+      })}
+      {Object.entries(metadata.customMetadata ?? {}).map(([k, v]) => (
+        <div key={`custom:${k}`} data-pyric-metadata-field="customMetadata" data-pyric-metadata-key={k}>
+          <dt>{k}</dt>
+          <dd>{v}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+/**
+ * Headless inspector for one storage object: metadata + a
+ * content-type-driven preview. Previews come from the registry
+ * (`image/*` and `text/* + application/json` built in; extend via
+ * `previews`). Blob bytes load lazily and ONLY when the matched
+ * preview asks (`needsBlob`) and the object is within the preview's
+ * `maxBytes` cap; the blob URL is revoked on unmount/path change
+ * (see `useStorageObject`).
+ *
+ * Ships no visual styling. Consumers style via:
+ * - `[data-pyric-ui="object-inspector"]` — root (stamps `data-size`)
+ * - `…[data-pyric-idle]` / `[data-pyric-loading]` / `[data-pyric-error]`
+ * - `[data-pyric-object-name]` / `[data-pyric-object-metadata]`
+ * - `[data-pyric-metadata-field="<field>"]` — each metadata row
+ * - `[data-pyric-object-preview]` — the preview container, stamping
+ *   `data-pyric-preview="<id>"` for the matched registry entry
+ * - `…[data-pyric-preview-loading]` — blob in flight
+ * - `…[data-pyric-preview-error]` — blob load failed
+ * - `…[data-pyric-preview-too-large]` — over the preview's cap
+ * - `…[data-pyric-preview-none]` — no registry match (metadata-only)
+ */
+export function ObjectInspector({
+  storage,
+  path,
+  previews,
+  renderMetadata,
+  children,
+  className,
+}: ObjectInspectorProps) {
+  const { ref: rootRef, size } = useContainerSize<HTMLDivElement>();
+  const object = useStorageObject(storage, path);
+  const { metadata, blobStatus, loadBlob } = object;
+
+  const preview = metadata ? selectStoragePreview(metadata, previews) : undefined;
+  const tooLarge =
+    preview?.maxBytes !== undefined &&
+    metadata !== undefined &&
+    metadata.size > preview.maxBytes;
+  const wantsBlob = preview?.needsBlob === true && !tooLarge;
+
+  // Auto-load the bytes when (and only when) the matched preview
+  // needs them. `blobStatus` resets to 'idle' on path change, which
+  // re-arms this effect for the next object.
+  useEffect(() => {
+    if (wantsBlob && blobStatus === 'idle') loadBlob();
+  }, [wantsBlob, blobStatus, loadBlob]);
+
+  if (object.status === 'idle') {
+    return (
+      <div className={className} data-pyric-ui="object-inspector" data-pyric-idle="" />
+    );
+  }
+  if (object.status === 'loading') {
+    return (
+      <div className={className} data-pyric-ui="object-inspector" data-pyric-loading="" />
+    );
+  }
+  if (object.status === 'error' || metadata === undefined) {
+    return (
+      <div
+        className={className}
+        data-pyric-ui="object-inspector"
+        data-pyric-error=""
+        role="alert"
+      >
+        {object.error?.message}
+      </div>
+    );
+  }
+
+  let previewContent: ReactNode;
+  let previewState: Record<string, ''> = {};
+  if (preview === undefined) {
+    previewState = { 'data-pyric-preview-none': '' };
+  } else if (tooLarge) {
+    previewState = { 'data-pyric-preview-too-large': '' };
+  } else if (wantsBlob && blobStatus === 'loading') {
+    previewState = { 'data-pyric-preview-loading': '' };
+  } else if (wantsBlob && blobStatus === 'error') {
+    previewState = { 'data-pyric-preview-error': '' };
+    previewContent = object.blobError?.message;
+  } else if (!wantsBlob || blobStatus === 'success') {
+    previewContent = preview.render({
+      metadata,
+      blob: object.blob,
+      blobUrl: object.blobUrl,
+    });
+  }
+
+  return (
+    <div
+      ref={rootRef}
+      className={className}
+      data-pyric-ui="object-inspector"
+      data-size={size}
+    >
+      <div data-pyric-object-name>{metadata.name}</div>
+      {renderMetadata ? renderMetadata(metadata) : <DefaultMetadata metadata={metadata} />}
+      <div
+        data-pyric-object-preview
+        data-pyric-preview={preview?.id}
+        {...previewState}
+      >
+        {previewContent}
+      </div>
+      {children}
+    </div>
+  );
+}

package/src/storage/components/PathBreadcrumb.tsx

@@ -0,0 +1,84 @@
+import type { ReactNode } from 'react';
+import { normalizeStoragePath } from '../hooks/usePathState.js';
+
+export interface PathBreadcrumbProps {
+  /** Current path. `''` renders just the root crumb. */
+  path: string;
+  /** Fired with the absolute path of the clicked crumb (`''` for
+   *  root). Wire to `usePathState.setPath`. */
+  onNavigate?: (path: string) => void;
+  /** Label for the root crumb. Default `'/'` — pass the bucket name
+   *  for a `gs://bucket` feel. */
+  rootLabel?: ReactNode;
+  /** Rendered between crumbs. Default `'/'`. */
+  separator?: ReactNode;
+  className?: string;
+}
+
+/**
+ * Headless breadcrumb for storage paths. Every crumb (including the
+ * current one) is a real `<button>` — clicking the current crumb is
+ * a cheap "refresh this level" affordance for consumers that wire
+ * `onNavigate` to a path-keyed loader.
+ *
+ * Ships no visual styling. Consumers style via:
+ * - `[data-pyric-ui="path-breadcrumb"]` — the `<nav>` root
+ * - `[data-pyric-breadcrumb-item]` — each `<li>`
+ * - `[data-pyric-breadcrumb-link]` — each crumb button
+ * - `[data-pyric-breadcrumb-link][data-pyric-current]` — the current level
+ * - `[data-pyric-breadcrumb-root]` — the root crumb's button
+ * - `[data-pyric-breadcrumb-separator]` — the separators
+ */
+export function PathBreadcrumb({
+  path,
+  onNavigate,
+  rootLabel = '/',
+  separator = '/',
+  className,
+}: PathBreadcrumbProps) {
+  const normalized = normalizeStoragePath(path);
+  const segments = normalized === '' ? [] : normalized.split('/');
+
+  return (
+    <nav
+      className={className}
+      data-pyric-ui="path-breadcrumb"
+      aria-label="Storage path"
+    >
+      <ol data-pyric-breadcrumb-list>
+        <li data-pyric-breadcrumb-item>
+          <button
+            type="button"
+            onClick={() => onNavigate?.('')}
+            data-pyric-breadcrumb-link
+            data-pyric-breadcrumb-root
+            data-pyric-current={segments.length === 0 ? '' : undefined}
+            aria-current={segments.length === 0 ? 'page' : undefined}
+          >
+            {rootLabel}
+          </button>
+        </li>
+        {segments.map((segment, i) => {
+          const isCurrent = i === segments.length - 1;
+          const target = segments.slice(0, i + 1).join('/');
+          return (
+            <li key={target} data-pyric-breadcrumb-item>
+              <span aria-hidden data-pyric-breadcrumb-separator>
+                {separator}
+              </span>
+              <button
+                type="button"
+                onClick={() => onNavigate?.(target)}
+                data-pyric-breadcrumb-link
+                data-pyric-current={isCurrent ? '' : undefined}
+                aria-current={isCurrent ? 'page' : undefined}
+              >
+                {segment}
+              </button>
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+}

package/src/storage/components/UploadDropzone.tsx

@@ -0,0 +1,182 @@
+import { useCallback, useRef, useState, type DragEvent, type ReactNode } from 'react';
+
+/** One dropped file, flattened from the drop's file/folder tree. */
+export interface DroppedFile {
+  file: File;
+  /**
+   * Path relative to the drop — `'a.txt'` for a plain file drop,
+   * `'photos/cat.png'` for a file inside a dropped folder. Feed
+   * straight into `useObjectUpload`:
+   * `upload(files.map((f) => ({ path: f.relativePath, data: f.file })))`.
+   */
+  relativePath: string;
+}
+
+export interface UploadDropzoneProps {
+  /**
+   * Fired once per drop with the flattened file list (folder drops
+   * are traversed recursively via `webkitGetAsEntry`; empty folders
+   * yield nothing — wire `useObjectUpload.createFolder` to your own
+   * "new folder" affordance instead). Not fired for empty drops.
+   */
+  onFiles: (files: DroppedFile[]) => void;
+  /** Slot — the dropzone chrome ("Drop files here…", a browse
+   *  `<input type="file">`, anything). The component owns only the
+   *  drag wiring + `data-*` states. */
+  children?: ReactNode;
+  /** Ignore drops + suppress the dragging state. */
+  disabled?: boolean;
+  /**
+   * Why the dropzone is disabled — stamped on
+   * `data-disabled-reason` (and only while `disabled`) so the
+   * chrome/styling can surface it. The canonical source is the rules
+   * gate: `disabled={!gate.verdictFor(path).upload}` +
+   * `disabledReason={gate.verdictFor(path).reasons.write.join('; ')}`.
+   */
+  disabledReason?: string;
+  className?: string;
+}
+
+/**
+ * Walk a `FileSystemEntry` tree depth-first, accumulating files with
+ * folder-relative paths. `readEntries` is batched per spec (Chrome
+ * caps a batch at 100) — loop until an empty batch.
+ */
+async function walkEntry(
+  entry: FileSystemEntry,
+  prefix: string,
+  out: DroppedFile[],
+): Promise<void> {
+  const path = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+  if (entry.isFile) {
+    const file = await new Promise<File>((resolve, reject) =>
+      (entry as FileSystemFileEntry).file(resolve, reject),
+    );
+    out.push({ file, relativePath: path });
+    return;
+  }
+  if (entry.isDirectory) {
+    const reader = (entry as FileSystemDirectoryEntry).createReader();
+    for (;;) {
+      const batch = await new Promise<FileSystemEntry[]>((resolve, reject) =>
+        reader.readEntries(resolve, reject),
+      );
+      if (batch.length === 0) break;
+      for (const child of batch) {
+        await walkEntry(child, path, out);
+      }
+    }
+  }
+}
+
+/**
+ * Flatten a drop's `DataTransfer` into files. Prefers the
+ * `webkitGetAsEntry` tree (the only channel that exposes folder
+ * structure); items without it fall back to `getAsFile`, and a
+ * `DataTransfer` with no usable `items` falls back to `files`.
+ */
+async function collectDroppedFiles(dt: DataTransfer): Promise<DroppedFile[]> {
+  const out: DroppedFile[] = [];
+  const items = dt.items ? Array.from(dt.items) : [];
+  for (const item of items) {
+    if (item.kind !== 'file') continue;
+    const getEntry = (
+      item as { webkitGetAsEntry?: () => FileSystemEntry | null }
+    ).webkitGetAsEntry;
+    const entry = typeof getEntry === 'function' ? getEntry.call(item) : null;
+    if (entry) {
+      await walkEntry(entry, '', out);
+    } else {
+      const file = item.getAsFile?.();
+      if (file) out.push({ file, relativePath: file.name });
+    }
+  }
+  if (out.length === 0) {
+    for (const file of Array.from(dt.files ?? [])) {
+      out.push({ file, relativePath: file.name });
+    }
+  }
+  return out;
+}
+
+/**
+ * Headless drop target for file + folder uploads. Slot-based: the
+ * children render the chrome; the component owns drag wiring and
+ * stamps `data-dragging` while a drag hovers (a counter tracks
+ * enter/leave pairs so crossing child elements doesn't flicker).
+ *
+ * Ships no visual styling. Consumers style via:
+ * - `[data-pyric-ui="upload-dropzone"]` — the root
+ * - `…[data-dragging]` — a drag is hovering
+ * - `…[data-disabled]`
+ * - `…[data-disabled-reason="…"]` — why (e.g. a denied write verdict)
+ */
+export function UploadDropzone({
+  onFiles,
+  children,
+  disabled,
+  disabledReason,
+  className,
+}: UploadDropzoneProps) {
+  const [dragging, setDragging] = useState(false);
+  // dragenter/dragleave fire for every child crossing — count the
+  // pairs and only clear at depth 0.
+  const depthRef = useRef(0);
+
+  const handleDragEnter = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      if (disabled) return;
+      depthRef.current += 1;
+      setDragging(true);
+    },
+    [disabled],
+  );
+
+  const handleDragOver = useCallback((e: DragEvent<HTMLDivElement>) => {
+    // Required — without preventDefault the browser refuses the drop.
+    e.preventDefault();
+  }, []);
+
+  const handleDragLeave = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      if (disabled) return;
+      depthRef.current = Math.max(0, depthRef.current - 1);
+      if (depthRef.current === 0) setDragging(false);
+    },
+    [disabled],
+  );
+
+  const handleDrop = useCallback(
+    (e: DragEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      depthRef.current = 0;
+      setDragging(false);
+      if (disabled) return;
+      const dt = e.dataTransfer;
+      if (!dt) return;
+      void collectDroppedFiles(dt).then((files) => {
+        if (files.length > 0) onFiles(files);
+      });
+    },
+    [disabled, onFiles],
+  );
+
+  return (
+    <div
+      className={className}
+      data-pyric-ui="upload-dropzone"
+      data-dragging={dragging ? '' : undefined}
+      data-disabled={disabled ? '' : undefined}
+      data-disabled-reason={disabled ? disabledReason : undefined}
+      aria-disabled={disabled || undefined}
+      onDragEnter={handleDragEnter}
+      onDragOver={handleDragOver}
+      onDragLeave={handleDragLeave}
+      onDrop={handleDrop}
+    >
+      {children}
+    </div>
+  );
+}

package/src/storage/folderPlaceholder.ts

@@ -0,0 +1,40 @@
+import { ref as refFn, type FirebaseStorage, type StorageReference } from 'pyric/storage';
+
+/**
+ * Internal — build a reference to the trailing-slash folder
+ * placeholder (`<path>/`, the GCS create-folder convention).
+ *
+ * `StorageReference` is a documented structural value object (two
+ * refs with the same `(storage, fullPath)` are equal), so a plain
+ * object is a legal reference — the only way to express a `<path>/`
+ * name past `ref()`'s slash normalization. This helper is specific to
+ * the Pyric sandbox mirror.
+ */
+export function folderPlaceholderRef(
+  storage: FirebaseStorage,
+  folderPath: string,
+): StorageReference {
+  const folder = refFn(storage, folderPath);
+  return {
+    storage,
+    bucket: folder.bucket,
+    fullPath: `${folder.fullPath}/`,
+    name: '',
+    parent: folder,
+    root: folder.root,
+    toString: () => `${folder.toString()}/`,
+  };
+}
+
+/** Preserve whichever backend identity a reference carries (in-process
+ *  storage handle or worker MessagePort) while targeting its trailing-slash
+ *  GCS folder placeholder. */
+export function asFolderPlaceholder<T extends { fullPath: string; name: string }>(
+  folder: T,
+): T {
+  return {
+    ...folder,
+    fullPath: `${folder.fullPath}/`,
+    name: '',
+  };
+}