@botiverse/porthole 0.1.1 → 0.1.3

package/src/index.ts

@@ -7,6 +7,7 @@
 export {
   CAPABILITIES,
   CAPABILITY_NAMES,
+  MAX_COPY_CHARS,
   capabilitySpec,
   isCapabilityName,
   type CapabilityArgs,
@@ -38,8 +39,14 @@ export {
   originSourceProblem,
   validateConfig,
 } from "./config/validate.ts";
-export { URL_SANDBOX_EXTRAS, type UrlSandboxExtra } from "./config/schema.ts";
+export {
+  URL_PERMISSIONS,
+  URL_SANDBOX_EXTRAS,
+  type UrlPermission,
+  type UrlSandboxExtra,
+} from "./config/schema.ts";
 export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
+export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
 
 // Presets.
 export {
@@ -99,6 +106,7 @@ export type {
   ShellConnection,
 } from "./protocol/adapter.ts";
 export {
+  COPY_TEXT_METHOD,
   MCP_APPS_METHODS,
   MCP_APPS_PROTOCOL_VERSION,
   MCP_APPS_STYLE_VARIABLES,
@@ -118,11 +126,33 @@ export type {
   Refusal,
 } from "./bridge/types.ts";
 export { createHost } from "./host/create-host.ts";
+export { writeClipboard } from "./host/clipboard.ts";
 export type {
+  AnnotationControls,
   DisplayControls,
   DisplayEvents,
+  FrameBlock,
+  FrameOutcome,
   DisplayHandle,
   HostOptions,
   MountOptions,
   PortholeHost,
 } from "./host/types.ts";
+
+// Annotations (P053): anchors, what a frame reports, and the host's checks on both.
+export {
+  ANNOTATE_METHODS,
+  ANNOTATION_LIMITS,
+  type AnchorResult,
+  type AnchorState,
+  type AnnotateMode,
+  type AnnotationAnchor,
+  type AnnotationMark,
+  type AnnotationRect,
+  type AnnotationReport,
+  type AnnotationSelector,
+  type CssSelector,
+  type TextPositionSelector,
+  type TextQuoteSelector,
+} from "./annotate/types.ts";
+export { parseAnchor, parseRect, parseReport } from "./annotate/validate.ts";

package/src/mcp/adapter.ts

@@ -14,7 +14,7 @@ import {
   MCP_APPS_PROTOCOL_VERSION,
   type HostContext,
 } from "../protocol/mcp-apps.ts";
-import { MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
+import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
 
 /**
  * The MCP Apps adapter (P004, P007): the host side of the protocol for full MCP Apps views, written
@@ -283,6 +283,15 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
           () => ({}),
         );
         return;
+      case COPY_TEXT_METHOD:
+        // Porthole's own request (the standard has no clipboard request): the host copies, and
+        // shows the person what (P052).
+        if (typeof params.text !== "string") {
+          invalid("needs text");
+          return;
+        }
+        await call(request, "copyText", { text: params.text }, done);
+        return;
       case MCP_APPS_METHODS.requestDisplayMode: {
         if (typeof params.mode !== "string" || !DISPLAY_MODES.has(params.mode)) {
           invalid("needs a display mode");

package/src/presets/presets.ts

@@ -10,6 +10,7 @@ import type {
   Limits,
   PortholeConfig,
   ThemeValue,
+  UrlPermission,
   UrlSandboxExtra,
 } from "../config/schema.ts";
 import { validateConfig } from "../config/validate.ts";
@@ -51,6 +52,8 @@ export interface UrlPresetOptions {
   readonly contentOrigins: readonly string[];
   /** Sandbox tokens to add for the app (popups for an OAuth flow, modals, downloads; P037). */
   readonly sandbox?: readonly UrlSandboxExtra[];
+  /** Features to delegate to the app (clipboard writes, full screen; P049). */
+  readonly permissions?: readonly UrlPermission[];
   readonly limits?: Partial<Limits>;
   readonly layout?: Partial<LayoutConfig>;
   readonly embedder?: EmbedderConfig;
@@ -211,6 +214,7 @@ export const presets = {
       contentOrigins: options.contentOrigins,
       embedder: options.embedder ?? {},
       ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
+      ...(options.permissions === undefined ? {} : { permissions: options.permissions }),
     }),
 } as const;
 

package/src/protocol/mcp-apps.ts

@@ -115,6 +115,12 @@ export const MCP_APPS_STYLE_VARIABLES: readonly string[] = [
  */
 export const PORTHOLE_STYLES = "porthole/styles";
 
+/**
+ * Porthole's own request for copying text (`copyText`, P052): `{ text }`, answered `{}` when the
+ * host copied it and `{ isError: true }` when it didn't. The standard has no clipboard request.
+ */
+export const COPY_TEXT_METHOD = "porthole/copy-text";
+
 /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
 export const SHELL_LOGGER = "porthole";
 

package/src/protocol/shell-adapter.ts

@@ -8,7 +8,12 @@ import {
   type JsonRpcRequest,
   type JsonRpcResponse,
 } from "./jsonrpc.ts";
-import { MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, type HostContext } from "./mcp-apps.ts";
+import {
+  COPY_TEXT_METHOD,
+  MCP_APPS_METHODS as M,
+  MCP_APPS_PROTOCOL_VERSION,
+  type HostContext,
+} from "./mcp-apps.ts";
 
 /**
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
@@ -42,6 +47,7 @@ const REQUESTS: Readonly<
     }),
   },
   [M.openLink]: { capability: "openLink", args: (params) => ({ url: params.url }) },
+  [COPY_TEXT_METHOD]: { capability: "copyText", args: (params) => ({ text: params.text }) },
   [M.downloadFile]: {
     capability: "downloadFile",
     args: (params) => ({ contents: params.contents }),
@@ -63,7 +69,10 @@ function answer(
   outcome: CallOutcome<unknown>,
 ): { result: unknown } | { error: { code: number; message: string } } {
   const flagged =
-    capability === "sendPrompt" || capability === "openLink" || capability === "downloadFile";
+    capability === "sendPrompt" ||
+    capability === "openLink" ||
+    capability === "downloadFile" ||
+    capability === "copyText";
   if (!outcome.ok) {
     return flagged
       ? { result: { isError: true } }

package/src/react/dialog.tsx

@@ -66,6 +66,8 @@ function words(request: ConfirmRequest): Words {
       return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
     case "readData":
       return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
+    case "copyText":
+      return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
     default:
       return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
   }

package/src/react/frame.tsx

@@ -14,8 +14,10 @@ import {
   type ReactElement,
   type ReactNode,
 } from "react";
+import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
 import type {
   CallContext,
+  CapabilityHandler,
   CapabilityHandlers,
   Confirm,
   ConfirmAnswer,
@@ -25,11 +27,13 @@ import type {
 } from "../bridge/types.ts";
 import type { CapabilityName } from "../config/capabilities.ts";
 import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
+import { writeClipboard } from "../host/clipboard.ts";
 import { createHost } from "../host/create-host.ts";
 import type { DisplayEvents, DisplayHandle, FrameOutcome } from "../host/types.ts";
 import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
 import { ConfirmDialog } from "./dialog.tsx";
 import { createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";
+import { CopyToast, type CopyNotice } from "./toast.tsx";
 
 /**
  * The React binding: a `<PortholeProvider>` near the root owns what is per page (which frames
@@ -50,6 +54,8 @@ interface PageState {
   readonly confirm?: Confirm;
   readonly hostInfo?: { readonly name: string; readonly version: string };
   readonly locator?: InstanceLocator;
+  /** The default `copyText`: copies on the host's page and shows the toast (P052). */
+  readonly copyText?: CapabilityHandler<"copyText">;
 }
 
 /** Without a provider: one registry for the page, and no one to confirm (gated calls refused). */
@@ -69,6 +75,8 @@ export interface PortholeProviderProps {
   readonly locator?: InstanceLocator;
   /** A class for the default dialog, to restyle it. */
   readonly dialogClassName?: string;
+  /** A class for the default copy toast, to restyle it. */
+  readonly toastClassName?: string;
   readonly children?: ReactNode;
 }
 
@@ -96,16 +104,26 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
           ),
     [],
   );
