@glw907/cairn-cms 0.17.0 → 0.21.0

package/src/lib/content/manifest.ts

@@ -0,0 +1,190 @@
+// cairn-cms: the content manifest, a committed JSON projection of the corpus (content-graph
+// design). The files in git stay the source of truth; the manifest exists so request-time admin
+// code reads the content graph without an N+1 GitHub crawl. The build regenerates and verifies
+// it; the save path patches one entry and commits it with the content in one commit. Each entry
+// carries its identity and its outbound cairn: edges, so the manifest is the link graph.
+import { idFromFilename, slugFromId } from './ids.js';
+import { parseMarkdown } from './frontmatter.js';
+import { permalink } from './permalink.js';
+import { extractCairnLinks, type CairnRef, type LinkResolve } from './links.js';
+import type { ConceptDescriptor } from './types.js';
+
+/** One entry's projection: its identity, routing, draft flag, and outbound cairn: edges. */
+export interface ManifestEntry {
+  id: string;
+  concept: string;
+  title: string;
+  date?: string;
+  permalink: string;
+  draft: boolean;
+  links: CairnRef[];
+}
+
+/** The whole corpus as one committed file. `version` guards a future shape migration. */
+export interface Manifest {
+  version: 1;
+  entries: ManifestEntry[];
+}
+
+/** The minimal entry view the preview resolver and (later) the picker read. */
+export interface LinkTarget {
+  concept: string;
+  id: string;
+  permalink: string;
+  title: string;
+  date?: string;
+  draft: boolean;
+}
+
+function basename(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash >= 0 ? path.slice(slash + 1) : path;
+}
+
+/** Mirror content-index's frontmatter coercion: a present non-empty string, else undefined. */
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+/** Mirror content-index's date coercion: an unquoted YAML date is a JS Date, a string is sliced. */
+function asDate(value: unknown): string | undefined {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? undefined : value.toISOString().slice(0, 10);
+  if (typeof value === 'string') return value.match(/^\d{4}-\d{2}-\d{2}/)?.[0];
+  return undefined;
+}
+
+/** Build one manifest entry from a content file. Drafts are included and flagged. */
+export function manifestEntryFromFile(descriptor: ConceptDescriptor, file: { path: string; raw: string }): ManifestEntry {
+  const id = idFromFilename(basename(file.path));
+  // Use the same slug rule content-index uses, so the manifest's permalink for an entry always
+  // equals content-index's permalink for it. A cairn link must resolve to one URL whether the
+  // admin preview reads the manifest or the public build reads the content index.
+  const slug = slugFromId(id, descriptor.routing.dated ? descriptor.datePrefix : null);
+  const { frontmatter, body } = parseMarkdown(file.raw);
+  const date = asDate(frontmatter.date);
+  return {
+    id,
+    concept: descriptor.id,
+    title: asString(frontmatter.title) ?? id,
+    date,
+    permalink: permalink(descriptor, { id, slug, date }),
+    draft: frontmatter.draft === true,
+    links: extractCairnLinks(body),
+  };
+}
+
+/** An empty manifest, the starting point when no committed file exists yet. */
+export function emptyManifest(): Manifest {
+  return { version: 1, entries: [] };
+}
+
+function compareRef(a: CairnRef, b: CairnRef): number {
+  return a.concept.localeCompare(b.concept) || a.id.localeCompare(b.id);
+}
+
+/** Serialize canonically: entries sorted by concept then id, links sorted and deduped, a fixed key
+ *  order, two-space pretty, and a trailing newline, so the committed file diffs cleanly in a PR. */
+export function serializeManifest(manifest: Manifest): string {
+  const entries = [...manifest.entries].sort(compareRef).map((e) => ({
+    id: e.id,
+    concept: e.concept,
+    title: e.title,
+    ...(e.date ? { date: e.date } : {}),
+    permalink: e.permalink,
+    draft: e.draft,
+    links: [...e.links].sort(compareRef).map((r) => ({ concept: r.concept, id: r.id })),
+  }));
+  return `${JSON.stringify({ version: 1, entries }, null, 2)}\n`;
+}
+
+/** Parse a committed manifest. Throws on malformed JSON, a wrong version, or a malformed entry, so
+ *  every reader (the save guard, the delete path, the preview) sees a well-formed graph or a clear
+ *  error. The build regenerates the manifest, so a real file is always canonical; this guards a
+ *  hand-edited or truncated one. */
+export function parseManifest(raw: string): Manifest {
+  const data = JSON.parse(raw) as unknown;
+  if (!data || typeof data !== 'object') {
+    throw new Error('content manifest: malformed file, expected { version, entries: [] }');
+  }
+  const obj = data as { version?: unknown; entries?: unknown };
+  if (obj.version !== 1) {
+    throw new Error(`content manifest: unsupported version ${String(obj.version)}, expected 1`);
+  }
+  if (!Array.isArray(obj.entries)) {
+    throw new Error('content manifest: malformed file, expected { version, entries: [] }');
+  }
+  for (const entry of obj.entries) {
+    const e = entry as Record<string, unknown>;
+    const ok =
+      e &&
+      typeof e.id === 'string' &&
+      typeof e.concept === 'string' &&
+      typeof e.title === 'string' &&
+      typeof e.permalink === 'string' &&
+      typeof e.draft === 'boolean' &&
+      (e.date === undefined || typeof e.date === 'string') &&
+      Array.isArray(e.links);
+    if (!ok) {
+      throw new Error(`content manifest: malformed entry ${JSON.stringify(e)}`);
+    }
+    // Validate each link element's shape, not just that links is an array. inboundLinks and the
+    // delete guard read l.concept and l.id, so a string, null, or id-less element would read as
+    // undefined and silently drop a real inbound linker. Reject it here instead.
+    for (const link of e.links as unknown[]) {
+      const l = link as Record<string, unknown> | null;
+      if (!l || typeof l !== 'object' || typeof l.concept !== 'string' || typeof l.id !== 'string') {
+        throw new Error(`content manifest: malformed link ${JSON.stringify(link)} in entry ${JSON.stringify(e)}`);
+      }
+    }
+  }
+  return { version: 1, entries: obj.entries as ManifestEntry[] };
+}
+
+/** Throw if the committed manifest drifts from what the corpus says. Both sides are compared in the
+ *  canonical serialized form, so semantic equality never spuriously fails. The build calls this so a
+ *  raw-git content edit, which leaves the committed manifest stale, fails the build loudly. */
+export function verifyManifest(built: Manifest, committedRaw: string): void {
+  if (committedRaw !== serializeManifest(built)) {
+    throw new Error(
+      'content manifest is stale: the committed file does not match the corpus. Regenerate it (npm run cairn:manifest) and commit the result.',
+    );
+  }
+}
+
+/** Replace the entry with the same concept and id, or add it. Order does not matter, since
+ *  serializeManifest sorts. This is the save path's incremental patch. */
+export function upsertEntry(manifest: Manifest, entry: ManifestEntry): Manifest {
+  const entries = manifest.entries.filter((e) => !(e.concept === entry.concept && e.id === entry.id));
+  entries.push(entry);
+  return { version: 1, entries };
+}
+
+/** Drop the entry with the given concept and id, if present. The delete path's patch. */
+export function removeEntry(manifest: Manifest, concept: string, id: string): Manifest {
+  return { version: 1, entries: manifest.entries.filter((e) => !(e.concept === concept && e.id === id)) };
+}
+
+/** One inbound linker: enough to name it and link to its edit page in the delete guard. */
+export interface InboundLink {
+  concept: string;
+  id: string;
+  title: string;
+  permalink: string;
+}
+
+/** Every entry whose outbound edges point at the target, excluding the target itself. The delete
+ *  guard reads this to name "what links here"; the backlinks panel will reuse it. Pure over the
+ *  manifest, so the request-time delete path and a unit test call it the same way. */
+export function inboundLinks(manifest: Manifest, concept: string, id: string): InboundLink[] {
+  return manifest.entries
+    .filter((e) => !(e.concept === concept && e.id === id))
+    .filter((e) => e.links.some((l) => l.concept === concept && l.id === id))
+    .map((e) => ({ concept: e.concept, id: e.id, title: e.title, permalink: e.permalink }));
+}
+
+/** A resolver backed by manifest targets, for the admin preview. A miss returns undefined, so the
+ *  render step marks the link broken rather than throwing. The build resolver throws instead. */
+export function manifestLinkResolver(targets: { concept: string; id: string; permalink: string }[]): LinkResolve {
+  const byKey = new Map(targets.map((t) => [`${t.concept}/${t.id}`, t.permalink]));
+  return (ref) => byKey.get(`${ref.concept}/${ref.id}`);
+}

