@pylonsync/functions 0.22.47 → 0.22.58

package/src/ssr-route-assets.ts

@@ -0,0 +1,68 @@
+// The client build files one page needs, from the bundle manifest.
+//
+// One list, two readers: the SSR render emits a tag for each file (stylesheet
+// links, modulepreloads, the polyfill and entry scripts, font preloads), and
+// the offline service worker precaches the same files for each offline route.
+// Computing them in one place keeps the two from drifting: a file the page
+// loads but the worker did not keep would break the page with no network.
+
+/** The bundle-manifest fields this module reads. */
+export interface RouteAssetManifest {
+  public_prefix?: string;
+  polyfills?: string;
+  routes: Record<
+    string,
+    { file: string; imports?: string[]; css?: string[]; path?: string } | undefined
+  >;
+  fonts?: { preload?: string[] } | null;
+}
+
+/** Outdir-relative files for one route, in the order the page loads them. */
+export interface RouteAssetFiles {
+  /** `<link rel="stylesheet">` (or inlined `<style>`) in the head. */
+  styles: string[];
+  /** `<link rel="modulepreload">` in the head. */
+  preloads: string[];
+  /** `<link rel="preload" as="font">` in the head. */
+  fonts: string[];
+  /** `<script type="module">` in the body tail: the polyfills, then the
+   *  route entry. */
+  scripts: string[];
+}
+
+/** The scripts the hydration tail loads for a route entry. */
+export function routeScriptFiles(
+  route: { file: string },
+  polyfills: string | undefined,
+): string[] {
+  return polyfills ? [polyfills, route.file] : [route.file];
+}
+
+/** Every client-build file the page for `component` loads, or null when the
+ *  build has no entry for it. */
+export function routeAssetFiles(
+  manifest: RouteAssetManifest,
+  component: string,
+): RouteAssetFiles | null {
+  const route = manifest.routes[component];
+  if (!route) return null;
+  return {
+    styles: route.css ?? [],
+    preloads: route.imports ?? [],
+    fonts: manifest.fonts?.preload ?? [],
+    scripts: routeScriptFiles(route, manifest.polyfills),
+  };
+}
+
+/** All of a route's files as URLs under the build's public prefix. */
+export function routeAssetUrls(
+  manifest: RouteAssetManifest,
+  component: string,
+): string[] {
+  const files = routeAssetFiles(manifest, component);
+  if (!files) return [];
+  const prefix = manifest.public_prefix || "/_pylon/build/";
+  return [...files.styles, ...files.preloads, ...files.fonts, ...files.scripts].map(
+    (f) => prefix + f,
+  );
+}

package/src/ssr-runtime.ts

@@ -9,6 +9,11 @@
 
 import { withMetaSlot } from "./ssr-page-tree";
 import { moduleKey, serverBundle } from "./server-bundle";
+import {
+  routeAssetFiles,
+  routeScriptFiles,
+  type RouteAssetFiles,
+} from "./ssr-route-assets";
 
 // Bun runtime global. This module runs under Bun but is type-checked by
 // consuming apps under node/DOM (no `Bun` global) — declare the surface used.
