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

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/clipboard/ClipboardResult.ts","../../../src/foundation/clipboard/ClipboardSupport.ts","../../../src/foundation/clipboard/LegacyCopy.ts","../../../src/foundation/clipboard/CopyText.ts","../../../src/foundation/clipboard/CopyItems.ts","../../../src/foundation/clipboard/ReadClipboard.ts","../../../src/foundation/clipboard/PasteItems.ts","../../../src/foundation/clipboard/UsePasteHandler.ts","../../../src/foundation/clipboard/UseClipboardCopy.ts","../../../src/foundation/clipboard/ClipboardPermission.ts"],"sourcesContent":["// The vocabulary every entry point in this slice answers in — the result unions, the options, and the helpers\n// that build a result from a caught value.\n//\n// WHY A DISCRIMINATED RESULT AND NOT A PROMISE THAT REJECTS. A clipboard write fails for four reasons that a UI\n// must render differently: the API is absent (render a manual \"select and press Ctrl+C\" affordance), the user or\n// the platform refused (explain the permission), the platform broke (a toast), or it worked. Collapsing those\n// into \"rejected\" throws away the distinction, and collapsing them into reactive state — what\n// `foundation/hooks`' `useClipboard` does — makes the outcome unreadable to any caller that is not a component.\n// So every entry point resolves to one of these unions and NOTHING in the slice throws.\n//\n// The three non-success arms are ONE type ({@link ClipboardFailure}) shared by the write and both read results,\n// not three parallel copies. Reading and writing fail for exactly the same reasons, so a consumer writes one\n// error renderer, and the helpers below build a value assignable to every result union.\n//\n// `denied` is split out from `failed` on the error's `name`, not its message: `NotAllowedError` is what the\n// platform raises when the permission was refused or there was no transient activation, and `SecurityError` is\n// what some engines raise for the same call in a non-secure context. Both mean \"the platform refused\", which is\n// a different repair for the user (grant the permission / use HTTPS) than \"the platform broke\".\n//\n// Matching on `name` rather than `instanceof DOMException` is deliberate, for the same reason\n// `foundation/errors`' recognizers do it: the check has to hold for a `DOMException` from another realm, for\n// environments with no `DOMException` global, and for the plain `{ name: 'NotAllowedError' }` a test double\n// throws.\n\nimport { toError } from '../errors';\n\n/**\n * The ways a clipboard operation ends without producing a payload. Shared by {@link ClipboardWriteResult} and\n * both read results, so one `switch` renders every error path in the slice.\n *\n * - `denied` — the platform refused: permission not granted, the paste prompt dismissed, or no user gesture\n *   behind the call.\n * - `unsupported` — no Clipboard API here: SSR, a non-secure context, or an engine without the method. A\n *   capability fact, not a failure — nothing went wrong, the road is simply not there.\n * - `failed` — anything else, carrying the normalized `Error`.\n */\nexport type ClipboardFailure =\n  | { readonly status: 'denied'; readonly error: Error }\n  | { readonly status: 'unsupported' }\n  | { readonly status: 'failed'; readonly error: Error };\n\n/** The outcome of a clipboard write — `copied` on success, otherwise a {@link ClipboardFailure}. */\nexport type ClipboardWriteResult = { readonly status: 'copied' } | ClipboardFailure;\n\n/** The `status` discriminant of a {@link ClipboardWriteResult} — for a consumer's own switch or status→copy map. */\nexport type ClipboardWriteStatus = ClipboardWriteResult['status'];\n\n/** One MIME-typed payload read off the system clipboard. */\nexport interface ClipboardReadItem {\n  /** The MIME type the platform reported — `text/plain`, `text/html`, `image/png`, … */\n  readonly type: string;\n\n  /** The payload itself. Read it with `blob.text()` for textual types, or hand it to `URL.createObjectURL`. */\n  readonly blob: Blob;\n}\n\n/**\n * The outcome of a clipboard text read. `read` carries the text — an empty clipboard reads as `''`, which is a\n * successful read of nothing rather than a failure.\n */\nexport type ClipboardReadTextResult = { readonly status: 'read'; readonly text: string } | ClipboardFailure;\n\n/** The outcome of a multi-format clipboard read. `read` carries one entry per MIME type the platform offered. */\nexport type ClipboardReadItemsResult =\n  | { readonly status: 'read'; readonly items: readonly ClipboardReadItem[] }\n  | ClipboardFailure;\n\n/** The `status` discriminant shared by both read results. */\nexport type ClipboardReadStatus = ClipboardReadTextResult['status'];\n\n/** Tunes a clipboard read. */\nexport interface ClipboardReadOptions {\n  /**\n   * Called with the normalized error on a `denied` or `failed` result — the seam for a toast or telemetry hook.\n   * Never called for `unsupported`, which is a capability fact rather than a failure. A throw from this callback\n   * is swallowed. Called at most once per operation, on the final result.\n   */\n  readonly onError?: (error: Error) => void;\n}\n\n/** Tunes a clipboard write. */\nexport interface ClipboardCopyOptions extends ClipboardReadOptions {\n  /**\n   * Whether a write the Clipboard API cannot complete retries through the deprecated\n   * `document.execCommand('copy')` path. Defaults to `false`.\n   *\n   * Opt in for reach — older Safari and any non-secure context have no `navigator.clipboard` at all, and\n   * `execCommand` is the only write available there. Leave it off to stay on standards-track APIs only. See\n   * `LegacyCopy.ts` for the deprecation caveats and for exactly when the retry runs.\n   */\n  readonly legacyFallback?: boolean;\n}\n\n/** The shape every result family shares, so one reporter can serve every entry point. */\ntype ClipboardOutcome = { readonly status: string; readonly error?: Error };\n\n/** Reads a caught value's `name` as a string. Guarded, so a throwing getter reads as absent. */\nfunction nameOf(value: unknown): string | undefined {\n  try {\n    if (typeof value !== 'object' || value === null) return undefined;\n    const name: unknown = (value as { name?: unknown }).name;\n    return typeof name === 'string' ? name : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Checks whether a caught value is the platform refusing rather than breaking — the split behind `denied`.\n * Exported for the sibling modules; absent from the barrel, where the statuses are the answer callers want.\n *\n * @param value The caught value.\n */\nexport function isPermissionRefusal(value: unknown): boolean {\n  const name = nameOf(value);\n  return name === 'NotAllowedError' || name === 'SecurityError';\n}\n\n/**\n * Turns a caught value into the `denied` or `failed` arm it belongs in. Serves reads and writes alike — the\n * returned {@link ClipboardFailure} is assignable to every result union in the slice. Exported for the sibling\n * modules; absent from the barrel. Never throws: `toError` is total.\n *\n * @param error The caught value.\n */\nexport function toClipboardFailure(error: unknown): ClipboardFailure {\n  const failure = toError(error);\n  return isPermissionRefusal(error) ? { status: 'denied', error: failure } : { status: 'failed', error: failure };\n}\n\n/**\n * Hands a consumer's callback the failure carried by `result`, absorbing a throw from the callback itself. A\n * reporter that throws must not convert a typed result into an unhandled rejection.\n *\n * Called once per entry point, on the FINAL result — so a write that degrades through the legacy fallback\n * reports the outcome the caller receives, not each intermediate attempt. Exported for the sibling modules;\n * absent from the barrel.\n *\n * @param result The outcome about to be returned.\n * @param onError The consumer's reporter, if they supplied one.\n * @returns `result`, unchanged — so a call site can `return reportClipboardOutcome(...)`.\n */\nexport function reportClipboardOutcome<TResult extends ClipboardOutcome>(\n  result: TResult,\n  onError: ((error: Error) => void) | undefined,\n): TResult {\n  if (onError === undefined) return result;\n  if (result.error === undefined) return result;\n\n  try {\n    onError(result.error);\n  } catch {\n    // The consumer's own reporter failed. There is nothing useful left to do with that — the result still\n    // reaches the caller, which is the guarantee that matters.\n  }\n  return result;\n}\n","// Capability detection — the four questions a UI asks BEFORE it renders a clipboard affordance, plus the two\n// guarded global reads every other module in the slice goes through.\n//\n// Per-method, not per-API. `navigator.clipboard` existing tells you almost nothing: Firefox exposes the object\n// and `writeText` on it while withholding `readText` from page script entirely, and every engine shipped\n// `writeText` years before `write`. So each predicate probes the exact method its operation calls, and the\n// modules never touch `navigator.clipboard` directly.\n//\n// Every read is wrapped: `navigator` can be absent (SSR), a getter can throw (a hardened page, an over-eager\n// polyfill), and a partial implementation can leave a property that is not a function. All of those have to\n// become `false`, never an exception — a feature check that throws is worse than no feature check.\n//\n// `ClipboardItem` is read off `globalThis` rather than referenced as a bare global for the same reason: it is\n// undefined in Node and in older Safari, and a bare reference would be a `ReferenceError` instead of a `false`.\n\n/** The `ClipboardItem` constructor, narrowed to the one overload this slice calls. */\nexport type ClipboardItemConstructor = new (items: Record<string, Blob>) => ClipboardItem;\n\n/** Reads a member off an object, guarded — a throwing getter reads as `undefined`. */\nfunction member(source: object, key: string): unknown {\n  try {\n    return (source as Record<string, unknown>)[key];\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Reads `navigator.clipboard` if it is there and usable. Guarded end-to-end; returns `undefined` under SSR.\n * Exported for the sibling modules; absent from the barrel.\n */\nexport function clipboardApi(): Clipboard | undefined {\n  try {\n    if (typeof navigator === 'undefined') return undefined;\n    const clipboard = member(navigator, 'clipboard');\n    if (typeof clipboard !== 'object' || clipboard === null) return undefined;\n    return clipboard as Clipboard;\n  } catch {\n    return undefined;\n  }\n}\n\n/** The Clipboard API methods this slice calls. */\nexport type ClipboardMethodName = 'writeText' | 'write' | 'readText' | 'read';\n\n/**\n * Resolves one of the Clipboard API's methods, bound to the clipboard object, or `undefined` when this engine\n * does not implement it. The single gate every operation passes through. Exported for the sibling modules;\n * absent from the barrel.\n *\n * Bound rather than returned bare: a caller invoking a detached `writeText` would lose its receiver and get a\n * `TypeError` (\"Illegal invocation\") from the real implementation.\n *\n * @param name The method to resolve — `writeText`, `write`, `readText`, or `read`.\n */\nexport function clipboardMethod<TName extends ClipboardMethodName>(name: TName): Clipboard[TName] | undefined {\n  const clipboard = clipboardApi();\n  if (clipboard === undefined) return undefined;\n\n  const method = member(clipboard, name);\n  if (typeof method !== 'function') return undefined;\n\n  try {\n    return (method as (...args: unknown[]) => unknown).bind(clipboard) as Clipboard[TName];\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Reads the `ClipboardItem` constructor, which multi-format writes need and which Node and older Safari lack.\n * Exported for the sibling modules; absent from the barrel.\n */\nexport function clipboardItemConstructor(): ClipboardItemConstructor | undefined {\n  try {\n    const constructor = member(globalThis, 'ClipboardItem');\n    if (typeof constructor !== 'function') return undefined;\n    return constructor as ClipboardItemConstructor;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Whether plain-text copying is available — `navigator.clipboard.writeText`.\n *\n * `false` under SSR, in a non-secure context, and on engines predating the Clipboard API. It does NOT predict\n * the permission: a copy can still come back `denied` if the call has no user gesture behind it. Treat it as\n * \"is the road there\", not \"will the trip succeed\".\n */\nexport function canCopy(): boolean {\n  return clipboardMethod('writeText') !== undefined;\n}\n\n/**\n * Whether multi-format copying is available — `navigator.clipboard.write` plus a `ClipboardItem` constructor.\n * Strictly narrower than {@link canCopy}: every engine shipped `writeText` first.\n */\nexport function canCopyItems(): boolean {\n  return clipboardMethod('write') !== undefined && clipboardItemConstructor() !== undefined;\n}\n\n/**\n * Whether reading from the clipboard is available — `navigator.clipboard.readText`.\n *\n * `false` in Firefox, which does not expose reading to page script at all, and under SSR. Even where it is\n * `true`, the read needs a user gesture and shows an explicit paste prompt. If all you need is the payload the\n * user just pasted, do not read at all — handle the `paste` event with `getPasteItems`, which needs no\n * permission and no prompt.\n */\nexport function canReadClipboard(): boolean {\n  return clipboardMethod('readText') !== undefined;\n}\n\n/**\n * Whether the deprecated `document.execCommand('copy')` path is available — the only write that exists in a\n * non-secure context or on older Safari. Requires a document; `false` under SSR.\n *\n * A `true` here does not mean the copy will succeed: `execCommand` still requires the call to sit inside a user\n * gesture, and reports its own refusal by returning `false`.\n */\nexport function canLegacyCopy(): boolean {\n  try {\n    if (typeof document === 'undefined') return false;\n    return typeof member(document, 'execCommand') === 'function';\n  } catch {\n    return false;\n  }\n}\n","// The deprecated write path: a hidden `<textarea>`, selected, copied with `document.execCommand('copy')`, and\n// removed. Opt-in only, via `legacyFallback: true`.\n//\n// WHY IT EXISTS AT ALL. `navigator.clipboard` requires a secure context. Any page served over plain HTTP — a LAN\n// tool, a staging box on an IP address, an embedded device's admin UI — has no Clipboard API whatsoever, and\n// neither does Safari before 13.1. In those places `execCommand` is not the worse option, it is the only one.\n//\n// WHY IT IS OPT-IN. `document.execCommand` is deprecated: removed from the standard, kept alive by web\n// compatibility, and free to disappear from any engine. It is also synchronous and re-entrant into layout, which\n// makes it a jank source on a large payload. A consumer should choose that trade, not inherit it.\n//\n// THE ELEMENT IS ALWAYS REMOVED. Removal is in a `finally`, not on the success path — if `execCommand` throws\n// (a hardened page, an extension patching it), an early `return` would leave a focus-stealing textarea in the\n// DOM forever, and every retry would leave another. The same `finally` restores focus to whatever had it, since\n// selecting the textarea takes focus away from the button the user just clicked and losing it mid-interaction\n// strands a keyboard user.\n//\n// The textarea is positioned rather than `display: none` / `hidden`: an element outside the layout tree cannot\n// be selected, and an unselected textarea copies nothing.\n\nimport { toClipboardFailure, type ClipboardCopyOptions, type ClipboardWriteResult } from './ClipboardResult';\nimport { canLegacyCopy } from './ClipboardSupport';\n\n/** Off-screen but laid out — selection requires a rendered element, so `display: none` would copy nothing. */\nconst HiddenTextareaCss =\n  'position:fixed;top:0;left:0;width:1px;height:1px;padding:0;margin:0;border:none;outline:none;box-shadow:none;background:transparent;opacity:0;pointer-events:none;';\n\n/** Restores focus to whatever held it before the textarea took it. Guarded — a stand-in may have no `focus`. */\nfunction restoreFocus(previous: Element | null): void {\n  try {\n    if (previous === null) return;\n    const focus = (previous as { focus?: unknown }).focus;\n    if (typeof focus !== 'function') return;\n    (previous as HTMLElement).focus({ preventScroll: true });\n  } catch {\n    // The previously focused element is gone or refuses focus. Not worth failing a completed copy over.\n  }\n}\n\n/** Detaches the temporary textarea, preferring `remove()` and falling back to the parent. Never throws. */\nfunction detach(element: HTMLTextAreaElement): void {\n  try {\n    if (typeof element.remove === 'function') {\n      element.remove();\n      return;\n    }\n    element.parentNode?.removeChild(element);\n  } catch {\n    // Nothing further to try. The failure to detach must not mask the copy's own result.\n  }\n}\n\n/**\n * Copies `text` through the deprecated `document.execCommand('copy')` path.\n *\n * Synchronous, unlike every other write in this slice — `execCommand` is. Requires a user gesture: outside one\n * the command reports its own refusal by returning `false`, which surfaces here as `failed` (the legacy API has\n * no way to say \"denied\" specifically). Returns `unsupported` under SSR or where `execCommand` is gone.\n *\n * Exported for the sibling modules and for a consumer that wants the legacy path explicitly; the temporary\n * element is removed on every path, including a throw from `execCommand` itself.\n *\n * Never throws.\n *\n * @param text The text to place on the clipboard.\n * @deprecated Prefer `copyText`, which uses the Clipboard API and falls back here only on `legacyFallback: true`.\n */\nexport function legacyCopyText(text: string): ClipboardWriteResult {\n  if (!canLegacyCopy()) return { status: 'unsupported' };\n\n  let element: HTMLTextAreaElement | undefined;\n  let previouslyFocused: Element | null = null;\n\n  try {\n    const body: unknown = document.body;\n    if (typeof body !== 'object' || body === null) return { status: 'unsupported' };\n\n    previouslyFocused = document.activeElement;\n\n    element = document.createElement('textarea');\n    element.value = text;\n    element.setAttribute('aria-hidden', 'true');\n    element.setAttribute('tabindex', '-1');\n    element.setAttribute('readonly', 'readonly');\n    element.style.cssText = HiddenTextareaCss;\n\n    (body as HTMLElement).appendChild(element);\n\n    element.focus({ preventScroll: true });\n    element.select();\n    element.setSelectionRange(0, text.length);\n\n    const copied = document.execCommand('copy');\n    return copied\n      ? { status: 'copied' }\n      : { status: 'failed', error: new Error('document.execCommand(\"copy\") reported failure.') };\n  } catch (error) {\n    return toClipboardFailure(error);\n  } finally {\n    if (element !== undefined) detach(element);\n    restoreFocus(previouslyFocused);\n  }\n}\n\n/**\n * Retries a write that the Clipboard API could not complete through the legacy path, when the caller opted in.\n *\n * The retry runs whenever `modern` is not `copied` — not only on `unsupported`. A `denied` from\n * `navigator.clipboard` is exactly the case `execCommand` can still serve: the legacy command is gated on the\n * user gesture the call already sits in, not on the Clipboard API's permission.\n *\n * Which result wins:\n *  - the legacy attempt, when it copied — a success outranks any diagnosis;\n *  - otherwise `modern`, when the Clipboard API was actually present (its `denied` / `failed` is the more\n *    specific account of what went wrong);\n *  - otherwise the legacy attempt's own result — with no Clipboard API at all, `modern` is a bare `unsupported`\n *    and the legacy failure says more.\n *\n * Exported for the sibling write modules; absent from the barrel. Never throws.\n *\n * @param modern The result the Clipboard API path produced.\n * @param text The plain-text payload, or `undefined` when the write has no text arm to degrade to.\n * @param options The caller's options — the retry runs only on `legacyFallback: true`.\n */\nexport function withLegacyFallback(\n  modern: ClipboardWriteResult,\n  text: string | undefined,\n  options: ClipboardCopyOptions | undefined,\n): ClipboardWriteResult {\n  if (modern.status === 'copied') return modern;\n  if (options?.legacyFallback !== true) return modern;\n  if (text === undefined) return modern;\n\n  const legacy = legacyCopyText(text);\n  if (legacy.status === 'copied') return legacy;\n  return modern.status === 'unsupported' ? legacy : modern;\n}\n","// The plain-text write — the one every \"copy link\" / \"copy code\" button wants, and the slice's most-used entry\n// point.\n//\n// The whole body sits inside a `try`, not only the `await`. `navigator.clipboard.writeText` can throw\n// synchronously rather than reject (a partial implementation, a polyfill, an extension patching the method), and\n// a synchronous throw would escape an `await`-only guard and reach the consumer's click handler as an unhandled\n// error — the exact failure mode the never-throws contract exists to prevent.\n//\n// A non-string `text` is answered, not coerced. The signature says `string`, so a non-string only arrives from\n// untyped JavaScript, and coercing it is a guess: `String(value)` on a `Symbol` throws, and on an object it\n// silently copies \"[object Object]\" to the user's clipboard — a wrong success is worse than a typed failure.\n\nimport {\n  reportClipboardOutcome,\n  toClipboardFailure,\n  type ClipboardCopyOptions,\n  type ClipboardWriteResult,\n} from './ClipboardResult';\nimport { clipboardMethod } from './ClipboardSupport';\nimport { withLegacyFallback } from './LegacyCopy';\n\n/** Runs the Clipboard API write, mapping every outcome onto the result union. Never throws. */\nasync function writeTextThroughApi(text: string): Promise<ClipboardWriteResult> {\n  const writeText = clipboardMethod('writeText');\n  if (writeText === undefined) return { status: 'unsupported' };\n\n  try {\n    await writeText(text);\n    return { status: 'copied' };\n  } catch (error) {\n    return toClipboardFailure(error);\n  }\n}\n\n/**\n * Writes `text` to the system clipboard.\n *\n * Call it from a user gesture: browsers require transient activation for a clipboard write, and without one the\n * platform refuses — which surfaces as `denied`, not `unsupported`, since the API was in fact present.\n *\n * Resolves to `unsupported` under SSR, in a non-secure context, and on engines with no Clipboard API. Pass\n * `legacyFallback: true` to retry those through the deprecated `document.execCommand` path.\n *\n * Never throws, never rejects.\n *\n * @param text The text to place on the clipboard. An empty string is a valid payload — it clears the clipboard.\n * @param options Error reporting and the legacy-fallback opt-in.\n */\nexport async function copyText(text: string, options?: ClipboardCopyOptions): Promise<ClipboardWriteResult> {\n  try {\n    if (typeof text !== 'string') {\n      return reportClipboardOutcome(\n        { status: 'failed', error: new TypeError('copyText expects a string.') } as const,\n        options?.onError,\n      );\n    }\n\n    const result = withLegacyFallback(await writeTextThroughApi(text), text, options);\n    return reportClipboardOutcome(result, options?.onError);\n  } catch (error) {\n    // Unreachable by design — every helper above is itself total. Kept so a future edit to one of them cannot\n    // turn this entry point into a rejecting promise.\n    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);\n  }\n}\n","// The multi-format write — one clipboard entry carrying the same content in several MIME types at once.\n//\n// WHY MULTI-FORMAT IS THE POINT. The clipboard holds ONE item with MANY representations, and the paste target\n// picks the richest one it understands. Write `text/html` alone and a plain `<textarea>` receives nothing; write\n// `text/plain` alone and a rich editor receives markup-free text. Writing both in a SINGLE `write` call means\n// pasting into Word or Notion keeps the formatting while pasting into a terminal still works. Two sequential\n// `writeText` + `write` calls do NOT achieve this — the second overwrites the first.\n//\n// `copyBlob` is the single-format case of the same call, spelled for the payload consumers actually reach for\n// (a generated PNG, a canvas export).\n//\n// Legacy degradation is text-only, and only from a string arm. `document.execCommand('copy')` can put text on\n// the clipboard and nothing else, so a rich write degrades to its `text/plain` representation or not at all. A\n// `Blob`-valued text arm is skipped rather than awaited: reading it is async, while the legacy path is\n// synchronous and must stay inside the user gesture that authorized the copy.\n\nimport {\n  reportClipboardOutcome,\n  toClipboardFailure,\n  type ClipboardCopyOptions,\n  type ClipboardWriteResult,\n} from './ClipboardResult';\nimport { clipboardItemConstructor, clipboardMethod } from './ClipboardSupport';\nimport { withLegacyFallback } from './LegacyCopy';\n\n/**\n * The representations of one clipboard entry, keyed by MIME type.\n *\n * A `string` value is wrapped in a `Blob` of that same type before it reaches the platform. Engines accept only\n * a small set of types — `text/plain`, `text/html`, `image/png` are the portable ones; anything else may be\n * refused with a `failed` result.\n *\n * @example\n * copyItems({ 'text/plain': 'Total: 42', 'text/html': '<b>Total:</b> 42' });\n */\nexport type ClipboardWriteItems = Readonly<Record<string, Blob | string>>;\n\n/** The MIME type a blob with no type of its own is written under — deliberately generic, and often refused. */\nconst FallbackMimeType = 'application/octet-stream';\n\n/** The representation the legacy path can degrade to. */\nconst PlainTextMimeType = 'text/plain';\n\n/** Pulls the plain-text arm out, for the legacy fallback only. `undefined` unless it is a literal string. */\nfunction plainTextArm(items: ClipboardWriteItems): string | undefined {\n  try {\n    const value = items[PlainTextMimeType];\n    return typeof value === 'string' ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Normalizes every representation to a `Blob` typed with its own key. Throws only if `Blob` itself does. */\nfunction toBlobRecord(items: ClipboardWriteItems): Record<string, Blob> {\n  const record: Record<string, Blob> = {};\n  for (const [type, value] of Object.entries(items)) {\n    record[type] = typeof value === 'string' ? new Blob([value], { type }) : value;\n  }\n  return record;\n}\n\n/** Runs the Clipboard API multi-format write, mapping every outcome onto the result union. Never throws. */\nasync function writeItemsThroughApi(items: ClipboardWriteItems): Promise<ClipboardWriteResult> {\n  const write = clipboardMethod('write');\n  const ClipboardItemConstructor = clipboardItemConstructor();\n  if (write === undefined || ClipboardItemConstructor === undefined) return { status: 'unsupported' };\n\n  try {\n    await write([new ClipboardItemConstructor(toBlobRecord(items))]);\n    return { status: 'copied' };\n  } catch (error) {\n    return toClipboardFailure(error);\n  }\n}\n\n/**\n * Writes several representations of one payload to the clipboard in a single entry, so the paste target can pick\n * the richest format it understands.\n *\n * Needs `navigator.clipboard.write` and a `ClipboardItem` constructor — strictly newer than the `writeText`\n * behind `copyText`, so `unsupported` is more likely here. With `legacyFallback: true` an unsupported or refused\n * write degrades to the `text/plain` arm alone, and only when that arm is a literal string.\n *\n * Call it from a user gesture. Never throws, never rejects.\n *\n * @param items The representations, keyed by MIME type. An empty object resolves to `failed` — a write with no\n *   payload is a caller mistake, and reporting it as `copied` would claim something reached the clipboard.\n * @param options Error reporting and the legacy-fallback opt-in.\n */\nexport async function copyItems(\n  items: ClipboardWriteItems,\n  options?: ClipboardCopyOptions,\n): Promise<ClipboardWriteResult> {\n  try {\n    if (typeof items !== 'object' || items === null) {\n      return reportClipboardOutcome(\n        { status: 'failed', error: new TypeError('copyItems expects an object keyed by MIME type.') } as const,\n        options?.onError,\n      );\n    }\n\n    if (Object.keys(items).length === 0) {\n      return reportClipboardOutcome(\n        { status: 'failed', error: new Error('copyItems was given no representations to write.') } as const,\n        options?.onError,\n      );\n    }\n\n    const result = withLegacyFallback(await writeItemsThroughApi(items), plainTextArm(items), options);\n    return reportClipboardOutcome(result, options?.onError);\n  } catch (error) {\n    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);\n  }\n}\n\n/**\n * Writes a single binary payload — a generated image, a canvas export, a downloaded file — to the clipboard.\n *\n * The single-format case of {@link copyItems}, and subject to the same support: it needs\n * `navigator.clipboard.write`, and the legacy fallback cannot serve it (`execCommand` writes text only).\n *\n * Engines accept a narrow set of types for binary payloads; `image/png` is the portable one. A type the platform\n * refuses comes back `failed`.\n *\n * Never throws, never rejects.\n *\n * @param blob The payload.\n * @param mimeType The type to write it under. Defaults to the blob's own `type`, then to\n *   `application/octet-stream` — which most engines refuse, so pass a real type for a typeless blob.\n * @param options Error reporting. `legacyFallback` has no effect here.\n */\nexport async function copyBlob(\n  blob: Blob,\n  mimeType?: string,\n  options?: ClipboardCopyOptions,\n): Promise<ClipboardWriteResult> {\n  try {\n    if (typeof blob !== 'object' || blob === null) {\n      return reportClipboardOutcome(\n        { status: 'failed', error: new TypeError('copyBlob expects a Blob.') } as const,\n        options?.onError,\n      );\n    }\n\n    const ownType: unknown = (blob as { type?: unknown }).type;\n    const type =\n      mimeType ?? (typeof ownType === 'string' && ownType.length > 0 ? ownType : FallbackMimeType);\n\n    return await copyItems({ [type]: blob }, options);\n  } catch (error) {\n    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);\n  }\n}\n","// Reading the clipboard — the most restricted operation in the slice, and usually the wrong one to reach for.\n//\n// READ THIS BEFORE USING EITHER FUNCTION. Reading the clipboard is reading a user's data, so browsers gate it far\n// harder than writing:\n//  - it requires a user gesture, and outside one the platform refuses (`denied`);\n//  - Chromium shows an explicit \"Allow the site to see text and images on the clipboard?\" prompt, and a\n//    dismissal is a `denied` — a decision by the user, not a bug to retry;\n//  - Firefox does not expose `readText` / `read` to page script at ALL. Only extensions get them. That surfaces\n//    here as `unsupported` rather than a generic `failed`, because the two need different UI: `failed` invites a\n//    retry, `unsupported` means stop asking and render the manual affordance instead.\n//\n// IF YOU WANT WHAT THE USER JUST PASTED, DO NOT READ. Handle the `paste` event and call `getPasteItems` — the\n// payload arrives on the event, no permission, no prompt, no gesture check, and it works in every engine\n// including Firefox. Reading is for the narrow case of pulling the clipboard WITHOUT a paste, like a \"detect a\n// copied invite code on focus\" affordance. That case is rare and worth questioning.\n//\n// An empty clipboard reads as `''` / `[]` and is a successful read of nothing, not a failure — a consumer\n// distinguishes \"nothing to paste\" from \"we could not look\" by the status, not by the payload's emptiness.\n\nimport {\n  reportClipboardOutcome,\n  toClipboardFailure,\n  type ClipboardReadItem,\n  type ClipboardReadItemsResult,\n  type ClipboardReadOptions,\n  type ClipboardReadTextResult,\n} from './ClipboardResult';\nimport { clipboardMethod } from './ClipboardSupport';\n\n/**\n * Turns one platform `ClipboardItem` into its flat `{ type, blob }` representations.\n *\n * Each type is resolved independently and a type that fails to resolve is SKIPPED rather than failing the read:\n * a clipboard entry carrying `text/plain` plus an exotic type the engine cannot materialize should still yield\n * its text. Never throws.\n */\nasync function flattenItem(item: ClipboardItem): Promise<ClipboardReadItem[]> {\n  const flattened: ClipboardReadItem[] = [];\n\n  let types: readonly string[];\n  try {\n    const declared: unknown = item.types;\n    if (!Array.isArray(declared)) return flattened;\n    types = declared as readonly string[];\n  } catch {\n    return flattened;\n  }\n\n  for (const type of types) {\n    if (typeof type !== 'string') continue;\n    try {\n      const blob = await item.getType(type);\n      if (typeof blob === 'object' && blob !== null) flattened.push({ type, blob });\n    } catch {\n      // This representation could not be materialized. The others still can.\n    }\n  }\n\n  return flattened;\n}\n\n/**\n * Reads the clipboard's plain text.\n *\n * Requires a user gesture and, in Chromium, an explicit permission prompt the user can dismiss — a dismissal is\n * `denied`. Resolves to `unsupported` under SSR and in Firefox, which withholds clipboard reading from page\n * script entirely.\n *\n * Prefer `getPasteItems` on a `paste` event wherever the flow is \"the user pastes something\": that path needs no\n * permission and works everywhere.\n *\n * Never throws, never rejects.\n *\n * @param options Error reporting.\n */\nexport async function readText(options?: ClipboardReadOptions): Promise<ClipboardReadTextResult> {\n  try {\n    const read = clipboardMethod('readText');\n    if (read === undefined) return { status: 'unsupported' };\n\n    const text = await read();\n    return typeof text === 'string'\n      ? { status: 'read', text }\n      : reportClipboardOutcome(\n          {\n            status: 'failed',\n            error: new TypeError('navigator.clipboard.readText resolved with a non-string.'),\n          } as const,\n          options?.onError,\n        );\n  } catch (error) {\n    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);\n  }\n}\n\n/**\n * Reads every representation currently on the clipboard — the multi-format counterpart of {@link readText}, and\n * the only way to pull a copied image.\n *\n * Same gating as {@link readText}, and narrower support still: `navigator.clipboard.read` postdates `readText`\n * in every engine that has it. Representations the platform cannot materialize are dropped from the result\n * rather than failing the whole read.\n *\n * Never throws, never rejects.\n *\n * @param options Error reporting.\n */\nexport async function readItems(options?: ClipboardReadOptions): Promise<ClipboardReadItemsResult> {\n  try {\n    const read = clipboardMethod('read');\n    if (read === undefined) return { status: 'unsupported' };\n\n    const raw: unknown = await read();\n    if (!Array.isArray(raw)) {\n      return reportClipboardOutcome(\n        { status: 'failed', error: new TypeError('navigator.clipboard.read resolved with a non-array.') } as const,\n        options?.onError,\n      );\n    }\n\n    const items: ClipboardReadItem[] = [];\n    for (const entry of raw as readonly ClipboardItem[]) {\n      if (typeof entry !== 'object' || entry === null) continue;\n      items.push(...(await flattenItem(entry)));\n    }\n\n    return { status: 'read', items };\n  } catch (error) {\n    return reportClipboardOutcome(toClipboardFailure(error), options?.onError);\n  }\n}\n","// Extracting a paste — the clipboard path that needs NO permission at all, and the right answer for most\n// \"let the user paste an image\" features.\n//\n// WHY THIS IS THE DEFAULT AND `readText` IS NOT. When the user presses Ctrl+V they have already authorized the\n// transfer; the browser hands the payload to the page on the `paste` event with no prompt, no gesture check, and\n// no engine carve-outs — this works in Firefox, where `navigator.clipboard.readText` does not exist. Any feature\n// framed as \"the user pastes something\" should be built here. Reading the clipboard directly is for the narrow\n// case of looking WITHOUT a paste.\n//\n// EVERY READ IS GUARDED. `clipboardData` is nullable in the DOM's own types, `getData` throws in some engines\n// when called outside the event's dispatch, and a synthetic event (a test double, a virtual-DOM shim) may carry\n// a partial `DataTransfer`. A paste handler that throws on a malformed event breaks the user's paste entirely,\n// so every access falls back to \"this representation is absent\".\n//\n// Files come from `items` first and `files` second. `DataTransferItemList` is what carries an image pasted from\n// the OS screenshot tool, where `files` is sometimes empty; `files` is the reliable one for a file copied out of\n// a file manager. Reading `items` first and only falling back avoids reporting the same file twice.\n\n/** What a paste carried, normalized to the three representations a consumer acts on. */\nexport interface PasteItems {\n  /** The `text/plain` representation, or `undefined` when the paste carried none (a bare image paste). */\n  readonly text: string | undefined;\n\n  /** The `text/html` representation, or `undefined`. Present when copying from a rich source — sanitize before rendering. */\n  readonly html: string | undefined;\n\n  /** Files on the paste — a screenshot, an image, a document. Empty when the paste was text only. */\n  readonly files: readonly File[];\n}\n\n/** Reads a member off an object, guarded — a throwing getter reads as `undefined`. */\nfunction member(source: object, key: string): unknown {\n  try {\n    return (source as Record<string, unknown>)[key];\n  } catch {\n    return undefined;\n  }\n}\n\n/** Reads one MIME representation as a string. Absent, blank, and throwing all read as `undefined`. */\nfunction readData(data: DataTransfer, type: string): string | undefined {\n  try {\n    const getData = member(data, 'getData');\n    if (typeof getData !== 'function') return undefined;\n\n    const value: unknown = (getData as (type: string) => unknown).call(data, type);\n    return typeof value === 'string' && value.length > 0 ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Collects files from `DataTransfer.items`, skipping non-file entries and any entry that refuses to resolve. */\nfunction filesFromItems(data: DataTransfer): File[] {\n  const files: File[] = [];\n  try {\n    const list = member(data, 'items');\n    if (typeof list !== 'object' || list === null) return files;\n\n    const length = member(list, 'length');\n    if (typeof length !== 'number') return files;\n\n    const items = list as DataTransferItemList;\n    for (let index = 0; index < length; index++) {\n      try {\n        const item = items[index];\n        if (item === undefined || item === null) continue;\n        if (item.kind !== 'file' || typeof item.getAsFile !== 'function') continue;\n\n        const file = item.getAsFile();\n        if (file !== null) files.push(file);\n      } catch {\n        // One malformed entry does not invalidate the others.\n      }\n    }\n  } catch {\n    // No usable item list. `files` is the fallback.\n  }\n  return files;\n}\n\n/** Collects files from `DataTransfer.files` — the `FileList` fallback when the item list yielded nothing. */\nfunction filesFromFileList(data: DataTransfer): File[] {\n  const files: File[] = [];\n  try {\n    const list = member(data, 'files');\n    if (typeof list !== 'object' || list === null) return files;\n\n    const length = member(list, 'length');\n    if (typeof length !== 'number') return files;\n\n    const fileList = list as FileList;\n    for (let index = 0; index < length; index++) {\n      const file = fileList[index];\n      if (file !== undefined && file !== null) files.push(file);\n    }\n  } catch {\n    // Nothing readable here either. An empty file list is a valid answer.\n  }\n  return files;\n}\n\n/**\n * Extracts the text, HTML, and files a `paste` event carried.\n *\n * Needs no permission and no user gesture — the event IS the user's authorization — and works in every engine,\n * including the ones that withhold `navigator.clipboard.read`. This is the path to build \"paste an image\"\n * features on.\n *\n * Does not call `preventDefault`: suppressing the browser's own paste is the consumer's decision, and a handler\n * that reads the payload for a side effect usually wants the default insert to happen too. `usePasteHandler`\n * exposes it as an option.\n *\n * Never throws — a malformed or partial event yields `{ text: undefined, html: undefined, files: [] }`.\n *\n * @param event The `paste` event, from a `@paste` binding or a native listener.\n */\nexport function getPasteItems(event: ClipboardEvent): PasteItems {\n  const empty: PasteItems = { text: undefined, html: undefined, files: [] };\n\n  try {\n    if (typeof event !== 'object' || event === null) return empty;\n\n    const transfer = member(event, 'clipboardData');\n    if (typeof transfer !== 'object' || transfer === null) return empty;\n\n    const data = transfer as DataTransfer;\n    const fromItems = filesFromItems(data);\n\n    return {\n      text: readData(data, 'text/plain'),\n      html: readData(data, 'text/html'),\n      files: fromItems.length > 0 ? fromItems : filesFromFileList(data),\n    };\n  } catch {\n    return empty;\n  }\n}\n","// The Vue binding of the paste path — a `paste` listener with the extraction already done and the teardown\n// guaranteed.\n//\n// WHY A COMPOSABLE RATHER THAN AN `@paste` BINDING. A template `@paste` only fires for a paste into that\n// element, which requires it to be focusable and focused. The common feature — \"paste a screenshot anywhere on\n// this page\" — needs a `window` listener, and hand-rolling one means a watcher and a cleanup that people\n// forget. Defaulting to `window` and accepting a `target` ref covers both shapes.\n//\n// The handler is called through the closure rather than captured into the listener, so it can never go stale;\n// a component's `setup` runs once, so the one the consumer passes is the one and only. Only `enabled` /\n// `target` / `preventDefault` re-run the effect, because only those change what is bound.\n//\n// SSR: the effect is post-flush, the default target is resolved LAZILY behind a `typeof window` guard, and a\n// `target` ref is `null` on the server — so nothing here reaches for `window` during a server render. This is\n// the same lazy-default shape `foundation/hooks`' `useEventListener` uses.\n//\n// A throw from the consumer's handler is swallowed. Inside a native listener a throw does not reject anything —\n// it escapes to `window.onerror` and, worse, skips the rest of the listener including a `preventDefault` the\n// consumer asked for. Absorbing it keeps the slice's never-throws contract at the one boundary where the\n// consumer's own code runs.\n\nimport { toValue, watchPostEffect, type MaybeRefOrGetter } from 'vue';\n\nimport { getPasteItems, type PasteItems } from './PasteItems';\n\n/** Tunes a {@link usePasteHandler} binding. */\nexport interface UsePasteHandlerOptions {\n  /**\n   * The element to listen on. Defaults to `window`, which catches a paste anywhere on the page — the right\n   * default for a drop-zone or an editor surface that is not itself focused. Pass a ref or getter to scope the\n   * listener to one element.\n   */\n  readonly target?: MaybeRefOrGetter<HTMLElement | null | undefined>;\n\n  /**\n   * Whether the listener is attached. Defaults to `true`; pass `false` to suspend it without tearing down — a\n   * modal that should own pastes only while open.\n   */\n  readonly enabled?: MaybeRefOrGetter<boolean | undefined>;\n\n  /**\n   * Whether to call `preventDefault()` on the event, suppressing the browser's own paste. Defaults to `false`.\n   *\n   * Turn it on when the handler fully owns the paste (inserting the image itself); leave it off when the handler\n   * is a side effect and the default insert should still happen. Applied BEFORE the handler runs, so a throw\n   * from the handler cannot skip it.\n   */\n  readonly preventDefault?: MaybeRefOrGetter<boolean | undefined>;\n}\n\n/**\n * Binds a `paste` listener that hands the handler the event's already-extracted text, HTML, and files.\n *\n * Needs no clipboard permission — see `PasteItems.ts` for why this is the path to prefer over `readText`.\n * Detaches on scope disposal, and on any change to `enabled` / `target` / `preventDefault`.\n *\n * @param handler Called on every paste with the extracted payload and the original event. A throw from it is\n *   swallowed.\n * @param options Where to listen, whether to listen, and whether to suppress the default paste.\n */\nexport function usePasteHandler(\n  handler: (items: PasteItems, event: ClipboardEvent) => void,\n  options?: UsePasteHandlerOptions,\n): void {\n  watchPostEffect((onCleanup) => {\n    if ((toValue(options?.enabled) ?? true) === false) return;\n\n    // Resolved lazily and guarded: importing this in an SSR pass must never touch `window`.\n    const node: EventTarget | null =\n      toValue(options?.target) ?? (typeof window === 'undefined' ? null : window);\n    if (node === null || typeof node.addEventListener !== 'function') return;\n\n    // Captured at attach time so remove uses the same behaviour the listener was bound with.\n    const preventDefault = toValue(options?.preventDefault) ?? false;\n\n    const listener = (event: Event): void => {\n      const pasteEvent = event as ClipboardEvent;\n      if (preventDefault) {\n        try {\n          pasteEvent.preventDefault();\n        } catch {\n          // A synthetic event without a usable `preventDefault`. The handler still gets its payload.\n        }\n      }\n\n      try {\n        handler(getPasteItems(pasteEvent), pasteEvent);\n      } catch {\n        // The consumer's handler failed. Their problem — and not a reason to break the listener for the next\n        // paste, which is what an escaping throw would risk.\n      }\n    };\n\n    node.addEventListener('paste', listener);\n    onCleanup(() => node.removeEventListener('paste', listener));\n  });\n}\n","// The Vue binding of the write path — the transient \"Copied!\" affordance, without hiding the outcome.\n//\n// THE DIFFERENCE FROM `foundation/hooks`' `useClipboard`: that composable's `copy` resolves `Promise<void>` on\n// both success and failure, folding the error into reactive state. A caller cannot branch on the outcome, and\n// anything that is not a component cannot see it at all. Here `copy` resolves to the same\n// `ClipboardWriteResult` the framework-free `copyText` returns, so the awaiting code can branch AND the\n// rendered `status` still drives the icon swap. State is the affordance; the result is the answer. Neither\n// replaces the other.\n//\n// `status` carries the failure statuses too, not just `copied`. A copy that came back `denied` needs its own\n// rendering — \"Press Ctrl+C to copy\" beside a still-selectable field — and a composable that exposed only a\n// boolean would force the consumer to keep a parallel error state, which is the flaw above in a different shape.\n//\n// The auto-reset applies to EVERY terminal status, not only `copied`: a stuck error badge is as wrong as a stuck\n// \"Copied!\". A consumer that wants a sticky failure passes `resetAfterMs: 0` and calls `reset` itself.\n//\n// The timer is cleared on scope disposal, and a `disposed` flag gates the post-await state write. The `await`\n// can outlive the component — a user copying and immediately closing the dialog — and scheduling a timeout from\n// a callback whose scope is gone would leave a timer with nothing to update.\n//\n// Nothing here touches a platform global at setup: `copyText` is only reached from a user gesture.\n\nimport { onScopeDispose, shallowRef, toValue, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport type { ClipboardCopyOptions, ClipboardWriteResult, ClipboardWriteStatus } from './ClipboardResult';\nimport { copyText } from './CopyText';\n\n/** How long a status lingers before the composable returns to `idle`, when the caller does not say. */\nconst DefaultResetAfterMs = 2000;\n\n/** Where a {@link useClipboardCopy} instance sits: `idle` before the first attempt, otherwise the last outcome. */\nexport type ClipboardCopyState = 'idle' | ClipboardWriteStatus;\n\n/** Tunes a {@link useClipboardCopy} instance. */\nexport interface UseClipboardCopyOptions extends ClipboardCopyOptions {\n  /**\n   * How long `status` holds the last outcome before returning to `idle`, in milliseconds. Defaults to 2000 —\n   * long enough to read \"Copied!\", short enough not to linger.\n   *\n   * Pass `0` to hold the status until {@link ClipboardCopyControls.reset} is called, which is what a failure\n   * message the user must acknowledge wants.\n   */\n  readonly resetAfterMs?: number;\n}\n\n/** What {@link useClipboardCopy} returns. */\nexport interface ClipboardCopyControls {\n  /**\n   * The last outcome, or `idle` before the first attempt and after the reset window. Drives the icon swap, the\n   * \"Copied!\" label, and the `denied` / `unsupported` fallback copy.\n   */\n  readonly status: Readonly<ShallowRef<ClipboardCopyState>>;\n\n  /**\n   * Writes `text` to the clipboard and resolves to the full result — the awaiting caller branches on the\n   * outcome, while `status` drives the render. Never throws, never rejects.\n   */\n  readonly copy: (text: string) => Promise<ClipboardWriteResult>;\n\n  /** Returns `status` to `idle` immediately and cancels the pending auto-reset. */\n  readonly reset: () => void;\n}\n\n/**\n * Wraps `copyText` in a transient status for post-action UI, without swallowing the outcome.\n *\n * Call `copy` from a user gesture — the platform requires transient activation, and a copy fired from a watcher\n * or a timeout comes back `denied`.\n *\n * @param options Error reporting, the legacy-fallback opt-in, and the auto-reset window. Read fresh on every\n *   call, so a ref or getter keeps them live.\n */\nexport function useClipboardCopy(\n  options?: MaybeRefOrGetter<UseClipboardCopyOptions | undefined>,\n): ClipboardCopyControls {\n  const status = shallowRef<ClipboardCopyState>('idle');\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let disposed = false;\n\n  /** Cancels a pending auto-reset. Safe to call when none is scheduled. */\n  function clearTimer(): void {\n    if (timer === null) return;\n    clearTimeout(timer);\n    timer = null;\n  }\n\n  onScopeDispose(() => {\n    disposed = true;\n    clearTimer();\n  });\n\n  const copy = async (text: string): Promise<ClipboardWriteResult> => {\n    const result = await copyText(text, toValue(options));\n\n    // The scope may have been disposed while the write was in flight. The RESULT still goes back to the\n    // caller — it is the answer to their call, not a piece of this component's state.\n    if (disposed) return result;\n\n    clearTimer();\n    status.value = result.status;\n\n    const resetAfterMs = toValue(options)?.resetAfterMs ?? DefaultResetAfterMs;\n    if (resetAfterMs > 0) {\n      timer = setTimeout(() => {\n        timer = null;\n        status.value = 'idle';\n      }, resetAfterMs);\n    }\n\n    return result;\n  };\n\n  const reset = (): void => {\n    clearTimer();\n    status.value = 'idle';\n  };\n\n  return { status, copy, reset };\n}\n","// The permission read — thin on purpose, and less useful than it looks.\n//\n// It delegates to `foundation/notifications`' `queryPermission`, which already wraps `navigator.permissions`\n// with exactly the guards this needs: absent API, an unknown permission name (Safari THROWS synchronously rather\n// than resolving), and an off-spec state string. Duplicating that here would be a second copy of a subtle\n// wrapper. The import is a deep one rather than the notifications barrel so this slice does not pull that\n// slice's Vue composables and `Notification` plumbing into the clipboard bundle.\n//\n// WHY `unsupported` IS THE COMMON ANSWER. `clipboard-read` and `clipboard-write` are not universally implemented\n// permission NAMES: Chromium has both, Firefox has neither, Safari rejects them. So this returns `unsupported`\n// on most of the web — which means \"we could not ask\", NOT \"the operation will fail\". Firefox writes to the\n// clipboard perfectly well while reporting `unsupported` here.\n//\n// CONSEQUENCE FOR CALLERS: do not gate a copy button on this. Attempt the write and branch on its result — the\n// operation is the only honest test of whether it is allowed. This helper is for the narrow case of rendering a\n// pre-emptive explanation where the answer happens to be known (a Chromium-only internal tool, a \"we will ask\n// for clipboard access\" notice before a paste-detection feature).\n\nimport { queryPermission, type PermissionQueryState } from '../notifications/QueryPermission';\n\n/** Which half of the clipboard a permission query is about. */\nexport type ClipboardPermissionMode = 'read' | 'write';\n\n/** The Permissions API names, which differ from this slice's vocabulary and are not implemented everywhere. */\nconst PermissionNames: Readonly<Record<ClipboardPermissionMode, string>> = {\n  read: 'clipboard-read',\n  write: 'clipboard-write',\n};\n\n/**\n * Reads the browser's recorded permission for clipboard reading or writing.\n *\n * Returns `unsupported` wherever the Permissions API is absent or does not implement the name — which is most\n * browsers, including all of Firefox and Safari. Read that as \"unknown\", never as \"denied\": the capability is\n * frequently available where the QUERY is not.\n *\n * A one-shot snapshot; the browser fires no event on this promise.\n *\n * Never throws, never rejects.\n *\n * @param mode `'read'` for `clipboard-read`, `'write'` for `clipboard-write`.\n */\nexport async function getClipboardPermission(mode: ClipboardPermissionMode): Promise<PermissionQueryState> {\n  const name = PermissionNames[mode];\n  if (name === undefined) return 'unsupported';\n  return queryPermission(name);\n}\n"],"names":["member"],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/clipboard/CopyItems.ts","../../../src/foundation/clipboard/ReadClipboard.ts","../../../src/foundation/clipboard/PasteItems.ts","../../../src/foundation/clipboard/hooks/UsePasteHandler.ts","../../../src/foundation/clipboard/hooks/UseClipboardCopy.ts","../../../src/foundation/clipboard/ClipboardPermission.ts","../../../src/foundation/clipboard/ClipboardFailureCode.ts"],"sourcesContent":["import {\n  reportClipboardOutcome,\n  toClipboardFailure,\n  type ClipboardCopyOptions,\n  type ClipboardWriteResult,\n} from './ClipboardResult';\nimport { clipboardItemConstructor, clipboardMethod } from './ClipboardSupport';\nimport { withLegacyFallback } from './LegacyCopy';\n\n/**\n * The representations of one clipboard entry, keyed by MIME type.\n *\n * A `string` value is wrapped in a `Blob` of that same type before it reaches the platform. Engines accept only\n * a small set of types — `text/plain`, `text/html`, `image/png` are the portable ones; anything else may be\n * refused with a `failed` result.\n *\n * @example\n * copyItems({ 'text/plain': 'Total: 42', 'text/html': '<b>Total:</b> 42' });\n */\nexport type ClipboardWriteItems = Readonly<Record<string, Blob | string>>;\n\n/** The MIME type a blob with no type of its own is written under — deliberately generic, and often refused. */\nconst FallbackMimeType = 'application/octet-stream';\n\n/** The representation the legacy path can degrade to. */\nconst PlainTextMimeType = 'text/plain';\n\n/** Pulls the plain-text arm out, for the legacy fallback only. `undefined` unless it is a literal string. */\nfunction plainTextArm(items: ClipboardWriteItems): string | undefined {\n  try {\n    const value = items[PlainTextMimeType];\n    return typeof value === 'string' ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Normalizes every representation to a `Blob` typed with its own key. Throws only if `Blob` itself does. */\nfunction toBlobRecord(items: ClipboardWriteItems): Record<string, Blob> {\n  const record: Record<string, Blob> = {};\n  for (const [type, value] of Object.entries(items)) {\n    record[type] = typeof value === 'string' ? new Blob([value], { type }) : value;\n  }\n  return record;\n}\n\n/** Runs the Clipboard API multi-format write, mapping every outcome onto the result union. Never throws. */\nasync function writeItemsThroughApi(items: ClipboardWriteItems): Promise<ClipboardWriteResult> {\n  const write = clipboardMethod('write');\n  const ClipboardItemConstructor = clipboardItemConstructor();\n  if (write === undefined || ClipboardItemConstructor === undefined)\n    return { ok: false, failure: { status: 'unsupported' } };\n\n  try {\n    await write([new ClipboardItemConstructor(toBlobRecord(items))]);\n    return { ok: true, value: undefined };\n  } catch (error) {\n    return { ok: false, failure: toClipboardFailure(error) };\n  }\n}\n\n/**\n * Writes several representations of one payload to the clipboard in a single entry, so the paste target can pick\n * the richest format it understands.\n *\n * Needs `navigator.clipboard.write` and a `ClipboardItem` constructor — strictly newer than the `writeText`\n * behind `copyText`, so `unsupported` is more likely here. With `legacyFallback: true` an unsupported or refused\n * write degrades to the `text/plain` arm alone, and only when that arm is a literal string.\n *\n * Call it from a user gesture. Never throws, never rejects.\n *\n * @param items The representations, keyed by MIME type. An empty object resolves to `failed` — a write with no\n *   payload is a caller mistake, and reporting it as `copied` would claim something reached the clipboard.\n * @param options Error reporting and the legacy-fallback opt-in.\n */\nexport async function copyItems(\n  items: ClipboardWriteItems,\n  options?: ClipboardCopyOptions,\n): Promise<ClipboardWriteResult> {\n  try {\n    if (typeof items !== 'object' || items === null) {\n      return reportClipboardOutcome(\n        {\n          ok: false,\n          failure: { status: 'failed', error: new TypeError('copyItems expects an object keyed by MIME type.') },\n        } as const,\n        options?.onError,\n      );\n    }\n\n    if (Object.keys(items).length === 0) {\n      return reportClipboardOutcome(\n        {\n          ok: false,\n          failure: { status: 'failed', error: new Error('copyItems was given no representations to write.') },\n        } as const,\n        options?.onError,\n      );\n    }\n\n    const result = withLegacyFallback(await writeItemsThroughApi(items), plainTextArm(items), options);\n    return reportClipboardOutcome(result, options?.onError);\n  } catch (error) {\n    return reportClipboardOutcome({ ok: false, failure: toClipboardFailure(error) }, options?.onError);\n  }\n}\n\n/**\n * Writes a single binary payload — a generated image, a canvas export, a downloaded file — to the clipboard.\n *\n * The single-format case of {@link copyItems}, and subject to the same support: it needs\n * `navigator.clipboard.write`, and the legacy fallback cannot serve it (`execCommand` writes text only).\n *\n * Engines accept a narrow set of types for binary payloads; `image/png` is the portable one. A type the platform\n * refuses comes back `failed`.\n *\n * Never throws, never rejects.\n *\n * @param blob The payload.\n * @param mimeType The type to write it under. Defaults to the blob's own `type`, then to\n *   `application/octet-stream` — which most engines refuse, so pass a real type for a typeless blob.\n * @param options Error reporting. `legacyFallback` has no effect here.\n */\nexport async function copyBlob(\n  blob: Blob,\n  mimeType?: string,\n  options?: ClipboardCopyOptions,\n): Promise<ClipboardWriteResult> {\n  try {\n    if (typeof blob !== 'object' || blob === null) {\n      return reportClipboardOutcome(\n        { ok: false, failure: { status: 'failed', error: new TypeError('copyBlob expects a Blob.') } } as const,\n        options?.onError,\n      );\n    }\n\n    const ownType: unknown = (blob as { type?: unknown }).type;\n    const type = mimeType ?? (typeof ownType === 'string' && ownType.length > 0 ? ownType : FallbackMimeType);\n\n    return await copyItems({ [type]: blob }, options);\n  } catch (error) {\n    return reportClipboardOutcome({ ok: false, failure: toClipboardFailure(error) }, options?.onError);\n  }\n}\n","import {\n  reportClipboardOutcome,\n  toClipboardFailure,\n  type ClipboardReadItem,\n  type ClipboardReadItemsResult,\n  type ClipboardReadOptions,\n  type ClipboardReadTextResult,\n} from './ClipboardResult';\nimport { clipboardMethod } from './ClipboardSupport';\n\n/**\n * Turns one platform `ClipboardItem` into its flat `{ type, blob }` representations.\n *\n * Each type is resolved independently and a type that fails to resolve is SKIPPED rather than failing the read:\n * a clipboard entry carrying `text/plain` plus an exotic type the engine cannot materialize should still yield\n * its text. Never throws.\n */\nasync function flattenItem(item: ClipboardItem): Promise<ClipboardReadItem[]> {\n  const flattened: ClipboardReadItem[] = [];\n\n  let types: ReadonlyArray<string>;\n  try {\n    const declared: unknown = item.types;\n    if (!Array.isArray(declared)) return flattened;\n    types = declared as readonly string[];\n  } catch {\n    return flattened;\n  }\n\n  for (const type of types) {\n    if (typeof type !== 'string') continue;\n    try {\n      const blob = await item.getType(type);\n      if (typeof blob === 'object' && blob !== null) flattened.push({ type, blob });\n    } catch {\n      // This representation could not be materialized. The others still can.\n    }\n  }\n\n  return flattened;\n}\n\n/**\n * Reads the clipboard's plain text.\n *\n * Requires a user gesture and, in Chromium, an explicit permission prompt the user can dismiss — a dismissal is\n * `denied`. Resolves to `unsupported` when the runtime lacks the method, including under SSR.\n *\n * Prefer `getPasteItems` on a `paste` event wherever the flow is \"the user pastes something\": that path needs no\n * permission and works everywhere.\n *\n * Never throws, never rejects.\n *\n * @param options Error reporting.\n */\nexport async function readText(options?: ClipboardReadOptions): Promise<ClipboardReadTextResult> {\n  try {\n    const read = clipboardMethod('readText');\n    if (read === undefined) return { ok: false, failure: { status: 'unsupported' } };\n\n    const text = await read();\n    return typeof text === 'string'\n      ? { ok: true, value: text }\n      : reportClipboardOutcome(\n          {\n            ok: false,\n            failure: {\n              status: 'failed',\n              error: new TypeError('navigator.clipboard.readText resolved with a non-string.'),\n            },\n          } as const,\n          options?.onError,\n        );\n  } catch (error) {\n    return reportClipboardOutcome({ ok: false, failure: toClipboardFailure(error) }, options?.onError);\n  }\n}\n\n/**\n * Reads every representation currently on the clipboard — the multi-format counterpart of {@link readText}, and\n * the only way to pull a copied image.\n *\n * Same gating as {@link readText}, and narrower support still: `navigator.clipboard.read` postdates `readText`\n * in every engine that has it. Representations the platform cannot materialize are dropped from the result\n * rather than failing the whole read.\n *\n * Never throws, never rejects.\n *\n * @param options Error reporting.\n */\nexport async function readItems(options?: ClipboardReadOptions): Promise<ClipboardReadItemsResult> {\n  try {\n    const read = clipboardMethod('read');\n    if (read === undefined) return { ok: false, failure: { status: 'unsupported' } };\n\n    const raw: unknown = await read();\n    if (!Array.isArray(raw)) {\n      return reportClipboardOutcome(\n        {\n          ok: false,\n          failure: { status: 'failed', error: new TypeError('navigator.clipboard.read resolved with a non-array.') },\n        } as const,\n        options?.onError,\n      );\n    }\n\n    const items: ClipboardReadItem[] = [];\n    for (const entry of raw as readonly ClipboardItem[]) {\n      if (typeof entry !== 'object' || entry === null) continue;\n      items.push(...(await flattenItem(entry)));\n    }\n\n    return { ok: true, value: items };\n  } catch (error) {\n    return reportClipboardOutcome({ ok: false, failure: toClipboardFailure(error) }, options?.onError);\n  }\n}\n","/** What a paste carried, normalized to the three representations a consumer acts on. */\nexport interface PasteItems {\n  /** The `text/plain` representation, or `undefined` when the paste carried none (a bare image paste). */\n  readonly text: string | undefined;\n\n  /** The `text/html` representation, or `undefined`. Present from a rich source — sanitize before rendering. */\n  readonly html: string | undefined;\n\n  /** Files on the paste — a screenshot, an image, a document. Empty when the paste was text only. */\n  readonly files: ReadonlyArray<File>;\n}\n\n/** Reads a member off an object, guarded — a throwing getter reads as `undefined`. */\nfunction member(source: object, key: string): unknown {\n  try {\n    return (source as Record<string, unknown>)[key];\n  } catch {\n    return undefined;\n  }\n}\n\n/** Reads one MIME representation as a string. Absent, blank, and throwing all read as `undefined`. */\nfunction readData(data: DataTransfer, type: string): string | undefined {\n  try {\n    const getData = member(data, 'getData');\n    if (typeof getData !== 'function') return undefined;\n\n    const value: unknown = (getData as (type: string) => unknown).call(data, type);\n    return typeof value === 'string' && value.length > 0 ? value : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\n/** Collects files from `DataTransfer.items`, skipping non-file entries and any entry that refuses to resolve. */\nfunction filesFromItems(data: DataTransfer): File[] {\n  const files: File[] = [];\n  try {\n    const list = member(data, 'items');\n    if (typeof list !== 'object' || list === null) return files;\n\n    const length = member(list, 'length');\n    if (typeof length !== 'number') return files;\n\n    const items = list as DataTransferItemList;\n    for (let index = 0; index < length; index++) {\n      try {\n        const item = items[index];\n        if (item === undefined || item === null) continue;\n        if (item.kind !== 'file' || typeof item.getAsFile !== 'function') continue;\n\n        const file = item.getAsFile();\n        if (file !== null) files.push(file);\n      } catch {\n        // One malformed entry does not invalidate the others.\n      }\n    }\n  } catch {\n    // No usable item list. `files` is the fallback.\n  }\n  return files;\n}\n\n/** Collects files from `DataTransfer.files` — the `FileList` fallback when the item list yielded nothing. */\nfunction filesFromFileList(data: DataTransfer): File[] {\n  const files: File[] = [];\n  try {\n    const list = member(data, 'files');\n    if (typeof list !== 'object' || list === null) return files;\n\n    const length = member(list, 'length');\n    if (typeof length !== 'number') return files;\n\n    const fileList = list as FileList;\n    for (let index = 0; index < length; index++) {\n      const file = fileList[index];\n      if (file !== undefined && file !== null) files.push(file);\n    }\n  } catch {\n    // Nothing readable here either. An empty file list is a valid answer.\n  }\n  return files;\n}\n\n/**\n * Extracts the text, HTML, and files a `paste` event carried.\n *\n * Needs no permission and no user gesture — the event IS the user's authorization — and works in every engine,\n * including the ones that withhold `navigator.clipboard.read`. This is the path to build \"paste an image\"\n * features on.\n *\n * Does not call `preventDefault`: suppressing the browser's own paste is the consumer's decision, and a handler\n * that reads the payload for a side effect usually wants the default insert to happen too. `usePasteHandler`\n * exposes it as an option.\n *\n * Never throws — a malformed or partial event yields `{ text: undefined, html: undefined, files: [] }`.\n *\n * @param event The `paste` event, from a `@paste` binding or a native listener.\n */\nexport function getPasteItems(event: ClipboardEvent): PasteItems {\n  const empty: PasteItems = { text: undefined, html: undefined, files: [] };\n\n  try {\n    if (typeof event !== 'object' || event === null) return empty;\n\n    const transfer = member(event, 'clipboardData');\n    if (typeof transfer !== 'object' || transfer === null) return empty;\n\n    const data = transfer as DataTransfer;\n    const fromItems = filesFromItems(data);\n\n    return {\n      text: readData(data, 'text/plain'),\n      html: readData(data, 'text/html'),\n      files: fromItems.length > 0 ? fromItems : filesFromFileList(data),\n    };\n  } catch {\n    return empty;\n  }\n}\n","import { toValue, watchPostEffect, type MaybeRefOrGetter } from 'vue';\n\nimport { getPasteItems, type PasteItems } from '../PasteItems';\n\n/** Tunes a {@link usePasteHandler} binding. */\nexport interface UsePasteHandlerOptions {\n  /**\n   * The element to listen on. Defaults to `window`, which catches a paste anywhere on the page — the right\n   * default for a drop-zone or an editor surface that is not itself focused. Pass a ref or getter to scope the\n   * listener to one element.\n   */\n  readonly target?: MaybeRefOrGetter<HTMLElement | null | undefined>;\n\n  /**\n   * Whether the listener is attached. Defaults to `true`; pass `false` to suspend it without tearing down — a\n   * modal that should own pastes only while open.\n   */\n  readonly enabled?: MaybeRefOrGetter<boolean | undefined>;\n\n  /**\n   * Whether to call `preventDefault()` on the event, suppressing the browser's own paste. Defaults to `false`.\n   *\n   * Turn it on when the handler fully owns the paste (inserting the image itself); leave it off when the handler\n   * is a side effect and the default insert should still happen. Applied BEFORE the handler runs, so a throw\n   * from the handler cannot skip it.\n   */\n  readonly preventDefault?: MaybeRefOrGetter<boolean | undefined>;\n}\n\n/**\n * Binds a `paste` listener that hands the handler the event's already-extracted text, HTML, and files.\n *\n * Needs no clipboard permission — see `PasteItems.ts` for why this is the path to prefer over `readText`.\n * Detaches on scope disposal, and on any change to `enabled` / `target` / `preventDefault`.\n *\n * @param handler Called on every paste with the extracted payload and the original event. A throw from it is\n *   swallowed.\n * @param options Where to listen, whether to listen, and whether to suppress the default paste.\n */\nexport function usePasteHandler(\n  handler: (items: PasteItems, event: ClipboardEvent) => void,\n  options?: UsePasteHandlerOptions,\n): void {\n  watchPostEffect((onCleanup) => {\n    if ((toValue(options?.enabled) ?? true) === false) return;\n\n    // Resolved lazily and guarded: importing this in an SSR pass must never touch `window`.\n    const node: EventTarget | null =\n      options?.target !== undefined ? (toValue(options.target) ?? null) : typeof window === 'undefined' ? null : window;\n    if (node === null || typeof node.addEventListener !== 'function') return;\n\n    // Captured at attach time so remove uses the same behaviour the listener was bound with.\n    const preventDefault = toValue(options?.preventDefault) ?? false;\n\n    const listener = (event: Event): void => {\n      const pasteEvent = event as ClipboardEvent;\n      if (preventDefault) {\n        try {\n          pasteEvent.preventDefault();\n        } catch {\n          // A synthetic event without a usable `preventDefault`. The handler still gets its payload.\n        }\n      }\n\n      try {\n        handler(getPasteItems(pasteEvent), pasteEvent);\n      } catch {\n        // The consumer's handler failed. Their problem — and not a reason to break the listener for the next\n        // paste, which is what an escaping throw would risk.\n      }\n    };\n\n    node.addEventListener('paste', listener);\n    onCleanup(() => node.removeEventListener('paste', listener));\n  });\n}\n","import { onScopeDispose, shallowRef, toValue, type MaybeRefOrGetter, type ShallowRef } from 'vue';\n\nimport type { ClipboardCopyOptions, ClipboardWriteResult, ClipboardWriteStatus } from '../ClipboardResult';\nimport { copyText } from '../CopyText';\n\n/** How long a status lingers before the composable returns to `idle`, when the caller does not say. */\nconst DefaultResetAfterMs = 2000;\n\n/** Where a {@link useClipboardCopy} instance sits: `idle` before the first attempt, otherwise the last outcome. */\nexport type ClipboardCopyState = 'idle' | ClipboardWriteStatus;\n\n/** Tunes a {@link useClipboardCopy} instance. */\nexport interface UseClipboardCopyOptions extends ClipboardCopyOptions {\n  /**\n   * How long `status` holds the last outcome before returning to `idle`, in milliseconds. Defaults to 2000 —\n   * long enough to read \"Copied!\", short enough not to linger.\n   *\n   * Pass `0` to hold the status until {@link ClipboardCopyControls.reset} is called, which is what a failure\n   * message the user must acknowledge wants.\n   */\n  readonly resetAfterMs?: number;\n}\n\n/** What {@link useClipboardCopy} returns. */\nexport interface ClipboardCopyControls {\n  /**\n   * The last outcome, or `idle` before the first attempt and after the reset window. Drives the icon swap, the\n   * \"Copied!\" label, and the `denied` / `unsupported` fallback copy.\n   */\n  readonly status: Readonly<ShallowRef<ClipboardCopyState>>;\n\n  /**\n   * Writes `text` to the clipboard and resolves to the full result — the awaiting caller branches on the\n   * outcome, while `status` drives the render. Never throws, never rejects.\n   */\n  readonly copy: (text: string) => Promise<ClipboardWriteResult>;\n\n  /** Returns `status` to `idle` immediately and cancels the pending auto-reset. */\n  readonly reset: () => void;\n}\n\n/**\n * Wraps `copyText` in a transient status for post-action UI, without swallowing the outcome.\n *\n * Call `copy` from a user gesture — the platform requires transient activation, and a copy fired from a watcher\n * or a timeout comes back `denied`.\n *\n * @param options Error reporting, the legacy-fallback opt-in, and the auto-reset window. Read fresh on every\n *   call, so a ref or getter keeps them live.\n */\nexport function useClipboardCopy(\n  options?: MaybeRefOrGetter<UseClipboardCopyOptions | undefined>,\n): ClipboardCopyControls {\n  const status = shallowRef<ClipboardCopyState>('idle');\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n  let disposed = false;\n  let generation = 0;\n\n  /** Cancels a pending auto-reset. Safe to call when none is scheduled. */\n  function clearTimer(): void {\n    if (timer === null) return;\n    clearTimeout(timer);\n    timer = null;\n  }\n\n  onScopeDispose(() => {\n    disposed = true;\n    clearTimer();\n  });\n\n  const copy = async (text: string): Promise<ClipboardWriteResult> => {\n    const operation = ++generation;\n    clearTimer();\n    const result = await copyText(text, toValue(options));\n\n    // The scope may have been disposed while the write was in flight. The RESULT still goes back to the\n    // caller — it is the answer to their call, not a piece of this component's state.\n    if (disposed || operation !== generation) return result;\n\n    clearTimer();\n    status.value = result.ok ? 'copied' : result.failure.status;\n\n    const resetAfterMs = toValue(options)?.resetAfterMs ?? DefaultResetAfterMs;\n    if (resetAfterMs > 0) {\n      timer = setTimeout(() => {\n        timer = null;\n        status.value = 'idle';\n      }, resetAfterMs);\n    }\n\n    return result;\n  };\n\n  const reset = (): void => {\n    generation++;\n    clearTimer();\n    status.value = 'idle';\n  };\n\n  return { status, copy, reset };\n}\n","import { queryPermission, type PermissionQueryState } from '../notifications/QueryPermission';\n\n/** Which half of the clipboard a permission query is about. */\nexport const ClipboardPermissionMode = {\n  /** Asks about reading the clipboard — the `clipboard-read` permission name. */\n  Read: 'read',\n\n  /** Asks about writing the clipboard — the `clipboard-write` permission name. */\n  Write: 'write',\n} as const;\n\n/** Which half of the clipboard a permission query is about. */\nexport type ClipboardPermissionMode = (typeof ClipboardPermissionMode)[keyof typeof ClipboardPermissionMode];\n\n/** The Permissions API names, which differ from this slice's vocabulary and are not implemented everywhere. */\nconst PermissionNames: Readonly<Record<ClipboardPermissionMode, string>> = {\n  read: 'clipboard-read',\n  write: 'clipboard-write',\n};\n\n/**\n * Reads the browser's recorded permission for clipboard reading or writing.\n *\n * Returns `unsupported` when the Permissions API cannot query the name. Treat this as unknown,\n * not denied: clipboard operations may remain available without a supported permission query.\n *\n * A one-shot snapshot; the browser fires no event on this promise.\n *\n * Never throws, never rejects.\n *\n * @param mode `'read'` for `clipboard-read`, `'write'` for `clipboard-write`.\n */\nexport async function getClipboardPermission(mode: ClipboardPermissionMode): Promise<PermissionQueryState> {\n  const name = PermissionNames[mode];\n  if (name === undefined) return 'unsupported';\n  return queryPermission(name);\n}\n","/** Closed failure vocabulary for ClipboardFailure. */\nexport const ClipboardFailureCode = {\n  Denied: 'denied',\n  Unsupported: 'unsupported',\n  Failed: 'failed',\n} as const;\n\nexport type ClipboardFailureCode = (typeof ClipboardFailureCode)[keyof typeof ClipboardFailureCode];\n"],"names":[],"mappings":"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"}

