@wow-two-beta/ui-vue 0.0.2

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

@@ -0,0 +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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"}

package/dist/foundation/utils/Align/Align.d.ts

@@ -0,0 +1,10 @@
+/** Defines the alignment of items along an axis. */
+export declare const Align: {
+    /** Refers to alignment at the logical start. */
+    readonly Start: "start";
+    /** Refers to centered alignment. */
+    readonly Center: "center";
+    /** Refers to alignment at the logical end. */
+    readonly End: "end";
+};
+export type Align = (typeof Align)[keyof typeof Align];

package/dist/foundation/utils/Align/index.d.ts

@@ -0,0 +1 @@
+export * from './Align';

package/dist/foundation/utils/ColorExtensions/ColorExtensions.d.ts

@@ -0,0 +1,51 @@
+import { CSSProperties } from 'vue';
+/** Defines the tone vocabulary shared by tone-aware components (Button, Checkbox, ToggleButton, Tag, Alert, etc.). */
+export declare const ColorTone: {
+    /** Refers to the primary brand palette. */
+    readonly Primary: "primary";
+    /** Refers to the neutral / default grey palette. */
+    readonly Neutral: "neutral";
+    /** Refers to the destructive / error palette. */
+    readonly Danger: "danger";
+    /** Refers to the positive / confirmation palette. */
+    readonly Success: "success";
+    /** Refers to the caution palette. */
+    readonly Warning: "warning";
+};
+export type ColorTone = (typeof ColorTone)[keyof typeof ColorTone];
+export interface ColorOverride {
+    bg?: string;
+    text?: string;
+    soft?: string;
+    softText?: string;
+    ring?: string;
+}
+export type ColorProp = string | ColorOverride;
+/**
+ * Convert a `color` / `colors` prop into a CSS-variable override style for
+ * the active tone's slot set. Returned style overrides the component's theme
+ * tokens locally — every Tailwind utility (`bg-{tone}`, `hover:bg-{tone}/X`,
+ * `text-{tone}-foreground`, etc.) that references the var picks it up
+ * automatically. No variant config refactor required.
+ *
+ * Single-seed mode (`input` is a string):
+ * - `bg` ← seed
+ * - `text` ← white (default contrast; override via `colors.text`)
+ * - `soft` ← seed mixed 12% over white via `color-mix(in oklch, ...)`
+ * - `softText` ← seed
+ * - `ring` ← seed
+ *
+ * Object mode (`input` is a `ColorOverride`):
+ * - Each slot independently overridable; unset slots retain the theme default.
+ */
+declare function toneColorOverride(input: ColorProp | undefined, tone: ColorTone | undefined): CSSProperties | undefined;
+export declare const ColorExtensions: {
+    readonly toneColorOverride: typeof toneColorOverride;
+    readonly TONE_TOKEN_MAP: Record<ColorTone, {
+        main: string;
+        fg: string;
+        soft: string;
+        softFg: string;
+    }>;
+};
+export {};

package/dist/foundation/utils/ColorExtensions/index.d.ts

@@ -0,0 +1 @@
+export * from './ColorExtensions';

package/dist/foundation/utils/Compare/Compare.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a cached locale-aware `Intl.Collator`. Numeric-aware by default — `"item 2"` sorts before
+ * `"item 10"`. Pass `options` to override (e.g. `{ sensitivity: 'base' }` for case-insensitive).
+ */
+export declare function createCollator(locale?: string, options?: Intl.CollatorOptions): Intl.Collator;
+/** Locale + numeric aware string comparison — the SDK default text comparator (sorts `"2"` before `"10"`). */
+export declare function compareStrings(a: string, b: string, locale?: string): number;

package/dist/foundation/utils/Compare/index.d.ts

@@ -0,0 +1 @@
+export * from './Compare';

package/dist/foundation/utils/CornerPosition/CornerPosition.d.ts

