@tryvitris/website-harness 0.1.0-beta.5 → 0.1.0-beta.7

package/bin/types/src/agent/jev/component-select.d.ts

@@ -1,102 +0,0 @@
-import type { JevClient } from "./client.ts";
-import { partitionBatchItems } from "./batching.ts";
-import { type ComponentFitDimension } from "./questions.ts";
-import { loadBlockLibrary, type BlockRecord, type SectionState } from "./block-catalog.ts";
-export declare const COMPONENT_FIT_WEIGHTS: Record<ComponentFitDimension, number>;
-export declare const CUSTOM_CANDIDATE_ID = "custom";
-export interface ComponentRecommendation {
-    id: string;
-    score: number;
-    scoreState?: "observed" | "partial" | "unavailable";
-    reasonCodes: string[];
-    adaptations: string[];
-    exampleHandle: string;
-    previewEvidence?: BlockRecord["previewEvidence"];
-    custom: boolean;
-}
-export interface ComponentSelectResult {
-    libraryProfile?: string;
-    libraryReleaseIdentity?: string;
-    ranked: ComponentRecommendation[];
-    routeToAgent: boolean;
-    reason?: string;
-    cacheKey: string;
-    raw: Record<string, unknown>;
-    receiptIds?: string[];
-    cacheHit?: boolean;
-    provenance?: ComponentCacheProvenance;
-    discovery?: {
-        eligibleIds: string[];
-        rejected: Array<{
-            id: string;
-            reason: string;
-        }>;
-        shortlistIds: string[];
-    };
-}
-export interface ComponentCacheProvenance {
-    libraryProfile?: string;
-    libraryReleaseIdentity?: string;
-    preparationId: string;
-    cacheKey: string;
-    libraryHash: string;
-    stateHash: string;
-    model: string;
-    policy: string;
-    questionSemantics: string;
-    receiptIds: string[];
-}
-export declare function cacheKeyForSelection(opts: {
-    state: SectionState;
-    libraryHash: string;
-    model: string;
-    policy: string;
-    questionSemantics?: string;
-    profile?: string;
-}): string;
-export declare function componentStateHash(state: SectionState): string;
-export declare function planComponentQuestions(state: SectionState, lib: ReturnType<typeof loadBlockLibrary>): {
-    questionIds: string[];
-    partitions: ReturnType<typeof partitionBatchItems>["partitions"];
-    stateHash: string;
-    candidates: BlockRecord[];
-    discovery: NonNullable<ComponentSelectResult["discovery"]>;
-};
-export declare function verifyComponentCacheHit(opts: {
-    root: string;
-    cached: ComponentSelectResult;
-    state: SectionState;
-    libraryHash: string;
-    model: string;
-    policy?: string;
-    profile?: string;
-}): {
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-};
-export declare function recommendComponents(opts: {
-    root: string;
-    kernel: string;
-    client: JevClient;
-    state: SectionState;
-    preparationId?: string;
-    nodeId?: string;
-    signal?: AbortSignal;
-}): Promise<ComponentSelectResult>;
-export declare function draftAuthoringSnippet(block: BlockRecord, copy: {
-    heading?: string;
-    body?: string;
-    cta?: string;
-    mediaId?: string;
-}): string;
-export declare function attachComponentRecommendations(opts: {
-    root: string;
-    kernel: string;
-    client: JevClient;
-    nodeId: string;
-    preparationId: string;
-    inputHash?: string;
-    signal?: AbortSignal;
-}): Promise<string>;

package/bin/types/src/blocks/library-profile.d.ts

@@ -1,9 +0,0 @@
-import { type BlockLibrary } from "../agent/jev/block-catalog.ts";
-export type LibraryProfile = "legacy-v0" | "slice-v1";
-/** The profile is site-owned. A refresh must not rewrite launch.json. */
-export declare function readLibraryProfile(siteRoot: string): LibraryProfile;
-export declare function loadProfiledBlockLibrary(kernel: string, siteRoot: string): {
-    profile: LibraryProfile;
-    releaseIdentity: string;
-    library: BlockLibrary;
-};