package/dist/foundation/clipboard/models/ClipboardFailure.d.ts

@@ -0,0 +1,11 @@
+import { ClipboardFailureCode } from '../ClipboardFailureCode';
+/** Expected reasons the operation could not produce its requested value. */
+export type ClipboardFailure = {
+    readonly status: typeof ClipboardFailureCode.Denied;
+    readonly error: Error;
+} | {
+    readonly status: typeof ClipboardFailureCode.Unsupported;
+} | {
+    readonly status: typeof ClipboardFailureCode.Failed;
+    readonly error: Error;
+};

package/dist/foundation/clipboard/models/ClipboardReadItemsResult.d.ts

@@ -0,0 +1,5 @@
+import { Result } from '../../results';
+import { ClipboardReadItem } from '../ClipboardResult';
+import { ClipboardFailure } from './ClipboardFailure';
+/** The completed operation, carrying either its value or its typed failure. */
+export type ClipboardReadItemsResult = Result<ReadonlyArray<ClipboardReadItem>, ClipboardFailure>;

package/dist/foundation/clipboard/models/ClipboardReadTextResult.d.ts

@@ -0,0 +1,4 @@
+import { Result } from '../../results';
+import { ClipboardFailure } from './ClipboardFailure';
+/** The completed operation, carrying either its value or its typed failure. */
+export type ClipboardReadTextResult = Result<string, ClipboardFailure>;

