@kamishibai/sdk 0.1.1

package/src/parser/index.js

@@ -0,0 +1,223 @@
+import MarkdownIt from 'markdown-it'
+import matter from 'gray-matter'
+import * as B from '../core/blocks.js'
+import { CODES, validationError } from '../core/errors.js'
+import {
+  DEFAULT_LAYOUT,
+  defaultTemplateOf,
+  layoutModules,
+  templateLayoutEntries,
+} from '../layouts/index.js'
+import { containerPlugin } from './container.js'
+import { walkTokens, nestSections } from './tokens.js'
+
+/** Verbatim — the root form that makes an artifact a deck. */
+const DECK_ROOT = 'deck'
+
+/**
+ * Which template draws a document nobody named a template for.
+ *
+ * Derived, not typed: every layout ships a built-in generic template, so the
+ * resolution chain is 指名模板 → that 文體's default, and `render` can never fail
+ * for want of a template (CONTRACT C1 補丁). What used to be one global default
+ * is now one per 文體, and this is the flowing one.
+ *
+ * A function, not a constant, for the same reason `blockTypes()` is one: a list
+ * frozen at import is a list a third party can never appear in. Registration
+ * happens at whatever moment a plugin is loaded, which is not guaranteed to be
+ * before this module's first evaluation.
+ */
+export const defaultTemplateKey = () => defaultTemplateOf(DEFAULT_LAYOUT)
+
+/**
+ * The template keys under which `---` stops being decoration and cuts a slide.
+ *
+ * A page break is a *文體* fact, not a template's: it means something exactly
+ * where the artifact has pages. Read off the registry on every call, so a
+ * third-party deck layout's built-in template inherits it — the frozen version
+ * of this list could only ever contain `kami/slides`, which made the sentence
+ * below a claim the code did not keep.
+ *
+ * **Installed packages count too** (F2f, closing the F3 deferral). Until F2f a
+ * store package riding the `deck` 文體 got no `---` page break here, because
+ * resolving an arbitrary key to a manifest means reading the store — and this
+ * layer may not reach for it (issues/08). That deferral is why F3's `init` had
+ * to refuse `-l deck` outright: the alternative was scaffolding a deck package
+ * whose pages silently never split. The dependency is now inverted instead
+ * (`src/layouts/template-index.js`), so both halves land together: the key is
+ * read off an index the delivery layer fills, and this layer still imports
+ * nothing it did not import before.
+ *
+ * Read on every call, never frozen at import: a package installed one command
+ * ago is a package a frozen list could never contain.
+ */
+export const deckTemplateKeys = () => {
+  const decks = layoutModules().filter((layout) => layout.rootForm === DECK_ROOT)
+  const names = new Set(decks.map((layout) => layout.name))
+  return [
+    ...new Set([
+      ...decks.map((layout) => layout.defaultTemplate),
+      ...templateLayoutEntries()
+        .filter((entry) => names.has(entry.layout))
+        .map((entry) => entry.key),
+    ]),
+  ]
+}
+
+/** `<namespace>/<name>` — the version suffix is advisory (see render/templates.js). */
+const bareKey = (key) => String(key ?? '').split('@')[0]
+
+const createMd = () => {
+  const md = new MarkdownIt({ html: true, linkify: false, typographer: false })
+  md.use(containerPlugin)
+  return md
+}
+
+const pad2 = (value) => String(value).padStart(2, '0')
+
+/** `YYYY-MM-DD` assembled from calendar *fields* — never sliced off an ISO string. */
+const localCalendarDay = (d) => `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`
+const utcCalendarDay = (d) =>
+  `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`
+
+/**
+ * YAML resolves a bare `date: 2026-08-17` to exactly UTC midnight: that value is
+ * a *calendar day*, not an instant, so reading it back in UTC is what keeps it
+ * stable everywhere. Anything with a time component is a real instant.
+ */
+const isCalendarDayOnly = (d) =>
+  d.getUTCHours() === 0 &&
+  d.getUTCMinutes() === 0 &&
+  d.getUTCSeconds() === 0 &&
+  d.getUTCMilliseconds() === 0
+
+/**
+ * Coerce one frontmatter value into a meta string, or `undefined` to drop it.
+ *
+ * Two failures live here, both of them silent:
+ *
+ *  - A *bare* `date:` is a Date object, so a `typeof === 'string'` gate threw
+ *    the field away entirely — quoted dates shipped, unquoted ones vanished.
+ *  - `toISOString().slice(0, 10)` re-reads the instant in UTC, so
+ *    `2026-08-18 01:00:00 +08:00` displayed as 2026-08-17. A date the author
+ *    wrote by hand must not come back a day earlier.
+ *
+ * So the day is assembled from calendar fields, picking the calendar the value
+ * was written in (SPEC-facing normal form: `YYYY-MM-DD`).
+ */
+const asMetaString = (value) => {
+  if (typeof value === 'string') return value.length > 0 ? value : undefined
+  if (value instanceof Date && Number.isFinite(value.getTime())) {
+    return isCalendarDayOnly(value) ? utcCalendarDay(value) : localCalendarDay(value)
+  }
+  return undefined
+}
+
+/** Frontmatter → doc meta with a deterministic key order. */
+const buildMeta = (data) => {
+  const meta = {}
+  for (const key of B.META_KEY_ORDER) {
+    const value = asMetaString(data[key])
+    if (value !== undefined) meta[key] = value
+  }
+  const extras = Object.keys(data)
+    .filter((k) => !B.META_KEY_ORDER.includes(k) && k !== 'template')
+    .sort()
+  for (const key of extras) {
+    const value = asMetaString(data[key])
+    if (value !== undefined) meta[key] = value
+  }
+  if (meta.title === undefined) meta.title = 'Untitled'
+  return meta
+}
+
+/**
+ * Cut the flat item stream into slides on `hr` markers and wrap them in a deck.
+ * N separators yield N+1 slides — the segment count of the source, verbatim.
+ */
+const buildDeck = (items) => {
+  const groups = [[]]
+  for (const item of items) {
+    if (item.kind === 'hr') groups.push([])
+    else groups[groups.length - 1].push(item)
+  }
+  return B.create.deck({ slides: groups.map((group) => B.create.slide({ children: nestSections(group) })) })
+}
+
+/**
+ * Compile the Markdown superset (frontmatter + fenced block types + `:::`
+ * callouts) into a canonical block tree.
+ *
+ * @param {string} source
+ * @param {{template?: string}} [options] CLI `-t` override; it decides deck mode
+ *   just as frontmatter `template:` does, so the two entry points cannot disagree.
+ * @returns {{doc: object, templateKey: string}}
+ */
+export function parseMarkdown(source, options = {}) {
+  if (typeof source !== 'string' || source.trim().length === 0) {
+    throw validationError('input is empty', CODES.INPUT_EMPTY, 'doc')
+  }
+
+  let front
+  try {
+    front = matter(source)
+  } catch (cause) {
+    throw validationError(
+      `frontmatter is not valid YAML: ${cause.message}`,
+      CODES.PARSE_FAILED,
+      'doc.meta',
+    )
+  }
+
+  const md = createMd()
+  const env = {}
+  let tokens
+  try {
+    tokens = md.parse(front.content, env)
+  } catch (cause) {
+    throw validationError(
+      `markdown could not be compiled: ${cause.message}`,
+      CODES.PARSE_FAILED,
+      'doc',
+    )
+  }
+
+  const ctx = {
+    inline: (token) => (token ? md.renderer.renderInline(token.children ?? [], md.options, env) : ''),
+  }
+
+  const meta = buildMeta(front.data ?? {})
+  const declared =
+    typeof front.data?.template === 'string' && front.data.template.length > 0
+      ? front.data.template
+      : defaultTemplateKey()
+  const templateKey =
+    typeof options.template === 'string' && options.template.length > 0
+      ? options.template
+      : declared
+
+  const flat = walkTokens(tokens, ctx)
+  const children =
+    deckTemplateKeys().includes(bareKey(templateKey)) ? [buildDeck(flat)] : nestSections(flat)
+
+  return { doc: B.withIds(B.doc({ meta, children })), templateKey }
+}
+
+/** Parse a canonical block-tree JSON document (the data-view entry point). */
+export function parseBlockTree(source) {
+  let parsed
+  try {
+    parsed = JSON.parse(source)
+  } catch (cause) {
+    throw validationError(`input is not valid JSON: ${cause.message}`, CODES.PARSE_FAILED, 'doc')
+  }
+  const node = parsed?.type === 'doc' ? parsed : parsed?.doc
+  if (node?.type !== 'doc') {
+    throw validationError('JSON input has no `doc` block at its root', CODES.PARSE_FAILED, 'doc')
+  }
+  const templateKey =
+    typeof parsed?.template === 'string' && parsed.template.length > 0
+      ? parsed.template
+      : defaultTemplateKey()
+  return { doc: B.withIds(node), templateKey }
+}

