@kamishibai/sdk 0.1.1

package/templates/kami/resume/styles.css

@@ -0,0 +1,424 @@
+:root {
+  --backdrop: #2b2f3a;
+  --surface: #ffffff;
+  --accent: #1B365D;
+  --accent-soft: #dbe2ec;
+  --rule: #d9d5cb;
+  --text-primary: #23201a;
+  --text-secondary: #55503f;
+  --text-muted: #8a8371;
+  --code-bg: #f1eee5;
+  --warn: #8a5a12;
+  /* Sheet geometry is the `resume` layout's A4 logical canvas, shipped on the
+     markup as data-ksb-canvas (src/layouts/resume.js). Not restated here: a
+     second copy of a size is a copy free to drift from the one that decides
+     anything. Comments in this file are ASCII on purpose -- every distinct
+     character in a stylesheet pulls a font subset into every artifact. */
+  /* ksb:maxWidth --max-width */
+  /* ksb:measure --measure */
+  /* 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(--backdrop);
+  color: var(--text-primary);
+  font-family: var(--serif);
+  font-size: 15px;
+  line-height: 1.55;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* The page box belongs to this layout rather than to the printer defaults.
+   This SDK's own PDF export prints A4 with 14mm margins (src/export/pdf.js),
+   which leaves a printable box narrower and shorter than one sheet -- so a
+   sheet drawn at its natural size would lose a strip off the right edge and
+   another off the bottom of every page, silently. Claiming the whole page box
+   back is what makes one sheet exactly one printed page. The sheet's own
+   padding is the margin a reader sees. */
+@page {
+  size: A4;
+  margin: 0;
+}
+
+/* The document: a stack of sheets. Its width is not capped here -- a sheet
+   carries its own fixed logical width inline, so a narrower window scrolls
+   sideways rather than squeezing a canvas that is not allowed to reflow. */
+.resume {
+  margin: 0 auto;
+  overflow-x: auto;
+}
+
+/* One sheet *is* the bounded canvas: its size arrives inline and the skeleton's
+   scale-to-fit asset scales it (src/render/scale-to-fit.client.js). Only the
+   skin lives here. Content starts at the top rather than being centred: a page
+   of a resume that is half full should look half full, not float.
+
+   No horizontal margin, and that is an assertion rather than an omission: the
+   skeleton already translates every canvas by its own offsetX, so a skin that
+   also centres the box centres it twice and the sheet drifts off to one side by
+   half the leftover width. Measured at 1920 wide: sheet centre landed at 1523
+   against a window centre of 960. Horizontal placement belongs to the skeleton,
+   which is the only party that knows the scale. */
+.sheet {
+  padding: 72px 67px;
+  background: var(--surface);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  box-shadow: 0 2px 18px rgba(0, 0, 0, 0.35);
+}
+
+/* Content region: capped by the sheet width minus the printer-safe margin the
+   padding above already reserves. */
+.sheet-inner {
+  width: 100%;
+  max-width: var(--max-width);
+  margin: 0 auto;
+  overflow-y: auto;
+  max-height: 100%;
+}
+
+/* Running text keeps the measure: on paper the page and the column are two
+   numbers just as they are on a screen (CONTRACT C3). */
+.prose,
+.list,
+.quote,
+.callout {
+  max-width: var(--measure);
+}
+
+.masthead {
+  border-bottom: 2px solid var(--accent);
+  padding-bottom: 18px;
+  margin-bottom: 26px;
+}
+
+.masthead .doc-title {
+  font-size: 34px;
+  line-height: 1.15;
+  font-weight: 700;
+  margin: 0;
+  color: var(--text-primary);
+  letter-spacing: 0.02em;
+}
+
+.masthead .kicker {
+  font-size: 13px;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  color: var(--accent);
+  margin: 10px 0 0;
+}
+
+.masthead .byline {
+  margin: 10px 0 0;
+  font-size: 13px;
+  color: var(--text-secondary);
+}
+
+/* A sheet holds one chapter, so the section gives up its outer margins and
+   keeps only its inner rhythm. */
+.sheet-inner > .section {
+  margin: 0;
+}
+
+.section {
+  margin: 0 0 18px;
+}
+
+.section > .section-title {
+  font-weight: 700;
+  color: var(--accent);
+  line-height: 1.3;
+}
+
+/* The band heading of a resume: small, ruled, and unmistakably a divider
+   between one part of a career and the next. */
+.section-l1 > .section-title,
+.section-l2 > .section-title {
+  font-size: 17px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  margin: 0 0 14px;
+  padding-bottom: 6px;
+  border-bottom: 1px solid var(--rule);
+}
+
+.section .section-l2 > .section-title,
+.section .section-l3 > .section-title {
+  font-size: 15px;
+  letter-spacing: 0;
+  text-transform: none;
+  border-bottom: 0;
+  padding-bottom: 0;
+  margin: 16px 0 6px;
+  color: var(--text-primary);
+}
+
+.section-l4 > .section-title,
+.section-l5 > .section-title,
+.section-l6 > .section-title {
+  font-size: 14px;
+  margin: 12px 0 6px;
+  color: var(--text-secondary);
+}
+
+.prose {
+  margin: 0 0 10px;
+}
+
+.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. On this layout the list is
+   the workhorse: a career is a list. */
+.prose ul,
+.prose ol,
+.list {
+  margin: 0 0 10px;
+  padding-left: 1.3em;
+}
+
+.prose li,
+.list li {
+  margin: 0 0 5px;
+}
+
+.prose li:last-child,
+.list li:last-child {
+  margin-bottom: 0;
+}
+
+.prose li::marker,
+.list li::marker {
+  color: var(--text-muted);
+}
+
+.list .list {
+  margin: 5px 0 0;
+}
+
+.list li > .prose {
+  margin: 0;
+}
+
+.list li > .prose + * {
+  margin-top: 5px;
+}
+
+.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 4px;
+}
+
+.quote {
+  margin: 0 0 12px;
+  padding: 2px 0 2px 14px;
+  border-left: 3px solid var(--accent-soft);
+  color: var(--text-secondary);
+}
+
+.quote > .prose:last-child {
+  margin-bottom: 0;
+}
+
+.callout {
+  margin: 0 0 12px;
+  padding: 12px 14px;
+  background: var(--code-bg);
+  border-left: 4px solid var(--accent);
+  border-radius: 2px;
+}
+
+.callout-warn {
+  border-left-color: var(--warn);
+}
+
+.callout .callout-label {
+  display: block;
+  font-size: 10px;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--accent);
+  margin-bottom: 5px;
+}
+
+.callout-warn .callout-label {
+  color: var(--warn);
+}
+
+.callout > .prose:last-child {
+  margin-bottom: 0;
+}
+
+.code {
+  margin: 0 0 12px;
+  padding: 12px 14px;
+  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.45;
+}
+
+.code code {
+  font-family: inherit;
+}
+
+.table-wrap {
+  margin: 0 0 12px;
+  overflow-x: auto;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 13px;
+}
+
+.table th,
+.table td {
+  border-bottom: 1px solid var(--rule);
+  padding: 6px 8px;
+  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 12px;
+}
+
+/* diagram (CONTRACT D1) -- the geometry is computed by core/diagram.js and the
+   skin only colours it, with variables every Kami skin agrees on, so one spec
+   draws one picture rather than several that look alike. */
+.diagram {
+  margin: 0 0 12px;
+  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: 13px;
+}
+
+.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: 11px;
+}
+
+/* The foot of the last sheet, inside the canvas: on paper anything outside a
+   sheet is laid onto a page of its own. */
+.colophon {
+  margin-top: auto;
+  padding-top: 18px;
+  font-size: 10px;
+  color: var(--text-muted);
+  letter-spacing: 0.06em;
+  text-align: right;
+}
+
+@media print {
+  body {
+    background: #fff;
+  }
+
+  /* scale-to-fit is a screen affordance. On paper (and in `export`, which asks
+     for the print form) the inline transform would shrink every sheet into a
+     corner of its page. The stacking shadow goes too: it is a screen cue that
+     these are sheets of paper, and on paper they already are.
+
+     The other three declarations undo what makes a sheet a *fixed frame* on
+     screen, and they are the difference between a resume and a truncated one.
+     On screen a sheet is exactly one canvas high and its inner region scrolls;
+     on paper there is no scrollbar to reach for, so the same three rules mean
+     that anything past the first page is painted nowhere and reported by
+     nothing. Measured before this was fixed: a one-sheet resume of 60 entries
+     exported to PDF as ONE page, the last line sitting 744px below the bottom
+     of the paper, exit 0, no message anywhere -- while the same artifact
+     scrolled to the end perfectly well in a browser.
+
+     `height: auto` is the load-bearing one of the three, and it needs
+     `!important` because the height arrives inline with the canvas. Control
+     measurement: keeping the fixed height and relaxing only the clipping still
+     printed one page -- a fixed-height box does not hand its overflow to the
+     next page, it just stops. `break-inside: avoid` is gone for the same
+     reason: a sheet with more than a page of content has to be allowed to
+     split, and a rule that says otherwise is a rule the browser ignores while
+     the reader believes it. */
+  .sheet {
+    transform: none !important;
+    box-shadow: none;
+    display: block;
+    overflow: visible;
+    height: auto !important;
+  }
+
+  .sheet-inner {
+    overflow: visible;
+    max-height: none;
+  }
+
+  /* One sheet *starts* one printed page -- and runs on to the next when it has
+     more than a page of content in it. */
+  .sheet + .sheet {
+    break-before: page;
+  }
+}

