@kamishibai/sdk 0.1.1

package/src/blocks/registry.js

@@ -0,0 +1,158 @@
+/**
+ * The block module registry — one block type's whole knowledge in one place.
+ *
+ * Before this existed, adding one block type meant editing eleven files spread
+ * across every layer (wayfinder issue 13): the type list, the JSON Schema, the
+ * example table, the renderer table, two template manifests, two stylesheets,
+ * and the parser. The slicing axis was the *layer*, which is right for the
+ * pipeline and wrong for extension — because the unit of extension is the
+ * block, and a block crosses every layer. A plugin block was therefore not
+ * "unimplemented" but structurally impossible.
+ *
+ * Registration replaces a frozen snapshot with a new frozen snapshot; no map is
+ * ever mutated in place. `version` ticks on every change so downstream caches
+ * (the compiled Ajv validator, most importantly) can tell that the vocabulary
+ * they were built against is stale.
+ */
+
+/** Every field a block module must declare. `syntax`/`validate`/`create`/`nesting` are optional. */
+export const BLOCK_MODULE_FIELDS = Object.freeze([
+  'type',
+  'schema',
+  'example',
+  'render',
+  'styleHooks',
+])
+
+/**
+ * SPEC §12 — a plugin block wears an `x-` prefix so that core and third-party
+ * vocabularies can never collide, and so a template's admission rule can name
+ * the whole class of them without knowing any single one.
+ */
+export const PLUGIN_TYPE_PREFIX = 'x-'
+
+/**
+ * What a template writes in `manifest.blocks` to admit the whole plugin class
+ * rather than naming blocks that did not exist when it was written.
+ */
+export const PLUGIN_TYPE_WILDCARD = `${PLUGIN_TYPE_PREFIX}*`
+
+/** SPEC §10.3 — every user-facing failure code wears this prefix. */
+const ERROR_CODE_PREFIX = 'KSB_'
+
+const EMPTY = Object.freeze({ modules: Object.freeze([]), byType: new Map(), version: 0 })
+
+/** The current snapshot. Replaced wholesale, never edited. */
+let current = EMPTY
+/** The snapshot `resetBlockRegistry()` returns to — the core vocabulary alone. */
+let baseline = EMPTY
+/** Whether the core vocabulary has been closed; after that, only plugins may register. */
+let sealed = false
+
+const reject = (message) => {
+  throw new TypeError(`invalid block module: ${message}`)
+}
+
+/**
+ * A module that can say "no" must also say *how the refusal is reported*.
+ *
+ * `validate` is optional; `invalid` is not optional once `validate` exists. The
+ * spec gate reads `mod.invalid.message(problems)` and `mod.invalid.code` at the
+ * moment a document is refused — the one moment a `TypeError` there would turn a
+ * clear authoring error into a stack trace, on the rarest path, where no happy-
+ * path test would ever reach it. Registration is the only place this can be
+ * caught before it matters.
+ */
+function assertReportableValidate(mod) {
+  if (mod.validate === undefined) return
+  const where = `"${mod.type}"`
+  if (typeof mod.validate !== 'function') reject(`\`validate\` of ${where} must be a function`)
+  const invalid = mod.invalid
+  if (invalid === null || typeof invalid !== 'object') {
+    reject(`${where} declares \`validate\` but no \`invalid\` {code, message}`)
+  }
+  if (typeof invalid.code !== 'string' || !invalid.code.startsWith(ERROR_CODE_PREFIX)) {
+    reject(`\`invalid.code\` of ${where} must be a \`${ERROR_CODE_PREFIX}\` code`)
+  }
+  if (typeof invalid.message !== 'function') {
+    reject(`\`invalid.message\` of ${where} must be a function of the problem list`)
+  }
+}
+
+/** Reject anything that would register a half-built module and fail later, deeper. */
+function assertModuleShape(mod, byType) {
+  if (mod === null || typeof mod !== 'object') reject('not an object')
+  for (const field of BLOCK_MODULE_FIELDS) {
+    if (mod[field] === undefined || mod[field] === null) reject(`missing \`${field}\``)
+  }
+  if (typeof mod.type !== 'string' || mod.type.length === 0) reject('`type` must be a non-empty string')
+  if (typeof mod.render !== 'function') reject(`\`render\` of "${mod.type}" must be a function`)
+  if (typeof mod.schema !== 'object') reject(`\`schema\` of "${mod.type}" must be an object`)
+  if (typeof mod.example !== 'object') reject(`\`example\` of "${mod.type}" must be an object`)
+  if (mod.example.block === undefined && typeof mod.example.source !== 'string') {
+    reject(`\`example\` of "${mod.type}" must carry \`block\` or \`source\``)
+  }
+  if (!Array.isArray(mod.styleHooks)) reject(`\`styleHooks\` of "${mod.type}" must be an array`)
+  assertReportableValidate(mod)
+  if (byType.has(mod.type)) reject(`block type "${mod.type}" is already registered`)
+  // Once the core vocabulary is sealed, everything further is a plugin and must
+  // wear the prefix (SPEC §12). Without it a plugin could quietly occupy a name
+  // the core vocabulary might later want, and no reader of an IR payload could
+  // tell which blocks came from the engine and which from a third party.
+  if (sealed && !mod.type.startsWith(PLUGIN_TYPE_PREFIX)) {
+    reject(`plugin block type "${mod.type}" must start with \`${PLUGIN_TYPE_PREFIX}\``)
+  }
+}
+
+const snapshotWith = (previous, mod) => {
+  const modules = Object.freeze([...previous.modules, mod])
+  const byType = new Map(previous.byType)
+  byType.set(mod.type, mod)
+  return Object.freeze({ modules, byType, version: previous.version + 1 })
+}
+
+/**
+ * Register one block module. The public extension point (CONTRACT A4): a third
+ * party reaches this and nothing else, and never edits a file inside the SDK.
+ *
+ * @param {{type: string, schema: object, example: object, render: Function,
+ *   styleHooks: readonly string[], syntax?: object, validate?: Function,
+ *   create?: Function, nesting?: {arrays?: string[], matrices?: string[]}}} mod
+ */
+export function registerBlockModule(mod) {
+  assertModuleShape(mod, current.byType)
+  current = snapshotWith(current, mod)
+  return mod.type
+}
+
+/**
+ * Freeze the current vocabulary as the one `resetBlockRegistry` returns to.
+ * Called once, by the core vocabulary's own index — a plugin never calls it.
+ */
+export function sealCoreRegistry() {
+  baseline = current
+  sealed = true
+  return baseline.version
+}
+
+/** Drop every module registered after the core seal (test hygiene). */
+export function resetBlockRegistry() {
+  current = baseline
+  return current.version
+}
+
+/** Registered modules, in registration order. */
+export const blockModules = () => current.modules
+
+/** One module by type name, or undefined. */
+export const blockModule = (type) => current.byType.get(type)
+
+/** Registered type names, in registration order — the canonical block vocabulary. */
+export const blockTypes = () => current.modules.map((mod) => mod.type)
+
+/** The types registered beyond the core vocabulary (SPEC §12 `x-*` blocks). */
+export const pluginBlockTypes = () =>
+  current.modules.filter((mod) => !baseline.byType.has(mod.type)).map((mod) => mod.type)
+
+/** Bumped whenever the vocabulary changes; caches key off it. */
+export const registryVersion = () => current.version

