@caelo-cms/shared 0.10.62 → 0.10.65

package/src/build-page.test.ts

@@ -60,6 +60,31 @@ describe("buildPageInputSchema — page target modes", () => {
     expect(issue.message).toContain("title");
   });
 
+  it("create mode takes the new page's meta description (trimmed), so it is Stage-ready from this call", () => {
+    const r = buildPageInputSchema.safeParse({
+      page: { slug: "pricing", title: "Pricing", metaDescription: "  Plans and prices.  " },
+      modules: [mintModule],
+    });
+    expect(r.success).toBe(true);
+    if (!r.success) return;
+    expect(r.data.page.metaDescription).toBe("Plans and prices.");
+  });
+
+  it("rejects a blank meta description and one given with pageId (fill-once is autofill_page_seo's job there)", () => {
+    const blank = buildPageInputSchema.safeParse({
+      page: { slug: "pricing", title: "Pricing", metaDescription: "   " },
+      modules: [],
+    });
+    expect(blank.success).toBe(false);
+    const existing = buildPageInputSchema.safeParse({
+      page: { pageId: UUID, metaDescription: "Plans and prices." },
+      modules: [],
+    });
+    expect(existing.success).toBe(false);
+    if (existing.success) return;
+    expect(existing.error.issues[0]!.message).toContain("autofill_page_seo");
+  });
+
   it("rejects a page target with neither pageId nor slug+title", () => {
     const r = buildPageInputSchema.safeParse({
       page: { slug: "pricing" },
@@ -132,6 +157,36 @@ describe("buildPageInputSchema — module entry modes name the failing index", (
     });
     expect(r.success).toBe(false);
   });
+
+  // e2e-livedit detected bug: the AI carried add_module's `position` into
+  // build_page entries and the whole call was refused as an unknown key.
+  it("accepts add_module's `position` grammar per placed entry", () => {
+    for (const position of ["top", "bottom", 0, 3, "2"]) {
+      const r = buildPageInputSchema.safeParse({
+        page: { pageId: UUID },
+        modules: [{ ...mintModule, position }],
+      });
+      expect(r.success).toBe(true);
+      if (r.success) {
+        expect(r.data.modules[0]?.position).toEqual(position === "2" ? 2 : position);
+      }
+    }
+    const bad = buildPageInputSchema.safeParse({
+      page: { pageId: UUID },
+      modules: [{ ...mintModule, position: "middle" }],
+    });
+    expect(bad.success).toBe(false);
+  });
+
+  it("rejects `position` on a detached (unplaced) entry", () => {
+    const { blockName: _b, ...detached } = mintModule;
+    const r = buildPageInputSchema.safeParse({
+      page: { pageId: UUID },
+      modules: [{ ...detached, ref: "card", position: "top" }],
+    });
+    expect(r.success).toBe(false);
+    if (!r.success) expect(r.error.issues[0]?.message).toContain("DETACHED");
+  });
 });
 
 describe("buildPageContentSchema — the three sources", () => {

package/src/build-page.ts

@@ -20,6 +20,7 @@
  */
 
 import { z } from "zod";
+import { positionInputSchema } from "./ai-tools.js";
 import {
   contentInstanceCreateSchema,
   MODULE_CSS_MAX,
@@ -31,6 +32,7 @@ import {
   slugSchema,
   syncModeSchema,
 } from "./content.js";
+import { SEO_DESCRIPTION_HARD_MAX } from "./seo.js";
 
 /** Content values keyed by the module's declared field names. */
 const contentValuesSchema = z.record(z.string(), z.unknown());
@@ -106,11 +108,25 @@ export const buildPageModuleSchema = z
      * module / module-list field value. A detached entry requires `ref`.
      */
     blockName: slugSchema.optional(),
+    /**
+     * Where in its block the entry lands — the same grammar as
+     * add_module's `position` ("top", "bottom", or a 0-based index).
+     * Omitted = "bottom": entries append in array order, so a new page
+     * needs none. Entries are inserted in array order, each into the
+     * block as it stands after the entries before it; an index past the
+     * end appends. Meaningless (and rejected) on a detached entry.
+     *
+     * Accepted because the AI carries `position` over from add_module,
+     * and on an existing page "put this at the top" is a real intent a
+     * pure append cannot express (e2e-livedit detected bugs).
+     */
+    position: positionInputSchema.optional(),
     /**
      * Local handle other entries in the SAME call can reference: a
-     * module/module-list field value of `{"$ref": "<ref>"}` resolves to
-     * this entry's `{moduleId, contentInstanceId}`. Entries resolve in
-     * array order, so referenced entries must come FIRST.
+     * module/module-list field value of `{"$ref": "<ref>"}` (or a
+     * `moduleId: {"$ref"}`) resolves to this entry's `{moduleId,
+     * contentInstanceId}`. Array position does not matter: the op mints
+     * referenced entries before the entries that embed them.
      */
     ref: z
       .string()
@@ -149,6 +165,14 @@ export const buildPageModuleSchema = z
   })
   .strict()
   .superRefine((entry, ctx) => {
+    if (entry.blockName === undefined && entry.position !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "`position` places an entry inside its block, but this entry has no `blockName` (a DETACHED, " +
+          "nested-only module is not placed). Drop `position`, or pass `blockName` to place it.",
+      });
+    }
     if (entry.blockName === undefined && entry.ref === undefined) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
@@ -211,6 +235,15 @@ export const buildPageTargetSchema = z
      * Compatible with either target shape (create OR existing pageId).
      */
     importPageId: z.string().uuid().optional(),
+    /**
+     * The new page's meta description, written in the same transaction
+     * with the fill-once semantics of `pages_seo.autofill` (CLAUDE.md §2).
+     * A staging build refuses a published page without one, so the page
+     * is Stage-ready from the call that creates it. Create mode (or an
+     * importPageId rebuild) only — an existing page gets its first
+     * description from `autofill_page_seo`.
+     */
+    metaDescription: z.string().trim().min(1).max(SEO_DESCRIPTION_HARD_MAX).optional(),
   })
   .strict()
   .superRefine((page, ctx) => {
@@ -218,6 +251,13 @@ export const buildPageTargetSchema = z
       ["slug", "title", "name", "templateId", "status", "parentPageId"] as const
     ).filter((k) => page[k] !== undefined);
     if (page.pageId !== undefined) {
+      if (page.metaDescription !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "page.metaDescription is written only for a page this call CREATES — drop it with pageId; an existing page without a description gets one via autofill_page_seo.",
+        });
+      }
       if (createKeys.length > 0) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
