@kamishibai/sdk 0.1.1

package/src/export/browser.js

@@ -0,0 +1,130 @@
+import { pathToFileURL } from 'node:url'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+
+/**
+ * The one place the SDK talks to a real browser.
+ *
+ * Export and snapshot cannot be faked: a PDF, a PPTX slide image and a PNG all
+ * require something that actually lays out CSS. So the browser is a hard
+ * dependency — and the *honest* way to carry a hard dependency is to name it
+ * when it is missing, with the exact command that fixes it (CONTRACT D4).
+ * Anything softer (a blank PDF, a stub PNG, a silent exit 0) would hand back a
+ * file that looks like a deliverable and is not one.
+ */
+
+/** Verbatim CONTRACT constant — the exact setup command, quoted in the error. */
+export const BROWSER_SETUP_COMMAND = 'npx playwright install chromium'
+/** Verbatim CONTRACT constant — disposable cache, never a protected asset. */
+export const BROWSER_CACHE_DIR = '~/.cache/ms-playwright'
+/** WSL + nvm convention (SPEC §10.3): npm/npx must run through a login shell. */
+export const BROWSER_SETUP_SHELL_HINT = `zsh -lic '${BROWSER_SETUP_COMMAND}'`
+
+/** Playwright's own words when the binary is absent, in either channel. */
+const MISSING_SIGNS = Object.freeze([
+  /Executable doesn't exist/i,
+  /Looks like Playwright was just installed/i,
+  /ENOENT/,
+])
+
+export const browserMissingError = (detail) =>
+  new KsbError({
+    code: CODES.BROWSER_MISSING,
+    message:
+      `找不到可用的瀏覽器：${detail}。` +
+      `export／snapshot 需要真的 Chromium 才能排版，請先執行 \`${BROWSER_SETUP_COMMAND}\`` +
+      `（WSL ＋ nvm 請包成 ${BROWSER_SETUP_SHELL_HINT}）。` +
+      `二進位檔落在 ${BROWSER_CACHE_DIR}，是可丟棄的快取，隨時可刪掉重抓。`,
+    exitCode: EXIT.VALIDATION,
+  })
+
+const exportFailedError = (detail) =>
+  new KsbError({
+    code: CODES.EXPORT_FAILED,
+    message: `瀏覽器操作失敗：${detail}`,
+    exitCode: EXIT.VALIDATION,
+  })
+
+/** Absence and breakage are different diagnoses; never report one as the other. */
+const asBrowserError = (cause) => {
+  const detail = String(cause?.message ?? cause).split('\n')[0]
+  return MISSING_SIGNS.some((re) => re.test(String(cause?.message ?? cause)))
+    ? browserMissingError(detail)
+    : exportFailedError(detail)
+}
+
+const loadChromium = async () => {
+  try {
+    const { chromium } = await import('playwright')
+    return chromium
+  } catch (cause) {
+    throw browserMissingError(`playwright 套件無法載入（${cause.message}）`)
+  }
+}
+
+/**
+ * Viewport used for every export — and since F2f it is **exactly** the `deck`
+ * 文體's logical canvas (1280×720), so one slide exports at 1:1: no scaling to
+ * blur the type, and a per-slide screenshot that is the canvas itself.
+ */
+export const EXPORT_VIEWPORT = Object.freeze({ width: 1280, height: 720 })
+
+/**
+ * Open an artifact in a real browser and hand the page to `visit`.
+ *
+ * JavaScript is **off** on purpose. The deck template's playback script hides
+ * every slide but the current one, so a JS-enabled page would export a deck of
+ * blank pages. Without JS the artifact degrades to the scrolling document the
+ * template already promises is fully readable — which is exactly the form a
+ * PDF/PPTX should capture.
+ */
+export async function withArtifactPage(artifactPath, visit) {
+  const chromium = await loadChromium()
+  let browser
+  try {
+    browser = await chromium.launch()
+  } catch (cause) {
+    throw asBrowserError(cause)
+  }
+  try {
+    const context = await browser.newContext({
+      javaScriptEnabled: false,
+      viewport: { ...EXPORT_VIEWPORT },
+    })
+    const page = await context.newPage()
+    // Print media, chosen by the *template*, is the export form.
+    //
+    // kami/slides paints its playback chrome with `position: fixed`, so a
+    // per-slide element screenshot came back with a dark band across the bottom
+    // of every slide — chrome that belongs to the on-screen deck, not to the
+    // slide. The stylesheet already says what the printed form is (`@media
+    // print` hides the chrome and the shadows), so the exporter asks for that
+    // form instead of hard-coding a template's class names here.
+    await page.emulateMedia({ media: 'print' })
+    await page.goto(pathToFileURL(artifactPath).href, { waitUntil: 'load' })
+    return await visit(page)
+  } catch (cause) {
+    if (cause instanceof KsbError) throw cause
+    throw asBrowserError(cause)
+  } finally {
+    await browser.close().catch(() => {})
+  }
+}
+
+/**
+ * Is a usable browser actually there? Answered by launching one, because that
+ * is the only question that matters — a present-but-unlaunchable binary is
+ * absent for every practical purpose.
+ *
+ * @returns {Promise<{available: boolean, reason: string, command: string}>}
+ */
+export async function probeBrowser() {
+  try {
+    const chromium = await loadChromium()
+    const browser = await chromium.launch()
+    await browser.close()
+    return { available: true, reason: '', command: BROWSER_SETUP_COMMAND }
+  } catch (cause) {
+    const error = cause instanceof KsbError ? cause : asBrowserError(cause)
+    return { available: false, reason: error.message, command: BROWSER_SETUP_COMMAND }
+  }
+}

