@kamishibai/sdk 0.1.1

package/templates/kami/cards/styles.css

@@ -0,0 +1,389 @@
+:root {
+  --paper: #f5f4ed;
+  --surface: #faf9f5;
+  --accent: #1B365D;
+  --accent-soft: #dbe2ec;
+  --rule: #ddd9cc;
+  --text-primary: #23201a;
+  --text-secondary: #5c574c;
+  --text-muted: #8a8371;
+  --code-bg: #efece1;
+  --warn: #8a5a12;
+  /* ksb:measure --measure */
+  /* ksb:maxWidth --max-width */
+  /* Decoration, not geometry: the grid is 24 tracks because that is this SDK's
+     column vocabulary, and how many of them one card takes is read by this
+     stylesheet and by nothing else. Numbers only CSS asks about belong in the
+     skin, never in the layout. */
+  --card-columns: 24;
+  --card-span: 8;
+  --card-gap: 24px;
+  /* Declared means embedded (CONTRACT A4): only families that really ship with
+     the artifact are named here; the rest fall back to generic keywords. */
+  --serif: 'Noto Serif TC', serif;
+  --mono: monospace;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  background: var(--paper);
+  color: var(--text-primary);
+  font-family: var(--serif);
+  font-size: 17px;
+  line-height: 1.55;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* The board: the `card` layout's outer frame. It is as wide as --max-width,
+   which is a page width and not a type ruler -- three cards across is nothing
+   like a column of prose, which is exactly why the two numbers are two. */
+.cards {
+  max-width: var(--max-width);
+  margin: 0 auto;
+  padding: 72px 28px 96px;
+}
+
+/* The lead-in: whatever sat at the top level and was not a chapter. It keeps
+   the measure, because it is ordinary running text. */
+.cards-intro {
+  max-width: var(--measure);
+  margin: 0 0 40px;
+}
+
+.cards-intro > * + * {
+  margin-top: 18px;
+}
+
+/* The card grid: 24 real column tracks, laid on the board itself. A card spans
+   --card-span of them, so the same stylesheet is a three-across board of
+   knowledge cards or a two-across dashboard by changing one number. */
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(var(--card-columns), minmax(0, 1fr));
+  column-gap: var(--card-gap);
+  row-gap: var(--card-gap);
+  align-items: start;
+}
+
+.card {
+  grid-column: span var(--card-span);
+  /* min-width: 0 -- a grid item defaults to min-width: auto, so one long
+     unbroken word (a URL, a code span) widens its track and silently narrows
+     every neighbour on the row. */
+  min-width: 0;
+  padding: 24px 26px 26px;
+  background: var(--surface);
+  border: 1px solid var(--rule);
+  border-radius: 6px;
+}
+
+/* A card is a whole chapter, so its own outer margins would fight the grid gap.
+   The section keeps its inner rhythm and gives up its outer one. */
+.card > .section {
+  margin: 0;
+}
+
+.card > .section > .section-title {
+  margin-top: 0;
+}
+
+.masthead {
+  border-bottom: 2px solid var(--accent);
+  padding-bottom: 20px;
+  margin-bottom: 40px;
+}
+
+.masthead .kicker {
+  font-size: 12px;
+  letter-spacing: 0.22em;
+  text-transform: uppercase;
+  color: var(--accent);
+  margin: 0 0 10px;
+}
+
+.masthead .doc-title {
+  font-size: 34px;
+  line-height: 1.3;
+  font-weight: 700;
+  margin: 0;
+  color: var(--text-primary);
+}
+
+.masthead .byline {
+  margin: 12px 0 0;
+  font-size: 14px;
+  color: var(--text-secondary);
+}
+
+.section {
+  margin: 0 0 24px;
+}
+
+.section > .section-title {
+  font-weight: 700;
+  color: var(--accent);
+  line-height: 1.35;
+}
+
+.section-l1 > .section-title {
+  font-size: 21px;
+  margin: 0 0 16px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--rule);
+}
+
+.section-l2 > .section-title {
+  font-size: 17px;
+  margin: 24px 0 10px;
+}
+
+.section-l3 > .section-title,
+.section-l4 > .section-title,
+.section-l5 > .section-title,
+.section-l6 > .section-title {
+  font-size: 15px;
+  margin: 20px 0 8px;
+  color: var(--text-primary);
+}
+
+.prose {
+  margin: 0 0 14px;
+  line-height: 1.55;
+}
+
+.prose:last-child {
+  margin-bottom: 0;
+}
+
+.prose a {
+  color: var(--accent);
+  text-underline-offset: 3px;
+}
+
+/* Lists arrive two ways -- a list block, and list markup pushed into prose by a
+   raw island -- and both get the same rules, or the same source would look
+   different depending on which door it came through. */
+.prose ul,
+.prose ol,
+.list {
+  margin: 0 0 14px;
+  padding-left: 1.4em;
+  line-height: 1.55;
+}
+
+.prose li,
+.list li {
+  margin: 0 0 6px;
+}
+
+.prose li:last-child,
+.list li:last-child {
+  margin-bottom: 0;
+}
+
+.prose li::marker,
+.list li::marker {
+  color: var(--text-muted);
+}
+
+.list .list {
+  margin: 6px 0 0;
+}
+
+.list li > .prose {
+  margin: 0;
+}
+
+.list li > .prose + * {
+  margin-top: 8px;
+}
+
+.prose code,
+.callout code,
+.quote code,
+.table code {
+  font-family: var(--mono);
+  font-size: 0.9em;
+  background: var(--code-bg);
+  border-radius: 3px;
+  padding: 1px 5px;
+}
+
+.quote {
+  margin: 0 0 16px;
+  padding: 4px 0 4px 16px;
+  border-left: 3px solid var(--accent-soft);
+  color: var(--text-secondary);
+}
+
+.quote > .prose:last-child {
+  margin-bottom: 0;
+}
+
+.callout {
+  margin: 0 0 16px;
+  padding: 14px 16px;
+  background: var(--paper);
+  border-left: 4px solid var(--accent);
+  border-radius: 2px;
+}
+
+.callout-warn {
+  border-left-color: var(--warn);
+}
+
+.callout .callout-label {
+  display: block;
+  font-size: 11px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--accent);
+  margin-bottom: 6px;
+}
+
+.callout-warn .callout-label {
+  color: var(--warn);
+}
+
+.callout > .prose:last-child {
+  margin-bottom: 0;
+}
+
+.code {
+  margin: 0 0 16px;
+  padding: 14px 16px;
+  background: var(--code-bg);
+  border: 1px solid var(--rule);
+  border-radius: 4px;
+  overflow-x: auto;
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.code code {
+  font-family: inherit;
+}
+
+.table-wrap {
+  margin: 0 0 16px;
+  overflow-x: auto;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 14px;
+}
+
+.table th,
+.table td {
+  border-bottom: 1px solid var(--rule);
+  padding: 8px 10px;
+  text-align: left;
+  vertical-align: top;
+}
+
+.table th {
+  color: var(--accent);
+  font-weight: 700;
+  border-bottom: 2px solid var(--accent-soft);
+}
+
+.island {
+  margin: 0 0 16px;
+}
+
+/* diagram (CONTRACT D1) -- the geometry is computed by core/diagram.js and the
+   skin only colours it, with variables both Kami skins agree on, so one spec
+   draws one picture rather than two that look alike. */
+.diagram {
+  margin: 0 0 16px;
+  overflow-x: auto;
+}
+
+.diagram-svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  font-family: var(--serif);
+}
+
+.diagram-node-box {
+  fill: var(--accent-soft);
+  stroke: var(--accent);
+  stroke-width: 1.5;
+}
+
+.diagram-node-label {
+  fill: var(--text-primary);
+  font-size: 15px;
+}
+
+.diagram-edge-line {
+  fill: none;
+  stroke: var(--accent);
+  stroke-width: 1.5;
+}
+
+.diagram-arrow {
+  fill: var(--accent);
+}
+
+.diagram-edge-label {
+  fill: var(--text-secondary);
+  font-size: 12px;
+}
+
+.colophon {
+  margin-top: 56px;
+  padding-top: 16px;
+  border-top: 1px solid var(--rule);
+  font-size: 12px;
+  color: var(--text-muted);
+  letter-spacing: 0.06em;
+}
+
+/* Medium window: two across. The tracks stay 24 -- only the span changes, so
+   the cards keep landing on the same column vocabulary at every width. */
+@media (max-width: 1024px) {
+  .card {
+    grid-column: span 12;
+  }
+}
+
+/* Narrow window: one card per row. A card squeezed to a third of a phone is a
+   card nobody can read, and the flowing genre stays flowing -- no fixed canvas,
+   no scaling, the measure intact. */
+@media (max-width: 680px) {
+  .card {
+    grid-column: 1 / -1;
+  }
+}
+
+@media print {
+  body {
+    background: #fff;
+  }
+
+  /* On paper the board goes back to one column: a printed card grid breaks
+     across pages in the middle of whichever card the page ended on. */
+  .card-grid {
+    display: block;
+  }
+
+  .card {
+    break-inside: avoid;
+    margin: 0 0 var(--card-gap);
+    border-color: #ccc;
+  }
+}

