feat: wire web file upload through the facade write handles

apps/web/src/components/file-browser/FileBrowser.tsx

@@ -2,10 +2,11 @@ import { useFolderNavigation } from '../../vault/useFolderNavigation';
 import { Breadcrumbs } from './Breadcrumbs';
 import { EmptyState } from './EmptyState';
 import { FileList } from './FileList';
+import { UploadPanel } from './UploadPanel';
 
 /** The vault browser: where you are, what is in it, and how to move. */
 export function FileBrowser() {
-  const { rows, breadcrumbs, isLoading, isRoot, error, navigateTo, navigateUp } =
+  const { rows, folder, breadcrumbs, isLoading, isRoot, error, navigateTo, navigateUp } =
     useFolderNavigation();
   const settled = !isLoading && error === null;
 
@@ -22,6 +23,9 @@ export function FileBrowser() {
           {'// LOADING VAULT...'}
         </p>
       )}
+      {/* Mounted whatever the route says, so a running upload survives a folder
+          change; only its drop target waits for a folder that can take one. */}
+      <UploadPanel folder={settled ? folder : null} />
       {/* An empty non-root folder still lists, so `[..]` remains reachable. */}
       {settled && (rows.length > 0 || !isRoot) && (
         <FileList

apps/web/src/components/file-browser/UploadListItem.test.tsx

@@ -0,0 +1,103 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { UploadEntry } from '../../hooks/useDropUpload';
+import { UploadListItem } from './UploadListItem';
+
+function entry(overrides: Partial<UploadEntry> = {}): UploadEntry {
+  return {
+    id: 'upload-1',
+    name: 'report.pdf',
+    size: 2048,
+    phase: 'staging',
+    progress: 0,
+    opId: null,
+    error: null,
+    code: null,
+    ...overrides,
+  };
+}
+
+function show(upload: UploadEntry) {
+  const handlers = { onCancel: vi.fn(), onRetry: vi.fn(), onDismiss: vi.fn() };
+  render(<UploadListItem upload={upload} {...handlers} />);
+  return handlers;
+}
+
+describe('an upload row', () => {
+  it('quotes the confirmed fraction once the drain reports blocks', () => {
+    show(entry({ phase: 'uploading', progress: 0.5, opId: 1n }));
+
+    const bar = screen.getByRole('progressbar');
+    expect(bar.getAttribute('aria-valuenow')).toBe('50');
+    expect(screen.getByTestId('upload-row-status').textContent).toBe('50%');
+  });
+
+  it('shimmers only while the client is feeding the engine', () => {
+    show(entry({ phase: 'staging' }));
+
+    const bar = screen.getByRole('progressbar');
+    expect(bar.getAttribute('aria-valuenow')).toBeNull();
+    expect(bar.className).toContain('upload-row-track--indeterminate');
+  });
+
+  it('leaves a queued row still, because nothing is moving yet', () => {
+    show(entry({ phase: 'queued', opId: 1n }));
+
+    const bar = screen.getByRole('progressbar');
+    expect(bar.getAttribute('aria-valuetext')).toBe('queued');
+    expect(bar.className).not.toContain('upload-row-track--indeterminate');
+  });
+
+  it('offers cancel while the engine still has work', () => {
+    const handlers = show(entry({ phase: 'uploading', opId: 1n }));
+
+    fireEvent.click(screen.getByLabelText('Cancel upload of report.pdf'));
+
+    expect(handlers.onCancel).toHaveBeenCalledWith('upload-1');
+    expect(screen.queryByLabelText('Retry upload of report.pdf')).toBeNull();
+  });
+
+  it('offers retry and dismiss once a row has failed for good', () => {
+    const handlers = show(entry({ phase: 'failed', error: 'no reachable pin provider' }));
+
+    fireEvent.click(screen.getByLabelText('Retry upload of report.pdf'));
+    fireEvent.click(screen.getByLabelText('Dismiss upload of report.pdf'));
+
+    expect(handlers.onRetry).toHaveBeenCalledWith('upload-1');
+    expect(handlers.onDismiss).toHaveBeenCalledWith('upload-1');
+    expect(screen.queryByRole('progressbar')).toBeNull();
+    expect(screen.getByRole('alert').textContent).toBe('no reachable pin provider');
+  });
+
+  it('lets a cancelled row be cleared, so none can strand its file', () => {
+    const handlers = show(entry({ phase: 'cancelled', opId: 1n }));
+
+    fireEvent.click(screen.getByLabelText('Dismiss upload of report.pdf'));
+
+    expect(handlers.onDismiss).toHaveBeenCalledWith('upload-1');
+    expect(screen.queryByLabelText('Cancel upload of report.pdf')).toBeNull();
+  });
+
+  it('marks an over-budget refusal apart from a failure that will never clear', () => {
+    show(
+      entry({
+        phase: 'failed',
+        code: 'overBudget',
+        error: 'this write needs 900 bytes but only 100 are free',
+      })
+    );
+
+    expect(screen.getByTestId('upload-row-error').className).toContain(
+      'upload-row-error--transient'
+    );
+  });
+
+  it('marks a stopped attempt as retryable, not settled', () => {
+    show(entry({ phase: 'stalled', opId: 1n, error: 'no reachable pin provider' }));
+
+    expect(screen.getByTestId('upload-row-error').className).toContain(
+      'upload-row-error--transient'
+    );
+    expect(screen.getByTestId('upload-row-error').getAttribute('role')).toBeNull();
+  });
+});

apps/web/src/components/file-browser/UploadListItem.tsx

@@ -0,0 +1,113 @@
+import { isActiveUpload, type UploadEntry, type UploadPhase } from '../../hooks/useDropUpload';
+import { formatBytes } from '../../utils/format';
+
+interface UploadListItemProps {
+  upload: UploadEntry;
+  onCancel: (id: string) => void;
+  onRetry: (id: string) => void;
+  onDismiss: (id: string) => void;
+}
+
+const LABELS: Record<UploadPhase, string> = {
+  staging: 'sealing',
+  queued: 'queued',
+  uploading: 'uploading',
+  uploaded: 'done',
+  stalled: 'retrying',
+  cancelled: 'cancelled',
+  failed: 'failed',
+};
+
+/** One in-flight upload, in the columns the listing below it uses. */
+export function UploadListItem({ upload, onCancel, onRetry, onDismiss }: UploadListItemProps) {
+  const { id, name, phase, error } = upload;
+  const percent = Math.round(upload.progress * 100);
+  const settled = !isActiveUpload(phase);
+  const measured = phase === 'uploading';
+  // Only the row the client is actually feeding animates; a queued or retrying
+  // one has nothing moving to report.
+  const indeterminate = phase === 'staging';
+  // An over-budget refusal is a ceiling and a stopped attempt is retried, so
+  // neither reads as the settled red of a row that will never publish.
+  const transient = phase === 'stalled' || upload.code === 'overBudget';
+
+  return (
+    <div
+      className={`file-list-item upload-row upload-row--${phase}`}
+      data-testid="upload-row"
+      data-phase={phase}
+      role="listitem"
+    >
+      <div className="file-list-item-row-top">
+        <span className="file-list-item-icon" aria-hidden="true">
+          {phase === 'failed' ? '[!]' : '[^]'}
+        </span>
+        <div className="upload-row-name">
+          <span className="file-list-item-name">{name}</span>
+          {!settled && (
+            <div
+              className={`upload-row-track${indeterminate ? ' upload-row-track--indeterminate' : ''}`}
+              role="progressbar"
+              aria-label={`Upload progress for ${name}`}
+              {...(measured
+                ? { 'aria-valuenow': percent, 'aria-valuemin': 0, 'aria-valuemax': 100 }
+                : { 'aria-valuetext': LABELS[phase] })}
+            >
+              <div className="upload-row-fill" style={{ width: `${measured ? percent : 0}%` }} />
+            </div>
+          )}
+        </div>
+      </div>
+      <div className="file-list-item-row-bottom">
+        <span className="file-list-item-size">{formatBytes(upload.size)}</span>
+        <span className="file-list-item-date upload-row-actions">
+          <span className="upload-row-status" data-testid="upload-row-status">
+            {phase === 'uploading' ? `${percent}%` : LABELS[phase]}
+          </span>
+          {!settled && (
+            <button
+              type="button"
+              className="upload-row-button"
+              aria-label={`Cancel upload of ${name}`}
+              onClick={() => onCancel(id)}
+            >
+              [x]
+            </button>
+          )}
+          {settled && (
+            <>
+              {phase !== 'uploaded' && (
+                <button
+                  type="button"
+                  className="upload-row-button upload-row-button--retry"
+                  aria-label={`Retry upload of ${name}`}
+                  onClick={() => onRetry(id)}
+                >
+                  [r]
+                </button>
+              )}
+              {/* Every settled row is clearable, so none can strand its `File`. */}
+              <button
+                type="button"
+                className="upload-row-button"
+                aria-label={`Dismiss upload of ${name}`}
+                onClick={() => onDismiss(id)}
+              >
+                [x]
+              </button>
+            </>
+          )}
+        </span>
+      </div>
+      {error !== null && (
+        <p
+          className={`upload-row-error${transient ? ' upload-row-error--transient' : ''}`}
+          data-testid="upload-row-error"
+          role={phase === 'failed' ? 'alert' : undefined}
+        >
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}

apps/web/src/components/file-browser/UploadPanel.test.tsx

@@ -0,0 +1,93 @@
+import type { EngineClient, EventDescriptor } from '@cipherbox/client';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { EngineProvider } from '../../providers/EngineProvider';
+import { UploadPanel } from './UploadPanel';
+
+const FOLDER = new Uint8Array(16).fill(7);
+
+/** The write-handle surface `useDropUpload` drives, held open at the commit. */
+function uploadEngine() {
+  let settle = () => undefined as void;
+  const facade = {
+    subscribe: (_listener: (event: EventDescriptor) => void) => () => undefined,
+    snapshot: () => new Promise<never>(() => undefined),
+    setFocus: () => Promise.resolve(),
+    beginWrite: vi.fn(() => Promise.resolve(1n)),
+    pushChunk: vi.fn(() => Promise.resolve()),
+    commitWrite: vi.fn(
+      () =>
+        new Promise<bigint>((resolve) => {
+          settle = () => resolve(1n);
+        })
+    ),
+    abortWrite: vi.fn(() => Promise.resolve()),
+    cancelUpload: vi.fn(() => Promise.resolve()),
+  };
+  const client = {
+    facade,
+    reportFocus: () => undefined,
+    dispose: () => Promise.resolve(),
+  } as unknown as EngineClient;
+  return { client, facade, settle: () => settle() };
+}
+
+function draw(client: EngineClient, folder: Uint8Array | null) {
+  return render(
+    <EngineProvider createClient={() => client}>
+      <UploadPanel folder={folder} />
+    </EngineProvider>
+  );
+}
+
+describe('the upload panel', () => {
+  it('offers no drop target when no folder can take one', () => {
+    draw(uploadEngine().client, null);
+    expect(screen.queryByTestId('upload-zone')).toBeNull();
+  });
+
+  it('keeps a running upload on screen across a folder change', async () => {
+    const engine = uploadEngine();
+    const { rerender } = draw(engine.client, FOLDER);
+
+    fireEvent.change(screen.getByLabelText('Choose files to upload'), {
+      target: { files: [new File(['x'], 'notes.txt')] },
+    });
+    await waitFor(() => expect(screen.getByTestId('upload-row')).toBeTruthy());
+
+    // The next folder's snapshot has not landed, so there is nowhere to drop.
+    rerender(
+      <EngineProvider createClient={() => engine.client}>
+        <UploadPanel folder={null} />
+      </EngineProvider>
+    );
+
+    expect(screen.queryByTestId('upload-zone')).toBeNull();
+    expect(screen.getByTestId('upload-row')).toBeTruthy();
+    expect(screen.getByLabelText('Cancel upload of notes.txt')).toBeTruthy();
+    // The write kept its handle rather than being torn down with the zone.
+    expect(engine.facade.abortWrite).not.toHaveBeenCalled();
+    await act(async () => {
+      engine.settle();
+    });
+  });
+
+  it('drops files into the folder on screen', async () => {
+    const engine = uploadEngine();
+    draw(engine.client, FOLDER);
+
+    fireEvent.drop(screen.getByTestId('upload-zone'), {
+      dataTransfer: { files: [new File(['x'], 'notes.txt')], types: ['Files'], dropEffect: 'none' },
+    });
+
+    await waitFor(() =>
+      expect(engine.facade.beginWrite).toHaveBeenCalledWith(
+        { parent: FOLDER, name: 'notes.txt' },
+        1
+      )
+    );
+    await act(async () => {
+      engine.settle();
+    });
+  });
+});

apps/web/src/components/file-browser/UploadPanel.tsx

@@ -0,0 +1,42 @@
+import { isActiveUpload, useDropUpload } from '../../hooks/useDropUpload';
+import { UploadListItem } from './UploadListItem';
+import { UploadZone } from './UploadZone';
+
+interface UploadPanelProps {
+  /** Where a drop lands, or `null` when nothing on screen can take one. */
+  folder: Uint8Array | null;
+}
+
+/**
+ * The upload surface. It owns the upload rows so a block-confirmed event
+ * repaints them alone, not the listing underneath, and it outlives a folder
+ * change so a running upload keeps its row, its controls, and its subscription
+ * to the engine's reports — only the drop target follows the folder.
+ */
+export function UploadPanel({ folder }: UploadPanelProps) {
+  const { uploads, upload, cancel, retry, dismiss } = useDropUpload();
+
+  return (
+    <>
+      {folder !== null && (
+        <UploadZone
+          onFiles={(files) => upload(files, folder)}
+          busy={uploads.some((entry) => isActiveUpload(entry.phase))}
+        />
+      )}
+      {uploads.length > 0 && (
+        <div className="upload-list" role="list" data-testid="upload-list">
+          {uploads.map((entry) => (
+            <UploadListItem
+              key={entry.id}
+              upload={entry}
+              onCancel={cancel}
+              onRetry={retry}
+              onDismiss={dismiss}
+            />
+          ))}
+        </div>
+      )}
+    </>
+  );
+}