@aivorynet/slaide 1.0.3 → 1.0.4

package/dist/render/css.js

@@ -161,7 +161,10 @@ body{
   background:rgba(0,0,0,.3);color:#fff;opacity:.26;cursor:pointer;font:16px/1 var(--font-sans,system-ui);
   display:grid;place-items:center;backdrop-filter:blur(6px);transition:opacity .2s;}
 .sl-present-toggle:hover{opacity:.85;}
-body.sl-presenting .sl-present-toggle,body.sl-presenting .sl-counter{opacity:0;pointer-events:none;}
+body.sl-presenting .sl-present-toggle,body.slv-presenting .sl-present-toggle,
+body.sl-presenting .sl-counter,body.slv-presenting .sl-counter,
+body.sl-presenting .sl-progress,body.slv-presenting .sl-progress{opacity:0;pointer-events:none;}
+body.sl-presenting .sl-stage,body.slv-presenting .sl-stage{box-shadow:none;}
 @media print{.sl-present-toggle{display:none;}}
 
 /* ---- builds + transitions live in anim.ts (appended to BASE_CSS below) ---- */
@@ -170,7 +173,7 @@ body.sl-presenting .sl-present-toggle,body.sl-presenting .sl-counter{opacity:0;p
 .sl-progress{position:fixed;left:0;bottom:0;height:3px;background:var(--color-accent,#6cf);width:0;z-index:50;transition:width .3s ease;}
 .sl-counter{position:fixed;right:14px;bottom:12px;font:600 13px/1 var(--font-sans,system-ui);color:#fff;opacity:.35;z-index:50;background:rgba(0,0,0,.3);padding:5px 9px;border-radius:20px;backdrop-filter:blur(6px);}
 .sl-counter:hover{opacity:.8;}
-.sl-notes{position:fixed;left:0;right:0;bottom:0;max-height:38vh;overflow:auto;background:rgba(10,10,16,.94);color:#ddd;padding:16px 22px;font:15px/1.6 var(--font-sans,system-ui);z-index:60;border-top:2px solid var(--color-accent,#6cf);display:none;}
+.sl-notes{position:fixed;left:var(--sl-dock-left,0px);right:var(--sl-dock-right,0px);bottom:var(--sl-dock-bottom,0px);height:180px;overflow:auto;background:rgba(10,10,16,.94);color:#ddd;padding:16px 22px;font:15px/1.6 var(--font-sans,system-ui);z-index:60;border-top:2px solid var(--color-accent,#6cf);display:none;box-sizing:border-box;}
 .sl-notes.sl-open{display:block;}
 .sl-help{position:fixed;inset:0;display:none;place-items:center;background:rgba(5,5,10,.82);z-index:70;}
 .sl-help.sl-open{display:grid;}

package/dist/render/css.js.map

@@ -1 +1 @@
-{"version":3,"file":"css.js","sourceRoot":"","sources":["../../src/render/css.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE1E,MAAM,UAAU,QAAQ,CAAC,EAAU;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzE,OAAO,WAAW,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,MAAM,CAAC,KAAK,qBAAqB,EAAE,CAAC,MAAM,CAAC,MAAM,0BAA0B,EAAE,CAAC,WAAW,CAAC,QAAQ,QAAQ,CAAC;AACpK,CAAC;AAED,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6KlB,CAAC;AAEF,qFAAqF;AACrF,gFAAgF;AAChF,MAAM,CAAC,MAAM,QAAQ,GAAG,UAAU,GAAG,IAAI,GAAG,YAAY,EAAE,GAAG,IAAI,GAAG,WAAW,EAAE,GAAG,IAAI,GAAG,kBAAkB,EAAE,CAAC"}
+{"version":3,"file":"css.js","sourceRoot":"","sources":["../../src/render/css.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE1E,MAAM,UAAU,QAAQ,CAAC,EAAU;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzE,OAAO,WAAW,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,MAAM,CAAC,KAAK,qBAAqB,EAAE,CAAC,MAAM,CAAC,MAAM,0BAA0B,EAAE,CAAC,WAAW,CAAC,QAAQ,QAAQ,CAAC;AACpK,CAAC;AAED,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgLlB,CAAC;AAEF,qFAAqF;AACrF,gFAAgF;AAChF,MAAM,CAAC,MAAM,QAAQ,GAAG,UAAU,GAAG,IAAI,GAAG,YAAY,EAAE,GAAG,IAAI,GAAG,WAAW,EAAE,GAAG,IAAI,GAAG,kBAAkB,EAAE,CAAC"}

package/dist/render/runtime.js

@@ -40,20 +40,20 @@ export const RUNTIME_JS = String.raw `
     panX = Math.max(-ox, Math.min(ox, panX));
     panY = Math.max(-oy, Math.min(oy, panY));
   }
-  // Docked panels (a left slide navigator, an optional right side panel) reserve gutters
-  // via the --sl-dock-left / --sl-dock-right CSS vars; the stage centers in the *remaining*
-  // width and shifts right by the left gutter. 0 (unset) means full-bleed, as before.
-  function dockVar(name){
-    var v = getComputedStyle(document.documentElement).getPropertyValue(name);
-    var n = parseFloat(v); return isFinite(n) ? n : 0;
-  }
+  function cssVar(cs, name){ var n = parseFloat(cs.getPropertyValue(name)); return isFinite(n) ? n : 0; }
   function scale(){
-    var dl = dockVar('--sl-dock-left'), dr = dockVar('--sl-dock-right');
-    var vw = window.innerWidth - dl - dr, vh = window.innerHeight;
+    var pres = isPresenting();
+    var cs = getComputedStyle(document.documentElement);
+    var dl = pres ? 0 : cssVar(cs,'--sl-dock-left'), dr = pres ? 0 : cssVar(cs,'--sl-dock-right');
+    var dt = pres ? 0 : cssVar(cs,'--sl-dock-top');
+    // Bottom dock = chrome dock (bstrip/filmstrip, absolute) + notes reservation (independent), so
+    // the two writers never clobber each other. .sl-notes sits at --sl-dock-bottom (above the chrome).
+    var db = pres ? 0 : cssVar(cs,'--sl-dock-bottom') + cssVar(cs,'--sl-dock-notes');
+    var vw = window.innerWidth - dl - dr, vh = window.innerHeight - dt - db;
     var fit = Math.min(vw/CW, vh/CH);
     var s = fit * zoomFactor;
     if(zoomFactor<=1){ panX = panY = 0; } else { clampPan(s, vw, vh); }
-    var tx = dl + (vw - CW*s)/2 + panX, ty = (vh - CH*s)/2 + panY;
+    var tx = dl + (vw - CW*s)/2 + panX, ty = dt + (vh - CH*s)/2 + panY;
     stage.style.transform = 'translate('+tx+'px,'+ty+'px) scale('+s+')';
   }
 
@@ -142,6 +142,27 @@ export const RUNTIME_JS = String.raw `
   }
 
   function toggle(sel){ var e=document.querySelector(sel); if(e) e.classList.toggle('sl-open'); updateChrome(); }
+  var NOTES_H = 180;
+  // Dock the notes panel BENEATH the slide (not floating over it). The panel is a fixed sibling;
+  // it reserves its own space via the INDEPENDENT --sl-dock-notes var (summed into the stage fit by
+  // scale()), and anchors at --sl-dock-bottom so it sits flush above the chrome dock (the editor
+  // filmstrip, or nothing). Keeping notes' reservation separate from --sl-dock-bottom means the
+  // bstrip's absolute writes and the notes' toggle never clobber each other (no overlap on toggle).
+  function setNotesOpen(open){
+    var np = document.querySelector('.sl-notes');
+    if(!np) return;
+    if(open === np.classList.contains('sl-open')) return;   // already in the requested state
+    var ds = document.documentElement.style;
+    if(open){ np.classList.add('sl-open'); ds.setProperty('--sl-dock-notes', NOTES_H + 'px'); }
+    else    { np.classList.remove('sl-open'); ds.setProperty('--sl-dock-notes', '0px'); }
+    // innerHTML is populated by the updateChrome() call below (it fills .sl-notes when open).
+    scale();
+    updateChrome();
+  }
+  function toggleNotes(){
+    var np = document.querySelector('.sl-notes');
+    if(np) setNotesOpen(!np.classList.contains('sl-open'));
+  }
 
   // ---- present extras: screen blank (b/w), presenter view, cross-window sync ----------------
   var blanked = '';
@@ -292,13 +313,18 @@ export const RUNTIME_JS = String.raw `
       case 'ArrowLeft': case 'ArrowDown': case 'PageUp': backward(); e.preventDefault(); break;
       case 'Home': goTo(0,1); break;
       case 'End': goTo(slides.length-1,1); break;
-      case 'n': case 'N': toggle('.sl-notes'); break;
+      case 'n': case 'N': toggleNotes(); break;
       case 'f': case 'F': setPresenting(!isPresenting(), true); break;
       case 'p': case 'P': presenter(); break;
       case 'b': case 'B': blank(blanked==='b'?'':'b'); e.preventDefault(); break;
       case 'w': case 'W': blank(blanked==='w'?'':'w'); e.preventDefault(); break;
       case '?': case 'h': toggle('.sl-help'); break;
-      case 'Escape': document.querySelectorAll('.sl-open').forEach(function(e){e.classList.remove('sl-open');}); break;
+      case 'Escape':
+        // Close any open overlay (help, etc.) directly; notes go through setNotesOpen so the
+        // reserved bottom dock unwinds too. (Loop param is el; the outer e is the KeyboardEvent.)
+        document.querySelectorAll('.sl-open').forEach(function(el){ if(!el.classList.contains('sl-notes')) el.classList.remove('sl-open'); });
+        setNotesOpen(false);
+        break;
     }
   });
   // ---- drag-to-pan (only when zoomed in past fit) -------------------------
@@ -347,6 +373,7 @@ export const RUNTIME_JS = String.raw `
   }
   document.addEventListener('fullscreenchange', function(){
     document.body.classList.toggle('sl-presenting', !!document.fullscreenElement);
+    scale();
   });
   var presentBtn = document.querySelector('.sl-present-toggle');
   if(presentBtn) presentBtn.addEventListener('click', function(){ setPresenting(!isPresenting(), true); });
@@ -359,7 +386,7 @@ export const RUNTIME_JS = String.raw `
     relayout: function(){ scale(); }, // recompute the stage fit (e.g. after the dock opens/closes)
     show: function(i){ if(i<0||i>=slides.length) return; activate(i, true); cur=i; updateChrome(); },
     setInteractive: function(on){ navEnabled = on!==false; },
-    toggleNotes: function(){ toggle('.sl-notes'); },
+    toggleNotes: function(){ toggleNotes(); },
     toggleHelp: function(){ toggle('.sl-help'); },
     zoom: function(f){
       zoomFactor = (f==='fit'||!f) ? 1 : Math.max(0.25, Math.min(8, f));

package/dist/render/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/render/runtime.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,sCAAsC;AACtC,8EAA8E;AAC9E,uFAAuF;AACvF,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmYnC,CAAC"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/render/runtime.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,sCAAsC;AACtC,8EAA8E;AAC9E,uFAAuF;AACvF,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8ZnC,CAAC"}

package/dist/vocab.d.ts

@@ -0,0 +1,36 @@
+import { DEFAULT_ENTRANCE } from './render/anim.js';
+/** Named slide transitions (frontmatter `transition:`). Canonical: render/anim.ts. */
+export declare const TRANSITIONS: readonly string[];
+/** Element/build entrances (`>>> <entrance>`), default `fade-up`. Canonical: render/anim.ts. */
+export declare const ENTRANCES: readonly string[];
+export { DEFAULT_ENTRANCE };
+/** Per-slide frontmatter keys the parser recognizes (metadata keys included — they also
+ *  become `{{placeholders}}`). Canonical: parser/parse.ts `KNOWN_SLIDE_KEYS`. */
+export declare const FRONTMATTER_KEYS: readonly string[];
+/** The config (non-metadata) subset — the keys that change how a slide renders. Used by
+ *  the docs lint to check the frontmatter-key table; metadata keys (title/author/…) are
+ *  documented as placeholders/headmatter instead. */
+export declare const FRONTMATTER_CONFIG_KEYS: readonly string[];
+/** Deck headmatter keys with defined meaning (plus any custom scalar → placeholder). */
+export declare const HEADMATTER_KEYS: readonly string[];
+/** Inline span size classes `[x]{.xs}`. Canonical: compiler/markdown.ts `SIZE_CLASS`. */
+export declare const SPAN_SIZE_CLASSES: readonly string[];
+/** Inline span utility classes (besides `.grad`/`.grad-<name>` and colour names). */
+export declare const SPAN_UTIL_CLASSES: readonly string[];
+/** Image `{...}` utility classes `![x](y){.round}`. Canonical: render/css.ts `.sl-img.*`. */
+export declare const IMAGE_UTIL_CLASSES: readonly string[];
+/** Renderable code-fence info-strings (rendered, not shown as code). Canonical: compiler/markdown.ts. */
+export declare const RENDERABLE_FENCES: readonly string[];
+/** Placeholder built-ins `{{page}}` (plus any scalar headmatter/frontmatter key). Canonical: compiler/chrome.ts `placeholderCtx`. */
+export declare const PLACEHOLDER_BUILTINS: readonly string[];
+/** Master layout slot `style:` keys. Canonical: compiler/compile.ts `STYLE_MAP` + the two
+ *  keys handled before the map (`anchor`, `box`). */
+export declare const SLOT_STYLE_KEYS: readonly string[];
+/** Master layout slot `type:`s that get first-class styling. Canonical: render/css.ts `.sl-slot-*`. */
+export declare const SLOT_TYPES: readonly string[];
+/** Every diagnostic (`validate`) code the engine can emit. Canonical: emitted as `code:`
+ *  literals across the parser/compiler; the lint scrapes src to keep this exhaustive. */
+export declare const DIAGNOSTIC_CODES: readonly string[];
+/** Diagnostics that are hard errors (`ok:false`); every other code is a warning.
+ *  Canonical here so `index.ts` and the docs share one definition. */
+export declare const ERROR_SEVERITY_CODES: ReadonlySet<string>;

package/dist/vocab.js

@@ -0,0 +1,77 @@
+// Copyright 2026 AIVory, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// THE canonical registry of the slaide language's author-facing vocabulary.
+//
+// Why this file exists: the token sets (transitions, frontmatter keys, span/slot
+// classes, placeholders, fence types, diagnostic codes) used to live scattered and
+// mostly un-exported across parser/compiler/render modules, and the human docs
+// (docs/spec.md, docs/grammar.md, docs/themes.md) were hand-kept in parallel — so they
+// drifted (e.g. docs listed ~5 transitions while the engine shipped 13). Everything the
+// docs must stay complete about is now imported/derived here from the real code, and
+// `test/docs-sync.test.ts` fails CI if a token is missing from the docs or if the code
+// grows a token this registry doesn't know about. Add a token to the engine → add it
+// here → the lint tells you which doc to update. One source, no drift.
+//
+// This module is a LEAF: it only pulls the already-exported catalogs it can reuse
+// verbatim; anything without a single code-level const is listed here as the canonical
+// definition and cross-checked against source text by the lint.
+import { SLIDE_TRANSITION_NAMES, ENTRANCE_NAMES, DEFAULT_ENTRANCE } from './render/anim.js';
+import { KNOWN_SLIDE_KEYS } from './parser/parse.js';
+import { SIZE_CLASS } from './compiler/markdown.js';
+import { STYLE_MAP } from './compiler/compile.js';
+/** Named slide transitions (frontmatter `transition:`). Canonical: render/anim.ts. */
+export const TRANSITIONS = SLIDE_TRANSITION_NAMES;
+/** Element/build entrances (`>>> <entrance>`), default `fade-up`. Canonical: render/anim.ts. */
+export const ENTRANCES = ENTRANCE_NAMES;
+export { DEFAULT_ENTRANCE };
+/** Per-slide frontmatter keys the parser recognizes (metadata keys included — they also
+ *  become `{{placeholders}}`). Canonical: parser/parse.ts `KNOWN_SLIDE_KEYS`. */
+export const FRONTMATTER_KEYS = [...KNOWN_SLIDE_KEYS];
+/** The config (non-metadata) subset — the keys that change how a slide renders. Used by
+ *  the docs lint to check the frontmatter-key table; metadata keys (title/author/…) are
+ *  documented as placeholders/headmatter instead. */
+export const FRONTMATTER_CONFIG_KEYS = [
+    'layout', 'transition', 'transition-ms', 'transition-ease',
+    'background', 'variant', 'morph', 'chrome', 'logo', 'footer', 'notes',
+];
+/** Deck headmatter keys with defined meaning (plus any custom scalar → placeholder). */
+export const HEADMATTER_KEYS = ['master', 'title', 'author', 'date', 'company', 'subtitle', 'progress'];
+/** Inline span size classes `[x]{.xs}`. Canonical: compiler/markdown.ts `SIZE_CLASS`. */
+export const SPAN_SIZE_CLASSES = Object.keys(SIZE_CLASS);
+/** Inline span utility classes (besides `.grad`/`.grad-<name>` and colour names). */
+export const SPAN_UTIL_CLASSES = ['grad', 'bold', 'muted'];
+/** Image `{...}` utility classes `![x](y){.round}`. Canonical: render/css.ts `.sl-img.*`. */
+export const IMAGE_UTIL_CLASSES = ['round', 'cover', 'shadow'];
+/** Renderable code-fence info-strings (rendered, not shown as code). Canonical: compiler/markdown.ts. */
+export const RENDERABLE_FENCES = ['svg', 'embed', 'widget', 'mermaid', 'echart'];
+/** Placeholder built-ins `{{page}}` (plus any scalar headmatter/frontmatter key). Canonical: compiler/chrome.ts `placeholderCtx`. */
+export const PLACEHOLDER_BUILTINS = [
+    'page', 'total', 'pagePadded', 'totalPadded', 'date', 'title', 'author', 'slideTitle', 'footer',
+];
+/** Master layout slot `style:` keys. Canonical: compiler/compile.ts `STYLE_MAP` + the two
+ *  keys handled before the map (`anchor`, `box`). */
+export const SLOT_STYLE_KEYS = [...Object.keys(STYLE_MAP), 'anchor', 'box'];
+/** Master layout slot `type:`s that get first-class styling. Canonical: render/css.ts `.sl-slot-*`. */
+export const SLOT_TYPES = ['title', 'subtitle', 'body', 'image', 'media', 'quote', 'caption'];
+/** Every diagnostic (`validate`) code the engine can emit. Canonical: emitted as `code:`
+ *  literals across the parser/compiler; the lint scrapes src to keep this exhaustive. */
+export const DIAGNOSTIC_CODES = [
+    // parser/parse.ts
+    'bad-config', 'no-headmatter', 'ambiguous-frontmatter', 'empty-deck',
+    // compiler/compile.ts
+    'unknown-color', 'unknown-gradient', 'bad-animation', 'unknown-layout',
+    'unknown-transition', 'unknown-background', 'unknown-slot', 'low-contrast',
+    // compiler/markdown.ts
+    'unknown-class', 'unknown-entrance', 'stray-build', 'bad-chart',
+    // compiler/tokens.ts
+    'unknown-token', 'token-cycle', 'non-embeddable-font', 'unknown-variant',
+    // compiler/chrome.ts
+    'unknown-placeholder',
+    // index.ts (validation entry)
+    'no-master', 'parse-error',
+];
+/** Diagnostics that are hard errors (`ok:false`); every other code is a warning.
+ *  Canonical here so `index.ts` and the docs share one definition. */
+export const ERROR_SEVERITY_CODES = new Set(['empty-deck', 'no-master', 'unknown-layout']);
+//# sourceMappingURL=vocab.js.map

package/dist/vocab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocab.js","sourceRoot":"","sources":["../src/vocab.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aivorynet/slaide",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "An AI-authorable slide language with beautiful web + PDF output",
   "type": "module",
   "license": "Apache-2.0",

package/skills/slaide/SKILL.md

@@ -16,7 +16,7 @@ Run as `npx @aivorynet/slaide <cmd>` (or `npm run slaide -- <cmd>` where a scrip
 
 ## Workflow
 1. **Brand first — check, then ask.** Scan the project/context for brand assets: colours, fonts, a logo, an existing `*.slaide.yaml` master, a brand doc. Found a master → use it. Found brand → build the master around it. Found nothing → **ask** the user: brand colours? logo? an existing theme, or author one from scratch? Prefer authoring a **new master** over copying an example.
-2. **Read** `reference.md` (language) and `themes.md` (the master format + footguns) before authoring a master. Worked example decks: https://github.com/aivorynet/slaide/tree/main/examples
+2. **Read** `reference.md` (language) and `themes.md` (the master format + footguns) before authoring a master; `grammar.md` is the precise formal reference (frontmatter detection, attribute braces, transitions/entrances, master value forms) when you need it. Worked example decks: https://github.com/aivorynet/slaide/tree/main/examples
 3. **`slaide slots <deck>`** — prints the master's real layouts, slots, colours, gradients, sizes, transitions. Reference these **by name**. (Run on the deck, not the master.)
 4. **Write** the `.slaide` — and the master, if authoring one.
 5. **`slaide validate <deck> --strict`** — a **gate**: must be clean. Every `unknown-*` / `low-contrast` / `non-embeddable-font` means something renders wrong even when it "looks valid".

package/skills/slaide/grammar.md

@@ -0,0 +1,183 @@
+# slaide grammar (v1)
+
+A formal grammar for the `.slaide` document layer. Notation: EBNF — `=` defines, `|` alternation, `{ }` zero-or-more, `[ ]` optional, `( )` grouping, `"x"` literal, `…` charset prose. The Markdown *inside* slot content is CommonMark and is not re-specified here; this grammar defines slaide' structural envelope, sigils, and the inline/attribute extensions, plus the master value forms.
+
+This file is the **precise structural reference**. For what each construct *does* — usage, examples, the full transition/entrance catalogs, chart/image/media options, and the `validate` diagnostic codes — see [spec.md](spec.md); for master semantics (colours, type scale, layouts, slot styles) see [themes.md](themes.md). The token sets are generated from the engine (`src/vocab.ts`) and kept in sync by `test/docs-sync.test.ts`.
+
+## 1. Document
+
+```ebnf
+deck            = [ headmatter ] , slide , { separator , slide } , [ NL ] ;
+headmatter      = fence , config-block , fence ;
+slide           = [ frontmatter ] , body ;
+frontmatter     = config-block , fence ;          (* see §2 detection rule *)
+separator       = NL , fence ;                     (* a line that is exactly "---" *)
+fence           = "---" , EOL ;
+NL              = newline ;
+```
+
+A deck is an optional headmatter block, then one or more slides separated by a bare `---` line. `headmatter` is the first fenced config block. Each slide is an optional fenced frontmatter block followed by a body.
+
+## 2. Frontmatter-vs-body detection (the load-bearing rule)
+
+A block immediately after a separator (or the leading fence) is **frontmatter** iff **both**:
+1. every non-blank, non-`#comment` line matches `config-line` (a `key:`/`~key:`/list-continuation), **and**
+2. it is terminated by a `fence` before the body begins.
+
+Otherwise the block is `body`. Consequences the parser guarantees:
+- The **first** config-like fenced block in the file is `headmatter`.
+- A body whose first line merely *contains* a colon (e.g. `We offer: Tooling`) is **not** frontmatter (it is not `key:`-only and has no trailing fence).
+- A config-shaped block whose keys are **none of** the known slide keys (`layout`, `background`, `transition`, `variant`, `chrome`, `footer`, `logo`, `morph`, …) is still read as frontmatter, **but** the compiler emits an `ambiguous-frontmatter` warning — so a spec-sheet body (`Name: …` / `Founded: …`) eaten as config is no longer silent.
+- To force a body that would otherwise look config-like, escape its first line with a leading backslash (`\Name: Acme`) or precede the slide with an empty frontmatter (`---` `---`).
+- Malformed YAML in a config block emits a `bad-config` warning (with the parser message) instead of silently rendering with defaults.
+
+```ebnf
+config-block    = { config-line | comment | blank } ;
+config-line     = [ "~" ] , key , ":" , [ value ] , EOL ;
+key             = ident ;
+comment         = "#" , … , EOL ;
+ident           = letter , { letter | digit | "-" | "_" } ;
+```
+
+`value` and nested structures follow YAML. A leading `~` on a key marks a **cascading** default (applies to this slide and all following until overridden); a bare key is **scoped** to its slide.
+
+## 3. Fences vs code
+
+`---` is a separator **only outside** a fenced code region. Inside ```` ``` ```` / `~~~` fences it is literal text.
+
+```ebnf
+code-fence      = ("```" | "~~~") , [ info-string ] , EOL , { any-line } , ("```" | "~~~") , EOL ;
+```
+
+A code fence whose `info-string` is a renderable type is rendered, not listed as code: `svg` (inline vector), `embed` (its body is a URL → sandboxed `<iframe>`), `widget` (its body is HTML/JS → `sandbox="allow-scripts"` srcdoc iframe, theme tokens injected), `mermaid` (diagram DSL → inline SVG), `echart` (ECharts `option` as JSON/YAML → inline SVG). Other info-strings render as code. CommonMark GFM pipe tables are supported as ordinary body content.
+
+Media uses the image syntax with a media extension: `![alt](clip.mp4)` / `![alt](track.mp3)` → `<video>`/`<audio>` (see §6).
+
+## 4. Body
+
+```ebnf
+body            = { region-marker | note | content-line } ;
+region-marker   = "::" , WS , slot-name , WS , "::" , EOL ;
+slot-name       = ident ;                          (* valid names are per-layout *)
+note            = "???" , [ WS ] , inline-text , EOL , { non-blank-line } ;
+content-line    = markdown-line ;                  (* CommonMark, with §5–§7 extensions *)
+```
+
+- `region-marker` routes following content into the named slot until the next marker or separator. Content before any marker → the layout's main slot.
+- `note` (a `???` line and its continuation until a blank line) is a speaker note: shown in the presenter overlay, omitted from audience view and PDF.
+
+### 4.1 Build sigil
+
+```ebnf
+build           = content , WS , ">>>" , EOL ;
+```
+
+A list item or block ending with `>>>` becomes an incremental build step. Steps auto-number in document order (a shared per-slide counter); identical effective step → simultaneous. In PDF all builds are settled (shown).
+
+### 4.2 Escaping sigils
+
+A leading backslash turns a slaide sigil into literal content (the backslash is removed):
+
+| Write | Renders as | Instead of |
+|---|---|---|
+| `\:: word ::` | literal `:: word ::` | a region marker |
+| `\??? text` | literal `??? text` body | a speaker note |
+| `… \>>>` | literal trailing `>>>` | a build step |
+| `\[text]{.cls}` | literal `[text]{.cls}` | a styled span (and skips class validation) |
+| `\Name: Acme` (first body line) | body line | frontmatter (see §2) |
+
+## 5. Inline styled spans
+
+```ebnf
+span            = "[" , inline-text , "]" , "{" , class , { class } , "}" ;
+class           = "." , class-name ;
+class-name      = ident ;                           (* resolved against the master *)
+```
+
+Classes chain (`[40-80%]{.grad-purple .huge}`). Resolution (see themes.md → *Marks / utility classes*):
+- `.grad` → brand gradient text; `.grad-<name>` → named gradient text.
+- `.<color>` → text color, where `<color>` is a `palette` key, `roles` name, or a literal CSS colour.
+- `.xs .sm .md .lg .xl .xxl .huge` → font-size (type-scale steps `small`…`stat`).
+- `.bold`, `.muted`, and image utilities `.round`, `.cover`, `.shadow`.
+
+A class that is **none** of the above (e.g. a typo like `.xxlarge` or `.grad-teel`) emits an `unknown-class` / `unknown-gradient` warning rather than silently degrading to inert/invisible CSS. Run `slaide slots <deck>` to print the legal slot, colour, gradient and size names for a deck's master; `slaide validate <deck> [--strict]` surfaces all diagnostics (`--strict` makes warnings fail).
+
+## 6. Image & attribute brace
+
+```ebnf
+image           = "![" , alt , "](" , src , [ WS , quoted ] , ")" , [ attr-brace ] ;
+attr-brace      = "{" , WS , { attr , WS } , "}" ;
+attr            = id-attr | class | kv-attr | anchor-attr ;
+id-attr         = "#" , ident ;
+kv-attr         = key , "=" , value-token ;         (* e.g. width=170px — unquoted, units ok *)
+anchor-attr     = "anchor" , ":" , WS , '"' , pct , WS , pct , WS , pct , WS , pct , '"' ;
+value-token     = { non-space-non-brace } ;
+pct             = number , "%" ;
+```
+
+One brace may mix `#id`, `.class`, `key=value`, and `anchor:"…"` in any order. `#id` enables shared-element **morph** to a same-id element on the next slide (`transition: morph`).
+
+## 7. Placeholders
+
+```ebnf
+placeholder     = "{{" , WS , ph-name , WS , "}}" ;
+ph-name         = ident ;
+```
+
+Substituted at compile time inside chrome bands and master text. Names: `page`, `total`, `pagePadded`, `totalPadded`, `date`, `title`, `author`, `slideTitle`, `footer`, plus any scalar headmatter/frontmatter key. Unknown names resolve to empty (with a warning).
+
+## 8. Master (`*.slaide.yaml`) value forms
+
+The master is YAML; this section pins the slaide-specific value vocabulary (see themes.md for full semantics).
+
+```ebnf
+master          = mapping of:
+                  "schema" , "name" , [ "description" ] ,
+                  [ "canvas" ] , [ "fonts" ] , [ "typeScale" ] , [ "colors" ] ,
+                  [ "gradients" ] , [ "tokens" ] , [ "backgrounds" ] ,
+                  [ "variants" ] , [ "transitions" ] , [ "chrome" ] , [ "ui" ] , [ "layouts" ] ;
+ui              = { [ "progress": boolean ] } ;     (* web position indicator; default true *)
+
+typeScale       = { "base": dim , "ratio": number , "steps": { step-name : (integer | dim) } } ;
+dim             = number , ("px"|"em"|"rem"|"%"|"vw"|"vh") ;
+color-ref       = "{palette." , ident , "}" | "{" , ident , "}" | css-color ;
+gradient-ref    = "{gradients." , ident , "}" | gradient-name ;
+
+layout          = { "areas": [ area-row , { area-row } ] ,
+                    [ "rows" ] , [ "cols" ] , [ "gap" ] , [ "padding" ] ,
+                    [ "align": ("start"|"center"|"end") ] ,
+                    [ "background": bg-name ] ,
+                    [ "chrome": ("both"|"header"|"footer"|"false") ] ,
+                    [ "logo": false ] ,
+                    "slots": { slot-name : slot } } ;
+area-row        = string ;                          (* space-separated slot names; rectangular *)
+slot            = { "type": slot-type , [ "style": style-map ] } ;
+slot-type       = "title"|"subtitle"|"body"|"image"|"media"|"quote"|"caption"| ident ;
+style-map       = { style-key : style-val } ;
+style-key       = "font"|"size"|"color"|"fill"|"align"|"valign"|"justify"
+                | "weight"|"leading"|"transform"|"italic"|"maxw"|"box" ;
+
+chrome          = { [ "header": band ] , [ "footer": band ] ,
+                    [ "logo": svg-string ] , [ "logoPos": corner ] } ;
+band            = { [ "left": tmpl ] , [ "center": tmpl ] , [ "right": tmpl ] } ;
+tmpl            = string ;                           (* Markdown-inline + placeholders *)
+corner          = "top-left"|"top-right"|"bottom-left"|"bottom-right" ;
+```
+
+## 9. Reserved tokens (summary)
+
+| Token | Context | Meaning |
+|---|---|---|
+| `---` | line | slide separator / config fence (outside code fences) |
+| `:: name ::` | line | region/slot marker |
+| `>>>` | end of line/item | build step |
+| `???` | line start | speaker note |
+| `~key:` | frontmatter | cascading default |
+| `[t]{.c}` | inline | styled span |
+| `{#id .c k=v anchor:"…"}` | after image | attributes |
+| `{{name}}` | chrome/master text | placeholder |
+| `![alt](x.mp4\|.mp3)` | inline | video / audio |
+| ```` ```svg ```` | fence | inline vector embed |
+| ```` ```embed ```` / ```` ```widget ```` | fence | sandboxed iframe (URL / inline JS) |
+| ```` ```mermaid ```` / ```` ```echart ```` | fence | chart → inline SVG (diagram / data viz) |
+| `\` (leading) | before a sigil | escape to literal (`\::`, `\???`, `\>>>`, `\[t]{.c}`) |

package/skills/slaide/reference.md

@@ -40,22 +40,37 @@ My Talk
 | Key | Values | Meaning |
 |---|---|---|
 | `layout` | a master layout name | Which grid to use. |
-| `transition` | `none`,`fade`,`slide-left/right/up/down`,`zoom`,`morph` | Transition **into** this slide. |
+| `transition` | a transition name (§3.1) | Transition **into** this slide. |
+| `transition-ms` | milliseconds | Duration override for this slide's transition. |
+| `transition-ease` | a CSS easing | Easing override (`ease`, `cubic-bezier(…)`). |
 | `background` | a master background name | Override the layout's background. |
 | `variant` | a master variant name | Scoped token overrides (e.g. a light section). |
 | `morph` | an id | Participate in a shared-element morph. |
 | `footer` | inline Markdown | Per-slide footer; also `{{footer}}`. |
 | `chrome` | `both`,`header`,`footer`,`none`,`false` | Header/footer visibility this slide. |
 | `logo` | `false` | Hide the corner logo this slide. |
+| `notes` | inline Markdown | Speaker note for this slide (frontmatter form of a `???` line). |
 | *any other scalar* | — | Available as a `{{placeholder}}`. |
 
 **Cascade vs scope:** a bare key (`transition: zoom`) is this-slide-only; a `~`-prefixed key cascades to this slide and every later one until overridden (also valid in headmatter).
 
+### 3.1 Transition names
+
+`transition:` takes one of these built-ins; per-slide `transition-ms` / `transition-ease` override timing, and the master's `transitions: { default, duration }` sets the deck-wide default.
+
+| Group | Names |
+|---|---|
+| Fades | `none`, `fade`, `dissolve`, `fade-through-black` (alias `fade-black`) |
+| Slides | `slide-left` (alias `slide`), `slide-right`, `slide-up`, `slide-down` |
+| Push/cover | `push`, `cover`, `reveal` |
+| Scale/3-D | `zoom`, `zoom-out`, `flip` |
+| Shared-element | `morph` — pairs a `{#id}` image (or a `morph:` id) with the same id on the next slide |
+
 ## 4. Slide body
 
 - **Regions:** `:: name ::` on its own line routes following Markdown into slot `name`. Text before any marker → the main slot (`body`, else the first slot).
 - **Markdown:** standard CommonMark — headings, lists, **bold**, *italic*, `code`, fences, > quotes, links, tables, images. (A single newline is a space; blank line = new paragraph.)
-- **Builds `>>>`:** end an item/block with `>>>` to reveal it; steps auto-number in order, same step = simultaneous. PDF shows all.
+- **Builds `>>>`:** end an item/block with `>>>` to reveal it; steps auto-number in order, same step = simultaneous. PDF shows all. Add an entrance and timing after the sigil (§4.7).
 - **Notes `??? …`:** a `???` line (until a blank line) is a speaker note — presenter overlay only, hidden from audience and PDF.
 
 ### 4.1 Inline styled spans — `[text]{.class …}`
@@ -114,6 +129,17 @@ Both render to **theme-coloured inline SVG** (web/PDF/PNG/PPTX); `slaide build`
 
 GFM pipe tables, styled by the master; use `[cell]{.class}` spans for emphasis.
 
+### 4.7 Build entrances — `>>> <entrance> [opts]`
+
+A bare `>>>` reveals with the default entrance (`fade-up`). Name an entrance right after the sigil, optionally with `delay=`, `dur=` and `ease=` (bare numbers are milliseconds): `- Big reveal >>> zoom-in delay=200 dur=600`. An unknown name warns (`unknown-entrance`) and falls back to the default. A master `animations:` block can define custom entrances too.
+
+| Group | Names |
+|---|---|
+| Fades | `fade`, `fade-up`, `fade-down`, `fade-left`, `fade-right`, `blur-in` |
+| Slides | `slide-in-left`, `slide-in-right`, `slide-in-up`, `slide-in-down`, `rise` |
+| Scale | `zoom-in`, `zoom-out`, `pop` |
+| Instant | `none` |
+
 ## 5. Layers
 
 Each slide composites **background → content → chrome** by paint order. Backgrounds come from the master (per layout or per slide); content flows through the layout's named slots; chrome sits on top.
@@ -175,3 +201,33 @@ footer: A first deck
 ```
 
 See [themes.md](themes.md) to author a master.
+
+## 10. Diagnostics — what `validate` reports
+
+`slaide validate <deck>` prints line-numbered diagnostics; `--strict` makes every warning fail. **Errors** fail regardless of `--strict`; everything else is a **warning** (a real render defect even when the deck "looks valid"). Every code:
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `parse-error` | error | The source could not be parsed at all. |
+| `empty-deck` | error | No slides were found. |
+| `no-master` | error | The deck's `master:` could not be resolved. |
+| `unknown-layout` | error | A slide's `layout:` names no layout in the master. |
+| `no-headmatter` | warning | No leading `---` deck headmatter block (e.g. `master:`). |
+| `bad-config` | warning | A headmatter/frontmatter block is not valid YAML (rendered with defaults). |
+| `ambiguous-frontmatter` | warning | A config-shaped **body** was eaten as frontmatter — escape the first line with `\` or add an explicit `---`. |
+| `unknown-transition` | warning | A `transition:` names no built-in transition (§3.1). |
+| `unknown-background` | warning | A `background:` names no master background. |
+| `unknown-variant` | warning | A `variant:` names no master variant. |
+| `unknown-slot` | warning | Content routed to a slot the chosen layout doesn't define (dropped silently). |
+| `unknown-class` | warning | An inline `[x]{.cls}` is not a size / `.bold` / `.muted` / `.grad` / master colour / CSS colour. |
+| `unknown-gradient` | warning | A `.grad-<name>` or slot `fill:` names no master gradient (text gets no fill — often invisible). |
+| `unknown-color` | warning | A slot `color:`/`box:` names no master role/palette or CSS colour (falls back to a literal, often invisible). |
+| `unknown-entrance` | warning | A `>>> <name>` build entrance isn't a known effect (§4.7). |
+| `stray-build` | warning | A `>>>` on a non-list line (headings, bold labels, paragraphs). |
+| `low-contrast` | warning | Resolved text ≈ its background (dark-on-dark / light-on-light) — bind a `variant:` or set an explicit `color:`. |
+| `bad-chart` | warning | An ````echart` option didn't parse — rendered as a plain code block instead. |
+| `bad-animation` | warning | A master `animations:` entry is missing its required keyframes/`hidden` state. |
+| `unknown-token` | warning | A master token reference names nothing. |
+| `token-cycle` | warning | A master token references itself in a cycle. |
+| `non-embeddable-font` | warning | A font won't embed in `.pptx` — PowerPoint will substitute it. |
+| `unknown-placeholder` | warning | A `{{name}}` resolves to nothing (renders empty). |

package/skills/slaide/themes.md

@@ -47,12 +47,14 @@ colors:
     accent:     "{palette.brand}"
 layouts:
   cover:
-    align: center
-    areas: ["title", "subtitle"]
+    areas: ["title visual", "subtitle visual"]
     rows: "auto auto"
+    cols: "1.1fr 0.9fr"
+    gap: "0.5em 3em"
     slots:
       title:    { type: title,    style: { font: display, size: h1, weight: "900" } }
       subtitle: { type: subtitle, style: { size: h3, color: accent } }
+      visual:   { type: image,    style: { valign: center } }
   title-content:
     areas: ["title", "body"]
     rows: "auto 1fr"
@@ -69,7 +71,7 @@ layouts:
 
 ## fonts / typeScale
 
-**Use real Google Fonts only** (`provider: google`) — pick families that actually exist on Google Fonts and embed (avoid **JetBrains Mono**, which doesn't). A `display` (headings) + a `sans` (body) is plenty; add a `mono` role only if the deck shows code. A `provider: system`/`local` font that isn't a common system font (Arial, Calibri, Georgia…) **warns** (`non-embeddable-font`): it won't embed in the `.pptx`, so PowerPoint substitutes it off your machine.
+**Use real Google Fonts only** (`provider: google`) — pick families that actually exist on Google Fonts. A `display` + `sans` is plenty; add `mono` only if the deck shows code. A `provider: system`/`local` font that isn't a common system font (Arial, Calibri, Georgia…) **warns** (`non-embeddable-font`): it won't embed in `.pptx`.
 
 ```yaml
 fonts:
@@ -195,6 +197,7 @@ layouts:
 | `box` | surface panel (bg + padding + radius) | `true`, a colour role/palette name (preferred), a **named master gradient** (`box: brand` → padded, rounded, gradient hero/closing panel), or a raw hex / CSS colour / gradient |
 | `bg` | background of the slot region | any CSS colour / gradient (literal) |
 | `anchor` | absolutely position the slot | `"x% y% w% h%"` of the canvas |
+| `pad` / `opacity` / `radius` / `border` / `rotate` | fine control — padding / opacity / border-radius / border / rotation (also emitted by the importer) | CSS values (`rotate` accepts a bare deg or a full `transform`) |
 
 `color:`/`box:`/`fill:` are validated against the master — an unresolved name warns, so `validate` can't call an invisible-text slide valid. Run `slaide slots` for legal names.
 
@@ -208,8 +211,19 @@ Inline `[text]{.class}` resolves against this master: **colour** = any `palette`
 
 ## Tips for AI authors
 
-- Reference **roles** and **scale steps**, not raw hex/px, so a reskin is a palette swap. Add a layout by adding an `areas` map + `slots` — no code.
-- **Cards (`box:`) — kill hollow tops.** A `box:` is bg + padding + radius only (solid colour — **no gradient/shadow/border**). With no `valign` a card **stretches to its grid row** and pins text to the top — hollow in a tall `1fr` row. Two fixes: **`valign: center`** shrinks the card to its content and centres it; or, to keep a row of cards equal height, put them in an **`auto`** row and centre that block with spacer rows (`rows: "auto 1fr auto 1fr"`). On a light ground, tint the card surface off-white vs the page so it reads.
-- **Signature, not just tidy:** give the deck one repeated motif (a faint logo-derived shape or a recurring accent panel) and vary composition slide to slide. Make the **cover and closing command** — don't leave half the canvas empty: pair a strong text column with a full-height brand/gradient panel or full-bleed motif.
-- **Inline `svg` needs a size:** give the `<svg>` explicit `width`/`height`, or a centered zero-size SVG collapses and vanishes.
-- **A deck about slaide itself?** Use the shipped brand in the sibling `slaide-hugo` repo (`themes/slaide/assets/css/slaide.css` `:root`; `static/images/slaide-*.svg`): slate-azure gradient `#243B6B→#3E6FB0→#6FA8DC` on cream `#FBF7F0` / ink `#15120E`; IBM Plex Sans + JetBrains Mono + Fraunces.
+- Use **roles** and **scale steps**, not raw hex/px — reskin = palette swap.
+- **Cards (`box:`):** bg + padding + radius only (no gradient/shadow/border). Without `valign` a card stretches full-height and pins text top (hollow). Fix: `valign: center` to shrink-wrap, or put cards in an `auto` row with `1fr` spacers. Tint card surface off-white vs the page.
+- **Cover = dramatic hero.** Visual slot FILLS — bold brand SVG, product mock, or illustrated motif at ≥ half the slide, not a small icon. Think Apple keynote: few bold shapes at large scale. Centred text on a gradient is a section divider, not a cover. Never `.grad` text on a gradient bg (vanishes). **Closing** = bold CTA or contact slide (name/role/email/URL for pitch/agency decks). Both must feel intentional.
+- **Brand ground dominates.** Most slides use the brand's background role (warm cream, tinted neutral — not generic white). Dark/gradient = accent moments only (cover, one stat, closing).
+- **No text-only slides — no exceptions.** Every content slide needs a visual: ` ```echart ` for data, inline ` ```svg ` for diagrams/mockups (preferred — precise, brand-styled), `box:` cards, or a stat callout. A comparison/pro-con slide is NOT exempt: use cards, a table, or SVG icons. Mix visual types across the deck — all-SVG or all-cards = monotone.
+- **Vary composition.** Never repeat the same layout archetype — two text+visual slides need structurally different layouts (not image-left twice). Mix archetypes, alternate dark/light grounds. One slide should break the pattern — oversized `.grad` stat, serif quote owning the canvas, or full-bleed visual.
+- **One idea per slide.** Each slide delivers one clear message (4 bullets max). The visual and text reinforce the SAME idea — if the visual still communicates without the text, that's right.
+- **Size contrast.** Pair `hero`/`stat` scale with body text. At least one slide MUST feature a single big number or statement using `.huge` or `.stat` — the audience remembers ONE number from every deck. No decorative accent lines under titles (AI tell).
+- **Use every font role** defined in the master (serif, display, mono).
+- **Whitespace.** `--slide-padding` ≥ 96px, `gap` ≥ 2em. `auto` rows for content, `1fr` spacers to centre. Cards need `pad`.
+- **Avoid `<a>` links in slides.** They aren't clickable during presentations and their `link` role color can override slot `color:`. Write URLs as plain text; style with `[text]{.class}` spans.
+- **Muted text must read at projection scale.** Keep well above 2.5:1 contrast. Never use light-ground `muted` inside a dark `box:`/`bg:` card — set explicit light `color:` instead.
+- **Inline SVG:** explicit `width`/`height` required (collapses without them). Images fill their container (the layout controls sizing via grid areas + padding).
+- **Academic / teaching decks** (symposia, lectures, workshops): clarity over flash. Favour ` ```svg ` / ` ```mermaid ` diagrams for processes and systems, ` ```echart ` for data/results. Use `>>>` heavily for progressive build. Larger body text (≥ h3). Section dividers between topics. End with summary/takeaways/questions, not a sales CTA. High-contrast, clean backgrounds.
+- **Financial / board reports**: data credibility first. Heavy ` ```echart ` (bar, line, waterfall, pie). Stats use `.huge` with exact numbers. Comparison tables via `box:` card grids (Plan vs Actual). Conservative palette — dark text on light ground, accent on KPI highlights only. Section dividers per business unit or period. Cover = clean title + period, not a hero. End with outlook/risks.
+- **A deck about slaide?** Brand from `slaide-hugo` repo: azure `#243B6B→#3E6FB0→#6FA8DC`, cream `#FBF7F0`, ink `#15120E`; IBM Plex Sans + JetBrains Mono + Fraunces.