contour-deck 0.2.2 → 0.3.0

package/README.md

@@ -13,7 +13,7 @@ Outline-first slide decks on real DOM.
 A deck is blocks, slides, and pages: it opens on an outline of every block, a block opens into a left-right track of slides, and each slide scrolls down one page at a time.
 The core is plain TypeScript with no runtime dependency (7 KB of JavaScript and 3 KB of CSS, gzipped); the phone remote is a separate module that loads on first use.
 
-Status: 0.1.0 on npm (M1). The M2 client is on `main`, not yet released: phone remote, laser pointer, drawing, tilt pointing, and a presenter window ([Remote](#remote)); the relay it talks to is a separate small service ([docs/PROTOCOL.md](docs/PROTOCOL.md)). Live demo: https://wayne930242.github.io/contour-deck/
+Status: 0.3.0 on npm. It holds the deck (M1), the M2 client (phone remote, laser pointer, drawing, tilt pointing, and a presenter window, see [Remote](#remote); the relay it talks to is a separate small service, [docs/PROTOCOL.md](docs/PROTOCOL.md)), and, new in 0.3.0, an opt-in structure for the Markdown plugins that reads blocks, slides, and pages from headings ([docs/PLUGINS.md](docs/PLUGINS.md#headings-mode)). Live demo: https://wayne930242.github.io/contour-deck/
 The design is in [docs/DESIGN.md](docs/DESIGN.md) (Traditional Chinese); the HTML the core reads is in [docs/CONTRACT.md](docs/CONTRACT.md).
 
 ## 看看它怎麼動
@@ -60,10 +60,15 @@ import { remarkDeck } from "contour-deck/remark";
 import { rehypeDeck } from "contour-deck/rehype";
 
 const isDeck = file => file.data.astro?.frontmatter?.type === "slide";
-// remarkPlugins: [remarkDirective, [remarkDeck, { match: isDeck }], …]
-// rehypePlugins: […, [rehypeDeck, { match: isDeck }]]
+// Optional. A deck with `slideOptions: { structure: headings }` in its frontmatter is read by its headings:
+// `---` starts a block, `##` a slide, `###` a page. Every other deck keeps the default rules.
+const structure = file => file.data.astro?.frontmatter?.slideOptions?.structure;
+// remarkPlugins: [remarkDirective, [remarkDeck, { match: isDeck, structure }], …]
+// rehypePlugins: […, [rehypeDeck, { match: isDeck, structure }]]
 ```
 
+By default a `---` starts a slide and `::vertical` a page; [docs/PLUGINS.md](docs/PLUGINS.md) has both sets of rules.
+
 ```astro
 ---
 import Deck from "contour-deck/astro";
@@ -228,7 +233,7 @@ The core removes both parameters in `destroy()` and leaves the others alone.
 src/core/      the core: model, stops, gestures, navigator, outline, rail, notes, transitions, deck
 src/remote/    contour-deck/remote: protocol, transports, pairing, clock, tilt math, QR, and the three views
 src/remark/    Markdown directives (block, vertical, summary, build)
-src/rehype/    builds the deck > block > slide > page HTML
+src/rehype/    builds the deck > block > slide > page HTML; headings.ts is the reader of `structure: "headings"`
 src/astro/     Deck.astro and the host script it runs (also contour-deck/host)
 styles/        index.css is the entry of contour-deck/style.css
 demo/          a plain-HTML deck that follows the contract, and media.html (clips and stills)

package/dist/rehype/draft.d.ts

@@ -0,0 +1,39 @@
+/** What the two readers (`---` slides in index.ts, headings.ts) share and hand to the assembler. */
+import { type Element, type HastNode } from "./hast.js";
+export declare const ORIGIN = "contour-deck:rehype";
+/** A `::block` as written: under `structure: "headings"` it may come without a title. */
+export interface BlockMark {
+    title?: string;
+    short?: string;
+    minutes?: string;
+    kind?: string;
+    id?: string;
+}
+export interface BlockSpec extends BlockMark {
+    title: string;
+}
+export interface SlideDraft {
+    pages: HastNode[][];
+    id?: string;
+    block?: BlockSpec;
+    /** Text of the first `h2` of the slide's first page: the key of the slide/page rule. */
+    h2?: string;
+    /** Old reveal.js indexes of the slide's first page: `?slide=h.v`. The headings reader has none. */
+    legacy?: number;
+    legacyV?: number;
+}
+export interface Group {
+    spec: BlockSpec;
+    slides: SlideDraft[];
+}
+/** Splits at breaks matching `isSplit`, dropping the breaks and the groups `keep` rejects. */
+export declare function splitAt(nodes: HastNode[], isSplit: (node: HastNode) => boolean, keep: (group: HastNode[]) => boolean): HastNode[][];
+/** A `---` of the author's, not the `<hr>` of a `::vertical` marker. */
+export declare const isRule: (node: HastNode) => boolean;
+export declare const hasContent: (group: HastNode[]) => boolean;
+export declare function blockMarkOf(marker: Element): BlockMark;
+/**
+ * The title of a block that has none of its own: the deck title, else the deck's first `h1`,
+ * else the title of the block's first slide.
+ */
+export declare function leadTitle(deckTitle: string | undefined, drafts: SlideDraft[], first: SlideDraft): string;

package/dist/rehype/draft.js

@@ -0,0 +1,36 @@
+/** What the two readers (`---` slides in index.ts, headings.ts) share and hand to the assembler. */
+import { isBlank, isElement, markOf } from "./hast.js";
+import { firstHeading, slideTitle } from "./titles.js";
+export const ORIGIN = "contour-deck:rehype";
+/** Splits at breaks matching `isSplit`, dropping the breaks and the groups `keep` rejects. */
+export function splitAt(nodes, isSplit, keep) {
+    const groups = [[]];
+    for (const node of nodes) {
+        if (isSplit(node))
+            groups.push([]);
+        else
+            groups[groups.length - 1].push(node);
+    }
+    return groups.filter(keep);
+}
+/** A `---` of the author's, not the `<hr>` of a `::vertical` marker. */
+export const isRule = (node) => isElement(node) && node.tagName === "hr" && markOf(node) === undefined;
+export const hasContent = (group) => group.some(node => !isBlank(node));
+export function blockMarkOf(marker) {
+    const text = (value) => (value === undefined ? undefined : String(value));
+    const { dataTitle, dataShort, dataMinutes, dataKind, id } = marker.properties;
+    return {
+        title: text(dataTitle),
+        short: text(dataShort),
+        minutes: text(dataMinutes),
+        kind: text(dataKind),
+        id: typeof id === "string" ? id : undefined,
+    };
+}
+/**
+ * The title of a block that has none of its own: the deck title, else the deck's first `h1`,
+ * else the title of the block's first slide.
+ */
+export function leadTitle(deckTitle, drafts, first) {
+    return deckTitle || firstHeading(drafts.flatMap(item => item.pages.flat()), 1) || slideTitle(first.pages, "Slides");
+}

package/dist/rehype/headings.d.ts

@@ -0,0 +1,9 @@
+import { type DeckFile } from "../shared/structure.js";
+import { type Group } from "./draft.js";
+import { type HastNode } from "./hast.js";
+/**
+ * Reads the blocks out of the flow. A block with a title of its own (`::block` title, else its
+ * heading) derives its label and the 附錄 kind from it unless `::block` gives them; a block
+ * without one takes the deck's title and derives nothing.
+ */
+export declare function readHeadings(flow: HastNode[], deckTitle: string | undefined, file: DeckFile): Group[];

package/dist/rehype/headings.js

@@ -0,0 +1,127 @@
+/**
+ * The reader of `structure: "headings"`: the deck's outline is the Markdown's own.
+ *
+ * - A top-level `---` starts a block.
+ * - A top-level `##` starts a slide. What stands before a block's first `##` is the block's first
+ *   slide (a title, a `# 拆解` divider), unless it is nothing but a `####` kicker, notes, and
+ *   directives: those open the first `##` slide.
+ * - A top-level `###` starts a further page of the slide, unless it stands right under the `##`
+ *   with no content between them: then both head the first page.
+ * - A block is titled by the first `#` or `####` before its first `##` or `###`; the heading stays
+ *   where it is. `::block{…}` anywhere at the block's top level overrides what it names.
+ * - Headings inside other elements, `####` and deeper, and a `#` after the first `##` are content.
+ */
+import { MARK_BLOCK, MARK_SLIDE, MARK_VERTICAL, NOTES } from "../shared/markers.js";
+import { NO_VERTICAL } from "../shared/structure.js";
+import { blockMarkOf, isRule, leadTitle, ORIGIN, splitAt } from "./draft.js";
+import { isBlank, isElement, markOf, plainText } from "./hast.js";
+import { kindOf, shortOf } from "./titles.js";
+function readBlock(nodes, file) {
+    let slide = { pages: [[]] };
+    const slides = [slide];
+    const idMarkers = new Map();
+    let bare = "opening";
+    let kicker = false;
+    /** No `##` or `###` yet: the part of the block its title heading stands in. */
+    let opening = true;
+    let heading;
+    let blockMarker;
+    /** The slide holds more than headings. */
+    let body = false;
+    /** A `::slide` written after the slide's body, with nothing after it yet. */
+    let trailing;
+    for (const node of nodes) {
+        if (!isElement(node)) {
+            if (!isBlank(node)) {
+                slide.pages[slide.pages.length - 1].push(node);
+                bare = trailing = undefined;
+                body = true;
+            }
+            continue;
+        }
+        const mark = markOf(node);
+        if (mark === MARK_VERTICAL)
+            file.fail(NO_VERTICAL, node, ORIGIN);
+        if (mark === MARK_BLOCK) {
+            if (blockMarker)
+                file.fail("a block holds two ::block directives", node, ORIGIN);
+            blockMarker = node;
+            continue;
+        }
+        if (mark === MARK_SLIDE) {
+            if (idMarkers.has(slide))
+                file.fail("a slide holds two ::slide directives", node, ORIGIN);
+            idMarkers.set(slide, node);
+            slide.id = String(node.properties.id);
+            trailing = body ? node : undefined;
+            continue;
+        }
+        if (node.tagName === "h2") {
+            if (bare === "opening") {
+                slide.pages[0].push(node);
+            }
+            else {
+                if (trailing) {
+                    file.fail(`::slide{#${slide.id}} stands between a slide's content and the next ##: write it under the heading of its own slide`, trailing, ORIGIN);
+                }
+                slide = { pages: [[node]] };
+                slides.push(slide);
+                body = false;
+            }
+            bare = "title";
+            opening = false;
+        }
+        else if (node.tagName === "h3") {
+            if (bare)
+                slide.pages[slide.pages.length - 1].push(node);
+            else
+                slide.pages.push([node]);
+            bare = undefined;
+            opening = false;
+        }
+        else {
+            slide.pages[slide.pages.length - 1].push(node);
+            if (NOTES in node.properties)
+                continue;
+            if (opening && (node.tagName === "h1" || node.tagName === "h4"))
+                heading ??= plainText(node) || undefined;
+            if (bare === "opening" && node.tagName === "h4" && !kicker)
+                kicker = true;
+            else
+                bare = undefined;
+            body ||= !/^h[1-6]$/.test(node.tagName);
+        }
+        trailing = undefined;
+    }
+    // Only the opening can be left empty: every other slide starts with its `##`.
+    if (!slides[0].pages[0].length) {
+        const marker = idMarkers.get(slides[0]);
+        if (marker)
+            file.fail("::slide without any content in its slide", marker, ORIGIN);
+        slides.shift();
+    }
+    if (!slides.length) {
+        if (blockMarker)
+            file.fail("::block stands in a block with no slide", blockMarker, ORIGIN);
+        return undefined;
+    }
+    return { mark: blockMarker && blockMarkOf(blockMarker), heading, slides };
+}
+/**
+ * Reads the blocks out of the flow. A block with a title of its own (`::block` title, else its
+ * heading) derives its label and the 附錄 kind from it unless `::block` gives them; a block
+ * without one takes the deck's title and derives nothing.
+ */
+export function readHeadings(flow, deckTitle, file) {
+    const blocks = splitAt(flow, isRule, () => true)
+        .map(nodes => readBlock(nodes, file))
+        .filter(block => block !== undefined);
+    const drafts = blocks.flatMap(block => block.slides);
+    return blocks.map(({ mark = {}, heading, slides }) => {
+        const own = mark.title ?? heading;
+        const spec = own
+            ? { ...mark, title: own, short: mark.short ?? shortOf(own), kind: mark.kind ?? kindOf(own) }
+            : { ...mark, title: leadTitle(deckTitle, drafts, slides[0]) };
+        return { spec, slides };
+    });
+}

package/dist/rehype/index.d.ts

@@ -1,12 +1,12 @@
+import { type DeckFile, type Structure, type StructureOption } from "../shared/structure.js";
 import { type HastNode } from "./hast.js";
 export interface DeckOptions {
     /** Deck title for `data-title`. Default: the `title` frontmatter field under Astro, else none. */
     title?: string;
     /** Whether to build a deck for this file. Default: every file. */
     match?: (file: DeckFile) => boolean;
+    /** `"slides"` (default) or `"headings"`, or a function of the file. Pass the same one to `contour-deck/remark`. */
+    structure?: StructureOption;
 }
-export interface DeckFile {
-    data: object;
-    fail(reason: string, place?: unknown, origin?: string): never;
-}
+export type { DeckFile, Structure, StructureOption };
 export declare function rehypeDeck(options?: DeckOptions): (tree: HastNode, file: DeckFile) => void;

package/dist/rehype/index.js

@@ -11,39 +11,29 @@
  *   starting with 附錄 gets `data-kind="appendix"`. Without any of these the deck is one block.
  * - `<section>` inside page content is left alone: the contract reads data attributes only.
  *
+ * These are the rules of `structure: "slides"`, the default. With `structure: "headings"` the
+ * slides come from headings.ts instead: `---` starts a block, `##` a slide, `###` a page.
+ *
  * Run it after `contour-deck/remark`, which writes the markers this plugin reads.
  */
 import { MARK_BLOCK, MARK_SLIDE, MARK_VERTICAL } from "../shared/markers.js";
-import { element, isBlank, isElement, markOf, plainText, walkElements, } from "./hast.js";
+import { structureOf } from "../shared/structure.js";
+import { blockMarkOf, hasContent, isRule, leadTitle, ORIGIN, splitAt, } from "./draft.js";
+import { element, isElement, markOf, plainText, walkElements } from "./hast.js";
+import { readHeadings } from "./headings.js";
 import { buildPage } from "./page.js";
 import { dividerOf, firstHeading, kickerOf, kindOf, shortOf, slideTitle } from "./titles.js";
-const ORIGIN = "contour-deck:rehype";
 function isFootnotes(node) {
     return isElement(node) && node.tagName === "section" && node.properties.dataFootnotes !== undefined;
 }
-/** Splits at breaks matching `isSplit`, dropping the breaks and the groups `keep` rejects. */
-function splitAt(nodes, isSplit, keep) {
-    const groups = [[]];
-    for (const node of nodes) {
-        if (isSplit(node))
-            groups.push([]);
-        else
-            groups[groups.length - 1].push(node);
-    }
-    return groups.filter(keep);
-}
-const isSlideBreak = (node) => isElement(node) && node.tagName === "hr" && markOf(node) === undefined;
 const isPageBreak = (node) => markOf(node) === MARK_VERTICAL;
-const hasContent = (group) => group.some(node => !isBlank(node));
-function blockSpecOf(marker) {
-    const { dataTitle, dataShort, dataMinutes, dataKind, id } = marker.properties;
-    return {
-        title: String(dataTitle),
-        short: dataShort === undefined ? undefined : String(dataShort),
-        minutes: dataMinutes === undefined ? undefined : String(dataMinutes),
-        kind: dataKind === undefined ? undefined : String(dataKind),
-        id: typeof id === "string" ? id : undefined,
-    };
+/** A `::block` of this mode always has a title: `contour-deck/remark` lets one through without only in headings mode. */
+function blockSpecOf(marker, file) {
+    const mark = blockMarkOf(marker);
+    if (mark.title === undefined) {
+        file.fail('::block has no title: remarkDeck ran with structure "headings" and rehypeDeck with "slides"; give both the same structure option', marker, ORIGIN);
+    }
+    return { ...mark, title: mark.title };
 }
 /**
  * Reads the slides out of the flow. A `---` always starts a slide. Inside a `---` group each
@@ -55,7 +45,7 @@ function readSlides(flow, file) {
     const drafts = [];
     let pending;
     let legacy = -1;
-    for (const group of splitAt(flow, isSlideBreak, group => group.length > 0)) {
+    for (const group of splitAt(flow, isRule, group => group.length > 0)) {
         let current;
         let vertical = 0;
         for (const chunk of splitAt(group, isPageBreak, chunk => chunk.length > 0)) {
@@ -66,7 +56,7 @@ function readSlides(flow, file) {
                 file.fail("a page holds two ::block directives", blocks[1], ORIGIN);
             if (slides.length > 1)
                 file.fail("a page holds two ::slide directives", slides[1], ORIGIN);
-            const spec = blocks[0] && blockSpecOf(blocks[0]);
+            const spec = blocks[0] && blockSpecOf(blocks[0], file);
             const twice = () => file.fail(`::block "${spec?.title}" follows ::block "${pending?.title}" with no slide between`, blocks[0], ORIGIN);
             if (!hasContent(rest)) {
                 if (slides.length)
@@ -144,8 +134,7 @@ function groupBlocks(drafts, deckTitle) {
             spec = { ...spec, short: spec.short ?? shortOf(spec.title) };
         }
         if (spec || !groups.length) {
-            const lead = deckTitle || firstHeading(drafts.flatMap(item => item.pages.flat()), 1) || slideTitle(draft.pages, "Slides");
-            groups.push({ spec: spec ?? { title: lead }, slides: [] });
+            groups.push({ spec: spec ?? { title: leadTitle(deckTitle, drafts, draft) }, slides: [] });
         }
         groups[groups.length - 1].slides.push(draft);
     }
@@ -159,15 +148,15 @@ function ids(nodes) {
     });
     return found;
 }
-function assemble(drafts, deckTitle, file) {
-    const taken = ids(drafts.flatMap(draft => draft.pages.flat()));
+function assemble(groups, file) {
+    const taken = ids(groups.flatMap(group => group.slides).flatMap(draft => draft.pages.flat()));
     const claim = (id, what) => {
         if (taken.has(id))
             file.fail(`${what} id "${id}" is already used in the document`, undefined, ORIGIN);
         taken.add(id);
         return id;
     };
-    return groupBlocks(drafts, deckTitle).map(({ spec, slides }, blockIndex) => {
+    return groups.map(({ spec, slides }, blockIndex) => {
         const properties = { dataCtBlock: true, dataTitle: spec.title };
         if (spec.short)
             properties.dataShort = spec.short;
@@ -184,8 +173,7 @@ function assemble(drafts, deckTitle, file) {
                 dataCtSlide: true,
                 id,
                 dataTitle: slideTitle(draft.pages, `Slide ${ordinal.replace("-", ".")}`),
-                dataLegacy: draft.legacy,
-                dataLegacyV: draft.legacyV,
+                ...(draft.legacy === undefined ? {} : { dataLegacy: draft.legacy, dataLegacyV: draft.legacyV }),
             }, draft.pages.map(buildPage));
         });
         return element("section", properties, sections);
@@ -212,9 +200,11 @@ export function rehypeDeck(options = {}) {
             else
                 flow.push(node);
         }
-        const drafts = readSlides(flow, file);
-        rejectNestedMarkers(drafts, file);
-        const blocks = assemble(drafts, deckTitle, file);
+        const groups = structureOf(options.structure, file, ORIGIN) === "headings"
+            ? readHeadings(flow, deckTitle, file)
+            : groupBlocks(readSlides(flow, file), deckTitle);
+        rejectNestedMarkers(groups.flatMap(group => group.slides), file);
+        const blocks = assemble(groups, file);
         const deck = element("div", { dataCtDeck: true, ...(deckTitle ? { dataTitle: deckTitle } : {}) }, blocks);
         tree.children = [...before, deck, ...after];
     };

package/dist/remark/index.d.ts

@@ -1,3 +1,5 @@
+import { type DeckFile, type Structure, type StructureOption } from "../shared/structure.js";
+export type { DeckFile, Structure, StructureOption };
 interface MdNode {
     type: string;
     name?: string;
@@ -8,13 +10,10 @@ interface MdNode {
         hProperties?: Record<string, unknown>;
     };
 }
-export interface DeckFile {
-    data: object;
-    fail(reason: string, place?: unknown, origin?: string): never;
-}
 export interface RemarkDeckOptions {
     /** Whether this file is a Contour deck. Default: every file. Pass the same test to `contour-deck/rehype`. */
     match?: (file: DeckFile) => boolean;
+    /** `"slides"` (default) or `"headings"`, or a function of the file. Pass the same one to `contour-deck/rehype`. */
+    structure?: StructureOption;
 }
 export declare function remarkDeck(options?: RemarkDeckOptions): (tree: MdNode, file: DeckFile) => void;
-export {};

package/dist/remark/index.js

@@ -12,8 +12,12 @@
  *
  * A directive written in the wrong form (`::summary` for `:::summary`) is an error here,
  * not an empty box, and so is an unknown attribute.
+ *
+ * With `structure: "headings"` the pages come from `###` headings, so `::vertical` is an error,
+ * and `::block` needs no `title`: the block has its heading.
  */
 import { MARK, MARK_BLOCK, MARK_BUILD, MARK_SLIDE, MARK_VERTICAL, NOTES } from "../shared/markers.js";
+import { NO_VERTICAL, structureOf } from "../shared/structure.js";
 const ORIGIN = "contour-deck:remark";
 const DIRECTIVES = {
     summary: {
@@ -29,7 +33,11 @@ const DIRECTIVES = {
     vertical: {
         form: "leaf",
         attributes: [],
-        hast: () => ({ hName: "hr", hProperties: { [MARK]: MARK_VERTICAL } }),
+        hast(node, _attributes, file, structure) {
+            if (structure === "headings")
+                file.fail(NO_VERTICAL, node, ORIGIN);
+            return { hName: "hr", hProperties: { [MARK]: MARK_VERTICAL } };
+        },
     },
     slide: {
         form: "leaf",
@@ -43,11 +51,18 @@ const DIRECTIVES = {
     block: {
         form: "leaf",
         attributes: ["title", "short", "minutes", "kind", "id"],
-        hast(node, attributes, file) {
+        hast(node, attributes, file, structure) {
             const title = attributes.title?.trim();
-            if (!title)
-                file.fail('::block needs a title: ::block{title="三、主要問題"}', node, ORIGIN);
-            const properties = { [MARK]: MARK_BLOCK, dataTitle: title };
+            if (structure === "slides") {
+                if (!title)
+                    file.fail('::block needs a title: ::block{title="三、主要問題"}', node, ORIGIN);
+            }
+            else if (attributes.title !== undefined && !title) {
+                file.fail("::block title is empty: leave it out to title the block by its heading", node, ORIGIN);
+            }
+            const properties = { [MARK]: MARK_BLOCK };
+            if (title)
+                properties.dataTitle = title;
             if (attributes.short !== undefined) {
                 const short = attributes.short.trim();
                 if (!short || [...short].length > 3) {
@@ -83,7 +98,7 @@ const EXAMPLE = {
     container: name => `:::${name} … :::`,
     leaf: name => `::${name}`,
 };
-function apply(node, file) {
+function apply(node, file, structure) {
     const directive = node.name ? DIRECTIVES[node.name] : undefined;
     if (!directive || !node.name)
         return;
@@ -99,19 +114,19 @@ function apply(node, file) {
         }
         attributes[key] = value ?? "";
     }
-    node.data = { ...node.data, ...directive.hast(node, attributes, file) };
+    node.data = { ...node.data, ...directive.hast(node, attributes, file, structure) };
     if (directive.form === "leaf")
         node.children = [];
 }
-function visit(node, file) {
-    apply(node, file);
+function visit(node, file, structure) {
+    apply(node, file, structure);
     for (const child of node.children ?? [])
-        visit(child, file);
+        visit(child, file, structure);
 }
 export function remarkDeck(options = {}) {
     return (tree, file) => {
         if (options.match && !options.match(file))
             return;
-        visit(tree, file);
+        visit(tree, file, structureOf(options.structure, file, ORIGIN));
     };
 }

package/dist/shared/structure.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How a deck's Markdown maps to blocks, slides, and pages. `contour-deck/remark` and
+ * `contour-deck/rehype` take the same `structure` option and resolve it here, per file.
+ *
+ * - `"slides"` (default): `---` starts a slide, `::vertical` a page, and blocks come from `::block`,
+ *   `####` kickers, or `#` dividers.
+ * - `"headings"`: `---` starts a block, `##` a slide, `###` a page.
+ */
+/** The file both plugins receive: a `VFile`, as far as they use it. */
+export interface DeckFile {
+    data: object;
+    fail(reason: string, place?: unknown, origin?: string): never;
+}
+export type Structure = "slides" | "headings";
+/** A structure for every file, or a function that picks one per file (nothing means `"slides"`). */
+export type StructureOption = Structure | ((file: DeckFile) => Structure | null | undefined);
+/** The one message for `::vertical` under `"headings"`, whichever plugin meets it. */
+export declare const NO_VERTICAL = "::vertical has no meaning with structure: \"headings\": start the next page with a ### heading";
+/**
+ * The structure of `file`. The value often comes from frontmatter, so anything other than the two
+ * names is an error here, not a silent fallback to the default.
+ */
+export declare function structureOf(option: StructureOption | undefined, file: DeckFile, origin: string): Structure;

package/dist/shared/structure.js

@@ -0,0 +1,22 @@
+/**
+ * How a deck's Markdown maps to blocks, slides, and pages. `contour-deck/remark` and
+ * `contour-deck/rehype` take the same `structure` option and resolve it here, per file.
+ *
+ * - `"slides"` (default): `---` starts a slide, `::vertical` a page, and blocks come from `::block`,
+ *   `####` kickers, or `#` dividers.
+ * - `"headings"`: `---` starts a block, `##` a slide, `###` a page.
+ */
+/** The one message for `::vertical` under `"headings"`, whichever plugin meets it. */
+export const NO_VERTICAL = '::vertical has no meaning with structure: "headings": start the next page with a ### heading';
+/**
+ * The structure of `file`. The value often comes from frontmatter, so anything other than the two
+ * names is an error here, not a silent fallback to the default.
+ */
+export function structureOf(option, file, origin) {
+    const value = typeof option === "function" ? option(file) : option;
+    if (value === undefined || value === null)
+        return "slides";
+    if (value === "slides" || value === "headings")
+        return value;
+    return file.fail(`structure must be "slides" or "headings", got ${JSON.stringify(value)}`, undefined, origin);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contour-deck",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Outline-first slide decks on real DOM: blocks, slides, pages.",
   "keywords": [
     "slides",