@erclx/canon 4.76.0 → 4.77.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.76.0",
+  "version": "4.77.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/draft-and-pick/SKILL.md

@@ -16,7 +16,7 @@ Some decisions are settled by looking rather than by reasoning, and no draft is
 ## Step 1: name the decision and the arms
 
 1. State the decision in one sentence, naming what changes between arms and what stays fixed.
-2. Derive a kebab slug from that sentence. Call the folder every file this run writes to `<dest>` below. `<dest>` is `.canon/tmp/<slug>/`, per `.claude/rules/canon/core/055-scratch.md`. Running inside a live `plan-groundwork` track is the one exception: `<dest>` is the track's own `evidence/<slug>/` instead, since a candidate render is evidence the track's decision file cites rather than spike input.
+2. Derive a kebab slug from that sentence. Call the folder every file this run writes to `<dest>` below. `<dest>` is `.canon/tmp/<slug>/`, a nested `<slug>/` folder rather than a flat `<slug>-<file>.md`, which is the shape every temporary write in this project takes. Running inside a live `plan-groundwork` track is the one exception: `<dest>` is the track's own `evidence/<slug>/` instead, since a candidate render is evidence the track's decision file cites rather than spike input.
 3. Write one arm per candidate, each carrying an id, a label, and what the arm costs. An arm with no stated cost is not an option.
 4. Make the current state arm `0`, so the baseline is a candidate rather than an absence. A decision with nothing shipped yet says so and starts at arm `1`.
 5. Stop at three to five arms. Two is a comparison the operator can hold in prose, and past five the pick stops being a look and becomes a sort.
@@ -48,7 +48,7 @@ canon capture <dest>/candidates.html --selector <element>
 
 ## Step 4: take the pick
 
-Put the choice to the operator through the structured question surface, per `.claude/rules/canon/core/005-behavior.md`.
+Put the choice to the operator through the structured question surface, since a call the operator's preference decides always routes through it rather than through prose.
 
 - One option per arm, labeled with the arm's id and carrying its cost as the description.
 - Rank the recommendation first and mark it `(Recommended)`.
@@ -68,7 +68,7 @@ Put the choice to the operator through the structured question surface, per `.cl
 1. Apply the winning arm to the real surface, in one change.
 2. Close out whatever document stated the decision as open, in the same change, naming the arm that won and the ones that stayed defensible. A pick that changes a surface and records nothing about why leaves the next reader to re-derive it from a diff. Skip this where nothing stated the decision.
 3. Batch-capture the final round's arm files, when `<dest>` is the scratch path: `canon capture <dest>/arms --selector <wrapper-class> --out <archive-dir>`, naming Step 2's chosen class. This is the directory-batch convention `draft-identity` Step 6 already uses.
-4. Resolve `<archive-dir>` as `.canon/review/evidence/<slug>/` against the main worktree root, per `.claude/rules/canon/core/085-worktrees.md`, never against a linked worktree this run happens to be building in. The capture is what keeps every arm past the pick, the losing ones included, as a durable revert record distinct from the live comparison page.
+4. Resolve `<archive-dir>` as `.canon/review/evidence/<slug>/` against the main worktree root, since shared session scratch resolves there rather than against a linked worktree this run happens to be building in. The capture is what keeps every arm past the pick, the losing ones included, as a durable revert record distinct from the live comparison page.
 5. Delete `<dest>` and every file inside it, when `<dest>` is the scratch path, now that every arm sits at the durable path above. A variant left behind there is a second design nobody maintains.
 6. Leave `<dest>` in place when it is a live track's `evidence/<slug>/`: `plan-groundwork`'s write scope treats evidence as durable rather than as scratch a session may delete, and the arms already sit at a durable path there.
 7. Report `<dest>` as still standing when the scratch-path delete is refused, naming the path for the operator to remove, rather than closing on a report the tree contradicts. The pick is applied either way, so the run has done its work and the folder is what outlives it.

package/docs/agents/commands.md

@@ -24,7 +24,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon docs [topic]`             | Emit toolkit reference docs (`list`, or a topic by name)                                                                                                                                                                                                                                                               |
 | `canon design render`            | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                                                                                                                                                                                                      |
 | `canon design regen`             | Rewrite this repository's `.claude/DESIGN.md` and `src/design/base.css` from `src/design/tokens.ts`                                                                                                                                                                                                                    |