package/templates/kami/long-form/components.js

@@ -0,0 +1,102 @@
+import { el } from '../../../src/blocks/element.js'
+import { manifest } from './manifest.js'
+
+/**
+ * Chrome of the Kami long-form template.
+ *
+ * The root form is no longer written here: the shape of a long-form page is the
+ * `article` 文體's, and every template on that layout gets the same frame and
+ * the same two slots (CONTRACT C1). What is left is exactly this template's own
+ * business — the masthead, the colophon, the table of contents in the rail, and
+ * every word of them, which is the half a layout is forbidden to have an
+ * opinion about.
+ *
+ * Nothing here is a component: each slot returns the same neutral element tree
+ * a block module returns, so this file is data with a little arithmetic in it
+ * and imports no rendering library at all (CONTRACT A1).
+ */
+
+const TEMPLATE_LABEL = `${manifest.namespace}/${manifest.name}`
+
+/** Verbatim — this template's word for the rail's contents. */
+const TOC_LABEL = '目次'
+
+/**
+ * The section tree, flattened into entries this template can draw.
+ *
+ * A section with no `id` cannot be linked to — the anchor would point at
+ * nothing — so it contributes its children in its own place rather than taking
+ * a whole subtree down with it. Ids come from the pipeline (`withIds`), so this
+ * is the defensive branch, not the normal one.
+ */
+const tocEntries = (blocks) =>
+  (blocks ?? []).flatMap((block) => {
+    if (block?.type !== 'section') return []
+    const children = tocEntries(block.children)
+    return typeof block.id === 'string' && block.id.length > 0
+      ? [{ id: block.id, title: block.title, children }]
+      : children
+  })
+
+const tocList = (entries) =>
+  el(
+    'ol',
+    { class: 'toc-list' },
+    entries.map((entry) =>
+      // Spread rather than `… : null`: a null child is a real empty comment
+      // node in the artifact, and a leaf-heavy table of contents would pay for
+      // one per entry, forever, to say nothing.
+      el('li', { class: 'toc-item' }, [
+        el('a', { class: 'toc-link', href: `#${entry.id}` }, [entry.title]),
+        ...(entry.children.length > 0 ? [tocList(entry.children)] : []),
+      ]),
+    ),
+  )
+
+/**
+ * The table of contents — **chrome this template computes**, not content.
+ *
+ * The author never writes it: it is derived from the section tree the document
+ * already has, exactly the way the masthead is derived from `meta` (wayfinder
+ * 14 號票, 量測報告 §5.4). Two consequences follow, and both are the point:
+ * it never enters the IR, so `replay` under another template gets that
+ * template's chrome instead of this one's; and the anchors are the section ids
+ * that have been in the DOM since F1, so jumping works with no script at all.
+ *
+ * A document with no sections yields **nothing**, and the empty rail region it
+ * leaves behind is collapsed by `styles.css` (`.doc-rail:empty`). Answering it
+ * here, in markup, would have made the page's shape depend on the document
+ * rather than on the template's applied state.
+ */
+const toc = (doc) => {
+  const entries = tocEntries(doc?.children)
+  if (entries.length === 0) return []
+  return [
+    el('nav', { class: 'doc-toc', 'aria-label': TOC_LABEL }, [
+      el('p', { class: 'toc-heading' }, [TOC_LABEL]),
+      tocList(entries),
+    ]),
+  ]
+}
+
+const masthead = (meta) =>
+  el('header', { class: 'masthead' }, [
+    meta.kicker ? el('p', { class: 'kicker' }, [meta.kicker]) : null,
+    el('h1', { class: 'doc-title' }, [meta.title]),
+    meta.author || meta.date
+      ? el('p', { class: 'byline' }, [[meta.author, meta.date].filter(Boolean).join(' · ')])
+      : null,
+  ])
+
+export const chrome = Object.freeze({
+  /** Above the body: who wrote this and what it is called. */
+  'doc-lead': (meta) => [masthead(meta)],
+
+  /** Beside it: where the reader is, derived from the document's own headings. */
+  'doc-rail': (doc) => toc(doc),
+
+  /** Below it: the engine and skin that drew the page, in this template's words. */
+  'doc-foot': () => [
+    el('footer', { class: 'colophon' }, [`kamishibai · ${TEMPLATE_LABEL}@${manifest.version}`]),
+  ],
+})