+  // The default copyText: the host's page writes the clipboard (in the frame's click, which
+  // activated this page too) and shows the person what went on it, or offers to copy it.
+  const [notice, setNotice] = useState<CopyNotice | null>(null);
+  const copyText = useCallback<CapabilityHandler<"copyText">>(async ({ text }, context) => {
+    const copied = await writeClipboard(text, globalThis.document);
+    setNotice({ text, copied, title: context.title });
+    return copied;
+  }, []);
+  const closeNotice = useCallback(() => setNotice(null), []);
   const { hostInfo, locator } = props;
   const value = useMemo<PageState>(
     () => ({
       live,
       heights,
       confirm,
+      copyText,
       ...(hostInfo === undefined ? {} : { hostInfo }),
       ...(locator === undefined ? {} : { locator }),
     }),
-    [live, heights, confirm, hostInfo, locator],
+    [live, heights, confirm, copyText, hostInfo, locator],
   );
   const current = queue[0] ?? null;
   return (
@@ -125,6 +143,17 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
           }}
         />
       ) : null}
+      <CopyToast
+        notice={notice}
+        {...(props.toastClassName === undefined ? {} : { className: props.toastClassName })}
+        onClose={closeNotice}
+        onCopy={(failed) => {
+          // A click on the host's own page: the write has the gesture it needs now.
+          void writeClipboard(failed.text, globalThis.document).then((copied) =>
+            setNotice({ ...failed, copied }),
+          );
+        }}
+      />
     </Page.Provider>
   );
 }
