@kamishibai/sdk 0.1.1

package/src/render/element.js

@@ -0,0 +1,32 @@
+import { h } from 'vue'
+import { isElement } from '../blocks/element.js'
+
+/**
+ * Neutral element tree → Vue vnodes.
+ *
+ * This is the *only* place the two representations meet, and it is why Vue no
+ * longer appears in `src/core`, in `src/blocks`, or in any template: a block
+ * module hands over `{tag, attrs, children}` data and the render layer decides
+ * what backend draws it. Swapping the backend, or serialising the same tree to
+ * something other than HTML, becomes a change to this file alone.
+ *
+ * Three pass-through rules keep the bytes identical to the hand-written vnodes
+ * this replaced:
+ *
+ *  - `attrs` are handed to `h` verbatim, key order and all — a `null` value is
+ *    how Vue is told to omit the attribute.
+ *  - a `null` child stays `null`, so it still serialises to the empty comment
+ *    node that separates "no element here" from "nothing at all".
+ *  - `html` becomes `innerHTML`, the one prop that carries raw content.
+ */
+export function toVNode(node) {
+  if (node === null || node === undefined) return null
+  if (typeof node === 'string' || typeof node === 'number') return String(node)
+  // Anything else is not a node this contract defines. Drawing it would put a
+  // third party's mistake into the artifact as markup nobody can account for.
+  if (!isElement(node)) return null
+  const { tag, attrs, children, html } = node
+  if (typeof html === 'string') return h(tag, { ...(attrs ?? undefined), innerHTML: html })
+  if (children === undefined || children === null) return h(tag, attrs ?? null)
+  return h(tag, attrs ?? null, Array.isArray(children) ? children.map(toVNode) : toVNode(children))
+}

package/src/render/fonts.js