package/dist/foundation/clipboard/models/ClipboardWriteResult.d.ts

@@ -0,0 +1,4 @@
+import { Result } from '../../results';
+import { ClipboardFailure } from './ClipboardFailure';
+/** The completed operation, carrying either its value or its typed failure. */
+export type ClipboardWriteResult = Result<void, ClipboardFailure>;

package/dist/foundation/collections/Arrays.d.ts

@@ -1,4 +1,4 @@
-import { EqualityComparer } from '../utils/Equality';
+import { EqualityComparer } from './Equality';
 /**
  * Removes duplicates, keeping the FIRST occurrence of each key and the input's order.
  *
@@ -10,7 +10,7 @@ import { EqualityComparer } from '../utils/Equality';
  * @param keyFn Optional key extractor receiving the item and its index.
  * @returns A new array holding the first item per distinct key.
  */
-export declare function unique<T, TKey = T>(items: readonly T[], keyFn?: (item: T, index: number) => TKey): T[];
+export declare function unique<T, TKey = T>(items: ReadonlyArray<T>, keyFn?: (item: T, index: number) => TKey): T[];
 /**
  * Buckets items by an extracted key into a `Map`.
  *
@@ -22,7 +22,7 @@ export declare function unique<T, TKey = T>(items: readonly T[], keyFn?: (item:
  * @param keyFn Extracts the group key from an item and its index.
  * @returns A new `Map` of key to a new array of that key's items, both in first-seen order.
  */
