stagecraft 0.1.0

package/src/helpers.js

@@ -0,0 +1,169 @@
+'use strict';
+
+/**
+ * Stagecraft — Layer 1 primitives.
+ *
+ * Small composable utilities every slide can use. Kept tiny on purpose:
+ * an agent should be able to read any one in 30 seconds.
+ *
+ * All helpers attach to the global `Stage` namespace.
+ */
+
+(function (root) {
+  const Stage = root.Stage = root.Stage || {};
+
+  // ---------------------------------------------------------------------------
+  // prefersReducedMotion()
+  // Whether the OS user has requested reduced motion. JS animations
+  // (typewriter, count-up, particle emit, stagger, etc.) should consult
+  // this and shortcut to the final state.
+  // ---------------------------------------------------------------------------
+  Stage.prefersReducedMotion = function () {
+    return typeof matchMedia !== 'undefined' &&
+      matchMedia('(prefers-reduced-motion: reduce)').matches;
+  };
+
+  // ---------------------------------------------------------------------------
+  // staggerIn(nodes, step, initial)
+  // Fade-in nodes one after another by adding `.in` class. Pairs with
+  // `.stagger > * { opacity: 0; transform: translateY(12px); transition: ... }`
+  // and `.stagger > *.in { opacity: 1; transform: translateY(0); }` in theme CSS.
+  // Reduced motion: snap all in at once.
+  // ---------------------------------------------------------------------------
+  Stage.staggerIn = function (nodes, step = 200, initial = 100) {
+    if (Stage.prefersReducedMotion()) {
+      nodes.forEach(n => n.classList.add('in'));
+      return () => {};
+    }
+    const timers = [];
+    nodes.forEach((n, i) => {
+      timers.push(setTimeout(() => n.classList.add('in'), initial + i * step));
+    });
+    return () => timers.forEach(clearTimeout);
+  };
+
+  // ---------------------------------------------------------------------------
+  // emitParticle(parent, x1, y1, x2, y2, duration)
+  // SVG particle traveling between two points with smooth-step easing.
+  // ---------------------------------------------------------------------------
+  Stage.emitParticle = function (parent, x1, y1, x2, y2, duration = 800) {
+    if (Stage.prefersReducedMotion()) {
+      // Skip the particle entirely in reduced-motion mode.
+      return () => {};
+    }
+    const NS = 'http://www.w3.org/2000/svg';
+    const c = document.createElementNS(NS, 'circle');
+    c.setAttribute('class', 'particle');
+    c.setAttribute('r', 3.5);
+    c.setAttribute('cx', x1);
+    c.setAttribute('cy', y1);
+    parent.appendChild(c);
+    const start = performance.now();
+    let rafId;
+    function step(now) {
+      const t = Math.min(1, (now - start) / duration);
+      const eased = t * t * (3 - 2 * t);
+      const x = x1 + (x2 - x1) * eased;
+      const y = y1 + (y2 - y1) * eased;
+      c.setAttribute('cx', x);
+      c.setAttribute('cy', y);
+      c.setAttribute('opacity', 1 - t * 0.3);
+      if (t < 1) rafId = requestAnimationFrame(step);
+      else c.remove();
+    }
+    rafId = requestAnimationFrame(step);
+    return () => { cancelAnimationFrame(rafId); c.remove(); };
+  };
+
+  // ---------------------------------------------------------------------------
+  // typewriter(el, text, opts)
+  // Character-by-character text reveal. Returns cleanup.
+  // opts: { speed: ms per char, jitter: ms random extra, onDone: fn }
+  // ---------------------------------------------------------------------------
+  Stage.typewriter = function (el, text, opts = {}) {
+    if (Stage.prefersReducedMotion()) {
+      el.textContent = text;
+      opts.onDone?.();
+      return () => {};
+    }
+    const speed = opts.speed ?? 50;
+    const jitter = opts.jitter ?? 30;
+    el.textContent = '';
+    let i = 0;
+    let cancelled = false;
+    const timers = [];
+    function tick() {
+      if (cancelled) return;
+      if (i >= text.length) { opts.onDone?.(); return; }
+      el.textContent += text[i++];
+      timers.push(setTimeout(tick, speed + Math.random() * jitter));
+    }
+    timers.push(setTimeout(tick, opts.initial ?? 0));
+    return () => { cancelled = true; timers.forEach(clearTimeout); };
+  };
+
+  // ---------------------------------------------------------------------------
+  // revealByDataStep(el, step)
+  // Toggle a `.shown` class on `[data-step="n"]` elements where n <= step.
+  // Designed to be passed directly as a slide's `onStep` for trivial reveals.
+  // ---------------------------------------------------------------------------
+  Stage.revealByDataStep = function (el, step) {
+    el.querySelectorAll('[data-step]').forEach(n => {
+      n.classList.toggle('shown', Number(n.dataset.step) <= step);
+    });
+  };
+
+  // ---------------------------------------------------------------------------
+  // blinkCaret(el)
+  // Attach a blinking caret to an element. CSS does the visual; this returns a
+  // cleanup that removes the caret span if you need it.
+  // ---------------------------------------------------------------------------
+  Stage.blinkCaret = function (el) {
+    const c = document.createElement('span');
+    c.className = 'caret';
+    el.appendChild(c);
+    return () => c.remove();
+  };
+
+  // ---------------------------------------------------------------------------
+  // sessionElapsedClock(opts)
+  // Live MM:SS / H:MM:SS clock that ticks every second. Returns the element
+  // plus a stop() function.
+  // ---------------------------------------------------------------------------
+  Stage.sessionElapsedClock = function (opts = {}) {
+    const start = opts.start ?? Date.now();
+    const el = document.createElement('span');
+    el.className = 'session-clock';
+    function format(ms) {
+      const total = Math.floor(ms / 1000);
+      const h = Math.floor(total / 3600);
+      const m = Math.floor((total % 3600) / 60);
+      const s = total % 60;
+      const pad = n => String(n).padStart(2, '0');
+      return h > 0 ? `${h}:${pad(m)}:${pad(s)}` : `${pad(m)}:${pad(s)}`;
+    }
+    function tick() { el.textContent = format(Date.now() - start); }
+    tick();
+    const id = setInterval(tick, 1000);
+    return { el, stop: () => clearInterval(id) };
+  };
+
+  // ---------------------------------------------------------------------------
+  // assignStageKeys(root)
+  // Walk a rendered element subtree, assigning `data-stage-key` to every
+  // element via a depth-indexed path (e.g. "0", "0.1", "0.1.2").
+  // Skipped for elements that already have a key (semantic override).
+  // Used by edit mode for element-pin annotations.
+  // ---------------------------------------------------------------------------
+  Stage.assignStageKeys = function (root) {
+    function walk(node, prefix) {
+      Array.from(node.children).forEach((child, i) => {
+        const key = prefix ? `${prefix}.${i}` : String(i);
+        if (!child.dataset.stageKey) child.dataset.stageKey = key;
+        walk(child, key);
+      });
+    }
+    walk(root, '');
+  };
+
+})(typeof window !== 'undefined' ? window : globalThis);