@@ -0,0 +1,129 @@
+import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+const FACE_RE = /@font-face\s*\{([^}]*)\}/g
+const DECL = (body, prop) => {
+  const m = new RegExp(`${prop}\\s*:\\s*([^;]+);`).exec(body)
+  return m ? m[1].trim() : null
+}
+
+const parseUnicodeRange = (spec) =>
+  spec
+    .split(',')
+    .map((chunk) => chunk.trim().replace(/^U\+/i, ''))
+    .filter((chunk) => chunk.length > 0)
+    .map((chunk) => {
+      const [lo, hi] = chunk.split('-')
+      return { lo: parseInt(lo, 16), hi: parseInt(hi ?? lo, 16) }
+    })
+    .filter((r) => Number.isFinite(r.lo) && Number.isFinite(r.hi))
+
+/** Parse a @fontsource stylesheet into ordered face descriptors. */
+export function parseFontFaces(cssPath) {
+  const css = readFileSync(cssPath, 'utf8')
+  const baseDir = dirname(cssPath)
+  const faces = []
+  let m
+  while ((m = FACE_RE.exec(css)) !== null) {
+    const body = m[1]
+    const unicodeRange = DECL(body, 'unicode-range')
+    const src = DECL(body, 'src')
+    if (unicodeRange === null || src === null) continue
+    const woff2 = /url\(([^)]+\.woff2)\)/.exec(src)
+    if (woff2 === null) continue
+    faces.push({
+      index: faces.length,
+      family: (DECL(body, 'font-family') ?? "'sans-serif'").replace(/^['"]|['"]$/g, ''),
+      style: DECL(body, 'font-style') ?? 'normal',
+      weight: DECL(body, 'font-weight') ?? '400',
+      display: DECL(body, 'font-display') ?? 'swap',
+      unicodeRange,
+      ranges: parseUnicodeRange(unicodeRange),
+      file: resolve(baseDir, woff2[1]),
+    })
+  }
+  return faces
+}
+
+/** Distinct code points used by a rendered document. */
+export function collectCodepoints(...texts) {
+  const points = new Set()
+  for (const text of texts) {
+    if (typeof text !== 'string') continue
+    for (const char of text) points.add(char.codePointAt(0))
+  }
+  return points
+}
+
+const buildIndex = (faces) => {
+  const entries = []
+  for (const face of faces) {
+    for (const range of face.ranges) entries.push({ ...range, face: face.index })
+  }
+  return entries.sort((a, b) => a.lo - b.lo || a.hi - b.hi)
+}
+
+const lookup = (index, cp) => {
+  let lo = 0
+  let hi = index.length - 1
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1
+    if (cp < index[mid].lo) hi = mid - 1
+    else if (cp > index[mid].hi) lo = mid + 1
+    else return index[mid].face
+  }
+  return -1
+}
+
+/** Faces whose unicode-range intersects the used code points, in file order. */
+export function selectFaces(faces, codepoints) {
+  const index = buildIndex(faces)
+  const used = new Set()
+  for (const cp of codepoints) {
+    const hit = lookup(index, cp)
+    if (hit !== -1) used.add(hit)
+  }
+  return faces.filter((face) => used.has(face.index))
+}
+
+const faceCss = (face) => {
+  const data = readFileSync(face.file).toString('base64')
+  return [
+    '@font-face{',
+    `font-family:'${face.family}';`,
+    `font-style:${face.style};`,
+    `font-display:${face.display};`,
+    `font-weight:${face.weight};`,
+    `src:url(data:font/woff2;base64,${data}) format('woff2');`,
+    `unicode-range:${face.unicodeRange};`,
+    '}',
+  ].join('')
+}
+
+/**
+ * Build the @font-face CSS for a template's font specs, embedding only the
+ * subset chunks whose unicode-range intersects the document's characters.
+ *
+ * @param {Array<{package: string, weights: string[]}>} specs
+ * @param {Set<number>} codepoints
+ * @returns {{css: string, embedded: number, available: number}}
+ */
+export function embedFontSubset(specs, codepoints) {
+  const parts = []
+  let embedded = 0
+  let available = 0
+  for (const spec of specs) {
+    for (const weight of spec.weights) {
+      const cssPath = require.resolve(`${spec.package}/${weight}.css`)
+      const faces = parseFontFaces(cssPath)
+      available += faces.length
+      const selected = selectFaces(faces, codepoints)
+      embedded += selected.length
+      for (const face of selected) parts.push(faceCss(face))
+    }
+  }
+  return { css: parts.join('\n'), embedded, available }
+}

package/src/render/graph-hover.client.js

