@kamishibai/sdk 0.1.1

package/src/layouts/card.js

@@ -0,0 +1,128 @@
+import { el } from '../blocks/element.js'
+import { CANVAS_FLOWING } from './registry.js'
+
+/**
+ * `card` — the flowing 文體 whose unit of reading is a **card**, not a column.
+ *
+ * A long-form page answers 「從頭讀到尾」; this one answers 「掃過去，挑一張看」.
+ * That is the whole difference, and it is a difference of *cut* rather than of
+ * content: the same document tree that `article` draws as one scrolling column
+ * is drawn here as a board of cards laid on a responsive grid — the home of a
+ * dashboard, a set of knowledge cards, a status board (CONTRACT F2c P1).
+ *
+ * The canvas stays `flowing`. A board of cards has no fixed logical size: it
+ * reflows to whatever window it lands in, and asking it to scale-to-fit would
+ * be asking a dashboard to be a slide. `maxWidth` is therefore how wide the
+ * board may get and `measure` is still the width of a line of text (CONTRACT
+ * C3) — two numbers, and on this 文體 they are pulled far apart, because a
+ * three-across board is nothing like a column of prose.
+ *
+ * ## The cut: top-level sections become cards, everything else leads in
+ *
+ * The document tree the parser produces nests every heading under its parent,
+ * so a document's **top-level `section` blocks are its chapters**. Each one
+ * becomes a card; whatever else sits at the top level (an opening paragraph, a
+ * callout, a table of contents someone wrote by hand) is the board's lead-in.
+ *
+ * CONTRACT F2c P1 words this as 「level-1 section 各成一卡」, and in an ordinary
+ * document — one that starts at `#` — the two sentences pick out exactly the
+ * same blocks. They part company only for a document that starts at `##`, and
+ * there the level test is the worse of the two: it would silently yield a board
+ * with no cards at all, because a heading-depth detail the author never thought
+ * about decided the shape of the page. Nothing is lost either way (every block
+ * is drawn), so the rule that does not depend on how deep the author started is
+ * the one this module takes (CONTRACT R10, executor's reason).
+ *
+ * ## Why there is no knob here
+ *
+ * `article` declares knobs because a rail is geometry the *markup* has to know
+ * about: the region only exists when the knob is on. A card board has no such
+ * switch — how many of the 24 columns a card spans, how wide the gutters are,
+ * where the grid breaks to one column: every one of those is read by the
+ * stylesheet and by nothing else, which makes them decoration, and decoration
+ * lives in the skin (`templates/kami/cards/styles.css`), never in a 文體.
+ * Declaring them here would put numbers in the layout that no other layer could
+ * ever ask about — the exact shape 「layout 只擁有切法」 rules out.
+ *
+ * It equally does **not** declare `gridAddressed`. The 24 tracks belong to the
+ * card grid, whose children are cards and only cards; a bare `col`/`colSpan` on
+ * a top-level block would land in the lead-in region, where there are no tracks
+ * to resolve against. Claiming the page is grid-addressed would licence exactly
+ * that coordinate and let CSS auto-placement drop it in silence.
+ */
+
+/** Verbatim — the block type one card is made of. */
+const CARD_BLOCK = 'section'
+
+/** Verbatim — the three regions of a board, as class names. */
+const BOARD_CLASS = 'cards'
+const LEAD_IN_CLASS = 'cards-intro'
+const GRID_CLASS = 'card-grid'
+const CARD_CLASS = 'card'
+
+const isCard = (block) => block?.type === CARD_BLOCK
+
+const region = (className, nodes) =>
+  nodes.length > 0 ? [el('div', { class: className }, nodes)] : []
+
+export default Object.freeze({
+  name: 'card',
+
+  canvas: CANVAS_FLOWING,
+
+  /** No required root form: a board draws whatever sits under `doc` (as `article`). */
+  rootForm: null,
+
+  /** The built-in generic template of this 文體 — `render` never wants for one. */
+  defaultTemplate: 'kami/cards',
+
+  slots: Object.freeze(['cards-lead', 'cards-foot']),
+
+  styleHooks: Object.freeze([BOARD_CLASS, LEAD_IN_CLASS, GRID_CLASS, CARD_CLASS]),
+
+  /**
+   * Factory geometry, in CSS pixels. Geometry only — a content-shaped default
+   * would make this layout mean something, and a layout that means something can
+   * only carry the documents it already imagined.
+   *
+   * 1200 is a board wide enough for three cards side by side without pretending
+   * to be a full-bleed application shell; 740 is the width of a line of text,
+   * unchanged from every other 文體 (CONTRACT C3: the page and the column are
+   * two numbers).
+   */
+  defaults: Object.freeze({ maxWidth: 1200, measure: 740 }),
+
+  /**
+   * A region is drawn only when something goes in it.
+   *
+   * The opposite reading of `article`'s rail, and deliberately so: the rail is
+   * *applied state* (a knob the template turned), so it stays in the markup even
+   * when empty, or the same package would be a different page for each document.
+   * These two regions have no knob and never could — whether a document has a
+   * lead-in is a fact about the document. Drawing an empty one would put a box
+   * in every artifact to say nothing, and a `null` child would put a real empty
+   * comment node there instead, which is worse: it is invisible and permanent.
+   */
+  root: (doc, ctx) => {
+    const children = doc?.children ?? []
+    const cards = children.filter(isCard)
+    const leadIn = children.filter((block) => !isCard(block))
+    return el(
+      'article',
+      { class: BOARD_CLASS, 'data-template': ctx.templateKey },
+      [
+        ...ctx.chrome('cards-lead', ctx.meta),
+        ...region(LEAD_IN_CLASS, ctx.renderChildren(leadIn)),
+        ...region(
+          GRID_CLASS,
+          cards.map((block, index) =>
+            el('div', { class: CARD_CLASS }, [
+              ctx.renderBlock(block, { index, total: cards.length }),
+            ]),
+          ),
+        ),
+        ...ctx.chrome('cards-foot', ctx.meta),
+      ],
+    )
+  },
+})

