@codename/deck 0.0.0-stage → 0.1.1

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+export { createDeck, markdownOf } from './deck.js';
+export { parseDeck } from './parse.js';
+export { renderSlide } from './render.js';
+export { STANDARD, mergeKits, layoutOf, inferLayout, labelOf, tokensFrom } from './kit.js';
+export { tokensOf, schemeOf, LOOKS, readable, contrast } from './look.js';
+export { readDeckFile, writeDeckFile, rendererUrl, escape, unescape } from './file.js';
+export { toPptx } from './pptx.js';
+export { defaultBlocks, libraryAt } from './blocks.js';
+export { inlinePictures } from './pictures.js';
+export { deckIn } from './repair.js';
+export { VERSION } from './version.js';

package/dist/types/kit.d.ts

@@ -0,0 +1,73 @@
+export type Budget = {
+    required?: boolean;
+    max_words?: number;
+    max_chars?: number;
+    items?: [number, number];
+    item_max_words?: number;
+    heading_max_words?: number;
+    kind?: string;
+};
+export type Layout = {
+    label?: Record<string, string> | string;
+    intent?: string;
+    use_when?: string;
+    avoid_when?: string;
+    slots: string[];
+    budgets: Record<string, Budget>;
+    areas: string[][];
+    columns: string[];
+    rows: string[];
+    align: 'start' | 'center' | 'end';
+    justify: 'start' | 'center' | 'end';
+    paper: 'paper' | 'fill' | 'ink' | 'soft';
+    title: 'normal' | 'large' | 'huge';
+    pptx: string;
+    numbered: boolean;
+};
+export type Kit = {
+    name?: string;
+    tokens: Record<string, any>;
+    layouts: Record<string, Layout>;
+};
+/** The names brains give the usual layouts, for the ones deck has. */
+export declare const ALIASES: Record<string, string>;
+/** deck's own kit: the usual layouts, the ones Slidev names and the ones PowerPoint has, as data. */
+export declare const STANDARD: Kit;
+/**
+ * A layout as given, checked: its slots, areas and tracks in the grammar, its words' place, paper
+ * and size among their names. @param {any} given @returns {{ layout: Layout | null, problems: string[] }}
+ */
+export declare function layoutOf(given: any): {
+    layout: Layout | null;
+    problems: string[];
+};
+/**
+ * Design tokens as the W3C's Design Tokens format (DTCG 2025.10) writes them, read into a kit's:
+ * `color.light` and `color.dark` groups (bg, surface, fg, muted, accent) or flat colours, `font.sans`
+ * and the like; each `$value` a hex string or a colour object with its `hex`. Tokens already flat
+ * pass through. @param {any} given @returns {Record<string, any>}
+ */
+export declare function tokensFrom(given: any): Record<string, any>;
+/**
+ * Kits merged, the later over the earlier: their tokens, and their layouts by name, each checked.
+ * @param {...any} kits @returns {{ kit: Kit, problems: string[] }}
+ */
+export declare function mergeKits(...kits: any[]): {
+    kit: Kit;
+    problems: string[];
+};
+/** A layout's name in a language, else its own name. @param {Layout} layout @param {string} name @param {string} lang */
+export declare function labelOf(layout: Layout, name: string, lang: string): string;
+/**
+ * The layout a slide that names none is given, from what it holds, as Pandoc's PowerPoint writer
+ * chooses: the first slide is the cover; a heading alone, a section; slots beyond the first, the
+ * layout of two (or three) columns that has them; a number alone as its heading, a fact; a quote
+ * alone, a quote; else the default. @param {{ index: number, slots: { name: string, text: string }[] }} slide
+ */
+export declare function inferLayout(slide: {
+    index: number;
+    slots: {
+        name: string;
+        text: string;
+    }[];
+}): "cover" | "default" | "fact" | "quote" | "section" | "three-cols" | "two-cols" | "two-cols-header";

package/dist/types/look.d.ts

