@tinvar/react 0.0.0-stage → 0.4.0

package/src/upload.js

@@ -0,0 +1,1240 @@
+'use client';
+
+// Uploads: a file sent to /_upload under the ticket a page issued, and the
+// reference that comes back put into the form, for the action to be called
+// with.
+//
+// tinvar-spec.md: "Uploaded files are referenced only by a server-issued
+// upload ticket bound to user, tenant, target model, key prefix and expiry.
+// Storage keys are server-generated; client filenames are metadata only."
+// So the file never goes with the form. The page's loader hands the form a
+// ticket for one action parameter; choosing a file sends it to /_upload at
+// once, with the ticket and the CSRF header, reporting progress; and what
+// /_upload answers -- an opaque reference -- is what the form posts under
+// the parameter's name. The action is held to everything the ticket bound
+// the upload to before its body sees it.
+//
+// <UploadField> renders the hidden input that carries the reference and
+// draws nothing else: the app draws the control, from the state it is
+// handed, in its own design system. useUpload() is the same state for a
+// form whose data React holds (useForm), where the app puts the reference
+// into its data itself. <UploadsField> and useUploads() are the same for a
+// parameter that takes several files (an UploadList): each file goes to
+// /_upload under the one ticket, and the form posts every reference.
+//
+// A page left open past its ticket's hour has the ticket issued again
+// (/_upload/refresh) the first time an upload under it is refused, and the
+// upload sent once more -- for the same session and user, and never past a
+// day from when the page first had it.
+//
+// `resumable` sends the file in pieces the server holds as they arrive
+// (resumable.js, ADR 0143): a dropped network is waited out and the upload
+// goes on by itself; and after a refresh, a closed tab or a crash the field
+// offers to go on from where the server is -- the person chooses the file
+// again, or, where the browser lets a file be reopened (the File System
+// Access API), only grants permission to read it.
+
+import { createElement, Fragment, useCallback, useEffect, useRef, useState } from 'react';
+import { useFormSession, useOptionalRouter } from './form.js';
+import { assignLocation, endSession } from './router-hooks.js';
+import { send } from './transport.js';
+import { defaultResumeStore } from './resume-store.js';
+import {
+  abortUpload,
+  askOffset,
+  fingerprintFile,
+  putToStore,
+  uploadResumable,
+  uploadScope,
+} from './resumable.js';
+
+export { abortUpload } from './resumable.js';
+export {
+  UPLOAD_ABORT_PATH,
+  UPLOAD_CHUNK_PATH,
+  UPLOAD_OFFSET_PATH,
+  UPLOAD_PARTS_PATH,
+  UPLOAD_SESSION_COMPLETE_PATH,
+  UPLOAD_SESSION_PATH,
+} from './resumable.js';
+export { indexedDbResumeStore, memoryResumeStore } from './resume-store.js';
+
+/** Where files go: the framework's upload endpoint. */
+export const UPLOAD_PATH = '/_upload';
+
+/** Where a ticket a page has outlived is issued again. */
+export const UPLOAD_REFRESH_PATH = '/_upload/refresh';
+
+/** Where a file to go straight to the object store is announced, for a URL to send it to. */
+export const UPLOAD_DIRECT_PATH = '/_upload/direct';
+
+/** Where a file sent straight to the store is said to be there, for PHP to check and keep. */
+export const UPLOAD_COMPLETE_PATH = '/_upload/complete';
+
+/** What /_upload calls the reference it answers with: the id it drew, as hex. */
+const REFERENCE = /^[a-f0-9]{32}$/;
+
+/**
+ * @typedef {import('./transport.js').Progress} Progress
+ *
+ * @typedef {{ upload: string, name: string, size: number, type: string }} Uploaded
+ *
+ * @typedef {'too_large' | 'type' | 'invalid' | 'refused' | 'signed_out' | 'throttled' | 'quota' | 'infected' | 'unavailable' | 'expired' | 'network' | 'failed'} UploadErrorKind
+ *
+ * @typedef {{
+ *   kind: UploadErrorKind,
+ *   status: number,
+ *   code: string | null,
+ *   reference: string | null,
+ *   retryAfter: number | null,
+ * }} UploadError
+ *
+ * @typedef {(
+ *   | { type: 'uploaded', file: Uploaded }
+ *   | { type: 'error', error: UploadError }
+ *   | { type: 'cancelled' }
+ * )} UploadOutcome
+ *
+ * @typedef {{
+ *   ticket: string,
+ *   file: Blob,
+ *   url?: string,
+ *   maxBytes?: number,
+ *   signal?: AbortSignal,
+ *   onProgress?: (progress: Progress) => void,
+ *   refresh?: boolean,
+ *   refreshUrl?: string,
+ *   onTicket?: (ticket: string) => void,
+ *   direct?: boolean,
+ *   resumable?: boolean,
+ *   onState?: (state: 'uploading' | 'paused' | 'resuming') => void,
+ *   onSession?: (session: import('./resumable.js').ResumableSession) => void,
+ *   handle?: unknown,
+ *   resumeStore?: import('./resume-store.js').ResumeStore,
+ *   backoff?: number[],
+ * }} UploadOptions
+ */
+
+/**
+ * Sends one file to /_upload under a ticket.
+ *
+ * Never throws for an outcome. Each refusal has a kind the app can say
+ * something specific about -- too large, not a type the field takes, a
+ * ticket that has run out -- and no kind ever carries the server's message,
+ * which is for its log.
+ *
+ * `maxBytes`, when given, refuses a file larger than it without sending
+ * it: the server holds the real limit, and this only spares the customer a
+ * wait for an answer that can only be no.
+ *
+ * `direct` sends the file straight to the application's object store
+ * rather than through PHP: /_upload/direct answers with a URL presigned for
+ * its size and the headers to send, the file is PUT there with progress,
+ * and /_upload/complete has PHP fetch it back and keep it as /_upload
+ * would -- or refuse it. The outcome is the same either way. The bucket
+ * must allow this origin's PUT (CORS).
+ *
+ * `resumable` sends it as a resumable upload (ADR 0143): in chunks through
+ * PHP, or -- with `direct` -- in parts straight to the store, each piece
+ * only from where the server says it holds. A network that drops is waited
+ * out, `onState` told `paused` and then `resuming`; and the same file chosen
+ * again, after a refresh or a crash, goes on from where the server is. A
+ * server that takes no resumable upload of the kind asked has the file sent
+ * whole, as without it. `onSession` is told the session once it is known:
+ * a cancel through `signal` keeps it on the server, and a caller that gives
+ * the upload up for good gives the session up too (abortUpload()).
+ *
+ * @param {UploadOptions} options
+ * @returns {Promise<UploadOutcome>}
+ */
+export async function uploadFile({
+  ticket,
+  file,
+  url = UPLOAD_PATH,
+  maxBytes,
+  signal,
+  onProgress,
+  refresh = false,
+  refreshUrl = UPLOAD_REFRESH_PATH,
+  onTicket,
+  direct = false,
+  resumable = false,
+  onState,
+  onSession,
+  handle,
+  resumeStore,
+  backoff,
+}) {
+  if (typeof maxBytes === 'number' && file.size > maxBytes) {
+    return { type: 'error', error: failure('too_large', 413) };
+  }
+
+  const sendWhole = (/** @type {string} */ under) =>
+    direct
+      ? sendDirect(under, file, signal, onProgress)
+      : send({ url, data: { ticket: under, file }, signal, onUploadProgress: onProgress });
+  const sendUnder = async (/** @type {string} */ under) => {
+    if (!resumable) return sendWhole(under);
+    const sent = await uploadResumable({
+      ticket: under,
+      file,
+      direct,
+      signal,
+      onProgress,
+      onState,
+      onSession,
+      handle,
+      store: resumeStore,
+      ...(backoff === undefined ? {} : { backoff }),
+    });
+    return sent.type === 'unsupported' ? sendWhole(under) : sent;
+  };
+
+  let outcome = await sendUnder(ticket);
+
+  // Refused: most likely a ticket the page has outlived. Asked for again
+  // once, and the file sent once more under it; a refresh refused is the
+  // first refusal, and the page has to be loaded again.
+  if (refresh && outcome.type === 'http' && outcome.status === 403) {
+    const renewed = await refreshTicket({ ticket, url: refreshUrl, signal });
+    if (renewed.type === 'refreshed') {
+      onTicket?.(renewed.ticket);
+      outcome = await sendUnder(renewed.ticket);
+    }
+  }
+
+  return outcomeOf(outcome);
+}
+
+/**
+ * What an upload's last answer means for the app: the file, or a refusal of
+ * a kind it can say something about.
+ *
+ * @param {import('./transport.js').Outcome} outcome
+ * @returns {UploadOutcome}
+ */
+function outcomeOf(outcome) {
+  switch (outcome.type) {
+    case 'success': {
+      const body = outcome.body;
+      const uploaded =
+        body !== null &&
+        typeof body === 'object' &&
+        typeof body.upload === 'string' &&
+        REFERENCE.test(body.upload) &&
+        typeof body.name === 'string' &&
+        typeof body.size === 'number' &&
+        typeof body.type === 'string';
+      return uploaded
+        ? {
+            type: 'uploaded',
+            file: { upload: body.upload, name: body.name, size: body.size, type: body.type },
+          }
+        : { type: 'error', error: failure('failed', outcome.status) };
+    }
+    case 'validation':
+      // A scanner's find is a 422 too, told apart by its code.
+      return outcome.body?.error?.code === 'upload_infected'
+        ? { type: 'error', error: failure('infected', 422, 'upload_infected') }
+        : { type: 'error', error: failure('invalid', 422) };
+    case 'http':
+      return {
+        type: 'error',
+        error: failure(
+          kindOf(outcome.status),
+          outcome.status,
+          outcome.code,
+          outcome.reference,
+          outcome.retryAfter,
+        ),
+      };
+    case 'expired':
+      return { type: 'error', error: failure('expired', 419) };
+    case 'network':
+      return { type: 'error', error: failure('network', 0) };
+    case 'cancelled':
+      return { type: 'cancelled' };
+    default:
+      // A redirect, which /_upload never answers with.
+      return { type: 'error', error: failure('failed', 0) };
+  }
+}
+
+/**
+ * A file sent straight to the object store, in three steps, answered as
+ * /_upload answers: the intent and the presigned URL from /_upload/direct;
+ * the PUT, with the headers it was signed with and nothing of this origin's
+ * -- no cookie, no CSRF header; and /_upload/complete, which answers with
+ * the reference, or the refusal /_upload would have given.
+ *
+ * @param {string} ticket
+ * @param {Blob} file
+ * @param {AbortSignal | undefined} signal
+ * @param {((progress: Progress) => void) | undefined} onProgress
+ * @returns {Promise<import('./transport.js').Outcome>}
+ */
+async function sendDirect(ticket, file, signal, onProgress) {
+  const name = typeof (/** @type {any} */ (file).name) === 'string' ? /** @type {any} */ (file).name : '';
+  const begun = await send({ url: UPLOAD_DIRECT_PATH, data: { ticket, size: file.size, name }, signal });
+  if (begun.type !== 'success') return begun;
+
+  const body = begun.body;
+  if (
+    body === null ||
+    typeof body !== 'object' ||
+    typeof body.intent !== 'string' ||
+    !REFERENCE.test(body.intent) ||
+    typeof body.url !== 'string' ||
+    body.headers === null ||
+    typeof body.headers !== 'object'
+  ) {
+    return {
+      type: 'http',
+      status: 0,
+      body: null,
+      headers: new Headers(),
+      code: null,
+      reference: null,
+      retryAfter: null,
+    };
+  }
+
+  const put = await putToStore(body.url, body.headers, file, signal, onProgress);
+  if (put.type !== 'sent') return put;
+
+  return send({ url: UPLOAD_COMPLETE_PATH, data: { ticket, intent: body.intent }, signal });
+}
+
+/**
+ * Asks for a ticket the page holds to be issued again: for the same
+ * session, user, action and record, for another hour, and never past a day
+ * from its first issue. Never throws for an outcome.
+ *
+ * @param {{ ticket: string, url?: string, signal?: AbortSignal }} options
+ * @returns {Promise<{ type: 'refreshed', ticket: string, expiresAt: number } | { type: 'error', error: UploadError } | { type: 'cancelled' }>}
+ */
+export async function refreshTicket({ ticket, url = UPLOAD_REFRESH_PATH, signal }) {
+  const outcome = await send({ url, data: { ticket }, signal });
+  if (outcome.type === 'cancelled') return { type: 'cancelled' };
+  if (outcome.type === 'success') {
+    const body = outcome.body;
+    if (
+      body !== null &&
+      typeof body === 'object' &&
+      typeof body.ticket === 'string' &&
+      typeof body.expiresAt === 'number'
+    ) {
+      return { type: 'refreshed', ticket: body.ticket, expiresAt: body.expiresAt };
+    }
+    return { type: 'error', error: failure('failed', outcome.status) };
+  }
+  if (outcome.type === 'http') {
+    return {
+      type: 'error',
+      error: failure(
+        kindOf(outcome.status),
+        outcome.status,
+        outcome.code,
+        outcome.reference,
+        outcome.retryAfter,
+      ),
+    };
+  }
+  return { type: 'error', error: failure(outcome.type === 'network' ? 'network' : 'failed', 0) };
+}
+
+/** @param {number} status @returns {UploadErrorKind} */
+function kindOf(status) {
+  switch (status) {
+    case 401:
+      return 'signed_out';
+    case 403:
+      return 'refused';
+    case 413:
+      return 'too_large';
+    case 415:
+      return 'type';
+    case 429:
+      return 'throttled';
+    case 507:
+      return 'quota';
+    case 503:
+      return 'unavailable';
+    default:
+      return 'failed';
+  }
+}
+
+/**
+ * @param {UploadErrorKind} kind
+ * @param {number} status
+ * @returns {UploadError}
+ */
+function failure(kind, status, code = null, reference = null, retryAfter = null) {
+  return { kind, status, code, reference, retryAfter };
+}
+
+/**
+ * @typedef {'idle' | 'uploading' | 'paused' | 'resuming' | 'uploaded' | 'error'} UploadStatus
+ *
+ * @typedef {{
+ *   ticket: string,
+ *   url?: string,
+ *   maxBytes?: number,
+ *   onUploaded?: (file: Uploaded) => void,
+ *   onError?: (error: UploadError) => void,
+ *   direct?: boolean,
+ *   resumable?: boolean,
+ *   resumeStore?: import('./resume-store.js').ResumeStore,
+ *   backoff?: number[],
+ * }} UseUploadOptions
+ *
+ * @typedef {{
+ *   name: string,
+ *   size: number,
+ *   offset: number,
+ *   percentage: number,
+ *   reopenable: boolean,
+ * }} PendingUpload
+ */
+
+/**
+ * One upload's state, for a field that takes one file.
+ *
+ * A second file chosen while the first is still going cancels the first:
+ * the reference that counts is the one for the file chosen last. Leaving
+ * the page cancels it too.
+ *
+ * `onUploaded` runs once the reference is in state -- after the render that
+ * puts it there -- so a form submitted from it sends the new reference,
+ * not the one before.
+ *
+ * A 401 means the session is over: what the page holds belongs to it, and
+ * the page is loaded again, as every form's 401 does.
+ *
+ * With `resumable`, `status` is also `paused` while a dropped network is
+ * waited out, and `resuming` while the server is asked where to go on; and
+ * once the field is drawn, `pending` is an upload of this field the server
+ * still holds part of -- begun before a refresh, a closed tab or a crash --
+ * for the app to offer to go on with (`resume()`) or give up
+ * (`discardPending()`). A browser cannot read a file again without the
+ * person: `resume()` reopens it where the File System Access API kept a
+ * handle to it, asking only for permission, and otherwise answers null, for
+ * the person to choose it again -- the same file goes on from where the
+ * server is; another starts over.
+ *
+ * @param {UseUploadOptions} options
+ */
+export function useUpload({
+  ticket,
+  url,
+  maxBytes,
+  onUploaded,
+  onError,
+  direct,
+  resumable = false,
+  resumeStore,
+  backoff,
+}) {
+  const router = useOptionalRouter();
+  const session = useFormSession();
+  const [status, setStatus] = useState(/** @type {UploadStatus} */ ('idle'));
+  const [progress, setProgress] = useState(/** @type {Progress | null} */ (null));
+  const [file, setFile] = useState(/** @type {Uploaded | null} */ (null));
+  const [error, setError] = useState(/** @type {UploadError | null} */ (null));
+  const [pending, setPending] = useState(/** @type {PendingUpload | null} */ (null));
+  const pendingRecord = useRef(/** @type {import('./resume-store.js').ResumeRecord | null} */ (null));
+  const inFlight = useRef(/** @type {Job | null} */ (null));
+  // The last upload that ended keeping its session on the server -- given
+  // up on the network, say -- for a reset or another file to give up.
+  const kept = useRef(/** @type {Job | null} */ (null));
+  // How many files have been chosen here: one chosen while the server was
+  // asked about a waiting upload is what the field holds, not that one.
+  const choices = useRef(0);
+
+  // The latest callbacks and options, for an upload started under older ones.
+  const latest = useRef({
+    ticket,
+    url,
+    maxBytes,
+    onUploaded,
+    onError,
+    direct,
+    resumable,
+    resumeStore,
+    backoff,
+  });
+  latest.current = { ticket, url, maxBytes, onUploaded, onError, direct, resumable, resumeStore, backoff };
+  const renewed = useRenewedTicket(ticket);
+
+  // Leaving the page cancels the upload but keeps its session: the next
+  // page offers to go on with it.
+  useEffect(() => () => inFlight.current?.controller.abort(), []);
+
+  // An upload of this field the server still holds part of, offered once
+  // the field is drawn: the newest one for what this ticket is for, asked
+  // of the server first -- one it has let go of, or that is another
+  // session's or user's, is forgotten without a word.
+  const scope = resumable ? uploadScope(ticket) : null;
+  useEffect(() => {
+    if (scope === null) return undefined;
+    let live = true;
+    const store = latest.current.resumeStore ?? defaultResumeStore();
+    const choicesBefore = choices.current;
+    void (async () => {
+      let records = [];
+      try {
+        records = await store.inScope(scope);
+      } catch {
+        records = [];
+      }
+      for (const record of records) {
+        const asked = await askOffset(record.session);
+        if (!live || choices.current !== choicesBefore) return;
+        if (asked.type === 'gone') {
+          await store.delete(record.id).catch(() => {});
+          continue;
+        }
+        const offset =
+          asked.type === 'open' ? asked.offset : asked.type === 'completed' ? record.size : record.offset;
+        pendingRecord.current = record;
+        setPending({
+          name: record.name,
+          size: record.size,
+          offset,
+          percentage: record.size > 0 ? Math.floor((offset / record.size) * 100) : 0,
+          reopenable: typeof (/** @type {any} */ (record.handle)?.getFile) === 'function',
+        });
+        return;
+      }
+    })();
+    return () => {
+      live = false;
+    };
+  }, [scope]);
+
+  // Told once per upload, after it has rendered.
+  const told = useRef(/** @type {Uploaded | null} */ (null));
+  useEffect(() => {
+    if (file !== null && told.current !== file) {
+      told.current = file;
+      latest.current.onUploaded?.(file);
+    }
+  }, [file]);
+
+  const upload = useCallback(
+    async (/** @type {Blob} */ chosen, /** @type {{ handle?: unknown }} */ { handle } = {}) => {
+      choices.current++;
+      const options = latest.current;
+      const fingerprint = options.resumable ? fingerprintFile(chosen) : null;
+      // This field takes one file: the one it replaces is given up, its
+      // session too -- unless it is the same file, which goes on in it.
+      const replaced = inFlight.current ?? kept.current;
+      kept.current = null;
+      if (replaced !== null) {
+        giveUp(
+          replaced,
+          (async () =>
+            replaced.fingerprint === null || (await replaced.fingerprint) !== (await fingerprint))(),
+          options.resumeStore,
+        );
+      }
+      const controller = new AbortController();
+      /** @type {Job} */
+      const job = { controller, fingerprint, session: null, discard: false, done: false };
+      inFlight.current = job;
+      const current = () => inFlight.current === job;
+
+      setStatus('uploading');
+      setProgress(null);
+      setFile(null);
+      setError(null);
+
+      // Another file than the one waiting to be gone on with: this field
+      // takes one, so the one waiting is given up, and its room with it.
+      const waiting = pendingRecord.current;
+      if (waiting !== null) {
+        pendingRecord.current = null;
+        setPending(null);
+        if (options.resumable && (await fingerprint) !== waiting.fingerprint) {
+          void discardRecord(waiting, options.resumeStore);
+        }
+      }
+
+      const outcome = await uploadFile({
+        ticket: renewed.current.ticket,
+        file: chosen,
+        url: options.url,
+        maxBytes: options.maxBytes,
+        direct: options.direct,
+        resumable: options.resumable,
+        resumeStore: options.resumeStore,
+        handle,
+        ...(options.backoff === undefined ? {} : { backoff: options.backoff }),
+        signal: controller.signal,
+        onProgress: (p) => {
+          if (current()) setProgress(p);
+        },
+        onState: (state) => {
+          if (current()) setStatus(state);
+        },
+        onSession: (held) => {
+          job.session = held;
+        },
+        refresh: true,
+        onTicket: (next) => {
+          renewed.current.ticket = next;
+        },
+      });
+
+      // Cancelled for good -- not by the field going away -- so the server
+      // need hold nothing more of it.
+      job.done = true;
+      if (outcome.type === 'cancelled' && job.session !== null && (await job.discard)) {
+        void discardRecord(job.session, options.resumeStore);
+        job.session = null;
+      }
+
+      // Superseded, or the field went away: the later upload owns the state.
+      if (!current()) return outcome;
+      inFlight.current = null;
+      // Ended with its session still on the server: the next file, or a reset, gives it up.
+      if (outcome.type === 'error' && job.session !== null) kept.current = job;
+      setProgress(null);
+
+      if (outcome.type === 'uploaded') {
+        setFile(outcome.file);
+        setStatus('uploaded');
+      } else if (outcome.type === 'error') {
+        setError(outcome.error);
+        setStatus('error');
+        latest.current.onError?.(outcome.error);
+        if (outcome.error.kind === 'signed_out') endSession(router, session?.hardNavigate ?? assignLocation);
+      } else {
+        setStatus('idle');
+      }
+
+      return outcome;
+    },
+    [router, session, renewed],
+  );
+
+  const cancel = useCallback(() => {
+    if (inFlight.current !== null) giveUp(inFlight.current, true, latest.current.resumeStore);
+  }, []);
+
+  const reset = useCallback(() => {
+    const job = inFlight.current ?? kept.current;
+    if (job !== null) giveUp(job, true, latest.current.resumeStore);
+    inFlight.current = null;
+    kept.current = null;
+    setStatus('idle');
+    setProgress(null);
+    setFile(null);
+    setError(null);
+  }, []);
+
+  const resume = useCallback(async () => {
+    const record = pendingRecord.current;
+    if (record === null) return null;
+
+    // Whole on the server already -- the last piece went in as the page
+    // went away -- so there is nothing to send, and no file to ask for.
+    if (pending !== null && pending.offset >= pending.size) {
+      const asked = await askOffset(record.session);
+      if (asked.type === 'completed') {
+        pendingRecord.current = null;
+        setPending(null);
+        await (latest.current.resumeStore ?? defaultResumeStore()).delete(record.id).catch(() => {});
+        const outcome = outcomeOf(asked.outcome);
+        if (outcome.type === 'uploaded') {
+          setFile(outcome.file);
+          setStatus('uploaded');
+        }
+        return outcome;
+      }
+    }
+
+    // A file the browser kept a handle to: read again once the person
+    // grants it, which needs this to run from their click.
+    const handle = /** @type {any} */ (record.handle);
+    if (handle && typeof handle.getFile === 'function') {
+      try {
+        let permission =
+          typeof handle.queryPermission === 'function'
+            ? await handle.queryPermission({ mode: 'read' })
+            : 'granted';
+        if (permission !== 'granted' && typeof handle.requestPermission === 'function') {
+          permission = await handle.requestPermission({ mode: 'read' });
+        }
+        if (permission === 'granted') return upload(await handle.getFile(), { handle });
+      } catch {
+        // Moved, deleted or refused: the person chooses it again.
+      }
+    }
+    return null;
+  }, [pending, upload]);
+
+  const discardPending = useCallback(async () => {
+    const record = pendingRecord.current;
+    pendingRecord.current = null;
+    setPending(null);
+    if (record !== null) await discardRecord(record, latest.current.resumeStore);
+  }, []);
+
+  return {
+    status,
+    uploading: status === 'uploading' || status === 'paused' || status === 'resuming',
+    paused: status === 'paused',
+    resuming: status === 'resuming',
+    progress,
+    file,
+    error,
+    /** What the form sends under the parameter's name: the reference, or null before one. */
+    reference: file?.upload ?? null,
+    pending,
+    upload,
+    resume,
+    discardPending,
+    cancel,
+    reset,
+  };
+}
+
+/**
+ * One upload of a single-file field: what cancels it, the fingerprint of
+ * its file (resumable only), the session it goes on in once known, and
+ * whether that session is to be given up once it has stopped -- false when
+ * the field merely went away.
+ *
+ * @typedef {{
+ *   controller: AbortController,
+ *   fingerprint: Promise<string | null> | null,
+ *   session: import('./resumable.js').ResumableSession | null,
+ *   discard: boolean | Promise<boolean>,
+ *   done: boolean,
+ * }} Job
+ */
+
+/**
+ * Gives an upload up: cancelled if it is still going -- its session given up
+ * once it has stopped, when $discard says so -- or, ended keeping its
+ * session, that session given up now.
+ *
+ * @param {Job} job
+ * @param {boolean | Promise<boolean>} discard
+ * @param {import('./resume-store.js').ResumeStore | undefined} store
+ */
+function giveUp(job, discard, store) {
+  job.discard = discard;
+  if (!job.done) {
+    job.controller.abort();
+    return;
+  }
+  const session = job.session;
+  job.session = null;
+  if (session !== null) {
+    void (async () => {
+      if (await discard) await discardRecord(session, store);
+    })();
+  }
+}
+
+/**
+ * Gives up an upload a record remembers: on the server, its bytes removed
+ * and its room given back, and the record forgotten. Never throws.
+ *
+ * @param {{ session: string, id: string | null }} record
+ * @param {import('./resume-store.js').ResumeStore | undefined} store
+ */
+async function discardRecord(record, store) {
+  try {
+    await abortUpload(record.session);
+  } catch {
+    // Pruned once it runs out, whatever happens here.
+  }
+  if (record.id === null) return;
+  try {
+    await (store ?? defaultResumeStore()).delete(record.id);
+  } catch {
+    // Run out, it is not offered again.
+  }
+}
+
+/**
+ * A form field that uploads the file chosen in it, and posts the reference.
+ *
+ *     <Form action={updateAvatar}>
+ *       <UploadField name="avatar" ticket={data.avatarTicket}>
+ *         {(field) => (
+ *           <>
+ *             <input {...field.input} hidden />
+ *             <button type="button" onClick={field.choose}>Choose a picture</button>
+ *             {field.uploading && <progress value={field.progress?.percentage ?? 0} max={100} />}
+ *           </>
+ *         )}
+ *       </UploadField>
+ *     </Form>
+ *
+ * It renders a hidden input under `name`, holding the reference once the
+ * upload is in, and hands its children the upload's state with `input` --
+ * the props for a file input, which has no name, so the file itself is
+ * never part of the form -- and `choose()`, which opens it.
+ *
+ * Without script -- before it has loaded, or with none -- the file input
+ * carries `name` and the ticket rides beside it in `_upload_tickets[name]`,
+ * so a form with `encType="multipart/form-data"` posts the file to the
+ * action itself, which takes it as /_upload would (ADR 0127). Once script
+ * runs the input loses its name, and the file goes to /_upload first.
+ *
+ * With `resumable`, choosing a file opens the browser's own file picker
+ * where it has one that keeps a handle to the file (the File System Access
+ * API), so an upload interrupted by a refresh or a crash can go on at the
+ * cost of a permission prompt; `resume()` goes on with `pending`, opening
+ * the file input for the person to choose the file again where there is no
+ * handle.
+ *
+ * @param {UseUploadOptions & {
+ *   name: string,
+ *   accept?: string,
+ *   children?: (field: any) => unknown,
+ * }} props
+ */
+export function UploadField({
+  name,
+  ticket,
+  url,
+  maxBytes,
+  accept,
+  onUploaded,
+  onError,
+  direct,
+  resumable,
+  resumeStore,
+  backoff,
+  children,
+}) {
+  const state = useUpload({
+    ticket,
+    url,
+    maxBytes,
+    onUploaded,
+    onError,
+    direct,
+    resumable,
+    resumeStore,
+    backoff,
+  });
+  const [hydrated, setHydrated] = useState(false);
+  useEffect(() => setHydrated(true), []);
+  const inputRef = useRef(/** @type {HTMLInputElement | null} */ (null));
+  const { upload, reset: resetUpload, resume: resumeUpload } = state;
+
+  const onChange = useCallback(
+    (/** @type {{ currentTarget: HTMLInputElement }} */ event) => {
+      const chosen = event.currentTarget.files?.[0];
+      if (chosen) void upload(chosen);
+    },
+    [upload],
+  );
+
+  const choose = useCallback(() => {
+    const picker = resumable ? openFilePicker(accept) : null;
+    if (picker === null) {
+      inputRef.current?.click();
+      return;
+    }
+    void picker.then((picked) => {
+      if (picked === 'unavailable') inputRef.current?.click();
+      else if (picked !== null) void upload(picked.file, { handle: picked.handle });
+    });
+  }, [resumable, accept, upload]);
+
+  const resume = useCallback(async () => {
+    const outcome = await resumeUpload();
+    if (outcome === null) choose();
+    return outcome;
+  }, [resumeUpload, choose]);
+
+  const reset = useCallback(() => {
+    resetUpload();
+    if (inputRef.current) inputRef.current.value = '';
+  }, [resetUpload]);
+
+  const field = {
+    ...state,
+    reset,
+    choose,
+    resume,
+    // Whether script runs: until it does, the app shows the file input
+    // itself and a button that submits the form, which carries the file.
+    scripted: hydrated,
+    // Named only until script runs: posted by the browser itself, the file
+    // goes with the form; posted by script, never.
+    input: { ref: inputRef, type: 'file', accept, onChange, name: hydrated ? undefined : name },
+  };
+
+  return createElement(
+    Fragment,
+    null,
+    createElement('input', { type: 'hidden', name, value: state.reference ?? '' }),
+    // Only until script runs, as the input's name: script sends the reference alone.
+    hydrated
+      ? null
+      : createElement('input', { type: 'hidden', name: `_upload_tickets[${name}]`, value: ticket }),
+    typeof children === 'function' ? children(field) : null,
+  );
+}
+
+/**
+ * The browser's own file picker, where it has one that hands back a handle
+ * to the file (the File System Access API): the file and its handle, null
+ * when the person closed it, or `unavailable` for the file input instead.
+ * Null at once where there is no such picker.
+ *
+ * @param {string | undefined} accept
+ * @returns {Promise<{ file: File, handle: unknown } | null | 'unavailable'> | null}
+ */
+function openFilePicker(accept) {
+  const show = /** @type {any} */ (globalThis).showOpenFilePicker;
+  if (typeof show !== 'function') return null;
+  const types = (accept ?? '')
+    .split(',')
+    .map((type) => type.trim())
+    .filter((type) => /^[a-z]+\/[a-z0-9.+-]+$/i.test(type));
+  return (async () => {
+    try {
+      const [handle] = await show({
+        multiple: false,
+        ...(types.length === 0
+          ? {}
+          : {
+              types: [
+                {
+                  description: 'Files',
+                  accept: Object.fromEntries(types.map((t) => [t, EXTENSIONS[t] ?? []])),
+                },
+              ],
+            }),
+      });
+      return { file: await handle.getFile(), handle };
+    } catch (error) {
+      return /** @type {any} */ (error)?.name === 'AbortError' ? null : 'unavailable';
+    }
+  })();
+}
+
+/** @type {Record<string, string[]>} */
+const EXTENSIONS = {
+  'image/png': ['.png'],
+  'image/jpeg': ['.jpg', '.jpeg'],
+  'image/webp': ['.webp'],
+  'image/avif': ['.avif'],
+  'image/gif': ['.gif'],
+  'application/pdf': ['.pdf'],
+};
+
+/**
+ * The ticket an upload goes under: the page's, until a refresh issues it
+ * again -- and the page's once more if the page hands a new one.
+ *
+ * @param {string} ticket
+ */
+function useRenewedTicket(ticket) {
+  const held = useRef({ given: ticket, ticket });
+  if (held.current.given !== ticket) held.current = { given: ticket, ticket };
+  return held;
+}
+
+/**
+ * @typedef {{
+ *   key: number,
+ *   status: UploadStatus,
+ *   progress: Progress | null,
+ *   file: Uploaded | null,
+ *   error: UploadError | null,
+ * }} UploadEntry
+ */
+
+/**
+ * The state of a parameter that takes several files (an UploadList): each
+ * file chosen is sent to /_upload under the one ticket, one after another,
+ * and `references` is every one that went in, in the order chosen.
+ *
+ * `maxFiles` refuses files past it without sending them, as `maxBytes`
+ * does a large one: the server holds the real limit.
+ *
+ * `remove()` cancels a file still going, and a file still queued is never
+ * sent; `reset()`, or the field going away, cancels the one going and sends
+ * none of those queued behind it. With `resumable`, `remove()` and
+ * `reset()` give up on the server the session of a file they cancel, or of
+ * one that ended keeping it; the field going away keeps it, so the same file
+ * chosen again goes on from where the server is.
+ *
+ * @param {UseUploadOptions & { maxFiles?: number }} options
+ */
+export function useUploads({
+  ticket,
+  url,
+  maxBytes,
+  maxFiles,
+  onUploaded,
+  onError,
+  direct,
+  resumable,
+  resumeStore,
+  backoff,
+}) {
+  const router = useOptionalRouter();
+  const session = useFormSession();
+  const [entries, setEntries] = useState(/** @type {UploadEntry[]} */ ([]));
+  const renewed = useRenewedTicket(ticket);
+  const controllers = useRef(/** @type {Map<number, AbortController>} */ (new Map()));
+  const nextKey = useRef(0);
+  const latest = useRef({
+    url,
+    maxBytes,
+    maxFiles,
+    onUploaded,
+    onError,
+    direct,
+    resumable,
+    resumeStore,
+    backoff,
+  });
+  latest.current = { url, maxBytes, maxFiles, onUploaded, onError, direct, resumable, resumeStore, backoff };
+  const count = useRef(0);
+  count.current = entries.length;
+  // The keys still wanted: a file removed, or every file on a reset, is
+  // dropped from here, and a batch sends none it no longer finds.
+  const wanted = useRef(/** @type {Set<number>} */ (new Set()));
+  // One per batch still going: a reset or the field going away stops each
+  // from sending the files it has queued.
+  const batches = useRef(/** @type {Set<AbortController>} */ (new Set()));
+  // The session each resumable file goes on in, while it goes, and after it
+  // ends in an error that keeps it on the server; and the files given up
+  // for good while they went, whose sessions go once they have stopped.
+  const sessions = useRef(/** @type {Map<number, import('./resumable.js').ResumableSession>} */ (new Map()));
+  const discarding = useRef(/** @type {Set<number>} */ (new Set()));
+
+  useEffect(
+    () => () => {
+      batches.current.forEach((b) => b.abort());
+      controllers.current.forEach((c) => c.abort());
+    },
+    [],
+  );
+
+  const patch = useCallback((/** @type {number} */ key, /** @type {Partial<UploadEntry>} */ change) => {
+    setEntries((all) => all.map((e) => (e.key === key ? { ...e, ...change } : e)));
+  }, []);
+
+  const upload = useCallback(
+    async (/** @type {Iterable<Blob>} */ chosen) => {
+      const files = Array.from(chosen);
+      const room =
+        typeof latest.current.maxFiles === 'number'
+          ? Math.max(0, latest.current.maxFiles - count.current)
+          : files.length;
+      const taken = files.slice(0, room);
+      const added = taken.map(() => ({
+        key: nextKey.current++,
+        status: /** @type {UploadStatus} */ ('uploading'),
+        progress: null,
+        file: null,
+        error: null,
+      }));
+      count.current += added.length;
+      for (const { key } of added) wanted.current.add(key);
+      setEntries((all) => [...all, ...added]);
+      const batch = new AbortController();
+      batches.current.add(batch);
+
+      /** @type {UploadOutcome[]} */
+      const outcomes = [];
+      for (let i = 0; i < taken.length; i++) {
+        const { key } = added[i];
+        // Reset, or the field gone: the rest are never sent. Removed: this one is not.
+        if (batch.signal.aborted || !wanted.current.has(key)) {
+          outcomes.push({ type: 'cancelled' });
+          continue;
+        }
+        const controller = new AbortController();
+        controllers.current.set(key, controller);
+        const outcome = await uploadFile({
+          ticket: renewed.current.ticket,
+          file: taken[i],
+          url: latest.current.url,
+          maxBytes: latest.current.maxBytes,
+          direct: latest.current.direct,
+          resumable: latest.current.resumable,
+          resumeStore: latest.current.resumeStore,
+          ...(latest.current.backoff === undefined ? {} : { backoff: latest.current.backoff }),
+          signal: controller.signal,
+          onProgress: (p) => patch(key, { progress: p }),
+          onState: (state) => patch(key, { status: state }),
+          onSession: (held) => {
+            sessions.current.set(key, held);
+          },
+          refresh: true,
+          onTicket: (next) => {
+            renewed.current.ticket = next;
+          },
+        });
+        controllers.current.delete(key);
+        outcomes.push(outcome);
+
+        // Removed or reset while it went -- not the field going away, which
+        // keeps it for the next page -- so the server need hold nothing more.
+        const held = sessions.current.get(key);
+        if (outcome.type === 'cancelled' && held !== undefined && discarding.current.has(key)) {
+          void discardRecord(held, latest.current.resumeStore);
+        }
+        discarding.current.delete(key);
+        if (outcome.type !== 'error' || !wanted.current.has(key)) sessions.current.delete(key);
+
+        // Removed or reset while it went: its entry is gone, and nothing is told of it.
+        if (!wanted.current.has(key)) continue;
+        if (outcome.type !== 'uploaded' && outcome.type !== 'error') wanted.current.delete(key);
+
+        if (outcome.type === 'uploaded') {
+          patch(key, { status: 'uploaded', progress: null, file: outcome.file });
+          latest.current.onUploaded?.(outcome.file);
+        } else if (outcome.type === 'error') {
+          patch(key, { status: 'error', progress: null, error: outcome.error });
+          latest.current.onError?.(outcome.error);
+          if (outcome.error.kind === 'signed_out') {
+            endSession(router, session?.hardNavigate ?? assignLocation);
+            break;
+          }
+        } else {
+          setEntries((all) => all.filter((e) => e.key !== key));
+          count.current -= 1;
+        }
+      }
+
+      batches.current.delete(batch);
+      return outcomes;
+    },
+    [router, session, renewed, patch],
+  );
+
+  // A file given up for good: cancelled if it is still going, its session
+  // given up once it has stopped; or, ended keeping one, that one given up now.
+  const giveUpFile = useCallback((/** @type {number} */ key) => {
+    wanted.current.delete(key);
+    const controller = controllers.current.get(key);
+    if (controller !== undefined) {
+      discarding.current.add(key);
+      controller.abort();
+      controllers.current.delete(key);
+      return;
+    }
+    const held = sessions.current.get(key);
+    sessions.current.delete(key);
+    if (held !== undefined) void discardRecord(held, latest.current.resumeStore);
+  }, []);
+
+  const remove = useCallback(
+    (/** @type {number} */ key) => {
+      giveUpFile(key);
+      setEntries((all) => all.filter((e) => e.key !== key));
+    },
+    [giveUpFile],
+  );
+
+  const reset = useCallback(() => {
+    batches.current.forEach((b) => b.abort());
+    batches.current.clear();
+    for (const key of new Set([
+      ...wanted.current,
+      ...controllers.current.keys(),
+      ...sessions.current.keys(),
+    ])) {
+      giveUpFile(key);
+    }
+    wanted.current.clear();
+    setEntries([]);
+  }, [giveUpFile]);
+
+  return {
+    entries,
+    uploading: entries.some(
+      (e) => e.status === 'uploading' || e.status === 'paused' || e.status === 'resuming',
+    ),
+    /** What the form sends under the parameter's name: a reference for each file that went in. */
+    references: entries.flatMap((e) => (e.file === null ? [] : [e.file.upload])),
+    upload,
+    remove,
+    reset,
+  };
+}
+
+/**
+ * A form field for a parameter that takes several files: it uploads each
+ * file chosen in it and posts every reference under `name[]`, drawing
+ * nothing but the hidden inputs.
+ *
+ * @param {UseUploadOptions & {
+ *   name: string,
+ *   accept?: string,
+ *   maxFiles?: number,
+ *   children?: (field: any) => unknown,
+ * }} props
+ */
+export function UploadsField({
+  name,
+  ticket,
+  url,
+  maxBytes,
+  maxFiles,
+  accept,
+  onUploaded,
+  onError,
+  direct,
+  resumable,
+  resumeStore,
+  backoff,
+  children,
+}) {
+  const state = useUploads({
+    ticket,
+    url,
+    maxBytes,
+    maxFiles,
+    onUploaded,
+    onError,
+    direct,
+    resumable,
+    resumeStore,
+    backoff,
+  });
+  const inputRef = useRef(/** @type {HTMLInputElement | null} */ (null));
+  const { upload } = state;
+
+  const onChange = useCallback(
+    (/** @type {{ currentTarget: HTMLInputElement }} */ event) => {
+      const chosen = event.currentTarget.files;
+      if (chosen && chosen.length > 0) void upload(Array.from(chosen));
+      event.currentTarget.value = '';
+    },
+    [upload],
+  );
+
+  const choose = useCallback(() => inputRef.current?.click(), []);
+
+  const field = {
+    ...state,
+    choose,
+    input: { ref: inputRef, type: 'file', multiple: true, accept, onChange },
+  };
+
+  return createElement(
+    Fragment,
+    null,
+    ...state.references.map((reference) =>
+      createElement('input', { key: reference, type: 'hidden', name: `${name}[]`, value: reference }),
+    ),
+    typeof children === 'function' ? children(field) : null,
+  );
+}