@cloudhal/mcp-server 0.0.0-stage → 0.1.0

package/dist/src/publish-tools.js

@@ -0,0 +1,248 @@
+/** Snapshot, diff, preview, publish and rollback tools (approval-gated publishing). */
+
+                                                             
+import { ownOnlyChangeSet } from "@cloudhal/agent-runtime";
+import { describeChanges } from "./changes.js";
+import {
+  ACTOR_OWNERSHIP,
+  callerPerson,
+  id,
+  mapError,
+  obj,
+  quote,
+  requireSite,
+  str,
+                   
+                      
+  ToolError,
+} from "./common.js";
+import { SITE, SNAPSHOT } from "./content-shared.js";
+import { publishMenuLines } from "./menu-tools.js";
+import { previewDoc } from "./preview-doc.js";
+import { PREVIEW_UI_URI } from "./preview-view.js";
+
+const createSnapshotTool                 = {
+  name: "create_snapshot",
+  title: "Create snapshot",
+  description: "Freeze the current state of the site as an immutable, labelled snapshot.",
+  inputSchema: obj({ siteId: id, label: str("Short label, e.g. 'Before: retitle about page'") }, [
+    "siteId",
+  ]),
+  outputSchema: obj({ snapshot: SNAPSHOT }, ["snapshot"]),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  scopes: ["content:draft:own"],
+  handler: async (a, ctx) => {
+    await requireSite(ctx, a.siteId          );
+    return {
+      snapshot: await ctx.store.createSnapshot(a.siteId          , {
+        actor: ctx.principal.actor,
+        reason: "manual",
+        ...(a.label ? { label: a.label           } : {}),
+      }),
+    };
+  },
+};
+
+const listSnapshotsTool                 = {
+  name: "list_snapshots",
+  title: "List snapshots",
+  description: "Snapshots of a site, newest first, and which one is live.",
+  inputSchema: obj(
+    { siteId: id, limit: { type: "integer", minimum: 1, maximum: 200, default: 20 } },
+    ["siteId"],
+  ),
+  outputSchema: obj(
+    {
+      snapshots: { type: "array", items: SNAPSHOT },
+      publishedSnapshotId: { type: ["string", "null"] },
+    },
+    ["snapshots", "publishedSnapshotId"],
+  ),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["site:read"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    return {
+      snapshots: await ctx.store.listSnapshots(site.id, (a.limit                      ) ?? 20),
+      publishedSnapshotId: site.publishedSnapshotId ?? null,
+    };
+  },
+};
+
+const diffSnapshotsTool                 = {
+  name: "diff_snapshots",
+  title: "Diff snapshots",
+  description: "Added, changed and removed nodes between two snapshots.",
+  inputSchema: obj({ siteId: id, fromSnapshotId: id, toSnapshotId: id }, [
+    "siteId",
+    "fromSnapshotId",
+    "toSnapshotId",
+  ]),
+  outputSchema: obj(
+    { added: { type: "array" }, removed: { type: "array" }, changed: { type: "array" } },
+    ["added", "removed", "changed"],
+  ),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["site:read"],
+  handler: async (a, ctx) => {
+    try {
+      for (const id of [a.fromSnapshotId          , a.toSnapshotId          ]) {
+        const snap = await ctx.store.getSnapshot(id);
+        if (!snap || snap.siteId !== a.siteId)
+          throw new ToolError("not_found", `snapshot ${id} not found`);
+      }
+      return await ctx.store.diffSnapshots(a.fromSnapshotId          , a.toSnapshotId          );
+    } catch (e) {
+      if (e instanceof ToolError) throw e;
+      mapError(e);
+    }
+  },
+};
+
+const previewPageTool                 = {
+  name: "preview_page",
+  title: "Preview page",
+  description:
+    "Render a page (or an article by entryId) to HTML as the site would show it, plus a preview link (signed, to the deployed site, or the `cloudhal dev` URL). To see how it looks in a browser, with screenshots and automatic checks, use render_page.",
+  inputSchema: obj({ siteId: id, pageId: id, entryId: id }, ["siteId"]),
+  outputSchema: obj(
+    {
+      title: { type: "string" },
+      path: { type: "string" },
+      html: { type: "string" },
+      url: { type: ["string", "null"] },
+    },
+    ["title", "path", "html", "url"],
+  ),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["preview:create"],
+  // RFC-0020 §6: MCP Apps hosts show the rendered page in Cloudhal's View.
+  ui: { resourceUri: PREVIEW_UI_URI },
+  handler: (a, ctx) => previewDoc(a, ctx),
+};
+
+const publishTool                 = {
+  name: "publish",
+  title: "Publish site",
+  description: "Snapshot the current state and make it live. Always asks for human approval.",
+  inputSchema: obj({ siteId: id, label: str("Label for the published snapshot") }, ["siteId"]),
+  outputSchema: obj({ site: SITE, snapshot: SNAPSHOT }, ["site", "snapshot"]),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  scopes: ["site:publish"],
+  own: "changeset",
+  requiresApproval: true,
+  approvalPrompt: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    // What the person approves is what goes live: the current state against the live snapshot.
+    const diff = await ctx.store.pendingChanges(site.id);
+    const lines = [
+      ...(await describeChanges(ctx, diff, site)),
+      ...(await publishMenuLines(ctx, site)),
+    ];
+    const counts = `+${diff.added.length} added, ~${diff.changed.length} changed, −${diff.removed.length} removed`;
+    return `Publish "${quote(site.name)}" to production (${counts} since the live version)?${lines.length ? `\n${lines.join("\n")}` : ""}`;
+  },
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const snapshot = await ctx.store.createSnapshot(site.id, {
+      actor: ctx.principal.actor,
+      reason: "publish",
+      ...(a.label ? { label: a.label           } : {}),
+    });
+    try {
+      return { site: await ctx.store.publish(site, snapshot.id), snapshot };
+    } catch (e) {
+      mapError(e);
+    }
+  },
+};
+
+const rollbackTool                 = {
+  name: "rollback",
+  title: "Roll back site",
+  description:
+    "Point production at an earlier snapshot (must be an ancestor of the live one). Always asks for human approval.",
+  inputSchema: obj({ siteId: id, snapshotId: id }, ["siteId", "snapshotId"]),
+  outputSchema: obj({ site: SITE, snapshot: SNAPSHOT }, ["site", "snapshot"]),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  scopes: ["site:rollback"],
+  requiresApproval: true,
+  approvalPrompt: async (a, ctx) => {
+    const snap = await ctx.store.getSnapshot(a.snapshotId          );
+    return `Roll back to snapshot "${snap?.label ?? a.snapshotId}" (${snap?.createdAt ?? "unknown time"})? The current live version stays in history.`;
+  },
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    try {
+      return await ctx.store.rollback(site, a.snapshotId          , ctx.principal.actor);
+    } catch (e) {
+      if (e instanceof Error && /not an ancestor|no published snapshot/.test(e.message))
+        throw new ToolError("invalid", e.message);
+      mapError(e);
+    }
+  },
+};
+
+/** create_snapshot … rollback, in `tools/list` order. */
+export function publishTools()                   {
+  return [
+    createSnapshotTool,
+    listSnapshotsTool,
+    diffSnapshotsTool,
+    previewPageTool,
+    publishTool,
+    rollbackTool,
+  ];
+}
+
+/**
+ * Is publishing the current state own-only for the caller (RFC-0005 §4, I10)? Every publicly
+ * visible pending change must be an entry the caller's person owns.
+ */
+export async function ownOnlyPublish(ctx             , siteId        )                         {
+  const store = ctx.store;
+  return ownOnlyChangeSet(
+    await store.pendingChanges(siteId),
+    callerPerson(ctx),
+    ctx.ownership ?? ACTOR_OWNERSHIP,
+    {
+      before: (ref) => store.readSnapshotNode(ref).catch(() => undefined),
+      after: async (ref) =>
+        ref.kind === "contentEntry"
+          ? store.getContentEntry(ref.id)
+          : ref.kind === "site"
+            ? store.getSite(ref.id)
+            : undefined,
+    },
+  );
+}