package/templates/kami/slides/components.js

@@ -0,0 +1,41 @@
+import { el } from '../../../src/blocks/element.js'
+
+/**
+ * Chrome of the Kami slides template.
+ *
+ * The deck frame and the slide frame belong to the `deck` and `slide` block
+ * modules; the *shape of the artifact* — that a deck-rooted document draws its
+ * deck and nothing else — belongs to the `deck` layout since F2a. What is left
+ * here is what only this template can decide: the wording of the deck chrome,
+ * and that the opening slide carries the document's own identity.
+ */
+
+/**
+ * The opening slide carries the document's own identity (frontmatter title and
+ * kicker); every later slide carries only its compiled blocks (CONTRACT C4).
+ */
+const slideMasthead = (meta) =>
+  el('header', { class: 'slide-masthead' }, [
+    meta.kicker ? el('p', { class: 'kicker' }, [meta.kicker]) : null,
+    el('h1', { class: 'deck-title' }, [meta.title]),
+    meta.author || meta.date
+      ? el('p', { class: 'byline' }, [[meta.author, meta.date].filter(Boolean).join(' · ')])
+      : null,
+  ])
+
+export const chrome = Object.freeze({
+  /** Only the first slide is led by the document masthead. */
+  'slide-lead': (position, ctx) => (position.index === 0 ? [slideMasthead(ctx.meta)] : []),
+
+  /**
+   * The progress readout starts at `1 / n` and is rewritten by the skeleton's
+   * playback script; the hint is this template's wording, in this template's
+   * language, and is the reason the deck frame itself carries no text.
+   */
+  'deck-chrome': ({ total }) => [
+    el('footer', { class: 'deck-chrome' }, [
+      el('span', { class: 'deck-progress' }, [`1 / ${total}`]),
+      el('span', { class: 'deck-hint' }, ['方向鍵／空白鍵翻頁 · F 全螢幕 · Esc 離開']),
+    ]),
+  ],
+})

