@glw907/cairn-cms 0.21.0 → 0.26.0

package/src/lib/render/pipeline.ts

@@ -13,7 +13,7 @@ import { buildSanitizeSchema, rehypeAnchorRel } from './sanitize-schema.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
 import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
 import { rehypeDispatch } from './rehype-dispatch.js';
-import type { ComponentRegistry } from './registry.js';
+import { defineRegistry, type ComponentRegistry } from './registry.js';
 import type { LinkResolve } from '../content/links.js';
 
 export interface RendererOptions {
@@ -30,12 +30,19 @@ export interface RendererOptions {
    *  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;
+  /** The `rel` value forced on every `target="_blank"` anchor, applied last so it also covers
+   *  component-built anchors. Defaults to `'noopener noreferrer'`. Set a different string to change
+   *  it, or `false` to disable the injection (a site that owns its own anchor hardening). */
+  anchorRel?: string | false;
 }
 
 /** Compose a site's render pipeline from its component registry: directive syntax to
  *  stamped markers to registry-built hast. Returns `renderMarkdown` plus the remark/
  *  rehype plugin arrays (so the admin editor preview can reuse the exact same set). */
-export function createRenderer(registry: ComponentRegistry, options: RendererOptions = {}) {
+export function createRenderer(
+  registry: ComponentRegistry = defineRegistry({ components: [] }),
+  options: RendererOptions = {},
+) {
   const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry], remarkResolveCairnLinks];
   // 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
@@ -43,13 +50,14 @@ export function createRenderer(registry: ComponentRegistry, options: RendererOpt
   const floor: PluggableList = options.unsafeDisableSanitize
     ? []
     : [[rehypeSanitize, buildSanitizeSchema(registry, options.sanitizeSchema)]];
+  const rel = options.anchorRel ?? 'noopener noreferrer';
   const rehypePlugins: PluggableList = [
     rehypeRaw,
     ...floor,
     [rehypeDispatch, registry, options.stagger],
     rehypeSlug,
-    rehypeAnchorRel,
   ];
+  if (rel !== false) rehypePlugins.push([rehypeAnchorRel, rel]);
   const processor = unified()
     .use(remarkParse)
     .use(remarkGfm)

package/src/lib/render/registry.ts

@@ -19,7 +19,7 @@ export interface AttributeField {
   /** Initial value; a string for text/select/icon, a boolean for boolean. */
   default?: string | boolean;
   /** Allowed values for `type: 'select'`. */
-  options?: string[];
+  options?: readonly string[];
   /** Helper text shown under the field. */
   help?: string;
 }

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

@@ -7,7 +7,7 @@ export function isElement(node: ElementContent | undefined): node is Element {
 }
 
 // hast Properties values are PropertyValue (string | number | boolean | array | null).
-// Directive markers (dataIcon/dataRole/dataPrimitive) are always stamped as strings;
+// Directive markers (dataPrimitive/dataRole/dataAttr<Key>) are always stamped as strings;
 // this reads them back with that guarantee instead of casting at each call site.
 export function strProp(node: Element, name: string): string | undefined {
   const value = node.properties?.[name];
@@ -28,6 +28,17 @@ export function cardShell(classes: string[], body: ElementContent[]): Element {
   return h('section', { className: classes }, [h('div', { className: ['card-body'] }, body)]);
 }
 
+/** Card head row: `<div class="ec-head">[icon]<h2 class="card-title">{title}</h2></div>`.
+ *  Pass the title's inline children and an optional pre-built icon element, the way `cardShell`
+ *  takes already-built body content. This factors the icon-plus-heading head that a titled
+ *  component build would otherwise rebuild by hand (the shape the removed `splitHead` produced). */
+export function headRow(title: ElementContent[], icon?: Element): Element {
+  const children: ElementContent[] = [];
+  if (icon) children.push(icon);
+  children.push(h('h2', { className: ['card-title'] }, title));
+  return h('div', { className: ['ec-head'] }, children);
+}
+
 /** Tag the first <ul> among children with `ec-grid` and strip its whitespace-only
  *  text nodes so the bare list serializes without newlines. Returns that <ul>. */
 export function markFirstList(children: ElementContent[]): Element | undefined {

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

@@ -59,17 +59,22 @@ export function remarkDirectiveStamp(registry: ComponentRegistry) {
       const def = registry.get(node.name);
       const attrs = node.attributes ?? {};
       const role = attrs.role || undefined;
-      let icon = attrs.icon || undefined;
+      const iconField = def?.attributes?.find((field) => field.type === 'icon');
+      const iconKey = iconField?.key ?? 'icon';
+      let icon = attrs[iconKey] || undefined;
       if (!icon && role) icon = registry.defaultIcon(node.name, role);
 
       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.
+      // component context. The icon attribute uses the already-resolved `icon` (the author value
+      // coerced through the same empty-is-absent rule above, or the defaultIconByRole default), so
+      // a role default reaches the build through the one declared path and a blank `icon=` falls
+      // back to that default the same way a missing one does. 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];
+        const raw = field === iconField ? icon : attrs[field.key];
         if (raw != null) properties[dataAttrProp(field.key)] = raw;
       }
 
@@ -91,6 +96,12 @@ export function remarkDirectiveStamp(registry: ComponentRegistry) {
           markSlot(child, (child as { name: string }).name);
         }
       }
+
+      // A directive [label] that the component has no `title` slot to claim would otherwise fall
+      // through as body content and render as a stray paragraph. Drop it.
+      if (!slotNames.has('title')) {
+        node.children = node.children.filter((child) => !isDirectiveLabel(child)) as typeof node.children;
+      }
     });
 
     visit(tree, ['textDirective', 'leafDirective'], (node, index, parent) => {

package/src/lib/render/sanitize-schema.ts

@@ -5,7 +5,7 @@ import { dataAttrProp, type ComponentRegistry } from './registry.js';
 
 // The fixed directive markers the stamp writes and the dispatch reads. They are inert data
 // attributes, never a script vector, and must survive the floor so the dispatch still runs.
-const FIXED_MARKERS = ['dataPrimitive', 'dataSlot', 'dataIcon', 'dataRole', 'dataRise'];
+const FIXED_MARKERS = ['dataPrimitive', 'dataSlot', 'dataRole', 'dataRise'];
 
 /**
  * Build the delivery sanitize schema. Starts from hast-util-sanitize's defaultSchema, the
@@ -51,15 +51,16 @@ export function buildSanitizeSchema(
 }
 
 /**
- * Force rel="noopener noreferrer" on every target="_blank" anchor, to prevent reverse-tabnabbing.
+ * Force a `rel` value on every target="_blank" anchor, to prevent reverse-tabnabbing.
  * hast-util-sanitize runs no per-node hook, so this small transform carries the behavior the old
- * DOMPurify preview pass enforced, now on the delivered output as well.
+ * DOMPurify preview pass enforced, now on the delivered output as well. The value is the renderer's
+ * `anchorRel` option (default `noopener noreferrer`); a site can override it or disable it entirely.
  */
-export function rehypeAnchorRel() {
+export function rehypeAnchorRel(rel: string) {
   return (tree: Root) => {
     visit(tree, 'element', (node: Element) => {
       if (node.tagName === 'a' && node.properties?.target === '_blank') {
-        node.properties.rel = 'noopener noreferrer';
+        node.properties.rel = rel;
       }
     });
   };

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

@@ -45,6 +45,7 @@ export interface TagIndexData {
 
 /** One entry's data: the detail entry, its rendered html, and its canonical URL. */
 export interface EntryData {
+  concept: string;
   entry: ContentEntry;
   html: string;
   canonicalUrl: string;
@@ -87,7 +88,7 @@ export function createPublicRoutes(deps: PublicRoutesDeps) {
       ...(fields.author ? { author: fields.author } : {}),
       ...(entry.date ? { feeds } : {}),
     });
-    return { entry, html: await render(entry.body, { stagger: true, resolve: buildLinkResolver(site) }), canonicalUrl, seo, newer, older };
+    return { concept: entry.concept, entry, html: await render(entry.body, { stagger: true, resolve: buildLinkResolver(site) }), canonicalUrl, seo, newer, older };
   }
 
   /** The chronological archive for one concept: every non-draft summary, newest-first. */

package/src/lib/vite/bin.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// cairn-manifest: the regenerate command. It evaluates the cairnManifest virtual module in write mode
+// through the consumer's own Vite resolution and writes the canonical content manifest. A thin shell
+// over writeManifest so the write logic stays testable apart from the CLI.
+import { writeManifest } from './index.js';
+
+writeManifest(process.cwd()).catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/lib/vite/index.ts

@@ -0,0 +1,213 @@
+// cairn-cms: the cairnManifest Vite plugin (@glw907/cairn-cms/vite). It owns a virtual module that
+// runs import.meta.glob over the content dirs inside the app's own Vite graph, builds the manifest
+// with the engine builder, and verifies it against the committed file. The verify runs in the
+// plugin's buildStart hook through a nested Vite SSR module load, so a drift throws there and fails
+// the build as a hard build error, outside the prerender request lifecycle (where handleHttpError
+// could downgrade it). The same virtual module in write mode produces the serialized manifest, which
+// the cairn-manifest bin uses to regenerate. See the design spec, locked decision 1.
+import type { Plugin, PluginOption } from 'vite';
+import { writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+/** The key the cairnManifest plugin stashes its options under, so the write path can read them off the
+ *  plugin instance in the consumer's loaded config without re-parsing the config file. */
+const CAIRN_OPTIONS = Symbol.for('cairn-cms.manifest-options');
+
+/** A cairnManifest plugin instance with its options stashed for the write path to read. */
+type CairnManifestPlugin = Plugin & { [CAIRN_OPTIONS]?: CairnManifestOptions };
+
+/** Options for {@link cairnManifest}. Paths are app-root-absolute (the form `import.meta.glob` wants),
+ *  so they match the build's own resolution. */
+export interface CairnManifestOptions {
+  /** The module exporting the `cairn` adapter and the parsed `siteConfig`, app-root-absolute. */
+  configModule: string;
+  /** Per-concept content globs, keyed by concept id, app-root-absolute. */
+  content: Record<string, string>;
+  /** The committed manifest path, app-root-absolute. Defaults to `/src/content/.cairn/index.json`. */
+  manifestPath?: string;
+}
+
+const VIRTUAL_ID = 'virtual:cairn-manifest';
+const RESOLVED_ID = '\0' + VIRTUAL_ID;
+
+/** The default committed manifest path, app-root-absolute. */
+const DEFAULT_MANIFEST_PATH = '/src/content/.cairn/index.json';
+
+/** Build the virtual module source. In verify mode it throws on drift; in write mode it exports the
+ *  serialized manifest as `result`. The module runs in the app graph, so its `import.meta.glob`,
+ *  package, and `?raw` resolution is the build's own. */
+function virtualSource(opts: CairnManifestOptions, mode: 'verify' | 'write'): string {
+  const manifestPath = opts.manifestPath ?? DEFAULT_MANIFEST_PATH;
+  const globEntries = Object.entries(opts.content)
+    .map(
+      ([id, pattern]) =>
+        `  ${JSON.stringify(id)}: import.meta.glob(${JSON.stringify(pattern)}, { query: '?raw', import: 'default', eager: true }),`,
+    )
+    .join('\n');
+  // In write mode the committed file may not exist yet, so do not import it.
+  const committedImport = mode === 'verify' ? `import committed from ${JSON.stringify(manifestPath + '?raw')};` : '';
+  const resultExpr =
+    mode === 'write' ? 'serializeManifest(built)' : '(verifyManifest(built, committed), "ok")';
+  return `
+import { buildSiteManifest } from '@glw907/cairn-cms/delivery/data';
+import { serializeManifest, verifyManifest } from '@glw907/cairn-cms';
+import { cairn, siteConfig } from ${JSON.stringify(opts.configModule)};
+${committedImport}
+const globs = {
+${globEntries}
+};
+const built = buildSiteManifest(cairn, siteConfig, globs);
+export const result = ${resultExpr};
+`;
+}
+
+/** Evaluate the virtual module in the given mode inside the consumer's own Vite resolution, then
+ *  return the module's `result`. It reuses the consumer's loaded config (so `$lib`, the config
+ *  module, `import.meta.glob`, and `?raw` resolve exactly as the build does) and strips the
+ *  cairnManifest plugin from the nested server's plugin list, so its buildStart never recurses.
+ *  This runs at build time and in the bin, never in the request lifecycle. */
+async function evalVirtual(
+  opts: CairnManifestOptions,
+  mode: 'verify' | 'write',
+  root: string,
+): Promise<string> {
+  const { createServer, loadConfigFromFile } = await import('vite');
+  // Load the consumer's real Vite config so the nested server inherits SvelteKit's resolution
+  // (the $lib alias, the app root, the ?raw and import.meta.glob handling). Drop cairnManifest from
+  // it so the nested server's buildStart does not recurse, and add a plugin that serves only the
+  // virtual module in the requested mode.
+  const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, undefined, root);
+  const inlineConfig = loaded?.config ?? {};
+  const server = await createServer({
+    ...inlineConfig,
+    root,
+    configFile: false,
+    logLevel: 'silent',
+    server: { middlewareMode: true, hmr: false, watch: null },
+    plugins: [...stripCairnManifest(inlineConfig.plugins ?? []), cairnVirtualOnly(opts, mode)],
+  });
+  try {
+    const mod = (await server.ssrLoadModule(VIRTUAL_ID)) as { result: string };
+    return mod.result;
+  } finally {
+    await server.close();
+  }
+}
+
+/** True for any plugin object whose name is the cairnManifest plugin, so the nested server drops it
+ *  and cannot recurse into another buildStart. The consumer's plugin list may nest arrays and hold
+ *  falsy slots, so guard the shape. */
+function isCairnManifestPlugin(p: unknown): boolean {
+  return !!p && typeof p === 'object' && 'name' in p && (p as { name?: unknown }).name === 'cairn-manifest';
+}
+
+/** Flatten the consumer's plugins option and drop the cairnManifest plugin at any nesting depth, so
+ *  the nested verify server can never re-enter its buildStart. Vite supports (and flattens) nested
+ *  plugin arrays, and findCairnOptions recurses into them, so a flat single-level filter would miss a
+ *  cairnManifest nested inside a shared preset's sub-array and let it survive into the nested server.
+ *  This mirrors findCairnOptions's recursion. Falsy slots pass through, which Vite tolerates. */
+export function stripCairnManifest(plugins: PluginOption | PluginOption[]): PluginOption[] {
+  if (Array.isArray(plugins)) return plugins.flatMap(stripCairnManifest);
+  if (isCairnManifestPlugin(plugins)) return [];
+  return [plugins];
+}
+
+/** Verify the committed manifest against the corpus from a Vite context, throwing on drift. The bin
+ *  and the plugin share this; the spike proved it runs cleanly inside the consumer's config. */
+export async function verifyManifestFromVite(opts: CairnManifestOptions, root: string): Promise<void> {
+  await evalVirtual(opts, 'verify', root);
+}
+
+/** Regenerate the serialized manifest from the corpus in a Vite context, sharing the build's
+ *  resolution. The cairn-manifest bin (a later task) will call this and write the result. */
+export async function buildManifestFromVite(opts: CairnManifestOptions, root: string): Promise<string> {
+  return evalVirtual(opts, 'write', root);
+}
+
+/** The cairnManifest plugin. It serves the verify virtual module to the app graph and, in
+ *  buildStart, evaluates it through a nested Vite SSR load so a manifest drift fails the build. */
+export function cairnManifest(opts: CairnManifestOptions): Plugin {
+  let root = process.cwd();
+  const plugin: CairnManifestPlugin = {
+    name: 'cairn-manifest',
+    configResolved(config) {
+      // Capture the resolved app root so the nested server loads the same config the build did.
+      root = config.root;
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+    },
+    load(id) {
+      if (id === RESOLVED_ID) return virtualSource(opts, 'verify');
+    },
+    async buildStart() {
+      try {
+        await verifyManifestFromVite(opts, root);
+      } catch (err) {
+        this.error(err instanceof Error ? err.message : String(err));
+      }
+    },
+  };
+  // Stash the options on the instance so the cairn-manifest bin's writeManifest can read the content
+  // globs, config module, and manifest path off the plugin in the consumer's loaded config, sharing
+  // exactly the options the build verifies with.
+  plugin[CAIRN_OPTIONS] = opts;
+  return plugin;
+}
+
+/** Regenerate the committed manifest from the consumer's corpus and write it to the configured
+ *  manifestPath. It loads the consumer's Vite config from `cwd`, reads the cairnManifest plugin's
+ *  options off the instance, evaluates the write-mode virtual module through the build's own
+ *  resolution, and writes the serialized manifest. The cairn-manifest bin calls this; it is exported
+ *  so the write logic is testable apart from the CLI shell. */
+export async function writeManifest(cwd: string = process.cwd()): Promise<void> {
+  const { loadConfigFromFile } = await import('vite');
+  const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, undefined, cwd);
+  if (!loaded) {
+    throw new Error(`cairn-manifest: no Vite config found in ${cwd}`);
+  }
+  const opts = findCairnOptions(loaded.config.plugins);
+  if (!opts) {
+    throw new Error(
+      'cairn-manifest: the Vite config has no cairnManifest() plugin. Add it so the bin shares the build options.',
+    );
+  }
+  const serialized = await buildManifestFromVite(opts, cwd);
+  const manifestPath = opts.manifestPath ?? DEFAULT_MANIFEST_PATH;
+  // The manifest path is app-root-absolute (a leading slash relative to the project), so resolve it
+  // against cwd, not the filesystem root.
+  const outPath = join(cwd, manifestPath.replace(/^\//, ''));
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, serialized);
+}
+
+/** Walk a Vite plugins option (which may nest arrays, hold falsy slots, or be a thenable) and return
+ *  the stashed cairnManifest options from the first matching plugin, or null if there is none. */
+function findCairnOptions(plugins: unknown): CairnManifestOptions | null {
+  if (!plugins) return null;
+  if (Array.isArray(plugins)) {
+    for (const p of plugins) {
+      const found = findCairnOptions(p);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (typeof plugins === 'object' && CAIRN_OPTIONS in plugins) {
+    return (plugins as CairnManifestPlugin)[CAIRN_OPTIONS] ?? null;
+  }
+  return null;
+}
+
+/** A minimal plugin that serves only the virtual module in one mode, for the nested SSR load. It
+ *  carries no buildStart, so the nested server never recurses into the verify. */
+function cairnVirtualOnly(opts: CairnManifestOptions, mode: 'verify' | 'write'): Plugin {
+  return {
+    name: 'cairn-manifest-virtual',
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID;
+    },
+    load(id) {
+      if (id === RESOLVED_ID) return virtualSource(opts, mode);
+    },
+  };
+}