@pylonsync/functions 0.22.50 → 0.22.59

package/src/ssr-client-nav-runtime.fixture.ts

@@ -0,0 +1,273 @@
+// The browser half of ssr-client-nav-runtime.test.ts, run in its own Bun
+// process: it stages CLIENT_RUNTIME_SOURCE and its sibling modules exactly as
+// the bundler does (writeClientRuntimeModules), imports the runtime into a
+// happy-dom window, hydrates a page, taps links, goes back and forward, and
+// prints what it saw as JSON. Its own process, because loading react-dom and
+// the staged runtime into the test runner broke later Bun.build calls in the
+// same run (EISDIR reading scheduler/index.js).
+
+import fs from "node:fs";
+import path from "node:path";
+import { Window } from "happy-dom";
+import React from "react";
+import { renderToString } from "react-dom/server";
+import { writeClientRuntimeModules } from "./ssr-client-bundler";
+
+const PKG_NODE_MODULES = path.join(import.meta.dir, "..", "node_modules");
+
+const MANIFEST = {
+  build_id: "t",
+  outdir: ".pylon/client-build",
+  public_prefix: "/_pylon/build/",
+  routes: {
+    "app/home/page": { file: "home.js", imports: [], css: [], path: "/" },
+    "app/fast/page": { file: "fast.js", imports: [], css: [], path: "/fast", navigation: "client" },
+    "app/slow/page": { file: "slow.js", imports: [], css: [], path: "/slow" },
+    "app/offline/page": { file: "offline.js", imports: [], css: [], path: "/offline" },
+  },
+  offline: { routes: ["/offline"] },
+};
+
+const LINKS = ["/", "/fast", "/slow", "/offline"];
+
+function Layout({ children }: { children?: React.ReactNode }) {
+  return React.createElement(
+    "html",
+    null,
+    React.createElement("head", null, React.createElement("title", null, "App")),
+    React.createElement(
+      "body",
+      null,
+      React.createElement(
+        "nav",
+        null,
+        ...LINKS.map((href) =>
+          React.createElement(
+            "a",
+            { key: href, href, "data-pylon-link": "", id: "to" + (href.slice(1) || "home") },
+            href,
+          ),
+        ),
+      ),
+      React.createElement("main", { id: "page" }, children),
+    ),
+  );
+}
+
+const page = (name: string) =>
+  function Page(props: any) {
+    return React.createElement("h1", null, `${name} ${props.pathname ?? ""}`);
+  };
+const Home = page("home");
+const Fast = page("fast");
+const Slow = page("slow");
+const Offline = page("offline");
+
+const fetches: string[] = [];
+const scrolls: number[] = [];
+let win: any;
+let rt: any;
+let dir = "";
+
+function pylonData(component: string, pathname: string): string {
+  const data = {
+    component,
+    layouts: [],
+    props: { pathname, url: pathname, params: {}, searchParams: {} },
+    ssrData: {},
+  };
+  return `<script id="__PYLON_DATA__" type="application/json">${JSON.stringify(data)}</script>`;
+}
+
+async function settle() {
+  for (let i = 0; i < 20; i++) await new Promise((r) => setTimeout(r, 0));
+}
+
+function click(id: string) {
+  const el = win.document.getElementById(id);
+  el.dispatchEvent(new win.MouseEvent("click", { bubbles: true, cancelable: true, button: 0 }));
+}
+
+// A browser fires popstate after back() and forward(); happy-dom 15 moves
+// the location without it, so the test fires it.
+async function traverse(direction: "back" | "forward") {
+  win.history[direction]();
+  win.dispatchEvent(new win.PopStateEvent("popstate", { state: win.history.state }));
+  await settle();
+}
+
+const heading = () => win.document.querySelector("#page h1")?.textContent;
+const pageFetches = () => fetches.filter((u) => !u.includes("/_pylon/build/manifest.json"));
+
+async function setUp() {
+  // Inside this package's node_modules, so the runtime resolves react and
+  // react-dom the way the test does. A symlinked node_modules in a temp dir
+  // left Bun's resolver cache broken for later Bun.build calls in the run.
+  const cacheDir = path.join(PKG_NODE_MODULES, ".cache");
+  fs.mkdirSync(cacheDir, { recursive: true });
+  dir = fs.mkdtempSync(path.join(cacheDir, "pylon-client-nav-"));
+  await writeClientRuntimeModules(fs, path, dir);
+  // @pylonsync/react is not a dependency of this package: stand in for the
+  // two functions the runtime calls at hydration.
+  const runtimeFile = path.join(dir, "client-runtime.ts");
+  fs.writeFileSync(
+    runtimeFile,
+    fs
+      .readFileSync(runtimeFile, "utf8")
+      .replace('from "@pylonsync/react"', 'from "./pylon-react-stub"'),
+  );
+  fs.writeFileSync(
+    path.join(dir, "pylon-react-stub.ts"),
+    "export function configureClient() {}\nexport async function registerOfflineWorker() { return null; }\n",
+  );
+  fs.writeFileSync(path.join(dir, "loading-registry.ts"), "export const LOADING_MODULES = {};\n");
+
+  win = new Window({ url: "http://localhost/" });
+  const g = globalThis as any;
+  g.window = win;
+  g.document = win.document;
+  g.navigator = win.navigator;
+  g.location = win.location;
+  g.history = win.history;
+  g.HTMLElement = win.HTMLElement;
+  g.Node = win.Node;
+  g.Event = win.Event;
+  g.MouseEvent = win.MouseEvent;
+  g.DOMParser = win.DOMParser;
+  g.MutationObserver = win.MutationObserver;
+  g.requestAnimationFrame = (cb: any) => setTimeout(() => cb(Date.now()), 0);
+  g.cancelAnimationFrame = (id: any) => clearTimeout(id);
+  win.scrollTo = (_x: number, y: number) => scrolls.push(y);
+  const fakeFetch = async (input: any) => {
+    const url = typeof input === "string" ? input : input.url;
+    fetches.push(url);
+    if (url === "/_pylon/build/manifest.json") {
+      return new Response(JSON.stringify(MANIFEST), { status: 200 });
+    }
+    const pathname = new URL(url, "http://localhost").pathname;
+    if (pathname === "/slow") {
+      return new Response(
+        `<!DOCTYPE html><html><head><title>Slow</title></head><body>${pylonData("app/slow/page", pathname)}</body></html>`,
+        { status: 200 },
+      );
+    }
+    return new Response("not found", { status: 404 });
+  };
+  g.fetch = fakeFetch;
+  win.fetch = fakeFetch;
+
+  // The server-rendered home page, with its hydration data.
+  const props = { pathname: "/", url: "/", params: {}, searchParams: {} };
+  const html = renderToString(React.createElement(Layout, null, React.createElement(Home, props)));
+  const parsed = new win.DOMParser().parseFromString(
+    "<!DOCTYPE html>" + html.replace("</body>", pylonData("app/home/page", "/") + "</body>"),
+    "text/html",
+  );
+  // Remove, then append: happy-dom 20's replaceChild inserts the new root
+  // before it removes the old one, which a document refuses.
+  const root = win.document.importNode(parsed.documentElement, true);
+  win.document.documentElement.remove();
+  win.document.appendChild(root);
+
+  rt = await import(path.join(dir, "client-runtime.ts"));
+  rt.hydrate("app/home/page", Home, [Layout]);
+  await settle();
+  // The other routes' entries, as their chunks register them.
+  rt.hydrate("app/fast/page", Fast, [Layout], { title: "Fast" });
+  rt.hydrate("app/slow/page", Slow, [Layout]);
+  rt.hydrate("app/offline/page", Offline, [Layout]);
+}
+
+
+
+
+interface Observation {
+  heading: string | null;
+  pathname: string;
+  pageFetches: string[];
+  historyLength: number;
+  scrolls: number[];
+  title: string;
+}
+
+function observe(): Observation {
+  const seen = {
+    heading: heading() ?? null,
+    pathname: win.location.pathname,
+    pageFetches: pageFetches(),
+    historyLength: win.history.length,
+    scrolls: [...scrolls],
+    title: win.document.title,
+  };
+  fetches.length = 0;
+  scrolls.length = 0;
+  return seen;
+}
+
+const report: Record<string, any> = {};
+
+const preloads = () =>
+  [...win.document.querySelectorAll('link[rel="modulepreload"]')].map((l: any) => l.getAttribute("href"));
+
+/** Prefetch timing: chunks for a link on screen wait for idle and skip
+ *  Save-Data; intent fetches at once. */
+async function prefetchTiming() {
+  const pylon = win.__pylon;
+  const before = preloads().length;
+  // Idle callbacks run only when the test says so.
+  const idle: Array<() => void> = [];
+  win.requestIdleCallback = (fn: () => void) => {
+    idle.push(fn);
+    return idle.length;
+  };
+  await pylon.prefetch("/fast");
+  await settle();
+  const sightBeforeIdle = preloads().length - before;
+  for (const fn of idle.splice(0)) fn();
+  await settle();
+  const sightAfterIdle = preloads().length - before;
+
+  // Save-Data: nothing on sight, even when idle.
+  Object.defineProperty(win.navigator, "connection", {
+    value: { saveData: true, effectiveType: "4g" },
+    configurable: true,
+  });
+  const beforeSave = preloads().length;
+  await pylon.prefetch("/offline");
+  await settle();
+  for (const fn of idle.splice(0)) fn();
+  await settle();
+  const saveDataSight = preloads().length - beforeSave;
+
+  // Intent fetches at once, Save-Data or not.
+  await pylon.prefetch("/offline", { document: true });
+  await settle();
+  const intent = preloads().length - beforeSave;
+  return { sightBeforeIdle, sightAfterIdle, saveDataSight, intent };
+}
+try {
+  await setUp();
+  report.hydrated = observe();
+  click("tofast");
+  await settle();
+  report.fast = observe();
+  click("tooffline");
+  await settle();
+  report.offline = observe();
+  click("toslow");
+  await settle();
+  report.slow = observe();
+  await traverse("back");
+  report.back1 = observe();
+  await traverse("back");
+  report.back2 = observe();
+  await traverse("forward");
+  report.forward1 = observe();
+  await traverse("forward");
+  report.forward2 = observe();
+  report.prefetch = await prefetchTiming();
+} finally {
+  if (dir) fs.rmSync(dir, { recursive: true, force: true });
+}
+console.log("REPORT " + JSON.stringify(report));
+process.exit(0);