@@ -0,0 +1,55 @@
+export type Tokens = {
+    paper: string;
+    ink: string;
+    primary: string;
+    voice: string;
+    radius: number;
+    muted?: string;
+    soft?: string;
+    dark?: Record<string, string>;
+    fonts?: {
+        heading: string[];
+        body: string[];
+    };
+};
+export type Scheme = {
+    paper: string;
+    ink: string;
+    muted: string;
+    line: string;
+    primary: string;
+    onPrimary: string;
+    soft: string;
+    series: string[];
+};
+/** @typedef {{ paper: string, ink: string, primary: string, voice: string, radius: number, muted?: string, soft?: string, dark?: Record<string, string>, fonts?: { heading: string[], body: string[] } }} Tokens */
+/** @typedef {{ paper: string, ink: string, muted: string, line: string, primary: string, onPrimary: string, soft: string, series: string[] }} Scheme */
+/** Looks a deck can name (`theme:`), each a handful of tokens. */
+export declare const LOOKS: Record<string, Tokens>;
+/** Type for each voice: the device's faces, so a deck needs nothing to download to look right. */
+export declare const VOICES: Record<string, {
+    heading: string;
+    body: string;
+}>;
+/**
+ * The tokens a deck's settings give, over the project's look and a named one.
+ * @param {Record<string, any>} settings @param {Partial<Tokens>} [project]
+ * @returns {Tokens}
+ */
+export declare function tokensOf(settings: Record<string, any>, project?: Partial<Tokens>): Tokens;
+/**
+ * Light or dark, worked out from the tokens: dark swaps paper and ink and lifts the primary.
+ * @param {Tokens} tokens @param {'light' | 'dark'} scheme @returns {Scheme}
+ */
+export declare function schemeOf(tokens: Tokens, scheme: 'light' | 'dark'): Scheme;
+/** @param {string} value @returns {[number, number, number] | null} */
+export declare function hex(value: string): [number, number, number] | null;
+/** @param {number[]} rgb */
+export declare const css: (rgb: number[]) => string;
+/** WCAG's contrast ratio. @param {number[]} a @param {number[]} b */
+export declare function contrast(a: number[], b: number[]): number;
+/**
+ * The colour, its hue kept, deepened or lightened toward black or white until it reads at the
+ * ratio on the paper. @param {number[]} colour @param {number[]} paper @param {number} ratio
+ */
+export declare function readable(colour: number[], paper: number[], ratio: number): [number, number, number];

package/dist/types/parse.d.ts

@@ -0,0 +1,20 @@
+export type Slot = {
+    name: string;
+    text: string;
+    start: number;
+};
+export type Slide = {
+    index: number;
+    start: number;
+    end: number;
+    settings: Record<string, any>;
+    slots: Slot[];
+    notes: string;
+    title: string;
+};
+export type Deck = {
+    settings: Record<string, any>;
+    slides: Slide[];
+};
+/** @param {string} source @returns {Deck} */
+export declare function parseDeck(source: string): Deck;

package/dist/types/pictures.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The deck with its pictures inside it.
+ * @param {string} source
+ * @param {(place: string) => Promise<{ type: string, bytes: Uint8Array } | null>} read
+ * @param {{ web?: boolean, largest?: number }} [options] `web`: pictures on the web too; `largest`: bytes past which a picture stays a link
+ * @returns {Promise<{ source: string, inlined: string[], missing: string[], kept: string[] }>}
+ */
+export declare function inlinePictures(source: string, read: (place: string) => Promise<{
+    type: string;
+    bytes: Uint8Array;
+} | null>, { web: fromWeb, largest }?: {
+    web?: boolean;
+    largest?: number;
+}): Promise<{
+    source: string;
+    inlined: string[];
+    missing: string[];
+    kept: string[];
+}>;

package/dist/types/pptx.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @param {import('./deck.js').DeckView} view
+ * @param {{ PptxGenJS: any, JSZip: any }} libraries
+ * @returns {Promise<{ blob: Blob, report: { slides: number, charts: number, pictures: number, tables: number, placeholders: number } }>}
+ */
+export declare function toPptx(view: import('./deck.js').DeckView, { PptxGenJS, JSZip }: {
+    PptxGenJS: any;
+    JSZip: any;
+}): Promise<{
+    blob: Blob;
+    report: {
+        slides: number;
+        charts: number;
+        pictures: number;
+        tables: number;
+        placeholders: number;
+    };
+}>;

package/dist/types/render.d.ts

