@kamishibai/sdk 0.1.1

package/src/render/placement.js

@@ -0,0 +1,136 @@
+import { blockArrayKeys, blockMatrixKeys } from '../core/blocks.js'
+import { CODES, validationError } from '../core/errors.js'
+import { GRID_COLUMNS, PLACEMENT_KEYS, hasPlacement, placementProblems } from '../blocks/placement.js'
+import { GRID_ADDRESSED_FIELD } from '../layouts/index.js'
+
+/**
+ * Where a 24-grid coordinate is allowed to mean anything.
+ *
+ * There are exactly two such places: inside an explicit `grid` container, and
+ * inside a layout that has **declared** its whole page addressable by grid
+ * coordinates (`gridAddressed`). Everywhere else a coordinate names a cell that
+ * does not exist, and CSS auto-placement drops it without a word — so the
+ * artifact renders, `lint` returns 0, and the layout is quietly not the one the
+ * author wrote.
+ *
+ * `:::place col=1 colSpan=8` under `kami/long-form` was exactly that: it passed
+ * every gate and the coordinates evaporated. Columns are not gentler than rows
+ * here — a span nobody applies is as invisible as a row nobody has — so **any**
+ * placement outside those two places is refused, which is the failure mode
+ * `KSB_PLACEMENT_INVALID`'s own wording condemns.
+ *
+ * **`bounded` is not the licence.** An earlier version of this gate exempted
+ * every bounded canvas, on the reasoning that a fixed logical page "is" a grid.
+ * It was not one: `bounded` says only that the canvas has a fixed size and gets
+ * scaled to fit, and it says nothing about anyone laying down the 24 tracks a
+ * bare `col: 1` would have to resolve against. Exempting it would therefore
+ * have re-opened the hole in the one place hardest to notice — the artifact
+ * scales beautifully and the coordinate is gone. The licence stays a claim a
+ * layout makes on purpose. Since F2f exactly one factory layout makes it:
+ * `deck`, whose slides lay the tracks (`src/blocks/slide.js`) — the claim and
+ * the tracks landed in the same slice, which is the only way it may be made.
+ *
+ * The exemption is **whole-page**, as F2a defined it: a layout that says the
+ * page is addressable says it about the page, not about one container in it.
+ * What the exemption is not is a hole — the relational rule still runs on the
+ * exempt path (`assertRelations` below), which is the half F2a deferred here.
+ *
+ * No block can check any of this for itself: it depends on the enclosing
+ * container *and* on the artifact's layout, neither of which is visible from
+ * inside a block module. Hence a gate at the layer that knows both, run before
+ * a byte is drawn — the same shape as `assertBlockSpecs`, for the same reason.
+ */
+
+const GRID_TYPE = 'grid'
+
+const carried = (block) => PLACEMENT_KEYS.filter((key) => block?.[key] !== undefined && block[key] !== null)
+
+/**
+ * Walk every block in the tree, handing each one its own path.
+ *
+ * Shared by both gates below so they can never disagree about what a block's
+ * path is: a refusal that names `doc.children[0].slides[1].children[0]` is only
+ * actionable if it is the same string an author would get from the other gate.
+ */
+function visitBlocks(doc, arrays, matrices, visit) {
+  const walk = (node, path, inGrid) => {
+    if (node === null || typeof node !== 'object') return
+    visit(node, path, inGrid)
+    const childInGrid = node.type === GRID_TYPE
+    for (const key of matrices) {
+      if (!Array.isArray(node[key])) continue
+      for (const [group, blocks] of node[key].entries()) {
+        if (!Array.isArray(blocks)) continue
+        for (const [index, child] of blocks.entries()) {
+          walk(child, `${path}.${key}[${group}][${index}]`, childInGrid)
+        }
+      }
+    }
+    for (const key of arrays) {
+      if (!Array.isArray(node[key])) continue
+      for (const [index, child] of node[key].entries()) {
+        walk(child, `${path}.${key}[${index}]`, childInGrid)
+      }
+    }
+  }
+  walk(doc, 'doc', false)
+}
+
+/**
+ * The **relational** rule on the exempt path — F2a's deferred half (終驗遞延).
+ *
+ * `col + colSpan - 1 ≤ 24` cannot be said in JSON Schema, so it is checked by
+ * the `grid` module's own `validate` — which only ever runs for `grid` blocks.
+ * The moment a layout declares `gridAddressed`, coordinates become legal
+ * *outside* any grid container, and that check stops running on them: F2a's
+ * gate returned at the first line and nothing downstream looked again. So on a
+ * grid-addressed page `col: 20 colSpan: 8` passed every gate and was then
+ * clamped by CSS to the 24th column — an artifact whose layout is silently not
+ * the one the author wrote, which is precisely what the refusal below condemns.
+ *
+ * Two defences, each pinned on its own: JSON Schema refuses a coordinate
+ * *outside* 1..24 with a block path (`KSB_IR_SCHEMA`), and this refuses a
+ * coordinate whose span *ends* outside them.
+ */
+function assertRelations(doc, canvas, arrays, matrices) {
+  visitBlocks(doc, arrays, matrices, (node, path, inGrid) => {
+    // Inside a grid container the grid module already said it, in its own
+    // wording. Saying it twice would give one mistake two sentences.
+    if (inGrid || !hasPlacement(node)) return
+    const problems = placementProblems(path, node)
+    if (problems.length === 0) return
+    throw validationError(
+      `擺位非法：${problems.join('；')}。` +
+        `layout \`${canvas?.layout}\` 宣告自己是格軌定址畫布（\`${GRID_ADDRESSED_FIELD}\`），` +
+        `整頁就是那 ${GRID_COLUMNS} 格——越界即報錯：` +
+        '靜默夾持會讓版面悄悄不是作者寫的那一個。',
+      CODES.PLACEMENT_INVALID,
+      path,
+    )
+  })
+}
+
+/**
+ * @throws {import('../core/errors.js').KsbError} exit 1 / KSB_PLACEMENT_INVALID
+ */
+export function assertPlacement(doc, canvas) {
+  const arrays = blockArrayKeys()
+  const matrices = blockMatrixKeys()
+  if (canvas?.[GRID_ADDRESSED_FIELD] === true) {
+    assertRelations(doc, canvas, arrays, matrices)
+    return
+  }
+
+  visitBlocks(doc, arrays, matrices, (node, path, inGrid) => {
+    if (inGrid || !hasPlacement(node)) return
+    throw validationError(
+      `${path} 帶擺位（${carried(node).join('／')}），但它既不在 grid 容器內，` +
+        `所屬 layout \`${canvas?.layout}\` 也沒有宣告自己是格軌定址畫布` +
+        `（\`${GRID_ADDRESSED_FIELD}\`）。` +
+        '24 格座標只有在版面真的鋪了那些格軌時才指得到東西——沒鋪的版面裡它會被 ' +
+        'CSS 自動排版靜默忽略，於是作者寫的擺位與看到的版面不是同一個。',
+      CODES.PLACEMENT_INVALID,
+      path,
+    )
+  })
+}

