@kamishibai/sdk 0.1.1

package/src/core/diagram.js

@@ -0,0 +1,282 @@
+import { DIAGRAM_KINDS, diagramProblems } from '../blocks/diagram.js'
+
+/**
+ * `diagram` geometry — the layout half of the block (SPEC §3.3).
+ *
+ * What a diagram *is* (its spec, its schema, its markup) lives in
+ * `src/blocks/diagram.js`; what it *measures out to* lives here, because layout
+ * is not a block-level fact: it depends on how much width the page gives the
+ * block, which only the layer above knows (wayfinder issue 13 試金石).
+ *
+ * **Layout is pure integer arithmetic.** No clock, no randomness, no measured
+ * text: the same spec and the same available width must yield byte-identical
+ * SVG (CONTRACT D1), because that is what makes `replay` and the export chain
+ * verifiable. The cost is honest ugliness — a long label overflows its box
+ * rather than being re-flowed by something we cannot reproduce.
+ */
+
+export { DIAGRAM_KINDS, diagramProblems }
+
+/**
+ * Geometry, in SVG user units. Even numbers keep every midpoint an integer.
+ *
+ * Layers run **downwards**, siblings run across. The direction is not a taste
+ * call: an artifact's SVG is scaled to the text measure, so a left-to-right
+ * chain of six nodes produced a 1500-unit canvas squeezed to half size — a
+ * picture whose labels could no longer be read. Stacking layers vertically
+ * keeps a chain one column wide and therefore legible at 1:1, and it is the
+ * conventional reading direction for a flow anyway.
+ */
+const NODE_W = 180
+const NODE_H = 56
+/** Vertical distance between one layer and the next. */
+const LAYER_GAP = 48
+/** Horizontal distance between two nodes sharing a layer. */
+const ROW_GAP = 28
+const PAD = 24
+/** How far a non-forward edge bulges out to the right of the boxes it joins. */
+const BACK_DIP = 44
+/** Extra canvas reserved on the right when non-forward edges exist. */
+const BACK_BAND = BACK_DIP + 40
+
+/**
+ * Available width, in CSS pixels, when nobody says otherwise.
+ *
+ * `NODE_W` was tuned against the long-form text measure of 740px, and that
+ * assumption used to be invisible — the layout took no width at all, so a
+ * diagram placed in a narrower column was simply squeezed until its labels
+ * stopped being readable (量測報告 §4.2). The assumption is now a parameter
+ * with the old value as its default, which is what keeps every existing
+ * artifact byte-identical while making the narrow case expressible.
+ */
+export const DEFAULT_MEASURE = 740
+
+/**
+ * How many boxes fit across the available width — at least one, because a
+ * single box cannot be narrower than a box.
+ */
+const rowCapacity = (measure) =>
+  Math.max(1, Math.floor((measure - PAD * 2 + ROW_GAP) / (NODE_W + ROW_GAP)))
+
+/**
+ * Edge indices that close a cycle, found by an iterative DFS in declaration
+ * order (so the answer is a deterministic function of the spec).
+ *
+ * Cycles must be *removed before layering*, not merely survived. A `store →
+ * render` back edge — which every real architecture diagram has — makes plain
+ * longest-path relaxation push its whole cycle one layer further on every
+ * pass: capping the passes terminates, but the picture it terminates on is a
+ * nonsense 5000-unit-wide canvas. Breaking the cycle first keeps the layering
+ * a property of the structure rather than of the iteration count.
+ *
+ * The DFS is iterative because the stack depth would otherwise be the node
+ * count, and a spec is user input.
+ */
+const findBackEdges = (nodes, edges) => {
+  const outgoing = new Map(nodes.map((node) => [node.id, []]))
+  for (const [index, edge] of edges.entries()) {
+    if (edge.from !== edge.to) outgoing.get(edge.from).push({ index, to: edge.to })
+  }
+
+  const UNSEEN = 0
+  const OPEN = 1
+  const DONE = 2
+  const state = new Map(nodes.map((node) => [node.id, UNSEEN]))
+  const back = new Set()
+
+  for (const root of nodes) {
+    if (state.get(root.id) !== UNSEEN) continue
+    const stack = [{ id: root.id, next: 0 }]
+    state.set(root.id, OPEN)
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1]
+      const edgesOut = outgoing.get(frame.id)
+      if (frame.next >= edgesOut.length) {
+        state.set(frame.id, DONE)
+        stack.pop()
+        continue
+      }
+      const { index, to } = edgesOut[frame.next]
+      frame.next += 1
+      const seen = state.get(to)
+      if (seen === OPEN) back.add(index)
+      else if (seen === UNSEEN) {
+        state.set(to, OPEN)
+        stack.push({ id: to, next: 0 })
+      }
+    }
+  }
+  return back
+}
+
+/** Longest-path layering over the acyclic remainder of the spec. */
+const assignLayers = (nodes, edges) => {
+  const back = findBackEdges(nodes, edges)
+  const forward = edges.filter((edge, index) => edge.from !== edge.to && !back.has(index))
+  const layer = new Map(nodes.map((node) => [node.id, 0]))
+  for (let pass = 0; pass < nodes.length; pass += 1) {
+    let changed = false
+    for (const edge of forward) {
+      const want = layer.get(edge.from) + 1
+      if (want > layer.get(edge.to)) {
+        layer.set(edge.to, want)
+        changed = true
+      }
+    }
+    if (!changed) break
+  }
+  return layer
+}
+
+const half = (value) => Math.round(value / 2)
+
+/**
+ * Labels sit *beside* their connector, anchored at the start, never centred on
+ * it: a centred label lands exactly on the line it describes.
+ */
+const LABEL_ANCHOR = 'start'
+const LABEL_INSET = 8
+
+/** `M …` path for an edge that goes strictly downwards, layer to layer. */
+const forwardPath = (a, b) => {
+  const x1 = a.cx
+  const y1 = a.y + NODE_H
+  const x2 = b.cx
+  const y2 = b.y
+  const bend = half(y2 - y1)
+  return {
+    d: `M ${x1} ${y1} C ${x1} ${y1 + bend} ${x2} ${y2 - bend} ${x2} ${y2}`,
+    labelX: half(x1 + x2) + LABEL_INSET,
+    labelY: half(y1 + y2) + 4,
+  }
+}
+
+/** `M …` path for a back edge or a same-layer edge: bulge out to the right. */
+const backPath = (a, b) => {
+  const x1 = a.x + NODE_W
+  const y1 = a.cy
+  const x2 = b.x + NODE_W
+  const y2 = b.cy
+  const bulge = Math.max(x1, x2) + BACK_DIP
+  return {
+    d: `M ${x1} ${y1} C ${bulge} ${y1} ${bulge} ${y2} ${x2} ${y2}`,
+    labelX: bulge + LABEL_INSET,
+    labelY: half(y1 + y2) + 4,
+  }
+}
+
+/** `M …` path for a self-loop: a lobe off the node's right edge. */
+const selfPath = (a) => {
+  const x1 = a.x + NODE_W
+  const y1 = a.y + Math.round(NODE_H / 3)
+  const y2 = a.y + Math.round((NODE_H * 2) / 3)
+  const out = x1 + BACK_DIP
+  return {
+    d: `M ${x1} ${y1} C ${out} ${y1} ${out} ${y2} ${x1} ${y2}`,
+    labelX: out + LABEL_INSET,
+    labelY: a.cy + 4,
+  }
+}
+
+/**
+ * Place every node on a (layer, row) grid, wrapping a layer whose siblings do
+ * not fit across `capacity` columns onto further rows of the same layer.
+ *
+ * Wrapping rather than shrinking is the whole point of taking a width: a
+ * narrower column must not make the boxes — and therefore the labels — smaller,
+ * or the picture stops being readable at exactly the moment it gets tight.
+ */
+const gridPositions = (nodes, layer, capacity) => {
+  const seenPerLayer = new Map()
+  const cells = new Map()
+  const rowsBefore = new Map()
+  let totalRows = 0
+  for (const node of nodes) {
+    const l = layer.get(node.id)
+    const seen = seenPerLayer.get(l) ?? 0
+    seenPerLayer.set(l, seen + 1)
+    cells.set(node.id, { layer: l, column: seen % capacity, wrap: Math.floor(seen / capacity) })
+  }
+  // Layers are laid out top to bottom, and a wrapped layer occupies more than
+  // one row, so a layer's vertical offset is the number of rows above it.
+  for (const l of [...seenPerLayer.keys()].sort((a, b) => a - b)) {
+    rowsBefore.set(l, totalRows)
+    totalRows += Math.ceil(seenPerLayer.get(l) / capacity)
+  }
+  const widestRow = Math.max(
+    ...[...seenPerLayer.values()].map((count) => Math.min(count, capacity)),
+  )
+  return { cells, rowsBefore, totalRows, widestRow }
+}
+
+/**
+ * Deterministic layered layout for a `kind: "graph"` diagram.
+ *
+ * Callers must have passed `diagramProblems` / `assertDiagrams` first; this
+ * function assumes a valid spec and does no error reporting of its own.
+ *
+ * @param {object} block a validated `diagram` block
+ * @param {{measure?: number}} [options] available width in CSS pixels
+ * @returns {{width: number, height: number,
+ *   nodes: Array<{id: string, label: string, x: number, y: number, w: number, h: number,
+ *     cx: number, cy: number}>,
+ *   edges: Array<{from: string, to: string, label: string|undefined, d: string,
+ *     labelX: number, labelY: number}>}}
+ */
+export function layoutGraph(block, options = {}) {
+  const measure = Number.isFinite(options.measure) ? options.measure : DEFAULT_MEASURE
+  const nodes = block.nodes
+  const edges = block.edges ?? []
+  const layer = assignLayers(nodes, edges)
+  const { cells, rowsBefore, totalRows, widestRow } = gridPositions(
+    nodes,
+    layer,
+    rowCapacity(measure),
+  )
+
+  const placed = nodes.map((node) => {
+    const cell = cells.get(node.id)
+    const x = PAD + cell.column * (NODE_W + ROW_GAP)
+    const y = PAD + (rowsBefore.get(cell.layer) + cell.wrap) * (NODE_H + LAYER_GAP)
+    return {
+      id: node.id,
+      label: node.label,
+      x,
+      y,
+      w: NODE_W,
+      h: NODE_H,
+      cx: x + half(NODE_W),
+      cy: y + half(NODE_H),
+    }
+  })
+  const byId = new Map(placed.map((node) => [node.id, node]))
+
+  let hasBackEdge = false
+  const drawn = edges.map((edge) => {
+    const a = byId.get(edge.from)
+    const b = byId.get(edge.to)
+    let geometry
+    if (edge.from === edge.to) {
+      geometry = selfPath(a)
+      hasBackEdge = true
+    } else if (b.y > a.y) geometry = forwardPath(a, b)
+    else {
+      geometry = backPath(a, b)
+      hasBackEdge = true
+    }
+    return {
+      from: edge.from,
+      to: edge.to,
+      label: edge.label,
+      labelAnchor: LABEL_ANCHOR,
+      ...geometry,
+    }
+  })
+
+  return {
+    width: PAD * 2 + widestRow * (NODE_W + ROW_GAP) - ROW_GAP + (hasBackEdge ? BACK_BAND : 0),
+    height: PAD * 2 + totalRows * (NODE_H + LAYER_GAP) - LAYER_GAP,
+    nodes: placed,
+    edges: drawn,
+  }
+}

