@kamishibai/sdk 0.1.1

package/src/render/templates.js

@@ -0,0 +1,191 @@
+import cards from '../../templates/kami/cards/index.js'
+import longForm from '../../templates/kami/long-form/index.js'
+import onePage from '../../templates/kami/one-page/index.js'
+import resume from '../../templates/kami/resume/index.js'
+import slides from '../../templates/kami/slides/index.js'
+import { CODES, validationError } from '../core/errors.js'
+
+/**
+ * Factory template registry (SPEC §6.1 出廠內建模板家族).
+ *
+ * One entry per 文體, because every layout ships a built-in generic template so
+ * `render` can never fail for want of one (`registry.js` の defaultTemplate).
+ * `kami/cards` joined in F2c with the `card` 文體 itself, `kami/one-page` in F2d
+ * with `one-page`, and `kami/resume` in F2e with `resume` — the fifth and last
+ * of the v1 set.
+ */
+const REGISTRY = new Map([
+  [cards.key, cards],
+  [longForm.key, longForm],
+  [onePage.key, onePage],
+  [resume.key, resume],
+  [slides.key, slides],
+])
+
+/**
+ * Additional places a template may come from, consulted after the factory
+ * registry (CONTRACT F3 D1, P4「解析鏈＝出廠 registry 優先 → store」).
+ *
+ * Until F3 this list did not exist and `resolveTemplate` read the map above and
+ * nothing else — which is why a package could be installed, listed by
+ * `templates` and counted by `debug`, and still come back
+ * `KSB_TEMPLATE_NOT_FOUND` when anyone tried to draw with it (量測報告 §5.2).
+ * The namespace was a ledger, not a loading point.
+ *
+ * A *source* rather than a hard-wired store lookup, because this layer must not
+ * learn where `~/.kamishibai` is: it renders, it does not deliver. The store
+ * installs itself from the delivery layer (`installTemplateStore`), the same
+ * inversion the block and layout registries already use.
+ */
+let sources = Object.freeze([])
+
+const reject = (message) => {
+  throw new TypeError(`invalid template source: ${message}`)
+}
+
+/**
+ * Register one template source — the public extension point of the chain.
+ *
+ * Shape-checked at registration for the reason the other two registries state:
+ * a source that cannot list or cannot load fails on the rarest path, deep
+ * inside a render, where the message would be about something else entirely.
+ *
+ * @param {{keys: () => string[], load: (key: string) => Promise<object|undefined>}} source
+ */
+export function registerTemplateSource(source) {
+  if (source === null || typeof source !== 'object') reject('not an object')
+  if (typeof source.keys !== 'function') reject('`keys` must be a function')
+  if (typeof source.load !== 'function') reject('`load` must be a function')
+  sources = Object.freeze([...sources, source])
+  return sources.length
+}
+
+/** Drop every registered source (test hygiene, and re-installation on a new HOME). */
+export function resetTemplateSources() {
+  sources = Object.freeze([])
+  return sources.length
+}
+
+export function listTemplateKeys() {
+  return [...REGISTRY.keys()].sort()
+}
+
+/**
+ * The namespaces the factory templates occupy — reserved (CONTRACT P4).
+ *
+ * Queried from the registry rather than frozen into a constant, per the F2a
+ * 封緘補丁 (c): a list captured at import time is a list a third party cannot
+ * see itself in.
+ */
+export function reservedNamespaces() {
+  return [...new Set([...REGISTRY.values()].map((t) => t.manifest.namespace))].sort()
+}
+
+const namespaceOf = (key) => String(key).split('/')[0]
+
+/**
+ * Whether a key names a store package squatting on a factory namespace — a
+ * package that exists on disk and can never be loaded (CONTRACT P4, 封緘 F2).
+ *
+ * The factory packages are themselves projected into the store, so being *in*
+ * `kami/` is not the test: being in `kami/` **without** being one of the factory
+ * templates is. One definition, because both consumers need exactly this
+ * predicate and a second copy would be free to disagree — the listing would then
+ * mark a package the resolver happily loaded, or worse, the other way round.
+ */
+export function isReservedKey(key) {
+  const bare = String(key ?? '').split('@')[0]
+  if (REGISTRY.has(bare)) return false
+  return reservedNamespaces().includes(namespaceOf(bare))
+}
+
+/**
+ * Every key `-t` could name on this machine **and actually get**: the factory
+ * family plus whatever the installed sources hold, minus the squatters.
+ *
+ * This is the list a `KSB_TEMPLATE_NOT_FOUND` prints, and it has to include the
+ * store: an error that recites only the two bundled templates, while the very
+ * package the user just installed sits unlisted, is how the store came to look
+ * broken in the first place.
+ *
+ * It equally has to *exclude* the unloadable ones (封緘 F2). This list is read
+ * as an offer — "try one of these" — so publishing a key that is refused the
+ * moment anyone takes the offer sends the reader in a circle, and the key it
+ * sends them to is precisely the one impersonating an official template. The
+ * listing (`templates`) still shows it, because that surface answers a different
+ * question: what is on disk. Here the question is what can be drawn with.
+ */
+export function availableTemplateKeys() {
+  const keys = new Set(listTemplateKeys())
+  for (const source of sources) {
+    for (const key of source.keys()) {
+      if (!isReservedKey(key)) keys.add(key)
+    }
+  }
+  return [...keys].sort()
+}
+
+/**
+ * The factory manifests as plain data, for layers that need to *describe* the
+ * built-ins without rendering with them (the store's template namespace, E3).
+ * Exposed from the registry rather than re-imported by the caller so a template
+ * added here cannot go unregistered on disk.
+ */
+export function builtinManifests() {
+  return listTemplateKeys().map((key) => REGISTRY.get(key).manifest)
+}
+
+/**
+ * A store package may not wear a factory namespace (CONTRACT P4).
+ *
+ * The factory packages are themselves projected into the store, so `kami/` is
+ * *expected* to be there — which is exactly what makes the squat dangerous. A
+ * `kami/`-named package would read as an official one to every human and every
+ * agent that lists the namespace, and the ordering rule alone (factory first)
+ * only protects the two keys that already exist: it would say nothing about
+ * `kami/report`. So the name is refused rather than merely out-ranked.
+ */
+function assertNotReserved(key) {
+  // The predicate itself lives in `isReservedKey` and is *called*, not restated
+  // (複驗 F-6). The earlier version repeated the namespace test here in a
+  // slightly different shape, so the comment's「單一定義」claim was already
+  // false: two spellings of one rule, free to drift apart, with the listing and
+  // the resolver each believing its own.
+  if (!isReservedKey(key)) return
+  const namespace = namespaceOf(key)
+  throw validationError(
+    `模板包 "${key}" 佔用了出廠保留的 namespace \`${namespace}\`；` +
+      `保留的 namespace：${reservedNamespaces().join(', ')}。` +
+      '庫裡的包不得冒用出廠名——冒用得逞的話，列表上它與出廠包長得一模一樣，' +
+      '而讀到的人無從分辨自己畫的是誰的模板。',
+    CODES.TEMPLATE_NAMESPACE_RESERVED,
+    'doc.meta.template',
+  )
+}
+
+/**
+ * Resolve `<namespace>/<name>[@version]`; the version part is advisory in S1.
+ *
+ * Chain: the factory registry first, then every installed source in
+ * registration order. Factory-first is what makes 「出廠名不可劫持」 structural
+ * rather than a matter of nobody having tried: a package planted at
+ * `kami/long-form` never gets asked.
+ */
+export async function resolveTemplate(key) {
+  const bare = String(key ?? '').split('@')[0]
+  const factory = REGISTRY.get(bare)
+  if (factory !== undefined) return factory
+
+  for (const source of sources) {
+    if (!source.keys().includes(bare)) continue
+    assertNotReserved(bare)
+    const loaded = await source.load(bare)
+    if (loaded !== undefined) return loaded
+  }
+
+  throw validationError(
+    `unknown template "${key}"; available: ${availableTemplateKeys().join(', ')}`,
+    CODES.TEMPLATE_NOT_FOUND,
+    'doc.meta.template',
+  )
+}

