@yargote/artifacts-cli 0.1.0-beta.6 → 0.1.0-beta.7

package/README.md

@@ -11,9 +11,9 @@ Use Node 24 or later. The beta targets macOS and Linux. Windows has not been ver
 Choose one persistent installation:
 
 ```sh
-npm install --global @yargote/artifacts-cli@0.1.0-beta.6
+npm install --global @yargote/artifacts-cli@0.1.0-beta.7
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.6
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.7
 artifacts --version
 ```
 
@@ -22,18 +22,18 @@ If pnpm reports that no global bin directory exists, run `pnpm setup` and reopen
 For one-off execution, pin the same version:
 
 ```sh
-npx --yes @yargote/artifacts-cli@0.1.0-beta.6 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.6 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.7 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.7 --help
 ```
 
 `@beta` follows future prereleases. Exact versions remain reproducible. No stable `latest` release is part of this beta. An organization's pnpm minimum release age or trust policy can delay a new release. Follow that policy rather than disabling it globally.
 
 ## Complete first use
 
-An existing Artifacts account is required. Select the complete OAuth resource, including `/mcp`:
+An existing Artifacts account is required. Select the REST OAuth resource, which is the API origin without `/mcp`. When upgrading an older deployment, complete the [API migration](../../docs/deployment.md#migrate-the-api-hostname) before using the address below.
 
 ```sh
-export ARTIFACTS_SERVER='https://artifacts-mcp.yersonargotev.workers.dev/mcp'
+export ARTIFACTS_SERVER='https://artifacts-api.yersonargotev.workers.dev'
 artifacts login
 artifacts whoami
 ```
@@ -82,7 +82,9 @@ Run `artifacts logout` before uninstalling if you want to clear credentials. Uni
 
 Skills, help, and version commands work without a server or login. Skills commands do not read credentials or create private state. They accept and ignore global `--server` and `--state-dir` values, including their environment defaults.
 
-`--server RESOURCE` selects the exact canonical OAuth resource. `ARTIFACTS_SERVER` supplies the same value. A resource ending in `/mcp` uses REST under `/mcp/v1`. The CLI has no production default.
+`--server RESOURCE` selects the exact canonical REST OAuth resource. `ARTIFACTS_SERVER` supplies the same value. Use the configured `API_URL` origin to call REST under `/v1`. The CLI has no production default and does not rewrite the supplied URL. Older deployments without `API_URL` still use their complete MCP resource and routes under `/mcp/v1`.
+
+A hostname change requires a new `artifacts login --server RESOURCE`. Credentials and retained operations remain bound to their exact original resource. Do not move an old operation file to the new resource or redirect its bearer requests.
 
 `--state-dir DIR` overrides `ARTIFACTS_STATE_DIR`. The default is `~/.local/state/artifacts`. The state directory must be private and owned by the current user. Credentials are separate from operation files. Profiles bind credentials to the exact resource. Retained operation paths hash the resource and request ID, so request IDs cannot select filesystem paths.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.7",
   "private": false,
   "type": "module",
   "description": "Command-line client for the Artifacts REST API.",
@@ -27,8 +27,8 @@
     "skills"
   ],
   "dependencies": {
-    "@yargote/artifacts-contracts": "0.1.0-beta.6",
-    "@yargote/artifacts-client": "0.1.0-beta.6",
+    "@yargote/artifacts-contracts": "0.1.0-beta.7",
+    "@yargote/artifacts-client": "0.1.0-beta.7",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },

package/skills/artifacts-cli/SKILL.md

@@ -17,11 +17,11 @@ Run `artifacts whoami` before the first mutation when the current identity is no
 
 A revision is a complete snapshot with `metadata`, `content`, and `files`. The command reference contains its JSON shape. Use the requested title, language, content, and attachments. Do not include unrelated files or credentials.
 
-Use self-contained HTML for interactive content. Inline styles and scripts and embed required assets as data URLs. External requests, CDN dependencies, relative executable assets, forms, browser storage, and multi-file websites are unsupported. Attachments are downloads, not importable website resources. Markdown and text display inertly.
+Use self-contained HTML for interactive content. For several HTML boards in one canvas, use `design` and follow the design skill's `references/canvas.md`. Inline styles and scripts and embed required assets as data URLs. External requests, CDN dependencies, relative executable assets, forms, browser storage, and multi-file websites are unsupported. Attachments are downloads, not importable website resources. Markdown and text display inertly.
 
 Keep the whole revision within 1 MiB of decoded content, metadata, attachment paths, media types, and attachment bytes. At most 32 attachments are accepted. Base64 changes wire size, not the decoded limit. If required content exceeds a limit, explain the constraint without silently removing it.
 
-Before writing or restyling HTML, run `artifacts skills get artifacts-design --full` and follow it. It owns typography, embedded fonts, color, layout, and the rendered checks. Finish those checks before saving when browser tools are available. A successful CLI write proves persistence, not visual quality or browser compatibility. Interactive HTML follows the server's Chrome policy; do not promise it in every browser.
+Before writing or restyling HTML or design boards, run `artifacts skills get artifacts-design --full` and follow it. It owns typography, embedded fonts, color, layout, and the rendered checks. Finish those checks before saving when browser tools are available. A successful CLI write proves persistence, not visual quality or browser compatibility. Interactive HTML follows the server's Chrome policy; do not promise it in every browser.
 
 ## Create or revise
 
@@ -63,10 +63,12 @@ A `request_conflict` means the ID was used with different arguments. Do not desc
 
 ## Verify and deliver
 
-After create or update, read the explicit returned revision. Use `read ARTIFACT_ID --revision REVISION_ID --out FILE --quiet` to retain the full response without printing its snapshot. Check that the installed `--help` supports `--quiet` first. For older versions, use the command workflow's stdout redirection fallback. Compare the saved complete metadata, content, and decoded attachment bytes with the intended snapshot. For an update, check that its parent is the head used for preparation. Compact responses cannot verify omitted content.
+Retain successful create, update, or edit stdout in a private receipt file. After create or update, read the explicit returned revision. Use `read ARTIFACT_ID --revision REVISION_ID --out FILE --quiet` to retain the full response without printing its snapshot. Check that the installed `--help` supports `--quiet` first. For older versions, use the command workflow's stdout redirection fallback. Compare the saved complete metadata, content, and decoded attachment bytes with the intended snapshot. For an update, check that its parent is the head used for preparation. Compact responses cannot verify omitted content.
 
 After publication, read current publication and compare revision, version, and URL with the committed result. A replayed receipt describes the original commit; another writer may have changed the current publication afterward. Report that difference.
 
+For real panel and requested protected-publication checks, follow [the exact saved revision recipe](references/verify-retained.md). It prepares the existing verifier inputs from the write receipt and independent full read. It also gives an installed-browser route when the complete verifier runtime is unavailable. Report persistence, local rendering, panel rendering, and protected publication separately. Input preparation is not a browser pass.
+
 Follow list and history cursors when the request needs more than the first page. Export an explicit retained revision to the requested destination. The CLI checks the archive digest. Confirm that the file exists and inspect its manifest and relevant content before linking it.
 
 Report the title, saved revision, and draft or published state in the user's language. Link the actual export or returned protected publication URL. Distinguish persistence from any visual or browser checks that did not run. Keep local credential and session identifiers private.

package/skills/artifacts-cli/references/commands.md

@@ -61,7 +61,7 @@ Save this JSON as `snapshot.json`, replacing its content with the requested arti
 }
 ```
 
-`metadata.description` and `files` are required even when empty. Content kind is `html`, `markdown`, or `text`. Binary files use `encoding: "base64"` and canonical padded base64. Paths are unique normalized relative paths. Do not use empty, dot, parent, absolute, backslash, percent, or colon path segments. A file cannot also be another file's directory.
+`metadata.description` and `files` are required even when empty. Content kind is `html`, `markdown`, `text`, or `design`. Binary files use `encoding: "base64"` and canonical padded base64. Paths are unique normalized relative paths. Do not use empty, dot, parent, absolute, backslash, percent, or colon path segments. A file cannot also be another file's directory.
 
 ```sh
 artifacts create --snapshot snapshot.json
@@ -75,6 +75,20 @@ For `read`, `--out FILE --quiet` saves the returned response without printing su
 
 Check installed help for `--quiet` support before running these examples. Older versions, including `0.1.0-beta.1`, can suppress stdout with `artifacts read ARTIFACT_ID --out saved.json > /dev/null`. This redirection preserves stderr and the command's exit status. Use the same fallback for the revision reads below.
 
+## Prepare a design canvas
+
+Read the design skill's `references/canvas.md` through `artifacts skills get artifacts-design --full`. Keep the index in `my-canvas/canvas.json` and complete UTF-8 board documents in `my-canvas/boards/*.html`.
+
+```sh
+artifacts skills path artifacts-cli
+node <returned-skill-directory>/scripts/prepare-retained.mjs ./my-canvas > snapshot.json
+artifacts create --snapshot snapshot.json
+```
+
+The positional form accepts exactly one directory. It preserves the index text and board HTML, sorts snapshot files by path, validates the complete `design` snapshot with the installed contracts, and rejects missing or orphan boards. It uses the directory basename as the title and an empty description. Edit the emitted metadata before saving when needed. Keep the script under the path returned by `skills path` so its package dependencies resolve. All board data, embedded fonts, index text, and metadata share the 1 MiB budget.
+
+The existing named-option form of `prepare-retained.mjs` builds a private retained-verification config from saved receipts and an independent read. It does not prepare a content snapshot. The two input forms cannot be combined.
+
 ## Organize projects
 
 Check that installed help lists `projects` and `move` before using them.
@@ -179,6 +193,10 @@ Share with `--notify` to request one email attempt. Access succeeds when mail is
 
 Owners can reserve 100 invitations per UTC day. Revoke, deletion, and failed delivery do not refund reservations. New access is limited to 100 people per artifact and 1000 grants per owner. Existing access remains listable and revocable.
 