@@ -186,6 +215,21 @@ export interface PortholeFrameProps {
    * restyle): the running frame reads them again.
    */
   readonly themeKey?: string | number;
+  /**
+   * Annotations, where the config declares `annotate` (P053): what the person may point at now
+   * (elements, text, or both), or null to stop. A picked element ends element picking: set it
+   * again to pick again.
+   */
+  readonly annotating?: AnnotateMode | null;
+  /** The anchors to mark in the frame (the host's comments). Keep it stable (memoized). */
+  readonly annotations?: readonly AnnotationMark[];
+  /** The mark to bring into view and make the active one; each new id focuses it. */
+  readonly focusedAnnotation?: string | null;
+  /**
+   * What the frame reported: a selection (an anchor and where it is), its clearing, a cancelled
+   * pick, where marks are. The content's word: UI hints, never permissions.
+   */
+  readonly onAnnotation?: (report: AnnotationReport) => void;
   /** Draws the placeholder instead of the default one. */
   readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
   readonly className?: string;
@@ -371,6 +415,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
         case "outcome":
           frame.onOutcome?.(detail as DisplayEvents["outcome"]);
           return;
+        case "annotation":
+          frame.onAnnotation?.(detail as DisplayEvents["annotation"]);
+          return;
       }
     },
   );
@@ -397,6 +444,14 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
           named(context),
         );
     }
+    // Copy buttons without a handler of the host's: the provider's, which shows a toast.
+    if (config.capabilities.copyText !== undefined && handlers.copyText === undefined) {
+      const fallback = page.copyText;
+      if (fallback !== undefined) {
+        handlers.copyText = (args, context) =>
+          fallback(args as { readonly text: string }, named(context));
+      }
+    }
     const asks = first.confirm !== undefined || page.confirm !== undefined;
     let display: DisplayHandle;
     try {
@@ -435,10 +490,14 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
       "refused",
       "muted",
       "outcome",
+      "annotation",
     ];
     for (const event of events) {
       display.on(event, (detail) => notify(event, detail));
     }
+    if (config.capabilities.annotate !== undefined) {
+      applyAnnotations(display, first);
+    }
     if (first.content !== undefined) {
       display.setContent(first.content, { partial: first.partial === true });
     }
@@ -455,6 +514,39 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
       handle.current?.setContent(content, { partial: partial === true });
     }
   }, [content, partial]);
