sibujs 4.13.0 → 4.14.0

package/dist/ssr-JpGpHnpC.d.ts

@@ -0,0 +1,841 @@
+/** Event handlers for {@link EachBindings}, typed per event name. */
+type EachEventBindings = {
+    [K in keyof HTMLElementEventMap]?: (event: HTMLElementEventMap[K], el: HTMLElement) => void;
+};
+/**
+ * What {@link EnhanceContext.each} attaches to one element.
+ *
+ * Every field maps one-to-one onto an existing `ctx.*` helper and is committed
+ * through it — this is a shorthand for calls you could write by hand, not a
+ * template language and not a second binding engine. There is no expression
+ * parsing, no string interpolation and no `eval`: every value is a plain
+ * function you wrote, so it stays CSP-safe and fully type-checked.
+ *
+ * Anything not covered here (two-way `model()`, listener options, a nested
+ * `enhance`) is written imperatively in the same callback — it receives the
+ * element, so `ctx.model(el, …)` beside a returned descriptor is normal.
+ */
+interface EachBindings {
+    /** Reactive `textContent` — same as `ctx.text(el, value)`. */
+    text?: () => unknown;
+    /** Reactive attributes by name — same as `ctx.attr(el, name, value)`. */
+    attr?: Record<string, () => unknown>;
+    /** Reactive class toggles by class name — same as `ctx.classed(el, name, on)`. */
+    class?: Record<string, () => boolean>;
+    /** Reactive visibility — same as `ctx.show(el, when)`. */
+    show?: () => boolean;
+    /** Event listeners by event name — same as `ctx.on(el, event, handler)`. */
+    on?: EachEventBindings;
+    /** Per-element teardown, run with the rest of the enhancement's cleanups. */
+    cleanup?: () => void;
+}
+/**
+ * Helpers handed to an `enhance` setup. Every binding is fine-grained (its own
+ * effect) and auto-disposed when the root element (or the returned dispose) is
+ * torn down.
+ *
+ * Target resolution for every helper:
+ *   - `"@name"`  → a descendant marked `data-ref="name"` (the ergonomic form).
+ *   - any other string → a raw CSS selector, queried within the root.
+ *   - an `Element` → used as-is.
+ *   - `null` / omitted (where allowed) → the root element itself.
+ */
+interface EnhanceContext {
+    /** The enhanced root element (the server-rendered node). */
+    root: HTMLElement;
+    /** First descendant matching a `@ref`/selector (or the root for `null`). */
+    ref<T extends Element = HTMLElement>(target: string | null): T | null;
+    /** All descendants matching a `@ref`/selector. */
+    refs<T extends Element = HTMLElement>(target: string): T[];
+    /** Attach an auto-removed event listener to a target (root if `null`). */
+    on<K extends keyof HTMLElementEventMap>(target: string | Element | null, event: K, handler: (event: HTMLElementEventMap[K], el: HTMLElement) => void, options?: AddEventListenerOptions): void;
+    /** Reactively drive `textContent` of an existing node. */
+    text(target: string | Element | null, value: () => unknown): void;
+    /** Reactively drive an attribute; a `null`/`false`/`undefined` value removes it. */
+    attr(target: string | Element | null, name: string, value: () => unknown): void;
+    /** Reactively toggle a class on a node. */
+    classed(target: string | Element | null, name: string, on: () => boolean): void;
+    /** Reactively toggle visibility (sets `display:none` when `false`). */
+    show(target: string | Element | null, when: () => boolean): void;
+    /** Two-way bind a form control to a `[get, set]` signal tuple. */
+    model<T>(target: string | Element, state: readonly [() => T, (value: T) => void], options?: {
+        event?: string;
+    }): void;
+    /**
+     * Bind a set of elements the server already rendered — a board, a table, a
+     * keyboard, a timeline, a legend — one descriptor at a time.
+     *
+     * The callback receives each element and its index and returns what to
+     * attach; every field is committed through the matching `ctx.*` helper, so
+     * ownership, disposal, write elision, attribute sanitization and error
+     * routing are byte-for-byte the same as writing the calls out by hand. No
+     * element is created, replaced, moved or re-parented — node identity is
+     * preserved, which is the entire point of enhancing existing markup.
+     *
+     * ```ts
+     * ctx.each<HTMLButtonElement>("@square", (el) => {
+     *   const square = el.dataset.square as Square;
+     *   return {
+     *     text: () => pieceAt(square),
+     *     class: { selected: () => selected() === square },
+     *     attr: { "aria-label": () => describe(square) },
+     *     on: { click: () => choose(square) },
+     *   };
+     * });
+     * ```
+     *
+     * The callback may also return nothing and wire the element imperatively —
+     * `ctx.model(el, …)`, `ctx.on(el, "click", h, { passive: true })` — for the
+     * cases the descriptor deliberately does not cover.
+     *
+     * Zero matches is a silent no-op. Calling `each` twice over the same
+     * elements creates two independent sets of bindings, exactly as calling
+     * `ctx.text()` twice on one node does; the helper is sugar over those calls
+     * and does not track what a previous call attached.
+     *
+     * @param target A `@ref`/CSS selector resolved with {@link EnhanceContext.refs},
+     *   or any iterable of elements (an array, a `NodeList`, an `HTMLCollection`).
+     * @param describe Called once per element, in document order.
+     */
+    each<T extends Element = HTMLElement>(target: string | Iterable<Element>, describe: (element: T, index: number) => EachBindings | void): void;
+    /** Register arbitrary teardown to run on disposal. */
+    cleanup(fn: () => void): void;
+}
+/** A setup function for `enhance` — wire reactivity, optionally return cleanup.
+ *  The `void | (() => void)` shape mirrors `useEffect`'s "return a teardown, or
+ *  nothing". */
+type EnhanceSetup = (ctx: EnhanceContext) => void | (() => void);
+/**
+ * Attach reactivity to an existing element (typically server-rendered) without
+ * replacing it. Returns a dispose function; disposal is also wired to the
+ * element, so removing its subtree cleans everything up.
+ *
+ * **Setup is a transaction.** If `setup` throws, every binding, listener and
+ * cleanup it registered through the {@link EnhanceContext} is torn down and the
+ * original error is rethrown unchanged — the element is left exactly as
+ * unenhanced as it started, so a retry is legal. The rollback covers
+ * framework-owned resources only (`ctx.on`, `ctx.text`, `ctx.attr`,
+ * `ctx.classed`, `ctx.show`, `ctx.model`, `ctx.cleanup`, and a cleanup returned
+ * from setup); work the setup performed outside those helpers — `innerHTML`
+ * writes, network calls, global mutation — cannot be reversed generically, so
+ * register its undo with `ctx.cleanup()` as you go.
+ *
+ * **Ownership.** A successfully enhanced root is marked
+ * `data-sibu-enhanced="true"`; disposal removes it. The marker tracks *current*
+ * ownership rather than history, so a **disposed root can be enhanced again**,
+ * while enhancing a root that is still active is refused (dev-warns) to prevent
+ * two competing sets of bindings. See `docs/architecture/enhancement-lifecycle.md`.
+ *
+ * @param target An `Element` or a CSS selector resolved against `document`
+ *   (the first match is used; see {@link enhanceAll} for many).
+ * @param setup  Wires reactivity via the {@link EnhanceContext}.
+ * @throws Whatever `setup` throws, after rolling its resources back.
+ *
+ * @example
+ * ```ts
+ * // server HTML: <div data-counter><b data-ref="n">0</b><button data-ref="inc">+1</button></div>
+ * const [n, setN] = signal(0);
+ * enhance("[data-counter]", (ctx) => {
+ *   ctx.text("@n", () => n());
+ *   ctx.on("@inc", "click", () => setN((v) => v + 1));
+ * });
+ * ```
+ */
+declare function enhance(target: Element | string, setup: EnhanceSetup): () => void;
+/**
+ * Enhance every element matching a selector. Returns a single dispose that
+ * tears down all of them.
+ *
+ * The whole collection is one transaction: if any element's setup throws, the
+ * elements already enhanced are rolled back (newest first, mirroring stack
+ * unwinding) and the original error is rethrown. A caller that never received
+ * the aggregate disposer is therefore never left holding live enhancements it
+ * has no way to release. A teardown that fails during that rollback is reported
+ * and skipped — it neither aborts the remaining rollback nor replaces the
+ * original setup error.
+ *
+ * The returned disposer is idempotent, and the collection may be enhanced again
+ * afterwards (see {@link enhance} on marker lifetime).
+ *
+ * @throws Whatever the failing element's setup threw, after rolling back.
+ */
+declare function enhanceAll(selector: string, setup: EnhanceSetup): () => void;
+
+/** When an island activates. Declared per-element via `data-sibu-load`. */
+type IslandStrategy = "load" | "idle" | "visible" | "interaction" | "media";
+/** A lazy code loader: resolves to an island setup (or a module whose `default`
+ *  is one). Only fetched when the island activates. Wrap with {@link lazyIsland}. */
+type IslandLoader = () => Promise<EnhanceSetup | {
+    default: EnhanceSetup;
+}>;
+/**
+ * A loader that has been through {@link lazyIsland}.
+ *
+ * Exported for callers that want to be explicit about having wrapped one. It is
+ * NOT required by {@link IslandRegistration}, and that is deliberate.
+ *
+ * Requiring the brand would catch a forgotten `lazyIsland(...)` at compile time,
+ * which is where a mistake is cheapest to find — but it also rejects code that
+ * compiles today, and this package's contract is that the existing public API
+ * keeps working, widening rather than replacing, with a codemod for anything
+ * that cannot be widened. There is no codemod infrastructure here to ship one
+ * through, so the narrowing is not taken: the mistake is caught at mount time
+ * instead, by the thenable guard in `enhance()`, which throws immediately with
+ * an actionable message and leaves the element unenhanced. Loud and instant at
+ * runtime beats a type error that arrives with a breaking change attached.
+ *
+ * The brand is a phantom STRING-keyed property, never a `unique symbol`. A
+ * `unique symbol` has nominal identity per declaration, so two copies of this
+ * package's `.d.ts` in one dependency tree would produce two incompatible
+ * types. That is not hypothetical: the registry is deliberately shared through
+ * `Symbol.for` precisely because duplicate copies are expected. The property
+ * exists only in the type — the runtime marker is the global symbol below.
+ */
+type LazyIslandLoader = IslandLoader & {
+    readonly __sibujsLazyIsland: true;
+};
+/**
+ * Either an inline setup, or a loader.
+ *
+ * Unchanged from 4.2: an unbranded `IslandLoader` is still accepted, so no
+ * previously-compiling code breaks. Wrapping with {@link lazyIsland} is what
+ * makes it *work* — see {@link LazyIslandLoader} for why this is not narrowed.
+ */
+type IslandRegistration = EnhanceSetup | IslandLoader | LazyIslandLoader;
+/**
+ * Mark a loader as lazy island code — its module is fetched only when the island
+ * activates, so a page ships ~0 JS for islands that never trigger.
+ *
+ * @example
+ * ```ts
+ * registerIsland("chart", lazyIsland(() => import("./islands/chart.js")));
+ * ```
+ */
+declare function lazyIsland(loader: IslandLoader): LazyIslandLoader;
+/**
+ * Register an island by name. The setup is applied via `enhance()` when a
+ * matching `[data-sibu-island="name"]` element activates.
+ *
+ * @example
+ * ```ts
+ * registerIsland("counter", (ctx) => {
+ *   const [n, setN] = signal(0);
+ *   ctx.text("@n", () => n());
+ *   ctx.on("@inc", "click", () => setN((v) => v + 1));
+ * });
+ * ```
+ */
+declare function registerIsland(name: string, setup: IslandRegistration): void;
+/** Remove a registration (mainly for tests / HMR). */
+declare function unregisterIsland(name: string): void;
+interface MountIslandsOptions {
+    /** IntersectionObserver options for the `visible` strategy. */
+    rootMargin?: string;
+    threshold?: number | number[];
+}
+/**
+ * Scan a root for `[data-sibu-island]` elements and activate each according to
+ * its `data-sibu-load` strategy (default `load`). Returns a cleanup function
+ * that cancels pending schedulers and disposes every mounted island.
+ *
+ * Strategies (`data-sibu-load`):
+ *   - `load`        — activate immediately (next microtask).
+ *   - `idle`        — `requestIdleCallback` (falls back to a timeout).
+ *   - `visible`     — when the element scrolls into view (IntersectionObserver).
+ *   - `interaction` — on first pointer/focus/key/touch interaction.
+ *   - `media`       — when `data-sibu-media` (a media query) matches.
+ *
+ * **Error isolation is lifecycle isolation.** Each island is one `enhance()`
+ * transaction, so an island whose setup throws is reported and leaves zero live
+ * bindings and zero live listeners; siblings activate normally, and the failed
+ * island can be mounted again once its setup is fixed.
+ *
+ * **Remounting is supported.** Cleanup disposes each island and releases its
+ * `data-sibu-enhanced` marker, so the same server markup can be mounted again
+ * with a fresh generation. Mounting twice *without* cleanup is also safe:
+ * islands that currently own an enhancement are skipped, never double-wired.
+ *
+ * Activation can never outlive its owner. Cleanup landing before a lazy chunk
+ * resolves prevents activation entirely, and cleanup landing *during* a setup
+ * disposes the island rather than stranding it — DISPOSED never becomes ACTIVE.
+ * `data-sibu-hydrated` is hydration provenance rather than ownership, and is
+ * therefore not cleared on disposal; see
+ * `docs/architecture/enhancement-lifecycle.md`.
+ */
+declare function mountIslands(root?: ParentNode | null, options?: MountIslandsOptions): () => void;
+
+/** The attribute carrying an island's serialized props. */
+declare const ISLAND_PROPS_ATTR = "data-sibu-props";
+/** Options of a server-rendered component island. */
+interface ComponentIslandOptions {
+    /** When the browser activates it (`data-sibu-load`). Default `"load"`. */
+    load?: IslandStrategy;
+    /** Media query for `load: "media"`. */
+    media?: string;
+}
+/**
+ * Render `Component(props)` as an island: on the server the markup carries the
+ * island marker, its props (JSON) and adoption ids; in the browser, outside an
+ * island runtime, the component simply renders.
+ *
+ * @param name Island name, matched by `registerIsland(name, islandComponent(Component))`.
+ * @param component The island's component.
+ * @param props JSON-serializable props, sent to the browser in the markup.
+ * @param options Load strategy.
+ * @returns The island's wrapper element (`display: contents`).
+ */
+declare function componentIsland<P>(name: string, component: (props: P) => Node, props: P, options?: ComponentIslandOptions): HTMLElement;
+/**
+ * The browser side of a server-rendered component island: an island setup
+ * (for `registerIsland` / `lazyIsland`) that reads the props from the markup
+ * and adopts the island's server nodes with `Component(props)`.
+ *
+ * @param component The same component the server rendered.
+ * @param validate Optional guard for the props read from the markup (they come
+ * from the page, so treat them as input).
+ * @returns An island setup.
+ *
+ * @example
+ * ```ts
+ * registerIsland("cart", islandComponent(Cart));
+ * registerIsland("reviews", lazyIsland(() => import("./Reviews").then((m) => islandComponent(m.Reviews))));
+ * mountIslands();
+ * ```
+ */
+declare function islandComponent<P>(component: (props: P) => Node, validate?: (props: unknown) => props is P): EnhanceSetup;
+
+/** Attribute carrying an element's creation-scope id in adopt-marked server output. */
+declare const ADOPT_ID_ATTR = "data-sibu-h";
+/** One divergence between the server markup and the client tree. */
+interface AdoptMismatch {
+    kind: "tag" | "missing" | "extra" | "text";
+    /** Where: the DOM path of the server node (or of the parent the client node went into). */
+    path: string;
+    /** The creation-scope id involved, when there is one. */
+    id: string | null;
+    serverValue: string;
+    clientValue: string;
+    /** What usually causes this divergence. */
+    cause: string;
+    message: string;
+}
+/** Options of an adopting `hydrate()`. */
+interface AdoptOptions {
+    /** Called for every divergence instead of the development warning. */
+    onMismatch?: (report: AdoptMismatch) => void;
+    /**
+     * How long to wait for lazy chunks and route loads before releasing the
+     * server markup nothing claimed. Default 10 000 ms.
+     */
+    timeout?: number;
+}
+/** What an adopting hydration did. */
+interface AdoptResult {
+    /** Server elements reused as client elements. */
+    adopted: number;
+    /** Elements the client had to create (0 on matching markup). */
+    created: number;
+    /** Server nodes removed because nothing claimed them. */
+    removed: number;
+    /** Every divergence found. */
+    mismatches: AdoptMismatch[];
+    /** True when the root itself did not match and the whole tree was replaced. */
+    replacedRoot: boolean;
+}
+
+/** Default time a server render waits for pending work before serializing anyway. */
+declare const DEFAULT_SETTLE_TIMEOUT = 5000;
+/** Default cap on the transferred state, in UTF-8 bytes (the `serializeState` default). */
+declare const DEFAULT_TRANSFER_MAX_BYTES: number;
+/** Outcome of {@link settled}. */
+interface SettleResult {
+    /** True when the timeout elapsed with work still pending. */
+    timedOut: boolean;
+    /** Labels of the work still pending at the timeout (`query:/api/catalog`). Empty when settled. */
+    pending: string[];
+}
+/** Options of {@link settled}. */
+interface SettleOptions {
+    /** Milliseconds to wait for pending work. Default 5000. */
+    timeout?: number;
+}
+/**
+ * Wait until the current request's render has settled: every deferred
+ * directive commit has run and every registered async unit (lazy chunks,
+ * `query()` / `resource()` fetches, router navigation and route loads,
+ * `prerenderWait()` promises) has settled — or until `timeout`.
+ *
+ * Must be awaited inside the request's scope (`runInSSRContext`); outside one
+ * there is no registry, and it only drains the microtask queue.
+ *
+ * @param _root The tree being rendered. Accepted for symmetry with test
+ * helpers; settling is decided by the request's registry, not by the DOM.
+ * @param options `timeout` in milliseconds (default 5000).
+ * @returns Whether it timed out, and what was still pending.
+ */
+declare function settled(_root?: Node | null, options?: SettleOptions): Promise<SettleResult>;
+/** Diagnostics of one async server render. */
+interface RenderDiagnostics {
+    /** True when the settle timeout elapsed; the output shows fallbacks for what was pending. */
+    timedOut: boolean;
+    /** Work still pending at the timeout. */
+    pending: string[];
+    /** Browser-only APIs read during the render (see `installServerDom`), with the reading site. */
+    browserApis: string[];
+    /** Size of the transferred state in UTF-8 bytes (0 when nothing was transferred). */
+    stateBytes: number;
+    /** The largest transferred entries, biggest first: `q:/api/catalog` → bytes. */
+    largestState: Array<{
+        key: string;
+        bytes: number;
+    }>;
+    /** Entries left out of the transferred state because it exceeded `maxStateBytes`. */
+    droppedState: string[];
+    /** Wall-clock render time in milliseconds. */
+    durationMs: number;
+}
+/** Result of {@link renderToStringAsync} and {@link renderToDocumentAsync}. */
+interface RenderResult {
+    /** The rendered markup: the body content, or the whole document for `renderToDocumentAsync`. */
+    html: string;
+    /** Head tags collected during the render (`<title>`, meta, link, JSON-LD), escaped. */
+    head: string;
+    /** The transfer `<script>` restoring server data in the browser, or `""`. */
+    state: string;
+    /** The transferred data itself (what `state` assigns), or `null`. */
+    stateData: Record<string, unknown> | null;
+    /** HTTP status: 200 unless a router render decided otherwise (see `renderRoute`). */
+    status: number;
+    /** Diagnostics: pending work at the timeout, browser-API reads, state size. */
+    diagnostics: RenderDiagnostics;
+}
+/** Options of {@link renderToStringAsync}. */
+interface AsyncRenderOptions {
+    /** Milliseconds to wait for pending work before serializing anyway. Default 5000. */
+    timeout?: number;
+    /** Embed the data the render fetched so the browser does not fetch it again. Default `true`. */
+    transfer?: boolean;
+    /** CSP nonce for the transfer script. */
+    nonce?: string;
+    /** Cap on the transferred state in bytes. Larger entries are dropped (largest first). Default 1 MB. */
+    maxStateBytes?: number;
+    /**
+     * Where the `data-sibu-ssr="true"` provenance marker goes. Default `"root"`:
+     * top-level elements only (`renderToString` stamps every element, ~20 bytes
+     * each, and nothing reads it beneath the root).
+     */
+    marker?: "all" | "root" | "none";
+    /**
+     * `"adopt"` marks the output for `hydrate(App, root, { strategy: "adopt" })`:
+     * every element built by a tag factory or `html` carries its creation id
+     * (`data-sibu-h`), so the browser binds to these nodes instead of replacing
+     * them. Default: no markers (the output `hydrate()`'s replace strategy uses).
+     */
+    hydration?: "adopt" | "replace";
+    /**
+     * Log a one-block summary of the render in development (time, settle
+     * outcome, what was pending, browser-API reads, transferred state and its
+     * largest entries). A string labels it (`renderRoute` passes the URL).
+     */
+    log?: boolean | string;
+}
+/**
+ * The diagnostics of one server render as readable text — what `log: true`
+ * prints, for a custom logger or a test failure message.
+ *
+ * @param d The render's `diagnostics`.
+ * @param label What was rendered (a URL).
+ * @returns A multi-line summary.
+ */
+declare function formatRenderDiagnostics(d: RenderDiagnostics, label?: string): string;
+/**
+ * Describe where a node sits, for an error message: `main > section.grid > div.card`.
+ * The runtime has no component stack, so the DOM position is the component path.
+ */
+declare function describeNodePath(node: unknown): string;
+/**
+ * The error an async server render rejects with for an error no
+ * `ErrorBoundary` claimed: the original as `cause`, the component name and DOM
+ * path of the failing node in the message.
+ * @internal
+ */
+declare function renderFailure(entry: {
+    error: unknown;
+    context: {
+        name?: string;
+        node?: unknown;
+    };
+}): Error;
+/**
+ * Render a tree to HTML once it has settled — one `await`, no manual
+ * microtask waits.
+ *
+ * Pass a FUNCTION so the tree is built inside the request scope: its queries
+ * then use the request's cache and its work is awaited. Called outside
+ * `runInSSRContext`, it opens a scope of its own.
+ *
+ * Rejects when an error escapes the tree (no `ErrorBoundary` claimed it), with
+ * the DOM path of the failing node in the message. A settle timeout does not
+ * reject: what is ready is serialized, `Suspense` and `lazy()` keep their
+ * fallbacks, and `diagnostics.pending` names what was still running.
+ *
+ * @param input The tree, or a function building it.
+ * @param options Timeout, state transfer, nonce, state cap.
+ * @returns `{ html, head, state, stateData, status, diagnostics }`.
+ *
+ * @example
+ * ```ts
+ * const { html, head, state } = await renderToStringAsync(() => App());
+ * ```
+ */
+declare function renderToStringAsync(input: Node | (() => Node), options?: AsyncRenderOptions): Promise<RenderResult>;
+/**
+ * {@link renderToStringAsync}, wrapped in the document `renderToDocument`
+ * produces. The collected head tags go into `<head>` and the transfer script
+ * at the end of `<body>`, before `options.scripts`.
+ *
+ * @param input The tree, or a function building it.
+ * @param options Document options plus the async render options.
+ * @returns The render result; `html` is the whole document.
+ */
+declare function renderToDocumentAsync(input: Node | (() => Node), options?: DocumentOptions & AsyncRenderOptions): Promise<RenderResult>;
+
+/** Options of the streaming `renderToReadableStream(() => App(), options)`. */
+interface StreamRenderOptions extends AsyncRenderOptions {
+    /**
+     * Wrap the stream in `renderToDocument`'s document (head tags flushed with
+     * the shell, the transfer script and `scripts` at the end). Default `{}`;
+     * `false` streams the body markup only.
+     */
+    document?: DocumentOptions | false;
+    /** Total time for every boundary (default 10 000 ms); a boundary still pending keeps its fallback. */
+    timeout?: number;
+    /** Time for the shell itself (default 5000 ms); past it the shell flushes with what is ready. */
+    shellTimeout?: number;
+}
+
+/**
+ * Serialize an element's open tag — `<tag attr="…" …` without the closing `>`
+ * — or return `null` when the element must not be emitted at all.
+ *
+ * THE single attribute serializer for server-emitted element trees, shared by
+ * `renderToString` and `renderToStream`:
+ *
+ *   - names are validated, `on*` and `srcdoc` dropped, policy sinks sanitized
+ *     through the same `sanitizeAttributeString` the client writers use;
+ *   - a `<meta>` whose EMITTED attributes form a refresh directive the shared
+ *     policy forbids is dropped whole, exactly as `renderToDocument`'s `meta`
+ *     option and `Head()` drop such an entry. DOM built through the
+ *     framework's writers can never reach this state; DOM built any other way
+ *     (application code, a third-party library) could, and rendering target is
+ *     not a security boundary.
+ *   - on a `foreign` (SVG / MathML) element, names keep their case and their
+ *     namespace prefix, and an SVG animation may not target a URL or handler
+ *     attribute — its `attributeName` is omitted, as the client writers omit it.
+ *   - an `<iframe>` built by `embed()` is re-judged against what `embed()`
+ *     wrote (`embedSerializedAttribute`): only the attributes it writes (plus
+ *     `id`, `class`, `style`, `width`, `height`, `data-*`, `aria-*`) are
+ *     served, `src` must match the allowlist the frame was built under,
+ *     `sandbox` / `allow` can only be narrower than what it wrote,
+ *     `allowfullscreen` follows the served `allow`, and a frame without a
+ *     non-blank `title` is not served — so a frame changed behind the
+ *     framework's back is never served wider than `embed()` built it.
+ */
+/**
+ * How a render path marks its output.
+ * @internal
+ */
+interface SerializeOptions {
+    /**
+     * Where `data-sibu-ssr="true"` goes: on every element (`renderToString`'s
+     * historical output), on top-level elements only, or nowhere.
+     */
+    marker: "all" | "root" | "none";
+    /** Adoption ids (`data-sibu-h`) of elements built under an adopt render. */
+    ids: WeakMap<Element, string> | null;
+}
+/**
+ * Converts an element tree to an HTML string for server-side rendering.
+ * HTML, SVG and MathML elements are serialized; SVG and MathML keep the case
+ * of their tag and attribute names and their `xlink:` / `xml:` prefixes.
+ *
+ * Security: attribute names are validated, `on*` handlers are dropped,
+ * URL-bearing attributes are routed through `sanitizeUrl`, attribute
+ * values are escaped against both `"` and `'`, and an SVG animation may not
+ * target a URL or handler attribute. `<script>` and `<style>` tags are
+ * stripped from the serialized output.
+ */
+declare function renderToString(element: HTMLElement | DocumentFragment | Node): string;
+/**
+ * `renderToString` with explicit marker options — the async renderers' entry.
+ * @internal
+ */
+declare function renderToStringWith(element: Node, opts: SerializeOptions): string;
+interface HydrateOptions {
+    /**
+     * Enable dev-mode hydration diagnostics. When true, the walker
+     * compares the server-rendered tree against the client tree and
+     * logs the first tag mismatch, attribute difference, or child count
+     * mismatch to the console. Disabled by default.
+     */
+    diagnostics?: boolean;
+    /**
+     * Called for each detected mismatch instead of the default console
+     * warning. Useful for routing diagnostics to a telemetry system.
+     */
+    onMismatch?: (report: HydrationMismatch) => void;
+}
+interface HydrationMismatch {
+    kind: "tag" | "attribute" | "child-count" | "text";
+    path: string;
+    serverValue: string;
+    clientValue: string;
+    message: string;
+}
+/**
+ * Activates a server-rendered SibuJS application by building the live client
+ * tree and **replacing** the inert server-rendered subtree with it.
+ *
+ * SibuJS uses replacement hydration rather than DOM adoption: the server markup
+ * is discarded, not attached to. It is not the case that listeners and bindings
+ * are wired onto the existing server nodes — reactive bindings belong to the
+ * nodes `component()` produced, and adopting server nodes would leave the
+ * visible DOM permanently frozen.
+ *
+ * Consequences worth knowing before deploying SSR:
+ *
+ *  - DOM node identity is not preserved.
+ *  - Pre-hydration user input, checkbox state, and focus are discarded.
+ *  - Conversely, partial-adoption mismatch bugs are avoided by this design —
+ *    the client tree is always authoritative.
+ *
+ * Re-hydrating the same container disposes the previous client tree first.
+ *
+ * When `options.diagnostics` is true, the walker reports the first
+ * server/client mismatch it finds. This is a dev-mode tool — pass
+ * `diagnostics: false` (or omit it) in production.
+ *
+ * @see docs/architecture/hydration.md
+ */
+declare function hydrate(component: () => Node, container: Element, options: AdoptOptions & {
+    strategy: "adopt";
+}): Promise<AdoptResult>;
+declare function hydrate(component: () => HTMLElement, container: HTMLElement, options?: HydrateOptions & {
+    strategy?: "replace";
+}): void;
+/**
+ * Branded type for raw HTML that has been explicitly marked as trusted.
+ * Use `trustHTML()` to create a value of this type. This prevents
+ * accidental injection of unsanitized user input into `headExtra`.
+ */
+type TrustedHTML = string & {
+    readonly __brand: "TrustedHTML";
+};
+/**
+ * Mark an HTML string as trusted for use in contexts that accept raw HTML
+ * (e.g. `renderToDocument({ headExtra })`). Only call this on
+ * developer-controlled strings — never on user input.
+ *
+ * @example
+ * ```ts
+ * const extra = trustHTML('<link rel="preconnect" href="https://fonts.googleapis.com">');
+ * renderToDocument(App, { headExtra: extra });
+ * ```
+ */
+declare function trustHTML(html: string): TrustedHTML;
+/**
+ * Should this meta entry be dropped entirely?
+ *
+ * Delegates to the SHARED meta-refresh policy. This used to be a private copy
+ * of four `includes()` checks that happened to match the client's private copy
+ * — two implementations of one rule, so a fix to either would silently diverge
+ * from the other. The exported name is kept for back-compat; the policy is no
+ * longer local.
+ *
+ * Returns true for a forbidden refresh directive AND for an entry carrying
+ * duplicate case-insensitive attribute names, since there the value validated
+ * would not be the value the browser ends up honouring.
+ */
+declare function isDangerousMetaRefresh(metaProps: Record<string, string>): boolean;
+/**
+ * Renders a component to a full HTML document string.
+ *
+ * `headExtra` requires a `TrustedHTML` value created via `trustHTML()`.
+ * This prevents accidental injection of unsanitized user input.
+ *
+ * Security: meta/link/bodyAttrs keys are validated against
+ * `SAFE_ATTR_NAME` (rejecting crafted keys that would break out of the
+ * attribute context). URL attributes in meta/link/scripts/bodyAttrs pass
+ * through `sanitizeUrl`. The page `title` is HTML-escaped.
+ */
+/** Document options shared by `renderToDocument` and `renderToDocumentAsync`. */
+interface DocumentOptions {
+    title?: string;
+    meta?: Record<string, string>[];
+    links?: Record<string, string>[];
+    /**
+     * External script URLs appended to `<body>`. Each passes the scheme
+     * allowlist; an allowed URL is still code that runs with the page's
+     * authority, so this option is an explicit trust decision — first-party
+     * or pinned URLs only, never request-derived values.
+     */
+    scripts?: string[];
+    bodyAttrs?: Record<string, string>;
+    /**
+     * Raw HTML injected into `<head>`. Must be wrapped in `trustHTML()`
+     * to confirm the content is developer-controlled.
+     */
+    headExtra?: TrustedHTML;
+}
+declare function renderToDocument(component: () => HTMLElement, options?: DocumentOptions): string;
+/**
+ * The document `renderToDocument` emits, around already-rendered `content`.
+ * `head` and `bodyEnd` are framework-generated markup (collected head tags,
+ * the transfer script), escaped by their producers.
+ * @internal
+ */
+declare function assembleDocument(content: string, options: DocumentOptions, head: string, bodyEnd: string): string;
+/**
+ * Renders a component tree to an async iterable of HTML chunks.
+ * Enables progressive server-side rendering — the consumer can write
+ * each chunk to a response stream as it becomes available.
+ *
+ * Same security posture as `renderToString`.
+ */
+declare function renderToStream(element: HTMLElement | DocumentFragment | Node): AsyncGenerator<string>;
+/**
+ * Collects the full output of renderToStream into a string.
+ */
+declare function collectStream(stream: AsyncGenerator<string> | AsyncIterable<string>): Promise<string>;
+/**
+ * Renders a component tree to a Web `ReadableStream<string>`.
+ *
+ * Uses pull-based backpressure — chunks are produced on demand.
+ *
+ * **Environment.** Supported on SibuJS's declared Node runtime (`>=22.3.0`) and
+ * on any other environment providing both the Web Streams API *and* a DOM
+ * implementation. Streaming SSR requires the same server DOM as every other
+ * SibuJS SSR API: this function takes real `Node` objects and walks them, so a
+ * DOM-less runtime cannot produce the input, let alone render it. Do not read
+ * "returns a Web stream" as "runs anywhere Web streams exist".
+ *
+ * **Semantics.** Suspense boundaries encountered during the walk are resolved
+ * as a batch before the affected chunk is emitted — the shell is not flushed
+ * ahead of individually-completing boundaries. See
+ * `docs/architecture/ssr.md` for the precise streaming and failure semantics.
+ */
+declare function renderToReadableStream(element: HTMLElement | DocumentFragment | Node): ReadableStream<string>;
+/**
+ * Stream a page built by `input` with out-of-order `Suspense`: the head and the
+ * shell (with each boundary's fallback) flush as soon as everything outside the
+ * boundaries has settled, then each boundary streams when it is ready, with a
+ * CSP-nonce-aware swap script, then the transferred state and the scripts.
+ * Backpressure: the next chunk is produced once the previous one was read.
+ * See `ssrStream.ts`.
+ */
+declare function renderToReadableStream(input: () => Node, options?: StreamRenderOptions): ReadableStream<string>;
+declare function island(id: string, component: () => HTMLElement): HTMLElement;
+/**
+ * A component island rendered on the server: the markup carries the island
+ * marker, its serialized `props` and adoption ids, and the browser adopts just
+ * this subtree with `registerIsland(name, islandComponent(Component))` +
+ * `mountIslands()`. See `componentIsland`.
+ */
+declare function island<P>(name: string, component: (props: P) => Node, props: P, options?: ComponentIslandOptions): HTMLElement;
+declare function hydrateIslands(container: HTMLElement, islands: Record<string, () => HTMLElement>): void;
+/**
+ * Progressively hydrate islands only when they enter the viewport.
+ * Uses IntersectionObserver to defer hydration of off-screen islands,
+ * reducing initial JavaScript execution cost.
+ *
+ * Returns a cleanup function that disconnects all observers.
+ */
+declare function hydrateProgressively(container: HTMLElement, islands: Record<string, () => HTMLElement>, options?: IntersectionObserverInit): () => void;
+/**
+ * Reset SSR state between requests. Call at the start of each SSR render
+ * to prevent ID drift in long-lived server processes.
+ *
+ * When running inside `runInSSRContext`, each request already owns its
+ * own counter via AsyncLocalStorage — this hook only touches the
+ * module-global fallback used outside that context.
+ */
+declare function resetSSRState(): void;
+/**
+ * Create a suspense boundary for SSR streaming.
+ * Renders fallback HTML inline and returns a promise for the resolved content.
+ *
+ * The returned element contains the fallback UI with a `data-sibu-suspense-id`
+ * marker. The promise resolves to `{ id, html }` once async content is ready.
+ *
+ * The promise never rejects. Any failure to produce the content HTML — the
+ * content factory throwing synchronously, its promise rejecting, the timeout,
+ * or rendering the resolved element throwing — resolves it with the fallback
+ * HTML, so the stream still produces a deterministic swap payload.
+ */
+declare function ssrSuspense(props: {
+    fallback: () => HTMLElement;
+    content: () => Promise<HTMLElement>;
+    /** Milliseconds before the content promise is rejected. Defaults to 30000. */
+    timeoutMs?: number;
+}): {
+    element: HTMLElement;
+    promise: Promise<{
+        id: string;
+        html: string;
+    }>;
+};
+/**
+ * Generate an inline script that swaps a suspense fallback with resolved content.
+ *
+ * Security: the `id` is validated against a strict allowlist. Values that
+ * do not match throw, so an attacker-controlled id cannot inject context
+ * breakers into the selector or the JS string. `ssrSuspense()`'s internal
+ * generator always produces allowlist-safe ids.
+ */
+declare function suspenseSwapScript(id: string, nonce?: string): string;
+/**
+ * Renders a component tree with suspense boundaries as a stream.
+ * Yields the main tree HTML first (including fallback content for suspended
+ * boundaries), then flushes resolved content with inline swap scripts.
+ *
+ * Supports an optional `nonce` that is propagated to the resolved-content
+ * swap scripts so the stream works with strict CSP.
+ */
+declare function renderToSuspenseStream(element: HTMLElement | DocumentFragment | Node, pendingBoundaries?: Promise<{
+    id: string;
+    html: string;
+}>[], options?: {
+    nonce?: string;
+}): AsyncGenerator<string>;
+/**
+ * Escape a JSON string for safe embedding inside a `<script>` tag. This
+ * goes beyond the usual `</script>` concern:
+ *
+ *  - `<`, `>`, `&` are unicode-escaped so nothing inside a string literal
+ *    can close the script tag or start a new one.
+ *  - `U+2028` (LINE SEPARATOR) and `U+2029` (PARAGRAPH SEPARATOR) are
+ *    unicode-escaped. Before ES2019 these were illegal inside a JS string
+ *    literal, so including them verbatim would cause a SyntaxError on
+ *    older engines and could break out of string context.
+ */
+declare function escapeScriptJson(json: string): string;
+declare function serializeState(state: Record<string, unknown>, nonce?: string, options?: {
+    maxBytes?: number;
+    /**
+     * The window global to assign (default `__SIBU_SSR_DATA__`). Must be a
+     * plain identifier; anything else throws.
+     */
+    global?: string;
+}): string;
+/**
+ * Retrieve state that was embedded by `serializeState()` during SSR.
+ *
+ * When a `validate` function is provided, it acts as a type guard —
+ * only data that passes validation is returned. This prevents
+ * tampered SSR payloads from being trusted by the client.
+ *
+ * @param validate Optional type guard to verify data integrity
+ */
+declare function deserializeState<T = Record<string, unknown>>(validate?: (data: unknown) => data is T): T | undefined;
+
+export { type IslandStrategy as $, type AsyncRenderOptions as A, DEFAULT_TRANSFER_MAX_BYTES as B, type ComponentIslandOptions as C, type DocumentOptions as D, type RenderDiagnostics as E, type SettleOptions as F, type SettleResult as G, type HydrateOptions as H, ISLAND_PROPS_ATTR as I, type StreamRenderOptions as J, componentIsland as K, describeNodePath as L, formatRenderDiagnostics as M, islandComponent as N, renderFailure as O, renderToDocumentAsync as P, renderToStringAsync as Q, type RenderResult as R, type SerializeOptions as S, type TrustedHTML as T, settled as U, type EachBindings as V, type EachEventBindings as W, type EnhanceContext as X, type EnhanceSetup as Y, type IslandLoader as Z, type IslandRegistration as _, type HydrationMismatch as a, type LazyIslandLoader as a0, type MountIslandsOptions as a1, enhance as a2, enhanceAll as a3, lazyIsland as a4, mountIslands as a5, registerIsland as a6, unregisterIsland as a7, assembleDocument as b, collectStream as c, deserializeState as d, escapeScriptJson as e, hydrateIslands as f, hydrateProgressively as g, hydrate as h, isDangerousMetaRefresh as i, island as j, renderToReadableStream as k, renderToStream as l, renderToString as m, renderToStringWith as n, renderToSuspenseStream as o, resetSSRState as p, ssrSuspense as q, renderToDocument as r, serializeState as s, suspenseSwapScript as t, trustHTML as u, ADOPT_ID_ATTR as v, type AdoptMismatch as w, type AdoptOptions as x, type AdoptResult as y, DEFAULT_SETTLE_TIMEOUT as z };