package/src/core/errors.js

@@ -0,0 +1,156 @@
+/**
+ * Error vocabulary. Every user-facing failure carries a KSB_ code and a block
+ * path so Agents get machine-actionable feedback (SPEC §10.3).
+ */
+
+export const EXIT = Object.freeze({
+  OK: 0,
+  VALIDATION: 1,
+  USAGE: 2,
+})
+
+export const CODES = Object.freeze({
+  INPUT_NOT_FOUND: 'KSB_INPUT_NOT_FOUND',
+  INPUT_EMPTY: 'KSB_INPUT_EMPTY',
+  PARSE_FAILED: 'KSB_PARSE_FAILED',
+  TEMPLATE_NOT_FOUND: 'KSB_TEMPLATE_NOT_FOUND',
+  TEMPLATE_BLOCK_UNSUPPORTED: 'KSB_TEMPLATE_BLOCK_UNSUPPORTED',
+  WRITE_FAILED: 'KSB_WRITE_FAILED',
+  USAGE: 'KSB_USAGE',
+  ARTIFACT_UNREADABLE: 'KSB_ARTIFACT_UNREADABLE',
+  ARTIFACT_NOT_FOUND: 'KSB_ARTIFACT_NOT_FOUND',
+  OPEN_FAILED: 'KSB_OPEN_FAILED',
+  IR_MISSING: 'KSB_IR_MISSING',
+  IR_DUPLICATE: 'KSB_IR_DUPLICATE',
+  IR_UNPARSABLE: 'KSB_IR_UNPARSABLE',
+  IR_SCHEMA: 'KSB_IR_SCHEMA',
+  EXTERNAL_SCRIPT: 'KSB_EXTERNAL_SCRIPT',
+  EXTERNAL_STYLESHEET: 'KSB_EXTERNAL_STYLESHEET',
+  EXTERNAL_IMAGE: 'KSB_EXTERNAL_IMAGE',
+  EXTERNAL_CSS_IMPORT: 'KSB_EXTERNAL_CSS_IMPORT',
+  EXTERNAL_CSS_URL: 'KSB_EXTERNAL_CSS_URL',
+  BANNED_FONT: 'KSB_BANNED_FONT',
+  DIAGRAM_INVALID: 'KSB_DIAGRAM_INVALID',
+  /** F6a — a board card pointing at a lane nobody declared (silent card loss). */
+  BOARD_INVALID: 'KSB_BOARD_INVALID',
+  /** F6a — a graph edge pointing at a node nobody declared (silent edge loss). */
+  GRAPH_INVALID: 'KSB_GRAPH_INVALID',
+  EXPORT_FORMAT_MISMATCH: 'KSB_EXPORT_FORMAT_MISMATCH',
+  BROWSER_MISSING: 'KSB_BROWSER_MISSING',
+  EXPORT_FAILED: 'KSB_EXPORT_FAILED',
+  /** S5 — a comment anchored to a block the artifact's IR does not contain. */
+  BLOCK_NOT_FOUND: 'KSB_BLOCK_NOT_FOUND',
+  /** S5 — `comments resolve` naming a comment id no record carries. */
+  COMMENT_NOT_FOUND: 'KSB_COMMENT_NOT_FOUND',
+  /** S5 — the dev preview server could not be started (port taken, no handshake). */
+  SERVE_START_FAILED: 'KSB_SERVE_START_FAILED',
+  /** S5 — `--port` that is not a legal TCP port. */
+  SERVE_PORT_INVALID: 'KSB_SERVE_PORT_INVALID',
+  /** S5 — a recorded server could not be terminated. */
+  SERVE_CLOSE_FAILED: 'KSB_SERVE_CLOSE_FAILED',
+  /** F4 — a command module could not be loaded (broken or partial install). */
+  COMMAND_LOAD_FAILED: 'KSB_COMMAND_LOAD_FAILED',
+  /** F2a — a 24-grid placement that cannot exist on a 24-column grid. */
+  PLACEMENT_INVALID: 'KSB_PLACEMENT_INVALID',
+  /** F2a — a template naming a 文體 nobody registered. */
+  LAYOUT_NOT_FOUND: 'KSB_LAYOUT_NOT_FOUND',
+  /** F2a — canvas geometry that contradicts itself (measure wider than maxWidth). */
+  LAYOUT_CANVAS_INVALID: 'KSB_LAYOUT_CANVAS_INVALID',
+  /** F2a — a template filling a chrome slot its layout does not offer. */
+  LAYOUT_SLOT_UNKNOWN: 'KSB_LAYOUT_SLOT_UNKNOWN',
+  /** F2a — a template restating a root form its 文體 does not require. */
+  LAYOUT_ROOT_CONFLICT: 'KSB_LAYOUT_ROOT_CONFLICT',
+  /** F3 — a store template package that is incomplete or declares an illegal field. */
+  TEMPLATE_PACKAGE_INVALID: 'KSB_TEMPLATE_PACKAGE_INVALID',
+  /** F3 — `init` aimed at a package directory that already holds a package. */
+  TEMPLATE_PACKAGE_EXISTS: 'KSB_TEMPLATE_PACKAGE_EXISTS',
+  /**
+   * F3 — a package's JS extension (rotor override / plugin block) would not load
+   * or would not pass the same shape check the core registries apply.
+   *
+   * It gets its own code for the reason F4 B9 names: falling back to
+   * `KSB_PARSE_FAILED` would tell an agent its *document* is broken when the
+   * truth is a package on disk, and it would go rewrite a document that was
+   * never at fault.
+   */
+  TEMPLATE_EXTENSION_FAILED: 'KSB_TEMPLATE_EXTENSION_FAILED',
+  /** F3 — a store package squatting on a namespace the factory templates own. */
+  TEMPLATE_NAMESPACE_RESERVED: 'KSB_TEMPLATE_NAMESPACE_RESERVED',
+
+  /**
+   * F7b core — a `src` the browser would have to *fetch*.
+   *
+   * `KSB_EXTERNAL_IMAGE` only ever caught `src="http`, because CONTRACT A3's
+   * verbatim 禁形 list names that form. A **relative** `src="./fig.png"` breaks
+   * the same promise and passed every gate: the artifact renders on the machine
+   * that drew it and comes up broken everywhere else, which is the failure mode
+   * 「離線單檔」 exists to make impossible.
+   */
+  EXTERNAL_ASSET_SRC: 'KSB_EXTERNAL_ASSET_SRC',
+  /** F7b core — a `<script>` inside an `<svg>`: a figure that executes. */
+  SVG_SCRIPT: 'KSB_SVG_SCRIPT',
+  /** F7b core — an `on…=` event attribute inside an `<svg>`. */
+  SVG_EVENT_HANDLER: 'KSB_SVG_EVENT_HANDLER',
+  /** F7b core — a `javascript:` URL inside an `<svg>`. */
+  SVG_JAVASCRIPT_URL: 'KSB_SVG_JAVASCRIPT_URL',
+  /** F7b core — `rgba()` inside an `<svg>`: alpha the export chain drops. */
+  SVG_RGBA: 'KSB_SVG_RGBA',
+  /** F7b core — a marker reference no `<marker id>` answers (silent arrowhead loss). */
+  SVG_MARKER_DANGLING: 'KSB_SVG_MARKER_DANGLING',
+
+  /** F7b — a manifest `[gates]` section that declares something illegal. */
+  GATE_DECLARATION_INVALID: 'KSB_GATE_DECLARATION_INVALID',
+  /** F7b gate — body line-height above the ceiling the package declared. */
+  GATE_LINE_HEIGHT: 'KSB_GATE_LINE_HEIGHT',
+  /** F7b gate — a heading rule heavier than the package declared. */
+  GATE_HEADING_WEIGHT: 'KSB_GATE_HEADING_WEIGHT',
+  /** F7b gate — a box-shadow blurrier-than-declared-minimum (a hard shadow). */
+  GATE_SHADOW_BLUR: 'KSB_GATE_SHADOW_BLUR',
+  /** F7b gate — `font-style: italic` in a package that declared italic off. */
+  GATE_ITALIC: 'KSB_GATE_ITALIC',
+  /** F7b gate — a colour the package's own palette put on its banned list. */
+  GATE_BANNED_HEX: 'KSB_GATE_BANNED_HEX',
+})
+
+/** Root path token used when a finding cannot be tied to a single block. */
+export const ROOT_PATH = '$'
+
+export class KsbError extends Error {
+  constructor({ code, message, path = ROOT_PATH, exitCode = EXIT.VALIDATION }) {
+    super(message)
+    this.name = 'KsbError'
+    this.code = code
+    this.path = path
+    this.exitCode = exitCode
+  }
+
+  /** Serialisable finding, shape pinned by CONTRACT lint --json surface. */
+  toFinding() {
+    return { path: this.path, code: this.code, message: this.message }
+  }
+}
+
+export function usageError(message, code = CODES.USAGE) {
+  return new KsbError({ code, message, exitCode: EXIT.USAGE })
+}
+
+export function validationError(message, code, path = ROOT_PATH) {
+  return new KsbError({ code, message, path, exitCode: EXIT.VALIDATION })
+}
+
+/**
+ * A command module that would not load — a broken or partial install, never a
+ * problem with what the user typed.
+ *
+ * It gets its own code because the fallback, `KSB_PARSE_FAILED`, means "your
+ * input could not be parsed": an agent reading that after a half-installed
+ * package would go and rewrite a document that was never at fault. The
+ * resolver's own words are kept, since they name the missing file.
+ */
+export function commandLoadError(command, cause) {
+  return new KsbError({
+    code: CODES.COMMAND_LOAD_FAILED,
+    message: `指令模組 \`${command}\` 載入失敗（安裝可能不完整）：${cause?.message ?? String(cause)}`,
+    exitCode: EXIT.VALIDATION,
+  })
+}