package/src/layouts/deck.js

@@ -0,0 +1,88 @@
+import { CANVAS_BOUNDED } from './registry.js'
+
+/** Verbatim — the root form that makes an artifact a deck. */
+const DECK_ROOT = 'deck'
+
+/**
+ * Verbatim — the deck's fixed logical canvas, in CSS pixels (CONTRACT F2f P3).
+ *
+ * 1280×720 rather than any other 16:9 pair because it is the size every slide
+ * tool, every projector mode and every screen-capture default already speaks,
+ * and because a *logical* canvas only has to be the one everybody means: the
+ * artifact is scaled to whatever the window is (`src/render/scale.js`), so the
+ * number's job is to be shared, not to be large.
+ */
+const DECK_CANVAS = Object.freeze({ width: 1280, height: 720 })
+
+/** The deck sits directly under `doc` (parser/index.js buildDeck). */
+const deckOf = (doc) => (doc?.children ?? []).find((block) => block?.type === DECK_ROOT)
+
+/**
+ * `deck` — the slide 文體.
+ *
+ * Its root form is a single `deck` block, and that requirement is the layout's,
+ * not any one template's: handing a flat document tree to a deck template used
+ * to type-check completely and then draw nothing at all. Stating it here is
+ * what turns 「replay 換皮不換文體」 from a rule into a structure — every deck
+ * template inherits the refusal, and none of them can decline it.
+ *
+ * ## The canvas is `bounded`, and the canvas is one slide
+ *
+ * F2a built the mechanism and deliberately did not connect it: declaring
+ * `bounded` moves every slide artifact's bytes, and that slice was only allowed
+ * to flip the structure (CONTRACT F2a P4「只建不接」). F2f is the slice that may
+ * move them, so the declaration is now true — and with it v1's 「fullscreen
+ * 只多黑框」 finally ends: going fullscreen used to enlarge the page and leave
+ * the artifact exactly as small as before, because nothing was ever scaled.
+ *
+ * The fixed logical canvas is **one slide**, not the whole deck. A deck has N
+ * pages; a page is the thing with a fixed size, and 1280×720 is what a page of
+ * a deck is. Putting the canvas on the deck instead would have made the
+ * artifact a single 720px-tall box containing every slide — which reads as
+ * one slide and hides the rest, and would take the no-JS fallback (a plain
+ * scrolling document, `playback.client.js` の前提) with it.
+ *
+ * ## Why it also declares `gridAddressed`
+ *
+ * Because it now lays the tracks. `gridAddressed` is a claim the placement gate
+ * takes at face value (`src/render/placement.js`), so a layout that declared it
+ * without building the 24 columns would license coordinates that CSS
+ * auto-placement then drops in silence — the exact hole F2a's gate closes. The
+ * tracks are laid on the slide's content region by `src/blocks/slide.js`, and
+ * they are laid **because this layout says so**: the block asks the resolved
+ * canvas rather than assuming, so the same module still draws a flowing
+ * deck-rooted layout the plain way.
+ */
+export default Object.freeze({
+  name: 'deck',
+
+  canvas: CANVAS_BOUNDED,
+
+  rootForm: DECK_ROOT,
+
+  defaultTemplate: 'kami/slides',
+
+  slots: Object.freeze(['slide-lead', 'deck-chrome']),
+
+  styleHooks: Object.freeze(['deck', 'slide', 'slide-inner', 'slide-cell']),
+
+  /**
+   * The whole page is addressable by 24-grid coordinates — see above, and note
+   * that `bounded` deliberately does **not** imply this (F2a 複驗補丁).
+   */
+  gridAddressed: true,
+
+  /**
+   * Factory geometry, in CSS pixels. Three numbers, three different jobs, and
+   * the reason they are three:
+   *
+   *  - `canvasSize` 1280×720 — the logical page that gets scaled to fit.
+   *  - `maxWidth` 1120 — how wide the content region inside that page may grow.
+   *    A slide with type running the full 1280 has no margin at all.
+   *  - `measure` 740 — the width a *line of text* wants, unchanged from every
+   *    other 文體 (CONTRACT C3: the page and the column are two numbers).
+   */
+  defaults: Object.freeze({ maxWidth: 1120, measure: 740, canvasSize: DECK_CANVAS }),
+
+  root: (doc, ctx) => ctx.renderBlock(deckOf(doc)),
+})

