@zerotal/flow 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -9,7 +9,26 @@ follows SemVer strictly: anything importable without an `@internal` marker keeps
 shape for the rest of the 1.x line, and `api-surface.md` is diffed by CI on every
 change.
 
-## [Unreleased]
+## [1.7.0] — 2026-08-16
+
+### Fixed
+
+- **SPA navigation no longer orphans the outgoing page's snapshot.** The swap removed the
+  first `[id^="flow-state-"]` in document order, but a page-level snapshot is a direct child
+  of `<body>` while a child island's sits inside the body content — so on any page with an
+  island it removed the island's script and left the page's behind. Ids are random per
+  request, so the leftovers accumulated one per navigation for as long as the tab stayed
+  open. Now scoped to `body > script[id^="flow-state-"]`, and every match is removed, so a
+  session that has already leaked cleans itself up on the next navigation.
+
+### Removed
+
+- **`Component._skipMount`**, an `@internal` field that was written by `hydrate()` and
+  `restoreDurable()` and read by nothing. Mount-skipping is structural — the router branches
+  between `onHydrate()` and `onMount()` — and wiring the flag up would have been wrong:
+  `$refresh` and `$mount` deliberately re-run `onMount()` on a hydrated page. An inert flag
+  that reads as load-bearing is worse than none, so it is gone and the guarantee is pinned by
+  a test instead: mount runs exactly once across an initial render and any number of actions.
 
 ## [1.6.0] — 2026-08-15
 

package/api-surface.md

