@aivorynet/slaide 1.0.3 → 1.0.5

package/dist/render/charts.js

@@ -36,13 +36,17 @@ export const CHARTS_BOOT_JS = String.raw `
   // deck's CSS custom properties so charts come out on-brand automatically.
   function ensure(engine){
     if(booted[engine]) return booted[engine];
-    var tag = document.getElementById('sl-'+engine+'-lib');
-    if(!tag) return null;
-    try{ (0,eval)(b64decode(tag.textContent)); }
-    catch(e){ console.error('slaide: failed to boot '+engine, e); return null; }
+    var global = engine==='echart' ? window.echarts : engine==='mermaid' ? window.mermaid : null;
+    if(!global){
+      var tag = document.getElementById('sl-'+engine+'-lib');
+      if(!tag) return null;
+      try{ (0,eval)(b64decode(tag.textContent)); }
+      catch(e){ console.error('slaide: failed to boot '+engine, e); return null; }
+    }
 
     if(engine==='mermaid' && window.mermaid){
-      var font = cssVar('--font-sans','system-ui');
+      var mSlide = document.querySelector('.sl-slide');
+      var font = cssVar('--font-sans','') || (mSlide ? getComputedStyle(mSlide).fontFamily : '') || 'system-ui, sans-serif';
       window.mermaid.initialize({
         startOnLoad:false, securityLevel:'strict', theme:'base', fontFamily:font,
         themeVariables:{
@@ -66,7 +70,8 @@ export const CHARTS_BOOT_JS = String.raw `
       if(accent && colors.indexOf(accent)<0) colors = [accent].concat(colors);
       var text = cssVar('--color-text','#ffffff');
       var muted = cssVar('--color-muted','#8B93A7');
-      var font = cssVar('--font-sans','system-ui');
+      var slideEl = document.querySelector('.sl-slide');
+      var font = cssVar('--font-sans','') || (slideEl ? getComputedStyle(slideEl).fontFamily : '') || 'system-ui, sans-serif';
       var axis = {
         axisLine:{lineStyle:{color:muted}},
         axisTick:{lineStyle:{color:muted}},

package/dist/render/charts.js.map

@@ -1 +1 @@
-{"version":3,"file":"charts.js","sourceRoot":"","sources":["../../src/render/charts.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,sCAAsC;AACtC,kFAAkF;AAClF,EAAE;AACF,yFAAyF;AACzF,yFAAyF;AACzF,0FAA0F;AAC1F,wFAAwF;AACxF,yFAAyF;AACzF,oDAAoD;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,oFAAoF;AACpF,mEAAmE;AACnE,uFAAuF;AACvF,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyJvC,CAAC"}
+{"version":3,"file":"charts.js","sourceRoot":"","sources":["../../src/render/charts.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAC9B,sCAAsC;AACtC,kFAAkF;AAClF,EAAE;AACF,yFAAyF;AACzF,yFAAyF;AACzF,0FAA0F;AAC1F,wFAAwF;AACxF,yFAAyF;AACzF,oDAAoD;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,oFAAoF;AACpF,mEAAmE;AACnE,uFAAuF;AACvF,iEAAiE;AACjE,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8JvC,CAAC"}

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

@@ -7,10 +7,12 @@ export const RUNTIME_JS = String.raw `
   var stage = document.querySelector('.sl-stage');
   if(!stage) return;
   var vp = document.querySelector('.sl-viewport');
-  var slides = Array.prototype.slice.call(document.querySelectorAll('.sl-slide'));
+  // Scope to the stage: a host (web editor) may clone .sl-slide into a filmstrip elsewhere in the
+  // document; collecting from the whole document would pollute the count/index and navigation.
+  var slides = Array.prototype.slice.call(stage.querySelectorAll('.sl-slide'));
   var CW = parseFloat(stage.dataset.w)||1280, CH = parseFloat(stage.dataset.h)||720;
   var notes = (window.__SLAIDE_NOTES__)||[];
-  var cur = 0, step = 0, busy = false;
+  var cur = 0, step = 0, busy = false, pendingNav = null;
   var zoomFactor = 1, panX = 0, panY = 0;
   // When false, taps don't advance and drag-pan is off (for interactive embeds,
   // kiosk mode, or a host that drives navigation itself). Default: on.
@@ -40,20 +42,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+')';
   }
 
@@ -118,30 +120,55 @@ export const RUNTIME_JS = String.raw `
     if(dir<0){ newSlide.classList.add('sl-anim-rev'); oldSlide.classList.add('sl-anim-rev'); }
     step = dir<0 ? buildCount(i) : 0; applyBuilds(newSlide, step);
     var done=0;
-    function endOld(){ oldSlide.classList.remove('sl-active', outC, 'sl-anim-rev'); oldSlide.removeEventListener('animationend', endOld); next(); }
-    function endNew(){ newSlide.classList.remove(inC, 'sl-anim-rev'); newSlide.removeEventListener('animationend', endNew); next(); }
-    function next(){ if(++done>=2){ busy=false; } }
+    function endOld(){ if(done&1) return; done|=1; oldSlide.classList.remove('sl-active', outC, 'sl-anim-rev'); oldSlide.removeEventListener('animationend', endOld); fin(); }
+    function endNew(){ if(done&2) return; done|=2; newSlide.classList.remove(inC, 'sl-anim-rev'); newSlide.removeEventListener('animationend', endNew); fin(); }
+    function fin(){ if((done&3)===3){ busy=false; if(pendingNav){ var p=pendingNav; pendingNav=null; if(p==='fwd') forward(); else backward(); } } }
     oldSlide.addEventListener('animationend', endOld);
     newSlide.addEventListener('animationend', endNew);
-    // safety timeout
-    setTimeout(function(){ if(busy){ oldSlide.classList.remove('sl-active',outC,'sl-anim-rev'); newSlide.classList.remove(inC,'sl-anim-rev'); busy=false; } }, 1200);
+    requestAnimationFrame(function(){
+      var cs1=getComputedStyle(oldSlide),cs2=getComputedStyle(newSlide);
+      if(!cs1.animationName||cs1.animationName==='none'||cs1.animationDuration==='0s') endOld();
+      if(!cs2.animationName||cs2.animationName==='none'||cs2.animationDuration==='0s') endNew();
+    });
+    setTimeout(function(){ if(busy){ endOld(); endNew(); } }, 800);
     cur=i; updateChrome(); sync();
   }
 
   function forward(){
-    if(busy) return;
+    if(busy){ pendingNav='fwd'; return; }
     if(blanked) blank('');
     if(step < buildCount(cur)){ step++; applyBuilds(slides[cur], step); updateChrome(); sync(); return; }
     goTo(cur+1, 1);
   }
   function backward(){
-    if(busy) return;
+    if(busy){ pendingNav='bwd'; return; }
     if(blanked) blank('');
     if(step > 0){ step--; applyBuilds(slides[cur], step); updateChrome(); sync(); return; }
     goTo(cur-1, -1);
   }
 
   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 +319,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 +379,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); });