package/src/parser/tokens.js

@@ -0,0 +1,265 @@
+import * as B from '../core/blocks.js'
+import { PLACEMENT_KEYS, containerSyntax } from '../blocks/index.js'
+
+const DEFAULT_INTENT = 'unspecified'
+
+/**
+ * Hand one `:::` fence back to the module that declared it.
+ *
+ * A module's `build` may answer with one block (`:::note` → a callout) or with
+ * a *list* of blocks (`:::place` → the blocks it contained, each now carrying a
+ * placement). The second shape is what lets placement live on the child, the
+ * way `grid-column` does in CSS, without inventing a cell block nobody asked
+ * for. An unclaimed name never reaches here: `container.js` refuses to open a
+ * fence the registry does not recognise.
+ */
+const buildContainer = (info, kids) => {
+  const raw = String(info ?? '').trim()
+  const name = raw.split(/\s+/)[0]
+  const mod = containerSyntax().get(name)
+  if (mod === undefined) return kids
+  const built = mod.syntax.build({ name, params: raw.slice(name.length).trim(), children: kids })
+  return Array.isArray(built) ? built : [built]
+}
+
+/** The placement fields a heading marker picked up from an enclosing `:::place`. */
+const placementOf = (item) => {
+  const out = {}
+  for (const key of PLACEMENT_KEYS) {
+    if (item?.[key] !== undefined) out[key] = item[key]
+  }
+  return out
+}
+
+const findClose = (tokens, openIndex) => {
+  const openType = tokens[openIndex].type
+  const closeType = openType.replace(/_open$/, '_close')
+  let depth = 0
+  for (let i = openIndex; i < tokens.length; i += 1) {
+    if (tokens[i].type === openType) depth += 1
+    else if (tokens[i].type === closeType) {
+      depth -= 1
+      if (depth === 0) return i
+    }
+  }
+  return tokens.length - 1
+}
+
+const rawSubtype = (info) => (info.startsWith('raw-svg') ? 'svg' : 'html')
+
+const intentOf = (info, content) => {
+  const fromInfo = /intent=(?:"([^"]*)"|'([^']*)')/.exec(info)
+  if (fromInfo) return fromInfo[1] ?? fromInfo[2]
+  const fromAttr = /data-intent=(?:"([^"]*)"|'([^']*)')/.exec(content)
+  if (fromAttr) return fromAttr[1] ?? fromAttr[2]
+  return DEFAULT_INTENT
+}
+
+/**
+ * ```` ```diagram ```` — the fence body is **JSON**, pinned (CONTRACT D2).
+ *
+ * JSON rather than YAML because the fence body and the IR block are then the
+ * same text: an author can paste `example diagram` straight into a fence, and
+ * the parser needs no second syntax whose failure modes differ from the IR's.
+ *
+ * A body that will not parse becomes an explicitly unrenderable diagram block
+ * rather than an exception here: by the time the render pipeline validates, the
+ * block has an id and therefore a block path to report (SPEC §10.3), which a
+ * throw from inside the token walk could not produce.
+ */
+const parseDiagram = (token) => {
+  let spec
+  try {
+    spec = JSON.parse(token.content)
+  } catch (cause) {
+    return B.diagramParseError(`fence 內容不是合法 JSON：${cause.message}`)
+  }
+  if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+    return B.diagramParseError('fence 內容必須是一個 JSON 物件（diagram block 的欄位）')
+  }
+  return B.create.diagram({ kind: spec.kind, nodes: spec.nodes, edges: spec.edges })
+}
+
+const parseFence = (token) => {
+  const info = (token.info ?? '').trim()
+  if (/^diagram\b/.test(info)) return parseDiagram(token)
+  if (/^raw(-html|-svg)?\b/.test(info)) {
+    return B.create.raw({
+      subtype: rawSubtype(info),
+      intent: intentOf(info, token.content),
+      html: token.content.replace(/\n+$/, ''),
+    })
+  }
+  return B.create.code({ lang: info.split(/\s+/)[0] ?? '', text: token.content.replace(/\n+$/, '') })
+}
+
+const parseTable = (tokens, openIndex, inline) => {
+  const end = findClose(tokens, openIndex)
+  const head = []
+  const rows = []
+  let currentRow = null
+  let inHead = false
+  for (let i = openIndex + 1; i < end; i += 1) {
+    const t = tokens[i]
+    if (t.type === 'thead_open') inHead = true
+    else if (t.type === 'thead_close') inHead = false
+    else if (t.type === 'tr_open') currentRow = []
+    else if (t.type === 'tr_close') {
+      if (currentRow !== null && !inHead) rows.push(currentRow)
+      currentRow = null
+    } else if (t.type === 'th_open' || t.type === 'td_open') {
+      const cell = inline(tokens[i + 1])
+      if (inHead) head.push(cell)
+      else if (currentRow !== null) currentRow.push(cell)
+    }
+  }
+  return { block: B.create.table({ head, rows }), next: end + 1 }
+}
+
+/**
+ * Compile one `<ul>`/`<ol>` token run into a real `list` block.
+ *
+ * S1 flattened lists into a prose HTML string, which meant a callout inside a
+ * list item had to be rendered by markdown-it — a second rendering path that
+ * disagreed with the Callout component — unless the list frame was thrown away
+ * entirely. Both halves of that trade-off are gone once list items carry real
+ * blocks: the `<ul>` frame survives *and* every child stays in the block tree.
+ */
+const parseList = (tokens, openIndex, closeIndex, ctx, ordered) => {
+  const items = []
+  let i = openIndex + 1
+  while (i < closeIndex) {
+    if (tokens[i].type !== 'list_item_open') {
+      i += 1
+      continue
+    }
+    const itemClose = findClose(tokens, i)
+    items.push(walkTokens(tokens.slice(i + 1, itemClose), ctx))
+    i = itemClose + 1
+  }
+  return B.create.list({ ordered, items })
+}
+
+/**
+ * Walk a markdown-it token stream into flat block items. Headings become
+ * `{kind:'heading'}` markers and thematic breaks `{kind:'hr'}` markers;
+ * `nestSections` turns the former into section blocks and drops the latter,
+ * while deck compilation (parser/index.js) cuts slides on the latter.
+ */
+export function walkTokens(tokens, ctx) {
+  const { inline } = ctx
+  const out = []
+  let i = 0
+
+  while (i < tokens.length) {
+    const t = tokens[i]
+    switch (t.type) {
+      case 'heading_open': {
+        out.push({
+          kind: 'heading',
+          level: Number(t.tag.slice(1)),
+          title: tokens[i + 1].content,
+        })
+        i = findClose(tokens, i) + 1
+        break
+      }
+      case 'paragraph_open': {
+        const close = findClose(tokens, i)
+        out.push(B.create.prose(inline(tokens[i + 1])))
+        i = close + 1
+        break
+      }
+      case 'fence': {
+        out.push(parseFence(t))
+        i += 1
+        break
+      }
+      case 'blockquote_open': {
+        const close = findClose(tokens, i)
+        out.push(B.create.quote(walkTokens(tokens.slice(i + 1, close), ctx)))
+        i = close + 1
+        break
+      }
+      case 'kami_container_open': {
+        const close = findClose(tokens, i)
+        out.push(...buildContainer(t.info, walkTokens(tokens.slice(i + 1, close), ctx)))
+        i = close + 1
+        break
+      }
+      case 'table_open': {
+        const { block, next } = parseTable(tokens, i, inline)
+        out.push(block)
+        i = next
+        break
+      }
+      case 'bullet_list_open':
+      case 'ordered_list_open': {
+        const close = findClose(tokens, i)
+        out.push(parseList(tokens, i, close, ctx, t.type === 'ordered_list_open'))
+        i = close + 1
+        break
+      }
+      case 'hr': {
+        out.push({ kind: 'hr' })
+        i += 1
+        break
+      }
+      case 'html_block': {
+        out.push(
+          B.create.raw({
+            subtype: 'html',
+            intent: intentOf('', t.content),
+            html: t.content.replace(/\n+$/, ''),
+          }),
+        )
+        i += 1
+        break
+      }
+      default:
+        i += 1
+    }
+  }
+  return out
+}
+
+/** Recurse into whichever nesting shape a container block uses. */
+const nestChildren = (item) => {
+  if (Array.isArray(item.items)) return { ...item, items: item.items.map(nestSections) }
+  if (Array.isArray(item.children)) return { ...item, children: nestSections(item.children) }
+  return item
+}
+
+/**
+ * Turn flat heading markers into a nested section tree (recursively).
+ *
+ * `hr` markers are dropped here: in document mode a thematic break carries no
+ * block meaning (a pre-existing, inventoried behaviour). Deck mode consumes
+ * them *before* calling this, which is the one place they mean anything.
+ */
+export function nestSections(items) {
+  const root = { children: [] }
+  const stack = [{ level: 0, node: root }]
+
+  for (const item of items) {
+    if (item.kind === 'hr') continue
+    if (item.kind === 'heading') {
+      while (stack.length > 1 && stack[stack.length - 1].level >= item.level) stack.pop()
+      // A heading inside a `:::place` keeps the coordinates the fence gave it:
+      // `nestSections` builds a fresh node, so anything not copied across here
+      // is silently dropped — and a placement that vanishes leaves a document
+      // whose layout is not the one its author wrote.
+      const node = {
+        type: 'section',
+        ...placementOf(item),
+        title: item.title,
+        level: item.level,
+        children: [],
+      }
+      stack[stack.length - 1].node.children.push(node)
+      stack.push({ level: item.level, node })
+      continue
+    }
+    stack[stack.length - 1].node.children.push(nestChildren(item))
+  }
+  return root.children
+}