package/templates/kami/long-form/index.js

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { manifest, templateKey } from './manifest.js'
+import { chrome } from './components.js'
+
+const STYLES_PATH = fileURLToPath(new URL('./styles.css', import.meta.url))
+
+/**
+ * Template package as consumed by the render layer.
+ *
+ * No `root`: the shape of the page belongs to the `article` layout this
+ * manifest names, and this package supplies only skin (`styles`), config
+ * (`manifest`) and chrome (CONTRACT C1).
+ */
+export default Object.freeze({
+  manifest,
+  key: templateKey,
+  chrome,
+  language: manifest.language,
+  /** Fonts subset into the artifact (SPEC §7.2 出廠字體堆疊). */
+  fonts: Object.freeze([
+    Object.freeze({ package: '@fontsource/noto-serif-tc', weights: Object.freeze(['400', '700']) }),
+  ]),
+  styles: () => readFileSync(STYLES_PATH, 'utf8'),
+})

package/templates/kami/long-form/manifest.js

@@ -0,0 +1,87 @@
+/**
+ * Template package descriptor (SPEC §5.2 `[template]` section).
+ * S1 ships it as a module; the TOML manifest lands with the template
+ * authoring slice (S7).
+ */
+export const manifest = Object.freeze({
+  namespace: 'kami',
+  name: 'long-form',
+  version: '0.1.0',
+  description: 'Kami 長文模板 — 紙感單欄閱讀版面',
+  language: 'zh-TW',
+  /**
+   * The 文體 this skin is a skin *of* (CONTRACT C1). Everything about the shape
+   * of the page — the frame, the body region, the two chrome slots, the flowing
+   * canvas — comes from there; this package only decides what it looks like.
+   */
+  layout: 'article',
+  /** No required root form: this template renders whatever sits under `doc`. */
+  root: null,
+  blocks: Object.freeze([
+    'doc',
+    'section',
+    'prose',
+    'list',
+    'quote',
+    'callout',
+    'code',
+    'table',
+    'raw',
+    'diagram',
+    // F6a 四型資料 block（11 號票 P1「資料」）。五張 Kami 皮一起宣告：
+    // 詞彙表是准入規則，一張皮少宣告一種，同一份文件在它底下就會被
+    // KSB_TEMPLATE_BLOCK_UNSUPPORTED 擋掉——而那不是守門，是缺角。
+    'stat',
+    'timeline',
+    'board',
+    'graph',
+  ]),
+  /**
+   * 轉子/<型別>/config — the template's settings for a block type.
+   *
+   * The callout labels live here because they are *wording*, and wording is
+   * decoration: freezing `NOTE`/`WARNING` inside the shared conversion path
+   * meant a template that wanted 「注意」 or an icon had to fork the renderer
+   * (CONTRACT A7). These two strings are this template's answer, not the SDK's.
+   */
+  blockConfig: Object.freeze({
+    callout: Object.freeze({ labels: Object.freeze({ note: 'NOTE', warn: 'WARNING' }) }),
+  }),
+  /**
+   * The applied state of the `article` layout's geometry knobs, in CSS pixels.
+   *
+   * `maxWidth` is how wide the page may get; `measure` is how wide a line of
+   * text may get. They are two numbers on purpose (CONTRACT C3): collapsing
+   * them is what made `--measure: 740px` simultaneously a page width and a type
+   * ruler, so a diagram in a narrow column had nothing to be measured against
+   * (量測報告 §4.2). They coincided here until F2b, because the page *was* one
+   * column; a page with a rail is precisely the case that pulls them apart —
+   * 1080px of paper carrying a 740px column of text, 「一般網站的玩法」
+   * (issue 14 裁決 3).
+   *
+   * These values are the *template's*, not the layout's — the layout only says
+   * which knobs exist and what they fall back to. `styles.css` no longer holds
+   * either number: it declares where they go, and the render layer writes them
+   * in (`src/render/styles.js`).
+   */
+  maxWidth: 1080,
+  measure: 740,
+  /**
+   * The rail knobs of the `article` 文體, turned on — this *is* what a Kami
+   * long-form page looks like (CONTRACT F2b P3): 左目錄、右內文, the layout
+   * every reader already knows from a documentation site.
+   *
+   * The three numbers are one sentence of arithmetic, not three tastes:
+   * `maxWidth` 1080 = `railWidth` 240 + the 44px column gap + `measure` 740 +
+   * the 56px the paper already reserves as left/right padding. Pick any other
+   * page width and the column of text stops being 740px wide, which would
+   * silently detune the type scale against a measure it never actually gets
+   * (量測報告 §4.2 の同じ罠). The gap lives in `styles.css` because it is the
+   * one part of the sum that is pure decoration.
+   */
+  rail: true,
+  railWidth: 240,
+  railSide: 'start',
+})
+
+export const templateKey = `${manifest.namespace}/${manifest.name}`