@kamishibai/sdk 0.1.1

package/src/layouts/registry.js

@@ -0,0 +1,251 @@
+/**
+ * The layout module registry — one 文體's whole knowledge in one place.
+ *
+ * Layout was the last thing in this SDK that was not a first-class citizen: the
+ * root form of an artifact lived inside each template's `components.js`, which
+ * made 「replay 換皮不換文體」 a rule two templates happened to obey rather than
+ * a structure (wayfinder issue 13 裁決 1). Registering a layout is now the same
+ * kind of act as registering a block: implement the interface, call the public
+ * entry point once, edit no file inside the SDK.
+ *
+ * A layout owns **the cut and nothing else** — the outer frame, the grid, the
+ * named slots, and the canvas geometry. It owns no wording, no section
+ * structure, no sample content: one layout has to be able to carry a dashboard
+ * and a maintenance page without knowing which one it is drawing. What a given
+ * template *looks like by default* is the template's applied state (its
+ * manifest values and its stylesheet), never the layout's.
+ */
+
+/** Every field a layout module must declare. */
+export const LAYOUT_MODULE_FIELDS = Object.freeze([
+  'name',
+  'canvas',
+  'root',
+  'slots',
+  'defaults',
+  'rootForm',
+  'defaultTemplate',
+  'styleHooks',
+])
+
+/** Verbatim — the two canvas kinds (wayfinder issue 14 裁決 4). */
+export const CANVAS_FLOWING = 'flowing'
+export const CANVAS_BOUNDED = 'bounded'
+export const CANVAS_MODES = Object.freeze([CANVAS_FLOWING, CANVAS_BOUNDED])
+
+/** SPEC §12 の同一條：a third-party layout wears the plugin prefix. */
+export const PLUGIN_LAYOUT_PREFIX = 'x-'
+
+/** The geometry knobs a layout defines and a template supplies values for. */
+export const LAYOUT_DEFAULT_KEYS = Object.freeze(['maxWidth', 'measure'])
+
+/**
+ * Optional — **this layout's own geometry knobs**, beyond the two every canvas
+ * has, as `{name: factory value}` (CONTRACT F2b G1).
+ *
+ * `defaults` is the canvas vocabulary *every* 文體 shares: how wide the page may
+ * get, how wide a line of text may get, and (bounded only) the fixed logical
+ * canvas. It is deliberately closed — a 文體 that grew a third meaning there
+ * would be asking every other 文體 to carry it too.
+ *
+ * A knob is the other half: geometry only one 文體 has. `article` declares the
+ * rail — a side region's switch, width and side — because a rail is a way of
+ * *cutting* a flowing page, and nothing about a deck wants one. Declaring the
+ * knobs here rather than in a table inside `src/render/**` is what keeps the
+ * doctrine true for a third party as well: a layout published from outside
+ * defines its own knobs and its template turns them, with no edit to the SDK.
+ *
+ * Values are scalars because a knob is a *setting*, and because the resolved
+ * canvas is one flat frozen object the markup and the stylesheet both read.
+ * The knob's factory value also fixes its **type**: a template may turn a knob,
+ * never redefine what kind of thing it is (`resolveCanvas` / `canvasProblems`).
+ */
+export const LAYOUT_KNOBS_FIELD = 'knobs'
+
+/**
+ * Optional — a layout's claim that its whole page is addressable by 24-grid
+ * coordinates, so a block may carry `col`/`row` without being wrapped in a
+ * `grid` container (CONTRACT C2 複驗補丁).
+ *
+ * It has to be *declared*, and `bounded` deliberately does not imply it. A
+ * bounded canvas is only a fixed logical size; whether anything lays the grid
+ * tracks that make a bare coordinate resolve to a real cell is a separate
+ * question, so treating `bounded` as the licence would re-open the exact hole
+ * this gate closes — the coordinate would be accepted and then dropped by CSS
+ * auto-placement, silently.
+ *
+ * Since F2f exactly one factory layout declares it: `deck`, whose slides lay
+ * 24 real column tracks (`src/blocks/slide.js`). `article` does not and must
+ * not. The rule for any layout, factory or third-party, is that the claim and
+ * the tracks land together — a layout that declares this without building them
+ * is licensing coordinates it will then throw away.
+ */
+export const GRID_ADDRESSED_FIELD = 'gridAddressed'
+
+/** Names the resolved canvas already occupies — a knob may not shadow one. */
+const RESERVED_KNOB_NAMES = Object.freeze([
+  'layout',
+  'canvas',
+  'canvasSize',
+  'canvasAttrs',
+  GRID_ADDRESSED_FIELD,
+  ...LAYOUT_DEFAULT_KEYS,
+])
+
+/** A knob name is an identifier: it becomes a `ksb:` marker word and a manifest key. */
+const KNOB_NAME = /^[A-Za-z][A-Za-z0-9]*$/
+
+const isScalar = (value) =>
+  typeof value === 'boolean' ||
+  typeof value === 'string' ||
+  (typeof value === 'number' && Number.isFinite(value))
+
+const EMPTY = Object.freeze({ modules: Object.freeze([]), byName: new Map(), version: 0 })
+
+let current = EMPTY
+let baseline = EMPTY
+let sealed = false
+
+const reject = (message) => {
+  throw new TypeError(`invalid layout module: ${message}`)
+}
+
+const isPositiveNumber = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0
+
+/**
+ * A bounded canvas is a *fixed logical canvas* scaled to fit (issue 14 裁決 4).
+ * Declaring `bounded` without saying how big that canvas is would give the
+ * skeleton nothing to scale, and the artifact would ship with a scale factor of
+ * one — i.e. silently flowing while claiming to be bounded.
+ */
+function assertCanvasGeometry(mod) {
+  const defaults = mod.defaults
+  if (defaults === null || typeof defaults !== 'object') reject(`\`defaults\` of "${mod.name}" must be an object`)
+  for (const key of LAYOUT_DEFAULT_KEYS) {
+    if (!isPositiveNumber(defaults[key])) {
+      reject(`\`defaults.${key}\` of "${mod.name}" must be a positive number of CSS pixels`)
+    }
+  }
+  if (mod.canvas !== CANVAS_BOUNDED) return
+  const size = defaults.canvasSize
+  if (size === null || typeof size !== 'object') {
+    reject(`"${mod.name}" is \`${CANVAS_BOUNDED}\` but declares no \`defaults.canvasSize\``)
+  }
+  if (!isPositiveNumber(size.width) || !isPositiveNumber(size.height)) {
+    reject(`\`defaults.canvasSize\` of "${mod.name}" needs positive \`width\`/\`height\``)
+  }
+}
+
+/**
+ * A layout's own knobs, checked at registration for the same reason the canvas
+ * geometry is: a knob that cannot be resolved fails inside a render, where the
+ * message would be about something else entirely.
+ *
+ * A knob that *shadows* a canvas field is the worst shape available here, and
+ * the reason this is a hard refusal rather than a warning: the resolved canvas
+ * merges knobs and geometry into one flat object, so a knob called `measure`
+ * would be silently overwritten — the template would turn it, the artifact
+ * would ignore it, and nothing anywhere would say so.
+ */
+function assertKnobs(mod) {
+  const knobs = mod[LAYOUT_KNOBS_FIELD]
+  if (knobs === undefined) return
+  if (knobs === null || typeof knobs !== 'object' || Array.isArray(knobs)) {
+    reject(`\`${LAYOUT_KNOBS_FIELD}\` of "${mod.name}" must be an object of scalar defaults`)
+  }
+  for (const [name, value] of Object.entries(knobs)) {
+    if (!KNOB_NAME.test(name)) {
+      reject(`knob "${name}" of "${mod.name}" is not an identifier`)
+    }
+    if (RESERVED_KNOB_NAMES.includes(name)) {
+      reject(`knob "${name}" of "${mod.name}" shadows a resolved-canvas field`)
+    }
+    if (!isScalar(value)) {
+      reject(`knob "${name}" of "${mod.name}" must default to a boolean, number or string`)
+    }
+  }
+}
+
+/**
+ * Reject anything that would register a half-built layout and fail later,
+ * deeper — the same discipline the block registry applies, for the same reason:
+ * the failing path is the rarest one, so registration is the only place it can
+ * be caught before it matters.
+ */
+function assertModuleShape(mod, byName) {
+  if (mod === null || typeof mod !== 'object') reject('not an object')
+  for (const field of LAYOUT_MODULE_FIELDS) {
+    if (mod[field] === undefined) reject(`missing \`${field}\``)
+  }
+  if (typeof mod.name !== 'string' || mod.name.length === 0) reject('`name` must be a non-empty string')
+  if (!CANVAS_MODES.includes(mod.canvas)) {
+    reject(`\`canvas\` of "${mod.name}" must be one of: ${CANVAS_MODES.join(', ')}`)
+  }
+  if (typeof mod.root !== 'function') reject(`\`root\` of "${mod.name}" must be a function`)
+  if (!Array.isArray(mod.slots) || mod.slots.some((slot) => typeof slot !== 'string')) {
+    reject(`\`slots\` of "${mod.name}" must be an array of slot names`)
+  }
+  if (!Array.isArray(mod.styleHooks)) reject(`\`styleHooks\` of "${mod.name}" must be an array`)
+  if (mod.rootForm !== null && (typeof mod.rootForm !== 'string' || mod.rootForm.length === 0)) {
+    reject(`\`rootForm\` of "${mod.name}" must be a block type name or null`)
+  }
+  // Optional, and boolean when present: a truthy string here would switch off a
+  // gate by accident, and the gate it switches off is the one that keeps a
+  // coordinate from evaporating.
+  const addressed = mod[GRID_ADDRESSED_FIELD]
+  if (addressed !== undefined && typeof addressed !== 'boolean') {
+    reject(`\`${GRID_ADDRESSED_FIELD}\` of "${mod.name}" must be a boolean when declared`)
+  }
+  // Every layout ships a built-in generic template, so `render` can never fail
+  // for want of one: the resolution chain is 指名模板 → this layout's default.
+  if (typeof mod.defaultTemplate !== 'string' || mod.defaultTemplate.length === 0) {
+    reject(`\`defaultTemplate\` of "${mod.name}" must name a built-in template`)
+  }
+  assertCanvasGeometry(mod)
+  assertKnobs(mod)
+  if (byName.has(mod.name)) reject(`layout "${mod.name}" is already registered`)
+  if (sealed && !mod.name.startsWith(PLUGIN_LAYOUT_PREFIX)) {
+    reject(`third-party layout "${mod.name}" must start with \`${PLUGIN_LAYOUT_PREFIX}\``)
+  }
+}
+
+const snapshotWith = (previous, mod) => {
+  const modules = Object.freeze([...previous.modules, mod])
+  const byName = new Map(previous.byName)
+  byName.set(mod.name, mod)
+  return Object.freeze({ modules, byName, version: previous.version + 1 })
+}
+
+/**
+ * Register one layout module — the public extension point (CONTRACT C1).
+ *
+ * @param {{name: string, canvas: string, root: Function, slots: readonly string[],
+ *   defaults: {maxWidth: number, measure: number, canvasSize?: {width: number, height: number}},
+ *   rootForm: string|null, defaultTemplate: string, styleHooks: readonly string[],
+ *   knobs?: Record<string, boolean|number|string>}} mod
+ */
+export function registerLayout(mod) {
+  assertModuleShape(mod, current.byName)
+  current = snapshotWith(current, mod)
+  return mod.name
+}
+
+/** Freeze the factory 文體 set as the one `resetLayoutRegistry` returns to. */
+export function sealCoreLayouts() {
+  baseline = current
+  sealed = true
+  return baseline.version
+}
+
+/** Drop every layout registered after the core seal (test hygiene). */
+export function resetLayoutRegistry() {
+  current = baseline
+  return current.version
+}
+
+export const layoutModules = () => current.modules
+export const layoutModule = (name) => current.byName.get(name)
+export const layoutNames = () => current.modules.map((mod) => mod.name)
+export const pluginLayoutNames = () =>
+  current.modules.filter((mod) => !baseline.byName.has(mod.name)).map((mod) => mod.name)
+export const layoutRegistryVersion = () => current.version

