@deckio/deck-engine 0.1.0

package/components/exportDeckPptx.js

@@ -0,0 +1,127 @@
+/**
+ * Export deck slides to PowerPoint (.pptx) — direct download, no dialogs.
+ *
+ * Uses modern-screenshot (SVG foreignObject) + PptxGenJS.
+ * Each slide is captured as a full-bleed image placed on a 10×5.625″ slide (16:9).
+ */
+
+const PAGE_W = 1920
+const PAGE_H = 1080
+const SETTLE_MS = 600
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms))
+
+async function waitForPaint() {
+  await new Promise((r) => requestAnimationFrame(() => r()))
+  await new Promise((r) => requestAnimationFrame(() => r()))
+}
+
+function sanitize(v) {
+  return String(v || 'deck').trim().toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'deck'
+}
+
+function buildFileName({ project, selectedCustomer }) {
+  const base = selectedCustomer
+    ? `${selectedCustomer} ${document.title || project || 'deck'}`
+    : document.title || project || 'deck'
+  return `${sanitize(base)}.pptx`
+}
+
+function pauseAnimations(slide) {
+  const undo = []
+  const pause = (el) => {
+    const orig = el.style.animationPlayState
+    el.style.animationPlayState = 'paused'
+    undo.push(() => { el.style.animationPlayState = orig })
+  }
+  pause(slide)
+  slide.querySelectorAll('*').forEach(pause)
+  return () => { for (let i = undo.length - 1; i >= 0; i--) undo[i]() }
+}
+
+export async function exportDeckPptx({
+  current,
+  goTo,
+  project,
+  selectedCustomer,
+  totalSlides,
+  onProgress,
+}) {
+  const deck = document.querySelector('.deck')
+  const slides = Array.from(deck?.querySelectorAll('.slide') || [])
+  if (!deck || slides.length === 0) throw new Error('No slides found')
+
+  const [{ domToPng }, PptxGenJS] = await Promise.all([
+    import('modern-screenshot'),
+    import('pptxgenjs'),
+  ])
+  const Pptx = PptxGenJS.default || PptxGenJS
+
+  const bg = getComputedStyle(document.documentElement)
+    .getPropertyValue('--background').trim() || '#080b10'
+  const scale = Math.min(window.devicePixelRatio || 1, 2)
+
+  const pptx = new Pptx()
+  pptx.defineLayout({ name: 'WIDE', width: 10, height: 5.625 })
+  pptx.layout = 'WIDE'
+
+  if (document.fonts?.ready) await document.fonts.ready
+
+  const origDeckCss = deck.style.cssText
+  deck.style.width = `${PAGE_W}px`
+  deck.style.height = `${PAGE_H}px`
+  await waitForPaint()
+  await wait(SETTLE_MS)
+
+  try {
+    for (let i = 0; i < totalSlides; i++) {
+      onProgress?.({ current: i + 1, total: totalSlides })
+      goTo(i)
+      await waitForPaint()
+      await wait(SETTLE_MS)
+
+      const active = document.querySelector('.slide.active') || slides[i]
+      if (!active) throw new Error(`Slide ${i + 1} not found`)
+
+      const restore = pauseAnimations(active)
+      await waitForPaint()
+
+      let dataUrl
+      try {
+        dataUrl = await domToPng(active, {
+          width: PAGE_W,
+          height: PAGE_H,
+          backgroundColor: bg,
+          scale,
+          style: {
+            opacity: '1',
+            transform: 'none',
+            transition: 'none',
+          },
+        })
+      } finally {
+        restore()
+      }
+
+      const slide = pptx.addSlide()
+      slide.background = { color: bg.replace('#', '') }
+      slide.addImage({
+        data: dataUrl,
+        x: 0,
+        y: 0,
+        w: '100%',
+        h: '100%',
+      })
+    }
+  } finally {
+    deck.style.cssText = origDeckCss
+    goTo(current)
+    await waitForPaint()
+  }
+
+  const fileName = buildFileName({ project, selectedCustomer })
+  await pptx.writeFile({ fileName })
+
+  return { fileName }
+}

package/context/SlideContext.jsx

