@kamishibai/sdk 0.1.1

package/README.md

@@ -0,0 +1,192 @@
+# kamishibai（紙芝居）
+
+**Agent Presentation SDK** — Agent 著作結構化內容，SDK 確定性地渲染成可單獨生存的離線單檔產物。
+
+> *An agent authors structured content; the SDK deterministically renders it into a self-contained offline artifact.*
+
+---
+
+## 這是什麼
+
+讓 LLM agent 直接手寫 HTML 是昂貴且不可驗收的：它得為每一份文件重新產出一套 CSS、手算 SVG 座標，
+而產物沒有任何機器可檢查的品質閘。
+
+kamishibai 把這件事切開：
+
+```
+agent 寫 Markdown 超集  →  SDK 解析成 block tree IR  →  確定性渲染成離線單檔 HTML
+                                                    ↘  lint 驗收（exit 0 才算數）
+```
+
+**Agent 負責內容，SDK 負責版面、遞送與持久化。** 渲染過程沒有模型參與，所以它是確定性的、
+可重播的、可驗收的。
+
+### 實測差異
+
+同一份繁中技術文件（12 KB）、同一交付目標，兩個同型號 agent 分別走兩條路：
+
+| | 走 kamishibai | 手寫 HTML |
+|---|---|---|
+| **agent 產出的 token** | **8,557** | **21,465**（2.51×） |
+| 耗時 | 184 s | 371 s（2.02×） |
+| 品質閘 | `lint` exit 0，首發即過 | 無 |
+
+手寫路徑的 token 有 **40%** 花在 CSS 設計系統與手算 SVG 座標上——**而那是每份新文件都要重付的**。
+
+量測方法與完整數字：[`.claude/research/2026-08-19-perf-token-benchmark.md`](.claude/research/2026-08-19-perf-token-benchmark.md)
+
+---
+
+## 快速開始
+
+需要 Node.js（ESM）。
+
+```bash
+git clone https://github.com/TLOGBen/kamishibai
+cd kamishibai
+npm install
+
+node ./src/cli/index.js setup --json                              # 建中央儲存庫、確認渲染用瀏覽器
+node ./src/cli/index.js example doc > demo.md                     # 要一份合法範例
+node ./src/cli/index.js render demo.md -o demo.html --json        # 渲染
+node ./src/cli/index.js lint demo.html --json                     # 驗收（exit 0 才算數）
+node ./src/cli/index.js snapshot demo.html -o demo.png --json     # 自己看一眼
+```
+
+你會得到 `demo.html`（離線單檔、內嵌 IR）、正典副本 `~/.kamishibai/artifacts/<專案>/demo.html`，
+以及一張 PNG。
+
+> 用 nvm 管 node 的話，非互動 shell 讀不到 PATH——每一行包 `zsh -lic '...'`。
+
+---
+
+## 產物長什麼樣
+
+- **單檔、離線、零外部請求** — 字體以 unicode-range 子集化後 base64 內嵌；`lint` 會擋下任何外部引用
+- **內嵌 IR** — 產物裡帶著自己的 block tree（`<script type="application/kamishibai+json">`），
+  所以 `replay` 可以只憑產物換模板、升版、換皮
+- **確定性** — 同一份 IR 永遠渲染出同樣的位元組；圖表版面是純整數運算，不量測文字、不用亂數
+
+實測：`example doc`（1.7 KB 來源）→ 2.34 MB HTML，熱身後 **18 ms**；
+31 KB 來源 → 3.22 MB HTML，**34 ms**。產物大小主要是內嵌字體的常數項（94–97%）。
+
+---
+
+## 著作格式
+
+帶 frontmatter 的 Markdown 超集：
+
+````markdown
+---
+title: 範例文件
+kicker: KAMISHIBAI EXAMPLE
+template: kami/long-form
+---
+
+# 第一章
+
+這是 **prose** 區塊，支援行內 Markdown。
+
+:::note
+這是 callout。另有 `:::warn`。
+:::
+
+```diagram
+{
+  "kind": "graph",
+  "nodes": [{ "id": "ir", "label": "block tree" }, { "id": "out", "label": "離線產物" }],
+  "edges": [{ "from": "ir", "to": "out", "label": "render" }]
+}
+```
+````
+
+`diagram` fence 裡是**結構化 spec，不是座標**——版面由 SDK 算，agent 不必手畫。
+
+也可以直接餵 block tree JSON。`kamishibai schema` 會吐出 IR 的 JSON Schema（draft 2020-12），
+`kamishibai example <kind>` 會吐出任一 block 的合法範例。
+
+**核心 block 型別**（11 種）：`section` `prose` `quote` `callout` `code` `table` `raw` `list`
+`deck` `slide` `diagram`
+
+---
+
+## CLI
+
+| 指令 | 用途 |
+|---|---|
+| `render <input>` | Markdown 超集／block JSON → 離線單檔 HTML |
+| `lint <artifact>` | 驗收：零外部請求、內嵌 IR 齊備且通過 schema |
+| `replay <artifact>` | 由產物內嵌 IR 重繪（換模板／升版／換皮） |
+| `serve <input>` | 本地預覽，來源檔一變就重繪推播 reload |
+| `close` | 終止本 SDK 起的預覽伺服器 |
+| `export <artifact>` | document → PDF、deck → PPTX |
+| `snapshot <artifact>` | 截成 PNG，讓 agent（與人）看得到視覺效果 |
+| `comments <args...>` | 讀寫產物留言，以 block id 錨定 |
+| `open <name>` / `list` | 由中央產物庫解析並開啟／列出呈現史 |
+| `templates` | 列出中央儲存庫已註冊的模板包 |
+| `example [kind]` / `schema` | 輸出合法範例／IR JSON Schema |
+| `setup` / `debug` | 初始化環境／診斷 |
+
+所有指令支援 `--json`，供 agent 直接解析。
+
+---
+
+## 出廠模板
+
+| key | root | 用途 |
+|---|---|---|
+| `kami/long-form` | document | 長文件、報告 |
+| `kami/slides` | deck | 簡報（鍵盤翻頁、fullscreen、無 JS 時降級為捲動長文） |
+
+模板決定 `---` 是不是分頁、決定產物長相；同一份 IR 換模板即換皮。
+
+---
+
+## 中央儲存庫
+
+`~/.kamishibai/` 是真實落點——每次 `render` 都會存一份正典副本，
+所以「上次那份簡報」永遠找得回來、重繪得出來。
+
+```
+~/.kamishibai/
+├── artifacts/<專案>/<slug>.html     # 正典產物（與遞送副本位元組相同）
+└── templates/<namespace>/<name>/    # 模板包命名空間
+```
+
+---
+
+## 專案狀態
+
+**v0.1.0 — 可用，但仍在成形中。** 已封緘的切片：渲染／IR／lint、持久化／replay、
+圖表／export／snapshot、serve／comment loop、模板命名空間。
+
+已知未完成（見報告 §5–§6）：
+
+- 中央儲存庫的模板命名空間目前**只是登記簿，還不是載入點**——第三方模板列得出來、還載不進去
+- **slot／plugin 擴充層尚未實作**（`SPEC.md` §11–§12 已定義機制）
+- diagram v1 只有一種 kind（`graph`），節點語意色／群組框／虛線邊等待 plugin 層
+- 沒有版面座標系；自訂版面目前只能走 `raw-html` 逃生艙
+
+---
+
+## 文件
+
+| 檔案 | 給誰看 |
+|---|---|
+| [`SPEC.md`](SPEC.md) | 實作用規格書 |
+| [`AGENTS.md`](AGENTS.md) | 在本 repo 內開發 SDK 的 agent |
+| [`.claude/wayfinder/kamishibai-sdk/`](.claude/wayfinder/kamishibai-sdk/) | 決策地圖與 12 張票面（**規格真源**） |
+| [`.claude/research/`](.claude/research/) | 查證與量測報告 |
+
+規格衝突時，以票面的 `## Answer` 為準。
+
+---
+
+## License
+
+**尚未授權（`UNLICENSED`）——保留所有權利。**
+
+本專案仍在成形中，v1.0 之前不附授權條款：你可以閱讀原始碼，但未獲授權使用、修改或再散布。
+
+`issues/09-public-packaging.md` 已定案**最終採 MIT**，但要等實作收斂、第三方資產的授權盤點完成（見 `.claude/research/tsanger-jinkai02-license.md`）之後才生效。
+屆時會補上 `LICENSE` 與 `THIRD_PARTY_LICENSES`——出廠字體 Noto Serif TC 走 SIL OFL 1.1，須保留自身授權全文，**不得併入 MIT 宣告**。

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@kamishibai/sdk",
+  "version": "0.1.1",
+  "description": "Agent Presentation SDK — agents author a structured IR; the SDK deterministically renders self-contained offline single-file HTML artifacts (five genres, template packages, replay/resk in, lint gates).",
+  "main": "index.js",
+  "directories": {
+    "test": "tests"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TLOGBen/kamishibai.git"
+  },
+  "keywords": [
+    "agent",
+    "presentation",
+    "sdk",
+    "html",
+    "renderer",
+    "claude",
+    "ir",
+    "offline",
+    "single-file"
+  ],
+  "author": "",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/TLOGBen/kamishibai/issues"
+  },
+  "homepage": "https://github.com/TLOGBen/kamishibai#readme",
+  "bin": {
+    "kamishibai": "src/cli/index.js"
+  },
+  "dependencies": {
+    "@fontsource/noto-serif-tc": "^5.3.0",
+    "ajv": "^8.20.0",
+    "commander": "^15.0.0",
+    "gray-matter": "^4.0.3",
+    "markdown-it": "^15.0.0",
+    "playwright": "^1.62.1",
+    "pptxgenjs": "^4.0.1",
+    "vue": "^3.5.41"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  },
+  "files": [
+    "src",
+    "templates"
+  ]
+}