@@ -250,8 +290,8 @@ export const buildPageInputSchema = z
   })
   .strict()
   .superRefine((input, ctx) => {
-    // `ref` handles must be unique — a duplicate would silently shadow
-    // the earlier entry when a later {"$ref"} resolves.
+    // `ref` handles must be unique — a duplicate would make a {"$ref"}
+    // ambiguous.
     const seen = new Set<string>();
     for (const [i, entry] of input.modules.entries()) {
       if (entry.ref === undefined) continue;

package/src/google-oauth.ts

@@ -25,3 +25,13 @@ export const GOOGLE_OAUTH_CLIENT_ID = /^[0-9]+-[a-z0-9]+\.apps\.googleuserconten
 export function iapRedirectUri(clientId: string): string {
   return `https://iap.googleapis.com/v1/oauth/clientIds/${clientId}:handleRedirect`;
 }
+
+/**
+ * #967 — the Google console page of one OAuth client, where its authorized
+ * redirect URIs and client secrets are edited. Shared so the setup page can
+ * link it as the Owner types the client ID, and the preflight can name it
+ * in every fix.
+ */
+export function oauthClientConsoleUrl(projectId: string, clientId: string): string {
+  return `https://console.cloud.google.com/auth/clients/${encodeURIComponent(clientId)}?project=${encodeURIComponent(projectId)}`;
+}

package/src/index.ts

@@ -43,6 +43,7 @@ export {
   type StructuredLogEntry,
 } from "./logger.js";
 export * from "./markup-structure.js";
+export * from "./mcp-access.js";
 export * from "./media.js";
 export * from "./nested-module-render.js";
 export * from "./page-log.js";
@@ -64,6 +65,7 @@ export * from "./release-manifest.js";
 export * from "./responsive-images.js";
 export * from "./result.js";
 export * from "./safe-keys.js";
+export * from "./screenshot-capture.js";
 export * from "./seo.js";
 export * from "./skills.js";
 export * from "./snapshots.js";

package/src/link-canonicalise.test.ts

@@ -180,6 +180,35 @@ describe("canonicaliseUrl", () => {
     expect(strict.issues.map((i) => i.kind)).toEqual(["unknown-page-path"]);
   });
 
+  // e2e-livedit detected bugs: the site header (brand link "/", nav
+  // "/#features") is built before the homepage exists and was refused.
+  it("keeps the site root literal while no page serves it, never an issue", () => {
+    const noRoot: LinkTargetLookup = {
+      ...lookup,
+      pageIdForPath: (p) => (p === "/" ? null : lookup.pageIdForPath(p)),
+    };
+    const r = linkCanonicaliseRun(noRoot);
+    expect(canonicaliseUrl("/", r, "html")).toBe("/");
+    expect(canonicaliseUrl("/#features", r, "fields.nav.default[1].href")).toBe("/#features");
+    expect(canonicaliseUrl("https://example.com/?ref=nav", r, "x")).toBe(
+      "https://example.com/?ref=nav",
+    );
+    expect(canonicaliseHtmlLinks('<a href="/">Home</a><a href="/#features">F</a>', r, "html")).toBe(
+      '<a href="/">Home</a><a href="/#features">F</a>',
+    );
+    expect(r.issues).toEqual([]);
+    // A suffix the stored grammar cannot carry is still refused, and any
+    // other unknown path still is an issue: only the root is guaranteed.
+    canonicaliseUrl('/#bad"anchor', r, "y");
+    canonicaliseUrl("/get-started", r, "z");
+    expect(r.issues.map((i) => [i.kind, i.value])).toEqual([
+      ["unsupported-link-form", '/#bad"anchor'],
+      ["unknown-page-path", "/get-started"],
+    ]);
+    // Once the homepage exists the root becomes its reference as usual.
+    expect(canonicaliseUrl("/#features", run(), "x")).toBe(`caelo:page/${HOME}#features`);
+  });
+
   it("reports a malformed reference instead of passing it through", () => {
     const r = run();
     const bad = [

package/src/link-canonicalise.ts

@@ -39,6 +39,12 @@
  *     that run not built yet is kept and listed in `run.pending`; the
  *     caller records it and the run's finalisation converts it (or
  *     reports it) once the run's pages exist.
+ *   - the site root: `/` (with an optional `#anchor` / `?query`) while no
+ *     page serves it yet is kept literal, not refused. Every site has a
+ *     root page by the time it ships — the staged build refuses one
+ *     without — so the link cannot dangle, and site chrome (the brand
+ *     link, `/#features` nav items) is routinely written before the
+ *     homepage. Once the homepage exists, `/` canonicalises as usual.
  */
 
 import {
@@ -322,6 +328,16 @@ export function canonicaliseUrl(
     run.pending.push({ value: v, path: normalised, where });
     return value;
   }
+  if (pageId === null && normalised === "/") {
+    // The site root before its page exists (a header built ahead of the
+    // homepage). It cannot dangle: the staged build refuses a site with
+    // no page at "/" (CLAUDE.md §2: loud there, not here). Kept literal;
+    // the next save after the homepage exists stores its reference.
+    if ((query !== null && !QUERY_OK.test(query)) || (anchor !== null && !ANCHOR_OK.test(anchor))) {
+      if (!run.grandfathered.has(v)) issue(run, "unsupported-link-form", v, where);
+    }
+    return value;
+  }
   if (pageId === null) {
     const lastSegment = path.slice(path.lastIndexOf("/") + 1);
     const isFile = FILE_EXT_RE.test(lastSegment);
@@ -592,7 +608,8 @@ export function describeLinkIssues(issues: readonly LinkCanonicaliseIssue[]): st
     `Internal link check failed — ${lines.join("; ")}${more}. ` +
     "Internal links must point at an existing page or media asset. Next step: use the exact path " +
     "of an existing page (list_pages shows every page's path) or an existing media URL (find_media); " +
-    "if the page does not exist yet, create it first (or leave the link out and add it once the page " +
-    "exists). For a link to another site, write the full https:// URL."
+    "if the page does not exist yet, create it first (build_page with `modules: []` makes an empty page " +
+    "shell) or leave the link out and add it once the page exists. The site root `/` is always valid. " +
+    "For a link to another site, write the full https:// URL."
   );
 }

package/src/mcp-access.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #968 — the facts about Caelo's MCP access paths that the admin UI,
+ * the remote resolver's error messages and the docs must agree on: which
+ * surface needs which permission, what each surface is for in plain words,
+ * and how a client app's key reads to a person. Client-safe (no server
+ * imports): Settings → MCP renders it, admin-core words refusals with it.
+ * The concept is docs/dev/mcp-access.md.
+ */
+
+/** A remote MCP surface: talk to the site's AI, or drive its admin tools. */
+export type McpSurfaceName = "chat" | "admin";
+
+/**
+ * The permission each remote surface needs. Chat writes content through
+ * Caelo's own AI; admin exposes every tool the AI has, so it needs what an
+ * admin-scoped MCP token needs. Owners have both.
+ */
+export const MCP_SURFACE_PERMISSION: Readonly<
+  Record<McpSurfaceName, "content.write" | "settings.write">
+> = {
+  chat: "content.write",
+  admin: "settings.write",
+};
+
+/** What a surface does and who may use it, in the words the UI and errors use. */
+export const MCP_SURFACE_COPY: Readonly<
+  Record<McpSurfaceName, { readonly title: string; readonly does: string; readonly who: string }>
+> = {
+  chat: {
+    title: "Chat with this site's AI",
+    does: "The AI tool sends requests to Caelo's own AI, which builds and edits the site like the Live Edit chat does.",
+    who: "Everyone who may edit content (content.write).",
+  },
+  admin: {
+    title: "Full admin access",
+    does: "The AI tool gets every tool Caelo's AI has and does the work itself, on a preview branch. Approval-gated actions still wait for an Owner's click.",
+    who: "Owners and roles that may change settings (settings.write).",
+  },
+};
+
+/**
+ * A suggested connector name, so two connectors to one site in the same AI
+ * tool are told apart: "Caelo viu.one (Chat)", "Caelo viu.one (Admin)".
+ */
+export function mcpConnectorName(siteHost: string, surface: McpSurfaceName): string {
+  return `Caelo ${siteHost} (${surface === "admin" ? "Admin" : "Chat"})`;
+}
+
+/**
+ * How a client app's key (the gateway's `mcpClientKey`) reads to a person.
+ * Known CIMD documents get their product name; a DCR key shows the name the
+ * app registered with (unverified — anyone can register any name).
+ */
+export function describeMcpClient(clientKey: string | null): string {
+  if (clientKey === null) return "An app from before per-app connections";
+  if (clientKey.startsWith("dcr:sha256:") || clientKey.startsWith("sha256:")) {
+    return "An app that did not give its name";
+  }
+  if (clientKey.startsWith("dcr:")) return clientKey.slice(4);
+  let url: URL;
+  try {
+    url = new URL(clientKey);
+  } catch {
+    return clientKey;
+  }
+  if (url.hostname === "chatgpt.com") return "ChatGPT";
+  if (url.hostname === "claude.ai") {
+    return url.pathname.includes("claude-code") ? "Claude Code" : "Claude";
+  }
+  return url.hostname;
+}

package/src/preview-compose.test.ts

@@ -818,4 +818,31 @@ describe("theme favicon in <head>", () => {
     expect(out.html).toContain('href="/x&quot;&gt;&lt;script&gt;"');
     expect(out.html).not.toContain('/x"><script>');
   });
+
+  it("base64-encodes the page-wide module script bundle when JS contains </script or <!--", () => {
+    const mod = {
+      ...blankModule,
+      html: "<p>x</p>",
+      js: 'const tpl = "</script><img src=x onerror=alert(1)>";',
+    };
+    const preview = composePagePreview({
+      templateHtml: `<html><head></head><body><caelo-slot name="content">_</caelo-slot></body></html>`,
+      templateCss: "",
+      blocks: [{ blockName: "content", modules: [mod] }],
+    });
+    expect(preview.html).not.toContain("<img src=x onerror=alert(1)>");
+    expect(preview.html).toContain('src="data:text/javascript;base64,');
+
+    const withLayout = composePageWithLayout({
+      templateHtml,
+      templateCss: "",
+      blocks: [{ blockName: "content", modules: [mod] }],
+      layoutHtml,
+      layoutCss: "",
+      layoutBlocks: [],
+      layoutSlug: "test",
+    });
+    expect(withLayout.html).not.toContain("<img src=x onerror=alert(1)>");
+    expect(withLayout.html).toContain('src="data:text/javascript;base64,');
+  });
 });

package/src/preview-compose.ts

@@ -369,7 +369,10 @@ export function composePagePreview(input: ComposeInput): ComposeOutput {
     html = injectBefore(html, HEAD_CLOSE_RE, styleTag);
   }
   if (allJs.length > 0) {
-    const scriptTag = `<script defer data-source="modules">\n${allJs.join("\n")}\n</script>`;
+    const joinedJs = allJs.join("\n");
+    const scriptTag = scriptNeedsEncoding(joinedJs)
+      ? `<script defer data-source="modules" src="data:text/javascript;base64,${utf8ToBase64(joinedJs)}"></script>`
+      : `<script defer data-source="modules">\n${joinedJs}\n</script>`;
     html = injectBefore(html, BODY_CLOSE_RE, scriptTag);
   }
 
@@ -958,11 +961,11 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
     );
   }
   if (jsParts.length > 0) {
-    html = injectBefore(
-      html,
-      BODY_CLOSE_RE,
-      `<script defer data-source="modules">\n${jsParts.join("\n")}\n</script>`,
-    );
+    const joinedJs = jsParts.join("\n");
+    const scriptTag = scriptNeedsEncoding(joinedJs)
+      ? `<script defer data-source="modules" src="data:text/javascript;base64,${utf8ToBase64(joinedJs)}"></script>`
+      : `<script defer data-source="modules">\n${joinedJs}\n</script>`;
+    html = injectBefore(html, BODY_CLOSE_RE, scriptTag);
   }
 
   // De-duplicate slot accounting across both passes — the template's