@@ -0,0 +1,190 @@
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useEffect,
+} from 'react'
+
+/*  ╔══════════════════════════════════════════════════════════════╗
+ *  ║                                                              ║
+ *  ║   ▂▃▅▇█  S L I D E   C O N T E X T  █▇▅▃▂                  ║
+ *  ║                                                              ║
+ *  ║   Central state for slide navigation, persistence,           ║
+ *  ║   keyboard / touch input, and customer selection.            ║
+ *  ║                                                              ║
+ *  ╚══════════════════════════════════════════════════════════════╝  */
+
+const SlideContext = createContext()
+
+/*  ┌─────────────────────────────────────────────────────────────┐
+ *  │  ◆  H E L P E R S                                          │
+ *  └─────────────────────────────────────────────────────────────┘  */
+
+/**
+ * Recover the last-viewed slide from sessionStorage.
+ * Survives Vite HMR so you stay on the same slide during dev.
+ *
+ *   sessionStorage key format:  slide:<project>
+ *   returns 0 when nothing stored or value is out of range.
+ */
+function getStoredSlide(project, totalSlides) {
+  try {
+    const idx = parseInt(sessionStorage.getItem(`slide:${project}`), 10)
+    return Number.isFinite(idx) && idx >= 0 && idx < totalSlides ? idx : 0
+  } catch {
+    return 0
+  }
+}
+
+/*  ╭──────────────────────────────────────────────────────────────╮
+ *  │  ◈  P R O V I D E R                                         │
+ *  ╰──────────────────────────────────────────────────────────────╯  */
+
+const DEFAULT_THEME = 'dark'
+
+export function SlideProvider({ children, totalSlides, project, slides, theme }) {
+  const [current, setCurrent] = useState(() =>
+    getStoredSlide(project, totalSlides),
+  )
+  const [selectedCustomer, setSelectedCustomer] = useState(null)
+  const [activeTheme, setActiveTheme] = useState(theme || DEFAULT_THEME)
+
+  /*  🎨 ─────────────────────────────────────────────
+   *  │  Theme → data-theme on <html> for CSS hooks  │
+   *  ───────────────────────────────────────── 🎨   */
+
+  useEffect(() => {
+    document.documentElement.setAttribute('data-theme', activeTheme)
+    return () => document.documentElement.removeAttribute('data-theme')
+  }, [activeTheme])
+
+  // Sync if the theme prop changes at runtime (e.g. HMR / config reload)
+  useEffect(() => {
+    if (theme && theme !== activeTheme) setActiveTheme(theme)
+  }, [theme])
+
+  /*  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+   *  ░  Persist slide index  ─  HMR keeps position  ░
+   *  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  */
+
+  useEffect(() => {
+    try {
+      sessionStorage.setItem(`slide:${project}`, current)
+    } catch {
+      /* storage full / unavailable – ignore */
+    }
+  }, [current, project])
+
+  /*  📡 ─────────────────────────────────────────────
+   *  │  Notify parent window of slide changes        │
+   *  │  (used by deck-launcher to provide context)   │
+   *  ───────────────────────────────────────── 📡   */
+
+  useEffect(() => {
+    try {
+      if (window.parent && window.parent !== window) {
+        const slideName = slides?.[current]?.displayName || slides?.[current]?.name || ''
+        window.parent.postMessage({
+          type: 'deck:slide',
+          project,
+          slideIndex: current,
+          slideName,
+          totalSlides,
+        }, '*')
+      }
+    } catch {
+      /* cross-origin or non-iframe – ignore */
+    }
+  }, [current, project, totalSlides, slides])
+
+  /*  ▸ ▸ ▸  Navigation helpers  ◂ ◂ ◂  */
+
+  const go = useCallback(
+    (dir) => {
+      setCurrent((prev) => {
+        const next = prev + dir
+        return next < 0 || next >= totalSlides ? prev : next
+      })
+    },
+    [totalSlides],
+  )
+
+  const goTo = useCallback(
+    (idx) => {
+      if (idx >= 0 && idx < totalSlides) setCurrent(idx)
+    },
+    [totalSlides],
+  )
+
+  /*  ⌨ ─────────────────────────────────────────────────────
+   *  │  Keyboard  →  ←  Space  PageDown  PageUp  Enter    │
+   *  ───────────────────────────────────────────────── ⌨  */
+
+  useEffect(() => {
+    const handler = (e) => {
+      if (e.key === 'ArrowRight' || e.key === ' ' || e.key === 'PageDown' || e.key === 'Enter') {
+        e.preventDefault()
+        go(1)
+      }
+      if (e.key === 'ArrowLeft' || e.key === 'PageUp') {
+        e.preventDefault()
+        go(-1)
+      }
+    }
+
+    document.addEventListener('keydown', handler)
+    return () => document.removeEventListener('keydown', handler)
+  }, [go])
+
+  /*  👆 ─────────────────────────────────
+   *  │  Touch / swipe  (threshold 50px) │
+   *  ───────────────────────────── 👆   */
+
+  useEffect(() => {
+    let touchX = 0
+
+    const onStart = (e) => {
+      touchX = e.changedTouches[0].screenX
+    }
+    const onEnd = (e) => {
+      const diff = touchX - e.changedTouches[0].screenX
+      if (Math.abs(diff) > 50) go(diff > 0 ? 1 : -1)
+    }
+
+    document.addEventListener('touchstart', onStart)
+    document.addEventListener('touchend', onEnd)
+    return () => {
+      document.removeEventListener('touchstart', onStart)
+      document.removeEventListener('touchend', onEnd)
+    }
+  }, [go])
+
+  /*  ◇─────────────── render ───────────────◇  */
+
+  return (
+    <SlideContext.Provider
+      value={{
+        current,
+        totalSlides,
+        go,
+        goTo,
+        selectedCustomer,
+        setSelectedCustomer,
+        project,
+        theme: activeTheme,
+        setTheme: setActiveTheme,
+      }}
+    >
+      {children}
+    </SlideContext.Provider>
+  )
+}
+
+/*  ┌─────────────────────────────────────────────────────────────┐
+ *  │  ◆  H O O K                                                │
+ *  └─────────────────────────────────────────────────────────────┘  */
+
+export function useSlides() {
+  return useContext(SlideContext)
+}