@@ -0,0 +1,12 @@
+/** Defines the corner an overlay anchors to. */
+export declare const CornerPosition: {
+    /** Refers to the top-right corner. */
+    readonly TopRight: "top-right";
+    /** Refers to the top-left corner. */
+    readonly TopLeft: "top-left";
+    /** Refers to the bottom-right corner. */
+    readonly BottomRight: "bottom-right";
+    /** Refers to the bottom-left corner. */
+    readonly BottomLeft: "bottom-left";
+};
+export type CornerPosition = (typeof CornerPosition)[keyof typeof CornerPosition];

package/dist/foundation/utils/CornerPosition/index.d.ts

@@ -0,0 +1 @@
+export * from './CornerPosition';

package/dist/foundation/utils/CssExtensions/CssExtensions.d.ts

@@ -0,0 +1,115 @@
+import { CSSProperties } from 'vue';
+import { Padding } from '../StyleTokens';
+/** CSS-value extensions — types, token maps, resolvers. Call as `CssExtensions.x(...)`. */
+export type PaddingToken = Padding;
+/** Defines the corner-radius token vocabulary local to CSS resolvers — diverges from the shared `Radius` (carries `xs`, omits `2xl`). */
+export declare const RadiusToken: {
+    /** Refers to no rounding (square corners). */
+    readonly None: "none";
+    /** Refers to an extra-small radius. */
+    readonly Xs: "xs";
+    /** Refers to a small radius. */
+    readonly Sm: "sm";
+    /** Refers to a medium radius. */
+    readonly Md: "md";
+    /** Refers to a large radius. */
+    readonly Lg: "lg";
+    /** Refers to an extra-large radius. */
+    readonly Xl: "xl";
+    /** Refers to a fully-rounded (pill) radius. */
+    readonly Full: "full";
+};
+export type RadiusToken = (typeof RadiusToken)[keyof typeof RadiusToken];
+export type SizeValue = string | number;
+export type PaddingProp = PaddingToken | {
+    x?: SizeValue;
+    y?: SizeValue;
+};
+export type RadiusProp = RadiusToken | SizeValue;
+export interface BoxSizeOverrides {
+    width?: SizeValue;
+    height?: SizeValue;
+    minWidth?: SizeValue;
+    minHeight?: SizeValue;
+    maxWidth?: SizeValue;
+    maxHeight?: SizeValue;
+    /** Shorthand for square boxes — applied as fallback for both `width` and `height`. Explicit `width`/`height` win when both are set. */
+    boxSize?: SizeValue;
+    /** CSS `aspect-ratio`. String like `'16/9'` or number like `1.5`. Pairs naturally with a single width/height. */
+    aspectRatio?: string | number;
+}
+/** Defines the canonical size preset vocabulary — shared across components. Each component picks the subset it supports via `Extract<SizePreset, ...>` and owns its internal dimension mapping. */
+export declare const SizePreset: {
+    /** Refers to the extra-small step. */
+    readonly Xs: "xs";
+    /** Refers to the small step. */
+    readonly Sm: "sm";
+    /** Refers to the medium (default) step. */
+    readonly Md: "md";
+    /** Refers to the large step. */
+    readonly Lg: "lg";
+    /** Refers to the extra-large step. */
+    readonly Xl: "xl";
+    /** Refers to the 2x extra-large step. */
+    readonly Xxl: "2xl";
+};
+export type SizePreset = (typeof SizePreset)[keyof typeof SizePreset];
+/** Defines the absolute-positioning preset — a 9-anchor value-set; pair with raw inset overrides. */
+export declare const AbsolutePositionPreset: {
+    /** Refers to the top-right corner. */
+    readonly TopRight: "top-right";
+    /** Refers to the top-left corner. */
+    readonly TopLeft: "top-left";
+    /** Refers to the bottom-right corner. */
+    readonly BottomRight: "bottom-right";
+    /** Refers to the bottom-left corner. */
+    readonly BottomLeft: "bottom-left";
+    /** Refers to the top edge, horizontally centered. */
+    readonly Top: "top";
+    /** Refers to the bottom edge, horizontally centered. */
+    readonly Bottom: "bottom";
+    /** Refers to the left edge, vertically centered. */
+    readonly Left: "left";
+    /** Refers to the right edge, vertically centered. */
+    readonly Right: "right";
+    /** Refers to the dead center. */
+    readonly Center: "center";
+};
+export type AbsolutePositionPreset = (typeof AbsolutePositionPreset)[keyof typeof AbsolutePositionPreset];
+export interface AbsoluteInsetOverrides {
+    top?: SizeValue;
+    right?: SizeValue;
+    bottom?: SizeValue;
+    left?: SizeValue;
+}
+export type AbsolutePosition = AbsolutePositionPreset | AbsoluteInsetOverrides;
+declare function toCss(v: SizeValue): string;
+declare function resolvePadding(padding: PaddingProp | undefined): CSSProperties | undefined;
+declare function resolveRadius(radius: RadiusProp | undefined): CSSProperties | undefined;
+declare function resolveBoxSize(overrides: BoxSizeOverrides): CSSProperties | undefined;
+/** Union type for size props that accept either a named preset, a raw value (applied as `boxSize`), or an explicit dim object. */
+export type SizeUnion<P extends string> = P | (string & {}) | number | BoxSizeOverrides;
+/**
+ * Parse a union-style size prop into (a) a preset name (if matched), or (b) a `BoxSizeOverrides` payload.
+ *
+ * Resolution order:
+ * - `undefined`         → `{}`
+ * - object              → `{ box: input }`
+ * - preset string       → `{ preset: input }`
+ * - any other string    → `{ box: { boxSize: input } }`
+ * - number              → `{ box: { boxSize: input } }`
+ */
+declare function parseSizeUnion<P extends string>(input: SizeUnion<P> | undefined, presets: ReadonlySet<string>): {
+    preset?: P;
+    box?: BoxSizeOverrides;
+};
+export declare const CssExtensions: {
+    readonly toCss: typeof toCss;
+    readonly resolvePadding: typeof resolvePadding;
+    readonly resolveRadius: typeof resolveRadius;
+    readonly resolveBoxSize: typeof resolveBoxSize;
+    readonly parseSizeUnion: typeof parseSizeUnion;
+    readonly PADDING_TOKEN_TO_CSS: Record<"xs" | "sm" | "md" | "lg" | "xl", string>;
+    readonly RADIUS_TOKEN_TO_CSS: Record<"xs" | "sm" | "md" | "lg" | "xl", string>;
+};
+export {};

