@zerotal/flow 1.4.0 → 1.5.0

package/src/router.ts

@@ -12,6 +12,8 @@ import { _renderFlowPage } from "./jsx-runtime.ts";
 import { populatePresence } from "./presence.ts";
 import { populateShared } from "./shared.ts";
 import { restoreDurable, persistDurable } from "./durable.ts";
+import { createSectionStore, runWithSections, resolveSections } from "./sections.ts";
+import { createStreamStore, runWithStreaming, streamChunk } from "./streaming.ts";
 import type { HtmlNode } from "./jsx-runtime.ts";
 import { _runtimeJs } from "./provider/FlowProvider.ts";
 import { randomComponentId, toScriptJson } from "./utils.ts";
@@ -31,7 +33,7 @@ import {
  *
  * Middleware attached here (or via an enclosing Router.group()) runs on the
  * initial page load AND is re-applied on every WebSocket update for this page
- * (Livewire-style persistent middleware).
+ * (persistent middleware).
  *
  * @example
  * import { Router } from '@zerotal/core';
@@ -90,127 +92,142 @@ export function _layoutId(page: Component): string {
   return "l" + (hash >>> 0).toString(36);
 }
 
-function _makeFlowHandler(path: string, PageClass: PageClassWithMeta) {
+/**
+ * Build the GET handler for a Flow page.
+ *
+ * @internal Exported so the document-assembly path — section resolution and the
+ * streamed response — can be driven directly in tests, without standing up a
+ * router and a server to reach it.
+ */
+export function _makeFlowHandler(path: string, PageClass: PageClassWithMeta) {
   return class FlowPageHandler {
     async handle(ctx: HttpContext): Promise<void> {
       const http = ctx;
       // Wrap the initial render: an onMount()/render() throw surfaces as the dev error overlay
       // (like an action throw) rather than a bare 500. Production rethrows → a normal 500 with no
       // stack leak.
+      // Both stores are per-request and must stay active for the whole render:
+      // sections are published during the page render and read after the layout
+      // one, and a streamed child is queued mid-render and drained afterwards.
+      const sections = createSectionStore();
+      const streams = createStreamStore();
+
       try {
-        const page = new PageClass() as Component;
-        const compId = randomComponentId(PageClass.name);
-        const compName = PageClass.name;
-
-        // Identity used by nested children (deterministic child ids) and by
-        // persistent middleware (children inherit the parent's route path).
-        page._flowId = compId;
-        page._flowPath = path;
-
-        // Seed @url properties from the request's query string before onMount().
-        // This makes the page state reflect the URL on initial render.
-        _seedUrlProps(page, http.request);
-
-        // Seed @session properties from the session (if SessionMiddleware is active).
-        _seedSessionProps(page, compName, http);
-
-        // Seed @param properties from the matched route segments — including resolved
-        // model bindings. Initial GET only; round-trips restore these from the snapshot.
-        _seedRouteParams(page, ctx);
-
-        // boot() runs on every request (here: the initial render), before mount().
-        // Forward the request HttpContext so dynamic-segment pages can read route
-        // params and implicitly-bound models off `ctx.params` (e.g. `:account` ->
-        // Account at `ctx.params.account`) inside onBoot()/onMount().
-        await page.onBoot(ctx);
-
-        // Durable/resumable snapshots: if this component opted into `static durable` and a valid
-        // stored snapshot exists for this user/session + route, resume from it — restore state and
-        // run onHydrate (like a WS round-trip), skipping onMount. Otherwise mount fresh. A missing,
-        // tampered, or stale-key entry falls through to a normal mount. No-op unless opted in.
-        if (await restoreDurable(page, ctx)) {
-          await page.onHydrate();
-        } else {
-          await page.onMount(ctx);
-        }
-
-        // Persist @session props back to session after onMount (captures any changes).
-        _persistSessionProps(page, compName, http);
-
-        // A redirect() issued from onBoot()/onMount() short-circuits the initial render —
-        // the page never paints, the browser is sent straight on (e.g. a landing page that
-        // forwards "/" to "/dashboard", or a server-side auth bounce). Without this, the
-        // redirect was only honoured on WebSocket actions and silently ignored on first GET.
-        if (page._redirectUrl) {
-          http.redirect(page._redirectUrl, _redirectStatus(page._redirectStatus));
-          return;
-        }
-
-        // Fill @presence member lists before the first paint (the client refreshes them on
-        // join/leave thereafter). No-op unless the component has @presence props.
-        await populatePresence(page);
-
-        // Refill @shared props from the room store before the first paint (seeding the store
-        // with the default when the room is new). No-op unless the component has @shared props.
-        populateShared(page);
-
-        const innerHtml = await _renderFlowPage(page, () => page.render());
-
-        // dehydrate() hook runs at the end of the request, before serialisation.
-        await page.onDehydrate();
-        const snapshot = dehydrate(page, { id: compId, name: compName, path });
-        warnIfLarge(snapshot, compName);
-
-        // Persist the durable snapshot (or clear it if clearDurable() was called). No-op unless
-        // the component opted into `static durable`.
-        await persistDurable(page, ctx, snapshot);
-
-        // toScriptJson, not JSON.stringify: the snapshot carries @expose/@locked values and
-        // @url props seeded from the query string, so it routinely holds attacker-controlled
-        // strings that would otherwise close the <script> island. See toScriptJson's docblock.
-        const snapshotJson = toScriptJson(snapshot);
-
-        // The flow component root — always the same wrapper regardless of layout.
-        const flowRoot: HtmlNode = {
-          html: `<div data-flow-root x-data="{}" data-flow-id="${compId}" data-flow-name="${compName}">${innerHtml}</div>`,
-        };
-
-        // Layout resolution. The JSX-native `layout(page)` instance hook wins; otherwise
-        // fall back to the legacy `static layout = SomeLayout` class. Both wrap the root in
-        // a [data-flow-layout] marker so the client navigate logic swaps only the
-        // [data-flow-root] on same-layout navigations (a full navigation otherwise).
-        let bodyContent: string;
-        let layoutHead = "";
-
-        const wrapped = await page.layout(flowRoot);
-        const LayoutClass = (PageClass as PageClassWithLayout).layout;
-
-        if (wrapped !== flowRoot) {
-          // JSX-native layout. If the layout component declared its own identity
-          // (data-flow-layout on its root), honour it — that's the robust way to keep the
-          // shell persistent across navigations, especially when the wrapper passes
-          // page-specific props. Otherwise fall back to a source-derived id, which matches
-          // for identical wrappers like `(page) => <AppLayout>{page}</AppLayout>`.
-          bodyContent = /\bdata-flow-layout\b/.test(wrapped.html)
-            ? wrapped.html
-            : `<div data-flow-layout="${_layoutId(page)}">${wrapped.html}</div>`;
-        } else if (LayoutClass) {
-          const layout = new LayoutClass();
-          const layoutNode = await layout.render(flowRoot);
-          bodyContent = `<div data-flow-layout="${LayoutClass.name}">${layoutNode.html}</div>`;
-          layoutHead = (LayoutClass as { head?: string }).head ?? "";
-        } else {
-          bodyContent = flowRoot.html;
-        }
-
-        const titleTag = PageClass.title ? `<title>${PageClass.title}</title>` : "";
-        // Component head takes precedence; layout head provides global resources.
-        const headExtra = [PageClass.head ?? "", layoutHead].filter(Boolean).join("\n  ");
-
-        const runtimeSrc = _runtimeJs() ? "/__flow/runtime.js" : "";
-        const runtimeTag = runtimeSrc ? `<script src="${runtimeSrc}" defer></script>` : "";
-
-        const html = `<!DOCTYPE html>
+        await runWithSections(sections, () =>
+          runWithStreaming(streams, async () => {
+            const page = new PageClass() as Component;
+            const compId = randomComponentId(PageClass.name);
+            const compName = PageClass.name;
+
+            // Identity used by nested children (deterministic child ids) and by
+            // persistent middleware (children inherit the parent's route path).
+            page._flowId = compId;
+            page._flowPath = path;
+
+            // Seed @url properties from the request's query string before onMount().
+            // This makes the page state reflect the URL on initial render.
+            _seedUrlProps(page, http.request);
+
+            // Seed @session properties from the session (if SessionMiddleware is active).
+            _seedSessionProps(page, compName, http);
+
+            // Seed @param properties from the matched route segments — including resolved
+            // model bindings. Initial GET only; round-trips restore these from the snapshot.
+            _seedRouteParams(page, ctx);
+
+            // boot() runs on every request (here: the initial render), before mount().
+            // Forward the request HttpContext so dynamic-segment pages can read route
+            // params and implicitly-bound models off `ctx.params` (e.g. `:account` ->
+            // Account at `ctx.params.account`) inside onBoot()/onMount().
+            await page.onBoot(ctx);
+
+            // Durable/resumable snapshots: if this component opted into `static durable` and a valid
+            // stored snapshot exists for this user/session + route, resume from it — restore state and
+            // run onHydrate (like a WS round-trip), skipping onMount. Otherwise mount fresh. A missing,
+            // tampered, or stale-key entry falls through to a normal mount. No-op unless opted in.
+            if (await restoreDurable(page, ctx)) {
+              await page.onHydrate();
+            } else {
+              await page.onMount(ctx);
+            }
+
+            // Persist @session props back to session after onMount (captures any changes).
+            _persistSessionProps(page, compName, http);
+
+            // A redirect() issued from onBoot()/onMount() short-circuits the initial render —
+            // the page never paints, the browser is sent straight on (e.g. a landing page that
+            // forwards "/" to "/dashboard", or a server-side auth bounce). Without this, the
+            // redirect was only honoured on WebSocket actions and silently ignored on first GET.
+            if (page._redirectUrl) {
+              http.redirect(page._redirectUrl, _redirectStatus(page._redirectStatus));
+              return;
+            }
+
+            // Fill @presence member lists before the first paint (the client refreshes them on
+            // join/leave thereafter). No-op unless the component has @presence props.
+            await populatePresence(page);
+
+            // Refill @shared props from the room store before the first paint (seeding the store
+            // with the default when the room is new). No-op unless the component has @shared props.
+            populateShared(page);
+
+            const innerHtml = await _renderFlowPage(page, () => page.render());
+
+            // dehydrate() hook runs at the end of the request, before serialisation.
+            await page.onDehydrate();
+            const snapshot = dehydrate(page, { id: compId, name: compName, path });
+            warnIfLarge(snapshot, compName);
+
+            // Persist the durable snapshot (or clear it if clearDurable() was called). No-op unless
+            // the component opted into `static durable`.
+            await persistDurable(page, ctx, snapshot);
+
+            // toScriptJson, not JSON.stringify: the snapshot carries @expose/@locked values and
+            // @url props seeded from the query string, so it routinely holds attacker-controlled
+            // strings that would otherwise close the <script> island. See toScriptJson's docblock.
+            const snapshotJson = toScriptJson(snapshot);
+
+            // The flow component root — always the same wrapper regardless of layout.
+            const flowRoot: HtmlNode = {
+              html: `<div data-flow-root x-data="{}" data-flow-id="${compId}" data-flow-name="${compName}">${innerHtml}</div>`,
+            };
+
+            // Layout resolution. The JSX-native `layout(page)` instance hook wins; otherwise
+            // fall back to the legacy `static layout = SomeLayout` class. Both wrap the root in
+            // a [data-flow-layout] marker so the client navigate logic swaps only the
+            // [data-flow-root] on same-layout navigations (a full navigation otherwise).
+            let bodyContent: string;
+            let layoutHead = "";
+
+            const wrapped = await page.layout(flowRoot);
+            const LayoutClass = (PageClass as PageClassWithLayout).layout;
+
+            if (wrapped !== flowRoot) {
+              // JSX-native layout. If the layout component declared its own identity
+              // (data-flow-layout on its root), honour it — that's the robust way to keep the
+              // shell persistent across navigations, especially when the wrapper passes
+              // page-specific props. Otherwise fall back to a source-derived id, which matches
+              // for identical wrappers like `(page) => <AppLayout>{page}</AppLayout>`.
+              bodyContent = /\bdata-flow-layout\b/.test(wrapped.html)
+                ? wrapped.html
+                : `<div data-flow-layout="${_layoutId(page)}">${wrapped.html}</div>`;
+            } else if (LayoutClass) {
+              const layout = new LayoutClass();
+              const layoutNode = await layout.render(flowRoot);
+              bodyContent = `<div data-flow-layout="${LayoutClass.name}">${layoutNode.html}</div>`;
+              layoutHead = (LayoutClass as { head?: string }).head ?? "";
+            } else {
+              bodyContent = flowRoot.html;
+            }
+
+            const titleTag = PageClass.title ? `<title>${PageClass.title}</title>` : "";
+            // Component head takes precedence; layout head provides global resources.
+            const headExtra = [PageClass.head ?? "", layoutHead].filter(Boolean).join("\n  ");
+
+            const runtimeSrc = _runtimeJs() ? "/__flow/runtime.js" : "";
+            const runtimeTag = runtimeSrc ? `<script src="${runtimeSrc}" defer></script>` : "";
+
+            const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8" />
@@ -226,7 +243,60 @@ function _makeFlowHandler(path: string, PageClass: PageClassWithMeta) {
 </body>
 </html>`;
 
-        http.html(html);
+            // Outlets are filled only now: this is the first moment at which both the
+            // page and the layout have rendered, so every publication has happened.
+            const document = resolveSections(html, sections);
+
+            if (streams.pending.length === 0) {
+              http.html(document);
+              return;
+            }
+
+            // Streamed children: flush the document up to </body>, then append each
+            // child's markup as it finishes, then close. Constructed here, inside the
+            // request's async context, so the renders below still see the same
+            // HttpContext and section store.
+            const closing = document.lastIndexOf("</body>");
+            const shell = closing === -1 ? document : document.slice(0, closing);
+            const tail = closing === -1 ? "" : document.slice(closing);
+            const queued = [...streams.pending];
+
+            const encoder = new TextEncoder();
+            const body = new ReadableStream<Uint8Array>({
+              async start(controller) {
+                controller.enqueue(encoder.encode(shell));
+                for (const entry of queued) {
+                  let markup: string;
+                  try {
+                    markup = await entry.render();
+                  } catch (error) {
+                    // The shell is already on the wire, so there is no failing the
+                    // response — the placeholder is replaced with a notice instead.
+                    console.error(
+                      `[Flow] Streamed child ${entry.childId} failed to render:`,
+                      error,
+                    );
+                    markup =
+                      '<div data-flow-stream-error role="alert" class="rounded border ' +
+                      'border-red-300 bg-red-50 p-3 text-sm text-red-700">' +
+                      "Something went wrong loading this section.</div>";
+                  }
+                  controller.enqueue(encoder.encode(streamChunk(entry.childId, markup)));
+                }
+                controller.enqueue(encoder.encode(tail));
+                controller.close();
+              },
+            });
+
+            http.response = new Response(body, {
+              headers: {
+                "Content-Type": "text/html; charset=utf-8",
+                // Proxies that buffer defeat streaming; this asks nginx not to.
+                "X-Accel-Buffering": "no",
+              },
+            });
+          }),
+        );
       } catch (error) {
         // Only UNEXPECTED throws get the dev overlay. Intended HTTP errors — auth (401/403), 404,
         // validation, and redirects thrown as errors — carry a numeric `status` and must keep

package/src/sections.ts

@@ -0,0 +1,121 @@
+// ── Named sections ────────────────────────────────────────────────────────────
+//
+// `<SectionContent name="toolbar">` publishes markup from anywhere in the page
+// tree; `<SectionOutlet name="toolbar" />` renders it somewhere else — usually
+// in the layout, which is exactly where a page cannot otherwise reach.
+//
+// Without this, a page that wants to put buttons in the layout's toolbar has to
+// thread them through every intermediate component as props, or the layout has
+// to know about every page that might contribute. Sections invert that: the
+// component that owns the content declares it, and the layout declares a hole.
+//
+// ## Why outlets resolve last
+//
+// An outlet emits a token and is filled in a final pass over the finished
+// document, rather than reading the store when it renders. Rendering is a single
+// forward pass, so a store read would make the result depend on whether the
+// outlet happened to render before or after the content — which for the common
+// case (outlet in the layout, content in the page) is *backwards*, since the
+// layout wraps a page that has already rendered. Deferring makes order
+// irrelevant in both directions.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** One `<SectionOutlet>` awaiting content. */
+interface Outlet {
+  name: string;
+  /** Markup to use when nothing was published to `name`. */
+  fallback: string;
+}
+
+/** Per-request section state. */
+export interface SectionStore {
+  /** Published markup, in publication order, per section name. */
+  readonly content: Map<string, string[]>;
+  /** Outlets awaiting resolution, keyed by their token index. */
+  readonly outlets: Outlet[];
+  /**
+   * Per-request random suffix on the outlet token.
+   *
+   * The resolving splice is a blind `split`/`join` over finished HTML, so any
+   * occurrence of the token is replaced — including one a user put in a string.
+   * Escaping is the actual control; this makes the token unguessable so a path
+   * that ever misses an escape still cannot be aimed at. Same reasoning as the
+   * child-placeholder nonce in `jsx-runtime.ts`.
+   */
+  readonly nonce: string;
+}
+
+const _storage = new AsyncLocalStorage<SectionStore>();
+
+/** A fresh store for one request. */
+export function createSectionStore(): SectionStore {
+  return {
+    content: new Map(),
+    outlets: [],
+    nonce: crypto.randomUUID().slice(0, 8),
+  };
+}
+
+/** Run `fn` with `store` as the active section store for the current async chain. */
+export function runWithSections<T>(store: SectionStore, fn: () => T): T {
+  return _storage.run(store, fn);
+}
+
+/** The active store, or `undefined` outside a page render (e.g. a WS patch). */
+export function getSectionStore(): SectionStore | undefined {
+  return _storage.getStore();
+}
+
+/**
+ * Publish `html` to the section called `name`.
+ *
+ * Repeated publications to one name accumulate in order rather than replacing,
+ * so two components can both contribute toolbar buttons.
+ */
+export function publishSection(name: string, html: string): void {
+  const store = _storage.getStore();
+  if (!store) return;
+  const existing = store.content.get(name);
+  if (existing) existing.push(html);
+  else store.content.set(name, [html]);
+}
+
+/**
+ * Reserve a place for section `name`, returning the token to emit.
+ *
+ * Returns `fallback` directly when there is no active store — a WS patch
+ * re-renders a component, not the document, so there is nothing to resolve
+ * against and the outlet renders its default.
+ */
+export function reserveSection(name: string, fallback: string): string {
+  const store = _storage.getStore();
+  if (!store) return fallback;
+  const index = store.outlets.length;
+  store.outlets.push({ name, fallback });
+  return `<!--flow-section:${store.nonce}:${index}-->`;
+}
+
+/**
+ * Replace every outlet token in `html` with what was published to it.
+ *
+ * Call once, after the page *and* its layout have rendered — that is the only
+ * point at which every publication has happened.
+ */
+export function resolveSections(html: string, store: SectionStore): string {
+  if (store.outlets.length === 0) return html;
+
+  // One pass, not one per outlet. Replacing outlets in a loop would rescan text
+  // that was itself just substituted, so markup published to an early section
+  // could go on to fill a later one. A function replacer is also what keeps `$&`
+  // and friends in the content from being interpreted as replacement patterns.
+  // The nonce is hex, so it needs no escaping to sit in this pattern.
+  const pattern = new RegExp(`<!--flow-section:${store.nonce}:(\\d+)-->`, "g");
+
+  return html.replace(pattern, (match, digits: string) => {
+    const outlet = store.outlets[Number(digits)];
+    if (!outlet) return match;
+    const published = store.content.get(outlet.name);
+    return published && published.length > 0 ? published.join("") : outlet.fallback;
+  });
+}

package/src/store.ts

@@ -33,7 +33,6 @@
  * }
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface FlowStore {}
 
 /** The one Alpine store name that backs `$flow.store`. */

package/src/streaming.ts

@@ -0,0 +1,92 @@
+// ── Streaming rendering ───────────────────────────────────────────────────────
+//
+// `<SlowWidget stream />` renders its placeholder immediately and its real
+// markup later, on the *same HTTP response*. The shell reaches the browser
+// without waiting for the slow child; the child's HTML arrives as a trailing
+// chunk and is swapped in by a one-line inline script.
+//
+// ## How this differs from `lazy` / `defer`
+//
+// `lazy` and `defer` also paint a placeholder first, but the real render happens
+// on a **second round trip**: the client mounts the child over the socket once
+// it is visible (`lazy`) or once the document is parsed (`defer`). That is the
+// right tool when the content may never be needed — a widget below the fold, a
+// tab nobody opens.
+//
+// `stream` is for content that is definitely needed and merely slow. There is no
+// second request, no socket involvement, and no client runtime requirement: the
+// swap happens during parse, so it works before (and without) Alpine.
+//
+// ## Degradation
+//
+// Streaming needs an unbuffered response. Behind a proxy that buffers, the
+// browser simply receives the whole document at once and the swap scripts run in
+// order — the page is correct, just not progressive. Nothing detects or reports
+// this, because there is nothing the app could do about it.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** One child whose real markup is still being rendered. */
+export interface PendingStream {
+  /** `data-flow-id` of the placeholder root this will replace the contents of. */
+  childId: string;
+  /** Resolves to the child's finished inner HTML plus its state script. */
+  render: () => Promise<string>;
+}
+
+/** Per-request streaming state. */
+export interface StreamStore {
+  readonly pending: PendingStream[];
+}
+
+const _storage = new AsyncLocalStorage<StreamStore>();
+
+/** A fresh store for one request. */
+export function createStreamStore(): StreamStore {
+  return { pending: [] };
+}
+
+/** Run `fn` with `store` as the active stream store for the current async chain. */
+export function runWithStreaming<T>(store: StreamStore, fn: () => T): T {
+  return _storage.run(store, fn);
+}
+
+/**
+ * The active store, or `undefined` when streaming is not available.
+ *
+ * Absent during WebSocket patches, which have no response to stream on. Callers
+ * treat that as "render this child inline instead", so `stream` degrades to an
+ * ordinary child rather than failing.
+ */
+export function getStreamStore(): StreamStore | undefined {
+  return _storage.getStore();
+}
+
+/** Queue a child to be rendered after the shell has been flushed. */
+export function queueStream(entry: PendingStream): void {
+  _storage.getStore()?.pending.push(entry);
+}
+
+/**
+ * The chunk that swaps one streamed child into place.
+ *
+ * The markup rides in a `<template>` so the parser will not execute or render it
+ * where it lands, and the script that follows moves it into the placeholder and
+ * removes itself. `document.currentScript` is used rather than an id lookup so
+ * the pair stays self-contained and repeatable.
+ */
+export function streamChunk(childId: string, html: string): string {
+  const id = JSON.stringify(childId);
+  return (
+    `<template data-flow-stream-for="${_escapeAttr(childId)}">${html}</template>` +
+    `<script>(function(){var s=document.currentScript;var t=s.previousElementSibling;` +
+    `var host=document.querySelector('[data-flow-id='+CSS.escape(${id})+']');` +
+    `if(host&&t){host.innerHTML='';host.appendChild(t.content.cloneNode(true));` +
+    `host.removeAttribute('data-flow-streaming');}` +
+    `if(t)t.remove();s.remove();})()</script>`
+  );
+}
+
+function _escapeAttr(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}

package/src/synths/index.ts

@@ -5,7 +5,7 @@
 //   - convert it to a JSON-safe primitive + metadata object
 //   - reconstruct the original value from that primitive + metadata
 //
-// Pattern lifted directly from Livewire v3's synthesizer system.
+// The synthesizer pattern: one registered handler per non-JSON type.
 
 /**
  * A synthesizer ("synth") teaches flow how to send a non-JSON type across the
@@ -19,7 +19,7 @@
  * match's {@link dehydrate} produces the stored data and its {@link key} is
  * written to `meta.s`. On the way back, {@link key} selects the synth whose
  * {@link hydrate} reconstructs the value. `hydrate` may be async (e.g. a model
- * synth re-fetches by id). The pattern is lifted from Livewire v3's synthesizers.
+ * synth re-fetches by id).
  *
  * @typeParam T - The live value type this synth handles.
  */

package/src/testing.ts

@@ -34,7 +34,7 @@
 import type { Component } from "./Component.ts";
 import type { FlowEffects } from "./Component.ts";
 import { _renderFlowPage } from "./jsx-runtime.ts";
-import { dehydrate, hydrate } from "./dehydrate.ts";
+import { dehydrate } from "./dehydrate.ts";
 import { ValidationError } from "./validation.ts";
 import type { Snapshot } from "./types.ts";
 

package/src/types.ts

@@ -18,7 +18,7 @@ export type SnapshotData = Record<string, SnapshotTuple>;
 
 /**
  * Metadata for a child Component component embedded inside a parent's render output.
- * Stored in memo.children (excluded from HMAC signing — same as Livewire).
+ * Stored in memo.children (excluded from HMAC signing).
  * @category Snapshot
  */
 export interface ChildMemo {

package/src/uploads/FileUploads.ts

@@ -1,6 +1,6 @@
 // ── FileUploads mixin ─────────────────────────────────────────────────────────
 //
-// The TypeScript equivalent of Livewire's `WithFileUploads` trait. File uploads work
+// A mixin that adds server-side upload management. File uploads work
 // like any other input: a `<FileUpload>` / file `<input flow:model>` POSTs the bytes to
 // `/__flow/upload` (over HTTP), shows live progress, then `$set`s a signed reference
 // that the base Component resolves into a `TemporaryUploadedFile` (signature verified).
@@ -29,8 +29,7 @@ import { expose } from "../decorators.ts";
 type AbstractComponentCtor = abstract new (...args: any[]) => Component;
 
 /**
- * Component mixin that adds server-side file-upload management — flow's
- * equivalent of Livewire's `WithFileUploads` trait.
+ * Component mixin that adds server-side file-upload management.
  *
  * @remarks
  * Uploading itself needs no mixin: a `<FileUpload>` / file `<input flow:model>`
@@ -72,7 +71,7 @@ type AbstractComponentCtor = abstract new (...args: any[]) => Component;
 export function FileUploads<TBase extends AbstractComponentCtor>(Base: TBase) {
   abstract class WithUploads extends Base {
     /**
-     * Remove a pending upload (Livewire's `removeUpload`). For a single-file property it
+     * Remove a pending upload. For a single-file property it
      * clears it (null); for a multiple-file array it removes the item at `index`, or all
      * when `index` is omitted.
      *

package/src/uploads/TemporaryUploadedFile.ts

@@ -82,7 +82,7 @@ async function disk(name?: string): Promise<Disk> {
 }
 
 /**
- * A Livewire-style temporary uploaded file — the server-side handle a component
+ * A temporary uploaded file — the server-side handle a component
  * receives for a pending upload before it's promoted to permanent storage.
  *
  * @remarks