sibujs 1.0.2 → 1.0.4

package/dist/plugins.d.cts

@@ -1,3 +1,4 @@
+import { T as TrustedHTML } from './ssr-BA6sxxUd.cjs';
 export { P as PluginContext, S as SibuPlugin, c as createPlugin, i as inject, p as plugin, r as resetPlugins, t as triggerPluginError, a as triggerPluginMount, b as triggerPluginUnmount } from './plugin-Bek4RhJY.cjs';
 export { M as Migration, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, a as compareSemVer, d as createBootSequence, e as createBundle, f as createMigrationRunner, g as createModuleRegistry, h as createSSRCache, i as createTestHarness, j as deferNonCritical, k as env, l as healthCheck, m as lazyModule, p as packageInfo, n as parseSemVer, o as preloadCritical, q as prerenderRoutes, s as satisfies } from './startup-0Qv6aosO.cjs';
 
@@ -85,6 +86,13 @@ interface RouterOptions {
     readonly cacheSize?: number;
     readonly errorRetryDelay?: number;
     readonly preloadStrategy?: "none" | "hover" | "visible";
+    /**
+     * Enable KeepAlive caching for route components.
+     * - `true` — cache all routes
+     * - string[] — cache only named routes matching these names
+     * - number — cache all routes with this max cache size
+     */
+    readonly keepAlive?: boolean | string[] | number;
 }
 type ScrollBehavior = (to: RouteContext, from: RouteContext, savedPosition: ScrollPosition | null) => ScrollPosition | null;
 interface ScrollPosition {
@@ -200,6 +208,34 @@ declare function beforeEach(guard: NavigationGuard): () => void;
 declare function beforeResolve(guard: NavigationGuard): () => void;
 declare function afterEach(hook: (to: RouteContext, from: RouteContext) => void): () => void;
 declare function Route(): Node;
+/**
+ * A route outlet that caches rendered components using KeepAlive.
+ * Routes are preserved in the DOM cache so signals, form state, and scroll
+ * position survive navigation.
+ *
+ * Uses the `keepAlive` option from RouterOptions if set, or accepts
+ * explicit options.
+ *
+ * @param options Optional: override the router-level keepAlive setting
+ *
+ * @example
+ * ```ts
+ * // Cache all routes (max 10)
+ * createRouter(routes, { keepAlive: 10 });
+ * mount(() => div({ nodes: [nav, KeepAliveRoute()] }), root);
+ *
+ * // Or cache specific routes by name
+ * createRouter(routes, { keepAlive: ["dashboard", "settings"] });
+ * mount(() => div({ nodes: [nav, KeepAliveRoute()] }), root);
+ *
+ * // Or override per-outlet
+ * KeepAliveRoute({ max: 5, include: ["dashboard"] })
+ * ```
+ */
+declare function KeepAliveRoute(options?: {
+    max?: number;
+    include?: string[];
+}): Node;
 declare function RouterLink(props: {
     to: NavigationTarget;
     replace?: boolean;
@@ -350,7 +386,7 @@ declare function renderRouteToDocument(url: string, routes: SSRRouteDef[], optio
     meta?: Record<string, string>[];
     links?: Record<string, string>[];
     scripts?: string[];
-    headExtra?: string;
+    headExtra?: TrustedHTML;
 }): string;
 /**
  * Serialize route state for embedding in HTML.
@@ -392,8 +428,8 @@ declare function createSSRRouter(routes: SSRRouteDef[]): {
         meta?: Record<string, string>[];
         links?: Record<string, string>[];
         scripts?: string[];
-        headExtra?: string;
+        headExtra?: TrustedHTML;
     }) => string;
 };
 
-export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, type LazyComponent, type NavigationFailure, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t };
+export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type NavigationFailure, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t };

package/dist/plugins.d.ts

@@ -1,3 +1,4 @@
+import { T as TrustedHTML } from './ssr-BA6sxxUd.js';
 export { P as PluginContext, S as SibuPlugin, c as createPlugin, i as inject, p as plugin, r as resetPlugins, t as triggerPluginError, a as triggerPluginMount, b as triggerPluginUnmount } from './plugin-Bek4RhJY.js';
 export { M as Migration, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, a as compareSemVer, d as createBootSequence, e as createBundle, f as createMigrationRunner, g as createModuleRegistry, h as createSSRCache, i as createTestHarness, j as deferNonCritical, k as env, l as healthCheck, m as lazyModule, p as packageInfo, n as parseSemVer, o as preloadCritical, q as prerenderRoutes, s as satisfies } from './startup-0Qv6aosO.js';
 
@@ -85,6 +86,13 @@ interface RouterOptions {
     readonly cacheSize?: number;
     readonly errorRetryDelay?: number;
     readonly preloadStrategy?: "none" | "hover" | "visible";
+    /**
+     * Enable KeepAlive caching for route components.
+     * - `true` — cache all routes
+     * - string[] — cache only named routes matching these names
+     * - number — cache all routes with this max cache size
+     */
+    readonly keepAlive?: boolean | string[] | number;
 }
 type ScrollBehavior = (to: RouteContext, from: RouteContext, savedPosition: ScrollPosition | null) => ScrollPosition | null;
 interface ScrollPosition {
@@ -200,6 +208,34 @@ declare function beforeEach(guard: NavigationGuard): () => void;
 declare function beforeResolve(guard: NavigationGuard): () => void;
 declare function afterEach(hook: (to: RouteContext, from: RouteContext) => void): () => void;
 declare function Route(): Node;
+/**
+ * A route outlet that caches rendered components using KeepAlive.
+ * Routes are preserved in the DOM cache so signals, form state, and scroll
+ * position survive navigation.
+ *
+ * Uses the `keepAlive` option from RouterOptions if set, or accepts
+ * explicit options.
+ *
+ * @param options Optional: override the router-level keepAlive setting
+ *
+ * @example
+ * ```ts
+ * // Cache all routes (max 10)
+ * createRouter(routes, { keepAlive: 10 });
+ * mount(() => div({ nodes: [nav, KeepAliveRoute()] }), root);
+ *
+ * // Or cache specific routes by name
+ * createRouter(routes, { keepAlive: ["dashboard", "settings"] });
+ * mount(() => div({ nodes: [nav, KeepAliveRoute()] }), root);
+ *
+ * // Or override per-outlet
+ * KeepAliveRoute({ max: 5, include: ["dashboard"] })
+ * ```
+ */
+declare function KeepAliveRoute(options?: {
+    max?: number;
+    include?: string[];
+}): Node;
 declare function RouterLink(props: {
     to: NavigationTarget;
     replace?: boolean;
@@ -350,7 +386,7 @@ declare function renderRouteToDocument(url: string, routes: SSRRouteDef[], optio
     meta?: Record<string, string>[];
     links?: Record<string, string>[];
     scripts?: string[];
-    headExtra?: string;
+    headExtra?: TrustedHTML;
 }): string;
 /**
  * Serialize route state for embedding in HTML.
@@ -392,8 +428,8 @@ declare function createSSRRouter(routes: SSRRouteDef[]): {
         meta?: Record<string, string>[];
         links?: Record<string, string>[];
         scripts?: string[];
-        headExtra?: string;
+        headExtra?: TrustedHTML;
     }) => string;
 };
 
-export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, type LazyComponent, type NavigationFailure, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t };
+export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type NavigationFailure, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t };

package/dist/plugins.js

@@ -18,10 +18,10 @@ import {
   preloadCritical,
   prerenderRoutes,
   satisfies
-} from "./chunk-DTCOOBMX.js";
+} from "./chunk-OF7UZIVB.js";
 import {
   renderToString
-} from "./chunk-7TQKR4PP.js";
+} from "./chunk-AZ3ISID5.js";
 import {
   createPlugin,
   inject,
@@ -33,10 +33,11 @@ import {
 } from "./chunk-K5ZUMYVS.js";
 import {
   span
-} from "./chunk-OWLQ4HZI.js";
+} from "./chunk-EWFVA3TJ.js";
 import {
+  dispose,
   registerDisposer
-} from "./chunk-QVKGGB2S.js";
+} from "./chunk-MDVXJWFN.js";
 import "./chunk-SDLZDHKP.js";
 import {
   effect
@@ -985,6 +986,120 @@ function Route() {
   routeCleanups.push(cleanupNodes);
   return anchor;
 }
+function KeepAliveRoute(options) {
+  if (!globalRouter) throw new Error("Router not initialized. Call createRouter() first.");
+  const anchor = document.createComment("keep-alive-route");
+  const cache = /* @__PURE__ */ new Map();
+  const lruOrder = [];
+  const routerOpts = globalRouter["options"];
+  const keepAliveOpt = routerOpts.keepAlive;
+  const maxCache = options?.max ?? (typeof keepAliveOpt === "number" ? keepAliveOpt : 20);
+  const includeNames = options?.include ?? (Array.isArray(keepAliveOpt) ? keepAliveOpt : void 0);
+  let currentNode = null;
+  let currentKey = "";
+  let currentCached = false;
+  let isUpdating = false;
+  let pendingUpdate = false;
+  const update = async () => {
+    if (!globalRouter) return;
+    if (isUpdating) {
+      pendingUpdate = true;
+      return;
+    }
+    const route2 = globalRouter.currentRoute;
+    const match = globalRouter["matcher"].match(route2.path);
+    if (!match) return;
+    const { route: routeDef } = match;
+    if ("redirect" in routeDef) {
+      const redirectPath = typeof routeDef.redirect === "function" ? routeDef.redirect(route2) : routeDef.redirect;
+      queueMicrotask(() => globalRouter?.navigate(redirectPath));
+      return;
+    }
+    if (!("component" in routeDef)) return;
+    const cacheKey = route2.path;
+    const shouldCache = !includeNames || routeDef.name != null && includeNames.includes(routeDef.name);
+    if (cacheKey === currentKey && currentNode) return;
+    isUpdating = true;
+    const parent = anchor.parentNode;
+    if (!parent) {
+      isUpdating = false;
+      return;
+    }
+    try {
+      if (currentNode?.parentNode) {
+        parent.removeChild(currentNode);
+        if (!currentCached) {
+          dispose(currentNode);
+        }
+      }
+      if (shouldCache && cache.has(cacheKey)) {
+        currentNode = cache.get(cacheKey);
+        currentCached = true;
+        const idx = lruOrder.indexOf(cacheKey);
+        if (idx !== -1) {
+          lruOrder.splice(idx, 1);
+        }
+        lruOrder.push(cacheKey);
+      } else {
+        const component = await globalRouter.loadComponent(routeDef, route2.path);
+        const node = component();
+        if (!node || route2.path !== globalRouter.currentRoute.path) {
+          isUpdating = false;
+          return;
+        }
+        currentNode = node;
+        currentCached = shouldCache;
+        if (shouldCache) {
+          cache.set(cacheKey, node);
+          lruOrder.push(cacheKey);
+          while (lruOrder.length > maxCache) {
+            const evictKey = lruOrder.shift();
+            const evictNode = cache.get(evictKey);
+            if (evictNode) {
+              dispose(evictNode);
+              if (evictNode.parentNode) evictNode.parentNode.removeChild(evictNode);
+              cache.delete(evictKey);
+            }
+          }
+        }
+      }
+      currentKey = cacheKey;
+      if (currentNode) {
+        parent.insertBefore(currentNode, anchor.nextSibling);
+      }
+    } catch (error) {
+      console.error("[KeepAliveRoute] Component error:", error);
+    } finally {
+      isUpdating = false;
+      if (pendingUpdate) {
+        pendingUpdate = false;
+        update();
+      }
+    }
+  };
+  let initialized = false;
+  const wrappedUpdate = async () => {
+    await update();
+    initialized = true;
+  };
+  track(wrappedUpdate);
+  if (!initialized) {
+    queueMicrotask(() => {
+      if (!initialized && anchor.parentNode) wrappedUpdate();
+    });
+  }
+  routeCleanups.push(() => {
+    for (const node of cache.values()) {
+      dispose(node);
+      if (node.parentNode) node.parentNode.removeChild(node);
+    }
+    cache.clear();
+    lruOrder.length = 0;
+    if (currentNode?.parentNode) currentNode.parentNode.removeChild(currentNode);
+    currentNode = null;
+  });
+  return anchor;
+}
 function RouterLink(props) {
   if (!globalRouter) throw new Error("Router not initialized. Call createRouter() first.");
   const { to, replace: replace2 = false, activeClass, exactActiveClass, nodes, target, rel, ...attrs } = props;
@@ -1474,7 +1589,7 @@ function hydrateRouter(routes, options) {
   if (container && serverState.path) {
     const resolved = resolveServerRoute(serverState.path, routes);
     if (resolved.component) {
-      import("./ssr-WKUPVSSK.js").then(({ hydrate }) => {
+      import("./ssr-6GIMY5MX.js").then(({ hydrate }) => {
         if (resolved.component) {
           hydrate(resolved.component, container);
         }
@@ -1502,6 +1617,7 @@ function escapeAttr(str) {
   return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 export {
+  KeepAliveRoute,
   Outlet,
   Route,
   RouterLink,

package/dist/{ssr-WKUPVSSK.js → ssr-6GIMY5MX.js}

@@ -13,8 +13,9 @@ import {
   resetSSRState,
   serializeState,
   ssrSuspense,
-  suspenseSwapScript
-} from "./chunk-7TQKR4PP.js";
+  suspenseSwapScript,
+  trustHTML
+} from "./chunk-AZ3ISID5.js";
 import "./chunk-4MYMUBRS.js";
 import "./chunk-MLKGABMK.js";
 export {
@@ -32,5 +33,6 @@ export {
   resetSSRState,
   serializeState,
   ssrSuspense,
-  suspenseSwapScript
+  suspenseSwapScript,
+  trustHTML
 };

package/dist/ssr-BA6sxxUd.d.cts

@@ -0,0 +1,135 @@
+/**
+ * Converts an HTMLElement tree to an HTML string for server-side rendering.
+ */
+declare function renderToString(element: HTMLElement | DocumentFragment | Node): string;
+/**
+ * Hydrates a server-rendered DOM tree by attaching event listeners
+ * and activating reactive bindings.
+ */
+declare function hydrate(component: () => HTMLElement, container: HTMLElement): 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;
+/**
+ * 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.
+ */
+declare function renderToDocument(component: () => HTMLElement, options?: {
+    title?: string;
+    meta?: Record<string, string>[];
+    links?: Record<string, string>[];
+    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;
+}): 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.
+ */
+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>.
+ * Compatible with Node 18+, Deno, and edge runtimes.
+ * Uses pull-based backpressure — chunks are produced on demand.
+ */
+declare function renderToReadableStream(element: HTMLElement | DocumentFragment | Node): ReadableStream<string>;
+/**
+ * Marks an element as a hydration island. During partial hydration
+ * only elements marked with `data-sibu-island` will be hydrated.
+ */
+declare function island(id: string, component: () => HTMLElement): HTMLElement;
+/**
+ * Hydrate only elements marked as islands (`data-sibu-island`).
+ * Non-island content keeps its server-rendered HTML untouched.
+ */
+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.
+ */
+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.
+ */
+declare function ssrSuspense(props: {
+    fallback: () => HTMLElement;
+    content: () => Promise<HTMLElement>;
+}): {
+    element: HTMLElement;
+    promise: Promise<{
+        id: string;
+        html: string;
+    }>;
+};
+/**
+ * Generate an inline script that swaps a suspense fallback with resolved content.
+ * The id is escaped for both JS string and HTML attribute contexts to prevent injection.
+ */
+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.
+ */
+declare function renderToSuspenseStream(element: HTMLElement | DocumentFragment | Node, pendingBoundaries?: Promise<{
+    id: string;
+    html: string;
+}>[]): AsyncGenerator<string>;
+/**
+ * Serialize application state into an HTML script tag for SSR.
+ * The serialized data is embedded in the document and picked up
+ * on the client with `deserializeState()`.
+ */
+declare function serializeState(state: Record<string, unknown>, nonce?: 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 TrustedHTML as T, hydrateIslands as a, hydrateProgressively as b, collectStream as c, deserializeState as d, renderToReadableStream as e, renderToStream as f, renderToString as g, hydrate as h, island as i, renderToSuspenseStream as j, resetSSRState as k, ssrSuspense as l, suspenseSwapScript as m, renderToDocument as r, serializeState as s, trustHTML as t };

package/dist/ssr-BA6sxxUd.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Converts an HTMLElement tree to an HTML string for server-side rendering.
+ */
+declare function renderToString(element: HTMLElement | DocumentFragment | Node): string;
+/**
+ * Hydrates a server-rendered DOM tree by attaching event listeners
+ * and activating reactive bindings.
+ */
+declare function hydrate(component: () => HTMLElement, container: HTMLElement): 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;
+/**
+ * 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.
+ */
+declare function renderToDocument(component: () => HTMLElement, options?: {
+    title?: string;
+    meta?: Record<string, string>[];
+    links?: Record<string, string>[];
+    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;
+}): 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.
+ */
+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>.
+ * Compatible with Node 18+, Deno, and edge runtimes.
+ * Uses pull-based backpressure — chunks are produced on demand.
+ */
+declare function renderToReadableStream(element: HTMLElement | DocumentFragment | Node): ReadableStream<string>;
+/**
+ * Marks an element as a hydration island. During partial hydration
+ * only elements marked with `data-sibu-island` will be hydrated.
+ */
+declare function island(id: string, component: () => HTMLElement): HTMLElement;
+/**
+ * Hydrate only elements marked as islands (`data-sibu-island`).
+ * Non-island content keeps its server-rendered HTML untouched.
+ */
+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.
+ */
+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.
+ */
+declare function ssrSuspense(props: {
+    fallback: () => HTMLElement;
+    content: () => Promise<HTMLElement>;
+}): {
+    element: HTMLElement;
+    promise: Promise<{
+        id: string;
+        html: string;
+    }>;
+};
+/**
+ * Generate an inline script that swaps a suspense fallback with resolved content.
+ * The id is escaped for both JS string and HTML attribute contexts to prevent injection.
+ */
+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.
+ */
+declare function renderToSuspenseStream(element: HTMLElement | DocumentFragment | Node, pendingBoundaries?: Promise<{
+    id: string;
+    html: string;
+}>[]): AsyncGenerator<string>;
+/**
+ * Serialize application state into an HTML script tag for SSR.
+ * The serialized data is embedded in the document and picked up
+ * on the client with `deserializeState()`.
+ */
+declare function serializeState(state: Record<string, unknown>, nonce?: 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 TrustedHTML as T, hydrateIslands as a, hydrateProgressively as b, collectStream as c, deserializeState as d, renderToReadableStream as e, renderToStream as f, renderToString as g, hydrate as h, island as i, renderToSuspenseStream as j, resetSSRState as k, ssrSuspense as l, suspenseSwapScript as m, renderToDocument as r, serializeState as s, trustHTML as t };

package/dist/ssr.cjs

@@ -55,6 +55,7 @@ __export(ssr_exports, {
   setStructuredData: () => setStructuredData,
   ssrSuspense: () => ssrSuspense,
   suspenseSwapScript: () => suspenseSwapScript,
+  trustHTML: () => trustHTML,
   wasm: () => wasm,
   worker: () => worker,
   workerFn: () => workerFn
@@ -156,6 +157,9 @@ function hydrateNode(serverNode, clientNode) {
     hydrateNode(serverChildren[i2], clientChildren[i2]);
   }
 }
+function trustHTML(html2) {
+  return html2;
+}
 function renderToDocument(component, options = {}) {
   let content;
   try {
@@ -1000,7 +1004,7 @@ function bindChildNode(placeholder, getter) {
       const node = lastNodes[i2];
       if (node.parentNode) node.parentNode.removeChild(node);
     }
-    if (result == null) {
+    if (result == null || typeof result === "boolean") {
       lastNodes.length = 0;
       return;
     }
@@ -1015,6 +1019,7 @@ function bindChildNode(placeholder, getter) {
       if (lastNodes.length < result.length) lastNodes = new Array(result.length);
       for (let i2 = 0; i2 < result.length; i2++) {
         const item = result[i2];
+        if (item == null || typeof item === "boolean") continue;
         const node = item instanceof Node ? item : document.createTextNode(String(item));
         parent.insertBefore(node, anchor);
         lastNodes[count++] = node;
@@ -1129,6 +1134,9 @@ function appendChildren(el, nodes) {
     el.textContent = String(nodes);
     return;
   }
+  if (typeof nodes === "boolean" || nodes == null) {
+    return;
+  }
   if (typeof nodes === "function") {
     const ph = document.createComment("");
     el.appendChild(ph);
@@ -1157,11 +1165,11 @@ function appendChildren(el, nodes) {
             registerDisposer(el, bindChildNode(ph, inner));
           } else if (inner instanceof Node) {
             el.appendChild(inner);
-          } else if (inner != null) {
+          } else if (inner != null && typeof inner !== "boolean") {
             el.appendChild(document.createTextNode(String(inner)));
           }
         }
-      } else if (c != null) {
+      } else if (c != null && typeof c !== "boolean") {
         el.appendChild(document.createTextNode(String(c)));
       }
     }
@@ -1832,6 +1840,7 @@ function isWasmCached(key) {
   setStructuredData,
   ssrSuspense,
   suspenseSwapScript,
+  trustHTML,
   wasm,
   worker,
   workerFn