@@ -0,0 +1,148 @@
+/*
+ * Graph dependency highlight (SPEC section 3.4, wayfinder issue 11 P5
+ * "graph hover highlight").
+ *
+ * A block-keyed client asset: the render layer embeds it only into artifacts
+ * that actually contain a `graph` 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/graph.js` and read here: the
+ * adjacency is already in the markup (`data-node-id` on a node,
+ * `data-edge-from` / `data-edge-to` on an edge), so this file computes no graph
+ * of its own -- there is no second model that could disagree with the picture.
+ * Keyboard focus is wired alongside the pointer because a highlight only
+ * pointing devices can reach is a highlight half the readers never get.
+ * Without JS every node and edge simply stays at full strength.
+ *
+ * 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 () {
+  /*
+   * The floor: what an unpainted graph has to look like to be a graph at all.
+   *
+   * SVG presentation defaults are `fill: black; stroke: none`, and every one of
+   * them is wrong for this picture: the node box is painted solid black, the
+   * label is painted black *inside* that box (black on black -- the label rect
+   * sits entirely within the box rect), and an edge, which is an open bezier,
+   * is filled rather than stroked, so it draws as a black blob instead of a
+   * line. Measured in real Chromium on the article path: box fill rgb(0,0,0),
+   * label fill rgb(0,0,0), edge-line fill rgb(0,0,0) / stroke none. None of the
+   * five shipped Kami skins matches a single one of these selectors.
+   *
+   * So this is the same sentence the dimming rules below already carry, applied
+   * one level down: when the skin has painted nothing, "invisible" and "never
+   * ran" are the same picture -- and here it is the *content* that disappears,
+   * not just the interaction.
+   *
+   * Two disciplines make this a floor rather than a ceiling:
+   *
+   *  - `:where()` zeroes the specificity, so any template rule on the same hook
+   *    wins no matter that this stylesheet is appended last. Paint stays the
+   *    template's (wayfinder issue 13, the three-way split of template duty);
+   *    this only refuses to leave the page blank when nobody painted.
+   *  - `currentColor` rather than a colour of its own, so the graph inherits
+   *    whatever ink the surrounding page already uses. The SDK names no colour.
+   */
+  var BASE_RULES =
+    ':where(.graph-edge-line){fill:none;stroke:currentColor}' +
+    ':where(.graph-arrow){fill:currentColor;stroke:none}' +
+    ':where(.graph-edge-label){fill:currentColor;stroke:none}' +
+    ':where(.graph-node-box){fill:none;stroke:currentColor}' +
+    ':where(.graph-node-label){fill:currentColor;stroke:none}'
+  var DIM_RULES =
+    '.graph.is-hovering .graph-edge:not(.is-linked){opacity:0.2}' +
+    '.graph.is-hovering .graph-node:not(.is-active):not(.is-linked){opacity:0.3}'
+  var graphs = Array.prototype.slice.call(document.querySelectorAll('.graph[data-graph]'))
+  if (graphs.length === 0) return
+
+  /*
+   * The dimming ships with the behaviour, not with the skin.
+   *
+   * A template is free to paint `.is-active` and `.is-linked` however it likes,
+   * but if nobody paints anything the class flip is invisible -- and an
+   * invisible highlight is indistinguishable from a script that never ran.
+   *
+   * Both blocks are injected from the same element and behind the same
+   * condition (a document with no graph gets neither, and no style element at
+   * all), so readability and behaviour can never arrive separately.
+   */
+  var rules = document.createElement('style')
+  rules.textContent = BASE_RULES + DIM_RULES
+  document.head.appendChild(rules)
+
+  function clear(graph) {
+    graph.classList.remove('is-hovering')
+    var marked = Array.prototype.slice.call(graph.querySelectorAll('.is-active, .is-linked'))
+    for (var i = 0; i < marked.length; i += 1) {
+      marked[i].classList.remove('is-active')
+      marked[i].classList.remove('is-linked')
+    }
+  }
+
+  function highlight(graph, id) {
+    clear(graph)
+    /*
+     * A list, not an object used as a set: a node whose id happens to be
+     * `constructor` or `toString` would test truthy against a bare object
+     * literal without anyone ever having put it there, and would then light up
+     * as a neighbour of every node in the graph.
+     */
+    var neighbours = []
+    var edges = Array.prototype.slice.call(graph.querySelectorAll('.graph-edge'))
+    for (var i = 0; i < edges.length; i += 1) {
+      var from = edges[i].getAttribute('data-edge-from')
+      var to = edges[i].getAttribute('data-edge-to')
+      if (from !== id && to !== id) continue
+      edges[i].classList.add('is-linked')
+      neighbours.push(from)
+      neighbours.push(to)
+    }
+    var nodes = Array.prototype.slice.call(graph.querySelectorAll('.graph-node'))
+    for (var j = 0; j < nodes.length; j += 1) {
+      var name = nodes[j].getAttribute('data-node-id')
+      if (name === id) nodes[j].classList.add('is-active')
+      else if (neighbours.indexOf(name) !== -1) nodes[j].classList.add('is-linked')
+    }
+    graph.classList.add('is-hovering')
+  }
+
+  for (var g = 0; g < graphs.length; g += 1) {
+    (function (graph) {
+      var nodes = Array.prototype.slice.call(graph.querySelectorAll('.graph-node'))
+      for (var k = 0; k < nodes.length; k += 1) {
+        (function (node) {
+          var id = node.getAttribute('data-node-id')
+          node.addEventListener('mouseenter', function () {
+            highlight(graph, id)
+          })
+          node.addEventListener('focus', function () {
+            highlight(graph, id)
+          })
+          node.addEventListener('mouseleave', function () {
+            clear(graph)
+          })
+          node.addEventListener('blur', function () {
+            clear(graph)
+          })
+        })(nodes[k])
+      }
+    })(graphs[g])
+  }
+})()

