@zerotal/flow 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -11,6 +11,63 @@ change.
 
 ## [Unreleased]
 
+## [1.9.0] — 2026-08-29
+
+- **The component and flash types are documented.** Every built-in component exports the type of
+  its own props — `ModalProps`, `ForProps`, `VirtualizeProps` and eighteen more — and none was
+  named anywhere a reader would look, though wrapping a component is the usual reason to want
+  one. The flash API's shapes are documented alongside them: `FlashBuilder` and the eight types
+  around it, for a helper that composes a message rather than writing one inline.
+
+### Changed
+
+- **INTERNAL: 35 exports are marked `@internal`.** The compiler's output helpers (`__esc`,
+  `__escAttr`, `jsLiteral`), the URL-safety internals, the wire-protocol frame types
+  (`PatchFrame`, `EventFrame`, `RedirectFrame`, …), the registration functions, the durable and
+  shared store accessors, and `FlowBrowser`'s Chrome discovery.
+
+  **Nothing is removed and nothing breaks.** The frame types are the clearest case: they
+  describe what crosses the socket, an app never constructs one, and naming them in the promised
+  surface implied a stability guarantee about a protocol that is free to change.
+
+- **A bound field the model will not accept now says so.** `flow:model` on a column missing from
+  `fillable` was dropped in silence: the form submitted, nothing was written, nothing failed, and
+  there was no clue. The drop stays — the same path receives whatever a browser sends, so an
+  unknown key must not write a column and must not be able to 500 the page — but a developer's
+  typo produced exactly the same silence as a hostile payload. In development it now warns once
+  per class per field, naming the field, the current `fillable`, and both ways to fix it.
+
+- **The client entries are held to the `@zerotal/orm` boundary.** Every orm import in this
+  package is `import type` — deliberately, because a root import once dragged
+  `await import("bun")` into a browser bundle and broke it at _resolution_ time, before
+  tree-shaking could drop it. One exception exists: `ModelSynth` imports a value. It is safe only
+  because no client entry reaches a synth, and that condition had been verified by hand, once,
+  with nothing holding it. A test now walks the import graph from each client entry and fails
+  naming the module that crossed.
+
+- **The plain-form enhancement bundle is built on first request, not at boot.** Most apps never
+  serve a page that uses `<form data-enhance>`, so building it at boot spends time on an artefact
+  nobody asked for, in every process.
+
+### Added
+
+- **`<form data-enhance>` — plain-form enhancement, no component required.** A page that is
+  just server-rendered HTML can now have a form that submits without the page flashing: it
+  posts through `fetch` and the matching form in the response replaces it in place, so a
+  validation error lands where the person is looking and nothing else on the page moves.
+
+  Delivered as its own dependency-free bundle at `/__flow/enhance.js`, because the whole point
+  is a page with no Flow component on it — such a page is never served `/__flow/runtime.js`,
+  and pulling Alpine and a WebSocket bridge onto it would be paying the framework's entire
+  client cost for a submit handler. Add it with `flowEnhanceTag()` in a non-Flow layout.
+
+  Every path degrades: a network failure re-submits natively rather than losing what was
+  typed, a redirect is followed and `pushState`d so the address bar agrees, and no JavaScript
+  at all is an ordinary form post — `data-enhance` is additive on a form that already works,
+  so there is no fallback path that can rot.
+
+  This completes ACTION 8, whose other two items turned out to be already shipped.
+
 ## [1.8.0] — 2026-08-24
 
 ### Added

package/api-surface.md

@@ -174,9 +174,7 @@ class WebSocketDisconnected = {
   readonly url: string
 }
 
-const BLOCKED_URL = 'about:blank'
-
-const DEFAULT_PERSISTENT_MIDDLEWARE = (string | MiddlewareClass)[]
+const FLOW_ENHANCE_PATH = '/__flow/enhance.js'
 
 const locked = (value: unknown, context: ClassFieldDecoratorContext) => void
 
@@ -186,8 +184,6 @@ const reactive = (value: unknown, context: ClassFieldDecoratorContext) => void
 
 const transient = (value: unknown, context: ClassFieldDecoratorContext) => void
 
-const URL_ATTRIBUTES = ReadonlySet<string>
-
 function Accordion = (props: AccordionProps) => HtmlNode
 
 function Alert = (props: AlertProps) => HtmlNode
@@ -230,26 +226,16 @@ function Flash = (props?: FlashProps) => HtmlNode
 
 function flow = <T>(target: T) => FlowChain<T>
 
-function flowActiveConnections = () => number
-
 function FlowConfig = (options?: Partial<FlowConfigShape>) => FlowConfigShape
 
-function flowConnections = () => FlowConnection[]
+function flowEnhanceTag = () => string
 
 function For = <T>(props: ForProps<T>) => HtmlNode
 
-function getDurableStore = () => DurableStore
-
-function getSharedStore = () => SharedStore
-
 function Head = (props: {    children?: unknown;}) => HtmlNode
 
 function InfiniteScroll = (props: InfiniteScrollProps) => HtmlNode
 
-function isSafeUrl = (url: string) => boolean
-
-function jsLiteral = (value: unknown) => string
-
 function Label = (props: LabelProps) => HtmlNode
 
 function Legend = (props: LegendProps) => HtmlNode