package/src/ssr-client-nav-runtime.test.ts

@@ -0,0 +1,79 @@
+// Instant client navigation, run in the real client runtime: the fixture
+// (ssr-client-nav-runtime.fixture.ts) hydrates a page in happy-dom and taps
+// through it, in its own process. This checks what it saw:
+//
+//   - /fast (the page exports navigation = "client") and /offline (an offline
+//     route) render with no page fetch;
+//   - /slow fetches its page, as before;
+//   - back and forward add no history entries and fetch only /slow;
+//   - every navigation resets the scroll, like a fetched one.
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import path from "node:path";
+
+let report: Record<string, any> = {};
+
+beforeAll(async () => {
+  const proc = Bun.spawn([process.execPath, path.join(import.meta.dir, "ssr-client-nav-runtime.fixture.ts")], {
+    cwd: path.join(import.meta.dir, ".."),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
+  await proc.exited;
+  const line = out.split("\n").find((l) => l.startsWith("REPORT "));
+  if (!line) throw new Error(`fixture printed no report:\n${out}\n${err}`);
+  report = JSON.parse(line.slice("REPORT ".length));
+}, 60_000);
+
+describe("instant client navigation", () => {
+  test("the page hydrated", () => {
+    expect(report.hydrated.heading).toBe("home /");
+  });
+
+  test('a click on a route with navigation = "client" makes no page fetch', () => {
+    const { fast, hydrated } = report;
+    expect(fast.heading).toBe("fast /fast");
+    expect(fast.pathname).toBe("/fast");
+    expect(fast.pageFetches).toEqual([]);
+    expect(fast.historyLength).toBe(hydrated.historyLength + 1);
+    expect(fast.scrolls).toEqual([0]);
+    // The title comes from the page's static metadata.
+    expect(fast.title).toBe("Fast");
+  });
+
+  test("a click on an offline route makes no page fetch", () => {
+    expect(report.offline.heading).toBe("offline /offline");
+    expect(report.offline.pageFetches).toEqual([]);
+  });
+
+  test("a route that did not opt in still fetches its page", () => {
+    const { slow } = report;
+    expect(slow.heading).toBe("slow /slow");
+    expect(slow.pageFetches).toEqual(["/slow"]);
+    expect(slow.pathname).toBe("/slow");
+    expect(slow.scrolls).toEqual([0]);
+    expect(slow.title).toBe("Slow");
+  });
+
+  test("back and forward re-render without new history entries, fetching only /slow", () => {
+    const { slow, back1, back2, forward1, forward2 } = report;
+    expect([back1.pathname, back1.heading]).toEqual(["/offline", "offline /offline"]);
+    expect([back2.pathname, back2.heading]).toEqual(["/fast", "fast /fast"]);
+    expect([forward1.pathname, forward1.heading]).toEqual(["/offline", "offline /offline"]);
+    expect([forward2.pathname, forward2.heading]).toEqual(["/slow", "slow /slow"]);
+    expect([back1, back2, forward1].flatMap((o) => o.pageFetches)).toEqual([]);
+    expect(forward2.pageFetches).toEqual(["/slow"]);
+    for (const o of [back1, back2, forward1, forward2]) {
+      expect(o.historyLength).toBe(slow.historyLength);
+    }
+  });
+
+  test("prefetch on sight waits for idle and skips Save-Data; intent fetches at once", () => {
+    const { sightBeforeIdle, sightAfterIdle, saveDataSight, intent } = report.prefetch;
+    expect(sightBeforeIdle).toBe(0);
+    expect(sightAfterIdle).toBeGreaterThan(0);
+    expect(saveDataSight).toBe(0);
+    expect(intent).toBeGreaterThan(0);
+  });
+});

package/src/ssr-client-nav.test.ts

@@ -0,0 +1,78 @@
+// Which routes navigate with no page fetch: a page that exports
+// `navigation = "client"`, or an offline route.
+
+import { describe, expect, test } from "bun:test";
+import { exportsStaticMetadata } from "./ssr-client-bundler";
+import { clientRouteFor, declaresClientNavigation, isOfflinePath } from "./ssr-client-nav";
+import { matchRoute } from "./ssr-route-match";
+
+const MANIFEST = {
+  routes: {
+    "app/leads/page": { path: "/leads", navigation: "client" },
+    "app/leads/[id]/page": { path: "/leads/[id]" },
+    "app/map/page": { path: "/map" },
+    "app/reports/page": { path: "/reports" },
+  },
+  offline: { routes: ["/map", "/leads/[id]"] },
+};
+
+describe("declaresClientNavigation", () => {
+  test("finds the export in its usual spellings", () => {
+    for (const src of [
+      `export const navigation = "client";`,
+      `export const navigation = 'client'`,
+      "export const navigation = `client`;",
+      `export const navigation: "client" | "server" = "client";`,
+      `export   const navigation="client" as const;`,
+    ]) {
+      expect(declaresClientNavigation(src)).toBe(true);
+    }
+  });
+
+  test("ignores other values and other names", () => {
+    for (const src of [
+      `export const navigation = "server";`,
+      `const navigation = "client";`,
+      `export const navigationMode = "client";`,
+      `// navigation = "client"`,
+      "",
+    ]) {
+      expect(declaresClientNavigation(src)).toBe(false);
+    }
+  });
+});
+
+describe("clientRouteFor", () => {
+  test("a page that opted in", () => {
+    expect(clientRouteFor(MANIFEST, "/leads", matchRoute)?.component).toBe("app/leads/page");
+  });
+
+  test("an offline route, static or dynamic", () => {
+    expect(clientRouteFor(MANIFEST, "/map", matchRoute)?.component).toBe("app/map/page");
+    const lead = clientRouteFor(MANIFEST, "/leads/42", matchRoute);
+    expect(lead?.component).toBe("app/leads/[id]/page");
+    expect(lead?.params).toEqual({ id: "42" });
+  });
+
+  test("anything else fetches its page", () => {
+    expect(clientRouteFor(MANIFEST, "/reports", matchRoute)).toBeNull();
+    expect(clientRouteFor(MANIFEST, "/nowhere", matchRoute)).toBeNull();
+    expect(clientRouteFor(null, "/leads", matchRoute)).toBeNull();
+    const { offline: _o, ...noOffline } = MANIFEST;
+    expect(clientRouteFor(noOffline, "/map", matchRoute)).toBeNull();
+  });
+
+  test("isOfflinePath matches route patterns", () => {
+    expect(isOfflinePath(MANIFEST, "/leads/7", matchRoute)).toBe(true);
+    expect(isOfflinePath(MANIFEST, "/leads", matchRoute)).toBe(false);
+  });
+});
+
+describe("exportsStaticMetadata", () => {
+  test("finds a static metadata export", () => {
+    expect(exportsStaticMetadata(`export const metadata = { title: "Leads" };`)).toBe(true);
+    expect(exportsStaticMetadata(`const metadata = {}; export { metadata };`)).toBe(true);
+    expect(exportsStaticMetadata(`export async function generateMetadata() {}`)).toBe(false);
+    expect(exportsStaticMetadata(`const metadata = {};`)).toBe(false);
+  });
+});

package/src/ssr-client-nav.ts

@@ -0,0 +1,70 @@
+// Instant client navigation: which routes the client runtime renders with no
+// page fetch.
+//
+// A client navigation normally fetches the destination's SSR payload for its
+// props and serverData, then renders. A route that reads neither does not
+// need that round trip: its data comes from the local replica (db.useQuery),
+// and the props it may read are the identity-free ones the last page had.
+// Such a route opts in one of two ways:
+//
+//   - its page declares `export const navigation = "client"`, or
+//   - its URL is one of `buildManifest({ offline: { routes } })`, which
+//     already follow the same render rule (see ssr-offline.ts).
+//
+// The client runtime imports this module as `./client-nav` (the bundler
+// stages this file next to it, like ./route-match), and the bundler uses
+// `declaresClientNavigation` to mark pages in the bundle manifest. No imports:
+// the staged copy must stand alone.
+
+/** A route match, as `matchRoute` in ssr-route-match.ts returns it. */
+export interface ClientRouteMatch {
+  component: string;
+  params: Record<string, string | string[]>;
+}
+
+/** The bundle manifest fields this module reads. */
+export interface ClientNavManifest {
+  routes: Record<string, { path?: string; navigation?: string }>;
+  offline?: { routes?: string[] };
+}
+
+type MatchRoute = (manifest: any, pathname: string) => ClientRouteMatch | null;
+
+/**
+ * Whether page source declares `export const navigation = "client"` (single,
+ * double or backtick quotes, with an optional type annotation or `as const`).
+ * A static scan: the bundler reads the page file without running it.
+ */
+export function declaresClientNavigation(source: string): boolean {
+  return /export\s+const\s+navigation\s*(?::[^=]+)?=\s*(["'`])client\1/.test(source);
+}
+
+/** Whether `pathname` is one of the app's offline routes. */
+export function isOfflinePath(
+  manifest: ClientNavManifest | null,
+  pathname: string,
+  matchRoute: MatchRoute,
+): boolean {
+  const patterns = manifest?.offline?.routes;
+  if (!patterns || patterns.length === 0) return false;
+  const routes: Record<string, { path: string }> = {};
+  for (const pattern of patterns) routes[pattern] = { path: pattern };
+  return matchRoute({ routes }, pathname) !== null;
+}
+
+/**
+ * The page to render from the client for `pathname`, or null when the
+ * navigation must fetch the page (no match, or the page did not opt in).
+ */
+export function clientRouteFor(
+  manifest: ClientNavManifest | null,
+  pathname: string,
+  matchRoute: MatchRoute,
+): ClientRouteMatch | null {
+  if (!manifest) return null;
+  const matched = matchRoute(manifest, pathname);
+  if (!matched) return null;
+  if (manifest.routes[matched.component]?.navigation === "client") return matched;
+  if (isOfflinePath(manifest, pathname, matchRoute)) return matched;
+  return null;
+}

package/src/ssr-offline-shell.test.ts

@@ -59,6 +59,7 @@ const BUNDLE_MANIFEST = {
     startUrl: "/",
     routes: ["/"],
     version: "v1",
+    builtAt: "2026-10-22T12:00:00.000Z",
   },
 };
 
@@ -204,10 +205,14 @@ test("every page of an offline app gets the install tags and the register flag",
   expect(html).toContain('<meta name="theme-color" content="#0b2545">');
   expect(html).toContain('<meta name="apple-mobile-web-app-title" content="Sales">');
   expect(html).toContain('<link rel="apple-touch-icon" href="/icons/512.png">');
-  expect(data.offline).toEqual({ dev: false });
+  expect(data.offline).toEqual({
+    dev: false,
+    version: "v1",
+    builtAt: "2026-10-22T12:00:00.000Z",
+  });
 
   const dev = await render(dir, { env: { PYLON_DEV_MODE: "1" } });
-  expect(dev.data.offline).toEqual({ dev: true });
+  expect(dev.data.offline.dev).toBe(true);
 });
 
 test("an app without offline gets neither", async () => {