package/src/render/playback.client.js

@@ -0,0 +1,74 @@
+/*
+ * Kami slides playback (SPEC section 7.4, CONTRACT C5).
+ *
+ * A template-layer asset, not a raw island: it ships with the template and is
+ * inlined by the render layer, which is what lets SPEC section 11 ban script
+ * elements *inside islands* -- interaction is a component concern, never
+ * hand-written escape-hatch markup.
+ *
+ * Every character here is ASCII, and that is a size decision rather than a
+ * stylistic one: the skeleton 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. Pinned across all six scanned
+ * surfaces 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.
+ * Comparison operators mean a bare left angle bracket does appear below. What
+ * must never appear -- in the code or, as this very sentence once proved, in a
+ * comment warning against it -- is any of the four sequences banned by
+ * `test_f2g_skeleton_assets_cannot_derail_the_parser`: naming two of them here
+ * and in the sibling skeleton asset was enough to make the parser read every
+ * deck artifact as one script element running to the end of the file, so that
+ * neither asset ever ran (CONTRACT F2g H2). Without JS every slide simply stays
+ * visible and the deck reads as a scrolling document.
+ */
+(function () {
+  var deck = document.querySelector('.deck')
+  if (!deck) return
+  var slides = Array.prototype.slice.call(deck.querySelectorAll('.slide'))
+  if (slides.length === 0) return
+
+  var progress = deck.querySelector('.deck-progress')
+  var index = 0
+
+  function show(next) {
+    index = Math.max(0, Math.min(slides.length - 1, next))
+    for (var i = 0; i < slides.length; i += 1) {
+      var current = i === index
+      slides[i].classList.toggle('is-current', current)
+      slides[i].setAttribute('aria-hidden', current ? 'false' : 'true')
+    }
+    if (progress) progress.textContent = index + 1 + ' / ' + slides.length
+  }
+
+  function enterFullscreen() {
+    var target = document.documentElement
+    if (document.fullscreenElement) return
+    if (target.requestFullscreen) target.requestFullscreen()
+  }
+
+  function exitFullscreen() {
+    if (document.fullscreenElement && document.exitFullscreen) document.exitFullscreen()
+  }
+
+  document.addEventListener('keydown', function (event) {
+    if (event.metaKey || event.ctrlKey || event.altKey) return
+    var key = event.key
+    if (key === 'ArrowRight' || key === ' ' || key === 'Spacebar' || key === 'PageDown') {
+      event.preventDefault()
+      show(index + 1)
+    } else if (key === 'ArrowLeft' || key === 'PageUp') {
+      event.preventDefault()
+      show(index - 1)
+    } else if (key === 'f' || key === 'F') {
+      event.preventDefault()
+      enterFullscreen()
+    } else if (key === 'Escape' || key === 'Esc') {
+      exitFullscreen()
+    }
+  })
+
+  deck.classList.add('is-live')
+  show(0)
+})()

