@zerotal/flow 1.0.0

package/src/compiler/cache.ts

@@ -0,0 +1,101 @@
+/**
+ * .zerotal/compiled/ disk cache for compiled render functions.
+ *
+ * Cache key: Bun.hash(sourceContent).toString(16)
+ * Cache entry: .zerotal/compiled/<hash>.js
+ *
+ * On a cache hit the compiled file is imported directly.
+ * On a miss the caller compiles, calls setCached, then imports the returned path.
+ */
+
+import { join } from "node:path";
+import { mkdir, unlink, readdir } from "node:fs/promises";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const COMPILED_DIR_NAME = join(".zerotal", "compiled");
+
+/**
+ * Cache version — a fingerprint of the COMPILER'S OWN SOURCE, computed once per process.
+ *
+ * This used to be a hand-bumped constant, which was a silent-staleness footgun: change the
+ * emit logic (or upgrade the package) without bumping it, and every page whose own source
+ * hadn't changed kept serving a compile from the OLD compiler — surviving server restarts,
+ * because the cache lives on disk. Deriving it from the compiler sources means any emit
+ * change invalidates every entry automatically, with nothing to remember.
+ *
+ * Falls back to a constant if the sources can't be read (e.g. an exotic bundled deploy).
+ */
+const COMPILER_VERSION: string = (() => {
+  try {
+    const dir = fileURLToPath(new URL(".", import.meta.url));
+    const parts = readdirSync(dir)
+      .filter((f) => f.endsWith(".ts") && !f.includes(".test.") && f !== "cache.ts")
+      .sort()
+      .map((f) => String(Bun.hash(readFileSync(join(dir, f), "utf8"))));
+    return parts.length > 0 ? `s${Bun.hash(parts.join("|"))}` : "4";
+  } catch {
+    return "4";
+  }
+})();
+
+function _cacheDir(appRoot: string): string {
+  return join(appRoot, COMPILED_DIR_NAME);
+}
+
+function _hashSource(source: string, cspSafe = false): string {
+  // Bun.hash returns a number or bigint depending on input type.
+  // Using String() avoids any ambiguity. The cspSafe marker keeps CSP and
+  // default builds in separate cache entries (their emitted output differs).
+  return String(Bun.hash(COMPILER_VERSION + (cspSafe ? "csp:" : "") + source));
+}
+
+/** Returns the cached compiled file path if up-to-date, otherwise null. */
+export function getCachedPath(
+  source: string,
+  appRoot: string,
+  cspSafe = false,
+  ext = "ts",
+): string | null {
+  const hash = _hashSource(source, cspSafe);
+  const path = join(_cacheDir(appRoot), `${hash}.${ext}`);
+  return existsSync(path) ? path : null;
+}
+
+/**
+ * Write a compiled render function to the cache and return its absolute path.
+ * Creates the cache directory if it doesn't exist.
+ */
+export async function writeCache(
+  source: string,
+  compiledCode: string,
+  sourceFile: string,
+  appRoot: string,
+  cspSafe = false,
+  ext = "ts",
+): Promise<string> {
+  const dir = _cacheDir(appRoot);
+  await mkdir(dir, { recursive: true });
+
+  const hash = _hashSource(source, cspSafe);
+  const outPath = join(dir, `${hash}.${ext}`);
+  const header = `// @flow-compiled\n// Source: ${sourceFile}\n// Hash: ${hash}\n\n`;
+
+  await Bun.write(outPath, header + compiledCode);
+  return outPath;
+}
+
+/**
+ * Clear all compiled cache entries.
+ * Called by the dev server on full restart or when flow itself is updated.
+ */
+export async function clearCache(appRoot: string): Promise<void> {
+  const dir = _cacheDir(appRoot);
+  if (!existsSync(dir)) return;
+  const files = await readdir(dir);
+  await Promise.all(
+    files
+      .filter((f) => f.endsWith(".js") || f.endsWith(".ts") || f.endsWith(".tsx"))
+      .map((f) => unlink(join(dir, f)).catch(() => undefined)),
+  );
+}

package/src/compiler/directives.ts