package/src/render/html.js

@@ -0,0 +1,52 @@
+import { IR_SCRIPT_TYPE } from '../core/ir.js'
+
+export { IR_SCRIPT_TYPE }
+
+const ESCAPES = Object.freeze({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })
+
+export const escapeHtml = (value) => String(value ?? '').replace(/[&<>"]/g, (c) => ESCAPES[c])
+
+/**
+ * Serialise the IR for embedding inside a <script> element.
+ *
+ * Both `</` (ends the element early) and `<!--` (opens an HTML comment state)
+ * are hazards, and every one of them starts with `<`. Escaping `<` itself as
+ * `<` neutralises the whole class at once — and unlike `\/` or `\!`, it is
+ * a legal JSON escape in *any* position, so the payload always parses back.
+ * `\!` is not a valid escape at all and silently corrupted the IR (CONTRACT A2).
+ */
+export const serializeIr = (ir) => JSON.stringify(ir).replace(/</g, '\\u003c')
+
+/**
+ * Assemble the single-file artifact. Nothing here depends on file paths (A8).
+ *
+ * `script` is the template's own inlined behaviour (playback chrome, SPEC §7.4).
+ * It is emitted without a `src`, so the零外部請求 rules see nothing to flag, and
+ * it sits outside the IR payload so `liveMarkup` still judges it as live markup.
+ * Templates without behaviour emit no element at all, which is what keeps their
+ * artifacts byte-identical to the pre-S3a bytes.
+ */
+export function assembleDocument({ language, title, styles, fontCss, body, script, ir }) {
+  const behaviour = typeof script === 'string' && script.length > 0 ? [`<script>${script}</script>`] : []
+  return [
+    '<!doctype html>',
+    `<html lang="${escapeHtml(language)}">`,
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<meta name="generator" content="${escapeHtml(`kamishibai ${ir.engine}`)}">`,
+    `<title>${escapeHtml(title)}</title>`,
+    '<style>',
+    fontCss,
+    styles,
+    '</style>',
+    '</head>',
+    '<body>',
+    body,
+    ...behaviour,
+    `<script type="${IR_SCRIPT_TYPE}">${serializeIr(ir)}</script>`,
+    '</body>',
+    '</html>',
+    '',
+  ].join('\n')
+}

package/src/render/index.js

@@ -0,0 +1,241 @@
+import { buildIr } from '../core/ir.js'
+import { findDeck, walkBlocks } from '../core/blocks.js'
+import { assertTemplateVocabulary } from '../core/vocabulary.js'
+import { layoutGraph } from '../core/diagram.js'
+import { assertBlockSpecs } from '../core/spec-check.js'
+import { CODES, validationError } from '../core/errors.js'
+import {
+  canvasProblems,
+  knownLayouts,
+  resolveCanvas,
+  resolveLayout,
+} from '../layouts/index.js'
+import { resolveTemplate } from './templates.js'
+import { createRenderContext } from './context.js'
+import { renderBody } from './ssr.js'
+import { artifactScript } from './skeleton.js'
+import { availableWidths } from './measure.js'
+import { assertPlacement } from './placement.js'
+import { injectLayoutVars } from './styles.js'
+import { collectCodepoints, embedFontSubset } from './fonts.js'
+import { assembleDocument } from './html.js'
+
+export {
+  availableTemplateKeys,
+  builtinManifests,
+  isReservedKey,
+  listTemplateKeys,
+  registerTemplateSource,
+  reservedNamespaces,
+  resetTemplateSources,
+  resolveTemplate,
+} from './templates.js'
+export { IR_SCRIPT_TYPE } from './html.js'
+
+/**
+ * The block types whose picture is laid out by the SDK rather than by the
+ * block: `diagram` (SPEC §3.1) and, since F6a, the core `graph` (issue 11 P1).
+ *
+ * Both draw a node-and-edge picture from the same engine, which is the whole
+ * reason the list exists here rather than as a flag on the module: layout needs
+ * the width the page gives the block, so it cannot be a block-level fact, and a
+ * *second* list of "who needs measuring" living inside the blocks layer would
+ * be a fact the render layer could disagree with.
+ */
+const LAID_OUT_TYPES = Object.freeze(['diagram', 'graph'])
+
+/**
+ * Measure every laid-out block in the document before anything is drawn.
+ *
+ * Layout is not a block-level fact — it needs the width the page gives the
+ * block, which is a layout-layer concern the block cannot see (wayfinder issue
+ * 13 試金石). Computing it here, once, is also what keeps the two Kami
+ * templates drawing the *same* picture from the same spec: a layout computed
+ * inside the renderer would be one layout per template.
+ *
+ * Since F2a the width is per block rather than per document: a diagram sitting
+ * in 8 of 24 columns is measured against those 8 columns, so it is drawn narrow
+ * instead of being drawn wide and then squeezed (量測報告 §4.2).
+ *
+ * @returns {Map<string, object>} block id → layout
+ */
+function measureLaidOutGraphs(doc, widths, canvas) {
+  const layouts = new Map()
+  for (const { block } of walkBlocks(doc)) {
+    if (!LAID_OUT_TYPES.includes(block?.type)) continue
+    const measure = widths.get(block.id) ?? canvas.measure
+    layouts.set(block.id, layoutGraph(block, { measure }))
+  }
+  return layouts
+}
+
+/**
+ * The 文體 this template is drawn in, refused loudly when nobody registered it.
+ *
+ * A missing layout cannot be defaulted away: the root form, the canvas and the
+ * slot vocabulary all come from it, so guessing would draw *some* artifact and
+ * call it this template's.
+ */
+function layoutFor(manifest, key) {
+  const layout = resolveLayout(manifest)
+  if (layout === undefined) {
+    throw validationError(
+      `template "${key}" 宣告的 layout \`${manifest.layout}\` 沒有人註冊；` +
+        `已註冊的文體：${knownLayouts().join(', ')}。`,
+      CODES.LAYOUT_NOT_FOUND,
+      'doc',
+    )
+  }
+  return layout
+}
+
+/**
+ * A template may only fill slots its layout offers.
+ *
+ * An unfilled slot is silence and a *misspelled* one is also silence — the
+ * chrome simply never appears, the artifact renders, and `lint` says nothing.
+ * That is the same invisible data-loss shape `manifest.blocks` exists to
+ * refuse, so it is refused the same way.
+ */
+function assertChromeSlots(template, layout, key) {
+  const filled = Object.keys(template.chrome ?? {})
+  const unknown = filled.filter((slot) => !layout.slots.includes(slot))
+  if (unknown.length === 0) return
+  throw validationError(
+    `template "${key}" 填了 layout \`${layout.name}\` 沒有的槽位：${unknown.join(', ')}；` +
+      `該文體提供：${layout.slots.join(', ') || '（無）'}。` +
+      '拼錯的槽位不會報錯、只會不出現——所以在這裡報。',
+    CODES.LAYOUT_SLOT_UNKNOWN,
+    'doc',
+  )
+}
+
+/**
+ * A template may restate its 文體's root form, and may not disagree with it.
+ *
+ * `manifest.root` predates layouts: it was where `kami/slides` said "this
+ * template only draws decks". Since that requirement belongs to the 文體, the
+ * field is now a restatement — and a restatement that disagrees is the most
+ * dangerous shape available here, because it *reads* like a template being
+ * careful. A `root: 'section'` on the `deck` layout would satisfy every guard
+ * and then hand a section-rooted document to a root form that looks for a deck
+ * and finds nothing: an artifact with an empty body and a playback script
+ * bolted to it, exit 0, `lint` 0.
+ *
+ * So the two must be the same sentence, in both directions — a template may not
+ * loosen its 文體's requirement, and may not invent one its 文體 does not have.
+ */
+function assertLayoutRootForm(manifest, layout, key) {
+  const declared = manifest.root ?? null
+  const required = layout.rootForm ?? null
+  if (declared === required) return
+  const say = (value) => (value === null ? '無根形要求' : `\`${value}\``)
+  throw validationError(
+    `template "${key}" 宣告根形 ${say(declared)}，但所屬 layout \`${layout.name}\` ` +
+      `要求 ${say(required)}。根形是文體的，模板只能複述、不能改寫或放寬——` +
+      '改寫得逞的產物會是「body 空白但帶著播放腳本」的殭屍，而且 exit 0。',
+    CODES.LAYOUT_ROOT_CONFLICT,
+    'doc',
+  )
+}
+
+/** The applied canvas geometry, refused loudly when it contradicts itself (C3). */
+function canvasFor(layout, manifest) {
+  const canvas = resolveCanvas(layout, manifest)
+  const problems = canvasProblems(canvas, layout, manifest)
+  if (problems.length > 0) {
+    throw validationError(problems.join('；'), CODES.LAYOUT_CANVAS_INVALID, 'doc')
+  }
+  return canvas
+}
+
+/**
+ * Render a canonical doc block tree with an already-resolved template package.
+ *
+ * The seam exists because a template is not always something `resolveTemplate`
+ * can find: a store-loaded package, a third-party layout's own built-in
+ * template, or a test's synthetic one all have to reach the same pipeline —
+ * the *same* one, not a re-implementation that could disagree with it.
+ */
+export async function renderWithTemplatePackage({ template, doc, createdAt, generator }) {
+  const key = `${template.manifest.namespace}/${template.manifest.name}`
+  const layout = layoutFor(template.manifest, key)
+  assertLayoutRootForm(template.manifest, layout, key)
+  assertChromeSlots(template, layout, key)
+  const canvas = canvasFor(layout, template.manifest)
+
+  // Before a single byte is drawn: a template that cannot express this document
+  // must fail loudly. Skipping unknown types is what a renderer does; doing it
+  // as the *only* answer turns a wrong `-t` into a silently empty artifact (C4).
+  assertTemplateVocabulary({ doc, manifest: template.manifest, layout })
+  // A block whose spec cannot be drawn is rejected here rather than turned into
+  // an empty SVG: a picture that silently disagrees with its spec is the one
+  // failure a reader cannot detect (CONTRACT D2). Every block checks its own.
+  assertBlockSpecs(doc)
+  // …and a coordinate that cannot mean anything where it sits is refused too,
+  // because no block can see where it sits (CONTRACT C2).
+  assertPlacement(doc, canvas)
+
+  const ir = buildIr({ doc, template: template.manifest, createdAt, generator })
+
+  const widths = availableWidths(doc, canvas)
+  const layouts = measureLaidOutGraphs(doc, widths, canvas)
+  const ctx = createRenderContext({
+    template,
+    doc,
+    layouts,
+    canvas,
+    // 轉子 override is *this* package's answer for a type the SDK already has
+    // (CONTRACT D3). It arrives here rather than in the block registry because
+    // the registry is global: an installed package that overrode `callout`
+    // there would silently change how every other template draws one.
+    overrides: template.overrides,
+  })
+  const body = await renderBody(layout.root, doc, ctx)
+  // Geometry flows from config into the stylesheet, never the other way (C3).
+  const styles = injectLayoutVars(template.styles(), canvas)
+  // Behaviour comes from the skeleton and from the blocks themselves, never
+  // from the template: a deck that could opt out of paging would ship as an
+  // unusable deck (issue 13 P3), and a board whose lanes could not be filtered
+  // would be a board missing the one interaction its ticket promised (11 P5).
+  const script = artifactScript(layout, doc)
+
+  const codepoints = collectCodepoints(body, styles, script, doc.meta?.title, doc.meta?.kicker)
+  const { css: fontCss, embedded, available } = embedFontSubset(template.fonts, codepoints)
+
+  const html = assembleDocument({
+    language: template.language,
+    title: doc.meta?.title ?? 'Untitled',
+    styles,
+    fontCss,
+    body,
+    script,
+    ir,
+  })
+
+  const deck = findDeck(doc)
+
+  return {
+    html,
+    ir,
+    fonts: { embedded, available },
+    slides: deck === undefined ? undefined : deck.slides.length,
+  }
+}
+
+/**
+ * Render a canonical doc block tree into a self-contained single-file artifact.
+ * Pure with respect to the filesystem destination — nothing about the output
+ * path enters the artifact, which is what keeps renders byte-identical (A8).
+ *
+ * `slides` is present only for deck artifacts, and is read off the block tree
+ * rather than off the parse: `replay` rebuilds from the embedded IR alone, so a
+ * count derived from the source would simply vanish on the replay path.
+ *
+ * @returns {Promise<{html: string, ir: object, fonts: {embedded: number, available: number},
+ *   slides: number|undefined}>}
+ */
+export async function renderArtifact({ doc, templateKey, createdAt, generator }) {
+  const template = await resolveTemplate(templateKey)
+  return await renderWithTemplatePackage({ template, doc, createdAt, generator })
+}

package/src/render/measure.js

@@ -0,0 +1,60 @@
+import { blockArrayKeys, blockMatrixKeys } from '../core/blocks.js'
+import { hasPlacement, placedWidth } from '../blocks/placement.js'
+
+/**
+ * How much width the page actually gives each block.
+ *
+ * `core/diagram.js` was tuned against 740px and could not see that number: a
+ * diagram dropped into a narrow column was squeezed until its labels stopped
+ * being readable, and nothing in the pipeline could tell (量測報告 §4.2). F1
+ * turned the assumption into a parameter; this is the layer that finally knows
+ * what to pass — 「diagram 一律收實際可用寬」 (wayfinder issue 14 裁決 3).
+ *
+ * The rule is one line of arithmetic and deliberately stays that way: a block
+ * that **carries a placement** gets its span's worth of the width around it;
+ * every other block gets that width whole. No text measurement, no percentages
+ * resolved against a viewport — the same document must produce the same bytes
+ * on any machine (CONTRACT D1).
+ *
+ * The rule used to be phrased as 「inside a `grid` container」 instead, which was
+ * the same rule while a `grid` was the only place a coordinate could exist: an
+ * unplaced child of a grid spans all 24 columns, so `placedWidth` already
+ * returned the full width for it. Since F2f a `gridAddressed` layout lays tracks
+ * of its own (a slide's content region), and a container test would have gone
+ * blind exactly there — the diagram in 8 of 24 columns of a slide would be
+ * measured against the whole page and then squeezed, which is 量測報告 §4.2
+ * happening a second time in a new place.
+ */
+
+/**
+ * Block id → available width in CSS pixels, for every block in the tree.
+ *
+ * @param {object} doc the canonical doc block tree
+ * @param {{measure: number}} canvas the resolved canvas of this artifact
+ * @returns {Map<string, number>}
+ */
+export function availableWidths(doc, { measure }) {
+  const arrays = blockArrayKeys()
+  const matrices = blockMatrixKeys()
+  const widths = new Map()
+
+  const visit = (node, available) => {
+    if (node === null || typeof node !== 'object') return
+    if (typeof node.id === 'string') widths.set(node.id, available)
+    const childWidth = (child) => (hasPlacement(child) ? placedWidth(available, child) : available)
+    for (const key of matrices) {
+      if (!Array.isArray(node[key])) continue
+      for (const group of node[key]) {
+        if (!Array.isArray(group)) continue
+        for (const child of group) visit(child, childWidth(child))
+      }
+    }
+    for (const key of arrays) {
+      if (!Array.isArray(node[key])) continue
+      for (const child of node[key]) visit(child, childWidth(child))
+    }
+  }
+
+  visit(doc, measure)
+  return widths
+}