package/src/transitions.js

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * Stagecraft — Built-in transitions library.
+ *
+ * Six transitions: cut, fade, slide, dissolve, glitch, wipe.
+ * Themes can override or extend via Stage.registerTransition(name, config).
+ *
+ * Each transition has optional enter(el) and exit(el) hooks. CSS classes
+ * named `tx-<name>-enter` and `tx-<name>-exit` are added/removed; themes
+ * provide the actual visual via CSS.
+ */
+
+(function (root) {
+  const Stage = root.Stage = root.Stage || {};
+
+  function classToggle(el, cls, ms = 800) {
+    el.classList.add(cls);
+    setTimeout(() => el.classList.remove(cls), ms);
+  }
+
+  Stage.registerTransition('cut', {
+    enter(el) { /* no-op, instant */ },
+    exit(el) { /* no-op */ }
+  });
+
+  Stage.registerTransition('fade', {
+    enter(el) { classToggle(el, 'tx-fade-enter', 700); },
+    exit(el) { classToggle(el, 'tx-fade-exit', 400); }
+  });
+
+  Stage.registerTransition('slide', {
+    enter(el) { classToggle(el, 'tx-slide-enter', 700); },
+    exit(el) { classToggle(el, 'tx-slide-exit', 500); }
+  });
+
+  Stage.registerTransition('dissolve', {
+    enter(el) { classToggle(el, 'tx-dissolve-enter', 1200); },
+    exit(el) { classToggle(el, 'tx-dissolve-exit', 1000); }
+  });
+
+  // Glitch: a brief scanline + RGB-shift overlay, then settle.
+  Stage.registerTransition('glitch', {
+    enter(el) {
+      classToggle(el, 'tx-glitch-enter', 600);
+      const overlay = document.createElement('div');
+      overlay.className = 'tx-glitch-overlay';
+      el.appendChild(overlay);
+      setTimeout(() => overlay.remove(), 600);
+    },
+    exit(el) { classToggle(el, 'tx-glitch-exit', 200); }
+  });
+
+  Stage.registerTransition('wipe', {
+    enter(el) { classToggle(el, 'tx-wipe-enter', 800); },
+    exit(el) { classToggle(el, 'tx-wipe-exit', 500); }
+  });
+
+  // -- Additional transitions (Phase 2) -- //
+
+  Stage.registerTransition('zoom-in', {
+    enter(el) { classToggle(el, 'tx-zoom-in-enter', 700); },
+    exit(el) { classToggle(el, 'tx-zoom-in-exit', 400); }
+  });
+
+  Stage.registerTransition('zoom-out', {
+    enter(el) { classToggle(el, 'tx-zoom-out-enter', 700); },
+    exit(el) { classToggle(el, 'tx-zoom-out-exit', 400); }
+  });
+
+  Stage.registerTransition('flip', {
+    enter(el) { classToggle(el, 'tx-flip-enter', 900); },
+    exit(el) { classToggle(el, 'tx-flip-exit', 500); }
+  });
+
+  Stage.registerTransition('iris', {
+    enter(el) { classToggle(el, 'tx-iris-enter', 900); },
+    exit(el) { classToggle(el, 'tx-iris-exit', 500); }
+  });
+
+  Stage.registerTransition('shutter', {
+    enter(el) { classToggle(el, 'tx-shutter-enter', 800); },
+    exit(el) { classToggle(el, 'tx-shutter-exit', 500); }
+  });
+
+  Stage.registerTransition('push', {
+    enter(el) { classToggle(el, 'tx-push-enter', 800); },
+    exit(el) { classToggle(el, 'tx-push-exit', 800); }
+  });
+
+  Stage.registerTransition('typewriter', {
+    enter(el) { classToggle(el, 'tx-typewriter-enter', 900); },
+    exit(el) { classToggle(el, 'tx-typewriter-exit', 300); }
+  });
+
+  Stage.registerTransition('shatter', {
+    enter(el) { classToggle(el, 'tx-shatter-enter', 900); },
+    exit(el) { classToggle(el, 'tx-shatter-exit', 500); }
+  });
+
+})(typeof window !== 'undefined' ? window : globalThis);

