@ngockhoi96/ctc 0.1.0

package/dist/clipboard-Bs9DV14p.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard-Bs9DV14p.cjs","names":[],"sources":["../src/lib/env.ts","../src/lib/errors.ts","../src/clipboard/copy.ts","../src/clipboard/detect.ts","../src/clipboard/fallback.ts","../src/clipboard/read.ts"],"sourcesContent":["/**\n * Check if code is running in a browser environment.\n *\n * @returns `true` if `navigator` and `window` are defined\n */\nexport function isBrowser(): boolean {\n\treturn typeof navigator !== 'undefined' && typeof window !== 'undefined'\n}\n\n/**\n * Check if the current context is secure (HTTPS or localhost).\n *\n * Clipboard API requires a secure context in modern browsers.\n *\n * @returns `true` if running in a browser with a secure context\n */\nexport function isSecureContext(): boolean {\n\treturn isBrowser() && window.isSecureContext === true\n}\n","import type { BrowserUtilsError, ErrorCode, OnErrorCallback } from './types.ts'\n\n/**\n * Error codes that represent expected, recoverable failures.\n *\n * Expected errors are logged with `console.warn`.\n * Unexpected errors are logged with `console.error`.\n *\n * @internal\n */\nconst EXPECTED_ERROR_CODES = new Set<ErrorCode>([\n\t'CLIPBOARD_NOT_SUPPORTED',\n\t'INSECURE_CONTEXT',\n\t'CLIPBOARD_PERMISSION_DENIED',\n])\n\n/**\n * Create a structured browser utils error.\n *\n * @param code - Error code identifying the failure type\n * @param message - Human-readable error description\n * @param cause - Original error that caused this failure\n * @returns A structured BrowserUtilsError object\n */\nexport function createError(\n\tcode: ErrorCode,\n\tmessage: string,\n\tcause?: unknown,\n): BrowserUtilsError {\n\treturn { code, message, cause }\n}\n\n/**\n * Invoke the onError callback if provided, otherwise log a warning or error.\n *\n * Expected failures (CLIPBOARD_NOT_SUPPORTED, INSECURE_CONTEXT,\n * CLIPBOARD_PERMISSION_DENIED) are logged with `console.warn`.\n * Unexpected failures (CLIPBOARD_WRITE_FAILED, CLIPBOARD_READ_FAILED) are\n * logged with `console.error` and include the original cause for debugging.\n *\n * @param error - The structured error to handle\n * @param onError - Optional callback for error reporting\n */\nexport function handleError(\n\terror: BrowserUtilsError,\n\tonError?: OnErrorCallback,\n): void {\n\tif (onError) {\n\t\ttry {\n\t\t\tonError(error)\n\t\t} catch {\n\t\t\t// Consumer callback errors must not escape — the no-throw contract\n\t\t\t// applies to the full call stack originating from clipboard functions.\n\t\t}\n\t\treturn\n\t}\n\n\tconst prefix = '[ngockhoi96]'\n\n\tif (EXPECTED_ERROR_CODES.has(error.code)) {\n\t\tconsole.warn(`${prefix} ${error.code}: ${error.message}`)\n\t} else {\n\t\tconsole.error(`${prefix} ${error.code}: ${error.message}`, error.cause)\n\t}\n}\n","import { isBrowser, isSecureContext } from '../lib/env.ts'\nimport { createError, handleError } from '../lib/errors.ts'\nimport type { ClipboardOptions } from './types.ts'\n\n/**\n * Copy text to the clipboard using the modern Clipboard API.\n *\n * Requires a secure context (HTTPS or localhost) and must be called from\n * within a user gesture handler (click, keydown, etc.).\n *\n * @param text - The text to copy to the clipboard\n * @param options - Optional configuration including `onError` callback\n * @returns `true` on success, `false` on any failure (never throws)\n *\n * @remarks\n * **User gesture requirement:** Must be called synchronously within a user\n * gesture handler. Programmatic calls from timers or microtasks will be\n * rejected by the browser with `CLIPBOARD_PERMISSION_DENIED`.\n *\n * **Secure context:** Returns `false` on HTTP pages with `INSECURE_CONTEXT`\n * error code. Use `copyToClipboardLegacy()` for HTTP environments.\n *\n * **Safari:** Calling any async operation before `writeText()` in the same\n * microtask may break Safari's user activation window. Keep the call\n * synchronous within the click handler.\n *\n * @example\n * ```ts\n * button.addEventListener('click', async () => {\n *   const success = await copyToClipboard('Hello, world!')\n *   if (!success) {\n *     showError('Copy failed — check HTTPS and permissions')\n *   }\n * })\n * ```\n */\nexport async function copyToClipboard(\n\ttext: string,\n\toptions?: ClipboardOptions,\n): Promise<boolean> {\n\tif (!isBrowser()) {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'Not in a browser environment'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\tif (!isSecureContext()) {\n\t\thandleError(\n\t\t\tcreateError(\n\t\t\t\t'INSECURE_CONTEXT',\n\t\t\t\t'Clipboard API requires a secure context (HTTPS)',\n\t\t\t),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\tif (typeof navigator.clipboard?.writeText !== 'function') {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'Clipboard API not available'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\ttry {\n\t\tawait navigator.clipboard.writeText(text)\n\t\treturn true\n\t} catch (error) {\n\t\tconst isPermissionDenied =\n\t\t\terror instanceof DOMException && error.name === 'NotAllowedError'\n\n\t\tif (isPermissionDenied) {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_PERMISSION_DENIED',\n\t\t\t\t\t'Clipboard write permission denied',\n\t\t\t\t\terror,\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t} else {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_WRITE_FAILED',\n\t\t\t\t\t'Failed to write to clipboard',\n\t\t\t\t\terror,\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t}\n\t\treturn false\n\t}\n}\n","import { isBrowser, isSecureContext } from '../lib/env.ts'\n\n/**\n * Check if the Clipboard API is available and usable in the current context.\n *\n * Returns `true` only when `navigator.clipboard.writeText` exists AND the\n * page is running in a secure context (HTTPS or localhost). Returns `false`\n * in SSR environments, on HTTP pages, or when the Clipboard API is absent.\n *\n * @returns `true` if clipboard write operations are supported\n *\n * @remarks\n * Permission state is not checked — a `true` result does not guarantee the\n * user has granted clipboard access. Permission denial is surfaced at call\n * time via the `CLIPBOARD_PERMISSION_DENIED` error code on `copyToClipboard`.\n *\n * @example\n * ```ts\n * if (isClipboardSupported()) {\n *   await copyToClipboard(text)\n * } else {\n *   copyToClipboardLegacy(text)\n * }\n * ```\n */\nexport function isClipboardSupported(): boolean {\n\treturn (\n\t\tisBrowser() &&\n\t\tisSecureContext() &&\n\t\ttypeof navigator.clipboard?.writeText === 'function'\n\t)\n}\n\n/**\n * Check if clipboard read operations are available and usable in the current context.\n *\n * Returns `true` only when `navigator.clipboard.readText` exists AND the\n * page is running in a secure context (HTTPS or localhost). Returns `false`\n * in SSR environments, on HTTP pages, or when the read API is absent.\n *\n * @returns `true` if clipboard read operations are supported\n *\n * @remarks\n * Permission state is not checked — a `true` result does not guarantee the\n * user has granted clipboard read access. Permission denial is surfaced at\n * call time via the `CLIPBOARD_PERMISSION_DENIED` error code on `readFromClipboard`.\n *\n * Firefox does not support the Permissions API `clipboard-read` query. This\n * function uses synchronous feature detection only — no async permission\n * queries are performed.\n *\n * @example\n * ```ts\n * if (isClipboardReadSupported()) {\n *   const text = await readFromClipboard()\n * }\n * ```\n */\nexport function isClipboardReadSupported(): boolean {\n\treturn (\n\t\tisBrowser() &&\n\t\tisSecureContext() &&\n\t\ttypeof navigator.clipboard?.readText === 'function'\n\t)\n}\n","import { isBrowser } from '../lib/env.ts'\nimport { createError, handleError } from '../lib/errors.ts'\nimport type { ClipboardOptions } from './types.ts'\n\n/**\n * Copy text to the clipboard using the legacy `document.execCommand` API.\n *\n * Use this function when the modern Clipboard API is unavailable — for\n * example, on HTTP pages (non-HTTPS) or in browsers that do not support\n * `navigator.clipboard`. For HTTPS pages, prefer `copyToClipboard()`.\n *\n * @param text - The text to copy to the clipboard\n * @param options - Optional configuration including `onError` callback\n * @returns `true` on success, `false` on any failure (never throws)\n *\n * @remarks\n * This function uses the deprecated `document.execCommand('copy')` API,\n * which is synchronous and text-only. It temporarily creates and removes a\n * textarea element in the DOM to perform the copy operation.\n *\n * **No secure context requirement:** This function works on HTTP pages.\n * This is by design — it exists for environments where `copyToClipboard()`\n * is unavailable due to missing secure context.\n *\n * **iOS Safari:** `execCommand` copy is not reliably supported on iOS.\n * This function may return `false` on iOS Safari without a usable fallback.\n *\n * @example\n * ```ts\n * if (isClipboardSupported()) {\n *   await copyToClipboard(text)\n * } else {\n *   const success = copyToClipboardLegacy(text)\n *   if (!success) {\n *     showManualCopyInstructions()\n *   }\n * }\n * ```\n */\nexport function copyToClipboardLegacy(\n\ttext: string,\n\toptions?: ClipboardOptions,\n): boolean {\n\tif (!isBrowser()) {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'Not in a browser environment'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\tif (!document.body) {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'document.body is not available'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\tconst textarea = document.createElement('textarea')\n\n\t// Position off-screen but visible to the browser — required for text selection on iOS.\n\t// display:none or visibility:hidden prevents the browser from selecting the content.\n\ttextarea.style.position = 'fixed'\n\ttextarea.style.top = '0'\n\ttextarea.style.left = '0'\n\ttextarea.style.opacity = '0'\n\ttextarea.style.pointerEvents = 'none'\n\t// Prevent iOS Safari from auto-zooming when the textarea is focused\n\ttextarea.style.fontSize = '16px'\n\t// Prevent the mobile keyboard from appearing during the copy operation\n\ttextarea.readOnly = true\n\ttextarea.value = text\n\n\tdocument.body.appendChild(textarea)\n\n\ttry {\n\t\ttextarea.focus()\n\t\t// setSelectionRange is more reliable than .select() on mobile browsers (Pitfall 3)\n\t\ttextarea.setSelectionRange(0, text.length)\n\n\t\tconst success = document.execCommand('copy')\n\n\t\tif (!success) {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_WRITE_FAILED',\n\t\t\t\t\t'execCommand copy returned false',\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t\treturn false\n\t\t}\n\n\t\treturn true\n\t} catch (error) {\n\t\thandleError(\n\t\t\tcreateError(\n\t\t\t\t'CLIPBOARD_WRITE_FAILED',\n\t\t\t\t'execCommand copy threw an error',\n\t\t\t\terror,\n\t\t\t),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t} finally {\n\t\t// Guard with isConnected before removing — prevents NotFoundError if a\n\t\t// framework (e.g., React 18 Strict Mode) or MutationObserver removed the\n\t\t// node between appendChild and here. textarea.remove() does not throw on\n\t\t// already-detached nodes. (Pitfall 4)\n\t\tif (textarea.isConnected) {\n\t\t\ttextarea.remove()\n\t\t}\n\t}\n}\n","import { isBrowser, isSecureContext } from '../lib/env.ts'\nimport { createError, handleError } from '../lib/errors.ts'\nimport type { ClipboardOptions } from './types.ts'\n\n/**\n * Read text from the clipboard using the modern Clipboard API.\n *\n * Requires a secure context (HTTPS or localhost). The browser may prompt\n * the user for permission on the first call.\n *\n * @param options - Optional configuration including `onError` callback\n * @returns The clipboard text on success, `null` on any failure (never throws)\n *\n * @remarks\n * **Permission prompt:** Chrome prompts for `clipboard-read` permission on\n * the first call. Firefox and Safari show a system-level paste prompt.\n * Permission denial is reported via `CLIPBOARD_PERMISSION_DENIED`.\n *\n * **Non-text content:** If the clipboard contains only non-text content\n * (e.g., an image), the browser throws `NotFoundError` which is reported\n * as `CLIPBOARD_READ_FAILED`.\n *\n * @example\n * ```ts\n * button.addEventListener('click', async () => {\n *   const text = await readFromClipboard()\n *   if (text !== null) {\n *     input.value = text\n *   }\n * })\n * ```\n */\nexport async function readFromClipboard(\n\toptions?: ClipboardOptions,\n): Promise<string | null> {\n\tif (!isBrowser()) {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'Not in a browser environment'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn null\n\t}\n\n\tif (!isSecureContext()) {\n\t\thandleError(\n\t\t\tcreateError(\n\t\t\t\t'INSECURE_CONTEXT',\n\t\t\t\t'Clipboard API requires a secure context (HTTPS)',\n\t\t\t),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn null\n\t}\n\n\tif (typeof navigator.clipboard?.readText !== 'function') {\n\t\thandleError(\n\t\t\tcreateError(\n\t\t\t\t'CLIPBOARD_NOT_SUPPORTED',\n\t\t\t\t'Clipboard read API not available',\n\t\t\t),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn null\n\t}\n\n\ttry {\n\t\treturn await navigator.clipboard.readText()\n\t} catch (error) {\n\t\tconst isPermissionDenied =\n\t\t\terror instanceof DOMException && error.name === 'NotAllowedError'\n\n\t\tif (isPermissionDenied) {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_PERMISSION_DENIED',\n\t\t\t\t\t'Clipboard read permission denied',\n\t\t\t\t\terror,\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t} else {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_READ_FAILED',\n\t\t\t\t\t'Failed to read from clipboard',\n\t\t\t\t\terror,\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t}\n\t\treturn null\n\t}\n}\n"],"mappings":"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"}

package/dist/clipboard-OTP55cvN.mjs

@@ -0,0 +1,309 @@
+//#region src/lib/env.ts
+/**
+* Check if code is running in a browser environment.
+*
+* @returns `true` if `navigator` and `window` are defined
+*/
+function isBrowser() {
+	return typeof navigator !== "undefined" && typeof window !== "undefined";
+}
+/**
+* Check if the current context is secure (HTTPS or localhost).
+*
+* Clipboard API requires a secure context in modern browsers.
+*
+* @returns `true` if running in a browser with a secure context
+*/
+function isSecureContext() {
+	return isBrowser() && window.isSecureContext === true;
+}
+//#endregion
+//#region src/lib/errors.ts
+/**
+* Error codes that represent expected, recoverable failures.
+*
+* Expected errors are logged with `console.warn`.
+* Unexpected errors are logged with `console.error`.
+*
+* @internal
+*/
+const EXPECTED_ERROR_CODES = new Set([
+	"CLIPBOARD_NOT_SUPPORTED",
+	"INSECURE_CONTEXT",
+	"CLIPBOARD_PERMISSION_DENIED"
+]);
+/**
+* Create a structured browser utils error.
+*
+* @param code - Error code identifying the failure type
+* @param message - Human-readable error description
+* @param cause - Original error that caused this failure
+* @returns A structured BrowserUtilsError object
+*/
+function createError(code, message, cause) {
+	return {
+		code,
+		message,
+		cause
+	};
+}
+/**
+* Invoke the onError callback if provided, otherwise log a warning or error.
+*
+* Expected failures (CLIPBOARD_NOT_SUPPORTED, INSECURE_CONTEXT,
+* CLIPBOARD_PERMISSION_DENIED) are logged with `console.warn`.
+* Unexpected failures (CLIPBOARD_WRITE_FAILED, CLIPBOARD_READ_FAILED) are
+* logged with `console.error` and include the original cause for debugging.
+*
+* @param error - The structured error to handle
+* @param onError - Optional callback for error reporting
+*/
+function handleError(error, onError) {
+	if (onError) {
+		try {
+			onError(error);
+		} catch {}
+		return;
+	}
+	const prefix = "[ngockhoi96]";
+	if (EXPECTED_ERROR_CODES.has(error.code)) console.warn(`${prefix} ${error.code}: ${error.message}`);
+	else console.error(`${prefix} ${error.code}: ${error.message}`, error.cause);
+}
+//#endregion
+//#region src/clipboard/copy.ts
+/**
+* Copy text to the clipboard using the modern Clipboard API.
+*
+* Requires a secure context (HTTPS or localhost) and must be called from
+* within a user gesture handler (click, keydown, etc.).
+*
+* @param text - The text to copy to the clipboard
+* @param options - Optional configuration including `onError` callback
+* @returns `true` on success, `false` on any failure (never throws)
+*
+* @remarks
+* **User gesture requirement:** Must be called synchronously within a user
+* gesture handler. Programmatic calls from timers or microtasks will be
+* rejected by the browser with `CLIPBOARD_PERMISSION_DENIED`.
+*
+* **Secure context:** Returns `false` on HTTP pages with `INSECURE_CONTEXT`
+* error code. Use `copyToClipboardLegacy()` for HTTP environments.
+*
+* **Safari:** Calling any async operation before `writeText()` in the same
+* microtask may break Safari's user activation window. Keep the call
+* synchronous within the click handler.
+*
+* @example
+* ```ts
+* button.addEventListener('click', async () => {
+*   const success = await copyToClipboard('Hello, world!')
+*   if (!success) {
+*     showError('Copy failed — check HTTPS and permissions')
+*   }
+* })
+* ```
+*/
+async function copyToClipboard(text, options) {
+	if (!isBrowser()) {
+		handleError(createError("CLIPBOARD_NOT_SUPPORTED", "Not in a browser environment"), options?.onError);
+		return false;
+	}
+	if (!isSecureContext()) {
+		handleError(createError("INSECURE_CONTEXT", "Clipboard API requires a secure context (HTTPS)"), options?.onError);
+		return false;
+	}
+	if (typeof navigator.clipboard?.writeText !== "function") {
+		handleError(createError("CLIPBOARD_NOT_SUPPORTED", "Clipboard API not available"), options?.onError);
+		return false;
+	}
+	try {
+		await navigator.clipboard.writeText(text);
+		return true;
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "NotAllowedError") handleError(createError("CLIPBOARD_PERMISSION_DENIED", "Clipboard write permission denied", error), options?.onError);
+		else handleError(createError("CLIPBOARD_WRITE_FAILED", "Failed to write to clipboard", error), options?.onError);
+		return false;
+	}
+}
+//#endregion
+//#region src/clipboard/detect.ts
+/**
+* Check if the Clipboard API is available and usable in the current context.
+*
+* Returns `true` only when `navigator.clipboard.writeText` exists AND the
+* page is running in a secure context (HTTPS or localhost). Returns `false`
+* in SSR environments, on HTTP pages, or when the Clipboard API is absent.
+*
+* @returns `true` if clipboard write operations are supported
+*
+* @remarks
+* Permission state is not checked — a `true` result does not guarantee the
+* user has granted clipboard access. Permission denial is surfaced at call
+* time via the `CLIPBOARD_PERMISSION_DENIED` error code on `copyToClipboard`.
+*
+* @example
+* ```ts
+* if (isClipboardSupported()) {
+*   await copyToClipboard(text)
+* } else {
+*   copyToClipboardLegacy(text)
+* }
+* ```
+*/
+function isClipboardSupported() {
+	return isBrowser() && isSecureContext() && typeof navigator.clipboard?.writeText === "function";
+}
+/**
+* Check if clipboard read operations are available and usable in the current context.
+*
+* Returns `true` only when `navigator.clipboard.readText` exists AND the
+* page is running in a secure context (HTTPS or localhost). Returns `false`
+* in SSR environments, on HTTP pages, or when the read API is absent.
+*
+* @returns `true` if clipboard read operations are supported
+*
+* @remarks
+* Permission state is not checked — a `true` result does not guarantee the
+* user has granted clipboard read access. Permission denial is surfaced at
+* call time via the `CLIPBOARD_PERMISSION_DENIED` error code on `readFromClipboard`.
+*
+* Firefox does not support the Permissions API `clipboard-read` query. This
+* function uses synchronous feature detection only — no async permission
+* queries are performed.
+*
+* @example
+* ```ts
+* if (isClipboardReadSupported()) {
+*   const text = await readFromClipboard()
+* }
+* ```
+*/
+function isClipboardReadSupported() {
+	return isBrowser() && isSecureContext() && typeof navigator.clipboard?.readText === "function";
+}
+//#endregion
+//#region src/clipboard/fallback.ts
+/**
+* Copy text to the clipboard using the legacy `document.execCommand` API.
+*
+* Use this function when the modern Clipboard API is unavailable — for
+* example, on HTTP pages (non-HTTPS) or in browsers that do not support
+* `navigator.clipboard`. For HTTPS pages, prefer `copyToClipboard()`.
+*
+* @param text - The text to copy to the clipboard
+* @param options - Optional configuration including `onError` callback
+* @returns `true` on success, `false` on any failure (never throws)
+*
+* @remarks
+* This function uses the deprecated `document.execCommand('copy')` API,
+* which is synchronous and text-only. It temporarily creates and removes a
+* textarea element in the DOM to perform the copy operation.
+*
+* **No secure context requirement:** This function works on HTTP pages.
+* This is by design — it exists for environments where `copyToClipboard()`
+* is unavailable due to missing secure context.
+*
+* **iOS Safari:** `execCommand` copy is not reliably supported on iOS.
+* This function may return `false` on iOS Safari without a usable fallback.
+*
+* @example
+* ```ts
+* if (isClipboardSupported()) {
+*   await copyToClipboard(text)
+* } else {
+*   const success = copyToClipboardLegacy(text)
+*   if (!success) {
+*     showManualCopyInstructions()
+*   }
+* }
+* ```
+*/
+function copyToClipboardLegacy(text, options) {
+	if (!isBrowser()) {
+		handleError(createError("CLIPBOARD_NOT_SUPPORTED", "Not in a browser environment"), options?.onError);
+		return false;
+	}
+	if (!document.body) {
+		handleError(createError("CLIPBOARD_NOT_SUPPORTED", "document.body is not available"), options?.onError);
+		return false;
+	}
+	const textarea = document.createElement("textarea");
+	textarea.style.position = "fixed";
+	textarea.style.top = "0";
+	textarea.style.left = "0";
+	textarea.style.opacity = "0";
+	textarea.style.pointerEvents = "none";
+	textarea.style.fontSize = "16px";
+	textarea.readOnly = true;
+	textarea.value = text;
+	document.body.appendChild(textarea);
+	try {
+		textarea.focus();
+		textarea.setSelectionRange(0, text.length);
+		if (!document.execCommand("copy")) {
+			handleError(createError("CLIPBOARD_WRITE_FAILED", "execCommand copy returned false"), options?.onError);
+			return false;
+		}
+		return true;
+	} catch (error) {
+		handleError(createError("CLIPBOARD_WRITE_FAILED", "execCommand copy threw an error", error), options?.onError);
+		return false;
+	} finally {
+		if (textarea.isConnected) textarea.remove();
+	}
+}
+//#endregion
+//#region src/clipboard/read.ts
+/**
+* Read text from the clipboard using the modern Clipboard API.
+*
+* Requires a secure context (HTTPS or localhost). The browser may prompt
+* the user for permission on the first call.
+*
+* @param options - Optional configuration including `onError` callback
+* @returns The clipboard text on success, `null` on any failure (never throws)
+*
+* @remarks
+* **Permission prompt:** Chrome prompts for `clipboard-read` permission on
+* the first call. Firefox and Safari show a system-level paste prompt.
+* Permission denial is reported via `CLIPBOARD_PERMISSION_DENIED`.
+*
+* **Non-text content:** If the clipboard contains only non-text content
+* (e.g., an image), the browser throws `NotFoundError` which is reported
+* as `CLIPBOARD_READ_FAILED`.
+*
+* @example
+* ```ts
+* button.addEventListener('click', async () => {
+*   const text = await readFromClipboard()
+*   if (text !== null) {
+*     input.value = text
+*   }
+* })
+* ```
+*/
+async function readFromClipboard(options) {
+	if (!isBrowser()) {
+		handleError(createError("CLIPBOARD_NOT_SUPPORTED", "Not in a browser environment"), options?.onError);
+		return null;
+	}
+	if (!isSecureContext()) {
+		handleError(createError("INSECURE_CONTEXT", "Clipboard API requires a secure context (HTTPS)"), options?.onError);
+		return null;
+	}
+	if (typeof navigator.clipboard?.readText !== "function") {
+		handleError(createError("CLIPBOARD_NOT_SUPPORTED", "Clipboard read API not available"), options?.onError);
+		return null;
+	}
+	try {
+		return await navigator.clipboard.readText();
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "NotAllowedError") handleError(createError("CLIPBOARD_PERMISSION_DENIED", "Clipboard read permission denied", error), options?.onError);
+		else handleError(createError("CLIPBOARD_READ_FAILED", "Failed to read from clipboard", error), options?.onError);
+		return null;
+	}
+}
+//#endregion
+export { copyToClipboard as a, isClipboardSupported as i, copyToClipboardLegacy as n, isClipboardReadSupported as r, readFromClipboard as t };
+
+//# sourceMappingURL=clipboard-OTP55cvN.mjs.map

package/dist/clipboard-OTP55cvN.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard-OTP55cvN.mjs","names":[],"sources":["../src/lib/env.ts","../src/lib/errors.ts","../src/clipboard/copy.ts","../src/clipboard/detect.ts","../src/clipboard/fallback.ts","../src/clipboard/read.ts"],"sourcesContent":["/**\n * Check if code is running in a browser environment.\n *\n * @returns `true` if `navigator` and `window` are defined\n */\nexport function isBrowser(): boolean {\n\treturn typeof navigator !== 'undefined' && typeof window !== 'undefined'\n}\n\n/**\n * Check if the current context is secure (HTTPS or localhost).\n *\n * Clipboard API requires a secure context in modern browsers.\n *\n * @returns `true` if running in a browser with a secure context\n */\nexport function isSecureContext(): boolean {\n\treturn isBrowser() && window.isSecureContext === true\n}\n","import type { BrowserUtilsError, ErrorCode, OnErrorCallback } from './types.ts'\n\n/**\n * Error codes that represent expected, recoverable failures.\n *\n * Expected errors are logged with `console.warn`.\n * Unexpected errors are logged with `console.error`.\n *\n * @internal\n */\nconst EXPECTED_ERROR_CODES = new Set<ErrorCode>([\n\t'CLIPBOARD_NOT_SUPPORTED',\n\t'INSECURE_CONTEXT',\n\t'CLIPBOARD_PERMISSION_DENIED',\n])\n\n/**\n * Create a structured browser utils error.\n *\n * @param code - Error code identifying the failure type\n * @param message - Human-readable error description\n * @param cause - Original error that caused this failure\n * @returns A structured BrowserUtilsError object\n */\nexport function createError(\n\tcode: ErrorCode,\n\tmessage: string,\n\tcause?: unknown,\n): BrowserUtilsError {\n\treturn { code, message, cause }\n}\n\n/**\n * Invoke the onError callback if provided, otherwise log a warning or error.\n *\n * Expected failures (CLIPBOARD_NOT_SUPPORTED, INSECURE_CONTEXT,\n * CLIPBOARD_PERMISSION_DENIED) are logged with `console.warn`.\n * Unexpected failures (CLIPBOARD_WRITE_FAILED, CLIPBOARD_READ_FAILED) are\n * logged with `console.error` and include the original cause for debugging.\n *\n * @param error - The structured error to handle\n * @param onError - Optional callback for error reporting\n */\nexport function handleError(\n\terror: BrowserUtilsError,\n\tonError?: OnErrorCallback,\n): void {\n\tif (onError) {\n\t\ttry {\n\t\t\tonError(error)\n\t\t} catch {\n\t\t\t// Consumer callback errors must not escape — the no-throw contract\n\t\t\t// applies to the full call stack originating from clipboard functions.\n\t\t}\n\t\treturn\n\t}\n\n\tconst prefix = '[ngockhoi96]'\n\n\tif (EXPECTED_ERROR_CODES.has(error.code)) {\n\t\tconsole.warn(`${prefix} ${error.code}: ${error.message}`)\n\t} else {\n\t\tconsole.error(`${prefix} ${error.code}: ${error.message}`, error.cause)\n\t}\n}\n","import { isBrowser, isSecureContext } from '../lib/env.ts'\nimport { createError, handleError } from '../lib/errors.ts'\nimport type { ClipboardOptions } from './types.ts'\n\n/**\n * Copy text to the clipboard using the modern Clipboard API.\n *\n * Requires a secure context (HTTPS or localhost) and must be called from\n * within a user gesture handler (click, keydown, etc.).\n *\n * @param text - The text to copy to the clipboard\n * @param options - Optional configuration including `onError` callback\n * @returns `true` on success, `false` on any failure (never throws)\n *\n * @remarks\n * **User gesture requirement:** Must be called synchronously within a user\n * gesture handler. Programmatic calls from timers or microtasks will be\n * rejected by the browser with `CLIPBOARD_PERMISSION_DENIED`.\n *\n * **Secure context:** Returns `false` on HTTP pages with `INSECURE_CONTEXT`\n * error code. Use `copyToClipboardLegacy()` for HTTP environments.\n *\n * **Safari:** Calling any async operation before `writeText()` in the same\n * microtask may break Safari's user activation window. Keep the call\n * synchronous within the click handler.\n *\n * @example\n * ```ts\n * button.addEventListener('click', async () => {\n *   const success = await copyToClipboard('Hello, world!')\n *   if (!success) {\n *     showError('Copy failed — check HTTPS and permissions')\n *   }\n * })\n * ```\n */\nexport async function copyToClipboard(\n\ttext: string,\n\toptions?: ClipboardOptions,\n): Promise<boolean> {\n\tif (!isBrowser()) {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'Not in a browser environment'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\tif (!isSecureContext()) {\n\t\thandleError(\n\t\t\tcreateError(\n\t\t\t\t'INSECURE_CONTEXT',\n\t\t\t\t'Clipboard API requires a secure context (HTTPS)',\n\t\t\t),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\tif (typeof navigator.clipboard?.writeText !== 'function') {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'Clipboard API not available'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\ttry {\n\t\tawait navigator.clipboard.writeText(text)\n\t\treturn true\n\t} catch (error) {\n\t\tconst isPermissionDenied =\n\t\t\terror instanceof DOMException && error.name === 'NotAllowedError'\n\n\t\tif (isPermissionDenied) {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_PERMISSION_DENIED',\n\t\t\t\t\t'Clipboard write permission denied',\n\t\t\t\t\terror,\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t} else {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_WRITE_FAILED',\n\t\t\t\t\t'Failed to write to clipboard',\n\t\t\t\t\terror,\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t}\n\t\treturn false\n\t}\n}\n","import { isBrowser, isSecureContext } from '../lib/env.ts'\n\n/**\n * Check if the Clipboard API is available and usable in the current context.\n *\n * Returns `true` only when `navigator.clipboard.writeText` exists AND the\n * page is running in a secure context (HTTPS or localhost). Returns `false`\n * in SSR environments, on HTTP pages, or when the Clipboard API is absent.\n *\n * @returns `true` if clipboard write operations are supported\n *\n * @remarks\n * Permission state is not checked — a `true` result does not guarantee the\n * user has granted clipboard access. Permission denial is surfaced at call\n * time via the `CLIPBOARD_PERMISSION_DENIED` error code on `copyToClipboard`.\n *\n * @example\n * ```ts\n * if (isClipboardSupported()) {\n *   await copyToClipboard(text)\n * } else {\n *   copyToClipboardLegacy(text)\n * }\n * ```\n */\nexport function isClipboardSupported(): boolean {\n\treturn (\n\t\tisBrowser() &&\n\t\tisSecureContext() &&\n\t\ttypeof navigator.clipboard?.writeText === 'function'\n\t)\n}\n\n/**\n * Check if clipboard read operations are available and usable in the current context.\n *\n * Returns `true` only when `navigator.clipboard.readText` exists AND the\n * page is running in a secure context (HTTPS or localhost). Returns `false`\n * in SSR environments, on HTTP pages, or when the read API is absent.\n *\n * @returns `true` if clipboard read operations are supported\n *\n * @remarks\n * Permission state is not checked — a `true` result does not guarantee the\n * user has granted clipboard read access. Permission denial is surfaced at\n * call time via the `CLIPBOARD_PERMISSION_DENIED` error code on `readFromClipboard`.\n *\n * Firefox does not support the Permissions API `clipboard-read` query. This\n * function uses synchronous feature detection only — no async permission\n * queries are performed.\n *\n * @example\n * ```ts\n * if (isClipboardReadSupported()) {\n *   const text = await readFromClipboard()\n * }\n * ```\n */\nexport function isClipboardReadSupported(): boolean {\n\treturn (\n\t\tisBrowser() &&\n\t\tisSecureContext() &&\n\t\ttypeof navigator.clipboard?.readText === 'function'\n\t)\n}\n","import { isBrowser } from '../lib/env.ts'\nimport { createError, handleError } from '../lib/errors.ts'\nimport type { ClipboardOptions } from './types.ts'\n\n/**\n * Copy text to the clipboard using the legacy `document.execCommand` API.\n *\n * Use this function when the modern Clipboard API is unavailable — for\n * example, on HTTP pages (non-HTTPS) or in browsers that do not support\n * `navigator.clipboard`. For HTTPS pages, prefer `copyToClipboard()`.\n *\n * @param text - The text to copy to the clipboard\n * @param options - Optional configuration including `onError` callback\n * @returns `true` on success, `false` on any failure (never throws)\n *\n * @remarks\n * This function uses the deprecated `document.execCommand('copy')` API,\n * which is synchronous and text-only. It temporarily creates and removes a\n * textarea element in the DOM to perform the copy operation.\n *\n * **No secure context requirement:** This function works on HTTP pages.\n * This is by design — it exists for environments where `copyToClipboard()`\n * is unavailable due to missing secure context.\n *\n * **iOS Safari:** `execCommand` copy is not reliably supported on iOS.\n * This function may return `false` on iOS Safari without a usable fallback.\n *\n * @example\n * ```ts\n * if (isClipboardSupported()) {\n *   await copyToClipboard(text)\n * } else {\n *   const success = copyToClipboardLegacy(text)\n *   if (!success) {\n *     showManualCopyInstructions()\n *   }\n * }\n * ```\n */\nexport function copyToClipboardLegacy(\n\ttext: string,\n\toptions?: ClipboardOptions,\n): boolean {\n\tif (!isBrowser()) {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'Not in a browser environment'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\tif (!document.body) {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'document.body is not available'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t}\n\n\tconst textarea = document.createElement('textarea')\n\n\t// Position off-screen but visible to the browser — required for text selection on iOS.\n\t// display:none or visibility:hidden prevents the browser from selecting the content.\n\ttextarea.style.position = 'fixed'\n\ttextarea.style.top = '0'\n\ttextarea.style.left = '0'\n\ttextarea.style.opacity = '0'\n\ttextarea.style.pointerEvents = 'none'\n\t// Prevent iOS Safari from auto-zooming when the textarea is focused\n\ttextarea.style.fontSize = '16px'\n\t// Prevent the mobile keyboard from appearing during the copy operation\n\ttextarea.readOnly = true\n\ttextarea.value = text\n\n\tdocument.body.appendChild(textarea)\n\n\ttry {\n\t\ttextarea.focus()\n\t\t// setSelectionRange is more reliable than .select() on mobile browsers (Pitfall 3)\n\t\ttextarea.setSelectionRange(0, text.length)\n\n\t\tconst success = document.execCommand('copy')\n\n\t\tif (!success) {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_WRITE_FAILED',\n\t\t\t\t\t'execCommand copy returned false',\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t\treturn false\n\t\t}\n\n\t\treturn true\n\t} catch (error) {\n\t\thandleError(\n\t\t\tcreateError(\n\t\t\t\t'CLIPBOARD_WRITE_FAILED',\n\t\t\t\t'execCommand copy threw an error',\n\t\t\t\terror,\n\t\t\t),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn false\n\t} finally {\n\t\t// Guard with isConnected before removing — prevents NotFoundError if a\n\t\t// framework (e.g., React 18 Strict Mode) or MutationObserver removed the\n\t\t// node between appendChild and here. textarea.remove() does not throw on\n\t\t// already-detached nodes. (Pitfall 4)\n\t\tif (textarea.isConnected) {\n\t\t\ttextarea.remove()\n\t\t}\n\t}\n}\n","import { isBrowser, isSecureContext } from '../lib/env.ts'\nimport { createError, handleError } from '../lib/errors.ts'\nimport type { ClipboardOptions } from './types.ts'\n\n/**\n * Read text from the clipboard using the modern Clipboard API.\n *\n * Requires a secure context (HTTPS or localhost). The browser may prompt\n * the user for permission on the first call.\n *\n * @param options - Optional configuration including `onError` callback\n * @returns The clipboard text on success, `null` on any failure (never throws)\n *\n * @remarks\n * **Permission prompt:** Chrome prompts for `clipboard-read` permission on\n * the first call. Firefox and Safari show a system-level paste prompt.\n * Permission denial is reported via `CLIPBOARD_PERMISSION_DENIED`.\n *\n * **Non-text content:** If the clipboard contains only non-text content\n * (e.g., an image), the browser throws `NotFoundError` which is reported\n * as `CLIPBOARD_READ_FAILED`.\n *\n * @example\n * ```ts\n * button.addEventListener('click', async () => {\n *   const text = await readFromClipboard()\n *   if (text !== null) {\n *     input.value = text\n *   }\n * })\n * ```\n */\nexport async function readFromClipboard(\n\toptions?: ClipboardOptions,\n): Promise<string | null> {\n\tif (!isBrowser()) {\n\t\thandleError(\n\t\t\tcreateError('CLIPBOARD_NOT_SUPPORTED', 'Not in a browser environment'),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn null\n\t}\n\n\tif (!isSecureContext()) {\n\t\thandleError(\n\t\t\tcreateError(\n\t\t\t\t'INSECURE_CONTEXT',\n\t\t\t\t'Clipboard API requires a secure context (HTTPS)',\n\t\t\t),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn null\n\t}\n\n\tif (typeof navigator.clipboard?.readText !== 'function') {\n\t\thandleError(\n\t\t\tcreateError(\n\t\t\t\t'CLIPBOARD_NOT_SUPPORTED',\n\t\t\t\t'Clipboard read API not available',\n\t\t\t),\n\t\t\toptions?.onError,\n\t\t)\n\t\treturn null\n\t}\n\n\ttry {\n\t\treturn await navigator.clipboard.readText()\n\t} catch (error) {\n\t\tconst isPermissionDenied =\n\t\t\terror instanceof DOMException && error.name === 'NotAllowedError'\n\n\t\tif (isPermissionDenied) {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_PERMISSION_DENIED',\n\t\t\t\t\t'Clipboard read permission denied',\n\t\t\t\t\terror,\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t} else {\n\t\t\thandleError(\n\t\t\t\tcreateError(\n\t\t\t\t\t'CLIPBOARD_READ_FAILED',\n\t\t\t\t\t'Failed to read from clipboard',\n\t\t\t\t\terror,\n\t\t\t\t),\n\t\t\t\toptions?.onError,\n\t\t\t)\n\t\t}\n\t\treturn null\n\t}\n}\n"],"mappings":"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"}

package/dist/index-B7FFRy7e.d.mts

@@ -0,0 +1,193 @@
+//#region src/lib/types.d.ts
+/**
+* Error codes for browser utility operations.
+*/
+type ErrorCode = "CLIPBOARD_NOT_SUPPORTED" | "CLIPBOARD_PERMISSION_DENIED" | "CLIPBOARD_WRITE_FAILED" | "CLIPBOARD_READ_FAILED" | "INSECURE_CONTEXT";
+/**
+* Structured error for browser utility operations.
+*
+* All clipboard functions accept an optional `onError` callback
+* that receives this type with a specific error code.
+*/
+interface BrowserUtilsError {
+  code: ErrorCode;
+  message: string;
+  cause?: unknown;
+}
+/**
+* Callback invoked when a browser utility operation fails.
+*
+* @param error - Structured error with code and message
+*/
+type OnErrorCallback = (error: BrowserUtilsError) => void;
+//#endregion
+//#region src/clipboard/types.d.ts
+/**
+* Options for clipboard operations.
+*/
+interface ClipboardOptions {
+  /**
+  * Callback invoked when the clipboard operation fails.
+  * Receives a structured error with a specific error code.
+  */
+  onError?: OnErrorCallback | undefined;
+}
+//#endregion
+//#region src/clipboard/copy.d.ts
+/**
+* Copy text to the clipboard using the modern Clipboard API.
+*
+* Requires a secure context (HTTPS or localhost) and must be called from
+* within a user gesture handler (click, keydown, etc.).
+*
+* @param text - The text to copy to the clipboard
+* @param options - Optional configuration including `onError` callback
+* @returns `true` on success, `false` on any failure (never throws)
+*
+* @remarks
+* **User gesture requirement:** Must be called synchronously within a user
+* gesture handler. Programmatic calls from timers or microtasks will be
+* rejected by the browser with `CLIPBOARD_PERMISSION_DENIED`.
+*
+* **Secure context:** Returns `false` on HTTP pages with `INSECURE_CONTEXT`
+* error code. Use `copyToClipboardLegacy()` for HTTP environments.
+*
+* **Safari:** Calling any async operation before `writeText()` in the same
+* microtask may break Safari's user activation window. Keep the call
+* synchronous within the click handler.
+*
+* @example
+* ```ts
+* button.addEventListener('click', async () => {
+*   const success = await copyToClipboard('Hello, world!')
+*   if (!success) {
+*     showError('Copy failed — check HTTPS and permissions')
+*   }
+* })
+* ```
+*/
+declare function copyToClipboard(text: string, options?: ClipboardOptions): Promise<boolean>;
+//#endregion
+//#region src/clipboard/detect.d.ts
+/**
+* Check if the Clipboard API is available and usable in the current context.
+*
+* Returns `true` only when `navigator.clipboard.writeText` exists AND the
+* page is running in a secure context (HTTPS or localhost). Returns `false`
+* in SSR environments, on HTTP pages, or when the Clipboard API is absent.
+*
+* @returns `true` if clipboard write operations are supported
+*
+* @remarks
+* Permission state is not checked — a `true` result does not guarantee the
+* user has granted clipboard access. Permission denial is surfaced at call
+* time via the `CLIPBOARD_PERMISSION_DENIED` error code on `copyToClipboard`.
+*
+* @example
+* ```ts
+* if (isClipboardSupported()) {
+*   await copyToClipboard(text)
+* } else {
+*   copyToClipboardLegacy(text)
+* }
+* ```
+*/
+declare function isClipboardSupported(): boolean;
+/**
+* Check if clipboard read operations are available and usable in the current context.
+*
+* Returns `true` only when `navigator.clipboard.readText` exists AND the
+* page is running in a secure context (HTTPS or localhost). Returns `false`
+* in SSR environments, on HTTP pages, or when the read API is absent.
+*
+* @returns `true` if clipboard read operations are supported
+*
+* @remarks
+* Permission state is not checked — a `true` result does not guarantee the
+* user has granted clipboard read access. Permission denial is surfaced at
+* call time via the `CLIPBOARD_PERMISSION_DENIED` error code on `readFromClipboard`.
+*
+* Firefox does not support the Permissions API `clipboard-read` query. This
+* function uses synchronous feature detection only — no async permission
+* queries are performed.
+*
+* @example
+* ```ts
+* if (isClipboardReadSupported()) {
+*   const text = await readFromClipboard()
+* }
+* ```
+*/
+declare function isClipboardReadSupported(): boolean;
+//#endregion
+//#region src/clipboard/fallback.d.ts
+/**
+* Copy text to the clipboard using the legacy `document.execCommand` API.
+*
+* Use this function when the modern Clipboard API is unavailable — for
+* example, on HTTP pages (non-HTTPS) or in browsers that do not support
+* `navigator.clipboard`. For HTTPS pages, prefer `copyToClipboard()`.
+*
+* @param text - The text to copy to the clipboard
+* @param options - Optional configuration including `onError` callback
+* @returns `true` on success, `false` on any failure (never throws)
+*
+* @remarks
+* This function uses the deprecated `document.execCommand('copy')` API,
+* which is synchronous and text-only. It temporarily creates and removes a
+* textarea element in the DOM to perform the copy operation.
+*
+* **No secure context requirement:** This function works on HTTP pages.
+* This is by design — it exists for environments where `copyToClipboard()`
+* is unavailable due to missing secure context.
+*
+* **iOS Safari:** `execCommand` copy is not reliably supported on iOS.
+* This function may return `false` on iOS Safari without a usable fallback.
+*
+* @example
+* ```ts
+* if (isClipboardSupported()) {
+*   await copyToClipboard(text)
+* } else {
+*   const success = copyToClipboardLegacy(text)
+*   if (!success) {
+*     showManualCopyInstructions()
+*   }
+* }
+* ```
+*/
+declare function copyToClipboardLegacy(text: string, options?: ClipboardOptions): boolean;
+//#endregion
+//#region src/clipboard/read.d.ts
+/**
+* Read text from the clipboard using the modern Clipboard API.
+*
+* Requires a secure context (HTTPS or localhost). The browser may prompt
+* the user for permission on the first call.
+*
+* @param options - Optional configuration including `onError` callback
+* @returns The clipboard text on success, `null` on any failure (never throws)
+*
+* @remarks
+* **Permission prompt:** Chrome prompts for `clipboard-read` permission on
+* the first call. Firefox and Safari show a system-level paste prompt.
+* Permission denial is reported via `CLIPBOARD_PERMISSION_DENIED`.
+*
+* **Non-text content:** If the clipboard contains only non-text content
+* (e.g., an image), the browser throws `NotFoundError` which is reported
+* as `CLIPBOARD_READ_FAILED`.
+*
+* @example
+* ```ts
+* button.addEventListener('click', async () => {
+*   const text = await readFromClipboard()
+*   if (text !== null) {
+*     input.value = text
+*   }
+* })
+* ```
+*/
+declare function readFromClipboard(options?: ClipboardOptions): Promise<string | null>;
+//#endregion
+export { copyToClipboard as a, ErrorCode as c, isClipboardSupported as i, OnErrorCallback as l, copyToClipboardLegacy as n, ClipboardOptions as o, isClipboardReadSupported as r, BrowserUtilsError as s, readFromClipboard as t };
+//# sourceMappingURL=index-B7FFRy7e.d.mts.map