package/src/blocks/schema-parts.js

@@ -0,0 +1,19 @@
+/**
+ * JSON Schema fragments shared by more than one block module.
+ *
+ * These are vocabulary *primitives* (a string, a list of child blocks), not a
+ * per-block table: nothing here knows which types exist. Each block module
+ * assembles its own `schema` out of them, and `core/schema.js` assembles the
+ * document schema out of the modules — one direction, no second list.
+ */
+
+export const str = Object.freeze({ type: 'string' })
+
+/** A flat array of child blocks. */
+export const children = Object.freeze({ type: 'array', items: { $ref: '#/$defs/block' } })
+
+/** A row of table cells — plain strings, already compiled to inline HTML. */
+export const cells = Object.freeze({ type: 'array', items: str })
+
+/** `list.items` is one block array *per list item* — an array of arrays. */
+export const itemGroups = Object.freeze({ type: 'array', items: children })

package/src/blocks/section.js

@@ -0,0 +1,53 @@
+import { el } from './element.js'
+import { str, children } from './schema-parts.js'
+
+/** Heading levels an HTML document actually has. */
+const MIN_LEVEL = 1
+const MAX_LEVEL = 6
+
+/**
+ * `section` — a heading and everything under it, already nested by the parser.
+ *
+ * The level is clamped rather than trusted: `id` and `h{level}` both flow into
+ * markup, and an out-of-range level would emit an element that does not exist.
+ */
+export default Object.freeze({
+  type: 'section',
+
+  schema: Object.freeze({
+    required: ['title', 'level', 'children'],
+    properties: {
+      title: str,
+      level: { type: 'integer', minimum: MIN_LEVEL, maximum: MAX_LEVEL },
+      children,
+    },
+  }),
+
+  example: Object.freeze({
+    block: { id: 'b2', type: 'section', title: '章節標題', level: 1, children: [] },
+  }),
+
+  nesting: Object.freeze({ arrays: Object.freeze(['children']) }),
+
+  styleHooks: Object.freeze([
+    'section',
+    'section-l1',
+    'section-l2',
+    'section-l3',
+    'section-l4',
+    'section-l5',
+    'section-l6',
+    'section-title',
+  ]),
+
+  create: ({ title, level, children: kids }) =>
+    Object.freeze({ type: 'section', title, level, children: kids }),
+
+  render: (block, ctx) => {
+    const level = Math.min(Math.max(block.level ?? MIN_LEVEL, MIN_LEVEL), MAX_LEVEL)
+    return el('section', { class: `section section-l${level}`, id: block.id }, [
+      el(`h${level}`, { class: 'section-title' }, [block.title]),
+      ...ctx.renderChildren(block.children),
+    ])
+  },
+})

