@wow-two-beta/ui-vue 0.0.4 → 0.0.6

package/dist/foundation/uploads/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/uploads/UploadItem.ts","../../../src/foundation/uploads/UploadTransport.ts","../../../src/foundation/uploads/XhrUploadTransport.ts","../../../src/foundation/uploads/UploadQueue.ts","../../../src/foundation/uploads/UseUploadQueue.ts"],"sourcesContent":["// The item contract — the vocabulary the queue, the composable, and any UI row all speak. Split from the queue so a\n// consumer can type a prop (`item: UploadItem<MyResponse>`) without importing the store.\n//\n// Non-obvious decisions:\n// - `status` is a const-object union, not a TS `enum` — matches `BackoffStrategy` / `CommandRunOutcome` and stays\n//   erasable under `isolatedModules` + `verbatimModuleSyntax`.\n// - An item is IMMUTABLE: the queue replaces the whole object on every change rather than mutating in place, so a\n//   UI row can key on item identity and a listener can diff snapshots. Nothing here is ever written twice.\n// - A file rejected up front (wrong type / too big) still becomes an item — status `failed` plus a `rejection`\n//   reason. Dropping it silently would leave the user staring at a picker that \"did nothing\"; making it an item\n//   means the same list renders the reason. `rejection` is what separates \"never attempted\" from \"the transport\n//   failed\", which is why `retry()` refuses the former: a 20 MB file stays 20 MB no matter how often it is sent.\n// - `attempt` counts attempts STARTED over the item's lifetime, not retries: `0` while queued, `1` on the first\n//   upload, `2` after one retry. A manual `retry()` continues the count rather than resetting it, so the number\n//   always answers \"how many times has this file been put on the wire\".\n\n/** Defines the lifecycle state of a queued upload. */\nexport const UploadStatus = {\n  /** Refers to an accepted file waiting for a free concurrency slot. */\n  Queued: 'queued',\n  /** Refers to an upload on the wire — including the backoff wait between retry attempts, which still holds its slot. */\n  Uploading: 'uploading',\n  /** Refers to an upload the transport completed; `result` carries its value. */\n  Succeeded: 'succeeded',\n  /** Refers to an upload that exhausted its retries, or a file rejected before it was ever sent (see `rejection`). */\n  Failed: 'failed',\n  /** Refers to an upload aborted by `cancel` / `cancelAll` / `clear`. Never retried automatically. */\n  Cancelled: 'cancelled',\n} as const;\n\nexport type UploadStatus = (typeof UploadStatus)[keyof typeof UploadStatus];\n\n/** Defines why a file was rejected before any upload attempt — set on `rejection`, never on a transport failure. */\nexport const UploadRejectionReason = {\n  /** Refers to a file that failed the queue's `accept` list. */\n  Type: 'type',\n  /** Refers to a file larger than the queue's `maxSize`. */\n  Size: 'size',\n} as const;\n\nexport type UploadRejectionReason = (typeof UploadRejectionReason)[keyof typeof UploadRejectionReason];\n\n/** Describes one file's journey through the queue. Immutable — the queue swaps the object rather than mutating it. */\nexport interface UploadItem<TResult = unknown> {\n  /** The stable id assigned at `add`; the handle every queue action takes. Survives retries and status changes. */\n  readonly id: string;\n\n  /** The file being uploaded. Identity is preserved across retries. */\n  readonly file: File;\n\n  /** The current lifecycle state. */\n  readonly status: UploadStatus;\n\n  /** Upload progress as a fraction `0`–`1`, normalized against `file.size` (see `bytesUploaded`). */\n  readonly progress: number;\n\n  /** Bytes of `file` uploaded so far. Resets to `0` at the start of each attempt — a retry re-sends from scratch. */\n  readonly bytesUploaded: number;\n\n  /** How many attempts have been STARTED for this item: `0` while queued, `1` on the first upload, `2` after one retry. */\n  readonly attempt: number;\n\n  /** The normalized failure (via `foundation/errors`' `toError`) for a `failed` item; absent otherwise. */\n  readonly error?: Error;\n\n  /** Why the file was rejected up front. Present only on a `failed` item that was never sent — a retry cannot help it. */\n  readonly rejection?: UploadRejectionReason;\n\n  /** The transport's return value for a `succeeded` item; absent otherwise. */\n  readonly result?: TResult;\n}\n\n/** Checks whether a status is terminal — the queue will not move it again on its own. */\nexport function isUploadTerminal(status: UploadStatus): boolean {\n  return status === UploadStatus.Succeeded || status === UploadStatus.Failed || status === UploadStatus.Cancelled;\n}\n\n/** Checks whether an item currently holds a concurrency slot (on the wire, or waiting out a retry backoff). */\nexport function isUploadActive(status: UploadStatus): boolean {\n  return status === UploadStatus.Uploading;\n}\n","// The transport seam — the one thing this slice does NOT own. The queue solves scheduling (concurrency, retry,\n// cancellation, progress aggregation); how a byte actually reaches a server is the consumer's decision, so\n// `UploadTransport` is an interface they implement and `createUploadQueue` requires. Nothing in the queue\n// references `fetch`, `XMLHttpRequest`, a URL, or a header — swap in S3 multipart, tus, a presigned PUT, or an\n// in-memory fake without touching the scheduler. `XhrUploadTransport.ts` ships one implementation as a\n// convenience, not as the contract.\n//\n// Non-obvious decisions:\n// - `onProgress` reports the TRANSPORT's numbers (`loaded` / `total`), not the file's. A multipart body carries\n//   boundary + header overhead, so `total` legitimately exceeds `file.size` and `loaded` can too. The queue\n//   normalizes on the ratio; a transport must not pre-scale, it just forwards what it observes.\n// - Retry eligibility is status-driven because `foundation/resilience`'s `shouldRetry` is status-driven. A\n//   transport signals \"this is a 413, don't bother retrying\" by throwing an error with a numeric `status` —\n//   `UploadHttpError` is the ready-made carrier. `readUploadErrorStatus` reads that field STRUCTURALLY, so an\n//   `ApiError` from `foundation/http`, or any custom error with a `status`, interoperates without this slice\n//   depending on the HTTP layer.\n// - No status ⇒ `0`, which `DefaultTransientStatuses` treats as transient. A thrown `TypeError` from a dropped\n//   connection is therefore retryable by default, which is the behaviour you want; a `4xx` you deliberately\n//   surfaced is not.\n\n/** Provides the per-attempt handles a transport receives — cancellation in, progress out. */\nexport interface UploadTransportContext {\n  /** Aborts this attempt. A transport MUST honour it and reject with an `AbortError` (or let `fetch`/`xhr` do so). */\n  readonly signal: AbortSignal;\n\n  /**\n   * Reports bytes sent so far. `totalBytes` is the transport's own total (multipart overhead included) and is\n   * used only as the denominator — omit it when the length is not computable.\n   */\n  readonly onProgress: (bytesUploaded: number, totalBytes?: number) => void;\n}\n\n/** Defines how a file is sent. The single seam a consumer implements to plug any backend into the queue. */\nexport interface UploadTransport<TResult = unknown> {\n  /**\n   * Sends one file, resolving with whatever the caller wants to keep (an id, a URL, the parsed body). Reject to\n   * signal failure; reject with an `AbortError` when `context.signal` fires. Called once per attempt — a retry\n   * calls it again with a fresh `signal`.\n   */\n  readonly upload: (file: File, context: UploadTransportContext) => Promise<TResult>;\n}\n\n/**\n * Defines a transport failure that carries an HTTP status, so the queue's retry decision can respect HTTP\n * semantics (`503` retries, `413` does not). Throw this from a custom transport, or throw anything with a\n * numeric `status` — {@link readUploadErrorStatus} is structural.\n */\nexport class UploadHttpError extends Error {\n  /** The HTTP status of the failed response (`0` when the request never got one). */\n  readonly status: number;\n\n  /** The raw response body, when the transport captured one — useful for surfacing a server-side reason. */\n  readonly body?: string;\n\n  /** Creates an error for a non-2xx (or network-level) upload response. */\n  constructor(status: number, message?: string, body?: string) {\n    super(message ?? `Upload failed with status ${status}`);\n    this.name = 'UploadHttpError';\n    this.status = status;\n    if (body !== undefined) this.body = body;\n  }\n}\n\n/**\n * Reads the HTTP status a caught transport failure carries, for `shouldRetry`. Returns `0` — the \"network /\n * unknown\" status that the default policy treats as transient — when the value has no numeric `status`.\n *\n * Structural on purpose: `UploadHttpError`, `foundation/http`'s `ApiError`, and a hand-rolled\n * `Object.assign(new Error(), { status })` all read the same, so no error class is privileged and this slice\n * stays free of an HTTP-layer import. Guarded against a throwing getter — it runs inside a `catch`.\n */\nexport function readUploadErrorStatus(error: unknown): number {\n  if (typeof error !== 'object' || error === null) return 0;\n  try {\n    const status: unknown = (error as { status?: unknown }).status;\n    return typeof status === 'number' && Number.isFinite(status) ? status : 0;\n  } catch {\n    return 0;\n  }\n}\n","// The one built-in transport — a multipart `POST` over `XMLHttpRequest`.\n//\n// WHY XHR AND NOT `fetch`: `fetch` CANNOT REPORT REQUEST-BODY PROGRESS. Its `ReadableStream` progress story\n// covers the RESPONSE body only; there is no upload-side equivalent, and the streaming-request work\n// (`duplex: 'half'`) is neither universally shipped nor a progress API. `XMLHttpRequest.upload` fires real\n// `progress` events with `loaded` / `total` during the send, so it remains the only portable way to drive an\n// upload progress bar. That single fact — not legacy inertia — is why this file exists in 2026.\n//\n// It is a convenience, never a dependency: `UploadQueue` knows only the `UploadTransport` interface, so a\n// consumer who needs S3 multipart, tus, or a presigned PUT (and no progress bar) writes their own with `fetch`\n// and loses nothing.\n//\n// Non-obvious decisions:\n// - `Content-Type` is deliberately NOT settable through `headers`. The browser derives it from the `FormData`\n//   body, including the multipart boundary; setting it by hand produces a body the server cannot parse. An\n//   explicit `content-type` entry is dropped rather than silently corrupting the request.\n// - Abort rejects with a plain `AbortError`-named error, not a `DOMException` subclass check: `foundation/errors`'\n//   `isAbortError` matches on `name`, which holds across realms (iframe · worker) and in environments without\n//   the global. `xhr.abort()` also fires `load`-adjacent events in some engines, so a `settled` latch guarantees\n//   exactly one settlement.\n// - The abort listener is removed on every exit path. A long-lived `AbortSignal` (one per queue item, reused\n//   across a `cancelAll`) would otherwise accumulate one listener per attempt.\n// - A non-2xx rejects with `UploadHttpError` carrying the status, which is what makes the queue's retry decision\n//   HTTP-aware: `503` retries under the default policy, `413` stops immediately.\n\nimport { UploadHttpError, type UploadTransport, type UploadTransportContext } from './UploadTransport';\n\n/** Configures the built-in `XMLHttpRequest` multipart transport. */\nexport interface XhrUploadTransportOptions {\n  /** The endpoint the file is sent to. */\n  readonly url: string;\n\n  /** The HTTP method. Defaults to `POST`. */\n  readonly method?: string;\n\n  /** Extra request headers. A `Content-Type` entry is ignored — the browser owns it (multipart boundary). */\n  readonly headers?: Readonly<Record<string, string>>;\n\n  /** The multipart field name the file is sent under. Defaults to `file`. */\n  readonly fieldName?: string;\n\n  /** Whether to send cookies / TLS client certs cross-origin (`XMLHttpRequest.withCredentials`). Defaults to `false`. */\n  readonly withCredentials?: boolean;\n}\n\n/** Creates the `AbortError`-named rejection every cancellation path shares — see `isAbortError` in `foundation/errors`. */\nfunction createAbortError(): Error {\n  const error = new Error('The upload was aborted.');\n  error.name = 'AbortError';\n  return error;\n}\n\n/** Parses a response body: JSON when it parses, the raw string when it does not, `undefined` when empty. */\nfunction parseResponseBody(text: string): unknown {\n  if (text === '') return undefined;\n  try {\n    return JSON.parse(text) as unknown;\n  } catch {\n    return text;\n  }\n}\n\n/**\n * Creates an {@link UploadTransport} that sends each file as a `multipart/form-data` request over\n * `XMLHttpRequest`, forwarding real upload-progress events to the queue.\n *\n * Resolves with the parsed JSON response body (the raw text when it is not JSON, `undefined` when empty), cast\n * to `TResult` — the server's contract is the caller's to declare. Rejects with {@link UploadHttpError} on a\n * non-2xx or a network failure, and with an `AbortError` when the attempt's signal fires.\n */\nexport function xhrUploadTransport<TResult = unknown>(options: XhrUploadTransportOptions): UploadTransport<TResult> {\n  const { url, method = 'POST', headers, fieldName = 'file', withCredentials = false } = options;\n\n  return {\n    upload(file: File, context: UploadTransportContext): Promise<TResult> {\n      return new Promise<TResult>((resolve, reject) => {\n        const { signal, onProgress } = context;\n        if (signal.aborted) {\n          reject(createAbortError());\n          return;\n        }\n\n        const request = new XMLHttpRequest();\n        const body = new FormData();\n        body.append(fieldName, file, file.name);\n\n        let settled = false;\n\n        /** Settles exactly once and detaches the signal listener, whichever event won the race. */\n        const settle = (action: () => void): void => {\n          if (settled) return;\n          settled = true;\n          signal.removeEventListener('abort', onAbort);\n          action();\n        };\n\n        function onAbort(): void {\n          settle(() => {\n            request.abort();\n            reject(createAbortError());\n          });\n        }\n\n        request.open(method, url, true);\n        request.withCredentials = withCredentials;\n        for (const [name, value] of Object.entries(headers ?? {})) {\n          // Skipped, not overridden: the multipart boundary is generated with the body and cannot be restated.\n          if (name.toLowerCase() === 'content-type') continue;\n          request.setRequestHeader(name, value);\n        }\n\n        request.upload.addEventListener('progress', (event: ProgressEvent) => {\n          onProgress(event.loaded, event.lengthComputable ? event.total : undefined);\n        });\n\n        request.addEventListener('load', () => {\n          settle(() => {\n            const { status, responseText } = request;\n            if (status >= 200 && status < 300) {\n              resolve(parseResponseBody(responseText) as TResult);\n              return;\n            }\n            reject(new UploadHttpError(status, `Upload of \"${file.name}\" failed with status ${status}.`, responseText));\n          });\n        });\n\n        request.addEventListener('error', () => {\n          // Status `0` — the request never reached a response. The default retry policy treats it as transient.\n          settle(() => reject(new UploadHttpError(0, `Upload of \"${file.name}\" failed: network error.`)));\n        });\n\n        request.addEventListener('timeout', () => {\n          settle(() => reject(new UploadHttpError(0, `Upload of \"${file.name}\" timed out.`)));\n        });\n\n        request.addEventListener('abort', () => {\n          settle(() => reject(createAbortError()));\n        });\n\n        signal.addEventListener('abort', onAbort, { once: true });\n        request.send(body);\n      });\n    },\n  };\n}\n","// The scheduler — the headless core of the uploads vector. Owns admission (validate), ordering, a bounded\n// concurrency pool, retry, cancellation, and progress aggregation. Framework-free (no Vue import) so it can be\n// created at module scope, inside a provider, or in a plain node test; `UseUploadQueue.ts` is the Vue seam on\n// top, exactly as `commands` splits `CommandRegistry` from `useCommandRegistry`.\n//\n// THE CONTRACT: NOTHING HERE THROWS AT THE CALLER. A transport that rejects, a transport that throws\n// synchronously, a cancelled attempt, and a file rejected up front are all NORMAL OUTCOMES that land on an item's\n// `status` and leave the pool running. A queue whose `add` could throw would force a try/catch around a drop\n// handler, and one failing file would take down the other nine.\n//\n// Non-obvious decisions:\n// - RETRY MATH IS NOT WRITTEN HERE. `shouldRetry` decides, `computeRetryDelay` sizes the wait, both from\n//   `foundation/resilience` — the same primitives `foundation/http`'s client and `/query` use, so an upload backs\n//   off identically to every other request in the app. The only timing code below is a plain abortable\n//   `setTimeout`, which schedules the delay it is handed; it never computes one.\n// - `shouldRetry` is status-driven, so a transport failure is read for a numeric `status`\n//   (`readUploadErrorStatus`). No status ⇒ `0` ⇒ transient under the default policy: a dropped connection retries,\n//   a `413` does not. That is the correct default for uploads, where the payload is unchanged by a retry.\n// - A CANCELLED UPLOAD IS NEVER RETRIED. `isAbortError` (plus a direct `signal.aborted` check, for a transport\n//   that rejects with something else) short-circuits before the retry decision. Retrying a cancel would make the\n//   button lie.\n// - An item stays `uploading` THROUGH its backoff wait, holding its concurrency slot. Freeing the slot would let\n//   a queue of failing files spawn unbounded parallel waiters and defeat the cap.\n// - Progress is normalized on the RATIO the transport reports, not its raw `loaded`: a multipart body is bigger\n//   than the file (boundary + headers), so `loaded` alone would overshoot `file.size`.\n// - `version()` exists for the subscribing composable: `items()` builds a fresh array per call, so it can never\n//   be the tracked value (identity changes on every read). The monotonic counter is the stable cursor; items\n//   themselves are swapped immutably so a row can key on item identity.\n// - Every mutation notifies, including each progress event. A chatty transport therefore means frequent\n//   listeners; throttle in YOUR listener if that matters — the queue will not silently drop state changes.\n// - `patch` is a no-op for an unknown id. An in-flight upload whose item was `remove`d or `clear`ed keeps running\n//   until its abort lands, and its late writes must not resurrect a deleted row.\n\nimport { isAbortError, toError } from '../errors';\nimport { fileExtension, matchesAccept, safeFileName } from '../files';\nimport { formatBytes } from '../format';\nimport { Guid } from '../identifiers';\nimport { DefaultRetryPolicy, computeRetryDelay, shouldRetry, type RetryPolicy } from '../resilience';\n\nimport { UploadRejectionReason, UploadStatus, isUploadTerminal, type UploadItem } from './UploadItem';\nimport { readUploadErrorStatus, type UploadTransport } from './UploadTransport';\n\n/** The default number of uploads in flight at once — enough to saturate a connection without starving the rest of the app. */\nexport const DefaultUploadConcurrency = 3;\n\n/** Notified after any queue mutation — admission, status change, progress, removal. Carries no payload; re-read the queue. */\nexport type UploadQueueListener = () => void;\n\n/** Configures a queue at creation. Only `transport` is required. */\nexport interface UploadQueueOptions<TResult = unknown> {\n  /** How a file is actually sent. The queue never assumes `fetch` or `XMLHttpRequest`; see {@link UploadTransport}. */\n  readonly transport: UploadTransport<TResult>;\n\n  /** Max uploads in flight. Defaults to {@link DefaultUploadConcurrency}; values below `1` are clamped up. */\n  readonly concurrency?: number;\n\n  /** An `accept`-attribute list (`image/*,.pdf`) admitted files must match, via `foundation/files`' `matchesAccept`. */\n  readonly accept?: string;\n\n  /** The largest admitted file, in bytes. A larger file is rejected up front rather than queued. */\n  readonly maxSize?: number;\n\n  /** The retry policy for failed attempts, or `false` to fail on the first error. Defaults to `DefaultRetryPolicy`. */\n  readonly retry?: RetryPolicy | false;\n}\n\n/** Describes the queue as a whole — what a summary bar renders without walking the item list. */\nexport interface UploadQueueState {\n  /** How many items the queue holds, in any status. */\n  readonly total: number;\n\n  /** How many items sit in each status. A file rejected up front counts under `failed`. */\n  readonly counts: Readonly<Record<UploadStatus, number>>;\n\n  /** Aggregate progress `0`–`1`, byte-weighted over in-play items. `0` when nothing is in play. */\n  readonly progress: number;\n\n  /** Total bytes uploaded across in-play items. */\n  readonly bytesUploaded: number;\n\n  /**\n   * Total bytes of in-play items — everything except cancelled items and files rejected up front, whose bytes\n   * will never arrive and would otherwise pin `progress` below `1` forever.\n   */\n  readonly totalBytes: number;\n\n  /** Whether any item is still queued or uploading. */\n  readonly isUploading: boolean;\n}\n\n/** The headless upload store — admission, scheduling, cancellation, retry, and change notification. */\nexport interface UploadQueue<TResult = unknown> {\n  /**\n   * Admits one file or many, returning the new item ids in the order given. Always returns an array, including\n   * for a single file. A file failing `accept` / `maxSize` still gets an id — as a `failed` item carrying a\n   * `rejection` — so the caller can render why. Never throws.\n   */\n  readonly add: (input: File | readonly File[]) => readonly string[];\n\n  /**\n   * Aborts an item. A queued item flips to `cancelled` immediately; an uploading one is aborted through its\n   * signal and settles `cancelled` once the transport unwinds (asynchronously). Reports whether anything was\n   * cancellable — `false` for an unknown id or an already-terminal item.\n   */\n  readonly cancel: (id: string) => boolean;\n\n  /** Aborts every queued and uploading item. In-flight ones settle asynchronously, as with {@link cancel}. */\n  readonly cancelAll: () => void;\n\n  /**\n   * Re-queues a `failed` or `cancelled` item for another run; `attempt` continues from where it stopped.\n   * Refuses (`false`) an item rejected up front — re-sending an oversized file cannot change the verdict.\n   */\n  readonly retry: (id: string) => boolean;\n\n  /** Drops an item, aborting it first when in flight (nothing would be listening for its result). */\n  readonly remove: (id: string) => boolean;\n\n  /** Drops every item, cancelling anything still in flight. */\n  readonly clear: () => void;\n\n  /** Every item in admission order. Fresh array per call — never track it directly; track `version()` instead. */\n  readonly items: () => readonly UploadItem<TResult>[];\n\n  /** Looks up one item — `undefined` when absent. Item identity is stable between changes to that item. */\n  readonly get: (id: string) => UploadItem<TResult> | undefined;\n\n  /** The aggregate snapshot — counts, byte totals, overall progress. Fresh object per call. */\n  readonly state: () => UploadQueueState;\n\n  /** Subscribes to mutations; returns an unsubscribe. */\n  readonly subscribe: (listener: UploadQueueListener) => () => void;\n\n  /** A monotonic counter bumped on every mutation — the stable-identity snapshot the composables subscribe to. */\n  readonly version: () => number;\n}\n\n/** Waits `ms`, resolving early (never rejecting) if `signal` aborts. The caller re-checks `signal.aborted` after. */\nfunction sleep(ms: number, signal: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve) => {\n    if (signal.aborted) {\n      resolve();\n      return;\n    }\n    // `finish` closes over `timer` declared below it: legal because it only ever runs after both are initialized\n    // (as the timer's own callback, or as an abort listener attached last).\n    const finish = (): void => {\n      clearTimeout(timer);\n      signal.removeEventListener('abort', finish);\n      resolve();\n    };\n    const timer = setTimeout(finish, ms);\n    signal.addEventListener('abort', finish, { once: true });\n  });\n}\n\n/**\n * Creates an {@link UploadQueue}. One per upload surface is the norm; create extra ones to isolate a modal's\n * uploads from a background set, or per test.\n */\nexport function createUploadQueue<TResult = unknown>(options: UploadQueueOptions<TResult>): UploadQueue<TResult> {\n  const { transport, accept, maxSize } = options;\n  const concurrency = Math.max(1, Math.floor(options.concurrency ?? DefaultUploadConcurrency));\n  const retryPolicy: RetryPolicy | false = options.retry ?? DefaultRetryPolicy;\n\n  const entries = new Map<string, UploadItem<TResult>>();\n  /** The in-flight set — one controller per running attempt. Its size IS the concurrency count. */\n  const controllers = new Map<string, AbortController>();\n  const listeners = new Set<UploadQueueListener>();\n  let revision = 0;\n  let pumping = false;\n\n  /** Bumps the version then fans out over a copy, so a listener may unsubscribe while being notified. */\n  function notify(): void {\n    revision += 1;\n    for (const listener of [...listeners]) listener();\n  }\n\n  /** Replaces an item with a changed copy and notifies. Silently drops writes for an id that is no longer queued. */\n  function patch(id: string, changes: Partial<Omit<UploadItem<TResult>, 'id' | 'file'>>): void {\n    const current = entries.get(id);\n    if (current === undefined) return;\n    entries.set(id, { ...current, ...changes });\n    notify();\n  }\n\n  /** Describes a file's type for a rejection message — the MIME type, or the extension when the browser left it blank. */\n  function describeFileType(file: File): string {\n    if (file.type !== '') return file.type;\n    const extension = fileExtension(file.name);\n    return extension === '' ? 'of an unknown type' : `a \".${extension}\" file`;\n  }\n\n  /** Applies the admission rules. `undefined` = admitted. */\n  function validate(file: File): UploadRejectionReason | undefined {\n    if (accept !== undefined && !matchesAccept(file, accept)) return UploadRejectionReason.Type;\n    if (maxSize !== undefined && file.size > maxSize) return UploadRejectionReason.Size;\n    return undefined;\n  }\n\n  /** Builds the user-facing reason for a rejection. The name is sanitized — it is attacker-controlled text headed for a UI. */\n  function rejectionError(file: File, reason: UploadRejectionReason): Error {\n    const name = safeFileName(file.name);\n    if (reason === UploadRejectionReason.Size) {\n      return new Error(`\"${name}\" is ${formatBytes(file.size)}, over the ${formatBytes(maxSize ?? 0)} limit.`);\n    }\n    return new Error(`\"${name}\" is ${describeFileType(file)}, which does not match \"${accept ?? ''}\".`);\n  }\n\n  /** Records a transport progress report, normalized onto `file.size` (see the ratio note in the header). */\n  function recordProgress(id: string, loaded: number, total?: number): void {\n    const current = entries.get(id);\n    if (current === undefined || current.status !== UploadStatus.Uploading) return;\n\n    const size = current.file.size;\n    const denominator = total !== undefined && total > 0 ? total : size;\n    const fraction = denominator > 0 ? Math.min(1, Math.max(0, loaded / denominator)) : 0;\n    const bytesUploaded = Math.round(fraction * size);\n\n    // Transports re-fire identical events; skipping the no-op keeps a listener from waking for nothing.\n    if (fraction === current.progress && bytesUploaded === current.bytesUploaded) return;\n    patch(id, { progress: fraction, bytesUploaded });\n  }\n\n  /**\n   * Runs one item to a terminal state: attempt → retry loop → settle. Never rejects; every exit path is a status.\n   * Holds a slot in `controllers` for its whole life, backoff waits included, and pumps the next item on exit.\n   */\n  async function runItem(id: string): Promise<void> {\n    const initial = entries.get(id);\n    if (initial === undefined) return;\n\n    // Attempts already spent in earlier run cycles — a manual `retry()` continues the count, never resets it.\n    const baseAttempt = initial.attempt;\n    const controller = new AbortController();\n    controllers.set(id, controller);\n\n    let retries = 0;\n    let previousDelayMs = 0;\n\n    try {\n      for (;;) {\n        const current = entries.get(id);\n        if (current === undefined) return;\n\n        patch(id, {\n          status: UploadStatus.Uploading,\n          attempt: baseAttempt + retries + 1,\n          progress: 0,\n          bytesUploaded: 0,\n          error: undefined,\n        });\n\n        try {\n          const result = await transport.upload(current.file, {\n            signal: controller.signal,\n            onProgress: (loaded: number, total?: number) => recordProgress(id, loaded, total),\n          });\n          // A transport that ignores its signal can still resolve after a cancel; the user's intent wins.\n          if (controller.signal.aborted) {\n            patch(id, { status: UploadStatus.Cancelled });\n            return;\n          }\n          patch(id, {\n            status: UploadStatus.Succeeded,\n            progress: 1,\n            bytesUploaded: current.file.size,\n            result,\n          });\n          return;\n        } catch (caught) {\n          if (isAbortError(caught) || controller.signal.aborted) {\n            patch(id, { status: UploadStatus.Cancelled });\n            return;\n          }\n\n          const status = readUploadErrorStatus(caught);\n          if (retryPolicy !== false && shouldRetry(retryPolicy, retries, status)) {\n            const attemptNumber = retries + 1;\n            const delayMs = computeRetryDelay(retryPolicy, attemptNumber, previousDelayMs);\n            retryPolicy.onRetry?.({ attempt: attemptNumber, error: caught, status, delayMs });\n            await sleep(delayMs, controller.signal);\n            if (controller.signal.aborted) {\n              patch(id, { status: UploadStatus.Cancelled });\n              return;\n            }\n            previousDelayMs = delayMs;\n            retries = attemptNumber;\n            continue;\n          }\n\n          patch(id, { status: UploadStatus.Failed, error: toError(caught) });\n          return;\n        }\n      }\n    } finally {\n      controllers.delete(id);\n      pump();\n    }\n  }\n\n  /**\n   * Starts queued items until the pool is full. Re-entrancy-guarded: `runItem`'s `finally` pumps again, and a\n   * transport that throws synchronously would otherwise recurse once per queued item.\n   */\n  function pump(): void {\n    if (pumping) return;\n    pumping = true;\n    try {\n      while (controllers.size < concurrency) {\n        let next: UploadItem<TResult> | undefined;\n        for (const item of entries.values()) {\n          if (item.status === UploadStatus.Queued) {\n            next = item;\n            break;\n          }\n        }\n        if (next === undefined) return;\n        void runItem(next.id);\n      }\n    } finally {\n      pumping = false;\n    }\n  }\n\n  /** Builds the item an admitted or rejected file starts life as. */\n  function createItem(file: File): UploadItem<TResult> {\n    const id = Guid.createV7() as string;\n    const rejection = validate(file);\n    if (rejection !== undefined) {\n      return {\n        id,\n        file,\n        status: UploadStatus.Failed,\n        progress: 0,\n        bytesUploaded: 0,\n        attempt: 0,\n        rejection,\n        error: rejectionError(file, rejection),\n      };\n    }\n    return { id, file, status: UploadStatus.Queued, progress: 0, bytesUploaded: 0, attempt: 0 };\n  }\n\n  function cancel(id: string): boolean {\n    const item = entries.get(id);\n    if (item === undefined || isUploadTerminal(item.status)) return false;\n\n    const controller = controllers.get(id);\n    if (controller !== undefined) {\n      // The status flips inside `runItem` once the transport unwinds — cancellation is inherently async.\n      controller.abort();\n      return true;\n    }\n    patch(id, { status: UploadStatus.Cancelled });\n    pump();\n    return true;\n  }\n\n  /** Hoisted out of the returned object so `clear` can call it without a `this` binding (the API is destructurable). */\n  function cancelAll(): void {\n    for (const item of [...entries.values()]) {\n      if (!isUploadTerminal(item.status)) cancel(item.id);\n    }\n  }\n\n  return {\n    add(input: File | readonly File[]): readonly string[] {\n      const files = input instanceof File ? [input] : input;\n      const created = files.map(createItem);\n      for (const item of created) entries.set(item.id, item);\n      // ONE notification for the whole admission — dropping ten files notifies once, not ten times. The `pump`\n      // below then adds one more per item it actually starts, since each of those is a real status change.\n      notify();\n      pump();\n      return created.map((item) => item.id);\n    },\n\n    cancel,\n\n    cancelAll,\n\n    retry(id: string): boolean {\n      const item = entries.get(id);\n      if (item === undefined || item.rejection !== undefined) return false;\n      if (item.status !== UploadStatus.Failed && item.status !== UploadStatus.Cancelled) return false;\n\n      patch(id, {\n        status: UploadStatus.Queued,\n        progress: 0,\n        bytesUploaded: 0,\n        error: undefined,\n        result: undefined,\n      });\n      pump();\n      return true;\n    },\n\n    remove(id: string): boolean {\n      if (!entries.has(id)) return false;\n      controllers.get(id)?.abort();\n      controllers.delete(id);\n      entries.delete(id);\n      notify();\n      pump();\n      return true;\n    },\n\n    clear(): void {\n      cancelAll();\n      entries.clear();\n      // Dropped rather than awaited: a transport that ignores its abort must not wedge the pool forever. The\n      // orphaned `runItem` finishes into `patch`, which no-ops on the vanished ids.\n      controllers.clear();\n      notify();\n    },\n\n    items(): readonly UploadItem<TResult>[] {\n      return [...entries.values()];\n    },\n\n    get(id: string): UploadItem<TResult> | undefined {\n      return entries.get(id);\n    },\n\n    state(): UploadQueueState {\n      const counts: Record<UploadStatus, number> = {\n        [UploadStatus.Queued]: 0,\n        [UploadStatus.Uploading]: 0,\n        [UploadStatus.Succeeded]: 0,\n        [UploadStatus.Failed]: 0,\n        [UploadStatus.Cancelled]: 0,\n      };\n\n      let bytesUploaded = 0;\n      let totalBytes = 0;\n      for (const item of entries.values()) {\n        counts[item.status] += 1;\n        // Cancelled + rejected bytes are excluded from both sides — they are never arriving.\n        if (item.status === UploadStatus.Cancelled || item.rejection !== undefined) continue;\n        bytesUploaded += item.bytesUploaded;\n        totalBytes += item.file.size;\n      }\n\n      return {\n        total: entries.size,\n        counts,\n        bytesUploaded,\n        totalBytes,\n        progress: totalBytes > 0 ? Math.min(1, bytesUploaded / totalBytes) : 0,\n        isUploading: counts[UploadStatus.Queued] > 0 || counts[UploadStatus.Uploading] > 0,\n      };\n    },\n\n    subscribe(listener: UploadQueueListener): () => void {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n\n    version(): number {\n      return revision;\n    },\n  };\n}\n","// The Vue subscription seam over a queue — how a component updates as uploads progress. Mirrors `commands`'\n// `UseCommandRegistry.ts`: the store is framework-free, this file is the only part that imports Vue.\n//\n// Non-obvious decisions:\n// - These track `queue.version()` as the subscription snapshot, NOT `items()` / `state()`. Both build a fresh\n//   value per call, so either as the snapshot would look changed on every read. The monotonic counter is\n//   identity-stable between mutations; the arrays and the aggregate derive from it through a `computed`.\n// - The subscription is attached in `onMounted` and dropped in `onScopeDispose`, the same shape\n//   `foundation/hooks`' `useMediaQuery` uses. The queue is plain in-memory state with no client-only source, so\n//   the SSR pass reads a correct version rather than a placeholder — the mount hook exists for the listener, not\n//   for a platform global.\n// - `useUploadQueueSnapshot(queue)` takes the queue EXPLICITLY, so an app that owns a module-scope queue (uploads\n//   that must survive tearing down the panel) can subscribe without this file creating anything.\n// - `useUploadQueue(options)` is the convenience on top and creates its queue ONCE, at setup — the queue holds\n//   in-flight work, so rebuilding it on a changed option would strand running uploads. Consequence, stated\n//   plainly: `concurrency` / `accept` / `maxSize` / `retry` are read at SETUP and later changes are ignored.\n//   Need them dynamic → own the queue and re-create it deliberately.\n// - `transport` is the exception: it is delegated through `toValue`, so an inline `{ upload: ... }` closing over\n//   current props stays live instead of being frozen at setup. Same trick `provideCommands` uses for `onError`,\n//   and it is what makes the common inline call site correct without any memoization by the caller.\n// - The action callbacks are the queue's own methods, already referentially stable, so nothing wraps them.\n\nimport {\n  computed,\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  type ComputedRef,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport type { UploadItem } from './UploadItem';\nimport { createUploadQueue, type UploadQueue, type UploadQueueOptions, type UploadQueueState } from './UploadQueue';\n\n/**\n * Subscribes to a queue's mutations and returns its version counter. The building block behind\n * {@link useUploadQueueSnapshot}; use it directly to derive a custom projection\n * (`computed(() => (version.value, queue.items().filter(failed)))`).\n */\nexport function useUploadQueueVersion<TResult = unknown>(\n  queue: UploadQueue<TResult>,\n): Readonly<ShallowRef<number>> {\n  const version = shallowRef(queue.version());\n\n  let unsubscribe: (() => void) | undefined;\n\n  onMounted(() => {\n    // Re-read first: a mutation between setup and mount would otherwise be missed entirely.\n    version.value = queue.version();\n    unsubscribe = queue.subscribe(() => {\n      version.value = queue.version();\n    });\n  });\n\n  onScopeDispose(() => {\n    unsubscribe?.();\n    unsubscribe = undefined;\n  });\n\n  return version;\n}\n\n/** The item list plus the aggregate state of an explicitly-owned queue, updating the caller on every change. */\nexport function useUploadQueueSnapshot<TResult = unknown>(\n  queue: UploadQueue<TResult>,\n): {\n  readonly items: ComputedRef<readonly UploadItem<TResult>[]>;\n  readonly state: ComputedRef<UploadQueueState>;\n} {\n  const version = useUploadQueueVersion(queue);\n  // `version` is the mutation cursor that invalidates both reads — touched, then discarded.\n  return {\n    items: computed(() => {\n      void version.value;\n      return queue.items();\n    }),\n    state: computed(() => {\n      void version.value;\n      return queue.state();\n    }),\n  };\n}\n\n/** What {@link useUploadQueue} hands a component — live state plus every queue action. */\nexport interface UseUploadQueueResult<TResult = unknown> {\n  /** The underlying queue, for anything the flattened actions don't cover (`get`, `subscribe`, passing it down). */\n  readonly queue: UploadQueue<TResult>;\n\n  /** Every item in admission order, refreshed on each change. */\n  readonly items: ComputedRef<readonly UploadItem<TResult>[]>;\n\n  /** The aggregate snapshot — counts, byte totals, overall progress. */\n  readonly state: ComputedRef<UploadQueueState>;\n\n  /** Admits one file or many; returns the new item ids. See `UploadQueue.add`. */\n  readonly add: UploadQueue<TResult>['add'];\n\n  /** Aborts one item. See `UploadQueue.cancel`. */\n  readonly cancel: UploadQueue<TResult>['cancel'];\n\n  /** Aborts every queued and uploading item. */\n  readonly cancelAll: UploadQueue<TResult>['cancelAll'];\n\n  /** Re-queues a failed or cancelled item. */\n  readonly retry: UploadQueue<TResult>['retry'];\n\n  /** Drops an item, aborting it first when in flight. */\n  readonly remove: UploadQueue<TResult>['remove'];\n\n  /** Drops every item, cancelling anything still in flight. */\n  readonly clear: UploadQueue<TResult>['clear'];\n}\n\n/**\n * Creates an upload queue scoped to the component and subscribes to it — the one-call entry point for an upload\n * panel or drop zone.\n *\n * The queue is created at setup and kept for the scope's lifetime, so `concurrency` / `accept` / `maxSize` /\n * `retry` are setup-time values (`transport` stays live — see the file header). Disposal does NOT cancel\n * in-flight uploads; call `cancelAll` from `onScopeDispose` if that is the behaviour you want, or hoist the\n * queue out of the component with `createUploadQueue` + {@link useUploadQueueSnapshot} so uploads survive it.\n *\n * @param options Queue configuration. A ref or getter keeps `transport` live; the rest is read once.\n */\nexport function useUploadQueue<TResult = unknown>(\n  options: MaybeRefOrGetter<UploadQueueOptions<TResult>>,\n): UseUploadQueueResult<TResult> {\n  const queue = createUploadQueue<TResult>({\n    ...toValue(options),\n    // Delegated, not captured: the current transport handles every attempt.\n    transport: { upload: (file, context) => toValue(options).transport.upload(file, context) },\n  });\n\n  const { items, state } = useUploadQueueSnapshot(queue);\n\n  return {\n    queue,\n    items,\n    state,\n    add: queue.add,\n    cancel: queue.cancel,\n    cancelAll: queue.cancelAll,\n    retry: queue.retry,\n    remove: queue.remove,\n    clear: queue.clear,\n  };\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/uploads/UploadItem.ts","../../../src/foundation/uploads/UploadTransport.ts","../../../src/foundation/uploads/XhrUploadTransport.ts","../../../src/foundation/uploads/UploadQueue.ts","../../../src/foundation/uploads/UseUploadQueue.ts"],"sourcesContent":["// The item contract — the vocabulary the queue, the composable, and any UI row all speak. Split from the queue so a\n// consumer can type a prop (`item: UploadItem<MyResponse>`) without importing the store.\n//\n// Non-obvious decisions:\n// - `status` is a const-object union, not a TS `enum` — matches `BackoffStrategy` / `CommandRunOutcome` and stays\n//   erasable under `isolatedModules` + `verbatimModuleSyntax`.\n// - An item is IMMUTABLE: the queue replaces the whole object on every change rather than mutating in place, so a\n//   UI row can key on item identity and a listener can diff snapshots. Nothing here is ever written twice.\n// - A file rejected up front (wrong type / too big) still becomes an item — status `failed` plus a `rejection`\n//   reason. Dropping it silently would leave the user staring at a picker that \"did nothing\"; making it an item\n//   means the same list renders the reason. `rejection` is what separates \"never attempted\" from \"the transport\n//   failed\", which is why `retry()` refuses the former: a 20 MB file stays 20 MB no matter how often it is sent.\n// - `attempt` counts attempts STARTED over the item's lifetime, not retries: `0` while queued, `1` on the first\n//   upload, `2` after one retry. A manual `retry()` continues the count rather than resetting it, so the number\n//   always answers \"how many times has this file been put on the wire\".\n\n/** Defines the lifecycle state of a queued upload. */\nexport const UploadStatus = {\n  /** Refers to an accepted file waiting for a free concurrency slot. */\n  Queued: 'queued',\n  /** Refers to an upload on the wire — including the backoff wait between retries, which still holds its slot. */\n  Uploading: 'uploading',\n  /** Refers to an upload the transport completed; `result` carries its value. */\n  Succeeded: 'succeeded',\n  /** Refers to an upload that exhausted its retries, or a file rejected before it was ever sent (see `rejection`). */\n  Failed: 'failed',\n  /** Refers to an upload aborted by `cancel` / `cancelAll` / `clear`. Never retried automatically. */\n  Cancelled: 'cancelled',\n} as const;\n\nexport type UploadStatus = (typeof UploadStatus)[keyof typeof UploadStatus];\n\n/** Defines why a file was rejected before any upload attempt — set on `rejection`, never on a transport failure. */\nexport const UploadRejectionReason = {\n  /** Refers to a file that failed the queue's `accept` list. */\n  Type: 'type',\n  /** Refers to a file larger than the queue's `maxSize`. */\n  Size: 'size',\n} as const;\n\nexport type UploadRejectionReason = (typeof UploadRejectionReason)[keyof typeof UploadRejectionReason];\n\n/** Describes one file's journey through the queue. Immutable — the queue swaps the object rather than mutating it. */\nexport interface UploadItem<TResult = unknown> {\n  /** The stable id assigned at `add`; the handle every queue action takes. Survives retries and status changes. */\n  readonly id: string;\n\n  /** The file being uploaded. Identity is preserved across retries. */\n  readonly file: File;\n\n  /** The current lifecycle state. */\n  readonly status: UploadStatus;\n\n  /** Upload progress as a fraction `0`–`1`, normalized against `file.size` (see `bytesUploaded`). */\n  readonly progress: number;\n\n  /** Bytes of `file` uploaded so far. Resets to `0` at the start of each attempt — a retry re-sends from scratch. */\n  readonly bytesUploaded: number;\n\n  /** How many attempts have been STARTED: `0` while queued, `1` on the first upload, `2` after one retry. */\n  readonly attempt: number;\n\n  /** The normalized failure (via `foundation/errors`' `toError`) for a `failed` item; absent otherwise. */\n  readonly error?: Error;\n\n  /** Why the file was rejected up front. Present only on a `failed` item never sent — a retry cannot help it. */\n  readonly rejection?: UploadRejectionReason;\n\n  /** The transport's return value for a `succeeded` item; absent otherwise. */\n  readonly result?: TResult;\n}\n\n/** Checks whether a status is terminal — the queue will not move it again on its own. */\nexport function isUploadTerminal(status: UploadStatus): boolean {\n  return status === UploadStatus.Succeeded || status === UploadStatus.Failed || status === UploadStatus.Cancelled;\n}\n\n/** Checks whether an item currently holds a concurrency slot (on the wire, or waiting out a retry backoff). */\nexport function isUploadActive(status: UploadStatus): boolean {\n  return status === UploadStatus.Uploading;\n}\n","// The transport seam — the one thing this slice does NOT own. The queue solves scheduling (concurrency, retry,\n// cancellation, progress aggregation); how a byte actually reaches a server is the consumer's decision, so\n// `UploadTransport` is an interface they implement and `createUploadQueue` requires. Nothing in the queue\n// references `fetch`, `XMLHttpRequest`, a URL, or a header — swap in S3 multipart, tus, a presigned PUT, or an\n// in-memory fake without touching the scheduler. `XhrUploadTransport.ts` ships one implementation as a\n// convenience, not as the contract.\n//\n// Non-obvious decisions:\n// - `onProgress` reports the TRANSPORT's numbers (`loaded` / `total`), not the file's. A multipart body carries\n//   boundary + header overhead, so `total` legitimately exceeds `file.size` and `loaded` can too. The queue\n//   normalizes on the ratio; a transport must not pre-scale, it just forwards what it observes.\n// - Retry eligibility is status-driven because `foundation/resilience`'s `shouldRetry` is status-driven. A\n//   transport signals \"this is a 413, don't bother retrying\" by throwing an error with a numeric `status` —\n//   `UploadHttpError` is the ready-made carrier. `readUploadErrorStatus` reads that field STRUCTURALLY, so an\n//   `ApiError` from `foundation/http`, or any custom error with a `status`, interoperates without this slice\n//   depending on the HTTP layer.\n// - No status ⇒ `0`, which `DefaultTransientStatuses` treats as transient. A thrown `TypeError` from a dropped\n//   connection is therefore retryable by default, which is the behaviour you want; a `4xx` you deliberately\n//   surfaced is not.\n\n/** Provides the per-attempt handles a transport receives — cancellation in, progress out. */\nexport interface UploadTransportContext {\n  /** Aborts this attempt. A transport MUST honour it and reject with an `AbortError` (or let `fetch`/`xhr` do so). */\n  readonly signal: AbortSignal;\n\n  /**\n   * Reports bytes sent so far. `totalBytes` is the transport's own total (multipart overhead included) and is\n   * used only as the denominator — omit it when the length is not computable.\n   */\n  readonly onProgress: (bytesUploaded: number, totalBytes?: number) => void;\n}\n\n/** Defines how a file is sent. The single seam a consumer implements to plug any backend into the queue. */\nexport interface UploadTransport<TResult = unknown> {\n  /**\n   * Sends one file, resolving with whatever the caller wants to keep (an id, a URL, the parsed body). Reject to\n   * signal failure; reject with an `AbortError` when `context.signal` fires. Called once per attempt — a retry\n   * calls it again with a fresh `signal`.\n   */\n  readonly upload: (file: File, context: UploadTransportContext) => Promise<TResult>;\n}\n\n/**\n * Defines a transport failure that carries an HTTP status, so the queue's retry decision can respect HTTP\n * semantics (`503` retries, `413` does not). Throw this from a custom transport, or throw anything with a\n * numeric `status` — {@link readUploadErrorStatus} is structural.\n */\nexport class UploadHttpError extends Error {\n  /** The HTTP status of the failed response (`0` when the request never got one). */\n  readonly status: number;\n\n  /** The raw response body, when the transport captured one — useful for surfacing a server-side reason. */\n  readonly body?: string;\n\n  /** Creates an error for a non-2xx (or network-level) upload response. */\n  constructor(status: number, message?: string, body?: string) {\n    super(message ?? `Upload failed with status ${status}`);\n    this.name = 'UploadHttpError';\n    this.status = status;\n    if (body !== undefined) this.body = body;\n  }\n}\n\n/**\n * Reads the HTTP status a caught transport failure carries, for `shouldRetry`. Returns `0` — the \"network /\n * unknown\" status that the default policy treats as transient — when the value has no numeric `status`.\n *\n * Structural on purpose: `UploadHttpError`, `foundation/http`'s `ApiError`, and a hand-rolled\n * `Object.assign(new Error(), { status })` all read the same, so no error class is privileged and this slice\n * stays free of an HTTP-layer import. Guarded against a throwing getter — it runs inside a `catch`.\n */\nexport function readUploadErrorStatus(error: unknown): number {\n  if (typeof error !== 'object' || error === null) return 0;\n  try {\n    const status: unknown = (error as { status?: unknown }).status;\n    return typeof status === 'number' && Number.isFinite(status) ? status : 0;\n  } catch {\n    return 0;\n  }\n}\n","// The one built-in transport — a multipart `POST` over `XMLHttpRequest`.\n//\n// WHY XHR AND NOT `fetch`: `fetch` CANNOT REPORT REQUEST-BODY PROGRESS. Its `ReadableStream` progress story\n// covers the RESPONSE body only; there is no upload-side equivalent, and the streaming-request work\n// (`duplex: 'half'`) is neither universally shipped nor a progress API. `XMLHttpRequest.upload` fires real\n// `progress` events with `loaded` / `total` during the send, so it remains the only portable way to drive an\n// upload progress bar. That single fact — not legacy inertia — is why this file exists in 2026.\n//\n// It is a convenience, never a dependency: `UploadQueue` knows only the `UploadTransport` interface, so a\n// consumer who needs S3 multipart, tus, or a presigned PUT (and no progress bar) writes their own with `fetch`\n// and loses nothing.\n//\n// Non-obvious decisions:\n// - `Content-Type` is deliberately NOT settable through `headers`. The browser derives it from the `FormData`\n//   body, including the multipart boundary; setting it by hand produces a body the server cannot parse. An\n//   explicit `content-type` entry is dropped rather than silently corrupting the request.\n// - Abort rejects with a plain `AbortError`-named error, not a `DOMException` subclass check: `foundation/errors`'\n//   `isAbortError` matches on `name`, which holds across realms (iframe · worker) and in environments without\n//   the global. `xhr.abort()` also fires `load`-adjacent events in some engines, so a `settled` latch guarantees\n//   exactly one settlement.\n// - The abort listener is removed on every exit path. A long-lived `AbortSignal` (one per queue item, reused\n//   across a `cancelAll`) would otherwise accumulate one listener per attempt.\n// - A non-2xx rejects with `UploadHttpError` carrying the status, which is what makes the queue's retry decision\n//   HTTP-aware: `503` retries under the default policy, `413` stops immediately.\n\nimport { UploadHttpError, type UploadTransport, type UploadTransportContext } from './UploadTransport';\n\n/** Configures the built-in `XMLHttpRequest` multipart transport. */\nexport interface XhrUploadTransportOptions {\n  /** The endpoint the file is sent to. */\n  readonly url: string;\n\n  /** The HTTP method. Defaults to `POST`. */\n  readonly method?: string;\n\n  /** Extra request headers. A `Content-Type` entry is ignored — the browser owns it (multipart boundary). */\n  readonly headers?: Readonly<Record<string, string>>;\n\n  /** The multipart field name the file is sent under. Defaults to `file`. */\n  readonly fieldName?: string;\n\n  /** Whether to send cookies / TLS client certs cross-origin (`XMLHttpRequest.withCredentials`). Defaults `false`. */\n  readonly withCredentials?: boolean;\n}\n\n/** Creates the `AbortError`-named rejection every cancellation path shares — recognized by `isAbortError`. */\nfunction createAbortError(): Error {\n  const error = new Error('The upload was aborted.');\n  error.name = 'AbortError';\n  return error;\n}\n\n/** Parses a response body: JSON when it parses, the raw string when it does not, `undefined` when empty. */\nfunction parseResponseBody(text: string): unknown {\n  if (text === '') return undefined;\n  try {\n    return JSON.parse(text) as unknown;\n  } catch {\n    return text;\n  }\n}\n\n/**\n * Creates an {@link UploadTransport} that sends each file as a `multipart/form-data` request over\n * `XMLHttpRequest`, forwarding real upload-progress events to the queue.\n *\n * Resolves with the parsed JSON response body (the raw text when it is not JSON, `undefined` when empty), cast\n * to `TResult` — the server's contract is the caller's to declare. Rejects with {@link UploadHttpError} on a\n * non-2xx or a network failure, and with an `AbortError` when the attempt's signal fires.\n */\nexport function xhrUploadTransport<TResult = unknown>(options: XhrUploadTransportOptions): UploadTransport<TResult> {\n  const { url, method = 'POST', headers, fieldName = 'file', withCredentials = false } = options;\n\n  return {\n    upload(file: File, context: UploadTransportContext): Promise<TResult> {\n      return new Promise<TResult>((resolve, reject) => {\n        const { signal, onProgress } = context;\n        if (signal.aborted) {\n          reject(createAbortError());\n          return;\n        }\n\n        const request = new XMLHttpRequest();\n        const body = new FormData();\n        body.append(fieldName, file, file.name);\n\n        let settled = false;\n\n        /** Settles exactly once and detaches the signal listener, whichever event won the race. */\n        const settle = (action: () => void): void => {\n          if (settled) return;\n          settled = true;\n          signal.removeEventListener('abort', onAbort);\n          action();\n        };\n\n        function onAbort(): void {\n          settle(() => {\n            request.abort();\n            reject(createAbortError());\n          });\n        }\n\n        request.open(method, url, true);\n        request.withCredentials = withCredentials;\n        for (const [name, value] of Object.entries(headers ?? {})) {\n          // Skipped, not overridden: the multipart boundary is generated with the body and cannot be restated.\n          if (name.toLowerCase() === 'content-type') continue;\n          request.setRequestHeader(name, value);\n        }\n\n        request.upload.addEventListener('progress', (event: ProgressEvent) => {\n          onProgress(event.loaded, event.lengthComputable ? event.total : undefined);\n        });\n\n        request.addEventListener('load', () => {\n          settle(() => {\n            const { status, responseText } = request;\n            if (status >= 200 && status < 300) {\n              resolve(parseResponseBody(responseText) as TResult);\n              return;\n            }\n            reject(new UploadHttpError(status, `Upload of \"${file.name}\" failed with status ${status}.`, responseText));\n          });\n        });\n\n        request.addEventListener('error', () => {\n          // Status `0` — the request never reached a response. The default retry policy treats it as transient.\n          settle(() => reject(new UploadHttpError(0, `Upload of \"${file.name}\" failed: network error.`)));\n        });\n\n        request.addEventListener('timeout', () => {\n          settle(() => reject(new UploadHttpError(0, `Upload of \"${file.name}\" timed out.`)));\n        });\n\n        request.addEventListener('abort', () => {\n          settle(() => reject(createAbortError()));\n        });\n\n        signal.addEventListener('abort', onAbort, { once: true });\n        request.send(body);\n      });\n    },\n  };\n}\n","// The scheduler — the headless core of the uploads vector. Owns admission (validate), ordering, a bounded\n// concurrency pool, retry, cancellation, and progress aggregation. Framework-free (no Vue import) so it can be\n// created at module scope, inside a provider, or in a plain node test; `UseUploadQueue.ts` is the Vue seam on\n// top, exactly as `commands` splits `CommandRegistry` from `useCommandRegistry`.\n//\n// THE CONTRACT: NOTHING HERE THROWS AT THE CALLER. A transport that rejects, a transport that throws\n// synchronously, a cancelled attempt, and a file rejected up front are all NORMAL OUTCOMES that land on an item's\n// `status` and leave the pool running. A queue whose `add` could throw would force a try/catch around a drop\n// handler, and one failing file would take down the other nine.\n//\n// Non-obvious decisions:\n// - RETRY MATH IS NOT WRITTEN HERE. `shouldRetry` decides, `computeRetryDelay` sizes the wait, both from\n//   `foundation/resilience` — the same primitives `foundation/http`'s client and `/query` use, so an upload backs\n//   off identically to every other request in the app. The only timing code below is a plain abortable\n//   `setTimeout`, which schedules the delay it is handed; it never computes one.\n// - `shouldRetry` is status-driven, so a transport failure is read for a numeric `status`\n//   (`readUploadErrorStatus`). No status ⇒ `0` ⇒ transient under the default policy: a dropped connection retries,\n//   a `413` does not. That is the correct default for uploads, where the payload is unchanged by a retry.\n// - A CANCELLED UPLOAD IS NEVER RETRIED. `isAbortError` (plus a direct `signal.aborted` check, for a transport\n//   that rejects with something else) short-circuits before the retry decision. Retrying a cancel would make the\n//   button lie.\n// - An item stays `uploading` THROUGH its backoff wait, holding its concurrency slot. Freeing the slot would let\n//   a queue of failing files spawn unbounded parallel waiters and defeat the cap.\n// - Progress is normalized on the RATIO the transport reports, not its raw `loaded`: a multipart body is bigger\n//   than the file (boundary + headers), so `loaded` alone would overshoot `file.size`.\n// - `version()` exists for the subscribing composable: `items()` builds a fresh array per call, so it can never\n//   be the tracked value (identity changes on every read). The monotonic counter is the stable cursor; items\n//   themselves are swapped immutably so a row can key on item identity.\n// - Every mutation notifies, including each progress event. A chatty transport therefore means frequent\n//   listeners; throttle in YOUR listener if that matters — the queue will not silently drop state changes.\n// - `patch` is a no-op for an unknown id. An in-flight upload whose item was `remove`d or `clear`ed keeps running\n//   until its abort lands, and its late writes must not resurrect a deleted row.\n\nimport { isAbortError, toError } from '../errors';\nimport { fileExtension, matchesAccept, safeFileName } from '../files';\nimport { formatBytes } from '../formatters';\nimport { Guid } from '../identifiers';\nimport { DefaultRetryPolicy, computeRetryDelay, shouldRetry, type RetryPolicy } from '../resilience';\n\nimport { UploadRejectionReason, UploadStatus, isUploadTerminal, type UploadItem } from './UploadItem';\nimport { readUploadErrorStatus, type UploadTransport } from './UploadTransport';\n\n/** The default number of uploads in flight — enough to saturate a connection without starving the rest of the app. */\nexport const DefaultUploadConcurrency = 3;\n\n/** Notified after a queue mutation — admission, status change, progress, removal. No payload; re-read the queue. */\nexport type UploadQueueListener = () => void;\n\n/** Configures a queue at creation. Only `transport` is required. */\nexport interface UploadQueueOptions<TResult = unknown> {\n  /** How a file is actually sent. The queue never assumes `fetch` or `XMLHttpRequest`; see {@link UploadTransport}. */\n  readonly transport: UploadTransport<TResult>;\n\n  /** Max uploads in flight. Defaults to {@link DefaultUploadConcurrency}; values below `1` are clamped up. */\n  readonly concurrency?: number;\n\n  /** An `accept`-attribute list (`image/*,.pdf`) admitted files must match, via `foundation/files`' `matchesAccept`. */\n  readonly accept?: string;\n\n  /** The largest admitted file, in bytes. A larger file is rejected up front rather than queued. */\n  readonly maxSize?: number;\n\n  /** The retry policy for failed attempts, or `false` to fail on the first error. Defaults to `DefaultRetryPolicy`. */\n  readonly retry?: RetryPolicy | false;\n}\n\n/** Describes the queue as a whole — what a summary bar renders without walking the item list. */\nexport interface UploadQueueState {\n  /** How many items the queue holds, in any status. */\n  readonly total: number;\n\n  /** How many items sit in each status. A file rejected up front counts under `failed`. */\n  readonly counts: Readonly<Record<UploadStatus, number>>;\n\n  /** Aggregate progress `0`–`1`, byte-weighted over in-play items. `0` when nothing is in play. */\n  readonly progress: number;\n\n  /** Total bytes uploaded across in-play items. */\n  readonly bytesUploaded: number;\n\n  /**\n   * Total bytes of in-play items — everything except cancelled items and files rejected up front, whose bytes\n   * will never arrive and would otherwise pin `progress` below `1` forever.\n   */\n  readonly totalBytes: number;\n\n  /** Whether any item is still queued or uploading. */\n  readonly isUploading: boolean;\n}\n\n/** The headless upload store — admission, scheduling, cancellation, retry, and change notification. */\nexport interface UploadQueue<TResult = unknown> {\n  /**\n   * Admits one file or many, returning the new item ids in the order given. Always returns an array, including\n   * for a single file. A file failing `accept` / `maxSize` still gets an id — as a `failed` item carrying a\n   * `rejection` — so the caller can render why. Never throws.\n   */\n  readonly add: (input: File | ReadonlyArray<File>) => ReadonlyArray<string>;\n\n  /**\n   * Aborts an item. A queued item flips to `cancelled` immediately; an uploading one is aborted through its\n   * signal and settles `cancelled` once the transport unwinds (asynchronously). Reports whether anything was\n   * cancellable — `false` for an unknown id or an already-terminal item.\n   */\n  readonly cancel: (id: string) => boolean;\n\n  /** Aborts every queued and uploading item. In-flight ones settle asynchronously, as with {@link cancel}. */\n  readonly cancelAll: () => void;\n\n  /**\n   * Re-queues a `failed` or `cancelled` item for another run; `attempt` continues from where it stopped.\n   * Refuses (`false`) an item rejected up front — re-sending an oversized file cannot change the verdict.\n   */\n  readonly retry: (id: string) => boolean;\n\n  /** Drops an item, aborting it first when in flight (nothing would be listening for its result). */\n  readonly remove: (id: string) => boolean;\n\n  /** Drops every item, cancelling anything still in flight. */\n  readonly clear: () => void;\n\n  /** Every item in admission order. Fresh array per call — never track it directly; track `version()` instead. */\n  readonly items: () => readonly UploadItem<TResult>[];\n\n  /** Looks up one item — `undefined` when absent. Item identity is stable between changes to that item. */\n  readonly get: (id: string) => UploadItem<TResult> | undefined;\n\n  /** The aggregate snapshot — counts, byte totals, overall progress. Fresh object per call. */\n  readonly state: () => UploadQueueState;\n\n  /** Subscribes to mutations; returns an unsubscribe. */\n  readonly subscribe: (listener: UploadQueueListener) => () => void;\n\n  /** A monotonic counter bumped on every mutation — the stable-identity snapshot the composables subscribe to. */\n  readonly version: () => number;\n}\n\n/** Waits `ms`, resolving early (never rejecting) if `signal` aborts. The caller re-checks `signal.aborted` after. */\nfunction sleep(ms: number, signal: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve) => {\n    if (signal.aborted) {\n      resolve();\n      return;\n    }\n    // `finish` closes over `timer` declared below it: legal because it only ever runs after both are initialized\n    // (as the timer's own callback, or as an abort listener attached last).\n    const finish = (): void => {\n      clearTimeout(timer);\n      signal.removeEventListener('abort', finish);\n      resolve();\n    };\n    const timer = setTimeout(finish, ms);\n    signal.addEventListener('abort', finish, { once: true });\n  });\n}\n\n/**\n * Creates an {@link UploadQueue}. One per upload surface is the norm; create extra ones to isolate a modal's\n * uploads from a background set, or per test.\n */\nexport function createUploadQueue<TResult = unknown>(options: UploadQueueOptions<TResult>): UploadQueue<TResult> {\n  const { transport, accept, maxSize } = options;\n  const requestedConcurrency = options.concurrency ?? DefaultUploadConcurrency;\n  const concurrency = Number.isFinite(requestedConcurrency)\n    ? Math.max(1, Math.floor(requestedConcurrency))\n    : DefaultUploadConcurrency;\n  const retryPolicy: RetryPolicy | false = options.retry ?? DefaultRetryPolicy;\n\n  const entries = new Map<string, UploadItem<TResult>>();\n  /** The in-flight set — one controller per running attempt. Its size IS the concurrency count. */\n  const controllers = new Map<string, AbortController>();\n  const listeners = new Set<UploadQueueListener>();\n  let revision = 0;\n  let pumping = false;\n\n  /** Bumps the version then fans out over a copy, so a listener may unsubscribe while being notified. */\n  function notify(): void {\n    revision += 1;\n    for (const listener of [...listeners]) listener();\n  }\n\n  /** Replaces an item with a changed copy and notifies. Silently drops writes for an id that is no longer queued. */\n  function patch(id: string, changes: Partial<Omit<UploadItem<TResult>, 'id' | 'file'>>): void {\n    const current = entries.get(id);\n    if (current === undefined) return;\n    entries.set(id, { ...current, ...changes });\n    notify();\n  }\n\n  /** Names a file's type for a rejection message — the MIME type, or the extension when the browser gave none. */\n  function describeFileType(file: File): string {\n    if (file.type !== '') return file.type;\n    const extension = fileExtension(file.name);\n    return extension === '' ? 'of an unknown type' : `a \".${extension}\" file`;\n  }\n\n  /** Applies the admission rules. `undefined` = admitted. */\n  function validate(file: File): UploadRejectionReason | undefined {\n    if (accept !== undefined && !matchesAccept(file, accept)) return UploadRejectionReason.Type;\n    if (maxSize !== undefined && file.size > maxSize) return UploadRejectionReason.Size;\n    return undefined;\n  }\n\n  /** Builds the user-facing rejection reason. The name is sanitized — attacker-controlled text headed for a UI. */\n  function rejectionError(file: File, reason: UploadRejectionReason): Error {\n    const name = safeFileName(file.name);\n    if (reason === UploadRejectionReason.Size) {\n      return new Error(`\"${name}\" is ${formatBytes(file.size)}, over the ${formatBytes(maxSize ?? 0)} limit.`);\n    }\n    return new Error(`\"${name}\" is ${describeFileType(file)}, which does not match \"${accept ?? ''}\".`);\n  }\n\n  /** Records a transport progress report, normalized onto `file.size` (see the ratio note in the header). */\n  function recordProgress(id: string, loaded: number, total?: number): void {\n    const current = entries.get(id);\n    if (current === undefined || current.status !== UploadStatus.Uploading) return;\n\n    const size = current.file.size;\n    const denominator = total !== undefined && total > 0 ? total : size;\n    const fraction = denominator > 0 ? Math.min(1, Math.max(0, loaded / denominator)) : 0;\n    const bytesUploaded = Math.round(fraction * size);\n\n    // Transports re-fire identical events; skipping the no-op keeps a listener from waking for nothing.\n    if (fraction === current.progress && bytesUploaded === current.bytesUploaded) return;\n    patch(id, { progress: fraction, bytesUploaded });\n  }\n\n  /**\n   * Runs one item to a terminal state: attempt → retry loop → settle. Never rejects; every exit path is a status.\n   * Holds a slot in `controllers` for its whole life, backoff waits included, and pumps the next item on exit.\n   */\n  async function runItem(id: string): Promise<void> {\n    const initial = entries.get(id);\n    if (initial === undefined) return;\n\n    // Attempts already spent in earlier run cycles — a manual `retry()` continues the count, never resets it.\n    const baseAttempt = initial.attempt;\n    const controller = new AbortController();\n    controllers.set(id, controller);\n\n    let retries = 0;\n    let previousDelayMs = 0;\n\n    try {\n      for (;;) {\n        const current = entries.get(id);\n        if (current === undefined) return;\n\n        patch(id, {\n          status: UploadStatus.Uploading,\n          attempt: baseAttempt + retries + 1,\n          progress: 0,\n          bytesUploaded: 0,\n          error: undefined,\n        });\n\n        try {\n          const result = await transport.upload(current.file, {\n            signal: controller.signal,\n            onProgress: (loaded: number, total?: number) => recordProgress(id, loaded, total),\n          });\n          // A transport that ignores its signal can still resolve after a cancel; the user's intent wins.\n          if (controller.signal.aborted) {\n            patch(id, { status: UploadStatus.Cancelled });\n            return;\n          }\n          patch(id, {\n            status: UploadStatus.Succeeded,\n            progress: 1,\n            bytesUploaded: current.file.size,\n            result,\n          });\n          return;\n        } catch (caught) {\n          if (isAbortError(caught) || controller.signal.aborted) {\n            patch(id, { status: UploadStatus.Cancelled });\n            return;\n          }\n\n          const status = readUploadErrorStatus(caught);\n          if (retryPolicy !== false && shouldRetry(retryPolicy, retries, status)) {\n            const attemptNumber = retries + 1;\n            const delayMs = computeRetryDelay(retryPolicy, attemptNumber, previousDelayMs);\n            retryPolicy.onRetry?.({ attempt: attemptNumber, error: caught, status, delayMs });\n            await sleep(delayMs, controller.signal);\n            if (controller.signal.aborted) {\n              patch(id, { status: UploadStatus.Cancelled });\n              return;\n            }\n            previousDelayMs = delayMs;\n            retries = attemptNumber;\n            continue;\n          }\n\n          patch(id, { status: UploadStatus.Failed, error: toError(caught) });\n          return;\n        }\n      }\n    } finally {\n      controllers.delete(id);\n      pump();\n    }\n  }\n\n  /**\n   * Starts queued items until the pool is full. Re-entrancy-guarded: `runItem`'s `finally` pumps again, and a\n   * transport that throws synchronously would otherwise recurse once per queued item.\n   */\n  function pump(): void {\n    if (pumping) return;\n    pumping = true;\n    try {\n      while (controllers.size < concurrency) {\n        let next: UploadItem<TResult> | undefined;\n        for (const item of entries.values()) {\n          if (item.status === UploadStatus.Queued) {\n            next = item;\n            break;\n          }\n        }\n        if (next === undefined) return;\n        void runItem(next.id);\n      }\n    } finally {\n      pumping = false;\n    }\n  }\n\n  /** Builds the item an admitted or rejected file starts life as. */\n  function createItem(file: File): UploadItem<TResult> {\n    const id = Guid.createV7() as string;\n    const rejection = validate(file);\n    if (rejection !== undefined) {\n      return {\n        id,\n        file,\n        status: UploadStatus.Failed,\n        progress: 0,\n        bytesUploaded: 0,\n        attempt: 0,\n        rejection,\n        error: rejectionError(file, rejection),\n      };\n    }\n    return { id, file, status: UploadStatus.Queued, progress: 0, bytesUploaded: 0, attempt: 0 };\n  }\n\n  function cancel(id: string): boolean {\n    const item = entries.get(id);\n    if (item === undefined || isUploadTerminal(item.status)) return false;\n\n    const controller = controllers.get(id);\n    if (controller !== undefined) {\n      // The status flips inside `runItem` once the transport unwinds — cancellation is inherently async.\n      controller.abort();\n      return true;\n    }\n    patch(id, { status: UploadStatus.Cancelled });\n    pump();\n    return true;\n  }\n\n  /** Hoisted out of the returned object so `clear` can call it without a `this` binding (the API is destructurable). */\n  function cancelAll(): void {\n    for (const item of [...entries.values()]) {\n      if (!isUploadTerminal(item.status)) cancel(item.id);\n    }\n  }\n\n  return {\n    add(input: File | ReadonlyArray<File>): ReadonlyArray<string> {\n      const files = input instanceof File ? [input] : input;\n      const created = files.map(createItem);\n      for (const item of created) entries.set(item.id, item);\n      // ONE notification for the whole admission — dropping ten files notifies once, not ten times. The `pump`\n      // below then adds one more per item it actually starts, since each of those is a real status change.\n      notify();\n      pump();\n      return created.map((item) => item.id);\n    },\n\n    cancel,\n\n    cancelAll,\n\n    retry(id: string): boolean {\n      const item = entries.get(id);\n      if (item === undefined || item.rejection !== undefined) return false;\n      if (item.status !== UploadStatus.Failed && item.status !== UploadStatus.Cancelled) return false;\n\n      patch(id, {\n        status: UploadStatus.Queued,\n        progress: 0,\n        bytesUploaded: 0,\n        error: undefined,\n        result: undefined,\n      });\n      pump();\n      return true;\n    },\n\n    remove(id: string): boolean {\n      if (!entries.has(id)) return false;\n      controllers.get(id)?.abort();\n      entries.delete(id);\n      notify();\n      pump();\n      return true;\n    },\n\n    clear(): void {\n      entries.clear();\n      // A slot belongs to the transport until it settles, even when its item has been removed.\n      for (const controller of controllers.values()) controller.abort();\n      notify();\n    },\n\n    items(): ReadonlyArray<UploadItem<TResult>> {\n      return [...entries.values()];\n    },\n\n    get(id: string): UploadItem<TResult> | undefined {\n      return entries.get(id);\n    },\n\n    state(): UploadQueueState {\n      const counts: Record<UploadStatus, number> = {\n        [UploadStatus.Queued]: 0,\n        [UploadStatus.Uploading]: 0,\n        [UploadStatus.Succeeded]: 0,\n        [UploadStatus.Failed]: 0,\n        [UploadStatus.Cancelled]: 0,\n      };\n\n      let bytesUploaded = 0;\n      let totalBytes = 0;\n      for (const item of entries.values()) {\n        counts[item.status] += 1;\n        // Cancelled + rejected bytes are excluded from both sides — they are never arriving.\n        if (item.status === UploadStatus.Cancelled || item.rejection !== undefined) continue;\n        bytesUploaded += item.bytesUploaded;\n        totalBytes += item.file.size;\n      }\n\n      return {\n        total: entries.size,\n        counts,\n        bytesUploaded,\n        totalBytes,\n        progress: totalBytes > 0 ? Math.min(1, bytesUploaded / totalBytes) : 0,\n        isUploading: counts[UploadStatus.Queued] > 0 || counts[UploadStatus.Uploading] > 0,\n      };\n    },\n\n    subscribe(listener: UploadQueueListener): () => void {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n\n    version(): number {\n      return revision;\n    },\n  };\n}\n","// The Vue subscription seam over a queue — how a component updates as uploads progress. Mirrors `commands`'\n// `UseCommandRegistry.ts`: the store is framework-free, this file is the only part that imports Vue.\n//\n// Non-obvious decisions:\n// - These track `queue.version()` as the subscription snapshot, NOT `items()` / `state()`. Both build a fresh\n//   value per call, so either as the snapshot would look changed on every read. The monotonic counter is\n//   identity-stable between mutations; the arrays and the aggregate derive from it through a `computed`.\n// - The subscription is attached in `onMounted` and dropped in `onScopeDispose`, the same shape\n//   `foundation/device`' `useMediaQuery` uses. The queue is plain in-memory state with no client-only source, so\n//   the SSR pass reads a correct version rather than a placeholder — the mount hook exists for the listener, not\n//   for a platform global.\n// - `useUploadQueueSnapshot(queue)` takes the queue EXPLICITLY, so an app that owns a module-scope queue (uploads\n//   that must survive tearing down the panel) can subscribe without this file creating anything.\n// - `useUploadQueue(options)` is the convenience on top and creates its queue ONCE, at setup — the queue holds\n//   in-flight work, so rebuilding it on a changed option would strand running uploads. Consequence, stated\n//   plainly: `concurrency` / `accept` / `maxSize` / `retry` are read at SETUP and later changes are ignored.\n//   Need them dynamic → own the queue and re-create it deliberately.\n// - `transport` is the exception: it is delegated through `toValue`, so an inline `{ upload: ... }` closing over\n//   current props stays live instead of being frozen at setup. Same trick `provideCommands` uses for `onError`,\n//   and it is what makes the common inline call site correct without any memoization by the caller.\n// - The action callbacks are the queue's own methods, already referentially stable, so nothing wraps them.\n\nimport {\n  computed,\n  onMounted,\n  onScopeDispose,\n  shallowRef,\n  toValue,\n  type ComputedRef,\n  type MaybeRefOrGetter,\n  type ShallowRef,\n} from 'vue';\n\nimport type { UploadItem } from './UploadItem';\nimport { createUploadQueue, type UploadQueue, type UploadQueueOptions, type UploadQueueState } from './UploadQueue';\n\n/**\n * Subscribes to a queue's mutations and returns its version counter. The building block behind\n * {@link useUploadQueueSnapshot}; use it directly to derive a custom projection\n * (`computed(() => (version.value, queue.items().filter(failed)))`).\n */\nexport function useUploadQueueVersion<TResult = unknown>(queue: UploadQueue<TResult>): Readonly<ShallowRef<number>> {\n  const version = shallowRef(queue.version());\n\n  let unsubscribe: (() => void) | undefined;\n\n  onMounted(() => {\n    // Re-read first: a mutation between setup and mount would otherwise be missed entirely.\n    version.value = queue.version();\n    unsubscribe = queue.subscribe(() => {\n      version.value = queue.version();\n    });\n  });\n\n  onScopeDispose(() => {\n    unsubscribe?.();\n    unsubscribe = undefined;\n  });\n\n  return version;\n}\n\n/** The item list plus the aggregate state of an explicitly-owned queue, updating the caller on every change. */\nexport function useUploadQueueSnapshot<TResult = unknown>(\n  queue: UploadQueue<TResult>,\n): {\n  readonly items: ComputedRef<ReadonlyArray<UploadItem<TResult>>>;\n  readonly state: ComputedRef<UploadQueueState>;\n} {\n  const version = useUploadQueueVersion(queue);\n  // `version` is the mutation cursor that invalidates both reads — touched, then discarded.\n  return {\n    items: computed(() => {\n      void version.value;\n      return queue.items();\n    }),\n    state: computed(() => {\n      void version.value;\n      return queue.state();\n    }),\n  };\n}\n\n/** What {@link useUploadQueue} hands a component — live state plus every queue action. */\nexport interface UseUploadQueueControls<TResult = unknown> {\n  /** The underlying queue, for anything the flattened actions don't cover (`get`, `subscribe`, passing it down). */\n  readonly queue: UploadQueue<TResult>;\n\n  /** Every item in admission order, refreshed on each change. */\n  readonly items: ComputedRef<ReadonlyArray<UploadItem<TResult>>>;\n\n  /** The aggregate snapshot — counts, byte totals, overall progress. */\n  readonly state: ComputedRef<UploadQueueState>;\n\n  /** Admits one file or many; returns the new item ids. See `UploadQueue.add`. */\n  readonly add: UploadQueue<TResult>['add'];\n\n  /** Aborts one item. See `UploadQueue.cancel`. */\n  readonly cancel: UploadQueue<TResult>['cancel'];\n\n  /** Aborts every queued and uploading item. */\n  readonly cancelAll: UploadQueue<TResult>['cancelAll'];\n\n  /** Re-queues a failed or cancelled item. */\n  readonly retry: UploadQueue<TResult>['retry'];\n\n  /** Drops an item, aborting it first when in flight. */\n  readonly remove: UploadQueue<TResult>['remove'];\n\n  /** Drops every item, cancelling anything still in flight. */\n  readonly clear: UploadQueue<TResult>['clear'];\n}\n\n/**\n * Creates an upload queue scoped to the component and subscribes to it — the one-call entry point for an upload\n * panel or drop zone.\n *\n * The queue is created at setup and kept for the scope's lifetime, so `concurrency` / `accept` / `maxSize` /\n * `retry` are setup-time values (`transport` stays live — see the file header). Disposal does NOT cancel\n * in-flight uploads; call `cancelAll` from `onScopeDispose` if that is the behaviour you want, or hoist the\n * queue out of the component with `createUploadQueue` + {@link useUploadQueueSnapshot} so uploads survive it.\n *\n * @param options Queue configuration. A ref or getter keeps `transport` live; the rest is read once.\n */\nexport function useUploadQueue<TResult = unknown>(\n  options: MaybeRefOrGetter<UploadQueueOptions<TResult>>,\n): UseUploadQueueControls<TResult> {\n  const queue = createUploadQueue<TResult>({\n    ...toValue(options),\n    // Delegated, not captured: the current transport handles every attempt.\n    transport: { upload: (file, context) => toValue(options).transport.upload(file, context) },\n  });\n\n  onScopeDispose(queue.clear);\n  const { items, state } = useUploadQueueSnapshot(queue);\n\n  return {\n    queue,\n    items,\n    state,\n    add: queue.add,\n    cancel: queue.cancel,\n    cancelAll: queue.cancelAll,\n    retry: queue.retry,\n    remove: queue.remove,\n    clear: queue.clear,\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/validators/Composites.d.ts