-export declare function groupBy<T, TKey>(items: readonly T[], keyFn: (item: T, index: number) => TKey): Map<TKey, T[]>;
+export declare function groupBy<T, TKey>(items: ReadonlyArray<T>, keyFn: (item: T, index: number) => TKey): Map<TKey, T[]>;
 /**
  * Splits a list in two by a predicate, in one pass, preserving order in both halves.
  *
@@ -30,7 +30,7 @@ export declare function groupBy<T, TKey>(items: readonly T[], keyFn: (item: T, i
  * @param predicate Decides whether an item belongs to the first half.
  * @returns A `[matched, rest]` tuple of two new arrays.
  */
-export declare function partition<T>(items: readonly T[], predicate: (item: T, index: number) => boolean): [T[], T[]];
+export declare function partition<T>(items: ReadonlyArray<T>, predicate: (item: T, index: number) => boolean): [T[], T[]];
 /**
  * Slices a list into consecutive groups of at most `size`. The final group is short when the length is
  * not a multiple of `size`.
@@ -41,7 +41,7 @@ export declare function partition<T>(items: readonly T[], predicate: (item: T, i
  * @throws {RangeError} When `size` is not a positive integer — a zero or negative size has no meaningful
  * result and would loop forever.
  */
-export declare function chunk<T>(items: readonly T[], size: number): T[][];
+export declare function chunk<T>(items: ReadonlyArray<T>, size: number): T[][];
 /**
  * Reorders one item, using drag-and-drop semantics: the item is REMOVED first, then re-inserted at `to`
  * measured in the shortened list. This is the behaviour a pointer drag implies — dropping item 0 onto
@@ -56,7 +56,7 @@ export declare function chunk<T>(items: readonly T[], size: number): T[][];
  * @param to The index it should occupy afterwards.
  * @returns A new array with the item relocated; a new copy when `from` and `to` resolve to the same slot.
  */
