rikiki-deck 0.4.0 → 0.6.0

package/docs/llms/rikiki-reference.md

@@ -1,6 +1,6 @@
 # Rikiki · LLM reference
 
-This reference documents rikiki v0.4.0.
+This reference documents rikiki v0.6.0.
 
 Exhaustive, self-consistent reference for authoring valid **rikiki** decks. Every
 tag, attribute, slot, and token below was derived from the source in this repo
@@ -107,7 +107,9 @@ debounce, discreet chevrons sit bottom-right (2D-aware), and mouse
 back/forward buttons map to back/advance. The wheel yields to scrollable
 content: a wheel over an overflowing descendant (a tall `deck-code` block, a
 zoomable inline `<svg>`, …) scrolls it natively and only advances the deck once
-that element reaches its scroll edge. The bottom-left key-hint chips
+that element reaches its scroll edge. **Ctrl/⌘ + wheel and trackpad pinch zoom
+the slide** (see Slide zoom below); set `no-zoom` to leave zoom to the browser.
+The bottom-left key-hint chips
 (`← → O P ?`) are also clickable shortcuts for the matching action. Interactive
 elements (`a`, `button`, inputs, `[contenteditable]`) never trigger navigation;
 add `data-no-advance` to opt any element out. Configure with the `mouse-nav`
@@ -129,10 +131,58 @@ Chevron styling tokens: `--deck-root-nav-color`, `--deck-root-nav-bg`,
 | `nav` | `2d` | Opt into 2D (chapter/slide) navigation · see above |
 | `mouse-nav` | *(absent)* / `none` / subset of `click wheel arrows aux` | Mouse navigation config · see above |
 | `transition` | `slide` (default-ish) / `slide-up` / `slide-down` / `slide-right` / `fade` / `zoom` / `flip` | Deck-wide slide transition (see table below) |
+| `fluid` | *(boolean)* | Fluid rendering · the deck fills its box and reflows like a web page (no logical canvas, no zoom-to-fit scale, no letterbox). Default is zoom-to-fit · see Rendering & sizing below. Also accepted **per slide** · see below |
+| `width` / `height` | integers (default `1920` / `1080`) | Logical canvas size for zoom-to-fit · only the aspect ratio and the rem baseline depend on these. Ignored in `fluid` mode |
+| `no-hint` | *(boolean)* | Hide the bottom-left key-hint chips (`← → · O · P · ?`) |
+| `no-arrows` | *(boolean)* | Hide the bottom-right on-screen navigation chevrons |
+| `no-zoom` | *(boolean)* | Disable slide zoom (Ctrl/⌘+wheel, pinch, `+`/`-`/`0`) · on by default; restores the browser's own zoom |
+| `no-counter` | *(boolean)* | Hide the slide counter (it is already hidden on cover, overview and blank screens) |
+| `preview` | *(boolean)* | Inert mode · render and letterbox the deck but wire no input, autoplay or presenter handlers. Used internally by the presenter's Current preview as a control surface; rarely set by hand |
 | `autoplay` | integer ms (e.g. `8000`) | Auto-advance every N ms; pauses on hover, resets on any manual nav. `0`/absent = off |
 | `loop` | *(boolean)* | With `autoplay`, wraps from the last slide back to the first |
 | `swipe` | *(boolean)* | Pointer-driven horizontal swipe (touch + mouse): a swipe ≥ 60 px advances / goes back |
 