@@ -357,9 +390,22 @@ export const RUNTIME_JS = String.raw `
     prev: backward,
     goTo: function(i){ goTo(i, i>cur?1:-1); },
     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(); },
+    show: function(i){ if(!slides.length) return; i=Math.max(0,Math.min(slides.length-1,i)); activate(i, true); cur=i; updateChrome(); },
+    // Re-collect slides after the host appended/replaced .sl-slide nodes in the stage (live agent
+    // build: new slides stream in one by one). Preserve the current index; re-assert active + builds
+    // + chrome. Returns the new slide count.
+    rescan: function(){
+      slides = Array.prototype.slice.call(stage.querySelectorAll(':scope > .sl-slide'));
+      if(!slides.length) return 0;
+      cur = Math.max(0, Math.min(cur, slides.length-1));
+      slides.forEach(function(s,idx){ s.classList.toggle('sl-active', idx===cur); });
+      if(step > buildCount(cur)) step = buildCount(cur);
+      applyBuilds(slides[cur], step);
+      scale(); updateChrome();
+      return slides.length;
+    },
     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));
@@ -388,6 +434,7 @@ export const RUNTIME_JS = String.raw `
   scale(); updateChrome();
   if(AM_PRESENTER) buildPresenter();                        // this window is the presenter view
   if(AM_AUDIENCE){ document.body.classList.add('slv-presenting'); navEnabled = false; }  // clean mirror, host-driven