package/src/blocks/board.js

@@ -0,0 +1,210 @@
+import { el } from './element.js'
+import { str } from './schema-parts.js'
+
+/**
+ * `board` — 卡片看板 (wayfinder issue 11 P1「資料」; 篩選互動 issue 11 P5).
+ *
+ * Shaped like `diagram`, not like a nest: lanes and cards are two flat arrays,
+ * and a card names its lane by id. That is the one field this slice added
+ * beyond the narrowest possible schema, so it owes an argument.
+ *
+ * ## Why `card.lane` is allowed in under the narrow rule
+ *
+ * 13 號票 裁決 5 keeps the core narrow by sending *semantic decoration* to a
+ * plugin kind — 副標, variant, 群組, and the battle-map palette (狀態色, effort)
+ * are its named examples. `lane` is none of those: without it there is no board
+ * at all, only a pile of cards. It is the same class of field as `edge.from` in
+ * a graph — a **referential** field that constitutes the structure, not one
+ * that describes it. The alternative shape (lanes each carrying their own card
+ * array) needs no reference field, but buries the cards inside an array of
+ * objects, where the id-assigning walk cannot reach them: every card would
+ * render with no id and therefore no block path (the same wall `timeline`
+ * documents). So the reference is the shape that keeps every card addressable.
+ *
+ * Everything else stays out. A card is `{lane, title}` and nothing more: no
+ * status colour, no assignee, no effort, no order key, no tags. The battle-map
+ * client that wants those gets them as an `x-*` plugin kind or as template
+ * config, which is 13 號票 裁決 5 read literally.
+ *
+ * ## The filter (issue 11 P5)
+ *
+ * The buttons are drawn here, server-side, so the lane vocabulary is visible in
+ * the artifact whether or not the script runs. Each button is labelled with its
+ * *lane's own label* — the SDK writes no user-facing word of its own, which is
+ * the rule `callout` had to be rescued from (CONTRACT A7). There is deliberately
+ * no 「all」 button for the same reason: pressing an active lane again releases
+ * it, so returning to the full board needs no word from anybody.
+ */
+
+/** A column of the board. `id` is what a card points at, so it may not be empty. */
+const boardLane = Object.freeze({
+  type: 'object',
+  required: ['id', 'label'],
+  properties: { id: { ...str, minLength: 1 }, label: str },
+  additionalProperties: false,
+})
+
+/** One card. `lane` is a reference, not a description — see the header. */
+const boardCard = Object.freeze({
+  type: 'object',
+  required: ['lane', 'title'],
+  properties: { lane: { ...str, minLength: 1 }, title: str },
+  additionalProperties: false,
+})
+
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0
+
+/**
+ * Every problem with one board block, as human-readable messages.
+ *
+ * A card pointing at a lane nobody declared is the failure that matters, and no
+ * JSON Schema keyword can express it: the card is well-formed, the lane list is
+ * well-formed, and the reference between them is the only thing that is wrong.
+ * Drawing anyway would put the card nowhere — it would simply not appear, which
+ * is exactly the silent data loss `manifest.blocks` and `assertBlockSpecs` both
+ * exist to refuse.
+ */
+export function boardProblems(block) {
+  const problems = []
+
+  const lanes = block?.lanes
+  if (!Array.isArray(lanes) || lanes.length === 0) {
+    problems.push('board.lanes 必須是至少一個欄位的陣列')
+    return problems
+  }
+
+  const ids = new Set()
+  for (const [index, lane] of lanes.entries()) {
+    if (!isNonEmptyString(lane?.id)) {
+      problems.push(`lanes[${index}].id 必須是非空字串`)
+      continue
+    }
+    if (ids.has(lane.id)) {
+      problems.push(`lanes[${index}].id "${lane.id}" 重複；欄位 id 必須唯一`)
+      continue
+    }
+    ids.add(lane.id)
+    if (typeof lane.label !== 'string') {
+      problems.push(`lanes[${index}].label（id "${lane.id}"）必須是字串`)
+    }
+  }
+
+  const cards = block?.cards
+  if (!Array.isArray(cards)) {
+    problems.push('board.cards 必須是陣列（沒有卡片就給空陣列）')
+    return problems
+  }
+  for (const [index, card] of cards.entries()) {
+    if (!isNonEmptyString(card?.lane)) {
+      problems.push(`cards[${index}].lane 必須是非空字串`)
+      continue
+    }
+    if (!ids.has(card.lane)) {
+      problems.push(
+        `cards[${index}].lane 指向不存在的欄位 "${card.lane}"；` +
+          `已宣告的欄位：${[...ids].join(', ')}`,
+      )
+    }
+  }
+  return problems
+}
+
+/** The cards belonging to one lane, in document order. */
+const cardsOf = (cards, laneId) => cards.filter((card) => card?.lane === laneId)
+
+export default Object.freeze({
+  type: 'board',
+
+  schema: Object.freeze({
+    required: ['lanes', 'cards'],
+    properties: {
+      lanes: { type: 'array', minItems: 1, items: boardLane },
+      cards: { type: 'array', items: boardCard },
+    },
+  }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b24',
+      type: 'board',
+      lanes: [
+        { id: 'todo', label: '待辦' },
+        { id: 'doing', label: '進行中' },
+        { id: 'done', label: '已完成' },
+      ],
+      cards: [
+        { lane: 'todo', title: 'figure／video 兩型落地' },
+        { lane: 'doing', title: '四型資料 block 落地' },
+        { lane: 'done', title: '五文體終局' },
+        { lane: 'done', title: '轉子接口與模組註冊表' },
+      ],
+    },
+  }),
+
+  styleHooks: Object.freeze([
+    'board',
+    'board-filters',
+    'board-filter',
+    'board-lanes',
+    'board-lane',
+    'board-lane-label',
+    'board-card',
+  ]),
+
+  create: ({ lanes, cards }) => Object.freeze({ type: 'board', lanes, cards }),
+
+  validate: boardProblems,
+
+  /**
+   * How a failed `validate` is reported. Plain data because this layer imports
+   * nothing — the core turns it into a `KsbError` with the block path attached
+   * (`test_f1_validate_codes_match_core` pins the spelling against `CODES`).
+   */
+  invalid: Object.freeze({
+    code: 'KSB_BOARD_INVALID',
+    message: (problems) =>
+      `board block 無法繪製：${problems.join('；')}。` +
+      '指向不存在欄位的卡片不會報錯、只會不出現——那正是看板最看不出來的資料遺失。',
+  }),
+
+  /**
+   * The filter's DOM contract, stated here because the client asset reads it:
+   * `data-board` scopes one board against every other board on the page, and
+   * `data-board-lane` is carried by the button, the lane and every card, so the
+   * script never has to know how a lane relates to its cards.
+   */
+  render: (block) => {
+    const lanes = block.lanes ?? []
+    const cards = block.cards ?? []
+    return el('section', { class: 'board', 'data-board': block.id }, [
+      el(
+        'div',
+        { class: 'board-filters' },
+        lanes.map((lane) =>
+          el(
+            'button',
+            {
+              type: 'button',
+              class: 'board-filter',
+              'data-board-lane': lane.id,
+              'aria-pressed': 'false',
+            },
+            [lane.label],
+          ),
+        ),
+      ),
+      el(
+        'div',
+        { class: 'board-lanes' },
+        lanes.map((lane) =>
+          el('div', { class: 'board-lane', 'data-board-lane': lane.id }, [
+            el('div', { class: 'board-lane-label' }, [lane.label]),
+            ...cardsOf(cards, lane.id).map((card) =>
+              el('article', { class: 'board-card', 'data-board-lane': lane.id }, [card.title]),
+            ),
+          ]),
+        ),
+      ),
+    ])
+  },
+})