package/src/render/board-filter.client.js

@@ -0,0 +1,80 @@
+/*
+ * Board lane filter (SPEC section 3.4, wayfinder issue 11 P5 "board filter").
+ *
+ * A block-keyed client asset: the render layer embeds it only into artifacts
+ * that actually contain a `board` block, which is what keeps every artifact
+ * drawn before this existed byte for byte unchanged.
+ *
+ * Every character here is ASCII, and that is a size decision rather than a
+ * stylistic one: client assets are fed to `collectCodepoints`, so one section
+ * sign or one em dash in a comment pulls a whole font subset (~8.5KB) into
+ * every artifact that carries this file. The same scan also bans the four
+ * sequences that would put the HTML tokenizer into its double-escaped state,
+ * where the closing tag of the script element stops closing it and the rest of
+ * the artifact -- the embedded IR included -- is swallowed as script data
+ * (CONTRACT F2g H2). Both rules are pinned by
+ * `test_f2g_skeleton_assets_cannot_derail_the_parser`.
+ *
+ * Deliberately ES5-shaped and dependency-free: it is embedded verbatim into one
+ * offline file, so it must parse in any evergreen browser without a build step.
+ *
+ * The DOM contract is stated by `src/blocks/board.js` and read here: `data-board`
+ * scopes one board, and `data-board-lane` is carried by the button, by the lane
+ * and by every card, so this file never needs to know how a lane relates to its
+ * cards. Without JS every lane simply stays visible and the board reads as the
+ * full, unfiltered kanban -- the filter is an addition, never a prerequisite.
+ *
+ * The leading semicolon is the same guard `scale-to-fit.client.js` carries and
+ * for the same reason: assets are concatenated with a newline between them, and
+ * `})()` followed by a line starting with `(` is one expression to a JS parser --
+ * the previous asset's return value would be called as a function and this whole
+ * file would never run. Pinned by `test_f6a_assets_survive_concatenation`.
+ */
+;(function () {
+  var HIDE_RULE = '.board-lane[hidden]{display:none !important}'
+  var boards = Array.prototype.slice.call(document.querySelectorAll('.board[data-board]'))
+  if (boards.length === 0) return
+
+  /*
+   * The hiding rule ships with the behaviour, not with the skin.
+   *
+   * `hidden` is display:none in every UA stylesheet, and a template that gives
+   * `.board-lane` any display of its own silently wins over it -- the button
+   * would then toggle a class that changes nothing, which is worse than having
+   * no filter at all because it looks like one.
+   */
+  var rules = document.createElement('style')
+  rules.textContent = HIDE_RULE
+  document.head.appendChild(rules)
+
+  function apply(board, lane) {
+    var lanes = Array.prototype.slice.call(board.querySelectorAll('.board-lane'))
+    for (var i = 0; i < lanes.length; i += 1) {
+      var name = lanes[i].getAttribute('data-board-lane')
+      lanes[i].hidden = lane !== null && name !== lane
+    }
+    var buttons = Array.prototype.slice.call(board.querySelectorAll('.board-filter'))
+    for (var j = 0; j < buttons.length; j += 1) {
+      var pressed = lane !== null && buttons[j].getAttribute('data-board-lane') === lane
+      buttons[j].setAttribute('aria-pressed', pressed ? 'true' : 'false')
+    }
+    board.setAttribute('data-board-filter', lane === null ? '' : lane)
+  }
+
+  for (var b = 0; b < boards.length; b += 1) {
+    (function (board) {
+      var selected = null
+      var buttons = Array.prototype.slice.call(board.querySelectorAll('.board-filter'))
+      for (var k = 0; k < buttons.length; k += 1) {
+        (function (button) {
+          button.addEventListener('click', function () {
+            var lane = button.getAttribute('data-board-lane')
+            selected = selected === lane ? null : lane
+            apply(board, selected)
+          })
+        })(buttons[k])
+      }
+      apply(board, null)
+    })(boards[b])
+  }
+})()

