@pylonsync/functions 0.11.6 → 0.12.0

package/src/ssr-og-runtime.ts

@@ -25,6 +25,7 @@
 
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { serverBundle } from "./server-bundle";
 
 // Satori's font descriptor.
 export interface OgFont {
@@ -68,9 +69,15 @@ function loadResvg() {
 	if (!resvgReady) {
 		resvgReady = (async () => {
 			const mod = await import("@resvg/resvg-wasm");
-			// Locate the wasm binary next to the package entry and init once.
-			const entry = fileURLToPath(import.meta.resolve("@resvg/resvg-wasm"));
-			const wasmPath = entry.replace(/index\.[^/]+$/, "index_bg.wasm");
+			// Locate the wasm binary next to the package entry (or in the
+			// production server bundle) and init once.
+			const bundled = serverBundle()?.ogAssets.resvgWasm;
+			const wasmPath =
+				bundled ??
+				fileURLToPath(import.meta.resolve("@resvg/resvg-wasm")).replace(
+					/index\.[^/]+$/,
+					"index_bg.wasm",
+				);
 			await mod.initWasm(readFileSync(wasmPath));
 			return mod;
 		})();
@@ -83,18 +90,23 @@ function loadResvg() {
 let defaultFonts: OgFont[] | null = null;
 function loadDefaultFonts(): OgFont[] {
 	if (defaultFonts) return defaultFonts;
+	const bundled = serverBundle()?.ogAssets;
 	const read = (rel: string) =>
 		readFileSync(fileURLToPath(new URL(rel, import.meta.url)));
 	defaultFonts = [
 		{
 			name: "Inter",
-			data: read("../assets/fonts/Inter-Regular.ttf"),
+			data: bundled
+				? readFileSync(bundled.interRegular)
+				: read("../assets/fonts/Inter-Regular.ttf"),
 			weight: 400,
 			style: "normal",
 		},
 		{
 			name: "Inter",
-			data: read("../assets/fonts/Inter-SemiBold.ttf"),
+			data: bundled
+				? readFileSync(bundled.interSemiBold)
+				: read("../assets/fonts/Inter-SemiBold.ttf"),
 			weight: 600,
 			style: "normal",
 		},

package/src/ssr-runtime.ts

@@ -7,6 +7,8 @@
 // the dispatch arm) so projects without SSR routes pay nothing — no
 // react-dom dependency requirement, no startup cost.
 
+import { moduleKey, serverBundle } from "./server-bundle";
+
 // 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.
 declare const Bun: {
@@ -716,8 +718,19 @@ export function renderMetadata(React: any, m: SsrMetadata | undefined): any {
 
 const MODULE_EXTS = [".tsx", ".ts", ".jsx", ".js"];
 
-/** Import a project-relative module, trying each common extension. */
+/**
+ * Import a project-relative module, trying each common extension. A
+ * production server bundle serves it from the bundle's module registry.
+ */
 export async function importModule(cwd: string, relPath: string): Promise<any> {
+  const bundle = serverBundle();
+  if (bundle) {
+    const load = bundle.modules[moduleKey(relPath)];
+    if (load === undefined) {
+      throw new Error(`module "${relPath}" is not in the server bundle`);
+    }
+    return load();
+  }
   const base = `${cwd}/${relPath}`;
   let lastErr: unknown = null;
   for (const ext of MODULE_EXTS) {
@@ -730,6 +743,58 @@ export async function importModule(cwd: string, relPath: string): Promise<any> {
   throw lastErr ?? new Error(`could not import module "${relPath}"`);
 }
 
+/**
+ * True when the project has a module at `<dir>/<name>` with any code
+ * extension. `dir` is project-relative and "/"-separated. A production server
+ * bundle answers from its module registry; source mode checks the disk.
+ */
+export function moduleExistsIn(
+  fs: any,
+  path: any,
+  cwd: string,
+  dir: string,
+  name: string,
+): boolean {
+  const bundle = serverBundle();
+  if (bundle) return moduleKey(`${dir}/${name}`) in bundle.modules;
+  return MODULE_EXTS.some((ext) =>
+    fs.existsSync(path.join(cwd, dir, `${name}${ext}`)),
+  );
+}
+
+/**
+ * The route-group directories (`(name)`) directly under the project-relative
+ * `dir`, sorted by name. A production server bundle derives them from its
+ * module registry keys; source mode reads the directory.
+ */
+function routeGroupDirsIn(fs: any, path: any, cwd: string, dir: string): string[] {
+  const isGroup = (n: string) => n.startsWith("(") && n.endsWith(")");
+  const bundle = serverBundle();
+  if (bundle) {
+    const prefix = `${dir}/`;
+    const found = new Set<string>();
+    for (const key of Object.keys(bundle.modules)) {
+      if (!key.startsWith(prefix)) continue;
+      const child = key.slice(prefix.length).split("/")[0];
+      // A key with no "/" after the prefix is a module file, not a directory.
+      if (key.slice(prefix.length).includes("/") && isGroup(child)) {
+        found.add(child);
+      }
+    }
+    return [...found].sort();
+  }
+  let entries: any[];
+  try {
+    entries = fs.readdirSync(path.join(cwd, dir), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e: any) => e.isDirectory() && isGroup(e.name))
+    .map((e: any) => e.name as string)
+    .sort();
+}
+
 /**
  * Wrap a leaf element in its layout chain (leaf → root). Resolves ALL
  * layouts first so a missing one fails before any chunk is emitted. Reused
@@ -829,25 +894,10 @@ function boundaryInDirOrGroups(
   dir: string,
   fileName: string,
 ): string | null {
-  for (const ext of MODULE_EXTS) {
-    if (fs.existsSync(path.join(cwd, dir, `${fileName}${ext}`))) {
-      return `${dir}/${fileName}`;
-    }
-  }
-  let entries: any[];
-  try {
-    entries = fs.readdirSync(path.join(cwd, dir), { withFileTypes: true });
-  } catch {
-    return null;
+  if (moduleExistsIn(fs, path, cwd, dir, fileName)) {
+    return `${dir}/${fileName}`;
   }
-  const groups = entries
-    .filter(
-      (e: any) =>
-        e.isDirectory() && e.name.startsWith("(") && e.name.endsWith(")"),
-    )
-    .map((e: any) => e.name as string)
-    .sort();
-  for (const g of groups) {
+  for (const g of routeGroupDirsIn(fs, path, cwd, dir)) {
     const hit = boundaryInDirOrGroups(fs, path, cwd, `${dir}/${g}`, fileName);
     if (hit) return hit;
   }
@@ -892,8 +942,6 @@ function findColocatedImage(
   return null;
 }
 
-const OG_IMAGE_CODE_EXTS = [".tsx", ".ts", ".jsx", ".js"];
-
 /**
  * Walk up from a page's directory to the nearest colocated dynamic OG
  * module (`opengraph-image.{tsx,ts,jsx,js}`) and return the CONCRETE
@@ -938,14 +986,12 @@ function findColocatedOgImageRoute(
     return below.filter((s) => !(s.startsWith("(") && s.endsWith(")"))).length;
   };
   while (dir && dir !== "." && dir !== "/") {
-    for (const ext of OG_IMAGE_CODE_EXTS) {
-      if (fs.existsSync(path.join(cwd, dir, `opengraph-image${ext}`))) {
-        const prefix =
-          dir === pageDir && !isBoundary
-            ? urlSegs
-            : urlSegs.slice(0, nonGroupDepth(dir));
-        return "/" + [...prefix, "opengraph-image"].join("/");
-      }
+    if (moduleExistsIn(fs, path, cwd, dir, "opengraph-image")) {
+      const prefix =
+        dir === pageDir && !isBoundary
+          ? urlSegs
+          : urlSegs.slice(0, nonGroupDepth(dir));
+      return "/" + [...prefix, "opengraph-image"].join("/");
     }
     const slash = dir.lastIndexOf("/");
     dir = slash >= 0 ? dir.slice(0, slash) : "";
@@ -2098,6 +2144,9 @@ export function buildHydrationTail(args: {
   manifestRoute: { file: string; imports: string[]; css: string[] } | null;
   publicPrefix: string;
   manifestErr: string | null;
+  /** core-js polyfill bundle (relative to `publicPrefix`), from the bundle
+   *  manifest. Loaded before the route entry. */
+  polyfills?: string;
   kind?: "error" | "not-found";
   errorForClient?: { message: string; digest?: string };
   // PPR Phase 0 (auth-bucketed caching): when set, this render is being stored
@@ -2181,6 +2230,11 @@ export function buildHydrationTail(args: {
     // reusable (no double fetch) and surfaces load errors. No-op for the
     // same-origin `/_pylon/build/` default.
     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>`;
+    }
     tail += `<script type="module"${co} src="${args.publicPrefix}${args.manifestRoute.file}"></script>`;
   } else {
     // Executable script → the serialized message MUST be script-escaped
@@ -2258,11 +2312,8 @@ function resolveLayoutChain(componentRelPath: string, cwd: string): string[] {
   let acc = "";
   for (const part of parts) {
     acc = acc ? `${acc}/${part}` : part;
-    for (const ext of MODULE_EXTS) {
-      if (fs.existsSync(path.join(cwd, acc, `layout${ext}`))) {
-        layouts.push(`${acc}/layout`);
-        break;
-      }
+    if (moduleExistsIn(fs, path, cwd, acc, "layout")) {
+      layouts.push(`${acc}/layout`);
     }
   }
   return layouts;
@@ -2321,6 +2372,7 @@ async function renderBoundaryToClient(
     | { file: string; imports: string[]; css: string[] }
     | null = null;
   let publicPrefix = "/_pylon/build/";
+  let polyfills: string | undefined;
   let headBlob = "";
   if (tail) {
     try {
@@ -2328,6 +2380,7 @@ async function renderBoundaryToClient(
       const manifest = await getManifest();
       publicPrefix = manifest.public_prefix || publicPrefix;
       manifestRoute = manifest.routes[tail.component] ?? null;
+      polyfills = manifest.polyfills;
     } catch {
       manifestRoute = null;
     }
@@ -2374,6 +2427,7 @@ async function renderBoundaryToClient(
       manifestRoute,
       publicPrefix,
       manifestErr: null,
+      polyfills,
       kind: tail.kind,
       errorForClient: tail.errorForClient,
     });
@@ -3201,22 +3255,30 @@ export async function handleRenderRoute(
     // `react-dom/server` (which is Node-stream-style). Try browser
     // first, fall back to the default entry for environments that
     // re-route it (Next runs a custom dist).
+    //
+    // A production server bundle carries the app's React, bundled with the
+    // page modules, so there is nothing to resolve.
+    const bundle = serverBundle();
     let reactDomServerImport: any;
-    try {
-      // @ts-ignore — user-dep, resolved at runtime
-      reactDomServerImport = await import(
-        /* @vite-ignore */ resolveFromUser("react-dom/server.browser")
-      );
-    } catch {
+    let reactImport: any;
+    if (bundle) {
+      reactDomServerImport = bundle.reactDomServer;
+      reactImport = bundle.react;
+    } else {
+      try {
+        // @ts-ignore — user-dep, resolved at runtime
+        reactDomServerImport = await import(
+          /* @vite-ignore */ resolveFromUser("react-dom/server.browser")
+        );
+      } catch {
+        // @ts-ignore — user-dep, resolved at runtime
+        reactDomServerImport = await import(
+          /* @vite-ignore */ resolveFromUser("react-dom/server")
+        );
+      }
       // @ts-ignore — user-dep, resolved at runtime
-      reactDomServerImport = await import(
-        /* @vite-ignore */ resolveFromUser("react-dom/server")
-      );
+      reactImport = await import(/* @vite-ignore */ resolveFromUser("react"));
     }
-    // @ts-ignore — user-dep, resolved at runtime
-    const reactImport = await import(
-      /* @vite-ignore */ resolveFromUser("react")
-    );
     React = reactImport.default ?? reactImport;
     renderToReadableStream =
       reactDomServerImport.renderToReadableStream ??
@@ -3700,11 +3762,13 @@ export async function handleRenderRoute(
       | null = null;
     let preloadManifestErr: string | null = null;
     let preloadPublicPrefix = "/_pylon/build/";
+    let preloadPolyfills: 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;
       if (!preloadManifestRoute) {
         preloadManifestErr = `manifest has no entry for "${msg.component}"`;
       }
@@ -3866,6 +3930,7 @@ export async function handleRenderRoute(
         manifestRoute: preloadManifestRoute,
         publicPrefix: preloadPublicPrefix,
         manifestErr: preloadManifestErr,
+        polyfills: preloadPolyfills,
         kind: isBoundaryComponent
           ? /(^|\/)error$/.test(msg.component)
             ? "error"

package/src/stdout-fence.ts

@@ -0,0 +1,69 @@
+// Keeps stdout for the host protocol. See `fenceStdout`.
+
+// Bun global used here. Declared locally so apps that type-check this source
+// without bun-types still pass `tsc` (same pattern as runtime.ts).
+declare const Bun: {
+  write(dest: unknown, data: string): unknown;
+  stderr: unknown;
+};
+
+/**
+ * Redirect console.* from user code to stderr so handlers can't accidentally
+ * emit a line that looks like a protocol frame and confuse the Rust reader.
+ *
+ * Before this guard, a handler calling `console.log('{"type":"return",...}')`
+ * — either intentionally or by logging an object shaped that way — would be
+ * parsed by the host as a real protocol message. Moving all console output
+ * to stderr keeps stdout reserved for NDJSON protocol frames only.
+ *
+ * The original console methods are saved on the console object as
+ * `__stdoutLog` etc. in case the runtime itself needs to write diagnostics
+ * to stdout for some reason (it currently doesn't).
+ *
+ * Safe to call more than once. A production server bundle calls it from its
+ * entry, before the app modules load, and the runtime's `main()` calls it
+ * again.
+ */
+export function fenceStdout(): void {
+  const c = globalThis.console as unknown as Record<string, unknown>;
+  if (c.__pylonFenced) return;
+  c.__pylonFenced = true;
+  const toStderr = (prefix: string) => (...args: unknown[]) => {
+    const line = args
+      .map((a) => {
+        if (typeof a === "string") return a;
+        // Error: JSON.stringify yields `{}` because message/stack are
+        // non-enumerable. That made `console.error("x:", err)` log as `x: {}`,
+        // hiding the real failure from operators. Unwrap by hand.
+        if (a instanceof Error) {
+          const parts = [a.stack || `${a.name}: ${a.message}`];
+          const code = (a as { code?: unknown }).code;
+          if (code !== undefined) parts.push(`code=${String(code)}`);
+          const cause = (a as { cause?: unknown }).cause;
+          if (cause !== undefined) {
+            try {
+              parts.push(`cause=${cause instanceof Error ? cause.stack || cause.message : JSON.stringify(cause)}`);
+            } catch {
+              parts.push(`cause=${String(cause)}`);
+            }
+          }
+          return parts.join(" ");
+        }
+        try {
+          return JSON.stringify(a);
+        } catch {
+          return String(a);
+        }
+      })
+      .join(" ");
+    Bun.write(Bun.stderr, `${prefix}${line}\n`);
+  };
+  // Intentional: we want console.* for user handlers to go to stderr.
+  // Overwrite the globals before any user code is loaded.
+  c.__stdoutLog = c.log;
+  c.log = toStderr("");
+  c.info = toStderr("");
+  c.warn = toStderr("[warn] ");
+  c.error = toStderr("[error] ");
+  c.debug = toStderr("[debug] ");
+}

package/src/types.ts

@@ -827,6 +827,42 @@ export interface Files {
   signedUrl(fileId: string, opts?: { ttlSecs?: number }): Promise<string>;
 }
 
+/**
+ * Shard tickets: short-lived, signed permission to join one realtime shard,
+ * with claims the shard's authorization hooks read without a database
+ * call. Check what the user may do here, then mint:
+ *
+ * ```ts
+ * export default mutation({
+ *   args: { characterId: v.id("Character") },
+ *   async handler(ctx, args) {
+ *     const c = await ctx.db.get("Character", args.characterId);
+ *     if (c?.ownerId !== ctx.auth.userId) throw ctx.error("FORBIDDEN", "not your character");
+ *     const shard = `zone-${c.zone}`;
+ *     const ticket = await ctx.shards.ticket(shard, {
+ *       subscriberId: c.id,
+ *       claims: { character: c.id, realm: c.realm },
+ *     });
+ *     return { shard, ticket };
+ *   },
+ * });
+ * ```
+ *
+ * The client passes the ticket when it connects (`connectShard(shard, {
+ * ticket })`). The shard rejects a ticket for another shard, another
+ * subscriber id, or past its expiry.
+ */
+export interface Shards {
+  /**
+   * Mint a ticket for `shardId`. `subscriberId` defaults to the calling
+   * user's id; `ttlSecs` defaults to 60 and is capped at 3600 by the host.
+   */
+  ticket(
+    shardId: string,
+    opts?: { subscriberId?: string; claims?: Record<string, unknown>; ttlSecs?: number },
+  ): Promise<string>;
+}
+
 /** Context for query handlers (read-only).
  *
  * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
@@ -852,6 +888,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
   requireMember: RequireMember;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
+  /** Shard tickets — see {@link Shards}. */
+  shards: Shards;
   /**
    * Fires when the host cancels this call (idle timeout exceeded).
    * Thread it into `fetch(url, { signal: ctx.signal })` or SDK calls so
@@ -880,6 +918,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   workflows: Workflows;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
+  /** Shard tickets — see {@link Shards}. */
+  shards: Shards;
   /** Create a typed error that triggers rollback. */
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */
@@ -1053,6 +1093,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   env: Record<string, string>;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
+  /** Shard tickets — see {@link Shards}. */
+  shards: Shards;
   /** Run a registered query within its own read transaction. */
   runQuery<T = unknown>(
     fnName: string,