package/dist/foundation/utils/CssExtensions/index.d.ts

@@ -0,0 +1 @@
+export * from './CssExtensions';

package/dist/foundation/utils/ElementTag/ElementTag.d.ts

@@ -0,0 +1,28 @@
+/** Defines the HTML tag a polymorphic component renders as. */
+export declare const ElementTag: {
+    /** Refers to a `<span>`. */
+    readonly Span: "span";
+    /** Refers to a `<div>`. */
+    readonly Div: "div";
+    /** Refers to a `<p>`. */
+    readonly P: "p";
+    /** Refers to an `<h1>`. */
+    readonly H1: "h1";
+    /** Refers to an `<h2>`. */
+    readonly H2: "h2";
+    /** Refers to an `<h3>`. */
+    readonly H3: "h3";
+    /** Refers to an `<h4>`. */
+    readonly H4: "h4";
+    /** Refers to an `<h5>`. */
+    readonly H5: "h5";
+    /** Refers to an `<h6>`. */
+    readonly H6: "h6";
+    /** Refers to a `<section>`. */
+    readonly Section: "section";
+    /** Refers to an `<article>`. */
+    readonly Article: "article";
+    /** Refers to an `<li>`. */
+    readonly Li: "li";
+};
+export type ElementTag = (typeof ElementTag)[keyof typeof ElementTag];

package/dist/foundation/utils/ElementTag/index.d.ts