package/src/render/scale-to-fit.client.js

@@ -0,0 +1,136 @@
+/**
+ * Skeleton asset: keep every bounded canvas exactly as large as it can be.
+ *
+ * Embedded verbatim into any artifact whose layout declares a bounded canvas,
+ * so a single edited character moves that artifact's bytes. It assumes nothing
+ * about the page beyond the canvas attribute -- a bounded layout this file has
+ * never heard of is scaled by it all the same, and gets the same flow geometry
+ * and the same print behaviour without having to ask for either.
+ *
+ * ## Nothing written here may perturb the HTML tokenizer (CONTRACT F2g H2)
+ *
+ * The four sequences banned by `test_f2g_skeleton_assets_cannot_derail_the_parser`
+ * are banned in comments too, and that is not pedantry. This file used to spell
+ * one of them out in this very paragraph, inside a sentence warning against it,
+ * while the sibling skeleton asset spelled out another in its own header. Apart
+ * they were harmless; together they walked the parser into its double-escaped
+ * state, where the end tag that should have closed the script is ordinary text.
+ * Every artifact carrying both assets therefore shipped a single script element
+ * that swallowed the rest of the document, embedded IR and all -- so neither
+ * asset ran at all, at any window size, and the artifact still looked plausible
+ * because a canvas that is never scaled is simply a canvas at scale 1.
+ *
+ * ## One scalar for both axes
+ *
+ * Fitting each axis separately would fill the window and stretch the type,
+ * which is the one outcome worse than a black border.
+ *
+ * ## A transform does not move the flow box (CONTRACT F2g H1)
+ *
+ * `transform` changes what is painted, never what the layout reserves, so a
+ * canvas scaled by k goes on occupying its unscaled height. Where one canvas
+ * fills the window that is invisible; where several are stacked in one host it
+ * is the whole geometry. Measured on a real browser before this was fixed: at
+ * k = 1.2 each canvas overflowed 180px into the next one and the content
+ * underneath became unclickable, and at k = 0.27 the same arithmetic opened
+ * 656px of dead space instead. So the advance owes the difference,
+ * `h * scale - h`, and margin-bottom is where that debt is paid: positive when
+ * the canvas grew, negative when it shrank, zero at k = 1. What is left is a
+ * gap of exactly nothing, which is the only gap that does not change meaning
+ * when everything beside it is scaled.
+ *
+ * ## Where a canvas centres itself
+ *
+ * In the space it is given -- and it is given the whole window only when it is
+ * the one canvas rendered in its host. Horizontally that always holds, so the
+ * horizontal offset is unconditional. Vertically it holds for a paged artifact
+ * (one page shown, the others not rendered) and fails for a stack, where
+ * centring each canvas in the window *is* the dead space above it. The test is
+ * structural on purpose: this file may not learn the name of a layout in order
+ * to lay it out.
+ */
+;(function () {
+  var ATTR = 'data-ksb-canvas'
+  var SCALE_ATTR = 'data-ksb-scale'
+
+  /*
+   * On paper the canvas is drawn at its natural size, so the transform and the
+   * flow correction that pays for it stand down together -- keeping one without
+   * the other would space the canvases by the very difference it corrects. The
+   * rule is written from here, not left to the stylesheet, because a skin that
+   * never wrote a print block is exactly the case this file exists to cover.
+   */
+  var standDown = document.createElement('style')
+  standDown.textContent =
+    '@media print{[' + ATTR + ']{transform:none !important;margin-bottom:0 !important}}'
+  ;(document.head || document.documentElement).appendChild(standDown)
+
+  /**
+   * What every canvas on the page should become -- read in full before any of
+   * them moves, because moving one can take a scrollbar with it and change what
+   * the next one would have measured.
+   */
+  function plan() {
+    var nodes = document.querySelectorAll('[' + ATTR + ']')
+    var steps = []
+    for (var i = 0; i < nodes.length; i += 1) {
+      var node = nodes[i]
+      var size = String(node.getAttribute(ATTR) || '').split('x')
+      var w = Number(size[0])
+      var h = Number(size[1])
+      if (!(w > 0) || !(h > 0)) continue
+      var host = node.parentNode
+      var vw = host && host.clientWidth ? host.clientWidth : window.innerWidth
+      var vh = window.innerHeight
+      var scale = Math.min(vw / w, vh / h)
+      steps.push({
+        node: node,
+        host: host,
+        /* Empty exactly when the box is not rendered: how a paged artifact says
+           that its other pages are not on screen at the moment. */
+        shown: node.getClientRects().length > 0,
+        scale: scale,
+        offsetX: (vw - w * scale) / 2,
+        offsetY: (vh - h * scale) / 2,
+        advance: h * scale - h,
+      })
+    }
+    return steps
+  }
+
+  /** Whether no other rendered canvas shares this one's host. */
+  function alone(steps, step) {
+    for (var i = 0; i < steps.length; i += 1) {
+      if (steps[i] !== step && steps[i].host === step.host && steps[i].shown) return false
+    }
+    return true
+  }
+
+  function fit() {
+    var steps = plan()
+    for (var i = 0; i < steps.length; i += 1) {
+      var step = steps[i]
+      var scale = step.scale
+      var x = step.offsetX
+      var y = alone(steps, step) ? step.offsetY : 0
+      step.node.style.transformOrigin = 'top left'
+      step.node.style.transform = 'translate(' + x + 'px, ' + y + 'px) scale(' + scale + ')'
+      step.node.style.marginBottom = step.advance + 'px'
+      step.node.setAttribute(SCALE_ATTR, String(scale))
+    }
+  }
+
+  window.addEventListener('resize', fit)
+  document.addEventListener('fullscreenchange', fit)
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', fit)
+  } else {
+    fit()
+  }
+
+  document.addEventListener('keydown', function (event) {
+    if (event.key !== 'f' && event.key !== 'F') return
+    if (document.fullscreenElement) document.exitFullscreen()
+    else if (document.documentElement.requestFullscreen) document.documentElement.requestFullscreen()
+  })
+})()

