@deckio/deck-engine 0.1.0

package/scripts/init-project.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * deck-engine init — provisions Copilot skills and state into a deck project.
+ *
+ * Copies .github/skills/ from the engine package and bootstraps
+ * .github/memory/state.md with project metadata from deck.config.js.
+ *
+ * Usage:
+ *   node node_modules/@deckio/deck-engine/scripts/init-project.mjs
+ *   npx deck-init   (if bin is configured)
+ *
+ * Idempotent — safe to re-run. Updates skills, preserves state.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, copyFileSync, rmSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const engineRoot = join(__dirname, '..')
+const projectRoot = process.cwd()
+
+// ── Discover project metadata from deck.config.js ──
+
+function readProjectMeta() {
+  const configPath = join(projectRoot, 'deck.config.js')
+  if (!existsSync(configPath)) {
+    console.error('❌ No deck.config.js found in', projectRoot)
+    process.exit(1)
+  }
+  const content = readFileSync(configPath, 'utf-8')
+  const str = (key) => {
+    const m = content.match(new RegExp(`${key}:\\s*['"\`]([^'"\`]+)['"\`]`))
+    return m ? m[1] : null
+  }
+  return {
+    id: str('id') || 'unknown',
+    title: str('title') || 'Deck Project',
+  }
+}
+
+// ── Copy skills ──
+
+function copySkills() {
+  const srcSkills = join(engineRoot, 'skills')
+  if (!existsSync(srcSkills)) {
+    console.warn('⚠️  No skills directory in engine package')
+    return 0
+  }
+
+  const destSkills = join(projectRoot, '.github', 'skills')
+  let count = 0
+
+  // Collect engine skill names to detect stale skills
+  const engineSkillNames = new Set()
+  for (const entry of readdirSync(srcSkills, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const skillFile = join(srcSkills, entry.name, 'SKILL.md')
+    if (!existsSync(skillFile)) continue
+    engineSkillNames.add(entry.name)
+
+    const destDir = join(destSkills, entry.name)
+    mkdirSync(destDir, { recursive: true })
+    copyFileSync(skillFile, join(destDir, 'SKILL.md'))
+    count++
+  }
+
+  // Remove stale skills no longer in the engine
+  if (existsSync(destSkills)) {
+    for (const entry of readdirSync(destSkills, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      if (!engineSkillNames.has(entry.name)) {
+        rmSync(join(destSkills, entry.name), { recursive: true, force: true })
+        console.log(`   Removed stale skill: ${entry.name}`)
+      }
+    }
+  }
+
+  return count
+}
+
+// ── Copy instructions ──
+
+function copyInstructions() {
+  const srcInstructions = join(engineRoot, 'instructions')
+  if (!existsSync(srcInstructions)) {
+    console.warn('⚠️  No instructions directory in engine package')
+    return 0
+  }
+
+  const destInstructions = join(projectRoot, '.github', 'instructions')
+  mkdirSync(destInstructions, { recursive: true })
+  let count = 0
+
+  // Collect engine instruction names to detect stale instructions
+  const engineInstrNames = new Set()
+  for (const entry of readdirSync(srcInstructions, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.instructions.md')) continue
+    engineInstrNames.add(entry.name)
+    copyFileSync(
+      join(srcInstructions, entry.name),
+      join(destInstructions, entry.name)
+    )
+    count++
+  }
+
+  // Remove stale instructions no longer in the engine
+  for (const entry of readdirSync(destInstructions, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.instructions.md')) continue
+    if (!engineInstrNames.has(entry.name)) {
+      rmSync(join(destInstructions, entry.name), { force: true })
+      console.log(`   Removed stale instruction: ${entry.name}`)
+    }
+  }
+
+  return count
+}
+
+// ── Copy AGENTS.md ──
+
+function copyAgentsMd() {
+  const src = join(engineRoot, 'instructions', 'AGENTS.md')
+  if (!existsSync(src)) return false
+  copyFileSync(src, join(projectRoot, 'AGENTS.md'))
+  return true
+}
+
+// ── Bootstrap state.md ──
+
+function bootstrapState(meta) {
+  const stateDir = join(projectRoot, '.github', 'memory')
+  const statePath = join(stateDir, 'state.md')
+
+  // Don't overwrite existing state (preserves user's port/url config)
+  if (existsSync(statePath)) {
+    console.log('   state.md already exists — preserved')
+    return
+  }
+
+  mkdirSync(stateDir, { recursive: true })
+  const content = `# Deck State
+
+## Project
+id: ${meta.id}
+title: ${meta.title}
+
+## Dev Server
+port: 5173
+url: http://localhost:5173/
+`
+  writeFileSync(statePath, content, 'utf-8')
+  console.log('   Created .github/memory/state.md')
+}
+
+// ── Create eyes directory ──
+
+function createEyesDir() {
+  const eyesDir = join(projectRoot, '.github', 'eyes')
+  mkdirSync(eyesDir, { recursive: true })
+
+  // Add to .gitignore if not already there
+  const gitignorePath = join(projectRoot, '.gitignore')
+  if (existsSync(gitignorePath)) {
+    const gitignore = readFileSync(gitignorePath, 'utf-8')
+    if (!gitignore.includes('.github/eyes')) {
+      writeFileSync(gitignorePath, gitignore.trimEnd() + '\n.github/eyes/\n', 'utf-8')
+      console.log('   Added .github/eyes/ to .gitignore')
+    }
+  }
+}
+
+function ensureVSCodeSettings() {
+  const vscodeDir = join(projectRoot, '.vscode')
+  const settingsPath = join(vscodeDir, 'settings.json')
+
+  mkdirSync(vscodeDir, { recursive: true })
+
+  let settings = {}
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'))
+    } catch {
+      console.warn('⚠️  Could not parse .vscode/settings.json — leaving it unchanged')
+      return
+    }
+  }
+
+  if (settings['simpleBrowser.useIntegratedBrowser'] === true) {
+    return
+  }
+
+  settings['simpleBrowser.useIntegratedBrowser'] = true
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8')
+  console.log('   Ensured .vscode/settings.json uses the integrated browser')
+}
+
+// ── Main ──
+
+const meta = readProjectMeta()
+console.log(`\n🎯 Initializing deck project: ${meta.title} (${meta.id})`)
+
+const skillCount = copySkills()
+console.log(`   Copied ${skillCount} Copilot skills to .github/skills/`)
+
+const instrCount = copyInstructions()
+console.log(`   Copied ${instrCount} Copilot instructions to .github/instructions/`)
+
+const agentsCopied = copyAgentsMd()
+if (agentsCopied) console.log('   Copied AGENTS.md to project root')
+
+bootstrapState(meta)
+createEyesDir()
+ensureVSCodeSettings()
+
+console.log(`\n✅ Done. Run \`copilot --yolo\` to start editing with Copilot skills.\n`)

package/skills/deck-add-slide/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: deck-add-slide
+description: Guide for adding a new slide to a deck project. Use this when asked to create, add, or build a new slide component.
+---
+
+# Adding a Slide to a Deck Project
+
+## A. Slide Component Structure (mandatory skeleton)
+
+Every slide **must** follow this structure:
+
+```jsx
+import { BottomBar, Slide } from '@deckio/deck-engine'
+import styles from './MyNewSlide.module.css'
+
+export default function MyNewSlide({ index, project }) {
+  return (
+    <Slide index={index} className={styles.myNewSlide}>
+      {/* 1. Decorative elements — always first */}
+      <div className="accent-bar" />
+      <div className={`orb ${styles.orb1}`} />
+      <div className={`orb ${styles.orb2}`} />
+
+      {/* 2. Content area — vertically centered */}
+      <div className={`${styles.body} content-frame content-gutter`}>
+        {/* Slide content */}
+      </div>
+
+      {/* 3. Footer — always last child */}
+      <BottomBar text="Project Footer Text" />
+    </Slide>
+  )
+}
+```
+
+### Mandatory elements (in order inside `<Slide>`):
+
+1. **`<div className="accent-bar" />`** — Left gradient accent bar. Include on every slide.
+2. **Orbs** — 2–4 `<div className={\`orb ${styles.orbN}\`} />` for ambient background glow.
+3. **Content wrapper** — `<div className="content-frame content-gutter">` constrains width to `1280px` and adds `72px` horizontal padding. **All visible content goes inside this wrapper.**
+4. **`<BottomBar text="..." />`** — Sticky footer, always the last child. The `text` must match the project's convention (check existing slides).
+
+### Import paths (standalone project):
+
+| Resource | Import Path |
+|---|---|
+| `Slide`, `BottomBar`, `Navigation`, `SlideProvider`, `useSlides` | `'@deckio/deck-engine'` |
+| `GenericThankYouSlide` | `'@deckio/deck-engine'` |
+| Data / logos | `'../data/<file>'` |
+
+---
+
+## B. CSS Module Rules
+
+Create a companion `.module.css` file matching the JSX filename (e.g., `MyNewSlide.module.css`).
+
+### Required root class properties
+
+```css
+.myNewSlide {
+  background: var(--bg-deep);
+  padding: 0 0 44px 0;
+}
+```
+
+- `background: var(--bg-deep)` — dark background on every slide
+- `padding: 0 0 44px 0` — reserves space for the 44px BottomBar
+
+The engine's `.slide` class provides `flex-direction: column`, `justify-content: center`, `align-items: stretch`, and `overflow: hidden` by default. It 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 (standard 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. Inner elements within the body should also avoid `flex: 1` unless they genuinely need to fill remaining space within the body.
+
+### Available CSS custom properties
+
+```
+--bg-deep: #080b10       --surface: #161b22      --border: #30363d
+--text: #e6edf3          --text-muted: #8b949e   --accent: #58a6ff
+--blue-glow: #1f6feb     --purple: #bc8cff       --purple-deep: #6e40c9
+--pink: #f778ba          --cyan: #56d4dd         --green: #3fb950
+--orange: #d29922
+```
+
+### Available global CSS classes (no import needed)
+
+| Class | Purpose |
+|---|---|
+| `accent-bar` | Left gradient accent bar |
+| `orb` | Base decorative orb (absolute, rounded, blur, opacity) |
+| `grid-dots` | Dot grid pattern (200×200px) |
+| `content-frame` | Width constraint to `1280px`, centered |
+| `content-gutter` | `72px` left/right padding |
+
+---
+
+## C. Typography Conventions
+
+| Element | Size | Weight | Spacing | Usage |
+|---|---|---|---|---|
+| `h1` | `clamp(42px, 5vw, 72px)` | 900 | `-2px` | Cover slides only |
+| `h2` | `clamp(28px, 3.2vw, 36px)` | 700 | `-0.8px` | Main slide heading |
+| `h3` | `16px–20px` | 700 | `-0.3px` | Card titles |
+| Subtitle | `17px` | 300–400 | — | `color: var(--text-muted)`, below heading |
+| Body text | `13px–14px` | 400 | — | `color: var(--text-muted)` |
+| Badge/label | `10px–11px` | 600–700 | `1.5px` | Uppercase, rounded bg |
+
+---
+
+## D. Content Layout Patterns
+
+### Card grid
+```css
+.cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 24px; }
+```
+
+### Standard card
+```css
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 16px;
+  padding: 24px;
+  overflow: hidden;
+  transition: transform 0.3s ease, border-color 0.3s ease;
+}
+.card::before {
+  content: '';
+  position: absolute;
+  top: 0; left: 0; right: 0; height: 3px;
+  background: linear-gradient(90deg, var(--purple), var(--accent));
+  opacity: 0.6;
+}
+```
+
+---
+
+## E. Registration in deck.config.js
+
+After creating the slide files, register the slide in `deck.config.js`:
+
+1. **Add an import** at the top: `import MyNewSlide from './src/slides/MyNewSlide.jsx'`
+2. **Add the component** to the `slides` array at the desired position.
+
+The generic `App.jsx` renders slides from this array, passing `index` as a prop automatically. **You do NOT need to manage index numbers manually** — they are assigned by array position.
+
+### Example: adding before ThankYou
+
+```js
+import MyNewSlide from './src/slides/MyNewSlide.jsx'
+// ... other imports
+
+export default {
+  // ... metadata
+  slides: [
+    CoverSlide,
+    // ... existing slides
+    MyNewSlide,        // ← insert here
+    ThankYouSlide,     // stays last
+  ],
+}
+```
+
+---
+
+## F. 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. Follow these limits:
+
+| Layout | Max items | Notes |
+|--------|-----------|-------|
+| Cards (3-col grid) | 6 (2 rows) | Reduce card padding if tight |
+| Cards (2-col grid) | 4 (2 rows) | Preferred for detailed cards |
+| Timeline / event list | 3–4 items | Use compact card height for 4 |
+| Bullet points | 6–8 | Depends on line length |
+| Full-width content blocks | 2–3 | E.g. quote + detail section |
+
+**When content exceeds limits**, split across multiple slides rather than cramming.
+
+---
+
+## G. Anti-Patterns to Avoid
+
+1. **Missing `accent-bar`** — include on every slide.
+2. **Missing `content-frame content-gutter`** — content will be full-width without standard margins.
+3. **Missing `BottomBar`** — every slide needs it as the last child.
+4. **String paths for images** — always use `import logo from '../data/...'` (Vite resolves to URL).
+5. **Missing `padding: 0 0 44px 0`** on the slide root CSS class — content will overlap the BottomBar.
+6. **Inconsistent `BottomBar text`** — check existing slides and match their footer text.
+7. **Using `flex: 1` on body wrapper** — defeats vertical centering; the body should size to its content.
+8. **Adding `flex-direction: column` on slide root** — already provided by the engine's `.slide` class.
+9. **Overloading a slide** — if the dev server shows a red dashed border, the slide has too much content. Split into multiple slides.
+
+---
+
+## H. Complete Step-by-Step
+
+1. **Create** `src/slides/<SlideName>Slide.jsx` following the mandatory skeleton (section A).
+2. **Create** `src/slides/<SlideName>Slide.module.css` with required root properties (section B).
+3. **Register** in `deck.config.js` — add import + add to `slides` array (section E).
+4. **Verify** — the dev server hot-reloads automatically. Navigate to the new slide and check layout.
+
+### Quick checklist
+
+- [ ] Created `<SlideName>Slide.jsx` with Slide, accent-bar, orbs, content-frame, BottomBar
+- [ ] Created `<SlideName>Slide.module.css` with `background: var(--bg-deep)`, `padding: 0 0 44px 0`, body wrapper (no `flex: 1`)
+- [ ] Import added to `deck.config.js`
+- [ ] Component added to `slides` array at correct position
+- [ ] `BottomBar text` matches project convention

package/skills/deck-delete-slide/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: deck-delete-slide
+description: Guide for removing a slide from a deck project. Use this when asked to delete, remove, or drop a slide.
+---
+
+# Removing a Slide from a Deck Project
+
+## Step 1: Identify the slide to remove
+
+Open `deck.config.js` and review the `slides` array to see all slides and their order. If the user didn't specify which slide to remove, list them so the user can choose.
+
+## Step 2: Remove from deck.config.js
+
+1. **Remove the import statement** for the slide being deleted.
+2. **Remove the component** from the `slides` array.
+
+No index management is needed — the generic `App.jsx` assigns indexes by array position automatically.
+
+## Step 3: Delete the slide files
+
+Delete from `src/slides/`:
+
+- `<SlideName>Slide.jsx`
+- `<SlideName>Slide.module.css`
+
+**Do not delete** shared slides from `@deckio/deck-engine` (like `GenericThankYouSlide`) — only remove the import.
+
+## Step 4: Check for references
+
+Search `src/slides/` for any remaining references to the deleted slide:
+
+- Other slides that import or reference the deleted component
+- Data files specific to the deleted slide (if any)
+- Remove any orphaned references
+
+## Step 5: Verify
+
+The dev server hot-reloads automatically. Navigate through all slides and confirm:
+
+- The deleted slide no longer appears
+- All remaining slides are navigable (← → arrows, keyboard)
+- Progress bar reflects the correct new total
+- No console errors
+
+## Quick checklist
+
+- [ ] Removed import from `deck.config.js`
+- [ ] Removed component from `slides` array
+- [ ] Deleted slide `.jsx` and `.module.css` files
+- [ ] No orphaned references to the deleted slide
+- [ ] No console errors, all slides navigable

package/skills/deck-generate-image/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: deck-generate-image
+description: Generate images (icons, illustrations, diagrams) using chatgpt-image-latest for use in slide components. Use this when a slide needs a visual element too complex for pure HTML/CSS.
+---
+
+# Generate Images for Slides
+
+Generate images via the OpenAI **Image API** with `chatgpt-image-latest` for specific visual elements within slides.
+
+> If `chatgpt-image-latest` returns a 403, pass `--model gpt-image-1.5` as a fallback.
+
+## When to use
+
+- A slide needs an **icon or illustration** that doesn't exist in the codebase.
+- A sketch element is too detailed to reproduce with CSS.
+- The user explicitly asks for a generated graphic.
+
+## When NOT to use
+
+- For entire slides — use **deck-add-slide** instead.
+- For simple shapes — use CSS or inline SVG.
+- For logos or photos — source them directly.
+
+## Prerequisites
+
+The `OPENAI_API_KEY` must be set. Create/edit `.env` in the project root:
+
+```
+OPENAI_API_KEY=sk-proj-...
+```
+
+## Workflow
+
+### Step 1 — Craft the prompt
+
+Write a detailed prompt including:
+
+- **Subject** — what the image depicts.
+- **Style** — flat icon, line art, illustration, isometric, etc.
+- **Colors** — match the design system: `#0d1117` (bg-deep), `#58a6ff` (accent), `#3fb950` (green), `#bc8cff` (purple).
+- **Background** — almost always "transparent background".
+- **Aspect ratio** — square (1024x1024) for icons, wide (1536x1024) for banners.
+
+### Step 2 — Generate
+
+Run from the project root:
+
+```bash
+node node_modules/@deckio/deck-engine/scripts/generate-image.mjs --prompt "your prompt" --name my-icon
+node node_modules/@deckio/deck-engine/scripts/generate-image.mjs --prompt "..." --name hero --size 1536x1024
+```
+
+| Flag | Description | Default |
+|---|---|---|
+| `--prompt` | Image description (required) | — |
+| `--name` | Filename without extension (required) | — |
+| `--size` | `1024x1024`, `1536x1024`, `1024x1536`, `auto` | `1024x1024` |
+| `--quality` | `low`, `medium`, `high`, `auto` | `auto` |
+| `--model` | OpenAI model | `chatgpt-image-latest` |
+
+Images are saved to `src/data/generated/`.
+
+### Step 3 — Use in a slide
+
+```jsx
+import myIcon from '../data/generated/my-icon.png'
+
+<img src={myIcon} alt="Bridge icon" style={{ width: 120, height: 120 }} />
+```
+
+### Step 4 — Iterate
+
+If the image doesn't match expectations, refine the prompt and re-run with the same `--name` to overwrite. Use **deck-eyes** to verify how it looks in the slide.
+
+## SVG alternative
+
+For simple icons, write SVG markup directly in JSX:
+
+```jsx
+<svg width="48" height="48" viewBox="0 0 48 48" fill="none">
+  <circle cx="24" cy="24" r="20" stroke="#58a6ff" strokeWidth="2" />
+</svg>
+```
+
+Prefer inline SVG for geometric shapes. Use image generation for complex illustrations.

package/skills/deck-inspect/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: deck-inspect
+description: Capture a screenshot of the deck app to visually inspect slides. Use this when asked to look at, see, view, inspect, check visually, or preview a slide.
+---
+
+# Visual Inspection — Capture a Slide Screenshot
+
+Captures a screenshot of the running deck using VS Code browser tools (Edge "Sharing with Agent").
+
+## Deciding what to capture
+
+1. **Slide** — resolve in this order:
+   - If the user said "slide 3" or "the cover slide" → map to a 1-based number.
+   - If you just created or edited a specific slide → use that slide's array position + 1.
+   - If not specified → capture slide 1.
+
+## Prerequisites
+
+The dev server must be running. Check `.github/memory/state.md` for the port. Default is `5173`.
+
+## Workflow
+
+### Step 1 — Open or reuse a browser page
+
+Check the attached browser pages for an existing deck tab. If none exists, open one:
+
+```
+open_browser_page → http://localhost:<port>/#/<project-id>
+```
+
+Read `project` and `port` from `.github/memory/state.md` if not known.
+
+### Step 2 — Navigate to the target slide
+
+The deck opens on slide 1. To reach slide N, press `ArrowRight` (N − 1) times:
+
+```js
+// run_playwright_code on the page
+for (let i = 0; i < N - 1; i++) {
+  await page.keyboard.press('ArrowRight');
+  await page.waitForTimeout(300);
+}
+```
+
+If the page is already on a different slide, navigate to slide 1 first by pressing `Home`, then advance forward.
+
+### Step 3 — Take a screenshot
+
+Use `screenshot_page` with the page ID to capture the current view. The screenshot is returned inline — no file path needed.
+
+### Step 4 — Inspect and report
+
+Study the screenshot and check for:
+- Layout alignment and spacing
+- Typography (size, weight, color)
+- Missing or broken elements
+- Color and contrast issues
+- Overflow or clipping
+
+Report any issues found to the user.