package/index.js

@@ -0,0 +1,5 @@
+export { SlideProvider, useSlides } from './context/SlideContext.jsx'
+export { default as Slide } from './components/Slide.jsx'
+export { default as Navigation } from './components/Navigation.jsx'
+export { default as BottomBar } from './components/BottomBar.jsx'
+export { default as GenericThankYouSlide } from './slides/GenericThankYouSlide.jsx'

package/instructions/AGENTS.md

@@ -0,0 +1,26 @@
+# Deck Project
+
+This is a presentation deck built with `@deckio/deck-engine`.
+
+## Purpose
+
+Create and maintain slide-based presentations. Each project is a self-contained deck with its own theme, data, and slides.
+
+## What to do
+
+- Create, edit, and delete slides in `src/slides/`
+- Manage project data in `src/data/`
+- Register and reorder slides in `deck.config.js`
+
+## What NOT to do
+
+- Do not modify `App.jsx`, `main.jsx`, `vite.config.js`, `package.json`, or `index.html` — these are scaffolding files driven by the engine
+- Do not modify anything in `node_modules/` or the engine itself
+- Do not add dependencies without being asked
+
+## Stack
+
+- React 19, Vite, CSS Modules
+- `@deckio/deck-engine` provides: `Slide`, `BottomBar`, `Navigation`, `SlideProvider`, `useSlides`, `GenericThankYouSlide`
+- See `.github/instructions/` for detailed conventions on slide JSX, CSS modules, and deck.config.js
+- See `.github/skills/` for step-by-step workflows (e.g., adding a slide)

package/instructions/deck-config.instructions.md

