@pylonsync/functions 0.3.299 → 0.3.301

package/dist/ssr-runtime.d.ts

@@ -335,6 +335,13 @@ export declare function isSafeRedirect(url: string, opts: {
  *  into a page's metadata. Explicit `metadata.icons.*` wins. */
 export declare function applyAutoIcons(component: string, metadata: SsrMetadata | undefined): SsrMetadata | undefined;
 export declare function applyAutoSocialImages(component: string, headers: Record<string, string> | undefined, metadata: SsrMetadata | undefined): SsrMetadata | undefined;
+/**
+ * Dev-only tail chunk: the `__PYLON_DEV__` info blob (cache verdict, render
+ * mode/timing, route) + the HUD bootstrap. Embedded after the page tail so the
+ * marker + probe are in place before the deferred client entry boots the sync
+ * engine. `<` is escaped so the JSON can't break out of the script.
+ */
+export declare function buildDevHudChunk(devInfo: Record<string, unknown>): string;
 /**
  * Build the hydration tail appended after React's stream EOFs: the
  * `__PYLON_DATA__` JSON blob (props + ssrData) + the per-route entry
@@ -444,6 +451,31 @@ export declare function computeBucketVerdict(args: {
     wantsStream: boolean;
     status: number;
 }): boolean;
+/**
+ * Dev HUD: explain the cache verdict for a finished render in human terms — the
+ * verdict, its TTL, and (when dynamic) the SINGLE reason it isn't cached. Pure so
+ * it's unit-tested and matches `computeCacheVerdict`/`computeBucketVerdict`
+ * exactly. The "why isn't my page caching?" answer the framework otherwise throws
+ * away.
+ */
+export declare function describeCacheVerdict(v: {
+    bucketOptIn: boolean;
+    cacheable: boolean;
+    bucketable: boolean;
+    revalidateSecs: number | null;
+    authTouched: boolean;
+    dynamicTouched: boolean;
+    sessionTouched: boolean;
+    cookieCount: number;
+    strictPolicies: boolean;
+    wantsStream: boolean;
+    forceDynamic: boolean;
+    status: number;
+}): {
+    verdict: "bucketed" | "cacheable" | "dynamic";
+    secs: number | null;
+    reason: string;
+};
 /**
  * #278: diff the response head committed at `response_start` against the final
  * state after EOF, to catch a late response.* mutation from a suspended subtree

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.299",
+  "version": "0.3.301",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/ssr-runtime.ts

@@ -1158,6 +1158,155 @@ const DEV_LIVE_RELOAD_SNIPPET =
   "if(b!==null&&e.data!==b){s.close();location.reload();return;}b=e.data;});" +
   "}catch(_){}})();</script>";
 
+/**
+ * The dev HUD (a floating bottom-left overlay, dev-only): surfaces the
+ * framework decisions a dev otherwise can't see — the cache verdict + WHY a page
+ * isn't cached, render mode + timing, sync connection + offline-outbox depth, and
+ * client error count. Written as a plain function and embedded via `.toString()`
+ * (Bun strips the TS annotations), so it ships as self-contained browser JS that
+ * closes over nothing. Browser globals go through `g` so it typechecks without a
+ * DOM lib. Mirrors Next's dev indicator, tuned to Pylon's hidden state.
+ */
+function pylonDevHud() {
+  const g: any = globalThis;
+  const d: any = g.document;
+  if (!d || g.__pylonHudMounted) return;
+  g.__pylonHudMounted = true;
+
+  let info: any = {};
+  try {
+    const el = d.getElementById("__PYLON_DEV__");
+    if (el) info = JSON.parse(el.textContent || "{}");
+  } catch (_e) {}
+  // Marker the sync engine checks before publishing its dev status probe.
+  g.__PYLON_DEV__ = info;
+
+  const errs: string[] = [];
+  const onErr = (m: any) => {
+    errs.push(String(m));
+    if (errs.length > 50) errs.shift();
+  };
+  if (g.addEventListener) {
+    g.addEventListener("error", (e: any) => onErr((e && (e.message || e.error)) || e));
+    g.addEventListener("unhandledrejection", (e: any) => onErr((e && e.reason) || e));
+  }
+
+  const C = { ok: "#3fb950", warn: "#d29922", bad: "#f85149", dim: "#6e7681" };
+  const make = (tag: string, css: string, text?: string) => {
+    const n = d.createElement(tag);
+    n.style.cssText = css;
+    if (text != null) n.textContent = text;
+    return n;
+  };
+  const dot = (color: string) =>
+    make("span", "display:inline-block;width:7px;height:7px;border-radius:50%;flex:0 0 auto;background:" + color);
+
+  const box = make(
+    "div",
+    "position:fixed;left:12px;bottom:12px;z-index:2147483646;font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace",
+  );
+  const panel = make(
+    "div",
+    "background:#0d1117;border:1px solid #30363d;border-radius:8px;padding:9px 11px;margin-bottom:6px;min-width:240px;max-width:360px;box-shadow:0 8px 28px rgba(0,0,0,.45)",
+  );
+  const pill = make(
+    "button",
+    "display:flex;align-items:center;gap:6px;background:#161b22;border:1px solid #30363d;border-radius:999px;padding:5px 11px;color:#e6edf3;cursor:pointer;font:inherit;box-shadow:0 2px 10px rgba(0,0,0,.35)",
+  );
+
+  const rowEl = (label: string) => {
+    const r = make("div", "display:flex;align-items:flex-start;gap:8px;margin:3px 0");
+    r.appendChild(make("span", "color:#8b949e;flex:0 0 60px", label));
+    const v = make("span", "color:#e6edf3;word-break:break-word;flex:1");
+    r.appendChild(v);
+    panel.appendChild(r);
+    return v;
+  };
+
+  const cache = info.cache || {};
+  const cacheLabel =
+    cache.verdict === "dynamic"
+      ? "dynamic"
+      : cache.verdict + (cache.secs ? " · " + cache.secs + "s" : "");
+  rowEl("route").textContent = info.route || "—";
+  rowEl("page").textContent = info.component || "—";
+  const cacheV = rowEl("cache");
+  cacheV.textContent = cacheLabel + (cache.reason ? "  ·  " + cache.reason : "");
+  cacheV.style.color = cache.verdict === "dynamic" ? C.warn : C.ok;
+  rowEl("render").textContent =
+    (info.renderMode || "ssr") + (info.renderMs != null ? " · " + info.renderMs + "ms" : "");
+  const syncV = rowEl("sync");
+  const errV = rowEl("errors");
+
+  pill.appendChild(dot(cache.verdict === "dynamic" ? C.warn : C.ok));
+  pill.appendChild(make("span", "font-weight:600;color:#e6edf3", "pylon"));
+  const pillSyncDot = dot(C.dim);
+  pill.appendChild(pillSyncDot);
+
+  let open = false;
+  try {
+    open = g.localStorage && g.localStorage.getItem("pylon.hud.open") === "1";
+  } catch (_e) {}
+  panel.style.display = open ? "block" : "none";
+  pill.onclick = () => {
+    open = !open;
+    panel.style.display = open ? "block" : "none";
+    try {
+      g.localStorage && g.localStorage.setItem("pylon.hud.open", open ? "1" : "0");
+    } catch (_e) {}
+  };
+
+  const refresh = () => {
+    const s = g.__pylonDevSync;
+    if (s) {
+      let st = "?";
+      let pend = 0;
+      let rows = 0;
+      try {
+        st = s.status();
+        pend = s.pending();
+        rows = s.rows();
+      } catch (_e) {}
+      syncV.textContent = st + " · " + pend + " pending · " + rows + " rows";
+      const col = st === "connected" ? C.ok : st === "offline" ? C.bad : C.warn;
+      syncV.style.color = col;
+      pillSyncDot.style.background = col;
+    } else {
+      const online = g.navigator ? g.navigator.onLine : true;
+      syncV.textContent = "no sync engine · " + (online ? "online" : "offline");
+      syncV.style.color = C.dim;
+      pillSyncDot.style.background = online ? C.dim : C.bad;
+    }
+    errV.textContent = errs.length === 0 ? "0" : errs.length + " · " + errs[errs.length - 1];
+    errV.style.color = errs.length ? C.bad : C.dim;
+  };
+
+  box.appendChild(panel);
+  box.appendChild(pill);
+  const mount = () => (d.body || d.documentElement).appendChild(box);
+  if (d.body) mount();
+  else if (g.addEventListener) g.addEventListener("DOMContentLoaded", mount);
+  refresh();
+  if (g.setInterval) g.setInterval(refresh, 1000);
+}
+
+/**
+ * Dev-only tail chunk: the `__PYLON_DEV__` info blob (cache verdict, render
+ * mode/timing, route) + the HUD bootstrap. Embedded after the page tail so the
+ * marker + probe are in place before the deferred client entry boots the sync
+ * engine. `<` is escaped so the JSON can't break out of the script.
+ */
+export function buildDevHudChunk(devInfo: Record<string, unknown>): string {
+  const json = JSON.stringify(devInfo)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+  return (
+    `<script id="__PYLON_DEV__" type="application/json">${json}</script>` +
+    `<script>(${pylonDevHud.toString()})();</script>`
+  );
+}
+
 /**
  * Build the <head> blob for a boundary render: the union of every route's
  * stylesheet links from the client build manifest. Boundary modules aren't
@@ -1705,6 +1854,69 @@ export function computeBucketVerdict(args: {
   );
 }
 
+/**
+ * Dev HUD: explain the cache verdict for a finished render in human terms — the
+ * verdict, its TTL, and (when dynamic) the SINGLE reason it isn't cached. Pure so
+ * it's unit-tested and matches `computeCacheVerdict`/`computeBucketVerdict`
+ * exactly. The "why isn't my page caching?" answer the framework otherwise throws
+ * away.
+ */
+export function describeCacheVerdict(v: {
+  bucketOptIn: boolean;
+  cacheable: boolean;
+  bucketable: boolean;
+  revalidateSecs: number | null;
+  authTouched: boolean;
+  dynamicTouched: boolean;
+  sessionTouched: boolean;
+  cookieCount: number;
+  strictPolicies: boolean;
+  wantsStream: boolean;
+  forceDynamic: boolean;
+  status: number;
+}): { verdict: "bucketed" | "cacheable" | "dynamic"; secs: number | null; reason: string } {
+  if (v.bucketable) {
+    return {
+      verdict: "bucketed",
+      secs: v.revalidateSecs,
+      reason: "shared cache, keyed on session presence",
+    };
+  }
+  if (v.cacheable) {
+    return {
+      verdict: "cacheable",
+      secs: v.revalidateSecs,
+      reason: "anonymous shared cache",
+    };
+  }
+  // Dynamic — surface the single most useful reason (mirrors the verdict order).
+  let reason: string;
+  if (!v.bucketOptIn && v.revalidateSecs == null) {
+    reason = "not opted in — add `export const revalidate = N` (or `cache = \"auth-bucketed\"`)";
+  } else if (v.status !== 200) {
+    reason = `status ${v.status} (only 200 is cacheable)`;
+  } else if (v.forceDynamic) {
+    reason = "dynamic = \"force-dynamic\"";
+  } else if (v.wantsStream) {
+    reason = "streaming render (loading.tsx / streaming = true)";
+  } else if (v.cookieCount > 0) {
+    reason = "the render set a cookie";
+  } else if (v.strictPolicies) {
+    reason = "PYLON_STRICT_FN_POLICIES (serverData reads are auth-filtered)";
+  } else if (v.authTouched) {
+    reason = "read props.auth (identity-specific)";
+  } else if (v.dynamicTouched) {
+    reason = "read request headers/cookies";
+  } else if (v.sessionTouched) {
+    reason = v.bucketOptIn
+      ? "read props.session"
+      : "read props.session — add `export const cache = \"auth-bucketed\"` to bucket-cache it";
+  } else {
+    reason = "not cacheable";
+  }
+  return { verdict: "dynamic", secs: null, reason };
+}
+
 /**
  * #278: diff the response head committed at `response_start` against the final
  * state after EOF, to catch a late response.* mutation from a suspended subtree
@@ -1902,6 +2114,10 @@ export async function handleRenderRoute(
       : null;
   if (dataKind) return handleDataRoute(msg, dataKind, send);
 
+  // Dev HUD: wall-clock for the whole render, surfaced in the dev overlay's
+  // render row. `performance.now()` is monotonic; harmless in prod (unused).
+  const renderStart = isDevMode() ? performance.now() : 0;
+
   // Declared OUTSIDE the try so the catch can read page-set status/
   // cookies when turning a redirect()/notFound() throw into a response.
   const responseState: ResponseState = {
@@ -2269,6 +2485,27 @@ export async function handleRenderRoute(
       wantsStream,
       status: responseState.status,
     });
+    // Dev diagnostics (the agent + HUD signal): the cache verdict + the single
+    // actionable reason, computed ONCE here and reused for the dev HUD blob, the
+    // `x-pylon-dev` header (→ the host's diagnostics ring + `pylon diagnostics`),
+    // and the structured dev log. Null in prod.
+    const renderMode = wantsStream ? "ssr-streaming" : "ssr-buffered";
+    const devVerdict = isDevMode()
+      ? describeCacheVerdict({
+          bucketOptIn,
+          cacheable,
+          bucketable,
+          revalidateSecs,
+          authTouched,
+          dynamicTouched,
+          sessionTouched,
+          cookieCount: responseState.cookies.length,
+          strictPolicies,
+          wantsStream,
+          forceDynamic,
+          status: responseState.status,
+        })
+      : null;
     // Serialization view of props built from the RAW `msg` values — the live
     // `props` (with its read-tracking proxies) is NEVER mutated back to raw, so
     // it can't become a vehicle that leaks a prior request's identity to a later
@@ -2306,19 +2543,32 @@ export async function handleRenderRoute(
       type: "response_start",
       call_id: msg.call_id,
       status: responseState.status,
-      headers: finalizeHeaders(
-        responseState,
-        undefined,
+      headers: finalizeHeaders(responseState, undefined, {
         // The #277 anon proof and the Phase 0 bucket proof both ride the TRUSTED
-        // `internal` channel (never stripped), so userland (page setHeader /
-        // route-handler headers via `extra`) can't forge either. Mutually
-        // exclusive (bucketOptIn splits the two verdicts).
-        bucketable
+        // `internal` channel (never stripped here, always stripped by the host
+        // before the client), so userland (page setHeader / route-handler headers
+        // via `extra`) can't forge either. Mutually exclusive (bucketOptIn splits
+        // the two verdicts).
+        ...(bucketable
           ? { "x-pylon-bucket": String(revalidateSecs) }
           : cacheable
             ? { "x-pylon-cacheable": String(revalidateSecs) }
-            : undefined,
-      ),
+            : {}),
+        // Dev-only: the host parses this into its diagnostics ring (served at
+        // /_pylon/dev/diagnostics + `pylon diagnostics`). Single-line JSON, no
+        // newlines. Stripped before the client like every x-pylon-* header.
+        ...(devVerdict
+          ? {
+              "x-pylon-dev": JSON.stringify({
+                verdict: devVerdict.verdict,
+                secs: devVerdict.secs,
+                reason: devVerdict.reason,
+                mode: renderMode,
+                component: msg.component,
+              }),
+            }
+          : {}),
+      }),
     });
 
     // Pre-load the manifest BEFORE the React stream starts emitting
@@ -2475,6 +2725,28 @@ export async function handleRenderRoute(
       sendChunk(tail);
     }
 
+    // Dev HUD (dev only): append the cache-verdict + render-timing blob + the
+    // floating overlay, and emit ONE structured log line. After the page tail so
+    // the HUD marker/probe are in place before the deferred client entry boots the
+    // sync engine. `devVerdict` was computed once above (reused here + in the
+    // x-pylon-dev header). The log rides the runtime's inherited stderr, so an
+    // agent running `pylon dev` sees the verdict without any extra call.
+    if (devVerdict) {
+      const renderMs = Math.round((performance.now() - renderStart) * 10) / 10;
+      sendChunk(
+        buildDevHudChunk({
+          route: msg.url,
+          component: msg.component,
+          renderMode,
+          renderMs,
+          cache: devVerdict,
+        }),
+      );
+      // The structured dev-log line is emitted host-side (Rust tracing) from the
+      // x-pylon-dev header, so it rides the same log stream as every other
+      // [pylon] line — no duplicate console.error here.
+    }
+
     send({ type: "render_done", call_id: msg.call_id });
   } catch (err: any) {
     // A page/layout called response.redirect()/response.notFound(), or

package/src/ssr-streaming.test.ts

@@ -22,6 +22,7 @@ import {
   computeCacheVerdict,
   computeRevalidateSecs,
   computeWantsStream,
+  describeCacheVerdict,
   diffCommittedResponse,
   isDevMode,
 } from "./ssr-runtime";
@@ -222,6 +223,61 @@ describe("computeBucketVerdict (PPR Phase 0 — session-presence shared cache)",
   });
 });
 
+describe("describeCacheVerdict (dev HUD — why isn't my page cached?)", () => {
+  const base = {
+    bucketOptIn: false,
+    cacheable: false,
+    bucketable: false,
+    revalidateSecs: null as number | null,
+    authTouched: false,
+    dynamicTouched: false,
+    sessionTouched: false,
+    cookieCount: 0,
+    strictPolicies: false,
+    wantsStream: false,
+    forceDynamic: false,
+    status: 200,
+  };
+
+  test("cacheable / bucketed verdicts carry the TTL", () => {
+    expect(describeCacheVerdict({ ...base, cacheable: true, revalidateSecs: 60 })).toEqual({
+      verdict: "cacheable",
+      secs: 60,
+      reason: "anonymous shared cache",
+    });
+    const b = describeCacheVerdict({
+      ...base,
+      bucketOptIn: true,
+      bucketable: true,
+      revalidateSecs: 30,
+    });
+    expect(b.verdict).toBe("bucketed");
+    expect(b.secs).toBe(30);
+  });
+
+  test("dynamic verdict reports the SINGLE actionable reason", () => {
+    const why = (over: any) =>
+      describeCacheVerdict({ ...base, ...over }).reason;
+    // Not opted in at all.
+    expect(why({})).toContain("not opted in");
+    // Opted in (revalidate set) but each veto wins in priority order.
+    const opted = { revalidateSecs: 60 };
+    expect(why({ ...opted, status: 404 })).toContain("status 404");
+    expect(why({ ...opted, forceDynamic: true })).toContain("force-dynamic");
+    expect(why({ ...opted, wantsStream: true })).toContain("streaming");
+    expect(why({ ...opted, cookieCount: 1 })).toContain("set a cookie");
+    expect(why({ ...opted, strictPolicies: true })).toContain("STRICT");
+    expect(why({ ...opted, authTouched: true })).toContain("props.auth");
+    expect(why({ ...opted, dynamicTouched: true })).toContain("headers/cookies");
+    // Reading session on a non-bucket page → the actionable hint to opt into buckets.
+    expect(why({ ...opted, sessionTouched: true })).toContain("auth-bucketed");
+    // …but on a bucket-opted page that didn't bucket for another reason, no hint.
+    expect(why({ bucketOptIn: true, revalidateSecs: 60, sessionTouched: true })).not.toContain(
+      "auth-bucketed",
+    );
+  });
+});
+
 describe("diffCommittedResponse (#278 late-response.* drop detector)", () => {
   const snap = (over: any = {}) => ({
     status: 200,