@glw907/cairn-cms 0.62.2 → 0.68.0

package/src/lib/render/highlight.ts

@@ -0,0 +1,259 @@
+// cairn-cms: build-time syntax highlighting for the shared render pipeline. It tokenizes fenced
+// code with Shiki and emits a <pre class="shiki"> whose tokens carry semantic CLASS names from a
+// fixed cairn ramp (cairn-tok-keyword, cairn-tok-string, ...), never an inline style and never a
+// baked hex literal. The colors live in the site theme, so recoloring the theme recolors code with
+// no markup change.
+//
+// CLASS-DRIVEN (load-bearing): the output is class-only, with no `style` attribute on the <pre>,
+// the <code>, or any token <span>. cairn is class-driven by design (the sink guard in
+// sanitize-schema.ts strips every inline `style` wholesale), and class output survives that floor
+// naturally because `className` is already allowed on `*`. The highlighter therefore needs no
+// special placement and no ordering invariant: it runs as an ordinary rehype plugin. Never weaken
+// the sanitize floor or the sink guard to accommodate this step, and never add `style` to an
+// allowlist; the point is that class-only output needs neither.
+//
+// THE .cairn-tok-* CLASS CONTRACT: the engine owns the token class names (below); the site owns the
+// colors. This mirrors the engine's .cairn-place-* figure-placement contract: a site styles the
+// classes in its own theme. The showcase binds each class to a --cairn-code-* role variable in
+// examples/showcase/src/lib/theme.css, so the syntax palette re-skins with the rest of the theme.
+//
+//   .cairn-tok-keyword    a language keyword, storage class, or control word
+//   .cairn-tok-string     a string or quoted literal
+//   .cairn-tok-comment    a comment
+//   .cairn-tok-function   a function name, tag name, or property key
+//   .cairn-tok-number     a numeric, boolean, or other constant literal
+//   .cairn-tok-punct      punctuation and operators
+//
+// Default text carries no token class and inherits the code block's foreground (--cairn-code-ink).
+//
+// SERVER/BUILD-ONLY: Shiki is loaded through a dynamic import so it stays out of the static client
+// graph (a separate async chunk). The highlighter runs only inside the async pipeline, at
+// render/prerender and in the Worker SSR. The highlighter is created once and its promise cached.
+import type { Root, Element } from 'hast';
+import { toString } from 'hast-util-to-string';
+import type { Highlighter, ThemeRegistrationRaw, ShikiTransformer } from 'shiki';
+
+// The curated language set Shiki preloads. Each id pulls its aliases too (loading `bash` also
+// registers `sh`, `shell`, `zsh`; loading `js` registers `javascript`, `mjs`, `cjs`). A fence whose
+// language is absent or outside this set falls back to plaintext rather than throwing.
+const LANGS = [
+  'js',
+  'ts',
+  'jsx',
+  'tsx',
+  'svelte',
+  'html',
+  'css',
+  'json',
+  'bash',
+  'markdown',
+  'python',
+  'yaml',
+  'sql',
+] as const;
+
+// The plaintext language id. Shiki special-cases it (and `plaintext`/`txt`/`ansi`) as always
+// available, so it is the safe fallback for an unknown or absent fence language: it escapes the
+// code text into the same <pre class="shiki"> wrapper with no token coloring.
+const PLAINTEXT = 'text';
+
+// Sentinel foreground colors, one per ramp slot. Shiki has no class-emitting mode, so the theme
+// assigns each scope group a unique sentinel hex, then the transformer below maps the resolved
+// sentinel back to its cairn-tok-* class and deletes the style. The sentinels never reach the
+// output. They are arbitrary distinct values; only their uniqueness and exact round-trip matter.
+const SENTINEL_INK = '#000000';
+const SENTINEL_TO_CLASS: Record<string, string> = {
+  '#000010': 'cairn-tok-comment',
+  '#000020': 'cairn-tok-keyword',
+  '#000030': 'cairn-tok-string',
+  '#000040': 'cairn-tok-function',
+  '#000050': 'cairn-tok-number',
+  '#000060': 'cairn-tok-punct',
+};
+
+// The Shiki theme that drives the class mapping. Every scope group resolves to its sentinel color;
+// the transformer turns the sentinel into a class. The background and default foreground are
+// sentinels too, stripped from the <pre> by the transformer so the site theme owns the surround.
+const CAIRN_CODE_THEME: ThemeRegistrationRaw = {
+  name: 'cairn-roles',
+  type: 'light',
+  fg: SENTINEL_INK,
+  bg: '#ffffff',
+  settings: [
+    { settings: { foreground: SENTINEL_INK, background: '#ffffff' } },
+    {
+      scope: ['comment', 'punctuation.definition.comment', 'string.comment'],
+      settings: { foreground: '#000010' },
+    },
+    {
+      scope: [
+        'keyword',
+        'keyword.control',
+        'storage',
+        'storage.type',
+        'storage.modifier',
+        'variable.language',
+        'keyword.operator.new',
+        'keyword.operator.expression',
+      ],
+      settings: { foreground: '#000020' },
+    },
+    {
+      scope: ['string', 'string.quoted', 'string.template', 'constant.other.symbol'],
+      settings: { foreground: '#000030' },
+    },
+    {
+      scope: [
+        'entity.name.function',
+        'support.function',
+        'meta.function-call',
+        'entity.name.tag',
+        'support.type.property-name',
+      ],
+      settings: { foreground: '#000040' },
+    },
+    {
+      scope: [
+        'constant.numeric',
+        'constant.language',
+        'constant.character',
+        'constant.other',
+        'keyword.other.unit',
+      ],
+      settings: { foreground: '#000050' },
+    },
+    {
+      scope: ['punctuation', 'meta.brace', 'keyword.operator', 'meta.delimiter'],
+      settings: { foreground: '#000060' },
+    },
+  ],
+};
+
+// Read the `color:#rrggbb` hex out of a token span's inline style, lowercased for the sentinel map.
+function styleColor(style: unknown): string | undefined {
+  if (typeof style !== 'string') return undefined;
+  const match = /color:(#[0-9a-fA-F]{6})/.exec(style);
+  return match ? match[1].toLowerCase() : undefined;
+}
+
+// Append a class to a hast element's class list, building the string form Shiki uses.
+function addClass(node: Element, className: string): void {
+  const existing = node.properties?.class;
+  const prefix = typeof existing === 'string' && existing.length > 0 ? `${existing} ` : '';
+  (node.properties ??= {}).class = `${prefix}${className}`;
+}
+
+// The transformer that converts Shiki's sentinel-colored inline styles into the cairn-tok-* classes
+// and strips every style attribute, so the output is class-only. The <pre> loses its
+// background/foreground style (the site theme owns the surround); each token <span> trades its
+// sentinel color for the matching class, and a default-foreground span is left unclassed.
+const cairnTokenClasses: ShikiTransformer = {
+  name: 'cairn-token-classes',
+  pre(node) {
+    if (node.properties) delete node.properties.style;
+  },
+  code(node) {
+    if (node.properties) delete node.properties.style;
+  },
+  span(node) {
+    const hex = styleColor(node.properties?.style);
+    if (node.properties) delete node.properties.style;
+    const className = hex ? SENTINEL_TO_CLASS[hex] : undefined;
+    if (className) addClass(node, className);
+  },
+};
+
+// The cached highlighter. Created once on first use and reused for every render. The dynamic import
+// keeps Shiki off the static client graph; the promise is cached so the WASM grammar load and the
+// theme registration happen at most once per process.
+let highlighterPromise: Promise<Highlighter> | undefined;
+
+function getHighlighter(): Promise<Highlighter> {
+  if (!highlighterPromise) {
+    highlighterPromise = import('shiki').then((shiki) =>
+      shiki.createHighlighter({ themes: [CAIRN_CODE_THEME], langs: [...LANGS] }),
+    );
+  }
+  return highlighterPromise;
+}
+
+// Read the fenced language off a <code> element's class list. Markdown emits the language as a
+// `language-<id>` class on the inner <code>. An empty or missing language returns undefined, which
+// the caller maps to plaintext.
+function codeLanguage(code: Element): string | undefined {
+  const className = code.properties?.className;
+  const classes = Array.isArray(className) ? className.map(String) : [];
+  const langClass = classes.find((c) => c.startsWith('language-'));
+  const lang = langClass?.slice('language-'.length);
+  return lang && lang.length > 0 ? lang : undefined;
+}
+
+// A fenced-code <pre> is a <pre> whose single element child is a <code>. Inline code (a bare <code>
+// with no <pre> parent) and any other <pre> are left untouched.
+function fencedCode(pre: Element): Element | undefined {
+  const child = pre.children.find((c): c is Element => c.type === 'element');
+  return child?.tagName === 'code' ? child : undefined;
+}
+
+// One pending highlight: the original <pre> to replace, the inner <code> to read text from, and the
+// fenced language. The <pre> is rewritten in place (mutated to become Shiki's <pre>) after the async
+// tokenize, which keeps the parent-children typing uniform across Root and Element.
+interface Job {
+  pre: Element;
+  code: Element;
+  lang: string;
+}
+
+// Descend the tree and collect every fenced-code <pre>. The walk is synchronous and gathers the
+// targets up front, because the highlight itself is async (unist-util-visit cannot await).
+function collectFencedCode(node: Root | Element, jobs: Job[]): void {
+  for (const child of node.children) {
+    if (child.type !== 'element') continue;
+    if (child.tagName === 'pre') {
+      const code = fencedCode(child);
+      if (code) {
+        jobs.push({ pre: child, code, lang: codeLanguage(code) ?? PLAINTEXT });
+        continue;
+      }
+    }
+    collectFencedCode(child, jobs);
+  }
+}
+
+/**
+ * The Shiki rehype plugin. Highlights every fenced-code block into a `<pre class="shiki">` whose
+ * tokens carry the cairn-tok-* classes (no inline style), then leaves the rest of the tree
+ * untouched. It runs as an async transformer because Shiki tokenizes asynchronously. Because the
+ * output is class-only it needs no special placement; it is safe anywhere after `remarkRehype`.
+ * @returns A unified transformer that mutates the hast tree in place.
+ */
+export function rehypeCairnHighlight() {
+  return async (tree: Root): Promise<void> => {
+    const jobs: Job[] = [];
+    collectFencedCode(tree, jobs);
+    if (jobs.length === 0) return;
+
+    const highlighter = await getHighlighter();
+    const loaded = new Set(highlighter.getLoadedLanguages());
+
+    for (const job of jobs) {
+      // Fall back to plaintext for any language outside the preloaded set so Shiki never throws on
+      // an unknown fence. Plaintext still produces the <pre class="shiki"> wrapper with escaped text.
+      const lang = loaded.has(job.lang) ? job.lang : PLAINTEXT;
+      const result = highlighter.codeToHast(toString(job.code), {
+        lang,
+        theme: 'cairn-roles',
+        transformers: [cairnTokenClasses],
+      });
+      const pre = result.children.find(
+        (c): c is Element => c.type === 'element' && c.tagName === 'pre',
+      );
+      if (!pre) continue;
+      // Rewrite the original <pre> into Shiki's <pre> in place: adopt its tag, properties, and
+      // children. Mutating the existing node avoids reindexing the parent's children array.
+      job.pre.tagName = pre.tagName;
+      job.pre.properties = pre.properties;
+      job.pre.children = pre.children;
+    }
+  };
+}

package/src/lib/render/pipeline.ts

@@ -9,7 +9,8 @@ import rehypeStringify from 'rehype-stringify';
 import rehypeSanitize from 'rehype-sanitize';
 import type { Schema } from 'hast-util-sanitize';
 import { VFile } from 'vfile';
-import { buildSanitizeSchema, rehypeAnchorRel, rehypeSinkGuard } from './sanitize-schema.js';
+import { buildSanitizeSchema, rehypeAnchorRel, rehypeSinkGuard, rehypeTaskListA11y } from './sanitize-schema.js';
+import { rehypeCairnHighlight } from './highlight.js';
 import { remarkDirectiveStamp } from './remark-directives.js';
 import { remarkFigure } from './remark-figure.js';
 import { remarkResolveCairnLinks, CAIRN_RESOLVE } from './resolve-links.js';
@@ -74,6 +75,16 @@ export function createRenderer(
     ...floor,
     [rehypeDispatch, registry, options.stagger],
     rehypeSlug,
+    // Name each GFM task-list checkbox from its item text. It runs after the sanitize floor (which
+    // does not allow aria-label) so the added attribute survives, and is content-not-sink, so it is
+    // not gated by unsafeDisableSanitize.
+    rehypeTaskListA11y,
+    // Build-time syntax highlighting. It emits class-only output (the cairn-tok-* ramp, no inline
+    // style), so it is class-driven like the rest of the pipeline and needs no special placement
+    // relative to the sanitize floor or the sink guard: the token classes survive the floor because
+    // `className` is already allowed on `*`. It runs unconditionally (a code fence is content, not a
+    // sink) and ships no client highlighter (Shiki is build-only behind a dynamic import).
+    rehypeCairnHighlight,
   ];
   if (rel !== false) rehypePlugins.push([rehypeAnchorRel, rel]);
   // The sink guard runs last, over the fully-built tree, so it neutralizes a sink a component

package/src/lib/render/registry.ts

@@ -86,7 +86,12 @@ export interface ComponentDef {
    *  result, so a build fn stays free of any motion concern.
    */
   build: (ctx: ComponentContext) => Element;
-  /** Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. */
+  /**
+   * Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. Maps a free-string role to a
+   *  glyph key in the site IconSet; choose a logically representative glyph and prefer glyphs
+   *  distinct across roles so the picker stays scannable. Overrides the engine
+   *  {@link DEFAULT_ICON_BY_ROLE} fallback for the roles it names.
+   */
   defaultIconByRole?: Record<string, string>;
   /** One line on when to reach for this component; feeds the picker and the reference file. */
   use?: string;
@@ -94,7 +99,10 @@ export interface ComponentDef {
   attributes?: AttributeField[];
   /** The named content regions this component accepts. */
   slots?: SlotDef[];
-  /** A glyph key from the site IconSet, shown beside the label in the picker. */
+  /**
+   * A glyph key from the site IconSet, shown beside the label in the picker. Choose a logically
+   *  representative glyph and prefer glyphs distinct across components so the picker stays scannable.
+   */
   icon?: string;
   /** A category heading for the picker. Components order by declaration within a group. */
   group?: string;
@@ -137,6 +145,20 @@ function findIconField(def: ComponentDef): AttributeField | undefined {
   return def.attributes?.find((field) => field.type === 'icon');
 }
 
+/**
+ * The engine's role-to-glyph-key fallback for the conventional admonition roles, which a site's
+ *  IconSet may satisfy. A component's own {@link ComponentDef.defaultIconByRole} overrides it.
+ */
+const DEFAULT_ICON_BY_ROLE: Record<string, string> = {
+  note: 'info',
+  tip: 'lightbulb',
+  important: 'star',
+  warning: 'warning',
+  caution: 'alert-triangle',
+  info: 'info',
+  danger: 'flame',
+};
+
 /**
  * Build a registry from a site's component definitions. The single source the render
  * pipeline (directive stamp plus rehype dispatch) and the editor palette both read.
@@ -159,7 +181,12 @@ export function defineRegistry({ components }: { components: ComponentDef[] }):
     defs: components,
     names: components.map((c) => c.name),
     get: (name) => byName.get(name),
-    defaultIcon: (name, role) => (role ? byName.get(name)?.defaultIconByRole?.[role] : undefined),
+    defaultIcon: (name, role) => {
+      if (!role) return undefined;
+      const def = byName.get(name);
+      if (!def || !findIconField(def)) return undefined;
+      return def.defaultIconByRole?.[role] ?? DEFAULT_ICON_BY_ROLE[role];
+    },
     iconField: (name) => {
       const def = byName.get(name);
       return def ? findIconField(def) : undefined;

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

@@ -2,9 +2,7 @@ import type { Root, Element, ElementContent } from 'hast';
 import { h } from 'hastscript';
 import { dataAttrProp, type ComponentContext, type ComponentDef, type ComponentRegistry } from './registry.js';
 
-/**
- *
- */
+/** Narrow a hast node to an Element, false for a text node, a comment, or undefined. */
 export function isElement(node: ElementContent | undefined): node is Element {
   return !!node && node.type === 'element';
 }
@@ -21,9 +19,7 @@ export function strAttr(ctx: ComponentContext, key: string): string | undefined
 // hast Properties values are PropertyValue (string | number | boolean | array | null).
 // 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.
-/**
- *
- */
+/** Read a hast element property as a string, or undefined when it is absent or non-string. */
 export function strProp(node: Element, name: string): string | undefined {
   const value = node.properties?.[name];
   return typeof value === 'string' ? value : undefined;

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

@@ -1,6 +1,7 @@
 import { defaultSchema, type Schema } from 'hast-util-sanitize';
 import type { Root, Element } from 'hast';
 import { visit } from 'unist-util-visit';
+import { toString } from 'hast-util-to-string';
 import { dataAttrProp, type ComponentRegistry } from './registry.js';
 
 // The fixed directive markers the stamp writes and the dispatch reads. They are inert data
@@ -68,6 +69,36 @@ export function rehypeAnchorRel(rel: string) {
   };
 }
 
+/**
+ * Give every GFM task-list checkbox an accessible name from its item text. remark-gfm emits a real
+ * `<input type="checkbox" disabled>` with no label, which axe's `label` rule flags as a critical
+ * violation even though the control is read-only; the visible label is the surrounding `<li>` text,
+ * not associated programmatically. This sets `aria-label` on each task-list checkbox to its item's
+ * text so the name travels with the control, keeping the engine's real disabled input (the bar's
+ * non-color cue) while clearing the violation on every site. It must run after the sanitize floor,
+ * which does not allow `aria-label`, so the attribute is added once the floor has run.
+ */
+export function rehypeTaskListA11y() {
+  return (tree: Root) => {
+    visit(tree, 'element', (node: Element) => {
+      const className = node.properties?.className;
+      const isTaskItem =
+        node.tagName === 'li' && Array.isArray(className) && className.includes('task-list-item');
+      if (!isTaskItem) return;
+      const checkbox = node.children.find(
+        (child): child is Element =>
+          child.type === 'element' &&
+          child.tagName === 'input' &&
+          child.properties?.type === 'checkbox',
+      );
+      if (!checkbox) return;
+      const label = toString(node).trim();
+      // Only when there is text to name it; an empty item leaves the box unnamed rather than blank.
+      if (label) (checkbox.properties ??= {})['ariaLabel'] = label;
+    });
+  };
+}
+
 // URL-bearing hast properties the post-dispatch guard scheme-checks. hast camelCases attribute
 // names through property-information (srcset -> srcSet, xlink:href -> xLinkHref with a capital L,
 // formaction -> formAction). data is the <object data> URL attribute; data-* attributes camelCase

package/src/lib/sveltekit/guard.ts

@@ -41,6 +41,21 @@ export function createAuthGuard() {
   return async function handle({ event, resolve }: HandleInput): Promise<Response> {
     const { pathname } = event.url;
 
+    // Fail closed if the dev-backend flag is set in a deployed runtime. Read both env sources: a
+    // Cloudflare Worker var lands on platform.env, an adapter-node OS var on process.env. A correct
+    // production build already eliminated the dev backend (the consumer gates it on the build-foldable
+    // `dev`), so a set flag signals a polluted environment; refuse loudly.
+    const platformFlag = event.platform?.env?.CAIRN_DEV_BACKEND;
+    const processFlag =
+      typeof process !== 'undefined' ? process.env?.CAIRN_DEV_BACKEND : undefined;
+    if (platformFlag === '1' || platformFlag === true || processFlag === '1') {
+      log.error('guard.rejected', { reason: 'dev_backend_in_prod', path: pathname });
+      return new Response(
+        'cairn: the dev backend flag is set in a deployed environment. Unset CAIRN_DEV_BACKEND.',
+        { status: 503 },
+      );
+    }
+
     // Rule 2 - non-admin: restore the framework's strict Origin check the consumer disabled when
     // they set checkOrigin: false to hand cairn the admin CSRF authority.
     if (!isAdminPath(pathname)) {