package/starter/index.html

@@ -0,0 +1,40 @@
+<!doctype html>
+<html lang="en" data-theme="phosphor">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+  <title>My Deck — Stagecraft</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:ital,wght@0,300;0,400;0,500;0,700;1,400&display=swap" rel="stylesheet">
+  <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0&display=swap" rel="stylesheet">
+
+  <link rel="stylesheet" href="node_modules/stagecraft/dist/themes/phosphor.bundle.css">
+</head>
+<body>
+
+  <div class="welcome" id="welcome">
+    <div class="key-prompt"><span class="accent">●</span>&nbsp;&nbsp;Press <span class="accent">→</span> or <span class="accent">Space</span> to begin</div>
+    <h1>My Deck</h1>
+    <div class="by">Made with Stagecraft</div>
+  </div>
+
+  <main id="stage"></main>
+
+  <div class="ui">
+    <div class="ui-brand"><span class="br-accent">DECK</span></div>
+    <div class="ui-title" id="uiTitle"></div>
+    <div class="ui-counter">
+      <span id="curSec">00</span><span class="slash">/</span><span class="total">00</span>
+    </div>
+    <div class="ui-dots" id="uiDots"></div>
+    <div class="ui-hint" id="uiHint">→ next · ← prev · S storyboard · F fullscreen · R replay · P presenter · E edit toggle</div>
+  </div>
+
+  <!-- Stagecraft runtime: engine + helpers + transitions + all components + edit-mode -->
+  <script src="node_modules/stagecraft/dist/stagecraft.bundle.js"></script>
+
+  <!-- Deck manifest: order + transitions -->
+  <script src="stagecraft.config.js"></script>
+</body>
+</html>