@@ -0,0 +1 @@
+export * from './ElementTag';

package/dist/foundation/utils/Environment/Environment.d.ts

@@ -0,0 +1,12 @@
+/** Defines the build environment. */
+export declare const Environment: {
+    /** Refers to a local development build. */
+    readonly Development: "development";
+    /** Refers to a production build. */
+    readonly Production: "production";
+    /** Refers to a test build. */
+    readonly Test: "test";
+};
+export type Environment = (typeof Environment)[keyof typeof Environment];
+export declare const IS_DEV: boolean;
+export declare const IS_PRODUCTION: boolean;

package/dist/foundation/utils/Environment/index.d.ts

@@ -0,0 +1 @@
+export * from './Environment';

package/dist/foundation/utils/Equality/Equality.d.ts

@@ -0,0 +1,13 @@
+/** Represents a function that decides whether two values are equal. */
+export type EqualityComparer<T> = (a: T, b: T) => boolean;
+/** Contains the standard equality comparers. */
+export declare const Equality: {
+    /** Checks NaN-safe strict equality (Object.is) — fits primitives + reference equality for objects. */
+    readonly strictEquals: <T>(a: T, b: T) => boolean;
+    /** Checks plain `===` equality (NaN !== NaN). */
+    readonly referenceEquals: <T>(a: T, b: T) => boolean;
+    /** Provides a comparer that compares two objects by an extracted scalar key. */
+    readonly byKey: <T, K = unknown>(extract: (item: T) => K) => EqualityComparer<T>;
+    /** Checks shallow object equality — equal iff every key has identical (Object.is) value. */
+    readonly shallowEquals: <T extends Record<string, unknown>>(a: T, b: T) => boolean;
+};

package/dist/foundation/utils/Equality/index.d.ts

@@ -0,0 +1 @@
+export * from './Equality';

package/dist/foundation/utils/HtmlExtensions/HtmlExtensions.d.ts

@@ -0,0 +1,22 @@
+/** Defines an HTML element tag name (for intrinsic elements and polymorphic components). */
+export declare const HtmlElement: {
+    /** Refers to a `<button>` element. */
+    readonly Button: "button";
+    /** Refers to an `<a>` (anchor) element. */
+    readonly Anchor: "a";
+    /** Refers to a `<span>` element. */
+    readonly Span: "span";
+    /** Refers to a `<div>` element. */
+    readonly Div: "div";
+};
+export type HtmlElement = (typeof HtmlElement)[keyof typeof HtmlElement];
+/** Defines the `<button type="">` attribute value. */
+export declare const ButtonType: {
+    /** Refers to a non-submitting button. */
+    readonly Button: "button";
+    /** Refers to a form-submitting button. */
+    readonly Submit: "submit";
+    /** Refers to a form-resetting button. */
+    readonly Reset: "reset";
+};
+export type ButtonType = (typeof ButtonType)[keyof typeof ButtonType];

package/dist/foundation/utils/HtmlExtensions/index.d.ts

@@ -0,0 +1 @@
+export * from './HtmlExtensions';

package/dist/foundation/utils/KeyboardExtensions/KeyboardExtensions.d.ts

@@ -0,0 +1,32 @@
+/** Defines a keyboard key value from `KeyboardEvent.key`. */
+export declare const Key: {
+    /** Refers to the space bar. */
+    readonly Space: " ";
+    /** Refers to the Enter / Return key. */
+    readonly Enter: "Enter";
+    /** Refers to the Escape key. */
+    readonly Escape: "Escape";
+    /** Refers to the Tab key. */
+    readonly Tab: "Tab";
+    /** Refers to the Backspace key. */
+    readonly Backspace: "Backspace";
+    /** Refers to the Delete key. */
+    readonly Delete: "Delete";
+    /** Refers to the Home key. */
+    readonly Home: "Home";
+    /** Refers to the End key. */
+    readonly End: "End";
+    /** Refers to the Page Up key. */
+    readonly PageUp: "PageUp";
+    /** Refers to the Page Down key. */
+    readonly PageDown: "PageDown";
+    /** Refers to the up-arrow key. */
+    readonly ArrowUp: "ArrowUp";
+    /** Refers to the down-arrow key. */
+    readonly ArrowDown: "ArrowDown";
+    /** Refers to the left-arrow key. */
+    readonly ArrowLeft: "ArrowLeft";
+    /** Refers to the right-arrow key. */
+    readonly ArrowRight: "ArrowRight";
+};
+export type Key = (typeof Key)[keyof typeof Key];

