@glw907/cairn-cms 0.11.0 → 0.17.0

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,64 @@
+// 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 globRecord = globs as Record<string, Record<string, string> | undefined>;
+  const byConcept: Record<string, ContentIndex> = {};
+  const conceptIndexes: ConceptIndex[] = [];
+  for (const descriptor of descriptors) {
+    if (descriptor.id === 'site') {
+      throw new Error(
+        'createSiteIndexes: a concept cannot be named "site", which is the reserved cross-concept resolver key',
+      );
+    }
+    if (!Object.prototype.hasOwnProperty.call(globRecord, descriptor.id)) {
+      const passed = Object.keys(globRecord);
+      throw new Error(
+        `createSiteIndexes: no glob passed for concept "${descriptor.id}"; pass its import.meta.glob (an empty {} for an intentionally empty concept). Globs passed: ${passed.length ? passed.join(', ') : '(none)'}`,
+      );
+    }
+    const record = globRecord[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/env.ts

@@ -13,6 +13,19 @@ export function requireOrigin(env: { PUBLIC_ORIGIN?: string }): string {
   if (!origin) {
     throw new Error('PUBLIC_ORIGIN is not configured');
   }
+  let hostname: string;
+  try {
+    hostname = new URL(origin).hostname;
+  } catch {
+    throw new Error(`PUBLIC_ORIGIN is not a valid URL, got ${origin}`);
+  }
+  // The magic-link origin must be https in production so the link and the __Host- cookie are
+  // origin-bound. http is allowed only for local dev on localhost or 127.0.0.1, matched exactly so
+  // a lookalike host like localhost.example.com cannot skip the https requirement.
+  const isLocal = hostname === 'localhost' || hostname === '127.0.0.1';
+  if (!origin.startsWith('https://') && !isLocal) {
+    throw new Error(`PUBLIC_ORIGIN must be https in production, got ${origin}`);
+  }
   return origin;
 }
 

package/src/lib/github/signing.ts

@@ -79,6 +79,38 @@ export async function installationToken(creds: AppCredentials): Promise<string>
   return ((await res.json()) as { token: string }).token;
 }
 
+interface CachedToken {
+  token: string;
+  expiresAt: number;
+}
+
+/**
+ * Build an installation-token cache. A module-global instance memoizes the minted token per
+ * installation for most of its one-hour life, so a warm Worker isolate reuses it across requests
+ * instead of re-signing and re-calling GitHub on every list and commit. A cold isolate re-mints,
+ * which is always safe. This mirrors the default of @octokit/auth-app, which caches installation
+ * tokens in memory and returns them until expiry. The TTL stays under GitHub's documented one-hour
+ * lifetime, so a fixed margin avoids parsing the API expiry. `mint` and `now` are injected so the
+ * cache is testable with no network call and no real clock.
+ */
+export function createInstallationTokenCache(
+  mint: (creds: AppCredentials) => Promise<string> = installationToken,
+  now: () => number = () => Date.now(),
+  ttlMs = 55 * 60 * 1000,
+): (creds: AppCredentials) => Promise<string> {
+  const cache = new Map<string, CachedToken>();
+  return async function get(creds: AppCredentials): Promise<string> {
+    const hit = cache.get(creds.installationId);
+    if (hit && hit.expiresAt > now()) return hit.token;
+    const token = await mint(creds);
+    cache.set(creds.installationId, { token, expiresAt: now() + ttlMs });
+    return token;
+  };
+}
+
+/** The shared installation-token cache, one instance per Worker isolate. */
+export const cachedInstallationToken = createInstallationTokenCache();
+
 /**
  * Deploy-time self-test for the App signer: sign a dummy JWT with the configured key. It
  * exercises the brittle PKCS#1-to-PKCS#8 conversion and the Web Crypto import and sign with

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/pipeline.ts

@@ -6,6 +6,9 @@ import remarkRehype from 'remark-rehype';
 import rehypeRaw from 'rehype-raw';
 import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
+import rehypeSanitize from 'rehype-sanitize';
+import type { Schema } from 'hast-util-sanitize';
+import { buildSanitizeSchema, rehypeAnchorRel } from './sanitize-schema.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
 import { rehypeDispatch } from './rehype-dispatch.js';
 import type { ComponentRegistry } from './registry.js';
@@ -15,6 +18,15 @@ export interface RendererOptions {
    *  CSS can drive an entrance-cascade delay off it. Omit for no stagger. The ordinal
    *  is inert, so a consumer's sanitize floor can keep `data-rise` and drop `style`. */
   stagger?: boolean;
+  /** Extend the sanitize allowlist. Receives cairn's default schema (defaultSchema plus the
+   *  directive markers and the common benign tags) and returns the schema to use. Add to the
+   *  allowlist for the benign HTML a site's content needs; start from the argument so the
+   *  dangerous strip is preserved. */
+  sanitizeSchema?: (defaults: Schema) => Schema;
+  /** Developer-only escape hatch: disable the sanitize floor entirely. This reintroduces the XSS
+   *  vector the floor closes, so it is only for a site whose content is fully developer-controlled.
+   *  It is a code-level adapter decision, never an editor-facing setting. */
+  unsafeDisableSanitize?: boolean;
 }
 
 /** Compose a site's render pipeline from its component registry: directive syntax to
@@ -22,7 +34,19 @@ export interface RendererOptions {
  *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
 export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
   const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
-  const rehypePlugins: PluggableList = [rehypeRaw, [rehypeDispatch, registry, options.stagger], rehypeSlug];
+  // The sanitize floor runs after rehype-raw (so author raw HTML is parsed, then cleaned) and
+  // before the dispatch (so the site's trusted build() output and its inline SVG icons are never
+  // sanitized). The anchor-rel hardening runs last so it also covers component-built anchors.
+  const floor: PluggableList = options.unsafeDisableSanitize
+    ? []
+    : [[rehypeSanitize, buildSanitizeSchema(registry, options.sanitizeSchema)]];
+  const rehypePlugins: PluggableList = [
+    rehypeRaw,
+    ...floor,
+    [rehypeDispatch, registry, options.stagger],
+    rehypeSlug,
+    rehypeAnchorRel,
+  ];
   const processor = unified()
     .use(remarkParse)
     .use(remarkGfm)

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.

package/src/lib/render/rehype-dispatch.ts

@@ -1,6 +1,6 @@
 import type { Root, Element, ElementContent } from 'hast';
 import { h } from 'hastscript';
-import type { ComponentRegistry } from './registry.js';
+import { dataAttrProp, type ComponentContext, type ComponentDef, type ComponentRegistry } from './registry.js';
 
 export function isElement(node: ElementContent | undefined): node is Element {
   return !!node && node.type === 'element';
@@ -23,24 +23,6 @@ export function iconSpan(glyphEl: Element, role?: string): Element {
 /** A site's icon factory: turn a stamped icon name + role into a hast element. */
 export type MakeIcon = (name: string, role?: string) => Element;
 