package/src/blocks/slide.js

@@ -0,0 +1,104 @@
+import { el } from './element.js'
+import { children } from './schema-parts.js'
+import { GRID_COLUMNS, placementStyle } from './placement.js'
+
+/**
+ * `slide` — one page of a deck.
+ *
+ * `<section class="slide">` verbatim: the class attribute stays exactly one
+ * token so the container is greppable as a constant, and per-slide variation
+ * lives in the markup inside rather than in extra classes on the frame.
+ *
+ * The `slide-lead` slot is how a template puts something *before* a slide's own
+ * blocks — `kami/slides` uses it to give the opening slide the document's own
+ * identity. The rule "which slide gets it" is the template's, so this module
+ * only hands over the position and asks.
+ *
+ * ## What the slide asks the canvas for (F2f)
+ *
+ * A slide is where a deck's fixed logical canvas actually lands, and where its
+ * 24 grid tracks actually are. Both facts are the **layout's**, so this module
+ * asks `ctx.canvas` for them instead of assuming either:
+ *
+ *  - `canvasAttrs` non-null → this artifact has a fixed logical page, so the
+ *    section *is* that page and wears the size the skeleton scales it by.
+ *  - `gridAddressed` → the layout has declared the whole page addressable, so
+ *    the content region lays the tracks that make a bare `col: 17` resolve.
+ *
+ * A third-party deck-rooted layout that is flowing and unaddressed therefore
+ * gets exactly the markup this module emitted before F2f, byte for byte.
+ */
+
+/**
+ * Verbatim — the tracks a grid-addressed slide lays on its content region.
+ *
+ * Columns are 24 explicit `1fr` tracks, identical in form to the `grid` block's
+ * (`src/blocks/grid.js`), because they are the same 24 columns: one vocabulary,
+ * one geometry, spelled the same way in both places so a coordinate means the
+ * same thing wherever an author writes it.
+ *
+ * Rows are 24 **explicit `auto`** tracks, and that asymmetry is deliberate. A
+ * row of a fixed fraction of the slide's height would be the more literally
+ * "normalised" canvas, and it would also break 「不包＝預設流式」 (issue 14
+ * 裁決 2): content with no placement is auto-placed one item per row, so every
+ * paragraph taller than 1/24 of the page — which is nearly all of them — would
+ * spill into the next item. Declaring the rows as `auto` keeps `row: 12` a real
+ * declared line rather than an implicit one, and keeps unplaced blocks flowing
+ * down the slide exactly as they always have. What is given up is that a row
+ * index addresses an *order*, not a fraction of the height.
+ */
+export const SLIDE_GRID_STYLE =
+  `display: grid; grid-template-columns: repeat(${GRID_COLUMNS}, minmax(0, 1fr)); ` +
+  `grid-template-rows: repeat(${GRID_COLUMNS}, minmax(0, auto))`
+
+export default Object.freeze({
+  type: 'slide',
+
+  schema: Object.freeze({ required: ['children'], properties: { children } }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b16',
+      type: 'slide',
+      children: [{ id: 'b17', type: 'prose', html: '單張投影片的內容。' }],
+    },
+  }),
+
+  nesting: Object.freeze({ arrays: Object.freeze(['children']) }),
+
+  styleHooks: Object.freeze(['slide', 'slide-inner', 'slide-cell']),
+
+  create: ({ children: kids }) => Object.freeze({ type: 'slide', children: kids }),
+
+  /**
+   * On a grid-addressed slide every direct child of the content region becomes
+   * a **cell**, carrying that child's placement as inline geometry — the same
+   * shape, and the same `placementStyle`, the `grid` block uses.
+   *
+   * Every child, not only the placed ones: an unplaced block dropped straight
+   * into a 24-column grid would be one column wide. `placementStyle` already
+   * says what "no placement" means on a grid — `auto / span 24`, the full
+   * width — so wrapping uniformly is what makes 「不包＝預設流式」 survive the
+   * tracks instead of being quietly contradicted by them. The chrome a template
+   * fills the `slide-lead` slot with is wrapped for the same reason: it is a
+   * direct child too, and an unwrapped masthead would be a 1/24-wide masthead.
+   */
+  render: (block, ctx) => {
+    const addressed = ctx.canvas?.gridAddressed === true
+    const cell = (node, source) =>
+      el('div', { class: 'slide-cell', style: placementStyle(source) }, [node])
+    const drawable = ctx.drawableChildren(block.children)
+    const lead = ctx.chrome('slide-lead', ctx.position)
+    const inner = addressed
+      ? [
+          ...lead.map((node) => cell(node, null)),
+          ...drawable.map((kid, index) =>
+            cell(ctx.renderBlock(kid, { index, total: drawable.length }), kid),
+          ),
+        ]
+      : [...lead, ...ctx.renderChildren(block.children)]
+    return el('section', { class: 'slide', ...(ctx.canvas?.canvasAttrs ?? {}) }, [
+      el('div', { class: 'slide-inner', ...(addressed ? { style: SLIDE_GRID_STYLE } : {}) }, inner),
+    ])
+  },
+})