package/src/render/scale.js

@@ -0,0 +1,41 @@
+/**
+ * Scale-to-fit — what a **bounded** 文體 gets because of what it is.
+ *
+ * A bounded artifact (a slide, a card, a one-page site, a résumé) has a *fixed
+ * logical canvas*: the author lays out 1280×720 once and the window shows all
+ * of it, whatever size the window happens to be (wayfinder issue 14 裁決 4).
+ * This is also the answer to v1's 「fullscreen 只多黑框」 — going fullscreen made
+ * the page bigger and the artifact exactly as small as before, because nothing
+ * was ever scaled.
+ *
+ * The arithmetic lives here, apart from the browser asset, so it can be
+ * asserted without a browser. **One scalar for both axes** is the whole
+ * correctness claim: two would fit the canvas exactly and distort every glyph
+ * in it, which is the failure mode that looks fine in a screenshot and is
+ * unreadable on a projector.
+ */
+
+/**
+ * The attribute and the attribute builder are **defined one layer down**, with
+ * the resolved canvas (`src/layouts/canvas.js`), and re-exported here so this
+ * module stays the one place the render layer asks about scaling. The reason
+ * for the move is in that file: the block that draws a bounded canvas element
+ * must be able to spell the attribute without importing the render layer.
+ */
+export { CANVAS_ATTR, canvasAttrs } from '../layouts/canvas.js'
+
+/**
+ * The uniform scale and the offsets that centre the canvas in the viewport.
+ *
+ * @param {{canvas: {width: number, height: number},
+ *   viewport: {width: number, height: number}}} input
+ * @returns {{scale: number, offsetX: number, offsetY: number}}
+ */
+export function scaleToFit({ canvas, viewport }) {
+  const scale = Math.min(viewport.width / canvas.width, viewport.height / canvas.height)
+  return {
+    scale,
+    offsetX: (viewport.width - canvas.width * scale) / 2,
+    offsetY: (viewport.height - canvas.height * scale) / 2,
+  }
+}