-export declare function move<T>(items: readonly T[], from: number, to: number): T[];
+export declare function move<T>(items: ReadonlyArray<T>, from: number, to: number): T[];
 /**
  * Inserts one value at an index. The index is clamped to `[0, length]`, so `length` appends and a
  * negative index prepends.
@@ -66,7 +66,7 @@ export declare function move<T>(items: readonly T[], from: number, to: number):
  * @param value The value to insert.
  * @returns A new array one longer than the input.
  */
-export declare function insertAt<T>(items: readonly T[], index: number, value: T): T[];
+export declare function insertAt<T>(items: ReadonlyArray<T>, index: number, value: T): T[];
 /**
  * Removes the item at an index. An out-of-range index removes nothing and still returns a fresh copy.
  *
@@ -74,7 +74,7 @@ export declare function insertAt<T>(items: readonly T[], index: number, value: T
  * @param index The index to drop.
  * @returns A new array, one shorter when the index was in range.
  */
-export declare function removeAt<T>(items: readonly T[], index: number): T[];
+export declare function removeAt<T>(items: ReadonlyArray<T>, index: number): T[];
 /**
  * Replaces the item at an index. An out-of-range index replaces nothing and still returns a fresh copy —
  * it never grows the array or punches an `undefined` hole in it.
@@ -84,11 +84,11 @@ export declare function removeAt<T>(items: readonly T[], index: number): T[];
  * @param value The replacement value.
  * @returns A new array of the same length as the input.
  */