package/src/blocks/stat.js

@@ -0,0 +1,83 @@
+import { el } from './element.js'
+import { str } from './schema-parts.js'
+
+/**
+ * `stat` — the KPI wall (wayfinder issue 11 P1「資料」「stat（KPI 磚）」).
+ *
+ * One block is a *wall* of bricks rather than a single brick, following the
+ * shape the data group already uses: `table` is a whole table and `list` a
+ * whole list, never one cell and never one item. A lone tile would also have
+ * nothing to be a tile *of* — the reading of a KPI is comparative, so the row
+ * is the unit that carries meaning.
+ *
+ * ## Why the item has exactly two fields (issue 13 裁決 5 的同一條)
+ *
+ * `label` and `value`, both strings, `additionalProperties: false`. Everything
+ * a KPI tile is usually *also* asked to carry — unit, delta, trend arrow,
+ * target, threshold colour, icon, variant — is semantics layered on top of the
+ * measurement, and 13 號票 裁決 5 put that class of growth in a plugin kind
+ * rather than in the core schema. The battle-map palette (狀態色, effort) is
+ * the named example there and would arrive here first if the door were left
+ * open.
+ *
+ * `value` is a string, not a number, and that is not laziness: a KPI reads
+ * `87%`, `3.2x`, `NT$1.2M`. Formatting is a decision the author has already
+ * made by the time the block exists, and re-deriving it here would need a
+ * locale, a precision and a unit — three fields the narrow rule just refused.
+ *
+ * No inline geometry (unlike `grid`): a stat wall carries no coordinates in the
+ * IR, so there is no geometry that *is* the block. Side-by-side is paint, and
+ * paint is the template's, through the four hooks below.
+ */
+
+/** One brick: what was measured, and what it measured. */
+const statItem = Object.freeze({
+  type: 'object',
+  required: ['label', 'value'],
+  properties: { label: str, value: str },
+  additionalProperties: false,
+})
+
+export default Object.freeze({
+  type: 'stat',
+
+  schema: Object.freeze({
+    required: ['items'],
+    properties: { items: { type: 'array', minItems: 1, items: statItem } },
+  }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b22',
+      type: 'stat',
+      items: [
+        { label: '核心詞彙', value: '16 種' },
+        { label: '出廠文體', value: '5 種' },
+        { label: '外部請求', value: '0' },
+      ],
+    },
+  }),
+
+  styleHooks: Object.freeze(['stat', 'stat-tile', 'stat-value', 'stat-label']),
+
+  create: ({ items }) => Object.freeze({ type: 'stat', items }),
+
+  /**
+   * Value before label, in document order.
+   *
+   * A screen reader reads them in this order too, and the number is the thing
+   * the reader came for; the label only says what it was. A stylesheet that
+   * wants the label on top says so with `order`, which is paint.
+   */
+  render: (block) =>
+    el(
+      'div',
+      { class: 'stat' },
+      (block.items ?? []).map((item) =>
+        el('div', { class: 'stat-tile' }, [
+          el('span', { class: 'stat-value' }, [item.value]),
+          el('span', { class: 'stat-label' }, [item.label]),
+        ]),
+      ),
+    ),
+})

