@zerotal/flow 1.4.0 → 1.5.0

package/src/decorators.ts

@@ -189,13 +189,26 @@ function _scanChain(startProto: object | null): void {
 interface PendingField {
   name: string;
   apply: (proto: object) => void;
+  /**
+   * `context.metadata` — one object per **file**, not per class (Bun shares it across
+   * every class defined in the same module). It is the only link back to where a
+   * buffered entry came from, because `Symbol.metadata` never reaches the class, so
+   * there is nothing to read at drain time.
+   *
+   * It is enough for the case that matters: a class may only claim registrations
+   * enqueued by its own file. Without it, a component that declares `count` and is
+   * never read leaves that entry in the buffer forever, and the next class in a
+   * *different* file with an own field called `count` claims it — silently getting
+   * the wrong decorator, and never getting its own.
+   */
+  group: object | undefined;
 }
 const _pendingFields: PendingField[] = [];
 const _drainedProtos = new WeakSet<object>();
 
 /** Enqueue a field registration captured (with the correct name) in the decorator body. */
-function _enqueueField(name: string, apply: (proto: object) => void): void {
-  _pendingFields.push({ name, apply });
+function _enqueueField(name: string, apply: (proto: object) => void, group?: object): void {
+  _pendingFields.push({ name, apply, group });
 }
 
 /**
@@ -206,6 +219,11 @@ function _enqueueField(name: string, apply: (proto: object) => void): void {
  * decorators run consecutively at definition time (including a subclass's mixin-supplied fields)
  * and in declaration order, so its block is exactly such a run.
  *
+ * The search is scoped to one FILE's entries at a time, newest first — see
+ * {@link PendingField.group}. Scanning the whole buffer let a class claim a same-named
+ * entry left behind by an unrelated file, which is invisible: it gets the wrong
+ * decorator and never gets its own.
+ *
  * The strictly-increasing constraint is what makes this robust when two classes share field
  * names AND their blocks are adjacent in the buffer (e.g. AddTransactionModal and TransferModal
  * both declare `accountId`/`open`/`fAmount`). A plain "longest run ⊆ own" would greedily extend
@@ -222,40 +240,109 @@ function _drainFields(ctor: unknown): void {
   _drainedProtos.add(proto); // mark first to stay re-entrancy-safe during the probe
   if (_pendingFields.length === 0) return;
 
+  // The fields THIS class declares — not the ones it inherits. Instance fields all
+  // land on the instance whoever declared them, so `Object.keys(new Derived())` also
+  // lists the base's; subtracting the base's own probe leaves this class's block.
+  //
+  // The difference is load-bearing, not tidiness. `PaginatedPage extends
+  // Pagination(Component)` inherits `page`, so an undrained `[page, page]` group left
+  // by *another* `Pagination(...)` application matched it — and being two entries long
+  // it beat `PaginatedPage`'s own one-entry `[rows]`. The subclass silently ended up
+  // with the mixin's decorators and none of its own.
+  //
+  // If the base cannot be constructed without arguments there is nothing to subtract,
+  // and the full key set is the same answer this used to give.
   let ownIndex: Map<string, number>;
   try {
     const keys = Object.keys(new (ctor as new () => object)());
-    ownIndex = new Map(keys.map((k, i) => [k, i]));
+    const base = Object.getPrototypeOf(ctor) as unknown;
+    let inherited: Set<string> | undefined;
+    if (typeof base === "function" && base !== Function.prototype) {
+      try {
+        inherited = new Set(Object.keys(new (base as new () => object)()));
+      } catch {
+        inherited = undefined;
+      }
+    }
+    const declared = inherited ? keys.filter((k) => !inherited.has(k)) : keys;
+    ownIndex = new Map(declared.map((k, i) => [k, i]));
   } catch {
     return; // not constructible without args — nothing we can match
   }
 
-  // Longest contiguous run whose names map to strictly-increasing declaration-order indices
-  // (equal allowed only for an identical repeated name — multiple decorators on one field).
-  let bestStart = -1;
-  let bestLen = 0;
+  // Match within one class's entries at a time — see {@link PendingField.group}.
+  //
+  // Scanning the buffer as one flat list let a class claim a same-named entry left
+  // behind by an unrelated class, and that is invisible when it happens: the class
+  // silently gets the wrong decorator and never gets its own. It is not
+  // hypothetical — a component that declares a field and is never read leaves its
+  // entry buffered for the life of the process, and names like `count`, `open` and
+  // `page` are declared all over a codebase.
+  //
+  // Groups are keyed by identity rather than by adjacency, because a class's entries
+  // need not be contiguous: an import evaluated part-way through a module interleaves
+  // another file's.
+  const groups: object[] = [];
+  const byGroup = new Map<object, number[]>();
+  const NO_GROUP = {}; // stand-in key, so entries without metadata still group together
   for (let i = 0; i < _pendingFields.length; i++) {
-    if (!ownIndex.has(_pendingFields[i]!.name)) continue;
-    let last = -1;
-    let lastName = "";
-    let j = i;
-    while (j < _pendingFields.length) {
-      const name = _pendingFields[j]!.name;
-      const idx = ownIndex.get(name);
-      if (idx === undefined) break;
-      if (idx < last || (idx === last && name !== lastName)) break;
-      last = idx;
-      lastName = name;
-      j++;
+    const key = _pendingFields[i]!.group ?? NO_GROUP;
+    let list = byGroup.get(key);
+    if (!list) {
+      list = [];
+      byGroup.set(key, list);
+      groups.push(key);
     }
-    if (j - i > bestLen) {
-      bestLen = j - i;
-      bestStart = i;
+    list.push(i);
+  }
+
+  // Best run across every group, NOT the first group that matches anything. A class
+  // whose own group is a two-field block must beat an unrelated group that happens to
+  // share one of those names, and only the length says so. Ties go to the most
+  // recently enqueued group: a class is drained after its own definition, so among
+  // equal candidates the newest is the one that just defined it, and older equals are
+  // leftovers by construction.
+  let bestIdxs: number[] | null = null;
+  let bestLen = 0;
+  let bestGroup = -1;
+  for (let g = 0; g < groups.length; g++) {
+    const idxs = byGroup.get(groups[g]!)!;
+
+    // Longest contiguous run whose names map to strictly-increasing declaration-order
+    // indices (equal allowed only for an identical repeated name — multiple decorators
+    // on one field). "Contiguous" is within this group's entries.
+    for (let i = 0; i < idxs.length; i++) {
+      if (!ownIndex.has(_pendingFields[idxs[i]!]!.name)) continue;
+      let last = -1;
+      let lastName = "";
+      let j = i;
+      while (j < idxs.length) {
+        const name = _pendingFields[idxs[j]!]!.name;
+        const idx = ownIndex.get(name);
+        if (idx === undefined) break;
+        if (idx < last || (idx === last && name !== lastName)) break;
+        last = idx;
+        lastName = name;
+        j++;
+      }
+      // Longer always wins. On a tie, a LATER group wins (newest definition), but an
+      // earlier run within the SAME group is kept — which is the previous behaviour.
+      const len = j - i;
+      if (len > bestLen || (len === bestLen && len > 0 && g > bestGroup)) {
+        bestLen = len;
+        bestIdxs = idxs.slice(i, j);
+        bestGroup = g;
+      }
     }
   }
-  if (bestStart === -1) return;
-  const claimed = _pendingFields.splice(bestStart, bestLen);
-  for (const e of claimed) e.apply(proto);
+  if (!bestIdxs || bestLen === 0) return;
+
+  // Apply, then remove the claimed entries. Removal is by descending buffer index so
+  // the earlier positions stay valid while splicing.
+  for (const bufIdx of bestIdxs) _pendingFields[bufIdx]!.apply(proto);
+  for (let k = bestIdxs.length - 1; k >= 0; k--) {
+    _pendingFields.splice(bestIdxs[k]!, 1);
+  }
 }
 
 /** Drain via an instance or a prototype before reading. */
@@ -291,7 +378,7 @@ function _fieldDecorator(
   return (_value, context) => {
     const name = String(context.name);
     _assertField(name, context);
-    _enqueueField(name, (proto) => register(proto, name));
+    _enqueueField(name, (proto) => register(proto, name), context.metadata);
   };
 }
 
@@ -415,7 +502,7 @@ function _memoizeGetter(orig: () => unknown, name: string): () => unknown {
  * @remarks
  * A computed getter is not serialized and is not client-writable; it renders as static
  * server-produced text. The result is memoized for the duration of a single render pass
- * (Livewire-style per-request caching): an expensive getter read several times in one template
+ * — an expensive getter read several times in one template
  * runs once. The cache is scoped to the active render (see `_renderFlowPage`), so reads
  * outside rendering always recompute and never go stale. Apply only to a getter — a field-style
  * decorator on it is rejected; conversely `@computed` on a non-getter is a TypeScript error.
@@ -512,7 +599,7 @@ export function expose(_value: unknown, context: ExposeContext): void {
   }
   if (context.kind === "field") {
     // Field: capture in the body and enqueue (see _fieldDecorator / _drainFields).
-    _enqueueField(name, (proto) => _register(_exposedProps, proto, name));
+    _enqueueField(name, (proto) => _register(_exposedProps, proto, name), context.metadata);
     return;
   }
   // Method: tag the function so `_scanProto` finds it on the DECLARING prototype (see header);
@@ -671,7 +758,7 @@ export function resolveSharedChannel(channel: SharedChannel, instance: object):
 // A child-component prop the PARENT can push new values into on every re-render.
 // Included in the snapshot and client-writable (so the framework can deliver
 // parent updates), and re-emitted by the parent so the child re-renders when the
-// bound value changes. Mirrors Livewire's #[Reactive].
+// bound value changes.
 
 /**
  * Marks a child-component prop as reactive — the parent re-pushes new values into it on every
@@ -680,8 +767,8 @@ export function resolveSharedChannel(channel: SharedChannel, instance: object):
  * @remarks
  * The prop is included in the snapshot and is client-writable (so the framework can deliver the
  * parent's updates), and the parent re-emits it so the child re-renders when the bound value
- * changes. This is a one-way parent→child binding; use `@modelable` for two-way. Mirrors
- * Livewire's `#[Reactive]`. Applies to a field only.
+ * changes. This is a one-way parent→child binding; use `@modelable` for two-way.
+ * Applies to a field only.
  *
  * @example
  * ```tsx
@@ -700,8 +787,8 @@ export const reactive = _fieldDecorator((proto, name) => {
 
 // ── @modelable ────────────────────────────────────────────────────────────────
 // A reactive prop that ALSO syncs back to the parent: `value={this.x}` on a child
-// component binds the parent's `x` to the child's modelable prop both ways. Mirrors
-// Livewire's #[Modelable]. A modelable prop is implicitly reactive.
+// component binds the parent's `x` to the child's modelable prop both ways.
+// A modelable prop is implicitly reactive.
 
 /**
  * Marks a child-component prop as two-way bound to the parent (parent↔child).
@@ -709,8 +796,8 @@ export const reactive = _fieldDecorator((proto, name) => {
  * @remarks
  * A modelable prop is reactive (the parent pushes new values in on re-render) AND syncs back:
  * `value={this.x}` on a child component binds the parent's `x` to the child's modelable prop in
- * both directions. A modelable prop is implicitly reactive (it registers as both). Mirrors
- * Livewire's `#[Modelable]`. Applies to a field only.
+ * both directions. A modelable prop is implicitly reactive (it registers as both).
+ * Applies to a field only.
  *
  * @example
  * ```tsx

package/src/dehydrate.ts

@@ -73,7 +73,7 @@ function currentSubject(): string | undefined {
 
 // ── Signing payload ───────────────────────────────────────────────────────────
 // children and listeners are excluded from signing:
-//   - children: Livewire pattern — ids are derived server-side, never trusted from client
+//   - children: ids are derived server-side, never trusted from the client
 //   - listeners: server-derived from class decorators, cannot meaningfully be tampered
 //     with (@on methods are still validated against @expose allowlist on every call)
 
@@ -155,7 +155,7 @@ export function dehydrate(
       : undefined;
 
   // Children collected during the render that preceded this dehydrate call.
-  // Excluded from HMAC (Livewire pattern).
+  // Excluded from HMAC — see the signing-payload note above.
   const snapshotMemo: Snapshot["memo"] = {
     ...memo,
     children: [...page._childIds],

package/src/events.ts

@@ -40,7 +40,7 @@
  *
  * @category Realtime
  */
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
+
 export interface FlowEvents {}
 
 /**

package/src/index.ts

@@ -105,6 +105,10 @@ export {
   Alert,
   Table,
   Drawer,
+  ErrorBoundary,
+  SectionContent,
+  SectionOutlet,
+  Virtualize,
 } from "./components.ts";
 export type {
   LinkProps,
@@ -126,6 +130,10 @@ export type {
   TableProps,
   TableColumn,
   DrawerProps,
+  ErrorBoundaryProps,
+  SectionContentProps,
+  SectionOutletProps,
+  VirtualizeProps,
 } from "./components.ts";
 
 // Headless (unstyled, accessible) primitives — data-* state, Tailwind-friendly.
@@ -221,8 +229,6 @@ import "./synths/CarbonIntervalSynth.ts";
 import "./synths/CollectionSynth.ts";
 import "./synths/DateSynth.ts";
 import "./synths/TemporaryUploadedFileSynth.ts";
-import type { MiddlewareClass, RouteRegistration } from "@zerotal/core";
-import type { PageClassWithMeta } from "./registry.ts";
 
 // File uploads
 export { TemporaryUploadedFile } from "./uploads/TemporaryUploadedFile.ts";

package/src/jsx-runtime.ts

@@ -163,6 +163,9 @@ interface FlowDirectives {
   [key: `flow:${string}`]: any;
 }
 
+// TypeScript resolves JSX element/attribute types by looking up a JSX namespace —
+// there is no module-shaped way to provide it.
+// eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace JSX {
   export type Element = HtmlNode;
 
@@ -184,6 +187,12 @@ export namespace JSX {
     lazy?: boolean;
     /** Mount a child component right after the first paint (non-blocking). */
     defer?: boolean;
+    /**
+     * Render a child component's placeholder now and its real markup later on the
+     * same response — no second round trip. For content that is definitely needed
+     * and merely slow; use `lazy`/`defer` for content that may never be needed.
+     */
+    stream?: boolean;
     /**
      * Named slot content for a child component: `slots={{ header: <h2>…</h2>, footer: … }}`.
      * The child places each with `this.slot("header")`; its plain children are the default slot.
@@ -266,9 +275,25 @@ function escapeAttr(s: string): string {
 // (e.g. two simultaneous GET requests each awaiting DB calls) cannot
 // cross-contaminate their page reference or child-thunk lists.
 
+/**
+ * How a failed child render is rendered instead of propagating.
+ *
+ * Installed by `<ErrorBoundary>` onto the thunks whose tokens appear in its
+ * children — see `_protectThunks`.
+ */
+export interface _ThunkBoundary {
+  fallback: (error: unknown) => string;
+}
+
+interface _Thunk {
+  token: string;
+  run: () => Promise<HtmlNode>;
+  boundary?: _ThunkBoundary;
+}
+
 interface _RenderCtx {
   page: Record<string, unknown>;
-  thunks: Array<{ token: string; run: () => Promise<HtmlNode> }>;
+  thunks: _Thunk[];
   seq: number;
   /**
    * Per-render random suffix on the child-placeholder token.
@@ -438,9 +463,17 @@ export async function _renderFlowPage(
       try {
         const node = await render();
         let html = node.html;
-        for (const { token, run } of ctx.thunks) {
-          const childNode = await run();
-          html = html.split(token).join(childNode.html);
+        for (const { token, run, boundary } of ctx.thunks) {
+          let childHtml: string;
+          try {
+            childHtml = (await run()).html;
+          } catch (error) {
+            // Unprotected children still take the page down — a boundary is the
+            // opt-in, and swallowing errors by default would hide real bugs.
+            if (!boundary) throw error;
+            childHtml = boundary.fallback(error);
+          }
+          html = html.split(token).join(childHtml);
         }
         return html;
       } finally {
@@ -759,6 +792,42 @@ function toFlowHtmlAttr(k: string): string {
   return "flow:" + local.replace(/-/g, ".");
 }
 
+/**
+ * Render a JSX child to its HTML string, escaping anything that is not already
+ * an {@link HtmlNode}.
+ *
+ * @internal Exported for built-in components that need their children as markup
+ * before the wrapper element is built — `<ErrorBoundary>` inspects the result
+ * for child tokens, `<SectionContent>` publishes it elsewhere entirely.
+ */
+export function _renderChild(child: unknown): string {
+  return renderChild(child);
+}
+
+/**
+ * Route failures of the child components in `html` through `fallback`.
+ *
+ * `jsx()` has already queued a thunk for every `<Component />` encountered while
+ * building `html`, but none of them have run yet — they resolve after the parent
+ * render finishes. Matching on the tokens embedded in `html` is therefore enough
+ * to say which pending children sit inside this boundary, without the boundary
+ * needing to be told about them.
+ *
+ * A thunk already claimed by an inner boundary keeps it, so the nearest boundary
+ * wins.
+ *
+ * @internal
+ */
+export function _protectThunks(html: string, fallback: (error: unknown) => string): void {
+  const ctx = _getRenderCtx();
+  if (!ctx) return;
+  for (const thunk of ctx.thunks) {
+    if (thunk.boundary === undefined && html.includes(thunk.token)) {
+      thunk.boundary = { fallback };
+    }
+  }
+}
+
 function renderChild(child: unknown): string {
   if (child === null || child === undefined || child === false) return "";
   if (child === true) return "";
@@ -882,6 +951,7 @@ export function jsx(
                 slots?: Record<string, string>;
                 lazy?: boolean;
                 defer?: boolean;
+                stream?: boolean;
               },
             ): Promise<HtmlNode>;
           }
@@ -902,6 +972,7 @@ export function jsx(
         slots: _namedSlots,
         lazy: _lazy,
         defer: _defer,
+        stream: _stream,
         ...componentProps
       } = p;
       const slots: Record<string, string> = {};
@@ -924,6 +995,7 @@ export function jsx(
             props: componentProps,
             ...(_lazy ? { lazy: true } : {}),
             ...(_defer ? { defer: true } : {}),
+            ...(_stream ? { stream: true } : {}),
             ...(Object.keys(slots).length ? { slots } : {}),
           }),
       });