@@ -0,0 +1,71 @@
+import { Validator, Infer, InferInput } from './Validator';
+/** A map of property name to the validator for that property. */
+export type ObjectShape = Readonly<Record<string, Validator<unknown>>>;
+/** Flattens an intersection into a single readable object type in editor tooltips and `.d.ts` output. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+};
+/** Keys whose validator admits `undefined` — these become optional properties on the output type. */
+type OptionalKeys<TShape extends ObjectShape> = {
+    [K in keyof TShape]-?: undefined extends Infer<TShape[K]> ? K : never;
+}[keyof TShape];
+/** Keys whose validator requires a value. */
+type RequiredKeys<TShape extends ObjectShape> = Exclude<keyof TShape, OptionalKeys<TShape>>;
+/**
+ * The object type a shape validates to. A member built with `.optional()` becomes an optional PROPERTY
+ * (`name?: string`), not merely `name: string | undefined`, so the output type matches what the runtime
+ * actually produces — an absent optional key stays absent.
+ */
+export type InferObject<TShape extends ObjectShape> = Prettify<{
+    [K in RequiredKeys<TShape>]: Infer<TShape[K]>;
+} & {
+    [K in OptionalKeys<TShape>]?: Infer<TShape[K]>;
+}>;
+/** The tuple type a fixed-length list of validators validates to. */
+export type InferTuple<TValidators extends readonly unknown[]> = {
+    -readonly [K in keyof TValidators]: Infer<TValidators[K]>;
+};
+/** Input object shape, preserving optional/defaulted inputs independently of output. */
+export type InferObjectInput<TShape extends ObjectShape> = Prettify<{
+    [K in keyof TShape as undefined extends InferInput<TShape[K]> ? never : K]: InferInput<TShape[K]>;
+} & {
+    [K in keyof TShape as undefined extends InferInput<TShape[K]> ? K : never]?: InferInput<TShape[K]>;
+}>;
+export type InferTupleInput<TValidators extends readonly unknown[]> = {
+    -readonly [K in keyof TValidators]: InferInput<TValidators[K]>;
+};
+/** A validator for arrays of `TItem`, carrying the length refinements. */
+export declare class ArrayValidator<TItem, TItemInput = TItem> extends Validator<TItem[], TItemInput[]> {
+    /** Requires at least `limit` items. */
+    min(limit: number, message?: string): this;
+    /** Requires at most `limit` items. */
+    max(limit: number, message?: string): this;
+    /** Requires exactly `exact` items. */
+    length(exact: number, message?: string): this;
+}
+/**
+ * Validates an object against a shape, reporting every failing property. Unknown keys are STRIPPED: the
+ * output carries only declared properties, so a validated payload cannot smuggle extra fields past the
+ * boundary into storage or a log.
+ */
+export declare function object<TShape extends ObjectShape>(shape: TShape, message?: string): Validator<InferObject<TShape>, InferObjectInput<TShape>>;
+/** Validates every item against `item`, reporting each failure at its own index. */
+export declare function array<TItem, TItemInput>(item: Validator<TItem, TItemInput>, message?: string): ArrayValidator<TItem, TItemInput>;
+/**
+ * Validates every value of an open-keyed object against `value`, reporting each failure under its key.
+ * Keys are not validated — only own enumerable string keys are visited, which is what `Object.entries`
+ * gives and what a JSON payload can carry.
+ */
+export declare function record<TValue, TInput>(value: Validator<TValue, TInput>, message?: string): Validator<Record<string, TValue>, Record<string, TInput>>;
+/**
+ * Accepts a value matching any one of `validators`, tried in order — the first match wins, so order
+ * matters when branches overlap. A total failure reports ONE issue naming the alternatives rather than
+ * every branch's issues; see the header note.
+ */
+export declare function union<const TValidators extends readonly Validator<unknown>[]>(validators: TValidators, message?: string): Validator<Infer<TValidators[number]>, InferInput<TValidators[number]>>;
+/**
+ * Validates a fixed-length, positionally-typed array. A length mismatch is reported once at the tuple's
+ * own path; a wrong element type is reported at that element's index.
+ */
+export declare function tuple<const TValidators extends readonly Validator<unknown>[]>(validators: TValidators, message?: string): Validator<InferTuple<TValidators>, InferTupleInput<TValidators>>;
+export {};