package/src/blocks/callout.js

@@ -0,0 +1,63 @@
+import { el } from './element.js'
+import { children } from './schema-parts.js'
+
+/** The variants the parser recognises after `:::`. */
+export const CALLOUT_VARIANTS = Object.freeze(['note', 'warn'])
+
+/**
+ * `callout` — an aside with a label.
+ *
+ * The label *text* is deliberately absent from this module. It used to live in
+ * the shared conversion path as a table of user-visible English words, which
+ * meant a template that wanted 「注意」, an icon, or no label at all could only
+ * fork the renderer. Wording is decoration, decoration belongs to the template,
+ * so the label arrives through the template's own `blockConfig.callout.labels`
+ * (CONTRACT A7). A variant the template did not name gets no label — silence,
+ * rather than someone else's word: falling back to a *sibling* variant's label
+ * would put 「NOTE」 on a warning, which is worse than an unlabelled box and
+ * invisible to every test that only renders the variants a template declared.
+ */
+export default Object.freeze({
+  type: 'callout',
+
+  schema: Object.freeze({
+    required: ['variant', 'children'],
+    properties: { variant: { enum: [...CALLOUT_VARIANTS] }, children },
+  }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b6',
+      type: 'callout',
+      variant: 'note',
+      children: [{ id: 'b7', type: 'prose', html: '提示內容。' }],
+    },
+  }),
+
+  nesting: Object.freeze({ arrays: Object.freeze(['children']) }),
+
+  /**
+   * The `:::note` / `:::warn` fences, declared rather than hard-coded in the
+   * parser. `parser/container.js` used to import `CALLOUT_VARIANTS` directly,
+   * which made the Markdown superset the one surface a third-party block still
+   * could not reach (wayfinder issue 13 的十一檔問題最後一處).
+   */
+  syntax: Object.freeze({
+    containers: CALLOUT_VARIANTS,
+    build: ({ name, children: kids }) => ({ type: 'callout', variant: name, children: kids }),
+  }),
+
+  styleHooks: Object.freeze(['callout', 'callout-note', 'callout-warn', 'callout-label']),
+
+  create: ({ variant, children: kids }) =>
+    Object.freeze({ type: 'callout', variant, children: kids }),
+
+  render: (block, ctx) => {
+    const labels = ctx.config('callout').labels ?? {}
+    const label = labels[block.variant] ?? ''
+    return el('aside', { class: `callout callout-${block.variant}` }, [
+      el('span', { class: 'callout-label' }, [label]),
+      ...ctx.renderChildren(block.children),
+    ])
+  },
+})