package/src/layouts/resume.js

@@ -0,0 +1,172 @@
+import { el } from '../blocks/element.js'
+import { CANVAS_BOUNDED } from './registry.js'
+
+/**
+ * `resume` — the 文體 of a printed curriculum vitae (13 號票 v1 五版面之五).
+ *
+ * The other four layouts answer questions about a screen: how a long page is
+ * read, how a board of cards is scanned, how a deck is presented, how a site is
+ * scrolled. This one answers a question about **paper**. A résumé is read on a
+ * screen only incidentally; it is sent as a PDF, opened by someone who prints
+ * it or flips through it a page at a time, and judged partly on whether it fits
+ * on one sheet. Every decision below follows from that single fact.
+ *
+ * ## The canvas is a sheet of A4 (CONTRACT F2e R10)
+ *
+ * 210mm x 297mm at 96dpi is 793.7 x 1122.5 CSS pixels, so the fixed logical
+ * canvas is **794 x 1123**. That is not an aesthetic choice the way the deck's
+ * 1280x720 or the one-page screen's 1440x900 were: those are shapes a window
+ * has, this is the shape the artifact will physically be. On screen the
+ * skeleton scales the sheet to fit the window like any other bounded canvas
+ * (`src/render/scale-to-fit.client.js`); on paper it stands down and the sheet
+ * is drawn at exactly its natural size, which is exactly one printed page.
+ *
+ * The measurement that settles the number is in the contract: this SDK's own
+ * PDF export prints A4 with 14mm margins (`src/export/pdf.js`), leaving a
+ * printable box of about 688.8 x 1017.9px. A sheet declared at 794 x 1123 loses
+ * 105px off the right edge and 105px off the bottom of every page unless the
+ * skin claims the whole page box back with `@page { margin: 0 }` — silently,
+ * with no error anywhere. So the skins on this 文體 declare it, and the two
+ * facts (canvas size, page box) are pinned together.
+ *
+ * ## The cut: one top-level section is one sheet
+ *
+ * The parser nests every heading under its parent, so a document's top-level
+ * `section` blocks are its chapters, and on this 文體 a chapter is a sheet. The
+ * test is 「是不是頂層 section」 and deliberately **not** 「是不是 level 1」, the
+ * same reasoning `card` and `one-page` record: the two sentences pick out
+ * identical blocks for an ordinary document and part company only for one that
+ * starts at `##`, where the level test would yield a résumé with no pages at
+ * all because of a heading-depth detail nobody thought about.
+ *
+ * A layout cannot measure text, so it cannot paginate by content — that is the
+ * browser's job and it does it on paper. What a layout *can* do is take the
+ * author's own top-level heading as the page break, which is the only honest
+ * signal available at the cutting layer. The 預設 md teaches the convention:
+ * `#` starts a sheet, `##` is a band inside one.
+ *
+ * ## Why nothing is drawn outside a sheet
+ *
+ * This is where the 文體 parts company with `one-page`, and printing is the
+ * whole reason. On a site the masthead gets a screen of its own (a hero) and
+ * the colophon floats below every canvas, because on a screen「小一點的頁尾」is
+ * a reasonable thing to be. On paper it is not: an element sitting after the
+ * last sheet is laid onto **the next page**, so every résumé would print one
+ * extra sheet carrying a single line of small type. And a masthead with a sheet
+ * to itself would be an entire A4 page holding a name.
+ *
+ * So the head chrome joins the **first** sheet and the foot chrome joins the
+ * **last** one, and the outer frame's only children are sheets.
+ *
+ * ## Why there is no knob here
+ *
+ * How a sheet is padded, how the name is set, how the contact line is arranged:
+ * every one of those is read by the stylesheet and by nothing else, which makes
+ * them decoration, and decoration lives in the skin. The logical canvas is not
+ * a knob either — it is `defaults.canvasSize`, the one extra field every
+ * bounded 文體 has, required at registration time.
+ *
+ * ## Why it does **not** declare `gridAddressed`
+ *
+ * Same shape as `one-page`: a sheet's child is exactly one `section`, so the 24
+ * tracks would be laid on a region with a single child, and a coordinate an
+ * author wrote *inside* the section would not be a direct child of the region
+ * at all — CSS auto-placement would drop it in silence while the placement gate
+ * (`src/render/placement.js`), which takes the declaration at face value, had
+ * stopped refusing it. The claim and the tracks land together, so neither lands.
+ */
+
+/** Verbatim — the block type one sheet is made of. */
+const SHEET_BLOCK = 'section'
+
+/** Verbatim — the three regions of a résumé, as class names. */
+const RESUME_CLASS = 'resume'
+const SHEET_CLASS = 'sheet'
+const SHEET_INNER_CLASS = 'sheet-inner'
+
+/**
+ * Verbatim — the fixed logical canvas of **one sheet**, in CSS pixels.
+ *
+ * A4 portrait at 96dpi: 210mm -> 793.7 -> 794, 297mm -> 1122.5 -> 1123. Unlike
+ * every other logical canvas in this SDK the number is not chosen, it is
+ * converted: the artifact ends up on this piece of paper.
+ */
+const SHEET_CANVAS = Object.freeze({ width: 794, height: 1123 })
+
+const isSheet = (block) => block?.type === SHEET_BLOCK
+
+export default Object.freeze({
+  name: 'resume',
+
+  canvas: CANVAS_BOUNDED,
+
+  /** No required root form: a résumé draws whatever sits under `doc`. */
+  rootForm: null,
+
+  /** The built-in generic template of this 文體 — `render` never wants for one. */
+  defaultTemplate: 'kami/resume',
+
+  /**
+   * Head and foot, named for where they land rather than for what they hold:
+   * both are drawn *inside* a sheet, so neither is a page-level region the way
+   * `one-page`'s `page-lead` / `page-foot` are.
+   */
+  slots: Object.freeze(['resume-head', 'resume-foot']),
+
+  styleHooks: Object.freeze([RESUME_CLASS, SHEET_CLASS, SHEET_INNER_CLASS]),
+
+  /**
+   * Factory geometry, in CSS pixels. Three numbers, three different jobs:
+   *
+   *  - `canvasSize` 794x1123 — the sheet of A4 that gets scaled to fit.
+   *  - `maxWidth` 660 — how wide the content region inside a sheet may grow,
+   *    i.e. the sheet minus a printer-safe margin on each side.
+   *  - `measure` 620 — the width a *line of text* wants. This is the first 文體
+   *    where it is not 740 (CONTRACT C3's number for every screen 文體), and the
+   *    reason is the paper: 740 plus any margin at all is wider than an A4
+   *    sheet, so keeping it would mean either type running off the page or a
+   *    page with no margin.
+   */
+  defaults: Object.freeze({ maxWidth: 660, measure: 620, canvasSize: SHEET_CANVAS }),
+
+  /**
+   * Sheets, in document order, with the head on the first and the foot on the
+   * last.
+   *
+   * A sheet is drawn only when something goes on it: a document with no
+   * top-level sections and no head chrome produces no sheets at all, rather than
+   * one blank page. `...(x ? [n] : [])` rather than `x ? n : null`, because a
+   * `null` child is a real, invisible, permanent empty comment node.
+   *
+   * The canvas attributes come from `ctx.canvas`, never from the constant
+   * above: a template may not move the logical canvas, but the resolved canvas
+   * is the one place that answer is computed, and a second computation here is
+   * a scale factor free to disagree with the one the skeleton uses.
+   */
+  root: (doc, ctx) => {
+    const children = doc?.children ?? []
+    const sections = children.filter(isSheet)
+    const head = [
+      ...ctx.chrome('resume-head', ctx.meta),
+      ...ctx.renderChildren(children.filter((block) => !isSheet(block))),
+    ]
+    const foot = ctx.chrome('resume-foot', ctx.meta)
+    const bodies = sections.map((block, index) => [
+      ctx.renderBlock(block, { index, total: sections.length }),
+    ])
+    const pages = bodies.length > 0 ? bodies : head.length + foot.length > 0 ? [[]] : []
+    const sheet = (nodes) =>
+      el('section', { class: SHEET_CLASS, ...(ctx.canvas?.canvasAttrs ?? {}) }, [
+        el('div', { class: SHEET_INNER_CLASS }, nodes),
+      ])
+    return el('article', { class: RESUME_CLASS, 'data-template': ctx.templateKey }, [
+      ...pages.map((nodes, index) =>
+        sheet([
+          ...(index === 0 ? head : []),
+          ...nodes,
+          ...(index === pages.length - 1 ? foot : []),
+        ]),
+      ),
+    ])
+  },
+})

