@zerotal/flow 1.0.0

package/src/client/index.csp.ts

@@ -0,0 +1,47 @@
+// ── @zerotal/flow CSP-safe client bundle entry point ─────────────────────────
+//
+// Built by FlowProvider.onBooting() when `flow.cspSafe` is enabled, producing
+// the `/__flow/runtime.js` served to browsers under a strict Content-Security-
+// Policy (no `'unsafe-eval'`).
+//
+// Identical to ./index.ts except it installs the eval-free CSP evaluator
+// (cspAdapter) before Alpine.start() and puts the bridge in CSP mode.
+
+import Alpine from "alpinejs";
+import morph from "@alpinejs/morph";
+import mask from "@alpinejs/mask";
+import focus from "@alpinejs/focus";
+import collapse from "@alpinejs/collapse";
+import anchor from "@alpinejs/anchor";
+import persist from "@alpinejs/persist";
+import resize from "@alpinejs/resize";
+
+import { initBridge, registerFlowMagic, setCspMode } from "./bridge.ts";
+import { registerHeadless } from "./headless.ts";
+import { installCspEvaluator } from "./cspAdapter.ts";
+import { initClientStore } from "../store.ts";
+
+(window as unknown as Record<string, unknown>).Alpine = Alpine;
+
+// Swap Alpine's evaluator for the eval-free interpreter BEFORE anything evaluates.
+installCspEvaluator(Alpine as never);
+setCspMode(true); // bridge-managed bindings (flow:text, …) also avoid new Function
+
+Alpine.plugin(morph);
+Alpine.plugin(mask);
+Alpine.plugin(focus);
+Alpine.plugin(collapse);
+Alpine.plugin(anchor);
+Alpine.plugin(persist);
+Alpine.plugin(resize);
+
+registerFlowMagic(Alpine as never);
+registerHeadless(Alpine as never);
+
+document.addEventListener("DOMContentLoaded", () => {
+  initBridge();
+  // Create the reactive global `store` (draining any defineStore() calls) BEFORE Alpine.start,
+  // so `$flow.store.*` bindings resolve against one shared object on their first evaluation.
+  initClientStore(Alpine as never);
+  Alpine.start();
+});

package/src/client/index.ts

@@ -0,0 +1,56 @@
+// ── @zerotal/flow client bundle entry point ─────────────────────────────────────
+//
+// This file is the entry point for Bun.build() in FlowProvider.onBooting().
+// It produces /__flow/runtime.js served to browsers.
+//
+// Includes:
+//   - Alpine.js core
+//   - @alpinejs/morph plugin (DOM diffing)
+//   - UI plugins: mask, focus (x-trap/$focus), collapse, anchor, persist ($persist), resize (x-resize)
+//   - Flow WS bridge + $flow magic
+
+import Alpine from "alpinejs";
+import morph from "@alpinejs/morph";
+import mask from "@alpinejs/mask";
+import focus from "@alpinejs/focus";
+import collapse from "@alpinejs/collapse";
+import anchor from "@alpinejs/anchor";
+import persist from "@alpinejs/persist";
+import resize from "@alpinejs/resize";
+
+import { initBridge, registerFlowMagic } from "./bridge.ts";
+import { registerHeadless } from "./headless.ts";
+import { initClientStore } from "../store.ts";
+
+// Expose Alpine on window so FlowComponent and third-party Alpine plugins
+// can access it via window.Alpine (standard Alpine convention).
+(window as unknown as Record<string, unknown>).Alpine = Alpine;
+
+// Register Alpine plugins (morph powers server patches; the rest back the Tier 3
+// directives: mask → x-mask, focus → x-trap/$focus, collapse → x-collapse,
+// anchor → x-anchor, persist → $persist, resize → x-resize).
+Alpine.plugin(morph);
+Alpine.plugin(mask);
+Alpine.plugin(focus);
+Alpine.plugin(collapse);
+Alpine.plugin(anchor);
+Alpine.plugin(persist);
+Alpine.plugin(resize);
+
+// Register $flow magic BEFORE Alpine.start() so it's available in x-data
+registerFlowMagic(Alpine as never);
+
+// Register headless Alpine.data factories (flowRadioGroup, flowListbox).
+registerHeadless(Alpine as never);
+
+// initBridge() MUST run before Alpine.start(). Alpine evaluates x-text / x-show
+// expressions immediately on start; the $flow magic needs _components populated
+// (by initBridge) or it returns undefined and no reactive dependency is tracked —
+// meaning x-text bindings would never update after the initial render.
+document.addEventListener("DOMContentLoaded", () => {
+  initBridge(); // ← registers FlowComponents into _components first
+  // Create the reactive global `store` (draining any defineStore() calls queued at
+  // app start) BEFORE Alpine.start, so `store.*` bindings resolve on first evaluation.
+  initClientStore(Alpine as never);
+  Alpine.start(); // ← then Alpine processes x-text etc. with $flow + store working
+});