package/src/lib/content/types.ts

@@ -11,6 +11,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';
+import type { LinkResolve } from './links.js';
 
 /** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
 interface FieldBase {
@@ -171,8 +172,13 @@ export interface CairnAdapter {
   };
   backend: BackendConfig;
   sender: SenderConfig;
-  /** The site's one renderer: the editor preview and every public page call it (design decision 4). */
-  render(md: string, opts?: { stagger?: boolean }): string | Promise<string>;
+  /** The site's one renderer: the editor preview and every public page call it (design decision 4).
+   *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-index resolver, the
+   *  preview a manifest one. */
+  render(md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }): string | Promise<string>;
+  /** Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
+   *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it. */
+  manifestPath?: string;
   /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
   registry?: ComponentRegistry;
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
@@ -267,7 +273,8 @@ export interface CairnRuntime {
   backend: BackendConfig;
   sender: SenderConfig;
   /** The site's one renderer: the editor preview and every public page call it (design decision 4). */
-  render(md: string, opts?: { stagger?: boolean }): string | Promise<string>;
+  render(md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }): string | Promise<string>;
+  manifestPath: string;
   registry?: ComponentRegistry;
   /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
   icons?: IconSet;

package/src/lib/delivery/index.ts

@@ -25,6 +25,7 @@ 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 { buildSiteManifest, buildLinkResolver } from './manifest.js';
 export { createPublicRoutes } from '../sveltekit/public-routes.js';
 export type {
   PublicRoutesDeps,

package/src/lib/delivery/manifest.ts

@@ -0,0 +1,44 @@
+// cairn-cms: the build-side manifest builder and the build link resolver (content-graph design).
+// buildSiteManifest mirrors createSiteIndexes: it maps the site descriptors over the per-concept
+// globs and projects each file to a manifest row. buildLinkResolver reads the site index, which is
+// fresh from the files at build, and throws on a missing target so a dangling cairn: token fails
+// the build (the backstop). The admin preview uses manifestLinkResolver instead.
+import { siteDescriptors } from './site-descriptors.js';
+import { fromGlob } from './content-index.js';
+import { parseMarkdown } from '../content/frontmatter.js';
+import { emptyManifest, manifestEntryFromFile } from '../content/manifest.js';
+import type { Manifest } from '../content/manifest.js';
+import type { LinkResolve } from '../content/links.js';
+import type { SiteIndex } from './site-index.js';
+import type { SiteConfig } from '../nav/site-config.js';
+import type { CairnAdapter } from '../content/types.js';
+import type { SiteGlobs } from './site-indexes.js';
+
+/** Build the whole-corpus manifest from a site's adapter, config, and per-concept globs. Drafts are
+ *  included and flagged, so the admin picker and the guards see the full graph. */
+export function buildSiteManifest<A extends CairnAdapter>(adapter: A, config: SiteConfig, globs: SiteGlobs<A>): Manifest {
+  const globRecord = globs as Record<string, Record<string, string> | undefined>;
+  const manifest = emptyManifest();
+  for (const descriptor of siteDescriptors(adapter, config)) {
+    const record = globRecord[descriptor.id] ?? {};
+    for (const file of fromGlob(record)) {
+      // Validate the same way createContentIndex does, so the manifest and the site index agree on
+      // which entries exist. A validation failure is excluded from both; otherwise the preview would
+      // resolve a link the build then rejects as a missing target.
+      const { frontmatter, body } = parseMarkdown(file.raw);
+      if (!descriptor.validate(frontmatter, body).ok) continue;
+      manifest.entries.push(manifestEntryFromFile(descriptor, file));
+    }
+  }
+  return manifest;
+}
+
+/** A resolver backed by the site index, for the build. A miss throws, so a dangling cairn: token
+ *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks. */
+export function buildLinkResolver(site: SiteIndex): LinkResolve {
+  return (ref) => {
+    const url = site.concept(ref.concept)?.byId(ref.id)?.permalink;
+    if (!url) throw new Error(`cairn link target not found: cairn:${ref.concept}/${ref.id}`);
+    return url;
+  };
+}

package/src/lib/github/repo.ts

@@ -136,3 +136,113 @@ export async function commitFile(
   if (!res.ok) throw new Error(`GitHub commit ${path} failed: ${res.status} ${await res.text()}`);
   return ((await res.json()) as { commit: { sha: string } }).commit.sha;
 }
+
+/** A path change for an atomic commit: write `content`, or delete the path when `content` is null. */
+export interface FileChange {
+  path: string;
+  content: string | null;
+}
+
+/** A Git Trees API change entry: a blob written from raw content, or a `sha: null` delete. */
+interface TreeChange {
+  path: string;
+  mode: '100644';
+  type: 'blob';
+  content?: string;
+  sha?: null;
+}
+
+/** A Git Data API URL under the repo's `git/` namespace. */
+function gitUrl(repo: RepoRef, suffix: string): string {
+  return `${API}/repos/${repo.owner}/${repo.repo}/git/${suffix}`;
+}
+
+/** The branch head commit sha, through the Git Data API single-ref read. */
+async function headCommitSha(repo: RepoRef, token: string): Promise<string> {
+  const res = await fetch(gitUrl(repo, `ref/heads/${encodeURIComponent(repo.branch)}`), {
+    headers: ghHeaders('application/vnd.github+json', token),
+  });
+  if (!res.ok) throw new Error(`GitHub ref ${repo.branch} failed: ${res.status}`);
+  return ((await res.json()) as { object: { sha: string } }).object.sha;
+}
+
+/** The base tree sha of a commit. */
+async function commitTreeSha(repo: RepoRef, commitSha: string, token: string): Promise<string> {
+  const res = await fetch(gitUrl(repo, `commits/${commitSha}`), {
+    headers: ghHeaders('application/vnd.github+json', token),
+  });
+  if (!res.ok) throw new Error(`GitHub commit ${commitSha} failed: ${res.status}`);
+  return ((await res.json()) as { tree: { sha: string } }).tree.sha;
+}
+
+/** Map file changes to Git Trees API entries, encoding a null content as a delete. */
+function treeChanges(changes: FileChange[]): TreeChange[] {
+  return changes.map((c) =>
+    c.content === null
+      ? { path: c.path, mode: '100644', type: 'blob', sha: null }
+      : { path: c.path, mode: '100644', type: 'blob', content: c.content },
+  );
+}
+
+/** Retries after the initial attempt when the branch moves under an atomic commit. */
+const COMMIT_RETRIES = 3;
+
+/**
+ * Commit several path changes in one commit over the Git Data API. The author is the editor; the
+ * committer is omitted, so GitHub attributes the commit to the App. Returns the new commit sha.
+ * Builds the new tree on the current head's tree, so paths not named here are preserved.
+ *
+ * Caller preconditions this layer cannot enforce (the save and lifecycle paths must): every
+ * `path` is confined to the site's content directories (the App token can write anywhere in the
+ * repo), and `author` is derived from the verified server-side session, never request input.
+ *
+ * An empty change set is rejected, since it would otherwise push an empty commit that triggers a
+ * site redeploy for no content change.
+ */
+export async function commitFiles(
+  repo: RepoRef,
+  changes: FileChange[],
+  opts: { message: string; author: CommitAuthor },
+  token: string,
+): Promise<string> {
+  if (changes.length === 0) throw new Error('commitFiles: no changes to commit');
+  const tree = treeChanges(changes);
+  for (let attempt = 0; attempt <= COMMIT_RETRIES; attempt++) {
+    const parent = await headCommitSha(repo, token);
+    const baseTree = await commitTreeSha(repo, parent, token);
+
+    const treeRes = await fetch(gitUrl(repo, 'trees'), {
+      method: 'POST',
+      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ base_tree: baseTree, tree }),
+    });
+    if (!treeRes.ok) {
+      // A 422 means an entry is unprocessable against the base tree, which a delete of an
+      // already-removed path produces (a concurrent delete or rename got there first). Treat it as
+      // the same non-fast-forward conflict the ref PATCH surfaces, so the caller fails safe with the
+      // reload-and-retry path instead of a raw 500.
+      if (treeRes.status === 422) throw new CommitConflictError(`${repo.branch} (tree create)`);
+      throw new Error(`GitHub tree create failed: ${treeRes.status} ${await treeRes.text()}`);
+    }
+    const newTree = ((await treeRes.json()) as { sha: string }).sha;
+
+    const commitRes = await fetch(gitUrl(repo, 'commits'), {
+      method: 'POST',
+      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ message: opts.message, tree: newTree, parents: [parent], author: opts.author }),
+    });
+    if (!commitRes.ok) throw new Error(`GitHub commit create failed: ${commitRes.status} ${await commitRes.text()}`);
+    const newCommit = ((await commitRes.json()) as { sha: string }).sha;
+
+    const refRes = await fetch(gitUrl(repo, `refs/heads/${encodeURIComponent(repo.branch)}`), {
+      method: 'PATCH',
+      headers: { ...ghHeaders('application/vnd.github+json', token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sha: newCommit, force: false }),
+    });
+    if (refRes.ok) return newCommit;
+    // A non-fast-forward means the branch moved; retry on the new head so a concurrent commit
+    // is preserved. Any other failure is not a race, so surface it.
+    if (refRes.status !== 422) throw new Error(`GitHub ref update failed: ${refRes.status} ${await refRes.text()}`);
+  }
+  throw new CommitConflictError(`${repo.branch} (atomic commit)`);
+}