-| `canon design board`             | Generate a static page set indexing tokens, surfaces, wireframes, and past candidates, against the toolkit checkout like `regen` (`--out`)                                                                                                                                                                             |
+| `canon design board`             | Generate a static page set indexing tokens, surfaces, wireframes, past candidates, and components, against the toolkit checkout like `regen` (`--out`)                                                                                                                                                                 |
 | `canon design css`               | Emit the design tokens and components as CSS on stdout (`--no-components` for properties alone)                                                                                                                                                                                                                        |
 | `canon design install`           | Install the base stylesheet into a project at `.claude/design/base.css`                                                                                                                                                                                                                                                |
 | `canon design sync`              | Update a base stylesheet already installed under `.claude/design/`                                                                                                                                                                                                                                                     |

package/docs/agents/design-board.md

@@ -5,7 +5,7 @@ description: Generating a static index over the toolkit checkout's own design su
 
 # Design board
 
-`canon design board [--out <path>]` generates a static page set indexing four design surfaces and reports the path a reader opens with `canon serve`. Like `canon design regen`, it runs against the toolkit checkout the CLI resolves its own root from, never against a target project's own files: a target holds none of the sources below, since none of `.claude/DESIGN.md`, `.claude/wireframes/`, `web/`, or the gitignored `.canon/` records ship with the published package. Running the installed CLI from inside a checkout of this project prints a mismatch warning when the caller's working directory disagrees with the root it resolved.
+`canon design board [--out <path>]` generates a static page set indexing five design surfaces and reports the path a reader opens with `canon serve`. Like `canon design regen`, it runs against the toolkit checkout the CLI resolves its own root from, never against a target project's own files: a target holds none of the sources below, since none of `.claude/DESIGN.md`, `.claude/wireframes/`, `web/`, or the gitignored `.canon/` records ship with the published package. Running the installed CLI from inside a checkout of this project prints a mismatch warning when the caller's working directory disagrees with the root it resolved.
 
 Each panel reads what is already on disk and reports its own missing source rather than failing the run, so an absent build or an empty corpus renders an empty-state message instead of a broken frame.
 
@@ -24,6 +24,7 @@ canon serve .canon/review/board
 - **Surfaces** iframes the built landing page from `web/dist/` and a teach workspace from `.canon/teach/`, copying each whole into the board's own tree. Either reports its own missing build or absent workspace rather than rendering a broken frame.
 - **Wireframes** renders each of the six files under `.claude/wireframes/` as-is inside a `<pre>`, beside a line naming the surface it describes.
 - **Past candidates** lists an arm capture image per folder under `.canon/review/evidence/`, and states the corpus carries none rather than rendering an empty grid.
+- **Components** iframes the gallery built by `bun run web:gallery`, a second Astro config at `web/gallery.config.mjs` reading `web/gallery-src/` and writing `web/gallery-dist/`. That config's `srcDir` is never read by `web:build`'s own config, so the gallery never reaches the published `web/dist/`. The gallery page renders every component under `web/src/components/` except two whose props carry no defaults, which it names rather than filling with invented data. Reports a missing gallery build rather than rendering a broken frame.
 
 ## What it does not do
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.76.0",
+  "version": "4.77.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {
@@ -46,6 +46,7 @@
     "web:favicon": "bun scripts/core/regen-web-favicon.ts",
     "web:previews": "bun scripts/core/regen-web-previews.ts",
     "web:build": "bun run web:tokens && bun run web:favicon && bun run web:previews && cd web && astro check && astro build",
+    "web:gallery": "cd web && astro build --config gallery.config.mjs",
     "web:preview": "cd web && astro preview",
     "web:e2e": "cd web && playwright test"
   },