package/src/export/index.js

@@ -0,0 +1,96 @@
+import { basename, extname, join } from 'node:path'
+import { findDeck } from '../core/blocks.js'
+import { CODES, EXIT, KsbError, usageError } from '../core/errors.js'
+import { readArtifact } from '../delivery/read.js'
+import { writeBytes } from '../delivery/write.js'
+import { readEmbeddedIr } from '../parser/artifact.js'
+import { withArtifactPage } from './browser.js'
+import { renderPdf } from './pdf.js'
+import { renderPptx } from './pptx.js'
+import { readPngSize } from './png.js'
+import { renderSnapshot } from './snapshot.js'
+
+export { BROWSER_SETUP_COMMAND, BROWSER_CACHE_DIR, probeBrowser } from './browser.js'
+export { DEFAULT_SLIDE } from './snapshot.js'
+
+/** Verbatim CONTRACT constants — the two附屬格式 and the root each one needs. */
+export const EXPORT_FORMATS = Object.freeze(['pdf', 'pptx'])
+export const FORMAT_ROOT = Object.freeze({ pdf: 'document', pptx: 'deck' })
+export const SNAPSHOT_EXT = 'png'
+
+/** Where a deliverable lands when the caller gave no `-o` (mirrors `render`). */
+const defaultOut = (artifactPath, ext) =>
+  join('out', `${basename(artifactPath, extname(artifactPath))}.${ext}`)
+
+/**
+ * What an artifact *is*, read from its own embedded IR rather than its markup.
+ *
+ * The root form decides which export formats are even meaningful, so it must
+ * come from the record the artifact carries — grepping for slide markup would
+ * make a document that merely *mentions* a slide class exportable as a deck.
+ *
+ * @returns {{path: string, html: string, root: 'document'|'deck', slides: number|undefined}}
+ */
+export function artifactShape(target) {
+  const { html, path } = readArtifact(target)
+  const ir = readEmbeddedIr(html, path)
+  const deck = findDeck(ir.doc)
+  return {
+    path,
+    html,
+    root: deck === undefined ? 'document' : 'deck',
+    slides: deck === undefined ? undefined : deck.slides.length,
+  }
+}
+
+const formatMismatch = (format, root, path) =>
+  new KsbError({
+    code: CODES.EXPORT_FORMAT_MISMATCH,
+    message:
+      `--to ${format} 只適用於 ${FORMAT_ROOT[format]} 根形的產物，但 ${path} 是 ${root} 產物。` +
+      `文體轉換不是匯出：deck 請用 --to pptx，document 請用 --to pdf。`,
+    exitCode: EXIT.VALIDATION,
+  })
+
+/**
+ * `export <artifact> --to pdf|pptx` (CONTRACT D3).
+ *
+ * The pairing is checked *before* the browser is launched: a wrong `--to` is an
+ * authoring mistake, and answering it with a 5-second browser start-up followed
+ * by the same rejection would only teach callers that export is slow.
+ *
+ * @returns {Promise<{result: {ok: true, artifact: string, format: string}, exitCode: number}>}
+ */
+export async function exportArtifact({ target, format, out }) {
+  if (!EXPORT_FORMATS.includes(format)) {
+    throw usageError(`--to 必須是 ${EXPORT_FORMATS.join(' 或 ')}，收到 ${JSON.stringify(format)}`)
+  }
+  const shape = artifactShape(target)
+  if (shape.root !== FORMAT_ROOT[format]) throw formatMismatch(format, shape.root, shape.path)
+
+  const buffer = await withArtifactPage(shape.path, async (page) =>
+    format === 'pdf' ? await renderPdf(page) : (await renderPptx(page, shape.slides)).buffer,
+  )
+
+  const { path } = writeBytes(out ?? defaultOut(shape.path, format), buffer)
+  return { result: { ok: true, artifact: path, format }, exitCode: EXIT.OK }
+}
+
+/**
+ * `snapshot <artifact> -o out.png [--slide N]` (CONTRACT D5).
+ *
+ * The reported dimensions are read back out of the PNG header, so the result
+ * describes the file on disk rather than the request that produced it.
+ *
+ * @returns {Promise<{result: {ok: true, artifact: string, width: number, height: number},
+ *   exitCode: number}>}
+ */
+export async function snapshotArtifact({ target, out, slide }) {
+  const shape = artifactShape(target)
+  const buffer = await withArtifactPage(shape.path, async (page) =>
+    await renderSnapshot(page, { slide, deckSlides: shape.slides }),
+  )
+  const { width, height } = readPngSize(buffer)
+  const { path } = writeBytes(out ?? defaultOut(shape.path, SNAPSHOT_EXT), buffer)
+  return { result: { ok: true, artifact: path, width, height }, exitCode: EXIT.OK }
+}