package/src/layouts/index.js

@@ -0,0 +1,90 @@
+import { registerLayout, sealCoreLayouts, layoutModule, layoutNames } from './registry.js'
+
+import article from './article.js'
+import card from './card.js'
+import deck from './deck.js'
+import onePage from './one-page.js'
+import resume from './resume.js'
+
+/**
+ * The factory 文體 set, in canonical order.
+ *
+ * **All five** of the v1 layouts (issue 13 裁決 1) exist as of F2e. `article` and
+ * `deck` were here from F2a because they are what the two shipped templates
+ * already were; `card` is the first one this SDK *added* rather than lifted, and
+ * adding it was the measurement F2c existed to take — a new 文體 should cost one
+ * layout module, one built-in template, one scaffold blueprint and this line,
+ * with no edit to the layout interface itself (CONTRACT F2c P2).
+ *
+ * `one-page` (F2d) takes that measurement again on the harder half: it is the
+ * first **bounded** 文體 added through the public shape rather than lifted from
+ * an existing template, so it is the first to exercise `defaults.canvasSize`,
+ * the registry's bounded-geometry refusal and the scale-to-fit skeleton from
+ * the outside. It cost the same one line here.
+ *
+ * `resume` (F2e) closes the set, and it is the one that asks the interface a
+ * question none of the other four could: its artifact is *printed*, so its
+ * canvas is a sheet of A4 rather than a shape a window has. It too cost one
+ * line here — the paper lives in the layout module, not in the SDK.
+ *
+ * A sixth does not belong here at all: the v1 list is five, and a third-party
+ * layout calls `registerLayout` from outside and needs no edit to any file
+ * inside `src/`.
+ */
+const CORE_LAYOUTS = Object.freeze([article, card, deck, onePage, resume])
+
+for (const mod of CORE_LAYOUTS) registerLayout(mod)
+sealCoreLayouts()
+
+/**
+ * The 文體 an artifact is drawn in, resolved from the template's manifest.
+ *
+ * A manifest that names no layout falls back to the first factory layout, which
+ * keeps every pre-F2a manifest (and every third-party one written against it)
+ * loadable: the flowing article is what a template *was* before layouts had
+ * names.
+ */
+export const DEFAULT_LAYOUT = article.name
+
+export function resolveLayout(manifest) {
+  return layoutModule(manifest?.layout ?? DEFAULT_LAYOUT)
+}
+
+/** The built-in generic template of a layout — the tail of the resolution chain. */
+export const defaultTemplateOf = (name = DEFAULT_LAYOUT) =>
+  layoutModule(name)?.defaultTemplate
+
+export {
+  CANVAS_BOUNDED,
+  CANVAS_FLOWING,
+  CANVAS_MODES,
+  GRID_ADDRESSED_FIELD,
+  LAYOUT_DEFAULT_KEYS,
+  LAYOUT_KNOBS_FIELD,
+  LAYOUT_MODULE_FIELDS,
+  PLUGIN_LAYOUT_PREFIX,
+  layoutModule,
+  layoutModules,
+  layoutNames,
+  layoutRegistryVersion,
+  pluginLayoutNames,
+  registerLayout,
+  resetLayoutRegistry,
+} from './registry.js'
+
+export {
+  CANVAS_ATTR,
+  CANVAS_INVALID_CODE,
+  canvasAttrs,
+  canvasProblems,
+  resolveCanvas,
+} from './canvas.js'
+
+export {
+  registerTemplateLayoutSource,
+  resetTemplateLayoutSources,
+  templateLayoutEntries,
+} from './template-index.js'
+
+/** Exported for the layer that has to name every 文體 in a message. */
+export const knownLayouts = () => layoutNames()