package/src/layouts/template-index.js

@@ -0,0 +1,78 @@
+/**
+ * Which 文體 an *installed* template rides — the inversion that let F2f close
+ * the `deckTemplateKeys` deferral.
+ *
+ * Whether `---` cuts a page is a 文體 fact, so the parser has to know which
+ * layout the document's template rides. For the two factory templates it can
+ * read that off the layout registry (每個 layout 自帶內建通用模板). For a
+ * package sitting in `~/.kamishibai/templates/` it cannot: resolving an
+ * arbitrary key to a manifest means reading a TOML file off disk, which is the
+ * delivery layer's job, and a parser that reached for it would be importing
+ * *upwards* through two layers — the one direction the architecture forbids
+ * (issues/08). F3 landed the store loader and left this deferred for exactly
+ * that reason, which is why `init -l deck` had to be refused outright: a
+ * scaffolded deck package would have had pages that silently never split.
+ *
+ * So the dependency is inverted, the same way the block, layout and template
+ * registries already are. The delivery layer, which knows the store, registers
+ * a **source** that can enumerate `{key, layout}` pairs; the parser reads the
+ * index and imports nothing new. Neither side learns about the other.
+ *
+ * A source rather than a plain map because the store is not static: packages
+ * appear when someone installs one, and a map captured at import time is a map
+ * the package installed a second ago can never be in.
+ */
+
+let sources = Object.freeze([])
+
+const reject = (message) => {
+  throw new TypeError(`invalid template layout source: ${message}`)
+}
+
+/**
+ * Register one source of `{key, layout}` pairs.
+ *
+ * Shape-checked at registration for the reason every other registry here states:
+ * a source that cannot enumerate fails on the rarest path — a document whose
+ * `---` should have split — and the failure there looks like a parser bug.
+ *
+ * @param {{entries: () => Array<{key: string, layout: string}>}} source
+ */
+export function registerTemplateLayoutSource(source) {
+  if (source === null || typeof source !== 'object') reject('not an object')
+  if (typeof source.entries !== 'function') reject('`entries` must be a function')
+  sources = Object.freeze([...sources, source])
+  return sources.length
+}
+
+/** Drop every registered source (test hygiene, and re-installation on a new HOME). */
+export function resetTemplateLayoutSources() {
+  sources = Object.freeze([])
+  return sources.length
+}
+
+/**
+ * Every installed template's `{key, layout}`, in registration order.
+ *
+ * A source that throws is skipped rather than allowed to take the caller down:
+ * the question being asked is 「這份文件的 `---` 要不要切頁」, and one unreadable
+ * package on disk must not stop an unrelated document from being parsed. The
+ * package itself is not thereby excused — the moment anyone tries to *draw*
+ * with it, `loadStoreTemplate` refuses it loudly by name.
+ */
+export function templateLayoutEntries() {
+  const found = []
+  for (const source of sources) {
+    let entries
+    try {
+      entries = source.entries()
+    } catch {
+      continue
+    }
+    if (!Array.isArray(entries)) continue
+    for (const entry of entries) {
+      if (typeof entry?.key === 'string' && typeof entry?.layout === 'string') found.push(entry)
+    }
+  }
+  return found
+}

