@bestagentkits/render 0.2.0 → 0.3.0

package/dist/registry/roster.js

@@ -12,86 +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 bool = (o = {}) => ({
-    kind: 'boolean',
-    ...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.',
@@ -106,6 +69,9 @@ 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; an inverse surface sets it on a night band.',
         props: {
@@ -118,35 +84,11 @@ export const BLOCK_DEFINITIONS = [
         },
         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.',
-        props: {
-            columns: num({ integer: true, min: 1, max: 6, default: 3 }),
-            ...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 },
@@ -154,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 },
@@ -162,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: {
@@ -173,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: {
@@ -183,24 +134,33 @@ 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'],
@@ -210,6 +170,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     define({
         type: 'badge',
+        category: 'content',
+        tags: ['label', 'status'],
+        useCases: ['status label'],
         purpose: 'Short status or category label.',
         summary: 'Badge: inline status chip.',
         props: {
@@ -220,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: {
@@ -230,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: {
@@ -242,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 },
@@ -249,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: {
@@ -261,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: {
@@ -272,6 +250,9 @@ 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, optionally over a framed product shot.',
         props: {
@@ -280,6 +261,7 @@ export const BLOCK_DEFINITIONS = [
             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.' }),
@@ -299,6 +281,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     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: {
@@ -310,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: {
@@ -323,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: {
@@ -335,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: {
@@ -347,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: {
@@ -360,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: {
@@ -370,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: {
@@ -383,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: {
@@ -395,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: {
@@ -411,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: {
@@ -488,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: {
@@ -529,39 +485,11 @@ export const BLOCK_DEFINITIONS = [
         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',
+        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: {
@@ -579,15 +507,18 @@ export const BLOCK_DEFINITIONS = [
     }),
     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 whose lines type in on load; commands, output, comments, success, and errors are styled apart.',
+        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 }),
+                text: txt({ required: true, maxLength: 2_000, description: VERBATIM_DESCRIPTION }),
             }, { minItems: 1, maxItems: 60 }),
             ...anchorProps,
         },
@@ -596,6 +527,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     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: {
@@ -614,17 +548,20 @@ export const BLOCK_DEFINITIONS = [
     }),
     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 }),
+                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 }),
+                src: urlProp({ required: true, asset: 'images' }),
                 alt: str({ required: true, maxLength: 300 }),
                 label: str({ maxLength: 40, default: 'After' }),
             }, { required: true }),
@@ -638,6 +575,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     semantic({
         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: {
@@ -661,6 +601,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     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: {
@@ -668,7 +611,7 @@ export const BLOCK_DEFINITIONS = [
             title: TITLE,
             text: txt(),
             bullets: list(str({ required: true, maxLength: 200 }), { maxItems: 8 }),
-            src: urlProp({ required: true }),
+            src: urlProp({ required: true, asset: 'images' }),
             alt: str({ required: true, maxLength: 300 }),
             frame: enumStr(['browser', 'plain'], { default: 'browser' }),
             address: str({
@@ -689,6 +632,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     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: {
@@ -701,6 +647,9 @@ export const BLOCK_DEFINITIONS = [
     }),
     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: {
@@ -725,10 +674,13 @@ export const BLOCK_DEFINITIONS = [
     // --- 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 }),
+            src: urlProp({ required: true, asset: 'images' }),
             alt: str({ required: true, maxLength: 300 }),
             caption: txt(),
             ...anchorProps,
@@ -737,32 +689,17 @@ export const BLOCK_DEFINITIONS = [
         assets: ['media'],
         a11y: 'Alt text is required; decorative images must use an empty alt explicitly.',
     }),
-    semantic({
-        type: 'gallery',
-        purpose: 'Image grid.',
-        summary: 'Gallery: responsive image grid with captions.',
-        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(),
-            }),
-            ...anchorProps,
-        },
-        network: 'optional',
-        assets: ['media'],
-        a11y: 'Every image keeps its alt text; captions are visible text, not tooltips.',
-    }),
     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.',
             }),
@@ -781,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.',
             }),
@@ -805,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: {
@@ -819,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 },
@@ -827,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: {
@@ -844,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: {
@@ -858,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: {
@@ -874,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: {
@@ -890,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: {
@@ -904,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