package/dist/foundation/utils/KeyboardExtensions/index.d.ts

@@ -0,0 +1 @@
+export * from './KeyboardExtensions';

package/dist/foundation/utils/Layers/Layers.d.ts

@@ -0,0 +1,35 @@
+/** Contains the semantic z-index tiers; matching `z-{name}` utilities ship via @theme. */
+export declare const Layer: {
+    /** Slips under the base layer; visually hidden. */
+    readonly Hide: -1;
+    /** Sits in the default DOM flow with no z-index applied. */
+    readonly Base: 0;
+    /** Slightly elevates over siblings — badges, sticky list items, in-grid overlays. */
+    readonly Raised: 10;
+    /** Pins widgets inside a section — panels, inline overlays. */
+    readonly Docked: 20;
+    /** Anchors a page-level sticky header or footer. */
+    readonly Sticky: 30;
+    /** Hosts system banners — cookie notice, status banner, persistent FAB. */
+    readonly Banner: 40;
+    /** Hosts dropdowns, popovers, comboboxes, menus, hover-cards anchored to a trigger. */
+    readonly Dropdown: 50;
+    /** Dims the page behind a modal — backdrop / scrim layer. */
+    readonly Overlay: 60;
+    /** Hosts modal / dialog / drawer / sheet content above its backdrop. */
+    readonly Modal: 70;
+    /** Hosts popovers / menus opened FROM inside a modal — must beat Modal. */
+    readonly Popover: 80;
+    /** Hosts toasts, snackbars, undo bars — survives above modals. */
+    readonly Toast: 90;
+    /** Hosts tooltips and live-cursors — highest functional layer. */
+    readonly Tooltip: 100;
+    /** Hosts DevTools / design-system inspector overlays — always wins. */
+    readonly Debug: 9999;
+};
+/** Represents the name of a semantic z-index tier. */
+export type LayerName = keyof typeof Layer;
+/** Provides an inline `style` object for programmatic z-index assignment. */
+export declare function layerStyle(layer: LayerName): {
+    zIndex: number;
+};

package/dist/foundation/utils/Layers/index.d.ts

@@ -0,0 +1 @@
+export * from './Layers';

package/dist/foundation/utils/OptionalExtensions/OptionalExtensions.d.ts

@@ -0,0 +1,12 @@
+/** Optional value extensions — call as `OptionalExtensions.x(...)`. */
+/**
+ * Construct an optional from a `(condition, value)` pair: returns `value` when
+ * `condition` is truthy, otherwise `undefined`. Use to keep DOM attributes
+ * absent when their default/false meaning is what we want (e.g. `aria-busy`,
+ * `tabIndex`, `disabled`).
+ */
+declare function from<T>(condition: unknown, value: T): T | undefined;
+export declare const OptionalExtensions: {
+    readonly from: typeof from;
+};
+export {};

package/dist/foundation/utils/OptionalExtensions/index.d.ts

@@ -0,0 +1 @@
+export * from './OptionalExtensions';

package/dist/foundation/utils/Orientation/Orientation.d.ts

@@ -0,0 +1,8 @@
+/** Defines the layout axis of a component (forms / layout / nav / actions / display / feedback). */
+export declare const Orientation: {
+    /** Refers to a horizontal (left-to-right) axis. */
+    readonly Horizontal: "horizontal";
+    /** Refers to a vertical (top-to-bottom) axis. */
+    readonly Vertical: "vertical";
+};
+export type Orientation = (typeof Orientation)[keyof typeof Orientation];