+## Verify the exact saved revision
+
+Follow [the retained revision recipe](verify-retained.md) after successful authoring and requested publication. Retain each successful write stdout in a private receipt file. The recipe extracts its IDs, performs a full independent explicit-revision read, and prepares the existing verifier config without authoring or account mutations. It includes an installed-browser path and identifies the additional capabilities for complete verification.
+
 ## Retry and export
 
 ```sh

package/skills/artifacts-cli/references/verify-retained.md

@@ -0,0 +1,119 @@
+# Verify the saved revision in the panel
+
+Use the successful create, update, or edit result and an independent full read to select the exact saved revision. Use an authorized browser session to inspect its real panel and, when requested, its protected publication. Preparation alone does not prove persistence or browser behavior.
+
+## Retain the authoring results
+
+Before the authorized write, use `umask 077` and save successful stdout to a new private receipt file. For example, add `> write-result.json` to the create or update command you already intend to run. Keep stderr and the retained request ID for recovery. Continue only after exit zero. Do not repeat a write to obtain a receipt after an uncertain response. Follow [retry recovery](commands.md#retry-and-export).
+
+If publication was requested, also retain the successful publish stdout as `publish-result.json`. Finish that authorized publication before the independent read below. Do not publish, share, or revoke access merely to verify an artifact.
+
+## Prepare the exact selection
+
+Use Node 24+ and a CLI whose help lists `skills path` and `read --quiet`. For older read output, use the [stdout fallback](commands.md#create-a-complete-snapshot). The installed helper requires only Node built-ins. It makes no service request and does not open a browser.
+
+Set `observed_panel_origin` to the panel origin observed in the authorized browser or supplied service configuration. Do not derive it from `ARTIFACTS_SERVER` or the publication host. Replace the example origin before execution.
+
+```sh
+umask 077
+observed_panel_origin=https://panel.example.test
+skill_directory=$(artifacts skills path artifacts-cli)
+artifact_id=$(node -e '
+try {
+	const id = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).artifactId;
+	if (typeof id !== "string" || id.length === 0) throw new Error();
+	process.stdout.write(id);
+} catch {
+	console.error("Cannot extract the artifact ID from the write receipt");
+	process.exitCode = 1;
+}
+' write-result.json)
+revision_id=$(node -e '
+try {
+	const id = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")).revision.id;
+	if (typeof id !== "string" || id.length === 0) throw new Error();
+	process.stdout.write(id);
+} catch {
+	console.error("Cannot extract the revision ID from the write receipt");
+	process.exitCode = 1;
+}
+' write-result.json)
+artifacts read "$artifact_id" --revision "$revision_id" --response full --out saved-read.json --quiet
+```
+
+Stop if any extraction or read fails. A compact write receipt can select a revision. The independent read must contain the complete snapshot. Compare its complete metadata, content, and decoded attachment bytes with the intended snapshot. For an update, check the saved parent against the head used to prepare that update.
+
+Save `checks.json` with the requested viewport sizes and meaningful expectations for this document. Replace the example selectors and values with intended content behavior. Expectations run in order inside the content iframe after a fresh load at each viewport.
+
+```json
+{
+	"viewports": [{ "width": 1440, "height": 900 }, { "width": 390, "height": 844 }],
+	"expectations": [
+		{ "kind": "text", "selector": "#total", "text": "5.00" },
+		{ "kind": "click", "selector": "#change" },
+		{ "kind": "text", "selector": "#total", "text": "28.40" }
+	],
+	"timeoutMs": 10000
+}
+```
+
+Use `text` for exact rendered text, `visible` for visibility, `count` for an element count, or `attribute` for an exact attribute value. Use `name` and `value` with `attribute`. Interactions also support `fill` with `value`, `check` with `checked`, and `select` with a `values` array. Do not use arbitrary JavaScript or target panel controls in these expectations.
+
+Prepare a new private config with a future evidence directory that does not yet exist.
+
+```sh
+node "$skill_directory/scripts/prepare-retained.mjs" \
+  --receipt write-result.json --read saved-read.json \
+  --panel-origin "$observed_panel_origin" --checks checks.json \
+  --evidence "$PWD/new-retained-evidence" --out retained-config.json
+```
+
+When publication was requested, add `--publication-receipt publish-result.json` to that invocation. The helper compares its artifact, revision, version, and URL with the current publication in the saved read. A different publication or concurrent change fails preparation. Report the difference. Do not replace expected versions or publish again to make verification pass.
+
+The helper derives all selected IDs and URLs from these inputs. It accepts a newer draft head while keeping the saved revision pinned and reports `headChanged: true`. It emits `status: "prepared"`, never a verification pass. Without a publication receipt, it omits publication coverage even when another revision is published. Existing output files are preserved.
+
+## Inspect with an authorized browser
+
+This route works with the installed CLI, its bundled files, and browser-control capabilities. It requires no repository checkout. Use a user-supplied session or complete the normal sign-in flow. CLI OAuth login does not supply panel cookies. Keep browser authentication inside the browser. Never extract credentials to construct a Playwright context or state file.
+
+After sign-in setup, perform these read-only checks on the selected artifact. Do not create revisions, publish, share, log out, or revoke sessions. Normal protected-viewer admission can consume its one-use grant through the existing GET handoff.
+
+1. Read `retained-config.json` privately and open its exact `panelUrl`. Compare the artifact, revision, digest, and publication version with `expected`. Current panels expose `data-artifact-id`, `data-revision-id`, `data-revision-sha256`, and `data-publication-version`. Version zero means no publication. Report a newer head separately. Never switch the selected revision to the head.
+2. Establish the actual browser version and available frame, response, console, download, and viewport controls. Record missing capabilities. A browser name, load event, or empty console does not establish that content loaded.
+3. Inspect the actual preview iframe source, pinned revision, sandbox, referrer policy, and dimensions. Wait for a distinctive expected element within the configured deadline. Exercise each authorized content control and record the resulting visible state. Repeat at each available requested viewport and check keyboard interactions and overflow where relevant.
+4. When response inspection or native DevTools is available, inspect the iframe request. Record completion, status, content type, CSP, connection allowlist, cache policy, and DNS policy. Distinguish interactive content, inert fallback, and error responses. A pending request has no final response evidence. A top-level preview navigation deliberately returns 403 and cannot replace this iframe check.
+5. When the config includes `publicationUrl`, open that separate protected viewer through normal admission. Compare its selected revision, digest, and version with `expected`. Observe the real content and repeat the authorized interactions. Open `Archivos` and compare the complete attachment inventory and revision-bound links. Check protected download bytes when that capability is available. Missing attachment or response evidence remains unavailable.
+6. After publication interactions, reread the same explicit revision with the quoted IDs into a new private file. Compare its current `publication.revisionId`, `version`, and `url` with the saved read and publish receipt. Reload the selected panel and compare its publication markers again. Report a changed publication as a concurrent change. Do not report protected-publication success for a different selected revision.
+7. If the frame is blank, distinguish admission, pending transport, policy, browser compatibility, content execution, and browser-control failures from observed evidence. If debugger attachment stalls it, disconnect through normal browser controls, reload the same pinned page, and repeat the interaction with native controls. Preserve authentication and containment. Attribute a debugger failure only when that comparison demonstrates it.
+8. Save a sanitized report and private screenshots. Include selected IDs, digest, browser version, viewport sizes, actions, resulting visible states, observed response policies, and unavailable checks. Exclude cookies, tokens, viewer grants, callback queries, raw authentication requests, and private content from diagnostic logs.
+
+This is partial browser verification. Do not return the complete verifier's pass verdict. Missing exact bytes, ZIP, policy, attachment, console, or viewport evidence must remain explicit.
+
+## Run the existing complete verifier when available
+
+The CLI package does not install Playwright, `tsx`, Chrome, or the repository's verifier and rendering-policy modules. Complete automated verification needs an operator-provided installation of that existing verifier with its dependencies and actual supported Chrome. It also needs an explicitly supplied authenticated Playwright `BrowserContext` or owner-private storage-state file prepared through an approved sign-in flow.
+
+For repository operators, run this command from the repository root. The paths in this command are repository capabilities, not paths inside an installed CLI package.
+
+```sh
+node --import tsx .agents/skills/verify-artifacts/scripts/verify-retained.ts \
+  --config /private/path/retained-config.json \
+  --storage-state /private/path/browser-state.json
+```
+
+Pass the prepared config unchanged. The existing verifier validates the full schema and canonical snapshot hash. It checks pinned responses, markers, policies, interactions, ZIP, attachment bytes, viewports, and publication state before and after viewer checks. It writes private evidence and fails on mismatches or concurrent publication changes. Use its callable `verifyRetainedArtifact(context, config)` when an authorized context is supplied. Do not build another viewer or weaken sandbox policies to establish deployed behavior.
+
+If this runtime or authenticated input is unavailable, use the partial route above and name that limit. If browser access is unavailable too, report only the persistence checks actually completed.
+
+## Deliver the observed outcomes
+
+Report each outcome separately, with its evidence and missing checks.
+
+| Outcome | Evidence needed |
+| --- | --- |
+| Persistence | Full independent explicit-revision read and complete intended-snapshot comparison. Name any exact export check separately. |
+| Local rendering | Observed local document layout and interactions. This does not prove hosted rendering. |
+| Panel rendering | Exact real panel selection, pinned iframe, visible content, and observed interaction. Name missing response, policy, byte, console, or viewport checks. |
+| Protected publication | Separate authorized viewer admission for the selected published revision, visible content, interactions, and attachment checks. Report concurrent changes and unavailable checks. |
+
+Use `passed`, `failed`, `unavailable`, or `not requested` for each outcome as the evidence permits. Keep session identifiers and private evidence private. A successful helper invocation establishes only input preparation.

package/skills/artifacts-cli/scripts/prepare-retained.mjs

@@ -0,0 +1,149 @@
+import { lstat, readFile, readdir, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+function requireValue(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function object(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function prepareRetainedSelection({ receipt, expected, checks, panelOrigin, evidenceDirectory, publicationReceipt }) {
+  requireValue(object(receipt) && object(receipt.revision), 'Write receipt must identify a saved revision');
+  requireValue(
+    typeof receipt.artifactId === 'string' && receipt.artifactId.length > 0 &&
+    typeof receipt.revision.id === 'string' && receipt.revision.id.length > 0 &&
+    /^[a-f0-9]{64}$/.test(receipt.revision.sha256),
+    'Write receipt must contain artifact, revision, and SHA-256',
+  );
+  const snapshot = expected?.revision?.snapshot;
+  requireValue(
+    object(expected) && object(snapshot) && object(snapshot.metadata) &&
+    typeof snapshot.metadata.title === 'string' && typeof snapshot.metadata.description === 'string' &&
+    object(snapshot.content) && ['html', 'markdown', 'text', 'design'].includes(snapshot.content.kind) &&
+    typeof snapshot.content.text === 'string' && Array.isArray(snapshot.files),
+    'Independent read must contain the full snapshot, not a compact response',
+  );
+  requireValue(expected.artifactId === receipt.artifactId && expected.revision.id === receipt.revision.id && expected.revision.sha256 === receipt.revision.sha256, 'Independent read differs from the saved write receipt');
+  requireValue(typeof expected.headRevisionId === 'string' && expected.headRevisionId.length > 0, 'Independent read must identify its current draft head');
+  requireValue(object(checks) && Object.keys(checks).every((key) => ['viewports', 'expectations', 'timeoutMs'].includes(key)) && Array.isArray(checks.viewports) && checks.viewports.length > 0 && Array.isArray(checks.expectations), 'Checks must contain viewports and expectations, with optional timeoutMs');
+  let panel;
+  try { panel = new URL(panelOrigin); } catch { throw new Error('Panel origin must be an observed HTTP origin'); }
+  requireValue(['http:', 'https:'].includes(panel.protocol) && !panel.username && !panel.password && panel.pathname === '/' && !panel.search && !panel.hash, 'Panel origin must be an observed HTTP origin without a path, credentials, query, or fragment');
+  panel.pathname = `/artifacts/${encodeURIComponent(expected.artifactId)}`;
+  panel.searchParams.set('revisionId', expected.revision.id);
+  let publicationUrl;
+  if (publicationReceipt !== undefined) {
+    const current = expected.publication;
+    requireValue(
+      object(publicationReceipt) && object(current) &&
+      publicationReceipt.artifactId === expected.artifactId &&
+      publicationReceipt.revisionId === expected.revision.id && publicationReceipt.revisionId === current.revisionId &&
+      Number.isInteger(publicationReceipt.version) && publicationReceipt.version > 0 && publicationReceipt.version === current.version &&
+      typeof publicationReceipt.url === 'string' && publicationReceipt.url === current.url,
+      'Publication differs from the requested receipt or selected revision; report the changed or different publication',
+    );
+    let publication;
+    try { publication = new URL(current.url); } catch { throw new Error('Publication receipt must contain a stable HTTP URL'); }
+    requireValue(['http:', 'https:'].includes(publication.protocol) && !publication.username && !publication.password && !publication.search && !publication.hash && publication.pathname === `/a/${encodeURIComponent(expected.artifactId)}`, 'Publication receipt must contain the selected artifact stable HTTP URL');
+    publicationUrl = publication.href;
+  }
+  return {
+    expected,
+    panelUrl: panel.href,
+    ...(publicationUrl === undefined ? {} : { publicationUrl }),
+    ...checks,
+    evidenceDirectory: resolve(evidenceDirectory),
+  };
+}
+
+async function canvasContracts() {
+  const name = '@yargote/artifacts-contracts';
+  let path;
+  try { path = createRequire(import.meta.url).resolve(name); }
+  catch (error) {
+    if (error.code !== 'MODULE_NOT_FOUND') throw error;
+    path = createRequire(new URL('../../../apps/cli/package.json', import.meta.url)).resolve(name);
+  }
+  return import(pathToFileURL(path).href);
+}
+
+async function prepareCanvasDirectory(input) {
+  const directory = resolve(input);
+  requireValue((await lstat(directory)).isDirectory(), 'Canvas input must be a directory');
+  const { canvasIndexSchema, snapshotSchema } = await canvasContracts();
+  const indexFile = join(directory, 'canvas.json');
+  const indexInfo = await lstat(indexFile);
+  requireValue(indexInfo.isFile(), 'canvas.json must be a regular file');
+  requireValue(indexInfo.size <= 1_048_576, 'canvas.json exceeds the shared 1 MiB revision budget');
+  const indexBytes = await readFile(indexFile);
+  const text = indexBytes.toString('utf8');
+  requireValue(Buffer.from(text, 'utf8').equals(indexBytes), 'canvas.json must contain valid UTF-8');
+  const index = canvasIndexSchema.parse(JSON.parse(text));
+  const boardDirectory = join(directory, 'boards');
+  requireValue((await lstat(boardDirectory)).isDirectory(), 'boards must be a directory, not a symbolic link');
+  const entries = await readdir(boardDirectory, { withFileTypes: true });
+  for (const entry of entries) {
+    const path = `boards/${entry.name}`;
+    requireValue(entry.isFile(), `Canvas board ${path} must be a regular file`);
+    requireValue(Object.hasOwn(index.boards, path), `Orphan canvas board ${path} is absent from canvas.json`);
+  }
+  const files = [];
+  for (const path of [...index.order].sort()) {
+    const filename = join(directory, path);
+    let info;
+    try { info = await lstat(filename); }
+    catch (error) {
+      if (error.code === 'ENOENT') throw new Error(`Canvas board ${path} has no matching file`);
+      throw error;
+    }
+    requireValue(info.isFile(), `Canvas board ${path} must be a regular file`);
+    requireValue(info.size <= 1_048_576, `Canvas board ${path} exceeds the shared 1 MiB revision budget`);
+    const bytes = await readFile(filename);
+    const data = bytes.toString('utf8');
+    requireValue(Buffer.from(data, 'utf8').equals(bytes), `Canvas board ${path} must contain valid UTF-8`);
+    files.push({ path, mediaType: 'text/html', encoding: 'utf8', data });
+  }
+  return snapshotSchema.parse({
+    metadata: { title: basename(directory), description: '' },
+    content: { kind: 'design', text },
+    files,
+  });
+}
+
+const required = ['--receipt', '--read', '--panel-origin', '--checks', '--evidence', '--out'];
+try {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && !args[0].startsWith('--')) {
+    console.log(JSON.stringify(await prepareCanvasDirectory(args[0]), null, 2));
+  } else {
+    const options = new Map();
+    requireValue(args.length % 2 === 0, 'Use named options with one value each');
+    for (let index = 0; index < args.length; index += 2) {
+      const name = args[index];
+      requireValue([...required, '--publication-receipt'].includes(name) && !options.has(name) && typeof args[index + 1] === 'string' && args[index + 1].length > 0, 'Use each supported option once with a nonempty value');
+      options.set(name, args[index + 1]);
+    }
+    requireValue(required.every((name) => options.has(name)), 'Required options are --receipt --read --panel-origin --checks --evidence --out');
+    const json = async (name) => {
+      try { return JSON.parse(await readFile(options.get(name), 'utf8')); }
+      catch { throw new Error(`Cannot read valid JSON for ${name}`); }
+    };
+    const receipt = await json('--receipt');
+    const expected = await json('--read');
+    const checks = await json('--checks');
+    const publication = options.has('--publication-receipt') ? await json('--publication-receipt') : undefined;
+    const config = prepareRetainedSelection({ receipt, expected, checks, panelOrigin: options.get('--panel-origin'), evidenceDirectory: options.get('--evidence'), publicationReceipt: publication });
+    try { await writeFile(options.get('--out'), `${JSON.stringify(config, null, 2)}\n`, { flag: 'wx', mode: 0o600 }); }
+    catch (error) { throw new Error(error?.code === 'EEXIST' ? 'Config output already exists; choose a new output path' : 'Cannot create the private config output'); }
+    const headChanged = expected.headRevisionId !== expected.revision.id;
+    console.log(JSON.stringify({ status: 'prepared', headChanged, publication: publication === undefined ? 'not-requested' : 'requested' }));
+    if (headChanged) console.error('Current draft head differs from the selected saved revision. The selection remains pinned.');
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/skills/artifacts-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: artifacts-design
-description: Design the HTML document of a retained Artifact with embedded fonts, light and dark Catppuccin tokens, purposeful layout, and rendered checks. Use before writing or restyling HTML for the artifacts or artifacts-cli skills.
+description: Design HTML documents and multi-board design canvases of a retained Artifact with embedded fonts, light and dark Catppuccin tokens, purposeful layout, and rendered checks. Use before writing or restyling HTML or design boards for the artifacts or artifacts-cli skills.
 ---
 
 # Design HTML artifacts
@@ -9,6 +9,8 @@ The calling skill owns the snapshot, size limit, and save workflow. This skill o
 
 The document renders in a sandbox that blocks every network request. Fonts, images, and icons load only as `data:` URIs. External stylesheets, Google Fonts links, and CDN scripts silently fail. Inline all CSS and JavaScript.
 
+For multiple boards, read [canvas authoring](references/canvas.md) before writing the index or HTML. It defines the board files, pages, geometry, shared font budget, and complete snapshot workflow.
+
 ## Choose the composition
 
 Before writing HTML, identify the reader's task, the facts and assets available, and what the reader should understand or do first. Use supplied facts. Label illustrative inputs and assumptions, and leave unavailable evidence absent.
@@ -49,7 +51,7 @@ After the HTML file is complete, embed the fonts it names:
 node <skill-directory>/scripts/embed-fonts.mjs page.html
 ```
 
-For the CLI, `<skill-directory>` is the output of `artifacts skills path artifacts-design`. The script rewrites the file in place and is safe to rerun after edits. It embeds only the families the page names and adds italic faces only for `font-style: italic`, `<em>`, `<i>`, or `<cite>`. It refuses to write a page above 1 MiB. Three families add about 135 KB. Newsreader adds about 80 to 165 KB. Do not name another family unless you embed its `woff2` yourself, because an unembedded face silently falls back. Without Node, keep the fallback stacks and report that the fonts were not embedded.
+For the CLI, `<skill-directory>` is the output of `artifacts skills path artifacts-design`. The script rewrites the file in place and is safe to rerun after edits. It selects families from CSS `font-family` and `font` declarations in style elements and inline styles, including referenced custom properties. Comments, content text, and JavaScript strings do not select fonts. It adds italic faces for CSS `font-style: italic`, italic `font` shorthand, or real `<em>`, `<i>`, and `<cite>` elements. It refuses to write a page above 1 MiB. Three families add about 135 KB. Newsreader adds about 80 to 165 KB. Do not name another family unless you embed its `woff2` yourself, because an unembedded face silently falls back. Without Node, keep the fallback stacks and report that the fonts were not embedded.
 
 ## Color
 
@@ -77,6 +79,14 @@ Give the `<title>` a specific name of two to four words, or the name the user al
 
 ## Check the rendered page
 
+Run the local helper after embedding fonts and before saving:
+
+```sh
+node <skill-directory>/scripts/verify-local.mjs page.html --evidence ./page-evidence
+```
+
+For the CLI, resolve `<skill-directory>` with `artifacts skills path artifacts-design`. Read [local checks](references/local-checks.md) for existing runtime requirements, optional declarative control expectations, browser selection, and report fields. The helper never installs a dependency, changes the HTML, saves, publishes, or requires service credentials. Its report proves **renderizado local** and leaves visual review required. It does not verify the retained revision or authenticated publication.
+
 Run the [interface checks](references/interface-checks.md) before saving. They distinguish required checks from visual judgment. Render the finished page at 375 px and 1280 px in both light and dark when browser tools are available. Fix observed failures and repeat the affected checks. Report checks you could not run.
 
 The license notices for bundled fonts and adapted guidance are in [third-party notices](THIRD-PARTY-NOTICES.md).

package/skills/artifacts-design/references/canvas.md

@@ -0,0 +1,100 @@
+# Author a design canvas
+
+Create a retained `design` snapshot when several HTML boards belong in one canvas. Each board is a complete self-contained HTML document. The canvas supplies placement, page selection, notes, pan, zoom, and a focus view. The calling MCP or CLI skill owns saving and publication.
+
+## Compose the boards
+
+1. Choose a frame size for each board. Common starting sizes are 1440 by 900 for desktop, 390 by 844 for a phone, and 768 by 1024 for a tablet. These are authoring conventions, not schema limits.
+2. Place boards in a row with 80 px between their edges. Start another row 120 px below the tallest board in the preceding row. Coordinates are canvas pixels, and boards can use different sizes.
+3. Write each board under `boards/` as one UTF-8 `.html` file. Inline its styles, scripts, images, and fonts. Files retained beside a board are downloads, not relative executable assets.
+4. Apply this skill's typography and Catppuccin tokens inside each board. The canvas ground follows the viewer's light or dark theme independently.
+5. Define `canvas.json` with the exact index below. Keep snapshot metadata outside the index.
+
+```json
+{
+	"v": 1,
+	"boards": {
+		"boards/Desktop.html": { "x": 0, "y": 0, "w": 1440, "h": 900, "title": "Desktop", "page": "overview" },
+		"boards/Phone.html": { "x": 1520, "y": 0, "w": 390, "h": 844, "title": "Phone", "page": "overview" },
+		"boards/Detail.html": { "x": 0, "y": 0, "w": 1440, "h": 900, "title": "Detail", "page": "detail" },
+		"boards/DetailPhone.html": { "x": 1520, "y": 0, "w": 390, "h": 844, "title": "Detail phone", "page": "detail" }
+	},
+	"order": ["boards/Desktop.html", "boards/Phone.html", "boards/Detail.html", "boards/DetailPhone.html"],
+	"notes": {
+		"review": { "x": 0, "y": 1020, "w": 390, "text": "Review both layouts.", "page": "overview" }
+	},
+	"pages": [
+		{ "id": "overview", "name": "Overview" },
+		{ "id": "detail", "name": "Detail" }
+	]
+}
+```
+
+The first page opens initially. Boards and notes without `page` appear on the first page when pages exist. Without pages, every board and note appears together. A page can reuse the coordinates of another page.
+
+## Index reference
+
+The index and its nested entries reject unknown fields. The complete rules are:
+
+| Field | Rule |
+| --- | --- |
+| `v` | Required integer `1`. |
+| `boards` | Required object with at most 32 entries. Every key matches `^boards/[A-Za-z0-9_][A-Za-z0-9_.-]*\.html$`. Names are case-sensitive and flat. |
+| Board `x`, `y` | Required finite numbers from -1,000,000 to 1,000,000 inclusive. Fractions are accepted. |
+| Board `w`, `h` | Required finite numbers from 40 to 8000 inclusive. Fractions are accepted. |
+| Board `title` | Optional string of 1 to 256 characters. The board path is the display fallback. |
+| Board `page` | Optional ID that names a declared page. |
+| `order` | Required array of 1 to 32 board paths. It names every board exactly once and contains no other path. Its order controls rendering. |
+| `notes` | Optional object with at most 200 entries. Each key is an ID. |
+| Note `x`, `y`, `text` | Coordinates use the board coordinate limits. `text` is a required string rendered as escaped text, not HTML. |
+| Note `w`, `page` | Optional width from 40 to 8000 and an optional declared page ID. |
+| `pages` | Optional array of at most 32 objects with required `id` and `name`. IDs are unique. `name` contains 1 to 256 characters. |
+| ID | 1 to 40 ASCII letters, digits, underscores, or hyphens. `__proto__` is rejected. |
+
+Every indexed board has a matching snapshot file with the same `path`, `mediaType: "text/html"`, `encoding: "utf8"`, and the complete HTML in `data`. A snapshot has at most 32 files total, including other retained downloads. The directory preparer rejects every unindexed entry in `boards/`, missing boards, directories, symbolic links, and invalid UTF-8. The snapshot contract itself permits other unindexed attachments.
+
+## Embed fonts within the shared budget
+
+Run the real font helper once for each board after completing its HTML:
+
+```sh
+node <design-skill-directory>/scripts/embed-fonts.mjs my-canvas/boards/Desktop.html
+node <design-skill-directory>/scripts/embed-fonts.mjs my-canvas/boards/Phone.html
+```
+
+For the CLI, resolve `<design-skill-directory>` with `artifacts skills path artifacts-design`. The helper selects bundled Latin font subsets from actual CSS declarations and embeds `data:` WOFF2 faces. It rewrites the board in place and is safe to rerun.
+
+Use one small, consistent selection of bundled families and styles across boards. Each board needs its own embedded font bytes because each iframe is an independent document. A subset cannot be shared through an attachment URL. Three families add about 135 KB per board, so repeated embedding can exhaust the canvas budget. Prefer one family and only the styles the board uses when many boards share one revision. The helper checks one board's 1 MiB limit. The preparer and server check the combined revision.
+
+The shared limit is 1,048,576 decoded bytes. It includes serialized snapshot metadata, UTF-8 index text, every file path and media type, and every decoded file body. Whitespace in `canvas.json` counts. The 1 MiB limit applies to all boards together, not to each board separately.
+
+## Save the canvas
+
+For MCP, send one complete snapshot to `artifacts_create` or `artifacts_update`:
+
+```js
+{
+	metadata: { title: 'Product layouts', description: 'Desktop and phone review.' },
+	content: { kind: 'design', text: JSON.stringify(index) },
+	files: boardPaths.map((path) => ({ path, mediaType: 'text/html', encoding: 'utf8', data: boardHtml[path] }))
+}
+```
+
+Here `index`, `boardPaths`, and `boardHtml` come from your completed source files. Read the saved revision back through `artifacts_read` before reporting persistence.
+
+For the CLI, keep `canvas.json` and `boards/*.html` in one directory. Run the bundled preparer:
+
+```sh
+node <cli-skill-directory>/scripts/prepare-retained.mjs ./my-canvas > snapshot.json
+artifacts create --snapshot snapshot.json
+```
+
+Resolve `<cli-skill-directory>` with `artifacts skills path artifacts-cli`. Use the script at that returned path so its installed contracts dependency resolves. The preparer preserves the index text and board HTML and sorts snapshot files by path. Canvas rendering still follows `order`. It emits a validated snapshot on stdout, uses the directory basename as `metadata.title`, and sets `metadata.description` to `""`. Edit those metadata fields in the emitted JSON before saving when the task calls for a specific title or description. The directory form accepts exactly one positional argument. The named-option form prepares retained-verification configuration and keeps its separate contract.
+
+## Check the retained canvas
+
+Open the exact saved revision in the authenticated panel. Confirm all boards fit on the initial page, select each page, and open a board through its name button. Focus view shows that board at its declared width and height and enables its controls. **Volver al lienzo** returns to the prior pan and zoom. Escape also returns when a canvas control has keyboard focus. After interacting inside a board, use **Volver al lienzo** to return. For Escape, first use Shift+Tab to move focus back to the canvas controls. Embedded boards remain inert in the overview.
+
+Check publication through the protected URL returned by `artifacts_publish`. In unsupported browsers, the canvas displays an inert listing of board source. Rendering uses nested opaque `srcdoc` iframes with `sandbox="allow-scripts"` and the existing content policy. Board scripts can still consume renderer time or briefly perturb focus. The canvas is not an absolute keyboard isolation boundary.
+
+Export retains the index as `content.json` and boards as `files/boards/*.html`. To recreate a snapshot, use the manifest's `metadata`, preserve `content.json` as `content.text`, and reconstruct each file using its declared encoding. The ZIP manifest sorts files by path, matching the directory preparer. Snapshot digests preserve the original `files` array order, so keep that order from an independent saved read when comparing digests after recreation. A directory preparer also derives new metadata. Restore the manifest metadata and original file order before comparing snapshot digests.

package/skills/artifacts-design/references/local-checks.md

@@ -0,0 +1,70 @@
+# Check local HTML before saving
+
+Run the helper after embedding fonts and before the calling skill's create or update operation.
+
+```sh
+design_skill=$(artifacts skills path artifacts-design)
+node "$design_skill/scripts/verify-local.mjs" page.html --evidence ./page-evidence
+```
+
+The helper needs Node 24+, an existing `playwright` or `playwright-core` package, and Chrome or Chromium 152+. It resolves the package from the current project first, then from its own installation. It tries existing Playwright browser binaries and system executables. To select an existing browser explicitly, add `--browser /absolute/path/to/chromium`. An explicit selection does not fall back to another executable.
+
+Missing dependencies, incompatible versions, and launch failures produce actionable diagnostics. The helper never installs software, downloads a browser, disables browser sandboxing, or relaxes document policies.
+
+## Describe controls
+
+Add `--expectations checks.json` to replay actions and assert their results. Each matrix case starts with a fresh document. Steps run in order. A failed step ends that case's sequence because later steps may depend on it. The remaining cases still run.
+
+```json
+{
+  "expectations": [
+    { "kind": "visibleCount", "selector": ".mobile-map, .desktop-map", "count": 1 },
+    { "kind": "visible", "selector": ".mobile-map", "visible": true, "when": { "width": 375 } },
+    { "kind": "visible", "selector": ".desktop-map", "visible": true, "when": { "width": 1280 } },
+    { "kind": "text", "selector": "#total", "text": "5.00" },
+    { "kind": "click", "selector": "#calculate" },
+    { "kind": "text", "selector": "#total", "text": "28.40" },
+    { "kind": "press", "selector": "#reset", "key": "Enter" },
+    { "kind": "text", "selector": "#total", "text": "5.00" }
+  ]
+}
+```
+
+Every step requires `kind` and a Playwright locator `selector`. Optional `when` limits it to `width` of 375 or 1280, `theme` of `light` or `dark`, or both. Unknown fields and malformed values fail configuration validation.
+
+| Kind | Additional fields | Observable result |
+| --- | --- | --- |
+| `text` | `text`, a string | Exact inner text of one element. Add a `visible` check when visibility is required. |
+| `count` | `count`, a nonnegative integer | Number of matching elements. |
+| `visible` | `visible`, a boolean | Visibility of exactly one matching element. A missing element fails. |
+| `visibleCount` | `count`, a nonnegative integer | Number of visible matches. Use one selector matching both responsive variants to assert exclusivity. |
+| `attribute` | `name`, a nonempty string, and `value`, a string or `null` | Exact attribute value. `null` requires absence. |
+| `click` | None. | Real pointer activation. |
+| `press` | `key`, a Playwright key string such as `Enter`, `Space`, or `Tab` | Keyboard input to the selected element. |
+| `fill` | `value`, a string | Input or textarea edit. |
+| `check` | `checked`, a boolean | Checkbox or radio state. |
+| `select` | `values`, an array of strings | Selected option values. |
+
+Assertions poll for their expected result. Actions wait for Playwright's actionability checks. The JSON document accepts at most 100 steps and an optional `timeoutMs` from 100 to 30000. Its default is 3000 ms per expectation. With no expectations file, the helper checks rendering and errors but does not infer the document's intended controls.
+
+Each variant also has a total deadline of `timeoutMs * (step count + 1)`, bounded between 10 and 60 seconds. The deadline includes loading, checks, captures, and final observations. If the renderer stops responding, the helper closes that variant's context, records `deadline.exceeded`, and marks its remaining evidence incomplete. The other variants still run. A deadline failure cannot pass the automatic checks.
+
+## Inspect the evidence
+
+The helper creates a fresh `local-*` subdirectory under `--evidence`. It writes `report.json`, `index.md`, and PNG images. Repeated runs keep separate evidence.
+
+The fixed matrix is 375 and 1280 px wide at 900 px high, each in light and dark. Every case checks document overflow before and after its scenario, runtime exceptions, error console entries, and forbidden resource attempts. CSP violations include resource attempts blocked before a browser request occurs. Initial and final captures scroll the actual iframe in viewport-sized steps. Each phase saves at most 12 tiles. Capture records include actual scroll offsets and mark incomplete coverage in `captureCoverage.truncated`.
+
+The document runs in an opaque-origin iframe with `sandbox="allow-scripts"`. Its response uses the Artifacts preview CSP, `Connection-Allowlist: ()`, and disabled DNS prefetching. Fonts, images, and media must be embedded as `data:` URIs. Network connections, remote scripts, frames, objects, forms, and workers remain blocked. The local server exposes only the generated wrapper and content, without arbitrary filesystem access. Browser request routing also denies other destinations.
+
+The report records the chosen executable, version, user agent, rejected browser candidates, source hashes before and after verification, actual content response policy and hash, per-case checks, errors, and screenshots. It identifies the evidence as **renderizado local** and leaves `authenticatedPublication` as `not-verified`. It does not modify the HTML, save a revision, publish, or contact the Artifacts service. No service credentials are required.
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Automatic checks passed. Visual review remains required. |
+| 1 | An automatic check failed. |
+| 2 | Setup or configuration blocked the run. |
+
+A structured blocked report is written when a valid evidence destination is available. The helper prints the report as JSON on standard output.
+
+Read the screenshots and the [interface checks](interface-checks.md) before accepting the design. Check content fidelity, reading order, labels, focus, alignment, density, and both themes. A clean console cannot establish those judgments. Each run observes load, font readiness, its declared interactions, and a short settling period. Delayed behavior beyond the run and content outside captured coverage require further inspection. Verify the retained revision and protected publication separately through the service workflow after saving.

package/skills/artifacts-design/scripts/embed-fonts.mjs

@@ -14,7 +14,208 @@ const faces = [
   { family: 'Newsreader', style: 'italic', weight: '400 700', file: 'newsreader-italic.woff2' },
 ];
 const limit = 1024 * 1024;
-const embedded = /<style data-artifacts-fonts>[\s\S]*?<\/style>\n?/;
+
+function htmlTypographySources(page) {
+  const sources = [];
+  const managed = [];
+  const tags = /<!--[\s\S]*?(?:-->|$)|<![^>]*>|<\/?([a-z][a-z0-9:-]*)(?=[\s/>])(?:[^"'<>]|"[^"]*"|'[^']*')*>/gi;
+  let italic = false;
+  let anchor;
+  let head;
+  let match;
+  while ((match = tags.exec(page))) {
+    const [tag, name] = match;
+    if (tag.startsWith('<!--')) continue;
+    if (/^<!doctype\b/i.test(tag)) head ??= tags.lastIndex;
+    if (!name || tag.startsWith('</')) continue;
+    const lower = name.toLowerCase();
+    if (lower === 'head') head = tags.lastIndex;
+    const attributes = new Map();
+    const attribute = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+    const entities = { quot: '"', apos: "'", amp: '&', lt: '<', gt: '>', sol: '/' };
+    for (const entry of tag.slice(name.length + 1, -1).matchAll(attribute)) {
+      const key = entry[1].toLowerCase();
+      const value = (entry[2] ?? entry[3] ?? entry[4] ?? '').replace(/&(#(?:[xX][\da-fA-F]+|\d+));?|&(quot|QUOT|apos|amp|AMP|lt|LT|gt|GT|sol);/g, (entity, numeric, named) => {
+        if (named) return entities[named.toLowerCase()];
+        const code = numeric[1].toLowerCase() === 'x' ? parseInt(numeric.slice(2), 16) : Number(numeric.slice(1));
+        return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : '\ufffd';
+      });
+      if (!attributes.has(key)) attributes.set(key, value);
+    }
+    if (attributes.has('style')) sources.push({ css: attributes.get('style'), inline: true });
+    if (['em', 'i', 'cite'].includes(lower)) italic = true;
+    if (lower === 'plaintext') break;
+    if (['style', 'script', 'textarea', 'title', 'xmp', 'iframe', 'noembed', 'noframes'].includes(lower)) {
+      const close = new RegExp(`</${lower}\\s*>`, 'gi');
+      close.lastIndex = tags.lastIndex;
+      const end = close.exec(page);
+      const contentEnd = end?.index ?? page.length;
+      if (lower === 'style') {
+        if (attributes.has('data-artifacts-fonts')) {
+          let after = end ? close.lastIndex : page.length;
+          if (page[after] === '\n') after++;
+          managed.push([match.index, after]);
+        } else if (!attributes.get('type') || /^text\/css$/i.test(attributes.get('type'))) {
+          anchor ??= match.index;
+          sources.push({ css: page.slice(tags.lastIndex, contentEnd), inline: false });
+        }
+      }
+      tags.lastIndex = end ? close.lastIndex : page.length;
+    }
+  }
+  return { sources, managed, italic, insertionAt: anchor ?? head ?? 0 };
+}
+
+function cssDeclarations(css, inline) {
+  const declarations = [];
+  const blocks = [];
+  let segment = '';
+  let quote = '';
+  let parentheses = 0;
+  let brackets = 0;
+  let valueBraces = 0;
+  function emit() {
+    const match = /^\s*(--[\w-]+|[-a-z]+)\s*:\s*([\s\S]*)$/i.exec(segment);
+    if (match && (inline || blocks.length) && !blocks.includes(true)) {
+      declarations.push({ property: match[1].startsWith('--') ? match[1] : match[1].toLowerCase(), value: match[2].replace(/\s*!\s*important\s*$/i, '') });
+    }
+    segment = '';
+  }
+  for (let index = 0; index < css.length; index++) {
+    const char = css[index];
+    if (char === '\\') {
+      segment += css.slice(index, index + 2);
+      index++;
+    } else if (quote) {
+      segment += char;
+      if (char === quote) quote = '';
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      segment += char;
+    } else if (char === '/' && css[index + 1] === '*') {
+      const end = css.indexOf('*/', index + 2);
+      index = end < 0 ? css.length : end + 1;
+      segment += ' ';
+    } else if (char === '(' || char === '[') {
+      if (char === '(') parentheses++;
+      else brackets++;
+      segment += char;
+    } else if (char === ')' || char === ']') {
+      if (char === ')') parentheses--;
+      else brackets--;
+      segment += char;
+    } else if (!parentheses && !brackets && char === '{') {
+      if (valueBraces || /^\s*--[\w-]+\s*:/.test(segment)) {
+        valueBraces++;
+        segment += char;
+      } else {
+        blocks.push(/^\s*@font-face\b/i.test(segment));
+        segment = '';
+      }
+    } else if (!parentheses && !brackets && char === '}' && valueBraces) {
+      valueBraces--;
+      segment += char;
+    } else if (!parentheses && !brackets && !valueBraces && (char === ';' || char === '}')) {
+      emit();
+      if (char === '}') blocks.pop();
+    } else segment += char;
+  }
+  emit();
+  return declarations;
+}
+
+function splitValue(value, separator) {
+  const parts = [];
+  let start = 0;
+  let depth = 0;
+  let quote = '';
+  for (let index = 0; index < value.length; index++) {
+    const char = value[index];
+    if (char === '\\') index++;
+    else if (quote) { if (char === quote) quote = ''; }
+    else if (char === '"' || char === "'") quote = char;
+    else if (char === '(') depth++;
+    else if (char === ')') depth--;
+    else if (!depth && separator.test(char)) {
+      parts.push(value.slice(start, index));
+      if (char === '/') parts.push('/');
+      start = index + 1;
+    }
+  }
+  parts.push(value.slice(start));
+  return parts;
+}
+
+function fontValueAlternatives(value, properties, visiting = new Set()) {
+  let quote = '';
+  for (let index = 0; index < value.length; index++) {
+    const char = value[index];
+    if (char === '\\') index++;
+    else if (quote) { if (char === quote) quote = ''; }
+    else if (char === '"' || char === "'") quote = char;
+    else if (/^var\(/i.test(value.slice(index, index + 4)) && !/[\w-]/.test(value[index - 1] ?? '')) {
+      let depth = 1;
+      let end = index + 4;
+      let innerQuote = '';
+      for (; end < value.length && depth; end++) {
+        const inner = value[end];
+        if (inner === '\\') end++;
+        else if (innerQuote) { if (inner === innerQuote) innerQuote = ''; }
+        else if (inner === '"' || inner === "'") innerQuote = inner;
+        else if (inner === '(') depth++;
+        else if (inner === ')') depth--;
+      }
+      if (depth) return [];
+      const [name, ...fallback] = splitValue(value.slice(index + 4, end - 1), /,/);
+      const key = name.trim();
+      const candidates = [];
+      if (!visiting.has(key)) {
+        const path = new Set(visiting).add(key);
+        for (const definition of properties.get(key) ?? []) candidates.push(...fontValueAlternatives(definition, properties, path));
+      }
+      if (fallback.length) candidates.push(...fontValueAlternatives(fallback.join(','), properties, visiting));
+      return [...new Set(candidates.flatMap((candidate) => fontValueAlternatives(value.slice(0, index) + candidate + value.slice(end), properties, visiting)))];
+    }
+  }
+  return [value];
+}
+
+function typographyUsage(document) {
+  const declarations = document.sources.flatMap(({ css, inline }) => cssDeclarations(css, inline));
+  const properties = new Map();
+  for (const { property, value } of declarations) {
+    if (property.startsWith('--')) properties.set(property, [...properties.get(property) ?? [], value]);
+  }
+  const usage = { families: new Set(), italic: document.italic };
+  for (const { property, value } of declarations) {
+    if (!['font-family', 'font', 'font-style'].includes(property)) continue;
+    for (let resolved of fontValueAlternatives(value, properties)) {
+      resolved = resolved.trim();
+      if (property === 'font-style') {
+        if (/^italic$/i.test(resolved)) usage.italic = true;
+        continue;
+      }
+      if (property === 'font') {
+        const tokens = splitValue(resolved, /[\s/]/).filter(Boolean);
+        const size = tokens.findIndex((token) => /^(?:\d*\.?\d+(?:[a-z]+|%)|0|xx?-small|small|medium|large|x{1,3}-large|smaller|larger)$/i.test(token) || /^(?:calc|min|max|clamp)\(/i.test(token));
+        if (size < 0) continue;
+        if (tokens.slice(0, size).some((token) => /^italic$/i.test(token))) usage.italic = true;
+        resolved = tokens.slice(size + (tokens[size + 1] === '/' ? 3 : 1)).join(' ');
+      }
+      for (let family of splitValue(resolved, /,/)) {
+        family = family.trim();
+        if (/^(["'])[\s\S]*\1$/.test(family)) family = family.slice(1, -1);
+        family = family.replace(/\\([\da-f]{1,6})(?:\r\n|[\t\n\r\f ])?|\\([^\r\n\f])/gi, (_, hex, escaped) => {
+          const code = parseInt(hex, 16);
+          return hex ? code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : '\ufffd' : escaped;
+        }).replace(/\s+/g, ' ').toLowerCase();
+        const face = faces.find((candidate) => candidate.family.toLowerCase() === family);
+        if (face) usage.families.add(face.family);
+      }
+    }
+  }
+  return usage;
+}
 
 const paths = process.argv.slice(2);
 if (paths.length !== 1) {
@@ -22,18 +223,18 @@ if (paths.length !== 1) {
   process.exit(2);
 }
 const [path] = paths;
-const page = (await readFile(path, 'utf8')).replace(embedded, '');
-const italic = /font-style\s*:\s*italic|<(em|i|cite)[\s>]/i.test(page);
-const used = faces.filter((face) => page.includes(face.family) && (face.style === 'normal' || italic));
+let page = await readFile(path, 'utf8');
+for (const [start, end] of htmlTypographySources(page).managed.reverse()) page = page.slice(0, start) + page.slice(end);
+const document = htmlTypographySources(page);
+const usage = typographyUsage(document);
+const used = faces.filter((face) => usage.families.has(face.family) && (face.style === 'normal' || usage.italic));
 const rules = await Promise.all(used.map(async (face) => {
   const data = (await readFile(join(fonts, face.file))).toString('base64');
   return `@font-face{font-family:"${face.family}";font-style:${face.style};font-weight:${face.weight};font-display:swap;src:url(data:font/woff2;base64,${data}) format("woff2");unicode-range:${latin}}`;
 }));
 const block = rules.length ? `<style data-artifacts-fonts>${rules.join('')}</style>\n` : '';
 
-const anchor = page.search(/<style[\s>]/i);
-const head = /<head[^>]*>\n?/i.exec(page) ?? /<!doctype[^>]*>\n?/i.exec(page);
-const at = anchor >= 0 ? anchor : head ? head.index + head[0].length : 0;
+const at = document.insertionAt;
 const output = page.slice(0, at) + block + page.slice(at);
 const bytes = Buffer.byteLength(output);
 if (bytes > limit) {

package/skills/artifacts-design/scripts/verify-local.mjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { once } from 'node:events';
+import { access, mkdir, mkdtemp, readFile, readdir, realpath, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { delimiter, join, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+
+const execute = promisify(execFile);
+const framePolicy = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; font-src data:; media-src data:; connect-src 'none'; frame-src 'none'; worker-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'";
+const previewPolicy = `${framePolicy}; frame-ancestors 'self'; sandbox allow-scripts`;
+const variants = [375, 1280].flatMap((width) => ['light', 'dark'].map((theme) => ({ width, height: 900, theme })));
+const fields = { text: ['text'], count: ['count'], visible: ['visible'], visibleCount: ['count'], attribute: ['name', 'value'], click: [], press: ['key'], fill: ['value'], check: ['checked'], select: ['values'] };
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const message = (error) => error instanceof Error ? error.message : String(error);
+const escape = (value) => value.replace(/[&<>"']/g, (character) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]);
+const compatible = (ua) => !/Edg|OPR|SamsungBrowser|CriOS|FxiOS/.test(ua) && Number(/(?:Headless)?Chrome\/(\d+)\./.exec(ua)?.[1]) >= 152;
+
+function object(value, required, optional, label) {
+  assert(value && typeof value === 'object' && !Array.isArray(value), `${label} must be an object`);
+  assert(required.every((key) => Object.hasOwn(value, key)), `${label} has missing fields`);
+  assert(Object.keys(value).every((key) => required.includes(key) || optional.includes(key)), `${label} has unknown fields`);
+  return value;
+}
+
+function parseExpectations(value) {
+  object(value, ['expectations'], ['timeoutMs'], 'expectations document');
+  assert(Array.isArray(value.expectations) && value.expectations.length <= 100, 'expectations must contain at most 100 steps');
+  const timeoutMs = value.timeoutMs ?? 3000;
+  assert(Number.isInteger(timeoutMs) && timeoutMs >= 100 && timeoutMs <= 30000, 'timeoutMs must be an integer from 100 to 30000');
+  for (const step of value.expectations) {
+    assert(step && Object.hasOwn(fields, step.kind), 'Unknown expectation kind');
+    object(step, ['kind', 'selector', ...fields[step.kind]], ['when'], 'expectation');
+    assert(typeof step.selector === 'string' && step.selector.trim() && step.selector.length <= 8192, 'selector must be a nonempty string');
+    if (step.when !== undefined) {
+      object(step.when, [], ['width', 'theme'], 'when');
+      if (step.when.width !== undefined) assert([375, 1280].includes(step.when.width), 'when.width must be 375 or 1280');
+      if (step.when.theme !== undefined) assert(['light', 'dark'].includes(step.when.theme), 'when.theme must be light or dark');
+    }
+    for (const key of fields[step.kind]) {
+      if (['count'].includes(key)) assert(Number.isInteger(step[key]) && step[key] >= 0, 'count must be a nonnegative integer');
+      else if (['visible', 'checked'].includes(key)) assert(typeof step[key] === 'boolean', `${key} must be boolean`);
+      else if (key === 'values') assert(Array.isArray(step.values) && step.values.length <= 100 && step.values.every((entry) => typeof entry === 'string'), 'values must be strings');
+      else if (key === 'value' && step.kind === 'attribute') assert(step.value === null || typeof step.value === 'string', 'attribute value must be a string or null');
+      else assert(typeof step[key] === 'string' && (!['key', 'name'].includes(key) || step[key].trim()), `${key} must be a string`);
+    }
+  }
+  return { expectations: value.expectations, timeoutMs };
+}
+
+function invocation(args) {
+  const options = {};
+  let html;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg.startsWith('--')) {
+      assert(['--evidence', '--expectations', '--browser'].includes(arg), `Unknown option ${arg}`);
+      assert(!Object.hasOwn(options, arg) && args[index + 1] && !args[index + 1].startsWith('--'), `Supply ${arg} once with a value`);
+      options[arg] = args[++index];
+    } else { assert(!html, 'Supply one HTML file'); html = arg; }
+  }
+  assert(html && options['--evidence'], 'Usage: verify-local.mjs HTML --evidence DIRECTORY [--expectations JSON] [--browser EXECUTABLE]');
+  return { html: resolve(html), evidence: resolve(options['--evidence']), expectations: options['--expectations'] && resolve(options['--expectations']), browser: options['--browser'] && resolve(options['--browser']) };
+}
+
+function playwright() {
+  for (const base of [join(process.cwd(), 'package.json'), import.meta.url]) {
+    const require = createRequire(base);
+    for (const name of ['playwright', 'playwright-core']) {
+      try { return require(name).chromium; }
+      catch (error) { if (error.code !== 'MODULE_NOT_FOUND') throw error; }
+    }
+  }
+  throw new Error('No Playwright runtime found. Provide an existing playwright or playwright-core package in the working directory project, then rerun. The helper does not install packages or browsers.');
+}
+
+async function cachedExecutables(chromium) {
+  const expected = chromium.executablePath();
+  const browserDirectory = /[\\/](?:chromium|chromium_headless_shell)-\d+[\\/]/.exec(expected);
+  const roots = new Set([browserDirectory && expected.slice(0, browserDirectory.index), process.env.PLAYWRIGHT_BROWSERS_PATH && process.env.PLAYWRIGHT_BROWSERS_PATH !== '0' && resolve(process.env.PLAYWRIGHT_BROWSERS_PATH)].filter(Boolean));
+  const executables = [];
+  for (const root of roots) {
+    let entries;
+    try { entries = await readdir(root, { withFileTypes: true }); }
+    catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+    for (const entry of entries.filter((item) => item.isDirectory() && /^(?:chromium|chromium_headless_shell)-\d+$/.test(item.name)).sort((a, b) => b.name.localeCompare(a.name, 'en', { numeric: true })).slice(0, 50)) {
+      const directory = join(root, entry.name);
+      for (const relative of [
+        'chrome-linux/chrome', 'chrome-linux64/chrome', 'chrome-linux/headless_shell', 'chrome-headless-shell-linux64/chrome-headless-shell',
+        'chrome-mac/Chromium.app/Contents/MacOS/Chromium', 'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing', 'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+        'chrome-headless-shell-mac-arm64/chrome-headless-shell', 'chrome-headless-shell-mac-x64/chrome-headless-shell',
+        'chrome-win/chrome.exe', 'chrome-win64/chrome.exe', 'chrome-headless-shell-win64/chrome-headless-shell.exe',
+      ]) {
+        const candidate = join(directory, relative);
+        try { await access(candidate, constants.X_OK); executables.push(candidate); } catch {}
+      }
+    }
+  }
+  return executables;
+}
+
+async function chooseBrowser(chromium, explicit, diagnostics) {
+  const candidates = explicit ? [explicit] : [
+    chromium.executablePath(), ...await cachedExecutables(chromium),
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    join(homedir(), 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome'),
+    ...['PROGRAMFILES', 'PROGRAMFILES(X86)', 'LOCALAPPDATA'].filter((key) => process.env[key]).flatMap((key) => [join(process.env[key], 'Google/Chrome/Application/chrome.exe'), join(process.env[key], 'Chromium/Application/chrome.exe')]),
+    ...(process.env.PATH ?? '').split(delimiter).flatMap((directory) => ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome'].map((name) => join(directory, name))),
+  ];
+  for (const candidate of new Set(candidates)) {
+    let browser;
+    try {
+      await access(candidate, constants.X_OK);
+      const executable = await realpath(candidate);
+      const { stdout, stderr } = await execute(executable, ['--version'], { timeout: 5000, maxBuffer: 65536 });
+      const version = `${stdout} ${stderr}`.trim();
+      assert(/Chrom(?:e|ium)/i.test(version) && Number(/(\d+)\./.exec(version)?.[1]) >= 152, `Incompatible version ${version}. Chrome or Chromium 152+ is required`);
+      browser = await chromium.launch({ executablePath: executable, headless: true, chromiumSandbox: true, timeout: 15000 });
+      const page = await browser.newPage();
+      const userAgent = await page.evaluate(() => navigator.userAgent);
+      assert(compatible(userAgent), `Unsupported launched user agent ${userAgent}`);
+      await page.close();
+      return { browser, identity: { executable, selectedPath: candidate, version: browser.version(), probeVersion: version, userAgent } };
+    } catch (error) {
+      await browser?.close();
+      diagnostics.push({ executable: candidate, reason: message(error) });
+    }
+  }
+  throw new Error('No compatible browser could launch. Use --browser /absolute/path/to/an/existing/Chrome-or-Chromium-152+ executable. Check browserDiagnostics in report.json. No software was installed and browser sandboxing was not disabled.');
+}
+
+async function poll(read, expected, timeout) {
+  const deadline = Date.now() + timeout;
+  let actual;
+  do {
+    actual = await read();
+    try { assert.deepEqual(actual, expected); return; } catch {}
+    await new Promise((done) => setTimeout(done, 50));
+  } while (Date.now() < deadline);
+  assert.deepEqual(actual, expected);
+}
+
+async function expectation(frame, step, timeout) {
+  const locator = frame.locator(step.selector);
+  const actions = {
+    click: () => locator.click(), press: () => locator.press(step.key), fill: () => locator.fill(step.value),
+    check: () => locator.setChecked(step.checked), select: () => locator.selectOption(step.values),
+  };
+  if (Object.hasOwn(actions, step.kind)) { await actions[step.kind](); return; }
+  if (step.kind === 'count') return poll(() => locator.count(), step.count, timeout);
+  if (step.kind === 'visibleCount') return poll(async () => {
+    const items = await locator.all();
+    const visible = await Promise.all(items.map((item) => item.isVisible()));
+    return visible.filter(Boolean).length;
+  }, step.count, timeout);
+  if (step.kind === 'visible') return poll(async () => {
+    const count = await locator.count();
+    return { count, visible: count === 1 ? await locator.isVisible() : null };
+  }, { count: 1, visible: step.visible }, timeout);
+  if (step.kind === 'text') return poll(() => locator.innerText(), step.text, timeout);
+  return poll(() => locator.getAttribute(step.name), step.value, timeout);
+}
+
+async function dimensions(frame) {
+  return frame.evaluate(() => ({ viewportWidth: innerWidth, documentWidth: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0), documentHeight: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0), viewportHeight: innerHeight }));
+}
+
+async function capture(page, frame, result, directory, phase) {
+  const size = await dimensions(frame);
+  const maximum = Math.max(0, size.documentHeight - size.viewportHeight);
+  const offsets = [0];
+  while (offsets.at(-1) < maximum && offsets.length < 12) offsets.push(Math.min(maximum, offsets.at(-1) + size.viewportHeight));
+  const actualOffsets = [];
+  for (const offset of offsets) {
+    const actual = await frame.evaluate((top) => { scrollTo({ top, left: 0, behavior: 'instant' }); return scrollY; }, offset);
+    actualOffsets.push(actual);
+    await page.waitForTimeout(50);
+    const path = `${result.variant.width}-${result.variant.theme}-${phase}-${offset}.png`;
+    await page.screenshot({ path: join(directory, path), timeout: 5000 });
+    result.screenshots.push({ path, phase, scrollY: actual, width: result.variant.width, height: result.variant.height });
+  }
+  const finalSize = await dimensions(frame);
+  const capturedThrough = Math.min(finalSize.documentHeight, Math.max(...actualOffsets) + size.viewportHeight);
+  const reachedOffsets = actualOffsets.every((actual, index) => Math.abs(actual - offsets[index]) <= 1);
+  result.captureCoverage.push({ phase, documentHeight: finalSize.documentHeight, capturedThrough, truncated: !reachedOffsets || capturedThrough < finalSize.documentHeight });
+  await frame.evaluate(() => scrollTo({ top: 0, left: 0, behavior: 'instant' }));
+}
+
+async function runVariant(browser, origin, config, variant, directory) {
+  const deadline = { timeoutMs: Math.min(60000, Math.max(10000, config.timeoutMs * (config.expectations.length + 1))), exceeded: false };
+  const result = { variant, status: 'passed', deadline, checks: [], screenshots: [], captureCoverage: [], consoleErrors: [], runtimeErrors: [], externalAttempts: [], errors: [] };
+  const context = await browser.newContext({ viewport: { width: variant.width, height: variant.height }, colorScheme: variant.theme, serviceWorkers: 'block' });
+  context.setDefaultTimeout(config.timeoutMs);
+  let closing;
+  const close = () => closing ??= context.close().catch((error) => { result.errors.push(`Browser context cleanup failed. ${message(error)}`); });
+  const watchdog = setTimeout(() => {
+    deadline.exceeded = true;
+    result.errors.push(`Variant deadline exceeded after ${deadline.timeoutMs} ms. Remaining checks, CSP observations, and captures are incomplete.`);
+    void close();
+  }, deadline.timeoutMs);
+  let frame;
+  const overflow = async (phase) => {
+    const size = await dimensions(frame);
+    const passed = size.documentWidth <= size.viewportWidth + 1;
+    result.checks.push({ kind: 'overflow', phase, status: passed ? 'passed' : 'failed', ...size });
+  };
+  try {
+    const page = await context.newPage();
+    page.on('console', (entry) => { if (entry.type() === 'error') result.consoleErrors.push(entry.text()); });
+    page.on('pageerror', (error) => result.runtimeErrors.push(message(error)));
+    await context.route('**/*', async (route) => {
+      const request = route.request();
+      if ([`${origin}/`, `${origin}/content`].includes(request.url()) && request.method() === 'GET' && request.resourceType() === 'document') await route.continue();
+      else { result.externalAttempts.push({ source: 'request', url: request.url(), resourceType: request.resourceType() }); await route.abort('blockedbyclient'); }
+    });
+    await context.addInitScript(() => {
+      globalThis.__artifactsLocalViolations = [];
+      addEventListener('securitypolicyviolation', (event) => globalThis.__artifactsLocalViolations.push({ source: 'csp', url: event.blockedURI, directive: event.effectiveDirective }));
+    });
+    const responsePromise = page.waitForResponse((response) => response.url() === `${origin}/content`);
+    const [, response] = await Promise.all([page.goto(`${origin}/`, { waitUntil: 'load', timeout: 10000 }), responsePromise]);
+    const headers = response.headers();
+    result.sandbox = { csp: headers['content-security-policy'], connectionAllowlist: headers['connection-allowlist'], dnsPrefetchControl: headers['x-dns-prefetch-control'], iframeSandbox: await page.locator('iframe').getAttribute('sandbox'), contentSha256: hash(await response.body()) };
+    assert.equal(result.sandbox.csp, previewPolicy);
+    assert.equal(result.sandbox.connectionAllowlist, '()');
+    assert.equal(result.sandbox.dnsPrefetchControl, 'off');
+    assert.equal(result.sandbox.iframeSandbox, 'allow-scripts');
+    frame = page.frames().find((item) => item.url() === `${origin}/content`);
+    assert(frame, 'The local sandboxed content frame must load');
+    await frame.evaluate(async (timeout) => {
+      await Promise.race([document.fonts.ready, new Promise((_, reject) => setTimeout(() => reject(new Error('Fonts readiness timed out')), timeout))]);
+    }, config.timeoutMs);
+    await page.waitForTimeout(200);
+    await overflow('initial');
+    await capture(page, frame, result, directory, 'initial');
+    for (const [index, step] of config.expectations.entries()) {
+      if (step.when && ((step.when.width !== undefined && step.when.width !== variant.width) || (step.when.theme !== undefined && step.when.theme !== variant.theme))) continue;
+      try {
+        await expectation(frame, step, config.timeoutMs);
+        result.checks.push({ kind: step.kind, step: index, status: 'passed' });
+      } catch (error) { result.checks.push({ kind: step.kind, step: index, status: 'failed', message: message(error) }); break; }
+    }
+    assert.equal(page.url(), `${origin}/`, 'The document must not navigate the wrapper');
+    assert.equal(frame.url(), `${origin}/content`, 'The document must not replace its content frame');
+    await page.waitForTimeout(200);
+    await overflow('final');
+    await capture(page, frame, result, directory, 'final');
+  } catch (error) { result.errors.push(message(error)); }
+  finally {
+    if (!deadline.exceeded && frame && !frame.isDetached()) {
+      try { result.externalAttempts.push(...await frame.evaluate(() => globalThis.__artifactsLocalViolations ?? [])); }
+      catch (error) { result.errors.push(`CSP evidence unavailable. ${message(error)}`); }
+    }
+    await close();
+    clearTimeout(watchdog);
+  }
+  if (result.checks.some((item) => item.status === 'failed') || result.errors.length || result.consoleErrors.length || result.runtimeErrors.length || result.externalAttempts.length) result.status = 'failed';
+  return result;
+}
+
+async function main() {
+  const report = {
+    schemaVersion: 1, evidenceKind: 'renderizado local', authenticatedPublication: 'not-verified', status: 'blocked',
+    visualReview: { status: 'required', checks: ['Content fidelity and reading order', 'Composition, alignment, legibility, and focus visibility at both widths and themes', 'Inspect screenshot tiles and any truncated capture coverage'] },
+    input: null, browser: null, browserDiagnostics: [],
+    sandbox: { csp: previewPolicy, iframeSandbox: 'allow-scripts', connectionAllowlist: '()', dnsPrefetchControl: 'off', referrerPolicy: 'no-referrer', chromiumSandbox: true },
+    observation: 'Each fresh variant waits for load and fonts, observes 200 ms before and after its scenario, and captures bounded viewport tiles. Delayed behavior beyond this run requires additional review.',
+    variants: [], errors: [],
+  };
+  let directory;
+  let server;
+  let browser;
+  let config;
+  try {
+    config = invocation(process.argv.slice(2));
+    for (const input of [config.html, config.expectations].filter(Boolean)) assert(config.evidence !== input && !config.evidence.startsWith(`${input}${sep}`), 'Evidence destination must not overwrite an input file');
+    await mkdir(config.evidence, { recursive: true });
+    directory = await mkdtemp(join(config.evidence, 'local-'));
+    report.evidenceDirectory = directory;
+    const bytes = await readFile(config.html);
+    report.input = { path: await realpath(config.html), sha256: hash(bytes), bytes: bytes.length };
+    const checks = config.expectations ? parseExpectations(JSON.parse(await readFile(config.expectations, 'utf8'))) : { expectations: [], timeoutMs: 3000 };
+    const content = `<!doctype html><html lang="es"><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="${escape(framePolicy)}"><meta name="referrer" content="no-referrer"></head><body>${bytes.toString('utf8')}</body></html>`;
+    report.sandbox.contentSha256 = hash(content);
+    const chosen = await chooseBrowser(playwright(), config.browser, report.browserDiagnostics);
+    browser = chosen.browser;
+    report.browser = chosen.identity;
+    server = createServer((request, response) => {
+      if (request.method !== 'GET' || !['/', '/content'].includes(request.url)) { response.writeHead(404).end(); return; }
+      response.setHeader('content-type', 'text/html; charset=utf-8');
+      response.setHeader('cache-control', 'no-store');
+      response.setHeader('x-content-type-options', 'nosniff');
+      response.setHeader('referrer-policy', 'no-referrer');
+      response.setHeader('x-dns-prefetch-control', 'off');
+      if (request.url === '/content') response.setHeader('connection-allowlist', '()');
+      response.setHeader('content-security-policy', request.url === '/content' ? previewPolicy : "default-src 'none'; style-src 'unsafe-inline'; frame-src 'self'; base-uri 'none'; form-action 'none'");
+      response.end(request.url === '/content' ? content : '<!doctype html><meta name="viewport" content="width=device-width,initial-scale=1"><style>html,body{margin:0;width:100%;height:100%;overflow:hidden}iframe{display:block;border:0;width:100%;height:100%}</style><iframe title="Local artifact" sandbox="allow-scripts" referrerpolicy="no-referrer" src="/content"></iframe>');
+    });
+    server.listen(0, '127.0.0.1');
+    await once(server, 'listening');
+    const origin = `http://127.0.0.1:${server.address().port}`;
+    for (const variant of variants) report.variants.push(await runVariant(browser, origin, checks, variant, directory));
+    report.status = report.variants.every((item) => item.status === 'passed') ? 'passed' : 'failed';
+  } catch (error) { report.errors.push(message(error)); }
+  finally {
+    try { await browser?.close(); } catch (error) { report.errors.push(`Browser cleanup failed. ${message(error)}`); }
+    if (server) {
+      try { await new Promise((done, reject) => server.close((error) => error ? reject(error) : done())); }
+      catch (error) { report.errors.push(`Local server cleanup failed. ${message(error)}`); }
+    }
+    if (report.errors.length && report.status === 'passed') report.status = 'failed';
+    if (report.input) {
+      try {
+        report.input.sha256After = hash(await readFile(config.html));
+        assert.equal(report.input.sha256After, report.input.sha256, 'Input HTML changed during verification');
+      } catch (error) { report.status = 'failed'; report.errors.push(message(error)); }
+    }
+    if (directory) {
+      await writeFile(join(directory, 'report.json'), `${JSON.stringify(report, null, 2)}\n`);
+      const links = report.variants.flatMap((item) => item.screenshots.map((capture) => `- [${capture.path}](${capture.path}). Frame scroll offset ${capture.scrollY} px.`));
+      await writeFile(join(directory, 'index.md'), `# Local rendering evidence\n\nEvidence kind is renderizado local. Authenticated publication is not verified.\n\nAutomatic checks ${report.status}. Visual review remains required.\n\n${links.join('\n')}\n`);
+    }
+    console.log(JSON.stringify(report));
+    process.exitCode = report.status === 'passed' ? 0 : report.status === 'failed' ? 1 : 2;
+  }
+}
+
+await main();

package/src/operations.d.ts

@@ -16,6 +16,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     text: "text";
                     html: "html";
                     markdown: "markdown";
+                    design: "design";
                 }>;
                 text: z.ZodString;
             }, z.core.$strict>;
@@ -55,6 +56,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     text: "text";
                     html: "html";
                     markdown: "markdown";
+                    design: "design";
                 }>;
                 text: z.ZodString;
             }, z.core.$strict>;