@glw907/cairn-cms 0.11.0 → 0.14.0

package/src/lib/content/types.ts

@@ -10,6 +10,7 @@
 import type { ComponentRegistry } from '../render/registry.js';
 import type { IconSet } from '../render/glyph.js';
 import type { DatePrefix } from './ids.js';
+import type { ConceptSchema } from './schema.js';
 
 /** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
 interface FieldBase {
@@ -24,16 +25,37 @@ interface FieldBase {
 /** A single-line text input. */
 export interface TextField extends FieldBase {
   type: 'text';
+  /** Minimum character length of a non-empty value. */
+  min?: number;
+  /** Maximum character length. */
+  max?: number;
+  /** Exact required character length. */
+  length?: number;
+  /** A regular-expression source string the value must match. Stored as a string so the field
+   *  list stays plain serializable data; the validator compiles it. */
+  pattern?: string;
 }
 /** A multi-line text input. */
 export interface TextareaField extends FieldBase {
   type: 'textarea';
   /** Visible rows; the editor picks a default when omitted. */
   rows?: number;
+  /** Minimum character length of a non-empty value. */
+  min?: number;
+  /** Maximum character length. */
+  max?: number;
+  /** Exact required character length. */
+  length?: number;
+  /** A regular-expression source string the value must match. */
+  pattern?: string;
 }
 /** A `YYYY-MM-DD` date input. */
 export interface DateField extends FieldBase {
   type: 'date';
+  /** Earliest allowed date, as `YYYY-MM-DD`. */
+  min?: string;
+  /** Latest allowed date, as `YYYY-MM-DD`. */
+  max?: string;
 }
 /** A checkbox; absent means false. */
 export interface BooleanField extends FieldBase {
@@ -74,18 +96,19 @@ export type ValidationResult =
   | { ok: false; errors: Record<string, string> };
 
 /**
- * Per-site configuration for one content concept (spec §8). Concept-fixed behavior such as
- * routability is not here; it lives in the engine's routing table (`CONCEPT_ROUTING`).
+ * Per-site configuration for one content concept (spec §8). One `schema`, built with
+ * `defineFields`, is the single source of truth for the editor form, the validator, and the
+ * inferred frontmatter type. Generic over the schema so a concept's concrete type survives for
+ * typed reads. Concept-fixed behavior such as routability is not here; it lives in the engine's
+ * routing table (`CONCEPT_ROUTING`).
  */
-export interface ConceptConfig {
+export interface ConceptConfig<S extends ConceptSchema = ConceptSchema> {
   /** Repo-relative content directory, e.g. "src/content/posts". */
   dir: string;
   /** Sidebar label; defaults from the concept id when omitted. */
   label?: string;
-  /** Drives the per-concept frontmatter form, in order. */
-  fields: FrontmatterField[];
-  /** Validate submitted frontmatter before any commit. */
-  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
+  /** The concept's schema: the form projection, the generated validator, and the inferred type. */
+  schema: S;
 }
 
 /**

package/src/lib/content/validate.ts

@@ -7,9 +7,11 @@ import { dateInputValue } from './frontmatter.js';
 
 /**
  * Validate raw frontmatter against a field list. Required text and date fields must be
- * non-empty; required tag fields must be non-empty lists. Booleans coerce to `true`/`false`
- * and tag fields to string arrays. Returns the normalized data, or field-keyed errors when
- * any required field is empty.
+ * non-empty; required tag fields must be non-empty lists. A present boolean coerces to `true`
+ * and an unchecked one is omitted; a present tag field coerces to a string array and an empty
+ * one is omitted; an empty optional text or date field is omitted, so the normalized data
+ * carries only meaningful values and committed frontmatter stays minimal. Returns the
+ * normalized data, or field-keyed errors when any required field is empty.
  *
  * Frontmatter may arrive from the edit form (all string values) or from `parseMarkdown`,
  * where gray-matter turns an unquoted YAML date into a JS `Date`. The `date` case coerces a
@@ -25,25 +27,26 @@ export function validateFields(
     const value = frontmatter[field.name];
     switch (field.type) {
       case 'boolean':
-        data[field.name] = value === true;
+        // Absent or unchecked means false; omit it so a published file carries no draft: false noise.
+        if (value === true) data[field.name] = true;
         break;
       case 'tags':
       case 'freetags': {
         const list = Array.isArray(value) ? value.map(String) : [];
         if (field.required && list.length === 0) errors[field.name] = `${field.label} is required`;
-        data[field.name] = list;
+        if (list.length > 0) data[field.name] = list;
         break;
       }
       case 'date': {
         const text = value instanceof Date ? dateInputValue(value) : typeof value === 'string' ? value.trim() : '';
         if (field.required && text === '') errors[field.name] = `${field.label} is required`;
-        data[field.name] = text;
+        if (text !== '') data[field.name] = text;
         break;
       }
       default: {
         const text = typeof value === 'string' ? value.trim() : '';
         if (field.required && text === '') errors[field.name] = `${field.label} is required`;
-        data[field.name] = text;
+        if (text !== '') data[field.name] = text;
       }
     }
   }

package/src/lib/delivery/content-index.ts

@@ -36,6 +36,13 @@ export interface ContentEntry<F = Record<string, unknown>> extends ContentSummar
   body: string;
 }
 
+/** One entry's validation failure, recorded at build for the site aggregator's gate. */
+export interface ContentProblem {
+  id: string;
+  draft: boolean;
+  errors: Record<string, string>;
+}
+
 /** The per-concept query surface. */
 export interface ContentIndex<F = Record<string, unknown>> {
   all(opts?: { includeDrafts?: boolean }): ContentSummary[];
@@ -43,6 +50,8 @@ export interface ContentIndex<F = Record<string, unknown>> {
   byTag(tag: string, opts?: { includeDrafts?: boolean }): ContentSummary[];
   allTags(): { tag: string; count: number }[];
   adjacent(id: string): { newer?: ContentSummary; older?: ContentSummary };
+  /** Per-entry validation failures recorded at build, for the site-level build gate. */
+  problems(): ContentProblem[];
 }
 
 /** Map a Vite eager `?raw` glob record (`{ path: raw }`) to `RawFile[]`. */
@@ -74,23 +83,30 @@ export function createContentIndex<F = Record<string, unknown>>(
   files: RawFile[],
   descriptor: ConceptDescriptor,
 ): ContentIndex<F> {
+  const problems: ContentProblem[] = [];
   const entries: ContentEntry<F>[] = files.map((file) => {
     const id = idFromFilename(basename(file.path));
     const slug = slugFromId(id, descriptor.routing.dated ? descriptor.datePrefix : null);
-    const { frontmatter, body } = parseMarkdown(file.raw);
-    const date = asDate(frontmatter.date);
+    const { frontmatter: raw, body } = parseMarkdown(file.raw);
+    const date = asDate(raw.date);
+    const draft = raw.draft === true;
+    // Validate once at build. The cheap summary stays raw-derived and robust; the typed detail
+    // frontmatter carries the normalized data on success, the raw frontmatter on failure. A
+    // failure is recorded, not thrown, so the query surface does not explode on construction.
+    const result = descriptor.validate(raw, body);
+    if (!result.ok) problems.push({ id, draft, errors: result.errors });
     return {
       id,
       slug,
       permalink: permalink(descriptor, { id, slug, date }),
-      title: asString(frontmatter.title) ?? id,
+      title: asString(raw.title) ?? id,
       date,
-      updated: asDate(frontmatter.updated),
-      tags: asTags(frontmatter.tags),
-      excerpt: deriveExcerpt(body, { description: asString(frontmatter.description) }),
+      updated: asDate(raw.updated),
+      tags: asTags(raw.tags),
+      excerpt: deriveExcerpt(body, { description: asString(raw.description) }),
       wordCount: wordCount(body),
-      draft: frontmatter.draft === true,
-      frontmatter: frontmatter as F,
+      draft,
+      frontmatter: (result.ok ? result.data : raw) as F,
       body,
     };
   });
@@ -131,5 +147,6 @@ export function createContentIndex<F = Record<string, unknown>>(
         older: i < list.length - 1 ? summarize(list[i + 1]) : undefined,
       };
     },
+    problems: () => problems,
   };
 }

package/src/lib/delivery/index.ts

@@ -4,9 +4,11 @@
 // helpers, the catch-all route loaders, and the head component. It imports nothing from auth,
 // github, or email, so importing it does not pull the server backend into a public bundle.
 export { createContentIndex, fromGlob } from './content-index.js';
-export type { RawFile, ContentSummary, ContentEntry, ContentIndex } from './content-index.js';
+export type { RawFile, ContentSummary, ContentEntry, ContentIndex, ContentProblem } from './content-index.js';
 export { createSiteIndex } from './site-index.js';
 export type { SiteIndex, ConceptIndex } from './site-index.js';
+export { createSiteIndexes } from './site-indexes.js';
+export type { SiteIndexes, SiteGlobs } from './site-indexes.js';
 export { siteDescriptors } from './site-descriptors.js';
 export { deriveExcerpt, wordCount } from './excerpt.js';
 export { buildRssFeed, buildJsonFeed } from './feeds.js';
@@ -16,6 +18,8 @@ export type { SitemapUrl } from './sitemap.js';
 export { buildRobots } from './robots.js';
 export { buildSeoMeta } from './seo.js';
 export type { SeoInput, SeoMeta } from './seo.js';
+export { readSeoFields, resolveImageUrl } from './seo-fields.js';
+export type { SeoFields } from './seo-fields.js';
 export { paginate } from './paginate.js';
 export type { Page } from './paginate.js';
 export { rssResponse, jsonFeedResponse, sitemapResponse, robotsResponse } from './responses.js';

package/src/lib/delivery/seo-fields.ts

@@ -0,0 +1,43 @@
+// cairn-cms: the SEO head fields read at the cross-concept boundary (schema-source-of-truth design,
+// Plan 3). The catch-all route resolves any concept by request path, so the entry's frontmatter is
+// typed Record<string, unknown>; this reads the known head fields by name and coerces. Kept apart
+// from seo.ts (the head builder) so reading frontmatter and building the head stay distinct concerns.
+
+/** The head fields a concept can carry in frontmatter. Each is optional and omitted when absent.
+ *  `author` is article-scoped downstream: the head builder emits `article:author` only for a dated
+ *  entry, so an `author` on an undated Page is read here but not rendered. */
+export interface SeoFields {
+  description?: string;
+  image?: string;
+  robots?: string;
+  author?: string;
+}
+
+const KEYS = ['description', 'image', 'robots', 'author'] as const;
+
+/** Read the known SEO head fields off an entry's normalized frontmatter. Keeps a present string,
+ *  trimmed, and omits an absent, empty, or non-string value. Trimming the stored value keeps a stray
+ *  `robots: "  noindex  "` from reaching the head tag with surrounding whitespace. The field must be
+ *  declared in the concept's schema to survive the validate-once read; an undeclared key is not on the
+ *  normalized frontmatter. */
+export function readSeoFields(frontmatter: Record<string, unknown>): SeoFields {
+  const fields: SeoFields = {};
+  for (const key of KEYS) {
+    const value = frontmatter[key];
+    if (typeof value === 'string' && value.trim() !== '') fields[key] = value.trim();
+  }
+  return fields;
+}
+
+/** Resolve an author-supplied image path to an absolute URL against the site origin. An absolute or
+ *  protocol-relative URL passes through; a root-relative path anchors to the origin; a malformed
+ *  string returns undefined rather than throwing at build. The sites use a bare-domain origin, so a
+ *  bare path also anchors to the origin root; against a sub-path origin it would resolve relative to
+ *  that path, per the WHATWG URL rules. */
+export function resolveImageUrl(image: string, origin: string): string | undefined {
+  try {
+    return new URL(image, origin).href;
+  } catch {
+    return undefined;
+  }
+}

package/src/lib/delivery/site-index.ts

@@ -30,33 +30,32 @@ function normalizePath(path: string): string {
   return path.length > 1 ? path.replace(/\/+$/, '') : path;
 }
 
-/** Validate every entry (drafts included) against its concept, aggregating failures. */
-function validateAll(concepts: ConceptIndex[]): void {
+/** Collect non-draft validation failures across concepts from each index's recorded verdicts. */
+function siteProblems(concepts: ConceptIndex[]): string[] {
   const problems: string[] = [];
   for (const { descriptor, index } of concepts) {
-    for (const summary of index.all({ includeDrafts: true })) {
-      const entry = index.byId(summary.id);
-      if (!entry) continue;
-      const result = descriptor.validate(entry.frontmatter, entry.body);
-      if (!result.ok) {
-        for (const [field, message] of Object.entries(result.errors)) {
-          problems.push(`${descriptor.dir}/${summary.id}: ${field}: ${message}`);
-        }
+    for (const problem of index.problems()) {
+      if (problem.draft) continue; // a half-finished draft never ships, so it does not fail the build
+      for (const [field, message] of Object.entries(problem.errors)) {
+        problems.push(`${descriptor.dir}/${problem.id}: ${field}: ${message}`);
       }
     }
   }
-  if (problems.length > 0) {
-    throw new Error(`site index: ${problems.length} invalid frontmatter field(s):\n  ${problems.join('\n  ')}`);
-  }
+  return problems;
 }
 
 /**
  * Union per-concept indexes into a site-level resolver. Throws on a duplicate permalink and,
- * unless `validate` is `false`, on any entry whose frontmatter fails its concept's validator,
- * so malformed content fails the build instead of shipping.
+ * unless `validate` is `false`, on any non-draft entry whose frontmatter fails its concept's
+ * validator, so malformed content fails the build instead of shipping.
  */
 export function createSiteIndex(concepts: ConceptIndex[], opts: { validate?: boolean } = {}): SiteIndex {
-  if (opts.validate !== false) validateAll(concepts);
+  if (opts.validate !== false) {
+    const problems = siteProblems(concepts);
+    if (problems.length > 0) {
+      throw new Error(`site index: ${problems.length} invalid frontmatter field(s):\n  ${problems.join('\n  ')}`);
+    }
+  }
   const byPath = new Map<string, { index: ContentIndex; id: string }>();
   const byId = new Map<string, ContentIndex>();
   for (const { descriptor, index } of concepts) {

package/src/lib/delivery/site-indexes.ts

@@ -0,0 +1,52 @@
+// cairn-cms: the full-auto typed site index (schema-source-of-truth design). It maps over a
+// defineAdapter-typed adapter to give one typed per-concept index, with frontmatter typed as the
+// concept's inferred schema type, plus a site resolver for the catch-all route. It is the typed
+// convenience over createContentIndex and createSiteIndex, not a replacement: both stay the
+// lower-level escape hatch. It imports only pure content and delivery code, so the delivery
+// bundle stays backend-free.
+import type { CairnAdapter, ConceptConfig } from '../content/types.js';
+import type { Infer } from '../content/schema.js';
+import type { SiteConfig } from '../nav/site-config.js';
+import { siteDescriptors } from './site-descriptors.js';
+import { createContentIndex, fromGlob } from './content-index.js';
+import { createSiteIndex } from './site-index.js';
+import type { ContentIndex } from './content-index.js';
+import type { ConceptIndex, SiteIndex } from './site-index.js';
+
+/** A per-concept raw glob record (`{ path: raw }`) keyed by concept id, from `import.meta.glob`. */
+export type SiteGlobs<A extends CairnAdapter> = {
+  [K in keyof A['content']]?: Record<string, string>;
+};
+
+/** The typed per-concept indexes plus the cross-concept `site` resolver. A concept literally named
+ *  `site` is not supported, since `site` is the reserved resolver key. */
+export type SiteIndexes<A extends CairnAdapter> = {
+  [K in keyof A['content']]: ContentIndex<
+    NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? Infer<S> : Record<string, unknown>
+  >;
+} & { readonly site: SiteIndex };
+
+/**
+ * Build typed per-concept indexes and a site resolver from one adapter. Pass the per-concept raw
+ * globs as `{ posts: import.meta.glob('...?raw', { eager: true }), ... }`; Vite needs the literal
+ * glob at the call site, so the engine cannot glob on the site's behalf. `validate: false` opts out
+ * of the build gate, exactly as on `createSiteIndex`.
+ */
+export function createSiteIndexes<const A extends CairnAdapter>(
+  adapter: A,
+  config: SiteConfig,
+  globs: SiteGlobs<A>,
+  opts: { validate?: boolean } = {},
+): SiteIndexes<A> {
+  const descriptors = siteDescriptors(adapter, config);
+  const byConcept: Record<string, ContentIndex> = {};
+  const conceptIndexes: ConceptIndex[] = [];
+  for (const descriptor of descriptors) {
+    const record = (globs as Record<string, Record<string, string> | undefined>)[descriptor.id] ?? {};
+    const index = createContentIndex(fromGlob(record), descriptor);
+    byConcept[descriptor.id] = index;
+    conceptIndexes.push({ descriptor, index });
+  }
+  const site = createSiteIndex(conceptIndexes, opts);
+  return { ...byConcept, site } as SiteIndexes<A>;
+}

package/src/lib/index.ts

@@ -37,7 +37,9 @@ export {
   serializeMarkdown,
   parseMarkdown,
 } from './content/frontmatter.js';
-export { validateFields } from './content/validate.js';
+export { defineFields } from './content/schema.js';
+export { defineAdapter } from './content/adapter.js';
+export type { ConceptSchema, Infer, InferFields, DefineFieldsOptions, StandardInput, StandardSchemaV1 } from './content/schema.js';
 export {
   isValidId,
   idFromFilename,
@@ -72,7 +74,6 @@ export {
   isElement,
   strProp,
   iconSpan,
-  splitHead,
   cardShell,
   markFirstList,
 } from './render/rehype-dispatch.js';
@@ -119,9 +120,12 @@ export type {
   ContentSummary,
   ContentEntry,
   ContentIndex,
+  ContentProblem,
 } from './delivery/content-index.js';
 export { createSiteIndex } from './delivery/site-index.js';
 export type { SiteIndex, ConceptIndex } from './delivery/site-index.js';
+export { createSiteIndexes } from './delivery/site-indexes.js';
+export type { SiteIndexes, SiteGlobs } from './delivery/site-indexes.js';
 export { deriveExcerpt, wordCount } from './delivery/excerpt.js';
 export { buildRssFeed, buildJsonFeed } from './delivery/feeds.js';
 export type { FeedChannel, FeedItem } from './delivery/feeds.js';
@@ -130,5 +134,7 @@ export type { SitemapUrl } from './delivery/sitemap.js';
 export { buildRobots } from './delivery/robots.js';
 export { buildSeoMeta } from './delivery/seo.js';
 export type { SeoInput, SeoMeta } from './delivery/seo.js';
+export { readSeoFields, resolveImageUrl } from './delivery/seo-fields.js';
+export type { SeoFields } from './delivery/seo-fields.js';
 export { paginate } from './delivery/paginate.js';
 export type { Page } from './delivery/paginate.js';

package/src/lib/render/component-grammar.ts

@@ -84,14 +84,19 @@ function childrenToText(children: RootContent[]): string {
   return String(toMd.stringify(root)).trim();
 }
 
-/** Parse a serialized component directive back into guided-form values, the inverse of
- *  {@link serializeComponent}. The grammar is reversible, so the editor can round-trip a
- *  saved directive through the form. */
-export async function parseComponent(markdown: string, def: ComponentDef): Promise<ComponentValues> {
+// Parse the markdown and find the component's opening container directive. The single seam both
+// parseComponent and parseRawAttributeKeys (and the combined validator helper) build on, so one
+// parse derives both the form values and the raw attribute keys.
+function findComponentRoot(markdown: string, def: ComponentDef): (RootContent & DirectiveNode) | undefined {
   const tree = unified().use(remarkParse).use(remarkDirective).parse(markdown) as Root;
-  const root = tree.children.find(
+  return tree.children.find(
     (c): c is RootContent & DirectiveNode => isContainer(c) && (c as DirectiveNode).name === def.name,
   );
+}
+
+// Build guided-form values from an already-found component root. Returns the empty base when the
+// root is absent.
+function valuesFromRoot(root: (RootContent & DirectiveNode) | undefined, def: ComponentDef): ComponentValues {
   const values = emptyComponentValues(def);
   if (!root) return values;
 
@@ -126,14 +131,33 @@ export async function parseComponent(markdown: string, def: ComponentDef): Promi
   return values;
 }
 
+// The raw attribute keys on an already-found component root.
+function rawKeysFromRoot(root: (RootContent & DirectiveNode) | undefined): string[] {
+  return Object.keys(root?.attributes ?? {});
+}
+
+/** Parse a serialized component directive back into guided-form values, the inverse of
+ *  {@link serializeComponent}. The grammar is reversible, so the editor can round-trip a
+ *  saved directive through the form. */
+export async function parseComponent(markdown: string, def: ComponentDef): Promise<ComponentValues> {
+  return valuesFromRoot(findComponentRoot(markdown, def), def);
+}
+
 /** The raw attribute keys present on the component's opening directive, read from the parsed tree
  *  (quote-aware, unlike a regex over the source). Used by validation to flag unknown keys. */
 export function parseRawAttributeKeys(markdown: string, def: ComponentDef): string[] {
-  const tree = unified().use(remarkParse).use(remarkDirective).parse(markdown) as Root;
-  const root = tree.children.find(
-    (c): c is RootContent & DirectiveNode => isContainer(c) && (c as DirectiveNode).name === def.name,
-  );
-  return Object.keys(root?.attributes ?? {});
+  return rawKeysFromRoot(findComponentRoot(markdown, def));
+}
+
+/** Parse the component once and derive both the guided-form values and the raw attribute keys.
+ *  Validation needs both, so this seam spares it the double parse that calling
+ *  {@link parseComponent} and {@link parseRawAttributeKeys} separately would cost. */
+export async function parseComponentWithRawKeys(
+  markdown: string,
+  def: ComponentDef,
+): Promise<{ values: ComponentValues; rawKeys: string[] }> {
+  const root = findComponentRoot(markdown, def);
+  return { values: valuesFromRoot(root, def), rawKeys: rawKeysFromRoot(root) };
 }
 
 // A bare parse base: empty strings, false, and empty lists, with no attribute defaults applied. The

package/src/lib/render/component-validate.ts

@@ -1,11 +1,11 @@
-import { parseComponent, parseRawAttributeKeys } from './component-grammar.js';
+import { parseComponentWithRawKeys } from './component-grammar.js';
 import type { ComponentDef } from './registry.js';
 
 /** A validation verdict: ok, or field-keyed error messages. */
 export type ComponentValidation = { ok: true } | { ok: false; errors: Record<string, string> };
 
 export async function validateComponent(markdown: string, def: ComponentDef): Promise<ComponentValidation> {
-  const values = await parseComponent(markdown, def);
+  const { values, rawKeys } = await parseComponentWithRawKeys(markdown, def);
   const errors: Record<string, string> = {};
   const declared = new Set((def.attributes ?? []).map((f) => f.key));
 
@@ -21,7 +21,7 @@ export async function validateComponent(markdown: string, def: ComponentDef): Pr
     }
   }
 
-  for (const key of parseRawAttributeKeys(markdown, def)) {
+  for (const key of rawKeys) {
     if (!declared.has(key)) errors[key] = `Unknown attribute "${key}".`;
   }
 

package/src/lib/render/glyph.ts

@@ -4,11 +4,15 @@ import type { Element } from 'hast';
 /** A glyph name to SVG path-data map (the site owns the icon set). */
 export type IconSet = Record<string, string>;
 
-/** Inline SVG glyph as a real hast node: class ec-glyph, 256 viewBox, currentColor fill. */
+/** Inline SVG glyph as a real hast node: class ec-glyph, 256 viewBox, currentColor fill.
+ *  An unknown icon name yields the bare svg shell with no path child, so it never serializes
+ *  a stray empty (or undefined) path. Callers always wrap the returned element, so the shell
+ *  keeps them safe. */
 export function glyph(name: string, icons: IconSet): Element {
+  const d = icons[name];
   return s(
     'svg',
     { className: ['ec-glyph'], viewBox: '0 0 256 256', fill: 'currentColor', ariaHidden: 'true' },
-    [s('path', { d: icons[name] })],
+    d == null ? [] : [s('path', { d })],
   );
 }

package/src/lib/render/registry.ts

@@ -3,7 +3,7 @@
 // (Plan 04) and the future component palette both derive from this single source, so the
 // parser, the render dispatch, and the editor never drift apart. The adapter references
 // `ComponentRegistry` from here.
-import type { Element } from 'hast';
+import type { Element, ElementContent } from 'hast';
 
 /** The input types a component attribute or repeatable item field can take. */
 export type FieldType = 'text' | 'select' | 'icon' | 'boolean';
@@ -38,6 +38,21 @@ export interface SlotDef {
   itemFields?: AttributeField[];
 }
 
+/** The structured input a component's `build` receives. The engine stamps the component's
+ *  attributes and partitions its slots from the rendered hast, so `build` arranges hast and
+ *  never walks the tree. `slot(name)` returns a slot's rendered children (title, body, or any
+ *  named slot); `items(name)` returns a repeatable slot's items, one child list per item. */
+export interface ComponentContext {
+  /** Declared attribute values, keyed by attribute key. Booleans are real booleans. */
+  attributes: Record<string, string | boolean>;
+  /** A named slot's rendered children. Returns `[]` for an absent or empty slot. */
+  slot(name: string): ElementContent[];
+  /** A repeatable slot's items, each item its own list of rendered children. `[]` when absent. */
+  items(name: string): ElementContent[][];
+  /** The stamped component element, for an escape hatch. Most builds never need it. */
+  node: Element;
+}
+
 /** A site component: how it inserts (editor) and how it renders (rehype). */
 export interface ComponentDef {
   /** Directive name, e.g. 'card' (matches `:::card`). */
@@ -48,10 +63,10 @@ export interface ComponentDef {
   description: string;
   /** Markdown scaffold inserted at the cursor by the editor palette. */
   insertTemplate?: string;
-  /** Build the final hast element from the stamped directive element. The engine
-   *  stamps the entrance-stagger ordinal (`data-rise`) on the top-level result, so a
-   *  build fn stays free of any motion concern. */
-  build: (node: Element) => Element;
+  /** Build the final hast element from the component context (attributes plus partitioned
+   *  slots). The engine stamps the entrance-stagger ordinal (`data-rise`) on the top-level
+   *  result, so a build fn stays free of any motion concern. */
+  build: (ctx: ComponentContext) => Element;
   /** Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. */
   defaultIconByRole?: Record<string, string>;
   /** One line on when to reach for this component; feeds the picker and the reference file. */
@@ -69,6 +84,13 @@ export interface ComponentRegistry {
   defaultIcon(name: string, role?: string): string | undefined;
 }
 
+/** The hast property name carrying one declared attribute from stamp to dispatch, e.g. `tone`
+ *  becomes `dataAttrTone`. The directive stamp writes it and the rehype dispatch reads it, so both
+ *  sides derive the name from this one helper rather than spelling the capitalize twice. */
+export function dataAttrProp(key: string): string {
+  return `dataAttr${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+}
+
 /**
  * Build a registry from a site's component definitions. The single source the render
  * pipeline (directive stamp plus rehype dispatch) and the editor palette both read.