@@ -0,0 +1,107 @@
+/**
+ * Compile-time directive resolution.
+ *
+ * Maps JSX prop names to their final HTML attribute equivalents.
+ * Mirrors PULSE_PROP_MAP in jsx-runtime.ts — kept in sync manually; both are the
+ * single source of truth for their respective runtime vs. compile-time roles.
+ */
+
+export type DirectiveKind =
+  | { kind: "boolean"; attr: string } // showOnLoading → flow:loading  (no value)
+  | { kind: "passthrough"; attr: string } // loadingAttr="disabled" → flow:loading.attr="disabled"
+  | { kind: "value"; attrs: [string, string] } // value={this.x} → flow:model="x" value="<dynamic>"
+  | { kind: "event"; prefix: string } // onClick → flow:click
+  | { kind: "passthrough-expr"; attr: string } // confirm={...} → flow:confirm="..."
+  | { kind: "text" }; // text={this.x} → flow:text="x" + child injection
+
+/** Directive entries for boolean JSX props (no value → no value in HTML). */
+export const BOOLEAN_DIRECTIVES: Record<string, string> = {
+  showOnLoading: "flow:loading",
+  hideOnLoading: "flow:loading.remove",
+  showOnDirty: "flow:dirty",
+  hideOnDirty: "flow:dirty.remove",
+  navigate: "flow:navigate",
+  navigateHover: "flow:navigate.hover",
+  currentExact: "flow:current.exact",
+  currentStrict: "flow:current.strict",
+  cloak: "flow:cloak",
+  ignore: "flow:ignore",
+  ignoreSelf: "flow:ignore.self",
+  replace: "flow:replace",
+  replaceSelf: "flow:replace.self",
+  showImportant: "flow:show.important",
+  intersectOnce: "flow:intersect.once", // fire onIntersect once, then stop observing
+  sortHandle: "flow:sort:handle",
+  sortIgnore: "flow:sort:ignore",
+  streamReplace: "flow:stream.replace",
+  delay: "flow:loading.delay",
+  collapse: "x-collapse", // Tier 3: animate x-show height
+  transition: "flow:transition", // enter animation on morph (bridge: _triggerEnterTransition)
+  showOnOffline: "flow:offline", // shown while the WS connection is down
+  hideOnOffline: "flow:offline.remove", // hidden while the WS connection is down
+  showOnError: "flow:failed", // shown after an action fails (optimistic failed state)
+  hideOnError: "flow:failed.remove", // hidden after an action fails
+  autoFocus: "flow:autofocus", // focus this field on mount
+  focusOnError: "flow:focus-error", // focus this field after a patch if it becomes invalid
+};
+
+/**
+ * String-passthrough directives: the prop name maps to a different attribute
+ * name but the string value is passed through unchanged.
+ * E.g. `loadingAttr="disabled"` → `flow:loading.attr="disabled"`.
+ */
+export const STRING_DIRECTIVES: Record<string, string> = {
+  loadingClass: "flow:loading.class",
+  loadingClassRemove: "flow:loading.class.remove",
+  loadingAttr: "flow:loading.attr",
+  dirtyClass: "flow:dirty.class",
+  dirtyClassRemove: "flow:dirty.class.remove",
+  dirtyAttr: "flow:dirty.attr",
+  current: "flow:current",
+  ref: "flow:ref",
+  loadingTarget: "flow:target", // scope loading state to specific action(s)
+  loadingTargetExcept: "flow:target.except",
+  dirtyTarget: "flow:target", // scope dirty state to specific prop(s)
+  offlineClass: "flow:offline.class", // class toggled while offline
+  offlineClassRemove: "flow:offline.class.remove",
+  offlineAttr: "flow:offline.attr", // attribute toggled while offline
+  intersectMargin: "flow:intersect.margin", // observer rootMargin, e.g. "200px" (fire before entry)
+  intersectThreshold: "flow:intersect.threshold", // "half" | "full" | 0..1
+  sortItem: "flow:sort:item", // per-item reorder key (literal keys; dynamic keys use the runtime path)
+  sortGroup: "flow:sort:group",
+  stream: "flow:stream",
+  poll: "flow:poll",
+  confirm: "flow:confirm",
+  show: "flow:show",
+  onInit: "flow:init",
+  teleport: "flow:teleport",
+  mask: "x-mask", // Tier 3: input masking
+  trap: "x-trap", // Tier 3: focus trap (truthy expression)
+  anchor: "x-anchor", // Tier 3: position relative to another element
+  transition: "flow:transition", // enter/leave preset for show= (e.g. transition="slide-right")
+  draft: "flow:draft", // persist an unsubmitted input value to localStorage under this key
+};
+
+/** HTML attribute name normalisation (JSX names → HTML names). */
+export const ATTR_RENAMES: Record<string, string> = {
+  className: "class",
+  htmlFor: "for",
+};
+
+/** VOID_ELEMENTS that must not have a closing tag. */
+export const VOID_ELEMENTS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);