@@ -0,0 +1,34 @@
+---
+description: "Use when editing deck.config.js to register slides or modify project configuration."
+applyTo: "**/deck.config.js"
+---
+
+# deck.config.js Conventions
+
+## Structure
+
+```js
+import CoverSlide from './src/slides/CoverSlide.jsx'
+import MySlide from './src/slides/MySlide.jsx'
+
+export default {
+  id: 'my-project',          // lowercase-hyphens, unique slug
+  title: 'Project Title',
+  subtitle: 'Tagline',
+  description: 'Metadata',
+  icon: '🚀',                // emoji for launcher
+  accent: '#7c3aed',         // CSS color, sets --accent
+  order: 1,                  // sort position in launcher
+  slides: [
+    CoverSlide,
+    MySlide,
+    // ThankYouSlide is typically last
+  ],
+}
+```
+
+## Registering a new slide
+
+1. Add an import at the top: `import NewSlide from './src/slides/NewSlide.jsx'`
+2. Insert the component in the `slides` array at the desired position
+3. Indices are assigned by array position — do not manage them manually

package/instructions/deck-project.instructions.md

@@ -0,0 +1,34 @@
+---
+description: "Use when working in any deck-project folder. Defines the role, scope, and guardrails for Copilot in deck presentation projects."
+applyTo: "deck-project-*/**"
+---
+
+# Deck Project Scope
+
+You are a **slide builder** for a presentation deck built with `@deckio/deck-engine`.
+
+## Your role
+
+- Create new slide components (JSX + CSS module pairs)
+- Edit existing slides
+- Manage data files in `src/data/`
+- Register / reorder slides in `deck.config.js`
+
+## Out of scope — do NOT modify
+
+- `App.jsx`, `main.jsx` — these are generic, engine-driven, identical across projects
+- `vite.config.js`, `package.json`, `index.html` — project scaffolding, don't touch
+- Anything in `node_modules/` or the deck-engine package itself
+
+## Project architecture
+
+- `deck.config.js` — single source of truth: metadata + slide array
+- `src/slides/` — one `PascalCase.jsx` + matching `.module.css` per slide
+- `src/data/` — ESM exports for logos, speakers, opportunity data, governance
+- The engine (`@deckio/deck-engine`) provides: `Slide`, `BottomBar`, `Navigation`, `SlideProvider`, `useSlides`, `GenericThankYouSlide`
+
+## Data conventions
+
+- Always use ESM imports for images: `import logo from '../data/logos/acme.png'`
+- Export data as named exports or default objects
+- Keep data files focused — one concern per file

package/instructions/slide-css.instructions.md

@@ -0,0 +1,96 @@
+---
+description: "Use when creating or editing slide CSS modules in a deck project. Enforces required properties, orb positioning, and theme variables."
+applyTo: "**/slides/**/*.module.css"
+---
+
+# Slide CSS Module Conventions
+
+## Required root class
+
+```css
+.mySlide {
+  background: var(--bg-deep);
+  padding: 0 0 44px 0;        /* reserve BottomBar height */
+}
+```
+
+The engine's `.slide` class already sets `flex-direction: column`, `justify-content: center`, and `overflow: hidden`. The engine also sets `flex-grow: 0` on all direct slide children, so **content stays at its natural height and is vertically centered by default** — building from the center outward. No scrolling is allowed.
+
+For dense slides that need top-alignment, override with `justify-content: flex-start`.
+
+## Orb positioning recipe
+
+```css
+.orb1 {
+  width: 420px; height: 420px;
+  top: -100px; right: -60px;
+  background: radial-gradient(circle at 40% 40%, var(--accent), var(--blue-glow) 50%, transparent 70%);
+}
+.orb2 {
+  width: 320px; height: 320px;
+  bottom: -40px; right: 100px;
+  background: radial-gradient(circle at 50% 50%, var(--purple-deep), rgba(110,64,201,0.25) 60%, transparent 75%);
+}
+```
+
+## Body wrapper
+
+```css
+.body {
+  position: relative;
+  z-index: 10;
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+}
+```
+
+> **Do NOT add `flex: 1` or `flex-grow: 1`** to the body wrapper or any direct slide child — it stretches the wrapper to fill the slide and defeats the engine's built-in vertical centering. The engine sets `flex-grow: 0` on all direct slide children to ensure content builds from the center outward. Inner elements within the body wrapper should also avoid `flex: 1` unless they genuinely need to fill remaining space within the body.
+
+## Theme variables (always use these, never hard-code colors)
+
+| Variable | Value |
+|----------|-------|
+| `--bg-deep` | `#080b10` |
+| `--surface` | `#161b22` |
+| `--border` | `#30363d` |
+| `--text` | `#e6edf3` |
+| `--text-muted` | `#8b949e` |
+| `--accent` | project-specific |
+| `--blue-glow` | `#1f6feb` |
+| `--purple` | `#bc8cff` |
+| `--purple-deep` | `#6e40c9` |
+| `--pink` | `#f778ba` |
+| `--cyan` | `#56d4dd` |
+| `--green` | `#3fb950` |
+| `--orange` | `#d29922` |
+
+## Global classes (no import needed)
+
+`accent-bar`, `orb`, `grid-dots`, `content-frame`, `content-gutter`
+
+## Card pattern
+
+```css
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 16px;
+  padding: 24px;
+}
+```
+
+## Typography
+
+| Element | Size | Weight | Spacing |
+|---------|------|--------|---------|
+| h1 | `clamp(42px, 5vw, 72px)` | 900 | `-2px` |
+| h2 | `clamp(28px, 3.2vw, 36px)` | 700 | `-0.8px` |
+| h3 | `16px–20px` | 700 | `-0.3px` |
+| Subtitle | `17px` | 300–400 | — |
+| Body | `13px–14px` | 400 | — |
+| Badge | `10px–11px` | 600–700 | `1.5px` |
+
+## Content density limits
+
+Slides must never overflow the viewport. The engine shows a **red dashed border warning** in dev mode when content exceeds the slide bounds. When content doesn't fit, split across multiple slides rather than cramming. A presentation with more slides is better than one with clipped content.