@@ -0,0 +1,34 @@
+export type Slide = import('./parse.js').Slide;
+export type Slot = import('./parse.js').Slot;
+export type Drawer = (element: HTMLElement, source: string) => void | Promise<void>;
+export type Context = {
+    blocks: Record<string, Drawer>;
+    resolve: (src: string) => string | null;
+    headings: 'real' | 'aria';
+    number: (n: number) => string;
+    total: number;
+    kit: import('./kit.js').Kit;
+    lex: (markdown: string) => any[];
+    slide: string;
+};
+/** @typedef {import('./parse.js').Slide} Slide */
+/** @typedef {import('./parse.js').Slot} Slot */
+/** @typedef {(element: HTMLElement, source: string) => void | Promise<void>} Drawer */
+/** @typedef {{ blocks: Record<string, Drawer>, resolve: (src: string) => string | null, headings: 'real' | 'aria', number: (n: number) => string, total: number, kit: import('./kit.js').Kit, lex: (markdown: string) => any[], slide: string }} Context */
+/**
+ * @param {string} tag @param {Record<string, string | number | boolean | undefined>} [attributes]
+ * @param {(Node | string | null | undefined | false)[]} [children]
+ */
+export declare function h(tag: string, attributes?: Record<string, string | number | boolean | undefined>, children?: (Node | string | null | undefined | false)[]): HTMLElement;
+/** An address a slide may show: the web's, a picture held in the file, or one beside it. @param {string} href */
+export declare function safeUrl(href: string): string | null;
+/**
+ * A slide, laid out by its layout, with its slots, steps and number.
+ * @param {Slide} slide @param {Context} context @returns {{ element: HTMLElement, steps: number }}
+ */
+export declare function renderSlide(slide: Slide, context: Context): {
+    element: HTMLElement;
+    steps: number;
+};
+/** @param {any[]} tokens @param {Context} context @returns {Node[]} */
+export declare function inline(tokens: any[] | undefined, context: Context): Node[];

package/dist/types/repair.d.ts

@@ -0,0 +1,5 @@
+/** The deck an answer holds, or null. @param {string} answer @returns {{ source: string, mended: string[] } | null} */
+export declare function deckIn(answer: string): {
+    source: string;
+    mended: string[];
+} | null;

package/dist/types/strings.d.ts

@@ -0,0 +1,2 @@
+/** @param {string} lang */
+export declare const stringsFor: (lang: string) => Record<string, string>;

package/dist/types/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.1";

package/dist/types/yaml.d.ts

@@ -0,0 +1,2 @@
+/** @param {string} text @returns {Record<string, any>} */
+export declare function parseYaml(text: string): Record<string, any>;

package/docs/findings.md

@@ -0,0 +1,57 @@
+# What phase 0 measured
+
+Measured on 25 October 2026 on a Mac (M3 Max), in Playwright's Chromium and WebKit, Microsoft PowerPoint 16.114 and Keynote 14, with two local brains through LM Studio: Qwen 3.6 35B A3B Splash and Qwen 3.5 4B.
+
+## Size
+
+| File | gzipped |
+|---|---|
+| `dist/deck.js`, the whole file renderer, `marked` inside | 37.8 KB (113 KB as held in a file) |
+| `dist/deck.mjs`, for a host with its own `marked` | 21.1 KB |
+| `dist/deck.css` | 3.8 KB |
+| A linked 11-slide `.deck.html` | 2.7 KB, not gzipped |
+
+## Browsers
+
+From disk (`file://`) in Chromium and WebKit: the first slide in 150 to 460 ms; no slide over its box; no error. Steps, the Morph between two slides sharing a heading, a change on a slide going back into the Markdown, a change in the Markdown drawn on the slide, the presenter's view, all slides at once, light and dark, Arabic right to left and Japanese. With scripts off, the Markdown as text. In a host page under `style-src 'self'` and `trusted-types 'none'`: no violation.
+
+## PowerPoint
+
+Made in the browser in 50 to 140 ms. PowerPoint opens every file without a repair: English light and dark, Arabic (bullets, the chart's axis and the table's columns mirrored), Japanese, and a deck with its own kit, whose layouts PowerPoint lists by their labels. Fixed during phase 0: text boxes as wide as their slot, titles anchored at their foot, centred layouts centred, Arabic upright.
+
+Left: a list beside a picture touches the slide's edge; CSS decorations (a quote's mark, a section's rule) are not exported; faces a kit names should be ones Office has.
+
+**Keynote is not a target.** It opens the files, says the format is invalid and drops the native charts; text, tables, layouts, diagrams and notes survive.
+
+## Brains, with a draft skill
+
+`eval/skill.md`, four requests (a support team's numbers, a children's park for a town council, training new staff, a school trip) in English, French, Arabic and Japanese.
+
+- Neither brain used the asked-for ` ````deck ` fence (0 of 8). With `deckIn`'s repairs, 8 of 8 decks, 55 slides, none over its box, every chart parsed and drawn, no stray HTML, the language right every time.
+- The 35B brain makes real decks (sections, a big number, two columns, a chart, a timeline). The 4B makes usable, weaker ones: charts nobody needed, squeezed under bullets.
+
+## Brains, with no help
+
+The same requests, asking for a title slide, a section, two columns, steps and notes on every slide, naming only the dialect, scored in that dialect's own syntax (`eval/dialects/`).
+
+| Asked in | 35B, of 5 | 4B, of 5 | HTML and CSS invented (35B / 4B) |
+|---|---|---|---|
+| Slidev | 2.3 | 0.8 (one reply empty) | 34 / 9 |
+| Marp | 1.8 | 1.8 (7 of 8 decks without `marp: true`) | 22 / 14 |
+| Quarto (Pandoc) | 3.0 | 2.0 | 2 / 88 |
+
+Brains blend dialects: Slidev decks with Pandoc's `::: notes`, Quarto decks with remark's `???`, Marp decks with reveal.js's fragments. Read liberally, all 23 replies that held anything became decks: 144 slides, no error.
+
+## Diagrams
+
+Fourteen samples (`test/diagrams/`), from a flowchart to a quadrant chart, two in Japanese and Arabic.
+
+| Renderer | gzipped | Samples drawn |
+|---|---|---|
+| Mermaid 12.2 | 1,567 KB | 14 |
+| @mermaid-js/tiny 12.2 | 744 KB | not run (no mind maps) |
+| beautiful-mermaid 1.1 | 458 KB | not run (6 kinds) |
+| **Pele 1.10** | 254 KB all, 130 KB twelve kinds, 17–52 KB a kind | 14, with no DOM, 0.14–1.3 ms each |
+| @crafter/mermaid 0.0.3 | 31 KB | 9, and no licence in its packages |
+
+Pele's drawings match Mermaid's or are clearer. It was first released on 17 October 2026: deck pins its version and draws the samples in its tests.