package/src/compiler/helpers.ts

@@ -0,0 +1,26 @@
+/**
+ * `@zerotal/flow/compiler-helpers` — tiny HTML-escaping helpers imported by
+ * AOT-compiled render functions. These are the only runtime dependency of the
+ * generated `.zerotal/compiled/*.js` files and are not intended for direct use.
+ *
+ * @example
+ * ```ts
+ * // Emitted by the Flow compiler into a compiled render function:
+ * html += "<p>" + __esc(this.name) + "</p>";
+ * html += '<a href="' + __escAttr(this.url) + '">link</a>';
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Escape a value for safe injection as HTML text content. */
+export function __esc(v: unknown): string {
+  if (v == null || v === false || v === true) return "";
+  return String(v).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Escape a value for safe injection inside an HTML attribute (double-quoted). */
+export function __escAttr(v: unknown): string {
+  if (v == null) return "";
+  return String(v).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}

package/src/compiler/index.ts

@@ -0,0 +1,172 @@
+/**
+ * Flow AOT compiler — orchestrates compilation of all registered Pages.
+ *
+ * Called once by FlowProvider.onBooting() before the server accepts requests.
+ * For each page that has a __sourceFile stored on it (set by the file-route
+ * resolver), we:
+ *   1. Read the source
+ *   2. Hash it and check .zerotal/compiled/ cache
+ *   3. On miss: transform() → write to cache
+ *   4. dynamic-import the compiled file
+ *   5. Patch PageClass.prototype.render + set __flowCompiled = true
+ *
+ * Pages that fall back (unsupported JSX patterns, manually-registered routes
+ * without __sourceFile) continue using the standard runtime transparently.
+ */
+
+import { pathToFileURL } from "node:url";
+import { frameworkLog } from "@zerotal/core/logger";
+import {
+  transformFlowFile,
+  buildBindInjectedRender,
+  validateFlowFile,
+  describeBlocker,
+  FlowValidationError,
+  type BlockerReport,
+} from "./transform.ts";
+import { getCachedPath, writeCache } from "./cache.ts";
+
+/**
+ * Set `ZT_FLOW_COMPILE_LOG=1` to have every page that falls back to the runtime
+ * renderer say why, with the line to look at. Off by default: falling back is
+ * normal and correct for component-heavy pages, so reporting it on every boot
+ * would be noise rather than news.
+ */
+function _explainFallbacks(): boolean {
+  return Bun.env["ZT_FLOW_COMPILE_LOG"] === "1";
+}
+
+const HELPERS_IMPORT = `import { __esc, __escAttr } from '@zerotal/flow/compiler-helpers';\n\n`;
+
+/**
+ * Compile all Component classes that have __sourceFile set.
+ *
+ * @param appRoot  Absolute path to the app root directory (contains .zerotal/).
+ */
+export async function compileRegisteredPages(appRoot: string, cspSafe = false): Promise<void> {
+  // Import registry lazily to avoid circular deps at module load time.
+  const { _getPageEntries } = await import("../registry.ts");
+  const entries = _getPageEntries();
+
+  let compiled = 0;
+  let cached = 0;
+  let skipped = 0;
+  let injected = 0;
+
+  const start = Date.now();
+
+  for (const [, entry] of entries) {
+    const PageClass = entry.PageClass as unknown as { new (): unknown } & {
+      prototype: { render?: (...a: unknown[]) => unknown };
+      __flowCompiled?: boolean;
+      __sourceFile?: string;
+    };
+
+    const sourceFile = PageClass.__sourceFile;
+    if (!sourceFile) {
+      skipped++;
+      continue;
+    }
+
+    // Already compiled in this process (e.g. shared base class registered twice)
+    if (PageClass.__flowCompiled) {
+      cached++;
+      continue;
+    }
+
+    const source = await Bun.file(sourceFile).text();
+
+    // Validate unconditionally — runs even on cache hits.
+    // FlowValidationError propagates here (not caught below) so the server
+    // refuses to start when a page references @locked props or non-@expose members
+    // from a client callback.
+    validateFlowFile(source, sourceFile);
+
+    try {
+      // ── Cache hit ────────────────────────────────────────────────────────
+      let compiledPath = getCachedPath(source, appRoot, cspSafe);
+
+      // ── Cache miss — transform and write ─────────────────────────────────
+      if (!compiledPath) {
+        const report: BlockerReport = {};
+        const result = transformFlowFile(source, sourceFile, { cspSafe, report });
+        if (!result) {
+          if (_explainFallbacks()) {
+            frameworkLog("flow").info(
+              `${PageClass.name} renders through the runtime.\n` +
+                describeBlocker(report.blocker, sourceFile).trimEnd(),
+            );
+          }
+          // CSP-safe mode cannot fall back to the runtime renderer (it emits
+          // eval-requiring expressions), so an un-compilable page is fatal.
+          if (cspSafe) {
+            throw new FlowValidationError(
+              `[Flow CSP] ${PageClass.name} could not be AOT-compiled, and CSP-safe mode ` +
+                `forbids the eval-based runtime fallback. Simplify the page's render().`,
+            );
+          }
+          // Bind-name injection: the page still renders through the runtime jsx()
+          // path, but with `__flowBinds` added so component bindings (show/bind/query)
+          // resolve statically instead of by the fragile value/capture heuristic.
+          // A faithful reprint of render() — if it fails to build or import, the
+          // catch below falls back to the untouched runtime render.
+          let injPath = getCachedPath(source, appRoot, cspSafe, "tsx");
+          if (!injPath) {
+            const injectedCode = buildBindInjectedRender(source, sourceFile);
+            if (!injectedCode) {
+              skipped++;
+              continue; // nothing to inject — plain runtime render
+            }
+            injPath = await writeCache(source, injectedCode, sourceFile, appRoot, cspSafe, "tsx");
+          }
+          const injMod = (await import(pathToFileURL(injPath).href)) as {
+            render: (...a: unknown[]) => unknown;
+          };
+          // Patch render but leave __flowCompiled unset: the injected render
+          // still uses jsx() and needs the runtime getter instrumentation for the
+          // non-component bindings (value=/checked=/text= on intrinsic elements).
+          PageClass.prototype.render = injMod.render;
+          injected++;
+          continue;
+        }
+
+        const code =
+          HELPERS_IMPORT +
+          (result.preamble ? result.preamble + "\n\n" : "") +
+          `export async function render() {\n${result.renderBody}\n}\n`;
+
+        compiledPath = await writeCache(source, code, sourceFile, appRoot, cspSafe);
+        compiled++;
+      } else {
+        cached++;
+      }
+
+      // ── Dynamic import + prototype patch ──────────────────────────────────
+      // Use file:// URL so dynamic import works on both Unix and Windows.
+      const mod = (await import(pathToFileURL(compiledPath).href)) as {
+        render: (...a: unknown[]) => unknown;
+      };
+      PageClass.prototype.render = mod.render;
+      PageClass.__flowCompiled = true;
+    } catch (err) {
+      // In CSP-safe mode there is no safe runtime fallback — surface the error so
+      // the server refuses to boot and the developer fixes the page.
+      if (cspSafe) throw err;
+      // Otherwise a non-fatal compile failure falls back to the runtime renderer.
+      // Compiler errors already carry a `[Flow]` tag; strip it so the line reads
+      // as one message rather than two stacked prefixes.
+      const detail = (err as Error).message.replace(/^\[Flow\]\s*/, "");
+      frameworkLog("flow").warn(`${PageClass.name} skipped — ${detail}`);
+      skipped++;
+    }
+  }
+
+  const ms = Date.now() - start;
+  if (compiled > 0 || cached > 0 || injected > 0) {
+    frameworkLog("flow").info(
+      `Compiled ${compiled} page(s), ${cached} from cache, ` +
+        `${injected} bind-injected, ${skipped} using runtime`,
+      { compiled, cached, injected, runtime: skipped, ms },
+    );
+  }
+}