package/bin/types/src/blocks/metadata.d.ts

@@ -1,65 +0,0 @@
-export interface BlockMeta {
-    schemaVersion: 1;
-    id: string;
-    revision: number;
-    status: "draft" | "inspected" | "pilot" | "stable" | "deprecated";
-    owner: string;
-    sourceHash: string;
-    fit: {
-        visitorJobs: string[];
-        pageRoles: string[];
-        useWhen: string[];
-        avoidWhen: string[];
-    };
-    content: {
-        requiredSlots: string[];
-        optionalSlots: string[];
-        testedItemCounts: number[];
-    };
-    media: {
-        min: number;
-        max: number;
-        optionalBehavior: string;
-        aspect: string[];
-    };
-    composition: {
-        hierarchy: string;
-        alignment: string;
-        density: string;
-        mediaProminence: string;
-        geometry: string[];
-        boundary: string;
-    };
-    adaptation: {
-        flexible: string[];
-        invariants: string[];
-        customWhen: string[];
-    };
-    responsive: {
-        readingOrder: string;
-        reflow: string;
-        crop: string;
-    };
-    interaction: {
-        behavior: string;
-        islands: string[];
-    };
-    evidence: {
-        provenance: string[];
-        testedContexts: string[];
-        accessibility: string[];
-        previewManifest?: string;
-    };
-}
-export declare function blockSourceHash(dir: string): string;
-export declare function blockPreviewRendererHash(root: string): string;
-export declare function readBlockMeta(dir: string, id: string, slots: {
-    name: string;
-    required: boolean;
-}[]): BlockMeta | undefined;
-export declare function blockPreviewEvidence(dir: string, meta?: BlockMeta): {
-    status: "current" | "stale" | "unavailable";
-    mobile?: string;
-    desktop?: string;
-    hashes?: Record<string, string>;
-};

package/bin/vitris-blocks.js