package/dist/foundation/utils/Orientation/index.d.ts

@@ -0,0 +1 @@
+export * from './Orientation';

package/dist/foundation/utils/OverlayPosition/OverlayPosition.d.ts

@@ -0,0 +1,16 @@
+/** Defines the anchor position of a floating overlay — the four corners plus top/bottom center. */
+export declare const OverlayPosition: {
+    /** Refers to the top-right corner. */
+    readonly TopRight: "top-right";
+    /** Refers to the top-left corner. */
+    readonly TopLeft: "top-left";
+    /** Refers to the bottom-right corner. */
+    readonly BottomRight: "bottom-right";
+    /** Refers to the bottom-left corner. */
+    readonly BottomLeft: "bottom-left";
+    /** Refers to the top edge, horizontally centered. */
+    readonly TopCenter: "top-center";
+    /** Refers to the bottom edge, horizontally centered. */
+    readonly BottomCenter: "bottom-center";
+};
+export type OverlayPosition = (typeof OverlayPosition)[keyof typeof OverlayPosition];

package/dist/foundation/utils/OverlayPosition/index.d.ts

@@ -0,0 +1 @@
+export * from './OverlayPosition';

package/dist/foundation/utils/PressExtensions/PressExtensions.d.ts

@@ -0,0 +1,17 @@
+/** Press-interaction extensions — types + constants shared by interactive components. */
+/** Unified press event — pointer OR keyboard activation on any HTML element. */
+export type PressEvent<T extends HTMLElement = HTMLElement> = (PointerEvent | KeyboardEvent) & {
+    currentTarget: T;
+};
+export declare const PressExtensions: {
+    /**
+     * Bounds for `longPressDelay` props. Below `min`: overlaps with normal
+     * click latency, too easy to trigger accidentally. Above `max`: clearly a
+     * developer error (5-min hold). `default` is the conventional 500ms.
+     */
+    readonly longPressDelay: {
+        readonly min: 200;
+        readonly max: 300000;
+        readonly default: 500;
+    };
+};

package/dist/foundation/utils/PressExtensions/index.d.ts

@@ -0,0 +1 @@
+export * from './PressExtensions';

package/dist/foundation/utils/ProgressTone/ProgressTone.d.ts

@@ -0,0 +1,14 @@
+/** Defines the tone of a progress indicator. */
+export declare const ProgressTone: {
+    /** Refers to the brand palette. */
+    readonly Brand: "brand";
+    /** Refers to the positive / success palette. */
+    readonly Success: "success";
+    /** Refers to the caution palette. */
+    readonly Warning: "warning";
+    /** Refers to the destructive / error palette. */
+    readonly Danger: "danger";
+    /** Refers to the neutral / default palette. */
+    readonly Neutral: "neutral";
+};
+export type ProgressTone = (typeof ProgressTone)[keyof typeof ProgressTone];

package/dist/foundation/utils/ProgressTone/index.d.ts

@@ -0,0 +1 @@
+export * from './ProgressTone';

package/dist/foundation/utils/Severity/Severity.d.ts

@@ -0,0 +1,14 @@
+/** Defines the severity of a feedback surface (alert / banner / toast / callout). */
+export declare const Severity: {
+    /** Refers to a neutral, non-semantic message. */
+    readonly Neutral: "neutral";
+    /** Refers to an informational message. */
+    readonly Info: "info";
+    /** Refers to a positive / success message. */
+    readonly Success: "success";
+    /** Refers to a caution / warning message. */
+    readonly Warning: "warning";
+    /** Refers to a destructive / error message. */
+    readonly Danger: "danger";
+};
+export type Severity = (typeof Severity)[keyof typeof Severity];

package/dist/foundation/utils/Severity/index.d.ts

@@ -0,0 +1 @@
+export * from './Severity';