-// Pull the section's <h2> out, retag it .card-title, and build the .ec-head row
-// (optional icon + heading). Returns the head plus the remaining body children.
-// `makeIcon` (site-supplied) turns the stamped data-icon into an element; omit it
-// for a head with no icon.
-export function splitHead(node: Element, makeIcon?: MakeIcon): { head: Element; rest: ElementContent[] } {
-  const children = node.children as ElementContent[];
-  const i = children.findIndex((c) => isElement(c) && c.tagName === 'h2');
-  const h2 = children[i] as Element;
-  h2.properties = { ...h2.properties, className: ['card-title'] };
-  const rest = children.filter((_, j) => j !== i);
-  const icon = strProp(node, 'dataIcon');
-  const role = strProp(node, 'dataRole');
-  const headKids: ElementContent[] = [];
-  if (makeIcon && icon) headKids.push(makeIcon(icon, role));
-  headKids.push(h2);
-  return { head: h('div', { className: ['ec-head'] }, headKids), rest };
-}
-
 /** Section wrapper: `<section class=…><div class="card-body">…</div></section>`. */
 export function cardShell(classes: string[], body: ElementContent[]): Element {
   return h('section', { className: classes }, [h('div', { className: ['card-body'] }, body)]);
@@ -70,11 +52,76 @@ function transformChildren(children: ElementContent[], registry: ComponentRegist
   });
 }
 