@@ -280,18 +266,10 @@ function presence = (channel: PresenceChannel) => (value: unknown, context: Clas
 
 function RadioGroup = (props: RadioGroupProps) => HtmlNode
 
-function registerComponent = (PageClass: typeof Component, path?: string) => void
-
 function registerFlowEvent = <K extends EventName>(name: K, guard: (payload: unknown) => payload is FlowEvents[K]) => void
 
-function registerForm = (FormClass: new () => Form) => void
-
-function registerSynth = (synth: Synth) => void
-
 function renderless = (_fn: unknown, context: ClassMethodDecoratorContext) => void
 
-function sanitizeUrl = (url: string) => string
-
 function SectionContent = (props: SectionContentProps) => HtmlNode
 
 function SectionOutlet = (props: SectionOutletProps) => HtmlNode
@@ -371,15 +349,6 @@ interface CalendarProps = {
   weekdayClass?: string
 }
 
-interface CallFrame = {
-  args: unknown[]
-  component: string
-  method: string
-  snapshot: Snapshot
-  type: 'call'
-  updates: Record<string, unknown>
-}
-
 interface CheckboxProps = {
   [key: string]: unknown
   bind: unknown
@@ -387,12 +356,6 @@ interface CheckboxProps = {
   class?: string
 }
 
-interface ChildMemo = {
-  id: string
-  key: string
-  name: string
-}
-
 interface ComboboxOption = {
   label: string
   value: string | number
@@ -440,13 +403,6 @@ interface DisclosureProps = {
   trigger?: unknown
 }
 
-interface DownloadFrame = {
-  content: string
-  filename: string
-  mime: string
-  type: 'download'
-}
-
 interface DrawerProps = {
   [key: string]: unknown
   children?: unknown
@@ -469,12 +425,6 @@ interface DropdownProps = {
   trigger?: unknown
 }
 
-interface DurableStore = {
-  delete: (key: string) => Promise<void> | void
-  get: (key: string) => Promise<Snapshot | undefined> | Snapshot | undefined
-  set: (key: string, value: Snapshot, ttlMs?: number) => Promise<void> | void
-}
-
 interface ErrorBoundaryProps = {
   [key: string]: unknown
   children?: unknown
@@ -484,15 +434,6 @@ interface ErrorBoundaryProps = {
   tag?: string
 }
 
-interface ErrorFrame = {
-  action?: string
-  component: string
-  message: string
-  name?: string
-  stack?: string
-  type: 'error'
-}
-
 interface ErrorProps = {
   [key: string]: unknown
   class?: string
@@ -505,20 +446,6 @@ interface ErrorsProps = {
   only?: string | string[]
 }
 
-interface ErrorsProxy = {
-  [key: string]: ErrorField | ((...args: never[]) => unknown)
-  add: {    (field: string, message: string): void;    (errors: Record<string, string | string[]>): void;}
-  any: () => boolean
-  clear: (field?: string) => void
-  has: (field: string) => boolean
-}
-
-interface EventFrame = {
-  data: Record<string, unknown>
-  name: string
-  type: 'event'
-}
-
 interface FieldProps = {
   [key: string]: unknown
   children?: unknown
@@ -583,20 +510,6 @@ interface FlashCallback = {
   method: string
 }
 
-interface FlashFrame = {
-  actions?: FlashAction[]
-  dismissible?: boolean
-  duration?: number
-  icon?: string | false
-  level: 'success' | 'error' | 'warning' | 'info'
-  message: string
-  onClose?: FlashCallback
-  position?: FlashPosition
-  progressBar?: boolean
-  title?: string
-  type: 'flash'
-}
-
 interface FlashMessage = {
   actions?: FlashAction[]
   dismissible?: boolean
@@ -658,26 +571,6 @@ interface FlowConfigShape = {
   persistentMiddleware: (string | MiddlewareClass)[]
 }
 
-interface FlowConnection = {
-  actions: number
-  connectedAt: number
-  id: string
-  ip: string
-  lastActivityAt: number
-  user: string | null
-}
-
-interface FlowEffects = {
-  downloads: {    filename: string;    content: string;    mime: string;}[]
-  errors: Record<string, string[]>
-  events: {    name: string;    data: Record<string, unknown>;    to?: string;    self?: boolean;}[]
-  flashes: FlashMessage[]
-  redirectUrl: string | null
-  scripts: string[]
-  shouldRefresh: boolean
-  title: string | null
-}
-
 interface FlowEvents = {}
 
 interface FlowStore = {}
@@ -757,16 +650,6 @@ interface ModalProps = {
   title?: unknown
 }
 
-interface PageClassWithMeta = {
-  new (): Component
-  head?: string
-  interactive?: boolean
-  layout?: new () => Layout
-  models?: Record<string, typeof BaseModel>
-  name: string
-  title?: string | ((component: never) => string)
-}
-
 interface PagerProps = {
   [key: string]: unknown
   activeClass?: string
@@ -792,22 +675,6 @@ interface Paginator = {
   total: number
 }
 
-interface PatchFrame = {
-  actionError?: boolean
-  checksum?: string
-  component: string
-  dataDelta?: SnapshotData
-  dataRemoved?: string[]
-  errors?: Record<string, string[]>
-  html?: string
-  memo?: SnapshotMemo
-  partial?: boolean
-  scripts?: string[]
-  snapshot?: Snapshot
-  title?: string
-  type: 'patch'
-}
-
 interface PopoverProps = {
   [key: string]: unknown
   buttonClass?: string
@@ -844,12 +711,6 @@ interface RedirectFlash = {
   withWarning: (message: string) => RedirectFlash
 }
 
-interface RedirectFrame = {
-  sessionToken?: string
-  type: 'redirect'
-  url: string
-}
-
 interface SectionContentProps = {
   children?: unknown
   name: string
@@ -878,12 +739,6 @@ interface SessionOptions = {
   scoped?: boolean
 }
 
-interface SharedStore = {
-  get: (key: string) => unknown | undefined
-  has: (key: string) => boolean
-  set: (key: string, value: unknown) => void
-}
-
 interface SkeletonProps = {
   [key: string]: unknown
   class?: string
@@ -913,19 +768,6 @@ interface Snapshot = {
   memo: SnapshotMemo
 }
 
-interface SnapshotMemo = {
-  children: string[]
-  iat?: number | undefined
-  id: string
-  listeners?: Record<string, string> | undefined
-  name: string
-  path: string
-  presence?: {    prop: string;    channel: string;}[] | undefined
-  shared?: {    prop: string;    channel: string;}[] | undefined
-  slots?: Record<string, string> | undefined
-  sub?: string | undefined
-}
-
 interface SwitchProps = {
   [key: string]: unknown
   bind: unknown
@@ -933,13 +775,6 @@ interface SwitchProps = {
   class?: string
 }
 
-interface Synth = {
-  dehydrate: (value: T, meta: Record<string, unknown>) => unknown
-  hydrate: (data: unknown, meta: Record<string, unknown>) => T | Promise<T>
-  key: string
-  match: (value: unknown) => value is T
-}
-
 interface TabItem = {
   content: unknown
   label: unknown
@@ -1048,10 +883,6 @@ type Mixin = (Base: TIn) => TOut
 
 type PresenceChannel = string | ((self: Record<string, any>) => string)
 
-type SharedChannel = string | ((self: Record<string, any>) => string)
-
-type SnapshotData = {    [x: string]: SnapshotTuple;}
-
 type ValidationRules = {    [x: string]: (rule: RuleBuilder) => FieldRule;}
 
 ## ./browser  `(./src/browser/index.ts)`
@@ -1076,18 +907,9 @@ class FlowBrowser = {
   waitUntil: (expression: string, label: string, timeoutMs?: number) => Promise<void>
 }
 
-function findChrome = () => string | null
-
-interface OpenOptions = {
-  timeout?: number
-  waitForConnection?: boolean
-}
-
 ## ./compiler-helpers  `(./src/compiler/helpers.ts)`
 
-function __esc = (v: unknown) => string
-
-function __escAttr = (v: unknown) => string
+_(no exports)_
 
 ## ./store  `(./src/store.ts)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/flow",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -47,15 +47,15 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/client": "1.8.0",
-    "@zerotal/core": "1.8.0",
-    "@zerotal/orm": "1.8.0",
-    "@zerotal/validator": "1.8.0",
+    "@zerotal/client": "1.9.0",
+    "@zerotal/core": "1.9.0",
+    "@zerotal/orm": "1.9.0",
+    "@zerotal/validator": "1.9.0",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.8.0",
+    "@zerotal/broadcasting": "1.9.0",
     "@types/alpinejs": "^3.13.10",
     "@types/alpinejs__anchor": "^3.13.1",
     "@types/alpinejs__collapse": "^3.13.4",

package/src/Component.ts

@@ -68,6 +68,7 @@ export class ErrorField {
 //   this.errors.has("field")   → boolean
 //   this.errors.field          → ErrorField (for error={this.errors.field})
 
+/** @internal */
 export interface ErrorsProxy {
   /** True when the given field has at least one error. */
   has(field: string): boolean;
@@ -265,6 +266,8 @@ function _autoChildKey(
  * The bag of side effects an action queued (flashes, a redirect, client scripts, events,
  * downloads, a title, and the current error bag). Drained by {@link Component._drainEffects}
  * and read by the WebSocket handler to build the response frames sent to the client.
+ *
+ * @internal
  */
 export interface FlowEffects {
   flashes: FlashMessage[];

package/src/Form.ts

@@ -29,7 +29,11 @@ import type { FieldRule, Schema } from "@zerotal/validator";
 /** Registry of Form subclasses by name, used to reconstruct forms on hydration. */
 const _formClasses = new Map<string, new () => Form>();
 
-/** Register a Form subclass so it can be rebuilt from a snapshot. Called automatically. */
+/**
+ * Register a Form subclass so it can be rebuilt from a snapshot. Called automatically.
+ *
+ * @internal
+ */
 export function registerForm(FormClass: new () => Form): void {
   _formClasses.set(FormClass.name, FormClass);
 }

package/src/browser/FlowBrowser.ts

@@ -29,6 +29,7 @@ import { CdpSession, findChrome, launchBrowser, type LaunchedBrowser } from "./c
 /** How long to wait for a condition driven by a server round-trip. */
 const DEFAULT_TIMEOUT_MS = 10_000;
 
+/** @internal */
 export interface OpenOptions {
   /** Milliseconds to wait for the page to load and Flow to connect. */
   timeout?: number;

package/src/browser/cdp.ts

@@ -42,6 +42,8 @@ const CHROME_PATHS: Record<string, string[]> = {
  * Returning `null` rather than throwing lets a suite skip itself on a machine
  * without a browser instead of failing — a browser test that cannot run is not
  * the same as one that failed.
+ *
+ * @internal
  */
 export function findChrome(): string | null {
   const override = Bun.env["CHROME_PATH"];

package/src/client/enhance.ts

@@ -0,0 +1,205 @@
+// ── @zerotal/flow plain-form enhancement bundle ─────────────────────────────────
+//
+// The entry point for the second Bun.build() in FlowProvider.onBooting(). It
+// produces /__flow/enhance.js.
+//
+// **Deliberately separate from the runtime bundle, and deliberately tiny.** The
+// whole point of this feature is a page with *no Flow component on it* — an
+// ordinary server-rendered form, on a route that is not `Router.flow`. Such a page
+// is never served `/__flow/runtime.js`, so there is no script to hook into; and
+// pulling Alpine and the WebSocket bridge onto a page with no component to drive
+// would be paying the entire framework's client cost for a submit handler.
+//
+// **This file exports nothing, and must not.** It is loaded as a classic script,
+// where a trailing `export` statement is a SyntaxError that discards the whole
+// bundle — silently, because the forms then post natively and the page still
+// works. The decisions worth testing live in `enhanceSupport.ts`, which Bun inlines
+// back in at build time.
+//
+// ## The contract
+//
+//   <form method="post" action="/subscribe" data-enhance>
+//
+// The form posts through `fetch`, and the matching form in the response replaces
+// this one in place. Validation errors then appear where they belong and the rest
+// of the page is untouched — no flash, no scroll loss, no re-render of a page that
+// did not change.
+//
+// Everything about it degrades:
+//
+//   - **No JavaScript is an ordinary post.** `data-enhance` is additive on a form
+//     that already has `method` and `action`, so the no-JS path is not a fallback
+//     that was written and might rot — it is the form itself, unmodified. If that
+//     is ever not free, the word "enhancement" is doing no work.
+//   - **A network failure re-submits natively.** The difference between a bad
+//     connection being slow and a bad connection losing what somebody typed.
+//   - **A redirect is followed**, its document swapped in and `pushState`d, so the
+//     address bar agrees with the page.
+
+import { ATTR, BUSY_ATTR, matchIn, sameUrl, targetFor } from "./enhanceSupport.ts";
+
+/**
+ * Move focus back to where it was before the swap.
+ *
+ * Replacing a subtree destroys the focused element, and a form that reports "this
+ * field is required" having just taken the cursor away from that field is worse
+ * than one that did not enhance at all. Matched by `name`, which survives a
+ * re-render in a way a DOM node cannot.
+ */
+function restoreFocus(root: Element, name: string | null, start: number | null): void {
+  if (!name) return;
+  const next = root.querySelector<HTMLInputElement>(`[name="${CSS.escape(name)}"]`);
+  if (!next) return;
+  next.focus();
+  if (start === null) return;
+  try {
+    next.setSelectionRange(start, start);
+  } catch {
+    // Not a text-like control (checkbox, select, file) — focus alone is the job.
+  }
+}
+
+/**
+ * Submit the form the way the browser would have, with the enhancement out of the
+ * way so this handler does not catch its own fallback.
+ */
+function nativeSubmit(form: HTMLFormElement, submitter: HTMLElement | null): void {
+  form.removeAttribute(ATTR);
+  if (submitter && "click" in submitter) {
+    // Through the submitter, so a named button still contributes its value.
+    submitter.click();
+    return;
+  }
+  form.submit();
+}
+
+/**
+ * Handle one enhanced submission.
+ *
+ * Throws nothing: every failure path either falls back to a native submit or
+ * leaves the page exactly as it was.
+ */
+async function submitEnhanced(form: HTMLFormElement, submitter: HTMLElement | null): Promise<void> {
+  const method = (form.getAttribute("method") || "get").toUpperCase();
+  const action = form.getAttribute("action") || window.location.href;
+
+  // `new FormData(form, submitter)` includes the button that was actually pressed,
+  // which is how `<button name="intent" value="delete">` tells the server which one.
+  const data = new FormData(form, submitter as HTMLButtonElement | null);
+
+  let url = action;
+  let body: FormData | null = data;
+  if (method === "GET") {
+    // A GET form carries its fields in the query string, not a body.
+    const query = new URLSearchParams();
+    for (const [key, value] of data.entries()) {
+      if (typeof value === "string") query.append(key, value);
+    }
+    const separator = action.includes("?") ? "&" : "?";
+    url = query.toString() ? `${action}${separator}${query}` : action;
+    body = null;
+  }
+
+  const target = targetFor(form, document, (selector) =>
+    console.warn(`[flow] data-enhance-target="${selector}" matched nothing; replacing the form.`),
+  );
+
+  const active = document.activeElement as HTMLInputElement | null;
+  const focusedName = active && form.contains(active) ? active.getAttribute("name") : null;
+  const caret = (() => {
+    try {
+      return active?.selectionStart ?? null;
+    } catch {
+      return null;
+    }
+  })();
+
+  form.setAttribute(BUSY_ATTR, "");
+
+  let response: Response;
+  let html: string;
+  try {
+    response = await fetch(url, {
+      method,
+      ...(body ? { body } : {}),
+      credentials: "same-origin",
+      redirect: "follow",
+      headers: { "X-Flow-Enhance": "1", Accept: "text/html" },
+    });
+    html = await response.text();
+  } catch {
+    // The network, not the server. Hand the submission back to the browser, which
+    // shows its own error and — crucially — has not lost the form data.
+    form.removeAttribute(BUSY_ATTR);
+    nativeSubmit(form, submitter);
+    return;
+  }
+
+  const parsed = new DOMParser().parseFromString(html, "text/html");
+
+  // `fetch` followed the redirect for us, so a changed URL means the server sent us
+  // somewhere. Swap the whole document and record the move, or the address bar
+  // keeps claiming we are on the page that did the posting.
+  if (response.redirected || !sameUrl(response.url, url, window.location.href)) {
+    document.documentElement.replaceWith(document.importNode(parsed.documentElement, true));
+    window.history.pushState({}, "", response.url);
+    window.dispatchEvent(new CustomEvent("flow:enhanced", { detail: { navigated: true } }));
+    return;
+  }
+
+  const replacement = matchIn(parsed, document, form, target);
+  if (!replacement) {
+    // The response has no counterpart for what we were going to replace — the page
+    // changed shape. Guessing would put arbitrary markup somewhere arbitrary; a
+    // full navigation is the honest answer.
+    window.location.href = response.url || url;
+    return;
+  }
+
+  const adopted = document.importNode(replacement, true);
+  target.replaceWith(adopted);
+  adopted.removeAttribute(BUSY_ATTR);
+  restoreFocus(adopted, focusedName, caret);
+  window.dispatchEvent(
+    new CustomEvent("flow:enhanced", { detail: { navigated: false, status: response.status } }),
+  );
+}
+
+/**
+ * One delegated listener on the document, for every enhanced form that exists now
+ * or is added later.
+ *
+ * Delegation rather than per-form binding because the swap above replaces forms
+ * with fresh nodes: anything bound directly would be discarded by the first
+ * successful submission, and the second one would post natively for no visible
+ * reason.
+ */
+function install(): void {
+  document.addEventListener(
+    "submit",
+    (event) => {
+      const form = (event.target as HTMLElement | null)?.closest?.(`form[${ATTR}]`) as
+        HTMLFormElement | null | undefined;
+      if (!form) return;
+      // Let a default-prevented submit stay prevented; another handler owns it.
+      if (event.defaultPrevented) return;
+      // An explicit opt-out on a form that carries the attribute for styling.
+      if (form.getAttribute(ATTR) === "false") return;
+      // A submission already in flight: drop the second rather than racing two
+      // responses into the same target.
+      if (form.hasAttribute(BUSY_ATTR)) {
+        event.preventDefault();
+        return;
+      }
+
+      event.preventDefault();
+      void submitEnhanced(form, (event as SubmitEvent).submitter);
+    },
+    // Bubble phase: a component's own handler gets to preventDefault first.
+    false,
+  );
+}
+
+if (typeof document !== "undefined") {
+  install();
+}

package/src/client/enhanceSupport.ts

@@ -0,0 +1,99 @@
+/**
+ * The parts of the plain-form enhancement that are decisions rather than effects.
+ *
+ * Split out of `enhance.ts` for a reason worth recording. That file is served as a
+ * **classic script** — `<script src="/__flow/enhance.js" defer>` on pages that have
+ * no module loader and no framework on them. A bundle ending in an `export`
+ * statement is a `SyntaxError` in that position, and the browser discards the whole
+ * file. It does so *silently*: the forms fall back to native posts and the page
+ * still works, so the enhancement is simply absent on exactly the pages it was
+ * added for, with nothing in the console to say why.
+ *
+ * So the entry exports nothing, and everything worth asserting on lives here, where
+ * a test can import it. Bun inlines this back into the bundle at build time, so the
+ * split costs the browser nothing.
+ *
+ * @module
+ */
+
+/** Marks a form as enhanced. */
+export const ATTR = "data-enhance";
+
+/** Overrides what gets replaced: any CSS selector. */
+export const TARGET_ATTR = "data-enhance-target";
+
+/** Set on a form while its submission is in flight, for styling and re-entry guards. */
+export const BUSY_ATTR = "data-enhance-busy";
+
+/**
+ * Whether two URLs name the same place, resolved against the document.
+ *
+ * Both sides are resolved before comparing, because one of them is whatever the
+ * author wrote in `action` — usually relative — and the other is `response.url`,
+ * which `fetch` always reports absolute. Comparing them raw would call every
+ * ordinary submission a redirect.
+ */
+export function sameUrl(a: string, b: string, baseHref: string): boolean {
+  if (!a || !b) return false;
+  try {
+    return new URL(a, baseHref).href === new URL(b, baseHref).href;
+  } catch {
+    return a === b;
+  }
+}
+
+/**
+ * Where a form's response should be written.
+ *
+ * The form itself by default. That is the useful default because it is what makes
+ * validation errors land where the person is looking without the page author
+ * naming anything — and because the form is the one element guaranteed to exist in
+ * the response, given the server just re-rendered it.
+ *
+ * @param onMissing - Called when `data-enhance-target` matches nothing.
+ */
+export function targetFor(
+  form: HTMLFormElement,
+  root: ParentNode,
+  onMissing: (selector: string) => void,
+): Element {
+  const selector = form.getAttribute(TARGET_ATTR);
+  if (!selector) return form;
+  const found = root.querySelector(selector);
+  if (found) return found;
+  // A selector matching nothing is an authoring mistake. Swapping the form instead
+  // is both harmless and visible: the page still works and the console says why it
+  // did not do what was asked.
+  onMissing(selector);
+  return form;
+}
+
+/**
+ * Find, in a freshly parsed response document, the element corresponding to
+ * `target` in the live one.
+ *
+ * Identity is by `id` when there is one, then by the selector the author gave, then
+ * — for a bare `<form data-enhance>` — by position among the enhanced forms on the
+ * page. The positional fallback is what lets the simplest possible usage work with
+ * no attributes at all, and it is why `id` is tried first: two forms that change
+ * order between renders would otherwise swap content.
+ */
+export function matchIn(
+  doc: Document,
+  live: ParentNode,
+  form: HTMLFormElement,
+  target: Element,
+): Element | null {
+  if (target.id) {
+    const byId = doc.getElementById(target.id);
+    if (byId) return byId;
+  }
+
+  const selector = form.getAttribute(TARGET_ATTR);
+  if (selector) return doc.querySelector(selector);
+
+  const forms = Array.from(live.querySelectorAll(`form[${ATTR}]`));
+  const index = forms.indexOf(form);
+  const candidates = doc.querySelectorAll(`form[${ATTR}]`);
+  return index >= 0 ? (candidates[index] ?? null) : (candidates[0] ?? null);
+}

package/src/compiler/helpers.ts

@@ -13,13 +13,21 @@
  * @packageDocumentation
  */
 
-/** Escape a value for safe injection as HTML text content. */
+/**
+ * Escape a value for safe injection as HTML text content.
+ *
+ * @internal
+ */
 export function __esc(v: unknown): string {
   if (v == null || v === false || v === true) return "";
   return String(v).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-/** Escape a value for safe injection inside an HTML attribute (double-quoted). */
+/**
+ * Escape a value for safe injection inside an HTML attribute (double-quoted).
+ *
+ * @internal
+ */
 export function __escAttr(v: unknown): string {
   if (v == null) return "";
   return String(v).replace(/&/g, "&amp;").replace(/"/g, "&quot;");

package/src/config.ts

@@ -23,7 +23,11 @@ export interface FlowConfigShape {
   persistentMiddleware: (string | MiddlewareClass)[];
 }
 
-/** Global middleware re-run on every WebSocket action unless overridden. */
+/**
+ * Global middleware re-run on every WebSocket action unless overridden.
+ *
+ * @internal
+ */
 export const DEFAULT_PERSISTENT_MIDDLEWARE: (string | MiddlewareClass)[] = [
   "SessionMiddleware",
   "PersistUserMiddleware",

package/src/decorators.ts

@@ -732,6 +732,8 @@ export function resolvePresenceChannel(channel: PresenceChannel, instance: objec
  * component instance to compute a per-instance name (for dynamic rooms).
  *
  * @category Realtime
+ *
+ * @internal
  */
 export type SharedChannel = string | ((self: Record<string, any>) => string);
 

package/src/durable.ts

@@ -66,6 +66,8 @@ interface DurableConfig {
  * `@zerotal/cache`/Redis) via {@link setDurableStore} to also survive redeploys.
  * Methods may be sync or async; a swapped store is responsible for its own TTL
  * eviction (the `ttlMs` hint is passed to {@link DurableStore.set | set}).
+ *
+ * @internal
  */
 export interface DurableStore {
   /** Fetch a stored snapshot by key, or `undefined` if absent/expired. */
@@ -130,6 +132,8 @@ export function setDurableStore(store: DurableStore): void {
  * inspects persisted snapshots directly.
  *
  * @returns The current {@link DurableStore}.
+ *
+ * @internal
  */
 export function getDurableStore(): DurableStore {
   return _store;

package/src/enhanceTag.ts

@@ -0,0 +1,36 @@
+/**
+ * The one line an app's layout needs for `<form data-enhance>` to work.
+ *
+ * A helper rather than a documented string, for the reason a sibling feature
+ * already learned the hard way: a resource nothing links is a resource nobody
+ * discovers is missing. A page whose layout forgot the tag does not fail — the
+ * forms simply post the way they always did, and the enhancement is silently
+ * absent on exactly the pages it was added for.
+ *
+ * @module
+ */
+
+/** The path `FlowProvider` serves the enhancement bundle at. */
+export const FLOW_ENHANCE_PATH = "/__flow/enhance.js";
+
+/**
+ * A `<script>` tag loading the plain-form enhancement.
+ *
+ * Put it in the layout that renders your non-Flow pages. Flow pages already get
+ * `/__flow/runtime.js`, which does not include this — the two are separate because
+ * the enhancement exists for pages that have no Flow component to run a runtime.
+ *
+ * `defer` so it never blocks the parse, and the listener is delegated on
+ * `document`, so a form that appears later is picked up without re-running
+ * anything.
+ *
+ * @example
+ * ```tsx
+ * <head>
+ *   {flowEnhanceTag()}
+ * </head>
+ * ```
+ */
+export function flowEnhanceTag(): string {
+  return `<script src="${FLOW_ENHANCE_PATH}" defer></script>`;
+}

package/src/index.ts

@@ -74,6 +74,7 @@ export type {
 // `class PostsPage extends Component.using(Pagination, …)`.
 export type { Constructor, Mixin, Compose } from "./mixins.ts";
 export { Layout } from "./Layout.ts";
+export { flowEnhanceTag, FLOW_ENHANCE_PATH } from "./enhanceTag.ts";
 export { Form, registerForm } from "./Form.ts";
 // Global client store — app-wide, client-only reactive UI state, read in JSX as
 // `$flow.$store.*`. `defineStore` declares its initial shape at app start; augment

package/src/provider/FlowProvider.ts

@@ -99,6 +99,17 @@ export function _devErrorInfo(error: unknown, action: string): DevErrorInfo {
 
 let _runtimeBundle: string | null = null;
 
+/**
+ * The `/__flow/enhance.js` bundle — the standalone plain-form enhancement.
+ *
+ * Separate from the runtime bundle on purpose. `/__flow/runtime.js` is injected
+ * only by `Router.flow` routes, and the whole point of `<form data-enhance>` is a
+ * page with no Flow component on it, which is therefore never served that script.
+ * It is also tiny and dependency-free, so an app that wants a form not to flash
+ * does not pay for Alpine and a WebSocket bridge to get it.
+ */
+let _enhanceBundle: string | null = null;
+
 /**
  * CSP-safe mode flag (no 'unsafe-eval'). Set `flow.cspSafe` in `config/flow.ts`,
  * or the ZT_FLOW_CSP_SAFE / APP_CSP_SAFE env flag when there is no config file.
@@ -113,6 +124,51 @@ export function _runtimeJs(): string | null {
   return _runtimeBundle;
 }
 
+/** @internal — the built plain-form enhancement bundle, or null when it failed to build. */
+export function _enhanceJs(): string | null {
+  return _enhanceBundle;
+}
+
+/** In-flight build, so concurrent first requests share one rather than racing. */
+let _enhanceBuild: Promise<string | null> | null = null;
+
+/**
+ * Build the enhancement bundle once, on first request.
+ *
+ * No CSP variant: it has no expression evaluator to swap, because it evaluates
+ * nothing — it reads attributes and calls `fetch`.
+ *
+ * @internal
+ */
+async function _buildEnhanceBundle(): Promise<string | null> {
+  if (_enhanceBundle) return _enhanceBundle;
+  // Cache the promise, not the result — two requests arriving together would
+  // otherwise both bundle.
+  _enhanceBuild ??= (async () => {
+    try {
+      const entry = fileURLToPath(new URL("../client/enhance.ts", import.meta.url));
+      const result = await Bun.build({
+        entrypoints: [entry],
+        target: "browser",
+        minify: isProdLike(deployEnv()),
+        format: "esm",
+      });
+      if (result.success && result.outputs.length > 0) {
+        _enhanceBundle = await result.outputs[0]!.text();
+        return _enhanceBundle;
+      }
+      console.warn("[Flow] Enhancement bundle build failed:", result.logs);
+    } catch (e) {
+      console.warn("[Flow] Could not build enhancement bundle:", e);
+    }
+    // A failed build is not cached: the next request tries again, which is right
+    // for a dev-time transient and harmless for a real one.
+    _enhanceBuild = null;
+    return null;
+  })();
+  return _enhanceBuild;
+}
+
 // ── Rate limiter for HMAC failures ───────────────────────────────────────────
 
 const _checksumFailures = new Map<string, { count: number; since: number }>();
@@ -1029,6 +1085,38 @@ export class FlowProvider extends ServiceProvider {
       console.warn("[Flow] Could not build client bundle:", e);
     }
 
+    // Serve the plain-form enhancement bundle. Deliberately cacheable, unlike the
+    // runtime: it carries no per-app route table, so there is nothing in it that can
+    // go stale between deploys of the same framework version.
+    //
+    // Built on first request rather than at boot. Most apps never serve a page that
+    // uses `<form data-enhance>` — it is for the pages Flow does not otherwise touch
+    // — so building it at boot spends time on an artefact nobody asks for, in every
+    // process, including every test that boots a provider.
+    Router.get(
+      "/__flow/enhance.js",
+      class FlowEnhanceHandler {
+        async handle(http: HttpContext): Promise<void> {
+          const bundle = await _buildEnhanceBundle();
+          if (!bundle) {
+            http.response = new Response("// Flow enhancement unavailable", {
+              status: 503,
+              headers: { "Content-Type": "text/javascript; charset=utf-8" },
+            });
+            return;
+          }
+          http.response = new Response(bundle, {
+            status: 200,
+            headers: {
+              "Content-Type": "text/javascript; charset=utf-8",
+              "Cache-Control": "public, max-age=3600",
+            },
+          });
+        }
+      },
+      "handle",
+    );
+
     // Serve the client-side runtime bundle
     Router.get(
       "/__flow/runtime.js",
@@ -1371,6 +1459,8 @@ let _activeConnections = 0;
  * Number of currently-open Flow (reactive SSR) WebSocket connections.
  * @returns The live count of open `/__flow/ws` connections.
  * @category Connections
+ *
+ * @internal
  */
 export function flowActiveConnections(): number {
   return _activeConnections;
@@ -1379,6 +1469,8 @@ export function flowActiveConnections(): number {
 /**
  * One currently-open Flow WebSocket client, enriched as actions identify the user.
  * @category Connections
+ *
+ * @internal
  */
 export interface FlowConnection {
   id: string;
@@ -1397,6 +1489,8 @@ const _connections = new Map<string, FlowConnection>();
  * Snapshot of currently-connected Flow clients (most-recently-active first).
  * @returns An array of {@link FlowConnection}, sorted by `lastActivityAt` descending.
  * @category Connections
+ *
+ * @internal
  */
 export function flowConnections(): FlowConnection[] {
   return [..._connections.values()].sort((a, b) => b.lastActivityAt - a.lastActivityAt);

package/src/registry.ts

@@ -56,6 +56,8 @@ export function _getPageEntries(): Map<string, PageEntry> {
  * // In a ServiceProvider's boot method:
  * registerComponent(CounterWidget);
  * ```
+ *
+ * @internal
  */
 export function registerComponent(PageClass: typeof Component, path = ""): void {
   if (!_pages.has(PageClass.name)) registerPage(path, PageClass);
@@ -103,6 +105,8 @@ export { getRenderlessMethods };
  * A Component constructor plus the optional static metadata a page class may declare
  * (`title`, `head`, `models`, `layout`). Used when resolving file-route page exports and
  * when auto-registering associated model classes.
+ *
+ * @internal
  */
 export interface PageClassWithMeta {
   new (): Component;

package/src/shared.ts

@@ -35,6 +35,8 @@ export const SHARED_EVENT = "flow:shared";
  * The default is an in-process {@link MemorySharedStore}; swap a distributed
  * implementation (e.g. Redis-backed) via {@link setSharedStore} to converge
  * across processes. Implement all three methods synchronously.
+ *
+ * @internal
  */
 export interface SharedStore {
   /** Read the current value for a `channel::prop` key, or `undefined` if unset. */
@@ -93,6 +95,8 @@ export function setSharedStore(store: SharedStore): void {
  *   @expose increment() { this.count++; } // written back + broadcast on commit
  * }
  * ```
+ *
+ * @internal
  */
 export function getSharedStore(): SharedStore {
   return _store;

package/src/synths/ModelSynth.ts

@@ -1,5 +1,6 @@
 import type { BaseModel } from "@zerotal/orm";
 import { modelsByName } from "@zerotal/orm";
+import { isProdLike, deployEnv } from "@zerotal/core";
 import { registerSynth } from "./index.ts";
 
 // Models register themselves here when their class is imported.
@@ -169,6 +170,71 @@ export function _writableFields(ModelClass: typeof BaseModel): readonly string[]
   return fields;
 }
 
+/** Model class → fields already reported, so a hundred-row list logs once. */
+const _warnedUnfillable = new WeakMap<object, Set<string>>();
+
+/**
+ * Say that a bound field was dropped, once per class per field.
+ *
+ * A `flow:model` on a column missing from `fillable` is almost always a typo or a
+ * forgotten entry, and the symptom is a form that appears to work and saves
+ * nothing. The alternative — throwing — is not available: the same path receives
+ * whatever a browser chooses to send, and a hostile payload naming an unknown key
+ * must not be able to 500 the page. So: keep dropping, and say so where the person
+ * who can fix it will see it.
+ *
+ * Keyed per class *and* per field, so a second unfillable field on the same model
+ * is still reported. Silent in production, where nobody is reading the log for
+ * this and the payload may well be hostile.
+ */
+function _warnUnfillableBinding(ModelClass: typeof BaseModel, dropped: string[]): void {
+  if (_isProductionRuntime()) return;
+
+  let seen = _warnedUnfillable.get(ModelClass);
+  if (!seen) {
+    seen = new Set<string>();
+    _warnedUnfillable.set(ModelClass, seen);
+  }
+  const fresh = dropped.filter((field) => !seen.has(field));
+  if (fresh.length === 0) return;
+  for (const field of fresh) seen.add(field);
+
+  const name = ModelClass.name || "the model";
+  const fillable = [...(ModelClass.fillable ?? [])];
+  const listed = fillable.map((f) => `"${f}"`).join(", ") || "empty";
+  console.warn(
+    `[Zerotal Flow] ${name} received ${fresh.map((f) => `\`${f}\``).join(", ")} from the ` +
+      `browser and dropped ${fresh.length === 1 ? "it" : "them"}: not in \`fillable\`, so ` +
+      `nothing was written and nothing failed.\n` +
+      `  fillable is [${listed}].\n` +
+      `  If the binding is intended, add the field:  static fillable = […, "${fresh[0]}"];\n` +
+      `  If it is not, remove the flow:model — mass assignment is the reason this list exists.`,
+  );
+}
+
+/**
+ * Forget what has been warned about, for one model class. Tests.
+ *
+ * A `WeakMap` has no `clear()`, and it does not need one here: every key a test
+ * seeds is a class the test itself owns, and dropping that one entry is the whole
+ * reset. Classes from other tests are unreachable by then.
+ *
+ * @internal
+ */
+export function _resetUnfillableWarnings(ModelClass: object): void {
+  _warnedUnfillable.delete(ModelClass);
+}
+
+/**
+ * Whether this process is a production deployment.
+ *
+ * `deployEnv()`, not `APP_ENV` — the latter holds the runtime mode once the app
+ * has booted, so reading it answered "no" on every production server.
+ */
+function _isProductionRuntime(): boolean {
+  return isProdLike(deployEnv()) || Bun.env["NODE_ENV"] === "production";
+}
+
 /**
  * Whether a value is an instance of a model registered with {@link registerFlowModel}.
  *
@@ -266,12 +332,22 @@ export function _restoreSnapshotValues(model: object, data: unknown): void {
 export function _applyWireValues(model: object, data: unknown): void {
   if (data === null || typeof data !== "object" || Array.isArray(data)) return;
 
-  const allowed = new Set(_writableFields(model.constructor as typeof BaseModel));
+  const ModelClass = model.constructor as typeof BaseModel;
+  const allowed = new Set(_writableFields(ModelClass));
   const incoming: Record<string, unknown> = {};
+  const dropped: string[] = [];
   for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
     if (allowed.has(key)) incoming[key] = value;
+    else dropped.push(key);
   }
 
+  // Dropping is right — a hostile payload must not become a 500, and it must not
+  // write a column nobody allowed. What was wrong is that it happened in silence:
+  // bind a field that is not `fillable` and there is no write, no error and no
+  // clue, which is the failure shape this project's own severity key calls the
+  // worst kind. Development only, once per class and field.
+  if (dropped.length > 0) _warnUnfillableBinding(ModelClass, dropped);
+
   if (Object.keys(incoming).length === 0) return;
 
   // `fill` is typed `UpdatePayload<this>`, which cannot be expressed for a model this

package/src/synths/index.ts

@@ -22,6 +22,8 @@
  * synth re-fetches by id).
  *
  * @typeParam T - The live value type this synth handles.
+ *
+ * @internal
  */
 export interface Synth<T = unknown> {
   /** Short tag stored as `meta.s` in the snapshot, e.g. `'cbn'`, `'mdl'`. */
@@ -54,6 +56,8 @@ const _synths: Synth[] = [];
  *   hydrate: (data, meta) => new Money(data as number, meta.cur as string),
  * });
  * ```
+ *
+ * @internal
  */
 export function registerSynth(synth: Synth): void {
   _synths.unshift(synth); // user-registered synths take priority

package/src/types.ts

@@ -13,6 +13,8 @@ export type SnapshotTuple = [data: unknown, meta: Record<string, unknown>];
 /**
  * The "data" map inside a snapshot: `propertyName → [value, meta]`.
  * @category Snapshot
+ *
+ * @internal
  */
 export type SnapshotData = Record<string, SnapshotTuple>;
 
@@ -20,6 +22,8 @@ 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).
  * @category Snapshot
+ *
+ * @internal
  */
 export interface ChildMemo {
   /** The JSX `key` prop that identifies this slot in the parent's template. */
@@ -33,6 +37,8 @@ export interface ChildMemo {
 /**
  * Component identity / routing metadata embedded in the snapshot.
  * @category Snapshot
+ *
+ * @internal
  */
 export interface SnapshotMemo {
   id: string;
@@ -92,6 +98,8 @@ export interface Snapshot {
 /**
  * Outbound WS frame sent by the client to the server.
  * @category Frames
+ *
+ * @internal
  */
 export interface CallFrame {
   type: "call";
@@ -112,6 +120,8 @@ export interface CallFrame {
  * legacy `snapshot` field remains as a full fallback. `html` is omitted when the
  * re-render is byte-identical to the last patch on this connection (HTML suppression).
  * @category Frames
+ *
+ * @internal
  */
 export interface PatchFrame {
   type: "patch";
@@ -215,6 +225,8 @@ export interface FlashMessage {
 /**
  * Flash notification frame.
  * @category Frames
+ *
+ * @internal
  */
 export interface FlashFrame extends FlashMessage {
   type: "flash";
@@ -223,6 +235,8 @@ export interface FlashFrame extends FlashMessage {
 /**
  * Programmatic redirect frame.
  * @category Frames
+ *
+ * @internal
  */
 export interface RedirectFrame {
   type: "redirect";
@@ -233,6 +247,8 @@ export interface RedirectFrame {
 /**
  * Error frame (action threw, onError ran).
  * @category Frames
+ *
+ * @internal
  */
 export interface ErrorFrame {
   type: "error";
@@ -261,6 +277,8 @@ export interface StreamFrame {
 /**
  * Cross-component event frame.
  * @category Frames
+ *
+ * @internal
  */
 export interface EventFrame {
   type: "event";
@@ -271,6 +289,8 @@ export interface EventFrame {
 /**
  * File download frame.
  * @category Frames
+ *
+ * @internal
  */
 export interface DownloadFrame {
   type: "download";

package/src/utils.ts

@@ -40,6 +40,8 @@ export function toScriptJson(value: unknown): string {
  *
  * @example
  * "x-on:click": `tab = ${jsLiteral(name)}`   // tab = "my-tab"
+ *
+ * @internal
  */
 export function jsLiteral(value: unknown): string {
   return JSON.stringify(String(value));