rikiki-deck 0.7.1 → 0.7.2

package/docs/llms/rikiki-reference.md

@@ -1,6 +1,6 @@
 # Rikiki · LLM reference
 
-This reference documents rikiki v0.7.1.
+This reference documents rikiki v0.7.2.
 
 Exhaustive, self-consistent reference for authoring valid **rikiki** decks. Every
 tag, attribute, slot, and token below was derived from the source in this repo
@@ -227,7 +227,7 @@ Direct children of `<deck-root>`. Each is one slide.
 
 | Tag | Purpose | Key attributes | Slots |
 |-----|---------|----------------|-------|
-| `deck-cover` | Opening slide, dark, with brand + meta | `brand` (split on " · "), `brand-src` (logo URL), `speaker`, `company`, `duration`, `audience`, `runtime`; per-row label overrides `speaker-label`, `company-label`, `duration-label`, `audience-label`, `runtime-label` | default `<h1>`, `.sub`/`p[slot=sub]` |
+| `deck-cover` | Opening slide, dark, with brand + meta | `brand` (split on " · "), `brand-src` (logo URL), `speaker`, `company`, `company-src` (client logo URL, shown before the company name), `duration`, `audience`, `runtime`; per-row label overrides `speaker-label`, `company-label`, `duration-label`, `audience-label`, `runtime-label` | default `<h1>`, `.sub`/`p[slot=sub]` |
 | `deck-section` | Chapter divider (also a chapter boundary for 2D nav) | `num` | default `<h1>` (may use `<em>`) |
 | `deck-feature` | Headline + lead + one focal block | `eyebrow` | `title` (`<h1>`), `lead`, default (focal block, e.g. `deck-code`) |
 | `deck-split` | Two or three columns side by side | `eyebrow`, `cols` (`1-1`/`1-2`/`2-1`/`3`), `gap` (1..6 or raw CSS length), `col-gap` (1..6 or raw CSS length) | `title`, `lead`; `left`/`right` (2-col) or `a`/`b`/`c` (3-col) |
