@avocadostudio-ai/site-sdk 0.21.0 → 0.22.0

package/NOTICE

@@ -0,0 +1,8 @@
+Avocado Studio
+Copyright 2026 Avocado Studio Contributors
+
+This product includes software developed by the Avocado Studio
+Contributors (https://www.avocadostudio.dev).
+
+Licensed under the Apache License, Version 2.0. See LICENSE for the
+full license text.

package/README.md

@@ -1098,6 +1098,44 @@ An agent integrating a site can call the same check as
 `avocado-check-editing-surface` over MCP, and should, before reporting an
 integration as done.
 
+## Last step: `avocado qa`
+
+Both coverage checks, and everything else that only shows up once a person
+opens the editor, in one command. Run it from the site's directory with the dev
+server up:
+
+```bash
+npx avocado qa                          # where the SDK is a direct dependency
+npx @avocadostudio-ai/site-sdk qa       # anywhere — the unscoped `avocado` on npm is someone else's
+```
+
+It frames every page from the editor's own origin, in editor mode, from a
+throwaway orchestrator session (`qa-<timestamp>`) seeded with your own pages —
+never your session — and exits 1 if any check fails:
+
+- **preflight** — Next 15–16 App Router or Astro 5+, Node, package manager and
+  corepack, free disk, frame headers against the editor origin, and known
+  blockers in your source (a CMS live-preview SDK, `draftMode()`, a CSS reset);
+- **static** — Next/React installed in a non-React site, and the preview bridge
+  on public pages (`--build` also runs your typecheck and build);
+- **content contract** — the manifest validates, every block type on every page
+  is in it, `panelCoverage`, and a diff of `.avocado/manifest.lock` against the
+  last run, so a renamed block type is caught before it strands a draft;
+- **editor render** — HTTP 200 and no uncaught errors in the frame, block ids
+  that exist in the draft, `editableCoverage`, one block per rendered section,
+  and fixtures your own content may never hold: rich text with every node type
+  (are the bullets visible?), an image from every source the editor writes, and
+  a probe proving the render reads the draft it was given;
+- **invasiveness** — what the integration changed, per git, including modules it
+  orphaned.
+
+The browser half needs Playwright where the command can find it
+(`npm i -D playwright && npx playwright install chromium`); without it the
+stage runs on server HTML and says what it skipped. It is not a dependency of
+this package. The full list of checks, flags and files is at
+[/integration/qa](https://docs.avocadostudio.dev/integration/qa). Commit
+`.avocado/manifest.lock`; ignore `.avocado/qa-report.json`.
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/cli/avocado.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * `avocado` — the SDK's command-line entry, with subcommands.
+ *
+ *   avocado qa         the integration gate (see ./qa/run.ts)
+ *   avocado register   the same command as `avocado-register`
+ *
+ * Published under two bin names, `avocado` and `site-sdk`. The second one is
+ * not decoration: `npx @avocadostudio-ai/site-sdk <cmd>` only works while the
+ * package has exactly one bin, or has one named after the package — that is
+ * npm's rule for picking which bin `npx <package>` runs. Adding `avocado` next
+ * to `avocado-register` would otherwise have broken the
+ * `npx @avocadostudio-ai/site-sdk register` line `avocado-register --help`
+ * prints.
+ *
+ * The unscoped `avocado` name on npm belongs to an unrelated package, so
+ * `npx avocado qa` finds this bin only where the SDK is installed — which is
+ * where it is meant to run. The scoped form works anywhere.
+ */
+export {};

package/dist/cli/avocado.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * `avocado` — the SDK's command-line entry, with subcommands.
+ *
+ *   avocado qa         the integration gate (see ./qa/run.ts)
+ *   avocado register   the same command as `avocado-register`
+ *
+ * Published under two bin names, `avocado` and `site-sdk`. The second one is
+ * not decoration: `npx @avocadostudio-ai/site-sdk <cmd>` only works while the
+ * package has exactly one bin, or has one named after the package — that is
+ * npm's rule for picking which bin `npx <package>` runs. Adding `avocado` next
+ * to `avocado-register` would otherwise have broken the
+ * `npx @avocadostudio-ai/site-sdk register` line `avocado-register --help`
+ * prints.
+ *
+ * The unscoped `avocado` name on npm belongs to an unrelated package, so
+ * `npx avocado qa` finds this bin only where the SDK is installed — which is
+ * where it is meant to run. The scoped form works anywhere.
+ */
+import { qaMain } from "./qa/cli.js";
+const HELP = `
+avocado — Avocado Studio site SDK commands
+
+USAGE
+  npx avocado <command> [options]
+  npx @avocadostudio-ai/site-sdk <command> [options]
+
+COMMANDS
+  qa         Check the integration the way the editor will use it — run it last,
+             and do not call the integration done until it passes
+  register   Register this site with an orchestrator (same as avocado-register)
+
+  avocado <command> --help   for a command's options
+`;
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    switch (command) {
+        case "qa":
+            return qaMain(rest);
+        case "register":
+            // register.ts runs on import and reads process.argv itself; the leading
+            // `register` is a positional it ignores.
+            await import("./register.js");
+            return -1;
+        case undefined:
+        case "help":
+        case "-h":
+        case "--help":
+            process.stdout.write(HELP);
+            return 0;
+        default:
+            process.stderr.write(`avocado: unknown command "${command}"\n${HELP}`);
+            return 2;
+    }
+}
+main().then((code) => {
+    if (code >= 0)
+        process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`\nUnexpected error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.exit(1);
+});

package/dist/cli/qa/cli.d.ts

@@ -0,0 +1,2 @@
+export declare const QA_HELP = "\navocado qa \u2014 check an Avocado integration the way the editor will use it\n\nUSAGE\n  npx avocado qa [options]\n  npx @avocadostudio-ai/site-sdk qa [options]     (same command, unambiguous name)\n\nRun it from the site's directory with the site's dev server up. It renders every\npage in a frame on the editor's origin, from a throwaway orchestrator session\n(qa-<timestamp>) seeded with the site's own pages \u2014 never your own session \u2014 and\nexits non-zero if any check fails. Warnings do not fail it; read them anyway.\n\nSTAGES\n  0 preflight   framework/Node/package manager, free disk, frame headers, known blockers\n  1 static      packages for a framework the site does not use, editor script on public pages\n                (typecheck + build only with --build)\n  2 contract    manifest valid, every page's block types in it, panel coverage,\n                .avocado/manifest.lock diff; seeds the throwaway session\n  3 render      every page in an editor frame: HTTP 200, no uncaught errors, markers and\n                block ids, granularity, rich-text styles, image sources, draft source,\n                preview-route drift (needs Playwright for the browser half)\n    invasiveness  lines and files the integration changed, public routes, orphaned modules\n  5 manual      a checklist, printed at the end\n\nOPTIONS\n  --site <url>             The running site (default: the port in package.json's dev script,\n                           else :3000 for Next, :4321 for Astro)\n  --orchestrator <url>     The orchestrator the SITE reads drafts from (default:\n                           ORCHESTRATOR_URL from the env files, else http://localhost:4200).\n                           Library mode: http://localhost:<port>/api/avocado\n  --editor-origin <url>    The editor's origin (default: NEXT_PUBLIC_EDITOR_ORIGIN /\n                           AVOCADO_EDITOR_ORIGINS, else http://localhost:4100)\n  --site-id <id>           Default: NEXT_PUBLIC_DEFAULT_SITE_ID / AVOCADO_SITE_ID, else package name\n  --secret <value>         DRAFT_MODE_SECRET (default: read from the env files)\n  --token <value>          Orchestrator access token (default: $ORCHESTRATOR_ACCESS_TOKEN)\n  --skip <stages>          Comma-separated: 0-5 or preflight,static,contract,render,invasiveness\n  --build                  Also run the site's typecheck and build scripts\n  --js-budget <kb>         Gzipped budget for editor code on a public page (default 10)\n  --max-pages <n>          Render at most n pages (default: all)\n  --base <ref>             Git ref for the invasiveness report (default: merge-base with the\n                           default branch)\n  --playwright <path>      A Playwright install to use when the project has none\n  --headed                 Show the browser\n  --no-browser             Server HTML only, even when Playwright is available\n  --report <path>          JSON report path (default .avocado/qa-report.json)\n  --timeout <ms>           Per-request timeout (default 20000)\n  --json                   Print the JSON report instead of the summary\n  --cwd <dir>              The site's directory (default: current directory)\n  -h, --help               This help\n\nFILES\n  .avocado/qa-report.json  Every check, with evidence. Do not commit it.\n  .avocado/manifest.lock   The block manifest's shape at the last run. Commit it: the next\n                           schema change shows up in review and in this command.\n";
+export declare function qaMain(argv: string[]): Promise<number>;

package/dist/cli/qa/cli.js

@@ -0,0 +1,89 @@
+/*
+ * `avocado qa` on the command line: arguments in, one screen and an exit code
+ * out. Exit 0 when no check failed, 1 when one did, 2 for a usage error — so
+ * an agent can gate on it without reading anything.
+ */
+import { formatSummary } from "./report.js";
+import { parseQaArgs, QaArgError, resolveQaOptions, runQa } from "./run.js";
+export const QA_HELP = `
+avocado qa — check an Avocado integration the way the editor will use it
+
+USAGE
+  npx avocado qa [options]
+  npx @avocadostudio-ai/site-sdk qa [options]     (same command, unambiguous name)
+
+Run it from the site's directory with the site's dev server up. It renders every
+page in a frame on the editor's origin, from a throwaway orchestrator session
+(qa-<timestamp>) seeded with the site's own pages — never your own session — and
+exits non-zero if any check fails. Warnings do not fail it; read them anyway.
+
+STAGES
+  0 preflight   framework/Node/package manager, free disk, frame headers, known blockers
+  1 static      packages for a framework the site does not use, editor script on public pages
+                (typecheck + build only with --build)
+  2 contract    manifest valid, every page's block types in it, panel coverage,
+                .avocado/manifest.lock diff; seeds the throwaway session
+  3 render      every page in an editor frame: HTTP 200, no uncaught errors, markers and
+                block ids, granularity, rich-text styles, image sources, draft source,
+                preview-route drift (needs Playwright for the browser half)
+    invasiveness  lines and files the integration changed, public routes, orphaned modules
+  5 manual      a checklist, printed at the end
+
+OPTIONS
+  --site <url>             The running site (default: the port in package.json's dev script,
+                           else :3000 for Next, :4321 for Astro)
+  --orchestrator <url>     The orchestrator the SITE reads drafts from (default:
+                           ORCHESTRATOR_URL from the env files, else http://localhost:4200).
+                           Library mode: http://localhost:<port>/api/avocado
+  --editor-origin <url>    The editor's origin (default: NEXT_PUBLIC_EDITOR_ORIGIN /
+                           AVOCADO_EDITOR_ORIGINS, else http://localhost:4100)
+  --site-id <id>           Default: NEXT_PUBLIC_DEFAULT_SITE_ID / AVOCADO_SITE_ID, else package name
+  --secret <value>         DRAFT_MODE_SECRET (default: read from the env files)
+  --token <value>          Orchestrator access token (default: $ORCHESTRATOR_ACCESS_TOKEN)
+  --skip <stages>          Comma-separated: 0-5 or preflight,static,contract,render,invasiveness
+  --build                  Also run the site's typecheck and build scripts
+  --js-budget <kb>         Gzipped budget for editor code on a public page (default 10)
+  --max-pages <n>          Render at most n pages (default: all)
+  --base <ref>             Git ref for the invasiveness report (default: merge-base with the
+                           default branch)
+  --playwright <path>      A Playwright install to use when the project has none
+  --headed                 Show the browser
+  --no-browser             Server HTML only, even when Playwright is available
+  --report <path>          JSON report path (default .avocado/qa-report.json)
+  --timeout <ms>           Per-request timeout (default 20000)
+  --json                   Print the JSON report instead of the summary
+  --cwd <dir>              The site's directory (default: current directory)
+  -h, --help               This help
+
+FILES
+  .avocado/qa-report.json  Every check, with evidence. Do not commit it.
+  .avocado/manifest.lock   The block manifest's shape at the last run. Commit it: the next
+                           schema change shows up in review and in this command.
+`;
+export async function qaMain(argv) {
+    let parsed;
+    try {
+        parsed = parseQaArgs(argv);
+        if (parsed.help) {
+            process.stdout.write(QA_HELP);
+            return 0;
+        }
+        const { options, env, envFiles } = resolveQaOptions(parsed);
+        const report = await runQa(options, env, envFiles);
+        if (parsed.json) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        }
+        else {
+            const tty = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+            process.stdout.write(`\n${formatSummary(report, { color: tty, width: process.stdout.columns ?? 110 })}\n`);
+        }
+        return report.ok ? 0 : 1;
+    }
+    catch (err) {
+        if (err instanceof QaArgError) {
+            process.stderr.write(`avocado qa: ${err.message}\nRun \`avocado qa --help\` for usage.\n`);
+            return 2;
+        }
+        throw err;
+    }
+}