package/scripts/core/check-gallery-exclusion.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+WEB_DIST="$PROJECT_ROOT/web/dist"
+GALLERY_DIST="$PROJECT_ROOT/web/gallery-dist"
+MARKER='name="canon-gallery-marker"'
+
+# Nothing to grep without a build. Callers run this after `bun run web:build`
+# and `bun run web:gallery`, so an absent dist here means a build step itself
+# failed rather than something this check can verify.
+if [ ! -d "$WEB_DIST" ]; then
+  echo "No $WEB_DIST. Run bun run web:build first." >&2
+  exit 1
+fi
+
+if [ ! -d "$GALLERY_DIST" ]; then
+  echo "No $GALLERY_DIST. Run bun run web:gallery first." >&2
+  exit 1
+fi
+
+# A prose notice is not load-bearing: rewording it silently retires the leak
+# check it backed with every workflow still green. The marker is a fixed
+# `<meta>` tag `web/gallery-src/pages/index.astro` carries for exactly this,
+# so asserting it survives in the gallery's own build is what turns a dropped
+# marker into a loud failure here rather than a blind spot in the check below.
+if ! grep -rl "$MARKER" "$GALLERY_DIST" >/dev/null 2>&1; then
+  echo "The gallery build at $GALLERY_DIST carries no $MARKER. The gallery page dropped its own marker, which is what the leak check below reads for." >&2
+  exit 1
+fi
+
+# `web/gallery.config.mjs` keeps the components-panel gallery out of the
+# published build by never pointing its srcDir at it. A later config change
+# that widens srcDir, or a gallery file moving under web/src/, would publish
+# this repository's component internals to a live domain with every other
+# check still green, which is what this guards against.
+if find "$WEB_DIST" -iname '*gallery*' | grep -q .; then
+  echo "A file named for the gallery reached $WEB_DIST. See web/gallery.config.mjs's srcDir." >&2
+  exit 1
+fi
+
+if grep -rl "$MARKER" "$WEB_DIST" >/dev/null 2>&1; then
+  echo "The gallery's own marker ($MARKER) reached $WEB_DIST. See web/gallery.config.mjs's srcDir." >&2
+  exit 1
+fi
+
+echo "check-gallery-exclusion: gallery marker present in $GALLERY_DIST, absent from $WEB_DIST"

package/src/design/board.ts

@@ -25,6 +25,15 @@ export const WIREFRAME_DIR = join('.claude', 'wireframes')
 const WEB_DIST = join('web', 'dist')
 const WEB_DIST_ENTRY = 'index.html'
 
+/**
+ * The gallery build, generated by `bun run web:gallery` through
+ * `web/gallery.config.mjs`. That config's own `srcDir` is `web/gallery-src`,
+ * which `web:build`'s config never reads, so this output never reaches
+ * `web/dist`.
+ */
+const WEB_GALLERY_DIST = join('web', 'gallery-dist')
+const WEB_GALLERY_DIST_ENTRY = 'index.html'
+
 interface WireframeEntry {
   readonly path: string
   readonly describes: string
@@ -338,6 +347,19 @@ function writeSurfacesPanel(root: string, outDir: string): void {
   )
 }
 
+function writeComponentsPanel(root: string, outDir: string): void {
+  const dir = join(outDir, 'components')
+  mkdirSync(dir, { recursive: true })
+
+  const gallerySource = join(root, WEB_GALLERY_DIST)
+  const body = existsSync(join(gallerySource, WEB_GALLERY_DIST_ENTRY))
+    ? (copyBuilt(gallerySource, join(dir, 'gallery')),
+      '<iframe src="gallery/index.html" loading="lazy"></iframe>')
+    : `<p class="empty">No ${WEB_GALLERY_DIST}/ build. Run bun run web:gallery, then regenerate the board.</p>`
+
+  writeFileSync(join(dir, 'index.html'), panelPage('Components', body))
+}
+
 function isImage(name: string): boolean {
   return IMAGE_EXTENSIONS.some((ext) => name.toLowerCase().endsWith(ext))
 }
@@ -437,12 +459,14 @@ export function generateBoard(
       title: 'Past candidates',
       path: 'candidates/index.html',
     },
+    { id: 'components', title: 'Components', path: 'components/index.html' },
   ]
 
   writeTokensPanel(root, outDir)
   writeSurfacesPanel(root, outDir)
   writeWireframesPanel(root, outDir)
   writeCandidatesPanel(root, outDir)
+  writeComponentsPanel(root, outDir)
 
   const indexPath = join(outDir, 'index.html')
   writeFileSync(indexPath, shellHtml(panels))

package/src/gate/measures.ts

@@ -523,6 +523,8 @@ function describeShippedReference(reference: ShippedReference): string {
       return 'a bare standards/ path that has nothing to expand it in an installed plugin cache'
     case 'phase-label':
       return 'a phase label that names a board no target holds'
+    case 'rule-path':
+      return 'a numbered rule path that reaches a target only through a separate canon gov sync, and only where governance was installed at all'
   }
 }
 
@@ -579,8 +581,8 @@ export const shippedReferences: Measure = async (ctx) => {
     ),
     failure:
       found.length === 1