package/src/render/skeleton.js

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { CANVAS_BOUNDED } from '../layouts/index.js'
+import { collectBlockTypes } from '../core/vocabulary.js'
+
+/**
+ * Client assets — the behaviour an artifact gets because of *what it is*,
+ * not because of which template drew it.
+ *
+ * None of them is keyed on a template name, so a third-party template inherits
+ * the behaviour without asking and without being able to decline: a slide
+ * artifact that cannot be paged through is not a slide artifact, and a bounded
+ * canvas that does not scale is a black border.
+ *
+ * Two keys, two reasons:
+ *
+ *  - **layout-keyed (skeleton)** — `playback` for a deck-rooted layout
+ *    (wayfinder issue 13 P3), `scale-to-fit` for a bounded canvas
+ *    (issue 14 裁決 4).
+ *  - **block-keyed (interaction)** — `board-filter` and `graph-hover`
+ *    (issue 11 P5), embedded only into artifacts that carry the block the
+ *    interaction belongs to. That condition is what keeps every artifact drawn
+ *    before F6a byte for byte unchanged: a document with no `board` and no
+ *    `graph` gets exactly the script it got before, and a document with no
+ *    behaviour at all still gets no script element at all.
+ */
+
+/**
+ * `playback.client.js` used to live in `templates/kami/slides/`, which made
+ * "a deck can be paged through" a property of one template rather than of
+ * decks. Its own header still describes itself as a template asset: the file is
+ * embedded into every deck artifact **verbatim**, so a single edited character
+ * moves the artifact's bytes (CONTRACT A2). The header is corrected together
+ * with SPEC §7.4, in the slice that is allowed to move those bytes *and* to
+ * edit the SPEC — F2f was allowed the first and not the second, so it left the
+ * pair alone rather than making the file and the SPEC disagree.
+ */
+const PLAYBACK_PATH = fileURLToPath(new URL('./playback.client.js', import.meta.url))
+const SCALE_PATH = fileURLToPath(new URL('./scale-to-fit.client.js', import.meta.url))
+const BOARD_FILTER_PATH = fileURLToPath(new URL('./board-filter.client.js', import.meta.url))
+const GRAPH_HOVER_PATH = fileURLToPath(new URL('./graph-hover.client.js', import.meta.url))
+
+/**
+ * Every asset this module can embed, by role — the **single source of the list**.
+ *
+ * Exported because the list has judges: the scan that keeps these files free of
+ * the sequences that would derail the HTML tokenizer, and free of non-ASCII,
+ * has to run over *all* of them. A hand-copied list in the test file is a list
+ * that silently misses the third asset the day one arrives — the same shape as
+ * the "至少" thresholds F2d's seal replaced with set equality. So the test
+ * derives its scan targets from here, and separately asserts this object's
+ * value set equals the `*.client.js` files actually sitting in this directory:
+ * adding a file without wiring it, or wiring one that does not exist, is red
+ * either way (CONTRACT F2g H4).
+ */
+export const SKELETON_ASSETS = Object.freeze({
+  playback: PLAYBACK_PATH,
+  scale: SCALE_PATH,
+  boardFilter: BOARD_FILTER_PATH,
+  graphHover: GRAPH_HOVER_PATH,
+})
+
+/** Verbatim — the root form that makes an artifact a deck. */
+const DECK_ROOT = 'deck'
+
+/**
+ * Which block type pulls in which interaction asset (issue 11 P5).
+ *
+ * Order is load-bearing in the same, dull way the module list is: it is the
+ * order the assets are concatenated in, and therefore part of the artifact's
+ * bytes. It follows the canonical block order, so it never has to be argued
+ * about again.
+ */
+const INTERACTION_ASSETS = Object.freeze([
+  Object.freeze({ type: 'board', path: BOARD_FILTER_PATH }),
+  Object.freeze({ type: 'graph', path: GRAPH_HOVER_PATH }),
+])
+
+/**
+ * The inline script for an artifact, or `undefined` when the skeleton has
+ * nothing to add (a layout without behaviour emits no element at all, which is
+ * what keeps its artifacts byte-identical).
+ *
+ * @param {{rootForm?: string|null, canvas?: string}} layout
+ * @returns {string|undefined}
+ */
+export function skeletonScript(layout) {
+  const assets = []
+  if (layout?.rootForm === DECK_ROOT) assets.push(readFileSync(PLAYBACK_PATH, 'utf8'))
+  if (layout?.canvas === CANVAS_BOUNDED) assets.push(readFileSync(SCALE_PATH, 'utf8'))
+  return assets.length === 0 ? undefined : assets.join('\n')
+}
+
+/**
+ * The inline script the *blocks in this document* ask for, or `undefined` when
+ * none of them does.
+ *
+ * Keyed on the document rather than on the template's declared vocabulary: a
+ * template may admit `board` and this document may contain none, and shipping
+ * the filter into an artifact with nothing to filter is dead weight in a file
+ * whose whole promise is that it is self-contained. It also makes the byte
+ * claim exact — every artifact rendered before F6a contains neither block, so
+ * every one of them still gets `undefined` here.
+ *
+ * @param {object} doc the canonical block tree
+ * @returns {string|undefined}
+ */
+export function interactionScript(doc) {
+  const present = collectBlockTypes(doc)
+  const assets = INTERACTION_ASSETS.filter(({ type }) => present.has(type)).map(({ path }) =>
+    readFileSync(path, 'utf8'),
+  )
+  return assets.length === 0 ? undefined : assets.join('\n')
+}
+
+/**
+ * Everything that goes into the artifact's one behaviour script, in order:
+ * skeleton first (it decides what the page *is*), interaction after.
+ *
+ * `undefined` rather than an empty string when there is nothing to say — a
+ * layout without behaviour emits no script element at all, which is what keeps
+ * its artifacts byte-identical.
+ *
+ * @returns {string|undefined}
+ */
+export function artifactScript(layout, doc) {
+  const parts = [skeletonScript(layout), interactionScript(doc)].filter(
+    (part) => typeof part === 'string',
+  )
+  return parts.length === 0 ? undefined : parts.join('\n')
+}