package/src/render/compile.js

@@ -0,0 +1,29 @@
+import { parseBlockTree, parseMarkdown } from '../parser/index.js'
+import { renderArtifact } from './index.js'
+
+/**
+ * Source text → finished artifact, with no filesystem in sight.
+ *
+ * `render` and `serve` must agree byte for byte on what a source file becomes —
+ * a preview that draws something the exported artifact does not is worse than
+ * no preview. Sharing one function is what makes that agreement structural
+ * rather than a matter of keeping two call sites in step.
+ *
+ * The template override reaches the *parser*, not just the renderer: whether
+ * `---` is a page break is a template decision, so resolving it later would
+ * compile a deck source as a document and then draw the empty result with the
+ * deck template.
+ *
+ * @param {{source: string, format: 'markdown'|'json', template?: string,
+ *   generator?: string, createdAt: string}} input
+ * @returns {Promise<{html: string, ir: object, slides: number|undefined}>}
+ */
+export async function compileDocument({ source, format, template, generator, createdAt }) {
+  const parsed = format === 'json' ? parseBlockTree(source) : parseMarkdown(source, { template })
+  return await renderArtifact({
+    doc: parsed.doc,
+    templateKey: template ?? parsed.templateKey,
+    createdAt,
+    generator,
+  })
+}

