@apisurf/canonui 0.1.1

package/theme/lib/markdown.ts

@@ -0,0 +1,115 @@
+/**
+ * Markdown, at build time.
+ *
+ * `marked` rather than Astro's own pipeline: that one renders `.md` files it
+ * finds on disk, and every block here is a string that arrived from a database.
+ * Rendering happens during the build, so nothing ships to the browser.
+ *
+ * The output is not sanitized. A block's HTML is written by whoever owns the
+ * database — the same person running the build — and stripping their markup
+ * would break the `html` block type, which exists precisely to pass markup
+ * through. Do not point a build at a database you did not write.
+ */
+import { Marked } from "marked";
+import type { SnapshotBlock } from "@canon/db";
+
+/** One entry in a page's outline: a heading, and the anchor that reaches it. */
+export interface Heading {
+  id: string;
+  text: string;
+  depth: 2 | 3;
+}
+
+/** A rendered block: its markup, and the headings a table of contents can link. */
+export interface RenderedBlock {
+  html: string;
+  headings: Heading[];
+}
+
+/**
+ * Where the renderer files headings while a parse is running.
+ *
+ * `marked.parse` is called synchronously and one block at a time, so a single
+ * slot cannot be written by two parses at once. It is the alternative to
+ * lexing every block twice — once for the outline and once for the markup —
+ * and to the two passes drifting apart on the ids they produce.
+ */
+let sink: Heading[] | null = null;
+let slugs: Map<string, number> | null = null;
+let prefix = "";
+
+const marked = new Marked({ gfm: true, breaks: false });
+
+marked.use({
+  renderer: {
+    /**
+     * Headings carry an id so a section can be linked, and are recorded on the
+     * way past so the page can draw its own contents.
+     */
+    heading(token) {
+      const text = this.parser.parseInline(token.tokens);
+      const id = slug(stripTags(text));
+      if (sink && (token.depth === 2 || token.depth === 3)) {
+        sink.push({ id, text: stripTags(text), depth: token.depth });
+      }
+      return `<h${token.depth} id="${id}"><a class="anchor" href="#${id}">${text}</a></h${token.depth}>\n`;
+    },
+  },
+});
+
+/**
+ * Render one block's markdown, and collect the headings inside it.
+ *
+ * Memoized on the block's uid because the page asks twice: once to build the
+ * table of contents, before anything is drawn, and once to draw the block
+ * itself. The second call is the same block with the same content.
+ */
+const cache = new Map<string, RenderedBlock>();
+
+export function renderBlock(block: SnapshotBlock): RenderedBlock {
+  const hit = cache.get(block.uid);
+  if (hit) return hit;
+
+  sink = [];
+  slugs = new Map();
+  prefix = `b${block.seq}`;
+  const html = marked.parse(block.content, { async: false });
+  const rendered: RenderedBlock = { html, headings: sink };
+  sink = null;
+  slugs = null;
+
+  cache.set(block.uid, rendered);
+  return rendered;
+}
+
+/**
+ * A block's headings, without drawing it.
+ *
+ * Only markdown contributes: an `html` block's headings would need a parser to
+ * find, and the other three types have none to find.
+ */
+export function headingsOf(block: SnapshotBlock): Heading[] {
+  return block.type === "markdown" ? renderBlock(block).headings : [];
+}
+
+/**
+ * `b2-when-a-retry-fires` — stable across builds, unique within the document.
+ *
+ * The block prefix is what keeps two blocks that both open with "Overview"
+ * from claiming the same anchor.
+ */
+function slug(text: string): string {
+  const base = text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "");
+  const stem = `${prefix}-${base || "section"}`;
+  const seen = slugs?.get(stem) ?? 0;
+  slugs?.set(stem, seen + 1);
+  return seen === 0 ? stem : `${stem}-${seen + 1}`;
+}
+
+/** Heading text for the contents list, which takes text and not markup. */
+function stripTags(html: string): string {
+  return html.replace(/<[^>]*>/g, "");
+}

package/theme/lib/outline.ts

