rikiki-deck 0.5.0 → 0.7.1

package/README.md

@@ -6,52 +6,92 @@
 
 A tiny **Lit Web Components** framework for technical presentations. Drop a folder anywhere, open `index.html`, give the talk. No build step on the consumer side · the framework itself is built from TypeScript, but the output is plain ES modules you import directly.
 
-This documentation tracks rikiki v0.5.0.
+This documentation tracks rikiki v0.7.1.
 
 ## TL;DR
 
 ```sh
-cp starter.html my-deck.html
+npm install rikiki-deck
+npx rikiki init my-deck.html
+python3 -m http.server        # ES modules need http://, not file://
 ```
 
-Edit `my-deck.html`. Each slide is a custom element. Markdown is available anywhere via `<deck-md>`. Navigate with `←` / `→` (or click, or the scroll wheel), `O` for the overview grid. Decks are linear by default; add `nav="2d"` on `<deck-root>` for chapter/slide grid navigation.
+`init` writes the deck and copies the runtime it loads into `./rikiki/` beside
+it. Edit `my-deck.html`. Each slide is a custom element. Markdown is available anywhere via `<deck-md>`. Navigate with `←` / `→` (or click, or the scroll wheel), `O` for the overview grid. Decks are linear by default; add `nav="2d"` on `<deck-root>` for chapter/slide grid navigation.
 