package/src/render/context.js

@@ -0,0 +1,98 @@
+import { blockModule } from '../blocks/index.js'
+
+const EMPTY_CONFIG = Object.freeze({})
+const ROOT_POSITION = Object.freeze({ index: 0, total: 1 })
+
+const asNodes = (value) => (Array.isArray(value) ? value : value === undefined ? [] : [value])
+
+/**
+ * The render context a block module is handed.
+ *
+ * A block module knows what its own type *is*; it deliberately knows nothing
+ * about the page it lands on. Everything situational reaches it through here,
+ * which is what keeps a module portable enough to be published by a third party:
+ *
+ *  - `templateKey` / `meta` — who is drawing, and the document's own identity
+ *  - `config(type)`         — the template's settings for a block type
+ *                             (`轉子/<型別>/config` in wayfinder issue 13)
+ *  - `chrome(name, payload)`— a slot the template may fill; empty when it does not
+ *  - `layoutOf(block)`      — geometry measured by the layer above (A5)
+ *  - `canvas`               — the resolved canvas geometry of this artifact (C3)
+ *  - `position`             — where this block sits among its siblings
+ *  - `renderBlock` / `renderChildren` / `drawableChildren` — recursion, so
+ *                             nesting stays uniform
+ *
+ * @param {{template: object, doc: object, layouts: Map<string, object>,
+ *   canvas?: object, overrides?: Record<string, Function>}} input
+ */
+export function createRenderContext({
+  template,
+  doc,
+  layouts,
+  canvas = EMPTY_CONFIG,
+  overrides = EMPTY_CONFIG,
+}) {
+  const { namespace, name } = template.manifest
+  const blockConfig = template.manifest.blockConfig ?? EMPTY_CONFIG
+  const chromeTable = template.chrome ?? EMPTY_CONFIG
+
+  const ctx = {
+    templateKey: `${namespace}/${name}`,
+    meta: doc.meta ?? EMPTY_CONFIG,
+    position: ROOT_POSITION,
+    config: (type) => blockConfig[type] ?? EMPTY_CONFIG,
+    chrome: (slot, payload) => {
+      const fill = chromeTable[slot]
+      return typeof fill === 'function' ? asNodes(fill(payload ?? EMPTY_CONFIG, ctx)) : []
+    },
+    layoutOf: (block) => layouts.get(block?.id),
+    canvas,
+    renderBlock,
+    renderChildren,
+    drawableChildren,
+  }
+
+  /**
+   * Render one block, or `null` when no module claims its type.
+   *
+   * Skipping an unknown type is what a renderer does; it is not the *only*
+   * answer here, because `assertTemplateVocabulary` has already refused any
+   * document the template cannot express (CONTRACT C4). By this point a miss
+   * means a block nobody registered at all.
+   *
+   * A template package's 轉子 override wins over the registered module, and
+   * *only* for the artifact this context is drawing (CONTRACT D3). The
+   * admission check still runs against `manifest.blocks` first: an override is
+   * a different conversion for a type the template already declared, never a
+   * back door into a vocabulary it did not.
+   */
+  function renderBlock(block, position = ROOT_POSITION) {
+    const type = block?.type
+    const mod = blockModule(type)
+    if (mod === undefined) return null
+    const render = overrides[type] ?? mod.render
+    return render(block, { ...ctx, position })
+  }
+
+  /**
+   * The children that will actually be drawn, in order.
+   *
+   * A container that has to pair each child with something of its own — a grid
+   * cell carrying that child's placement — cannot use `renderChildren` alone,
+   * because the returned array is already filtered and would silently pair the
+   * wrong child with the wrong coordinates.
+   */
+  function drawableChildren(blocks) {
+    if (!Array.isArray(blocks)) return []
+    return blocks.filter((block) => blockModule(block?.type) !== undefined)
+  }
+
+  function renderChildren(blocks) {
+    const drawable = drawableChildren(blocks)
+    return drawable.map((block, index) =>
+      renderBlock(block, { index, total: drawable.length }),
+    )
+  }
+
+  return ctx
+}