kerfjs 4.3.0-beta.1 → 4.4.0-beta.1

package/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+- **New `kerfjs/router` subpath — a client-side router (the "postcard router").** `createRouter({ routes, mode?, base?, interceptLinks? })` returns a handle over three things kerf already has: a reactive `route` signal (`{ path, params, query, hash }`), `delegate()`-based `<a href>` link interception, and a keyed **outlet** — `router.outlet()` renders the matched route in a `data-key`ed wrapper, so kerf's keyed morph **replaces the page wholesale on a route change** (fresh DOM) and **reconciles in place on a same-route param change** (preserving scroll / focus). Route patterns are static, `:param`, a trailing `*rest` wildcard, and `*` catch-all; the handle also gives `navigate(path, { replace?, state? })`, `back()`/`forward()`, `match(pattern)` / `activeClass(pattern, className)` reactive active-link helpers, hash **or** history mode, an optional base path, and `dispose()`. Link interception is automatic (same-origin, left-click, no modifier/`target`/`download`, opt out per-link with `data-router-ignore` / `rel="external"` or globally with `interceptLinks: false`). **Deliberately scoped** — no nested layouts, data loaders, lazy routes, guards, or SSR matching; compose those with kerf primitives (`resource` for loading, an `effect` on `route` for guards). The kerf **core stays router-free** — this is opt-in and tree-shakeable, adding nothing to the main barrel until imported, and docs/1's "Not a router" is about the runtime. See [`docs/20-router.md`](docs/20-router.md).
+
+## [4.3.0] - 2026-08-22
+
+
+
+- KF-529: refresh README for the 4.3 cycle (prep-major-release) (`909c82a`)
+- KF-530: extract promise-dialog helpers into overlay-dialogs.ts (`5d4ac38`)
+- KF-528: sync llms.txt with docs/19 + 4.3 features (`1d9c004`)
+
 - **`kerfjs/overlay` gains opt-in native top-layer backing (`native: true`).** Every overlay surface (`overlay`, `confirm`, `prompt`, `form`, `choice`, `popover`, `tooltip`) now takes `native?: boolean` (default `false`). When `true` and the engine supports it, a **modal** surface (`trap: true`) is hosted in a `<dialog>` opened with `.showModal()` — real document inerting (pointer + focus + AT) and guaranteed stacking above any `z-index` — and a **non-modal** surface (`trap: false`) uses the **Popover API** (`[popover]` + `showPopover()`). Feature-detected (`HTMLDialogElement.prototype.showModal`, `HTMLElement.prototype.showPopover`), falling back to today's plain `<div>` where unsupported, so `native: true` is always safe to pass. The `render` slot + promise API are unchanged — kerf just hosts your markup in a `<dialog>` / `[popover]`. **Opt-in on purpose:** the native elements carry UA default styles (a `::backdrop`, centering, border, padding) that kerf does **not** reset (a reset would violate the zero-CSS contract) — style the element and its `::backdrop` via `className` (`.kerf-overlay::backdrop { … }`, the stable contract); and `container` becomes a visual no-op in native mode (the top layer ignores DOM position). See [`docs/19-native-overlay-backing.md`](docs/19-native-overlay-backing.md).
 - **`bindList` virtualization gains a `content-visibility` mode.** `virtualize: { rowHeight, mode: 'content-visibility' }` is a second virtualization strategy alongside the default `mode: 'window'` (today's JS windowing). It keeps **every** row in the DOM and sets `content-visibility: auto` + `contain-intrinsic-size: 0 <rowHeight>px` on each row, so a supporting engine (Chromium, Safari 18) skips the *layout/paint* of off-screen rows while **all rows stay findable** — find-in-page (Cmd/Ctrl+F), the accessibility tree, and anchor links / `scrollIntoView` all work on any row (the exact guarantee `mode: 'window'` can't give, since it removes off-window rows from the DOM). The `mode` choice is the app's and it's about list size: pick `'content-visibility'` for medium lists where findability beats the node ceiling, keep `'window'` for very large (100k-row) lists. In this mode `rowHeight` is only the `contain-intrinsic-size` placeholder (no windowing math), `setHeight` / `observeRowHeights` are no-ops (the browser owns measurement), `minRows` is ignored (all rows already render), and no scroll listener / `ResizeObserver` is installed — while `handle.container` / `containerClass` / `containerId` still work. There is deliberately **no feature detection**: on an engine without `content-visibility` the CSS is inert, so all rows still render (correct, still findable) — only the off-screen-skip optimization is absent. See [`docs/17-list-virtualization.md`](docs/17-list-virtualization.md) §17.11.
 - **Docs: `bindList` virtualization findability/a11y tradeoff is now a first-class caveat.** Off-window rows are removed from the DOM (not just hidden), so with `virtualize` set, find-in-page (Cmd/Ctrl+F), screen readers / the accessibility tree, and anchor links / `scrollIntoView` reach only the visible window. New `docs/17-list-virtualization.md` §17.10 spells out the consequences and the guidance (don't virtualize, or use `minRows` above the list length, when full findability matters more than the DOM node ceiling), and the `bindList` JSDoc + `docs/8-api-reference.md` §8.11 carry the same note. Behavior unchanged — documentation only.

package/README.md

@@ -53,7 +53,7 @@ Here's the whole development loop — write a component, run the dev server, cli
 
 7. **Small public API.** ~18 exports from the main barrel (plus `arraySignal`, the `html` tagged template, and the companion-utility subpaths below — each opt-in, none in the core). No hooks, no lifecycle, no per-instance state. Components are plain functions that return JSX.
 
-8. **Batteries on their own subpaths.** Nine optional, tree-shakeable subpaths cover the patterns every real app otherwise hand-rolls — **`kerfjs/list`** (a keyed list with per-row fine-grained mounts and fixed / app-declared / measured-height viewport **virtualization**), **`kerfjs/overlay`** (modals, `confirm` / `prompt` / `form` / `choice`, anchored popovers + tooltips, toasts), **`kerfjs/async`** (`resource` async-state with a built-in stale-response guard + SWR cache), **`kerfjs/scope`** (dispose-scopes that tie teardown to a DOM node's lifetime), plus `timing`, `remount`, `attach`, and `actions`. None of them grows the ~12 KB core until you import it.
+8. **Batteries on their own subpaths.** Nine optional, tree-shakeable subpaths cover the patterns every real app otherwise hand-rolls — **`kerfjs/list`** (a keyed list with per-row fine-grained mounts and fixed / app-declared / measured-height viewport **virtualization**, plus a `content-visibility` mode that keeps every row find-in-page-able), **`kerfjs/router`** (a "postcard **router**": route matching, `navigate`, auto `<a>` link interception, and a keyed outlet — the *core* stays router-free, this is opt-in), **`kerfjs/overlay`** (modals, `confirm` / `prompt` / `form` / `choice`, anchored popovers + tooltips, toasts — with opt-in native **top-layer** backing that stacks above any `z-index`), **`kerfjs/async`** (`resource` async-state with a built-in stale-response guard + SWR cache), **`kerfjs/scope`** (dispose-scopes that tie teardown to a DOM node's lifetime), plus `timing`, `remount`, `attach`, and `actions`. None of them grows the ~12 KB core until you import it.
 
 9. **Plain TS, plain JSX, plain ESM.** Drops into anything using esbuild / Vite / tsup. No plugin chain. And with the `html` tagged template (`import { html } from 'kerfjs/html'` — identical runtime semantics to JSX), a CDN / importmap project needs no build step at all.
 
@@ -227,7 +227,25 @@ const list = bindList(scrollEl, messages, {
 observeRowHeights(list); // one ResizeObserver → kerf anchor-corrects scroll
 ```
 
-Each subpath adds nothing to the main barrel until it's imported. See [`docs/8-api-reference.md`](./docs/8-api-reference.md) for the full list (`list`, `overlay`, `scope`, `async`, `timing`, `remount`, `attach`, `actions`).
+And a whole client-side router in one call — `kerfjs/router`, the "postcard router." A route table, a keyed `outlet()`, and automatic `<a href>` interception; the *core* stays router-free (this is opt-in):
+
+```ts
+import { createRouter } from 'kerfjs/router';
+
+const router = createRouter({
+  routes: [
+    { path: '/',          component: () => <Home /> },
+    { path: '/users/:id', component: ({ id }) => <User id={id} /> },
+    { path: '*',          component: () => <NotFound /> },
+  ],
+});
+
+mount(app, () => <div><nav>{/* <a href> links, auto-intercepted */}</nav>{router.outlet()}</div>);
+```
+
+`router.route` is a signal; `router.outlet()` swaps the page wholesale across routes and morphs in place within one. Deliberately small — no nested layouts, loaders, or guards; compose those with the primitives above.
+
+Each subpath adds nothing to the main barrel until it's imported. See [`docs/8-api-reference.md`](./docs/8-api-reference.md) for the full list (`list`, `router`, `overlay`, `scope`, `async`, `timing`, `remount`, `attach`, `actions`).
 
 ## Install
 

package/ai/manifest.json

@@ -1,5 +1,5 @@
 {
-  "kerfjsVersion": "4.2.0",
+  "kerfjsVersion": "4.3.0",
   "files": [
     {
       "name": "skill",

package/dist/overlay.d.ts

@@ -39,145 +39,6 @@ declare function positionAnchored(el: HTMLElement, anchor: Element, options?: An
  */
 declare function autoReposition(el: HTMLElement, anchor: Element, options?: AnchorPositionOptions): () => void;
 
-/**
- * `toast()` for `kerfjs/overlay` — a non-modal, auto-dismissing notification that
- * stacks in a shared body-level region. Split out of `overlay.ts` (KF-513) since
- * it's a distinct transient-UI concern from the modal dialogs; re-exported from
- * `overlay.ts` so the public `kerfjs/overlay` surface is unchanged. Structural
- * only — kerf ships no CSS; you style the region / toast / animations.
- */
-
-/** Content for a {@link toast}: text, `SafeHtml`, or a render function. */
-type ToastContent = string | SafeHtml | (() => MountResult);
-/** Accent variant for a {@link toast} — mapped to a `${className}--${variant}` class. */
-type ToastVariant = 'info' | 'success' | 'warning';
-/** 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;
-    /**
-     * `'stack'` (default) shows toasts stacked in the region; `'replace'` dismisses
-     * the region's current toast(s) first (collapse-to-latest for a rapid sequence).
-     */
-    mode?: 'stack' | 'replace';
-    /**
-     * How `mode: 'replace'` drops the prior toast(s): `'fade'` (default) runs their
-     * full exit transition (nice for a STACKING region), or `'instant'` removes them
-     * synchronously with no exit — what a single, exactly-centered toast slot wants,
-     * so the outgoing and incoming messages never cross-fade in the same spot.
-     */
-    collapse?: 'fade' | 'instant';
-    /** Accent variant — adds a `${className}--${variant}` class (kerf ships no CSS; you style it). */
-    variant?: ToastVariant;
-    /** Class added on the next animation frame after mount, so a CSS **entrance** transition can run. */
-    enterClass?: string;
-    /**
-     * Class added when dismissing, so CSS owns the **exit**. On dismiss the
-     * `enterClass` (if any) is also REMOVED, so `exitClass` doesn't have to
-     * out-specify it — and a symmetric single-class fade (entrance = add
-     * `enterClass`, exit = remove it) works by setting only `enterClass` +
-     * `exitDuration`. The node is removed `exitDuration` ms later.
-     */
-    exitClass?: string;
-    /** ms to wait before removing the node on dismiss — applies when `exitClass` is set OR when it's > 0 (to let a removed `enterClass` transition out). Default `0`. */
-    exitDuration?: number;
-}
-/** Handle returned by {@link toast}. */
-interface ToastHandle {
-    /** The toast element — inspect it, or run your own entrance/exit transitions. */
-    el: HTMLElement;
-    /**
-     * Dismiss it early. Default runs the `exitClass` transition (removed after
-     * `exitDuration`); pass `{ instant: true }` to remove it **synchronously** with
-     * no exit — for an action button that immediately shows a replacement toast in a
-     * single centered slot (no cross-fade). Idempotent.
-     */
-    dismiss(options?: {
-        instant?: boolean;
-    }): void;
-}
-/**
- * Show a non-modal, auto-dismissing notification. Stacks in a shared body-level
- * region (or your `container`). Returns a {@link ToastHandle} (`{ el, dismiss }`)
- * so you can run entrance/exit transitions, wire an action button, or inspect the
- * node. `mode: 'replace'` collapses a rapid sequence to the latest; `variant`
- * adds an accent class; `enterClass`/`exitClass` let CSS own the animation.
- */
-declare function toast(content: ToastContent, options?: ToastOptions): ToastHandle;
-
-/** 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[];
-    /**
-     * Opt into the browser **top layer** (`docs/19-native-overlay-backing.md`).
-     * When `true` and the engine supports it, a modal overlay (`trap: true`) is
-     * hosted in a `<dialog>` opened with `.showModal()` — real inerting of the rest
-     * of the document + guaranteed stacking above any `z-index` — and a non-modal
-     * one (`trap: false`) uses the Popover API (`[popover]` + `showPopover()`).
-     * Feature-detected; falls back to today's plain `<div>` where unsupported.
-     *
-     * The `render` slot + promise API are unchanged — kerf just hosts your markup
-     * in a `<dialog>` / `[popover]` instead of a `<div>`. Two caveats: native
-     * `<dialog>` / `[popover]` carry **UA default styles** (a `::backdrop`,
-     * centering, border, padding) that kerf does not reset — style the element (and
-     * its `::backdrop`) via `className`; and `container` is effectively a **no-op**
-     * for visual position, since the top layer ignores where the element lives in
-     * the DOM. Default `false`.
-     */
-    native?: boolean;
-}
-/** 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;
 /**
  * Wiring slots passed to a {@link ConfirmOptions.render} — spread `ok` / `cancel`
  * onto your own clickable elements so `confirm()` still resolves them (they are
@@ -384,6 +245,168 @@ interface ChoiceOptions<R> {
  */
 declare function choice<R>(message: string, actions: ReadonlyArray<ChoiceAction<R>>, options?: ChoiceOptions<R>): Promise<R | null>;
 
+/**
+ * `toast()` for `kerfjs/overlay` — a non-modal, auto-dismissing notification that
+ * stacks in a shared body-level region. Split out of `overlay.ts` (KF-513) since
+ * it's a distinct transient-UI concern from the modal dialogs; re-exported from
+ * `overlay.ts` so the public `kerfjs/overlay` surface is unchanged. Structural
+ * only — kerf ships no CSS; you style the region / toast / animations.
+ */
+
+/** Content for a {@link toast}: text, `SafeHtml`, or a render function. */
+type ToastContent = string | SafeHtml | (() => MountResult);
+/** Accent variant for a {@link toast} — mapped to a `${className}--${variant}` class. */
+type ToastVariant = 'info' | 'success' | 'warning';
+/** 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;
+    /**
+     * `'stack'` (default) shows toasts stacked in the region; `'replace'` dismisses
+     * the region's current toast(s) first (collapse-to-latest for a rapid sequence).
+     */
+    mode?: 'stack' | 'replace';
+    /**
+     * How `mode: 'replace'` drops the prior toast(s): `'fade'` (default) runs their
+     * full exit transition (nice for a STACKING region), or `'instant'` removes them
+     * synchronously with no exit — what a single, exactly-centered toast slot wants,
+     * so the outgoing and incoming messages never cross-fade in the same spot.
+     */
+    collapse?: 'fade' | 'instant';
+    /** Accent variant — adds a `${className}--${variant}` class (kerf ships no CSS; you style it). */
+    variant?: ToastVariant;
+    /** Class added on the next animation frame after mount, so a CSS **entrance** transition can run. */
+    enterClass?: string;
+    /**
+     * Class added when dismissing, so CSS owns the **exit**. On dismiss the
+     * `enterClass` (if any) is also REMOVED, so `exitClass` doesn't have to
+     * out-specify it — and a symmetric single-class fade (entrance = add
+     * `enterClass`, exit = remove it) works by setting only `enterClass` +
+     * `exitDuration`. The node is removed `exitDuration` ms later.
+     */
+    exitClass?: string;
+    /** ms to wait before removing the node on dismiss — applies when `exitClass` is set OR when it's > 0 (to let a removed `enterClass` transition out). Default `0`. */
+    exitDuration?: number;
+}
+/** Handle returned by {@link toast}. */
+interface ToastHandle {
+    /** The toast element — inspect it, or run your own entrance/exit transitions. */
+    el: HTMLElement;
+    /**
+     * Dismiss it early. Default runs the `exitClass` transition (removed after
+     * `exitDuration`); pass `{ instant: true }` to remove it **synchronously** with
+     * no exit — for an action button that immediately shows a replacement toast in a
+     * single centered slot (no cross-fade). Idempotent.
+     */
+    dismiss(options?: {
+        instant?: boolean;
+    }): void;
+}
+/**
+ * Show a non-modal, auto-dismissing notification. Stacks in a shared body-level
+ * region (or your `container`). Returns a {@link ToastHandle} (`{ el, dismiss }`)
+ * so you can run entrance/exit transitions, wire an action button, or inspect the
+ * node. `mode: 'replace'` collapses a rapid sequence to the latest; `variant`
+ * adds an accent class; `enterClass`/`exitClass` let CSS own the animation.
+ */
+declare function toast(content: ToastContent, options?: ToastOptions): ToastHandle;
+
+/**
+ * `kerfjs/overlay` — the modal / overlay + dismiss manager.
+ *
+ * Every real kerf app hand-rolls this: `toElement → body.appendChild → mount →
+ * wire dismissal → remove`, plus the fiddly parts (Escape, backdrop / outside
+ * click, focus trap, restoring focus on close). `window.confirm` is a no-op in
+ * Tauri WKWebViews, so a hand-built overlay is mandatory there. This subpath
+ * blesses the pattern as three functions over `mount()` — `overlay()`, and the
+ * `confirm()` / `toast()` conveniences built on it. No per-instance framework
+ * state: each call owns its DOM + listeners in a closure and returns a handle.
+ *
+ *   import { overlay, confirm, toast } from 'kerfjs/overlay';
+ *
+ *   const ok = await confirm('Delete this file?', { danger: true });
+ *   toast('Saved');
+ *   const dialog = overlay(<Settings />, { dismiss: ['escape', 'backdrop'] });
+ *   // …later: dialog.close();  or  await dialog.result;
+ *
+ * Structural only — kerf ships no CSS. The wrapper gets your `className`; style
+ * the backdrop / centering / animation yourself.
+ */
+
+/** 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[];
+    /**
+     * Opt into the browser **top layer** (`docs/19-native-overlay-backing.md`).
+     * When `true` and the engine supports it, a modal overlay (`trap: true`) is
+     * hosted in a `<dialog>` opened with `.showModal()` — real inerting of the rest
+     * of the document + guaranteed stacking above any `z-index` — and a non-modal
+     * one (`trap: false`) uses the Popover API (`[popover]` + `showPopover()`).
+     * Feature-detected; falls back to today's plain `<div>` where unsupported.
+     *
+     * The `render` slot + promise API are unchanged — kerf just hosts your markup
+     * in a `<dialog>` / `[popover]` instead of a `<div>`. Two caveats: native
+     * `<dialog>` / `[popover]` carry **UA default styles** (a `::backdrop`,
+     * centering, border, padding) that kerf does not reset — style the element (and
+     * its `::backdrop`) via `className`; and `container` is effectively a **no-op**
+     * for visual position, since the top layer ignores where the element lives in
+     * the DOM. Default `false`.
+     */
+    native?: boolean;
+}
+/** 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 popover}. */
 interface PopoverOptions {
     /** Where to append the popover wrapper. Default `document.body`. */