-## Layout
+## Look at it, and measure it
+
+You cannot review a deck you cannot see. Two commands stand in for eyes, both
+needing the optional peer `playwright`:
+
+```sh
+npx rikiki render talk.html            # one PNG per slide + a gallery + a manifest
+npx rikiki render talk.html --steps    # every revealed state, not just the first
+npx rikiki render talk.html --out after/ --baseline before/   # what moved since last time
+npx rikiki check talk.html             # what is wrong, where, and what to try
+npx rikiki check talk.html --json      # the same, as a versioned report
+npx rikiki check talk.html --steps     # measure every revealed state, not just the first
+```
+
+`render --baseline <dir>` compares the fresh pictures to an earlier set, slide
+by slide, and ranks them by how much changed, with the bounding box of what
+moved and a `diff.json` beside the manifest. It exits 1 on a slide that
+changed, disappeared or changed size. The default `--threshold 0.5` (percent of
+pixels) keeps anti-aliasing noise out of the report; `--threshold 0` lists
+every pixel change.
+
+`check` reports a runtime that never loaded, a file that did not arrive, a
+misspelled `deck-*` element that renders as nothing, content the slide clips
+away, text too small for a room, and duplicate slide ids. It exits 0 when
+nothing blocks, 1 on defects, 2 when it could not look at the deck at all. It
+also lists what it did **not** check, because silence would read as approval.
+Under `--steps`, each slide is measured in its opening state and in every
+state its own reveals step through, and each diagnostic says which one
+(`state: 2`).
+
+## For LLMs / coding assistants
+
+If you point a coding assistant (Claude Code, Copilot, …) at this package, give it
+the machine-oriented docs — they are the single source of truth and ship with the
+npm package:
+
+- **[`llms.txt`](./llms.txt)** — concise capability map and entry points (the
+  [llms.txt convention](https://llmstxt.org)).
+- **[`docs/llms/rikiki-workflow.md`](./docs/llms/rikiki-workflow.md)** — the
+  working guide: brief to plan to slides to checks to delivery, with nine
+  compositions by intent whose HTML is verified by the test suite. The one to
+  read first.
+- **[`docs/llms/rikiki-reference.md`](./docs/llms/rikiki-reference.md)** — every
+  tag, attribute, slot, design token, plugin, and recipe in one file. Have the
+  assistant read this first; tell it not to invent tags or tokens outside it.
+- **Claude Code skills** — `rikiki-deck`, `rikiki-theme`, `rikiki-debug` ship in
+  `.claude/skills/` (see [Claude Code skills](#claude-code-skills) to install
+  them); they teach an assistant the authoring/theming/debugging workflows.
+
+## What the install gives you
 
 ```
-rikiki/
+node_modules/rikiki-deck/
 ├── tokens.css                ← entry point · re-exports the default theme
 ├── themes/
 │   ├── rikiki.css            ← default theme (acid greens + mango, on dark)
 │   ├── siliceum.css          ← alternative theme (warm paper + yellow)
 │   └── siliceum-fonts.css    ← self-hosted Source Sans Pro + JetBrains Mono
 ├── fonts/                    ← woff2 files used by the Siliceum theme
-├── src/                      ← TypeScript sources · organised by DS bucket
-│   ├── index.ts              ← registers every component
-│   ├── shared-styles.ts
-│   ├── livereload.ts
-│   ├── runtime/              ← deck-root, deck-help, deck-overview,
-│   │                            deck-presenter, deck-transition, deck-notes
-│   ├── layouts/              ← deck-cover, deck-section, deck-feature,
-│   │                            deck-split, deck-feature-cards, deck-takeaway,
-│   │                            deck-photo
-│   ├── molecules/            ← deck-callout, deck-card, deck-md, deck-mermaid,
-│   │                            deck-stat, deck-metric, deck-tier-list,
-│   │                            deck-step-list, deck-shortcut, deck-stack,
-│   │                            deck-grid
-│   ├── atoms/                ← deck-badge, deck-kicker, deck-punch, deck-code
-│   └── plugins/              ← opt-in (shiki for advanced syntax highlighting)
-├── dist/                     ← built output · FLAT regardless of src bucket
-│                                (deck-root's dynamic imports rely on it)
-├── build.mjs                 ← esbuild script
-├── tsconfig.json
-└── starter.html              ← blank template, one slide per layout type
+├── dist/                     ← the runtime · plain ES modules, FLAT layout
+│   └── vendor/               ← lit and marked · mermaid and Shiki when asked
+├── bin/                      ← the rikiki CLI
+├── docs/llms/                ← the full agent reference
+└── .claude/skills/           ← three agent skills · install with `rikiki skills`
 ```
 
+`init` copies the first five of those next to your deck, minus the heavy
+plugin payloads unless you ask for them.
+
 ## Three-layer styling
 
 1. **Theme tokens** (`themes/<name>.css`) at `:root` · custom properties cross the Shadow DOM, so they reach every component.
-2. **Shared styles** (`src/shared-styles.ts`) · base typography, helpers, imported by every layout via `static styles`.
+2. **Shared styles** · base typography and helpers, compiled into every layout's own Shadow DOM.
 3. **Layout-specific CSS** · each component's own Shadow DOM.
 
 To re-theme: copy a theme file, change the values, that's it. All components follow.
@@ -77,10 +117,14 @@ To re-theme: copy a theme file, change the values, that's it. All components fol
 | `<deck-code lang="js" hero?>` | Code block with light syntax highlighting |
 | `<deck-callout type="info\|warn\|danger\|ok">` | Information callout |
 | `<deck-card color="yellow\|orange\|green\|red?">` | Tinted card |
-| `<deck-mermaid>` | Diagram via Mermaid (loaded on demand from CDN) |
+| `<deck-mermaid>` | Diagram via the vendored Mermaid runtime (opt-in bundle) |
+| `<deck-figure>` | An image with its own caption and credit (opt-in bundle) |
+| `<deck-source>` | The credit line under a table, chart, screenshot or quote |
 
 Plus `<deck-badge>`, `<deck-metric>`, `<deck-tier-list>`, `<deck-step-list>`, `<deck-kicker>`, `<deck-stack>`, `<deck-grid>`, `<deck-punch>`.
 
+Opt-in components add `<deck-annotate>` (numbered badges on a screenshot, placed by `above` / `below` / `left` / `right` anchors as well as pixel offsets) and `<deck-versus slide>` (a before/after slide with its own `title`, `lead` and `footer` slots).
+
 ## Common patterns
 
 ### Slide with markdown + code
@@ -124,7 +168,7 @@ Plus `<deck-badge>`, `<deck-metric>`, `<deck-tier-list>`, `<deck-step-list>`, `<
 
 ## Markdown support (`<deck-md>`)
 
-Parser: `marked` 12 from CDN. Supports GFM (tables, task lists), code blocks, inline code, **bold**, *italic*, lists, blockquotes, links, `---`.
+Parser: vendored `marked` 12. Supports GFM (tables, task lists), code blocks, inline code, **bold**, *italic*, lists, blockquotes, links, `---`.
 
 ## Navigation
 
@@ -172,6 +216,16 @@ reflows like a web page:
 <deck-root fluid>  <!-- fills its box, reflows, no letterbox -->
 ```
 
+A single slide can also escape the canvas by carrying its own `fluid` attribute
+· that slide gets the real viewport (handy for an embedded live demo) while the
+rest of the deck stays on the fixed canvas:
+
+```html
+<deck-feature fluid>
+  <iframe src="playground.html" style="position:fixed; inset:0; border:0;"></iframe>
+</deck-feature>
+```
+
 Both modes are embed-safe · a `<deck-root>` placed inside a larger page scales
 to (or fills) its own container and never touches the host page's scroll or
 typography.
@@ -208,18 +262,28 @@ deck-cover::part(brand) { font-family: 'Comic Sans'; }
 
 ### Add a layout
 
-Create `src/layouts/deck-my-layout.ts`, `import { slideBase } from '../shared-styles.js'`, extend `LitElement`, register in `src/index.ts`. Rebuild.
+Adding a `deck-*` element means changing the framework itself, which lives in
+the repository rather than in this package. See
+[CONTRIBUTING](https://gitlab.com/tordu-jardin/rikiki/-/blob/main/CONTRIBUTING.md).
 
-## Build
+## No build step
 
-```bash
-npm install
-npm run build      # node build.mjs (esbuild) + tsc --emitDeclarationOnly
-npm run watch      # esbuild watch mode
-npm run typecheck  # tsc --noEmit
+The published runtime is plain ES modules. Nothing here needs compiling,
+bundling or transpiling to author, serve or present a deck.
+
+## Claude Code skills
+
+The package ships three Claude Code skills so an assistant authoring your deck
+knows the framework: `rikiki-deck` (build a deck), `rikiki-theme` (theming), and
+`rikiki-debug` (diagnose a deck).
+
+```sh
+npx rikiki skills                       # into ./.claude/skills/
+npx rikiki skills --dir ~/.claude/skills   # or once, for every project
 ```
 
-`dist/` is versioned · consumers don't run a build.
+Claude Code discovers them on the next session. Re-run the command with
+`--force` after upgrading the package to pick up skill changes.
 
 ## Reveals & animations
 
@@ -227,8 +291,7 @@ Per-element click-through builds are an opt-in plugin (`installClickStages()` fr
 `dist/click-stages.js`): annotate elements with `data-click`, `data-click-hide`,
 `data-click-auto`, `data-click-stagger`, and `data-morph` (Keynote-style Magic
 Move via View Transitions). Slide transitions are driven by `transition="…"` on
-`<deck-root>`. See `docs/llms/rikiki-reference.md` §7 for the full attribute set,
-and `decks/tests/demo.html` for a runnable feature tour.
+`<deck-root>`. See `docs/llms/rikiki-reference.md` §7 for the full attribute set.
 
 ## Known limits
 

package/bin/lib/assemble.mjs

@@ -0,0 +1,154 @@
+// ════════════════════════════════════════════════════════════════
+// rikiki assemble · build one deck HTML from ordered partials.
+//
+// A long talk is easier to write, review and diff in pieces. This joins them
+// back into the single HTML file everything else in rikiki expects: `bundle`
+// folds it, `export` prints it, a browser serves it.
+//
+// deck.config.{js,json} shape:
+//   export default {
+//     title: 'My talk',
+//     theme: 'rikiki/tokens.css',      // href, relative to the OUTPUT file
+//     bundle: 'rikiki/dist/index.js',  // runtime href, relative to OUTPUT
+//     transition: 'slide',             // optional <deck-root transition="…">
+//     lang: 'fr',                      // optional <html lang="…">
+//     slides: ['parts/cover.html', 'parts/intro.md', 'parts/closing.html'],
+//   };
+//
+// .html partials are inlined verbatim (one or more <deck-*> elements).
+// .md partials become slides · a line that is exactly `---` starts a new one.
+// ════════════════════════════════════════════════════════════════
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, extname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ExpectedError } from './cli-error.mjs';
+
+// What `rikiki init` writes, so an assembled deck bundles like any other.
+const DEFAULT_THEME = 'rikiki/tokens.css';
+const DEFAULT_RUNTIME = 'rikiki/dist/index.js';
+
+const escapeHtml = (s) =>
+  String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/** Split a markdown file into slides on lines that are exactly `---`
+ *  (reveal.js convention). One file, many slides. A blank chunk collapses. */
+function splitMarkdownSlides(body) {
+  const chunks = [];
+  let current = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (/^[ \t]*---[ \t]*$/.test(line)) {
+      chunks.push(current.join('\n'));
+      current = [];
+    } else current.push(line);
+  }
+  chunks.push(current.join('\n'));
+  return chunks.map((c) => c.trim()).filter((c) => c.length > 0);
+}
+
+function renderPartial(absPath) {
+  const body = readFileSync(absPath, 'utf8');
+  if (extname(absPath) !== '.md') return body.trimEnd();
+  // <deck-md> deindents and parses the raw markdown at runtime, so the body is
+  // inlined verbatim. `***` stays available as an in-slide rule.
+  return splitMarkdownSlides(body)
+    .map((slide) => `<deck-feature>\n<deck-md>\n${slide}\n</deck-md>\n</deck-feature>`)
+    .join('\n\n');
+}
+
+async function loadConfig(absPath) {
+  if (!existsSync(absPath) || !statSync(absPath).isFile()) {
+    throw new ExpectedError(`assemble · config not found: ${absPath}`);
+  }
+  if (extname(absPath) === '.json') {
+    try {
+      return JSON.parse(readFileSync(absPath, 'utf8'));
+    } catch (cause) {
+      throw new ExpectedError(`assemble · ${absPath} is not valid JSON · ${cause.message}`);
+    }
+  }
+  try {
+    const mod = await import(pathToFileURL(absPath).href);
+    return mod.default ?? mod;
+  } catch (cause) {
+    // A `.js` file is read as CommonJS or as an ES module depending on the
+    // nearest package.json, and `npm init -y` writes "type": "commonjs". Both
+    // dialects are legitimate here; only the mismatch is worth a message.
+    if (cause?.code === 'ERR_REQUIRE_ESM' || cause instanceof SyntaxError) {
+      throw new ExpectedError(
+        `assemble · ${absPath} looks like an ES module, but the nearest package.json\n` +
+          '  does not declare "type": "module". Use `module.exports = {…}`, rename the\n' +
+          '  file to .mjs, or use a .json config.',
+      );
+    }
+    throw cause;
+  }
+}
+
+/** The default output path: the title, slugged, next to the config. */
+export function defaultOutputPath(configPath, title) {
+  const slug = String(title || 'deck')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+  return resolve(dirname(configPath), (slug || 'deck') + '.html');
+}
+
+/**
+ * Assemble a deck from its config.
+ * @returns {Promise<{ html: string, outputPath: string, slides: number, unbundleable: string[] }>}
+ *          `outputPath` is null when the caller asked for stdout · `unbundleable`
+ *          lists the hrefs `rikiki bundle` will not be able to inline.
+ */
+export async function assembleDeck(configPath, outputPath) {
+  const absConfig = resolve(process.cwd(), configPath);
+  const config = await loadConfig(absConfig);
+  const configDir = dirname(absConfig);
+
+  if (!Array.isArray(config.slides) || config.slides.length === 0) {
+    throw new ExpectedError(`assemble · ${configPath} · \`slides\` must be a non-empty array`);
+  }
+
+  const slidesHtml = config.slides
+    .map((rel) => {
+      const abs = resolve(configDir, rel);
+      if (!existsSync(abs)) throw new ExpectedError(`assemble · partial not found: ${rel}`);
+      return renderPartial(abs);
+    })
+    .join('\n\n');
+
+  const transitionAttr = config.transition ? ` transition="${escapeHtml(config.transition)}"` : '';
+  const html = `<!doctype html>
+<html lang="${escapeHtml(config.lang ?? 'en')}">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${escapeHtml(config.title ?? 'Rikiki deck')}</title>
+<link rel="stylesheet" href="${escapeHtml(config.theme ?? DEFAULT_THEME)}">
+<script type="module" src="${escapeHtml(config.bundle ?? DEFAULT_RUNTIME)}"></script>
+</head>
+<body>
+<deck-root${transitionAttr}>
+${slidesHtml}
+</deck-root>
+</body>
+</html>
+`;
+
+  // A href that does not follow the `rikiki/…` spelling serves fine but will
+  // not inline · saying so here beats a silent surprise at bundle time.
+  const hrefs = [config.theme ?? DEFAULT_THEME, config.bundle ?? DEFAULT_RUNTIME];
+  const unbundleable = hrefs.filter((href) => !/(^|\/)rikiki\//.test(href));
+
+  if (outputPath === '-') {
+    return { html, outputPath: null, slides: config.slides.length, unbundleable };
+  }
+
+  const absOutput = outputPath
+    ? resolve(process.cwd(), outputPath)
+    : defaultOutputPath(absConfig, config.title);
+  mkdirSync(dirname(absOutput), { recursive: true });
+  writeFileSync(absOutput, html);
+  return { html, outputPath: absOutput, slides: config.slides.length, unbundleable };
+}

package/bin/lib/box-geometry.mjs

@@ -0,0 +1,66 @@
+// ════════════════════════════════════════════════════════════════
+// Does a painted box leave its container, or land on top of a sibling?
+//
+// Pure rect arithmetic, kept out of `check.mjs` for the same reason as
+// `graph-hit.mjs`: the answer is the whole diagnostic, so the thresholds
+// belong beside tests that pin them, not scattered through the DOM walk that
+// calls them.
+//
+// The functions are also serialized into the browser by `check.mjs` (see
+// BOX_GEOMETRY_READER), so they must stay self-contained: no imports, no
+// closure over anything in this module.
+// ════════════════════════════════════════════════════════════════
+
+/**
+ * How far `rect` sits outside `container`, per side and at its worst side.
+ *
+ * Only the sides where `rect` actually spills are counted · a box that sits
+ * fully inside its container reports zero on every side, whatever slack it
+ * leaves.
+ */
+export function escapeOf(rect, container) {
+  const sides = {
+    left: Math.max(0, container.left - rect.left),
+    right: Math.max(0, rect.right - container.right),
+    top: Math.max(0, container.top - rect.top),
+    bottom: Math.max(0, rect.bottom - container.bottom),
+  };
+  return { pixels: Math.max(sides.left, sides.right, sides.top, sides.bottom), sides };
+}
+
+/**
+ * How much two rects intersect, on each axis.
+ *
+ * A negative value means the rects do not touch on that axis at all · the
+ * caller compares both axes against its own tolerance rather than this
+ * function deciding what counts as an overlap.
+ */
+export function overlapOf(a, b) {
+  return {
+    x: Math.min(a.right, b.right) - Math.max(a.left, b.left),
+    y: Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top),
+  };
+}
+
+/**
+ * Does `outer` fully contain `inner`, within `tolerance` px on each side?
+ *
+ * The tolerance absorbs sub-pixel layout rounding · two rects that agree to
+ * the pixel should not read as "neither encloses the other".
+ */
+export function encloses(outer, inner, tolerance = 1) {
+  return (
+    outer.left <= inner.left + tolerance &&
+    outer.right >= inner.right - tolerance &&
+    outer.top <= inner.top + tolerance &&
+    outer.bottom >= inner.bottom - tolerance
+  );
+}
+
+/** The same three functions, as source, for `page.evaluate` · the inspector
+ *  runs in the browser and cannot import from here. */
+export const BOX_GEOMETRY_READER = `({
+  escapeOf: ${escapeOf},
+  overlapOf: ${overlapOf},
+  encloses: ${encloses},
+})`;