package/starter/slides/00-title.js

@@ -0,0 +1,12 @@
+'use strict';
+
+Stage.register(Stage.KineticText({
+  section: 1,
+  title: '01 · Welcome',
+  pace: 700,
+  lines: [
+    { text: 'A new deck.',         color: 'fg' },
+    { text: 'Ready to be built.',  color: 'dim' },
+    { text: 'Press → to begin.',   color: 'accent', pause: 600 }
+  ]
+}));

package/starter/stagecraft.config.js

@@ -0,0 +1,8 @@
+'use strict';
+
+Stage.deck({
+  theme: 'phosphor',
+  slides: [
+    { src: 'slides/00-title.js' }
+  ]
+});

package/themes/brand/base.css

@@ -0,0 +1,4 @@
+@import url('../phosphor/base.css');
+
+/* Brand: cleaner, no film grain */
+:root[data-theme="brand"] body::after { display: none; }

package/themes/brand/components-business.css

@@ -0,0 +1,173 @@
+/* Stagecraft — Brand theme: business component overrides.
+ * Pricing · Testimonial · TeamGrid · Agenda · Checklist · Steps ·
+ * CTA · Callout · Tip · BeforeAfter */
+
+@import url('../phosphor/components-business.css');
+
+/* ===========================================================================
+ * Pricing — featured tier keeps the accent border but loses the halo
+ * ===========================================================================*/
+:root[data-theme="brand"] .pricing-tier {
+  background: var(--bg-elevated);
+  border: 1px solid var(--dim-2);
+}
+:root[data-theme="brand"] .pricing-tier--featured {
+  border: 1px solid var(--accent);
+  box-shadow: none;
+  /* keep the slight scale lift — it's structural, not flashy */
+}
+:root[data-theme="brand"] .pricing-badge {
+  box-shadow: none;
+  background: var(--accent);
+  color: var(--bg);
+  font-weight: 600;
+}
+:root[data-theme="brand"] .pricing-name { letter-spacing: 0.1em; }
+:root[data-theme="brand"] .pricing-price { font-weight: 600; }
+:root[data-theme="brand"] .pricing-tier--featured .pricing-price {
+  color: var(--accent);
+  text-shadow: none;
+}
+
+/* ===========================================================================
+ * Testimonial — round photo with thin border, no glow ring
+ * ===========================================================================*/
+:root[data-theme="brand"] .testimonial-photo-wrap {
+  box-shadow: none;
+  border: 1px solid var(--dim-2);
+}
+:root[data-theme="brand"] .testimonial-mark {
+  color: var(--accent);
+  text-shadow: none;
+  font-weight: 300;
+}
+:root[data-theme="brand"] .testimonial-quote {
+  font-style: normal;       /* schlicht */
+  font-weight: 500;
+}
+:root[data-theme="brand"] .testimonial-author { font-weight: 600; }
+
+/* ===========================================================================
+ * TeamGrid — flat cards
+ * ===========================================================================*/
+:root[data-theme="brand"] .team-card {
+  background: var(--bg-elevated);
+  border: 1px solid var(--dim-2);
+}
+:root[data-theme="brand"] .team-name { font-weight: 600; }
+:root[data-theme="brand"] .team-role { letter-spacing: 0.1em; }
+
+/* ===========================================================================
+ * Agenda — strip the dot glow ring
+ * ===========================================================================*/
+:root[data-theme="brand"] .agenda-dot {
+  box-shadow: none;
+  border: 1px solid var(--accent);
+  background: var(--bg-elevated);
+}
+:root[data-theme="brand"] .agenda-label { font-weight: 600; }
+:root[data-theme="brand"] .agenda-duration { letter-spacing: 0.1em; }
+
+/* ===========================================================================
+ * Checklist — flat checkbox accent, no glow
+ * ===========================================================================*/
+:root[data-theme="brand"] .checklist-item {
+  background: var(--bg-elevated);
+  border: 1px solid var(--dim-2);
+}
+:root[data-theme="brand"] .checklist-item.is-done {
+  border-color: color-mix(in srgb, var(--accent) 40%, var(--dim-2));
+}
+:root[data-theme="brand"] .checklist-item.is-done .checklist-box {
+  text-shadow: none;
+}
+:root[data-theme="brand"] .checklist-text { font-weight: 500; }
+
+/* ===========================================================================
+ * Steps — flat numerals
+ * ===========================================================================*/
+:root[data-theme="brand"] .step-card {
+  background: var(--bg-elevated);
+  border: 1px solid var(--dim-2);
+}
+:root[data-theme="brand"] .step-numeral {
+  color: var(--accent);
+  text-shadow: none;
+  font-weight: 600;
+}
+:root[data-theme="brand"] .step-label { font-weight: 600; }
+
+/* ===========================================================================
+ * CTA — accent card without the soft gradient and halo
+ * ===========================================================================*/
+:root[data-theme="brand"] .cta {
+  background: var(--bg-elevated);
+  border: 1px solid var(--dim-2);
+}
+:root[data-theme="brand"] .cta--accent {
+  border-color: var(--accent);
+  background: var(--bg-elevated);
+  box-shadow: none;
+}
+:root[data-theme="brand"] .cta-headline { font-weight: 600; }
+:root[data-theme="brand"] .cta-button {
+  letter-spacing: 0.08em;
+  font-weight: 600;
+}
+:root[data-theme="brand"] .cta--accent .cta-button {
+  background: var(--accent);
+  color: var(--bg);
+  box-shadow: none;
+}
+
+/* ===========================================================================
+ * Callout & Tip — keep semantic accent borders, drop colored gradients
+ * ===========================================================================*/
+:root[data-theme="brand"] .callout {
+  background: var(--bg-elevated);
+}
+:root[data-theme="brand"] .callout--info,
+:root[data-theme="brand"] .callout--tip,
+:root[data-theme="brand"] .callout--warning,
+:root[data-theme="brand"] .callout--danger,
+:root[data-theme="brand"] .callout--success {
+  /* Override the linear-gradient backgrounds — too colorful for boardroom. */
+  background: var(--bg-elevated);
+}
+:root[data-theme="brand"] .callout--success .callout-icon {
+  text-shadow: none;
+}
+:root[data-theme="brand"] .callout-heading { font-weight: 600; }
+
+:root[data-theme="brand"] .tip {
+  background: var(--bg-elevated);
+  border: 1px solid var(--dim-2);
+}
+:root[data-theme="brand"] .tip--success {
+  background: var(--bg-elevated);
+  border-color: var(--accent);
+}
+:root[data-theme="brand"] .tip--success .tip-icon { text-shadow: none; }
+
+/* ===========================================================================
+ * BeforeAfter — clean dividers, no accent glow on arrow / divider
+ * ===========================================================================*/
+:root[data-theme="brand"] .ba-col {
+  background: var(--bg-elevated);
+  border: 1px solid var(--dim-2);
+}
+:root[data-theme="brand"] .ba-col.ba-after {
+  border-color: color-mix(in srgb, var(--accent) 40%, var(--dim-2));
+}
+:root[data-theme="brand"] .ba-arrow {
+  color: var(--accent);
+  text-shadow: none;
+}
+:root[data-theme="brand"] .ba-tag--accent {
+  box-shadow: none;
+}
+:root[data-theme="brand"] .before-after--image .ba-divider {
+  background: var(--accent);
+  box-shadow: none;
+  transform: none;          /* drop the skew — boardroom flat */
+}