package/src/blocks/table.js

@@ -0,0 +1,50 @@
+import { el, rawEl } from './element.js'
+import { cells } from './schema-parts.js'
+
+/**
+ * `table` — head row plus body rows, every cell already inline-compiled.
+ *
+ * Two style hooks only, `.table-wrap` and `.table`. A stylesheet that needs to
+ * treat a two-column table differently selects on column count rather than
+ * asking the IR to carry an extra field: 模板樣式不得要求 IR 多帶資訊.
+ */
+export default Object.freeze({
+  type: 'table',
+
+  schema: Object.freeze({
+    required: ['head', 'rows'],
+    properties: { head: cells, rows: { type: 'array', items: cells } },
+  }),
+
+  example: Object.freeze({
+    block: { id: 'b9', type: 'table', head: ['欄位', '意義'], rows: [['id', 'block 識別碼']] },
+  }),
+
+  styleHooks: Object.freeze(['table-wrap', 'table']),
+
+  create: ({ head, rows }) => Object.freeze({ type: 'table', head, rows }),
+
+  render: (block) =>
+    el('div', { class: 'table-wrap' }, [
+      el('table', { class: 'table' }, [
+        el('thead', null, [
+          el(
+            'tr',
+            null,
+            block.head.map((cell) => rawEl('th', null, cell)),
+          ),
+        ]),
+        el(
+          'tbody',
+          null,
+          block.rows.map((row) =>
+            el(
+              'tr',
+              null,
+              row.map((cell) => rawEl('td', null, cell)),
+            ),
+          ),
+        ),
+      ]),
+    ]),
+})

package/src/blocks/timeline.js