package/src/parser/artifact.js

@@ -0,0 +1,38 @@
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { IR_SCRIPT_TYPE } from '../core/ir.js'
+
+const SCRIPT_SOURCE = `<script[^>]*type\\s*=\\s*["']${IR_SCRIPT_TYPE.replace('+', '\\+')}["'][^>]*>([\\s\\S]*?)<\\/script>`
+
+/** Raw payloads of every embedded IR script found in an artifact. */
+export function extractIrPayloads(html) {
+  const re = new RegExp(SCRIPT_SOURCE, 'gi')
+  const payloads = []
+  let m
+  while ((m = re.exec(html)) !== null) payloads.push(m[1])
+  return payloads
+}
+
+const irError = (code, message) => new KsbError({ code, message, exitCode: EXIT.VALIDATION })
+
+/**
+ * Recover the single IR envelope an artifact carries, or fail with a pinned code.
+ *
+ * Shared by `replay` and by the export chain: both have to answer "what is this
+ * artifact, really?" from the embedded record rather than from its markup, and
+ * two copies of these three failure codes would eventually disagree about what
+ * a malformed artifact is called.
+ */
+export function readEmbeddedIr(html, path) {
+  const payloads = extractIrPayloads(html)
+  if (payloads.length === 0) {
+    throw irError(CODES.IR_MISSING, `no embedded IR found in ${path}; nothing to replay`)
+  }
+  if (payloads.length > 1) {
+    throw irError(CODES.IR_DUPLICATE, `${path} carries ${payloads.length} IR payloads, expected 1`)
+  }
+  try {
+    return JSON.parse(payloads[0])
+  } catch (cause) {
+    throw irError(CODES.IR_UNPARSABLE, `embedded IR in ${path} is not valid JSON: ${cause.message}`)
+  }
+}