package/themes/brand/components-chart.css

@@ -0,0 +1,65 @@
+/* Stagecraft — Brand theme: chart component overrides.
+ * Matrix2x2 · BarChart · Progress · ProcessFlow · Venn */
+
+@import url('../phosphor/components-chart.css');
+
+/* ===========================================================================
+ * Matrix2x2 — desaturated dim quadrants, active quadrant gets clean accent
+ * ===========================================================================*/
+:root[data-theme="brand"] .matrix2x2 .quadrant.active {
+  background: color-mix(in srgb, var(--q-color, var(--accent)) 6%, var(--bg));
+  box-shadow: inset 0 0 0 1px var(--q-color, var(--accent));
+}
+:root[data-theme="brand"] .matrix2x2 .q-label { font-weight: 600; }
+
+/* ===========================================================================
+ * BarChart — flat fills, no drop shadow on bars
+ * ===========================================================================*/
+:root[data-theme="brand"] .barchart .bar-fill {
+  box-shadow: none;
+}
+:root[data-theme="brand"] .barchart .bar-label,
+:root[data-theme="brand"] .barchart .bar-value {
+  font-family: var(--body);
+  font-weight: 500;
+}
+
+/* ===========================================================================
+ * Progress — same: flat track + flat fill
+ * ===========================================================================*/
+:root[data-theme="brand"] .progress-fill {
+  box-shadow: none;
+}
+:root[data-theme="brand"] .progress-track {
+  border-radius: 0;     /* squarer, more corporate */
+}
+:root[data-theme="brand"] .progress-label,
+:root[data-theme="brand"] .progress-value {
+  font-family: var(--body);
+  font-weight: 500;
+}
+
+/* ===========================================================================
+ * ProcessFlow — kill the arrow text-shadow pulse glow
+ * ===========================================================================*/
+:root[data-theme="brand"] .processflow .pf-step {
+  background: var(--bg-elevated);
+  border: 1px solid var(--dim-2);
+}
+:root[data-theme="brand"] .processflow .pf-step.accent { border-color: var(--accent); }
+:root[data-theme="brand"] .processflow .pf-step.amber  { border-color: color-mix(in srgb, var(--amber) 50%, var(--dim-2)); }
+:root[data-theme="brand"] .processflow .pf-step.blue   { border-color: color-mix(in srgb, var(--blue) 50%, var(--dim-2)); }
+:root[data-theme="brand"] .processflow .pf-step.red    { border-color: color-mix(in srgb, var(--red) 50%, var(--dim-2)); }
+:root[data-theme="brand"] .processflow .pf-label { font-weight: 600; }
+:root[data-theme="brand"] .processflow .pf-arrow.pulse {
+  animation: none;        /* no flashy pulse */
+}
+
+/* ===========================================================================
+ * Venn — keep SVG geometry, tone fill opacity down slightly
+ * ===========================================================================*/
+:root[data-theme="brand"] .venn .v-circle {
+  fill-opacity: 0.14;
+  stroke-width: 1.5;
+}
+:root[data-theme="brand"] .venn .v-label.set { font-weight: 600; }