package/src/blocks/code.js

@@ -0,0 +1,28 @@
+import { el } from './element.js'
+import { str } from './schema-parts.js'
+
+/**
+ * `code` — a fenced block, rendered verbatim.
+ *
+ * The `language-*` class is the highlight.js/Prism convention, emitted only
+ * when the fence declared a language: an empty `language-` class would claim a
+ * language that is not there.
+ */
+export default Object.freeze({
+  type: 'code',
+
+  schema: Object.freeze({ required: ['lang', 'text'], properties: { lang: str, text: str } }),
+
+  example: Object.freeze({
+    block: { id: 'b8', type: 'code', lang: 'js', text: 'export const x = 1' },
+  }),
+
+  styleHooks: Object.freeze(['code', 'language-*']),
+
+  create: ({ lang, text }) => Object.freeze({ type: 'code', lang, text }),
+
+  render: (block) =>
+    el('pre', { class: 'code' }, [
+      el('code', { class: block.lang ? `language-${block.lang}` : null }, [block.text]),
+    ]),
+})

package/src/blocks/deck.js

@@ -0,0 +1,76 @@
+import { el } from './element.js'
+import { children } from './schema-parts.js'
+
+/**
+ * The canonical deck source. `---` is a page break *only* under the slides
+ * template, so the frontmatter is load-bearing — copying the body under
+ * `kami/long-form` gives a document with the breaks silently dropped.
+ */
+export const EXAMPLE_DECK = `---
+title: 範例簡報
+kicker: KAMISHIBAI EXAMPLE
+author: kamishibai
+template: kami/slides
+---
+
+# 第一張　開場
+
+首張自動帶出 frontmatter 的 title 與 kicker。
+
+---
+
+# 第二張　構件
+
+- 清單、callout、程式碼、表格都與長文模板同源
+- \`---\` 前後各留一個空行，否則 Markdown 會把它讀成 setext 標題
+
+:::note
+產物內建播放：方向鍵／空白鍵翻頁，f 全螢幕，Esc 離開。
+:::
+
+---
+
+# 第三張　收束
+
+\`\`\`js
+export const slides = (deck) => deck.slides.length
+\`\`\`
+`
+
+/**
+ * `deck` — the root container of a slide artifact.
+ *
+ * It draws the frame and nothing else. The progress readout and the keyboard
+ * hint are wording, so they arrive through the `deck-chrome` slot the template
+ * fills; the playback behaviour is skeleton, so it arrives from the render
+ * layer (wayfinder issue 13 P3) rather than from either of them.
+ *
+ * `data-template` sits here because this element *is* the artifact's outermost
+ * container under a deck-rooted template — the same place `kami/long-form`
+ * puts it on `article.paper`.
+ */
+export default Object.freeze({
+  type: 'deck',
+
+  schema: Object.freeze({ required: ['slides'], properties: { slides: children } }),
+
+  /**
+   * A deck's teachable example is a whole Markdown-superset source, not one
+   * block: it is the form that can be piped straight back into `render -`.
+   */
+  example: Object.freeze({ source: EXAMPLE_DECK }),
+
+  nesting: Object.freeze({ arrays: Object.freeze(['slides']) }),
+
+  styleHooks: Object.freeze(['deck']),
+
+  create: ({ slides }) => Object.freeze({ type: 'deck', slides }),
+
+  render: (block, ctx) => {
+    const slides = block.slides ?? []
+    return el('div', { class: 'deck', 'data-template': ctx.templateKey }, [
+      ...slides.map((slide, index) => ctx.renderBlock(slide, { index, total: slides.length })),
+      ...ctx.chrome('deck-chrome', { total: slides.length }),
+    ])
+  },
+})