package/src/serve/daemon.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { basename, extname, resolve } from 'node:path'
+import { readSource } from '../delivery/read.js'
+import { archiveArtifact, refreshArtifact } from '../delivery/store.js'
+import { resolveCreatedAt } from '../core/ir.js'
+import { compileDocument } from '../render/compile.js'
+import { installTemplateStore } from '../delivery/template-package.js'
+import { EXIT, KsbError, ROOT_PATH, CODES } from '../core/errors.js'
+import { startServer } from './server.js'
+
+/**
+ * The detached half of `serve` (CONTRACT E1).
+ *
+ * `serve` has to return to the shell — an Agent that blocks on a preview server
+ * cannot do anything else, and a foreground server dies with the session that
+ * started it, which is precisely the state `close` exists to manage. So the CLI
+ * spawns this file detached and hands back the URL.
+ *
+ * The handshake is one JSON line on stdout, written the moment the port is
+ * really listening. That is what makes `serve` honest: the parent prints a URL
+ * only after something answers on it, and a failure here comes back as the same
+ * KSB_ finding shape any other command would have emitted, with its exit code.
+ */
+
+const parseArgs = (argv) => {
+  const options = {}
+  for (let i = 0; i < argv.length; i += 2) {
+    const key = String(argv[i] ?? '').replace(/^--/, '')
+    options[key] = argv[i + 1]
+  }
+  return options
+}
+
+const say = (payload) => {
+  try {
+    process.stdout.write(`${JSON.stringify(payload)}\n`)
+  } catch {
+    // The parent may already be gone; a preview server must not die of EPIPE.
+  }
+}
+
+const toFinding = (error) =>
+  error instanceof KsbError
+    ? { finding: error.toFinding(), exitCode: error.exitCode }
+    : {
+        finding: { path: ROOT_PATH, code: CODES.PARSE_FAILED, message: error?.message ?? String(error) },
+        exitCode: EXIT.VALIDATION,
+      }
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const input = resolve(String(options.input))
+  const project = String(options.project)
+  const port = Number(options.port ?? 0)
+
+  // `serve` and `render` must agree on what a source file becomes (see
+  // `compileDocument`), and that agreement now includes *which* templates exist:
+  // a preview that cannot open the package the exported artifact uses is the
+  // same drift, one layer up (F3 D1).
+  installTemplateStore(process.env)
+
+  const compile = async () => {
+    const { source, format } = readSource(input)
+    return await compileDocument({
+      source,
+      format,
+      template: options.template,
+      generator: options.generator,
+      createdAt: resolveCreatedAt(process.env),
+    })
+  }
+
+  // The session claims **one** name in the store and then keeps that copy alive
+  // (CONTRACT E1, seal patch F1). One name, because a live preview re-renders on
+  // every keystroke-save and archiving each of those would bury the project's
+  // presentation history under hundreds of near-identical records. *Alive*,
+  // because comments anchor to this artifact: if it froze at the opening render
+  // while the page moved on, a human could comment on a block the canonical does
+  // not contain, and the file meant to answer "which block did they mean?" would
+  // be the one thing unable to. So every later render replaces it atomically.
+  // Artifacts from other runs are never touched — history stays immutable.
+  const first = await compile()
+  const slug = basename(input, extname(input)) || 'document'
+  const { path: artifactPath } = archiveArtifact({
+    project,
+    slug,
+    html: first.html,
+    copies: [],
+    env: process.env,
+  })
+
+  // The first render is handed over rather than repeated, so the served bytes
+  // and the archived bytes are the same object; every later render goes through
+  // the real compiler.
+  const { url, port: actualPort, close } = await startServer({
+    compile,
+    initial: first,
+    persist: (rendered) => refreshArtifact(artifactPath, rendered.html),
+    sourcePath: input,
+    artifactPath,
+    port,
+  })
+
+  say({ ok: true, url, port: actualPort, pid: process.pid, artifact: artifactPath })
+
+  const shutdown = () => {
+    close().finally(() => process.exit(EXIT.OK))
+  }
+  process.on('SIGTERM', shutdown)
+  process.on('SIGINT', shutdown)
+}
+
+main().catch((error) => {
+  const { finding, exitCode } = toFinding(error)
+  say({ ok: false, errors: [finding], exitCode })
+  process.exit(exitCode)
+})