package/src/lib/index.ts

@@ -49,6 +49,23 @@ export {
   composeDatedId,
 } from './content/ids.js';
 export type { DatePrefix } from './content/ids.js';
+// Internal-link token and the committed content manifest (content-graph design). The corpus
+// builder and the request-time resolver ship from the delivery entry; this surface is the
+// grammar, the manifest operations, and their types a migrating site adopts.
+export { parseCairnToken, extractCairnLinks, formatCairnToken, escapeLinkText } from './content/links.js';
+export type { CairnRef, LinkResolve } from './content/links.js';
+export {
+  serializeManifest,
+  parseManifest,
+  emptyManifest,
+  verifyManifest,
+  upsertEntry,
+  removeEntry,
+  manifestEntryFromFile,
+  manifestLinkResolver,
+  inboundLinks,
+} from './content/manifest.js';
+export type { Manifest, ManifestEntry, LinkTarget, InboundLink } from './content/manifest.js';
 // Render engine (Plan 04): generic directive pipeline; sites own the component registry.
 export { defineRegistry, emptyValues } from './render/registry.js';
 export type {

package/src/lib/render/pipeline.ts

@@ -8,10 +8,13 @@ import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
 import rehypeSanitize from 'rehype-sanitize';
 import type { Schema } from 'hast-util-sanitize';
+import { VFile } from 'vfile';
 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 type { LinkResolve } from '../content/links.js';
 
 export interface RendererOptions {
   /** Stamp a `data-rise` ordinal (0, 1, 2, …) on each top-level component so a site's
@@ -33,7 +36,7 @@ export interface RendererOptions {
  *  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 = {}) {
-  const remarkPlugins: PluggableList = [remarkDirective, [remarkDirectiveStamp, registry]];
+  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
   // sanitized). The anchor-rel hardening runs last so it also covers component-built anchors.
@@ -57,6 +60,9 @@ export function createRenderer(registry: ComponentRegistry, options: RendererOpt
   return {
     remarkPlugins,
     rehypePlugins,
-    renderMarkdown: async (content: string): Promise<string> => String(await processor.process(content)),
+    renderMarkdown: async (content: string, opts: { resolve?: LinkResolve } = {}): Promise<string> => {
+      const file = new VFile({ value: content, data: { [CAIRN_RESOLVE]: opts.resolve } });
+      return String(await processor.process(file));
+    },
   };
 }

package/src/lib/render/resolve-links.ts

@@ -0,0 +1,42 @@
+// cairn-cms: the cairn: link resolver, an mdast step in the render pipeline (content-graph design).
+// It runs before remark-rehype, so the rewritten href passes through the sanitize floor exactly as
+// any other anchor. The per-call resolver is read off the VFile (set by renderMarkdown), so the
+// processor is still built once. A miss either marks the link broken (preview) or throws (build),
+// decided by the injected resolver.
+import { visit } from 'unist-util-visit';
+import type { VFile } from 'vfile';
+import { parseCairnToken, type LinkResolve } from '../content/links.js';
+
+/** The VFile data key the renderer sets the per-call resolver under. */
+export const CAIRN_RESOLVE = 'cairnResolve';
+
+interface LinkNode {
+  url: string;
+  data?: { hProperties?: Record<string, unknown> };
+}
+
+/** Resolve cairn: link nodes against the VFile's resolver. A non-cairn href and a malformed token
+ *  pass through. A missing target is marked with the cairn-broken-link class (the resolver returns
+ *  undefined) or, when the resolver throws, the error propagates and fails the build. */
+export function remarkResolveCairnLinks() {
+  return (tree: unknown, file: VFile): void => {
+    const resolve = file.data[CAIRN_RESOLVE] as LinkResolve | undefined;
+    if (!resolve) return;
+    visit(tree as Parameters<typeof visit>[0], 'link', (node: LinkNode) => {
+      const ref = parseCairnToken(node.url);
+      if (!ref) return;
+      const url = resolve(ref); // may throw (build backstop); propagates out of render
+      if (url) {
+        node.url = url;
+        return;
+      }
+      // Missing target in the preview: mark it broken and neutralize the href, keeping the text.
+      node.url = '#';
+      node.data = node.data ?? {};
+      const props = (node.data.hProperties = node.data.hProperties ?? {});
+      const existing = Array.isArray(props.className) ? (props.className as string[]) : [];
+      props.className = [...existing, 'cairn-broken-link'];
+      props.title = 'Broken internal link';
+    });
+  };
+}

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

@@ -29,6 +29,11 @@ export function buildSanitizeSchema(
   const anchorAttrs = (attributes.a ?? []).filter(
     (entry) => !(Array.isArray(entry) && entry[0] === 'className'),
   );
+  // Admit the inert `cairn:` href scheme on top of the default protocol allowlist. The render
+  // resolver rewrites a `cairn:` link to a live permalink before delivery; an unresolved one
+  // survives the floor in its inert token form (a visible unresolved-link signal), never as an
+  // executable vector. The dangerous-protocol strip (javascript:, data:) is preserved.
+  const protocols = defaultSchema.protocols ?? {};
   const schema: Schema = {
     ...defaultSchema,
     tagNames: [...(defaultSchema.tagNames ?? []), 'nav', 'details', 'summary'],
@@ -37,6 +42,10 @@ export function buildSanitizeSchema(
       '*': [...(attributes['*'] ?? []), 'className', ...markers],
       a: [...anchorAttrs, 'className', 'target', 'rel'],
     },
+    protocols: {
+      ...protocols,
+      href: [...(protocols.href ?? []), 'cairn'],
+    },
   };
   return extend ? extend(schema) : schema;
 }