@kamishibai/sdk 0.1.1

package/src/delivery/scaffold-blueprints.js

@@ -0,0 +1,728 @@
+import { NO_ROOT } from './template-format.js'
+
+/**
+ * What the scaffold has to *say* to produce a working package, per 文體.
+ *
+ * `template-scaffold.js` owns the mechanism — validate, refuse an occupied
+ * directory, write three files atomically — and none of that differs between
+ * 文體. What differs is entirely content: which blocks the package admits, what
+ * root form it restates, how its skin paints the hooks that 文體 emits, and what
+ * its 預設 md looks like. Keeping the content here is what lets a new 文體 be
+ * supported by writing a blueprint rather than by editing the writer, and it is
+ * why `SCAFFOLD_SUPPORTED_LAYOUTS` is *derived* from this table: a 文體 the flag
+ * lets through but has no blueprint for would scaffold a package that cannot
+ * draw, which is the failure F3's 複驗 F-1 narrowed the flag to prevent.
+ *
+ * Every stylesheet here is deliberately small and deliberately **complete**:
+ * every hook the admitted blocks emit gets at least a rule, because a block
+ * nobody painted renders as invisible data loss with exit 0 (issue 13「這類系統
+ * 最惡毒的失敗模式」). The `ksb:` comment is the geometry marker
+ * `src/render/styles.js` fills from the manifest — the scaffold teaches the
+ * mechanism by using it.
+ */
+
+/** The applied state the article scaffold turns its 文體's knobs to, in CSS pixels. */
+const ARTICLE_MAX_WIDTH = 740
+const ARTICLE_MEASURE = 740
+
+/**
+ * The deck scaffold's applied state. The two numbers are *not* the logical
+ * canvas: the canvas (1280×720) belongs to the `deck` 文體 and arrives with it,
+ * while `maxWidth` is how wide the content region inside a slide may grow and
+ * `measure` is still the width of a line of text (CONTRACT C3).
+ */
+const DECK_MAX_WIDTH = 1120
+const DECK_MEASURE = 740
+
+/**
+ * The card scaffold's applied state — the board and the column, at their
+ * furthest apart. `maxWidth` 1200 is how wide the board of cards may get;
+ * `measure` 740 is still the width of a line of text, and on this 文體 it is the
+ * lead-in paragraph rather than the cards that respects it.
+ */
+const CARD_MAX_WIDTH = 1200
+const CARD_MEASURE = 740
+
+/**
+ * The one-page scaffold's applied state. Like the deck's, the two numbers are
+ * *not* the logical canvas: the canvas (1440×900, one screen) belongs to the
+ * `one-page` 文體 and arrives with it, while `maxWidth` is how wide the content
+ * region inside a screen may grow and `measure` is still the width of a line of
+ * text (CONTRACT C3).
+ */
+const ONE_PAGE_MAX_WIDTH = 1200
+const ONE_PAGE_MEASURE = 740
+
+/**
+ * The resume scaffold's applied state. Again the two numbers are *not* the
+ * logical canvas — the canvas (794×1123, one sheet of A4) belongs to the
+ * `resume` 文體 and arrives with it. What is different here is that neither
+ * number is the usual one: on paper `measure` cannot be 740, because a 740px
+ * column plus any margin at all is wider than an A4 sheet.
+ */
+const RESUME_MAX_WIDTH = 660
+const RESUME_MEASURE = 620
+
+/** The block types the article scaffold admits — the core long-form vocabulary. */
+const ARTICLE_BLOCKS = Object.freeze([
+  'doc',
+  'section',
+  'prose',
+  'list',
+  'quote',
+  'callout',
+  'code',
+  'table',
+  'raw',
+  'diagram',
+])
+
+/**
+ * The deck scaffold admits the same vocabulary **plus the two container types a
+ * deck is made of**. `deck`/`slide` are not optional extras here: the 文體
+ * requires a `deck` root form, so a package that did not admit them would be
+ * refused by the vocabulary guard on its own 預設 md.
+ */
+const DECK_BLOCKS = Object.freeze(['doc', 'deck', 'slide', ...ARTICLE_BLOCKS.slice(1)])
+
+/** Rules every 文體's skin needs, because every 文體 admits these blocks. */
+const commonBlockRules = () => [
+  '.section-title { line-height: 1.3; }',
+  '.prose { margin: 0; }',
+  '.list { padding-left: 1.4rem; }',
+  '.quote { margin: 0; padding-left: 1rem; border-left: 3px solid var(--rule); }',
+  '.callout { padding: 1rem; border: 1px solid var(--rule); border-radius: 4px; }',
+  '.callout-label { font-size: 0.75rem; letter-spacing: 0.08em; }',
+  '.code { padding: 1rem; overflow-x: auto; background: #f2efe9; }',
+  '.table-wrap { overflow-x: auto; }',
+  '.table { border-collapse: collapse; width: 100%; }',
+  '.table th, .table td { border: 1px solid var(--rule); padding: 0.4rem 0.6rem; }',
+  '.island { margin: 0; }',
+  '.diagram { max-width: 100%; }',
+]
+
+const articleStylesheet = () =>
+  [
+    ':root {',
+    '  /* ksb:measure --measure */',
+    '  --ink: #1a1a1a;',
+    '  --paper: #fdfdfb;',
+    '  --rule: #d8d4cc;',
+    '}',
+    '',
+    'body { margin: 0; background: var(--paper); color: var(--ink);',
+    '  font-family: Georgia, "Noto Serif TC", serif; line-height: 1.75; }',
+    '.paper { max-width: var(--measure); margin: 0 auto; padding: 4rem 1.5rem; }',
+    '.doc-body > * + * { margin-top: 1.2rem; }',
+    ...commonBlockRules(),
+    '',
+  ].join('\n')
+
+/**
+ * The deck skin.
+ *
+ * Three rules here are not decoration and would each break 開箱即用 if dropped:
+ *
+ *  - `.deck.is-live` / `.is-current` — the playback asset only adds classes.
+ *    A skin that never acts on them ships a deck whose arrow keys do nothing,
+ *    which looks like a broken artifact rather than an unpainted one.
+ *  - `.slide-cell { min-width: 0 }` — a grid cell defaults to `min-width: auto`,
+ *    so one long unbroken word widens its track and silently narrows its
+ *    neighbours.
+ *  - `transform: none !important` under `@media print` — scale-to-fit is a
+ *    screen affordance; on paper (and in `export`, which asks for the print
+ *    form) the inline transform would shrink every slide into a corner.
+ */
+const deckStylesheet = () =>
+  [
+    ':root {',
+    '  /* ksb:maxWidth --slide-measure */',
+    '  --ink: #1a1a1a;',
+    '  --paper: #14161c;',
+    '  --surface: #fdfdfb;',
+    '  --rule: #d8d4cc;',
+    '}',
+    '',
+    '* { box-sizing: border-box; }',
+    'body { margin: 0; background: var(--paper); color: var(--ink);',
+    '  font-family: Georgia, "Noto Serif TC", serif; line-height: 1.6; }',
+    '',
+    '/* 每張投影片就是文體宣告的有界邏輯畫布；寬高隨標記出貨，縮放由骨架資產做。 */',
+    '.deck { margin: 0 auto; padding: 2rem 1.5rem; overflow-x: auto; }',
+    '.slide { margin: 0 auto 1.5rem; padding: 3rem 3.5rem; background: var(--surface);',
+    '  border-radius: 4px; overflow: hidden; display: flex; flex-direction: column;',
+    '  justify-content: center; }',
+    // 列距走**下**緣，不走上緣、也不走 row-gap。上緣會讓同一列的側欄比主欄低
+    // 一截；row-gap 更糟——格軌有 24 條顯式列，gap 連空列都算，於是每一張都被
+    // 撐掉半頁高。兩種錯都只是「看起來有點怪」，沒有人會去查。
+    '.slide-inner { width: 100%; max-width: var(--slide-measure); margin: 0 auto;',
+    '  overflow-y: auto; max-height: 100%; }',
+    '.slide-cell { min-width: 0; margin-bottom: 1.2rem; }',
+    '.slide-cell:last-child { margin-bottom: 0; }',
+    '',
+    '/* 播放模式：沒有 JS 時每張照常可讀，整份產物退化成一份可捲動的文件。 */',
+    '.deck.is-live { position: fixed; inset: 0; padding: 0; overflow: hidden; }',
+    '.deck.is-live .slide { display: none; margin: 0; }',
+    '.deck.is-live .slide.is-current { display: flex; }',
+    '',
+    ...commonBlockRules(),
+    '',
+    '@media print {',
+    '  body { background: #fff; }',
+    '  .deck.is-live { position: static; overflow: visible; padding: 2rem 1.5rem; }',
+    '  .deck.is-live .slide { display: flex; margin: 0 auto 1.5rem; }',
+    '  .slide { break-inside: avoid; transform: none !important; }',
+    '}',
+    '',
+  ].join('\n')
+
+/**
+ * The card skin.
+ *
+ * Three rules here are load-bearing rather than decorative:
+ *
+ *  - the 24 tracks plus `grid-column: span N` — this is the 文體's whole shape,
+ *    and a scaffold that laid no tracks would produce a package whose cards
+ *    stack in one column, i.e. an `article` wearing another name.
+ *  - `.card { min-width: 0 }` — a grid item defaults to `min-width: auto`, so
+ *    one long unbroken word widens its track and silently narrows the rest of
+ *    the row.
+ *  - the two breakpoints — 「寬視窗多欄、窄視窗單欄」 is part of what the 文體
+ *    promises (CONTRACT F2c P1); without them the starter package is unreadable
+ *    on the first phone that opens it.
+ */
+const cardStylesheet = () =>
+  [
+    ':root {',
+    '  /* ksb:measure --measure */',
+    '  /* ksb:maxWidth --max-width */',
+    '  --card-columns: 24;',
+    '  --card-span: 8;',
+    '  --card-gap: 24px;',
+    '  --ink: #1a1a1a;',
+    '  --paper: #fdfdfb;',
+    '  --surface: #ffffff;',
+    '  --rule: #d8d4cc;',
+    '}',
+    '',
+    '* { box-sizing: border-box; }',
+    'body { margin: 0; background: var(--paper); color: var(--ink);',
+    '  font-family: Georgia, "Noto Serif TC", serif; line-height: 1.6; }',
+    '',
+    '.cards { max-width: var(--max-width); margin: 0 auto; padding: 3rem 1.5rem; }',
+    '.cards-intro { max-width: var(--measure); margin: 0 0 2rem; }',
+    '.cards-intro > * + * { margin-top: 1rem; }',
+    '',
+    '/* The board: 24 real tracks, and a card spans some of them. */',
+    '.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;',
+    '  padding: 1.25rem 1.4rem; background: var(--surface);',
+    '  border: 1px solid var(--rule); border-radius: 6px; }',
+    '.card > .section { margin: 0; }',
+    '.card > .section > .section-title { margin-top: 0; }',
+    ...commonBlockRules(),
+    '',
+    '@media (max-width: 1024px) { .card { grid-column: span 12; } }',
+    '@media (max-width: 680px) { .card { grid-column: 1 / -1; } }',
+    '',
+    '@media print {',
+    '  body { background: #fff; }',
+    '  .card-grid { display: block; }',
+    '  .card { break-inside: avoid; margin: 0 0 var(--card-gap); }',
+    '}',
+    '',
+  ].join('\n')
+
+/**
+ * The one-page skin.
+ *
+ * Three rules here are load-bearing rather than decorative:
+ *
+ *  - `.screen { display: flex; justify-content: center }` plus `overflow:
+ *    hidden` — a screen is a *fixed frame*, not a column that grows. Without
+ *    them the content sits at the top of a 900px box and anything longer
+ *    silently spills past the canvas the skeleton is scaling.
+ *  - `.one-page { overflow-x: auto }` — the screen carries its logical width
+ *    inline and is not allowed to reflow, so a narrower window has to scroll.
+ *    Without this the starter package overflows the document instead.
+ *  - `transform: none !important` under `@media print` — scale-to-fit is a
+ *    screen affordance; on paper (and in `export`, which asks for the print
+ *    form) the inline transform would shrink every screen into a corner.
+ */
+const onePageStylesheet = () =>
+  [
+    ':root {',
+    '  /* ksb:measure --measure */',
+    '  /* ksb:maxWidth --max-width */',
+    '  --ink: #1a1a1a;',
+    '  --paper: #14161c;',
+    '  --surface: #fdfdfb;',
+    '  --rule: #d8d4cc;',
+    '}',
+    '',
+    '* { box-sizing: border-box; }',
+    'body { margin: 0; background: var(--paper); color: var(--ink);',
+    '  font-family: Georgia, "Noto Serif TC", serif; line-height: 1.6; }',
+    '',
+    '/* The site is a scrollable sequence of screens; a screen is the bounded',
+    '   logical canvas, and its size arrives inline on the markup. */',
+    '.one-page { margin: 0 auto; overflow-x: auto; }',
+    '.screen { margin: 0 auto; padding: 4rem 5rem; background: var(--surface);',
+    '  overflow: hidden; display: flex; flex-direction: column;',
+    '  justify-content: center; }',
+    '.screen-inner { width: 100%; max-width: var(--max-width); margin: 0 auto;',
+    '  overflow-y: auto; max-height: 100%; }',
+    '.screen-inner > .section { margin: 0; }',
+    '.prose, .list, .quote, .callout { max-width: var(--measure); }',
+    '.colophon { padding: 1.5rem; text-align: center; font-size: 0.75rem;',
+    '  color: #8a8371; }',
+    ...commonBlockRules(),
+    '',
+    '@media print {',
+    '  body { background: #fff; }',
+    '  /* scale-to-fit is for screens; on paper the inline transform stands down. */',
+    '  .screen { transform: none !important; break-inside: avoid; background: #fff; }',
+    '}',
+    '',
+  ].join('\n')
+
+/**
+ * The resume skin.
+ *
+ * Three rules here are load-bearing rather than decorative:
+ *
+ *  - `@page { margin: 0 }` — this SDK's PDF export prints A4 with 14mm margins
+ *    (`src/export/pdf.js`), so the printable box is smaller than one sheet. A
+ *    package that never claimed the page box back would lose a strip off the
+ *    right edge and another off the bottom of *every* printed page, silently.
+ *  - `.sheet + .sheet { break-before: page }` — one sheet *opens* one printed
+ *    page, alone. `break-inside: avoid` is deliberately absent: 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.
+ *  - the print form hands back the three screen devices (`display: block;
+ *    overflow: visible; height: auto !important`) — on screen a sheet is a
+ *    fixed frame whose inner region scrolls; on paper there is no scrollbar,
+ *    so a frame that kept its fixed height would paint everything past the
+ *    first page nowhere and report it to nobody. `overflow: hidden` is a
+ *    screen-only affordance.
+ */
+const resumeStylesheet = () =>
+  [
+    ':root {',
+    '  /* ksb:measure --measure */',
+    '  /* ksb:maxWidth --max-width */',
+    '  --ink: #1a1a1a;',
+    '  --backdrop: #2b2f3a;',
+    '  --surface: #ffffff;',
+    '  --rule: #d8d4cc;',
+    '}',
+    '',
+    '* { box-sizing: border-box; }',
+    'body { margin: 0; background: var(--backdrop); color: var(--ink);',
+    '  font-family: Georgia, "Noto Serif TC", serif; font-size: 15px; line-height: 1.55; }',
+    '',
+    '/* The page box belongs to this genre, not to the printer defaults: the',
+    '   exporter prints A4 with margins, and a sheet drawn at its natural size',
+    '   would be clipped by them. */',
+    '@page {',
+    '  size: A4;',
+    '  margin: 0;',
+    '}',
+    '',
+    '/* A resume is a stack of sheets; a sheet is the bounded logical canvas,',
+    '   and its size arrives inline on the markup. */',
+    '.resume { margin: 0 auto; overflow-x: auto; }',
+    '/* No horizontal margin on the sheet: the skeleton already translates every',
+    '   canvas by its own offsetX, so centring it here as well centres it twice',
+    '   and the sheet drifts off to one side. */',
+    '.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); }',
+    '.sheet-inner { width: 100%; max-width: var(--max-width); margin: 0 auto;',
+    '  overflow-y: auto; max-height: 100%; }',
+    '.sheet-inner > .section { margin: 0; }',
+    '.prose, .list, .quote, .callout { max-width: var(--measure); }',
+    '.colophon { margin-top: auto; padding-top: 1rem; text-align: right;',
+    '  font-size: 0.7rem; color: #8a8371; }',
+    ...commonBlockRules(),
+    '',
+    '@media print {',
+    '  body { background: #fff; }',
+    '  /* scale-to-fit is for screens; on paper the inline transform stands down.',
+    '     The fixed height, the clip and the inner scroll region stand down with',
+    '     it: on screen they make a sheet a fixed frame, on paper -- where there',
+    '     is no scrollbar -- they mean anything past the first page is printed',
+    '     nowhere and reported by nothing. `height: auto` is the load-bearing one',
+    '     and needs !important, because the height arrives inline. */',
+    '  .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 when it holds more. */',
+    '  .sheet + .sheet { break-before: page; }',
+    '}',
+    '',
+  ].join('\n')
+
+/**
+ * The 預設 md — 「起手內容文件，render 即得該模板預設樣貌」 (issue 14 補充裁定).
+ *
+ * The frontmatter names the package itself, so the file renders with the
+ * template it belongs to even without `-t`. That is the property D4 turns into
+ * a test: the scaffold is only 開箱即 render if this exact file, unedited, comes
+ * out the other side as a clean artifact.
+ */
+const articleDocument = ({ namespace, name }) =>
+  [
+    '---',
+    `template: ${namespace}/${name}`,
+    `title: ${namespace}/${name}`,
+    'kicker: kamishibai 模板包骨架',
+    '---',
+    '',
+    '# 這是預設 md',
+    '',
+    `這份文件跟著模板包 \`${namespace}/${name}\` 一起被建立。它的用途是「秀出這個模板`,
+    '預設長什麼樣」——改它的內容，或改隔壁的 `stylesheet.css`，兩者都不需要動 SDK。',
+    '',
+    ':::note',
+    'manifest.toml 管宣告與套用態（所騎的 layout、准入的 block、measure 與 maxWidth）；',
+    'stylesheet.css 管皮；這份 md 管預設樣貌。三者分工，缺一不可。',
+    ':::',
+    '',
+    '## 想再往前一步',
+    '',
+    '- 純資料就夠用：多數模板只要改 `stylesheet.css` 與這份 md。',
+    '- 要換掉某個型別的轉換：放 `rotors/<型別>/override.js`。',
+    '- 要加新的 block 型別：放 `plugins/x-<名字>.js`，並把 `x-*` 寫進 manifest 的 blocks。',
+    '',
+  ].join('\n')
+
+/**
+ * The deck 預設 md. Three slides, because the thing a deck scaffold has to
+ * demonstrate is the one thing a one-slide file cannot: that `---` is a page
+ * break under this package's own key, not decoration. `:::place` appears on the
+ * third slide for the same reason — the 文體 declares the whole page addressable
+ * by 24-grid coordinates, and a starter file that never uses them leaves the
+ * reader to discover the feature from a specification.
+ *
+ * Note that the `:::place` fences stand on their own, with no `::::grid` around
+ * them. That is the visible consequence of the 文體's `gridAddressed` claim: on
+ * a deck the *page* lays the tracks, so a coordinate resolves without anyone
+ * wrapping it — and on a flowing 文體 the same three lines are refused loudly
+ * rather than silently dropped (`src/render/placement.js`).
+ */
+const deckDocument = ({ namespace, name }) =>
+  [
+    '---',
+    `template: ${namespace}/${name}`,
+    `title: ${namespace}/${name}`,
+    'kicker: kamishibai 簡報骨架',
+    '---',
+    '',
+    '# 這是預設簡報',
+    '',
+    `這份文件跟著模板包 \`${namespace}/${name}\` 一起被建立。\`---\` 在這個包底下是切頁符——`,
+    '前後各留一個空行，否則 Markdown 會把它讀成 setext 標題。',
+    '',
+    '---',
+    '',
+    '# 三份分工',
+    '',
+    '- `manifest.toml` 管宣告與套用態（所騎的 layout、准入的 block、maxWidth 與 measure）',
+    '- `stylesheet.css` 管皮',
+    '- 這份 md 管預設樣貌',
+    '',
+    ':::note',
+    '產物內建播放：方向鍵／空白鍵翻頁，f 全螢幕，Esc 離開。',
+    ':::',
+    '',
+    '---',
+    '',
+    ':::place col=1 colSpan=16',
+    '**24 格座標**：這一段占 24 格中的 16 格。這個文體宣告了整頁以 24 格軌定址，',
+    '所以座標不必再包一層 `grid`。',
+    ':::',
+    '',
+    ':::place col=17 colSpan=8',
+    '**側欄**：占右邊 8 格。',
+    ':::',
+    '',
+    ':::place col=1 colSpan=24',
+    '這一張沒有標題，是刻意的：`#` 標題會開一個 section，把後面的內容都收進去，',
+    '於是擺位是相對那個 section 而不是相對整張投影片的格軌。',
+    ':::',
+    '',
+  ].join('\n')
+
+/**
+ * The card 預設 md. **Three cards**, because the one thing a card board has to
+ * demonstrate is the thing a single-card file cannot: that a top-level heading
+ * is a card, that the cards sit side by side, and that they reflow. A starter
+ * file with one heading is indistinguishable from an `article`.
+ *
+ * It opens with a paragraph *before* the first heading, on purpose: that is the
+ * lead-in region, the other half of the 文體's cut, and a starter file that never
+ * produced one would leave the reader to discover it from a specification.
+ *
+ * No `---` anywhere. On this 文體 it is not a page break (that is a `deck` fact,
+ * `src/layouts/template-index.js`), so a stray one would come out as a thematic
+ * rule and teach exactly the wrong thing.
+ */
+const cardDocument = ({ namespace, name }) =>
+  [
+    '---',
+    `template: ${namespace}/${name}`,
+    `title: ${namespace}/${name}`,
+    'kicker: kamishibai 卡片骨架',
+    '---',
+    '',
+    `這份文件跟著模板包 \`${namespace}/${name}\` 一起被建立。第一個標題之前的段落`,
+    '不會變成卡片，而是卡群的前導語區——文體把頂層內容切成這兩塊。',
+    '',
+    '# 一張卡就是一個頂層標題',
+    '',
+    '標題底下的所有東西都留在同一張卡裡，子標題也是。卡片之間彼此獨立，',
+    '所以讀的人可以只挑一張看。',
+    '',
+    '## 子標題留在卡內',
+    '',
+    '- 卡內照常有清單',
+    '- 也照常有行內 `程式碼`',
+    '',
+    '# 三張卡才看得出鋪排',
+    '',
+    '一張卡看起來與長文沒有兩樣，兩張看不出換行，三張才畫得出「寬視窗多欄、',
+    '窄視窗單欄」這件事。',
+    '',
+    ':::note',
+    '卡格是 24 條格軌，一張卡佔其中幾條由 `stylesheet.css` 的 `--card-span` 決定。',
+    '想要兩欄看板就把它改成 12。',
+    ':::',
+    '',
+    '# 三份分工',
+    '',
+    '- `manifest.toml` 管宣告與套用態（所騎的 layout、准入的 block、maxWidth 與 measure）',
+    '- `stylesheet.css` 管皮，包含卡格與斷點',
+    '- 這份 md 管預設樣貌',
+    '',
+  ].join('\n')
+
+/**
+ * The one-page 預設 md. **Two screens plus an opening**, because the one thing a
+ * one-page site has to demonstrate is the thing a single-screen file cannot:
+ * that a top-level heading starts a new screen, and that scrolling is what moves
+ * between them. A starter file with one heading is indistinguishable from an
+ * `article` that happens to be scaled.
+ *
+ * It opens with a paragraph *before* the first heading, on purpose: together
+ * with the package's masthead that is the opening screen — the other half of the
+ * 文體's cut, and a starter file that never produced one would leave the reader
+ * to discover it from a specification.
+ *
+ * No `---` anywhere. On this 文體 it is not a page break (that is a `deck` fact,
+ * `src/layouts/template-index.js`), so a stray one would come out as a thematic
+ * rule *inside* a screen and teach exactly the wrong thing — the screen break is
+ * the heading.
+ */
+const onePageDocument = ({ namespace, name }) =>
+  [
+    '---',
+    `template: ${namespace}/${name}`,
+    `title: ${namespace}/${name}`,
+    'kicker: kamishibai 一頁式骨架',
+    '---',
+    '',
+    `這份文件跟著模板包 \`${namespace}/${name}\` 一起被建立。第一個標題之前的段落`,
+    '不會自成一屏，而是與抬頭一起組成開場屏——文體把頂層內容切成這兩塊。',
+    '',
+    '# 一屏就是一個頂層標題',
+    '',
+    '標題底下的所有東西都留在同一屏裡，子標題也是。一屏是一塊固定邏輯畫布，',
+    '視窗多大它就等比縮放到多大，所以在投影幕上與在筆電上看到的是同一個版面。',
+    '',
+    '## 子標題留在屏內',
+    '',
+    '- 屏內照常有清單',
+    '- 也照常有行內 `程式碼`',
+    '',
+    '# 兩屏才看得出捲動',
+    '',
+    '一屏看起來與一頁縮放過的長文沒有兩樣，兩屏才畫得出「往下捲，換一屏」這件事。',
+    '',
+    ':::note',
+    '切屏的是頂層標題，不是切頁符：deck 用的那組三橫線在這個文體上只會畫出一條分隔線。',
+    ':::',
+    '',
+    '# 三份分工',
+    '',
+    '- `manifest.toml` 管宣告與套用態（所騎的 layout、准入的 block、maxWidth 與 measure）',
+    '- `stylesheet.css` 管皮，包含屏的內距與列印形',
+    '- 這份 md 管預設樣貌',
+    '',
+  ].join('\n')
+
+/**
+ * The resume 預設 md. **Two sheets**, because the one thing a résumé scaffold has
+ * to demonstrate is the thing a single-sheet file cannot: that a top-level
+ * heading starts a **new sheet of paper**, and that a résumé section is `##`
+ * rather than `#`. A starter file with one heading would teach the opposite
+ * convention by omission, and the reader would find out at the printer.
+ *
+ * It opens with a line *before* the first heading, on purpose: together with the
+ * package's masthead that is the top of the first sheet — and, unlike every
+ * other 文體 here, it does **not** get a page of its own. An A4 sheet holding
+ * only a name is the failure this cut exists to avoid.
+ *
+ * No `---` anywhere. On this 文體 it is not a page break (that is a `deck` fact,
+ * `src/layouts/template-index.js`), so a stray one would come out as a thematic
+ * rule *inside* a sheet and teach exactly the wrong thing — the page break is
+ * the top-level heading.
+ */
+const resumeDocument = ({ namespace, name }) =>
+  [
+    '---',
+    `template: ${namespace}/${name}`,
+    `title: ${namespace}/${name}`,
+    'kicker: kamishibai 履歷骨架',
+    'author: you@example.org',
+    '---',
+    '',
+    `這份文件跟著模板包 \`${namespace}/${name}\` 一起被建立。第一個標題之前的段落`,
+    '不會自成一張紙，而是與抬頭一起排在**第一張紙的頂端**——紙上只印一個名字',
+    '是這個文體刻意避開的浪費。',
+    '',
+    '# 這一張紙',
+    '',
+    '一個頂層標題就是一張 A4。履歷的各段落請用 `##`：它們留在同一張紙裡，',
+    '而列印時一張紙就是一頁，不多也不少。',
+    '',
+    '## 經歷',
+    '',
+    '- **某某公司**（2023 - 至今）｜職稱',
+    '  - 一行寫清楚做了什麼、對誰有用',
+    '- **另一間公司**（2021 - 2023）｜職稱',
+    '',
+    '## 技能',
+    '',
+    '- 一組工具、一組語言、一組領域知識',
+    '',
+    ':::note',
+    '切紙的是頂層標題，不是切頁符：deck 用的那組三橫線在這個文體上只會畫出一條分隔線。',
+    ':::',
+    '',
+    '# 第二張紙',
+    '',
+    '兩張紙才看得出換頁。第二張紙用來放作品、著作或推薦人——內容放不下的時候，',
+    '開一個新的頂層標題就是開一張新的紙。',
+    '',
+    '## 三份分工',
+    '',
+    '- `manifest.toml` 管宣告與套用態（所騎的 layout、准入的 block、maxWidth 與 measure）',
+    '- `stylesheet.css` 管皮，包含紙的內距、@page 邊界與列印形',
+    '- 這份 md 管預設樣貌',
+    '',
+  ].join('\n')
+
+/**
+ * The 文體 this scaffold can actually produce a **working** package for, and
+ * everything it needs in order to.
+ *
+ * 複驗 F-1 (F3): `-l` used to accept any string. `init x/y -l deck` therefore
+ * wrote a manifest declaring the `deck` 文體 next to an article-shaped 預設 md,
+ * and then printed 「開箱即用：kamishibai render …」 — a command that cannot
+ * work, because the deck layout requires a `deck` root form the scaffolded
+ * document does not have. Two harms, and the second is the worse one: a dead
+ * package is a file you can delete, while a wrong copy-paste command from the
+ * SDK's own mouth is something the user will trust and then blame themselves for.
+ *
+ * So the flag is narrowed to what this table has content for. `deck` joined it
+ * in F2f, together with the other half it could not work without — a store deck
+ * package's `---` actually cutting pages (`src/layouts/template-index.js`).
+ */
+export const SCAFFOLD_BLUEPRINTS = Object.freeze({
+  article: Object.freeze({
+    root: NO_ROOT,
+    blocks: ARTICLE_BLOCKS,
+    maxWidth: ARTICLE_MAX_WIDTH,
+    measure: ARTICLE_MEASURE,
+    stylesheet: articleStylesheet,
+    document: articleDocument,
+  }),
+  /**
+   * `card` joined the table in F2c, and the entry is the measurement that slice
+   * exists to take: supporting a third 文體 cost this object and nothing else —
+   * no edit to `template-scaffold.js`, no new branch anywhere in the writer.
+   *
+   * `root: NO_ROOT` restated for the same reason `article` restates it: the
+   * `card` 文體 requires no root form, and a manifest that said nothing would be
+   * a disagreement rather than a silence (`KSB_LAYOUT_ROOT_CONFLICT`).
+   */
+  card: Object.freeze({
+    root: NO_ROOT,
+    blocks: ARTICLE_BLOCKS,
+    maxWidth: CARD_MAX_WIDTH,
+    measure: CARD_MEASURE,
+    stylesheet: cardStylesheet,
+    document: cardDocument,
+  }),
+  deck: Object.freeze({
+    /**
+     * Restated, never invented: the `deck` 文體 requires this root form, and a
+     * manifest that disagreed with its 文體 is refused outright
+     * (`KSB_LAYOUT_ROOT_CONFLICT`). Saying nothing would be a disagreement too.
+     */
+    root: 'deck',
+    blocks: DECK_BLOCKS,
+    maxWidth: DECK_MAX_WIDTH,
+    measure: DECK_MEASURE,
+    stylesheet: deckStylesheet,
+    document: deckDocument,
+  }),
+  /**
+   * `one-page` joined the table in F2d — the first **bounded** 文體 the scaffold
+   * can produce a working package for. That matters here rather than being a
+   * label: the logical canvas is the 文體's and arrives on the markup, so this
+   * entry supplies no size at all, and the skin's whole job is to be a frame
+   * that does not grow (see `onePageStylesheet`). A blueprint that laid the
+   * screen out like an article would produce a package whose content overflows
+   * the very canvas the skeleton is scaling — a page that looks broken in a way
+   * no error ever mentions.
+   *
+   * `root: NO_ROOT` restated for the same reason `article` and `card` restate
+   * it: the 文體 requires no root form, and a manifest that said nothing would
+   * be a disagreement rather than a silence (`KSB_LAYOUT_ROOT_CONFLICT`).
+   */
+  'one-page': Object.freeze({
+    root: NO_ROOT,
+    blocks: ARTICLE_BLOCKS,
+    maxWidth: ONE_PAGE_MAX_WIDTH,
+    measure: ONE_PAGE_MEASURE,
+    stylesheet: onePageStylesheet,
+    document: onePageDocument,
+  }),
+  /**
+   * `resume` joined the table in F2e, completing the v1 五版面. It is the first
+   * entry whose skin has to be right about **paper** rather than about a
+   * window: the `@page` box, the forced break between sheets and the print
+   * stand-down are not polish here, they are the difference between a PDF that
+   * is a résumé and a PDF that is a clipped ribbon of one.
+   *
+   * `root: NO_ROOT` restated for the same reason the other flowing-rooted
+   * entries restate it: the 文體 requires no root form, and a manifest that said
+   * nothing would be a disagreement rather than a silence
+   * (`KSB_LAYOUT_ROOT_CONFLICT`).
+   */
+  resume: Object.freeze({
+    root: NO_ROOT,
+    blocks: ARTICLE_BLOCKS,
+    maxWidth: RESUME_MAX_WIDTH,
+    measure: RESUME_MEASURE,
+    stylesheet: resumeStylesheet,
+    document: resumeDocument,
+  }),
+})
+
+/** Verbatim — the 文體 `init -l` lets through, derived from the table above. */
+export const SCAFFOLD_SUPPORTED_LAYOUTS = Object.freeze(Object.keys(SCAFFOLD_BLUEPRINTS))