package/src/core/example.js

@@ -0,0 +1,109 @@
+import { blockModule, blockTypes } from '../blocks/index.js'
+
+/**
+ * The canonical Markdown-superset example. It must always be valid input to
+ * `render` — that round-trip is the SDK's anti-trial-and-error guarantee
+ * (SPEC §4「CLI 必須提供 example／schema，讓 Agent 免反覆試錯」).
+ *
+ * `doc` is the one kind with no block module: it is the envelope every block
+ * sits in, not a block. Every other example comes from its own module.
+ */
+export const EXAMPLE_DOC = `---
+title: 範例文件
+kicker: KAMISHIBAI EXAMPLE
+author: kamishibai
+template: kami/long-form
+---
+
+# 第一章　散文與引言
+
+這是 **prose** 區塊，支援行內 Markdown：粗體、\`行內程式碼\`、以及[連結](https://example.com/)。
+
+> 這是 quote 區塊：引用一段話。
+
+## 第一節　程式碼、表格與提示框
+
+\`\`\`js
+export const hello = (name) => \`你好，\${name}\`
+\`\`\`
+
+| block | 用途 |
+|-------|------|
+| prose | 散文段落 |
+| table | 表格資料 |
+
+清單是真正的 \`list\` block——項目內容是子 block，所以清單裡放 callout 不會拆掉外框：
+
+- 項目一
+- 項目二
+  :::note
+  項目內的 callout 仍走同一個 Callout 元件。
+  :::
+- 項目三
+
+1. 有序項目一
+2. 有序項目二
+
+:::note
+這是 callout（note 型）。另有 warn 型。
+:::
+
+:::warn
+警示型 callout 長這樣。
+:::
+
+# 第二章　結構化圖表
+
+下面這個 diagram fence 的內容是 **JSON**，欄位就是 IR 的 diagram block；版面由 SDK
+算出，不必手畫座標。v1 只有一種 kind：有向的節點邊圖。
+
+\`\`\`diagram
+{
+  "kind": "graph",
+  "nodes": [
+    { "id": "input", "label": "來源語料" },
+    { "id": "ir", "label": "block tree" },
+    { "id": "artifact", "label": "離線產物" }
+  ],
+  "edges": [
+    { "from": "input", "to": "ir", "label": "parse" },
+    { "from": "ir", "to": "artifact", "label": "render" },
+    { "from": "artifact", "to": "ir", "label": "replay" }
+  ]
+}
+\`\`\`
+
+# 第三章　raw 島嶼
+
+島嶼是逃生艙：模板敘述不出來的東西才手寫，並以 intent 記錄原因。
+
+\`\`\`raw-html intent="示範 raw 島嶼的宣告方式"
+<div class="example-island">手寫 HTML 島嶼</div>
+\`\`\`
+`
+
+/** Re-exported for callers that want the deck teaching source by name. */
+export { EXAMPLE_DECK } from '../blocks/deck.js'
+
+/**
+ * `doc` plus every registered block type.
+ *
+ * A function, not a frozen array: the vocabulary grows when a plugin registers,
+ * and a list snapshotted at import would answer `unknown example kind "x-…"`
+ * for a block the renderer had just drawn.
+ */
+export const exampleKinds = () => ['doc', ...blockTypes()]
+
+/**
+ * @param {string} kind `doc`/`deck` for the Markdown superset, or a block type name
+ * @returns {{kind: string, example: string}|null} null when the kind is unknown
+ */
+export function exampleFor(kind) {
+  if (kind === 'doc') return { kind, example: EXAMPLE_DOC }
+  const mod = blockModule(kind)
+  if (mod === undefined) return null
+  // A module may teach with a whole source file (the kinds that can be piped
+  // straight back into `render -`) or with one block, never both.
+  if (typeof mod.example.source === 'string') return { kind, example: mod.example.source }
+  return { kind, example: JSON.stringify(mod.example.block, null, 2) }
+}