@@ -807,12 +807,18 @@ an `element` path that reaches into the Shadow DOM (`deck-feature#detail
 | `SLIDE_TOP_HEAVY` | warning | measured on the pixels · the ink sits in the top with a dead band under it |
 | `TALK_SHORTER_THAN_ANNOUNCED` | warning | the notes carry far less speech than the cover announces |
 | `TEXT_TOO_SMALL` | warning | below the readable floor once the canvas is scaled |
+| `TEXT_LAST_LINE_ORPHAN` | warning | a block of prose ends on a stub under a quarter of the width above it · measured on the painted lines, headings and short blocks excepted · worst one per slide |
 | `UNKNOWN_ATTRIBUTE` | warning | an attribute the element neither reads nor styles on · the value is dropped |
 | `DUPLICATE_SLIDE_ID` | warning | two slides answer to the same name |
 | `EXTERNAL_DEPENDENCY` | warning | the deck fetches from the network at runtime |
 | `GRAPH_NODE_OUT_OF_BOUNDS` | error | a `deck-node` is painted outside its `deck-graph` canvas · move it inward with `at`, shorten its note, or constrain it with `width` |
 | `GRAPH_EDGE_CROSSES_NODE` | warning | the line a `deck-edge` actually paints, bends and stroke width included, runs over a node it does not connect · move the obstructing node, or route the edge around it |
 | `GRAPH_NODE_OVERLAPS_NODE` | error | two `deck-node` of the same `deck-graph` are painted on top of each other · one of them is unreadable |
+| `GRAPH_NODE_COVERS_LABEL` | error | a `deck-node` is painted over a `deck-group` / `deck-lane` / edge caption · move the node with `at`, or the region with its own `at` |
+| `GRAPH_EDGE_SKEWED` | warning | an edge misses horizontal or vertical by a few pixels · a frank diagonal is left alone, a three-degree slope is a slip · align the two `at` coordinates, or set `route="ortho"` |
+| `GRAPH_NODES_OFF_AXIS` | warning | two nodes sit within the alignment slack of the same row or column without sharing it · worst offender per graph |
+| `GRAPH_NODE_SIZES_MIXED` | warning | two nodes of one row (or column) differ by a few pixels in height (or width) · near-equal boxes read as a failed attempt at the same size, plainly different ones are left alone |
+| `GRAPH_LAYOUT_NOT_SEMANTIC` | warning | every node of a graph of three or more sits on one axis, with no `layout` · the `at` coordinates re-do what `layout="row"` / `layout="column"` says |
 
 The report also carries `notChecked`, which names what was **not** looked at:
 revealed steps, accessibility, wording and facts, other viewports, text inside
@@ -1242,7 +1248,7 @@ Pick one deliberately · they make different promises.
 
 **Served** · the folder as you wrote it. HTML, CSS and JS stay separate files,
 so editing a slide needs no build. ES modules mean it needs a **static HTTP
-server**, not a double-click: `python3 -m http.server`, `npx serve`, anything.
+server**, not a double-click: `npx serve .`, or anything that speaks HTTP.
 Offline once every asset is local.
 
 **Standalone** · one HTML file, produced by `rikiki bundle deck.html out.html`.
@@ -1383,6 +1389,23 @@ script, so a standalone deck keeps them and stays offline. Forget the `<script>`
 and the tag stays an unknown element: it renders its text content, logs nothing,
 and the rest of the deck is unaffected.
 
+**Past about four added modules, stop adding script tags and bundle.** Each
+module is compiled on its own and carries its own copy of the shared code, and
+gzip compresses one large repetitive file far better than several small ones,
+so script tags stop paying off quickly. Measured on this release, gzipped:
+
+| what the deck loads | gzip |
+|---|---|
+| `dist/index.js` alone | 26 KB |
+| `dist/index.js` + 3 modules | 30 KB |
+| `dist/index.js` + 5 modules | 33 KB |
+
+`rikiki bundle` carries only the components the deck actually writes, in one
+file, so it is smaller than the plain bundle for any deck that does not use
+every component · and it is the only option that gets *smaller* as the deck
+gets simpler, rather than larger. Script tags are the convenient path for one
+or two extras, not the cheap one.
+
 Every evidence block below (`deck-csv`, `deck-table`, `deck-bar`,
 `deck-kpi-grid`, `deck-annotate`, and plain prose) takes a `deck-source`
 underneath it for the credit line · `deck-source` is a core atom (§6), not an
@@ -1400,7 +1423,7 @@ authoring paths render identically and cannot drift.
 | `deck-persona` | Who is speaking, or who the case study is about · the portrait block is the inverse surface, so the person has a place on the slide | `name`, `person-role` (**not** `role`), `org`, `context` (the quiet line, gapped away from the identity), `src` (a portrait; initials in inverse ink stand in without one), `on-dark` (the block flips to paper with ink initials), `compact` (shrinks the block and the name together, for a supporting persona), `inline` (name, role and context on one wrapping row) | · |
 | `deck-versus` | A directed comparison as a BLOCK inside a slide (`deck-split` covers the case where the comparison is the whole slide) | `pivot`, `winner` (`left`/`right`), `slide` (make the comparison a deck-root slide of its own, with `title` and `lead` slots), `eyebrow` (context label above the title, slide mode only) | `title`, `lead`, `left`, `right`, `footer` (full width, under both sides, slide mode only; a slotted `deck-callout` keeps its own size) |
 | `deck-flow` / `deck-flow-step` | A chain across the width · numbered stages, and only the active one takes the block | flow: `cols`, `reveal` · stage: `label`, `note` | stage default = extra content |
-| `deck-timeline` / `deck-milestone` | A trajectory in time, on an axis | timeline: `direction` (`row`/`column`), `reveal` · milestone: `date`, `label`, `note`, `tone` | · |
+| `deck-timeline` / `deck-milestone` | A trajectory in time, on an axis | timeline: `direction` (`row`/`column`), `alternate` (row only · milestones alternate above and below the axis, each twice as wide), `reveal` · milestone: `date`, `label`, `note`, `tone` | · |
 | `deck-graph` / `deck-node` / `deck-edge` / `deck-group` / `deck-lane` | Nodes, edges, regions and bands · the primitive behind every boxes-and-arrows slide | graph: `layout` (`free`/`row`/`column`), `reveal` · node: `at` (`x,y` in percent), `label`, `note`, `boxed`, `tone`, `icon`, `width` (an explicit CSS width such as `18ch` or `240px`, so a long label wraps instead of colliding) · edge: `from`, `to`, `label`, `dashed`, `arrow` (`end` default / `start` / `both` / `none`), `route` (`straight` default / `ortho` for right-angle segments), `label-offset` (`x,y` in pixels, moves the label off the line) · each edge publishes the polyline it paints back onto itself as `data-path` (`x1,y1 x2,y2[ ...]`, graph-relative CSS pixels), which is what `rikiki check` reads · group: `at` (`x,y,w,h`), `label`, `solid` · lane: `at` (`top,height`), `label` | node default = extra content |
 | `deck-table` | A hand-authored table with the hierarchy `deck-csv` has · the table stays in your light DOM, so its cells may carry markup | `highlight-rows`, `highlight-cols`, `reveal` | default = your `<table>` |
 | `deck-annotate` | A screenshot the speaker can point at · numbered markers positioned in percent, revealed one per step through the engine's own step mechanism · a real `<figure>`/`<figcaption>`, so it can carry its own caption and source like `deck-figure` | `src`, `alt`, `marks` (`x,y,label` triples separated by `\|`, coordinates in percent), `all-at-once`, `no-legend`, `leader` (draw a line from the target point to a displaced badge), `offset` (`x,y` in pixels, or a named side `above` / `below` / `left` / `right` : the badge is displaced by its own rendered diameter plus `--deck-annotate-anchor-gap` in that direction, and its leader turns on regardless of `leader`), `offsets` (per-mark displacements separated by `\|`, mixing pixel and keyword forms, e.g. `above\|0,-40\|right`; a missing entry falls back to `offset`), `caption`, `source`, `source-href` (turns the credit into a link) | `caption`, `source` |
@@ -1702,3 +1725,7 @@ when a clipping box loses more than a few pixels of content.
 **Too empty is a judgement.** A section title is meant to be sparse. The same
 spec measures how much of the canvas each slide uses and attaches the report to
 the run, without failing · the numbers are advice, and §19 is the answer.
+
+## Presentation previews (0.7.2)
+
+Overview prepares thumbnails incrementally while idle and keeps its grid for reopening. Content or theme changes invalidate the cache. Presenter previews retain their documents and mirror the current slide step, including annotations; the footer reports the current step. Cover layouts display slide numbers unless `no-counter` is set. Custom components can implement `applyStep(step)` to synchronize their reveal state.

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.7.1.
+This reference documents rikiki v0.7.2.
 
 The framework is opinionated:
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "rikiki-deck",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "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>",
+  "author": "Cédric Chariere Fiedler <chariere.fiedler.cedric@gmail.com>",
   "homepage": "https://rikiki.tordu-jardin.fr",
   "repository": {
     "type": "git",
@@ -19,6 +19,10 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./check-api": {
+      "types": "./bin/lib/check-api.d.ts",
+      "import": "./bin/lib/check-api.mjs"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
@@ -44,21 +48,24 @@
     ".claude/skills/rikiki-debug"
   ],
   "scripts": {
-    "build": "node build-vendor.mjs && node build.mjs && node build-standalone.mjs && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "build": "node build-vendor.mjs && node build.mjs && node build-standalone.mjs && node build-types.mjs",
     "vendor": "node build-vendor.mjs",
     "watch": "node build.mjs --watch",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "bundle": "node bundle.mjs",
+    "examples": "node scripts/rebuild-examples.mjs",
+    "readme": "node scripts/build-readme.mjs",
     "deck": "node bin/rikiki.mjs assemble",
     "deck:example": "node bin/rikiki.mjs assemble decks/example/deck.config.js",
     "test": "vitest run",
     "test:e2e": "playwright test",
     "test:smoke": "playwright test --grep @smoke",
     "release:smoke": "node scripts/release-smoke.mjs",
-    "lint": "biome check src scripts",
-    "format": "biome format --write src scripts",
+    "lint": "biome check src scripts tools",
+    "format": "biome format --write src scripts tools",
     "bump": "node scripts/bump-version.mjs",
+    "new:component": "node scripts/new-component.mjs",
     "prepublishOnly": "npm run build && npm test"
   },
   "devDependencies": {
@@ -68,7 +75,7 @@
     "esbuild": "^0.24.0",
     "lit": "^3.3.3",
     "marked": "^12.0.2",
-    "mermaid": "^10.9.6",
+    "mermaid": "^10.9.8",
     "rolldown": "^1.1.1",
     "shiki": "^1.24.0",
     "typescript": "^5.6.0",

package/dist/contrast.js

@@ -1 +0,0 @@
-var R=/^#([0-9a-f])([0-9a-f])([0-9a-f])$/i,E=/^#([0-9a-f])([0-9a-f])([0-9a-f])([0-9a-f])$/i,M=/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i,N=/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i,v=/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?/i,s=n=>parseInt(n.length===1?n+n:n,16);function T(n){if(n===void 0)return;let t=n.endsWith("%")?Number(n.slice(0,-1))/100:Number(n);return Number.isFinite(t)?Math.min(1,Math.max(0,t)):void 0}function A(n){let t=n.trim(),r=t.match(E)??t.match(R);if(r){let[,u,a,i,c]=r;return{r:s(u),g:s(a),b:s(i),...c?{a:s(c)/255}:{}}}let e=t.match(N)??t.match(M);if(e){let[,u,a,i,c]=e;return{r:s(u),g:s(a),b:s(i),...c?{a:s(c)/255}:{}}}let o=t.match(v);if(o){let u=T(o[4]);return{r:Number(o[1]),g:Number(o[2]),b:Number(o[3]),...u===void 0?{}:{a:u}}}return null}function C(n){return n.a===void 0||n.a>=1}function $(n,t){if(!C(t))throw new Error("flatten: the backdrop must be opaque");let r=n.a??1;return{r:n.r*r+t.r*(1-r),g:n.g*r+t.g*(1-r),b:n.b*r+t.b*(1-r)}}var b=n=>{let t=n/255;return t<=.03928?t/12.92:((t+.055)/1.055)**2.4};function m({r:n,g:t,b:r}){return .2126*b(n)+.7152*b(t)+.0722*b(r)}function w(n,t){let r=m(n),e=m(t),[o,u]=r>=e?[r,e]:[e,r];return(o+.05)/(u+.05)}function d({r:n,g:t,b:r}){let[e,o,u]=[b(n),b(t),b(r)],a=(e*.4124+o*.3576+u*.1805)/.95047,i=e*.2126+o*.7152+u*.0722,c=(e*.0193+o*.1192+u*.9505)/1.08883,f=g=>g>.008856?Math.cbrt(g):7.787*g+16/116,[h,l,x]=[f(a),f(i),f(c)];return[116*l-16,500*(h-l),200*(l-x)]}function H(n,t){let[r,e,o]=d(n),[u,a,i]=d(t);return Math.hypot(r-u,e-a,o-i)}var S=10;function X(n){let t=new Map,r=n.replace(/\/\*[\s\S]*?\*\//g,"");for(let e of r.matchAll(/(--[\w-]+)\s*:\s*([^;{}]+);/g))t.set(e[1],e[2].trim());return t}function p(n,t,r=new Set){if(r.has(t))return null;r.add(t);let e=n.get(t);if(e===void 0)return null;let o=e.match(/^var\(\s*(--[\w-]+)\s*(?:,\s*([^)]*))?\)$/);if(!o)return e;let u=p(n,o[1],r);return u!==null?u:o[2]?o[2].trim():null}function _(n,t){let r=p(n,t);return r===null?null:A(r)}var k={normalText:4.5,largeText:3,uiComponent:3};export{S as DELTA_E_DISTINCT,k as WCAG_AA,w as contrastRatio,H as deltaE,$ as flatten,C as isOpaque,A as parseColor,X as readTokens,m as relativeLuminance,_ as resolveColor,p as resolveToken};

package/dist/shared/contrast.d.ts

@@ -1,52 +0,0 @@
-export interface Rgb {
-    r: number;
-    g: number;
-    b: number;
-    /** 0 to 1 · absent means fully opaque. A translucent color has NO contrast
-     *  ratio of its own, only one against a named backdrop · see flatten(). */
-    a?: number;
-}
-/** Parse `#abc`, `#abcd`, `#aabbcc`, `#aabbccdd`, `rgb(…)` or `rgba(…)` ·
- *  null for anything else. Alpha is CARRIED, not dropped: a value read as
- *  opaque when it is not turns a 1.1 contrast into a 20 and makes any guard
- *  built on it a lie. */
-export declare function parseColor(value: string): Rgb | null;
-/** True when the color is fully opaque, so it has a luminance of its own. */
-export declare function isOpaque(color: Rgb): boolean;
-/** Composite `fg` over `bg` (source-over) · the color the eye actually sees.
- *  `bg` must be opaque; a translucent backdrop has no single answer. */
-export declare function flatten(fg: Rgb, bg: Rgb): Rgb;
-/** WCAG 2.1 relative luminance, 0 (black) to 1 (white). */
-export declare function relativeLuminance({ r, g, b }: Rgb): number;
-/** WCAG 2.1 contrast ratio between two colors · 1 to 21, order-independent. */
-export declare function contrastRatio(a: Rgb, b: Rgb): number;
-/**
- * CIE76 colour difference between two opaque colours.
- *
- * WHY THIS EXISTS ALONGSIDE contrastRatio · the WCAG ratio is luminance only,
- * so it cannot tell a saturated accent from the paper it sits on: the mango
- * accent scores 1.48 against the siliceum page and is nonetheless one of the
- * most visible things on the slide. Judging a SURFACE by luminance alone would
- * condemn every colour-coded tile and miss none of the grey ones. A surface is
- * distinguishable when it wins on either axis.
- *
- * The threshold used across this repo is DELTA_E_DISTINCT, below.
- */
-export declare function deltaE(a: Rgb, b: Rgb): number;
-/** Clearly perceptible between two large adjacent areas · the easiest case for
- *  the eye, and the one a slide always presents. Not a taste threshold. */
-export declare const DELTA_E_DISTINCT = 10;
-/** Collect every `--name: value;` declaration in a stylesheet · later
- *  declarations win, matching the cascade for a single theme file. */
-export declare function readTokens(css: string): Map<string, string>;
-/** Follow a `var(--a, fallback)` chain down to a literal color.
- *  Returns null on an unresolvable or cyclic reference. */
-export declare function resolveToken(tokens: Map<string, string>, name: string, seen?: Set<string>): string | null;
-/** Resolve a token straight to RGB · null when it is missing or not a color. */
-export declare function resolveColor(tokens: Map<string, string>, name: string): Rgb | null;
-/** WCAG 2.1 minimum ratios. Large text is >= 24px, or >= 18.66px bold. */
-export declare const WCAG_AA: {
-    readonly normalText: 4.5;
-    readonly largeText: 3;
-    readonly uiComponent: 3;
-};