package/src/client/optimistic.ts

@@ -0,0 +1,52 @@
+// ── Optimistic collections (client) ────────────────────────────────────────────
+//
+// `appendOptimistic(prop, item)` / `removeOptimistic(prop, match)` mutate a reactive array on the
+// client *before* the server confirms, so a list add/remove shows instantly. The item survives any
+// interim (broadcast/event) patch — the pending ops are re-applied on top of each server merge —
+// and is reconciled when the owning action's patch lands: on success the authoritative server list
+// stands (the real, persisted row); on failure the server list is unchanged, so the optimistic
+// change rolls back automatically. This module is the pure, DOM-free core (the bridge applies it to
+// the live Alpine store).
+
+/** A pending optimistic mutation on one array prop. */
+export interface OptOp {
+  prop: string;
+  kind: "append" | "remove";
+  /** The exact item reference appended (append ops). */
+  item?: unknown;
+  /** Predicate identifying the removed item(s) (remove ops). */
+  match?: (item: unknown) => boolean;
+}
+
+/** Append `item` unless the array already holds that exact reference (idempotent re-apply). */
+export function applyAppend(arr: readonly unknown[], item: unknown): unknown[] {
+  return arr.includes(item) ? [...arr] : [...arr, item];
+}
+
+/** Remove every item matching `match`. */
+export function applyRemove(arr: readonly unknown[], match: (item: unknown) => boolean): unknown[] {
+  return arr.filter((x) => !match(x));
+}
+
+/**
+ * Re-apply all pending ops onto a fresh (server) snapshot of the arrays, keyed by prop. Pure —
+ * returns a new record, leaving `current` untouched. Ops for props absent from `current` (or
+ * non-array values) are skipped.
+ */
+export function reapply(
+  current: Record<string, unknown[]>,
+  ops: readonly OptOp[],
+): Record<string, unknown[]> {
+  const out: Record<string, unknown[]> = { ...current };
+  for (const op of ops) {
+    const arr = out[op.prop];
+    if (!Array.isArray(arr)) continue;
+    out[op.prop] = op.kind === "append" ? applyAppend(arr, op.item) : applyRemove(arr, op.match!);
+  }
+  return out;
+}
+
+/** The distinct prop names touched by a set of ops (so the bridge knows which arrays to refresh). */
+export function opProps(ops: readonly OptOp[]): string[] {
+  return [...new Set(ops.map((o) => o.prop))];
+}

package/src/client/timeline.ts