package/templates/kami/slides/index.js

@@ -0,0 +1,26 @@
+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 `script`: playback is a skeleton asset supplied to every deck-rooted
+ * layout by `src/render/skeleton.js`, with no opt-out. No `root` either: the
+ * shape of a deck artifact is the `deck` 文體's. What is left here is paint and
+ * wording — which is the whole claim of wayfinder issue 13.
+ */
+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/slides/manifest.js

@@ -0,0 +1,64 @@
+/**
+ * Template package descriptor (SPEC §5.2 `[template]` section) for the deck
+ * family. `---` only becomes a page break under this key (CONTRACT C4).
+ */
+export const manifest = Object.freeze({
+  namespace: 'kami',
+  name: 'slides',
+  version: '0.1.0',
+  description: 'Kami 簡報模板 — 16:9 單張版面，內建離線播放',
+  language: 'zh-TW',
+  /**
+   * The 文體 this skin is a skin *of* (CONTRACT C1) — and the reason the root
+   * form below is inherited rather than invented: every template on the `deck`
+   * layout requires a deck root, whether or not it remembers to say so.
+   */
+  layout: 'deck',
+  /**
+   * Required root form (CONTRACT C4). `blocks` cannot express this: every
+   * long-form type below is legal *inside* a slide, so a flat document tree
+   * passes the type check while this template draws only `deck.slides` — the
+   * whole document silently disappears. The root form is a separate claim.
+   */
+  root: 'deck',
+  blocks: Object.freeze([
+    'doc',
+    'deck',
+    'slide',
+    'section',
+    'prose',
+    'list',
+    'quote',
+    'callout',
+    'code',
+    'table',
+    'raw',
+    'diagram',
+    // F6a 四型資料 block（11 號票 P1「資料」）。五張 Kami 皮一起宣告：
+    // 詞彙表是准入規則，一張皮少宣告一種，同一份文件在它底下就會被
+    // KSB_TEMPLATE_BLOCK_UNSUPPORTED 擋掉——而那不是守門，是缺角。
+    'stat',
+    'timeline',
+    'board',
+    'graph',
+  ]),
+  /** 轉子/<型別>/config — see the long-form manifest for why wording lives here. */
+  blockConfig: Object.freeze({
+    callout: Object.freeze({ labels: Object.freeze({ note: 'NOTE', warn: 'WARNING' }) }),
+  }),
+  /**
+   * The applied state of the `deck` layout's geometry knobs, in CSS pixels.
+   *
+   * A deck is the case that makes the numbers obviously distinct. Since F2f
+   * there are three of them and each has a different job: the logical page is
+   * 1280×720 and belongs to the 文體 (it arrives with the layout, not from
+   * here); `maxWidth` 1120 is how wide the content region inside that page may
+   * grow (`--slide-measure` in styles.css); and a line of text still wants the
+   * same 740px ruler everything else uses. Collapsing any two of them is
+   * exactly the mistake CONTRACT C3 separates out.
+   */
+  maxWidth: 1120,
+  measure: 740,
+})
+
+export const templateKey = `${manifest.namespace}/${manifest.name}`