+In presenter mode (`P`) the projected (main) window auto-hides its hint chips
+and nav arrows while the speaker popup is open · `no-hint` / `no-arrows` stay
+useful for a clean look outside presenter mode (and for embedded thumbnails).
+
+**Rendering & sizing.** By default a deck renders into a fixed logical canvas
+(`width`×`height`, 1920×1080 by default) scaled uniformly to fit the host box,
+so a slide's layout is identical at any window size and the deck is letterboxed
+when the aspect differs. Set `fluid` to opt out: the deck then fills its box and
+reflows like a web page. Either mode is embed-safe · a `<deck-root>` placed
+inside a larger document scales to (or fills) its own container and never
+touches the host page's scroll or typography.
+
+**Per-slide fluid escape.** A single slide can opt out of the fixed canvas by
+carrying its own `fluid` attribute · while that slide is active the deck drops
+the zoom-to-fit scale and letterbox and gives the slide the real viewport (the
+rem baseline tracks the viewport too), then restores the canvas on navigation
+back to a fixed slide. Use it for one slide that embeds a live interactive demo
+(an `<iframe>` playground, a mini-game) which should consume the whole screen
+while the rest of the deck stays on the predictable fixed canvas:
+
+```html
+<deck-root>
+  <deck-feature><h1 slot="title">Regular fixed slide</h1></deck-feature>
+  <deck-feature fluid>
+    <iframe src="playground.html" style="position:fixed; inset:0; border:0;"></iframe>
+  </deck-feature>
+</deck-root>
+```
+
+(A deck-wide `fluid` already makes every slide fluid · the per-slide attribute
+is only meaningful inside an otherwise fixed deck.)
+
+**Slide zoom.** On by default in fixed-canvas mode: Ctrl/⌘ + wheel (and trackpad
+pinch) magnify the active slide around the cursor; `+`/`-` zoom by steps and `0`
+resets to fit. While magnified, a plain wheel and pointer drag pan the slide, and
+slide navigation snaps back to fit. Because it scales the whole stage uniformly,
+fonts and layout grow together (no reflow) · this is also how to "make the fonts
+bigger". Zoom is a no-op in `fluid` mode (nothing fixed to magnify), in overview,
+and with `no-zoom`. It is local to the projected window (not mirrored into the
+presenter popup).
+
 **Transition values** (deck-wide via `transition="…"` on `<deck-root>`, or
 per-slide via `data-transition="…"` on a slide host). When unset, the effective
 default is `fade`:
@@ -221,22 +271,30 @@ Direct children of `<deck-root>`. Each is one slide.
 
 ### deck-code details
 
-- `lang` · drives highlighting: `js` / `ts` / `json` (default), `html` / `xml` /
-  `svg`, `css` / `scss` / `less`.
+- `lang` · drives highlighting. The **built-in highlighter understands only**
+  `js` / `ts` / `json` (default), `html` / `xml` / `svg`, and `css` / `scss` /
+  `less`. **Any other value** (`python`, `rust`, `bash`, `go`, `sql`, …) is **not
+  an error and produces no warning** — the block is silently colored with the JS
+  rules, so the result looks plausible but is wrong. For any language outside the
+  list above, install the Shiki plugin (see below); it adds Shiki's full set of
+  grammars and is the only way to highlight non-built-in languages correctly.
 - `hero` · centers the block vertically as the slide's focal element.
 - `nested` · lighter border, no shadow (for use inside a `deck-card`).
 - `step-groups` · a JSON array attribute that turns the snippet into a stepped
   reveal; the number of groups becomes the slide's step count (see §7).
 
 Highlighting is done client-side with a built-in regex highlighter (no build
-step). An opt-in **Shiki plugin** can upgrade every `deck-code` block to
-Shiki's grammars/themes.
+step), limited to the languages listed under `lang` above. An opt-in **Shiki
+plugin** upgrades every `deck-code` block to Shiki's full grammar/theme set —
+**required** whenever a deck uses a language the built-in highlighter does not
+understand.
 
 ### Shiki plugin (optional, opt-in)
 
 `src/plugins/shiki.ts` (`dist/shiki.js`) re-renders all `<deck-code>` blocks