package/dist/cli/qa/contract.d.ts

@@ -0,0 +1,31 @@
+import { type BlockManifest } from "@avocadostudio-ai/shared";
+import { type QaPage, type QaState } from "./state.ts";
+import type { QaCheck } from "./types.ts";
+export declare const MANIFEST_LOCK_PATH: string;
+export declare function checkManifest(raw: unknown): {
+    check: QaCheck;
+    manifest?: BlockManifest;
+};
+export declare function checkPages(raw: unknown): {
+    check: QaCheck;
+    pages?: QaPage[];
+};
+/**
+ * Chrome types — a site header, a footer — are Avocado built-ins the manifest
+ * leaves out on purpose: they are pinned, never added or moved, and the editor
+ * edits them through its own registry. A page holding one is not a gap.
+ */
+export declare function builtinChromeTypes(builtins?: Record<string, unknown>): Set<string>;
+/** Every block type a page uses that the manifest does not describe, by the slugs that use it. */
+export declare function unknownBlockTypes(manifest: BlockManifest, pages: QaPage[], chrome?: Set<string>): Map<string, string[]>;
+export declare function checkBlockTypes(manifest: BlockManifest, pages: QaPage[], builtins?: Record<string, unknown>): QaCheck;
+export declare function checkPropsAgainstSchema(manifest: BlockManifest, pages: QaPage[]): QaCheck;
+export declare function checkPanelCoverage(manifest: BlockManifest, pages: QaPage[]): QaCheck;
+export declare function checkDraftEndpoint(state: QaState): Promise<QaCheck>;
+export declare function checkManifestLock(state: QaState, manifest: BlockManifest, now?: Date): QaCheck;
+/**
+ * Fill a throwaway session with pages. `force`, because the session is ours and
+ * nothing in it is anybody's work; the user's own session is never named here.
+ */
+export declare function seedSession(state: QaState, pages: QaPage[], session?: string): Promise<QaCheck>;
+export declare function runContract(state: QaState): Promise<QaCheck[]>;