package/src/core/ir.js

@@ -0,0 +1,62 @@
+import { engineVersion } from './version.js'
+
+export const IR_VERSION = '1'
+export const DEFAULT_GENERATOR = 'kamishibai-cli'
+export const BUILD_TIME_ENV = 'KAMISHIBAI_BUILD_TIME'
+/** SPEC §7.3 / issues/11 P4 — the embedding media type, verbatim. */
+export const IR_SCRIPT_TYPE = 'application/kamishibai+json'
+
+/**
+ * Deterministic build timestamp: KAMISHIBAI_BUILD_TIME wins so that repeated
+ * renders of the same input are byte-identical (CONTRACT A8).
+ */
+export function resolveCreatedAt(env = {}, now = () => new Date()) {
+  const pinned = env[BUILD_TIME_ENV]
+  if (typeof pinned === 'string' && pinned.trim().length > 0) return pinned.trim()
+  return now().toISOString()
+}
+
+/**
+ * Timestamp for a replay. A pinned `KAMISHIBAI_BUILD_TIME` still wins, but the
+ * fallback is the *original* artifact's `createdAt` rather than "now": replay
+ * reproduces a document from its own embedded record, so an unpinned replay
+ * that stamped the current clock would silently break byte-identity (B6).
+ */
+export function replayCreatedAt(env = {}, ir = {}) {
+  const pinned = env[BUILD_TIME_ENV]
+  if (typeof pinned === 'string' && pinned.trim().length > 0) return pinned.trim()
+  if (typeof ir.createdAt === 'string' && ir.createdAt.length > 0) return ir.createdAt
+  return resolveCreatedAt(env)
+}
+
+/** `<namespace>/<name>` — the template key an IR envelope was rendered with. */
+export function templateKeyOf(ir) {
+  const t = ir?.template
+  if (!t || typeof t.namespace !== 'string' || typeof t.name !== 'string') return undefined
+  return `${t.namespace}/${t.name}`
+}
+
+/** `<namespace>/<name>@<version>` — the display form used by `list`. */
+export function templateLabelOf(ir) {
+  const key = templateKeyOf(ir)
+  return key === undefined ? '' : `${key}@${ir.template.version}`
+}
+
+/**
+ * Assemble the embedded IR envelope (SPEC §7.3). Key order is fixed so that
+ * JSON.stringify output is stable.
+ */
+export function buildIr({ doc, template, createdAt, generator = DEFAULT_GENERATOR }) {
+  return {
+    irVersion: IR_VERSION,
+    engine: engineVersion(),
+    template: {
+      namespace: template.namespace,
+      name: template.name,
+      version: template.version,
+    },
+    doc,
+    createdAt,
+    generator,
+  }
+}