@@ -0,0 +1,160 @@
+// ── Time-travel devtools (client, dev-only) ───────────────────────────────────
+//
+// The engine already signs and delta-encodes the full component state on every round-trip,
+// and the client already receives + reconstructs that snapshot for each patch. This module
+// RECORDS that stream — one frame per applied patch (plus the initial mount) — into a capped
+// ring buffer, and lets a dev scrub back to any frame: "jump" re-applies a held snapshot + its
+// HTML to the live component (client-only, no server), so state and DOM restore exactly.
+//
+// It is intentionally DOM-free and dependency-free (types only) so the core is unit-testable.
+// The one DOM-touching step — applying a frame to a live component — is an APPLIER function the
+// bridge injects via setTimelineApplier(); everything else is pure data.
+
+import type { Snapshot, SnapshotData } from "../types.ts";
+
+/** One recorded step in the timeline: the component's state (and DOM) after a patch. */
+export interface TimelineFrame {
+  /** Monotonic global sequence number (ordering across all components). */
+  seq: number;
+  compId: string;
+  compName: string;
+  /** The action that produced this frame — a method name, `"$set"`, or `"mount"`. */
+  action: string;
+  /** The full signed snapshot at this frame (restored verbatim on a jump). */
+  snapshot: Snapshot;
+  /** Snapshot-data field names that changed since this component's previous frame. */
+  changed: string[];
+  /** The component's outer HTML at this frame, for DOM restore on a jump. */
+  html: string | null;
+  ts: number;
+}
+
+const MAX_FRAMES = 250;
+
+let _enabled = false;
+let _seq = 0;
+const _frames: TimelineFrame[] = [];
+const _lastDataByComp = new Map<string, SnapshotData>();
+const _currentByComp = new Map<string, number>(); // compId → seq currently displayed (live = latest)
+const _subs = new Set<() => void>();
+
+/** DOM applier injected by the bridge; restores a frame's snapshot + HTML into the live component. */
+type Applier = (frame: TimelineFrame) => void;
+let _apply: Applier | null = null;
+
+export function setTimelineEnabled(on: boolean): void {
+  _enabled = on;
+}
+export function isTimelineEnabled(): boolean {
+  return _enabled;
+}
+export function setTimelineApplier(fn: Applier): void {
+  _apply = fn;
+}
+
+/** Subscribe to timeline changes (a new frame, or a jump) — used to re-render the panel. */
+export function onTimelineChange(fn: () => void): void {
+  _subs.add(fn);
+}
+function _notify(): void {
+  for (const fn of _subs) {
+    try {
+      fn();
+    } catch {
+      /* a panel render error must not break recording */
+    }
+  }
+}
+
+/** Field names that differ between two snapshot-data maps (added, removed, or changed value). */
+export function computeChanged(prev: SnapshotData | undefined, next: SnapshotData): string[] {
+  const changed: string[] = [];
+  for (const [k, v] of Object.entries(next)) {
+    const before = prev?.[k];
+    if (before === undefined || JSON.stringify(before) !== JSON.stringify(v)) changed.push(k);
+  }
+  if (prev) for (const k of Object.keys(prev)) if (!(k in next)) changed.push(k);
+  return changed;
+}
+
+/**
+ * Record a frame for a just-applied patch (or the initial mount). No-op unless enabled.
+ * Computes the changed fields vs this component's previous frame and appends to the ring buffer.
+ */
+export function recordFrame(input: {
+  compId: string;
+  compName: string;
+  action: string;
+  snapshot: Snapshot;
+  html: string | null;
+}): TimelineFrame | null {
+  if (!_enabled) return null;
+  const changed = computeChanged(_lastDataByComp.get(input.compId), input.snapshot.data);
+  _lastDataByComp.set(input.compId, input.snapshot.data);
+  const frame: TimelineFrame = {
+    seq: _seq++,
+    compId: input.compId,
+    compName: input.compName,
+    action: input.action,
+    snapshot: input.snapshot,
+    changed,
+    html: input.html,
+    ts: Date.now(),
+  };
+  _frames.push(frame);
+  if (_frames.length > MAX_FRAMES) _frames.shift();
+  _currentByComp.set(frame.compId, frame.seq); // a live frame → we're at the latest
+  _notify();
+  return frame;
+}
+
+export function getFrames(): readonly TimelineFrame[] {
+  return _frames;
+}
+export function getFramesFor(compId: string): TimelineFrame[] {
+  return _frames.filter((f) => f.compId === compId);
+}
+export function frameBySeq(seq: number): TimelineFrame | undefined {
+  return _frames.find((f) => f.seq === seq);
+}
+export function latestFrameFor(compId: string): TimelineFrame | undefined {
+  for (let i = _frames.length - 1; i >= 0; i--)
+    if (_frames[i]!.compId === compId) return _frames[i];
+  return undefined;
+}
+/** The seq currently displayed for a component (its latest frame unless the user jumped back). */
+export function currentSeq(compId: string): number | undefined {
+  return _currentByComp.get(compId);
+}
+/** True when the component is showing its most recent frame (not rewound). */
+export function isLive(compId: string): boolean {
+  const latest = latestFrameFor(compId);
+  return !latest || _currentByComp.get(compId) === latest.seq;
+}
+
+/** Restore the component to the frame with this seq (client-only). Returns false if unavailable. */
+export function jumpTo(seq: number): boolean {
+  const f = frameBySeq(seq);
+  if (!f || !_apply) return false;
+  _apply(f);
+  _currentByComp.set(f.compId, seq);
+  _notify();
+  return true;
+}
+
+/** Return a rewound component to its most recent frame. */
+export function resumeLive(compId: string): boolean {
+  const f = latestFrameFor(compId);
+  return f ? jumpTo(f.seq) : false;
+}
+
+/** @internal Test hook — clear all recorded state. */
+export function _resetTimeline(): void {
+  _seq = 0;
+  _frames.length = 0;
+  _lastDataByComp.clear();
+  _currentByComp.clear();
+  _subs.clear();
+  _apply = null;
+  _enabled = false;
+}