-through [Shiki](https://shiki.style), loaded from a CDN on first use. Install it
-after the rikiki bundle:
+through [Shiki](https://shiki.style), loaded from the vendored
+`dist/vendor/shiki.js` bundle on first use (offline · no CDN). Install it after
+the rikiki bundle:
 
 ```html
 <script type="module" src="./dist/index.js"></script>
@@ -252,19 +310,23 @@ API:
 async function installShiki(opts?: {
   theme?: string;    // any Shiki theme name (https://shiki.style/themes) · default 'one-dark-pro'
   langs?: string[];  // grammars to preload · default ['ts', 'js', 'html', 'css', 'json']
-  cdn?: string;      // CDN base to load Shiki from · default 'https://esm.sh/'
 }): Promise<void>
 ```
 
 - Any Shiki theme/language works (not just the built-in highlighter's set); set
   `langs` to whatever your deck uses.
-- Shiki's inline token colors are stripped so the deck's `--rik-code__syntax-*`
-  tokens still theme the output.
+- Shiki owns the palette under this plugin: it colors each token with an inline
+  style from the chosen `theme`, so pick a `theme` that suits your code
+  background (e.g. `one-dark-pro` on a dark deck). The `--deck-code-syntax-*`
+  tokens only affect the built-in highlighter, not Shiki output.
 - A language not loaded falls back silently to the built-in regex highlighter
   (no error).
-- **Trade-off:** pulls ~300 KB of Shiki + requested grammars from the CDN. That
-  is why it is opt-in · the core bundle stays ~12 KB gzip. Use `cdn` to point at
-  a self-hosted mirror.
+- **How it hooks in:** it registers a highlighter on the shared `<deck-code>`
+  class via `setDeckCodeHighlighter` (resolved through `customElements.get`), so
+  it never patches the component's internals · see *Writing a plugin* below.
+- **Trade-off:** the vendored Shiki bundle is large (every grammar + theme, JS
+  engine, no wasm). That is why it is opt-in and lazy · the core bundle stays
+  ~14 KB gzip.
 
 ---
 
@@ -333,9 +395,11 @@ Morph pairs that swap on the same click need explicit steps
 (`data-click-hide="1"` on the outgoing element, `data-click="1"` on the
 incoming one) · bare attributes would put them on two sequential clicks.
 
-The plugin patches `deck-root` so its step counter accounts for `[data-click]`
-elements, and stepping toggles their visibility. Going back cancels pending
-auto/stagger timers. Deep links and back-navigation settle instantly (no
+The plugin registers on each `<deck-root>` through the plugin hook API (see
+*Writing a plugin* below): its `steps` hook makes the step counter account for
+`[data-click]` elements, its `applyStep` hook toggles their visibility, and its
+`navigate` hook wraps cross-slide `data-morph` transitions. Going back cancels
+pending auto/stagger timers. Deep links and back-navigation settle instantly (no
 replayed delays). It respects `prefers-reduced-motion`. When a `data-morph`
 navigation runs, the deck-wide `transition="…"` animation is skipped for that
 navigation so the two don't fight, and pending auto/stagger reveals start
@@ -343,6 +407,42 @@ once the morph settles instead of firing mid-transition. On auto/stagger
 elements, `data-anim-delay` is folded into the timer (delays add up once,
 they don't apply twice).
 
+### Writing a plugin (the hook API)
+
+Both opt-in plugins extend the deck through a small **public** contract rather
+than reaching into engine internals. A plugin is a `DeckPlugin` object; register
+it on a deck instance with `deckRoot.use(plugin)`, which returns an unregister
+function.
+
+```ts
+import type { DeckPlugin } from './dist/index.js';
+
+const myPlugin: DeckPlugin = {
+  name: 'my-plugin',                          // unique · use() is idempotent by name
+  setup(ctx) { /* … */ return () => {}; },    // on register · optional teardown
+  steps(slide, ctx) { return 0; },            // contribute step count (combined as a max)
+  applyStep(step, slide, ctx) { /* … */ },    // after the engine applied the step
+  navigate(to, ctx, proceed) { return false; }, // around-advice · call proceed() to navigate
+};
+document.querySelector('deck-root').use(myPlugin);
+```
+
+The `ctx` (`DeckContext`) is the only surface a plugin touches:
+`ctx.host` (the element), `ctx.current`, `ctx.step`, `ctx.slides`,
+`ctx.requestUpdate()`. Notes:
+
+- **`navigate` is around-advice** · return a truthy value to take ownership and
+  call `proceed()` yourself (e.g. inside a `startViewTransition`); return falsy
+  to let the engine navigate. Only the **first** registered plugin with a
+  `navigate` hook owns navigation (a second one warns and is ignored).
+- **`steps` from all plugins are combined with the engine's own as a maximum.**
+- **`<deck-code>` highlighting** is a separate hook: `setDeckCodeHighlighter(fn)`
+  registers a `(code, lang) => string | null` highlighter on the shared
+  `<deck-code>` class (return `null` to fall back to the built-in regex one).
+- `installClickStages()` / `installShiki()` are **back-compat shims** that attach
+  the plugin to every `<deck-root>` already on the page · a deck created
+  dynamically *after* the call must register the plugin itself with `use()`.
+
 ---
 
 ## 8 · Presenter mode
@@ -351,6 +451,28 @@ Press **`P`** to open a speaker window. It mirrors the current slide and the
 next slide (rendered live via the rikiki bundle), shows a timer/clock, and
 displays the speaker notes for the current slide.
 
+On a Chromium browser with a second screen, pressing **`P`** sends the **deck
+fullscreen to the external screen** (the projector) and opens the **speaker
+window on the speaker's current screen** · the audience gets the slides, the
+speaker keeps the presenter view on their laptop. The deck fullscreen is
+released when the presenter closes. Without the Window Management API
+(Firefox/Safari), the permission, or a second screen, the deck stays in its
+window and the popup uses the default placement.
+
+Notes on the first use: the **first** `P` press prompts for the Window
+Management permission; the speaker window always opens regardless (it is never
+blocked on the prompt). The slides move to the projector as soon as the screen
+layout is known · because that layout is only available after the permission is
+granted, the very first time may take a second `P` press (close + reopen) before
+the slides go fullscreen; afterwards it happens on the press itself (the cached
+layout lets the fullscreen ride the keypress activation, and `window.open`
+relies on popups being allowed for the origin · which the presenter already
+requires). The Current/Next previews are constrained to a 16:9 box so the
+thumbnail matches the projected slide's geometry regardless of the window shape.
+While the speaker window is open, the projected deck auto-hides its key-hint
+chips and nav arrows (the same effect as `no-hint` / `no-arrows`), restoring
+them on close.
+
 Speaker notes live in a `<deck-notes>` element placed inside any slide host.
 It is hidden in the deck itself; only the presenter window reads its text.
 

package/llms.txt

@@ -5,7 +5,7 @@
 > stylesheet, then the component bundle, then write a `<deck-root>` wrapping
 > `deck-*` slide elements. No build step to author or run a deck.
 
-This reference documents rikiki v0.4.0.
+This reference documents rikiki v0.6.0.
 
 The framework is opinionated:
 
@@ -33,9 +33,11 @@ Authoring tags fall into four buckets (see the reference for the exhaustive attr
 ## Plugins (opt-in, lazy)
 
 - **Transitions**: `transition="slide|slide-up|slide-down|slide-right|fade|zoom|flip"` on `<deck-root>` (per-slide `data-transition`).
-- **Presenter window**: press `P` · mirrors current + next slide, timer, and `<deck-notes>`.
-- **Shiki highlighting**: `import { installShiki } from './dist/shiki.js'` then `await installShiki({ theme, langs })`.
+- **Presenter window**: press `P` · mirrors current + next slide, timer, and `<deck-notes>`. With a second screen it sends the slides fullscreen to the projector and keeps the presenter view on the speaker's screen; previews are 16:9; the projected deck auto-hides its chrome while it's open.
+- **Shiki highlighting**: the built-in `deck-code` highlighter only knows js/ts/json/html/xml/svg/css/scss/less; any other `lang` is silently colored as JS (no error). For any other language, install Shiki **after** `dist/index.js`: `import { installShiki } from './dist/shiki.js'` then `await installShiki({ theme, langs })` (list every language the deck uses in `langs`).
 - **Click-stages**: `import { installClickStages } from './dist/click-stages.js'` then `installClickStages()` · per-element `data-click` / `data-anim` / `data-morph` reveals.
+- **Slide zoom**: Ctrl/⌘+wheel / pinch / `+`/`-`/`0` magnify a slide (fixed canvas, on by default, pan by drag/wheel); `no-zoom` on `<deck-root>` opts out.
+- **Writing a plugin**: `deckRoot.use(plugin)` with a `DeckPlugin` (`steps` / `applyStep` / `navigate` / `setup` hooks); `setDeckCodeHighlighter(fn)` overrides `<deck-code>` highlighting. Both re-exported from `dist/index.js`. `installShiki` / `installClickStages` are back-compat shims.
 - **Livereload (authoring only)**: append `?live` to the deck URL.
 
 ## Build & assembly

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "rikiki-deck",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A tiny Lit Web Components framework for technical presentations · zero-build for consumers, TypeScript for contributors.",
+  "author": "Cédric Chariere Fiedler <cedric@siliceum.com>",
   "homepage": "https://rikiki.tordu-jardin.fr",
   "repository": {
     "type": "git",
@@ -36,10 +37,13 @@
     "fonts",
     "README.md",
     "llms.txt",
-    "docs/llms"
+    "docs/llms",
+    ".claude/skills/rikiki-deck",
+    ".claude/skills/rikiki-theme",
+    ".claude/skills/rikiki-debug"
   ],
   "scripts": {
-    "build": "node build-vendor.mjs && node build.mjs && node build-standalone.mjs && tsc --emitDeclarationOnly",
+    "build": "node build-vendor.mjs && node build.mjs && node build-standalone.mjs && tsc --emitDeclarationOnly -p tsconfig.build.json",
     "vendor": "node build-vendor.mjs",
     "watch": "node build.mjs --watch",
     "typecheck": "tsc --noEmit",
@@ -48,9 +52,16 @@
     "deck": "node build/vite-deck.mjs",
     "deck:example": "node build/vite-deck.mjs decks/example/deck.config.js",
     "test": "vitest run",
-    "bump": "node scripts/bump-version.mjs"
+    "test:e2e": "playwright test",
+    "test:smoke": "playwright test --grep @smoke",
+    "lint": "biome check src scripts",
+    "format": "biome format --write src scripts",
+    "bump": "node scripts/bump-version.mjs",
+    "prepublishOnly": "npm run build && npm test"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@playwright/test": "^1.60.0",
     "esbuild": "^0.24.0",
     "lit": "^3.3.3",
     "marked": "^12.0.2",

package/themes/rikiki.css

@@ -177,7 +177,8 @@
   --rik-font-mono:                    'Space Mono', 'JetBrains Mono', ui-monospace, monospace;
 
   /* Typography · body scale · modular ratio 1.25 (major third) from 1rem.
-     html root-size is `clamp(14px, 2.35vh, 42px)` so rems scale with viewport.
+     html root-size is constant (`canvas-h × 0.0235` ≈ 25px); the deck-root
+     transform scales the whole canvas to fit, so rems never touch the viewport.
      New `--rik-text-*` aliases follow a documented t-shirt scale; the
      historical `--rik-font-size-*` names map to the same values for back-compat. */
   --rik-text-2xs:                     0.64rem;     /* 1 / 1.25^2 */
@@ -196,10 +197,10 @@
      order is now monotonic (strong < big < mega < hook < stat). */
   --rik-font-size-xs:                 var(--rik-text-2xs);
   --rik-font-size-sm:                 var(--rik-text-xs);
-  --rik-font-size-body:               0.92rem;     /* between -xs and -sm */
-  --rik-font-size-lead:               var(--rik-text-sm);
-  --rik-font-size-h2:                 var(--rik-text-base);
-  --rik-font-size-h1:                 var(--rik-text-md);
+  --rik-font-size-body:               var(--rik-text-base);  /* ≈32px · sized for projection */
+  --rik-font-size-lead:               var(--rik-text-md);
+  --rik-font-size-h2:                 var(--rik-text-md);
+  --rik-font-size-h1:                 var(--rik-text-lg);
   --rik-font-size-section:            var(--rik-text-lg);
   --rik-font-size-display:            var(--rik-text-xl);
   --rik-font-size-mono:               0.88rem;
@@ -277,14 +278,10 @@
 *, *::before, *::after { box-sizing: border-box; }
 body, h1, h2, h3, h4, p, ul, ol, li, blockquote, pre, table, td, th,
 figure, dl, dd { margin: 0; padding: 0; }
-html { font-size: clamp(14px, 2.35vh, 42px); }
-/* Fixed-viewport decks (<deck-root fixed>) anchor the root font-size to the
-   logical canvas height instead of the window, so every rem-based size scales
-   with the letterboxed stage rather than the screen · no reflow off-ratio. */
-html:has(deck-root[fixed]) {
-  font-size: calc(min(100vh, 100vw * var(--deck-canvas-h, 1080) / var(--deck-canvas-w, 1920)) * 0.0235);
-}
-html, body { width: 100%; height: 100%; overflow: hidden; background: var(--rik-surface-page); }
+/* The rem baseline and the no-scroll reset are injected globally by deck-root
+   (theme-independent · see _injectGlobals). The theme only owns the page surface
+   and the type below. */
+html, body { background: var(--rik-surface-page); }
 body { font-family: var(--rik-font-sans); color: var(--rik-text-default); }
 
 ::selection { background: var(--rik-selection__bg); color: var(--rik-selection__text); }

package/themes/siliceum.css

@@ -164,10 +164,12 @@
 
   --rik-font-size-xs:                 var(--rik-text-2xs);
   --rik-font-size-sm:                 var(--rik-text-xs);
-  --rik-font-size-body:               0.92rem;
-  --rik-font-size-lead:               var(--rik-text-sm);
-  --rik-font-size-h2:                 var(--rik-text-base);
-  --rik-font-size-h1:                 var(--rik-text-md);
+  /* Slide body sized for projection (≈32px on the 1080 canvas) · the headings
+     step up with it so the hierarchy (incl. markdown ## → h2) stays above body. */
+  --rik-font-size-body:               var(--rik-text-base);
+  --rik-font-size-lead:               var(--rik-text-md);
+  --rik-font-size-h2:                 var(--rik-text-md);
+  --rik-font-size-h1:                 var(--rik-text-lg);
   --rik-font-size-section:            var(--rik-text-lg);
   --rik-font-size-display:            var(--rik-text-xl);
   --rik-font-size-mono:               0.88rem;
@@ -236,14 +238,10 @@
 *, *::before, *::after { box-sizing: border-box; }
 body, h1, h2, h3, h4, p, ul, ol, li, blockquote, pre, table, td, th,
 figure, dl, dd { margin: 0; padding: 0; }
-html { font-size: clamp(14px, 2.35vh, 42px); }
-/* Fixed-viewport decks (<deck-root fixed>) anchor the root font-size to the
-   logical canvas height instead of the window, so every rem-based size scales
-   with the letterboxed stage rather than the screen · no reflow off-ratio. */
-html:has(deck-root[fixed]) {
-  font-size: calc(min(100vh, 100vw * var(--deck-canvas-h, 1080) / var(--deck-canvas-w, 1920)) * 0.0235);
-}
-html, body { width: 100%; height: 100%; overflow: hidden; background: var(--rik-surface-page); }
+/* The rem baseline and the no-scroll reset are injected globally by deck-root
+   (theme-independent · see _injectGlobals). The theme only owns the page surface
+   and the type below. */
+html, body { background: var(--rik-surface-page); }
 body { font-family: var(--rik-font-sans); color: var(--rik-text-default); }
 
 ::selection { background: var(--rik-selection__bg); color: var(--rik-selection__text); }