package/src/export/pdf.js

@@ -0,0 +1,25 @@
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+
+/**
+ * Document artifact → PDF, printed by the browser that already knows how to lay
+ * the artifact out. Nothing is re-implemented here: the template's own
+ * `@media print` rules are what shape the page.
+ */
+
+/** Verbatim PDF file signature. */
+export const PDF_MAGIC = '%PDF-'
+
+const PAGE_FORMAT = 'A4'
+const MARGIN = Object.freeze({ top: '14mm', right: '14mm', bottom: '14mm', left: '14mm' })
+
+export async function renderPdf(page) {
+  const buffer = await page.pdf({ format: PAGE_FORMAT, printBackground: true, margin: MARGIN })
+  if (buffer.subarray(0, PDF_MAGIC.length).toString('latin1') !== PDF_MAGIC) {
+    throw new KsbError({
+      code: CODES.EXPORT_FAILED,
+      message: `瀏覽器回傳的不是 PDF（開頭應為 ${PDF_MAGIC}）`,
+      exitCode: EXIT.VALIDATION,
+    })
+  }
+  return buffer
+}

package/src/export/png.js

@@ -0,0 +1,40 @@
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+
+/**
+ * PNG header reading, so `snapshot` reports the dimensions of the file it
+ * actually wrote rather than the dimensions it asked for. A screenshot that
+ * came back clipped, scaled or empty is exactly the failure a caller cannot see
+ * in a JSON result — so the number is read out of the bytes.
+ */
+
+/** Verbatim PNG signature (RFC 2083 §3.1). */
+export const PNG_MAGIC = Object.freeze([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+const IHDR_OFFSET = 12
+const WIDTH_OFFSET = 16
+const HEIGHT_OFFSET = 20
+const MIN_LENGTH = 24
+
+const malformed = (detail) =>
+  new KsbError({
+    code: CODES.EXPORT_FAILED,
+    message: `截圖不是合法的 PNG：${detail}`,
+    exitCode: EXIT.VALIDATION,
+  })
+
+/** @returns {{width: number, height: number}} */
+export function readPngSize(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < MIN_LENGTH) {
+    throw malformed(`長度只有 ${buffer?.length ?? 0} bytes`)
+  }
+  for (const [index, byte] of PNG_MAGIC.entries()) {
+    if (buffer[index] !== byte) throw malformed(`第 ${index} 個位元組不符 PNG 簽章`)
+  }
+  if (buffer.subarray(IHDR_OFFSET, IHDR_OFFSET + 4).toString('latin1') !== 'IHDR') {
+    throw malformed('缺少 IHDR 區塊')
+  }
+  const width = buffer.readUInt32BE(WIDTH_OFFSET)
+  const height = buffer.readUInt32BE(HEIGHT_OFFSET)
+  if (width === 0 || height === 0) throw malformed(`尺寸為 ${width}×${height}`)
+  return { width, height }
+}

package/src/export/pptx.js

@@ -0,0 +1,48 @@
+import PptxGenJS from 'pptxgenjs'
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+import { slideHandles } from './slides.js'
+
+/**
+ * Deck artifact → PPTX, one slide per `<section class="slide">`.
+ *
+ * v1 puts a **screenshot** on each slide. That is a deliberate floor, not an
+ * oversight: the alternative — re-deriving PowerPoint shapes from the block tree
+ * — is a second renderer, and a second renderer is a second answer to "what does
+ * this deck look like". A picture of the real artifact cannot disagree with the
+ * artifact. The price is honest and stated: the text is not selectable in
+ * PowerPoint. Structured shapes are later work, driven by the IR.
+ */
+
+/** 16:9, matching the `deck` 文體's logical canvas (1280×720, src/layouts/deck.js). */
+const LAYOUT = 'LAYOUT_16x9'
+const FULL_BLEED = Object.freeze({ x: 0, y: 0, w: '100%', h: '100%' })
+
+export async function renderPptx(page, expectedSlides) {
+  const handles = await slideHandles(page, expectedSlides)
+
+  const shots = []
+  for (const handle of handles) {
+    shots.push(await handle.screenshot({ type: 'png' }))
+  }
+
+  const pptx = new PptxGenJS()
+  pptx.layout = LAYOUT
+  for (const shot of shots) {
+    pptx.addSlide().addImage({
+      ...FULL_BLEED,
+      data: `data:image/png;base64,${shot.toString('base64')}`,
+    })
+  }
+
+  const written = await pptx.write({ outputType: 'nodebuffer' })
+  const buffer = Buffer.isBuffer(written) ? written : Buffer.from(written)
+  // A PPTX is a ZIP container; `PK` is the local file header signature.
+  if (buffer.subarray(0, 2).toString('latin1') !== 'PK') {
+    throw new KsbError({
+      code: CODES.EXPORT_FAILED,
+      message: 'pptx 產出不是合法的 OOXML 容器（開頭應為 PK）',
+      exitCode: EXIT.VALIDATION,
+    })
+  }
+  return { buffer, slides: handles.length }
+}

package/src/export/slides.js

@@ -0,0 +1,33 @@
+import { CODES, EXIT, KsbError } from '../core/errors.js'
+
+/**
+ * Verbatim CONTRACT constant — a deck slide *is* `<section class="slide">`.
+ * The exporter counts the same containers the template emits, so "one slide per
+ * section" is checked against the rendered DOM rather than assumed.
+ */
+export const SLIDE_SELECTOR = 'section.slide'
+
+const exportFailed = (message) =>
+  new KsbError({ code: CODES.EXPORT_FAILED, message, exitCode: EXIT.VALIDATION })
+
+/**
+ * Every slide container in a rendered deck, in document order.
+ *
+ * `expected` is the slide count the artifact's own embedded IR claims. The two
+ * must agree: a DOM that drew fewer sections than the IR carries means the
+ * export would silently lose pages, which is precisely the class of failure
+ * that motivated the template vocabulary guard in S3a.
+ */
+export async function slideHandles(page, expected) {
+  const handles = await page.locator(SLIDE_SELECTOR).all()
+  if (handles.length === 0) {
+    throw exportFailed(`產物內找不到任何 \`${SLIDE_SELECTOR}\`，無法逐張匯出`)
+  }
+  if (Number.isInteger(expected) && handles.length !== expected) {
+    throw exportFailed(
+      `產物的 ${SLIDE_SELECTOR} 數（${handles.length}）與內嵌 IR 的張數（${expected}）不符；` +
+        '匯出會漏頁，故不產出檔案',
+    )
+  }
+  return handles
+}

package/src/export/snapshot.js

@@ -0,0 +1,33 @@
+import { usageError } from '../core/errors.js'
+import { slideHandles, SLIDE_SELECTOR } from './slides.js'
+
+/**
+ * Artifact → PNG, so an Agent can *see* what it rendered (SPEC §10.1).
+ *
+ * A deck is snapshotted one slide at a time (CONTRACT D5: slide 1 by default),
+ * because a full-page shot of a deck is a column of thumbnails — technically an
+ * image, useless as a look at the deck.
+ */
+
+/** Verbatim CONTRACT constant — deck snapshots default to the first slide. */
+export const DEFAULT_SLIDE = 1
+
+export async function renderSnapshot(page, { slide, deckSlides } = {}) {
+  const isDeck = Number.isInteger(deckSlides)
+
+  if (!isDeck) {
+    if (slide !== undefined) {
+      throw usageError(
+        `--slide 只適用於 deck 產物；這份是 document 產物（沒有 ${SLIDE_SELECTOR}）`,
+      )
+    }
+    return await page.screenshot({ type: 'png', fullPage: true })
+  }
+
+  const handles = await slideHandles(page, deckSlides)
+  const wanted = slide === undefined ? DEFAULT_SLIDE : slide
+  if (!Number.isInteger(wanted) || wanted < 1 || wanted > handles.length) {
+    throw usageError(`--slide 必須是 1…${handles.length} 之間的整數，收到 ${JSON.stringify(slide)}`)
+  }
+  return await handles[wanted - 1].screenshot({ type: 'png' })
+}

package/src/layouts/article.js

@@ -0,0 +1,103 @@
+import { el } from '../blocks/element.js'
+import { CANVAS_FLOWING } from './registry.js'
+
+/**
+ * `article` — the flowing long-form 文體: one column of text, read by scrolling.
+ *
+ * What this module supplies is the *cut*: an outer frame, a body region, and
+ * two named slots above and below it. What goes **into** those slots — a
+ * masthead, a colophon, a table of contents, nothing at all — is the template's
+ * business, and so is every word of it. That division is the whole point of
+ * lifting the root form out of `templates/kami/long-form/components.js`: the
+ * same layout has to be able to carry a report and a maintenance page.
+ *
+ * The canvas is flowing, so `measure` is a *maximum* the body respects rather
+ * than a fixed logical size, and the artifact simply gets taller with its
+ * content (issue 14 裁決 4「流動文體流式」).
+ *
+ * ## The rail is a knob, not a 文體 (CONTRACT F2b)
+ *
+ * 「上面掛 header、旁邊塞 side menu、中間內文、底下 footer」 is what a long-form
+ * page looks like when it is finished, and the side region is the piece this
+ * layout was missing. It arrives here as **geometry**: a switch, a width, a
+ * side — plus one more slot for whoever fills it. What goes in is not this
+ * module's business and never can be, which is exactly why a table of contents
+ * is *not* a sixth 文體: it is a template computing chrome out of the section
+ * tree, on the same layout, through the same door as the masthead (量測報告
+ * §5.4). A rail that knew it contained a table of contents would be a rail no
+ * maintenance page could ever use for anything else.
+ *
+ * The knob is off by factory default, which is what makes every article
+ * template written before this slice byte-identical after it: an existing
+ * package turns nothing, resolves `rail: false`, and gets exactly the tree it
+ * got before. `kami/long-form` turns it on, because a long-form skin with a
+ * table of contents is what that particular template *looks like*.
+ */
+export default Object.freeze({
+  name: 'article',
+
+  canvas: CANVAS_FLOWING,
+
+  /** No required root form: an article draws whatever sits under `doc`. */
+  rootForm: null,
+
+  /** The built-in generic template of this 文體 — `render` never wants for one. */
+  defaultTemplate: 'kami/long-form',
+
+  slots: Object.freeze(['doc-lead', 'doc-rail', 'doc-foot']),
+
+  styleHooks: Object.freeze(['paper', 'doc-rail', 'doc-body']),
+
+  /**
+   * Factory geometry, in CSS pixels — the fallback when a template names no
+   * value of its own. Geometry only: a content-shaped default would make this
+   * layout mean something, and a layout that means something can only carry the
+   * documents it already imagined.
+   */
+  defaults: Object.freeze({ maxWidth: 740, measure: 740 }),
+
+  /**
+   * This 文體's own geometry — the side region, in CSS pixels and plain words.
+   * Off by default (third-party compatibility, above); `start` and `end` are
+   * sides rather than left and right, so the same knob still means something
+   * when the page runs the other way.
+   */
+  knobs: Object.freeze({ rail: false, railWidth: 240, railSide: 'start' }),
+
+  /**
+   * The rail region is drawn whenever the **knob** says so, empty slot or not.
+   *
+   * Tying it to "the template actually filled the slot" would read as tidier
+   * and would quietly make the applied state depend on the document: the same
+   * package would be a two-column page for one file and a one-column page for
+   * the next, with nothing in its manifest saying either. A region that is
+   * switched on and left empty is the template's own doing, and its stylesheet
+   * is where that is answered (`.doc-rail:empty`) — one place, in the layer
+   * that owns appearance.
+   *
+   * `...(x ? [n] : [])` rather than `x ? n : null`, because a `null` child is a
+   * deliberate empty comment node in the artifact: spreading nothing is what
+   * keeps an unknobbed package byte-identical (CONTRACT F2b G7).
+   */
+  root: (doc, ctx) => {
+    const railed = ctx.canvas.rail === true
+    return el(
+      'article',
+      {
+        class: 'paper',
+        'data-template': ctx.templateKey,
+        ...(railed ? { 'data-rail': ctx.canvas.railSide } : {}),
+      },
+      [
+        ...ctx.chrome('doc-lead', ctx.meta),
+        // The rail's payload is the document tree, because navigating a
+        // document is what a rail on *this* 文體 is for. What is made of it —
+        // a table of contents, a progress meter, nothing — stays the
+        // template's, exactly like the masthead's wording.
+        ...(railed ? [el('aside', { class: 'doc-rail' }, ctx.chrome('doc-rail', doc))] : []),
+        el('main', { class: 'doc-body' }, ctx.renderChildren(doc.children)),
+        ...ctx.chrome('doc-foot', ctx.meta),
+      ],
+    )
+  },
+})

package/src/layouts/canvas.js

@@ -0,0 +1,144 @@
+import {
+  CANVAS_BOUNDED,
+  GRID_ADDRESSED_FIELD,
+  LAYOUT_DEFAULT_KEYS,
+  LAYOUT_KNOBS_FIELD,
+} from './registry.js'
+
+/**
+ * Resolving the canvas: **layout defines the knobs, the template turns them.**
+ *
+ * `maxWidth` and `measure` are two independent numbers, and keeping them apart
+ * is the whole of CONTRACT C3. They used to be one: `--measure: 740px` was
+ * simultaneously the width of the page and the width of a line of text, which
+ * is why a diagram in a narrow column had no width to be measured against
+ * (量測報告 §4.2). A page can be 1120px wide and still hold a 740px column of
+ * text — 「一般網站的玩法」 (issue 14 裁決 3), not a value derived from column
+ * arithmetic.
+ *
+ * The layout ships factory geometry; the template's manifest carries the values
+ * this particular skin applies. Nothing here reads a stylesheet: the numbers
+ * flow the other way, from config into CSS (see `src/render/styles.js`).
+ */
+
+/** Verbatim — `KSB_LAYOUT_CANVAS_INVALID`, kept as data so this layer imports nothing. */
+export const CANVAS_INVALID_CODE = 'KSB_LAYOUT_CANVAS_INVALID'
+
+/**
+ * Verbatim — the attribute a bounded canvas element wears, value `<w>x<h>`.
+ *
+ * It lives *here*, with the resolved canvas, rather than beside the browser
+ * asset that reads it, because three parties have to spell it identically and
+ * none of them may own it: the skeleton script that scales every element
+ * wearing it (`src/render/scale-to-fit.client.js`), the render layer that
+ * re-exports it (`src/render/scale.js`), and whichever **block** draws the
+ * element itself. A block must not import the render layer to learn one string,
+ * and a second copy of the string is a scale factor that silently stays 1.
+ */
+export const CANVAS_ATTR = 'data-ksb-canvas'
+
+/**
+ * The attributes a bounded canvas element carries.
+ *
+ * The size travels in the markup rather than in the script because the script
+ * is one shared skeleton asset: a third-party bounded layout that never heard
+ * of it still gets scaled, as long as it says how big its canvas is.
+ */
+export function canvasAttrs({ width, height }) {
+  return {
+    [CANVAS_ATTR]: `${width}x${height}`,
+    style: `width: ${width}px; height: ${height}px`,
+  }
+}
+
+/**
+ * The applied canvas of one artifact.
+ *
+ * @param {{name: string, canvas: string, defaults: object}} layout
+ * @param {{maxWidth?: number, measure?: number}} manifest the template's applied state
+ */
+export function resolveCanvas(layout, manifest) {
+  const defaults = layout.defaults
+  const applied = {}
+  for (const key of LAYOUT_DEFAULT_KEYS) {
+    const override = manifest?.[key]
+    applied[key] = typeof override === 'number' ? override : defaults[key]
+  }
+  /**
+   * This 文體's own knobs, turned by the template (CONTRACT F2b G1).
+   *
+   * An override of the wrong *type* is ignored here and reported by
+   * `canvasProblems` rather than coerced: `rail = "false"` is a truthy string,
+   * so coercion would draw a side region for a template that switched it off,
+   * and the artifact would look deliberate.
+   */
+  const knobs = {}
+  for (const [name, fallback] of Object.entries(layout[LAYOUT_KNOBS_FIELD] ?? {})) {
+    const override = manifest?.[name]
+    knobs[name] = typeof override === typeof fallback ? override : fallback
+  }
+  const canvasSize = defaults.canvasSize ?? null
+  return Object.freeze({
+    layout: layout.name,
+    canvas: layout.canvas,
+    canvasSize,
+    /**
+     * Ready-made markup attributes for the element that *is* this canvas, or
+     * `null` when the artifact has no fixed logical canvas at all. Resolved
+     * once, here, so the block that draws the element neither recomputes the
+     * format nor has to reach up into the render layer for it.
+     */
+    canvasAttrs: canvasSize === null ? null : Object.freeze(canvasAttrs(canvasSize)),
+    // Absent means false, and false is the safe direction: an unrecognised
+    // layout shape must not accidentally licence bare coordinates.
+    gridAddressed: layout[GRID_ADDRESSED_FIELD] === true,
+    ...knobs,
+    ...applied,
+  })
+}
+
+/**
+ * Why a resolved canvas cannot be drawn — empty array when it can.
+ *
+ * A text measure wider than the page it sits on is **not** clamped. Clamping
+ * would produce an artifact that renders, looks nearly right, and disagrees
+ * with the config it came from: the type scale would be tuned against a width
+ * the page never gives it, and nobody would ever be told. Loud is the only
+ * honest answer, which is the same reasoning that refuses a half-drawn diagram.
+ *
+ * `layout` and `manifest` are optional and carry the third refusal: a knob
+ * turned to the wrong *kind* of value. It needs both sides, because a resolved
+ * canvas alone cannot tell "the template left this alone" from "the template
+ * set it to something this knob is not" — the fallback looks identical.
+ *
+ * @param {object} resolved the canvas `resolveCanvas` produced
+ * @param {object} [layout] the layout module it was resolved from
+ * @param {object} [manifest] the template's applied state
+ */
+export function canvasProblems(resolved, layout, manifest) {
+  const problems = []
+  for (const [name, fallback] of Object.entries(layout?.[LAYOUT_KNOBS_FIELD] ?? {})) {
+    const override = manifest?.[name]
+    if (override === undefined || typeof override === typeof fallback) continue
+    problems.push(
+      `layout \`${resolved.layout}\` 的旋鈕 \`${name}\` 要的是 ${typeof fallback}，` +
+        `模板給的是 ${typeof override}（${JSON.stringify(override)}）。` +
+        '這裡不轉型也不靜默落回底值：字串 "false" 是真值，' +
+        '於是「關著的旋鈕」會畫出一塊誰也沒要求過的版面，而且看起來像是刻意的。',
+    )
+  }
+  if (resolved.measure > resolved.maxWidth) {
+    problems.push(
+      `layout \`${resolved.layout}\` 的內文寬 measure ${resolved.measure}px ` +
+        `大於畫布上限 maxWidth ${resolved.maxWidth}px。` +
+        '內文不得寬過畫布——這裡不靜默夾持：夾小的字級節奏會與版面上限對不上，' +
+        '而產物仍舊畫得出來，於是沒有人會發現。',
+    )
+  }
+  if (resolved.canvas === CANVAS_BOUNDED && resolved.canvasSize === null) {
+    problems.push(
+      `layout \`${resolved.layout}\` 宣告 ${CANVAS_BOUNDED} 畫布卻沒有固定邏輯畫布尺寸`,
+    )
+  }
+  return problems
+}