@glw907/cairn-cms 0.17.0 → 0.18.0

package/dist/render/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/lib/render/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAStD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAIjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B;;0FAEsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;wCAGoC;IACpC,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C;;+EAE2E;IAC3E,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;uFAEuF;AACvF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,GAAE,eAAoB;;;8BAyBrD,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;EAE3D"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/lib/render/pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAStD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAMjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,eAAe;IAC9B;;0FAEsF;IACtF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;wCAGoC;IACpC,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC9C;;+EAE2E;IAC3E,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;uFAEuF;AACvF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,GAAE,eAAoB;;;8BAyBrD,MAAM,SAAQ;QAAE,OAAO,CAAC,EAAE,WAAW,CAAA;KAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;EAKjG"}

package/dist/render/pipeline.js

@@ -7,14 +7,16 @@ import rehypeRaw from 'rehype-raw';
 import rehypeSlug from 'rehype-slug';
 import rehypeStringify from 'rehype-stringify';
 import rehypeSanitize from 'rehype-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';
 /** 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, options = {}) {
-    const remarkPlugins = [remarkDirective, [remarkDirectiveStamp, registry]];
+    const remarkPlugins = [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.
@@ -38,6 +40,9 @@ export function createRenderer(registry, options = {}) {
     return {
         remarkPlugins,
         rehypePlugins,
-        renderMarkdown: async (content) => String(await processor.process(content)),
+        renderMarkdown: async (content, opts = {}) => {
+            const file = new VFile({ value: content, data: { [CAIRN_RESOLVE]: opts.resolve } });
+            return String(await processor.process(file));
+        },
     };
 }

package/dist/render/resolve-links.d.ts

@@ -0,0 +1,8 @@
+import type { VFile } from 'vfile';
+/** The VFile data key the renderer sets the per-call resolver under. */
+export declare const CAIRN_RESOLVE = "cairnResolve";
+/** 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 declare function remarkResolveCairnLinks(): (tree: unknown, file: VFile) => void;
+//# sourceMappingURL=resolve-links.d.ts.map

package/dist/render/resolve-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-links.d.ts","sourceRoot":"","sources":["../../src/lib/render/resolve-links.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGnC,wEAAwE;AACxE,eAAO,MAAM,aAAa,iBAAiB,CAAC;AAO5C;;yFAEyF;AACzF,wBAAgB,uBAAuB,KAC7B,MAAM,OAAO,EAAE,MAAM,KAAK,KAAG,IAAI,CAoB1C"}

package/dist/render/resolve-links.js

@@ -0,0 +1,36 @@
+// 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 { parseCairnToken } from '../content/links.js';
+/** The VFile data key the renderer sets the per-call resolver under. */
+export const CAIRN_RESOLVE = 'cairnResolve';
+/** 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, file) => {
+        const resolve = file.data[CAIRN_RESOLVE];
+        if (!resolve)
+            return;
+        visit(tree, 'link', (node) => {
+            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 : [];
+            props.className = [...existing, 'cairn-broken-link'];
+            props.title = 'Broken internal link';
+        });
+    };
+}

package/dist/render/sanitize-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sanitize-schema.d.ts","sourceRoot":"","sources":["../../src/lib/render/sanitize-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAMrE;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GACpC,MAAM,CAoBR;AAED;;;;GAIG;AACH,wBAAgB,eAAe,KACrB,MAAM,IAAI,UAOnB"}
+{"version":3,"file":"sanitize-schema.d.ts","sourceRoot":"","sources":["../../src/lib/render/sanitize-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,IAAI,EAAW,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAMrE;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GACpC,MAAM,CA6BR;AAED;;;;GAIG;AACH,wBAAgB,eAAe,KACrB,MAAM,IAAI,UAOnB"}

package/dist/render/sanitize-schema.js

@@ -21,6 +21,11 @@ export function buildSanitizeSchema(registry, extend) {
     // that restricts a link's class to that one value. A per-tag tuple wins over a bare `*` entry, so
     // it would strip an author's link class. Drop that tuple before admitting a free-form `className`.
     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 = {
         ...defaultSchema,
         tagNames: [...(defaultSchema.tagNames ?? []), 'nav', 'details', 'summary'],
@@ -29,6 +34,10 @@ export function buildSanitizeSchema(registry, extend) {
             '*': [...(attributes['*'] ?? []), 'className', ...markers],
             a: [...anchorAttrs, 'className', 'target', 'rel'],
         },
+        protocols: {
+            ...protocols,
+            href: [...(protocols.href ?? []), 'cairn'],
+        },
     };
     return extend ? extend(schema) : schema;
 }

package/dist/sveltekit/content-routes.d.ts

@@ -1,4 +1,5 @@
 import { type GithubKeyEnv } from '../github/credentials.js';
+import { type LinkTarget } from '../content/manifest.js';
 import type { CairnRuntime, FrontmatterField } from '../content/types.js';
 import type { Editor, Role } from '../auth/types.js';
 /** A sidebar concept entry: just enough to render the nav without shipping validators to the client. */
