@glw907/cairn-cms 0.9.0 → 0.11.0

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

@@ -28,16 +28,18 @@ export interface ContentSummary {
   draft: boolean;
 }
 
-/** The detail view: a summary plus the frontmatter and the body to render. */
-export interface ContentEntry extends ContentSummary {
-  frontmatter: Record<string, unknown>;
+/** The detail view: a summary plus the frontmatter and the body to render. The frontmatter
+ *  type defaults to `Record<string, unknown>`; the typed-reads pass infers it from the concept
+ *  fields. Generic now so that change does not break this signature. */
+export interface ContentEntry<F = Record<string, unknown>> extends ContentSummary {
+  frontmatter: F;
   body: string;
 }
 
 /** The per-concept query surface. */
-export interface ContentIndex {
+export interface ContentIndex<F = Record<string, unknown>> {
   all(opts?: { includeDrafts?: boolean }): ContentSummary[];
-  byId(id: string): ContentEntry | undefined;
+  byId(id: string): ContentEntry<F> | undefined;
   byTag(tag: string, opts?: { includeDrafts?: boolean }): ContentSummary[];
   allTags(): { tag: string; count: number }[];
   adjacent(id: string): { newer?: ContentSummary; older?: ContentSummary };
@@ -68,8 +70,11 @@ function asTags(value: unknown): string[] {
 }
 
 /** Build a concept's index from its raw files and normalized descriptor. */
-export function createContentIndex(files: RawFile[], descriptor: ConceptDescriptor): ContentIndex {
-  const entries: ContentEntry[] = files.map((file) => {
+export function createContentIndex<F = Record<string, unknown>>(
+  files: RawFile[],
+  descriptor: ConceptDescriptor,
+): ContentIndex<F> {
+  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);
@@ -85,7 +90,7 @@ export function createContentIndex(files: RawFile[], descriptor: ConceptDescript
       excerpt: deriveExcerpt(body, { description: asString(frontmatter.description) }),
       wordCount: wordCount(body),
       draft: frontmatter.draft === true,
-      frontmatter,
+      frontmatter: frontmatter as F,
       body,
     };
   });
@@ -95,11 +100,11 @@ export function createContentIndex(files: RawFile[], descriptor: ConceptDescript
     descriptor.routing.dated ? (b.date ?? '').localeCompare(a.date ?? '') : a.title.localeCompare(b.title),
   );
 
-  const summarize = (entry: ContentEntry): ContentSummary => {
+  const summarize = (entry: ContentEntry<F>): ContentSummary => {
     const { frontmatter: _frontmatter, body: _body, ...summary } = entry;
     return summary;
   };
-  const visible = (list: ContentEntry[], includeDrafts?: boolean): ContentEntry[] =>
+  const visible = (list: ContentEntry<F>[], includeDrafts?: boolean): ContentEntry<F>[] =>
     includeDrafts ? list : list.filter((entry) => !entry.draft);
 
   return {

package/src/lib/delivery/index.ts

@@ -0,0 +1,32 @@
+// cairn-cms: the public delivery entry (@glw907/cairn-cms/delivery). The complete, canonical,
+// backend-free toolkit a SvelteKit site wires its public pages with: the content index and the
+// site resolver, the descriptor helper, the syndication and SEO builders, the endpoint response
+// 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 { createSiteIndex } from './site-index.js';
+export type { SiteIndex, ConceptIndex } from './site-index.js';
+export { siteDescriptors } from './site-descriptors.js';
+export { deriveExcerpt, wordCount } from './excerpt.js';
+export { buildRssFeed, buildJsonFeed } from './feeds.js';
+export type { FeedChannel, FeedItem } from './feeds.js';
+export { buildSitemap } from './sitemap.js';
+export type { SitemapUrl } from './sitemap.js';
+export { buildRobots } from './robots.js';
+export { buildSeoMeta } from './seo.js';
+export type { SeoInput, SeoMeta } from './seo.js';
+export { paginate } from './paginate.js';
+export type { Page } from './paginate.js';
+export { rssResponse, jsonFeedResponse, sitemapResponse, robotsResponse } from './responses.js';
+export { jsonLdScript } from './json-ld.js';
+export { permalink } from '../content/permalink.js';
+export { createPublicRoutes } from '../sveltekit/public-routes.js';
+export type {
+  PublicRoutesDeps,
+  ListData,
+  TagData,
+  TagIndexData,
+  EntryData,
+} from '../sveltekit/public-routes.js';
+export { default as CairnHead } from './CairnHead.svelte';

package/src/lib/delivery/json-ld.ts

@@ -0,0 +1,16 @@
+// cairn-cms: serialize a JSON-LD object into a safe inline script string. JSON.stringify does
+// not escape <, >, or &, so a value containing "</script>" would close the element and inject
+// markup. Escaping the three characters to their JSON unicode forms keeps the structured data
+// identical for a parser while making the bytes unable to break out of the script element.
+// The line separator U+2028 and paragraph separator U+2029 get the same treatment: they are
+// legal inside a JSON string but unsafe in inline script text, where some parsers read them as
+// line terminators, so an author pasting one into frontmatter would corrupt the JSON-LD block.
+export function jsonLdScript(data: Record<string, unknown>): string {
+  const json = JSON.stringify(data)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+  return `<script type="application/ld+json">${json}</script>`;
+}

package/src/lib/delivery/responses.ts

@@ -0,0 +1,34 @@
+// cairn-cms: response helpers for the public delivery endpoints. Each wraps a builder in a
+// Response with the correct Content-Type, so a site's +server.ts GET is a single call. The
+// content type is the one detail every site otherwise copies and occasionally gets wrong.
+import { buildRssFeed, buildJsonFeed, type FeedChannel, type FeedItem } from './feeds.js';
+import { buildSitemap, type SitemapUrl } from './sitemap.js';
+import { buildRobots } from './robots.js';
+
+/** An RSS 2.0 feed response. */
+export function rssResponse(channel: FeedChannel, items: FeedItem[]): Response {
+  return new Response(buildRssFeed(channel, items), {
+    headers: { 'Content-Type': 'application/rss+xml; charset=utf-8' },
+  });
+}
+
+/** A JSON Feed 1.1 response. */
+export function jsonFeedResponse(channel: FeedChannel, items: FeedItem[]): Response {
+  return new Response(buildJsonFeed(channel, items), {
+    headers: { 'Content-Type': 'application/feed+json; charset=utf-8' },
+  });
+}
+
+/** A sitemap response. */
+export function sitemapResponse(urls: SitemapUrl[]): Response {
+  return new Response(buildSitemap(urls), {
+    headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+  });
+}
+
+/** A robots.txt response. */
+export function robotsResponse(opts: { sitemapUrl: string; disallow?: string[] }): Response {
+  return new Response(buildRobots(opts), {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+}

package/src/lib/delivery/seo.ts

@@ -13,6 +13,10 @@ export interface SeoInput {
   modified?: string;
   feeds?: { rss?: string; json?: string };
   image?: string;
+  /** A robots meta directive, e.g. "noindex, nofollow". Omitted from the head when absent. */
+  robots?: string;
+  /** Author name, emitted as article:author for the article type. */
+  author?: string;
 }
 
 /** Plain-data head: a title, meta tags, link tags, and one JSON-LD object. */
@@ -40,6 +44,15 @@ export function buildSeoMeta(input: SeoInput): SeoMeta {
     meta.push({ name: 'twitter:image', content: input.image });
   }
 
+  if (input.robots) {
+    meta.push({ name: 'robots', content: input.robots });
+  }
+  if (type === 'article') {
+    if (input.published) meta.push({ property: 'article:published_time', content: input.published });
+    if (input.modified) meta.push({ property: 'article:modified_time', content: input.modified });
+    if (input.author) meta.push({ property: 'article:author', content: input.author });
+  }
+
   const links: SeoMeta['links'] = [{ rel: 'canonical', href: input.canonicalUrl }];
   if (input.feeds?.rss) {
     links.push({ rel: 'alternate', type: 'application/rss+xml', href: input.feeds.rss, title: input.siteName });

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

@@ -0,0 +1,12 @@
+// cairn-cms: the one-call descriptor helper. A delivery site needs the same per-concept
+// descriptors the admin runtime uses; this wraps the two calls that derive them so the
+// pairing is not tribal knowledge. The YAML URL policy stays the single source of truth.
+import { normalizeConcepts } from '../content/concepts.js';
+import { urlPolicyFrom } from '../nav/site-config.js';
+import type { CairnAdapter, ConceptDescriptor } from '../content/types.js';
+import type { SiteConfig } from '../nav/site-config.js';
+
+/** Per-concept descriptors for a site, from its adapter content and its parsed site config. */
+export function siteDescriptors(adapter: CairnAdapter, siteConfig: SiteConfig): ConceptDescriptor[] {
+  return normalizeConcepts(adapter.content, urlPolicyFrom(siteConfig));
+}

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

@@ -30,8 +30,33 @@ function normalizePath(path: string): string {
   return path.length > 1 ? path.replace(/\/+$/, '') : path;
 }
 
-/** Union per-concept indexes into a site-level resolver; throw on a duplicate permalink. */
-export function createSiteIndex(concepts: ConceptIndex[]): SiteIndex {
+/** Validate every entry (drafts included) against its concept, aggregating failures. */
+function validateAll(concepts: ConceptIndex[]): void {
+  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}`);
+        }
+      }
+    }
+  }
+  if (problems.length > 0) {
+    throw new Error(`site index: ${problems.length} invalid frontmatter field(s):\n  ${problems.join('\n  ')}`);
+  }
+}
+
+/**
+ * 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.
+ */
+export function createSiteIndex(concepts: ConceptIndex[], opts: { validate?: boolean } = {}): SiteIndex {
+  if (opts.validate !== false) validateAll(concepts);
   const byPath = new Map<string, { index: ContentIndex; id: string }>();
   const byId = new Map<string, ContentIndex>();
   for (const { descriptor, index } of concepts) {

package/src/lib/index.ts

@@ -48,8 +48,22 @@ export {
 } from './content/ids.js';
 export type { DatePrefix } from './content/ids.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
-export { defineRegistry } from './render/registry.js';
-export type { ComponentDef, ComponentRegistry } from './render/registry.js';
+export { defineRegistry, emptyValues } from './render/registry.js';
+export type {
+  ComponentDef,
+  ComponentRegistry,
+  FieldType,
+  AttributeField,
+  SlotKind,
+  SlotDef,
+  ComponentValues,
+} from './render/registry.js';
+export { serializeComponent, parseComponent } from './render/component-grammar.js';
+export { validateComponent } from './render/component-validate.js';
+export type { ComponentValidation } from './render/component-validate.js';
+export { buildComponentInsert, type ComponentInsert } from './render/component-insert.js';
+export { generateComponentReference } from './render/component-reference.js';
+export type { ReferenceOptions } from './render/component-reference.js';
 export { glyph } from './render/glyph.js';
 export type { IconSet } from './render/glyph.js';
 export { remarkDirectiveStamp } from './render/remark-directives.js';

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

@@ -0,0 +1,167 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkDirective from 'remark-directive';
+import remarkStringify from 'remark-stringify';
+import type { Root, RootContent } from 'mdast';
+import type { ComponentDef, ComponentValues, SlotDef } from './registry.js';
+
+const COLON = ':';
+
+function attrBlock(def: ComponentDef, values: ComponentValues): string {
+  const parts: string[] = [];
+  for (const field of def.attributes ?? []) {
+    const v = values.attributes[field.key];
+    if (field.type === 'boolean') {
+      if (v === true) parts.push(`${field.key}="true"`);
+    } else if (typeof v === 'string' && v !== '') {
+      // The directive attribute grammar (mdast-util-directive) treats a literal `"` as the value
+      // terminator and decodes HTML entities, so a backslash escape does not survive a round-trip.
+      // Encode `&` first (so existing entities are not double-decoded) then `"`; the parser decodes
+      // both back. A backslash is literal in this grammar and needs no escaping.
+      const escaped = v.replace(/&/g, '&').replace(/"/g, '"');
+      parts.push(`${field.key}="${escaped}"`);
+    }
+  }
+  return parts.length ? `{${parts.join(' ')}}` : '';
+}
+
+function slotByName(def: ComponentDef, name: string): SlotDef | undefined {
+  return (def.slots ?? []).find((s) => s.name === name);
+}
+
+function nestedSlots(def: ComponentDef): SlotDef[] {
+  return (def.slots ?? []).filter((s) => s.name !== 'title' && s.name !== 'body');
+}
+
+export function serializeComponent(def: ComponentDef, values: ComponentValues): string {
+  const fence = COLON.repeat(nestedSlots(def).length > 0 ? 4 : 3);
+
+  const title = slotByName(def, 'title') ? (values.slots.title as string) ?? '' : '';
+  // Escape brackets in the label so a `[` or `]` in the title does not break the directive label
+  // grammar; remark un-escapes them back to literal text on parse, so readLabel recovers them.
+  const label = title ? `[${title.replace(/\[/g, '\\[').replace(/\]/g, '\\]')}]` : '';
+
+  const open = `${fence}${def.name}${label}${attrBlock(def, values)}`;
+
+  const lines: string[] = [open];
+  const body = slotByName(def, 'body') ? (values.slots.body as string) ?? '' : '';
+  if (body) lines.push(body);
+
+  for (const slot of nestedSlots(def)) {
+    const raw = values.slots[slot.name];
+    const content =
+      slot.kind === 'repeatable'
+        ? (Array.isArray(raw) ? raw : []).filter((i) => i !== '').map((i) => `- ${i}`).join('\n')
+        : ((raw as string | undefined) ?? '');
+    if (!content) continue;
+    if (lines.length > 1) lines.push(''); // blank line before this block
+    lines.push(`${COLON.repeat(3)}${slot.name}`, content, COLON.repeat(3));
+  }
+
+  lines.push(fence);
+  return lines.join('\n');
+}
+
+// A minimal structural view of a mdast containerDirective node (mdast-util-directive shape).
+interface DirectiveNode {
+  type: 'containerDirective' | 'leafDirective' | 'textDirective';
+  name: string;
+  attributes?: Record<string, string | null> | null;
+  children: RootContent[];
+}
+
+function isContainer(node: RootContent): node is RootContent & DirectiveNode {
+  return (node as DirectiveNode).type === 'containerDirective';
+}
+
+// Pin the bullet to `-` so a markdown body or slot that uses dash bullets round-trips unchanged
+// rather than drifting to remark-stringify's default `*`, which would silently mutate author content.
+const toMd = unified().use(remarkStringify, { bullet: '-' });
+
+/** Render mdast children back to trimmed markdown text. */
+function childrenToText(children: RootContent[]): string {
+  const root: Root = { type: 'root', children };
+  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> {
+  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,
+  );
+  const values = emptyComponentValues(def);
+  if (!root) return values;
+
+  for (const field of def.attributes ?? []) {
+    const raw = root.attributes?.[field.key];
+    if (field.type === 'boolean') values.attributes[field.key] = raw === 'true';
+    else if (typeof raw === 'string') values.attributes[field.key] = raw;
+  }
+
+  const titleSlot = slotByName(def, 'title');
+  const bodySlot = slotByName(def, 'body');
+  const nested = nestedSlots(def);
+  const nestedNames = new Set(nested.map((s) => s.name));
+
+  const directChildren = root.children.filter(
+    (c) => !(isContainer(c) && nestedNames.has((c as DirectiveNode).name)) && !isDirectiveLabel(c),
+  );
+  const nestedChildren = root.children.filter(
+    (c): c is RootContent & DirectiveNode => isContainer(c) && nestedNames.has((c as DirectiveNode).name),
+  );
+
+  if (titleSlot) values.slots.title = readLabel(root) ?? '';
+  if (bodySlot) values.slots.body = childrenToText(directChildren);
+
+  for (const slot of nested) {
+    const node = nestedChildren.find((c) => c.name === slot.name);
+    if (!node) continue;
+    if (slot.kind === 'repeatable') values.slots[slot.name] = readListItems(node.children);
+    else values.slots[slot.name] = childrenToText(node.children);
+  }
+
+  return values;
+}
+
+/** 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 ?? {});
+}
+
+// A bare parse base: empty strings, false, and empty lists, with no attribute defaults applied. The
+// `emptyValues` helper in registry.ts seeds form defaults instead, so it is deliberately not reused
+// here; the parse must overwrite only the fields actually present in the markdown.
+function emptyComponentValues(def: ComponentDef): ComponentValues {
+  const attributes: Record<string, string | boolean> = {};
+  for (const f of def.attributes ?? []) attributes[f.key] = f.type === 'boolean' ? false : '';
+  const slots: Record<string, string | string[]> = {};
+  for (const s of def.slots ?? []) slots[s.name] = s.kind === 'repeatable' ? [] : '';
+  return { attributes, slots };
+}
+
+// mdast-util-directive carries the `[label]` as a paragraph whose `data.directiveLabel` is set.
+function isDirectiveLabel(node: RootContent): boolean {
+  return Boolean((node as { data?: { directiveLabel?: boolean } }).data?.directiveLabel);
+}
+
+function readLabel(root: DirectiveNode): string | undefined {
+  for (const child of root.children) {
+    const p = child as { type: string; data?: { directiveLabel?: boolean }; children?: { value?: string }[] };
+    if (p.type === 'paragraph' && p.data?.directiveLabel) return (p.children ?? []).map((c) => c.value ?? '').join('');
+  }
+  return undefined;
+}
+
+function readListItems(children: RootContent[]): string[] {
+  const list = children.find((c) => (c as { type: string }).type === 'list') as { children?: RootContent[] } | undefined;
+  if (!list?.children) return [];
+  return list.children.map((li) => childrenToText((li as { children?: RootContent[] }).children ?? []));
+}

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

@@ -0,0 +1,15 @@
+import { serializeComponent } from './component-grammar.js';
+import { validateComponent } from './component-validate.js';
+import type { ComponentDef, ComponentValues } from './registry.js';
+
+/** The outcome of preparing a guided-form component for insertion: the markdown to insert, or the
+ *  field-keyed errors to show on the form. */
+export type ComponentInsert = { ok: true; markdown: string } | { ok: false; errors: Record<string, string> };
+
+/** Serialize a component's form values, then validate the result against its schema. Returns the
+ *  markdown to insert at the cursor, or the field errors keyed by attribute key or slot name. */
+export async function buildComponentInsert(def: ComponentDef, values: ComponentValues): Promise<ComponentInsert> {
+  const markdown = serializeComponent(def, values);
+  const verdict = await validateComponent(markdown, def);
+  return verdict.ok ? { ok: true, markdown } : { ok: false, errors: verdict.errors };
+}

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

@@ -0,0 +1,38 @@
+import { serializeComponent } from './component-grammar.js';
+import { emptyValues, type ComponentDef, type ComponentRegistry, type ComponentValues } from './registry.js';
+
+export interface ReferenceOptions {
+  /** The H1 title of the reference document. */
+  title: string;
+  /** The one-line blockquote summary under the title. */
+  summary: string;
+}
+
+/** Build a self-contained markdown reference (the llms-full.txt shape) for a component registry, for
+ *  authors and for pointing an LLM at one curated file. */
+export function generateComponentReference(registry: ComponentRegistry, opts: ReferenceOptions): string {
+  const sections = registry.defs.map((def) => componentSection(def));
+  return `# ${opts.title}\n\n> ${opts.summary}\n\n${sections.join('\n\n')}\n`;
+}
+
+function componentSection(def: ComponentDef): string {
+  const lines = [`## ${def.label} (\`:::${def.name}\`)`, '', def.description ?? ''];
+  if (def.use) lines.push('', `**When to use:** ${def.use}`);
+  lines.push('', '```', serializeComponent(def, exampleValues(def)), '```');
+  return lines.join('\n');
+}
+
+/** Seed example values that show every declared field: an ellipsis for strings, one sample list item. */
+function exampleValues(def: ComponentDef): ComponentValues {
+  const values = emptyValues(def);
+  for (const field of def.attributes ?? []) {
+    if (field.type === 'boolean') values.attributes[field.key] = false;
+    else values.attributes[field.key] = field.options?.[0] ?? '…';
+  }
+  for (const slot of def.slots ?? []) {
+    if (slot.kind === 'repeatable') values.slots[slot.name] = ['…'];
+    else if (slot.name === 'title') values.slots[slot.name] = 'Title';
+    else values.slots[slot.name] = '…';
+  }
+  return values;
+}

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

@@ -0,0 +1,36 @@
+import { parseComponent, parseRawAttributeKeys } 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 errors: Record<string, string> = {};
+  const declared = new Set((def.attributes ?? []).map((f) => f.key));
+
+  for (const field of def.attributes ?? []) {
+    const v = values.attributes[field.key];
+    const filled = field.type === 'boolean' ? true : typeof v === 'string' && v !== '';
+    if (field.required && !filled) {
+      errors[field.key] = `${field.label} is required.`;
+      continue;
+    }
+    if (field.type === 'select' && typeof v === 'string' && v !== '' && !(field.options ?? []).includes(v)) {
+      errors[field.key] = `${field.label} must be one of: ${(field.options ?? []).join(', ')}.`;
+    }
+  }
+
+  for (const key of parseRawAttributeKeys(markdown, def)) {
+    if (!declared.has(key)) errors[key] = `Unknown attribute "${key}".`;
+  }
+
+  for (const slot of def.slots ?? []) {
+    if (!slot.required) continue;
+    const v = values.slots[slot.name];
+    const filled = Array.isArray(v) ? v.length > 0 : typeof v === 'string' && v !== '';
+    if (!filled) errors[slot.name] = `${slot.label} is required.`;
+  }
+
+  return Object.keys(errors).length ? { ok: false, errors } : { ok: true };
+}

package/src/lib/render/registry.ts

@@ -5,6 +5,39 @@
 // `ComponentRegistry` from here.
 import type { Element } from 'hast';
 
+/** The input types a component attribute or repeatable item field can take. */
+export type FieldType = 'text' | 'select' | 'icon' | 'boolean';
+
+/** One `{key="value"}` attribute on a component directive, or one field of a repeatable item. */
+export interface AttributeField {
+  /** The attribute name as it appears in the directive, e.g. `icon`. */
+  key: string;
+  /** The form label. */
+  label: string;
+  type: FieldType;
+  required?: boolean;
+  /** Initial value; a string for text/select/icon, a boolean for boolean. */
+  default?: string | boolean;
+  /** Allowed values for `type: 'select'`. */
+  options?: string[];
+  /** Helper text shown under the field. */
+  help?: string;
+}
+
+export type SlotKind = 'markdown' | 'inline' | 'repeatable';
+
+/** One named content region of a component. The slots named `title` and `body` are special: `title`
+ *  serializes to the directive `[label]` and `body` to the unmarked content (see the canonical grammar). */
+export interface SlotDef {
+  name: string;
+  label: string;
+  kind: SlotKind;
+  required?: boolean;
+  help?: string;
+  /** For `kind: 'repeatable'`: the fields composing each list item (v1 uses the first field). */
+  itemFields?: AttributeField[];
+}
+
 /** A site component: how it inserts (editor) and how it renders (rehype). */
 export interface ComponentDef {
   /** Directive name, e.g. 'card' (matches `:::card`). */
@@ -14,13 +47,19 @@ export interface ComponentDef {
   /** Palette description. */
   description: string;
   /** Markdown scaffold inserted at the cursor by the editor palette. */
-  insertTemplate: string;
+  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;
   /** 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. */
+  use?: string;
+  /** The `{key="value"}` attributes this component accepts. */
+  attributes?: AttributeField[];
+  /** The named content regions this component accepts. */
+  slots?: SlotDef[];
 }
 
 export interface ComponentRegistry {
@@ -43,3 +82,24 @@ export function defineRegistry({ components }: { components: ComponentDef[] }):
     defaultIcon: (name, role) => (role ? byName.get(name)?.defaultIconByRole?.[role] : undefined),
   };
 }
+
+/** Guided-form values for one component: attribute values keyed by attribute key, slot values keyed
+ *  by slot name (a string, or a string list for a repeatable slot). */
+export interface ComponentValues {
+  attributes: Record<string, string | boolean>;
+  slots: Record<string, string | string[]>;
+}
+
+/** Seed an empty {@link ComponentValues} from a component's schema: attribute defaults (or '' / false)
+ *  and empty slot values ([] for repeatable, '' otherwise). */
+export function emptyValues(def: ComponentDef): ComponentValues {
+  const attributes: Record<string, string | boolean> = {};
+  for (const field of def.attributes ?? []) {
+    attributes[field.key] = field.default ?? (field.type === 'boolean' ? false : '');
+  }
+  const slots: Record<string, string | string[]> = {};
+  for (const slot of def.slots ?? []) {
+    slots[slot.name] = slot.kind === 'repeatable' ? [] : '';
+  }
+  return { attributes, slots };
+}

package/src/lib/sveltekit/public-routes.ts

@@ -6,12 +6,20 @@
 import { error } from '@sveltejs/kit';
 import type { ContentSummary, ContentEntry } from '../delivery/content-index.js';
 import type { SiteIndex } from '../delivery/site-index.js';
+import { buildSeoMeta } from '../delivery/seo.js';
+import type { SeoMeta } from '../delivery/seo.js';
 
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
   site: SiteIndex;
   render: (md: string, opts?: { stagger?: boolean }) => string | Promise<string>;
   origin: string;
+  /** Site name for og:site_name and the SEO head. */
+  siteName: string;
+  /** Default description used when an entry has none. */
+  description: string;
+  /** Absolute feed URLs for the head's autodiscovery links. */
+  feeds?: { rss?: string; json?: string };
 }
 
 /** The archive and tag list data: summaries the template renders. */
@@ -34,13 +42,14 @@ export interface EntryData {
   entry: ContentEntry;
   html: string;
   canonicalUrl: string;
+  seo: SeoMeta;
   newer?: ContentSummary;
   older?: ContentSummary;
 }
 
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps: PublicRoutesDeps) {
-  const { site, render, origin } = deps;
+  const { site, render, origin, siteName, description, feeds } = deps;
 
   /** Resolve one concept's index by id, or a 404 (the route names an unconfigured concept). */
   function indexOf(conceptId: string) {
@@ -54,7 +63,19 @@ export function createPublicRoutes(deps: PublicRoutesDeps) {
     const entry = site.byPermalink(event.url.pathname);
     if (!entry) throw error(404, `Not found: ${event.url.pathname}`);
     const { newer, older } = site.adjacent(entry);
-    return { entry, html: await render(entry.body, { stagger: true }), canonicalUrl: origin + entry.permalink, newer, older };
+    const canonicalUrl = origin + entry.permalink;
+    // A dated entry is an article; an undated one (a page) is a website.
+    const seo = buildSeoMeta({
+      title: entry.title,
+      description: (entry.frontmatter.description as string) || entry.excerpt || description,
+      canonicalUrl,
+      siteName,
+      type: entry.date ? 'article' : 'website',
+      ...(entry.date ? { published: entry.date } : {}),
+      ...(entry.updated ? { modified: entry.updated } : {}),
+      feeds,
+    });
+    return { entry, html: await render(entry.body, { stagger: true }), canonicalUrl, seo, newer, older };
   }
 
   /** The chronological archive for one concept: every non-draft summary, newest-first. */