@@ -2126,6 +2131,7 @@ async function collectBoundaryHeadBlob(): Promise<string> {
     // Fonts first: the @font-face faces + preloads must be discoverable before
     // the app stylesheet that references the font family.
     let blob = await buildFontHeadBlob();
+    blob += await buildOfflineHeadBlob();
     for (const route of Object.values(manifest.routes || {}) as any[]) {
       for (const css of (route.css || []) as string[]) {
         if (seen.has(css)) continue;
@@ -2167,6 +2173,20 @@ async function buildFontHeadBlob(): Promise<string> {
   }
 }
 
+/** The install tags (web app manifest link, theme color, home-screen icon)
+ *  for an app that opted into `buildManifest({ offline })`; "" otherwise. */
+async function buildOfflineHeadBlob(): Promise<string> {
+  try {
+    const { getManifest } = await import("./ssr-client-bundler");
+    const manifest = await getManifest();
+    if (!manifest.offline) return "";
+    const { offlineHeadTags } = await import("./ssr-offline");
+    return offlineHeadTags(manifest.offline);
+  } catch {
+    return "";
+  }
+}
+
 /**
  * Build the hydration tail appended after React's stream EOFs: the
  * `__PYLON_DATA__` JSON blob (props + ssrData) + the per-route entry
@@ -2201,6 +2221,10 @@ export function buildHydrationTail(args: {
   // user's identity to another (the #277 leak class, at the body level). The
   // raw `auth` is replaced AFTER the live-handle strip below.
   bucketAuth?: { signedIn: boolean };
+  /** The app opted into `buildManifest({ offline })`: the client registers
+   *  the service worker (production only), and `useAppUpdate` compares this
+   *  build's version with `/_pylon/version`. */
+  offline?: { version: string; builtAt?: string };
   /** Client-side NAVIGATION payload: emit the `__PYLON_DATA__` blob and
    *  nothing else. The client already has the runtime and resolves the route
    *  entry from the build manifest, so the entry `<script>`, the preload tags
@@ -2265,6 +2289,14 @@ export function buildHydrationTail(args: {
   const appName =
     typeof process !== "undefined" ? process.env.PYLON_APP_NAME : undefined;
   if (appName) hydrationPayload.app = appName;
+  // App-global, identity-free: safe in a shared or offline tail.
+  if (args.offline) {
+    hydrationPayload.offline = {
+      dev: isDevMode(),
+      version: args.offline.version,
+      builtAt: args.offline.builtAt ?? null,
+    };
+  }
   if (args.kind) hydrationPayload.kind = args.kind;
   const json = escapeScriptJson(JSON.stringify(hydrationPayload));
   let tail = `<script id="__PYLON_DATA__" type="application/json">${json}</script>`;
@@ -2277,10 +2309,9 @@ export function buildHydrationTail(args: {
     const co = /^https?:\/\//i.test(args.publicPrefix) ? " crossorigin" : "";
     // Module scripts run in document order, so the polyfills are in place
     // before the entry (and the shared chunk it imports) runs.
-    if (args.polyfills) {
-      tail += `<script type="module"${co} src="${args.publicPrefix}${args.polyfills}"></script>`;
+    for (const script of routeScriptFiles(args.manifestRoute, args.polyfills)) {
+      tail += `<script type="module"${co} src="${args.publicPrefix}${script}"></script>`;
     }
-    tail += `<script type="module"${co} src="${args.publicPrefix}${args.manifestRoute.file}"></script>`;
   } else {
     // Executable script → the serialized message MUST be script-escaped
     // (`manifestErr` is server-derived today, but this is the one script sink
@@ -2651,16 +2682,23 @@ export function makeServerData(
   // executes it exactly like ctx.runQuery). Lets a page SSR data whose safe
   // public projection lives in a gated query instead of open row policies.
   callFn?: (name: string, args?: Record<string, unknown>) => Promise<unknown>,
-  // Fired on every serverData.fn call so the render can veto shared caching
-  // when the call carried a real identity (the fn may read ctx.auth, making
-  // its output identity-specific without the page ever touching props.auth).
-  onFnCall?: () => void,
+  // Fired on every call whose result can depend on the caller: serverData.fn
+  // (the fn may read ctx.auth) and every policy-filtered read (the host applies
+  // the caller's read policies to `ssrRead` reads). The render vetoes shared
+  // caching when it carried a real identity. `serverData.unsafe.*` skips
+  // policies, so its rows are the same for every caller and it does not fire.
+  onIdentityRead?: () => void,
+  // Fired on every serverData read (fn calls included), so an offline-shell
+  // render can refuse a page that needs the server to render.
+  onRead?: () => void,
 ): any {
   const promiseCache = new Map<string, Promise<any>>();
-  const wrap = (r: any, prefix: string): any => {
+  const wrap = (r: any, prefix: string, callerFiltered: boolean): any => {
     const out: any = {};
     for (const m of SERVER_DATA_METHODS) {
       out[m] = (...args: any[]) => {
+        onRead?.();
+        if (callerFiltered) onIdentityRead?.();
         const key = prefix + m + ":" + stableStringify(args);
         let p = promiseCache.get(key);
         if (!p) {
@@ -2675,16 +2713,17 @@ export function makeServerData(
     }
     return out;
   };
-  const sd = wrap(reader, "");
-  if (reader.unsafe) sd.unsafe = wrap(reader.unsafe, "u:");
+  const sd = wrap(reader, "", true);
+  if (reader.unsafe) sd.unsafe = wrap(reader.unsafe, "u:", false);
   if (callFn) {
     sd.fn = (name: string, args?: Record<string, unknown>) => {
+      onRead?.();
       // Key MUST match the client shim's `fn` key so hydration replays
       // the value from ssrData without a mismatch.
       const key = "fn:" + name + ":" + stableStringify(args ?? {});
       let p = promiseCache.get(key);
       if (!p) {
-        onFnCall?.();
+        onIdentityRead?.();
         p = callFn(name, args).then((value: any) => {
           valueCache[key] = value;
           return value;
@@ -2776,11 +2815,11 @@ export function computeCacheVerdict(args: {
  *    `authTouched` proves a bucketable body depends on nothing but the binary
  *    session bit.
  *  - `dynamicTouched` — reading request headers/cookies makes it request-specific.
- *  - `strictPolicies` — in strict mode serverData reads are auth-FILTERED, so the
- *    body/ssrData would vary by identity even without the page reading auth. In
- *    the default (non-strict) mode serverData reads bypass the policy gate and
- *    return identity-independent rows, so the cached body is safe to share within
- *    the bucket. Strict mode therefore must NOT bucket.
+ *  - `strictPolicies` — kept as a veto. Safe serverData reads are filtered by
+ *    the caller's read policies in EVERY mode (not only strict), so an
+ *    identity-carrying render that reads serverData sets `authTouched` itself
+ *    (makeServerData's onIdentityRead); that, not this flag, is what keeps a
+ *    signed-in render with policy-filtered rows out of the bucket.
  *  - cookieCount / forceDynamic / wantsStream / non-200 — same reasons as the
  *    anon verdict (a Set-Cookie, a streaming head, or an error/redirect can't be
  *    safely shared).
@@ -2813,6 +2852,50 @@ export function computeBucketVerdict(args: {
   );
 }
 
+/** Whether the host forwarded the service worker's offline-shell request
+ *  header (`X-Pylon-Offline-Shell: 1`). */
+export function isOfflineShellRequest(
+  headers: Record<string, unknown> | undefined,
+): boolean {
+  const v = headers?.["x-pylon-offline-shell"];
+  return typeof v === "string" && v.trim() === "1";
+}
+
+/**
+ * May the offline service worker keep this render as the route's shell? The
+ * shell is stored on the device and shown, with no network, to whoever is
+ * signed in at the time, so its HTML must not depend on who rendered it:
+ *
+ *  - `authTouched`: reading `props.auth` (or a `serverData.fn` call with an
+ *    identity) makes the HTML one user's. Read `props.session.exists` for a
+ *    signed-in check; the shell keeps that bit and nothing else.
+ *  - `dynamicTouched`: request headers and cookies are one request's.
+ *  - `serverDataTouched`: offline there is no server; an offline route
+ *    renders its data from the replica with `db.useQuery`.
+ *  - a Set-Cookie, or any status but 200 (a redirect to sign-in, an error).
+ *
+ * Pure and exported for the leak-class tests.
+ */
+export function computeOfflineShellVerdict(args: {
+  authTouched: boolean;
+  dynamicTouched: boolean;
+  serverDataTouched: boolean;
+  cookieCount: number;
+  status: number;
+}): { ok: true } | { ok: false; reason: string } {
+  if (args.status !== 200) return { ok: false, reason: `status ${args.status}` };
+  // serverData before auth: a signed-in serverData read also sets authTouched
+  // (it returns the caller's rows), and "read serverData" is the actionable
+  // reason.
+  if (args.serverDataTouched) return { ok: false, reason: "the page read serverData" };
+  if (args.authTouched) return { ok: false, reason: "the page read props.auth" };
+  if (args.dynamicTouched) {
+    return { ok: false, reason: "the page read request headers or cookies" };
+  }
+  if (args.cookieCount > 0) return { ok: false, reason: "the render set a cookie" };
+  return { ok: true };
+}
+
 /**
  * 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
@@ -3365,6 +3448,9 @@ export async function handleRenderRoute(
     // caching, because the output could differ by identity. Declared before
     // serverData so `serverData.fn` can flip it too (below).
     let authTouched = false;
+    // Whether the render read `serverData` at all. An offline shell may not:
+    // offline there is no server, so the page must render from the replica.
+    let serverDataTouched = false;
     // `ssrRead: true` — serverData results are serialized into the
     // client-visible `__PYLON_DATA__` blob, so the host applies the same
     // per-row policy filter + `server_only`/`passwordHash` projection the
@@ -3373,18 +3459,22 @@ export async function handleRenderRoute(
       buildDbReader(msg.call_id, true),
       ssrValueCache,
       buildSsrFnCaller(msg.call_id),
-      // A query function runs with the page's auth and may read ctx.auth
-      // internally — identity-specific output the read-tracking proxies
-      // can't see. An identity-carrying render that called serverData.fn
-      // must therefore veto shared caches exactly as if it read props.auth.
-      // Anonymous renders stay cacheable: the anonymous result is uniform
-      // across every anonymous visitor.
+      // A query function may read ctx.auth, and a safe read returns only the
+      // rows the caller's read policies allow: identity-specific output the
+      // read-tracking proxies can't see. An identity-carrying render that
+      // called serverData.fn or made a safe read must therefore veto shared
+      // caches exactly as if it read props.auth. Anonymous renders stay
+      // cacheable: the anonymous result is uniform across every anonymous
+      // visitor.
       () => {
         const a = msg.auth as Record<string, unknown> | undefined;
         if (a && (a.user_id || a.is_admin || a.tenant_id)) {
           authTouched = true;
         }
       },
+      () => {
+        serverDataTouched = true;
+      },
     );
 
     // #277 cache-safety proof. A render is shareable (CDN/disk cacheable) ONLY
@@ -3468,7 +3558,11 @@ export async function handleRenderRoute(
     // a shallow allowlist would copy that mutation by reference into the shared
     // tail. Captured only for opted-in pages (zero cost otherwise).
     const bucketOptIn = (mod as any).cache === "auth-bucketed";
-    const bucketTailBase = bucketOptIn
+    // The offline service worker asked for this route's HTML to keep (see
+    // `computeOfflineShellVerdict`). Read off the raw headers: the framework
+    // reading it is not the page reading a request input.
+    const offlineShell = isOfflineShellRequest(msg.headers as Record<string, unknown>);
+    const bucketTailBase = bucketOptIn || offlineShell
       ? {
           pathname: msg.url,
           url: msg.url,
@@ -3556,7 +3650,10 @@ export async function handleRenderRoute(
     // with `export const streaming = true` (inner-boundary streaming, Stage 2).
     // Every un-annotated page keeps the byte-identical BUFFERED path (allReady)
     // that 100% of today's prod traffic rides — this is opt-in, never default.
-    const wantsStream = computeWantsStream(!!Loading, mod);
+    // An offline shell is always buffered: its verdict reads `authTouched`
+    // and friends, which a streaming render has not finished setting when its
+    // head goes out.
+    const wantsStream = !offlineShell && computeWantsStream(!!Loading, mod);
 
     // Resolve the layout chain. Each layout module exports a default
     // function that accepts the same props + `children`. Walk leaf →
@@ -3705,6 +3802,16 @@ export async function handleRenderRoute(
       wantsStream,
       status: responseState.status,
     });
+    const shellVerdict = offlineShell
+      ? computeOfflineShellVerdict({
+          authTouched,
+          dynamicTouched,
+          serverDataTouched,
+          cookieCount: responseState.cookies.length,
+          status: responseState.status,
+        })
+      : null;
+    const shellOk = shellVerdict?.ok === true;
     // 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`),
@@ -3743,7 +3850,7 @@ export async function handleRenderRoute(
           headers: msg.headers,
           cookies: msg.cookies,
           session: { exists: msg.session_present === true },
-          ...(bucketable && bucketTailBase ? bucketTailBase : {}),
+          ...((bucketable || shellOk) && bucketTailBase ? bucketTailBase : {}),
         }
       : props;
     // #278: on a STREAMING render the head commits NOW, before suspended
@@ -3781,6 +3888,15 @@ export async function handleRenderRoute(
         // 406, and the `<path>.md` URL 404s. Trusted channel, stripped by the
         // host, so a page can't forge the inverse and force a conversion.
         ...((mod as any).markdown === false ? { "x-pylon-md": "0" } : {}),
+        // Offline shell verdict. The host re-emits it as `Pylon-Offline-Shell`
+        // for the service worker, which keeps the HTML only on "1".
+        ...(shellVerdict
+          ? {
+              "x-pylon-offline-shell": shellVerdict.ok
+                ? "1"
+                : `refused; ${shellVerdict.reason}`,
+            }
+          : {}),
         // 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.
@@ -3814,12 +3930,23 @@ export async function handleRenderRoute(
     let preloadManifestErr: string | null = null;
     let preloadPublicPrefix = "/_pylon/build/";
     let preloadPolyfills: string | undefined;
+    // The same file list the offline service worker precaches for this route.
+    let preloadAssets: RouteAssetFiles | null = null;
+    // The build's version when the app opted into `buildManifest({ offline })`.
+    let offlineApp: { version: string; builtAt?: string } | undefined;
     try {
       const { getManifest } = await import("./ssr-client-bundler");
       const manifest = await getManifest();
       preloadPublicPrefix = manifest.public_prefix || preloadPublicPrefix;
       preloadManifestRoute = manifest.routes[msg.component] ?? null;
       preloadPolyfills = manifest.polyfills;
+      preloadAssets = routeAssetFiles(manifest, msg.component);
+      if (manifest.offline) {
+        offlineApp = {
+          version: manifest.offline.version,
+          builtAt: manifest.offline.builtAt,
+        };
+      }
       if (!preloadManifestRoute) {
         preloadManifestErr = `manifest has no entry for "${msg.component}"`;
       }
@@ -3839,13 +3966,14 @@ export async function handleRenderRoute(
       );
     } else if (preloadManifestRoute) {
       headBlob += await buildFontHeadBlob();
+      headBlob += await buildOfflineHeadBlob();
       const co = /^https?:\/\//i.test(preloadPublicPrefix) ? " crossorigin" : "";
       const inlineOverride =
         typeof mod?.inlineCss === "boolean" ? mod.inlineCss : undefined;
-      for (const css of preloadManifestRoute.css) {
+      for (const css of preloadAssets?.styles ?? []) {
         headBlob += await cssHeadTag(css, preloadPublicPrefix, inlineOverride);
       }
-      for (const chunk of preloadManifestRoute.imports) {
+      for (const chunk of preloadAssets?.preloads ?? []) {
         headBlob += `<link rel="modulepreload"${co} href="${preloadPublicPrefix}${chunk}">`;
       }
     } else {
@@ -3991,9 +4119,12 @@ export async function handleRenderRoute(
           : undefined,
         // A bucketed render is stored shared → its tail must carry ONLY the
         // binary signed-in bit, never this request's real identity.
-        bucketAuth: bucketable
+        // An offline shell is kept on the device and replayed to whoever is
+        // signed in later, so it gets the same identity-free tail.
+        bucketAuth: bucketable || shellOk
           ? { signedIn: msg.session_present === true }
           : undefined,
+        offline: offlineApp,
         dataOnly: navRender,
       });
       sendChunk(tail);

package/src/ssr-serverdata-fn.test.ts

@@ -8,7 +8,7 @@
  *  - promise caching per (name, args) so React 19 `use()` gets the SAME
  *    promise on the post-suspense re-render;
  *  - resolved values recorded into the valueCache (the ssrData blob);
- *  - the onFnCall notification that lets the render veto shared caching for
+ *  - the onIdentityRead notification that lets the render veto shared caching for
  *    identity-carrying requests;
  *  - the client runtime template carrying the matching `fn` shim.
  */
@@ -47,7 +47,7 @@ describe("makeServerData.fn", () => {
     ]);
   });
 