package/src/serve/overlay.js

@@ -0,0 +1,213 @@
+import { IR_SCRIPT_TYPE } from '../core/ir.js'
+import {
+  COMMENTS_PATH,
+  DEV_RUNTIME_MARKER,
+  ERROR_EVENT,
+  EVENTS_PATH,
+  RELOAD_EVENT,
+} from './protocol.js'
+
+/**
+ * The dev-only runtime: live-reload listener plus the block-anchored comment
+ * overlay (CONTRACT E1/E2, SPEC §13.1).
+ *
+ * **It is injected at serve time and never written to disk.** An artifact is a
+ * self-contained, offline, read-only document; a comment widget baked into one
+ * would POST to a server that no longer exists, and the file that a reader
+ * receives would carry behaviour they never asked for. So the artifact bytes
+ * on disk stay exactly what `render` produced, and the preview is the artifact
+ * *plus* this script — which is also why `render`/`replay` stay byte-identical
+ * while `serve` is running.
+ *
+ * **Anchoring reads the IR, it does not guess.** The overlay offers the block
+ * list straight out of the artifact's own embedded IR, so the id that reaches
+ * the log is one the artifact really contains and the human really chose. A
+ * click-to-anchor overlay would have to map DOM elements back onto blocks
+ * heuristically, and a heuristic that mis-anchors is worse than no anchor at
+ * all: the Agent would confidently edit the wrong block. Structured picking is
+ * the entire point of §13.1's「非自然語言猜謎」.
+ */
+
+/** Rendered inside the injected `<style>`; kept small and namespaced. */
+const OVERLAY_CSS = `
+.${DEV_RUNTIME_MARKER}{position:fixed;right:16px;bottom:16px;z-index:2147483000;
+font:13px/1.6 system-ui,-apple-system,"Noto Sans TC",sans-serif;color:#1a1a1a}
+.${DEV_RUNTIME_MARKER} button{font:inherit;cursor:pointer;border:1px solid #3a3a3a;
+background:#fff;color:#1a1a1a;border-radius:6px;padding:6px 12px}
+.${DEV_RUNTIME_MARKER}-panel{display:none;width:320px;max-height:60vh;overflow:auto;
+background:#fff;border:1px solid #3a3a3a;border-radius:8px;padding:12px;
+box-shadow:0 8px 24px rgba(0,0,0,.18);margin-bottom:8px}
+.${DEV_RUNTIME_MARKER}[data-open="1"] .${DEV_RUNTIME_MARKER}-panel{display:block}
+.${DEV_RUNTIME_MARKER} select,.${DEV_RUNTIME_MARKER} textarea{width:100%;font:inherit;
+margin:4px 0 8px;box-sizing:border-box;border:1px solid #bbb;border-radius:4px;padding:4px}
+.${DEV_RUNTIME_MARKER} textarea{height:72px;resize:vertical}
+.${DEV_RUNTIME_MARKER}-list{margin:8px 0 0;padding:0;list-style:none}
+.${DEV_RUNTIME_MARKER}-list li{border-top:1px solid #eee;padding:6px 0}
+.${DEV_RUNTIME_MARKER}-status{color:#8a4b00;min-height:1.6em}
+`.trim()
+
+/**
+ * The runtime source. Written as one string rather than a bundled module
+ * because it must survive being read by a browser with no build step and no
+ * network — the same constraint the artifacts themselves live under.
+ */
+const runtimeSource = () => `
+(function () {
+  var MARKER = ${JSON.stringify(DEV_RUNTIME_MARKER)};
+  var EVENTS = ${JSON.stringify(EVENTS_PATH)};
+  var COMMENTS = ${JSON.stringify(COMMENTS_PATH)};
+  var IR_TYPE = ${JSON.stringify(IR_SCRIPT_TYPE)};
+  var RELOAD = ${JSON.stringify(RELOAD_EVENT)};
+  var ERRORED = ${JSON.stringify(ERROR_EVENT)};
+
+  function readIr() {
+    var el = document.querySelector('script[type="' + IR_TYPE + '"]');
+    if (!el) return null;
+    try { return JSON.parse(el.textContent); } catch (e) { return null; }
+  }
+
+  function snippet(block) {
+    var text = block.title || block.text || block.html || '';
+    text = String(text).replace(/<[^>]*>/g, ' ').replace(/\\s+/g, ' ').trim();
+    return text.length > 28 ? text.slice(0, 28) + '…' : text;
+  }
+
+  /** Document-order walk over every nesting shape the IR uses. */
+  function walk(node, out) {
+    if (!node || typeof node !== 'object') return out;
+    if (typeof node.id === 'string') {
+      out.push({ id: node.id, type: node.type, label: snippet(node) });
+    }
+    var groups = [node.children, node.slides];
+    for (var g = 0; g < groups.length; g += 1) {
+      if (!Array.isArray(groups[g])) continue;
+      for (var i = 0; i < groups[g].length; i += 1) walk(groups[g][i], out);
+    }
+    if (Array.isArray(node.items)) {
+      for (var j = 0; j < node.items.length; j += 1) {
+        var item = node.items[j];
+        if (!Array.isArray(item)) continue;
+        for (var k = 0; k < item.length; k += 1) walk(item[k], out);
+      }
+    }
+    return out;
+  }
+
+  var ir = readIr();
+  var blocks = ir ? walk(ir.doc, []) : [];
+
+  var root = document.createElement('div');
+  root.className = MARKER;
+  root.setAttribute('data-open', '0');
+  root.innerHTML =
+    '<div class="' + MARKER + '-panel">' +
+    '<strong>留言（錨定 block）</strong>' +
+    '<select class="' + MARKER + '-block"></select>' +
+    '<textarea class="' + MARKER + '-text" placeholder="這個 block 要怎麼改？"></textarea>' +
+    '<button type="button" class="' + MARKER + '-send">送出</button>' +
+    '<p class="' + MARKER + '-status"></p>' +
+    '<ul class="' + MARKER + '-list"></ul>' +
+    '</div>' +
+    '<button type="button" class="' + MARKER + '-toggle">留言</button>';
+  document.body.appendChild(root);
+
+  var picker = root.querySelector('.' + MARKER + '-block');
+  var textarea = root.querySelector('.' + MARKER + '-text');
+  var status = root.querySelector('.' + MARKER + '-status');
+  var list = root.querySelector('.' + MARKER + '-list');
+
+  for (var b = 0; b < blocks.length; b += 1) {
+    var option = document.createElement('option');
+    option.value = blocks[b].id;
+    option.textContent = blocks[b].id + ' · ' + blocks[b].type +
+      (blocks[b].label ? ' · ' + blocks[b].label : '');
+    picker.appendChild(option);
+  }
+
+  function paint(entries) {
+    list.textContent = '';
+    for (var i = 0; i < entries.length; i += 1) {
+      var li = document.createElement('li');
+      li.textContent = '[' + entries[i].status + '] ' + entries[i].id + ' → ' +
+        entries[i].blockId + '：' + entries[i].text;
+      list.appendChild(li);
+    }
+  }
+
+  function refresh() {
+    fetch(COMMENTS, { headers: { accept: 'application/json' } })
+      .then(function (r) { return r.json(); })
+      .then(function (entries) { if (Array.isArray(entries)) paint(entries); })
+      .catch(function () { /* listing is a convenience; never block commenting */ });
+  }
+
+  root.querySelector('.' + MARKER + '-toggle').addEventListener('click', function () {
+    root.setAttribute('data-open', root.getAttribute('data-open') === '1' ? '0' : '1');
+    if (root.getAttribute('data-open') === '1') refresh();
+  });
+
+  root.querySelector('.' + MARKER + '-send').addEventListener('click', function () {
+    var body = { blockId: picker.value, text: textarea.value };
+    status.textContent = '送出中…';
+    fetch(COMMENTS, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body)
+    })
+      .then(function (r) { return r.json().then(function (j) { return { ok: r.ok, json: j }; }); })
+      .then(function (out) {
+        if (!out.ok) {
+          var first = out.json && out.json.errors && out.json.errors[0];
+          status.textContent = '失敗：' + (first ? first.code + ' ' + first.message : '未知錯誤');
+          return;
+        }
+        status.textContent = '已記錄 ' + out.json.id;
+        textarea.value = '';
+        refresh();
+      })
+      .catch(function (e) { status.textContent = '失敗：' + e.message; });
+  });
+
+  if (typeof EventSource === 'function') {
+    var source = new EventSource(EVENTS);
+    source.addEventListener(RELOAD, function () { location.reload(); });
+    source.addEventListener(ERRORED, function (event) {
+      status.textContent = '來源渲染失敗：' + event.data;
+      root.setAttribute('data-open', '1');
+    });
+  }
+})();
+`.trim()
+
+/**
+ * The full injected fragment: style, runtime, and a marker attribute so the
+ * "absent from artifacts" pin has one unambiguous thing to look for.
+ */
+export function devRuntimeFragment() {
+  return [
+    `<style data-${DEV_RUNTIME_MARKER}="1">${OVERLAY_CSS}</style>`,
+    `<script data-${DEV_RUNTIME_MARKER}="1">${runtimeSource()}</script>`,
+  ].join('\n')
+}
+
+const BODY_CLOSE = '</body>'
+
+/**
+ * Inject the dev runtime into a rendered artifact, in memory.
+ *
+ * The artifact is not re-parsed and not modified anywhere else: the fragment
+ * goes immediately before `</body>`, after the template's own behaviour and
+ * after the IR payload, so the runtime can read the IR that is already there.
+ * When there is no `</body>` (a hand-written fixture, say) the fragment is
+ * appended — a preview without live reload is a bug, but a preview that throws
+ * is worse.
+ */
+export function injectDevRuntime(html) {
+  const source = String(html ?? '')
+  const fragment = devRuntimeFragment()
+  const index = source.lastIndexOf(BODY_CLOSE)
+  if (index === -1) return `${source}\n${fragment}\n`
+  return `${source.slice(0, index)}${fragment}\n${source.slice(index)}`
+}
+
+export { DEV_RUNTIME_MARKER }