package/dist/cli/qa/contract.js

@@ -0,0 +1,355 @@
+/*
+ * Stage 2 — the content contract.
+ *
+ * The editor believes two documents the site serves: `/api/editor/blocks` (what
+ * each block type is and how to edit it) and `/api/editor/pages` (what is on
+ * each page). Everything the editor does rests on those agreeing, and the
+ * disagreement that cost the most on a real integration was the plainest one:
+ * pages holding a block type the manifest no longer listed, after the blog
+ * split one `pageBlogPost` block into `articleHero` + `articleBody`.
+ *
+ * This stage also seeds the throwaway session stage 3 renders from. It is
+ * `qa-<timestamp>`, never the user's: a QA run that bootstrapped `dev` would
+ * overwrite the very drafts it exists to protect.
+ */
+import { join } from "node:path";
+import { blockManifestSchema, findManifestSchemaIssue, formatPanelCoverage, getAllBlockMeta, panelCoverage, resolveManifestFieldMeta, validateManifestDefaultProps, } from "@avocadostudio-ai/shared";
+import { describeFailure, joinUrl, request } from "./http.js";
+import { diffManifestLocks, readManifestLock, snapshotManifest, writeManifestLock } from "./manifest-lock.js";
+import { orchestratorHeaders } from "./state.js";
+const STAGE = "contract";
+export const MANIFEST_LOCK_PATH = join(".avocado", "manifest.lock");
+// ── manifest ─────────────────────────────────────────────────────────────
+export function checkManifest(raw) {
+    const id = "contract.manifest";
+    const title = "The block manifest is valid";
+    const parsed = blockManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.slice(0, 5).map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`);
+        return {
+            check: {
+                id, stage: STAGE, title, status: "fail",
+                detail: issues.join("; "),
+                fix: "Serve /api/editor/blocks from the SDK's handler (createEditorApiHandler / the Astro editor-api route), and describe blocks with registerBlock — a hand-written manifest drifts from the schema the editor validates against.",
+            },
+        };
+    }
+    const manifest = parsed.data;
+    const problems = [];
+    const seen = new Set();
+    for (const block of manifest.blocks) {
+        if (seen.has(block.type))
+            problems.push(`"${block.type}" is declared twice`);
+        seen.add(block.type);
+        try {
+            resolveManifestFieldMeta(block);
+        }
+        catch (err) {
+            problems.push(`"${block.type}" field metadata does not resolve: ${err.message}`);
+        }
+    }
+    const defaults = validateManifestDefaultProps(manifest.blocks);
+    if (defaults)
+        problems.push(defaults);
+    if (manifest.blocks.length === 0)
+        problems.push("the manifest lists no block types");
+    if (problems.length > 0) {
+        return {
+            check: { id, stage: STAGE, title, status: "fail", detail: problems.join("; "), fix: "Fix the block definitions named above; the editor refuses a manifest it cannot resolve." },
+            manifest,
+        };
+    }
+    return { check: { id, stage: STAGE, title, status: "pass", detail: `${manifest.blocks.length} block types` }, manifest };
+}
+// ── pages ────────────────────────────────────────────────────────────────
+export function checkPages(raw) {
+    const id = "contract.pages";
+    const title = "The page list is well-formed";
+    const list = raw?.pages;
+    if (!Array.isArray(list)) {
+        return { check: { id, stage: STAGE, title, status: "fail", detail: "no `pages` array in the response", fix: "`/api/editor/pages` must answer `{ pages: PageDoc[] }` — wire it to the same content fetcher the site renders from." } };
+    }
+    if (list.length === 0) {
+        return { check: { id, stage: STAGE, title, status: "fail", detail: "the site reports no pages", fix: "An empty page list gives the editor nothing to open. Check the content source (credentials, fixture file, locale) behind getPages." } };
+    }
+    const problems = [];
+    const pages = [];
+    const slugs = new Set();
+    list.forEach((candidate, index) => {
+        const page = candidate;
+        if (!page || typeof page.slug !== "string") {
+            problems.push(`page #${index} has no slug`);
+            return;
+        }
+        if (!page.slug.startsWith("/"))
+            problems.push(`slug "${page.slug}" does not start with "/"`);
+        if (slugs.has(page.slug))
+            problems.push(`slug "${page.slug}" appears twice`);
+        slugs.add(page.slug);
+        if (!Array.isArray(page.blocks)) {
+            problems.push(`${page.slug} has no blocks array`);
+            return;
+        }
+        const ids = new Set();
+        for (const block of page.blocks) {
+            if (!block || typeof block.id !== "string" || !block.id)
+                problems.push(`${page.slug}: a block has no id`);
+            else if (ids.has(block.id))
+                problems.push(`${page.slug}: block id "${block.id}" appears twice — selection and edits address blocks by id`);
+            else
+                ids.add(block.id);
+            if (!block || typeof block.type !== "string" || !block.type)
+                problems.push(`${page.slug}: block ${block?.id ?? "?"} has no type`);
+        }
+        pages.push(page);
+    });
+    if (problems.length > 0) {
+        return {
+            check: { id, stage: STAGE, title, status: "fail", detail: problems.slice(0, 8).join("; ") + (problems.length > 8 ? ` and ${problems.length - 8} more` : ""), fix: "Every page needs a unique leading-slash slug, and every block a type and an id unique within its page." },
+            pages,
+        };
+    }
+    const locales = [...new Set(pages.map((p) => p.locale).filter((l) => typeof l === "string"))];
+    return {
+        check: { id, stage: STAGE, title, status: "pass", detail: `${pages.length} pages${locales.length ? ` in ${locales.length} locales (${locales.join(", ")})` : ""}` },
+        pages,
+    };
+}
+/**
+ * Chrome types — a site header, a footer — are Avocado built-ins the manifest
+ * leaves out on purpose: they are pinned, never added or moved, and the editor
+ * edits them through its own registry. A page holding one is not a gap.
+ */
+export function builtinChromeTypes(builtins = getAllBlockMeta()) {
+    return new Set(Object.entries(builtins).filter(([, meta]) => meta.chrome).map(([type]) => type));
+}
+/** Every block type a page uses that the manifest does not describe, by the slugs that use it. */
+export function unknownBlockTypes(manifest, pages, chrome = builtinChromeTypes()) {
+    const known = new Set(manifest.blocks.map((b) => b.type));
+    const unknown = new Map();
+    for (const page of pages) {
+        for (const block of page.blocks ?? []) {
+            if (!block?.type || known.has(block.type) || chrome.has(block.type))
+                continue;
+            const slugs = unknown.get(block.type) ?? [];
+            if (!slugs.includes(page.slug))
+                slugs.push(page.slug);
+            unknown.set(block.type, slugs);
+        }
+    }
+    return unknown;
+}
+export function checkBlockTypes(manifest, pages, builtins = getAllBlockMeta()) {
+    const id = "contract.block-types";
+    const title = "Every block type on every page is in the manifest";
+    const chrome = builtinChromeTypes(builtins);
+    const unknown = unknownBlockTypes(manifest, pages, chrome);
+    const used = new Set(pages.flatMap((p) => (p.blocks ?? []).map((b) => b.type)));
+    const unused = manifest.blocks.map((b) => b.type).filter((t) => !used.has(t));
+    const chromeUsed = [...used].filter((t) => chrome.has(t) && !manifest.blocks.some((b) => b.type === t));
+    // A built-in the site did not list still edits — the editor has its own
+    // definition — but not necessarily as the site renders it.
+    const fallback = [...unknown].filter(([t]) => t in builtins);
+    const missing = [...unknown].filter(([t]) => !(t in builtins));
+    const list = (entries) => entries.map(([type, slugs]) => `${type} (${slugs.slice(0, 3).join(", ")}${slugs.length > 3 ? ", …" : ""})`).join("; ");
+    if (missing.length > 0) {
+        return {
+            id, stage: STAGE, title, status: "fail",
+            detail: `not in the manifest: ${list(missing)}${fallback.length ? `; built-ins the site does not list: ${fallback.map(([t]) => t).join(", ")}` : ""}`,
+            fix: "The editor cannot render, select or edit a block it has no definition for. Register the type, or map the content to a type that is registered — and after renaming a type, re-pull drafts that still hold the old one.",
+            data: { unknown: Object.fromEntries(unknown), unused },
+        };
+    }
+    if (fallback.length > 0) {
+        return {
+            id, stage: STAGE, title, status: "warn",
+            detail: `Avocado built-ins on pages but not in the site's manifest: ${list(fallback)}`,
+            fix: "The editor falls back to its own definition of these, which may not match what the site renders. Declare them in the site's catalogue if the site renders them.",
+            data: { fallback: fallback.map(([t]) => t), unused },
+        };
+    }
+    return {
+        id, stage: STAGE, title, status: "pass",
+        detail: `${used.size} types in use${chromeUsed.length ? ` (chrome: ${chromeUsed.join(", ")})` : ""}${unused.length ? `; declared but on no page: ${unused.join(", ")}` : ""}`,
+        data: { unused },
+    };
+}
+export function checkPropsAgainstSchema(manifest, pages) {
+    const id = "contract.props-schema";
+    const title = "Block props match their propsSchema";
+    const definitions = new Map(manifest.blocks.map((b) => [b.type, b]));
+    const issues = [];
+    for (const page of pages) {
+        for (const block of page.blocks ?? []) {
+            const definition = definitions.get(block.type);
+            if (!definition)
+                continue;
+            const issue = findManifestSchemaIssue(definition.propsSchema, block.props ?? {});
+            if (issue)
+                issues.push(`${page.slug} ${block.type} (${block.id}): ${issue.path} ${issue.message}`);
+        }
+    }
+    if (issues.length === 0)
+        return { id, stage: STAGE, title, status: "pass", detail: "every block validates" };
+    return {
+        id, stage: STAGE, title, status: "warn",
+        detail: issues.slice(0, 6).join("; ") + (issues.length > 6 ? ` and ${issues.length - 6} more` : ""),
+        fix: "The first edit to such a block is validated against the schema and refused. Make the projection produce what the schema says, or loosen the schema to what the content really holds.",
+        data: { issues },
+    };
+}
+export function checkPanelCoverage(manifest, pages) {
+    const id = "contract.panel-coverage";
+    const title = "The property panel can label and describe every field";
+    const report = panelCoverage(manifest, pages, { builtinTypes: getAllBlockMeta() });
+    const detail = formatPanelCoverage(report);
+    if (report.findings.length === 0) {
+        return { id, stage: STAGE, title, status: "pass", detail: `${report.rowsLabelled}/${report.rowsExamined} list rows labelled`, data: report };
+    }
+    return {
+        id, stage: STAGE, title, status: "warn", detail,
+        fix: "Each finding names the block and path. Declare list-row labels, narrow polymorphic lists (discriminator + itemFieldsByType), describe orphan props or mark them `internal`, and rename types that collide with Avocado's built-ins.",
+        data: report,
+    };
+}
+// ── the draft endpoint ───────────────────────────────────────────────────
+export async function checkDraftEndpoint(state) {
+    const id = "contract.draft-endpoint";
+    const title = "The draft endpoint refuses a bad secret with a 4xx, not a 500";
+    const url = joinUrl(state.options.siteUrl, "/api/editor/draft?secret=avocado-qa-wrong-secret&redirect=/");
+    const result = await request(state.fetch, url, { timeoutMs: state.options.timeoutMs, redirect: "manual" });
+    if (result.status === 0)
+        return { id, stage: STAGE, title, status: "skip", detail: describeFailure(result) };
+    if (result.status >= 500) {
+        return {
+            id, stage: STAGE, title, status: "warn",
+            detail: `${url} → ${describeFailure(result)}`,
+            fix: "A 500 here usually means DRAFT_MODE_SECRET is empty in the process that serves the site (Astro does not copy .env into process.env by itself). Set it where the server reads it.",
+        };
+    }
+    return { id, stage: STAGE, title, status: "pass", detail: `HTTP ${result.status}` };
+}
+// ── manifest.lock ────────────────────────────────────────────────────────
+export function checkManifestLock(state, manifest, now = new Date()) {
+    const id = "contract.manifest-lock";
+    const title = "No block types removed or renamed since the last run";
+    const path = join(state.options.cwd, MANIFEST_LOCK_PATH);
+    const previous = readManifestLock(path);
+    const next = snapshotManifest(manifest, state.options.siteId, now);
+    try {
+        writeManifestLock(path, next);
+    }
+    catch (err) {
+        return { id, stage: STAGE, title, status: "warn", detail: `could not write ${MANIFEST_LOCK_PATH}: ${err.message}`, fix: "Make .avocado/ writable." };
+    }
+    if (!previous) {
+        return { id, stage: STAGE, title, status: "info", detail: `first snapshot written to ${MANIFEST_LOCK_PATH} — commit it, and the next schema change shows up here and in review` };
+    }
+    const diff = diffManifestLocks(previous, next);
+    const breaking = [...diff.removedTypes.map((t) => `type ${t}`), ...diff.removedFields, ...diff.changedKinds];
+    if (breaking.length > 0) {
+        return {
+            id, stage: STAGE, title, status: "warn",
+            detail: `since ${previous.generatedAt}: ${breaking.slice(0, 8).join("; ")}${breaking.length > 8 ? ` and ${breaking.length - 8} more` : ""}` +
+                (diff.addedTypes.length ? `; added ${diff.addedTypes.join(", ")}` : ""),
+            fix: "Block types removed/renamed since last run: drafts holding them will go stale — the preview cannot render them and the editor reports the block as missing from the page. " +
+                "Publish or discard edited drafts before shipping the change, then pull the affected pages fresh (the Studio's \"Pull from site\", or POST /draft/bootstrap with force for those slugs).",
+            data: diff,
+        };
+    }
+    const added = [...diff.addedTypes.map((t) => `type ${t}`), ...diff.addedFields];
+    return {
+        id, stage: STAGE, title, status: "pass",
+        detail: added.length ? `additive changes only: ${added.slice(0, 6).join(", ")}${added.length > 6 ? ", …" : ""}` : "unchanged since the last run",
+        data: diff,
+    };
+}
+// ── the throwaway session ────────────────────────────────────────────────
+/**
+ * Fill a throwaway session with pages. `force`, because the session is ours and
+ * nothing in it is anybody's work; the user's own session is never named here.
+ */
+export async function seedSession(state, pages, session = state.options.session) {
+    const id = "contract.seed-session";
+    const title = `Throwaway session ${session} seeded from the site's pages`;
+    const { options } = state;
+    const result = await request(state.fetch, joinUrl(options.orchestratorUrl, "/draft/bootstrap"), {
+        method: "POST",
+        headers: orchestratorHeaders(state),
+        timeoutMs: options.timeoutMs,
+        body: { session, siteId: options.siteId, pages, overwrite: true, force: true },
+    });
+    const body = result.json;
+    if (!result.ok || !body || body.status !== "bootstrapped") {
+        return {
+            id, stage: STAGE, title, status: "fail",
+            detail: `POST /draft/bootstrap → ${body?.error ?? describeFailure(result)}`,
+            fix: "Stage 3 renders from this session. Check the orchestrator accepts the site's pages (a 409 means the site is registered at a different origin than --site).",
+        };
+    }
+    if (session === options.session)
+        state.seeded = true;
+    const count = body.count ?? pages.length;
+    if (count < pages.length) {
+        const kept = new Set(body.slugs ?? []);
+        const dropped = pages.map((p) => p.slug).filter((slug) => !kept.has(slug));
+        return {
+            id, stage: STAGE, title, status: "warn",
+            detail: `the orchestrator accepted ${count} of ${pages.length} pages; dropped: ${dropped.slice(0, 6).join(", ")}${dropped.length > 6 ? ", …" : ""}`,
+            fix: "A page the orchestrator's PageDoc schema rejects is silently left out of every session — the editor cannot open it. Give each page an id, a slug and a blocks array of { id, type, props }.",
+        };
+    }
+    return { id, stage: STAGE, title, status: "pass", detail: `${count} pages` };
+}
+export async function runContract(state) {
+    const { options } = state;
+    const checks = [];
+    if (!state.siteReachable) {
+        return [{ id: "contract.manifest", stage: STAGE, title: "The block manifest is valid", status: "skip", detail: "the site is not reachable" }];
+    }
+    const siteQuery = `?siteId=${encodeURIComponent(options.siteId)}`;
+    const [blocksResult, pagesResult] = await Promise.all([
+        request(state.fetch, joinUrl(options.siteUrl, `/api/editor/blocks${siteQuery}`), { timeoutMs: options.timeoutMs }),
+        request(state.fetch, joinUrl(options.siteUrl, `/api/editor/pages${siteQuery}`), { timeoutMs: Math.max(options.timeoutMs, 60_000) }),
+    ]);
+    if (!blocksResult.ok || blocksResult.json === undefined) {
+        checks.push({
+            id: "contract.manifest", stage: STAGE, title: "The block manifest is valid", status: "fail",
+            detail: `/api/editor/blocks → ${describeFailure(blocksResult)}`,
+            fix: "Mount the editor API: app/api/editor/[...path]/route.ts with createEditorApiHandler (Next), or src/pages/api/editor/[...path].ts (Astro).",
+        });
+    }
+    else {
+        const { check, manifest } = checkManifest(blocksResult.json);
+        checks.push(check);
+        state.manifest = manifest;
+    }
+    if (!pagesResult.ok || pagesResult.json === undefined) {
+        checks.push({
+            id: "contract.pages", stage: STAGE, title: "The page list is well-formed", status: "fail",
+            detail: `/api/editor/pages → ${describeFailure(pagesResult)}`,
+            fix: "`/api/editor/pages` must answer `{ pages }`. A 500 here is usually the content source (credentials, a query the CMS rejects) — render every page after seeding, not only the home page.",
+        });
+    }
+    else {
+        const { check, pages } = checkPages(pagesResult.json);
+        checks.push(check);
+        state.pages = pages;
+    }
+    checks.push(await checkDraftEndpoint(state));
+    const { manifest, pages } = state;
+    if (!manifest || !pages)
+        return checks;
+    checks.push(checkBlockTypes(manifest, pages));
+    checks.push(checkPropsAgainstSchema(manifest, pages));
+    checks.push(checkPanelCoverage(manifest, pages));
+    checks.push(checkManifestLock(state, manifest));
+    if (!state.orchestratorReachable) {
+        checks.push({ id: "contract.seed-session", stage: STAGE, title: "Throwaway session seeded", status: "skip", detail: "the orchestrator is not reachable" });
+        return checks;
+    }
+    // The site's own pages, unmodified: stage 3 measures what a person will see.
+    // Fixtures go into sessions of their own (see fixtures.ts).
+    checks.push(await seedSession(state, pages));
+    return checks;
+}