package/dist/foundation/validators/Messages.d.ts

@@ -0,0 +1,69 @@
+/** A field-level failure widened to carry its machine tag — the channel a catalogue can key on. */
+export interface FieldIssue {
+    /** The authoring or server message. Always present; used verbatim when no catalogue entry matches. */
+    readonly message: string;
+    /** The normalized rule code (`required`, `min`, `pattern`, …). Absent when the source reported none. */
+    readonly code?: string;
+    /** The rule's own operands (`{ max: 50 }`), normalized to the vocabulary's names. */
+    readonly params?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The rule codes this ecosystem speaks. The client's own validators report a subset (`type`, `min`,
+ * `pattern`, …); the rest arrive from the server. Kept as one flat union because a catalogue keys on it
+ * and a split would mean two lookups for one concept.
+ */
+export declare const ValidationCodes: readonly ["required", "type", "mustBeNull", "mustBeEmpty", "min", "max", "length", "integer", "precision", "greaterThan", "lessThan", "between", "betweenExclusive", "equal", "notEqual", "literal", "oneOf", "union", "pattern", "email", "url", "uuid", "isoDate", "creditCard", "custom", "transform", "internal"];
+/** A member of the shared rule-code vocabulary. */
+export type ValidationCode = (typeof ValidationCodes)[number];
+/**
+ * Maps FluentValidation's `ErrorCode` onto the shared vocabulary. Covers the built-in validators whose
+ * failures reach a form; anything absent falls through with its raw code, which simply misses the
+ * catalogue and renders the server's own message.
+ */
+export declare const FluentValidationCodes: Readonly<Record<string, ValidationCode>>;
+/**
+ * Maps FluentValidation's message placeholders onto the vocabulary's param names, so one catalogue entry
+ * reads the same operand whichever side reported it. Unlisted placeholders pass through unchanged —
+ * `PropertyName` deliberately among them, since the label is resolved from the form, not the payload.
+ */
+export declare const FluentValidationParameters: Readonly<Record<string, string>>;
+/** What a catalogue entry renders from. */
+export interface ValidationMessageContext {
+    /** The normalized rule code that failed. */
+    readonly code: string;
+    /** The rule's operands, vocabulary-named. Empty when the source reported none. */
+    readonly params: Readonly<Record<string, unknown>>;
+    /** The form path the failure is filed under; `''` for a form-level failure. */
+    readonly path: string;
+    /** The field's display label, when the form named one. Absent means render label-free. */
+    readonly label?: string;
+    /** The originating message — return this to defer to the source. */
+    readonly message: string;
+}
+/** Renders one rule code into user-facing text. */
+export type ValidationMessageEntry = (context: ValidationMessageContext) => string;
+/** A code → renderer table. Partial by design: an unlisted code falls back to the source's message. */
+export type ValidationMessageCatalogue = Readonly<Record<string, ValidationMessageEntry>>;
+/** Resolves one issue at one path into the string a field renders. */
+export type ResolveValidationMessage = (issue: FieldIssue, path: string) => string;
+/**
+ * The English voice for the vocabulary. Entries are FRAGMENTS, not sentences — a field message renders
+ * under its own labelled control, so "must be at least 2 characters" reads correctly and repeating the
+ * label there is noise. A form that supplies `labels` gets the label prefixed by `createMessageResolver`,
+ * which is the form-level and cross-field case where the fragment alone would be unaddressed.
+ *
+ * An entry that cannot render (its operand never arrived) returns `context.message`, so a half-populated
+ * payload degrades to the source's wording instead of to "must be at most undefined".
+ */
+export declare const defaultValidationMessages: ValidationMessageCatalogue;
+/**
+ * Builds the resolver the form engines call for every message they are about to render.
+ *
+ * Resolution order per issue: the caller's catalogue → {@link defaultValidationMessages} → the issue's
+ * own message. A known label is prefixed to the rendered fragment; an unlabelled field renders the
+ * fragment alone, which is what every message in this SDK did before a catalogue existed.
+ *
+ * `catalogue` is MERGED over the defaults rather than replacing them, so overriding one code's wording —
+ * or translating a handful — never silently drops the rest of the vocabulary.
+ */
+export declare function createMessageResolver(catalogue?: ValidationMessageCatalogue, labels?: Readonly<Record<string, string>>): ResolveValidationMessage;