@@ -50,6 +51,8 @@ export interface EditData {
     isNew: boolean;
     saved: boolean;
     error: string | null;
+    /** The site's link targets, for the preview resolver and the link picker; from the committed manifest. */
+    linkTargets: LinkTarget[];
 }
 /** The structural event the content routes read; a real SvelteKit RequestEvent satisfies it. */
 export interface ContentEvent {

package/dist/sveltekit/content-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"content-routes.d.ts","sourceRoot":"","sources":["../../src/lib/sveltekit/content-routes.ts"],"names":[],"mappings":"AAQA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAI7E,OAAO,KAAK,EAAE,YAAY,EAAqB,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAErD,wGAAwG;AACxG,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,gGAAgG;AAChG,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC;IAC1C,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,yGAAyG;IACzG,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,oCAAoC;AACpC,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,2FAA2F;IAC3F,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,gFAAgF;IAChF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qDAAqD;IACrD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,6FAA6F;AAC7F,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,gGAAgG;AAChG,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,GAAG,CAAC;IACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACnC,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC;CACnC;AAED,sFAAsF;AACtF,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACpD;AAgBD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,GAAE,iBAAsB;wBAK1D,YAAY,KAAG,UAAU;yBAa1B,KAAK;sBAqBA,YAAY,KAAG,OAAO,CAAC,QAAQ,CAAC;0BAqB5B,YAAY,KAAG,OAAO,CAAC,KAAK,CAAC;sBAyCjC,YAAY,KAAG,OAAO,CAAC,QAAQ,CAAC;wBAgC9B,YAAY,KAAG,OAAO,CAAC,KAAK,CAAC;qBAtJ5C,YAAY,KAAK,OAAO,CAAC,MAAM,CAAC;EA+LnD"}
+{"version":3,"file":"content-routes.d.ts","sourceRoot":"","sources":["../../src/lib/sveltekit/content-routes.ts"],"names":[],"mappings":"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"}

package/dist/sveltekit/content-routes.js

@@ -7,8 +7,9 @@ import { findConcept } from '../content/concepts.js';
 import { frontmatterFromForm, parseMarkdown, dateInputValue, serializeMarkdown } from '../content/frontmatter.js';
 import { isValidId, slugify, filenameFromId, composeDatedId } from '../content/ids.js';
 import { appCredentials } from '../github/credentials.js';
-import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
+import { listMarkdown, readRaw, commitFiles } from '../github/repo.js';
 import { cachedInstallationToken } from '../github/signing.js';