+  // Annotations follow their props (a new display gets them all when it is made, above).
+  const annotates = config.capabilities.annotate !== undefined;
+  const { annotating, annotations, focusedAnnotation } = frame;
+  const mode =
+    annotating === undefined || annotating === null
+      ? ""
+      : JSON.stringify([annotating.elements ?? true, annotating.text ?? true]);
+  useEffect(() => {
+    const display = handle.current;
+    if (!annotates || display === null) {
+      return;
+    }
+    const wanted = mode === "" ? null : (JSON.parse(mode) as [boolean, boolean]);
+    attempt(
+      () =>
+        wanted === null
+          ? display.annotations.stop()
+          : display.annotations.start({ elements: wanted[0], text: wanted[1] }),
+      latest(),
+    );
+  }, [annotates, mode]);
+  useEffect(() => {
+    const display = handle.current;
+    if (annotates && display !== null) {
+      attempt(() => display.annotations.show(annotations ?? []), latest());
+    }
+  }, [annotates, annotations]);
+  useEffect(() => {
+    const display = handle.current;
+    if (annotates && display !== null && typeof focusedAnnotation === "string") {
+      attempt(() => display.annotations.focus(focusedAnnotation), latest());
+    }
+  }, [annotates, focusedAnnotation]);
   useEffect(() => {
     handle.current?.setTheme(scheme);
   }, [scheme]);
@@ -484,3 +576,27 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
     </div>
   );
 }
+
+/** Runs an annotation call, telling the frame's `onError` what it threw (a bad anchor, say). */
+function attempt(run: () => void, frame: PortholeFrameProps): void {
+  try {
+    run();
+  } catch (error) {
+    frame.onError?.(error instanceof Error ? error.message : String(error));
+  }
+}
+
+/** A new display's annotations, from the props as they are. */
+function applyAnnotations(display: DisplayHandle, frame: PortholeFrameProps): void {
+  attempt(() => {
+    if (frame.annotations !== undefined && frame.annotations.length > 0) {
+      display.annotations.show(frame.annotations);
+    }
+    if (typeof frame.focusedAnnotation === "string") {
+      display.annotations.focus(frame.focusedAnnotation);
+    }
+    if (frame.annotating !== undefined && frame.annotating !== null) {
+      display.annotations.start(frame.annotating);
+    }
+  }, frame);
+}

package/src/react/index.ts

