kerfjs 4.1.1 → 4.2.0-beta.2

package/dist/jsx-runtime.d.ts

@@ -1162,6 +1162,18 @@ declare class SafeHtml {
 declare function isSafeHtml(value: unknown): value is SafeHtml;
 /** Inject a pre-escaped HTML string. Use sparingly — caller is responsible for escaping. */
 declare function raw(html: string): SafeHtml;
+/**
+ * `trustedRaw(html)` — identical to {@link raw} at runtime, but names your intent:
+ * "this dynamic value is server-trusted, inject it verbatim." The
+ * `kerfjs/no-raw-with-dynamic-arg` lint rule flags a `raw()` with a NON-literal
+ * argument (unsanitized user input is the common XSS mistake) but leaves
+ * `trustedRaw()` alone — so a CSRF token, a trusted `<script src>`, or a
+ * server-issued id can be injected without scattering `eslint-disable` comments.
+ *
+ * It is NOT a sanitizer — it bypasses escaping exactly like `raw()`. Only pass
+ * values you control (server output, config, hard-coded), never raw user input.
+ */
+declare function trustedRaw(html: string): SafeHtml;
 /**
  * Internal: build a `SafeHtml` representing a list segment. Used by
  * `each()` so the JSX runtime is the sole owner of `SafeHtml` construction.
@@ -1236,4 +1248,4 @@ declare namespace JSX {
 declare function _toSegment(child: unknown): Segment;
 declare function _renderAttrVerbatim(name: string, value: unknown): string;
 
-export { type AttrLike, type AttrValue, type DataAriaAttrs, Fragment, JSX, type KerfBaseAttrs, type KerfCustomElement, SafeHtml, assertEmittableAttrName as _assertEmittableAttrName, _renderAttrVerbatim, _toSegment, granularListSafeHtml, isSafeHtml, jsx, jsx as jsxDEV, jsx as jsxs, listSafeHtml, raw };
+export { type AttrLike, type AttrValue, type DataAriaAttrs, Fragment, JSX, type KerfBaseAttrs, type KerfCustomElement, SafeHtml, assertEmittableAttrName as _assertEmittableAttrName, _renderAttrVerbatim, _toSegment, granularListSafeHtml, isSafeHtml, jsx, jsx as jsxDEV, jsx as jsxs, listSafeHtml, raw, trustedRaw };

package/dist/jsx-runtime.js

@@ -1,6 +1,6 @@
-export { Fragment, SafeHtml, assertEmittableAttrName as _assertEmittableAttrName, _renderAttrVerbatim, _toSegment, granularListSafeHtml, isSafeHtml, jsx, jsx as jsxDEV, jsx as jsxs, listSafeHtml, raw } from './chunk-JXAR5J54.js';
-import './chunk-GY4XV2UV.js';
+export { Fragment, SafeHtml, assertEmittableAttrName as _assertEmittableAttrName, _renderAttrVerbatim, _toSegment, granularListSafeHtml, isSafeHtml, jsx, jsx as jsxDEV, jsx as jsxs, listSafeHtml, raw, trustedRaw } from './chunk-FSAQR6IU.js';
 import './chunk-3APBEVHF.js';
+import './chunk-GY4XV2UV.js';
 import './chunk-VVDJLWMP.js';
 //# sourceMappingURL=jsx-runtime.js.map
 //# sourceMappingURL=jsx-runtime.js.map

package/dist/list.d.ts

@@ -0,0 +1,39 @@
+import { M as MountResult } from './mount-Bo2qOx25.js';
+import './jsx-runtime.js';
+import '@preact/signals-core';
+import './bindings-CYwoJpQb.js';
+
+/** A row's stable key. */
+type ListKey = string | number;
+/** Anything with a tracking `.value` array read — a `signal<readonly T[]>` or an `arraySignal<T>`. */
+interface ListSource<T> {
+    readonly value: readonly T[];
+}
+/** Options for {@link bindList}. */
+interface BindListOptions<T> {
+    /** Stable per-row key. Rows are matched, moved, and reused by this. */
+    key: (item: T) => ListKey;
+    /** Renders a row's content into its (individually mounted) row element. Read signals here for per-row reactivity. */
+    render: (item: T) => MountResult;
+    /** Row element tag. Default `'div'` (use `'li'` inside a `<ul>`, `'tr'` inside a `<tbody>`, …). */
+    tag?: string;
+    /**
+     * Turn on viewport virtualization. `rowHeight` is the fixed pixel height of
+     * every row; `overscan` (default 3) is how many extra rows to render above and
+     * below the viewport. `parent` must be a scroll container (your CSS: a fixed
+     * height + `overflow: auto`).
+     */
+    virtualize?: {
+        rowHeight: number;
+        overscan?: number;
+    };
+}
+/**
+ * Bind a keyed, per-row-reactive list to `parent`, driven by `source` (a
+ * `signal<readonly T[]>` or an `arraySignal<T>`). Returns a disposer that tears
+ * down every row mount, the scroll listener (if virtualized), and the source
+ * subscription.
+ */
+declare function bindList<T>(parent: HTMLElement, source: ListSource<T>, options: BindListOptions<T>): () => void;
+
+export { type BindListOptions, type ListKey, type ListSource, bindList };

package/dist/list.js

@@ -0,0 +1,146 @@
+import { ARRAY_SIGNAL_BRAND } from './chunk-MRYM3O3V.js';
+import { mount } from './chunk-4MY2656S.js';
+import './chunk-QIP723L4.js';
+import './chunk-YHH7OUFA.js';
+import './chunk-FSAQR6IU.js';
+import { effect } from './chunk-3APBEVHF.js';
+import './chunk-GY4XV2UV.js';
+import './chunk-VVDJLWMP.js';
+
+// src/list.ts
+function bindList(parent, source, options) {
+  const { key, render, tag = "div", virtualize } = options;
+  const overscan = virtualize?.overscan ?? 3;
+  const rows = /* @__PURE__ */ new Map();
+  const order = [];
+  let items = [];
+  let disposed = false;
+  let rafPending = false;
+  let firstRender = true;
+  const patchSource = source;
+  const granularEligible = virtualize === void 0 && patchSource[ARRAY_SIGNAL_BRAND] === true;
+  const container = virtualize === void 0 ? parent : document.createElement("div");
+  if (virtualize !== void 0) parent.appendChild(container);
+  const makeRow = (item) => {
+    const el = document.createElement(tag);
+    if (virtualize !== void 0) el.style.height = `${virtualize.rowHeight}px`;
+    const dispose = mount(el, () => render(item));
+    return { el, item, dispose };
+  };
+  const syncRows = (visible) => {
+    const wanted = /* @__PURE__ */ new Set();
+    for (const item of visible) wanted.add(key(item));
+    for (const [k, row] of rows) {
+      if (!wanted.has(k)) {
+        row.dispose();
+        row.el.remove();
+        rows.delete(k);
+      }
+    }
+    order.length = 0;
+    for (const item of visible) {
+      const k = key(item);
+      let row = rows.get(k);
+      if (row !== void 0 && row.item !== item) {
+        row.dispose();
+        row.el.remove();
+        rows.delete(k);
+        row = void 0;
+      }
+      if (row === void 0) {
+        row = makeRow(item);
+        rows.set(k, row);
+      }
+      order.push(row);
+    }
+    let ref = null;
+    for (let i = order.length - 1; i >= 0; i--) {
+      const el = order[i].el;
+      if (el.parentNode !== container || el.nextSibling !== ref) {
+        container.insertBefore(el, ref);
+      }
+      ref = el;
+    }
+  };
+  const applyPatches = (patches) => {
+    for (const patch of patches) {
+      if (patch.type === "insert") {
+        const row = makeRow(patch.item);
+        rows.set(key(patch.item), row);
+        order.splice(patch.index, 0, row);
+        container.insertBefore(row.el, order[patch.index + 1]?.el ?? null);
+      } else if (patch.type === "remove") {
+        const [row] = order.splice(patch.index, 1);
+        row.dispose();
+        row.el.remove();
+        rows.delete(key(row.item));
+      } else if (patch.type === "move") {
+        const [row] = order.splice(patch.from, 1);
+        order.splice(patch.to, 0, row);
+        container.insertBefore(row.el, order[patch.to + 1]?.el ?? null);
+      } else if (patch.type === "update") {
+        const current = order[patch.index];
+        if (current.item !== patch.item) {
+          current.dispose();
+          current.el.remove();
+          rows.delete(key(current.item));
+          const row = makeRow(patch.item);
+          rows.set(key(patch.item), row);
+          order[patch.index] = row;
+          container.insertBefore(row.el, order[patch.index + 1]?.el ?? null);
+        }
+      }
+    }
+  };
+  const renderWindow = () => {
+    if (virtualize === void 0) {
+      if (granularEligible) {
+        const patches = patchSource._consumePatches();
+        if (!firstRender && patches.length > 0 && !patches.some((p) => p.type === "replace")) {
+          applyPatches(patches);
+          return;
+        }
+      }
+      syncRows(items);
+      firstRender = false;
+      return;
+    }
+    const { rowHeight } = virtualize;
+    const total = items.length;
+    const start = Math.max(0, Math.floor(parent.scrollTop / rowHeight) - overscan);
+    const end = Math.min(total, Math.ceil((parent.scrollTop + parent.clientHeight) / rowHeight) + overscan);
+    syncRows(items.slice(start, end));
+    container.style.paddingTop = `${start * rowHeight}px`;
+    container.style.paddingBottom = `${Math.max(0, total - end) * rowHeight}px`;
+  };
+  const stopEffect = effect(() => {
+    items = source.value;
+    renderWindow();
+  });
+  const onScroll = () => {
+    if (rafPending) return;
+    rafPending = true;
+    globalThis.requestAnimationFrame(() => {
+      rafPending = false;
+      if (!disposed) renderWindow();
+    });
+  };
+  if (virtualize !== void 0) parent.addEventListener("scroll", onScroll);
+  return () => {
+    disposed = true;
+    stopEffect();
+    for (const row of rows.values()) {
+      row.dispose();
+      if (virtualize === void 0) row.el.remove();
+    }
+    rows.clear();
+    if (virtualize !== void 0) {
+      parent.removeEventListener("scroll", onScroll);
+      container.remove();
+    }
+  };
+}
+
+export { bindList };
+//# sourceMappingURL=list.js.map
+//# sourceMappingURL=list.js.map

package/dist/list.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/list.ts"],"names":[],"mappings":"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","file":"list.js","sourcesContent":["/**\n * `kerfjs/list` — `bindList`, a keyed list with a live per-row mount and\n * optional viewport virtualization.\n *\n * This is a DELIBERATE second list API, distinct from `each()`. It does two\n * things `each()` structurally cannot:\n *  1. **Per-row reactivity.** Every row is individually `mount()`ed, so a signal\n *     the row's `render` reads updates just that row (fine-grained binding or a\n *     one-row morph) without touching its siblings — no full-list pass.\n *  2. **Virtualization.** With `{ virtualize: { rowHeight } }` only the rows in\n *     the scroll viewport are rendered; padding on the scroll container keeps\n *     `scrollHeight` honest.\n *\n * `each()` stays the choice for item-owned-state lists rendered to HTML strings;\n * reach for `bindList` when you need surgical per-row updates or windowing.\n *\n *   import { bindList } from 'kerfjs/list';\n *\n *   const dispose = bindList(listEl, itemsSignal, {\n *     key: (row) => row.id,\n *     render: (row) => <span class={selected} data-id={row.id}>{row.label}</span>,\n *     tag: 'li',\n *     virtualize: { rowHeight: 32 },\n *   });\n *\n * `render` reads signals for reactivity (external state like a `selectedId`, or\n * signals the item carries) — keep the item OBJECTS stable across renders and\n * drive structure (add/remove/move) through `itemsSignal`. A row whose item\n * object identity changes is rebuilt (same rule as `each()`'s memo). `bindList`\n * OWNS `parent`'s children. It reads `itemsSignal.value`, so a plain\n * `signal<T[]>` or an `arraySignal<T>` both work.\n */\nimport { ARRAY_SIGNAL_BRAND, type ArrayPatch } from './array-signal.js';\nimport { mount, type MountResult } from './mount.js';\nimport { effect } from './reactive.js';\n\n/** A row's stable key. */\nexport type ListKey = string | number;\n\n/** Anything with a tracking `.value` array read — a `signal<readonly T[]>` or an `arraySignal<T>`. */\nexport interface ListSource<T> {\n  readonly value: readonly T[];\n}\n\n/** Options for {@link bindList}. */\nexport interface BindListOptions<T> {\n  /** Stable per-row key. Rows are matched, moved, and reused by this. */\n  key: (item: T) => ListKey;\n  /** Renders a row's content into its (individually mounted) row element. Read signals here for per-row reactivity. */\n  render: (item: T) => MountResult;\n  /** Row element tag. Default `'div'` (use `'li'` inside a `<ul>`, `'tr'` inside a `<tbody>`, …). */\n  tag?: string;\n  /**\n   * Turn on viewport virtualization. `rowHeight` is the fixed pixel height of\n   * every row; `overscan` (default 3) is how many extra rows to render above and\n   * below the viewport. `parent` must be a scroll container (your CSS: a fixed\n   * height + `overflow: auto`).\n   */\n  virtualize?: { rowHeight: number; overscan?: number };\n}\n\ninterface Row<T> {\n  el: HTMLElement;\n  item: T;\n  dispose: () => void;\n}\n\n/**\n * Bind a keyed, per-row-reactive list to `parent`, driven by `source` (a\n * `signal<readonly T[]>` or an `arraySignal<T>`). Returns a disposer that tears\n * down every row mount, the scroll listener (if virtualized), and the source\n * subscription.\n */\nexport function bindList<T>(\n  parent: HTMLElement,\n  source: ListSource<T>,\n  options: BindListOptions<T>,\n): () => void {\n  const { key, render, tag = 'div', virtualize } = options;\n  const overscan = virtualize?.overscan ?? 3;\n\n  const rows = new Map<ListKey, Row<T>>();\n  // The current DOM order of rows, kept in step by both the keyed-diff and the\n  // granular patch paths so index-based patches can address rows directly.\n  const order: Array<Row<T>> = [];\n  let items: readonly T[] = [];\n  let disposed = false;\n  let rafPending = false;\n  let firstRender = true;\n\n  // Granular fast path (KF-478): when the source is an `arraySignal` and the\n  // list is NOT virtualized, apply its insert/remove/move/update patches\n  // directly in O(patches) instead of diffing the whole snapshot. Virtualized\n  // lists keep the keyed diff — their visible set is just the window (cheap),\n  // and absolute-index patches don't compose with a shifting window. A plain\n  // `signal<T[]>` has no patches, so it always uses the keyed diff.\n  const patchSource = source as {\n    [ARRAY_SIGNAL_BRAND]?: boolean;\n    _consumePatches?: () => ArrayPatch<T>[];\n  };\n  const granularEligible = virtualize === undefined && patchSource[ARRAY_SIGNAL_BRAND] === true;\n\n  // Virtualized lists put the windowing padding + rows on an INNER sizer, so the\n  // padding never inflates the scroll container's clientHeight (padding counts\n  // toward clientHeight). `parent` stays the clean scroll viewport; `container`\n  // holds the rows. Non-virtualized lists render straight into `parent`.\n  const container: HTMLElement = virtualize === undefined ? parent : document.createElement('div');\n  if (virtualize !== undefined) parent.appendChild(container);\n\n  const makeRow = (item: T): Row<T> => {\n    const el = document.createElement(tag);\n    // bindList knows the fixed row height, so it sizes rows itself — no\n    // consumer CSS needed for the windowing math to line up.\n    if (virtualize !== undefined) el.style.height = `${virtualize.rowHeight}px`;\n    const dispose = mount(el, () => render(item));\n    return { el, item, dispose };\n  };\n\n  // Reconcile the live rows to exactly `visible`, in order, keyed.\n  const syncRows = (visible: readonly T[]): void => {\n    const wanted = new Set<ListKey>();\n    for (const item of visible) wanted.add(key(item));\n\n    // Remove rows that are gone from the window.\n    for (const [k, row] of rows) {\n      if (!wanted.has(k)) {\n        row.dispose();\n        row.el.remove();\n        rows.delete(k);\n      }\n    }\n\n    // Create missing rows (and rebuild a row whose item OBJECT changed identity).\n    order.length = 0;\n    for (const item of visible) {\n      const k = key(item);\n      let row = rows.get(k);\n      if (row !== undefined && row.item !== item) {\n        row.dispose();\n        row.el.remove();\n        rows.delete(k);\n        row = undefined;\n      }\n      if (row === undefined) {\n        row = makeRow(item);\n        rows.set(k, row);\n      }\n      order.push(row);\n    }\n\n    // Reverse pass: move only rows that are out of position.\n    let ref: Node | null = null;\n    for (let i = order.length - 1; i >= 0; i--) {\n      const el = order[i].el;\n      if (el.parentNode !== container || el.nextSibling !== ref) {\n        container.insertBefore(el, ref);\n      }\n      ref = el;\n    }\n  };\n\n  // Apply arraySignal structural patches directly to `order` + the DOM, in\n  // O(patches). Indices are always valid by construction: `order` reflects the\n  // last-rendered state and the patches are exactly the delta from it (bindList\n  // drains the queue every render, and `replace` is filtered out by the caller,\n  // which snapshots instead). The `splice()`s mirror `arraySignal`'s own\n  // `_items` mutations exactly.\n  const applyPatches = (patches: readonly ArrayPatch<T>[]): void => {\n    for (const patch of patches) {\n      if (patch.type === 'insert') {\n        const row = makeRow(patch.item);\n        rows.set(key(patch.item), row);\n        order.splice(patch.index, 0, row);\n        container.insertBefore(row.el, order[patch.index + 1]?.el ?? null);\n      } else if (patch.type === 'remove') {\n        const [row] = order.splice(patch.index, 1);\n        row.dispose();\n        row.el.remove();\n        rows.delete(key(row.item));\n      } else if (patch.type === 'move') {\n        const [row] = order.splice(patch.from, 1);\n        order.splice(patch.to, 0, row);\n        container.insertBefore(row.el, order[patch.to + 1]?.el ?? null);\n      } else if (patch.type === 'update') {\n        // Decision #3: an item whose OBJECT identity changed rebuilds the row\n        // (matching the keyed-diff rule). A same-ref update needs nothing here —\n        // the row's own mount reacts to whatever signals its render reads.\n        const current = order[patch.index];\n        if (current.item !== patch.item) {\n          current.dispose();\n          current.el.remove();\n          rows.delete(key(current.item));\n          const row = makeRow(patch.item);\n          rows.set(key(patch.item), row);\n          order[patch.index] = row;\n          container.insertBefore(row.el, order[patch.index + 1]?.el ?? null);\n        }\n      }\n      // 'replace' never reaches here — the caller snapshots on it.\n    }\n  };\n\n  const renderWindow = (): void => {\n    if (virtualize === undefined) {\n      if (granularEligible) {\n        // Always drain to keep the single patch queue clean (so patches never\n        // double-apply). Take the granular path past the first render, when\n        // there are patches, and none is a `replace` (which reshapes the whole\n        // array — snapshot instead). Otherwise fall through to a keyed diff.\n        const patches = patchSource._consumePatches!();\n        if (\n          !firstRender\n          && patches.length > 0\n          && !patches.some((p) => p.type === 'replace')\n        ) {\n          applyPatches(patches);\n          return;\n        }\n      }\n      syncRows(items);\n      firstRender = false;\n      return;\n    }\n    const { rowHeight } = virtualize;\n    const total = items.length;\n    const start = Math.max(0, Math.floor(parent.scrollTop / rowHeight) - overscan);\n    const end = Math.min(total, Math.ceil((parent.scrollTop + parent.clientHeight) / rowHeight) + overscan);\n    syncRows(items.slice(start, end));\n    container.style.paddingTop = `${start * rowHeight}px`;\n    container.style.paddingBottom = `${Math.max(0, total - end) * rowHeight}px`;\n  };\n\n  const stopEffect = effect(() => {\n    items = source.value; // tracking read — re-runs on any structural change\n    renderWindow();\n  });\n\n  const onScroll = (): void => {\n    if (rafPending) return;\n    rafPending = true;\n    globalThis.requestAnimationFrame(() => {\n      rafPending = false;\n      if (!disposed) renderWindow();\n    });\n  };\n  if (virtualize !== undefined) parent.addEventListener('scroll', onScroll);\n\n  return () => {\n    disposed = true;\n    stopEffect();\n    for (const row of rows.values()) {\n      row.dispose();\n      if (virtualize === undefined) row.el.remove();\n    }\n    rows.clear();\n    if (virtualize !== undefined) {\n      parent.removeEventListener('scroll', onScroll);\n      container.remove(); // removes the inner sizer and its rows in one go\n    }\n  };\n}\n"]}

package/dist/mount-Bo2qOx25.d.ts

@@ -0,0 +1,57 @@
+import { SafeHtml } from './jsx-runtime.js';
+
+/**
+ * `mount(rootEl, render)` — kerf's render primitive.
+ *
+ * Wraps `effect()` so that whenever any signal read inside `render()`
+ * changes, we re-run `render()` and apply the minimum DOM mutations against
+ * the live tree. Element identity (and thus focus, selection, in-flight
+ * pointer interactions, and event listeners on preserved nodes) is preserved
+ * wherever the keyed/positional diff matches.
+ *
+ * Two phases per render:
+ *
+ *   - Static surrounds (everything outside `each()` lists): kerf's native
+ *     `morph()` reconciler walks a freshly-built template against the live
+ *     tree. Conventions: id/data-key matching, `data-morph-skip`, focus
+ *     preservation.
+ *
+ *   - List interiors (children of every `each()` parent): native keyed
+ *     reconciler operates directly on the live parent's children. No
+ *     re-parse, no morph walk for cache-hit rows. Cost is O(changes), not
+ *     O(rows).
+ *
+ * Compared to a `replaceChildren(...rows.map(toElement))` rebuild pattern,
+ * the user-visible win is that an `<input>` the user is typing into
+ * survives an unrelated re-render — its DOM node, focus state, and cursor
+ * position are not destroyed and recreated on each tick.
+ */
+
+/** What `mount()`'s render function may return; non-SafeHtml values coerce (nullish/boolean → render nothing). */
+type MountResult = SafeHtml | string | number | boolean | null | undefined;
+/**
+ * Bind `render()` to the children of `rootEl`. Re-runs whenever any signal
+ * read inside `render()` changes. Returns a disposer that tears down the
+ * effect; call it when the host element is removed from the DOM.
+ *
+ * Conventions:
+ *
+ * - Diff keys: `id` and `data-key` are matched across the morph by key
+ *   rather than positionally, so list reorders move existing nodes instead
+ *   of churning unrelated siblings.
+ * - `data-morph-skip`: any element with this attribute is left untouched
+ *   inside on subsequent renders. Used for library-owned subtrees (xterm-
+ *   style widgets, charts, third-party editors) where the library's own
+ *   lifecycle manages the children.
+ * - Focused text-entry inputs (`<input>` of typing kinds, `<textarea>`)
+ *   keep their current value + selection range across morphs while focused.
+ *   The user never sees their cursor jump mid-keystroke.
+ * - Focused `[contenteditable]` elements have their entire subtree
+ *   skipped (same mechanism as `data-morph-skip`). The user's in-progress
+ *   edit — typed content, caret position, multi-range selections, anything
+ *   else they did to the DOM — survives verbatim. The next render after
+ *   blur catches up.
+ */
+declare function mount(rootEl: HTMLElement, render: () => MountResult): () => void;
+
+export { type MountResult as M, mount as m };

package/dist/overlay.d.ts

@@ -0,0 +1,204 @@
+import { SafeHtml } from './jsx-runtime.js';
+import { M as MountResult } from './mount-Bo2qOx25.js';
+import '@preact/signals-core';
+import './bindings-CYwoJpQb.js';
+
+/** A user-initiated dismissal trigger. */
+type DismissTrigger = 'escape' | 'backdrop' | 'outside';
+/** Content for an overlay: static `SafeHtml`, or a render function `mount()` drives reactively. */
+type OverlayContent = SafeHtml | (() => MountResult);
+/** Options for {@link overlay}. */
+interface OverlayOptions {
+    /** Where to append the overlay wrapper. Default `document.body`. */
+    container?: Element;
+    /** Class on the wrapper element (you style it — kerf ships no CSS). Default `'kerf-overlay'`. */
+    className?: string;
+    /**
+     * Which user actions dismiss the overlay. Default `['escape', 'backdrop']`.
+     * `'backdrop'` = a click on the wrapper itself (not its content); `'outside'`
+     * = a click anywhere outside the wrapper (for anchored popovers). `false`
+     * disables user dismissal (close it programmatically).
+     */
+    dismiss?: DismissTrigger | DismissTrigger[] | false;
+    /**
+     * Where focus lands on open: a selector, `true` (first focusable element, or
+     * the wrapper if none), or `false` (leave focus alone). Default `true`.
+     */
+    initialFocus?: string | boolean;
+    /**
+     * Trap Tab / Shift+Tab within the overlay while open and mark it
+     * `role="dialog"` / `aria-modal="true"`. Default `true`. Set `false` for a
+     * non-modal popover.
+     */
+    trap?: boolean;
+    /** ARIA role for the wrapper when `trap` is on. Default `'dialog'`. */
+    role?: string;
+    /** Called on any user-initiated dismissal (before `close()` runs). */
+    onDismiss?: () => void;
+    /** For `'outside'` dismissal: clicks on these elements do NOT count as outside (e.g. the trigger button). */
+    outsideIgnore?: Element | readonly Element[];
+}
+/** Handle returned by {@link overlay}. Holds no framework state — it's a closure. */
+interface OverlayHandle {
+    /** The wrapper element (mounted into, appended to `container`). */
+    el: HTMLElement;
+    /** Tear down: dispose the mount, remove listeners + the node, restore focus, resolve `result`. Idempotent. */
+    close(result?: unknown): void;
+    /** Resolves with the value passed to `close()` (or `undefined` on user dismissal). */
+    result: Promise<unknown>;
+}
+/**
+ * Open an overlay: append a wrapper to `container`, `mount()` `content` inside
+ * it, wire the requested dismissals + (optionally) a focus trap, and return a
+ * handle. See {@link OverlayOptions}.
+ */
+declare function overlay(content: OverlayContent, options?: OverlayOptions): OverlayHandle;
+/** Options for {@link confirm}. */
+interface ConfirmOptions {
+    /** Where to append the overlay. Default `document.body`. */
+    container?: Element;
+    /** Wrapper class. Default `'kerf-overlay'`. */
+    className?: string;
+    /** Optional heading above the message. */
+    title?: string;
+    /** Confirm button label. Default `'OK'`. */
+    okText?: string;
+    /** Cancel button label. Default `'Cancel'`. */
+    cancelText?: string;
+    /** Add a `kerf-confirm--danger` class to the wrapper for destructive actions. */
+    danger?: boolean;
+}
+/**
+ * A promise-based `window.confirm` replacement (that global is a no-op in Tauri
+ * webviews). Renders a two-button dialog and resolves `true` for OK, `false`
+ * for Cancel or any dismissal (Escape / backdrop). Message + labels are
+ * auto-escaped (rendered through the JSX runtime).
+ */
+declare function confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
+/**
+ * Validate a single field's value. Return a non-empty error string to BLOCK
+ * submission (shown inline next to the field); return `undefined`/`null`/`''` to
+ * allow it.
+ */
+type FieldValidator = (value: string) => string | null | undefined | void;
+/** Options for {@link prompt}. */
+interface PromptOptions {
+    /** Where to append the overlay. Default `document.body`. */
+    container?: Element;
+    /** Wrapper class. Default `'kerf-overlay'`. */
+    className?: string;
+    /** Optional heading above the message. */
+    title?: string;
+    /** Pre-filled input value. Default `''`. */
+    defaultValue?: string;
+    /** Input placeholder. */
+    placeholder?: string;
+    /** `type` attribute of the input (`'text'`, `'email'`, `'password'`, …). Default `'text'`. */
+    inputType?: string;
+    /** Confirm button label. Default `'OK'`. */
+    okText?: string;
+    /** Cancel button label. Default `'Cancel'`. */
+    cancelText?: string;
+    /** Block OK while this returns an error string; the message shows inline. */
+    validate?: FieldValidator;
+}
+/**
+ * A promise-based `window.prompt` replacement (that global is a no-op in Tauri
+ * webviews). Renders a one-field dialog and resolves the entered **string** on OK
+ * (an empty string is a valid result) or `null` on Cancel / dismissal. Enter in
+ * the input submits. `message`, the default value, and labels are auto-escaped
+ * (rendered through the JSX runtime). Optional `validate` blocks OK inline.
+ */
+declare function prompt(message: string, options?: PromptOptions): Promise<string | null>;
+/** A single field in a {@link form}. */
+interface FormField {
+    /** Field name — the key in the resolved record (and the input's `name`). */
+    name: string;
+    /** Label shown above the input. Defaults to `name`. */
+    label?: string;
+    /** Pre-filled value. Default `''`. */
+    defaultValue?: string;
+    /** Input placeholder. */
+    placeholder?: string;
+    /** `type` attribute of the input. Default `'text'`. */
+    type?: string;
+    /** Block OK while this returns an error string; the message shows inline for this field. */
+    validate?: FieldValidator;
+}
+/** Options for {@link form}. */
+interface FormOptions {
+    /** Where to append the overlay. Default `document.body`. */
+    container?: Element;
+    /** Wrapper class. Default `'kerf-overlay'`. */
+    className?: string;
+    /** Optional heading above the fields. */
+    title?: string;
+    /** Confirm button label. Default `'OK'`. */
+    okText?: string;
+    /** Cancel button label. Default `'Cancel'`. */
+    cancelText?: string;
+}
+/**
+ * A promise-based multi-field dialog — the two-or-three-input sibling of
+ * {@link prompt}. Renders one labeled input per {@link FormField} and resolves a
+ * `Record<name, value>` on OK (after every field's `validate` passes) or `null`
+ * on Cancel / dismissal. Enter in any field submits. All labels, defaults, and
+ * the title are auto-escaped through the JSX runtime.
+ */
+declare function form(fields: readonly FormField[], options?: FormOptions): Promise<Record<string, string> | null>;
+/** Vertical placement of a {@link popover} relative to its anchor. */
+type PopoverPlacement = 'bottom' | 'top';
+/** Options for {@link popover}. */
+interface PopoverOptions {
+    /** Where to append the popover wrapper. Default `document.body`. */
+    container?: Element;
+    /** Class on the wrapper. Default `'kerf-popover'`. */
+    className?: string;
+    /** Preferred side of the anchor. Flips to the other side if it would overflow the viewport. Default `'bottom'`. */
+    placement?: PopoverPlacement;
+    /** Horizontal edge to line up with the anchor: `'start'` (left edges) or `'end'` (right edges). Default `'start'`. */
+    align?: 'start' | 'end';
+    /** Gap in px between the anchor and the popover. Default `4`. */
+    gap?: number;
+    /**
+     * Which user actions dismiss the popover. Default `['outside']` (a click
+     * outside the popover, the anchor exempt). Pass `false` to close only via `close()`.
+     */
+    dismiss?: DismissTrigger | DismissTrigger[] | false;
+    /** Focus behavior on open. Default `false` (non-modal — leave focus alone). */
+    initialFocus?: string | boolean;
+    /** Extra elements (besides the anchor) whose clicks do NOT count as outside. */
+    outsideIgnore?: Element | readonly Element[];
+    /** Called on any user-initiated dismissal. */
+    onDismiss?: () => void;
+}
+/**
+ * Anchored, non-modal overlay: positions `content` relative to `anchor` (below by
+ * default, flipping above if it would overflow, and clamped horizontally to the
+ * viewport) and repositions on scroll / resize while open. A thin wrapper over
+ * {@link overlay} with non-modal defaults — `trap: false`, `dismiss: ['outside']`,
+ * and the anchor added to `outsideIgnore` so the trigger click doesn't self-close.
+ * Returns the same {@link OverlayHandle}; `close()` also drops the reposition
+ * listeners. `position: fixed` is set inline (you style everything else).
+ */
+declare function popover(anchor: Element, content: OverlayContent, options?: PopoverOptions): OverlayHandle;
+/** Content for a {@link toast}: text, `SafeHtml`, or a render function. */
+type ToastContent = string | SafeHtml | (() => MountResult);
+/** Options for {@link toast}. */
+interface ToastOptions {
+    /** Where toasts stack. Default: a lazily-created `<div class="kerf-toasts">` on `document.body`. */
+    container?: Element;
+    /** Class on the toast element. Default `'kerf-toast'`. */
+    className?: string;
+    /** Auto-dismiss after this many ms. `0` keeps it until dismissed by hand. Default `4000`. */
+    duration?: number;
+    /** ARIA role. Default `'status'`. */
+    role?: string;
+}
+/**
+ * Show a non-modal, auto-dismissing notification. Stacks in a shared body-level
+ * region (or your `container`). Returns a `() => void` that dismisses it early.
+ */
+declare function toast(content: ToastContent, options?: ToastOptions): () => void;
+
+export { type ConfirmOptions, type DismissTrigger, type FieldValidator, type FormField, type FormOptions, type OverlayContent, type OverlayHandle, type OverlayOptions, type PopoverOptions, type PopoverPlacement, type PromptOptions, type ToastContent, type ToastOptions, confirm, form, overlay, popover, prompt, toast };