@bestagentkits/render 0.1.1-next.1 → 0.3.0

package/dist/registry/roster.js

@@ -12,82 +12,49 @@
  * cannot drift apart.
  */
 import { EMBED_PROVIDER_NAMES } from '../spec/providers.js';
-const DEFAULT_MIGRATION = 'Props are additive; removed props are reported as diagnostics, never silently dropped.';
-const DEFAULT_SERIALIZER = 'Serializes back to the same Page Spec shape; child blocks keep their order and slots.';
-const DEFAULT_SIZING = {
-    sizes: ['medium', 'large'],
-    default: 'medium',
-    responsive: 'Fills its parent slot and reflows its content; never clips or scales by transform.',
-};
-const str = (o = {}) => ({
-    kind: 'string',
-    ...o,
-});
-const txt = (o = {}) => ({
-    kind: 'text',
-    ...o,
-});
-const num = (o = {}) => ({ kind: 'number', ...o });
-const urlProp = (o = {}) => ({
-    kind: 'url',
-    ...o,
-});
-const list = (of, o = {}) => ({ kind: 'list', of, ...o });
-const obj = (fields, o = {}) => ({ kind: 'object', fields, ...o });
-const oneOf = (options, o = {}) => ({ kind: 'oneOf', options, ...o });
-const enumStr = (values, o = {}) => ({
-    kind: 'string',
-    enum: values,
-    ...o,
-});
-const idProp = (description) => ({ kind: 'string', id: true, description });
-const actionMap = (description) => ({
-    kind: 'json',
-    description,
-    maxBytes: 8_000,
-    schemaRef: '#/$defs/actionMap',
-});
-/** Reusable prop fragments. */
-const onProp = (description = 'Declarative action bindings for this block.') => actionMap(description);
-const anchorProps = {
-    id: idProp('Stable node id. Author-provided ids are used verbatim and must be unique.'),
-};
-const itemsOf = (fields, o = {}) => list(obj(fields), { required: true, minItems: o.minItems ?? 1, maxItems: o.maxItems ?? 200 });
-const TITLE = str({ required: true, maxLength: 200 });
-const OPTIONAL_TITLE = str({ maxLength: 200 });
-const LABEL = str({ required: true, maxLength: 200 });
-/** Chart kinds, SVG-first and deterministic. */
-export const CHART_KINDS = [
-    'bar',
-    'line',
-    'area',
-    'pie',
-    'donut',
-    'sparkline',
-    'progress',
+import { anchorProps, bool, define, enumStr, idProp, itemsOf, LABEL, list, num, OPTIONAL_TITLE, obj, oneOf, onProp, semantic, str, TITLE, txt, urlProp, VERBATIM_DESCRIPTION, } from './define-helpers.js';
+export { CHART_KINDS } from '../blocks/chart/chart-kinds.js';
+export * from './define-helpers.js';
+/**
+ * Features the core compiler emits. Block groups may add their own features
+ * (see `FeatureModule`); the registry rejects any name outside both lists.
+ */
+export const CORE_RUNTIME_FEATURES = [
+    'tabs',
+    'accordion',
+    'carousel',
+    'slider',
+    'copy',
+    'filter',
+    'theme',
+    'dialog',
+    'chart',
+    'diagram',
+    'media',
+    'outline',
+    'bento',
+    'marquee',
+    'terminal',
+    'tree',
+    'before-after',
+    'kpi',
+    'showcase',
+    'cta',
+    'frame',
+    'checklist',
+    'state',
 ];
-function define(specification) {
-    return {
-        version: 1,
-        kind: 'primitive',
-        sizing: DEFAULT_SIZING,
-        a11y: 'Renders semantic markup; text alternatives come from the authored content.',
-        actions: [],
-        runtimeFeatures: [],
-        assets: [],
-        network: 'none',
-        migration: DEFAULT_MIGRATION,
-        serializer: DEFAULT_SERIALIZER,
-        ...specification,
-    };
-}
-function semantic(specification) {
-    return define({ kind: 'semantic', ...specification });
-}
-export const BLOCK_DEFINITIONS = [
+/**
+ * Core blocks: the roster entries that have not moved into a block module
+ * under `src/blocks/`. The registry appends every module's definition.
+ */
+export const CORE_BLOCK_DEFINITIONS = [
     // --- root ---------------------------------------------------------------
     define({
         type: 'page',
+        category: 'layout',
+        tags: ['root', 'document'],
+        useCases: ['page shell'],
         kind: 'semantic',
         purpose: 'The document root. Synthesized by the normalizer from the spec envelope.',
         summary: 'Page root: title, description, locale, and top-level blocks.',
@@ -102,40 +69,26 @@ export const BLOCK_DEFINITIONS = [
     // --- layout primitives --------------------------------------------------
     define({
         type: 'section',
+        category: 'layout',
+        tags: ['container', 'heading', 'band'],
+        useCases: ['group related blocks', 'dark feature band'],
         purpose: 'A titled group of blocks.',
-        summary: 'Section with an optional heading wrapping child blocks.',
-        props: { title: OPTIONAL_TITLE, ...anchorProps },
-        slots: { children: { accepts: '*', min: 1, max: 200 } },
-    }),
-    define({
-        type: 'stack',
-        purpose: 'Vertical flow container.',
-        summary: 'Stack: children flow vertically with a controlled gap.',
-        props: { gap: enumStr(['tight', 'normal', 'loose'], { default: 'normal' }), ...anchorProps },
-        slots: { children: { accepts: '*', min: 1, max: 200 } },
-    }),
-    define({
-        type: 'grid',
-        purpose: 'Responsive grid container.',
-        summary: 'Grid: children in N columns that collapse on narrow viewports.',
+        summary: 'Section with an optional heading wrapping child blocks; an inverse surface sets it on a night band.',
         props: {
-            columns: num({ integer: true, min: 1, max: 6, default: 3 }),
+            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({
-        type: 'split',
-        purpose: 'Two-column split container.',
-        summary: 'Split: two child groups side by side, stacking when narrow.',
-        props: {
-            ratio: enumStr(['even', 'wide-left', 'wide-right'], { default: 'even' }),
-            ...anchorProps,
-        },
-        slots: { children: { accepts: '*', min: 2, max: 2 } },
-    }),
     define({
         type: 'spacer',
+        category: 'layout',
+        tags: ['spacing'],
+        useCases: ['vertical breathing room'],
         purpose: 'Vertical rhythm spacer.',
         summary: 'Spacer: vertical space without content.',
         props: { size: enumStr(['small', 'medium', 'large'], { default: 'medium' }), ...anchorProps },
@@ -143,6 +96,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'divider',
+        category: 'layout',
+        tags: ['rule', 'separator'],
+        useCases: ['separate sections'],
         purpose: 'Horizontal rule with an optional label.',
         summary: 'Divider: semantic separator with an optional label.',
         props: { label: str({ maxLength: 120 }), ...anchorProps },
@@ -151,6 +107,9 @@ export const BLOCK_DEFINITIONS = [
     // --- typography and content --------------------------------------------
     define({
         type: 'heading',
+        category: 'content',
+        tags: ['title', 'outline'],
+        useCases: ['section title'],
         purpose: 'Section heading at a chosen level.',
         summary: 'Heading: h1–h6 with the author-chosen level.',
         props: {
@@ -162,6 +121,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'text',
+        category: 'content',
+        tags: ['prose', 'paragraph'],
+        useCases: ['body copy'],
         purpose: 'A paragraph, lead sentence, or caption.',
         summary: 'Text: single paragraph with body, lead, or caption treatment.',
         props: {
@@ -172,32 +134,45 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'rich-text',
+        category: 'content',
+        tags: ['prose', 'inline-marks'],
+        useCases: ['formatted paragraphs'],
         purpose: 'Multi-paragraph prose.',
         summary: 'RichText: multiple paragraphs from line breaks.',
         props: { text: txt({ required: true }), ...anchorProps },
     }),
     define({
         type: 'quote',
+        category: 'content',
+        tags: ['testimonial', 'citation'],
+        useCases: ['customer quote', 'pull quote'],
         purpose: 'Pulled quotation.',
         summary: 'Quote: blockquote with an optional attribution.',
         props: { text: txt({ required: true }), cite: str({ maxLength: 200 }), ...anchorProps },
     }),
     define({
         type: 'code',
+        category: 'content',
+        tags: ['source', 'snippet', 'copy'],
+        useCases: ['code sample', 'command to copy'],
         purpose: 'Code or configuration sample.',
         summary: 'Code: preformatted block with optional language and copy target.',
         props: {
             language: str({ maxLength: 32, default: 'text' }),
             title: OPTIONAL_TITLE,
-            text: txt({ required: true, maxLength: 100_000 }),
+            text: txt({ required: true, maxLength: 100_000, description: VERBATIM_DESCRIPTION }),
             ...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({
         type: 'badge',
+        category: 'content',
+        tags: ['label', 'status'],
+        useCases: ['status label'],
         purpose: 'Short status or category label.',
         summary: 'Badge: inline status chip.',
         props: {
@@ -208,6 +183,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'kbd',
+        category: 'content',
+        tags: ['keyboard', 'shortcut'],
+        useCases: ['keyboard shortcut'],
         purpose: 'Keyboard key sequence.',
         summary: 'Kbd: one or more keys rendered as <kbd> elements.',
         props: {
@@ -218,6 +196,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'key-value',
+        category: 'content',
+        tags: ['metadata', 'pairs'],
+        useCases: ['spec sheet', 'document metadata'],
         purpose: 'Compact definition list.',
         summary: 'KeyValue: label/value pairs rendered as a description list.',
         props: {
@@ -230,6 +211,9 @@ export const BLOCK_DEFINITIONS = [
     // --- information --------------------------------------------------------
     define({
         type: 'card',
+        category: 'layout',
+        tags: ['surface', 'container'],
+        useCases: ['boxed summary', 'feature card'],
         purpose: 'Bounded content container.',
         summary: 'Card: titled container that holds child blocks.',
         props: { title: OPTIONAL_TITLE, text: txt(), ...anchorProps },
@@ -237,6 +221,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'alert',
+        category: 'content',
+        tags: ['notice', 'status'],
+        useCases: ['warning banner', 'status notice'],
         purpose: 'Inline notice.',
         summary: 'Alert: notice with tone and title.',
         props: {
@@ -249,6 +236,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     semantic({
         type: 'callout',
+        category: 'content',
+        tags: ['note', 'aside'],
+        useCases: ['tip or note', 'highlighted aside'],
         purpose: 'Emphasized aside for a key point or risk.',
         summary: 'Callout: highlighted aside with tone, title, and body.',
         props: {
@@ -260,23 +250,40 @@ export const BLOCK_DEFINITIONS = [
     }),
     semantic({
         type: 'hero',
+        category: 'content',
+        tags: ['landing', 'headline', 'intro'],
+        useCases: ['landing page header', 'report title'],
         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({
+                asset: 'images',
+                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',
+        category: 'data',
+        tags: ['numbers', 'summary'],
+        useCases: ['headline numbers', 'report summary'],
         purpose: 'KPI or summary figures.',
         summary: 'Stats: labeled values as a figure list.',
         props: {
@@ -288,6 +295,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'progress',
+        category: 'data',
+        tags: ['completion', 'bars'],
+        useCases: ['completion status', 'goal tracking'],
         purpose: 'Single progress or completeness value.',
         summary: 'Progress: single bar with an accessible value range.',
         props: {
@@ -301,6 +311,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     semantic({
         type: 'steps',
+        category: 'content',
+        tags: ['process', 'ordered'],
+        useCases: ['how-to steps', 'onboarding flow'],
         purpose: 'Ordered procedure.',
         summary: 'Steps: numbered sequence of titled steps.',
         props: {
@@ -313,6 +326,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     semantic({
         type: 'timeline',
+        category: 'content',
+        tags: ['chronology', 'history'],
+        useCases: ['release history', 'project milestones'],
         purpose: 'Chronological or staged events.',
         summary: 'Timeline: ordered entries with a when/title/body shape.',
         props: {
@@ -325,6 +341,9 @@ export const BLOCK_DEFINITIONS = [
     // --- collections --------------------------------------------------------
     define({
         type: 'list',
+        category: 'content',
+        tags: ['bullets', 'items'],
+        useCases: ['bullet list', 'checklist of points'],
         purpose: 'Short item list with optional badges.',
         summary: 'List: bulleted items with optional status badges.',
         props: {
@@ -338,6 +357,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     semantic({
         type: 'card-grid',
+        category: 'content',
+        tags: ['cards', 'overview'],
+        useCases: ['feature overview', 'link directory'],
         purpose: 'Grid of short cards.',
         summary: 'CardGrid: titled cards in a responsive grid.',
         props: {
@@ -348,6 +370,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'table',
+        category: 'data',
+        tags: ['tabular', 'rows', 'columns'],
+        useCases: ['tabular data', 'comparison rows'],
         purpose: 'Tabular data with a header row.',
         summary: 'Table: columns and rows with a real header row.',
         props: {
@@ -361,6 +386,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     semantic({
         type: 'comparison',
+        category: 'data',
+        tags: ['versus', 'options'],
+        useCases: ['compare options', 'plan comparison'],
         purpose: 'Side-by-side comparison of two alternatives.',
         summary: 'Comparison: two labeled columns of points.',
         props: {
@@ -373,6 +401,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     semantic({
         type: 'risk-matrix',
+        category: 'data',
+        tags: ['risk', 'impact', 'likelihood'],
+        useCases: ['risk register', 'threat assessment'],
         purpose: 'Impact/likelihood risk table.',
         summary: 'RiskMatrix: risks rated by impact and likelihood.',
         props: {
@@ -389,50 +420,11 @@ export const BLOCK_DEFINITIONS = [
         a11y: 'Ratings are text values in table cells, never colour-only.',
     }),
     // --- interactive collections -------------------------------------------
-    define({
-        type: 'tabs',
-        purpose: 'Tabbed groups of related content.',
-        summary: 'Tabs: roving-tabindex tablist with tabpanels.',
-        props: {
-            title: OPTIONAL_TITLE,
-            items: itemsOf({ id: idProp('Tab id.'), title: LABEL, text: txt({ required: true }) }, { minItems: 2 }),
-            on: onProp('Optional state binding fired when a tab is selected.'),
-            ...anchorProps,
-        },
-        runtimeFeatures: ['tabs'],
-        actions: ['select-tab'],
-        a11y: 'role="tablist" with arrow-key roving focus, aria-selected, aria-controls, and labelled tabpanels.',
-    }),
-    define({
-        type: 'accordion',
-        purpose: 'Collapsible sections.',
-        summary: 'Accordion: disclosure sections that expand and collapse.',
-        props: {
-            title: OPTIONAL_TITLE,
-            items: itemsOf({ title: LABEL, text: txt({ required: true }) }),
-            on: onProp('Optional state binding fired when a section toggles.'),
-            ...anchorProps,
-        },
-        runtimeFeatures: ['accordion'],
-        actions: ['toggle', 'expand', 'collapse'],
-        a11y: 'Native <details>/<summary> where possible; otherwise button + region with aria-expanded.',
-    }),
-    define({
-        type: 'carousel',
-        purpose: 'Sequenced slides with manual navigation.',
-        summary: 'Carousel: prev/next, keyboard, and swipe across slides.',
-        props: {
-            ariaLabel: str({ required: true, maxLength: 120 }),
-            items: itemsOf({ title: LABEL, text: txt({ required: true }) }, { minItems: 1 }),
-            on: onProp('Optional state binding fired when the active slide changes.'),
-            ...anchorProps,
-        },
-        runtimeFeatures: ['carousel'],
-        actions: ['next', 'previous'],
-        a11y: 'Labeled region with prev/next buttons, arrow-key support, a slide counter, and no autoplay.',
-    }),
     semantic({
         type: 'toolbar',
+        category: 'interaction',
+        tags: ['controls', 'actions'],
+        useCases: ['page actions', 'quick links'],
         purpose: 'Row of controls or chips.',
         summary: 'Toolbar: buttons, badges, and links in one accessible row.',
         props: {
@@ -466,26 +458,12 @@ export const BLOCK_DEFINITIONS = [
         a11y: 'role="toolbar" with roving focus order; every control is a real button or link.',
     }),
     // --- data visualization -------------------------------------------------
-    define({
-        type: 'chart',
-        purpose: 'Deterministic SVG chart with a text summary.',
-        summary: 'Chart: bar, line, area, pie, donut, sparkline, or progress from labeled series.',
-        props: {
-            kind: enumStr(CHART_KINDS, { required: true }),
-            title: OPTIONAL_TITLE,
-            description: txt(),
-            labels: list(str({ maxLength: 80 }), { required: true, minItems: 1, maxItems: 200 }),
-            series: itemsOf({ label: LABEL, values: list(num(), { required: true, minItems: 1, maxItems: 200 }) }, { minItems: 1 }),
-            ...anchorProps,
-        },
-        runtimeFeatures: ['chart'],
-        assets: ['chart'],
-        a11y: 'SVG carries role="img" plus a generated text summary; the same values are available as a table for assistive technology.',
-        serializer: 'Serializes to the labels/series data, never to rendered SVG.',
-    }),
     // --- diagrams (adapter) -------------------------------------------------
     semantic({
         type: 'diagram-panel',
+        category: 'engineering',
+        tags: ['diagram', 'architecture'],
+        useCases: ['architecture diagram', 'flow chart'],
         purpose: 'Typed diagram rendered through an adapter.',
         summary: 'DiagramPanel: embeds trusted output from a diagram adapter (ak:diagram when installed).',
         props: {
@@ -506,47 +484,222 @@ 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.',
     }),
-    // --- media --------------------------------------------------------------
+    // --- showcase -----------------------------------------------------------
     define({
-        type: 'image',
-        purpose: 'Single image or picture.',
-        summary: 'Image: local asset or allowlisted URL with required alt text.',
+        type: 'marquee',
+        category: 'showcase',
+        tags: ['ticker', 'logos'],
+        useCases: ['customer logos', 'highlight ticker'],
+        purpose: 'Continuously scrolling strip of short highlights.',
+        summary: 'Marquee: looping ticker of short items that pauses on hover and stops under reduced motion.',
         props: {
-            src: urlProp({ required: true }),
-            alt: str({ required: true, maxLength: 300 }),
+            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',
+        category: 'engineering',
+        tags: ['shell', 'commands', 'output'],
+        useCases: ['install steps', 'cli session'],
+        purpose: 'A command-line session: commands with their output.',
+        summary: 'Terminal: window-framed session that types in on load; commands, output 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, description: VERBATIM_DESCRIPTION }),
+            }, { 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',
+        category: 'engineering',
+        tags: ['files', 'paths', 'repository'],
+        useCases: ['project layout', 'changed files'],
+        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',
+        category: 'media',
+        tags: ['comparison', 'slider', 'images'],
+        useCases: ['redesign comparison', 'visual diff'],
+        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, asset: 'images' }),
+                alt: str({ required: true, maxLength: 300 }),
+                label: str({ maxLength: 40, default: 'Before' }),
+            }, { required: true }),
+            after: obj({
+                src: urlProp({ required: true, asset: 'images' }),
+                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',
-        assets: ['media'],
-        a11y: 'Alt text is required; decorative images must use an empty alt explicitly.',
+        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: 'gallery',
-        purpose: 'Image grid.',
-        summary: 'Gallery: responsive image grid with captions.',
+        type: 'kpi',
+        category: 'data',
+        tags: ['metrics', 'sparkline', 'trend'],
+        useCases: ['dashboard metrics', 'performance summary'],
+        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,
-            columns: num({ integer: true, min: 1, max: 6, default: 3 }),
             items: itemsOf({
-                src: urlProp({ required: true }),
-                alt: str({ required: true, maxLength: 300 }),
-                caption: txt(),
+                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',
+        category: 'showcase',
+        tags: ['spotlight', 'screenshot'],
+        useCases: ['feature spotlight', 'product tour'],
+        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, asset: 'images' }),
+            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',
+        category: 'data',
+        tags: ['tasks', 'status'],
+        useCases: ['launch checklist', 'review 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',
+        category: 'showcase',
+        tags: ['conversion', 'action'],
+        useCases: ['sign-up prompt', 'closing call to action'],
+        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',
+        category: 'media',
+        tags: ['picture', 'figure'],
+        useCases: ['screenshot', 'illustration'],
+        purpose: 'Single image or picture.',
+        summary: 'Image: local asset or allowlisted URL with required alt text.',
+        props: {
+            src: urlProp({ required: true, asset: 'images' }),
+            alt: str({ required: true, maxLength: 300 }),
+            caption: txt(),
             ...anchorProps,
         },
         network: 'optional',
         assets: ['media'],
-        a11y: 'Every image keeps its alt text; captions are visible text, not tooltips.',
+        a11y: 'Alt text is required; decorative images must use an empty alt explicitly.',
     }),
     define({
         type: 'video',
+        category: 'media',
+        tags: ['player', 'poster'],
+        useCases: ['product demo', 'recorded talk'],
         purpose: 'Local video or a network-denied fallback.',
-        summary: 'Video: plays local sources; a provider reference becomes a poster plus link; network sources degrade to poster plus link.',
+        summary: 'Video: plays local sources; a provider or network source degrades to a poster plus link.',
         props: {
             title: LABEL,
-            src: urlProp({ required: true }),
-            poster: urlProp(),
+            src: urlProp({ required: true, asset: 'media' }),
+            poster: urlProp({ asset: 'images', rejectBlocked: true }),
             provider: enumStr(EMBED_PROVIDER_NAMES, {
                 description: 'Network media provider. Requires the media capability and this provider in the page provider allowlist; the page still links out instead of embedding.',
             }),
@@ -565,11 +718,14 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'audio',
+        category: 'media',
+        tags: ['player', 'sound'],
+        useCases: ['podcast clip', 'voice note'],
         purpose: 'Local audio or a network-denied fallback.',
-        summary: 'Audio: plays local sources; a provider reference becomes metadata plus link; network sources degrade to metadata plus link.',
+        summary: 'Audio: plays local sources; a provider or network source degrades to metadata plus link.',
         props: {
             title: LABEL,
-            src: urlProp({ required: true }),
+            src: urlProp({ required: true, asset: 'media' }),
             provider: enumStr(EMBED_PROVIDER_NAMES, {
                 description: 'Network media provider. Requires the media capability and this provider in the page provider allowlist; the page still links out instead of embedding.',
             }),
@@ -589,6 +745,9 @@ export const BLOCK_DEFINITIONS = [
     // --- controls -----------------------------------------------------------
     define({
         type: 'button',
+        category: 'interaction',
+        tags: ['action', 'control'],
+        useCases: ['trigger an action', 'primary call'],
         purpose: 'Single actionable control.',
         summary: 'Button: clickable control with declarative action bindings.',
         props: {
@@ -603,6 +762,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'link',
+        category: 'interaction',
+        tags: ['navigation', 'anchor'],
+        useCases: ['external link', 'related page'],
         purpose: 'Navigational link.',
         summary: 'Link: allowlisted URL with descriptive text.',
         props: { label: LABEL, href: urlProp({ required: true }), ...anchorProps },
@@ -611,6 +773,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'slider',
+        category: 'interaction',
+        tags: ['range', 'input', 'state'],
+        useCases: ['adjust a value', 'what-if input'],
         purpose: 'Bounded numeric input.',
         summary: 'Slider: range input with pointer drag and full keyboard support.',
         props: {
@@ -628,6 +793,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'search',
+        category: 'interaction',
+        tags: ['filter', 'input'],
+        useCases: ['filter a list', 'find an item'],
         purpose: 'Filter input for a collection.',
         summary: 'Search: labeled filter input bound to a collection.',
         props: {
@@ -642,6 +810,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'dialog',
+        category: 'interaction',
+        tags: ['modal', 'overlay'],
+        useCases: ['confirmation', 'detail popup'],
         purpose: 'Modal detail surface.',
         summary: 'Dialog: native <dialog> with labeled title and close controls.',
         props: {
@@ -658,6 +829,9 @@ export const BLOCK_DEFINITIONS = [
     // --- review-specific semantic blocks ------------------------------------
     semantic({
         type: 'diff-summary',
+        category: 'engineering',
+        tags: ['diff', 'changes'],
+        useCases: ['change summary', 'pull request files'],
         purpose: 'Changed-file summary from a diff.',
         summary: 'DiffSummary: file paths with change status and line counts.',
         props: {
@@ -674,6 +848,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     semantic({
         type: 'code-review',
+        category: 'engineering',
+        tags: ['review', 'findings'],
+        useCases: ['review findings', 'audit notes'],
         purpose: 'Structured review findings.',
         summary: 'CodeReview: good/bad/ugly/concern/question findings.',
         props: {
@@ -688,5 +865,4 @@ export const BLOCK_DEFINITIONS = [
         a11y: 'The finding kind is written as text; tone colour is decorative.',
     }),
 ];
-export const BLOCKS_BY_TYPE = new Map(BLOCK_DEFINITIONS.map((definition) => [definition.type, definition]));
 //# sourceMappingURL=roster.js.map