@@ -0,0 +1,48 @@
+/**
+ * A document's outline: what a reader can jump to.
+ *
+ * Two things make a section in a document, and the outline has to show both.
+ * A block with a title is a section boundary the author drew explicitly; a
+ * markdown heading inside a block is one they drew in prose. Listing only the
+ * second would lose the structure the block model exists to express, and
+ * listing only the first would stop at four entries on a page with forty
+ * headings.
+ */
+import type { SnapshotBlock } from "@canon/db";
+import { headingsOf } from "./markdown";
+
+export interface OutlineEntry {
+  id: string;
+  text: string;
+  /** 1 for a section, 2 for something inside it. Nesting, not heading level. */
+  depth: 1 | 2;
+}
+
+/**
+ * Build it.
+ *
+ * A titled block owns the headings under it, so they indent; an untitled
+ * block's own h2s are the sections. Either way the reader sees one list whose
+ * indentation matches what the document looks like.
+ */
+export function outline(blocks: SnapshotBlock[]): OutlineEntry[] {
+  const entries: OutlineEntry[] = [];
+
+  for (const block of blocks) {
+    const headings = headingsOf(block);
+
+    if (block.title) {
+      entries.push({ id: `b${block.seq}`, text: block.title, depth: 1 });
+      for (const heading of headings) {
+        entries.push({ id: heading.id, text: heading.text, depth: 2 });
+      }
+      continue;
+    }
+
+    for (const heading of headings) {
+      entries.push({ id: heading.id, text: heading.text, depth: heading.depth === 2 ? 1 : 2 });
+    }
+  }
+
+  return entries;
+}

package/theme/lib/snapshot.ts

@@ -0,0 +1,49 @@
+/**
+ * The snapshot this build renders.
+ *
+ * Read once, at module load, from the path in $CANON_SITE_DATA. The theme never
+ * opens the database — it is handed a plain JSON document, which is what keeps
+ * SQLite out of this package and Astro out of the CLI's dependency tree.
+ *
+ * The shape is `DocumentSnapshot` from @canon/db, brought in as a type-only
+ * import. It disappears from the output, which is what lets the same JSON be
+ * rendered by something that is not this theme at all.
+ */
+import { readFileSync } from "node:fs";
+import type { DocumentSnapshot, SnapshotBlock } from "@canon/db";
+
+/** The snapshot shape this theme renders. The CLI and the theme ship as a pair. */
+const SNAPSHOT_VERSION = 7;
+
+function load(): DocumentSnapshot {
+  const path = process.env.CANON_SITE_DATA;
+  if (!path) {
+    throw new Error(
+      "canonui: CANON_SITE_DATA is not set. The theme renders a snapshot, and `canonui build` is what writes one.",
+    );
+  }
+
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as DocumentSnapshot;
+  if (parsed.version !== SNAPSHOT_VERSION) {
+    throw new Error(
+      `canonui: snapshot version ${parsed.version} is not one this theme understands ` +
+        `(${SNAPSHOT_VERSION}). Upgrade @apisurf/canonui, or canon, so the two match.`,
+    );
+  }
+  return parsed;
+}
+
+export const snapshot: DocumentSnapshot = load();
+export const document = snapshot.document;
+/** In the order `canon mv block` put them. */
+export const blocks: SnapshotBlock[] = snapshot.blocks;
+
+/** `2026-08-25` — the same date on every machine that builds this site. */
+export function isoDate(epochMs: number): string {
+  return new Date(epochMs).toISOString().slice(0, 10);
+}
+
+/** Href for the document's markdown twin, honouring the configured base path. */
+export function mdHref(base: string): string {
+  return `${base.endsWith("/") ? base : `${base}/`}index.md`;
+}

package/theme/pages/404.astro

@@ -0,0 +1,12 @@
+---
+import Site from "../layouts/Site.astro";
+import { document } from "../lib/snapshot";
+
+const base = import.meta.env.BASE_URL;
+---
+
+<Site title={`Not found · ${document.title}`}>
+  <h1>Not found</h1>
+  <p>There is nothing at this address.</p>
+  <p><a href={base}>Back to {document.title}</a></p>
+</Site>

package/theme/pages/index.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * The document, at the root of the site.
+ *
+ * One document builds into one page: its title, its description, then every
+ * block in order, with the contents rail beside it.
+ */
+import Site from "../layouts/Site.astro";
+import Blocks from "../components/Blocks.astro";
+import Copy from "../components/Copy.astro";
+import Toc from "../components/Toc.astro";
+import { outline } from "../lib/outline";
+import { blocks, document, mdHref } from "../lib/snapshot";
+
+const base = import.meta.env.BASE_URL;
+---
+
+<Site title={document.title} description={document.description}>
+  <Toc slot="aside" entries={outline(blocks)} />
+
+  <article>
+    <header class="page-header">
+      <h1>{document.title}</h1>
+      {document.description && <p class="lede">{document.description}</p>}
+      <p class="page-actions">
+        <Copy href={mdHref(base)} what="document" />
+      </p>
+    </header>
+
+    <Blocks blocks={blocks} />
+  </article>
+</Site>