@@ -0,0 +1,1125 @@
+# @zerotal/flow — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class Component = {
+  new (): Component
+  static durable?: boolean | {    ttl?: string;    scope?: 'user' | 'session';}
+  static readonly __isFlowPage: true
+  static using: Compose
+  $refresh: () => void
+  $set: (key: string, value: unknown) => void
+  _applyClientUpdate: (key: string, value: unknown, arrayKey?: string) => Promise<void>
+  _buildSchema: (builders: Map<string, ValidateBuilder>) => Schema
+  _childIds: string[]
+  _clearDurable: boolean
+  _clientScripts: string[]
+  _downloads: {    filename: string;    content: string;    mime: string;}[]
+  _drainEffects: () => FlowEffects
+  _emitUpdateHook: (base: 'onUpdating' | 'onUpdated', prop: string, value: unknown, key?: string) => Promise<void>
+  _errors: Record<string, string[]>
+  _events: {    name: string;    data: Record<string, unknown>;    to?: string;    self?: boolean;}[]
+  _exposedData: () => Record<string, unknown>
+  _flashes: FlashMessage[]
+  _flowId: string
+  _flowPath: string
+  _flowSlots: Record<string, string>
+  _isHydrated: boolean
+  _prevChildIds: string[]
+  _redirectStatus: number | null
+  _redirectUrl: string | null
+  _shouldRefresh: boolean
+  _streamSender: ((ref: string, content: string, replace: boolean) => void) | null
+  _taskSignal: AbortSignal | null
+  _titleValue: string | null
+  _validateField: (field: string) => Promise<void>
+  addError: (field: string, message: string) => void
+  bind: (key: string, optionValue?: string) => Record<string, unknown>
+  cancelled: boolean
+  child: <C extends Component>(ChildClass: new () => C, opts?: {    key?: string | number;    props?: Partial<C>;    lazy?: boolean;    defer?: boolean;    stream?: boolean;    slots?: Record<string, string>;}) => Promise<HtmlNode>
+  clearDurable: () => void
+  client: (script: string) => void
+  currentUrl: (_options?: CurrentUrlOptions) => string
+  dispatch: <K extends string>(name: K, ...args: K extends EventName ? EventArgs<FlowEvents[K]> : [payload?: Record<string, unknown>]) => void
+  dispatchSelf: <K extends string>(name: K, ...args: K extends EventName ? EventArgs<FlowEvents[K]> : [payload?: Record<string, unknown>]) => void
+  dispatchTo: <K extends string>(component: string, name: K, ...args: K extends EventName ? EventArgs<FlowEvents[K]> : [payload?: Record<string, unknown>]) => void
+  download: (filename: string, content: string | Uint8Array, mime?: string) => void
+  errors: ErrorsProxy
+  flash: (message: string, optionsOrLevel?: FlashLevel | FlashOptions) => FlashBuilder
+  hasSlot: (name?: string) => boolean
+  layout: (page: HtmlNode) => HtmlNode | Promise<HtmlNode>
+  navigateCurrent: (_options?: CurrentUrlOptions) => Promise<void>
+  onBoot: (_ctx?: HttpContext) => Promise<void>
+  onDehydrate: () => Promise<void>
+  onError: (error: Error) => Promise<void>
+  onHydrate: () => Promise<void>
+  onMount: (_ctx?: HttpContext) => Promise<void>
+  onRendered: (_html: string) => Promise<void>
+  onRendering: () => Promise<void>
+  onUpdate: () => Promise<void>
+  onUpdated: (_prop: string, _value: unknown, _key?: string) => Promise<void>
+  onUpdating: (_prop: string, _value: unknown, _key?: string) => Promise<void>
+  placeholder: () => HtmlNode
+  redirect: (url: string, status?: number) => RedirectFlash
+  redirectIntended: (fallback?: string, status?: number) => RedirectFlash
+  redirectRoute: <N extends RouteTarget>(name: N, params?: RouteParamsArg<N>, status?: number) => RedirectFlash
+  refresh: () => Promise<void>
+  render: () => Promise<HtmlNode>
+  resetValidation: (field?: string) => void
+  signal: AbortSignal
+  slot: (name?: string) => HtmlNode
+  stream: (ref: string, content: string, opts?: {    replace?: boolean;}) => void
+  title: {    (): string;    (value: string): void;}
+  validate: (rulesOrForm?: ValidationRules | {    __isFlowForm: true;    _validateToErrors(): Record<string, string[]>;}) => Promise<void>
+}
+
+class ErrorField = {
+  new (field: string, messages: string[]): ErrorField
+  readonly __field: string
+  readonly __isErrorField: true
+  readonly __value: string
+}
+
+class FlowActionHandled = {
+  new (component: string, action: string, durationMs: number, ok: boolean, ip: string | null, ctx: object | undefined): FlowActionHandled
+  readonly action: string
+  readonly component: string
+  readonly ctx: object | undefined
+  readonly durationMs: number
+  readonly ip: string | null
+  readonly ok: boolean
+}
+
+class FlowProvider = {
+  new (app: Application): FlowProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static persistMiddleware: (...middleware: (string | MiddlewareClass)[]) => void
+  static persistentMiddleware: (string | MiddlewareClass)[]
+  static priority?: number
+  static provides?: readonly (keyof ContainerBindings)[]
+  static registerSynth: (synth: Synth) => void
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class Form = {
+  new (): Form
+  _validateToErrors: () => Record<string, string[]>
+  data: () => Record<string, unknown>
+  fill: (values: Record<string, unknown>) => Form
+  readonly __isFlowForm: true
+  reset: (...fields: string[]) => Form
+  rules: (_v: RuleBuilder) => Record<string, FieldRule>
+  validate: () => Record<string, unknown>
+}
+
+class Layout = {
+  new (): Layout
+  static head?: string
+  render: (slot: HtmlNode) => HtmlNode | Promise<HtmlNode>
+}
+
+class TemporaryUploadedFile = {
+  new (d: TufData): TemporaryUploadedFile
+  static fromSignedRef: (ref: UploadRef) => TemporaryUploadedFile | null
+  static fromTrustedRef: (data: TufData) => TemporaryUploadedFile
+  bytes: () => Promise<Uint8Array>
+  extension: () => string
+  isImage: () => boolean
+  name: string
+  readonly mime: string
+  readonly originalName: string
+  readonly size: number
+  readonly tempDisk?: string | undefined
+  readonly tmpPath: string
+  store: (directory: string, diskName?: string, filename?: string) => Promise<string>
+  temporaryUrl: (ttlSeconds?: number) => Promise<string>
+  toRef: () => TufData
+}
+
+class ValidationError = {
+  new (errors: Record<string, string[]>): ValidationError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly errors: Record<string, string[]>
+  readonly status: number
+}
+
+class WebSocketConnected = {
+  new (url: string): WebSocketConnected
+  readonly url: string
+}
+
+class WebSocketDisconnected = {
+  new (url: string): WebSocketDisconnected
+  readonly url: string
+}
+
+const BLOCKED_URL = 'about:blank'
+
+const DEFAULT_PERSISTENT_MIDDLEWARE = (string | MiddlewareClass)[]
+
+const locked = (value: unknown, context: ClassFieldDecoratorContext) => void
+
+const modelable = (value: unknown, context: ClassFieldDecoratorContext) => void
+
+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
+
+function Calendar = (props: CalendarProps) => HtmlNode
+
+function Checkbox = (props: CheckboxProps) => HtmlNode
+
+function Combobox = (props: ComboboxProps) => HtmlNode
+
+function computed = <This, Return>(getter: (this: This) => Return, context: ClassGetterDecoratorContext<This, Return>) => (this: This) => Return
+
+function defineStore = (initial: Record<string, unknown>) => void
+
+function Description = (props: DescriptionProps) => HtmlNode
+
+function Disclosure = (props: DisclosureProps) => HtmlNode
+
+function Drawer = (props: DrawerProps) => HtmlNode
+
+function Dropdown = (props: DropdownProps) => HtmlNode
+
+function ErrorBoundary = (props: ErrorBoundaryProps) => HtmlNode
+
+function ErrorMessage = (props: ErrorProps) => HtmlNode
+
+function Errors = (props?: ErrorsProps) => HtmlNode
+
+function expose = (_value: unknown, context: ExposeContext) => void
+
+function Field = (props: FieldProps) => HtmlNode
+
+function Fieldset = (props: FieldsetProps) => HtmlNode
+
+function FileUpload = (props: FileUploadProps) => HtmlNode
+
+function FileUploads = <TBase extends AbstractComponentCtor>(Base: TBase) => ((abstract new (...args: any[]) => WithUploads) & {    prototype: FileUploads<any>.WithUploads;}) & TBase
+
+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 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
+
+function Link = (props: LinkProps & {    children?: unknown;}) => HtmlNode
+
+function Listbox = (props: ListboxProps) => HtmlNode
+
+function Loading = (props: LoadingProps) => HtmlNode
+
+function Modal = (props: ModalProps) => HtmlNode
+
+function on = (eventName: LooseEventName) => (fn: unknown, context: ClassMethodDecoratorContext) => void
+
+function Pager = (props: PagerProps) => HtmlNode
+
+function paginate = <T>(items: T[], page?: number, perPage?: number) => Paginator<T>
+
+function Pagination = <TBase extends AbstractComponentCtor>(Base: TBase) => ((abstract new (...args: any[]) => Paginated) & {    prototype: Pagination<any>.Paginated;}) & TBase
+
+function param = {    (value: unknown, context: ClassFieldDecoratorContext): void;    (source?: string | ParamModel): ParamDecorator;}
+
+function Persist = (props: {    name: string;    children?: unknown;}) => HtmlNode
+
+function Popover = (props: PopoverProps) => HtmlNode
+
+function presence = (channel: PresenceChannel) => (value: unknown, context: ClassFieldDecoratorContext) => void
+
+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 registerFlowModel = (name: string, ModelClass: typeof BaseModel) => 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
+
+function Select = (props: SelectProps) => HtmlNode
+
+function session = {    (value: unknown, context: ClassFieldDecoratorContext): void;    (opts?: SessionOptions): SessionDecorator;}
+
+function setDurableStore = (store: DurableStore) => void
+
+function setSharedStore = (store: SharedStore) => void
+
+function shared = (channel: SharedChannel) => (value: unknown, context: ClassFieldDecoratorContext) => void
+
+function Skeleton = (props: SkeletonProps) => HtmlNode
+
+function Slider = (props: SliderProps) => HtmlNode
+
+function Switch = (props: SwitchProps) => HtmlNode
+
+function Table = <T extends Record<string, unknown>>(props: TableProps<T>) => HtmlNode
+
+function Tabs = (props: TabsProps) => HtmlNode
+
+function task = (_fn: unknown, context: ClassMethodDecoratorContext) => void
+
+function Title = (props: {    children?: unknown;}) => HtmlNode
+
+function ToggleGroup = (props: ToggleGroupProps) => HtmlNode
+
+function Tooltip = (props: TooltipProps) => HtmlNode
+
+function url = {    (value: unknown, context: ClassFieldDecoratorContext): void;    (opts?: UrlOptions): UrlDecorator;}
+
+function validate = (build: ValidateBuilder) => (value: unknown, context: ClassFieldDecoratorContext) => void
+
+function Virtualize = <T>(props: VirtualizeProps<T>) => HtmlNode
+
+interface AccordionItem = {
+  content: unknown
+  label: unknown
+}
+
+interface AccordionProps = {
+  [key: string]: unknown
+  buttonClass?: string
+  class?: string
+  defaultIndex?: number
+  itemClass?: string
+  items: AccordionItem[]
+  multiple?: boolean
+  panelClass?: string
+}
+
+interface AlertProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+  dismissible?: boolean
+  title?: unknown
+  variant?: 'success' | 'error' | 'warning' | 'info'
+}
+
+interface CalendarProps = {
+  [key: string]: unknown
+  bind?: unknown
+  class?: string
+  dayClass?: string
+  gridClass?: string
+  headerClass?: string
+  max?: string
+  min?: string
+  month?: string
+  name?: string
+  navClass?: string
+  sundayFirst?: boolean
+  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
+  children?: unknown
+  class?: string
+}
+
+interface ChildMemo = {
+  id: string
+  key: string
+  name: string
+}
+
+interface ComboboxOption = {
+  label: string
+  value: string | number
+}
+
+interface ComboboxProps = {
+  [key: string]: unknown
+  bind?: unknown
+  class?: string
+  inputClass?: string
+  name?: string
+  optionClass?: string
+  options: ComboboxOption[]
+  optionsClass?: string
+  placeholder?: string
+  query?: unknown
+  queryName?: string
+}
+
+interface Compose = {
+  <TBase extends Constructor, A extends Constructor, B extends Constructor, C extends Constructor, D extends Constructor, E extends Constructor, F extends Constructor, G extends Constructor, H extends Constructor>(this: TBase, a: (base: TBase) => A, b: (base: A) => B, c: (base: B) => C, d: (base: C) => D, e: (base: D) => E, f: (base: E) => F, g: (base: F) => G, h: (base: G) => H): H
+  <TBase extends Constructor, A extends Constructor, B extends Constructor, C extends Constructor, D extends Constructor, E extends Constructor, F extends Constructor, G extends Constructor>(this: TBase, a: (base: TBase) => A, b: (base: A) => B, c: (base: B) => C, d: (base: C) => D, e: (base: D) => E, f: (base: E) => F, g: (base: F) => G): G
+  <TBase extends Constructor, A extends Constructor, B extends Constructor, C extends Constructor, D extends Constructor, E extends Constructor, F extends Constructor>(this: TBase, a: (base: TBase) => A, b: (base: A) => B, c: (base: B) => C, d: (base: C) => D, e: (base: D) => E, f: (base: E) => F): F
+  <TBase extends Constructor, A extends Constructor, B extends Constructor, C extends Constructor, D extends Constructor, E extends Constructor>(this: TBase, a: (base: TBase) => A, b: (base: A) => B, c: (base: B) => C, d: (base: C) => D, e: (base: D) => E): E
+  <TBase extends Constructor, A extends Constructor, B extends Constructor, C extends Constructor, D extends Constructor>(this: TBase, a: (base: TBase) => A, b: (base: A) => B, c: (base: B) => C, d: (base: C) => D): D
+  <TBase extends Constructor, A extends Constructor, B extends Constructor, C extends Constructor>(this: TBase, a: (base: TBase) => A, b: (base: A) => B, c: (base: B) => C): C
+  <TBase extends Constructor, A extends Constructor, B extends Constructor>(this: TBase, a: (base: TBase) => A, b: (base: A) => B): B
+  <TBase extends Constructor, A extends Constructor>(this: TBase, a: (base: TBase) => A): A
+}
+
+interface DescriptionProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+}
+
+interface DisclosureProps = {
+  [key: string]: unknown
+  buttonClass?: string
+  children?: unknown
+  class?: string
+  defaultOpen?: boolean
+  label?: unknown
+  panelClass?: string
+  trigger?: unknown
+}
+
+interface DownloadFrame = {
+  content: string
+  filename: string
+  mime: string
+  type: 'download'
+}
+
+interface DrawerProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+  closable?: boolean
+  name?: string
+  onClose?: unknown
+  show?: unknown
+  side?: 'left' | 'right' | 'top' | 'bottom'
+  title?: unknown
+}
+
+interface DropdownProps = {
+  [key: string]: unknown
+  align?: 'left' | 'right'
+  children?: unknown
+  class?: string
+  label?: unknown
+  panelClass?: string
+  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
+  class?: string
+  fallback?: HtmlNode | ((error: unknown) => HtmlNode)
+  onError?: (error: unknown) => void
+  tag?: string
+}
+
+interface ErrorFrame = {
+  action?: string
+  component: string
+  message: string
+  name?: string
+  stack?: string
+  type: 'error'
+}
+
+interface ErrorProps = {
+  [key: string]: unknown
+  class?: string
+  for?: unknown
+}
+
+interface ErrorsProps = {
+  [key: string]: unknown
+  class?: string
+  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
+  class?: string
+  description?: unknown
+  error?: unknown
+  label?: unknown
+}
+
+interface FieldsetProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+  disabled?: boolean
+  legend?: unknown
+}
+
+interface FileUploadProps = {
+  [key: string]: unknown
+  accept?: string
+  bind: unknown
+  children?: unknown
+  class?: string
+  label?: string
+  multiple?: boolean
+}
+
+interface FlashAction = {
+  args?: unknown[]
+  color?: string
+  label: string
+  method: string
+  uppercase?: boolean
+  variant?: FlashActionVariant
+}
+
+interface FlashActionStyle = {
+  color?: string
+  uppercase?: boolean
+  variant?: FlashActionVariant
+}
+
+interface FlashBuilder = {
+  action: (label: string, method: string, args?: unknown[], style?: string | FlashActionStyle) => FlashBuilder
+  dismissible: (value?: boolean) => FlashBuilder
+  duration: (ms: number) => FlashBuilder
+  error: () => FlashBuilder
+  icon: (icon: string | false) => FlashBuilder
+  info: () => FlashBuilder
+  level: (level: FlashLevel) => FlashBuilder
+  noAutoDismiss: () => FlashBuilder
+  onClose: (method: string, args?: unknown[]) => FlashBuilder
+  position: (position: FlashPosition) => FlashBuilder
+  progressBar: (value?: boolean) => FlashBuilder
+  success: () => FlashBuilder
+  title: (title: string) => FlashBuilder
+  warning: () => FlashBuilder
+}
+
+interface FlashCallback = {
+  args?: unknown[]
+  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
+  duration?: number
+  icon?: string | false
+  level: 'success' | 'error' | 'warning' | 'info'
+  message: string
+  onClose?: FlashCallback
+  position?: FlashPosition
+  progressBar?: boolean
+  title?: string
+}
+
+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'
+}
+
+interface FlashProps = {
+  [key: string]: unknown
+  duration?: number
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'
+}
+
+interface FlowChain = {
+  confirm: (message: string) => FlowChain<T>
+  debounce: (ms: string | number) => FlowChain<T>
+  readonly __isFlow: true
+  readonly __key: string | undefined
+  readonly __modifiers: string[]
+  readonly __target: T
+  readonly blur: FlowChain<T>
+  readonly camel: FlowChain<T>
+  readonly capture: FlowChain<T>
+  readonly document: FlowChain<T>
+  readonly fill: FlowChain<T>
+  readonly lazy: FlowChain<T>
+  readonly live: FlowChain<T>
+  readonly once: FlowChain<T>
+  readonly outside: FlowChain<T>
+  readonly passive: FlowChain<T>
+  readonly prevent: FlowChain<T>
+  readonly self: FlowChain<T>
+  readonly stop: FlowChain<T>
+  readonly window: FlowChain<T>
+  throttle: (ms: string | number) => FlowChain<T>
+}
+
+interface FlowConfigShape = {
+  cspSafe: boolean
+  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 = {}
+
+interface ForProps = {
+  children: (item: T, index: number) => HtmlNode
+  each: readonly T[]
+  keyBy?: string
+}
+
+interface InfiniteScrollProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+  onMore: unknown
+  show?: boolean
+}
+
+interface LabelProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+}
+
+interface LegendProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+}
+
+interface LinkProps = {
+  [key: string]: unknown
+  current?: boolean
+  exact?: boolean
+  hover?: boolean
+  href: string
+  preserveScroll?: boolean
+}
+
+interface ListboxOption = {
+  label: unknown
+  value: string | number
+}
+
+interface ListboxProps = {
+  [key: string]: unknown
+  bind: unknown
+  buttonClass?: string
+  class?: string
+  multiple?: boolean
+  optionClass?: string
+  options: ListboxOption[]
+  optionsClass?: string
+  placeholder?: string
+}
+
+interface LoadingProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+  delay?: boolean
+  hide?: boolean
+  skeleton?: boolean | SkeletonProps
+  tag?: string
+  target?: string | string[]
+}
+
+interface ModalProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+  closable?: boolean
+  name?: string
+  onClose?: unknown
+  show?: unknown
+  title?: unknown
+}
+
+interface PageClassWithMeta = {
+  new (): Component
+  head?: string
+  layout?: new () => Layout
+  models?: Record<string, typeof BaseModel>
+  name: string
+  title?: string
+}
+
+interface PagerProps = {
+  [key: string]: unknown
+  activeClass?: string
+  class?: string
+  hover?: boolean
+  linkClass?: string
+  nextLabel?: string
+  paginator: PagerLike
+  params?: Record<string, string | number | null | undefined>
+  prevLabel?: string
+}
+
+interface Paginator = {
+  data: T[]
+  elements: (each?: number) => (number | '...')[]
+  from: number
+  hasMorePages: boolean
+  lastPage: number
+  onFirstPage: boolean
+  page: number
+  perPage: number
+  to: number
+  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
+  children?: unknown
+  class?: string
+  label?: unknown
+  panelClass?: string
+  trigger?: unknown
+}
+
+interface PresenceMember = {
+  [key: string]: unknown
+  id: string | number
+}
+
+interface RadioGroupProps = {
+  [key: string]: unknown
+  bind: unknown
+  class?: string
+  optionClass?: string
+  options: RadioOption[]
+}
+
+interface RadioOption = {
+  label: unknown
+  value: string | number
+}
+
+interface RedirectFlash = {
+  with: (message: string, level: FlashLevel) => RedirectFlash
+  withError: (message: string) => RedirectFlash
+  withInfo: (message: string) => RedirectFlash
+  withSuccess: (message: string) => RedirectFlash
+  withWarning: (message: string) => RedirectFlash
+}
+
+interface RedirectFrame = {
+  sessionToken?: string
+  type: 'redirect'
+  url: string
+}
+
+interface SectionContentProps = {
+  children?: unknown
+  name: string
+}
+
+interface SectionOutletProps = {
+  children?: unknown
+  name: string
+}
+
+interface SelectOption = {
+  label: unknown
+  value: string | number
+}
+
+interface SelectProps = {
+  [key: string]: unknown
+  bind: unknown
+  class?: string
+  options: SelectOption[]
+  placeholder?: string
+}
+
+interface SessionOptions = {
+  key?: string
+  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
+  height?: string
+  lines?: number
+  rounded?: string | boolean
+  width?: string
+}
+
+interface SliderProps = {
+  [key: string]: unknown
+  bind?: unknown
+  children?: unknown
+  class?: string
+  inputClass?: string
+  inputStyle?: string
+  inputStyleExpression?: string
+  max?: number
+  min?: number
+  name?: string
+  step?: number
+}
+
+interface Snapshot = {
+  checksum: string
+  data: SnapshotData
+  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
+  children?: unknown
+  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
+  name?: string
+}
+
+interface TableColumn = {
+  class?: string
+  key: string
+  label: unknown
+  render?: (row: T) => unknown
+  sortable?: boolean
+}
+
+interface TableProps = {
+  [key: string]: unknown
+  class?: string
+  columns: TableColumn<T>[]
+  hover?: boolean
+  params?: Record<string, string | number | null | undefined>
+  rowKey?: string
+  rows: T[]
+  sortBy?: string
+  sortDir?: 'asc' | 'desc'
+  theadClass?: string
+}
+
+interface TabsProps = {
+  [key: string]: unknown
+  class?: string
+  items: TabItem[]
+}
+
+interface ToggleGroupProps = {
+  [key: string]: unknown
+  bind?: unknown
+  class?: string
+  multiple?: boolean
+  name?: string
+  optionClass?: string
+  options: ToggleOption[]
+}
+
+interface ToggleOption = {
+  disabled?: boolean
+  label?: unknown
+  value: string
+}
+
+interface TooltipProps = {
+  [key: string]: unknown
+  children?: unknown
+  class?: string
+  content?: unknown
+  placement?: 'top' | 'bottom'
+  text?: unknown
+  tooltipClass?: string
+}
+
+interface UploadRef = {
+  __flow_upload: true
+  mime: string
+  originalName: string
+  sig: string
+  size: number
+  tempDisk?: string | undefined
+  tmpPath: string
+}
+
+interface UrlOptions = {
+  as?: string
+  history?: 'replace' | 'push'
+}
+
+interface VirtualizeProps = {
+  children: (item: T, index: number) => HtmlNode
+  class?: string
+  height?: number
+  itemHeight: number
+  items: readonly T[]
+  onWindow?: unknown
+  overscan?: number
+  start?: number
+  total?: number
+}
+
+type Constructor = abstract new (...args: any[]) => T
+
+type DurableOption = boolean | {    ttl?: string;    scope?: 'user' | 'session';}
+
+type EventName = never
+
+type EventPayload = FlowEvents[K]
+
+type FlashActionVariant = 'solid' | 'soft' | 'ghost'
+
+type FlashLevel = 'success' | 'error' | 'warning' | 'info'
+
+type FlashPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'
+
+type HtmlNode = {    html: string;}
+
+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)`
+
+class FlowBrowser = {
+  new (_browser: LaunchedBrowser, _session: CdpSession): FlowBrowser
+  static available: () => boolean
+  static open: (url: string, options?: OpenOptions) => Promise<FlowBrowser>
+  attr: (selector: string, name: string) => Promise<string | null>
+  click: (selector: string) => Promise<void>
+  close: () => Promise<void>
+  consoleErrors: () => string[]
+  evaluate: <T = unknown>(expression: string) => Promise<T>
+  fill: (selector: string, value: string) => Promise<void>
+  goto: (url: string, options?: OpenOptions) => Promise<void>
+  html: () => Promise<string>
+  pageErrors: () => string[]
+  text: (selector: string) => Promise<string>
+  value: (selector: string) => Promise<string>
+  waitForSelector: (selector: string, timeoutMs?: number) => Promise<void>
+  waitForText: (selector: string, text: string, timeoutMs?: number) => Promise<void>
+  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
+
+## ./store  `(./src/store.ts)`
+
+function clientStore = () => Record<string, unknown>
+
+function defineStore = (initial: Record<string, unknown>) => void
+
+function initClientStore = (alpine: AlpineStores) => Record<string, unknown>
+
+interface FlowStore = {}
+
+## ./testing  `(./src/testing.ts)`
+
+class FlowTest = {
+  new <T extends Component>(page: T, name: string): FlowTest<T>
+  static mount: <T extends Component>(PageClass: PageClass<T>, props?: Partial<T>) => Promise<FlowTest<T>>
+  assertDispatched: (eventName: string) => FlowTest<T>
+  assertDontSee: (text: string) => FlowTest<T>
+  assertErrored: (match?: string | RegExp) => FlowTest<T>
+  assertFlashed: (level?: string, message?: string) => FlowTest<T>
+  assertHasErrors: (field: string, message?: string) => FlowTest<T>
+  assertNoErrors: () => FlowTest<T>
+  assertNotRedirected: () => FlowTest<T>
+  assertRedirectedTo: (url: string) => FlowTest<T>
+  assertSee: (text: string) => FlowTest<T>
+  call: (method: string, ...args: unknown[]) => Promise<FlowTest<T>>
+  effects: () => FlowEffects | null
+  errors: () => Record<string, string[]>
+  flashes: () => FlowEffects['flashes']
+  html: () => string
+  lastError: () => Error | null
+  page: () => T
+  render: () => Promise<FlowTest<T>>
+  seed: (prop: keyof T, value: unknown) => Promise<FlowTest<T>>
+  set: (prop: keyof T, value: unknown) => Promise<FlowTest<T>>
+  snapshot: () => Snapshot | null
+  tolerateErrors: () => FlowTest<T>
+  update: (prop: keyof T, value: unknown) => Promise<FlowTest<T>>
+}
+
+function hydrate = <T extends Component>(snapshot: Snapshot, PageClass: new () => T) => Promise<T>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/flow",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -18,6 +18,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -46,14 +47,14 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/core": "1.6.2",
-    "@zerotal/orm": "1.6.2",
-    "@zerotal/validator": "1.6.2",
+    "@zerotal/core": "1.7.0",
+    "@zerotal/orm": "1.7.0",
+    "@zerotal/validator": "1.7.0",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.6.2",
+    "@zerotal/broadcasting": "1.7.0",
     "@types/alpinejs": "^3.13.10",
     "@types/alpinejs__anchor": "^3.13.1",
     "@types/alpinejs__collapse": "^3.13.4",

package/src/Component.ts

@@ -493,8 +493,19 @@ export abstract class Component {
 
   // ── @internal: framework bookkeeping, not part of the developer API ──────────
 
-  /** Set to true by hydrate() so the framework skips calling onMount(). @internal */
-  _skipMount = false;
+  // `_skipMount` used to live here, declared as "set to true by hydrate() so the
+  // framework skips calling onMount()". Nothing ever read it. Mount-skipping is
+  // structural and always has been: the router branches between `onHydrate()`
+  // and `onMount()`, and the action dispatcher calls `onMount()` only when an
+  // action asks for it.
+  //
+  // It was removed rather than wired up because wiring it would have been wrong.
+  // `$refresh` and `$mount` deliberately re-run `onMount()` on a page that was
+  // hydrated — so a flag whose stated meaning is "this page has been hydrated,
+  // do not mount it" would have broken both the moment anyone honoured it. An
+  // inert flag that reads as load-bearing is worse than none: the next person
+  // building render modes would reach for it, find it does nothing, and ship a
+  // double-mount. `hooks.test.ts` pins the real guarantee instead.
 
   /** Populated by flash() — read by the WS handler to emit flash frames. @internal */
   _flashes: FlashMessage[] = [];

package/src/client/bridge.ts

@@ -2684,7 +2684,21 @@ async function _navigateTo(href: string, options: NavigateOptions = {}): Promise
   // browser supports it, for a smooth cross-page animation; falls back to an
   // instant swap otherwise.
   const _swap = (): void => {
-    document.querySelector('[id^="flow-state-"]')?.remove();
+    // Page-level state scripts only: the server renders one as a direct child of
+    // <body>, after the body content, while every child island's script sits
+    // *inside* that content.
+    //
+    // This used to be `document.querySelector('[id^="flow-state-"]')`, which
+    // matches in document order — so on any page with an island it removed the
+    // first island's script and left the page's own behind. The outgoing
+    // snapshot was orphaned, and ids are random per request, so they accumulated
+    // one per navigation for as long as the tab stayed open.
+    //
+    // Removing *all* of them rather than just this page's also clears whatever a
+    // previously-buggy session left behind.
+    for (const stale of document.querySelectorAll('body > script[id^="flow-state-"]')) {
+      stale.remove();
+    }
     document.body.appendChild(incomingState.cloneNode(true));
     currentRoot.replaceWith(incomingClone);
     _cleanupDisconnected();

package/src/dehydrate.ts

@@ -206,9 +206,9 @@ export async function hydrate<T extends Component>(
   //    still someone else's state.
   assertSnapshotSubject(snapshot);
 
-  // 3. Fresh blank instance — constructor runs but onMount() is skipped.
+  // 3. Fresh blank instance. `onMount()` is not called here and the dispatcher
+  //    does not call it either — the skip is structural, not a flag on the page.
   const page = new PageClass();
-  (page as Record<string, unknown>)["_skipMount"] = true;
 
   // 4. Restore slots + each property (see applySnapshotData).
   await applySnapshotData(page, snapshot);

package/src/durable.ts

@@ -237,7 +237,8 @@ export async function restoreDurable(page: Component, ctx: HttpContext): Promise
   if (!key) return false;
   const stored = await _store.get(key);
   if (!stored || !verifySnapshot(stored)) return false;
-  (page as unknown as Record<string, unknown>)["_skipMount"] = true;
+  // Returning `true` is what skips the mount: the caller branches on it and runs
+  // `onHydrate()` instead. Nothing is marked on the page.
   await applySnapshotData(page, stored);
   return true;
 }