@beignet/react-uploads 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# @beignet/react-uploads
+
+## 0.0.3
+
+### Patch Changes
+
+- 4cb1784: Add first-class upload router primitives, a typed browser upload client, a
+  React upload adapter, Next.js upload route helper, S3-compatible direct upload
+  signing, devtools upload watcher support, an upload generator, and a
+  first-class `beignet make feature` command with optional policy, event, job,
+  and upload artifacts for the standard vertical slice. Add first-class job retry
+  helpers, outbox retry policy integration, and job retry/dead-letter devtools
+  events. Add a Next.js outbox drain route helper and doctor warnings for
+  serverless background-work footguns.
+- Updated dependencies [3160184]
+- Updated dependencies [254ef6d]
+- Updated dependencies [4cb1784]
+- Updated dependencies [8bd9085]
+  - @beignet/core@0.0.3
+
+## 0.0.2
+
+- Initial Beignet React uploads integration.

package/README.md

@@ -0,0 +1,88 @@
+# @beignet/react-uploads
+
+React upload hooks for Beignet upload clients.
+
+## Install
+
+```bash
+bun add @beignet/react-uploads react
+```
+
+## Usage
+
+Create a typed upload client with `@beignet/core/uploads/client`, then wrap it
+once for React components:
+
+```typescript
+// client/uploads.ts
+import { createUploadClient } from "@beignet/core/uploads/client";
+import { createReactUploads } from "@beignet/react-uploads";
+import type { postUploads } from "@/features/posts/uploads";
+
+export type AppUploads = typeof postUploads;
+
+export const uploads = createUploadClient<AppUploads>({
+  baseUrl: "/api/uploads",
+});
+
+export const reactUploads = createReactUploads({
+  uploads,
+});
+```
+
+Use the hook in components:
+
+```tsx
+"use client";
+
+import { reactUploads } from "@/client/uploads";
+
+export function AttachmentPicker({ postSlug }: { postSlug: string }) {
+  const attachment = reactUploads.useUpload("posts.attachment");
+
+  return (
+    <input
+      type="file"
+      accept={attachment.accept}
+      disabled={attachment.isUploading}
+      onChange={(event) => {
+        const files = Array.from(event.currentTarget.files ?? []);
+        if (files.length === 0) return;
+
+        attachment.upload({
+          metadata: { postSlug },
+          files,
+        });
+      }}
+    />
+  );
+}
+```
+
+The hook exposes `status`, `progress`, `error`, `result`, `reset`, and `abort`.
+It keeps uploads imperative and does not hide React Query; invalidate queries in
+`onSuccess` when an upload changes visible app state.
+
+```typescript
+const attachment = reactUploads.useUpload("posts.attachment", {
+  onSuccess() {
+    queryClient.invalidateQueries({ queryKey: rq(getPost).key() });
+  },
+});
+```
+
+## API
+
+- `createReactUploads({ uploads })` creates an adapter bound to a typed upload
+  client.
+- `adapter.useUpload(name, options?)` returns state and methods for one upload
+  workflow.
+- `adapter.useUploadMany(name, options?)` returns the same state with an
+  `upload(files, options)` convenience method.
+
+## Related
+
+- [`@beignet/core/uploads`](https://beignet.dev/uploads) - upload definitions
+  and runtime router
+- [`@beignet/core/uploads/client`](https://beignet.dev/uploads) - typed browser
+  upload client

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+import type { CompleteUploadResult, InferUploadMetadata, InferUploadResult, UploadDef, UploadFileConstraints } from "@beignet/core/uploads";
+import type { UploadByName, UploadClient, UploadClientFileEvent, UploadClientName, UploadClientProgressEvent, UploadClientRegistry, UploadClientUploadOptions } from "@beignet/core/uploads/client";
+/**
+ * Upload status exposed by Beignet React upload hooks.
+ */
+export type ReactUploadStatus = "idle" | "preparing" | "uploading" | "completing" | "success" | "error";
+/**
+ * Per-file upload state tracked by React upload hooks.
+ */
+export interface ReactUploadFileState {
+    /**
+     * Browser file name.
+     */
+    fileName: string;
+    /**
+     * Zero-based file index from the caller's file array.
+     */
+    index: number;
+    /**
+     * Prepared upload id when available.
+     */
+    uploadId?: string;
+    /**
+     * Storage key when available.
+     */
+    key?: string;
+    /**
+     * Uploaded bytes reported by the browser or upload client.
+     */
+    loaded: number;
+    /**
+     * Total bytes expected for the file.
+     */
+    total: number;
+    /**
+     * Upload progress for this file from `0` to `100`.
+     */
+    progress: number;
+}
+/**
+ * State returned by Beignet React upload hooks.
+ */
+export interface ReactUploadState<Upload extends UploadDef> {
+    /**
+     * Current upload lifecycle status.
+     */
+    status: ReactUploadStatus;
+    /**
+     * Aggregate upload progress from `0` to `100`.
+     */
+    progress: number;
+    /**
+     * Aggregate upload progress from `0` to `1`.
+     */
+    progressFraction: number;
+    /**
+     * Latest error thrown by the upload client.
+     */
+    error: unknown | null;
+    /**
+     * Latest successful upload result.
+     */
+    result: CompleteUploadResult<InferUploadResult<Upload>> | null;
+    /**
+     * Per-file progress state for the active or latest upload.
+     */
+    files: readonly ReactUploadFileState[];
+}
+/**
+ * Lifecycle callbacks accepted by React upload hooks.
+ */
+export interface ReactUploadLifecycleOptions<Upload extends UploadDef> {
+    /**
+     * Called when a file is about to be uploaded.
+     */
+    onFileBegin?(event: UploadClientFileEvent): void;
+    /**
+     * Called when the upload client reports file progress.
+     */
+    onProgress?(event: UploadClientProgressEvent): void;
+    /**
+     * Called after the upload completes successfully.
+     */
+    onSuccess?(result: CompleteUploadResult<InferUploadResult<Upload>>): void | Promise<void>;
+    /**
+     * Called after the upload client throws.
+     */
+    onError?(error: unknown): void | Promise<void>;
+    /**
+     * Called after either success or failure.
+     */
+    onSettled?(result: CompleteUploadResult<InferUploadResult<Upload>> | undefined, error: unknown | undefined): void | Promise<void>;
+}
+/**
+ * Options shared by every upload started from one hook instance.
+ */
+export type ReactUploadHookOptions<Upload extends UploadDef> = Omit<UploadClientUploadOptions<Upload>, "metadata" | "files" | "onFileBegin" | "onProgress"> & ReactUploadLifecycleOptions<Upload>;
+/**
+ * Options for starting one upload from `useUpload(...)`.
+ */
+export type ReactUploadStartOptions<Upload extends UploadDef> = UploadClientUploadOptions<Upload> & ReactUploadLifecycleOptions<Upload>;
+/**
+ * Options for starting one upload from `useUploadMany(...)`.
+ */
+export type ReactUploadManyStartOptions<Upload extends UploadDef> = Omit<ReactUploadStartOptions<Upload>, "files">;
+/**
+ * Options for starting a single-file upload from `uploadFile(...)`.
+ */
+export type ReactUploadFileStartOptions<Upload extends UploadDef> = Omit<ReactUploadStartOptions<Upload>, "files">;
+/**
+ * React hook controller for one Beignet upload workflow.
+ */
+export interface ReactUploadController<Upload extends UploadDef> extends ReactUploadState<Upload> {
+    /**
+     * File input `accept` value derived from the upload manifest when available.
+     */
+    accept: string | undefined;
+    /**
+     * Client-safe file constraints derived from the upload manifest when available.
+     */
+    constraints: UploadFileConstraints | undefined;
+    /**
+     * True while a request is active.
+     */
+    isPending: boolean;
+    /**
+     * True while the hook has no active or completed upload.
+     */
+    isIdle: boolean;
+    /**
+     * True while files are being prepared, uploaded, or completed.
+     */
+    isUploading: boolean;
+    /**
+     * True after the last upload completed successfully.
+     */
+    isSuccess: boolean;
+    /**
+     * True after the last upload failed.
+     */
+    isError: boolean;
+    /**
+     * Start an upload through the wrapped upload client.
+     */
+    upload(options: ReactUploadStartOptions<Upload>): Promise<CompleteUploadResult<InferUploadResult<Upload>>>;
+    /**
+     * Convenience helper for uploading exactly one file.
+     */
+    uploadFile(file: File, options: ReactUploadFileStartOptions<Upload>): Promise<CompleteUploadResult<InferUploadResult<Upload>>>;
+    /**
+     * Abort the active upload request, when one exists.
+     */
+    abort(): void;
+    /**
+     * Clear hook state without changing files already stored by the server.
+     */
+    reset(): void;
+}
+/**
+ * React hook controller for many-file upload ergonomics.
+ */
+export interface ReactUploadManyController<Upload extends UploadDef> extends Omit<ReactUploadController<Upload>, "upload" | "uploadFile"> {
+    /**
+     * Start an upload with an explicit file array.
+     */
+    upload(files: readonly File[], options: ReactUploadManyStartOptions<Upload>): Promise<CompleteUploadResult<InferUploadResult<Upload>>>;
+}
+/**
+ * Options for `createReactUploads(...)`.
+ */
+export interface CreateReactUploadsOptions<Registry extends UploadClientRegistry> {
+    /**
+     * Typed Beignet upload client created by `createUploadClient(...)`.
+     */
+    uploads: UploadClient<Registry>;
+}
+/**
+ * React adapter bound to one typed Beignet upload client.
+ */
+export interface ReactUploadsAdapter<Registry extends UploadClientRegistry> {
+    /**
+     * Track state for one upload workflow.
+     */
+    useUpload<Name extends UploadClientName<Registry>>(uploadName: Name, options?: ReactUploadHookOptions<UploadByName<Registry, Name>>): ReactUploadController<UploadByName<Registry, Name>>;
+    /**
+     * Track state for one many-file upload workflow.
+     */
+    useUploadMany<Name extends UploadClientName<Registry>>(uploadName: Name, options?: ReactUploadHookOptions<UploadByName<Registry, Name>>): ReactUploadManyController<UploadByName<Registry, Name>>;
+}
+/**
+ * Create React hooks for a typed Beignet upload client.
+ */
+export declare function createReactUploads<Registry extends UploadClientRegistry>(options: CreateReactUploadsOptions<Registry>): ReactUploadsAdapter<Registry>;
+/**
+ * Infer upload metadata for a named upload in a registry.
+ */
+export type InferReactUploadMetadata<Registry extends UploadClientRegistry, Name extends UploadClientName<Registry>> = InferUploadMetadata<UploadByName<Registry, Name>>;
+/**
+ * Infer upload completion result for a named upload in a registry.
+ */
+export type InferReactUploadResult<Registry extends UploadClientRegistry, Name extends UploadClientName<Registry>> = InferUploadResult<UploadByName<Registry, Name>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,212 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+const INITIAL_STATE = {
+    status: "idle",
+    progress: 0,
+    progressFraction: 0,
+    error: null,
+    result: null,
+    files: [],
+};
+/**
+ * Create React hooks for a typed Beignet upload client.
+ */
+export function createReactUploads(options) {
+    const { uploads } = options;
+    function useUpload(uploadName, hookOptions = {}) {
+        const abortRef = useRef(null);
+        const progressRef = useRef(new Map());
+        const [state, setState] = useState(INITIAL_STATE);
+        const reset = useCallback(() => {
+            progressRef.current.clear();
+            setState(INITIAL_STATE);
+        }, []);
+        const abort = useCallback(() => {
+            abortRef.current?.abort();
+        }, []);
+        const upload = useCallback(async (startOptions) => {
+            abortRef.current?.abort();
+            const controller = new AbortController();
+            abortRef.current = controller;
+            const { onFileBegin: hookOnFileBegin, onProgress: hookOnProgress, onSuccess: hookOnSuccess, onError: hookOnError, onSettled: hookOnSettled, ...hookClientOptions } = hookOptions;
+            const { onFileBegin: startOnFileBegin, onProgress: startOnProgress, onSuccess: startOnSuccess, onError: startOnError, onSettled: startOnSettled, ...startClientOptions } = startOptions;
+            const isCurrentUpload = () => abortRef.current === controller;
+            const externalSignal = startClientOptions.signal ?? hookClientOptions.signal;
+            const abortFromExternalSignal = () => controller.abort();
+            if (externalSignal?.aborted) {
+                controller.abort();
+            }
+            else {
+                externalSignal?.addEventListener("abort", abortFromExternalSignal, {
+                    once: true,
+                });
+            }
+            progressRef.current.clear();
+            setState({
+                ...INITIAL_STATE,
+                status: "preparing",
+            });
+            let settledResult;
+            let settledError;
+            try {
+                const result = await uploads.upload(uploadName, {
+                    ...hookClientOptions,
+                    ...startClientOptions,
+                    signal: controller.signal,
+                    onFileBegin(event) {
+                        recordFileBegin(progressRef.current, event);
+                        if (isCurrentUpload()) {
+                            setState((current) => ({
+                                ...current,
+                                status: "uploading",
+                                files: currentFileState(progressRef.current),
+                            }));
+                        }
+                        hookOnFileBegin?.(event);
+                        startOnFileBegin?.(event);
+                    },
+                    onProgress(event) {
+                        recordFileProgress(progressRef.current, event);
+                        const aggregate = aggregateProgress(progressRef.current);
+                        if (isCurrentUpload()) {
+                            setState((current) => ({
+                                ...current,
+                                status: aggregate.progressFraction >= 1
+                                    ? "completing"
+                                    : "uploading",
+                                progress: aggregate.progress,
+                                progressFraction: aggregate.progressFraction,
+                                files: currentFileState(progressRef.current),
+                            }));
+                        }
+                        hookOnProgress?.(event);
+                        startOnProgress?.(event);
+                    },
+                });
+                settledResult = result;
+                await hookOnSuccess?.(settledResult);
+                await startOnSuccess?.(settledResult);
+                if (isCurrentUpload()) {
+                    setState((current) => ({
+                        ...current,
+                        status: "success",
+                        progress: 100,
+                        progressFraction: 1,
+                        error: null,
+                        result: settledResult ?? null,
+                    }));
+                }
+                return settledResult;
+            }
+            catch (error) {
+                settledError = error;
+                await hookOnError?.(error);
+                await startOnError?.(error);
+                if (isCurrentUpload()) {
+                    setState((current) => ({
+                        ...current,
+                        status: "error",
+                        error,
+                    }));
+                }
+                throw error;
+            }
+            finally {
+                externalSignal?.removeEventListener("abort", abortFromExternalSignal);
+                if (abortRef.current === controller) {
+                    abortRef.current = null;
+                }
+                await hookOnSettled?.(settledResult, settledError);
+                await startOnSettled?.(settledResult, settledError);
+            }
+        }, [hookOptions, uploadName]);
+        const uploadFile = useCallback((file, startOptions) => upload({
+            ...startOptions,
+            files: [file],
+        }), [upload]);
+        return useMemo(() => {
+            const isIdle = state.status === "idle";
+            const isSuccess = state.status === "success";
+            const isError = state.status === "error";
+            const isUploading = state.status === "preparing" ||
+                state.status === "uploading" ||
+                state.status === "completing";
+            return {
+                ...state,
+                accept: uploads.accept(uploadName),
+                constraints: uploads.constraints(uploadName),
+                isPending: isUploading,
+                isIdle,
+                isUploading,
+                isSuccess,
+                isError,
+                upload,
+                uploadFile,
+                abort,
+                reset,
+            };
+        }, [state, uploadName, upload, uploadFile, abort, reset]);
+    }
+    function useUploadMany(uploadName, hookOptions = {}) {
+        const controller = useUpload(uploadName, hookOptions);
+        const uploadMany = useCallback((files, startOptions) => controller.upload({
+            ...startOptions,
+            files,
+        }), [controller.upload]);
+        return useMemo(() => ({
+            ...controller,
+            upload: uploadMany,
+        }), [controller, uploadMany]);
+    }
+    return { useUpload, useUploadMany };
+}
+function recordFileBegin(progress, event) {
+    progress.set(event.index, {
+        fileName: event.fileName,
+        index: event.index,
+        uploadId: event.uploadId,
+        key: event.key,
+        loaded: 0,
+        total: event.file.size,
+    });
+}
+function recordFileProgress(progress, event) {
+    progress.set(event.index, {
+        fileName: event.fileName,
+        index: event.index,
+        uploadId: event.uploadId,
+        key: event.key,
+        loaded: event.loaded,
+        total: event.total,
+    });
+}
+function currentFileState(progress) {
+    return [...progress.values()]
+        .sort((a, b) => a.index - b.index)
+        .map((file) => ({
+        ...file,
+        progress: percent(file.loaded, file.total),
+    }));
+}
+function aggregateProgress(progress) {
+    const files = [...progress.values()];
+    if (files.length === 0) {
+        return { progress: 0, progressFraction: 0 };
+    }
+    const totals = files.reduce((acc, file) => ({
+        loaded: acc.loaded + file.loaded,
+        total: acc.total + file.total,
+    }), { loaded: 0, total: 0 });
+    const progressFraction = totals.total > 0
+        ? Math.min(1, totals.loaded / totals.total)
+        : Math.min(1, files.reduce((sum, file) => sum + percent(file.loaded, file.total) / 100, 0) / files.length);
+    return {
+        progress: Math.round(progressFraction * 100),
+        progressFraction,
+    };
+}
+function percent(loaded, total) {
+    if (total <= 0)
+        return loaded > 0 ? 100 : 0;
+    return Math.round(Math.min(1, loaded / total) * 100);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@beignet/react-uploads",
+  "version": "0.0.3",
+  "type": "module",
+  "description": "React upload hooks for Beignet upload clients",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "contract",
+    "api",
+    "typescript",
+    "react",
+    "uploads"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/react-uploads"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^9.3.4",
+    "@testing-library/react": "^14.3.1",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "@types/react": "^19.0.0",
+    "happy-dom": "^20.0.11",
+    "react": "^19.0.0",
+    "react-dom": "^19.2.5",
+    "typescript": "^5.3.0",
+    "zod": "^4.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,589 @@
+import type {
+  CompleteUploadResult,
+  InferUploadMetadata,
+  InferUploadResult,
+  UploadDef,
+  UploadFileConstraints,
+} from "@beignet/core/uploads";
+import type {
+  UploadByName,
+  UploadClient,
+  UploadClientFileEvent,
+  UploadClientName,
+  UploadClientProgressEvent,
+  UploadClientRegistry,
+  UploadClientUploadOptions,
+} from "@beignet/core/uploads/client";
+import { useCallback, useMemo, useRef, useState } from "react";
+
+/**
+ * Upload status exposed by Beignet React upload hooks.
+ */
+export type ReactUploadStatus =
+  | "idle"
+  | "preparing"
+  | "uploading"
+  | "completing"
+  | "success"
+  | "error";
+
+/**
+ * Per-file upload state tracked by React upload hooks.
+ */
+export interface ReactUploadFileState {
+  /**
+   * Browser file name.
+   */
+  fileName: string;
+  /**
+   * Zero-based file index from the caller's file array.
+   */
+  index: number;
+  /**
+   * Prepared upload id when available.
+   */
+  uploadId?: string;
+  /**
+   * Storage key when available.
+   */
+  key?: string;
+  /**
+   * Uploaded bytes reported by the browser or upload client.
+   */
+  loaded: number;
+  /**
+   * Total bytes expected for the file.
+   */
+  total: number;
+  /**
+   * Upload progress for this file from `0` to `100`.
+   */
+  progress: number;
+}
+
+/**
+ * State returned by Beignet React upload hooks.
+ */
+export interface ReactUploadState<Upload extends UploadDef> {
+  /**
+   * Current upload lifecycle status.
+   */
+  status: ReactUploadStatus;
+  /**
+   * Aggregate upload progress from `0` to `100`.
+   */
+  progress: number;
+  /**
+   * Aggregate upload progress from `0` to `1`.
+   */
+  progressFraction: number;
+  /**
+   * Latest error thrown by the upload client.
+   */
+  error: unknown | null;
+  /**
+   * Latest successful upload result.
+   */
+  result: CompleteUploadResult<InferUploadResult<Upload>> | null;
+  /**
+   * Per-file progress state for the active or latest upload.
+   */
+  files: readonly ReactUploadFileState[];
+}
+
+/**
+ * Lifecycle callbacks accepted by React upload hooks.
+ */
+export interface ReactUploadLifecycleOptions<Upload extends UploadDef> {
+  /**
+   * Called when a file is about to be uploaded.
+   */
+  onFileBegin?(event: UploadClientFileEvent): void;
+  /**
+   * Called when the upload client reports file progress.
+   */
+  onProgress?(event: UploadClientProgressEvent): void;
+  /**
+   * Called after the upload completes successfully.
+   */
+  onSuccess?(
+    result: CompleteUploadResult<InferUploadResult<Upload>>,
+  ): void | Promise<void>;
+  /**
+   * Called after the upload client throws.
+   */
+  onError?(error: unknown): void | Promise<void>;
+  /**
+   * Called after either success or failure.
+   */
+  onSettled?(
+    result: CompleteUploadResult<InferUploadResult<Upload>> | undefined,
+    error: unknown | undefined,
+  ): void | Promise<void>;
+}
+
+/**
+ * Options shared by every upload started from one hook instance.
+ */
+export type ReactUploadHookOptions<Upload extends UploadDef> = Omit<
+  UploadClientUploadOptions<Upload>,
+  "metadata" | "files" | "onFileBegin" | "onProgress"
+> &
+  ReactUploadLifecycleOptions<Upload>;
+
+/**
+ * Options for starting one upload from `useUpload(...)`.
+ */
+export type ReactUploadStartOptions<Upload extends UploadDef> =
+  UploadClientUploadOptions<Upload> & ReactUploadLifecycleOptions<Upload>;
+
+/**
+ * Options for starting one upload from `useUploadMany(...)`.
+ */
+export type ReactUploadManyStartOptions<Upload extends UploadDef> = Omit<
+  ReactUploadStartOptions<Upload>,
+  "files"
+>;
+
+/**
+ * Options for starting a single-file upload from `uploadFile(...)`.
+ */
+export type ReactUploadFileStartOptions<Upload extends UploadDef> = Omit<
+  ReactUploadStartOptions<Upload>,
+  "files"
+>;
+
+/**
+ * React hook controller for one Beignet upload workflow.
+ */
+export interface ReactUploadController<Upload extends UploadDef>
+  extends ReactUploadState<Upload> {
+  /**
+   * File input `accept` value derived from the upload manifest when available.
+   */
+  accept: string | undefined;
+  /**
+   * Client-safe file constraints derived from the upload manifest when available.
+   */
+  constraints: UploadFileConstraints | undefined;
+  /**
+   * True while a request is active.
+   */
+  isPending: boolean;
+  /**
+   * True while the hook has no active or completed upload.
+   */
+  isIdle: boolean;
+  /**
+   * True while files are being prepared, uploaded, or completed.
+   */
+  isUploading: boolean;
+  /**
+   * True after the last upload completed successfully.
+   */
+  isSuccess: boolean;
+  /**
+   * True after the last upload failed.
+   */
+  isError: boolean;
+  /**
+   * Start an upload through the wrapped upload client.
+   */
+  upload(
+    options: ReactUploadStartOptions<Upload>,
+  ): Promise<CompleteUploadResult<InferUploadResult<Upload>>>;
+  /**
+   * Convenience helper for uploading exactly one file.
+   */
+  uploadFile(
+    file: File,
+    options: ReactUploadFileStartOptions<Upload>,
+  ): Promise<CompleteUploadResult<InferUploadResult<Upload>>>;
+  /**
+   * Abort the active upload request, when one exists.
+   */
+  abort(): void;
+  /**
+   * Clear hook state without changing files already stored by the server.
+   */
+  reset(): void;
+}
+
+/**
+ * React hook controller for many-file upload ergonomics.
+ */
+export interface ReactUploadManyController<Upload extends UploadDef>
+  extends Omit<ReactUploadController<Upload>, "upload" | "uploadFile"> {
+  /**
+   * Start an upload with an explicit file array.
+   */
+  upload(
+    files: readonly File[],
+    options: ReactUploadManyStartOptions<Upload>,
+  ): Promise<CompleteUploadResult<InferUploadResult<Upload>>>;
+}
+
+/**
+ * Options for `createReactUploads(...)`.
+ */
+export interface CreateReactUploadsOptions<
+  Registry extends UploadClientRegistry,
+> {
+  /**
+   * Typed Beignet upload client created by `createUploadClient(...)`.
+   */
+  uploads: UploadClient<Registry>;
+}
+
+/**
+ * React adapter bound to one typed Beignet upload client.
+ */
+export interface ReactUploadsAdapter<Registry extends UploadClientRegistry> {
+  /**
+   * Track state for one upload workflow.
+   */
+  useUpload<Name extends UploadClientName<Registry>>(
+    uploadName: Name,
+    options?: ReactUploadHookOptions<UploadByName<Registry, Name>>,
+  ): ReactUploadController<UploadByName<Registry, Name>>;
+  /**
+   * Track state for one many-file upload workflow.
+   */
+  useUploadMany<Name extends UploadClientName<Registry>>(
+    uploadName: Name,
+    options?: ReactUploadHookOptions<UploadByName<Registry, Name>>,
+  ): ReactUploadManyController<UploadByName<Registry, Name>>;
+}
+
+type FileProgress = {
+  fileName: string;
+  index: number;
+  uploadId?: string;
+  key?: string;
+  loaded: number;
+  total: number;
+};
+
+const INITIAL_STATE = {
+  status: "idle",
+  progress: 0,
+  progressFraction: 0,
+  error: null,
+  result: null,
+  files: [],
+} satisfies ReactUploadState<UploadDef>;
+
+/**
+ * Create React hooks for a typed Beignet upload client.
+ */
+export function createReactUploads<Registry extends UploadClientRegistry>(
+  options: CreateReactUploadsOptions<Registry>,
+): ReactUploadsAdapter<Registry> {
+  const { uploads } = options;
+
+  function useUpload<Name extends UploadClientName<Registry>>(
+    uploadName: Name,
+    hookOptions: ReactUploadHookOptions<UploadByName<Registry, Name>> = {},
+  ): ReactUploadController<UploadByName<Registry, Name>> {
+    type Upload = UploadByName<Registry, Name>;
+    type Result = CompleteUploadResult<InferUploadResult<Upload>>;
+
+    const abortRef = useRef<AbortController | null>(null);
+    const progressRef = useRef(new Map<number, FileProgress>());
+    const [state, setState] = useState<ReactUploadState<Upload>>(
+      INITIAL_STATE as ReactUploadState<Upload>,
+    );
+
+    const reset = useCallback(() => {
+      progressRef.current.clear();
+      setState(INITIAL_STATE as ReactUploadState<Upload>);
+    }, []);
+
+    const abort = useCallback(() => {
+      abortRef.current?.abort();
+    }, []);
+
+    const upload = useCallback(
+      async (
+        startOptions: ReactUploadStartOptions<Upload>,
+      ): Promise<Result> => {
+        abortRef.current?.abort();
+        const controller = new AbortController();
+        abortRef.current = controller;
+
+        const {
+          onFileBegin: hookOnFileBegin,
+          onProgress: hookOnProgress,
+          onSuccess: hookOnSuccess,
+          onError: hookOnError,
+          onSettled: hookOnSettled,
+          ...hookClientOptions
+        } = hookOptions;
+        const {
+          onFileBegin: startOnFileBegin,
+          onProgress: startOnProgress,
+          onSuccess: startOnSuccess,
+          onError: startOnError,
+          onSettled: startOnSettled,
+          ...startClientOptions
+        } = startOptions;
+
+        const isCurrentUpload = () => abortRef.current === controller;
+        const externalSignal =
+          startClientOptions.signal ?? hookClientOptions.signal;
+        const abortFromExternalSignal = () => controller.abort();
+        if (externalSignal?.aborted) {
+          controller.abort();
+        } else {
+          externalSignal?.addEventListener("abort", abortFromExternalSignal, {
+            once: true,
+          });
+        }
+
+        progressRef.current.clear();
+        setState({
+          ...(INITIAL_STATE as ReactUploadState<Upload>),
+          status: "preparing",
+        });
+
+        let settledResult: Result | undefined;
+        let settledError: unknown;
+
+        try {
+          const result = await uploads.upload(uploadName, {
+            ...hookClientOptions,
+            ...startClientOptions,
+            signal: controller.signal,
+            onFileBegin(event) {
+              recordFileBegin(progressRef.current, event);
+              if (isCurrentUpload()) {
+                setState((current) => ({
+                  ...current,
+                  status: "uploading",
+                  files: currentFileState(progressRef.current),
+                }));
+              }
+              hookOnFileBegin?.(event);
+              startOnFileBegin?.(event);
+            },
+            onProgress(event) {
+              recordFileProgress(progressRef.current, event);
+              const aggregate = aggregateProgress(progressRef.current);
+              if (isCurrentUpload()) {
+                setState((current) => ({
+                  ...current,
+                  status:
+                    aggregate.progressFraction >= 1
+                      ? "completing"
+                      : "uploading",
+                  progress: aggregate.progress,
+                  progressFraction: aggregate.progressFraction,
+                  files: currentFileState(progressRef.current),
+                }));
+              }
+              hookOnProgress?.(event);
+              startOnProgress?.(event);
+            },
+          });
+
+          settledResult = result as Result;
+          await hookOnSuccess?.(settledResult);
+          await startOnSuccess?.(settledResult);
+          if (isCurrentUpload()) {
+            setState((current) => ({
+              ...current,
+              status: "success",
+              progress: 100,
+              progressFraction: 1,
+              error: null,
+              result: settledResult ?? null,
+            }));
+          }
+          return settledResult;
+        } catch (error) {
+          settledError = error;
+          await hookOnError?.(error);
+          await startOnError?.(error);
+          if (isCurrentUpload()) {
+            setState((current) => ({
+              ...current,
+              status: "error",
+              error,
+            }));
+          }
+          throw error;
+        } finally {
+          externalSignal?.removeEventListener("abort", abortFromExternalSignal);
+          if (abortRef.current === controller) {
+            abortRef.current = null;
+          }
+          await hookOnSettled?.(settledResult, settledError);
+          await startOnSettled?.(settledResult, settledError);
+        }
+      },
+      [hookOptions, uploadName],
+    );
+
+    const uploadFile = useCallback(
+      (
+        file: File,
+        startOptions: ReactUploadFileStartOptions<Upload>,
+      ): Promise<Result> =>
+        upload({
+          ...startOptions,
+          files: [file],
+        }),
+      [upload],
+    );
+
+    return useMemo(() => {
+      const isIdle = state.status === "idle";
+      const isSuccess = state.status === "success";
+      const isError = state.status === "error";
+      const isUploading =
+        state.status === "preparing" ||
+        state.status === "uploading" ||
+        state.status === "completing";
+
+      return {
+        ...state,
+        accept: uploads.accept(uploadName),
+        constraints: uploads.constraints(uploadName),
+        isPending: isUploading,
+        isIdle,
+        isUploading,
+        isSuccess,
+        isError,
+        upload,
+        uploadFile,
+        abort,
+        reset,
+      };
+    }, [state, uploadName, upload, uploadFile, abort, reset]);
+  }
+
+  function useUploadMany<Name extends UploadClientName<Registry>>(
+    uploadName: Name,
+    hookOptions: ReactUploadHookOptions<UploadByName<Registry, Name>> = {},
+  ): ReactUploadManyController<UploadByName<Registry, Name>> {
+    type Upload = UploadByName<Registry, Name>;
+    type Result = CompleteUploadResult<InferUploadResult<Upload>>;
+
+    const controller = useUpload(uploadName, hookOptions);
+    const uploadMany = useCallback(
+      (
+        files: readonly File[],
+        startOptions: ReactUploadManyStartOptions<Upload>,
+      ): Promise<Result> =>
+        controller.upload({
+          ...startOptions,
+          files,
+        }),
+      [controller.upload],
+    );
+
+    return useMemo(
+      () => ({
+        ...controller,
+        upload: uploadMany,
+      }),
+      [controller, uploadMany],
+    );
+  }
+
+  return { useUpload, useUploadMany };
+}
+
+function recordFileBegin(
+  progress: Map<number, FileProgress>,
+  event: UploadClientFileEvent,
+): void {
+  progress.set(event.index, {
+    fileName: event.fileName,
+    index: event.index,
+    uploadId: event.uploadId,
+    key: event.key,
+    loaded: 0,
+    total: event.file.size,
+  });
+}
+
+function recordFileProgress(
+  progress: Map<number, FileProgress>,
+  event: UploadClientProgressEvent,
+): void {
+  progress.set(event.index, {
+    fileName: event.fileName,
+    index: event.index,
+    uploadId: event.uploadId,
+    key: event.key,
+    loaded: event.loaded,
+    total: event.total,
+  });
+}
+
+function currentFileState(
+  progress: Map<number, FileProgress>,
+): ReactUploadFileState[] {
+  return [...progress.values()]
+    .sort((a, b) => a.index - b.index)
+    .map((file) => ({
+      ...file,
+      progress: percent(file.loaded, file.total),
+    }));
+}
+
+function aggregateProgress(progress: Map<number, FileProgress>): {
+  progress: number;
+  progressFraction: number;
+} {
+  const files = [...progress.values()];
+  if (files.length === 0) {
+    return { progress: 0, progressFraction: 0 };
+  }
+
+  const totals = files.reduce(
+    (acc, file) => ({
+      loaded: acc.loaded + file.loaded,
+      total: acc.total + file.total,
+    }),
+    { loaded: 0, total: 0 },
+  );
+
+  const progressFraction =
+    totals.total > 0
+      ? Math.min(1, totals.loaded / totals.total)
+      : Math.min(
+          1,
+          files.reduce(
+            (sum, file) => sum + percent(file.loaded, file.total) / 100,
+            0,
+          ) / files.length,
+        );
+
+  return {
+    progress: Math.round(progressFraction * 100),
+    progressFraction,
+  };
+}
+
+function percent(loaded: number, total: number): number {
+  if (total <= 0) return loaded > 0 ? 100 : 0;
+  return Math.round(Math.min(1, loaded / total) * 100);
+}
+
+/**
+ * Infer upload metadata for a named upload in a registry.
+ */
+export type InferReactUploadMetadata<
+  Registry extends UploadClientRegistry,
+  Name extends UploadClientName<Registry>,
+> = InferUploadMetadata<UploadByName<Registry, Name>>;
+
+/**
+ * Infer upload completion result for a named upload in a registry.
+ */
+export type InferReactUploadResult<
+  Registry extends UploadClientRegistry,
+  Name extends UploadClientName<Registry>,
+> = InferUploadResult<UploadByName<Registry, Name>>;