@@ -1016,7 +1088,7 @@ export function jsx(
       // Emitted as flow:{event} so the bridge detects the $flow prefix and
       // evaluates it via Alpine instead of sending a WebSocket action.
       if (typeof target === "function" && !target.name && k.startsWith("on")) {
-        const body = _clientExprFromFn(target as Function);
+        const body = _clientExprFromFn(target);
         const event = k.slice(2).toLowerCase();
         const base = `flow:${event}`;
         const attr = modifiers ? `${base}.${modifiers}` : base;

package/src/pagination.ts

@@ -128,8 +128,7 @@ export function paginate<T>(items: T[], page = 1, perPage = 15): Paginator<T> {
 
 // ── Pagination mixin ──────────────────────────────────────────────────────────
 //
-// The TypeScript equivalent of Livewire's `WithPagination` trait: compose it onto a
-// component to add a URL-synced `page` plus page-navigation methods (`nextPage`,
+// A mixin: compose it onto a component to add a URL-synced `page` plus page-navigation methods (`nextPage`,
 // `previousPage`, `gotoPage`, `resetPage`), WITHOUT putting any of that on
 // the base Component.
 //
@@ -147,12 +146,12 @@ export function paginate<T>(items: T[], page = 1, perPage = 15): Paginator<T> {
 // applied here register on the mixin's prototype, which the component's prototype-chain
 // walk already traverses — so it "just works".
 //
-// Named paginators (Livewire's `pageName`): every nav method accepts an optional page
+// Named paginators: every nav method accepts an optional page
 // name so a single page can drive more than one independent paginator —
 // `this.nextPage("invoices")`, `Invoice.paginate(10, undefined, "invoices")`. The default
 // paginator ("page") is the URL-synced one; named paginators live in the snapshot.
 //
-// Optional update hooks fire around a page change, mirroring Livewire — define any of
+// Optional update hooks fire around a page change — define any of
 // `updatingPage(page, name)` / `updatedPage(page, name)` (default paginator) or the
 // generic `updatingPaginators(page, name)` / `updatedPaginators(page, name)`.
 
@@ -174,8 +173,7 @@ interface PaginationHooks {
 const DEFAULT_PAGE = "page";
 
 /**
- * Component mixin that adds URL-synced pagination state and navigation actions —
- * flow's equivalent of Livewire's `WithPagination` trait.
+ * Component mixin that adds URL-synced pagination state and navigation actions.
  *
  * @remarks
  * Composing this onto a component adds:
@@ -221,7 +219,7 @@ export function Pagination<TBase extends AbstractComponentCtor>(Base: TBase) {
     /** Current page of the default paginator, synced to the `?page=` query string. */
     @expose @url page = 1;
 
-    /** Current page of each NAMED paginator (Livewire `pageName`), keyed by name. Snapshot-only. */
+    /** Current page of each NAMED paginator, keyed by name. Snapshot-only. */
     @expose paginators: Record<string, number> = {};
 
     /**

package/src/provider/FlowProvider.ts

@@ -97,7 +97,7 @@ export function _runtimeJs(): string | null {
   return _runtimeBundle;
 }
 
-// ── Rate limiter for HMAC failures (Livewire pattern) ─────────────────────────
+// ── Rate limiter for HMAC failures ───────────────────────────────────────────
 
 const _checksumFailures = new Map<string, { count: number; since: number }>();
 const CHECKSUM_MAX = 10;
@@ -260,7 +260,7 @@ async function _handleFlowMessage(ws: FlowBunWs, raw: string, deps: FlowWsDeps):
   // with no user at all, so every action on an authenticated page is rejected
   // as somebody else's.
 
-  // ── Persistent middleware (Livewire-style) ──────────────────────────────────
+  // ── Persistent middleware ───────────────────────────────────────────────────
   const pagePath = frame.snapshot.memo.path;
   const middleware = [
     ...deps.globalMiddleware().filter(_isPersistentMiddleware),
@@ -785,7 +785,7 @@ async function _dispatchFrame(
     ws.send(JSON.stringify({ type: "flash", component: canonicalId, ...f }));
   }
 
-  // Dispatch cross-component events (to/self targeting mirrors Livewire's dispatch()->to()/->self()).
+  // Dispatch cross-component events (to/self targeting).
   for (const event of effects.events) {
     ws.send(
       JSON.stringify({
@@ -922,10 +922,9 @@ export class FlowProvider extends ServiceProvider {
   }
 
   /**
-   * Global middleware re-applied on every WebSocket update (Livewire-style
-   * persistent middleware). Matched against the app's global pipeline by
-   * class reference or class name. Route middleware always re-runs and does
-   * not need to be listed here.
+   * Global middleware re-applied on every WebSocket update. Matched against the
+   * app's global pipeline by class reference or class name. Route middleware
+   * always re-runs and does not need to be listed here.
    */
   static persistentMiddleware: (string | MiddlewareClass)[] = [...DEFAULT_PERSISTENT_MIDDLEWARE];
 
@@ -966,6 +965,11 @@ export class FlowProvider extends ServiceProvider {
     this._applyPersistentMiddlewareConfig();
     Router.macro("flow", flowRoute);
 
+    // Declared here rather than alongside the handlers below, because the handlers are
+    // only wired in the web runtime and `bun zt doctor --url=…` runs in a console one.
+    // The socket is the whole application, so a CLI that cannot name it cannot check it.
+    this.app.declareWebSocketPath("/__flow/ws");
+
     registerFileRouteResolver(({ urlPath, module, middleware, name, filePath }) => {
       const PageClass = _findPageExport(module);
       if (!PageClass) return false;
@@ -1244,8 +1248,13 @@ export class FlowProvider extends ServiceProvider {
 
     if (!cssExists && !jsExists) return;
 
-    const { registerDevBuildHook, buildCssBundle, buildJsBundle } =
-      await import("@zerotal/core/dev");
+    const {
+      registerDevBuildHook,
+      buildCssBundle,
+      buildJsBundle,
+      isDevOrchestrated,
+      bootBuildDecision,
+    } = await import("@zerotal/core/dev");
 
     // Combined hook — DevOrchestrator calls this on any frontend file change.
     // Registered under Flow's own name so it sits alongside, rather than on
@@ -1256,16 +1265,40 @@ export class FlowProvider extends ServiceProvider {
       const results = await Promise.all([
         cssExists
           ? buildCssBundle(cssEntry, cssOutdir, false)
-          : Promise.resolve({ success: true, logs: [] as unknown[] }),
+          : Promise.resolve({ success: true, logs: [] as unknown[], skipped: true }),
         jsExists
           ? buildJsBundle(jsEntry, jsOutdir, false)
-          : Promise.resolve({ success: true, logs: [] as unknown[] }),
+          : Promise.resolve({ success: true, logs: [] as unknown[], skipped: true }),
       ]);
       const failed = results.flatMap((r) => (r.success ? [] : (r.logs ?? [])));
-      return { success: failed.length === 0, logs: failed };
+      return {
+        success: failed.length === 0,
+        logs: failed,
+        // A bundle with no entry point counts as skipped: it did no work either.
+        skipped: results.every((r) => r.skipped === true),
+      };
     });
 
-    // Build once at startup so assets are ready before the first request.
+    // Build once at startup so assets are ready before the first request —
+    // except under `serve --dev`, where the orchestrator owns builds and has
+    // already run the hook above before this process could serve anything.
+    // Without this guard a Flow app built its bundles three times per boot (once
+    // here in the orchestrator process, once in the orchestrator's own initial
+    // build, once here again in the spawned worker) and twice per backend save.
+    if (isDevOrchestrated()) return;
+
+    // Nor in a production deployment whose output directory is read-only: those assets
+    // were built at deploy time, and rebuilding them is what turns a hardened systemd
+    // unit into a restart loop. See @zerotal/core/dev/bootBuild.ts.
+    const decision = await bootBuildDecision(
+      [...(cssExists ? [cssOutdir] : []), ...(jsExists ? [jsOutdir] : [])],
+      config.safe<string>("app.env", Bun.env["APP_ENV"] ?? "development"),
+    );
+    if (!decision.build) {
+      console.info(`[Flow] ${decision.reason}`);
+      return;
+    }
+
     const [cssResult, jsResult] = await Promise.all([
       cssExists
         ? buildCssBundle(cssEntry, cssOutdir, false)