+import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry } from '../content/manifest.js';
 import { CommitConflictError } from '../github/types.js';
 /** The signed-in editor the guard resolved, or a login redirect. Kept local to decouple event shapes. */
 function sessionOf(event) {
@@ -139,6 +140,18 @@ export function createContentRoutes(runtime, deps = {}) {
             throw error(404, 'Entry not found');
         const parsed = raw === null ? { frontmatter: {}, body: '' } : parseMarkdown(raw);
         const title = typeof parsed.frontmatter.title === 'string' && parsed.frontmatter.title.trim() ? parsed.frontmatter.title : id;
+        let linkTargets = [];
+        const manifestRaw = await readRaw(runtime.backend, runtime.manifestPath, token);
+        if (manifestRaw !== null) {
+            linkTargets = parseManifest(manifestRaw).entries.map((e) => ({
+                concept: e.concept,
+                id: e.id,
+                permalink: e.permalink,
+                title: e.title,
+                date: e.date,
+                draft: e.draft,
+            }));
+        }
         return {
             conceptId: concept.id,
             id,
@@ -150,6 +163,7 @@ export function createContentRoutes(runtime, deps = {}) {
             isNew,
             saved: event.url.searchParams.get('saved') === '1',
             error: event.url.searchParams.get('error'),
+            linkTargets,
         };
     }
     /** Match a commit conflict by class and by name (bundling can alias the class identity). */
@@ -177,8 +191,21 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         const markdown = serializeMarkdown(result.data, body);
         const token = await mintToken(event.platform?.env ?? {});
+        // Read the committed manifest, upsert this entry's row, and commit content and manifest in one
+        // commit. A missing manifest starts empty (first save on a fresh repo). The build regenerates
+        // and verifies the manifest, so this incremental patch is the cheap request-time path. On a
+        // 422 retry commitFiles re-sends this manifest blob last-writer-wins. A concurrent save can then
+        // leave the committed manifest stale, which the next build rejects via verifyManifest; regenerate
+        // it with npm run cairn:manifest to recover.
+        const manifestRaw = await readRaw(runtime.backend, runtime.manifestPath, token);
+        const manifest = manifestRaw === null ? emptyManifest() : parseManifest(manifestRaw);
+        const row = manifestEntryFromFile(concept, { path, raw: markdown });
+        const nextManifest = serializeManifest(upsertEntry(manifest, row));
         try {
-            await commitFile(runtime.backend, path, markdown, { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
+            await commitFiles(runtime.backend, [
+                { path, content: markdown },
+                { path: runtime.manifestPath, content: nextManifest },
+            ], { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
         }
         catch (err) {
             if (isConflict(err)) {

package/dist/sveltekit/public-routes.d.ts

@@ -1,11 +1,13 @@
 import type { ContentSummary, ContentEntry } from '../delivery/content-index.js';
 import type { SiteIndex } from '../delivery/site-index.js';
 import type { SeoMeta } from '../delivery/seo.js';
+import type { LinkResolve } from '../content/links.js';
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
     site: SiteIndex;
     render: (md: string, opts?: {
         stagger?: boolean;
+        resolve?: LinkResolve;
     }) => string | Promise<string>;
     origin: string;
     /** Site name for og:site_name and the SEO head. */

package/dist/sveltekit/public-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public-routes.d.ts","sourceRoot":"","sources":["../../src/lib/sveltekit/public-routes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,KAAK,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC;6EACyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,uDAAuD;AACvD,MAAM,WAAW,OAAQ,SAAQ,QAAQ;IACvC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxC;AAED,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB;uBAWvB;QAAE,GAAG,EAAE,GAAG,CAAA;KAAE,KAAG,OAAO,CAAC,SAAS,CAAC;6BA0BjC,MAAM,KAAG,QAAQ;8BAKhB,MAAM,KAAG,YAAY;yBAK1B,MAAM,SAAS;QAAE,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,KAAG,OAAO;mBAO5D;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;EAKvC"}
+{"version":3,"file":"public-routes.d.ts","sourceRoot":"","sources":["../../src/lib/sveltekit/public-routes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtG,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,KAAK,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC;6EACyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,uDAAuD;AACvD,MAAM,WAAW,OAAQ,SAAQ,QAAQ;IACvC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxC;AAED,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB;uBAWvB;QAAE,GAAG,EAAE,GAAG,CAAA;KAAE,KAAG,OAAO,CAAC,SAAS,CAAC;6BA0BjC,MAAM,KAAG,QAAQ;8BAKhB,MAAM,KAAG,YAAY;yBAK1B,MAAM,SAAS;QAAE,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,KAAG,OAAO;mBAO5D;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;EAKvC"}

package/dist/sveltekit/public-routes.js

@@ -6,6 +6,7 @@
 import { error } from '@sveltejs/kit';
 import { buildSeoMeta } from '../delivery/seo.js';
 import { readSeoFields, resolveImageUrl } from '../delivery/seo-fields.js';
+import { buildLinkResolver } from '../delivery/manifest.js';
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps) {
     const { site, render, origin, siteName, description, feeds, defaultImage } = deps;
@@ -40,7 +41,7 @@ export function createPublicRoutes(deps) {
             ...(fields.author ? { author: fields.author } : {}),
             ...(entry.date ? { feeds } : {}),
         });
-        return { entry, html: await render(entry.body, { stagger: true }), canonicalUrl, seo, newer, older };
+        return { 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. */
     function archiveLoad(conceptId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [

package/src/lib/components/EditPage.svelte

@@ -12,6 +12,8 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
   import type { IconSet } from '../render/glyph.js';
   import type { EditData } from '../sveltekit/content-routes.js';
   import type { TextareaField, TagsField, FreeTagsField } from '../content/types.js';
+  import type { LinkResolve } from '../content/links.js';
+  import { manifestLinkResolver } from '../content/manifest.js';
 
   interface Props {
     /** The edit load's data, plus the site name for the heading. */
@@ -19,7 +21,7 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
     /** The site's component registry, for the insert palette. */
     registry?: ComponentRegistry;
     /** The site's design-accurate render pipeline; the preview pane renders its output, which the floored pipeline already sanitized. */
-    render?: (md: string, opts?: { stagger?: boolean }) => string | Promise<string>;
+    render?: (md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }) => string | Promise<string>;
     /** The site's icon set, for the guided form's icon fields. */
     icons?: IconSet;
   }
@@ -33,6 +35,10 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
   let previewHtml = $state('');
   let insert = $state.raw<(text: string) => void>(() => {});
 
+  // The manifest-backed resolver turns a cairn: link into its live permalink in the preview, and
+  // returns undefined for a missing target so the render step marks it cairn-broken-link.
+  const resolveLink = $derived(manifestLinkResolver(data.linkTargets));
+
   const PREVIEW_KEY = 'cairn-admin:preview';
 
   $effect(() => {
@@ -53,10 +59,11 @@ markdown editor and a live, design-accurate preview. The whole surface is one fo
   $effect(() => {
     if (!showPreview || !render) return;
     const md = body;
+    const resolve = resolveLink; // tracked read in the effect body
     const run = ++previewRun;
     const handle = setTimeout(async () => {
       try {
-        const html = await render(md);
+        const html = await render(md, { resolve });
         if (run === previewRun) previewHtml = html;
       } catch {
         if (run === previewRun) previewHtml = '';

package/src/lib/content/compose.ts

@@ -31,6 +31,7 @@ export function composeRuntime(
     backend: adapter.backend,
     sender: adapter.sender,
     render: adapter.render,
+    manifestPath: adapter.manifestPath ?? 'src/content/.cairn/index.json',
     registry: adapter.registry,
     icons: adapter.icons,
     navMenu: adapter.navMenu,

package/src/lib/content/links.ts

@@ -0,0 +1,48 @@
+// cairn-cms: the cairn: internal-link token. An internal link is a standard CommonMark link
+// whose href is `cairn:<concept>/<id>`, keyed to the target's permanent filename stem so it
+// survives a slug, date, or permalink change (content-graph design). This module owns the
+// grammar; the render resolver (resolve-links.ts) reuses parseCairnToken.
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import { visit } from 'unist-util-visit';
+import { isValidId } from './ids.js';
+
+/** A resolved reference to a content entry by its concept and permanent id. */
+export interface CairnRef {
+  concept: string;
+  id: string;
+}
+
+/** Resolve a reference to its live permalink. Returns undefined when the target is missing (the
+ *  preview marks it); the build resolver throws instead, so a dangling token fails the build. */
+export type LinkResolve = (ref: CairnRef) => string | undefined;
+
+/** Parse a `cairn:<concept>/<id>` href, or null for any other href or a malformed token. */
+export function parseCairnToken(href: string): CairnRef | null {
+  if (!href.startsWith('cairn:')) return null;
+  const rest = href.slice('cairn:'.length);
+  const slash = rest.indexOf('/');
+  if (slash <= 0) return null;
+  const concept = rest.slice(0, slash);
+  const id = rest.slice(slash + 1);
+  if (!concept || !isValidId(id)) return null;
+  return { concept, id };
+}
+
+/** The cairn links a markdown body points at, in first-occurrence order, deduped by concept/id.
+ *  Parses the body as mdast, so a token inside a code span or fence is never matched. */
+export function extractCairnLinks(body: string): CairnRef[] {
+  const tree = unified().use(remarkParse).use(remarkGfm).parse(body);
+  const seen = new Set<string>();
+  const refs: CairnRef[] = [];
+  visit(tree, 'link', (node: { url?: string }) => {
+    const ref = node.url ? parseCairnToken(node.url) : null;
+    if (!ref) return;
+    const key = `${ref.concept}/${ref.id}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    refs.push(ref);
+  });
+  return refs;
+}

package/src/lib/content/manifest.ts

@@ -0,0 +1,138 @@
+// 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 or the wrong shape. */
+export function parseManifest(raw: string): Manifest {
+  const data = JSON.parse(raw) as unknown;
+  if (!data || typeof data !== 'object' || !Array.isArray((data as { entries?: unknown }).entries)) {
+    throw new Error('content manifest: malformed file, expected { version, entries: [] }');
+  }
+  return { version: 1, entries: (data as Manifest).entries };
+}
+
+/** 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)) };
+}
+
+/** 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,38 @@
+// 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 { 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)) {
+      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;
+  };
+}