@zerotal/flow 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -11,6 +11,28 @@ change.
 
 ## [Unreleased]
 
+## [1.6.0] — 2026-08-15
+
+### Added
+
+- **`$route()` in Alpine expressions.** Build a URL by route name in the browser, from the
+  same table the server rendered with:
+
+  ```html
+  <a :href="$route('posts.show', { slug: post.slug })">Read</a>
+  ```
+
+  Nothing to install and nothing to wire up. Inertia apps hand `route()` their table by
+  static import, but `/__flow/runtime.js` is built by the framework rather than by your app,
+  so it cannot import a file that lives in the application. The runtime handler serialises
+  `Router.namedRoutes` onto the bundle it serves instead — at serve time, not at build time,
+  because the bundle is built in `onBooting()` when providers registered after Flow have not
+  added their routes yet. The bundle is already `no-store`, so there is no cache to
+  invalidate and nothing is added to any page's HTML.
+
+  Same helper as the server's `route()`, sharing one URL builder, so a link built in an
+  Alpine expression and one built in JSX cannot disagree about encoding.
+
 ## [1.5.0] — 2026-08-15
 
 ### Changed — BREAKING

package/package.json

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

package/src/Component.ts

@@ -30,6 +30,7 @@ import { _validateEventPayload } from "./events.ts";
 import type { FlowEvents, EventName, EventArgs } from "./events.ts";
 import { route, request, safeRedirectPath, HttpContext } from "@zerotal/core";
 import type { RouteParamValues, RouteParamsArg, RouteTarget } from "@zerotal/core";
+import { isProdLike, deployEnv } from "@zerotal/core";
 
 /**
  * Convert the validator's one-message-per-field result (`Record<string, string>`) into
@@ -167,7 +168,9 @@ function _fnv1a(input: string): string {
 }
 
 function _isProduction(): boolean {
-  return (Bun.env["APP_ENV"] ?? Bun.env["NODE_ENV"]) === "production";
+  // `deployEnv()`, not `APP_ENV` — the latter holds the runtime mode once the app
+  // has booted, so this answered "no" on every production server.
+  return isProdLike(deployEnv()) || Bun.env["NODE_ENV"] === "production";
 }
 
 /** Classes already warned about, so a hundred-row list logs once. */

package/src/client/bridge.ts

@@ -34,6 +34,7 @@ import { confirmDialog, type ConfirmDialogOptions } from "./confirm.ts";
 import { showErrorOverlay } from "./errorOverlay.ts";
 import { applyAppend, applyRemove, type OptOp } from "./optimistic.ts";
 import { clientStore } from "../store.ts";