package/src/serve/protocol.js

@@ -0,0 +1,36 @@
+/**
+ * The wire vocabulary shared by the dev server and the runtime it injects.
+ *
+ * Both halves are written in this repository and shipped together, but they run
+ * in different processes and are wired by strings. One table of those strings
+ * is what stops the browser half from listening on a path the server half
+ * stopped serving — a drift that shows up as "reload silently stopped working",
+ * the single most expensive failure mode a preview server has.
+ *
+ * Every dev-only route lives under one reserved prefix so that nothing a
+ * template could ever emit collides with it.
+ */
+
+/** Reserved prefix for everything the preview server adds to a page. */
+export const DEV_PREFIX = '/__kamishibai'
+
+/** SSE stream the injected runtime subscribes to. */
+export const EVENTS_PATH = `${DEV_PREFIX}/events`
+/** Comment collection: `GET` lists, `POST` appends. */
+export const COMMENTS_PATH = `${DEV_PREFIX}/comments`
+
+/** SSE event names. `reload` is the one CONTRACT E1 pins. */
+export const RELOAD_EVENT = 'reload'
+export const ERROR_EVENT = 'error'
+/** Sent once on connect so a client can tell "subscribed" from "server hung". */
+export const READY_EVENT = 'ready'
+
+/**
+ * The marker that identifies the injected runtime.
+ *
+ * It is asserted *absent* from every rendered and exported artifact (CONTRACT
+ * E2). That pin only means something if the marker is a single distinctive
+ * token that appears nowhere else, so it is defined here and used verbatim by
+ * both the injector and the test.
+ */
+export const DEV_RUNTIME_MARKER = 'kamishibai-dev-overlay'