From 92c386731a38e334cd397282a197ab2b6e8afaba Mon Sep 17 00:00:00 2001
From: Madraka <8898640+Madraka@users.noreply.github.com>
Date: Fri, 23 Oct 2026 18:53:32 +0300
Subject: [PATCH] fix(renderer): ship theme scripts as files; render_page names
 broken surfaces and blocked scripts

Astro inlines component <script>s under assetsInlineLimit, and the Site
Worker's script-src 'self' blocked them on deployed sites. The cloudhal()
integration now keeps every script chunk a file, and cloudhal dev sends
SITE_CSP report-only so the console shows what a deploy would block.

render_page gains surface-broken (.ch-surface-problem notes and unknown
components in previews) and script-blocked (CSP violations kept by a
listener registered before the page's own scripts).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com>
---
 .changeset/theme-scripts-csp.md               | 11 +++
 ...021-design-md-and-the-agent-design-loop.md |  2 +
 packages/astro-renderer/package.json          |  5 ++
 packages/astro-renderer/src/csp-middleware.ts | 33 +++++++++
 packages/astro-renderer/src/csp.ts            | 15 ++++
 packages/astro-renderer/src/integration.ts    | 26 ++++---
 packages/astro-renderer/test/csp.test.ts      | 69 +++++++++++++++++++
 packages/cli/test/render-chrome.test.ts       | 59 ++++++++++++++++
 packages/mcp-server/src/render-tools.ts       |  4 +-
 packages/mcp-server/src/render.ts             |  7 +-
 packages/mcp-server/src/render/cdp.ts         |  3 +
 .../mcp-server/src/render/checks/index.ts     |  2 +
 .../mcp-server/src/render/checks/scripts.ts   | 45 ++++++++++++
 packages/mcp-server/src/render/types.ts       |  4 ++
 scripts/size-baseline.json                    |  2 +-
 15 files changed, 273 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/theme-scripts-csp.md
 create mode 100644 packages/astro-renderer/src/csp-middleware.ts
 create mode 100644 packages/astro-renderer/test/csp.test.ts
 create mode 100644 packages/mcp-server/src/render/checks/scripts.ts

diff --git a/.changeset/theme-scripts-csp.md b/.changeset/theme-scripts-csp.md
new file mode 100644
index 00000000..3194c544
--- /dev/null
+++ b/.changeset/theme-scripts-csp.md
@@ -0,0 +1,11 @@
+---
+"@cloudhal/astro-renderer": patch
+"@cloudhal/mcp-server": patch
+"@cloudhal/cli": patch
+---
+
+Theme scripts work on deployed sites, and `render_page` says when they would not.
+
+- The `cloudhal()` integration no longer lets Astro inline a component's `<script>` (under 4 KB) into the page, where the Site Worker's `script-src 'self'` blocked it: script chunks always ship as files (`build.assetsInlineLimit`), other assets keep the project's own limit. A theme that set `vite.build.assetsInlineLimit` itself for this can drop it.
+- `cloudhal dev` sends the Site Worker's policy as `Content-Security-Policy-Report-Only` on pages without their own, so the browser console shows what a deploy would block without breaking Vite's dev client.
+- `render_page` and `cloudhal render` gain two checks: `surface-broken` (a body ```` ```surface ```` fence the preview cannot draw, or a component with an unknown block type or props that do not fit, named with the problem) and `script-blocked` (a script the page's CSP refused, inline or by URL; under `cloudhal dev`'s report-only policy, what a deploy would block).
diff --git a/docs/rfcs/0021-design-md-and-the-agent-design-loop.md b/docs/rfcs/0021-design-md-and-the-agent-design-loop.md
index 9b94ac51..5d023a39 100644
--- a/docs/rfcs/0021-design-md-and-the-agent-design-loop.md
+++ b/docs/rfcs/0021-design-md-and-the-agent-design-loop.md
@@ -174,6 +174,8 @@ The site's Markdown reaches agents as **owner-written data**, between `<site-des
 | `empty-section` | A `[data-section-id]` renders under 8 px high |
 | `tap-target` | At 390 px, a link or button is smaller than 24×24 px (WCAG 2.5.8) |
 | `long-line` | Body text lines are longer than 90 characters at 1440 px |
+| `surface-broken` | A body ```` ```surface ```` fence the preview cannot draw, or a component in one with an unknown block type or props that do not fit (added later) |
+| `script-blocked` | The page's Content-Security-Policy refused a script, an inline `<script>` under the Site Worker's `script-src 'self'` say; `cloudhal dev` sends that policy report-only, so the check names what a deploy would block (added later) |
 
 **Runtimes:**
 - **Cloudflare.**
diff --git a/packages/astro-renderer/package.json b/packages/astro-renderer/package.json
index 6d71a4dd..69838075 100644
--- a/packages/astro-renderer/package.json
+++ b/packages/astro-renderer/package.json
@@ -50,6 +50,7 @@
     "./comments": "./src/comments-view.ts",
     "./comments-middleware": "./src/comments-middleware.ts",
     "./embed-middleware": "./src/embed-middleware.ts",
+    "./csp-middleware": "./src/csp-middleware.ts",
     "./embeds": "./src/embed-client.ts",
     "./theme-settings": "./src/theme-settings.ts",
     "./kit": "./src/kit.ts",
@@ -244,6 +245,10 @@
         "types": "./dist/src/embed-middleware.d.ts",
         "default": "./dist/src/embed-middleware.js"
       },
+      "./csp-middleware": {
+        "types": "./dist/src/csp-middleware.d.ts",
+        "default": "./dist/src/csp-middleware.js"
+      },
       "./embeds": {
         "types": "./dist/src/embed-client.d.ts",
         "default": "./dist/src/embed-client.js"
diff --git a/packages/astro-renderer/src/csp-middleware.ts b/packages/astro-renderer/src/csp-middleware.ts
new file mode 100644
index 00000000..a224eae1
--- /dev/null
+++ b/packages/astro-renderer/src/csp-middleware.ts
@@ -0,0 +1,33 @@
+/**
+ * `cloudhal dev` sends the deployed site's policy as `Content-Security-Policy-Report-Only` on
+ * HTML pages that set none of their own: the browser (and `render_page`) reports what the Site
+ * Worker's `SITE_CSP` would block, an inline theme script say, without breaking Vite's dev client.
+ */
+import { SITE_CSP } from "./csp.ts";
+
+interface MiddlewareContext {
+  request: Request;
+}
+
+export async function onRequest(
+  _context: MiddlewareContext,
+  next: () => Promise<Response>,
+): Promise<Response> {
+  const response = await next();
+  if (!(response.headers.get("content-type") ?? "").includes("text/html")) return response;
+  if (response.headers.has("content-security-policy")) return response;
+  if (response.headers.has("content-security-policy-report-only")) return response;
+  try {
+    response.headers.set("content-security-policy-report-only", SITE_CSP);
+    return response;
+  } catch {
+    // Immutable headers (a fetched response): copy them.
+    const headers = new Headers(response.headers);
+    headers.set("content-security-policy-report-only", SITE_CSP);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+}
diff --git a/packages/astro-renderer/src/csp.ts b/packages/astro-renderer/src/csp.ts
index 536997a6..b39a86a2 100644
--- a/packages/astro-renderer/src/csp.ts
+++ b/packages/astro-renderer/src/csp.ts
@@ -26,3 +26,18 @@ export function turnstileCsp(): string {
     `frame-src ${TURNSTILE_ORIGIN}; object-src 'none'`,
   );
 }
+
+/**
+ * Vite's `build.assetsInlineLimit` for a site build: never inline a script chunk. Astro inlines a
+ * component's `<script>` under the limit (4 KB by default) into the page, where `SITE_CSP`'s
+ * `script-src 'self'` blocks it on the deployed site. Other assets keep the project's own limit.
+ */
+export function scriptsNotInlined<C extends Uint8Array>(
+  limit: number | ((file: string, content: C) => boolean | undefined) | undefined,
+): (file: string, content: C) => boolean | undefined {
+  return (file, content) => {
+    if (/\.[cm]?js$/.test(file)) return false;
+    if (typeof limit === "function") return limit(file, content);
+    return limit === undefined ? undefined : content.byteLength < limit;
+  };
+}
diff --git a/packages/astro-renderer/src/integration.ts b/packages/astro-renderer/src/integration.ts
index d4189b5d..91aed255 100644
--- a/packages/astro-renderer/src/integration.ts
+++ b/packages/astro-renderer/src/integration.ts
@@ -1,6 +1,7 @@
 import type { AstroIntegration } from "astro";
 import type { AnalyticsClient } from "./analytics-client.ts";
 import type { CommentsClient } from "./comments-client.ts";
+import { scriptsNotInlined } from "./csp.ts";
 
 /** Options for the `cloudhal()` integration; made available to pages via `virtual:cloudhal/config`. */
 export interface CloudhalRendererConfig {
@@ -81,6 +82,17 @@ function configPlugin(modules: { config: unknown; client: unknown; comments: unk
   };
 }
 
+/**
+ * What only `cloudhal dev` runs as middleware (the Site Worker's entry and builds do these jobs):
+ * the analytics beacon (RFC-0006 §5.1); the click-to-load video player (RFC-0015 §4) and the
+ * interaction runtime (RFC-0020 §4), which builds write as files; and the Site Worker's CSP sent
+ * report-only, so the console shows what a deploy would block.
+ */
+const DEV_MIDDLEWARE = ["analytics-middleware", "embed-middleware", "csp-middleware"].map((m) => ({
+  entrypoint: `@cloudhal/astro-renderer/${m}`,
+  order: "pre" as const,
+}));
+
 export function cloudhal(config: CloudhalRendererConfig): AstroIntegration {
   let resolved: CloudhalRendererConfig = config;
   let client: AnalyticsClient | undefined;
@@ -115,15 +127,7 @@ export function cloudhal(config: CloudhalRendererConfig): AstroIntegration {
           client = await buildAnalyticsClient();
           resolved = { ...resolved, analyticsScript: client.script.path };
         }
-        if (!cloudflare && command === "dev")
-          addMiddleware({
-            entrypoint: "@cloudhal/astro-renderer/analytics-middleware",
-            order: "pre",
-          });
-        // The click-to-load video player (RFC-0015 §4) and the interaction runtime (RFC-0020 §4):
-        // served here in dev, written by builds.
-        if (!cloudflare && command === "dev")
-          addMiddleware({ entrypoint: "@cloudhal/astro-renderer/embed-middleware", order: "pre" });
+        if (!cloudflare && command === "dev") for (const m of DEV_MIDDLEWARE) addMiddleware(m);
         // Reader comments (RFC-0007 §8.2, §15.2), on the same targets: the Site Worker build ships
         // the module and its proof-of-work worker as hashed static assets and its entry answers the
         // endpoints; `cloudhal dev` serves both and answers them from a middleware on SQLite.
@@ -154,6 +158,10 @@ export function cloudhal(config: CloudhalRendererConfig): AstroIntegration {
                 comments: cloudflare ? null : (comments ?? null),
               }),
             ],
+            // `SITE_CSP` allows no inline script, so theme `<script>`s ship as files (any size).
+            build: {
+              assetsInlineLimit: scriptsNotInlined(astroConfig.vite?.build?.assetsInlineLimit),
+            },
             // Native module must stay external in Node SSR; workerd never loads it.
             ...(cloudflare ? {} : { ssr: { external: ["better-sqlite3"] } }),
           },
diff --git a/packages/astro-renderer/test/csp.test.ts b/packages/astro-renderer/test/csp.test.ts
new file mode 100644
index 00000000..f13e66f1
--- /dev/null
+++ b/packages/astro-renderer/test/csp.test.ts
@@ -0,0 +1,69 @@
+/**
+ * Theme scripts under `SITE_CSP` (`script-src 'self'`): the `cloudhal()` integration keeps Astro
+ * from inlining a component's `<script>` into the page, and `cloudhal dev` sends the policy
+ * report-only so a blocked script shows before a deploy.
+ */
+import { describe, expect, it } from "vitest";
+import { SITE_CSP, scriptsNotInlined } from "../src/csp.ts";
+import { onRequest } from "../src/csp-middleware.ts";
+import { cloudhal } from "../src/integration.ts";
+
+const bytes = (n: number) => new Uint8Array(n);
+
+describe("scriptsNotInlined", () => {
+  it("never inlines a script chunk; other assets keep the project's limit", () => {
+    const vite = scriptsNotInlined(undefined);
+    expect(vite("_astro/Hero.astro_astro_type_script_index_0_lang.Bx1.js", bytes(10))).toBe(false);
+    expect(vite("_astro/chunk.mjs", bytes(10))).toBe(false);
+    // Undefined: Vite's (and Astro's) own 4 KB default decides.
+    expect(vite("_astro/logo.svg", bytes(10))).toBeUndefined();
+    expect(scriptsNotInlined(100)("a.png", bytes(99))).toBe(true);
+    expect(scriptsNotInlined(100)("a.png", bytes(100))).toBe(false);
+    expect(scriptsNotInlined(100)("a.js", bytes(1))).toBe(false);
+    const own = scriptsNotInlined((file) => file.endsWith(".woff2"));
+    expect(own("a.woff2", bytes(1))).toBe(true);
+    expect(own("a.js", bytes(1))).toBe(false);
+  });
+
+  it("is what the integration gives Vite, on top of the project's own setting", async () => {
+    let vite: { build?: { assetsInlineLimit?: unknown } } = {};
+    const middleware: string[] = [];
+    const setup = cloudhal({ dataDir: "/tmp/data", siteId: "site_1" }).hooks["astro:config:setup"];
+    await setup?.({
+      updateConfig: (c: { vite: typeof vite }) => {
+        vite = c.vite;
+      },
+      addMiddleware: (m: { entrypoint: string }) => middleware.push(m.entrypoint),
+      config: { root: new URL("file:///site/"), vite: { build: { assetsInlineLimit: 0 } } },
+      command: "dev",
+    } as never);
+    const limit = vite.build?.assetsInlineLimit as (f: string, c: Uint8Array) => unknown;
+    expect(limit("_astro/Theme.js", bytes(1))).toBe(false);
+    expect(limit("_astro/icon.svg", bytes(1))).toBe(false);
+    expect(middleware).toContain("@cloudhal/astro-renderer/csp-middleware");
+  });
+});
+
+describe("cloudhal dev's report-only CSP", () => {
+  const run = (response: Response) =>
+    onRequest({ request: new Request("http://localhost/") }, async () => response);
+
+  it("reports what the Site Worker would block on HTML pages", async () => {
+    const page = await run(
+      new Response("<p>hi</p>", { headers: { "content-type": "text/html; charset=utf-8" } }),
+    );
+    expect(page.headers.get("content-security-policy-report-only")).toBe(SITE_CSP);
+    expect(page.headers.has("content-security-policy")).toBe(false);
+  });
+
+  it("leaves other responses and a page's own policy alone", async () => {
+    const js = await run(new Response("1", { headers: { "content-type": "text/javascript" } }));
+    expect(js.headers.has("content-security-policy-report-only")).toBe(false);
+    const own = await run(
+      new Response("<p>hi</p>", {
+        headers: { "content-type": "text/html", "content-security-policy": "default-src 'none'" },
+      }),
+    );
+    expect(own.headers.has("content-security-policy-report-only")).toBe(false);
+  });
+});
diff --git a/packages/cli/test/render-chrome.test.ts b/packages/cli/test/render-chrome.test.ts
index df3fabc3..33b5a3da 100644
--- a/packages/cli/test/render-chrome.test.ts
+++ b/packages/cli/test/render-chrome.test.ts
@@ -3,6 +3,8 @@
  * Skipped where this machine has no Chrome (set CHROME_PATH).
  */
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -273,6 +275,63 @@ header{position:sticky;top:0;height:80px;color:#fff;margin-bottom:-80px}header a
       expect.stringMatching(/p "Jumps" — "bare" has no metric-matched fallback/),
     ]);
   }, 90_000);
+
+  it("names a body surface that cannot be shown and a script the CSP blocked", async () => {
+    dir ??= await mkdtemp(path.join(os.tmpdir(), "cloudhal-render-test-"));
+    const render = async (name: string, html: string) => {
+      const file = path.join(dir, name);
+      await writeFile(file, html);
+      const r = await renderPage(
+        chromeRenderer(chrome as string, { idleMs: 10 }),
+        pathToFileURL(file).href,
+        { widths: [1440], fullPage: false, timeoutMs: 50_000 },
+      );
+      return (id: string) => r.checks.find((c) => c.id === id);
+    };
+    await writeFile(path.join(dir, "theme.js"), "document.body.dataset.ran = '1';");
+    // The Site Worker's policy, as a meta tag (a file:// page has no headers); the markup is what
+    // a preview draws for a broken ```surface fence and for an unknown component in one.
+    const head = (csp: string) =>
+      `<!doctype html><html lang="en"><head><meta name="viewport" content="width=device-width"><meta http-equiv="${csp}" content="script-src 'self'"></head><body><main><h1>S</h1>`;
+    const page = (csp: string) =>
+      `${head(csp)}<section data-section-id="sec_body"><div class="ch-surface-problem" role="note"><p><strong>This interactive block cannot be shown.</strong> Fix it in Markdown mode:</p><ul><li><code>srf_cards/components/c1 unknown component</code></li></ul></div>
+<div class="ch-block ch-block--missing" data-component-id="c2"><p>link-cards: unknown block type</p></div>
+<div class="ch-block ch-block--missing" data-component-id="c3"><p>lens-hero: shown by the theme on the site</p></div></section>
+<script>document.body.dataset.inline = "1";</script><script src="theme.js"></script></main></body></html>`;
+    const blocked = await render("csp.html", page("content-security-policy"));
+    expect(blocked("surface-broken")?.examples).toEqual([
+      expect.stringMatching(
+        /section sec_body div\.ch-surface-problem .* — srf_cards\/components\/c1 unknown component$/,
+      ),
+      expect.stringMatching(/component c2 .* — link-cards: unknown block type$/),
+    ]);
+    expect(blocked("script-blocked")?.examples).toEqual([
+      expect.stringMatching(
+        /^script .* — an inline script .*was blocked by script-src-elem; ship it as a file/,
+      ),
+    ]);
+    // `cloudhal dev` sends the policy report-only, a header only (a meta tag cannot): the same
+    // script, named as what a deploy blocks.
+    const server = createServer((_req, res) => {
+      res.setHeader("content-type", "text/html");
+      res.setHeader("content-security-policy-report-only", "script-src 'self'");
+      res.end(page("x-none").replace('<script src="theme.js"></script>', ""));
+    });
+    await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
+    try {
+      const { port } = server.address() as AddressInfo;
+      const r = await renderPage(
+        chromeRenderer(chrome as string, { idleMs: 10 }),
+        `http://127.0.0.1:${port}/`,
+        { widths: [1440], fullPage: false, timeoutMs: 50_000 },
+      );
+      expect(r.checks.find((c) => c.id === "script-blocked")?.examples).toEqual([
+        expect.stringMatching(/an inline script .*would be blocked on the site by script-src-elem/),
+      ]);
+    } finally {
+      server.close();
+    }
+  }, 90_000);
 });
 
 describe("localRender", () => {
diff --git a/packages/mcp-server/src/render-tools.ts b/packages/mcp-server/src/render-tools.ts
index f9c0bc7e..e910d1b6 100644
--- a/packages/mcp-server/src/render-tools.ts
+++ b/packages/mcp-server/src/render-tools.ts
@@ -73,6 +73,8 @@ const WHAT: Record<(typeof RENDER_CHECK_IDS)[number], string> = {
   "carousel-autoplay": "carousel autoplay",
   "image-fit": "image crops",
   "font-fallback": "font swap shift",
+  "surface-broken": "interactive blocks that cannot be shown",
+  "script-blocked": "scripts blocked by the CSP",
 };
 
 function summary(r: RenderPageResult): string {
@@ -130,7 +132,7 @@ export function renderTools(previewDoc: PreviewDoc): ToolDefinition[] {
       name: "render_page",
       title: "Render a page in a browser",
       description:
-        "Look at a page's draft as people will see it: renders it in a real browser at desktop (1440), tablet (768) and phone (390) widths and returns screenshots plus automatic checks (sideways scrolling, alt text, broken images, heading order, text contrast, empty sections, tap targets, line length, motion under reduced motion, layout shift) that name the section and component behind each problem. Use it after building or changing a page and before asking a person to publish; fix what it finds and render again. Read-only. Rate-limited (about 10 a minute); when no browser is available, use preview_page.",
+        "Look at a page's draft as people will see it: renders it in a real browser at desktop (1440), tablet (768) and phone (390) widths and returns screenshots plus automatic checks (sideways scrolling, alt text, broken images, heading order, text contrast, empty sections, tap targets, line length, motion under reduced motion, layout shift, interactive blocks that cannot be shown, scripts the site's Content-Security-Policy blocks) that name the section and component behind each problem. Use it after building or changing a page and before asking a person to publish; fix what it finds and render again. Read-only. Rate-limited (about 10 a minute); when no browser is available, use preview_page.",
       inputSchema: obj(
         {
           siteId: id,
diff --git a/packages/mcp-server/src/render.ts b/packages/mcp-server/src/render.ts
index 3938d007..cd944f9f 100644
--- a/packages/mcp-server/src/render.ts
+++ b/packages/mcp-server/src/render.ts
@@ -1,9 +1,10 @@
 /**
  * Sight for agents (RFC-0021 §4): renders a page in a real browser at a few widths and returns
  * screenshots plus automatic checks (overflow, alt text, broken images, heading order, contrast,
- * empty sections, tap targets, line length). The browser is a DevTools socket: local Chrome under
- * Node (`@cloudhal/cli`), Cloudflare Browser Rendering on Workers (`@cloudhal/cloudflare`). One
- * small DevTools client serves both, so there is no browser library to bundle.
+ * empty sections, tap targets, line length, broken surfaces, blocked scripts, …). The browser is a
+ * DevTools socket: local Chrome under Node (`@cloudhal/cli`), Cloudflare Browser Rendering on
+ * Workers (`@cloudhal/cloudflare`). One small DevTools client serves both, so there is no browser
+ * library to bundle.
  *
  * Worker-safe: no Node imports.
  */
diff --git a/packages/mcp-server/src/render/cdp.ts b/packages/mcp-server/src/render/cdp.ts
index 30e2d9c1..ee324492 100644
--- a/packages/mcp-server/src/render/cdp.ts
+++ b/packages/mcp-server/src/render/cdp.ts
@@ -1,4 +1,5 @@
 /** A minimal DevTools client over a browser-level socket (flat sessions), and base64 helpers. */
+import { CSP_LISTENER } from "./checks/scripts.ts";
 import { type CdpSocket, RenderError, type RenderSession } from "./types.ts";
 
 /**
@@ -123,6 +124,8 @@ export async function cdpSession(
           },
         ],
       });
+      // Before the page's own scripts: keep the CSP violations it raises (`script-blocked`).
+      await s("Page.addScriptToEvaluateOnNewDocument", { source: CSP_LISTENER });
       const loaded = cdp.waitFor("Page.loadEventFired", sessionId, options.loadTimeoutMs ?? 12_000);
       const nav = await s("Page.navigate", { url });
       if (typeof nav.errorText === "string" && nav.errorText)
diff --git a/packages/mcp-server/src/render/checks/index.ts b/packages/mcp-server/src/render/checks/index.ts
index 7f0967b2..d44cbc61 100644
--- a/packages/mcp-server/src/render/checks/index.ts
+++ b/packages/mcp-server/src/render/checks/index.ts
@@ -15,6 +15,7 @@ import { LAYOUT_CHECKS } from "./layout.ts";
 import { MOTION_CHECKS } from "./motion.ts";
 import { NAVIGATION_CHECKS } from "./navigation.ts";
 import { PRELUDE } from "./prelude.ts";
+import { SCRIPT_CHECKS } from "./scripts.ts";
 
 export const RENDER_CHECK_SCRIPT = [
   "(async () => {",
@@ -23,6 +24,7 @@ export const RENDER_CHECK_SCRIPT = [
   CONTRAST_CHECKS,
   CONTENT_CHECKS,
   FONT_CHECKS,
+  SCRIPT_CHECKS,
   MOTION_CHECKS,
   NAVIGATION_CHECKS,
   COMPONENT_CHECKS,
diff --git a/packages/mcp-server/src/render/checks/scripts.ts b/packages/mcp-server/src/render/checks/scripts.ts
new file mode 100644
index 00000000..5f1df660
--- /dev/null
+++ b/packages/mcp-server/src/render/checks/scripts.ts
@@ -0,0 +1,45 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: surface-broken, script-blocked.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+
+/**
+ * Runs in the page before any of its own scripts (`Page.addScriptToEvaluateOnNewDocument`):
+ * keeps the Content-Security-Policy violations the page raises while it loads, which the
+ * `script-blocked` check reads. Report-only ones (`cloudhal dev`) are kept too.
+ */
+export const CSP_LISTENER = `(() => {
+  const seen = (window.__chCsp = []);
+  window.addEventListener("securitypolicyviolation", (e) => {
+    if (seen.length < 50)
+      seen.push({ directive: e.effectiveDirective || e.violatedDirective || "", blocked: e.blockedURI || "", sample: e.sample || "", line: e.lineNumber || 0, report: e.disposition === "report", el: e.target instanceof Element ? e.target : null });
+  }, true);
+})();`;
+
+export const SCRIPT_CHECKS = `  // surface-broken: a body surface the preview could not draw (RFC-0020 §5), or a component in one
+  // with an unknown block type or props that do not fit it. Theme blocks the preview leaves to the
+  // site are fine.
+  for (const el of document.querySelectorAll(".ch-surface-problem")) {
+    const why = [...el.querySelectorAll("li")].map((li) => (li.textContent || "").trim()).filter(Boolean);
+    add("surface-broken", el, why.length ? why.slice(0, 3).join("; ") : "this interactive block cannot be shown");
+  }
+  for (const el of document.querySelectorAll(".ch-block--missing")) {
+    const text = (el.textContent || "").trim();
+    if (!/shown by the theme on the site$/.test(text)) add("surface-broken", el, text);
+  }
+
+  // script-blocked: scripts the page's Content-Security-Policy refused (the Site Worker sends
+  // script-src 'self', so an inline <script> never runs there). A static preview runs none on
+  // purpose (its own CSP), so it is not asked.
+  const runsScripts = !document.querySelector('meta[name="generator"][content="Cloudhal preview"]');
+  for (const v of runsScripts ? window.__chCsp || [] : []) {
+    if (!/^(script-src|script-src-elem|script-src-attr|worker-src)$/.test(v.directive)) continue;
+    const inline = v.blocked === "inline" || v.blocked === "eval" || !v.blocked;
+    const what = inline
+      ? (v.blocked === "eval" ? "eval" : "an inline script") + (v.sample ? " " + JSON.stringify(clip(v.sample.trim(), 40)) : "") + (v.line ? " at line " + v.line : "")
+      : "the script " + v.blocked;
+    const fix = inline ? "; ship it as a file (a .js under /_astro or public/)" : "";
+    const el = v.el && v.el.isConnected ? v.el : document.body;
+    add("script-blocked", el, what + (v.report ? " would be blocked on the site" : " was blocked") + " by " + v.directive + fix);
+  }
+`;
diff --git a/packages/mcp-server/src/render/types.ts b/packages/mcp-server/src/render/types.ts
index f0f4aeab..6cfbfef6 100644
--- a/packages/mcp-server/src/render/types.ts
+++ b/packages/mcp-server/src/render/types.ts
@@ -89,6 +89,10 @@ export const RENDER_CHECK_IDS = [
   "image-fit",
   // RFC-0023 §2: a web font with no metric-matched fallback, so its text moves when it loads.
   "font-fallback",
+  // RFC-0020 §5: a body surface the page could not draw (an unknown component, props that do not fit).
+  "surface-broken",
+  // A script the page's Content-Security-Policy refused (the Site Worker's is script-src 'self').
+  "script-blocked",
 ] as const;
 export type RenderCheckId = (typeof RENDER_CHECK_IDS)[number];
 
diff --git a/scripts/size-baseline.json b/scripts/size-baseline.json
index 52f2f80d..c2ed8683 100644
--- a/scripts/size-baseline.json
+++ b/scripts/size-baseline.json
@@ -352,7 +352,7 @@
       "params": 5
     },
     "packages/astro-renderer/src/integration.ts::cloudhal": {
-      "lines": 172
+      "lines": 168
     },
     "packages/astro-renderer/src/preview.ts::document": {
       "params": 5