+// Read a stamped attribute back into its typed value. Booleans arrive as the strings
+// 'true'/'false'; everything else is the literal string the author wrote.
+function readAttributes(node: Element, def: ComponentDef): Record<string, string | boolean> {
+  const out: Record<string, string | boolean> = {};
+  for (const field of def.attributes ?? []) {
+    const value = strProp(node, dataAttrProp(field.key));
+    if (value == null) continue;
+    out[field.key] = field.type === 'boolean' ? value === 'true' : value;
+  }
+  return out;
+}
+
+// The title label paragraph carries data-slot="title"; build() wants its inline children, not
+// the marked paragraph. Return the paragraph's children.
+function stripSlotMarker(child: ElementContent): ElementContent[] {
+  return isElement(child) ? (child.children as ElementContent[]) : [child];
+}
+
+// Split a component's stamped children into named slots and the default body. A child marked
+// data-slot="title"/<name> routes to that slot; an unmarked child is body. A repeatable slot
+// wraps a <ul>, so its items are that list's <li> children, one child-list per item.
+function partitionSlots(node: Element): {
+  slot(name: string): ElementContent[];
+  items(name: string): ElementContent[][];
+} {
+  const named = new Map<string, ElementContent[]>();
+  const body: ElementContent[] = [];
+  for (const child of node.children as ElementContent[]) {
+    const slotName = isElement(child) ? strProp(child, 'dataSlot') : undefined;
+    if (slotName === 'title') named.set('title', stripSlotMarker(child));
+    else if (slotName) named.set(slotName, [child]);
+    else body.push(child);
+  }
+  return {
+    slot(name: string): ElementContent[] {
+      if (name === 'body') return body;
+      const wrap = named.get(name);
+      if (!wrap) return [];
+      // For title we stored the label's own children, so return them as-is. For a markdown or
+      // inline named slot the wrapper <div> holds the rendered children; unwrap it.
+      if (name === 'title') return wrap;
+      const div = wrap[0];
+      return isElement(div) ? (div.children as ElementContent[]) : wrap;
+    },
+    items(name: string): ElementContent[][] {
+      const wrap = named.get(name);
+      const div = wrap?.[0];
+      if (!div || !isElement(div)) return [];
+      const ul = (div.children as ElementContent[]).find((c) => isElement(c) && c.tagName === 'ul');
+      if (!ul || !isElement(ul)) return [];
+      return (ul.children as ElementContent[])
+        .filter((li) => isElement(li) && li.tagName === 'li')
+        .map((li) => (li as Element).children as ElementContent[]);
+    },
+  };
+}
+
 function transformNode(node: Element, registry: ComponentRegistry): Element {
   node.children = transformChildren(node.children as ElementContent[], registry);
   const name = strProp(node, 'dataPrimitive');
   const def = name ? registry.get(name) : undefined;
-  return def ? def.build(node) : node;
+  if (!def) return node;
+  const parts = partitionSlots(node);
+  const ctx: ComponentContext = {
+    attributes: readAttributes(node, def),
+    slot: parts.slot,
+    items: parts.items,
+    node,
+  };
+  return def.build(ctx);
 }
 
 /** Rehype transformer: dispatch each stamped element through its registry `build`

package/src/lib/render/remark-directives.ts

@@ -1,7 +1,22 @@
 import type { Paragraph, PhrasingContent, Root, Text } from 'mdast';
 import type { ContainerDirective, LeafDirective, TextDirective } from 'mdast-util-directive';
 import { visit } from 'unist-util-visit';
-import type { ComponentRegistry } from './registry.js';
+import { dataAttrProp, type ComponentRegistry } from './registry.js';
+
+// mdast-util-directive carries the `[label]` as a paragraph whose `data.directiveLabel` is set.
+function isDirectiveLabel(node: unknown): boolean {
+  return Boolean((node as { data?: { directiveLabel?: boolean } }).data?.directiveLabel);
+}
+
+// Stamp data-slot on a child so the rehype dispatch partitioner can route it. For a nested
+// container directive we also set hName so it renders as a <div> wrapper rather than being
+// dropped as an unknown directive.
+function markSlot(node: unknown, name: string): void {
+  const n = node as { type?: string; data?: { hName?: string; hProperties?: Record<string, string> } };
+  const data = n.data ?? (n.data = {});
+  if (n.type === 'containerDirective') data.hName = 'div';
+  data.hProperties = { ...(data.hProperties ?? {}), dataSlot: name };
+}
 
 // Reconstruct a directive's authored attribute block (`{#id .class key="value"}`).
 // Accidental prose directives carry none, so this is almost always empty.
@@ -41,6 +56,7 @@ export function remarkDirectiveStamp(registry: ComponentRegistry) {
   return (tree: Root) => {
     visit(tree, 'containerDirective', (node: ContainerDirective) => {
       if (!known.has(node.name)) return;
+      const def = registry.get(node.name);
       const attrs = node.attributes ?? {};
       const role = attrs.role || undefined;
       let icon = attrs.icon || undefined;
@@ -49,10 +65,32 @@ export function remarkDirectiveStamp(registry: ComponentRegistry) {
       const properties: Record<string, string> = { dataPrimitive: node.name };
       if (icon) properties.dataIcon = icon;
       if (role) properties.dataRole = role;
+      // Carry every declared attribute to hast so the dispatch partitioner can build the
+      // component context. data-attr-<key> survives to the element; build() consumes it and
+      // returns a fresh element, so the marker never reaches the published DOM.
+      for (const field of def?.attributes ?? []) {
+        const raw = attrs[field.key];
+        if (raw != null) properties[dataAttrProp(field.key)] = raw;
+      }
 
       const data = node.data ?? (node.data = {});
       data.hName = 'div';
       data.hProperties = properties;
+
+      // Mark the title label paragraph and the nested slot directives so they survive to hast
+      // and the partitioner can find them. A slot named in the component schema (other than the
+      // default body) is a nested container directive; the title is the directive [label].
+      const slotNames = new Set((def?.slots ?? []).map((s) => s.name));
+      for (const child of node.children) {
+        if (isDirectiveLabel(child) && slotNames.has('title')) {
+          markSlot(child, 'title');
+        } else if (
+          (child as { type?: string }).type === 'containerDirective' &&
+          slotNames.has((child as { name: string }).name)
+        ) {
+          markSlot(child, (child as { name: string }).name);
+        }
+      }
     });
 
     visit(tree, ['textDirective', 'leafDirective'], (node, index, parent) => {