package/src/client/url.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure URL helpers for SPA navigation. No Alpine / DOM imports so this stays
+ * unit-testable in isolation — the `$flow.currentUrl` / `$flow.navigateCurrent`
+ * helpers in bridge.ts feed it `window.location.href`.
+ */
+
+/** Options for {@link buildUrlWithQuery}: query params to merge and an optional hash. */
+export interface CurrentUrlOptions {
+  /**
+   * Query params to add/update/remove on top of the base URL. A value of
+   * `null`, `undefined`, or `""` removes the param; anything else is stringified
+   * and set. Params not listed here are preserved.
+   */
+  query?: Record<string, unknown>;
+  /** Replace the URL hash. `""` clears it; omit to leave the hash untouched. */
+  hash?: string;
+}
+
+/**
+ * Build a URL from `baseHref`, merging the given query-param changes.
+ *
+ * Mirrors the ergonomics of filter UIs: pass only the params you want to change,
+ * clear one by passing an empty/nullish value, and keep everything else.
+ *
+ * @example
+ *   // base: /users?search=john&status=active&page=2
+ *   buildUrlWithQuery(location.href, { query: { page: 3 } })
+ *   // → /users?search=john&status=active&page=3
+ *
+ *   buildUrlWithQuery(location.href, { query: { status: null, page: 1 } })
+ *   // → /users?search=john&page=1   (status removed)
+ */
+export function buildUrlWithQuery(baseHref: string, options: CurrentUrlOptions = {}): string {
+  const url = new URL(baseHref);
+
+  if (options.query) {
+    for (const [key, value] of Object.entries(options.query)) {
+      if (value === null || value === undefined || value === "") {
+        url.searchParams.delete(key);
+      } else {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+
+  if (options.hash !== undefined) {
+    url.hash = options.hash;
+  }
+
+  return url.toString();
+}

package/src/commands/MakeFlowCommand.ts

@@ -0,0 +1,290 @@
+/**
+ * The `make:flow` command — scaffolds a Flow page or child component.
+ *
+ * This is the Flow counterpart to `make:controller` / `make:page`: the
+ * flagship server-driven layer previously had no generator, so every
+ * `Component` was hand-written. `make:flow Name` emits a ready-to-run class
+ * with an `@expose`/`render` skeleton; `--child`, `--crud`, and `--layout`
+ * cover the common shapes.
+ */
+import { Command } from "@zerotal/core";
+import { existsSync } from "node:fs";
+
+/** Where pages live, in preference order. Real apps use `app/flow/pages`. */
+const PAGE_DIRS = ["app/flow/pages", "app/flow"];
+/** Where child components live, in preference order. */
+const CHILD_DIRS = ["app/flow/components", "app/flow/components"];
+
+export class MakeFlowCommand extends Command {
+  static override commandName = "make:flow";
+  static override description = "Create a new Flow page or child component";
+  static override needsApp = false;
+
+  static override args = [
+    {
+      name: "name",
+      required: true,
+      description: "Class name, optionally nested (e.g. Dashboard or Users/Index)",
+    },
+  ];
+
+  static override flags = [
+    {
+      name: "child",
+      type: "boolean" as const,
+      description: "Scaffold a child component (props come from its parent) instead of a page",
+      default: false,
+    },
+    {
+      name: "crud",
+      type: "boolean" as const,
+      description: "Scaffold a resourceful page with list/create/edit/delete actions",
+      default: false,
+    },
+    {
+      name: "layout",
+      type: "string" as const,
+      description: "Wrap the page in a layout, e.g. --layout AppLayout",
+      default: "",
+    },
+    {
+      name: "dir",
+      type: "string" as const,
+      description: "Override the target directory (default: app/flow/pages or app/flow/components)",
+      default: "",
+    },
+  ];
+
+  override async run(): Promise<void> {
+    const name = this.args["name"]!; // e.g. "Users/Index"
+    const child = this.flags["child"] as boolean;
+    const crud = this.flags["crud"] as boolean;
+    const layout = ((this.flags["layout"] as string | undefined) ?? "").trim();
+    const dirFlag = ((this.flags["dir"] as string | undefined) ?? "").trim();
+
+    const componentName = name.includes("/") ? name.split("/").pop()! : name;
+    const baseDir = dirFlag
+      ? dirFlag.replace(/\\/g, "/").replace(/\/+$/, "")
+      : _pickDir(child ? CHILD_DIRS : PAGE_DIRS);
+    const path = `${baseDir}/${name}.tsx`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    // Depth relative to the pages dir, so the layout import resolves correctly:
+    // a page at app/flow/pages/Foo.tsx reaches app/flow/layouts/AppLayout.tsx via ../layouts/…
+    const depth = name.split("/").length;
+    const prefix = "../".repeat(depth);
+
+    let stub: string;
+    if (child) {
+      if (crud || layout) {
+        this.warn("--crud and --layout are ignored for a child component.");
+      }
+      stub = _childStub(componentName);
+    } else if (crud) {
+      stub = _crudStub(componentName, layout, prefix);
+    } else {
+      stub = _pageStub(componentName, layout, prefix);
+    }
+
+    await Bun.write(path, stub);
+    this.info(`Created: ${path}`);
+
+    if (layout && !child) {
+      this.dim(
+        `  Layout: assumes \`export { ${layout} }\` from ${prefix}layouts/${layout}.tsx — ` +
+          `adjust the import if your layout's path or export name differs.`,
+      );
+    }
+
+    if (!child) {
+      // File-based routing (`.fileBasedRouting("app/flow/pages")`) auto-discovers this page.
+      // Show the explicit registration too, for apps that register routes by hand.
+      const url = _urlFor(name);
+      this.dim(
+        "  File-based routing serves this automatically. To register it explicitly, add to routes/web.ts:",
+      );
+      this.dim(`    Router.flow("${url}", ${componentName});`);
+    }
+  }
+}
+
+/** First existing candidate directory, else the first candidate as the default. */
+function _pickDir(candidates: string[]): string {
+  return candidates.find((d) => existsSync(d)) ?? candidates[0]!;
+}
+
+/** Derive a kebab-case URL path from a (possibly nested) class name. */
+function _urlFor(name: string): string {
+  const segments = name.split("/").map((seg) =>
+    seg
+      .replace(/Page$/, "")
+      .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+      .toLowerCase(),
+  );
+  const path = segments.filter(Boolean).join("/");
+  return "/" + path;
+}
+
+function _layoutImport(layout: string, prefix: string): string {
+  return layout ? `import { ${layout} } from "${prefix}layouts/${layout}.tsx";\n` : "";
+}
+
+function _layoutStatic(layout: string): string {
+  return layout ? `  static layout = ${layout};\n\n` : "";
+}
+
+/** A minimal page: one exposed field, one action, a render. */
+function _pageStub(name: string, layout: string, prefix: string): string {
+  return `/** @jsxImportSource @zerotal/flow */
+import { Component, expose } from "@zerotal/flow";
+${_layoutImport(layout, prefix)}
+export class ${name} extends Component {
+${_layoutStatic(layout)}  @expose count = 0;
+
+  @expose increment(): void {
+    this.count++;
+  }
+
+  override async render() {
+    return (
+      <div>
+        <h1>${name}</h1>
+        <p>Count: {this.count}</p>
+        <button onClick={this.increment}>+</button>
+      </div>
+    );
+  }
+}
+`;
+}
+
+/** A child component: props assigned by the parent, its own isolated state. */
+function _childStub(name: string): string {
+  return `/** @jsxImportSource @zerotal/flow */
+import { Component, expose, locked } from "@zerotal/flow";
+
+export class ${name} extends Component {
+  // A prop from the parent lands on the same-named field before any hook runs.
+  // Mark it @locked so the value survives WebSocket round-trips.
+  @locked label = "Count";
+
+  @expose count = 0;
+
+  @expose increment(): void {
+    this.count++;
+  }
+
+  override async render() {
+    return (
+      <div class="rounded-lg border p-4">
+        <p class="text-sm text-gray-500">{this.label}</p>
+        <p class="text-2xl font-bold">{this.count}</p>
+        <button onClick={this.increment}>+</button>
+      </div>
+    );
+  }
+}
+`;
+}
+
+/** A resourceful page: list + create/edit/delete, validation, and a form. */
+function _crudStub(name: string, layout: string, prefix: string): string {
+  return `/** @jsxImportSource @zerotal/flow */
+import { Component, expose, locked, validate } from "@zerotal/flow";
+${_layoutImport(layout, prefix)}
+// TODO: swap this shape for your model type.
+interface Item {
+  id: number;
+  name: string;
+}
+
+export class ${name} extends Component {
+${_layoutStatic(layout)}  @locked items: Item[] = [];
+  @expose editingId: number | null = null;
+  @expose @validate((rule) => rule.required().min(2)) name = "";
+
+  override async onMount(): Promise<void> {
+    await this.load();
+  }
+
+  @expose async load(): Promise<void> {
+    // TODO: load from your model, e.g. this.items = await Item.query().get();
+    this.items = [];
+  }
+
+  @expose async save(): Promise<void> {
+    await this.validate();
+
+    if (this.editingId === null) {
+      // TODO: create — await Item.create({ name: this.name });
+    } else {
+      // TODO: update — await Item.where("id", this.editingId).update({ name: this.name });
+    }
+
+    this.reset();
+    this.refresh(); // re-run onMount() → reload the list
+    this.flash("Saved.");
+  }
+
+  @expose edit(id: number): void {
+    const item = this.items.find((i) => i.id === id);
+    if (!item) return;
+    this.editingId = id;
+    this.name = item.name;
+  }
+
+  @expose async destroy(id: number): Promise<void> {
+    // TODO: delete — await Item.where("id", id).delete();
+    this.refresh();
+    this.flash("Deleted.");
+  }
+
+  @expose reset(): void {
+    this.editingId = null;
+    this.name = "";
+    this.resetValidation();
+  }
+
+  override async render() {
+    return (
+      <div class="max-w-xl mx-auto space-y-6 p-6">
+        <h1 class="text-2xl font-bold">${name}</h1>
+
+        <form onSubmit={this.save} class="flex items-start gap-2">
+          <div class="flex-1">
+            <input value={this.name} class="input w-full" placeholder="Name" />
+            <span error={this.errors.name} class="text-sm text-red-500" />
+          </div>
+          <button type="submit" loadingAttr="disabled">
+            {this.editingId === null ? "Add" : "Update"}
+          </button>
+          {this.editingId !== null && (
+            <button type="button" onClick={this.reset}>
+              Cancel
+            </button>
+          )}
+        </form>
+
+        <ul class="divide-y">
+          {this.items.map((item) => (
+            <li key={String(item.id)} class="flex items-center justify-between py-2">
+              <span>{item.name}</span>
+              <span class="flex gap-3">
+                <button onClick={() => this.edit(item.id)}>Edit</button>
+                <button onClick={() => this.destroy(item.id)} confirm="Delete this?" class="text-red-600">
+                  Delete
+                </button>
+              </span>
+            </li>
+          ))}
+        </ul>
+      </div>
+    );
+  }
+}
+`;
+}