@pylonsync/functions 0.22.40 → 0.22.43

package/dist/index.d.ts

@@ -27,4 +27,4 @@ export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunne
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, WorkflowRunSummary, WorkflowRunStatus, Audit, AuditLog, AuditEntry, Agents, AgentRunOptions, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainRecord, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, Files, ActionFiles, StoreFileOptions, StoredFile, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, WorkflowRunSummary, WorkflowRunStatus, Audit, AuditLog, AuditEntry, Agents, AgentRunOptions, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainRecord, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, Files, ActionFiles, Crdt, StoreFileOptions, StoredFile, } from "./types";

package/dist/ssr-page-tree.d.ts

@@ -0,0 +1,4 @@
+type CreateElement = (type: any, props: any, ...children: any[]) => any;
+/** The page with its metadata slot. `meta` is null in the browser. */
+export declare function withMetaSlot(createElement: CreateElement, Fragment: any, meta: unknown, page: unknown): any;
+export {};

package/dist/types.d.ts

@@ -949,6 +949,29 @@ export type RequireMember = (orgId: string, opts?: RequireMemberOptions) => Prom
  * });
  * ```
  */
+/**
+ * `ctx.crdt` (actions only): read and change a row's live CRDT document, the
+ * one editors bind to with `@pylonsync/loro`. Bytes are Loro's own formats.
+ * `@pylonsync/loro/server` wraps this in a `LoroDoc` (`openLiveDoc`).
+ *
+ * Each `apply` is its own write: it merges, then reaches everyone editing at
+ * once, so it cannot roll back with a mutation (queries and mutations get
+ * CRDT_ACTIONS_ONLY). Policies follow the `ctx.db` rule: they apply under
+ * strict function policies (`PYLON_STRICT_FN_POLICIES=1`), except through
+ * `ctx.crdt.unsafe`. Without strict policies, check access yourself.
+ */
+export interface Crdt {
+    /** The row's whole document, or null when the row does not exist (or, under
+     *  strict policies, the caller may not read it). */
+    snapshot(entity: string, id: string): Promise<Uint8Array | null>;
+    /** The changes since `version` (a Loro version vector, `doc.oplogVersion().encode()`),
+     *  or null as for {@link Crdt.snapshot}. */
+    since(entity: string, id: string, version: Uint8Array): Promise<Uint8Array | null>;
+    /** Merge a Loro update into the row and broadcast it. */
+    apply(entity: string, id: string, update: Uint8Array): Promise<void>;
+    /** The same operations with server trust even under strict policies. */
+    unsafe: Omit<Crdt, "unsafe">;
+}
 export interface Files {
     /**
      * Mint a signed download path for a file id. `ttlSecs` defaults to 300
@@ -1422,6 +1445,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     env: Record<string, string>;
     /** Signed file-download URLs — see {@link Files}. */
     files: ActionFiles;
+    /** A row's live CRDT document, as Loro bytes — see {@link Crdt}. */
+    crdt: Crdt;
     /** Shard tickets, reads, and start/stop — see {@link Shards}. */
     shards: Shards;
     /** Run a registered query within its own read transaction. */

package/package.json

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

package/src/index.ts

@@ -117,6 +117,7 @@ export type {
   // File storage from functions.
   Files,
   ActionFiles,
+  Crdt,
   StoreFileOptions,
   StoredFile,
 } from "./types";

package/src/runtime.ts

@@ -24,6 +24,7 @@ import type {
   EmailSender,
   Files,
   ActionFiles,
+  Crdt,
   StoredFile,
   Shards,
   ShardInfo,
@@ -673,6 +674,36 @@ function buildActionFiles(callId: string): ActionFiles {
  *  FILES_STORE_MAX_BYTES; `PYLON_MAX_UPLOAD_BYTES` can lower the host's. */
 const FILES_STORE_MAX_BYTES = 25 * 1024 * 1024;
 
+/** `ctx.crdt` — see {@link Crdt}. */
+function buildCrdt(callId: string): Crdt {
+  const ops = (unsafeOp: boolean): Omit<Crdt, "unsafe"> => {
+    const call = (entity: string, id: string, op: Record<string, unknown>) =>
+      rpcDb(callId, { type: "crdt_op", entity, id, unsafe_op: unsafeOp, ...op }) as Promise<
+        Record<string, string> | null
+      >;
+    return {
+      async snapshot(entity, id) {
+        const res = await call(entity, id, { op: "snapshot" });
+        return res ? fromBase64(res.snapshot) : null;
+      },
+      async since(entity, id, version) {
+        const res = await call(entity, id, { op: "since", version_base64: toBase64(version) });
+        return res ? fromBase64(res.update) : null;
+      },
+      async apply(entity, id, update) {
+        await call(entity, id, { op: "apply", update_base64: toBase64(update) });
+      },
+    };
+  };
+  return { ...ops(false), unsafe: ops(true) };
+}
+
+/** Bytes of a base64 string. */
+function fromBase64(data: string): Uint8Array {
+  const buf = Buffer.from(data, "base64");
+  return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+}
+
 /** Base64 of bytes, or of a string's UTF-8 encoding. */
 function toBase64(data: Uint8Array | ArrayBuffer | string): string {
   const bytes =
@@ -1445,6 +1476,7 @@ function buildActionCtx(
       return err;
     },
     files: buildActionFiles(callId),
+    crdt: buildCrdt(callId),
     shards: buildShards(callId),
     // Actions have no ctx.db; read membership via the built-in internal query.
     requireMember: makeRequireMember(auth.userId, (entity, filter) =>
@@ -1640,6 +1672,9 @@ async function handleCall(msg: CallMessage): Promise<void> {
         // so a call from a query or mutation gets the host's
         // FILES_WRITE_NOT_ALLOWED instead of a TypeError.
         files: buildActionFiles(msg.call_id),
+        // Not on the query or mutation type; present at runtime so a call
+        // gets the host's CRDT_ACTIONS_ONLY instead of a TypeError.
+        crdt: buildCrdt(msg.call_id),
         shards: buildShards(msg.call_id),
       };
       break;
@@ -1669,6 +1704,9 @@ async function handleCall(msg: CallMessage): Promise<void> {
         // so a call from a query or mutation gets the host's
         // FILES_WRITE_NOT_ALLOWED instead of a TypeError.
         files: buildActionFiles(msg.call_id),
+        // Not on the query or mutation type; present at runtime so a call
+        // gets the host's CRDT_ACTIONS_ONLY instead of a TypeError.
+        crdt: buildCrdt(msg.call_id),
         shards: buildShards(msg.call_id),
       };
       break;

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

@@ -395,6 +395,33 @@ export default function Doc() {
   });
 });
 
+describe("assets a stylesheet references", () => {
+  // The asset plugin answers JavaScript imports with a JavaScript module; a
+  // stylesheet's url(...) must stay with Bun, or the build fails with
+  // "Cannot import a .js file into a CSS file".
+  test("a page importing CSS that uses url() still builds", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": `
+import React from "react";
+import "./look.css";
+export default function Home() {
+  return <div className="hero">home</div>;
+}
+`,
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    fs.writeFileSync(path.join(tempDir, "app", "look.css"), ".hero { background: url(./bg.png); }\n");
+    fs.writeFileSync(path.join(tempDir, "app", "bg.png"), new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]));
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath } = await buildClientBundle();
+    expect(fs.existsSync(manifestPath)).toBe(true);
+  });
+});
+
 describe("nearestBoundaryComponent (client boundary resolution)", () => {
   const routes = new Set([
     "web/app/not-found",
@@ -767,6 +794,13 @@ describe("loading.tsx is wired into the client build", () => {
     // (see ssr-hydration.test.ts for why a missing boundary breaks hydration).
     expect(runtime).toContain("buildTree(Page, Layouts, currentPageProps, data.component)");
     expect(runtime).toContain("createElement(Suspense, { fallback: createElement(Loading, props) }, tree)");
+    // The metadata slot the server renders beside every page, empty in the
+    // browser, from the same module the server uses (ssr-page-tree.ts).
+    expect(runtime).toContain('import { withMetaSlot } from "./page-tree";');
+    expect(runtime).toContain("tree = withMetaSlot(createElement, Fragment, null, tree);");
+    expect(fs.readFileSync(path.join(tempDir, ".pylon", "page-tree.ts"), "utf8")).toBe(
+      fs.readFileSync(path.join(import.meta.dir, "ssr-page-tree.ts"), "utf8"),
+    );
   });
 
   test("an app with no loading.tsx still builds and navigates", async () => {

package/src/ssr-client-bundler.ts

@@ -93,7 +93,7 @@ type BunBuildOutput = {
 type BunPluginBuild = {
   onResolve(
     opts: { filter: RegExp; namespace?: string },
-    callback: (args: { path: string; importer: string }) => void,
+    callback: (args: { path: string; importer: string }) => { path: string; namespace: string } | undefined | void,
   ): void;
   onLoad(
     opts: { filter: RegExp; namespace?: string },
@@ -355,13 +355,14 @@ ${entries}
 const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime).
 // DO NOT EDIT — overwritten on every pylon dev / build.
 
-import { createElement, Suspense } from "react";
+import { createElement, Fragment, Suspense } from "react";
 import { hydrateRoot } from "react-dom/client";
 import { configureClient } from "@pylonsync/react";
 import { createPylonBoundary, nearestBoundaryComponent } from "./client-boundary";
 import { LOADING_MODULES } from "./loading-registry";
 import { createNavPayloadCache } from "./nav-cache";
 import { matchRoute, prefetchTargets } from "./route-match";
+import { withMetaSlot } from "./page-tree";
 
 const routeCache = Object.create(null);
 let activeRoot = null;
@@ -387,6 +388,9 @@ function buildTree(Page, Layouts, props, loadingFor) {
   if (Loading) {
     tree = createElement(Suspense, { fallback: createElement(Loading, props) }, tree);
   }
+  // The server renders the page's metadata in this slot; the browser leaves
+  // it empty. Same shape on both sides, so useId values match (page-tree.ts).
+  tree = withMetaSlot(createElement, Fragment, null, tree);
   for (let i = Layouts.length - 1; i >= 0; i--) {
     const Layout = Layouts[i];
     if (!Layout) continue;
@@ -1568,6 +1572,14 @@ export async function _doBuildInner(
       "utf8",
     );
 
+    // Same pattern for the page's tree shape, which the server render
+    // shares (ssr-page-tree.ts): the runtime imports it as `./page-tree`.
+    fs.writeFileSync(
+      path.join(stageDir, "page-tree.ts"),
+      fs.readFileSync(path.join(here, "ssr-page-tree.ts"), "utf8"),
+      "utf8",
+    );
+
     // Same pattern for the optimistic-navigation route matcher — the runtime
     // imports it as `./route-match`; its source of truth is ssr-route-match.ts,
     // unit-tested directly.
@@ -2081,41 +2093,23 @@ function makeBuildId(): string {
   return `${process.pid.toString(36)}-${Date.now().toString(36)}-${_buildCounter}`;
 }
 
-/**
- * Base URL/path prepended to every SSR-emitted asset reference (the entry
- * `<script type="module">`, `<link rel="stylesheet">`, and `modulepreload`s)
- * and to client-side chunk loads — baked into the bundle manifest as
- * `public_prefix`.
- *
- * Defaults to `/_pylon/build/`, which the Rust host serves from the build's
- * local `outdir`. That keeps dev and any deploy that doesn't opt in unchanged.
- *
- * Set `PYLON_PUBLIC_PREFIX` to an ABSOLUTE base (a CDN / object-storage URL for
- * this build's content-hashed assets, e.g. `https://assets.pyln.dev/<build>/`)
- * to serve assets off the app machines entirely. This is what makes hashed
- * assets survive an artifact prune and resolve IDENTICALLY across every Fly
- * machine: the entry filename SSR emits becomes an absolute URL that always
- * exists, instead of a machine-local path a prune/rollover can 404 (the bug
- * where a stale machine emitted `client-entry-…-<oldhash>.js` after that file
- * was pruned, breaking hydration). A trailing slash is enforced so
- * `${prefix}${file}` always joins correctly.
- */
-/** Where the Rust host serves the client build (`/_pylon/build/<path>`). The
- *  manifest's `public_prefix` and the bundler's `publicPath` must agree. */
+/** Where the Rust host serves the client build (`/_pylon/build/<path>`): the
+ *  manifest's `public_prefix`, and the prefix of imported assets' URLs. */
 const BUILD_PREFIX = "/_pylon/build/";
 
 /** Files a page can import as a URL (Bun's `file` loader). */
 const ASSET_RE = /\.(wasm|png|jpe?g|gif|webp|avif|ico|svg|woff2?|ttf|otf|mp3|mp4|webm|wav|ogg)$/i;
 
 /**
- * Imported assets (a `.wasm`, an image) as absolute URLs under the build
- * prefix. Bun's own `file` loader exports a RELATIVE path ("assets/x.wasm"),
+ * Assets JavaScript imports (a `.wasm`, an image) as absolute URLs under the
+ * build prefix. Bun's `file` loader exports a RELATIVE path ("assets/x.wasm"),
  * and code that fetches it resolves it against the page: loro-crdt's browser
  * build fetched /dashboard/orgs/acme/assets/loro_wasm_bg-….wasm and 404'd.
  * Bun's `publicPath` would make it absolute, but it also rewrites imports
  * between split chunks and drops their `chunks/` directory (Bun 1.3.14), so
  * this plugin writes the file itself, named by its content hash, and exports
- * the absolute URL.
+ * the absolute URL. A stylesheet's `url(...)` is left to Bun: CSS cannot
+ * import a JavaScript module.
  */
 function absoluteAssetPlugin(
   outdir: string,
@@ -2123,10 +2117,19 @@ function absoluteAssetPlugin(
   path: typeof import("node:path"),
   createHash: typeof import("node:crypto").createHash,
 ): { name: string; setup(build: BunPluginBuild): void } {
+  const NAMESPACE = "pylon-asset";
   return {
     name: "pylon-absolute-assets",
     setup(build) {
-      build.onLoad({ filter: ASSET_RE }, (args) => {
+      build.onResolve({ filter: ASSET_RE }, (args) => {
+        if (!args.importer || /\.css$/i.test(args.importer)) return undefined;
+        const from = path.dirname(args.importer);
+        const resolved = args.path.startsWith(".") || path.isAbsolute(args.path)
+          ? path.resolve(from, args.path)
+          : ((Bun as any).resolveSync(args.path, from) as string);
+        return { path: resolved, namespace: NAMESPACE };
+      });
+      build.onLoad({ filter: /.*/, namespace: NAMESPACE }, (args) => {
         const bytes = fs.readFileSync(args.path);
         const hash = createHash("sha256").update(bytes).digest("hex").slice(0, 12);
         const ext = path.extname(args.path);
@@ -2139,6 +2142,25 @@ function absoluteAssetPlugin(
   };
 }
 
+/**
+ * Base URL/path prepended to every SSR-emitted asset reference (the entry
+ * `<script type="module">`, `<link rel="stylesheet">`, and `modulepreload`s)
+ * and to client-side chunk loads — baked into the bundle manifest as
+ * `public_prefix`.
+ *
+ * Defaults to `/_pylon/build/`, which the Rust host serves from the build's
+ * local `outdir`. That keeps dev and any deploy that doesn't opt in unchanged.
+ *
+ * Set `PYLON_PUBLIC_PREFIX` to an ABSOLUTE base (a CDN / object-storage URL for
+ * this build's content-hashed assets, e.g. `https://assets.pyln.dev/<build>/`)
+ * to serve assets off the app machines entirely. This is what makes hashed
+ * assets survive an artifact prune and resolve IDENTICALLY across every Fly
+ * machine: the entry filename SSR emits becomes an absolute URL that always
+ * exists, instead of a machine-local path a prune/rollover can 404 (the bug
+ * where a stale machine emitted `client-entry-…-<oldhash>.js` after that file
+ * was pruned, breaking hydration). A trailing slash is enforced so
+ * `${prefix}${file}` always joins correctly.
+ */
 function resolvePublicPrefix(): string {
   const raw = (process.env.PYLON_PUBLIC_PREFIX ?? "").trim();
   if (!raw) return "/_pylon/build/";

package/src/ssr-hydration.test.ts

@@ -21,6 +21,7 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { Window } from "happy-dom";
 import React, { Suspense, use } from "react";
 import { renderToReadableStream } from "react-dom/server.browser";
+import { withMetaSlot } from "./ssr-page-tree";
 
 // Mirrors `fulfilledThenable` in ssr-client-bundler.ts's CLIENT_RUNTIME_SOURCE:
 // a React-recognized fulfilled thenable so use() reads `.value` synchronously
@@ -238,3 +239,93 @@ describe("route-level loading.tsx hydration", () => {
     expect(errors.length).toBeGreaterThan(0);
   });
 });
+
+// Every page with metadata had different useId values on the server and in
+// the browser: the server put the metadata beside the page, the browser
+// hydrated the page alone. Radix menus, dialogs and form labels then
+// mismatched. Both sides now share withMetaSlot (ssr-page-tree.ts).
+describe("metadata slot keeps useId values stable", () => {
+  function Layout({ children }: { children?: any }) {
+    return React.createElement("main", { id: "layout" }, children);
+  }
+  function Control() {
+    const id = React.useId();
+    return React.createElement("button", { id: `menu-${id}`, "data-probe": "" }, "Menu");
+  }
+  function MenuPage() {
+    return React.createElement("div", { id: "page" }, React.createElement(Control));
+  }
+  const meta = React.createElement("meta", { name: "description", content: "A page" });
+
+  async function render(tree: any): Promise<string> {
+    const stream = await renderToReadableStream(tree);
+    await (stream as any).allReady;
+    const reader = stream.getReader();
+    let html = "";
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      html += dec.decode(value);
+    }
+    return html;
+  }
+
+  async function hydrate(serverTree: any, clientTree: any) {
+    const html = await render(serverTree);
+    const serverId = /id="(menu-[^"]+)"/.exec(html)?.[1];
+    const win = new Window({ url: "http://localhost/" });
+    const root = win.document.createElement("div");
+    root.insertAdjacentHTML("afterbegin", html);
+    win.document.body.appendChild(root);
+    registerDom(win);
+    const errors: string[] = [];
+    const origErr = console.error;
+    console.error = (...a: any[]) => {
+      errors.push(a.map(String).join(" "));
+    };
+    try {
+      const { hydrateRoot } = await import("react-dom/client");
+      hydrateRoot(root as any, clientTree, {
+        onRecoverableError: (e: any) => errors.push(String(e?.message ?? e)),
+      });
+      await new Promise((r) => setTimeout(r, 50));
+    } finally {
+      console.error = origErr;
+    }
+    return {
+      serverId,
+      errors: errors.filter((e) => /hydrat|did not match|mismatch/i.test(e)),
+    };
+  }
+
+  const e = React.createElement;
+
+  test("the server's slot with metadata and the browser's empty slot give the same ids", async () => {
+    // What the browser's ids are, rendered alone with the client shape.
+    const clientHtml = await render(e(Layout, null, withMetaSlot(e, React.Fragment, null, e(MenuPage))));
+    const clientId = /id="(menu-[^"]+)"/.exec(clientHtml)?.[1];
+    const { serverId, errors } = await hydrate(
+      e(Layout, null, withMetaSlot(e, React.Fragment, meta, e(MenuPage))),
+      e(Layout, null, withMetaSlot(e, React.Fragment, null, e(MenuPage))),
+    );
+    expect(serverId).toBeDefined();
+    expect(serverId).toBe(clientId);
+    expect(errors).toEqual([]);
+  });
+
+  test("a page without metadata has the same shape", async () => {
+    const { errors } = await hydrate(
+      e(Layout, null, withMetaSlot(e, React.Fragment, null, e(MenuPage))),
+      e(Layout, null, withMetaSlot(e, React.Fragment, null, e(MenuPage))),
+    );
+    expect(errors).toEqual([]);
+  });
+
+  test("hydrating the page without the slot mismatches (the bug)", async () => {
+    const { errors } = await hydrate(
+      e(Layout, null, e(React.Fragment, null, meta, e(MenuPage))),
+      e(Layout, null, e(MenuPage)),
+    );
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});

package/src/ssr-page-tree.ts

@@ -0,0 +1,21 @@
+// The shape of the tree around a route's page, shared by the server render
+// (ssr-runtime.ts) and the browser's hydration (the generated client runtime
+// imports this file as `./page-tree`).
+//
+// React derives `useId` values from the tree's shape, including how many
+// children each element has. The server renders the page's metadata (<title>,
+// <meta>, <link>, which React hoists into <head>) beside the page; the browser
+// never renders those tags. So both sides give the page a fragment with two
+// slots: on the server the first slot holds the metadata, in the browser it
+// holds null. React counts a null slot, so every id inside the page is the
+// same on both sides. Without the slot, every Radix menu, dialog and label id
+// on a page with metadata mismatched on hydration.
+//
+// No imports: the client bundler copies this file next to the runtime.
+
+type CreateElement = (type: any, props: any, ...children: any[]) => any;
+
+/** The page with its metadata slot. `meta` is null in the browser. */
+export function withMetaSlot(createElement: CreateElement, Fragment: any, meta: unknown, page: unknown): any {
+  return createElement(Fragment, null, meta ?? null, page);
+}

package/src/ssr-runtime.ts

@@ -7,6 +7,7 @@
 // the dispatch arm) so projects without SSR routes pay nothing — no
 // react-dom dependency requirement, no startup cost.
 
+import { withMetaSlot } from "./ssr-page-tree";
 import { moduleKey, serverBundle } from "./server-bundle";
 
 // Bun runtime global. This module runs under Bun but is type-checked by
@@ -2561,15 +2562,14 @@ async function tryRenderBoundary(
     );
     boundaryMeta = applyAutoIcons(rel, boundaryMeta);
     const boundaryMetaFragment = renderMetadata(React, boundaryMeta);
-    let tree = React.createElement(Comp, compProps);
-    if (boundaryMetaFragment) {
-      tree = React.createElement(
-        React.Fragment,
-        null,
-        boundaryMetaFragment,
-        tree,
-      );
-    }
+    // The same metadata slot a page gets: the browser hydrates a boundary
+    // with the page's tree shape (ssr-page-tree.ts).
+    let tree = withMetaSlot(
+      React.createElement,
+      React.Fragment,
+      boundaryMetaFragment,
+      React.createElement(Comp, compProps),
+    );
     tree = await buildLayoutTree(cwd, tree, boundaryLayouts, compProps, React);
     await renderBoundaryToClient(
       React,
@@ -3563,11 +3563,10 @@ export async function handleRenderRoute(
     // root: start with the page component as `tree`, then for each
     // layout (innermost first) wrap it as the new tree. Result is
     // the outermost layout containing all nested layouts down to
-    // the page. The metadata fragment is the FIRST child so React hoists
-    // its <title>/<meta> into the <head> a layout renders.
-    let tree: any = metaFragment
-      ? React.createElement(React.Fragment, null, metaFragment, pageLeaf)
-      : pageLeaf;
+    // the page. The metadata is the FIRST child so React hoists its
+    // <title>/<meta> into the <head> a layout renders; the browser renders
+    // the same slot empty (ssr-page-tree.ts), so useId values match.
+    let tree: any = withMetaSlot(React.createElement, React.Fragment, metaFragment, pageLeaf);
     tree = await buildLayoutTree(cwd, tree, msg.layouts, props, React);
     const element = tree;
     // Tracks whether the HTTP head (response_start) has actually gone out. A

package/src/types.ts

@@ -1044,6 +1044,30 @@ export type RequireMember = (
  * });
  * ```
  */
+/**
+ * `ctx.crdt` (actions only): read and change a row's live CRDT document, the
+ * one editors bind to with `@pylonsync/loro`. Bytes are Loro's own formats.
+ * `@pylonsync/loro/server` wraps this in a `LoroDoc` (`openLiveDoc`).
+ *
+ * Each `apply` is its own write: it merges, then reaches everyone editing at
+ * once, so it cannot roll back with a mutation (queries and mutations get
+ * CRDT_ACTIONS_ONLY). Policies follow the `ctx.db` rule: they apply under
+ * strict function policies (`PYLON_STRICT_FN_POLICIES=1`), except through
+ * `ctx.crdt.unsafe`. Without strict policies, check access yourself.
+ */
+export interface Crdt {
+  /** The row's whole document, or null when the row does not exist (or, under
+   *  strict policies, the caller may not read it). */
+  snapshot(entity: string, id: string): Promise<Uint8Array | null>;
+  /** The changes since `version` (a Loro version vector, `doc.oplogVersion().encode()`),
+   *  or null as for {@link Crdt.snapshot}. */
+  since(entity: string, id: string, version: Uint8Array): Promise<Uint8Array | null>;
+  /** Merge a Loro update into the row and broadcast it. */
+  apply(entity: string, id: string, update: Uint8Array): Promise<void>;
+  /** The same operations with server trust even under strict policies. */
+  unsafe: Omit<Crdt, "unsafe">;
+}
+
 export interface Files {
   /**
    * Mint a signed download path for a file id. `ttlSecs` defaults to 300
@@ -1542,6 +1566,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   env: Record<string, string>;
   /** Signed file-download URLs — see {@link Files}. */
   files: ActionFiles;
+  /** A row's live CRDT document, as Loro bytes — see {@link Crdt}. */
+  crdt: Crdt;
   /** Shard tickets, reads, and start/stop — see {@link Shards}. */
   shards: Shards;
   /** Run a registered query within its own read transaction. */