package/dist/foundation/validators/ValidationError.d.ts

@@ -0,0 +1,14 @@
+import { ValidationIssue } from './ValidationOutcome';
+import { Validator } from './Validator';
+/** The error `assertValid` throws, carrying every issue found rather than only the summarized first. */
+export declare class ValidationError extends Error {
+    /** Every issue from the failed run, in traversal order, each with its own path. */
+    readonly issues: ReadonlyArray<ValidationIssue>;
+    /** Wraps the issues; `message` overrides the generated summary when a call site has better copy. */
+    constructor(issues: ReadonlyArray<ValidationIssue>, message?: string);
+}
+/**
+ * Validates `value` and returns the parsed output, throwing `ValidationError` if it fails. The typed
+ * escape hatch for callers that want a throw — everything else in this slice stays total.
+ */
+export declare function assertValid<TOutput>(validator: Validator<TOutput>, value: unknown): TOutput;

package/dist/foundation/validators/ValidationOutcome.d.ts

@@ -0,0 +1,40 @@
+import { ValidatorParseResult } from './models/ValidatorParseResult';
+/** A single segment of an issue path — an object key or an array index. */
+export type PathSegmentKey = string | number;
+/** One reason a value was rejected, addressed at the exact spot it failed. */
+export interface ValidationIssue {
+    /** Location of the failure relative to the validated root: `['items', 0, 'name']`. Empty at the root. */
+    readonly path: ReadonlyArray<PathSegmentKey>;
+    /** Human-readable, display-ready explanation of the failure. Never contains the rejected value. */
+    readonly message: string;
+    /** Stable machine tag for the rule that failed (`type`, `min`, `pattern`, `union`, `custom`, …). */
+    readonly code?: string;
+    /**
+     * The rule's own operands — `{ min: 2, unit: 'characters' }` for `string().min(2)`.
+     *
+     * Present so a message CATALOGUE can re-render the failure in another voice or another language
+     * (`Messages.ts`). `message` already reads correctly on its own; without the operands beside it, a
+     * catalogue could only ever emit parameterless text, which is a catalogue that cannot replace the
+     * message it exists to replace. Holds operands only — never the rejected value, for the same reason
+     * `describeType` exists.
+     */
+    readonly params?: Readonly<Record<string, unknown>>;
+}
+export type { ValidationFailure } from './models/ValidationFailure';
+export type { ValidatorParseResult } from './models/ValidatorParseResult';
+/** Builds a success carrying the parsed output. */
+export declare function valid<T>(value: T): ValidatorParseResult<T>;
+/** Builds a display-safe failure preserving every field issue. */
+export declare function invalid<T>(issues: ReadonlyArray<ValidationIssue>): ValidatorParseResult<T>;
+/**
+ * Names a value's type for an error message. Total and hostile-input safe: a `Proxy` may trap
+ * `getPrototypeOf` (which `instanceof` calls) and throw, so the object probes are guarded — a message
+ * is never worth a second failure. `NaN` reports as `NaN` rather than `number`, since "expected number,
+ * received number" reads as a bug.
+ */
+export declare function describeType(value: unknown): string;
+/**
+ * Renders an issue path in the familiar display form: `['items', 0, 'name']` → `items[0].name`.
+ * A root-level issue (empty path) renders as the empty string — callers decide how to label the root.
+ */
+export declare function formatIssuePath(path: ReadonlyArray<PathSegmentKey>): string;