package/instructions/slide-jsx.instructions.md

@@ -0,0 +1,34 @@
+---
+description: "Use when creating, editing, or reviewing slide JSX components in a deck project. Enforces the mandatory slide skeleton, imports, and anti-patterns."
+applyTo: "**/slides/**/*.jsx"
+---
+
+# Slide JSX Conventions
+
+## Imports
+
+```jsx
+import { BottomBar, Slide } from '@deckio/deck-engine'
+import styles from './MySlide.module.css'
+```
+
+## Mandatory skeleton (in order inside `<Slide>`)
+
+1. `<div className="accent-bar" />` — always first
+2. 2–4 orbs: `<div className={\`orb ${styles.orbN}\`} />`
+3. Content wrapper: `<div className={\`${styles.body} content-frame content-gutter\`}>` — all visible content here
+4. `<BottomBar text="..." />` — always last child
+
+## Props
+
+Every slide receives `{ index, project, title, subtitle }`. Pass `index` to `<Slide>`.
+
+## Available engine exports
+
+`Slide`, `BottomBar`, `Navigation`, `SlideProvider`, `useSlides`, `GenericThankYouSlide`
+
+## Anti-patterns
+
+- Never omit `accent-bar`, `content-frame content-gutter`, or `BottomBar`
+- Never use string paths for images — always `import logo from '../data/...'`
+- Never hardcode slide indices — use `useSlides().goTo()` for navigation

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@deckio/deck-engine",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deckio-art/deck-engine.git",
+    "directory": "packages/deck-engine"
+  },
+  "main": "./index.js",
+  "module": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./slides/*": "./slides/*.jsx",
+    "./components/*": "./components/*.jsx",
+    "./styles/*": "./styles/*",
+    "./themes/*": "./themes/*",
+    "./themes/theme-loader": "./themes/theme-loader.js",
+    "./vite": "./vite.js",
+    "./vite.js": "./vite.js"
+  },
+  "files": [
+    "index.js",
+    "vite.js",
+    "components",
+    "context",
+    "slides",
+    "styles",
+    "themes",
+    "scripts",
+    "skills",
+    "instructions"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm test --if-present"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.2.1",
+    "jspdf": "^3.0.3",
+    "modern-screenshot": "^4.6.8",
+    "pptxgenjs": "^3.12.0",
+    "tailwindcss": "^4.2.1"
+  },
+  "peerDependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "optionalDependencies": {
+    "puppeteer": "^24.38.0",
+    "puppeteer-core": "^24.38.0"
+  }
+}