@@ -2,7 +2,7 @@
  * `@botiverse/porthole/react`: the thin React binding (TSX: a host's bundler compiles it, or the
  * package's `dist`). Peer: `react` (19.2+, for `useEffectEvent`).
  *
- *   <PortholeProvider>                         // per page: live-frame cap, heights, the dialog
+ *   <PortholeProvider>                         // per page: live-frame cap, heights, the dialog, the copy toast
  *     <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
  *       content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
  *       theme={tokensFor} onError={report} />
@@ -17,4 +17,12 @@ export {
   type PortholeProviderProps,
 } from "./frame.tsx";
 export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
+export {
+  CopyToast,
+  TOAST_CHARS,
+  TOAST_MS,
+  clipped,
+  type CopyNotice,
+  type CopyToastProps,
+} from "./toast.tsx";
 export { admitFrame, createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";

package/src/react/toast.tsx

@@ -0,0 +1,96 @@
+import { useEffect, type ReactElement } from "react";
+
+/**
+ * The default copy notice (P052): when content's `copyText` copied something, the host's page
+ * shows the person what went on their clipboard, clipped, in a small toast outside every frame.
+ * If the write failed (no recent gesture), it says so and offers a Copy button: a click on the
+ * host's own page, which writes it. A host replaces it by passing its own `copyText` handler; it
+ * styles it through the `porthole-toast` class and data attributes.
+ */
+
+/** How long a toast for a copy that worked stays. */
+export const TOAST_MS = 5_000;
+/** The most of the copied text a toast shows. */
+export const TOAST_CHARS = 280;
+const TOAST_LINES = 4;
+
+export interface CopyNotice {
+  /** The whole text copied (or to copy). */
+  readonly text: string;
+  /** Whether it is on the clipboard. */
+  readonly copied: boolean;
+  /** The display's title, as the host named it. */
+  readonly title: string;
+}
+
+export interface CopyToastProps {
+  readonly notice: CopyNotice | null;
+  /** The person asked to copy it again (it failed), from this click. */
+  readonly onCopy: (notice: CopyNotice) => void;
+  readonly onClose: () => void;
+  readonly className?: string;
+}
+
+/** The text as the toast shows it: at most a few lines and `TOAST_CHARS` characters. */
+export function clipped(text: string): { readonly shown: string; readonly clipped: boolean } {
+  const lines = text.split("\n");
+  let shown = lines.slice(0, TOAST_LINES).join("\n");
+  if (shown.length > TOAST_CHARS) {
+    shown = shown.slice(0, TOAST_CHARS);
+  }
+  return shown.length < text.length
+    ? { shown: `${shown}…`, clipped: true }
+    : { shown, clipped: false };
+}
+
+const STYLE = `.porthole-toast{position:fixed;left:50%;bottom:24px;transform:translateX(-50%);z-index:2147483647;color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent);border-radius:12px;padding:12px 14px;width:min(420px,calc(100vw - 32px));box-shadow:0 8px 28px rgb(0 0 0 / .25);font:inherit;font-size:.9em}
+.porthole-toast p{margin:0 0 6px}
+.porthole-toast [data-porthole-source]{opacity:.72}
+.porthole-toast pre{margin:0;white-space:pre-wrap;overflow-wrap:anywhere;max-height:8em;overflow:hidden;padding:8px 10px;border-radius:8px;background:color-mix(in srgb,CanvasText 7%,transparent);font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace}
+.porthole-toast menu{display:flex;justify-content:flex-end;gap:8px;margin:8px 0 0;padding:0}
+.porthole-toast button{font:inherit;min-height:32px;padding:0 12px;border-radius:8px;border:1px solid color-mix(in srgb,CanvasText 25%,transparent);background:transparent;color:inherit;cursor:pointer}`;
+
+export function CopyToast({ notice, onCopy, onClose, className }: CopyToastProps): ReactElement {
+  useEffect(() => {
+    if (notice === null || !notice.copied) {
+      return;
+    }
+    const timer = setTimeout(onClose, TOAST_MS);
+    return () => clearTimeout(timer);
+  }, [notice, onClose]);
+  const view = notice === null ? null : clipped(notice.text);
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className={className === undefined ? "porthole-toast" : `porthole-toast ${className}`}
+      data-porthole-toast=""
+      data-porthole-copied={notice === null ? "" : String(notice.copied)}
+      hidden={notice === null}
+    >
+      <style>{STYLE}</style>
+      {notice === null || view === null ? null : (
+        <>
+          <p>
+            <strong>{notice.copied ? "Copied" : "Not copied yet"}</strong>{" "}
+            <span data-porthole-source="">{`from “${notice.title}”`}</span>
+          </p>
+          <pre data-porthole-copied-text="">{view.shown}</pre>
+          {view.clipped ? (
+            <p data-porthole-length="">{`${notice.text.length.toLocaleString("en-US")} characters in all`}</p>
+          ) : null}
+          <menu>
+            {notice.copied ? null : (
+              <button type="button" data-porthole-copy="" onClick={() => onCopy(notice)}>
+                Copy
+              </button>
+            )}
+            <button type="button" data-porthole-close="" onClick={onClose}>
+              {notice.copied ? "OK" : "Close"}
+            </button>
+          </menu>
+        </>
+      )}
+    </div>
+  );
+}

package/src/server/crypto.ts

@@ -0,0 +1,166 @@
+/**
+ * The hashing `/server` needs, in plain JavaScript over web-standard types (`Uint8Array`,
+ * `TextEncoder`, `crypto.getRandomValues`), so it runs the same on Node, Cloudflare Workers and
+ * any other runtime (P044). Synchronous on purpose: Web Crypto's HMAC is async, and an origin
+ * (`originFor`) is computed synchronously. SHA-256 per FIPS 180-4, HMAC per RFC 2104; checked
+ * against the standard vectors and `node:crypto` in `test/crypto.test.ts`.
+ */
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+const rotr = (x: number, n: number): number => (x >>> n) | (x << (32 - n));
+
+export function sha256(data: Uint8Array): Uint8Array {
+  const length = data.length;
+  // Padded to a multiple of 64 bytes: a 1 bit, zeros, then the length in bits (64-bit big-endian).
+  const padded = new Uint8Array(Math.ceil((length + 9) / 64) * 64);
+  padded.set(data);
+  padded[length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(padded.length - 8, Math.floor(length / 0x20000000), false);
+  view.setUint32(padded.length - 4, (length * 8) >>> 0, false);
+
+  const h = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const w = new Uint32Array(64);
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    for (let i = 0; i < 16; i += 1) {
+      w[i] = view.getUint32(offset + i * 4, false);
+    }
+    for (let i = 16; i < 64; i += 1) {
+      const a = w[i - 15] as number;
+      const b = w[i - 2] as number;
+      const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+      const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+      w[i] = ((w[i - 16] as number) + s0 + (w[i - 7] as number) + s1) >>> 0;
+    }
+    let [a, b, c, d, e, f, g, hh] = h as unknown as number[] as [
+      number,
+      number,
+      number,
+      number,
+      number,
+      number,
+      number,
+      number,
+    ];
+    for (let i = 0; i < 64; i += 1) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (hh + s1 + ch + (K[i] as number) + (w[i] as number)) >>> 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (s0 + maj) >>> 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = (d + t1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) >>> 0;
+    }
+    const next = [a, b, c, d, e, f, g, hh];
+    for (let i = 0; i < 8; i += 1) {
+      h[i] = ((h[i] as number) + (next[i] as number)) >>> 0;
+    }
+  }
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  for (let i = 0; i < 8; i += 1) {
+    outView.setUint32(i * 4, h[i] as number, false);
+  }
+  return out;
+}
+
+const BLOCK = 64;
+
+export function hmacSha256(key: Uint8Array, message: Uint8Array): Uint8Array {
+  const block = new Uint8Array(BLOCK);
+  block.set(key.length > BLOCK ? sha256(key) : key);
+  const inner = new Uint8Array(BLOCK + message.length);
+  const outer = new Uint8Array(BLOCK + 32);
+  for (let i = 0; i < BLOCK; i += 1) {
+    inner[i] = (block[i] as number) ^ 0x36;
+    outer[i] = (block[i] as number) ^ 0x5c;
+  }
+  inner.set(message, BLOCK);
+  outer.set(sha256(inner), BLOCK);
+  return sha256(outer);
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export const utf8 = (text: string): Uint8Array => encoder.encode(text);
+export const fromUtf8 = (bytes: Uint8Array): string => decoder.decode(bytes);
+
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/** Base64url without padding (RFC 4648 §5). */
+export function base64url(bytes: Uint8Array): string {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const n = ((bytes[i] as number) << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    out += B64[(n >>> 18) & 63];
+    out += B64[(n >>> 12) & 63];
+    if (i + 1 < bytes.length) {
+      out += B64[(n >>> 6) & 63];
+    }
+    if (i + 2 < bytes.length) {
+      out += B64[n & 63];
+    }
+  }
+  return out;
+}
+
+/** Decodes base64url without padding; null for anything else. */
+export function fromBase64url(text: string): Uint8Array | null {
+  if (!/^[A-Za-z0-9_-]*$/u.test(text) || text.length % 4 === 1) {
+    return null;
+  }
+  const out = new Uint8Array(Math.floor((text.length * 3) / 4));
+  let bits = 0;
+  let buffer = 0;
+  let index = 0;
+  for (const char of text) {
+    buffer = (buffer << 6) | B64.indexOf(char);
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[index] = (buffer >>> bits) & 0xff;
+      index += 1;
+    }
+  }
+  // The leftover bits of a canonical encoding are zero.
+  return (buffer & ((1 << bits) - 1)) === 0 ? out : null;
+}
+
+/** Equal bytes, compared in time that depends only on the length. */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let difference = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    difference |= (a[i] as number) ^ (b[i] as number);
+  }
+  return difference === 0;
+}
+
+/** Random bytes from the runtime's CSPRNG (`crypto.getRandomValues`: Node, Workers, browsers). */
+export function randomBytes(length: number): Uint8Array {
+  const bytes = new Uint8Array(length);
+  globalThis.crypto.getRandomValues(bytes);
+  return bytes;
+}