+import { route } from "@zerotal/core/routes";
 import { URL_ATTRIBUTES, sanitizeUrl } from "../urlSafety.ts";
 import {
   recordFrame as _recordTimelineFrame,
@@ -3659,6 +3660,12 @@ export function registerFlowMagic(alpine: AlpineType): void {
         // $store — the "flow" Alpine store (app-wide, client-only UI state). It's a real Alpine
         // store, so reads inside a binding track and writes re-render with no round-trip. Declare
         // its shape with defineStore(); see store.ts.
+        // $route('posts.show', { slug }) — the same helper the server renders
+        // with, so a link built in an Alpine expression and one built in JSX
+        // resolve identically. The table is installed from window.__zerotalRoutes
+        // by the bundle entry (see installClientRoutes).
+        if (key === "$route") return route;
+
         if (key === "$store") return clientStore();
 
         // $dispatch('event', {data}) — fire an event to every component on the page

package/src/client/index.csp.ts

@@ -20,6 +20,10 @@ import { initBridge, registerFlowMagic, setCspMode } from "./bridge.ts";
 import { registerHeadless } from "./headless.ts";
 import { installCspEvaluator } from "./cspAdapter.ts";
 import { initClientStore } from "../store.ts";
+import { installClientRoutes } from "./routes.ts";
+
+// Install the route table before anything can evaluate a `$route(...)` binding.
+installClientRoutes();
 
 (window as unknown as Record<string, unknown>).Alpine = Alpine;
 

package/src/client/index.ts

@@ -21,6 +21,10 @@ import resize from "@alpinejs/resize";
 import { initBridge, registerFlowMagic } from "./bridge.ts";
 import { registerHeadless } from "./headless.ts";
 import { initClientStore } from "../store.ts";
+import { installClientRoutes } from "./routes.ts";
+
+// Install the route table before anything can evaluate a `$route(...)` binding.
+installClientRoutes();
 
 // Expose Alpine on window so FlowComponent and third-party Alpine plugins
 // can access it via window.Alpine (standard Alpine convention).

package/src/client/routes.ts

@@ -0,0 +1,40 @@
+/**
+ * Install the route table into the Flow client runtime.
+ *
+ * Inertia apps hand `route()` their table by static import, because they own
+ * their bundle entry. Flow apps don't: `/__flow/runtime.js` is built by the
+ * framework from `client/index.ts`, so it cannot import a file that lives in
+ * the application. The table is handed over at serve time instead — the runtime
+ * handler prepends `window.__zerotalRoutes = {...}` to the bundle it returns
+ * (see `FlowProvider`), and this reads it back.
+ *
+ * Prepending rather than embedding at build time is deliberate: the bundle is
+ * built in `onBooting()`, when providers registered after Flow have not added
+ * their routes yet. The handler runs per request, long after boot, so the table
+ * it serialises is the complete one. The bundle is already `no-store`, so there
+ * is no cache to invalidate.
+ */
+import { defineRoutes } from "@zerotal/core/routes";
+
+// Declared rather than cast at the call site: `window` genuinely carries this
+// property in a Flow page, and saying so once is what makes reading it type-safe
+// everywhere instead of an assertion each time.
+declare global {
+  interface Window {
+    /** The route table the runtime handler prepends to the bundle. */
+    __zerotalRoutes?: Readonly<Record<string, string>>;
+  }
+}
+
+/**
+ * Read `window.__zerotalRoutes` and install it, so `$route(...)` in an Alpine
+ * expression resolves the same names the server rendered with.
+ *
+ * Installs an empty table when the global is absent — `route()` then throws
+ * "Named route not found" for any name, which is the truthful error. Leaving it
+ * uninstalled would instead report a missing `defineRoutes()` call and send the
+ * reader looking for app wiring that Flow does not have.
+ */
+export function installClientRoutes(): void {
+  defineRoutes(window.__zerotalRoutes ?? {});
+}

package/src/dehydrate.ts

@@ -14,6 +14,7 @@ import {
   resolveSharedChannel,
 } from "./decorators.ts";
 import { ZerotalError, safeEqual, hmacHex, RequestContext } from "@zerotal/core";
+import { isProdLike, deployEnv } from "@zerotal/core";
 
 // ── Stable JSON stringify ─────────────────────────────────────────────────────
 // Keys are sorted so the HMAC is deterministic regardless of insertion order.
@@ -316,8 +317,7 @@ export function applySnapshotDelta(prev: Snapshot, delta: SnapshotDelta): Snapsh
 const SNAPSHOT_WARN_BYTES = 100 * 1024; // 100 KB
 
 export function warnIfLarge(snapshot: Snapshot, name: string): void {
-  const env = Bun.env["APP_ENV"] ?? "development";
-  if (env === "production" || env === "prod") return;
+  if (isProdLike(deployEnv())) return;
 
   // Buffer.byteLength is a native call that avoids allocating a typed array.
   const size = Buffer.byteLength(JSON.stringify(snapshot), "utf8");

package/src/provider/FlowProvider.ts

@@ -19,6 +19,7 @@ import { installFlowObservability } from "../observability.ts";
 import { DEFAULT_PERSISTENT_MIDDLEWARE } from "../config.ts";
 import type { AppEnvironment, Container, MiddlewareClass, NextFn } from "@zerotal/core";
 import type { WebSocketHandlers } from "@zerotal/core";
+import { isProdLike, deployEnv } from "@zerotal/core";
 import type { CallFrame, Snapshot } from "../types.ts";
 import { getPage, getAllowedMethods, getRenderlessMethods, BUILTIN_ACTIONS } from "../registry.ts";
 import {
@@ -44,6 +45,21 @@ import { isAllowedOrigin } from "@zerotal/core/http";
 
 // ── In-memory runtime.js bundle (built once at boot) ─────────────────────────
 
+/**
+ * The `window.__zerotalRoutes = {...}` line prepended to the served runtime
+ * bundle, which `installClientRoutes()` reads back on load.
+ *
+ * Served as JavaScript, not embedded in HTML, so the `</script>` hazard the
+ * state island guards against does not apply here — this response is never
+ * parsed as markup. Plain `JSON.stringify` is enough.
+ *
+ * @internal exported for tests.
+ */
+export function _routeTablePrelude(): string {
+  const table = Object.fromEntries(Router.namedRoutes);
+  return `window.__zerotalRoutes=${JSON.stringify(table)};\n`;
+}
+
 /** True when this process is the `serve --dev-worker` (dev fast refresh gates on it). */
 const _isDevWorker = Bun.argv.includes("--dev-worker");
 
@@ -998,7 +1014,9 @@ export class FlowProvider extends ServiceProvider {
       const result = await Bun.build({
         entrypoints: [entry],
         target: "browser",
-        minify: Bun.env["APP_ENV"] === "production",
+        // `deployEnv()` — comparing APP_ENV ran the check against the runtime mode
+        // ("web"), so the client bundle shipped UNMINIFIED to every production visitor.
+        minify: isProdLike(deployEnv()),
         format: "esm",
       });
 
@@ -1023,7 +1041,13 @@ export class FlowProvider extends ServiceProvider {
             });
             return;
           }
-          http.response = new Response(_runtimeBundle, {
+          // Prepend the named-route table so `$route(...)` resolves the same
+          // names the server renders with. Serialised here rather than baked
+          // into the bundle because the bundle is built in onBooting(), before
+          // providers registered after Flow have added their routes; this
+          // handler runs per request, so the table is complete. `no-store`
+          // above means there is no cached copy to go stale.
+          http.response = new Response(`${_routeTablePrelude()}${_runtimeBundle}`, {
             status: 200,
             headers: {
               "Content-Type": "text/javascript; charset=utf-8",
@@ -1292,7 +1316,7 @@ export class FlowProvider extends ServiceProvider {
     // 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"),
+      config.safe<string>("app.env", deployEnv() || "development"),
     );
     if (!decision.build) {
       console.info(`[Flow] ${decision.reason}`);