package/src/layouts/one-page.js

@@ -0,0 +1,161 @@
+import { el } from '../blocks/element.js'
+import { CANVAS_BOUNDED } from './registry.js'
+
+/**
+ * `one-page` — the 文體 of a general one-page static website.
+ *
+ * A long-form page answers 「從頭讀到尾」, a board of cards answers 「掃過去，挑
+ * 一張看」; this one answers 「一直往下捲，一屏換一屏」. It is the shape a landing
+ * page, a product page or a service page already has: a few full-bleed screens,
+ * each holding one idea, read by scrolling past them in order (13 號票 v1 五版面
+ * 之四).
+ *
+ * ## The cut: one top-level section is one screen
+ *
+ * The parser nests every heading under its parent, so a document's **top-level
+ * `section` blocks are its chapters** — and on this 文體 a chapter is a screen.
+ * Whatever else sits at the top level (an opening paragraph, a callout, a lead
+ * sentence someone wrote before the first heading) joins the template's
+ * `page-lead` chrome to become the **opening screen**, which is what a hero is.
+ *
+ * The test is 「是不是頂層 section」 and deliberately **not** 「是不是 level 1」,
+ * the same R10 reasoning `card` records: an ordinary document (one that starts
+ * at `#`) makes the two sentences pick out identical blocks, and they part
+ * company only for a document that starts at `##` — where the level test would
+ * silently yield a site with no screens at all, because a heading-depth detail
+ * the author never thought about decided the shape of the page.
+ *
+ * ## The canvas is bounded, and **one screen is one canvas** (CONTRACT F2d R10)
+ *
+ * A bounded 文體 has a fixed logical canvas that is scaled to fit (issue 14
+ * 裁決 4), and the contract left *which* canvas to the executor. There were two
+ * candidates and the measurement settles it. Making the whole scrolling page a
+ * single tall canvas puts a page-height divided by a window-height into
+ * `Math.min(vw / w, vh / h)` — so the whole site is shrunk to a postage stamp.
+ * Measured in a real browser on `fixtures/one-page-sample.md` (6 screens,
+ * natural height 2398px) with the real `scale-to-fit.client.js` running:
+ *
+ *   viewport 1440x900   whole page 0.375x -> 18px body text lands at 6.8px
+ *                       per screen 1.000x -> 18px body text lands at 18.0px
+ *   viewport 1280x720   whole page 0.300x -> 5.4px    per screen 0.800x -> 14.4px
+ *   viewport 1920x1080  whole page 0.450x -> 8.1px    per screen 1.200x -> 21.6px
+ *
+ * and the whole-page half gets *worse the longer the page is* — which is the
+ * defining property of a one-page site. So the canvas is a screen, exactly as a
+ * `deck`'s canvas is a slide and not the deck: the artifact is a scrollable
+ * sequence of bounded screens, which is also what keeps the no-JS form honest
+ * (nothing is scaled, everything is still there, in order).
+ *
+ * ## Why there is no knob here
+ *
+ * How a screen is padded, how the opening screen arranges itself, how large the
+ * type is: every one of those is read by the stylesheet and by nothing else,
+ * which makes them decoration, and decoration lives in the skin
+ * (`templates/kami/one-page/styles.css`). The logical canvas is not a knob — it
+ * is `defaults.canvasSize`, the one extra field every bounded 文體 has, and the
+ * registry requires it at registration time.
+ *
+ * ## Why it does **not** declare `gridAddressed`
+ *
+ * `deck` may declare it because a slide's children are a flat run of blocks:
+ * the 24 tracks are laid on that content region and a bare `col: 17` resolves
+ * to a real cell. A screen is not that shape. A screen's child is exactly **one
+ * `section`**, and a `#` heading swallows everything beneath it — which is why
+ * even the deck scaffold's own 預設 md warns that a titled slide places its
+ * content relative to the section rather than to the page. Tracks laid here
+ * would have a single child, and any coordinate an author wrote *inside* the
+ * section would not be a direct child of the region at all: CSS auto-placement
+ * would drop it in silence, and the placement gate — which takes the
+ * declaration at face value (`src/render/placement.js`) — would have stopped
+ * refusing it. The claim and the tracks must land together, so neither lands.
+ */
+
+/** Verbatim — the block type one screen is made of. */
+const SCREEN_BLOCK = 'section'
+
+/** Verbatim — the two regions of a one-page site, as class names. */
+const PAGE_CLASS = 'one-page'
+const SCREEN_CLASS = 'screen'
+const SCREEN_INNER_CLASS = 'screen-inner'
+
+/**
+ * Verbatim — the fixed logical canvas of **one screen**, in CSS pixels.
+ *
+ * 1440×900 rather than the deck's 1280×720 because a screen of a website is not
+ * a slide: 1440 is the width every design tool's desktop artboard already is,
+ * and 16:10 rather than 16:9 leaves a screen the extra height a page of a site
+ * uses for a heading plus a paragraph plus a call to action. Like every logical
+ * canvas the number's job is to be shared, not to be large — the artifact is
+ * scaled to whatever window it lands in (`src/render/scale.js`).
+ */
+const SCREEN_CANVAS = Object.freeze({ width: 1440, height: 900 })
+
+const isScreen = (block) => block?.type === SCREEN_BLOCK
+
+export default Object.freeze({
+  name: 'one-page',
+
+  canvas: CANVAS_BOUNDED,
+
+  /** No required root form: a site draws whatever sits under `doc` (as `article`). */
+  rootForm: null,
+
+  /** The built-in generic template of this 文體 — `render` never wants for one. */
+  defaultTemplate: 'kami/one-page',
+
+  slots: Object.freeze(['page-lead', 'page-foot']),
+
+  styleHooks: Object.freeze([PAGE_CLASS, SCREEN_CLASS, SCREEN_INNER_CLASS]),
+
+  /**
+   * Factory geometry, in CSS pixels. Three numbers, three different jobs:
+   *
+   *  - `canvasSize` 1440×900 — the logical screen that gets scaled to fit.
+   *  - `maxWidth` 1200 — how wide the content region inside a screen may grow.
+   *    A screen with type running the full 1440 has no margin at all.
+   *  - `measure` 740 — the width a *line of text* wants, unchanged from every
+   *    other 文體 (CONTRACT C3: the page and the column are two numbers).
+   */
+  defaults: Object.freeze({ maxWidth: 1200, measure: 740, canvasSize: SCREEN_CANVAS }),
+
+  /**
+   * A screen is drawn only when something goes in it.
+   *
+   * The opening screen exists when the document has top-level content that is
+   * not a chapter, or when the template filled `page-lead` — and not otherwise.
+   * The same reading as `card`'s two regions, and for the same reason: whether
+   * a site has an opening is a fact about the document, not applied state a
+   * template turned, so drawing an empty one would put a blank screen in front
+   * of every artifact that has no lead-in. `...(x ? [n] : [])` rather than
+   * `x ? n : null`, because a `null` child is a real, invisible, permanent empty
+   * comment node in the artifact.
+   *
+   * The canvas attributes come from `ctx.canvas`, never from the constant above:
+   * a template may not move the logical canvas, but the resolved canvas is the
+   * one place that answer is computed, and a second computation here is a scale
+   * factor free to disagree with the one the skeleton uses.
+   */
+  root: (doc, ctx) => {
+    const children = doc?.children ?? []
+    const screens = children.filter(isScreen)
+    const opening = [
+      ...ctx.chrome('page-lead', ctx.meta),
+      ...ctx.renderChildren(children.filter((block) => !isScreen(block))),
+    ]
+    const screen = (nodes) =>
+      el('section', { class: SCREEN_CLASS, ...(ctx.canvas?.canvasAttrs ?? {}) }, [
+        el('div', { class: SCREEN_INNER_CLASS }, nodes),
+      ])
+    return el(
+      'article',
+      { class: PAGE_CLASS, 'data-template': ctx.templateKey },
+      [
+        ...(opening.length > 0 ? [screen(opening)] : []),
+        ...screens.map((block, index) =>
+          screen([ctx.renderBlock(block, { index, total: screens.length })]),
+        ),
+        ...ctx.chrome('page-foot', ctx.meta),
+      ],
+    )
+  },
+})