-  test("onFnCall fires once per unique call (the cache-veto hook)", async () => {
+  test("onIdentityRead fires once per unique fn call (the cache-veto hook)", async () => {
     let touches = 0;
     const sd = makeServerData(
       noopReader,

package/src/types.ts

@@ -832,7 +832,21 @@ export type LlmContentBlock =
       tool_use_id: string;
       content: string;
       is_error?: boolean;
-    };
+    }
+  /** An image the model reads: png, jpeg, gif or webp, as base64. */
+  | { type: "image"; source: LlmMediaSource }
+  /**
+   * A document the model reads: a PDF or plain text, as base64. Anthropic
+   * only: the OpenAI provider refuses it (LLM_UNSUPPORTED_CONTENT).
+   */
+  | { type: "document"; source: LlmMediaSource; title?: string };
+
+/** The bytes of an image or document block. */
+export interface LlmMediaSource {
+  type: "base64";
+  media_type: string;
+  data: string;
+}
 
 export interface LlmTool {
   name: string;
@@ -1075,6 +1089,35 @@ export interface Files {
    * so keep lifetimes short.
    */
   signedUrl(fileId: string, opts?: { ttlSecs?: number }): Promise<string>;
+  /**
+   * What the host knows of a stored file, in any function. On a backend
+   * that tracks owners (local disk, a private S3 bucket) `ownerId` is who
+   * uploaded or stored it, and a file that does not exist is null. A
+   * backend that does not (`ownerTracked: false`, the Stack0 CDN) knows no
+   * owner: there a file id is a capability, so check who may use it
+   * yourself, for example by recording uploads in your own rows.
+   */
+  info(fileId: string): Promise<FileInfo | null>;
+}
+
+/** {@link Files.info}. */
+export interface FileInfo {
+  id: string;
+  /** Recorded at upload, when the backend keeps it. */
+  contentType: string | null;
+  /** The uploader, or null when the backend does not track it or the system stored it. */
+  ownerId: string | null;
+  public: boolean;
+  /** The backend records owners, so `ownerId` and a null answer can be trusted. */
+  ownerTracked: boolean;
+}
+
+/** {@link ActionFiles.read}. */
+export interface ReadFile {
+  id: string;
+  contentType: string | null;
+  size: number;
+  data: Uint8Array;
 }
 
 /** Options for {@link ActionFiles.store}. */
@@ -1117,6 +1160,12 @@ export interface ActionFiles extends Files {
   ): Promise<StoredFile>;
   /** Delete a stored file. `deleted` is false when it did not exist. */
   delete(fileId: string): Promise<{ deleted: boolean }>;
+  /**
+   * A stored file's bytes, with server trust: the function decides who may
+   * read it. At most the host's upload limit (25 MiB, or
+   * `PYLON_MAX_UPLOAD_BYTES`).
+   */
+  read(fileId: string): Promise<ReadFile>;
 }
 
 /**