-export declare function replaceAt<T>(items: readonly T[], index: number, value: T): T[];
+export declare function replaceAt<T>(items: ReadonlyArray<T>, index: number, value: T): T[];
 /**
  * Adds an item when absent, removes it when present — the checkbox/chip/multi-select primitive.
  *
- * Equality defaults to `foundation/utils`' `Equality.strictEquals` (`Object.is`), which is reference
+ * Equality defaults to `foundation/collections`' `Equality.strictEquals` (`Object.is`), which is reference
  * equality for objects; pass `Equality.byKey((row) => row.id)` (or any comparer) when the toggled value is
  * a fresh object each render. EVERY match is removed, so a list that already held duplicates toggles all of
  * them off at once. An added item is appended at the end.
@@ -98,7 +98,7 @@ export declare function replaceAt<T>(items: readonly T[], index: number, value:
  * @param equalsFn Decides whether a list entry IS the toggled item.
  * @returns A new array with the item removed or appended.
  */
-export declare function toggleItem<T>(items: readonly T[], item: T, equalsFn?: EqualityComparer<T>): T[];
+export declare function toggleItem<T>(items: ReadonlyArray<T>, item: T, equalsFn?: EqualityComparer<T>): T[];
 /**
  * Pairs two lists positionally, stopping at the SHORTER one — the extra tail is dropped rather than
  * padded with `undefined`, so the result type has no holes to narrow away at every call site.
@@ -107,7 +107,7 @@ export declare function toggleItem<T>(items: readonly T[], item: T, equalsFn?: E
  * @param second The list supplying each pair's second slot.
  * @returns A new array of `[first, second]` tuples, `min(first.length, second.length)` long.
  */