package/dist/foundation/validators/Validator.d.ts

@@ -0,0 +1,76 @@
+import { StandardSchemaV1 } from './StandardSchema';
+import { PathSegmentKey, ValidatorParseResult } from './ValidationOutcome';
+/** Parses the value at a structured path. Expected failures are results; programmer errors may throw. */
+export type ParseFn<TOutput> = (value: unknown, path: ReadonlyArray<PathSegmentKey>) => ValidatorParseResult<TOutput>;
+/** The `vendor` reported by every validator's Standard Schema props. */
+export declare const ValidationVendor = "wow-two-beta";
+/** Extracts the output type of a validator: `Infer<typeof user>` → `{ name: string }`. */
+export type Infer<TValidator> = TValidator extends {
+    readonly __output: infer TOutput;
+} ? TOutput : never;
+/** Extracts the editable input type before transforms/defaults. */
+export type InferInput<TValidator> = TValidator extends {
+    readonly __input: infer TInput;
+} ? TInput : never;
+/** Converts a slice result into the Standard Schema result shape (`{ value }` or `{ issues }`). */
+export declare function toStandardResult<TOutput>(result: ValidatorParseResult<TOutput>): StandardSchemaV1.Result<TOutput>;
+/**
+ * A total, composable validator for one shape of value. Build one with `string()`, `object({…})`, etc.
+ * rather than constructing it directly; the constructor is public only so a caller can define a
+ * validator this slice does not ship.
+ */
+export declare class Validator<TOutput, TInput = TOutput> implements StandardSchemaV1<TInput, TOutput> {
+    /** Phantom carrier for `Infer`. Never assigned, never read — erased at compile time. */
+    readonly __output: TOutput;
+    readonly __input: TInput;
+    /** Human-facing name of the accepted shape, used in messages and in composite type names. */
+    readonly typeName: string;
+    /** Standard Schema props — lets this validator be handed to any spec consumer unchanged. */
+    readonly '~standard': StandardSchemaV1.Props<TInput, TOutput>;
+    /** The total parse function this validator wraps. */
+    protected readonly parseFn: ParseFn<TOutput>;
+    /** Wraps a parse function under a display name. Prefer the builders (`string()`, `object()`, …). */
+    constructor(typeName: string, parseFn: ParseFn<TOutput>);
+    /** Validates `value` from the root. Expected validation failures are results; caller code bugs remain exceptional. */
+    validate(value: unknown): ValidatorParseResult<TOutput>;
+    /**
+     * Validates `value` as if it sat at `path` inside a larger structure, so nested issues carry their
+     * full address. Composites call this to thread the path; prefer `validate` at ordinary call sites.
+     */
+    parseAt(value: unknown, path: ReadonlyArray<PathSegmentKey>): ValidatorParseResult<TOutput>;
+    /** Accepts `undefined` as-is; any other value must satisfy this validator. Widens to `TOutput | undefined`. */
+    optional(): Validator<TOutput | undefined, TInput | undefined>;
+    /** Accepts `null` as-is; any other value must satisfy this validator. Widens to `TOutput | null`. */
+    nullable(): Validator<TOutput | null, TInput | null>;
+    /**
+     * Substitutes `fallback` when the value is `undefined`, narrowing the output back to a defined type.
+     *
+     * `null` is NOT defaulted. An explicit `null` is a value the caller chose — in a JSON payload it means
+     * "known to be empty", which is different from "absent" — so it keeps flowing into this validator and
+     * is rejected unless the validator is also `.nullable()`. Matches zod's split.
+     */
+    default(fallback: Exclude<TOutput, undefined>): Validator<Exclude<TOutput, undefined>, TInput | undefined>;
+    /**
+     * Adds a custom check that runs only after this validator accepts the value, so `check` always sees a
+     * fully parsed `TOutput`. Returns the same validator class, keeping type-specific methods chainable.
+     * A thrown check indicates a programmer error and propagates.
+     *
+     * `params` carries the rule's operands onto the issue so a message catalogue can re-render it
+     * (`Messages.ts`). Pass the limits the check compares against, never the value it rejected.
+     */
+    refine(check: (value: TOutput) => boolean, message: string, code?: string, params?: Readonly<Record<string, unknown>>): this;
+    /**
+     * Maps the parsed value to another shape. Runs strictly AFTER validation, so `map` receives a valid
+     * `TOutput`. A thrown mapper indicates a programmer error and propagates. The result is a base
+     * `Validator<TNext, TInput>` — type-specific methods do not survive a change of output type.
+     */
+    transform<TNext>(map: (value: TOutput) => TNext): Validator<TNext, TInput>;
+    /** Rebuilds this validator's own class around a new parse function, keeping the chain's static type. */
+    protected derive(parseFn: ParseFn<TOutput>): this;
+}
+/**
+ * Presents a validator as a bare Standard Schema object. Every validator already implements the spec —
+ * this is sugar for a call site that reads better handing over a plain `{ '~standard': … }` than the
+ * whole validator (and for narrowing the surface a consumer sees).
+ */
+export declare function toStandardSchema<TOutput, TInput>(validator: Validator<TOutput, TInput>): StandardSchemaV1<TInput, TOutput>;

package/dist/foundation/validators/index.d.ts

@@ -0,0 +1,8 @@
+export { type PathSegmentKey, type ValidationIssue, type ValidatorParseResult, type ValidationFailure, valid, invalid, describeType, formatIssuePath, } from './ValidationOutcome';
+export { type StandardSchemaV1 } from './StandardSchema';
+export { type ParseFn, type Infer, type InferInput, Validator, ValidationVendor, toStandardResult, toStandardSchema, } from './Validator';
+export { StringValidator, NumberValidator, DateValidator, string, number, boolean, date, literal, oneOf, } from './Primitives';
+export { type ObjectShape, type InferObject, type InferTuple, ArrayValidator, object, array, record, union, tuple, } from './Composites';
+export { email, url, uuid, isoDate } from './Formats';
+export { ValidationError, assertValid } from './ValidationError';
+export { type FieldIssue, type ValidationCode, type ValidationMessageContext, type ValidationMessageEntry, type ValidationMessageCatalogue, type ResolveValidationMessage, ValidationCodes, FluentValidationCodes, FluentValidationParameters, defaultValidationMessages, createMessageResolver, } from './Messages';