package/src/screenshot-capture.ts

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The operator-browser `screenshot_page` capture (html2canvas in the chat
+ * panel) and the tool handler that receives its result agree on one failure
+ * kind: the capture target exists but has no rendered size.
+ *
+ * Why it needs its own kind: the browser capture renders the preview WITHOUT
+ * the page's scripts (#946 — the frame shares the admin origin, so scripts
+ * must not run with the operator's session). An element a script reveals —
+ * the consent banner is `display:none` until the consent runtime adds a class
+ * to `<html>` — is therefore 0×0 there, html2canvas paints a 0×0 canvas and
+ * `canvas.toBlob` answers null (e2e-livedit 2026-10, "canvas.toBlob returned
+ * null" on `[data-consent-banner]`). That is a limit of this backend, not of
+ * the page: the server-side renderer runs real Chromium with scripts and can
+ * capture the element, so the handler routes such a failure there.
+ */
+
+/** Prefix of a browser-capture failure whose target has no rendered size. */
+export const SCREENSHOT_TARGET_NOT_RENDERED = "capture target is not rendered";
+
+/** A rendered box, as `getBoundingClientRect()` / a canvas reports it. */
+export interface ScreenshotBox {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The failure message when the capture target (or the canvas painted from
+ * it) has no area, else null.
+ *
+ * @param target - what is being captured: the selector, or "page body".
+ */
+export function screenshotTargetNotRendered(target: string, box: ScreenshotBox): string | null {
+  if (box.width > 0 && box.height > 0) return null;
+  return (
+    `${SCREENSHOT_TARGET_NOT_RENDERED}: ${target} is ${Math.round(box.width)}×${Math.round(box.height)}px ` +
+    "in the operator-browser capture, which runs without the page's scripts — an element a script " +
+    "reveals (display:none until then) has no size there"
+  );
+}
+
+/** True when a browser-capture failure message is the not-rendered kind. */
+export function isScreenshotTargetNotRendered(message: string): boolean {
+  return message.includes(SCREENSHOT_TARGET_NOT_RENDERED);
+}

package/src/seo.test.ts

@@ -199,6 +199,15 @@ describe("injectSeoIntoHead", () => {
     const out = injectSeoIntoHead(html, headBlock);
     expect(out).toContain(headBlock);
   });
+
+  it("matches uppercase </HEAD> and preserves <svg><title> inside <body>", () => {
+    const html =
+      "<html><HEAD><title>LayoutTitle</title></HEAD><body><svg><title>IconTitle</title></svg></body></html>";
+    const out = injectSeoIntoHead(html, "<title>PageTitle</title>");
+    expect(out).not.toContain("LayoutTitle");
+    expect(out).toContain("<title>PageTitle</title>\n</HEAD>");
+    expect(out).toContain("<svg><title>IconTitle</title></svg>");
+  });
 });
 
 describe("schemas", () => {

package/src/seo.ts

@@ -340,12 +340,16 @@ export function renderSeoHead(input: SeoMetaInput): string {
  * the layout HTML.
  */
 export function injectSeoIntoHead(html: string, headBlock: string): string {
-  // Strip a layout-supplied <title> if present; we'll re-emit it in
-  // the headBlock at the right position.
-  const titleStripped = html.replace(/<title\b[^>]*>[\s\S]*?<\/title>/i, "");
-  if (titleStripped.includes("</head>")) {
-    return titleStripped.replace("</head>", () => `${headBlock}\n</head>`);
+  const headCloseMatch = /<\/head\s*>/i.exec(html);
+  if (headCloseMatch) {
+    const headEnd = headCloseMatch.index;
+    // Strip a layout-supplied <title> inside <head> only (never an SVG
+    // <title> in <body>); we re-emit the page title in headBlock.
+    const beforeClose = html.slice(0, headEnd).replace(/<title\b[^>]*>[\s\S]*?<\/title>/i, "");
+    const afterClose = html.slice(headEnd);
+    return `${beforeClose}${headBlock}\n${afterClose}`;
   }
   // No closing head tag — prepend the block to the document.
+  const titleStripped = html.replace(/<title\b[^>]*>[\s\S]*?<\/title>/i, "");
   return `${headBlock}\n${titleStripped}`;
 }

package/src/theme-importers/__tests__/proto-pollution.test.ts

@@ -9,7 +9,7 @@
 
 import { describe, expect, it } from "bun:test";
 import { isUnsafeKey } from "../../safe-keys.js";
-import { applyDtcgWrites } from "../../themes.js";
+import { applyDtcgWrites, removeDtcgPath } from "../../themes.js";
 import { importTailwind } from "../tailwind.js";
 
 describe("isUnsafeKey", () => {
@@ -51,4 +51,12 @@ describe("applyDtcgWrites / setLeafAtPath path guard (S5)", () => {
     const out = applyDtcgWrites({}, { "color.primary": "#fff" }, { "color.primary": "color" });
     expect(JSON.stringify(out)).toContain("primary");
   });
+
+  it("removeDtcgPath rejects __proto__/constructor/prototype and inherited keys", () => {
+    const doc = applyDtcgWrites({}, { "color.primary": "#fff" }, { "color.primary": "color" });
+    expect(removeDtcgPath(doc, "__proto__.toString").removed).toBe(false);
+    expect(removeDtcgPath(doc, "color.toString").removed).toBe(false);
+    expect(removeDtcgPath(doc, "constructor.prototype").removed).toBe(false);
+    expect(removeDtcgPath(doc, "color.primary").removed).toBe(true);
+  });
 });

package/src/theme-literal-binding.test.ts

@@ -62,9 +62,29 @@ describe("applyThemeLiteralBinding", () => {
     expect(r.suggestions).toEqual([{ literal: "6rem", varName: "--spacing-xl" }]);
   });
 
+  it("leaves a var() fallback literal as written (e2e-livedit: edit_content anchors missed)", () => {
+    // The AI authors `var(--x, #literal)`; rebinding the fallback stored
+    // CSS it never wrote and its next edit_content anchor did not match.
+    const css =
+      ".f{border-top:1px solid var(--color-foreground, #0f172a);background:var(--color-surface, #4f46e5);color:var( --color-x ,#0F172A)}";
+    const r = applyThemeLiteralBinding(css, TOKENS);
+    expect(r.css).toBe(css);
+    expect(r.rewrites).toEqual([]);
+  });
+
+  it("still binds a bare literal next to a var() reference", () => {
+    const r = applyThemeLiteralBinding(
+      ".f{color:var(--color-foreground);background:#4f46e5}",
+      TOKENS,
+    );
+    expect(r.css).toBe(".f{color:var(--color-foreground);background:var(--color-primary)}");
+  });
+
   it("formats a report and stays silent on no-ops", () => {
     const bound = applyThemeLiteralBinding(".a{color:#0F172A}", TOKENS);
     expect(formatBindingReport(bound)).toContain("#0F172A→var(--color-foreground)");
+    // The AI must know the stored css differs from what it sent.
+    expect(formatBindingReport(bound)).toContain("anchor later edit_content calls");
     const noop = applyThemeLiteralBinding(".a{color:#123456}", TOKENS);
     expect(formatBindingReport(noop)).toBeNull();
   });

package/src/theme-literal-binding.ts

@@ -26,6 +26,9 @@ import type { ThemeDocument } from "./themes.js";
 
 const COLOR_LITERAL_RE = /#[0-9a-fA-F]{3,8}\b|(?:oklch|rgba?|hsla?|lab|lch|hwb)\([^()]*\)/g;
 const DIMENSION_VALUE_RE = /^-?\d+(\.\d+)?(rem|em|px|%)$/;
+/** The text before a literal ends in an open `var(--name,` — the literal is
+ *  (the start of) that var's fallback. */
+const VAR_FALLBACK_BEFORE_RE = /var\(\s*--[\w-]+\s*,[^()]*$/i;
 
 export interface ThemeValueMap {
   /** normalized color value → var name (first-declared wins). */
@@ -107,11 +110,18 @@ export function applyThemeLiteralBinding(css: string, tokens: ThemeDocument): Li
   });
 
   out = out.replace(COLOR_LITERAL_RE, (literal, offset: number) => {
-    // Never rewrite inside an already-produced var(...) fallback or a
-    // remaining gradient (a gradient that did NOT match stays literal
-    // by decision — rebinding its stops would half-tokenise it).
+    // Never rewrite inside a remaining gradient (a gradient that did NOT
+    // match stays literal by decision — rebinding its stops would
+    // half-tokenise it) or a var() fallback. The author already referenced
+    // a var there; rebinding its fallback produced
+    // `var(--color-border, var(--color-border))` and
+    // `var(--color-surface, var(--color-primary-foreground))` — CSS the AI
+    // never wrote, so its next edit_content anchored on its own copy
+    // missed (5 "oldString not found" in e2e-livedit, 2026-10). An unknown
+    // var name in front of the fallback is reported by the unknown-var check.
     const before = out.slice(Math.max(0, offset - 64), offset);
     if (/gradient\([^()]*$/i.test(before)) return literal;
+    if (VAR_FALLBACK_BEFORE_RE.test(before)) return literal;
     const varName = map.colors.get(normalizeColor(literal));
     if (varName === undefined) return literal;
     const entry = counts.get(literal) ?? { to: varName, count: 0 };
@@ -145,7 +155,9 @@ export function formatBindingReport(result: LiteralBindingResult): string | null
     parts.push(
       `🔗 bound ${total} literal(s) to theme vars: ${result.rewrites
         .map((r) => `${r.from}→var(${r.to})${r.count > 1 ? `×${r.count}` : ""}`)
-        .join(", ")}`,
+        .join(
+          ", ",
+        )} — the STORED css has var(…) in place of those literals, so anchor later edit_content calls on that text, not on the css you sent`,
     );
   }
   if (result.suggestions.length > 0) {

package/src/theme-render-sanitize.test.ts

@@ -82,4 +82,13 @@ describe("renderThemeCss CSS-token sanitization (S6)", () => {
     } as unknown as ThemeDocument;
     expect(renderThemeCss(doc)).toContain("--color-grün:#0a0;");
   });
+
+  it("scrubs CSS declaration/block delimiters (; { }) from fontFamily and shadow strings", () => {
+    const css = renderThemeCss(
+      fontDoc("Inter; } body { background: url(https://evil.example/x) } :root { --x: 1"),
+    );
+    expect(css).toBe(
+      ":root{--font-body:Inter  body  background: url(https://evil.example/x)  :root  --x: 1;}",
+    );
+  });
 });

package/src/theme-render.ts

@@ -549,7 +549,8 @@ function sanitizeCssTokenValue(value: string): string {
     out = out
       .replace(/<\/style/gi, "")
       .replace(/<!--/g, "")
-      .replace(/--!?>/g, "");
+      .replace(/--!?>/g, "")
+      .replace(/[;{}]/g, "");
   } while (out !== prev);
   return out;
 }

package/src/themes.ts

@@ -882,19 +882,21 @@ export function removeDtcgPath(
   doc: ThemeDocument,
   path: string,
 ): { tokens: ThemeDocument; removed: boolean } {
-  const out: ThemeDocument = JSON.parse(JSON.stringify(doc));
   const parts = path.split(".");
+  if (parts.some(isUnsafeKey)) return { tokens: doc, removed: false };
+  const out: ThemeDocument = JSON.parse(JSON.stringify(doc));
   let cur: Record<string, unknown> = out;
   for (let i = 0; i < parts.length - 1; i++) {
     const k = parts[i];
     if (!k) continue;
+    if (!Object.hasOwn(cur, k)) return { tokens: doc, removed: false };
     const next = cur[k];
     if (!next || typeof next !== "object") return { tokens: doc, removed: false };
     cur = next as Record<string, unknown>;
   }
   const last = parts[parts.length - 1];
   if (!last) return { tokens: doc, removed: false };
-  if (!(last in cur)) return { tokens: doc, removed: false };
+  if (!Object.hasOwn(cur, last)) return { tokens: doc, removed: false };
   delete cur[last];
   return { tokens: out, removed: true };
 }