-export declare function zip<TFirst, TSecond>(first: readonly TFirst[], second: readonly TSecond[]): Array<[TFirst, TSecond]>;
+export declare function zip<TFirst, TSecond>(first: ReadonlyArray<TFirst>, second: ReadonlyArray<TSecond>): Array<[TFirst, TSecond]>;
 /**
  * Splits a list of pairs back into two lists — the inverse of {@link zip}.
  *

package/dist/foundation/collections/Comparison.d.ts

@@ -9,7 +9,7 @@
  * @param second The right array.
  * @returns `true` when both have the same length and every index holds the same value.
  */
-export declare function arrayShallowEqual<T>(first: readonly T[], second: readonly T[]): boolean;
+export declare function arrayShallowEqual<T>(first: ReadonlyArray<T>, second: ReadonlyArray<T>): boolean;
 /**
  * Compares two values one level deep.
  *

package/dist/foundation/collections/Records.d.ts

@@ -7,7 +7,7 @@
  * @returns A new `Map` in first-seen key order.
  * @see groupBy — the same shape when a key can legitimately hold several items.
  */
-export declare function keyBy<T, TKey>(items: readonly T[], keyFn: (item: T, index: number) => TKey): Map<TKey, T>;
+export declare function keyBy<T, TKey>(items: ReadonlyArray<T>, keyFn: (item: T, index: number) => TKey): Map<TKey, T>;
 /**
  * Transforms every value, keeping the keys and their order. Overloaded on the container: a `Map` in gives
  * a `Map` out, a record in gives a record out.
@@ -36,7 +36,7 @@ export declare function mapValues<TKey extends PropertyKey, TValue, TResult>(sou
  * @param keys The keys to keep.
  * @returns A new object holding only the present named keys.
  */
