@zerotal/flow 1.8.1 → 1.10.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
@@ -611,16 +524,16 @@ interface FlashMessage = {
 }
 
 interface FlashOptions = {
-  actions?: FlashAction[]
-  dismissible?: boolean
-  duration?: number
-  icon?: string | false
-  level?: 'success' | 'error' | 'warning' | 'info'
-  onClose?: FlashCallback
-  position?: FlashPosition
-  progressBar?: boolean
-  title?: string
-  type?: 'success' | 'error' | 'warning' | 'info'
+  actions?: FlashAction[] | undefined
+  dismissible?: boolean | undefined
+  duration?: number | undefined
+  icon?: string | false | undefined
+  level?: 'success' | 'error' | 'warning' | 'info' | undefined
+  onClose?: FlashCallback | undefined
+  position?: FlashPosition | undefined
+  progressBar?: boolean | undefined
+  title?: string | undefined
+  type?: 'success' | 'error' | 'warning' | 'info' | undefined
 }
 
 interface FlashProps = {
@@ -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
@@ -874,14 +735,8 @@ interface SelectProps = {
 }
 
 interface SessionOptions = {
-  key?: string
-  scoped?: boolean
-}
-
-interface SharedStore = {
-  get: (key: string) => unknown | undefined
-  has: (key: string) => boolean
-  set: (key: string, value: unknown) => void
+  key?: string | undefined
+  scoped?: boolean | undefined
 }
 
 interface SkeletonProps = {
@@ -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
@@ -1010,8 +845,8 @@ interface UploadRef = {
 }
 
 interface UrlOptions = {
-  as?: string
-  history?: 'replace' | 'push'
+  as?: string | undefined
+  history?: 'replace' | 'push' | undefined
 }
 
 interface VirtualizeProps = {
@@ -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.1",
+  "version": "1.10.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.1",
-    "@zerotal/core": "1.8.1",
-    "@zerotal/orm": "1.8.1",
-    "@zerotal/validator": "1.8.1",
+    "@zerotal/client": "1.10.0",
+    "@zerotal/core": "1.10.0",
+    "@zerotal/orm": "1.10.0",
+    "@zerotal/validator": "1.10.0",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.8.1",
+    "@zerotal/broadcasting": "1.10.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[];
@@ -303,21 +306,21 @@ export interface RedirectFlash {
  * for `level` (Tailwind/Notyf parlance).
  */
 export interface FlashOptions {
-  level?: FlashLevel;
+  level?: FlashLevel | undefined;
   /** Alias for `level`. */
-  type?: FlashLevel;
-  title?: string;
-  position?: FlashPosition;
+  type?: FlashLevel | undefined;
+  title?: string | undefined;
+  position?: FlashPosition | undefined;
   /** Auto-dismiss after N ms. `0` keeps the toast until dismissed. */
-  duration?: number;
-  dismissible?: boolean;
+  duration?: number | undefined;
+  dismissible?: boolean | undefined;
   /** Custom icon (emoji/text), or `false` to hide the status icon. */
-  icon?: string | false;
-  progressBar?: boolean;
+  icon?: string | false | undefined;
+  progressBar?: boolean | undefined;
   /** Action buttons that each invoke a `@expose` method on click. */
-  actions?: FlashAction[];
+  actions?: FlashAction[] | undefined;
   /** A `@expose` method invoked when the toast is dismissed. */
-  onClose?: FlashCallback;
+  onClose?: FlashCallback | undefined;
 }
 
 /**

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,14 +29,15 @@ 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;
+  timeout?: number | undefined;
   /**
    * Wait for Flow's WebSocket to report itself online before returning.
    * Default: true. Set false for a page with no Flow component on it.
    */
-  waitForConnection?: boolean;
+  waitForConnection?: boolean | undefined;
 }
 
 export class FlowBrowser {

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/confirm.ts

@@ -15,17 +15,17 @@ export interface ConfirmDialogOptions {
   /** Body text (the description, or the heading when no `title` is given). */
   message: string;
   /** Bold heading above the message. */
-  title?: string;
+  title?: string | undefined;
   /** Confirm button label (default: "Confirm", or "Delete" for danger). */
-  confirmLabel?: string;
+  confirmLabel?: string | undefined;
   /** Cancel button label (default: "Cancel"). */
-  cancelLabel?: string;
+  cancelLabel?: string | undefined;
   /** `danger` = destructive (red); `primary` = neutral/indigo (default). */
-  variant?: "danger" | "primary";
+  variant?: "danger" | "primary" | undefined;
   /** Custom icon (emoji/text/SVG markup), or `false` to hide the icon entirely. */
-  icon?: string | false;
+  icon?: string | false | undefined;
   /** Show a type-to-confirm input; Confirm unlocks only when the value matches this. */
-  prompt?: string;
+  prompt?: string | undefined;
 }
 
 const ICONS = {