package/docs/format.md

@@ -0,0 +1,70 @@
+# The deck file
+
+## The page
+
+A deck is one HTML file, named `<name>.deck.html`. Any browser opens it; the renderer draws and presents it. A host reads its Markdown as text and never runs the page.
+
+````html
+<!doctype html>
+<html lang="en" dir="ltr">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="deck 0.1.0">
+<title>A second oven</title>
+<style>#deck{display:block;white-space:pre-wrap;overflow-wrap:anywhere;font:1rem/1.6 ui-monospace,Menlo,Consolas,monospace;max-width:72ch;margin:2rem auto;padding:0 1rem}</style>
+<body>
+<script type="text/markdown" id="deck">
+…the Markdown…
+</script>
+<script src="https://cdn.jsdelivr.net/npm/@codename/deck@0.1.0/dist/deck.js"></script>
+</html>
+````
+
+- **The Markdown** sits whole in one element, `<script type="text/markdown" id="deck">`, which no browser runs. Nothing inside a script element is decoded, so `R&D` stays `R&D`.
+- **One escape.** `<script` and `</script`, in any case, gain a backslash after their `<`, and one more for each already there; reading takes one away. The HTML parser would otherwise end the element at `</script`, and a `<script` after `<!--` would keep it from ending. `readDeckFile(writeDeckFile(md))` gives back `md` exactly.
+- **In the body.** Without the explicit `<body>`, the parser would put the element in the head, which is never shown.
+- **With scripts off,** the style above shows the Markdown as plain text in the body.
+- **The renderer** is linked by default, to this version of the package on jsDelivr (`rendererUrl()`). A host may link another address, or hold the renderer whole (`{ code }`, about 113 KB), its `<!--`, `<script` and `</script` written with `\x3C`. A `data-base` attribute on the renderer's script says where the libraries a slide needs come from: a CDN's npm mirror (the default) or a `node_modules/` folder.
+- **Pictures** the deck names by a host's own address are held inside the file as `data:` addresses when it leaves the host (`inlinePictures`). Pictures on the web stay links unless asked for. A page opened from disk can't read back a picture beside it, so a file meant to travel holds its pictures.
+- **Title, language and direction** are in the head for whatever reads the page before the renderer does.
+
+## The Markdown
+
+Slidev's form, as `@slidev/parser` splits it, and the parts a deck for knowledge workers needs. Every deck written this way opens in Slidev too; ECharts blocks and kits need an addon there.
+
+### Written and read
+
+- **Slides** between lines holding only `---`. A `---` followed by a `key:` line opens that slide's settings, YAML up to the next `---` line; a ` ```yaml ` block at a slide's top does the same.
+- **The first slide's settings** are the deck's too (its headmatter): `title`, `lang`, `dir`, `colorSchema` (`auto`, `light`, `dark`), `transition`, `theme`, `themeConfig`, `kit`.
+- **A slide's settings:** `layout`, `transition` (`slide-left`, `slide-right`, `slide-up`, `fade`, `view-transition`; `a | b` for forward and back), `class` (`invert`, `text-center`), `image`, `background`, `alt`, `title`, `paginate`.
+- **Slots:** `::name::` alone on a line starts the slot of that name; what comes before is `default`.
+- **Notes:** the last HTML comment at a slide's end.
+- **Steps:** `<v-clicks>` and `</v-clicks>` around a list, each on its own line with empty lines around; `<v-click>` around a block.
+- **Code** in fences, with lines marked as Slidev marks them: ` ```ts {2,4-5} `.
+- **Charts:** ` ```echarts ` holding an ECharts option as JSON, data only.
+- **Diagrams:** ` ```mermaid ` holding Mermaid's language.
+- **Markdown** as CommonMark and GFM have it: headings, lists, task lists, tables, quotes, emphasis, links, pictures.
+
+### Added by deck
+
+- ` ```echarts `, `lang` and `dir`.
+- `kit`: tokens and layouts as data ([kits.md](kits.md)).
+- A layout chosen from what a slide holds when it names none.
+- A Morph between two slides that share a heading, a picture or a list item, with `transition: view-transition`.
+
+### Also read, as brains write it
+
+Brains blend dialects. These are read, never rewritten:
+
+- Pandoc's `::: notes`, `:::: columns` holding `::: column`s (slots `left`, `right`, or `left`, `middle`, `right`; what follows them `bottom`), `::: incremental`.
+- remark's `???` and reveal.js's `Note:` (what follows is the notes), reveal.js's `<aside class="notes">`.
+- Slides at headings of the first two levels when a deck has no `---` at all, as Pandoc splits a document.
+- Steps written as `<li v-click>`.
+- A `---` followed by words, which Slidev would take for settings, as a new slide.
+- Names brains give layouts: `title`, `two-columns`, `comparison`, `divider`, `thanks`…
+
+`deckIn(answer)` finds a deck in a brain's answer and mends what brains get wrong most: a deck fenced as ` ```markdown ` or with nothing, a chart's fence inside three backticks, settings after an empty line, steps without their empty lines, a chart fenced as ` ```json `, words after a slot's marker.
+
+### Left out
+
+Vue components and expressions, UnoCSS classes, `<style>`, imported slides, Monaco, drawing. Other HTML gives up its words alone.

package/docs/host.md

@@ -0,0 +1,50 @@
+# Drawing decks in a host
+
+A host is a page that draws decks itself: Jean, or any other. deck builds every element with the DOM's own calls, sets custom properties through the CSSOM rather than style attributes, and needs no Trusted Types policy, so it runs under a policy with `style-src 'self'` and `trusted-types 'none'`. Load `@codename/deck` (with your own `marked` through an import map) or `@codename/deck/bundle`, and `@codename/deck/css` as a stylesheet.
+
+## createDeck(element, options)
+
+```js
+import { createDeck } from '@codename/deck'
+
+const view = createDeck(document.querySelector('#deck'), {
+  source,                       // the Markdown
+  lang: 'fr', dir: 'ltr',       // else the deck's own, else the page's
+  kit,                          // the host's kit: an organisation's, a person's, a project's, merged
+  scheme: 'auto',               // 'light', 'dark' or 'auto', over the deck's colorSchema
+  blocks: { echarts, mermaid }, // drawers for fenced blocks: (box, source) => void | Promise<void>
+  resolve: (src) => url,        // a picture's address as the page can load it, or null
+  strings,                      // the bar's words, and `slide` and `carousel` for screen readers, else deck's own (en, fr, ar, ja)
+  lex: (markdown) => tokens,    // how a slide's Markdown is read: the host's own marked, its extensions too; else marked's GFM
+  headings: 'aria',             // 'real' (h1–h6) or 'aria' (role=heading), for a deck inside a page
+  editable: true,
+  onChange: (source) => {},     // after each change, by the Markdown or on a slide
+  onSave: (source) => {},       // ⌘S or Ctrl+S
+  onExport: (view) => {},       // the bar's Save as PowerPoint
+})
+```
+
+The view: `source`, `deck` (parsed), `at`, `scheme`, `kit`, `kitProblems`, `lang`, `dir`, `slides()`, `setSource(text)`, `go(index, step)`, `toggle('is-editing' | 'is-presenting' | 'is-overview')`, `present()`, `setScheme(scheme)`, `fitAll()`, `destroy()`.
+
+Events on the element: `deck-scheme` (`detail: { scheme, colours, tokens }`) when the look is set, `deck-move` (`detail: { at, step }`) on each move.
+
+Every block that can be changed by hand carries `data-edit="from-to"`, the offsets of its words in the source, so a host can point at a part of a slide and change it in the Markdown.
+
+## Drawers
+
+`defaultBlocks({ base, root, versions })` gives the drawers a file uses alone: ECharts as SVG in the deck's colours and type, its category axis mirrored right to left; Pele for Mermaid's language, its SVG shown as a picture coloured by Pele's variables, its words the picture's text. Each library loads the first time a slide needs it, from `base` (jsDelivr's npm mirror, or a `node_modules/` folder, `libraryAt()`). A host with a strict policy gives its own: Pele's SVG holds style attributes, so it belongs in an image or a worker's output, not in the page's DOM.
+
+## PowerPoint
+
+```js
+const { blob, report } = await toPptx(view, { PptxGenJS, JSZip })
+```
+
+PptxGenJS 4 (its bundle carries JSZip) is the host's to load, on demand. The file is made from the deck as drawn: a slide layout per deck layout, named by its label in the deck's language, with a placeholder for its title and each slot; lists as lists with their levels; tables; bars, lines, areas, pies, rings, points and radars as native charts with their numbers, other charts and diagrams as pictures; notes; transitions; the kit's colours as the theme. `report` counts slides, charts, tables, pictures and placeholders.
+
+## Files
+
+- `readDeckFile(html)`: the Markdown, or `null`; never parses the page.
+- `writeDeckFile(markdown, { title, lang, dir, renderer, base })`: the page. `renderer` is `{ src }` (default: `rendererUrl()`) or `{ code }`.
+- `inlinePictures(source, read, { web, largest })`: the deck with its pictures inside it. `read(place)` gives `{ type, bytes }` for a picture the host holds. Hosts call it on a deck leaving them (a download, a share).
+- `deckIn(answer)`: a brain's deck from its answer, mended, with what was mended.

package/docs/kits.md

@@ -0,0 +1,76 @@
+# Kits
+
+A kit is a design system and the layouts that go with it, as data. deck checks every layout against the grammar below and drops what fails, with a reason, so no kit can do more than lay out a slide: no CSS, no addresses, no code. A person, an organisation or a brain can make one safely.
+
+```yaml
+kit:
+  name: Martin's bakery
+  tokens: { primary: '#c2410c', voice: elegant, radius: 4 }
+  layouts:
+    three-numbers:
+      label: { en: Three numbers, fr: Trois chiffres }
+      intent: Prove the title with three numbers.
+      slots: [default, one, two, three]
+      areas: default default default | one two three
+      rows: auto 1fr
+      align: center
+      pptx: Comparison
+```
+
+## Where kits come from
+
+Kits stack, the later over the earlier: deck's own (`STANDARD`), then what the host gives (`options.kit`: an organisation's, a person's, a project's, merged by the host), then the file's own `kit` in its headmatter. A host writes the kit a deck was drawn with into its file, so it looks the same wherever it goes.
+
+## Tokens
+
+Flat:
+
+| Token | What it is |
+|---|---|
+| `paper`, `ink`, `primary` | Colours, as `#rgb` or `#rrggbb` |
+| `muted`, `soft` | Optional: secondary words, a pale fill |
+| `voice` | `calm`, `elegant`, `bold`, `friendly`: the device's own faces for headings and text |
+| `fonts` | Optional: `{ heading: [...], body: [...] }`, face stacks, over the voice |
+| `radius` | Corners, in pixels |
+| `dark` | Optional: `{ paper, ink, primary, muted, soft }` for the dark scheme, else worked out |
+
+Or in the W3C's Design Tokens format (DTCG 2025.10): `color.light` and `color.dark` groups of `bg`, `surface`, `fg`, `muted`, `accent` (or flat colours), `font.sans`, `font.heading`, `font.body`; each `$value` a hex string or a colour object with its `hex`. `tokensFrom()` reads them.
+
+Whatever the tokens, light and dark are each checked: words at 4.5:1 on their paper, a chart's marks at 3:1, each colour deepened or lightened at its hue until it reads.
+
+## Layouts
+
+| Field | Grammar | Default |
+|---|---|---|
+| `slots` | Names (`a-z`, `0-9`, `-`), or a map of names to budgets; `title` there means the heading the default slot opens with | `[default]` |
+| `areas` | Rows of slot names or `.`, split by `\|` or new lines, or a list of rows; every slot a rectangle | the slots in a row |
+| `columns`, `rows` | One track a column or row: `auto`, `min-content`, `max-content`, `1fr`…`99fr`, `10%`… | `1fr` each |
+| `align` | `start`, `center`, `end`: across | `start` |
+| `justify` | `start`, `center`, `end`: down | `start` |
+| `paper` | `paper`, `fill` (the primary), `ink`, `soft` | `paper` |
+| `title` | `normal`, `large`, `huge` | `normal` |
+| `pptx` | Title Slide, Title and Content, Section Header, Two Content, Comparison, Title Only, Blank, Content with Caption, Picture with Caption | by its slots |
+| `numbered` | `false` for no slide number | `true` |
+| `label` | Words, or words by language: `{ en: …, fr: … }`; PowerPoint's layout is named so | the name |
+| `intent`, `use_when`, `avoid_when` | Words for the brain choosing a layout | none |
+| budgets | `required`, `max_words`, `max_chars`, `items: [min, max]`, `item_max_words`, `heading_max_words`, `kind` | none |
+
+A catalog's `types` are read as `layouts`. Budgets are kept with each layout for a linter and for the brain; deck 0.1 does not check them yet.
+
+## deck's own layouts
+
+| Layout | Slots | In PowerPoint |
+|---|---|---|
+| `cover`, `intro`, `end` | one | Title Slide |
+| `default` | one | Title and Content |
+| `section` | one | Section Header |
+| `two-cols` | `default`, `right` | Two Content |
+| `two-cols-header` | `default` across, `left`, `right`, `bottom` | Comparison |
+| `three-cols` | `default` across, `left`, `middle`, `right` | Comparison |
+| `center`, `statement`, `fact`, `quote` | one | Title Only |
+| `image-left`, `image-right` | one, beside the slide's `image` | Picture with Caption |
+| `image`, `full`, `none` | one | Blank |
+
+## A slide that names none
+
+As Pandoc's PowerPoint writer chooses: a slide with `middle` is `three-cols`, with `left` `two-cols-header`, with `right` `two-cols`; the first slide is `cover`; a heading alone is `section`; a number alone as its heading, a line or two under it, is `fact`; a quote alone, its author under it, is `quote`; else `default`. A layout the kit lacks falls back the same way.

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@codename/deck",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Slide decks as one web page: Markdown in Slidev's form inside a .deck.html file any browser presents, a renderer that runs anywhere, kits of layouts and looks, and an editable PowerPoint out",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/deck.mjs"
+    },
+    "./bundle": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/deck.bundle.mjs"
+    },
+    "./file": "./dist/deck.js",
+    "./css": "./dist/deck.css",
+    "./src/*": "./src/*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "slides",
+    "presentation",
+    "markdown",
+    "slidev",
+    "powerpoint",
+    "pptx"
+  ],
+  "scripts": {
+    "build": "node build.mjs && tsc -p tsconfig.types.json",
+    "examples": "npm run build && node examples/make.mjs",
+    "test": "node --test test/*.test.js",
+    "test:browsers": "npm run examples && node test/browser.mjs && node test/kit-browser.mjs",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test && npm run test:browsers",
+    "eval": "node eval/run.mjs",
+    "eval:check": "node eval/check.mjs && node eval/dialects/check.mjs && node eval/dialects/draw.mjs",
+    "prepare": "git config core.hooksPath .githooks || true",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "peerDependencies": {
+    "marked": "^18.0.14"
+  },
+  "devDependencies": {
+    "echarts": "6.1.0",
+    "esbuild": "0.28.2",
+    "marked": "^18.1.1",
+    "pele": "1.10.0",
+    "playwright": "1.64.1",
+    "pptxgenjs": "^4.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}