package/src/parser/container.js

@@ -0,0 +1,103 @@
+import { containerSyntax } from '../blocks/index.js'
+
+const COLON = 0x3a
+
+/**
+ * markdown-it block rule for the Markdown-superset container fences:
+ *
+ *   :::note                ::::grid
+ *   body                   :::place col=1 colSpan=16
+ *   :::                    左欄。
+ *                          :::
+ *                          ::::
+ *
+ * Which names are legal is **not** written here. A block module declares
+ * `syntax.containers`, and this rule asks the registry — so a third-party
+ * container block needs no parser edit, which was the one surface the F1 slice
+ * left behind (wayfinder issue 13). Emits `kami_container_open` /
+ * `kami_container_close` tokens carrying the whole parameter string in `info`;
+ * splitting name from parameters is the module's business, not the lexer's.
+ *
+ * Modelled on markdown-it-container, including its nesting rule: a fence closes
+ * on a bare colon run at least as long as its own. Unlike the original, nesting
+ * *depth* is counted, so an inner fence of the same length no longer lets its
+ * closing line close the outer one — without that, `:::grid` containing
+ * `:::place` would end at the first `:::` and silently lose everything after it.
+ */
+export function containerPlugin(md) {
+  const rule = (state, startLine, endLine, silent) => {
+    if (state.sCount[startLine] - state.blkIndent >= 4) return false
+
+    let start = state.bMarks[startLine] + state.tShift[startLine]
+    let max = state.eMarks[startLine]
+    if (start + 3 > max) return false
+    if (state.src.charCodeAt(start) !== COLON) return false
+
+    let pos = state.skipChars(start, COLON)
+    const markerLen = pos - start
+    if (markerLen < 3) return false
+
+    const params = state.src.slice(pos, max).trim()
+    const known = containerSyntax()
+    if (!known.has(params.split(/\s+/)[0])) return false
+    if (silent) return true
+
+    let nextLine = startLine
+    let autoClosed = false
+    let depth = 1
+    for (;;) {
+      nextLine += 1
+      if (nextLine >= endLine) break
+      start = state.bMarks[nextLine] + state.tShift[nextLine]
+      max = state.eMarks[nextLine]
+      if (start < max && state.sCount[nextLine] < state.blkIndent) break
+      if (state.src.charCodeAt(start) !== COLON) continue
+      if (state.sCount[nextLine] - state.blkIndent >= 4) continue
+      pos = state.skipChars(start, COLON)
+      if (pos - start < markerLen) continue
+      const rest = state.src.slice(pos, max).trim()
+      if (rest.length > 0) {
+        // An opener of a *recognised* container nests; anything else is text
+        // this rule has no opinion about, and counting it would mis-balance the
+        // very fence it is trying to close.
+        if (known.has(rest.split(/\s+/)[0])) depth += 1
+        continue
+      }
+      depth -= 1
+      if (depth > 0) continue
+      autoClosed = true
+      break
+    }
+
+    const oldParent = state.parentType
+    const oldLineMax = state.lineMax
+    state.parentType = 'kami_container'
+    state.lineMax = nextLine
+
+    const open = state.push('kami_container_open', 'div', 1)
+    open.markup = ':'.repeat(markerLen)
+    open.block = true
+    open.info = params
+    open.map = [startLine, nextLine]
+
+    state.md.block.tokenize(state, startLine + 1, nextLine)
+
+    const close = state.push('kami_container_close', 'div', -1)
+    close.markup = ':'.repeat(markerLen)
+    close.block = true
+
+    state.parentType = oldParent
+    state.lineMax = oldLineMax
+    state.line = nextLine + (autoClosed ? 1 : 0)
+    return true
+  }
+
+  md.block.ruler.before('fence', 'kami_container', rule, {
+    alt: ['paragraph', 'reference', 'blockquote', 'list'],
+  })
+
+  // 刻意不註冊 kami_container 的 renderer rule：container 的標記屬於 block 模組
+  // （src/blocks/<型別>.js 的 render），parser 不得自行產出一份。
+  // 容器 token 一律由 walkTokens 交回宣告它的模組，永遠不會走到 renderer；
+  // 「body 有 callout 標記則 IR 必有 callout block」的反向對稱斷言看守這一點。
+}