-export declare function pickKeys<T extends object, TKey extends keyof T>(source: T, keys: readonly TKey[]): Pick<T, TKey>;
+export declare function pickKeys<T extends object, TKey extends keyof T>(source: T, keys: ReadonlyArray<TKey>): Pick<T, TKey>;
 /**
  * Copies every own enumerable string key EXCEPT the named ones into a new object — the immutable spelling
  * of `delete`, and the typed one (the result type loses the removed keys).
@@ -45,7 +45,7 @@ export declare function pickKeys<T extends object, TKey extends keyof T>(source:
  * @param keys The keys to drop.
  * @returns A new object without the named keys.
  */
-export declare function omitKeys<T extends object, TKey extends keyof T>(source: T, keys: readonly TKey[]): Omit<T, TKey>;
+export declare function omitKeys<T extends object, TKey extends keyof T>(source: T, keys: ReadonlyArray<TKey>): Omit<T, TKey>;
 /**
  * Collects key/value pairs into a record. Accepts any iterable, so a `Map`, a `URLSearchParams`, or the
  * output of {@link recordToEntries} all feed it directly. The LAST pair wins on a duplicate key.

package/dist/foundation/collections/SetOps.d.ts

@@ -10,7 +10,7 @@
  * @param keyFn Optional key extractor; defaults to the item itself (SameValueZero).
  * @returns A new array; neither input is mutated.
  */
-export declare function union<T, TKey = T>(first: readonly T[], second: readonly T[], keyFn?: (item: T) => TKey): T[];
+export declare function union<T, TKey = T>(first: ReadonlyArray<T>, second: ReadonlyArray<T>, keyFn?: (item: T) => TKey): T[];
 /**
  * Only the items whose key appears in BOTH lists, de-duplicated, in `first`'s order and holding `first`'s
  * item instances.
@@ -20,7 +20,7 @@ export declare function union<T, TKey = T>(first: readonly T[], second: readonly
  * @param keyFn Optional key extractor; defaults to the item itself (SameValueZero).
  * @returns A new array; neither input is mutated.
  */
-export declare function intersection<T, TKey = T>(first: readonly T[], second: readonly T[], keyFn?: (item: T) => TKey): T[];
+export declare function intersection<T, TKey = T>(first: ReadonlyArray<T>, second: ReadonlyArray<T>, keyFn?: (item: T) => TKey): T[];
 /**
  * The items of `first` whose key does NOT appear in `second`, de-duplicated, in `first`'s order.
  *
@@ -32,7 +32,7 @@ export declare function intersection<T, TKey = T>(first: readonly T[], second: r
  * @param keyFn Optional key extractor; defaults to the item itself (SameValueZero).
  * @returns A new array; neither input is mutated.
  */
-export declare function difference<T, TKey = T>(first: readonly T[], second: readonly T[], keyFn?: (item: T) => TKey): T[];
+export declare function difference<T, TKey = T>(first: ReadonlyArray<T>, second: ReadonlyArray<T>, keyFn?: (item: T) => TKey): T[];
 /**
  * Everything present in exactly one of the two lists — the "what changed" relation, `first`-only entries
  * followed by `second`-only entries.
@@ -42,4 +42,4 @@ export declare function difference<T, TKey = T>(first: readonly T[], second: rea
  * @param keyFn Optional key extractor; defaults to the item itself (SameValueZero).
  * @returns A new array; neither input is mutated.
  */
-export declare function symmetricDifference<T, TKey = T>(first: readonly T[], second: readonly T[], keyFn?: (item: T) => TKey): T[];
+export declare function symmetricDifference<T, TKey = T>(first: ReadonlyArray<T>, second: ReadonlyArray<T>, keyFn?: (item: T) => TKey): T[];

package/dist/foundation/collections/Tree.d.ts

@@ -28,7 +28,7 @@ export interface BuildTreeOptions<T, TId> {
  * @param options The `id` / `parentId` accessors.
  * @returns A new array of root nodes.
  */
-export declare function buildTree<T, TId>(items: readonly T[], options: BuildTreeOptions<T, TId>): TreeNode<T>[];
+export declare function buildTree<T, TId>(items: ReadonlyArray<T>, options: BuildTreeOptions<T, TId>): TreeNode<T>[];
 /**
  * Walks a nested structure depth-first, pre-order, into one flat list — parent before its children, which
  * is the order a collapsed/expanded tree view renders rows in.
@@ -39,7 +39,7 @@ export declare function buildTree<T, TId>(items: readonly T[], options: BuildTre
  * @param childrenKey The property holding a node's children; defaults to `'children'`.
  * @returns A new flat array of the same node objects.
  */
-export declare function flattenTree<TNode extends object>(nodes: readonly TNode[], childrenKey?: PropertyKey): TNode[];
+export declare function flattenTree<TNode extends object>(nodes: ReadonlyArray<TNode>, childrenKey?: PropertyKey): TNode[];
 /**
  * Finds the first node matching a predicate, depth-first, pre-order — the lookup behind "select the node
  * for this route" and "reveal the row with this id".
@@ -49,7 +49,7 @@ export declare function flattenTree<TNode extends object>(nodes: readonly TNode[
  * @param childrenKey The property holding a node's children; defaults to `'children'`.
  * @returns The matching node, or `undefined` when nothing matches.
  */
-export declare function findInTree<TNode extends object>(nodes: readonly TNode[], predicate: (node: TNode, depth: number) => boolean, childrenKey?: PropertyKey): TNode | undefined;
+export declare function findInTree<TNode extends object>(nodes: ReadonlyArray<TNode>, predicate: (node: TNode, depth: number) => boolean, childrenKey?: PropertyKey): TNode | undefined;
 /**
  * Rebuilds a {@link TreeNode} tree with every item transformed, keeping the shape and the order.
  *
@@ -59,5 +59,6 @@ export declare function findInTree<TNode extends object>(nodes: readonly TNode[]
  * @param nodes The roots to map; never mutated.
  * @param mapFn Produces the replacement item from the current item and its 0-based depth.
  * @returns A new tree of new nodes.
+ * @throws {TypeError} When the input contains a cycle; shared subtrees remain supported.
  */
-export declare function mapTree<T, TResult>(nodes: readonly TreeNode<T>[], mapFn: (item: T, depth: number) => TResult): TreeNode<TResult>[];
+export declare function mapTree<T, TResult>(nodes: ReadonlyArray<TreeNode<T>>, mapFn: (item: T, depth: number) => TResult): TreeNode<TResult>[];

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

@@ -1,5 +1,6 @@
 export { chunk, groupBy, insertAt, move, partition, range, removeAt, replaceAt, toggleItem, unique, unzip, zip, } from './Arrays';
 export { difference, intersection, symmetricDifference, union } from './SetOps';
-export { entriesToRecord, invertRecord, keyBy, mapValues, omitKeys, pickKeys, recordToEntries, } from './Records';
+export { entriesToRecord, invertRecord, keyBy, mapValues, omitKeys, pickKeys, recordToEntries } from './Records';
 export { arrayShallowEqual, deepEqual, shallowEqual } from './Comparison';
-export { buildTree, findInTree, flattenTree, mapTree, type BuildTreeOptions, type TreeNode, } from './Tree';
+export { buildTree, findInTree, flattenTree, mapTree, type BuildTreeOptions, type TreeNode } from './Tree';
+export { Equality, type EqualityComparer } from './Equality';