sibujs 3.4.0 → 4.0.0

package/dist/{ssr-D62yFwuw.d.cts → ssr-BiPRdZ6n.d.cts}

@@ -29,12 +29,29 @@ interface HydrationMismatch {
     message: string;
 }
 /**
- * Hydrates a server-rendered DOM tree by attaching event listeners
- * and activating reactive bindings.
+ * 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: () => HTMLElement, container: HTMLElement, options?: HydrateOptions): void;
 /**
@@ -58,10 +75,17 @@ type TrustedHTML = string & {
  */
 declare function trustHTML(html: string): TrustedHTML;
 /**
- * Detect `<meta http-equiv="refresh" content="0;url=javascript:...">`.
- * Returns true if the props describe a refresh directive whose URL uses
- * a dangerous protocol — in which case the entire meta entry must be
- * dropped to avoid an XSS vector via the browser refresh mechanism.
+ * 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;
 /**
@@ -100,19 +124,24 @@ declare function renderToStream(element: HTMLElement | DocumentFragment | Node):
  */
 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.
+ * 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>;
 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.
- *
- * Security: uses `hasOwnProperty.call` to guard against prototype-pollution
- * lookups (e.g. an island id of `__proto__` must not resolve to `Object.prototype`).
- */
 declare function hydrateIslands(container: HTMLElement, islands: Record<string, () => HTMLElement>): void;
 /**
  * Progressively hydrate islands only when they enter the viewport.

package/dist/{ssr-D62yFwuw.d.ts → ssr-BiPRdZ6n.d.ts}

@@ -29,12 +29,29 @@ interface HydrationMismatch {
     message: string;
 }
 /**
- * Hydrates a server-rendered DOM tree by attaching event listeners
- * and activating reactive bindings.
+ * 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: () => HTMLElement, container: HTMLElement, options?: HydrateOptions): void;
 /**
@@ -58,10 +75,17 @@ type TrustedHTML = string & {
  */
 declare function trustHTML(html: string): TrustedHTML;
 /**
- * Detect `<meta http-equiv="refresh" content="0;url=javascript:...">`.
- * Returns true if the props describe a refresh directive whose URL uses
- * a dangerous protocol — in which case the entire meta entry must be
- * dropped to avoid an XSS vector via the browser refresh mechanism.
+ * 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;
 /**
@@ -100,19 +124,24 @@ declare function renderToStream(element: HTMLElement | DocumentFragment | Node):
  */
 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.
+ * 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>;
 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.
- *
- * Security: uses `hasOwnProperty.call` to guard against prototype-pollution
- * lookups (e.g. an island id of `__proto__` must not resolve to `Object.prototype`).
- */
 declare function hydrateIslands(container: HTMLElement, islands: Record<string, () => HTMLElement>): void;
 /**
  * Progressively hydrate islands only when they enter the viewport.

package/dist/{ssr-2PPULEK2.js → ssr-JFP5535P.js}

@@ -17,10 +17,11 @@ import {
   ssrSuspense,
   suspenseSwapScript,
   trustHTML
-} from "./chunk-EX77FXTT.js";
-import "./chunk-L3GAGWCC.js";
-import "./chunk-S3NFJO6L.js";
-import "./chunk-COY6PUD2.js";
+} from "./chunk-HYCCIYNS.js";
+import "./chunk-5INI7D2L.js";
+import "./chunk-TIRZCERI.js";
+import "./chunk-DHDZ7IVN.js";
+import "./chunk-VPP2FONR.js";
 export {
   collectStream,
   deserializeState,