package/src/render/ssr.js

@@ -0,0 +1,24 @@
+import { createSSRApp } from 'vue'
+import { renderToString } from 'vue/server-renderer'
+import { toVNode } from './element.js'
+
+/**
+ * Server-render a layout's root form against a doc block tree.
+ *
+ * The root is a plain function returning a neutral element tree, so Vue never
+ * sees the layout, the template or any block module — it only sees the vnodes
+ * `toVNode` builds. That is what makes the SSR backend replaceable and both a
+ * layout and a template package pure data (wayfinder issue 13 裁決 3).
+ *
+ * The root arrives as a function rather than as a package, because since F2a it
+ * comes from the **layout**: a template supplies skin, config and chrome, and
+ * the shape of the page is the 文體's (CONTRACT C1).
+ *
+ * @param {(doc: object, ctx: object) => object} root the layout's root form
+ */
+export async function renderBody(root, doc, ctx) {
+  const app = createSSRApp({
+    render: () => toVNode(root(doc, ctx)),
+  })
+  return await renderToString(app)
+}

package/src/render/styles.js

@@ -0,0 +1,56 @@
+/**
+ * Layout geometry flows **into** the stylesheet, never out of it.
+ *
+ * `--measure: 740px` used to be a constant typed into
+ * `templates/kami/long-form/styles.css`, while `manifest.measure: 740` restated
+ * the same number as data so a diagram could be measured against it (量測報告
+ * §4.2). Two copies of one number, in two languages, with nothing keeping them
+ * in step — and the CSS copy was the one the reader actually saw.
+ *
+ * So the stylesheet now declares *where* a geometry value goes and the config
+ * says *what* it is: inside `:root`, a CSS comment reading `ksb:measure
+ * --measure` is replaced by the declaration `--measure: 740px;`.
+ *
+ * The marker is a CSS comment, so a stylesheet stays a valid stylesheet and can
+ * be opened, linted and edited by anything that understands CSS. It names the
+ * canvas knob it wants and the custom property to write it into, which is what
+ * lets `kami/slides` fill `--slide-measure` from `maxWidth` without the SDK
+ * knowing either name.
+ *
+ * Substituting in place (rather than prepending a `:root` block) is also what
+ * keeps CONTRACT C5 satisfiable at all: the emitted CSS is byte-for-byte the
+ * text that was there before the marker replaced the constant.
+ */
+
+/** A CSS comment reading `ksb:<knob> --<custom-property>` — the one legal form. */
+const MARKER = /\/\*\s*ksb:([A-Za-z][A-Za-z0-9]*)\s+(--[A-Za-z0-9-]+)\s*\*\//g
+
+/**
+ * Fill every geometry marker in a template's stylesheet.
+ *
+ * What a marker may name is **whatever the resolved canvas holds as a number** —
+ * the two canvas dimensions every 文體 has, plus whichever knobs that 文體
+ * declared for itself (`article` declares `railWidth`; CONTRACT F2b G1). A
+ * hard-coded list here would mean a third-party layout could define a knob, a
+ * template could turn it, and the stylesheet still had no way to read it
+ * without an edit inside the SDK — which is the one thing the layout axis
+ * exists to make unnecessary.
+ *
+ * An unknown knob, or one that is not a number (a boolean switch, a side), is
+ * left exactly as written rather than replaced with `undefined`: a typo must
+ * not silently become a broken declaration that still parses.
+ * `test_f2a_style_markers_resolved` asserts no marker survives in the factory
+ * templates, so a typo is loud in the suite instead of in the artifact.
+ *
+ * @param {string} css the template's raw stylesheet
+ * @param {{maxWidth: number, measure: number}} canvas the resolved canvas
+ */
+export function injectLayoutVars(css, canvas) {
+  return String(css ?? '').replace(MARKER, (whole, knob, property) => {
+    if (typeof canvas?.[knob] !== 'number') return whole
+    return `${property}: ${canvas[knob]}px;`
+  })
+}
+
+/** Whether any geometry marker is still unfilled — for the suite, not the pipeline. */
+export const unresolvedMarkers = (css) => String(css ?? '').match(MARKER) ?? []