package/dist/src/render/cdp.d.ts

@@ -0,0 +1,29 @@
+/** A minimal DevTools client over a browser-level socket (flat sessions), and base64 helpers. */
+import { type CdpSocket, type RenderSession } from "./types.js";
+/**
+ * A minimal DevTools client over a browser-level socket (flat sessions). Enough for
+ * `render_page`: a browser context per session, one page per width, evaluate and screenshot.
+ */
+export declare class Cdp {
+    #private;
+    constructor(socket: CdpSocket);
+    send<T = Record<string, unknown>>(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<T>;
+    /** Resolves on the next event `method` of `sessionId` (or after `ms`, whichever comes first). */
+    waitFor(method: string, sessionId: string, ms: number): Promise<void>;
+    close(): void;
+}
+export interface CdpEvent {
+    method?: string;
+    sessionId?: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * A render session over a DevTools socket: an isolated browser context (no cookies shared
+ * between calls). `closeBrowser` also closes the browser (Browser Rendering sessions).
+ */
+export declare function cdpSession(socket: CdpSocket, options?: {
+    closeBrowser?: boolean;
+    loadTimeoutMs?: number;
+}): Promise<RenderSession>;
+export declare function base64ToBytes(b64: string): Uint8Array;
+export declare function bytesToBase64(bytes: Uint8Array): string;

package/dist/src/render/cdp.js

@@ -0,0 +1,190 @@
+/** A minimal DevTools client over a browser-level socket (flat sessions), and base64 helpers. */
+import {                 RenderError,                    } from "./types.js";
+
+/**
+ * A minimal DevTools client over a browser-level socket (flat sessions). Enough for
+ * `render_page`: a browser context per session, one page per width, evaluate and screenshot.
+ */
+export class Cdp {
+  #id = 0;
+           #pending = new Map 
+           
+                                                                 
+   ();
+           #listeners = new Set                       ();
+           #socket           ;
+  #closed = false;
+  constructor(socket           ) {
+    this.#socket = socket;
+    socket.onMessage((raw) => {
+      let m                                                                            ;
+      try {
+        m = JSON.parse(raw);
+      } catch {
+        return;
+      }
+      if (m.id !== undefined) {
+        const p = this.#pending.get(m.id);
+        if (!p) return;
+        this.#pending.delete(m.id);
+        if (m.error) p.reject(new RenderError(m.error.message ?? "DevTools error"));
+        else p.resolve(m.result);
+      } else if (m.method) {
+        for (const l of this.#listeners) l(m);
+      }
+    });
+    socket.onClose(() => {
+      this.#closed = true;
+      for (const p of this.#pending.values()) p.reject(new RenderError("the browser went away"));
+      this.#pending.clear();
+    });
+  }
+  send                             (
+    method        ,
+    params                          = {},
+    sessionId         ,
+  )             {
+    if (this.#closed) return Promise.reject(new RenderError("the browser went away"));
+    return new Promise   ((resolve, reject) => {
+      const id = ++this.#id;
+      this.#pending.set(id, { resolve: resolve                        , reject });
+      this.#socket.send(
+        JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }),
+      );
+    });
+  }
+  /** Resolves on the next event `method` of `sessionId` (or after `ms`, whichever comes first). */
+  waitFor(method        , sessionId        , ms        )                {
+    return new Promise((resolve) => {
+      const done = () => {
+        clearTimeout(timer);
+        this.#listeners.delete(listener);
+        resolve();
+      };
+      const listener = (m          ) => {
+        if (m.method === method && m.sessionId === sessionId) done();
+      };
+      const timer = setTimeout(done, ms);
+      this.#listeners.add(listener);
+    });
+  }
+  close()       {
+    if (!this.#closed) this.#socket.close();
+    this.#closed = true;
+  }
+}
+
+                           
+                  
+                     
+                                   
+ 
+
+/**
+ * A render session over a DevTools socket: an isolated browser context (no cookies shared
+ * between calls). `closeBrowser` also closes the browser (Browser Rendering sessions).
+ */
+export async function cdpSession(
+  socket           ,
+  options                                                     = {},
+)                         {
+  const cdp = new Cdp(socket);
+  const { browserContextId } = await cdp.send                              (
+    "Target.createBrowserContext",
+    { disposeOnDetach: true },
+  );
+  return {
+    async open(url, viewport) {
+      const { targetId } = await cdp.send                      ("Target.createTarget", {
+        url: "about:blank",
+        browserContextId,
+      });
+      const { sessionId } = await cdp.send                       ("Target.attachToTarget", {
+        targetId,
+        flatten: true,
+      });
+      const s = (method        , params                          = {}) =>
+        cdp.send(method, params, sessionId);
+      await s("Page.enable");
+      await s("Emulation.setDeviceMetricsOverride", {
+        width: viewport.width,
+        height: viewport.height,
+        deviceScaleFactor: 1,
+        mobile: viewport.width < 768,
+      });
+      if (viewport.width < 768) await s("Emulation.setTouchEmulationEnabled", { enabled: true });
+      // The same render on every machine: the scheme asked for, whatever the host prefers.
+      await s("Emulation.setEmulatedMedia", {
+        features: [
+          { name: "prefers-color-scheme", value: viewport.scheme ?? "light" },
+          {
+            name: "prefers-reduced-motion",
+            value: viewport.reducedMotion === false ? "no-preference" : "reduce",
+          },
+        ],
+      });
+      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)
+        throw new RenderError(`could not open the page: ${nav.errorText}`);
+      await loaded;
+      // Phones zoom out to fit a page that is too wide; stay at 100 % so the screenshot shows
+      // what overflows (the overflow-x check names it).
+      if (viewport.width < 768) await s("Emulation.setPageScaleFactor", { pageScaleFactor: 1 });
+      return {
+        async evaluate   (expression        )             {
+          const r = await cdp.send  
+                                   
+                                                                                       
+            (
+            "Runtime.evaluate",
+            { expression, awaitPromise: true, returnByValue: true },
+            sessionId,
+          );
+          if (r.exceptionDetails)
+            throw new RenderError(
+              r.exceptionDetails.exception?.description ??
+                r.exceptionDetails.text ??
+                "script failed",
+            );
+          return r.result?.value     ;
+        },
+        async screenshot(quality) {
+          const r = await cdp.send                  (
+            "Page.captureScreenshot",
+            { format: "jpeg", quality },
+            sessionId,
+          );
+          return base64ToBytes(r.data);
+        },
+        async close() {
+          await cdp.send("Target.closeTarget", { targetId });
+        },
+      };
+    },
+    async close() {
+      try {
+        await cdp.send("Target.disposeBrowserContext", { browserContextId });
+        if (options.closeBrowser) await cdp.send("Browser.close");
+      } catch {
+        // already gone
+      } finally {
+        cdp.close();
+      }
+    },
+  };
+}
+
+export function base64ToBytes(b64        )             {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export function bytesToBase64(bytes            )         {
+  let bin = "";
+  for (let i = 0; i < bytes.length; i += 0x8000)
+    bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(bin);
+}

package/dist/src/render/checks/components.d.ts

@@ -0,0 +1,5 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: carousel-label / -lcp / -focus / -autoplay, image-fit, overlay-open; ends at the top of the page.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export declare const COMPONENT_CHECKS = "  // A static preview runs no scripts (its CSP), so checks of what a module does wait for the site.\n  const staticPreview = !!document.querySelector('meta[name=\"generator\"][content=\"Cloudhal preview\"]');\n  // carousel-label and carousel-lcp: named carousels and slides; a hero's first slide not lazy.\n  for (const c of document.querySelectorAll('[aria-roledescription=\"carousel\"], [aria-roledescription=\"kayd\u0131rmal\u0131 alan\"]')) {\n    const name = (c.getAttribute(\"aria-label\") || \"\").trim();\n    if (!name) add(\"carousel-label\", c, \"a carousel without a name (aria-label)\");\n    else if (/carousel|karusel/i.test(name)) add(\"carousel-label\", c, \"its name says carousel; name what it shows\");\n    const slides = [...c.querySelectorAll('[aria-roledescription=\"slide\"], [aria-roledescription=\"slayt\"]')];\n    for (const s of slides) if (!(s.getAttribute(\"aria-label\") || \"\").trim()) add(\"carousel-label\", s, \"a slide without a name\");\n    if (!staticPreview && c.querySelector('[data-ch-carousel=\"prev\"][data-ch-pending],[data-ch-carousel=\"next\"][data-ch-pending]'))\n      add(\"carousel-focus\", c, \"its arrows never appeared: the carousel module did not run\");\n    if (!staticPreview && c.getAttribute(\"data-variant\") === \"hero\")\n      for (const s of slides.slice(1)) {\n        if (s.closest(\"[inert]\")) continue;\n        const f = s.querySelector('a[href],button,input,select,textarea,[tabindex]:not([tabindex=\"-1\"])');\n        if (f) add(\"carousel-focus\", f, \"Tab can land in a slide out of view (make off-screen slides inert)\");\n      }\n    if (c.hasAttribute(\"data-autoplay\")) {\n      const first = c.querySelector('a[href],button,input,select,textarea,[tabindex]:not([tabindex=\"-1\"])');\n      if (!first || first.getAttribute(\"data-ch-carousel\") !== \"rotate\")\n        add(\"carousel-autoplay\", c, \"it plays on its own without a rotation control first in Tab order\");\n      else if (!(first.getAttribute(\"aria-label\") || \"\").trim())\n        add(\"carousel-autoplay\", first, \"its rotation control has no name\");\n    }\n    if (c.getAttribute(\"data-variant\") === \"hero\")\n      slides.forEach((s, i) => {\n        for (const img of s.querySelectorAll(\"img\")) {\n          const lazy = wasLazy.has(img);\n          if (i === 0 && lazy) add(\"carousel-lcp\", img, \"the first hero slide's image is lazy; it is what the reader sees first\");\n          if (i > 0 && !lazy) add(\"carousel-lcp\", img, \"slide \" + (i + 1) + \"'s image loads before anyone sees it; make it lazy\");\n        }\n      });\n  }\n\n  // image-fit: cover crops that cut away much of a picture without a focal point (object-position).\n  for (const img of document.querySelectorAll(\"[data-section-id] img\")) {\n    const box = img.getBoundingClientRect();\n    if (!img.naturalWidth || !img.naturalHeight || box.width < 80 || box.height < 80) continue;\n    const cs = getComputedStyle(img);\n    if (cs.objectFit !== \"cover\" || /object-position/.test(img.getAttribute(\"style\") || \"\")) continue;\n    const own = img.naturalWidth / img.naturalHeight;\n    const frame = box.width / box.height;\n    const kept = Math.min(own, frame) / Math.max(own, frame);\n    if (kept < 0.6)\n      add(\"image-fit\", img, \"the frame keeps \" + Math.round(kept * 100) + \"% of the picture with no focal point; set one (update_asset focal) or use fit blur-fill\");\n  }\n\n  const playing = document.querySelectorAll(\"[data-autoplay]\");\n  if (playing.length > 1) add(\"carousel-autoplay\", playing[1], \"a second carousel plays on its own; one per page at most\");\n\n  // overlay-open: every overlay of the page's sections, opened the way a reader would.\n  const isOpen = (t) => !!t.open || t.matches(\":popover-open\");\n  const overlaysOf = [...document.querySelectorAll(\"[data-section-id] dialog.ch-dialog, [data-section-id] [popover].ch-popover\")];\n  for (const t of overlaysOf) {\n    const sel = '[commandfor=\"' + t.id + '\"]:not([command=\"close\"]),[popovertarget=\"' + t.id + '\"]:not([popovertargetaction=\"hide\"]),[data-ch-open=\"' + t.id + '\"],[data-ch-lightbox=\"' + t.id + '\"]';\n    const trigger = [...document.querySelectorAll(sel)].find(shown);\n    if (!trigger) { add(\"overlay-open\", t, \"nothing on the page opens it\"); continue; }\n    trigger.scrollIntoView({ block: \"center\" });\n    trigger.focus();\n    trigger.click();\n    await frame();\n    if (!isOpen(t)) { add(\"overlay-open\", trigger, \"did not open its overlay\"); continue; }\n    const modal = t.tagName === \"DIALOG\";\n    if (modal && !t.contains(document.activeElement)) add(\"overlay-open\", t, \"focus stayed outside when it opened\");\n    if (modal && t.getAttribute(\"closedby\") === \"none\" && !t.querySelector('[command=\"close\"]'))\n      add(\"overlay-open\", t, \"it closes only by a button, and has none\");\n    // Its text against its own paint (an overlay is opaque).\n    const tw = document.createTreeWalker(t, NodeFilter.SHOW_TEXT);\n    const doneT = new Set();\n    while (tw.nextNode()) {\n      const el = tw.currentNode.parentElement;\n      if (!el || doneT.has(el) || !tw.currentNode.nodeValue.trim() || !visible(el)) continue;\n      doneT.add(el);\n      // The first opaque fill between the text and the overlay's edge.\n      let bg = null;\n      for (let e = el; e && !bg; e = e === t ? null : e.parentElement) {\n        const c = rgba(getComputedStyle(e).backgroundColor);\n        if (c[3] >= 1) bg = c.slice(0, 3);\n      }\n      if (!bg) continue;\n      const st = getComputedStyle(el);\n      const got = ratio(over(rgba(st.color), bg), bg);\n      const big = parseFloat(st.fontSize) >= 24 || (parseFloat(st.fontSize) >= 18.66 && Number(st.fontWeight) >= 700);\n      if (got < (big ? 3 : 4.5)) add(\"overlay-open\", el, got.toFixed(1) + \":1 inside the overlay, needs \" + (big ? 3 : 4.5) + \":1\");\n    }\n    if (modal) t.close(); else t.hidePopover();\n    await frame();\n    if (document.activeElement !== trigger) add(\"overlay-open\", trigger, \"focus did not come back when it closed\");\n  }\n  window.scrollTo(0, 0);\n";

package/dist/src/render/checks/components.js

@@ -0,0 +1,95 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: carousel-label / -lcp / -focus / -autoplay, image-fit, overlay-open; ends at the top of the page.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export const COMPONENT_CHECKS = `  // A static preview runs no scripts (its CSP), so checks of what a module does wait for the site.
+  const staticPreview = !!document.querySelector('meta[name="generator"][content="Cloudhal preview"]');
+  // carousel-label and carousel-lcp: named carousels and slides; a hero's first slide not lazy.
+  for (const c of document.querySelectorAll('[aria-roledescription="carousel"], [aria-roledescription="kaydırmalı alan"]')) {
+    const name = (c.getAttribute("aria-label") || "").trim();
+    if (!name) add("carousel-label", c, "a carousel without a name (aria-label)");
+    else if (/carousel|karusel/i.test(name)) add("carousel-label", c, "its name says carousel; name what it shows");
+    const slides = [...c.querySelectorAll('[aria-roledescription="slide"], [aria-roledescription="slayt"]')];
+    for (const s of slides) if (!(s.getAttribute("aria-label") || "").trim()) add("carousel-label", s, "a slide without a name");
+    if (!staticPreview && c.querySelector('[data-ch-carousel="prev"][data-ch-pending],[data-ch-carousel="next"][data-ch-pending]'))
+      add("carousel-focus", c, "its arrows never appeared: the carousel module did not run");
+    if (!staticPreview && c.getAttribute("data-variant") === "hero")
+      for (const s of slides.slice(1)) {
+        if (s.closest("[inert]")) continue;
+        const f = s.querySelector('a[href],button,input,select,textarea,[tabindex]:not([tabindex="-1"])');
+        if (f) add("carousel-focus", f, "Tab can land in a slide out of view (make off-screen slides inert)");
+      }
+    if (c.hasAttribute("data-autoplay")) {
+      const first = c.querySelector('a[href],button,input,select,textarea,[tabindex]:not([tabindex="-1"])');
+      if (!first || first.getAttribute("data-ch-carousel") !== "rotate")
+        add("carousel-autoplay", c, "it plays on its own without a rotation control first in Tab order");
+      else if (!(first.getAttribute("aria-label") || "").trim())
+        add("carousel-autoplay", first, "its rotation control has no name");
+    }
+    if (c.getAttribute("data-variant") === "hero")
+      slides.forEach((s, i) => {
+        for (const img of s.querySelectorAll("img")) {
+          const lazy = wasLazy.has(img);
+          if (i === 0 && lazy) add("carousel-lcp", img, "the first hero slide's image is lazy; it is what the reader sees first");
+          if (i > 0 && !lazy) add("carousel-lcp", img, "slide " + (i + 1) + "'s image loads before anyone sees it; make it lazy");
+        }
+      });
+  }
+
+  // image-fit: cover crops that cut away much of a picture without a focal point (object-position).
+  for (const img of document.querySelectorAll("[data-section-id] img")) {
+    const box = img.getBoundingClientRect();
+    if (!img.naturalWidth || !img.naturalHeight || box.width < 80 || box.height < 80) continue;
+    const cs = getComputedStyle(img);
+    if (cs.objectFit !== "cover" || /object-position/.test(img.getAttribute("style") || "")) continue;
+    const own = img.naturalWidth / img.naturalHeight;
+    const frame = box.width / box.height;
+    const kept = Math.min(own, frame) / Math.max(own, frame);
+    if (kept < 0.6)
+      add("image-fit", img, "the frame keeps " + Math.round(kept * 100) + "% of the picture with no focal point; set one (update_asset focal) or use fit blur-fill");
+  }
+
+  const playing = document.querySelectorAll("[data-autoplay]");
+  if (playing.length > 1) add("carousel-autoplay", playing[1], "a second carousel plays on its own; one per page at most");
+
+  // overlay-open: every overlay of the page's sections, opened the way a reader would.
+  const isOpen = (t) => !!t.open || t.matches(":popover-open");
+  const overlaysOf = [...document.querySelectorAll("[data-section-id] dialog.ch-dialog, [data-section-id] [popover].ch-popover")];
+  for (const t of overlaysOf) {
+    const sel = '[commandfor="' + t.id + '"]:not([command="close"]),[popovertarget="' + t.id + '"]:not([popovertargetaction="hide"]),[data-ch-open="' + t.id + '"],[data-ch-lightbox="' + t.id + '"]';
+    const trigger = [...document.querySelectorAll(sel)].find(shown);
+    if (!trigger) { add("overlay-open", t, "nothing on the page opens it"); continue; }
+    trigger.scrollIntoView({ block: "center" });
+    trigger.focus();
+    trigger.click();
+    await frame();
+    if (!isOpen(t)) { add("overlay-open", trigger, "did not open its overlay"); continue; }
+    const modal = t.tagName === "DIALOG";
+    if (modal && !t.contains(document.activeElement)) add("overlay-open", t, "focus stayed outside when it opened");
+    if (modal && t.getAttribute("closedby") === "none" && !t.querySelector('[command="close"]'))
+      add("overlay-open", t, "it closes only by a button, and has none");
+    // Its text against its own paint (an overlay is opaque).
+    const tw = document.createTreeWalker(t, NodeFilter.SHOW_TEXT);
+    const doneT = new Set();
+    while (tw.nextNode()) {
+      const el = tw.currentNode.parentElement;
+      if (!el || doneT.has(el) || !tw.currentNode.nodeValue.trim() || !visible(el)) continue;
+      doneT.add(el);
+      // The first opaque fill between the text and the overlay's edge.
+      let bg = null;
+      for (let e = el; e && !bg; e = e === t ? null : e.parentElement) {
+        const c = rgba(getComputedStyle(e).backgroundColor);
+        if (c[3] >= 1) bg = c.slice(0, 3);
+      }
+      if (!bg) continue;
+      const st = getComputedStyle(el);
+      const got = ratio(over(rgba(st.color), bg), bg);
+      const big = parseFloat(st.fontSize) >= 24 || (parseFloat(st.fontSize) >= 18.66 && Number(st.fontWeight) >= 700);
+      if (got < (big ? 3 : 4.5)) add("overlay-open", el, got.toFixed(1) + ":1 inside the overlay, needs " + (big ? 3 : 4.5) + ":1");
+    }
+    if (modal) t.close(); else t.hidePopover();
+    await frame();
+    if (document.activeElement !== trigger) add("overlay-open", trigger, "focus did not come back when it closed");
+  }
+  window.scrollTo(0, 0);
+`;

package/dist/src/render/checks/content.d.ts

@@ -0,0 +1,5 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: empty-section, tap-target, input-label, chart-empty, long-line.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export declare const CONTENT_CHECKS = "  // empty-section\n  for (const s of document.querySelectorAll(\"[data-section-id]\")) {\n    if (getComputedStyle(s).display === \"none\") continue;\n    const text = (s.innerText || \"\").trim();\n    const media = s.querySelector(\"img,video,iframe,svg,canvas,input,select,textarea,picture\");\n    const r = s.getBoundingClientRect();\n    if (!text && !media) add(\"empty-section\", s, \"no text or media\");\n    else if (r.height < 8) add(\"empty-section\", s, Math.round(r.height) + \" px tall\");\n  }\n\n  // tap-target: on small screens, controls under 24 \u00D7 24 px that sit too close to another one\n  // (WCAG 2.5.8: a 24 px circle on each must not touch another target; links inside sentences are exempt).\n  if (W < 768) {\n    const targets = [...document.querySelectorAll(\"a[href],button,input:not([type=hidden]),select,textarea,summary,[role=button]\")]\n      .filter(visible)\n      .map((el) => ({ el, r: el.getBoundingClientRect() }))\n      // screen-reader-only controls (1 \u00D7 1 px) are not tapped\n      .filter((t) => t.r.width > 2 || t.r.height > 2);\n    const small = (t) => t.r.width < 24 || t.r.height < 24;\n    const centre = (r) => [r.left + r.width / 2, r.top + r.height / 2];\n    const toRect = (p, r) => Math.hypot(Math.max(r.left - p[0], 0, p[0] - r.right), Math.max(r.top - p[1], 0, p[1] - r.bottom));\n    for (const t of targets) {\n      if (!small(t)) continue;\n      if (t.el.tagName === \"A\" && getComputedStyle(t.el).display === \"inline\") {\n        const block = t.el.closest(\"p,li,td,dd,blockquote,figcaption\");\n        if (block && (block.innerText || \"\").trim().length > (t.el.innerText || \"\").trim().length + 20) continue;\n      }\n      const c = centre(t.r);\n      const near = targets.find((o) => o !== t && !o.el.contains(t.el) && !t.el.contains(o.el) &&\n        (toRect(c, o.r) < 12 || (small(o) && Math.hypot(c[0] - centre(o.r)[0], c[1] - centre(o.r)[1]) < 24)));\n      if (near) add(\"tap-target\", t.el, Math.round(t.r.width) + \" \u00D7 \" + Math.round(t.r.height) + \" px, too close to \" + JSON.stringify(clip((near.el.innerText || near.el.getAttribute(\"aria-label\") || near.el.tagName.toLowerCase()).trim(), 24)));\n    }\n  }\n\n  // input-label: form controls without an accessible name (a label, aria-label or aria-labelledby).\n  for (const el of document.querySelectorAll(\"input:not([type=hidden]):not([type=submit]):not([type=button]),select,textarea\")) {\n    if (!visible(el) && !(el.type === \"radio\" || el.type === \"checkbox\")) continue;\n    const named = [...(el.labels || [])].some((l) => (l.innerText || l.textContent || \"\").trim()) ||\n      (el.getAttribute(\"aria-label\") || \"\").trim() ||\n      (el.getAttribute(\"aria-labelledby\") || \"\").split(/s+/).some((id) => id && (document.getElementById(id)?.textContent || \"\").trim());\n    if (!named) add(\"input-label\", el, \"no label a screen reader can announce\");\n  }\n\n  // chart-empty: a chart whose data has no rows.\n  for (const el of document.querySelectorAll(\"[data-ch-chart-empty]\")) add(\"chart-empty\", el, \"no rows in its data\");\n\n  // long-line: paragraphs averaging more than 90 characters a line.\n  for (const p of document.querySelectorAll(\"p,li,dd,blockquote\")) {\n    if (!visible(p) || p.querySelector(\"p,li\")) continue;\n    const text = (p.innerText || \"\").trim();\n    if (text.length < 180) continue;\n    const s = getComputedStyle(p);\n    const lh = s.lineHeight === \"normal\" ? parseFloat(s.fontSize) * 1.2 : parseFloat(s.lineHeight);\n    const lines = Math.round(p.getBoundingClientRect().height / lh);\n    if (lines < 3) continue;\n    const per = Math.round(text.length / lines);\n    if (per > 90) add(\"long-line\", p, \"about \" + per + \" characters a line\");\n  }\n";

package/dist/src/render/checks/content.js

@@ -0,0 +1,63 @@
+/**
+ * In-page checks, part of `RENDER_CHECK_SCRIPT`: empty-section, tap-target, input-label, chart-empty, long-line.
+ * Plain source text, run inside the page; it shares the script's locals (see ./index.ts).
+ */
+export const CONTENT_CHECKS = `  // empty-section
+  for (const s of document.querySelectorAll("[data-section-id]")) {
+    if (getComputedStyle(s).display === "none") continue;
+    const text = (s.innerText || "").trim();
+    const media = s.querySelector("img,video,iframe,svg,canvas,input,select,textarea,picture");
+    const r = s.getBoundingClientRect();
+    if (!text && !media) add("empty-section", s, "no text or media");
+    else if (r.height < 8) add("empty-section", s, Math.round(r.height) + " px tall");
+  }
+
+  // tap-target: on small screens, controls under 24 × 24 px that sit too close to another one
+  // (WCAG 2.5.8: a 24 px circle on each must not touch another target; links inside sentences are exempt).
+  if (W < 768) {
+    const targets = [...document.querySelectorAll("a[href],button,input:not([type=hidden]),select,textarea,summary,[role=button]")]
+      .filter(visible)
+      .map((el) => ({ el, r: el.getBoundingClientRect() }))
+      // screen-reader-only controls (1 × 1 px) are not tapped
+      .filter((t) => t.r.width > 2 || t.r.height > 2);
+    const small = (t) => t.r.width < 24 || t.r.height < 24;
+    const centre = (r) => [r.left + r.width / 2, r.top + r.height / 2];
+    const toRect = (p, r) => Math.hypot(Math.max(r.left - p[0], 0, p[0] - r.right), Math.max(r.top - p[1], 0, p[1] - r.bottom));
+    for (const t of targets) {
+      if (!small(t)) continue;
+      if (t.el.tagName === "A" && getComputedStyle(t.el).display === "inline") {
+        const block = t.el.closest("p,li,td,dd,blockquote,figcaption");
+        if (block && (block.innerText || "").trim().length > (t.el.innerText || "").trim().length + 20) continue;
+      }
+      const c = centre(t.r);
+      const near = targets.find((o) => o !== t && !o.el.contains(t.el) && !t.el.contains(o.el) &&
+        (toRect(c, o.r) < 12 || (small(o) && Math.hypot(c[0] - centre(o.r)[0], c[1] - centre(o.r)[1]) < 24)));
+      if (near) add("tap-target", t.el, Math.round(t.r.width) + " × " + Math.round(t.r.height) + " px, too close to " + JSON.stringify(clip((near.el.innerText || near.el.getAttribute("aria-label") || near.el.tagName.toLowerCase()).trim(), 24)));
+    }
+  }
+
+  // input-label: form controls without an accessible name (a label, aria-label or aria-labelledby).
+  for (const el of document.querySelectorAll("input:not([type=hidden]):not([type=submit]):not([type=button]),select,textarea")) {
+    if (!visible(el) && !(el.type === "radio" || el.type === "checkbox")) continue;
+    const named = [...(el.labels || [])].some((l) => (l.innerText || l.textContent || "").trim()) ||
+      (el.getAttribute("aria-label") || "").trim() ||
+      (el.getAttribute("aria-labelledby") || "").split(/s+/).some((id) => id && (document.getElementById(id)?.textContent || "").trim());
+    if (!named) add("input-label", el, "no label a screen reader can announce");
+  }
+
+  // chart-empty: a chart whose data has no rows.
+  for (const el of document.querySelectorAll("[data-ch-chart-empty]")) add("chart-empty", el, "no rows in its data");
+
+  // long-line: paragraphs averaging more than 90 characters a line.
+  for (const p of document.querySelectorAll("p,li,dd,blockquote")) {
+    if (!visible(p) || p.querySelector("p,li")) continue;
+    const text = (p.innerText || "").trim();
+    if (text.length < 180) continue;
+    const s = getComputedStyle(p);
+    const lh = s.lineHeight === "normal" ? parseFloat(s.fontSize) * 1.2 : parseFloat(s.lineHeight);
+    const lines = Math.round(p.getBoundingClientRect().height / lh);
+    if (lines < 3) continue;
+    const per = Math.round(text.length / lines);
+    if (per > 90) add("long-line", p, "about " + per + " characters a line");
+  }
+`;