-        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
-        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
+        ? `One reference in the shipped corpora resolves wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark the line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`
+        : `${found.length} references in the shipped corpora resolve wrong for a reader in a target. Qualify a cross-repository citation as owner/repo#123 or owner/repo@abc1234, cite a docs page through canon docs <name>, rewrite a bare standards/ path under claude/skills/ as \${CLAUDE_SKILL_DIR}/../../standards/<name>.md, state a same-repository citation or a phase label as a fact instead and relocate the evidence to the owning .claude/context/ entry, state the fact a shipped skill body's cited rule enforces instead of its path, or mark each line ${REFERENCE_MARKER}: <reason> where the bare form is the point.`,
   }
 }
 

package/src/shipped/references.ts

@@ -203,6 +203,22 @@ const STANDARDS_PATH = /(?<![\w./-])standards\/[^\s`)\]]*\.md\b/g
  */
 const PHASE_LABEL = /\bv\d+\.\d+(?!\.\d)\b/g
 
+/**
+ * A `.claude/rules/<segments>/<nnn>-<slug>.md` citation from a body under
+ * `claude/skills/`, the installed-path spelling `598-authoring-layout.md`
+ * bans a shipped skill body from citing as authority for its own behavior.
+ *
+ * Anchored on the trailing `\d{3}-[\w-]+\.md` rather than on the bare
+ * `.claude/rules/` prefix, which is what keeps a folder mention carrying no
+ * number, such as `create-rule`, `memory-review`, and `setup-gov` already
+ * write correctly, from matching. The segment group between `rules/` and the
+ * numbered file admits both a governance-namespace path
+ * (`canon/core/055-scratch.md`) and a project-namespace one
+ * (`project/<subdir>/<n>-<slug>.md`) without distinguishing them, since
+ * either shape is the same broken citation.
+ */
+const RULE_PATH = /(?<![\w./-])\.claude\/rules\/[^\s`)\]]*\/\d{3}-[\w-]+\.md\b/g
+
 export interface ShippedReference {
   readonly file: string
   /** One-based, matching the `file:line` form a reader clicks. */
@@ -213,6 +229,7 @@ export interface ShippedReference {
     | 'docs-path'
     | 'standards-path'
     | 'phase-label'
+    | 'rule-path'
   /** The reference as written, so a report names the token to qualify. */
   readonly text: string
   /**
@@ -259,14 +276,19 @@ function isDocsPathReportable(
 }
 
 /**
- * Whether `file` sits in the one corpus `STANDARDS_PATH` gates.
+ * Whether `file` sits in the one corpus `STANDARDS_PATH` and `RULE_PATH`
+ * both gate: a shipped skill body, minus its own `REQUIREMENT.md`.
  *
- * `REQUIREMENT.md` is excluded for the reason `598-authoring-layout.md`
- * leaves it alone: a maintainer or an audit command reads that file rather
- * than a session loading it, so the resolver rule this pattern enforces
- * never applies there.
+ * Both patterns share this scope because both bans live in
+ * `598-authoring-layout.md`, stated for the same reader: a session loading
+ * the `SKILL.md` body a target actually receives. `REQUIREMENT.md` is
+ * excluded for the reason that file states there, since a maintainer or an
+ * audit command reads it rather than a session loading it, so neither
+ * resolver rule this pair enforces ever applies to it. One predicate serves
+ * both call sites rather than two copies drifting apart with nothing
+ * comparing them.
  */
-function isStandardsPathScope(file: string): boolean {
+function isSkillBodyScope(file: string): boolean {
   return file.startsWith('claude/skills/') && !file.endsWith('/REQUIREMENT.md')
 }
 
@@ -357,7 +379,7 @@ export function referencesIn(
       })
     }
 
-    if (isStandardsPathScope(file)) {
+    if (isSkillBodyScope(file)) {
       for (const match of line.matchAll(STANDARDS_PATH)) {
         if (!isStandardsPathReportable(match[0])) continue
         references.push({
@@ -377,6 +399,18 @@ export function referencesIn(
         text: match[0],
       })
     }
+
+    if (isSkillBodyScope(file)) {
+      for (const match of line.matchAll(RULE_PATH)) {
+        if (isPlaceholderPath(match[0])) continue
+        references.push({
+          file,
+          line: index + 1,
+          kind: 'rule-path',
+          text: match[0],
+        })
+      }
+    }
   }
 
   return references

package/src/teach/components/heading.tsx

@@ -0,0 +1,11 @@
+/** @jsxImportSource ../html */
+import type { Child, Element } from '@/teach/html/jsx-runtime'
+
+export interface HeadingProps {
+  readonly level: 1 | 2
+  readonly children: Child
+}
+
+export function Heading({ level, children }: HeadingProps): Element {
+  return level === 1 ? <h1>{children}</h1> : <h2>{children}</h2>
+}

package/src/teach/components/list.tsx

@@ -0,0 +1,17 @@
+/** @jsxImportSource ../html */
+import type { Child, Element } from '@/teach/html/jsx-runtime'
+
+export interface ListProps {
+  readonly ordered?: boolean
+  readonly items: readonly Child[]
+}
+
+/**
+ * Composes an item per entry rather than taking pre-built `<li>` children, so
+ * every list in a lesson escapes the same way regardless of what the caller
+ * hands in.
+ */
+export function List({ ordered, items }: ListProps): Element {
+  const rendered = items.map((item) => <li>{item}</li>)
+  return ordered ? <ol>{rendered}</ol> : <ul>{rendered}</ul>
+}

package/src/teach/components/paragraph.tsx

@@ -0,0 +1,12 @@
+/** @jsxImportSource ../html */
+import type { Child, Element } from '@/teach/html/jsx-runtime'
+
+export interface ParagraphProps {
+  /** The lesson's dek, read back by `extractLessonMeta` in `@/teach/nav`. */
+  readonly lede?: boolean
+  readonly children: Child
+}
+
+export function Paragraph({ lede, children }: ParagraphProps): Element {
+  return lede ? <p class="lede">{children}</p> : <p>{children}</p>
+}

package/src/teach/html/jsx-dev-runtime.ts

@@ -0,0 +1,13 @@
+/**
+ * Bun resolves this module rather than `jsx-runtime` at run time (spike 1,
+ * `.canon/groundwork/56-teach-render-layer/08-spikes.md`), so every export a
+ * caller might reach through either entry point has to exist here too.
+ */
+export {
+  Fragment,
+  jsx,
+  jsx as jsxDEV,
+  jsxs,
+  render,
+  type JSX,
+} from './jsx-runtime'

package/src/teach/html/jsx-runtime.ts

@@ -0,0 +1,113 @@
+import { escape, isRaw, raw, type RawMarkup } from './raw'
+
+export type Child =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | RawMarkup
+  | readonly Child[]
+
+export interface Props {
+  readonly children?: Child
+  readonly [key: string]: unknown
+}
+
+/**
+ * What a component returns and what `jsx` produces: markup already rendered,
+ * carrying the same brand `raw` gives an author's own escape hatch. One brand
+ * for both is what lets a parent's `{children}` compose a child's output
+ * without escaping it a second time, since a plain string cannot say whether
+ * it is author text or already-rendered markup.
+ */
+export type Element = RawMarkup
+
+export type Component<P extends Props = Props> = (props: P) => Element
+
+export const Fragment = Symbol('Fragment')
+
+const ARIA_PREFIX = 'aria-'
+
+const VOID_ELEMENTS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'source',
+  'track',
+  'wbr',
+])
+
+function renderChild(child: Child): string {
+  if (child === null || child === undefined || typeof child === 'boolean') {
+    return ''
+  }
+  if (typeof child === 'number') return String(child)
+  if (typeof child === 'string') return escape(child)
+  if (isRaw(child)) return child.html
+  return child.map(renderChild).join('')
+}
+
+/**
+ * ARIA takes the literal word for a boolean, where HTML boolean attributes
+ * take presence or absence. Spike 1's first draft rendered a bare
+ * `aria-disabled` for `true` and dropped `aria-disabled={false}` entirely,
+ * silently removing state a screen reader reads.
+ */
+function renderAttribute(key: string, value: unknown): string {
+  if (key.startsWith(ARIA_PREFIX) && typeof value === 'boolean') {
+    return ` ${key}="${value}"`
+  }
+  if (value === undefined || value === null || value === false) return ''
+  if (value === true) return ` ${key}`
+  if (isRaw(value)) return ` ${key}="${escape(value.html)}"`
+  return ` ${key}="${escape(String(value))}"`
+}
+
+function renderAttributes(props: Props): string {
+  return Object.entries(props)
+    .filter(([key]) => key !== 'children')
+    .map(([key, value]) => renderAttribute(key, value))
+    .join('')
+}
+
+export function jsx(
+  type: string | Component | typeof Fragment,
+  props: Props,
+): Element {
+  if (type === Fragment) return raw(renderChild(props.children ?? null))
+  if (typeof type === 'function') return type(props)
+
+  const attrs = renderAttributes(props)
+  if (VOID_ELEMENTS.has(type)) return raw(`<${type}${attrs}>`)
+
+  return raw(
+    `<${type}${attrs}>${renderChild(props.children ?? null)}</${type}>`,
+  )
+}
+
+export const jsxs = jsx
+
+/** Unwraps a rendered element to the plain string a file writes to disk. */
+export function render(element: Element): string {
+  return element.html
+}
+
+export namespace JSX {
+  export type Element = RawMarkup
+
+  export interface ElementChildrenAttribute {
+    children: Record<string, never>
+  }
+
+  export interface IntrinsicElements {
+    [name: string]: Props
+  }
+}

package/src/teach/html/raw.ts

@@ -0,0 +1,28 @@
+const RAW = Symbol('raw')
+
+/**
+ * Markup already rendered, exempt from the escaping every other string
+ * receives. `raw` is the only way to produce one, so a lesson has to opt in
+ * explicitly rather than an author text string accidentally passing through
+ * unescaped.
+ */
+export interface RawMarkup {
+  readonly [RAW]: true
+  readonly html: string
+}
+
+export function raw(html: string): RawMarkup {
+  return { [RAW]: true, html }
+}
+
+export function isRaw(value: unknown): value is RawMarkup {
+  return typeof value === 'object' && value !== null && RAW in value
+}
+
+export function escape(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}

package/src/teach/render-fixture.tsx

@@ -0,0 +1,95 @@
+/** @jsxImportSource ./html */
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { TEACH_STYLESHEET_COMPONENTS } from '@/design/components'
+import { buildDesignCss } from '@/design/css'
+import { TEACH_FONT_FACES } from '@/teach/fonts'
+import { Heading } from '@/teach/components/heading'
+import { List } from '@/teach/components/list'
+import { Paragraph } from '@/teach/components/paragraph'
+import { render } from '@/teach/html/jsx-runtime'
+
+/**
+ * Regenerates the committed fixture lesson under
+ * `examples/teach/00-fixture/`, the same shape `examples/slides/showcase.md`
+ * takes against its own hand-rendered snapshot. Run with
+ * `bun src/teach/render-fixture.tsx` after a component changes shape.
+ */
+
+const FIXTURE_ROOT = join(
+  import.meta.dir,
+  '..',
+  '..',
+  'examples',
+  'teach',
+  '00-fixture',
+)
+const LESSON_TITLE = 'Compass bearings'
+const LESSON_FILE = '0001-compass-bearings.html'
+
+const STEPS = [
+  'Point the direction-of-travel arrow at the landmark.',
+  'Rotate the bezel until the orienting arrow lines up with the needle.',
+  'Read the bearing where the direction-of-travel arrow meets the bezel.',
+]
+
+const body = (
+  <>
+    <Heading level={1}>{LESSON_TITLE}</Heading>
+    <Paragraph lede>
+      A bearing is the compass direction from where you stand to whatever you
+      are aiming at, measured clockwise from north.
+    </Paragraph>
+    <Paragraph>
+      Hold the compass level and let the needle settle before reading anything
+      off it. A bearing taken while walking or tilted reads confidently and
+      wrong.
+    </Paragraph>
+    <Paragraph>
+      Three steps turn a sighted landmark into a number you can act on:
+    </Paragraph>
+    <List ordered items={STEPS} />
+    <Paragraph>
+      The same three steps run in reverse turn a bearing on a map into a
+      direction to walk, which is the only reason to learn them in this order.
+    </Paragraph>
+  </>
+)
+
+function page(title: string, main: string): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<link rel="stylesheet" href="../assets/course.css">
+</head>
+<body>
+<main class="wide-body">
+${main}
+</main>
+</body>
+</html>
+`
+}
+
+async function main(): Promise<void> {
+  await mkdir(join(FIXTURE_ROOT, 'lessons'), { recursive: true })
+  await mkdir(join(FIXTURE_ROOT, 'assets'), { recursive: true })
+
+  await writeFile(
+    join(FIXTURE_ROOT, 'assets', 'course.css'),
+    buildDesignCss(undefined, {
+      embedFonts: TEACH_FONT_FACES,
+      components: TEACH_STYLESHEET_COMPONENTS,
+    }),
+  )
+
+  await writeFile(
+    join(FIXTURE_ROOT, 'lessons', LESSON_FILE),
+    page(LESSON_TITLE, render(body)),
+  )
+}
+
+await main()

package/tsconfig.json

@@ -3,6 +3,7 @@
     "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "jsx": "react-jsx",
     "types": ["bun-types"],
     "strict": true,
     "skipLibCheck": true,