@@ -0,0 +1,80 @@
+import { el } from './element.js'
+import { str } from './schema-parts.js'
+
+/**
+ * `timeline` — 時間軸 (wayfinder issue 11 P1「資料」).
+ *
+ * An ordered list of moments: each entry is `when` it happened and `what`
+ * happened, both plain strings.
+ *
+ * ## Why an entry carries no child blocks
+ *
+ * The obvious next field is a body — a paragraph, a callout, anything under
+ * each moment. It is deliberately absent, and the reason is structural rather
+ * than a taste call: nested blocks reach the id-assigning walk through a
+ * module's `nesting` declaration, which names *top-level* keys on the block
+ * (`children`, `slides`, `items`). Blocks buried inside an array of objects
+ * are reachable by neither shape, so they would silently receive no ids —
+ * and a block with no id has no block path, cannot be commented on, and
+ * cannot be reported when it fails validation. Growing the nesting vocabulary
+ * to a third shape is a registry change, and the registry is exactly what this
+ * slice may not touch.
+ *
+ * So an entry is flat, and a timeline that needs prose under a moment is a
+ * timeline followed by prose — or a plugin kind, per issue 13 裁決 5.
+ *
+ * `time` is a string and no format is imposed. A timeline legitimately mixes
+ * `2026-08`, `Q3`, `第三戰役` and `未定`; a date type would refuse three of
+ * those, and normalising them would need a calendar this block has no business
+ * knowing about.
+ */
+
+/** One moment: when, and what. */
+const timelineEntry = Object.freeze({
+  type: 'object',
+  required: ['time', 'label'],
+  properties: { time: str, label: str },
+  additionalProperties: false,
+})
+
+export default Object.freeze({
+  type: 'timeline',
+
+  schema: Object.freeze({
+    required: ['items'],
+    properties: { items: { type: 'array', minItems: 1, items: timelineEntry } },
+  }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b23',
+      type: 'timeline',
+      items: [
+        { time: '2026-08-19', label: '轉子接口定案，block 模組化' },
+        { time: '2026-08-24', label: '五文體終局，骨架資產歸位' },
+        { time: '2026-08-25', label: '四型資料 block 落地' },
+      ],
+    },
+  }),
+
+  styleHooks: Object.freeze(['timeline', 'timeline-entry', 'timeline-time', 'timeline-label']),
+
+  create: ({ items }) => Object.freeze({ type: 'timeline', items }),
+
+  /**
+   * `<ol>` rather than `<div>`: a timeline *is* an ordered sequence, and the
+   * ordering is semantic, not visual. A reader on a screen reader hears "list,
+   * 3 items" and can move through it; a stack of divs is silent about that.
+   */
+  render: (block) =>
+    el(
+      'ol',
+      { class: 'timeline' },
+      (block.items ?? []).map((entry) =>
+        el('li', { class: 'timeline-entry' }, [
+          el('span', { class: 'timeline-time' }, [entry.time]),
+          el('span', { class: 'timeline-label' }, [entry.label]),
+        ]),
+      ),
+    ),
+})

package/src/cli/commands/close.js

@@ -0,0 +1,51 @@
+import { CODES, EXIT, KsbError } from '../../core/errors.js'
+import { clearServeRecords, isAlive, readServeRecords } from '../../delivery/run.js'
+
+/**
+ * `kamishibai close` (CONTRACT E1).
+ *
+ * Idempotent by construction: "there is no server running" is a *success*, not
+ * an error. The command answers one question — "is anything this SDK started
+ * still running?" — and the only honest post-condition is "no". A `close` that
+ * failed when the server was already gone would train every caller to ignore
+ * its exit code, which is how the orphan-daemon trap (G2) reopens.
+ *
+ * Every recorded server is signalled, not just the newest: an orphan is by
+ * definition the one nobody remembers, so `close` must not depend on being told
+ * which process to stop.
+ *
+ * @returns {{result: {ok: true, closed: number[], stale: number[]}, exitCode: number}}
+ */
+export function closeCommand(options = {}, env = process.env) {
+  const records = readServeRecords(env)
+  const closed = []
+  const stale = []
+  const failures = []
+
+  for (const record of records) {
+    if (!isAlive(record.pid)) {
+      stale.push(record.pid)
+      continue
+    }
+    try {
+      process.kill(record.pid, 'SIGTERM')
+      closed.push(record.pid)
+    } catch (cause) {
+      failures.push(`${record.pid}（${cause.message}）`)
+    }
+  }
+
+  if (failures.length > 0) {
+    // The pidfile is deliberately left intact: a server we could not stop is
+    // still running, and forgetting it would make the next `close` claim there
+    // was nothing to do.
+    throw new KsbError({
+      code: CODES.SERVE_CLOSE_FAILED,
+      message: `無法終止 serve 程序：${failures.join('、')}`,
+      exitCode: EXIT.VALIDATION,
+    })
+  }
+
+  clearServeRecords(env)
+  return { result: { ok: true, closed, stale }, exitCode: EXIT.OK }
+}