@@ -1,238 +0,0 @@
-#!/usr/bin/env node
-import {
-  blockPreviewRendererHash,
-  blockSourceHash,
-  loadBlockLibrary,
-  loadProfiledBlockLibrary
-} from "./chunks/chunk-FOXUQXTV.js";
-import "./chunks/chunk-HNORQ74T.js";
-import {
-  baseCss,
-  flattenBody,
-  primitivesCss,
-  siteIslands
-} from "./chunks/chunk-YCVGD2CG.js";
-import {
-  themeCss
-} from "./chunks/chunk-LKN75JGA.js";
-import {
-  defaultTheme
-} from "./chunks/chunk-YYPYYOEV.js";
-import "./chunks/chunk-GZDLXYZV.js";
-import "./chunks/chunk-7FS67SRF.js";
-
-// scripts/blocks-preview.ts
-import { mkdirSync, readdirSync, readFileSync, writeFileSync, existsSync, statSync, unlinkSync } from "node:fs";
-import { join, dirname, normalize, extname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createServer } from "node:http";
-import { createHash } from "node:crypto";
-var kernelRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
-var blocksRoot = join(kernelRoot, "blocks");
-var argv = process.argv.slice(2);
-var outIndex = argv.indexOf("--out");
-var siteIndex = argv.indexOf("--site");
-var siteRoot = siteIndex >= 0 && argv[siteIndex + 1] ? resolve(argv[siteIndex + 1]) : void 0;
-var installed = /(^|[/\\])node_modules([/\\]|$)/.test(kernelRoot);
-var outRoot = outIndex >= 0 && argv[outIndex + 1] ? resolve(argv[outIndex + 1]) : join(siteRoot || (installed ? process.cwd() : kernelRoot), "dist", "blocks");
-var profiled = siteRoot ? loadProfiledBlockLibrary(kernelRoot, siteRoot) : void 0;
-var library = new Map((profiled?.library || loadBlockLibrary(kernelRoot)).blocks.map((block) => [block.id, block]));
-var sha = (bytes) => createHash("sha256").update(bytes).digest("hex");
-var esc = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-function imageStatus(id, dir, previewHtml) {
-  const block = library.get(id);
-  const rel = block?.meta?.evidence.previewManifest;
-  if (!rel) return { status: "unavailable" };
-  const file = join(dir, rel);
-  if (!existsSync(file)) return { status: "unavailable" };
-  try {
-    const manifest = JSON.parse(readFileSync(file, "utf8"));
-    const valid = manifest.blockId === id && manifest.sourceHash === blockSourceHash(dir) && manifest.previewHtmlHash === sha(previewHtml) && manifest.rendererHash === blockPreviewRendererHash(kernelRoot) && ["mobile", "desktop"].every((kind) => {
-      const image = manifest.images?.[kind];
-      return image?.file && existsSync(join(dirname(file), image.file)) && sha(readFileSync(join(dirname(file), image.file))) === image.hash;
-    });
-    return { status: valid ? "current" : "stale", manifest: rel };
-  } catch {
-    return { status: "stale", manifest: rel };
-  }
-}
-function placeholder(w, h, label) {
-  const fs = Math.max(12, Math.round(Math.min(w, h) / 9));
-  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}"><defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#cbbba9"/><stop offset="1" stop-color="#7a6756"/></linearGradient></defs><rect width="${w}" height="${h}" fill="url(#g)"/><text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" font-family="system-ui,sans-serif" font-size="${fs}" fill="#fff" opacity="0.7">${label}</text></svg>`;
-  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
-}
-function placeholderMedia(html) {
-  return html.replace(/<img\b[^>]*>/g, (tag) => {
-    const src = tag.match(/\bsrc="([^"]*)"/)?.[1] ?? "";
-    if (!/^\/(media|stock)\//.test(src)) return tag;
-    const w = Number(tag.match(/\bwidth="(\d+)"/)?.[1] ?? 1200);
-    const h = Number(tag.match(/\bheight="(\d+)"/)?.[1] ?? 900);
-    const isLogo = /logo/i.test(src) || w <= 240 && h <= 80;
-    const isAvatar = /avatar|review|portrait-sm/i.test(src) || w === h && w <= 160;
-    const label = isLogo ? "logo" : isAvatar ? "" : `${w}\xD7${h}`;
-    const fill = isLogo ? placeholderLogo(w, h) : placeholder(w, h, label);
-    return tag.replace(/\bsrc="[^"]*"/, `src="${fill}"`);
-  });
-}
-function placeholderLogo(w, h) {
-  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}"><rect x="2" y="${h / 4}" width="${h / 2}" height="${h / 2}" rx="4" fill="#555"/><rect x="${h / 2 + 10}" y="${h / 2 - 5}" width="${w - h / 2 - 14}" height="10" rx="5" fill="#555"/></svg>`;
-  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
-}
-function readmeExample(readme) {
-  const m = readme.match(/## Example\s*```html\s*([\s\S]*?)```/);
-  return m ? m[1].trim() : null;
-}
-function readmeVariants(readme) {
-  const line = readme.match(/\*\*Variants:\*\*\s*(.+)/)?.[1]?.trim() ?? "";
-  if (!line || line.startsWith("(none)")) return [];
-  return line.split(",").map((v) => v.trim()).filter(Boolean);
-}
-function readmeLook(readme) {
-  return readme.split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#") && !l.startsWith("-") && !l.startsWith("```")) ?? "";
-}
-function withVariant(example, name, variant) {
-  return example.replace(new RegExp(`^<${name}(\\s|>)`), `<${name} variant="${variant}"$1`);
-}
-var sharedCss = [themeCss(defaultTheme), baseCss, primitivesCss].join("\n");
-var indexByCat = /* @__PURE__ */ new Map();
-var total = 0;
-var written = /* @__PURE__ */ new Set();
-mkdirSync(outRoot, { recursive: true });
-var cats = readdirSync(blocksRoot, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
-for (const cat of cats) {
-  const names = readdirSync(join(blocksRoot, cat), { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort();
-  for (const name of names) {
-    const dir = join(blocksRoot, cat, name);
-    if (!existsSync(join(dir, "template.html"))) continue;
-    if (!library.has(`${cat}/${name}`)) continue;
-    const catalog = {
-      [name]: {
-        html: readFileSync(join(dir, "template.html"), "utf8"),
-        css: readFileSync(join(dir, "styles.css"), "utf8"),
-        island: existsSync(join(dir, "island.js")) ? readFileSync(join(dir, "island.js"), "utf8") : null
-      }
-    };
-    const readme = existsSync(join(dir, "README.md")) ? readFileSync(join(dir, "README.md"), "utf8") : "";
-    const example = readmeExample(readme) ?? `<${name}><h2 slot="heading">${name}</h2><p>No example in README yet.</p></${name}>`;
-    const variants = readmeVariants(readme);
-    const look = readmeLook(readme);
-    const id = `${cat}/${name}`;
-    const record = library.get(id);
-    const renders = [{ file: `${name}.html`, label: name, body: example }];
-    for (const v of variants) renders.push({ file: `${name}--${v}.html`, label: `${name} \xB7 ${v}`, body: withVariant(example, name, v) });
-    const destDir = join(outRoot, cat);
-    mkdirSync(destDir, { recursive: true });
-    let baseHtml = "";
-    for (const r of renders) {
-      const flat = flattenBody(placeholderMedia(r.body), catalog, { name: "Blocks Preview", motion: { strength: "off" } });
-      const page = {
-        path: `/${cat}/${r.file}`,
-        title: r.label,
-        bodyHtml: flat.html,
-        used: [name],
-        usesMotion: false,
-        usesLeadForm: /data-lead-form/.test(flat.html)
-      };
-      const js = siteIslands([page], catalog);
-      const html = `<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>${cat}/${r.label}</title>
-  <style>${sharedCss}
-${catalog[name].css}</style>
-  <style>.bp-bar{position:fixed;inset-inline:0;bottom:0;z-index:999;display:flex;gap:1rem;align-items:center;padding:.4rem .9rem;font:12px/1.4 system-ui,sans-serif;color:#eee;background:#1d1a17;opacity:.9}.bp-bar a{color:#fff}.bp-bar span{color:#bbb}</style>
-</head>
-<body>
-  ${flat.html}
-  <div class="bp-bar"><a href="../index.html">\u2190 All blocks</a><strong>${cat}/${r.label}</strong><span>${look}</span></div>
-  ${js.trim() ? `<script type="module">${js}</script>` : ""}
-</body>
-</html>`;
-      const output = join(destDir, r.file);
-      writeFileSync(output, html);
-      if (r.file === `${name}.html`) baseHtml = html;
-      written.add(output);
-    }
-    if (!indexByCat.has(cat)) indexByCat.set(cat, []);
-    const variantLinks = variants.map((v) => `<a href="${cat}/${name}--${v}.html" class="badge badge--outline">${v}</a>`).join(" ");
-    const image = imageStatus(id, dir, baseHtml);
-    const roles = record?.meta?.fit.pageRoles.join("|") || cat;
-    const jobs = record?.meta?.fit.visitorJobs.join("|") || look;
-    const geometry = record?.geometry.join("|") || "";
-    const mediaFit = record?.meta ? record.meta.media.min > 0 ? "required" : "optional" : record?.mediaRequired ? "required" : "optional";
-    indexByCat.get(cat).push(
-      `<li class="bp-item" data-role="${esc(roles)}" data-job="${esc(jobs)}" data-geometry="${esc(geometry)}" data-media="${mediaFit}"><div><a class="bp-item__name" href="${cat}/${name}.html">${esc(name)}</a><label class="bp-compare-label"><input type="checkbox" class="bp-compare" value="${cat}/${name}.html"> compare</label></div><span class="bp-item__look">${esc(look)}<small>Image evidence: ${image.status}; metadata: ${record?.metadataSource || "legacy-readme"}</small></span>${variantLinks ? `<span class="bp-item__variants">${variantLinks}</span>` : ""}</li>`
-    );
-    total++;
-  }
-}
-for (const cat of readdirSync(outRoot, { withFileTypes: true }).filter((d) => d.isDirectory())) {
-  const dir = join(outRoot, cat.name);
-  for (const name of readdirSync(dir)) {
-    const file = join(dir, name);
-    if (name.endsWith(".html") && !written.has(file) && statSync(file).isFile()) unlinkSync(file);
-  }
-}
-var groups = [...indexByCat.entries()].map(
-  ([cat, items]) => `<section class="bp-group" id="${cat}"><h2>${cat} <span class="bp-count">${items.length}</span></h2><ul class="bp-list">${items.join("\n")}</ul></section>`
-).join("\n");
-var toc = [...indexByCat.keys()].map((cat) => `<a class="badge" href="#${cat}">${cat}</a>`).join(" ");
-var geometryOptions = [...new Set([...library.values()].flatMap((b) => b.geometry))].sort().map((value) => `<option value="${esc(value)}">${esc(value)}</option>`).join("");
-var roleOptions = [...new Set([...library.values()].flatMap((b) => b.meta?.fit.pageRoles || [b.category]))].sort().map((value) => `<option value="${esc(value)}">${esc(value)}</option>`).join("");
-writeFileSync(
-  join(outRoot, "index.html"),
-  `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Vitris blocks</title>
-  <style>${sharedCss}
-  .bp-head{padding-block:var(--space-8) var(--space-6);display:grid;gap:var(--space-4)}
-  .bp-toc{display:flex;flex-wrap:wrap;gap:var(--space-2)}
-  .bp-toc .badge{text-decoration:none}
-  .bp-group{padding-block:var(--space-6);border-top:1px solid var(--color-border)}
-  .bp-group h2{font-size:var(--step-2);margin-bottom:var(--space-4);display:flex;gap:.5rem;align-items:baseline}
-  .bp-count{font-family:var(--font-body);font-size:var(--step-0);color:var(--color-muted);font-weight:500}
-  .bp-list{list-style:none;margin:0;padding:0;display:grid;gap:var(--space-2)}
-  .bp-item{display:grid;grid-template-columns:14rem 1fr auto;gap:var(--space-4);align-items:center;padding:var(--space-2) 0;border-bottom:1px dashed var(--color-border)}
-  .bp-item__name{font-weight:600}
-  .bp-item__look{color:var(--color-muted);font-size:var(--step-0)}
-  .bp-item__variants{display:flex;gap:var(--space-1)}
-  .bp-item__variants .badge{text-decoration:none;min-height:1.5rem;padding:0 .5rem;font-size:.75rem}
-  .bp-item__look small{display:block;color:var(--color-muted);font-size:.75rem}
-  .bp-compare-label{display:block;font:12px system-ui;color:var(--color-muted);margin-top:.3rem}
-  .bp-filters{display:flex;flex-wrap:wrap;gap:var(--space-2);align-items:end}
-  .bp-filters label{display:grid;gap:.2rem;font:12px system-ui}
-  .bp-filters input,.bp-filters select{min-height:2.5rem;padding:.3rem .5rem}
-  .bp-compare-view{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:var(--space-3);margin-top:var(--space-4)}
-  .bp-compare-view iframe{width:100%;height:650px;border:1px solid var(--color-border)}
-  [hidden]{display:none!important}
-  @media(max-width:719px){.bp-item{grid-template-columns:1fr}}
-  </style></head>
-  <body><main class="wrap"><header class="bp-head"><p class="eyebrow">Kernel block library</p><h1>Vitris blocks</h1><p class="lede">${total} blocks across ${indexByCat.size} categories, rendered from each block's README example with the default theme and placeholder media. Variant chips render the same example with <code>variant="\u2026"</code>. Image evidence is marked unavailable or stale when no verified capture exists.</p><div class="bp-filters"><label>Find by job or name<input id="bp-search" type="search" placeholder="e.g. hours, credentials"></label><label>Page role<select id="bp-role"><option value="">Any role</option>${roleOptions}</select></label><label>Media<select id="bp-media"><option value="">Any</option><option value="optional">Works without essential media</option><option value="required">Requires media</option></select></label><label>Geometry<select id="bp-geometry"><option value="">Any</option>${geometryOptions}</select></label></div><div class="bp-toc">${toc}</div><div class="bp-compare-view" id="bp-compare-view" hidden></div></header>${groups}</main><script>
-  const items=[...document.querySelectorAll('.bp-item')];
-  const fields=['search','role','media','geometry'].map(id=>document.getElementById('bp-'+id));
-  function filter(){const [search,role,media,geometry]=fields.map(x=>x.value.toLowerCase().trim());for(const item of items){const text=item.textContent.toLowerCase()+' '+item.dataset.job.toLowerCase();item.hidden=!!(search&&!text.includes(search)||role&&!item.dataset.role.toLowerCase().split('|').includes(role)||media&&item.dataset.media!==media||geometry&&!item.dataset.geometry.toLowerCase().split('|').includes(geometry));}for(const group of document.querySelectorAll('.bp-group'))group.hidden=![...group.querySelectorAll('.bp-item')].some(x=>!x.hidden);}
-  fields.forEach(x=>x.addEventListener('input',filter));
-  document.querySelectorAll('.bp-compare').forEach(box=>box.addEventListener('change',()=>{const selected=[...document.querySelectorAll('.bp-compare:checked')];if(selected.length>2){selected[0].checked=false;selected.shift();}const view=document.getElementById('bp-compare-view');view.hidden=!selected.length;view.innerHTML='';for(const item of selected){const frame=document.createElement('iframe');frame.title='Comparison: '+item.value;frame.src=item.value;view.append(frame);}}));
-  </script></body></html>`
-);
-console.log(`Wrote ${total} block previews to ${outRoot}`);
-if (argv.includes("--serve")) {
-  const portIdx = argv.indexOf("--port");
-  const port = portIdx >= 0 ? Number(argv[portIdx + 1]) || 4173 : 4173;
-  const types = { ".html": "text/html; charset=utf-8", ".css": "text/css", ".js": "text/javascript", ".svg": "image/svg+xml" };
-  const server = createServer((req, res) => {
-    const urlPath = decodeURIComponent((req.url ?? "/").split("?")[0]);
-    let rel = normalize(urlPath).replace(/^(\.\.[/\\])+/, "");
-    if (rel.endsWith("/") || rel === "\\" || rel === "") rel = join(rel, "index.html");
-    const file = join(outRoot, rel);
-    if (!file.startsWith(outRoot) || !existsSync(file) || !statSync(file).isFile()) {
-      res.writeHead(404, { "content-type": "text/plain" }).end("Not found");
-      return;
-    }
-    res.writeHead(200, { "content-type": types[extname(file)] ?? "application/octet-stream" });
-    res.end(readFileSync(file));
-  });
-  server.listen(port, "127.0.0.1", () => {
-    console.log(`Serving block previews at http://127.0.0.1:${port}/ (Ctrl+C to stop)`);
-  });
-}

package/blocks/CONVENTIONS.md

@@ -1,121 +0,0 @@
-# Block conventions
-
-Original vanilla blocks for Vitris agents. Inspired by modern small-business templates (Apex / Munch / Verdict visual language) — not a port of any paid library.
-
-## How agents use blocks
-
-These conventions govern library maintenance and optional block reuse. In `composition-v1`, a site author may consult an eligible block after describing the content relationship; the gallery and shortlist are not mandatory authoring steps. The procedure below applies to block selection and `blocks-v0` authoring.
-
-1. Open [`INDEX.md`](INDEX.md) and pick by **role** (hero, feature, faq, …) and **register** (trade / beauty / b2b / food / professional).
-2. Open the block's `README.md`. The **Slots** table lists every slot and whether it is optional; the **Example** is a complete, working authoring snippet — copy it, then swap copy and media.
-3. Copy `blocks/<category>/<name>/` into the site as `components/<your-kebab-name>/`. Rename the root class if you rename the folder (`c-<folder>`).
-4. Compose pages with authoring tags + optional `variant="…"`.
-
-Sites own their components. Blocks are copy sources in the kernel package (`node_modules/@vitris/kernel/blocks/`).
-
-`blocks/` is the source of truth. `scripts/generate-blocks.ts` only produced the first draft and refuses to overwrite the library without `--force`. After editing a README, regenerate the index with `node --experimental-strip-types scripts/write-blocks-index.ts`.
-
-## Previewing blocks
-
-From the kernel repo: `npm run blocks:serve` renders every block's README example (once per variant) into `dist/blocks/` and serves it at `http://127.0.0.1:4173/` (default theme, placeholder media, islands live). `npm run blocks:preview` only writes the files.
-
-From an installed package, run `vitris-blocks --out <output-directory>` (or `vitris-blocks --serve --out <output-directory>`). This is a compiled JavaScript bin; Node does not strip TypeScript under `node_modules`. The gallery marks image evidence current, stale, or unavailable, and supports job/role/media/geometry filters plus two-block comparison.
-
-Because the preview renders the README example, the example _is_ the visual spec. Keep it realistic: 3–4 cards, real-length copy, one CTA pair.
-
-## Anatomy of a block
-
-```
-blocks/<category>/<name>/
-  template.html   root `.c-<name>`; bare <slot> elements; layout classes only
-  styles.css      `.c-<name>…` rules on top of kernel primitives; tokens only
-  README.md       look line, metadata, Slots table, Example, variants
-  island.js       optional; kernel islands (`data-island="…"`) are preferred
-```
-
-### Slots carry the content classes
-
-Templates expose bare slots. Typography classes live on the slotted content so authors control emphasis without touching the template:
-
-```html
-<feature-grid-3>
-  <p slot="eyebrow" class="eyebrow eyebrow--accent">Why homeowners call us first</p>
-  <h2 slot="heading">Built for Maine weather.</h2>
-  <p slot="lede" class="lede">Three things every crew member signs up for.</p>
-  <article slot="items" class="card">…</article>
-</feature-grid-3>
-```
-
-Heroes use the default slot for `<h1>` + `<p class="lede lede--lg">` + a `.btn-group`; named slots for `eyebrow`, `media`, and optional `proof`.
-
-### README contract (enforced by `src/blocks.test.ts`)
-
-- `## Slots` table: `| \`slot\` | description |`. Descriptions starting with "Optional" mark non-required slots. Every `<slot name>` in the template must appear here and vice-versa; the default slot is documented as `(default)`.
-- `## Example` fenced `html` block whose outer tag is `<name …>` and which fills every required slot.
-- The flattened example must not leave a stray `<slot>` or nest block elements inside `<p>`.
-
-## Section rhythm
-
-Four useful head patterns. Choose or adapt them to the section's job and surrounding rhythm:
-
-```html
-<!-- left-aligned (default for feature / services / process / about / team / blog) -->
-<div class="section__head"><slot name="eyebrow"></slot><slot name="heading"></slot><slot name="lede"></slot></div>
-
-<!-- centered (pricing / testimonial / FAQ / CTA cards / contact cards / menu / values / trust) -->
-<div class="section__head section__head--center">…</div>
-
-<!-- head + actions on one row (carousels, "All projects" links) -->
-<div class="section__head section__head--row"><div>…</div><div class="btn-group">…</div></div>
-
-<!-- editorial split: short label column left, heading + lede right (about / work / interior pages) -->
-<div class="section__head section__head--split"><slot name="eyebrow"></slot><slot name="heading"></slot><slot name="lede"></slot></div>
-```
-
-`.section__head` supplies a readable default measure and gap. Page-specific CSS may change those values where the composition needs it.
-
-Interior pages need a clear page purpose, one `h1`, and a useful opening. `hero/hero-page`, `hero/hero-service`, and `work/case-header` are starting points; a site-owned opening may fit better. Use `content/prose-split`, `content/list-split`, and `content/glossary` when their structure helps the reader. Plain semantic prose is also valid.
-
-## Spacing, borders, radii
-
-- Prefer semantic spacing tokens. `.grid`, `.split`, and `.card__body` are useful defaults; a site-owned layout may replace them. Control trailing margins so content does not create accidental gaps.
-- Border, surface, radius, and elevation follow the selected direction. `.card` variants provide available treatments, not required styling.
-- Give media explicit dimensions and a deliberate crop. `.frame` and `.ratio-*` are optional presentation helpers. A hero image that is the LCP candidate should use `fetchpriority="high"`.
-- Photo tiles with text over a scrim use `.photo-card` (`<a class="photo-card"><img><div class="photo-card__body"><h3>…</h3><p>…</p></div></a>`). The scrim and light text live in the primitive, so block CSS stays token-only.
-- Mosaics (`testimonial-mosaic`, `gallery-mosaic-split`) span tiles with `is-wide` / `is-tall` on the slotted tile. Fill every cell in the example — an empty cell reads as a bug.
-- Pill choices in forms use `<fieldset class="chips"><legend>…</legend><label><input type="radio"><span>…</span></label>…</fieldset>`; town lists and jump-navs reuse the same pill look.
-- Stats: `.stat` / `.stat__value` (`--step-4`), `.stat--sm` in bands. Prices: `.price` / `.price__amount` / `.price__period`.
-- Let long button labels reflow or change the layout so controls remain readable and reachable. On small screens, preserve essential navigation and actions; secondary actions may move into an accessible drawer.
-
-## Mobile
-
-Check blocks at mobile and desktop widths, and at intermediate widths where their content changes. These are examples, not universal geometry rules:
-
-- Photo grids may stack or remain two-up when crop, captions, and tap targets support that choice.
-- Stats can stack or pair according to label length and reading order.
-- Navbars retain the brand, primary route access, and important actions at narrow widths; drawer transformation is one option.
-- Tables must remain understandable and operable on narrow screens. A labeled responsive layout can be preferable to horizontal scrolling.
-
-## Dark bands
-
-Use `variant="dark"` where the block documents it (CTA / footer / quote / stats bands). That remaps tokens locally on the block root — not a global dark theme.
-
-For a dark *panel inside* a light block (founder quote, stat tiles, a CTA tile in a photo grid, the service-hero quote card) put `data-scheme="dark"` on that element — in the template or on the slotted tile. It remaps the same tokens, so `.card`, `.stat`, `.btn-outline` and friends adapt without any hex in block CSS.
-
-## Motion & islands
-
-- Scroll reveal stays on authoring tags (`motion="editorial"`).
-- Interactive widgets use `data-island="header|carousel|tabs|before-after|counter|lightbox"`.
-- `data-count-to` counts integers only — leave decimals (4.9) as static text.
-- No autoplay carousels, no scroll-jacking, no background video autoplay.
-- Tabs (`process-stepper`, `testimonial-switcher`, `feature-tabs`) hide panels with the `hidden` attribute. If a panel has its own `display` (e.g. `.photo-card` is flex), add `.c-x__panels > [hidden]{display:none}` or the hidden panel will still render.
-- No marquees — not for logos, not for CTA copy (`design-system/MASTER.md`). Use `trust-logos` / `trust-reviews` and a static `cta-band` instead, even when a reference site scrolls them.
-- Hover-expanding panels (`services-panels`) must also expand on `:focus-within`, and the first panel is open by default when nothing is hovered.
-
-## Icons
-
-Inline SVG with class `.icon` (see [`icons.md`](icons.md)). Stroke icons, currentColor, 24 viewBox. Filled glyphs (stars, play) set `fill: currentColor; stroke: none` locally.
-
-## Tokens only
-
-Block CSS must use `var(--color-*)`, `var(--space-*)`, `var(--step-*)`, `var(--radius*)`, `var(--shadow-*)`. No raw hex except inside documented dark variants / overlays / scrims that intentionally set a local palette. Use `color-mix(in srgb, var(--color-text) 85%, transparent)` for translucent overlays instead of `#000`.