@bestagentkits/render 0.1.1-next.1 → 0.2.0

package/dist/mcp-server.js

@@ -0,0 +1,274 @@
+/**
+ * `ak-render mcp`: the compiler as a Model Context Protocol server over stdio.
+ *
+ * The tools mirror the CLI so an agent follows the same loop either way:
+ * `catalog` → `describe` → `validate` → `render`. `render` writes the HTML to a
+ * file and returns only a summary, because the point of the compiler is to keep
+ * presentation bytes out of the model's context.
+ *
+ * The transport is newline-delimited JSON-RPC 2.0 on stdin/stdout, implemented
+ * here without an SDK so the package keeps its single runtime dependency.
+ * Nothing in this module touches the network.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { isRenderError } from './errors.js';
+import { catalog, describe } from './registry/registry.js';
+import { compile } from './render/render.js';
+import { validate } from './spec/validate.js';
+import { buildThemeCatalog } from './theme/theme-catalog.js';
+import { PACKAGE_NAME, VERSION } from './version.js';
+/** Protocol revisions this server answers with; the newest is the default. */
+const PROTOCOL_VERSIONS = ['2024-11-05', '2025-03-26', '2025-06-18', '2025-11-25'];
+const LATEST_PROTOCOL = PROTOCOL_VERSIONS[PROTOCOL_VERSIONS.length - 1];
+const INSTRUCTIONS = `AK Render compiles a Page Spec (YAML or JSON) into one self-contained, offline HTML file.
+Loop: call catalog once, describe only the block types you plan to use, validate the spec and fix every diagnostic by its JSON path, then render to a file.
+Describe meaning, not presentation: the compiler owns layout, colour, typography and motion.`;
+const SPEC_INPUT = {
+    description: 'The Page Spec: YAML or JSON text, or the parsed object.',
+    anyOf: [{ type: 'string' }, { type: 'object' }],
+};
+const text = (value) => ({
+    content: [
+        { type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) },
+    ],
+});
+const failure = (value) => ({ ...text(value), isError: true });
+const HTML_FILE = /\.html?$/iu;
+function themeCatalogFor(context) {
+    return buildThemeCatalog({ cwd: context.cwd, home: context.home, discovery: true });
+}
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string' || value === '') {
+        throw new TypeError(`"${key}" must be a non-empty string`);
+    }
+    return value;
+}
+const TOOLS = [
+    {
+        name: 'catalog',
+        description: 'List every block type and action with a one-line summary. Call once per task, then describe only the types you use.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        run: () => text(catalog()),
+    },
+    {
+        name: 'describe',
+        description: 'Full contract for one block type: props with defaults and bounds, slots, actions, runtime features, network needs and accessibility.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: { type: 'string', description: 'Block type from catalog, e.g. "hero".' },
+            },
+            required: ['type'],
+            additionalProperties: false,
+        },
+        run: (args) => text(describe(requireString(args, 'type'))),
+    },
+    {
+        name: 'validate',
+        description: 'Check a Page Spec without rendering. Returns ok plus diagnostics, each with a code and the JSON path to fix.',
+        inputSchema: {
+            type: 'object',
+            properties: { spec: SPEC_INPUT },
+            required: ['spec'],
+            additionalProperties: false,
+        },
+        run: (args) => {
+            const result = validate(args.spec, { source: '<spec>' });
+            return result.ok ? text(result) : failure(result);
+        },
+    },
+    {
+        name: 'render',
+        description: 'Compile a Page Spec and write the standalone HTML to `out`. Returns a summary (bytes, hash, features, warnings), never the HTML itself.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                spec: SPEC_INPUT,
+                out: {
+                    type: 'string',
+                    description: 'HTML file to write (.html or .htm). A relative path resolves against the server working directory; an absolute path is used as given.',
+                },
+                theme: { type: 'string', description: 'Optional preset name overriding the spec theme.' },
+            },
+            required: ['spec', 'out'],
+            additionalProperties: false,
+        },
+        run: (args, context) => {
+            const out = resolve(context.cwd, requireString(args, 'out'));
+            // The tool only ever writes pages; refusing other extensions keeps a
+            // misdirected call from replacing a config or source file with HTML.
+            if (!HTML_FILE.test(out))
+                throw new TypeError('"out" must end in .html or .htm');
+            const theme = args.theme;
+            const result = compile(args.spec, {
+                source: '<spec>',
+                themeCatalog: themeCatalogFor(context),
+                ...(typeof theme === 'string' && theme !== '' ? { theme } : {}),
+            });
+            mkdirSync(dirname(out), { recursive: true });
+            writeFileSync(out, result.html, 'utf8');
+            return text({
+                out,
+                bytes: result.bytes,
+                hash: result.hash,
+                title: result.ir.meta.title,
+                theme: result.theme.name,
+                features: result.features,
+                nodes: result.ir.nodes.length,
+                warnings: result.warnings,
+            });
+        },
+    },
+    {
+        name: 'themes',
+        description: 'List theme presets (built-ins plus project or user presets discovered on disk) and any preset file that failed to load.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        run: (_args, context) => {
+            const themes = themeCatalogFor(context);
+            const presets = themes.sources
+                .map(({ name, origin }) => ({ name, origin }))
+                .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+            // A preset file that failed to load is reported, not silently dropped.
+            return text({ presets, problems: themes.problems });
+        },
+    },
+];
+function callTool(tool, params, context) {
+    const args = (params.arguments ?? {});
+    try {
+        return tool.run(args, context);
+    }
+    catch (error) {
+        if (isRenderError(error)) {
+            return failure({
+                code: error.code,
+                message: error.message,
+                path: error.path ?? '$',
+                ...(error.details?.diagnostics === undefined
+                    ? {}
+                    : { diagnostics: error.details.diagnostics }),
+            });
+        }
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+}
+function isRequest(message) {
+    return (typeof message === 'object' &&
+        message !== null &&
+        message.jsonrpc === '2.0' &&
+        typeof message.method === 'string');
+}
+/**
+ * Answer one JSON-RPC message. Returns `undefined` for notifications and for
+ * responses sent to us, which need no reply.
+ */
+export function handleMcpMessage(message, context) {
+    if (!isRequest(message)) {
+        const id = message?.id;
+        const isResponse = typeof message === 'object' &&
+            message !== null &&
+            ('result' in message || 'error' in message);
+        if (isResponse)
+            return undefined;
+        return {
+            jsonrpc: '2.0',
+            id: typeof id === 'string' || typeof id === 'number' ? id : null,
+            error: { code: -32600, message: 'invalid request' },
+        };
+    }
+    if (message.id === undefined)
+        return undefined;
+    // MCP requires a string or number id; null is reserved for error replies.
+    if (message.id === null) {
+        return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'invalid request' } };
+    }
+    const id = message.id;
+    const params = message.params ?? {};
+    const reply = (result) => ({ jsonrpc: '2.0', id, result });
+    switch (message.method) {
+        case 'initialize': {
+            const requested = params.protocolVersion;
+            const protocolVersion = PROTOCOL_VERSIONS.find((version) => version === requested);
+            return reply({
+                protocolVersion: protocolVersion ?? LATEST_PROTOCOL,
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: { name: PACKAGE_NAME, version: VERSION },
+                instructions: INSTRUCTIONS,
+            });
+        }
+        case 'ping':
+            return reply({});
+        case 'tools/list':
+            return reply({
+                tools: TOOLS.map(({ name, description, inputSchema }) => ({
+                    name,
+                    description,
+                    inputSchema,
+                })),
+            });
+        case 'tools/call': {
+            const tool = TOOLS.find((candidate) => candidate.name === params.name);
+            if (tool === undefined) {
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    error: { code: -32602, message: `unknown tool: ${String(params.name)}` },
+                };
+            }
+            return reply(callTool(tool, params, context));
+        }
+        default:
+            return {
+                jsonrpc: '2.0',
+                id,
+                error: { code: -32601, message: `method not found: ${message.method}` },
+            };
+    }
+}
+/** Answer one line of the stdio transport, or return `undefined` for no reply. */
+export function handleMcpLine(line, context) {
+    if (line.trim() === '')
+        return undefined;
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        return JSON.stringify({
+            jsonrpc: '2.0',
+            id: null,
+            error: { code: -32700, message: 'parse error' },
+        });
+    }
+    // Revision 2025-03-26 allows batches: answer each member, omit the silent ones.
+    if (Array.isArray(message)) {
+        if (message.length === 0) {
+            return JSON.stringify({
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32600, message: 'invalid request' },
+            });
+        }
+        const responses = message
+            .map((member) => handleMcpMessage(member, context))
+            .filter((response) => response !== undefined);
+        return responses.length === 0 ? undefined : JSON.stringify(responses);
+    }
+    const response = handleMcpMessage(message, context);
+    return response === undefined ? undefined : JSON.stringify(response);
+}
+/** Serve MCP on stdin/stdout until stdin closes. Logs go to stderr only. */
+export function serveMcp(context = { cwd: process.cwd(), home: homedir() }) {
+    const lines = createInterface({ input: process.stdin, crlfDelay: Number.POSITIVE_INFINITY });
+    lines.on('line', (line) => {
+        const response = handleMcpLine(line, context);
+        if (response !== undefined)
+            process.stdout.write(`${response}\n`);
+    });
+    return lines;
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/dist/registry/roster.d.ts

@@ -13,7 +13,7 @@
  */
 import type { ActionType } from './actions.js';
 import type { PropSchema } from './prop-schema.js';
-export type RuntimeFeature = 'tabs' | 'accordion' | 'carousel' | 'slider' | 'copy' | 'filter' | 'theme' | 'dialog' | 'chart' | 'diagram' | 'media';
+export type RuntimeFeature = 'tabs' | 'accordion' | 'carousel' | 'slider' | 'copy' | 'filter' | 'theme' | 'dialog' | 'chart' | 'diagram' | 'media' | 'outline' | 'bento' | 'marquee' | 'terminal' | 'tree' | 'before-after' | 'kpi' | 'showcase' | 'cta' | 'frame' | 'checklist';
 export interface SlotSpec {
     /** Types accepted by the slot; `'*'` accepts any block. */
     accepts: readonly string[] | '*';

package/dist/registry/roster.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roster.d.ts","sourceRoot":"","sources":["../../src/registry/roster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,WAAW,GACX,UAAU,GACV,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,GAAG,WAAW,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,yEAAyE;IACzE,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAoFD,gDAAgD;AAChD,eAAO,MAAM,WAAW,2EAQd,CAAC;AA4BX,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EA2nBvD,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAE/D,CAAC"}
+{"version":3,"file":"roster.d.ts","sourceRoot":"","sources":["../../src/registry/roster.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,WAAW,GACX,UAAU,GACV,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GACT,OAAO,GACP,SAAS,GACT,OAAO,GACP,SAAS,GACT,UAAU,GACV,MAAM,GACN,cAAc,GACd,KAAK,GACL,UAAU,GACV,KAAK,GACL,OAAO,GACP,WAAW,CAAC;AAEhB,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,GAAG,WAAW,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,yEAAyE;IACzE,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AA0FD,gDAAgD;AAChD,eAAO,MAAM,WAAW,2EAQd,CAAC;AA4BX,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAk3BvD,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAE/D,CAAC"}

package/dist/registry/roster.js

@@ -28,6 +28,10 @@ const txt = (o = {}) => ({
     ...o,
 });
 const num = (o = {}) => ({ kind: 'number', ...o });
+const bool = (o = {}) => ({
+    kind: 'boolean',
+    ...o,
+});
 const urlProp = (o = {}) => ({
     kind: 'url',
     ...o,
@@ -103,8 +107,15 @@ export const BLOCK_DEFINITIONS = [
     define({
         type: 'section',
         purpose: 'A titled group of blocks.',
-        summary: 'Section with an optional heading wrapping child blocks.',
-        props: { title: OPTIONAL_TITLE, ...anchorProps },
+        summary: 'Section with an optional heading wrapping child blocks; an inverse surface sets it on a night band.',
+        props: {
+            title: OPTIONAL_TITLE,
+            surface: enumStr(['plain', 'inverse'], {
+                default: 'plain',
+                description: 'inverse renders the section on a dark band using the theme dark palette, in both schemes.',
+            }),
+            ...anchorProps,
+        },
         slots: { children: { accepts: '*', min: 1, max: 200 } },
     }),
     define({
@@ -193,7 +204,8 @@ export const BLOCK_DEFINITIONS = [
             ...anchorProps,
         },
         assets: ['code'],
-        a11y: 'Renders <pre><code> with the authored text; no syntax highlighting requires network access.',
+        runtimeFeatures: ['copy'],
+        a11y: 'Renders <pre><code> with the authored text and a labelled Copy button; no syntax highlighting requires network access.',
         serializer: 'Emits the code text verbatim inside the fenced block when serialized back to Markdown.',
     }),
     define({
@@ -261,19 +273,29 @@ export const BLOCK_DEFINITIONS = [
     semantic({
         type: 'hero',
         purpose: 'Page opener that states the artifact subject.',
-        summary: 'Hero: eyebrow, title, and one-line description.',
+        summary: 'Hero: eyebrow, title, and one-line description, optionally over a framed product shot.',
         props: {
             eyebrow: str({ maxLength: 80 }),
             title: TITLE,
             description: txt(),
+            align: enumStr(['start', 'center'], { default: 'start' }),
+            src: urlProp({
+                description: 'Optional product shot shown in a browser frame below the copy.',
+            }),
+            alt: str({ maxLength: 300, description: 'Required when src is set.' }),
+            address: str({
+                maxLength: 120,
+                description: 'Text shown in the frame address bar; not a link.',
+            }),
             ...anchorProps,
         },
+        network: 'optional',
         sizing: {
             sizes: ['medium', 'large'],
             default: 'large',
-            responsive: 'Full width; text reflows.',
+            responsive: 'Full width; text reflows and the product shot scales to the column without cropping.',
         },
-        a11y: 'The hero title is an <h1>; the eyebrow is supporting text, not a heading.',
+        a11y: 'The hero title is an <h1>; the eyebrow is supporting text, not a heading. The shot keeps its alt text and its frame is decorative.',
     }),
     semantic({
         type: 'stats',
@@ -506,6 +528,200 @@ export const BLOCK_DEFINITIONS = [
         a11y: 'Requires a textual fallback summary when the adapter cannot render; the fallback is always emitted.',
         migration: 'Adapter contract is versioned separately; a spec that no longer compiles degrades to the fallback.',
     }),
+    // --- showcase -----------------------------------------------------------
+    semantic({
+        type: 'bento',
+        purpose: 'Feature mosaic: tiles of mixed size that each carry one idea, figure, or image.',
+        summary: 'Bento: asymmetric tile grid; a tile can hold an eyebrow, title, text, a large figure, and a local image.',
+        props: {
+            title: OPTIONAL_TITLE,
+            items: itemsOf({
+                title: LABEL,
+                text: txt(),
+                eyebrow: str({ maxLength: 60 }),
+                value: str({ maxLength: 40, description: 'A large figure shown above the title.' }),
+                size: enumStr(['small', 'wide', 'tall', 'large'], { default: 'small' }),
+                src: urlProp({
+                    description: 'Optional image; remote sources follow the network policy.',
+                }),
+                alt: str({
+                    maxLength: 300,
+                    description: 'Required when src is set; use "" for a decorative image.',
+                }),
+            }, { minItems: 1, maxItems: 12 }),
+            ...anchorProps,
+        },
+        runtimeFeatures: ['bento'],
+        network: 'optional',
+        sizing: {
+            sizes: ['large'],
+            default: 'large',
+            responsive: 'Four columns on wide screens, two on tablets, one on phones; spans collapse with the grid.',
+        },
+        a11y: 'A list of tiles; each tile title is a heading-styled paragraph, images keep their alt text.',
+    }),
+    define({
+        type: 'marquee',
+        purpose: 'Continuously scrolling strip of short highlights.',
+        summary: 'Marquee: looping ticker of short items that pauses on hover and stops under reduced motion.',
+        props: {
+            label: str({ maxLength: 120, default: 'Highlights' }),
+            items: list(str({ required: true, maxLength: 80 }), {
+                required: true,
+                minItems: 1,
+                maxItems: 30,
+            }),
+            speed: enumStr(['slow', 'normal', 'fast'], { default: 'normal' }),
+            ...anchorProps,
+        },
+        runtimeFeatures: ['marquee'],
+        a11y: 'Screen readers get one static list; the duplicated scrolling track is aria-hidden, and motion stops under prefers-reduced-motion.',
+    }),
+    define({
+        type: 'terminal',
+        purpose: 'A command-line session: commands with their output.',
+        summary: 'Terminal: window-framed session whose lines type in on load; commands, output, comments, success, and errors are styled apart.',
+        props: {
+            title: str({ maxLength: 120, default: 'Terminal' }),
+            lines: itemsOf({
+                kind: enumStr(['command', 'output', 'comment', 'success', 'error'], {
+                    default: 'output',
+                }),
+                text: txt({ required: true, maxLength: 2_000 }),
+            }, { minItems: 1, maxItems: 60 }),
+            ...anchorProps,
+        },
+        runtimeFeatures: ['terminal', 'copy'],
+        a11y: 'Renders <pre> text; the prompt glyph is decorative, and the line reveal is skipped under reduced motion.',
+    }),
+    semantic({
+        type: 'file-tree',
+        purpose: 'Files and folders, optionally with change status, derived from flat paths.',
+        summary: 'File tree: nested folders built from slash-separated paths, with per-file status and notes.',
+        props: {
+            title: OPTIONAL_TITLE,
+            items: itemsOf({
+                path: str({ required: true, maxLength: 300 }),
+                status: enumStr(['added', 'modified', 'deleted', 'renamed', 'unchanged'], {
+                    default: 'unchanged',
+                }),
+                note: str({ maxLength: 200 }),
+            }, { minItems: 1, maxItems: 200 }),
+            ...anchorProps,
+        },
+        runtimeFeatures: ['tree'],
+        a11y: 'Nested lists mirror the folder structure; status is written as text, not only color.',
+    }),
+    semantic({
+        type: 'before-after',
+        purpose: 'Before and after: two images of the same frame, revealed by a draggable divider.',
+        summary: 'Compare: before/after image slider driven by a native range input; without script both images stay visible.',
+        props: {
+            title: OPTIONAL_TITLE,
+            before: obj({
+                src: urlProp({ required: true }),
+                alt: str({ required: true, maxLength: 300 }),
+                label: str({ maxLength: 40, default: 'Before' }),
+            }, { required: true }),
+            after: obj({
+                src: urlProp({ required: true }),
+                alt: str({ required: true, maxLength: 300 }),
+                label: str({ maxLength: 40, default: 'After' }),
+            }, { required: true }),
+            start: num({ min: 0, max: 100, default: 50 }),
+            caption: txt(),
+            ...anchorProps,
+        },
+        runtimeFeatures: ['before-after'],
+        network: 'optional',
+        a11y: 'The divider is a labelled <input type="range">: keyboard, pointer, and touch all move it, and both images keep their alt text.',
+    }),
+    semantic({
+        type: 'kpi',
+        purpose: 'Headline metrics with direction of change and a small trend line.',
+        summary: 'KPI: metric cards with value, signed delta, good/bad direction, and an optional sparkline series.',
+        props: {
+            title: OPTIONAL_TITLE,
+            items: itemsOf({
+                label: LABEL,
+                value: str({ required: true, maxLength: 40 }),
+                delta: str({ maxLength: 24 }),
+                trend: enumStr(['up', 'down', 'flat'], { default: 'flat' }),
+                good: enumStr(['up', 'down'], {
+                    default: 'up',
+                    description: 'Which direction counts as an improvement for this metric.',
+                }),
+                series: list(num({ required: true, min: -1e12, max: 1e12 }), { maxItems: 60 }),
+                caption: str({ maxLength: 120 }),
+            }, { minItems: 1, maxItems: 8 }),
+            ...anchorProps,
+        },
+        runtimeFeatures: ['kpi'],
+        a11y: 'Value, delta, and direction are text; the sparkline is decorative and aria-hidden.',
+    }),
+    semantic({
+        type: 'showcase',
+        purpose: 'Feature spotlight: copy beside a framed screenshot.',
+        summary: 'Showcase: eyebrow, title, text, and bullets beside an image in a browser frame; the image side can flip.',
+        props: {
+            eyebrow: str({ maxLength: 60 }),
+            title: TITLE,
+            text: txt(),
+            bullets: list(str({ required: true, maxLength: 200 }), { maxItems: 8 }),
+            src: urlProp({ required: true }),
+            alt: str({ required: true, maxLength: 300 }),
+            frame: enumStr(['browser', 'plain'], { default: 'browser' }),
+            address: str({
+                maxLength: 120,
+                description: 'Text shown in the browser frame address bar; not a link.',
+            }),
+            align: enumStr(['media-right', 'media-left'], { default: 'media-right' }),
+            ...anchorProps,
+        },
+        runtimeFeatures: ['showcase'],
+        network: 'optional',
+        sizing: {
+            sizes: ['large'],
+            default: 'large',
+            responsive: 'Copy and media sit side by side on wide screens and stack, media last, on narrow ones.',
+        },
+        a11y: 'The title is a heading; the frame chrome is decorative and the image keeps its alt text.',
+    }),
+    define({
+        type: 'checklist',
+        purpose: 'Task list with done and open items and a completion count.',
+        summary: 'Checklist: items marked done or open, with a visible completion count.',
+        props: {
+            title: OPTIONAL_TITLE,
+            items: itemsOf({ text: LABEL, done: bool({ default: false }) }, { maxItems: 100 }),
+            ...anchorProps,
+        },
+        a11y: 'Each item states "done" or "open" in text; the check glyph is decorative.',
+        runtimeFeatures: ['checklist'],
+    }),
+    semantic({
+        type: 'cta',
+        purpose: 'Closing call to action that sends the reader somewhere next.',
+        summary: 'CTA: eyebrow, oversized title, text, and up to three link actions on a night band.',
+        props: {
+            eyebrow: str({ maxLength: 60 }),
+            title: TITLE,
+            text: txt(),
+            actions: list(obj({
+                label: LABEL,
+                href: urlProp({ required: true }),
+                variant: enumStr(['primary', 'secondary'], { default: 'secondary' }),
+            }), { maxItems: 3 }),
+            ...anchorProps,
+        },
+        runtimeFeatures: ['cta'],
+        sizing: {
+            sizes: ['large'],
+            default: 'large',
+            responsive: 'Full width; the title scales with the viewport and the actions wrap.',
+        },
+        a11y: 'The title is an <h2>; every action is a real link with its own text.',
+    }),
     // --- media --------------------------------------------------------------
     define({
         type: 'image',