package/src/cli/commands/comments.js

@@ -0,0 +1,73 @@
+import { EXIT, usageError } from '../../core/errors.js'
+import { readArtifact } from '../../delivery/read.js'
+import { readEmbeddedIr } from '../../parser/artifact.js'
+import { appendComment, listComments, resolveComment } from '../../delivery/comments.js'
+import { collectBlockIds } from '../../core/blocks.js'
+
+/**
+ * `kamishibai comments <artifact> [--json]`
+ * `kamishibai comments resolve <artifact> <id>`
+ * `kamishibai comments add <artifact> <blockId> <text…>`
+ *
+ * The Agent end of SPEC §13.1's loop: read what a human said about which block,
+ * edit the IR, `replay`, then mark it resolved.
+ *
+ * `add` is the CLI mirror of the overlay's POST and shares its one
+ * implementation. It exists so the write path — including the anchor check that
+ * makes a comment trustworthy — is reachable and assertable without a browser;
+ * two write paths that only *ought* to validate the same way is exactly the
+ * drift that would let an unanchored comment into the log.
+ */
+
+const SUBCOMMANDS = Object.freeze(['resolve', 'add'])
+
+const listing = (artifactPath) => {
+  const { path } = readArtifact(artifactPath)
+  return { result: listComments(path), exitCode: EXIT.OK }
+}
+
+const adding = (artifactPath, blockId, textParts) => {
+  const { html, path } = readArtifact(artifactPath)
+  const entry = appendComment({
+    artifactPath: path,
+    blockId,
+    text: textParts.join(' '),
+    // Legal anchors are read off the artifact's own embedded IR — the same
+    // source the served page shows, so an id that was pickable is appendable.
+    blockIds: collectBlockIds(readEmbeddedIr(html, path).doc),
+  })
+  return { result: { ok: true, ...entry }, exitCode: EXIT.OK }
+}
+
+const resolving = (artifactPath, id) => {
+  const { path } = readArtifact(artifactPath)
+  const entry = resolveComment({ artifactPath: path, id })
+  return { result: { ok: true, ...entry }, exitCode: EXIT.OK }
+}
+
+/**
+ * @param {string[]} args the raw positional words, so the three documented call
+ *   forms stay spelled exactly as CONTRACT E2 writes them
+ */
+export function commentsCommand(args = []) {
+  const [head, ...rest] = args
+
+  if (head === undefined) throw usageError('comments 需要一個產物路徑')
+
+  if (!SUBCOMMANDS.includes(head)) {
+    if (rest.length > 0) throw usageError(`comments 不認得多餘的參數：${rest.join(' ')}`)
+    return listing(head)
+  }
+
+  const [artifact, ...tail] = rest
+  if (artifact === undefined) throw usageError(`comments ${head} 需要一個產物路徑`)
+
+  if (head === 'resolve') {
+    if (tail.length !== 1) throw usageError('comments resolve <artifact> <id> 需要恰好一個留言 id')
+    return resolving(artifact, tail[0])
+  }
+
+  if (tail.length < 2) throw usageError('comments add <artifact> <blockId> <text> 需要 block id 與留言內容')
+  const [blockId, ...text] = tail
+  return adding(artifact, blockId, text)
+}