+  if(document.body.classList.contains('sl-editing')) navEnabled = false;
 })();
 `;
 //# sourceMappingURL=runtime.js.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkbnC,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":"AAAA,8BAA8B;AAC9B,sCAAsC;AACtC,EAAE;AACF,4EAA4E;AAC5E,EAAE;AACF,iFAAiF;AACjF,mFAAmF;AACnF,+EAA+E;AAC/E,uFAAuF;AACvF,wFAAwF;AACxF,qFAAqF;AACrF,uFAAuF;AACvF,qFAAqF;AACrF,uEAAuE;AACvE,EAAE;AACF,kFAAkF;AAClF,uFAAuF;AACvF,gEAAgE;AAEhE,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,sFAAsF;AACtF,MAAM,CAAC,MAAM,WAAW,GAAsB,sBAAsB,CAAC;AAErE,gGAAgG;AAChG,MAAM,CAAC,MAAM,SAAS,GAAsB,cAAc,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAE5B;iFACiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAsB,CAAC,GAAG,gBAAgB,CAAC,CAAC;AAEzE;;qDAEqD;AACrD,MAAM,CAAC,MAAM,uBAAuB,GAAsB;IACxD,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB;IAC1D,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO;CACtE,CAAC;AAEF,wFAAwF;AACxF,MAAM,CAAC,MAAM,eAAe,GAAsB,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAE3H,yFAAyF;AACzF,MAAM,CAAC,MAAM,iBAAiB,GAAsB,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAE5E,qFAAqF;AACrF,MAAM,CAAC,MAAM,iBAAiB,GAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9E,6FAA6F;AAC7F,MAAM,CAAC,MAAM,kBAAkB,GAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AAElF,yGAAyG;AACzG,MAAM,CAAC,MAAM,iBAAiB,GAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AAEpG,qIAAqI;AACrI,MAAM,CAAC,MAAM,oBAAoB,GAAsB;IACrD,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ;CAChG,CAAC;AAEF;qDACqD;AACrD,MAAM,CAAC,MAAM,eAAe,GAAsB,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;AAE/F,uGAAuG;AACvG,MAAM,CAAC,MAAM,UAAU,GAAsB,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAEjH;yFACyF;AACzF,MAAM,CAAC,MAAM,gBAAgB,GAAsB;IACjD,kBAAkB;IAClB,YAAY,EAAE,eAAe,EAAE,uBAAuB,EAAE,YAAY;IACpE,sBAAsB;IACtB,eAAe,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB;IACtE,oBAAoB,EAAE,oBAAoB,EAAE,cAAc,EAAE,cAAc;IAC1E,uBAAuB;IACvB,eAAe,EAAE,kBAAkB,EAAE,aAAa,EAAE,WAAW;IAC/D,qBAAqB;IACrB,eAAe,EAAE,aAAa,EAAE,qBAAqB,EAAE,iBAAiB;IACxE,qBAAqB;IACrB,qBAAqB;IACrB,8BAA8B;IAC9B,WAAW,EAAE,aAAa;CAC3B,CAAC;AAEF;sEACsE;AACtE,MAAM,CAAC,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aivorynet/slaide",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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".
@@ -48,7 +48,7 @@ layout: title-content
 - Charts: ` ```echart ` (data viz, ECharts option as JSON) and ` ```mermaid ` (diagrams) → theme-coloured SVG. Put a chart in a slot with height (a `1fr` row).
 
 ## The master (theme)
-Use the bundled theme — omit `master:` or set `master: aurora` — or author your own (preferred for branded decks). **Read `themes.md` for the format before writing one**: fonts, a type scale, two-tier colour (palette + roles), gradients, backgrounds, grid layouts, chrome — all data. Reference **roles, not hex**, so a reskin is a palette swap. Past "tidy", give the deck **one signature** (a faint logo-derived motif or a recurring accent panel) and vary composition slide to slide. The load-bearing footguns — dark-on-dark text, hollow `box:` cards, chrome-corner collisions — are flagged in `themes.md`; heed them. A deck about slaide itself: use the shipped brand in the sibling `slaide-hugo` repo, don't invent one.
+Use the bundled theme — omit `master:` or set `master: aurora` — or author your own (preferred for branded decks). **Read `themes.md` for the format before writing one**: fonts, a type scale, two-tier colour (palette + roles), gradients, backgrounds, grid layouts, chrome — all data. Reference **roles, not hex**, so a reskin is a palette swap. Past "tidy", give the deck **one signature** (a recurring accent panel, a distinctive layout rhythm, or a colour-block motif) and vary composition slide to slide. Chrome `logo:` is opt-in — only add it when the user supplies a real brand logo; do NOT invent a generic icon. The load-bearing footguns — dark-on-dark text, hollow `box:` cards, chrome-corner collisions — are flagged in `themes.md`; heed them. A deck about slaide itself: use the shipped brand in the sibling `slaide-hugo` repo, don't invent one.
 
 ## Commands (prefix `npx @aivorynet/slaide`)
 | Command | Does |

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}`) |