heygen-com · vanceingalls · May 13, 2026 · May 13, 2026 · May 13, 2026 · May 14, 2026
diff --git a/.gitignore b/.gitignore
@@ -103,3 +103,10 @@ claude-design-hyperframes-video/
 .claude/worktrees/
 .claude/
 docs/superpowers/
+
+# hyperframes pick — generated picker + per-project picker data
+.hyperframes/
+
+# hyperframes pick — generated user-design template (created when DESIGN.html exists)
+/templates/
+
diff --git a/.oxfmtignore b/.oxfmtignore
@@ -0,0 +1 @@
+skills/**/deck-stage.js
diff --git a/.oxlintignore b/.oxlintignore
@@ -0,0 +1 @@
+skills/hyperframes/templates/presentations/*/deck-stage.js
diff --git a/.oxlintrc.json b/.oxlintrc.json
@@ -4,5 +4,5 @@
     "correctness": "error"
   },
   "plugins": ["react", "typescript"],
-  "ignorePatterns": ["dist/", "coverage/", "node_modules/"]
+  "ignorePatterns": ["dist/", "coverage/", "node_modules/", "skills/**/deck-stage.js"]
 }
diff --git a/docs/DESIGN-PICKER-V2-HANDOFF.md b/docs/DESIGN-PICKER-V2-HANDOFF.md
@@ -0,0 +1,87 @@
+# Design Picker V2 — Handoff
+
+## What's Done
+
+### Per-template DESIGN.html generation
+- `build-design-templates.py` generates `design.html` for all 34 templates mechanically
+- Reads each template's CSS tokens (fonts, colors, borders, shadows, radius) from `summary.html`
+- Classifies by scheme (dark/light), border style (heavy/hairline/subtle), radius
+- Dark templates → dark canvas, accent cover, hairline borders, lowercase
+- Heavy border templates → 4px solid, hard shadows, uppercase, tilted swatches
+- Each template's own fonts flow through to page design
+- Hand-crafted designs for block-frame + broadside preserved (skipped by generator)
+- All 34 templates now export bespoke DESIGN.html
+
+### Template summaries (`build-summaries.py`)
+- CSS tokens + unique slide skeletons with `{{placeholders}}`
+- Handles external CSS files (pin-and-paper)
+- Universal slide extraction across all template patterns
+- 15-79% compression vs full template HTML
+
+### Token system
+`__PRIMARY__`, `__SECONDARY__`, `__TERTIARY__`, `__ACCENT__`, `__NAME__`,
+`__SHADER_VERTEX__`, `__SHADER_FRAGMENT__`, `__SHADER_CONFIG__`, `__SHADER_SCRIPT__`,
+`__TEMPLATE_CSS__`, `__SLIDE_CARDS__`, `__DOS__`, `__DONTS__`,
+`__EASING_NAME__`, `__EASING_VALUE__`, `__CORNER_RADIUS__`, `__PADDING__`, `__GAP__`,
+`__ELEVATION__`, `__DENSITY__`, `__BG_HEADLINE__`, `__BG_TYPE__`, etc.
+
+### V2 picker scaffold (`design-picker-v2.html`)
+- Template grid overlay → select template
+- Loads design.html + applies tokens with current state
+- Click palette/motion/background sections to cycle options
+- Export button downloads resolved HTML
+- Nav rail with Template + Export buttons
+
+## What's Next
+
+### Phase 2: Better edit affordances
+- Replace click-to-cycle with dropdown/popup pickers per section
+- Palette section: swatch popup showing all palette options
+- Typography: font pair selector
+- Surface: corner radius / density / depth controls
+- Motion: easing curve picker (reuse existing custom easing UI)
+- Background: shader preset grid with live preview thumbnails
+
+### Shader integration
+- The v2 picker doesn't yet run the shader renderer in the loaded design page
+- Need to wire up `_sgShaders` (vertex/fragment GLSL) and the Three.js pipeline
+- The `__SHADER_SCRIPT__` token is currently empty — needs the full renderer script
+- The shader preview canvas (`#bg-preview-canvas`) needs the drawImage approach
+
+### CSS collision hardening
+- Use `#hf-` prefix for all picker chrome
+- Picker toolbar needs `!important` on critical properties
+- Clean up injected styles when switching templates
+- Destroy Three.js renderers on template switch to prevent GPU leaks
+
+### Font loading
+- Template fonts loaded via `<link>` injection into `<head>`
+- May need preloading strategy for smoother transitions
+
+## Architecture
+
+```
+design-picker-v2.html (shell)
+  ├── #tmpl-overlay (template grid, z-index: 1000)
+  ├── #design-page (receives resolved design.html content)
+  │   ├── <style> blocks from design.html
+  │   ├── <canvas id="design-bg"> (shader background)
+  │   ├── .rail (nav rail + edit buttons)
+  │   ├── sections: #palette, #type, #surface, #motion, #background, #guidelines, #templates
+  │   ├── <template id="tmpl-source"> (slide cards)
+  │   └── <script type="module"> (shader renderer)
+  └── #export-overlay (export textarea + download)
+
+State: { template, palette, type, easing, corners, density, depth, bg }
+Token resolution: applyTokens(rawHtml, slug, summary) → resolved HTML string
+Export: snapshot of resolved HTML (not live DOM serialization)
+```
+
+## Key Files
+- `skills/hyperframes/templates/design-picker-v2.html` — new picker
+- `skills/hyperframes/templates/design-picker.html` — old picker (keep for now)
+- `skills/hyperframes/templates/presentations/*/design.html` — 34 design templates
+- `skills/hyperframes/templates/presentations/*/summary.html` — CSS + skeletons
+- `skills/hyperframes/scripts/build-design-templates.py` — design.html generator
+- `skills/hyperframes/scripts/build-summaries.py` — summary.html generator
+- `skills/hyperframes/templates/index.json` — template metadata
diff --git a/docs/TEMPLATE-PICKER-STATUS.md b/docs/TEMPLATE-PICKER-STATUS.md
@@ -0,0 +1,179 @@
+# Template Picker — Current Status & Handoff
+
+## What This Is
+
+A visual design picker that lets users browse 34 HTML presentation templates, apply color palettes, typography, and other design tokens, then export a design.md. It replaces the original moodboard-based design picker with a template-first approach.
+
+## Architecture
+
+```
+skills/hyperframes/
+├── templates/
+│   ├── design-picker.html          ← Main picker page (Phase 1 + Phase 2)
+│   ├── template-picker.html        ← Phase 1: template grid (embedded in design-picker via iframe)
+│   └── presentations/              ← 34 tokenized HTML templates (from beautiful-html-templates)
+│       ├── 8-bit-orbit/
+│       ├── biennale-yellow/
+│       ├── studio/
+│       └── ... (34 total)
+├── scripts/
+│   ├── build-template-picker.py    ← Generates template-picker.html with injected data
+│   └── tokenize-templates.py       ← Converts templates to use --tp-* CSS variable contract
+└── references/
+    └── design-picker.md            ← Skill reference (updated with template-based flow docs)
+```
+
+## How It Works
+
+### Data Flow
+
+1. **Agent generates prompt-specific data** (palettes, text pools, prompt description)
+2. **`build-template-picker.py`** reads template index, extracts CSS color vars and `preview_html` from each template, injects data into `template-picker.html`
+3. **`design-picker.html`** embeds `template-picker.html` as Phase 1 iframe, has Phase 2 fine-tune controls
+4. Served via `python3 -m http.server`
+
+### Two Phases
+
+- **Phase 1 (Template tab)**: Grid of 34 templates. Each shows first slide as inline HTML preview. Palette bar at top re-themes all templates live. Click a template → transition animation → Phase 2.
+- **Phase 2 (Fine-tune tab)**: Selected template preview + config options (theme, palette, typography, corners, density, depth, easing, background shader) + design sections (palette swatches, type specimens, corner radius, elevation, motion).
+
+### CSS Variable Contract (`--tp-*`)
+
+All 34 templates have been tokenized with `tokenize-templates.py`. Each template's `:root` block now has:
+
+```css
+:root {
+  --tp-bg: #E9E5DB;        /* background */
+  --tp-fg: #1B2566;        /* foreground/text */
+  --tp-ac: #F1EE2E;        /* accent */
+  --tp-mt: #888888;        /* muted */
+  --tp-surface: #E9E5DB;   /* card/panel bg */
+  --tp-border: #1B2566;    /* borders */
+  --tp-hf: "Archivo";      /* headline font */
+  --tp-bf: "Instrument Serif"; /* body font */
+  --tp-mf: "monospace";    /* mono font */
+  --tp-bg-layer: none;     /* shader background slot */
+}
+```
+
+Original template variables reference these tokens:
+```css
+--paper: var(--tp-bg, #E9E5DB);
+--sun: var(--tp-ac, #F1EE2E);
+--ink: var(--tp-fg, #1B2566);
+```
+
+Hardcoded hex values throughout the CSS were also replaced with `var(--tp-*)` references (1240 total replacements across 34 templates).
+
+## What Works
+
+- [x] Template grid with 34 templates rendering inline (extracted first-slide HTML)
+- [x] Palette bar with mini type specimen chips
+- [x] Contextual text injection (prompt-specific headlines, body, stats, labels replace template placeholder text)
+- [x] Word-length matching (replacement text matches original word count)
+- [x] Phase 1 → Phase 2 transition animation (fade to black, card lift, phase slide-in)
+- [x] Phase 2 fine-tune panel with all config options (theme, palette, type, corners, density, depth, easing, background)
+- [x] Phase 2 shows palette swatches, typography specimens, corner radius, elevation, motion sections
+- [x] Back navigation (← Template tab returns to grid)
+- [x] Template Default palette clears overrides, restoring original template colors
+- [x] `--tp-*` CSS variable contract on all 34 templates
+- [x] Name-aware color role detection (variables named "sun" map to accent, "paper" to bg, etc.)
+- [x] Build script (`build-template-picker.py`) extracts preview_html with scoped CSS
+- [x] Skill reference updated (`design-picker.md`) with full template-based flow documentation
+
+## Known Bugs / Incomplete
+
+### Critical — Must Fix
+
+1. **Page won't scroll in Phase 1**. The `.phase` container has `overflow: auto` but the template-picker iframe with `position: absolute; inset: 0` creates a non-scrolling layer. The iframe content (template grid) scrolls internally but the parent page doesn't respond to scroll events. Need to either:
+   - Remove the iframe and embed the picker content directly in the DOM
+   - Or fix the iframe sizing so it doesn't need `position: absolute`
+
+2. **Some template preview cards render as black rectangles**. The `extract_preview()` function in `build-template-picker.py` uses regex to find the first slide — works for most templates but fails silently for some (returns empty/minimal HTML). Templates with unusual structure (no `.slide` class, deck-stage only, complex nesting) may not extract correctly.
+
+3. **Fine-tune palette/theme changes don't visually update the template preview**. The override code sets `--tp-*` variables on the inline template container via `style.setProperty()`, but the scoped CSS uses `.tp-{slug}` class prefix which may not inherit `:root` variables from the parent. The cascade path: `renderPreview()` → `querySelector("[class^='tp-']")` → `setProperty("--tp-bg", ...)` — this should work but hasn't been verified end-to-end since the inline rendering change.
+
+4. **Background shader options have no effect on template preview**. The Three.js shader canvas renders in the design-picker page behind the scene grid. With iframe-based templates, the canvas was invisible behind the opaque iframe. With inline templates, it SHOULD show through if the template's background is transparent — but the templates still have opaque backgrounds. Need to:
+   - Set `--tp-bg-layer` to control the background
+   - Or make template background transparent when a shader is selected, letting the canvas show through
+
+### Medium Priority
+
+5. **Producer dist files fail format checks**. `packages/producer/dist/index.js` and `public-server.js` were modified somewhere and now fail `oxfmt --check`. These are build artifacts — should be in `.gitignore` or reset.
+
+6. **Text injection doesn't work on all templates**. Templates using `<deck-stage>` with sections that don't have `.slide` class need the query `deck-stage > section, section[class]` to find text elements. Some templates still show original placeholder text.
+
+7. **React app (`template-picker-app/`) exists but is incomplete**. Started a React rewrite, reverted to vanilla. The app scaffolding is in the repo at `skills/hyperframes/template-picker-app/` with working components but missing features. Should either complete or delete.
+
+### Low Priority
+
+8. **Component extraction below hero card** not implemented. User wants actual buttons, cards, headings, tags from the selected template displayed as a specimen sheet below the main preview. This requires parsing the template DOM to identify distinct component patterns — deferred.
+
+9. **Motion templates (HyperFrames compositions)** partially built. Created restyled versions of launch video compositions (thesis × biennale-yellow, end card × biennale-yellow, save-time × bold-poster). The `<hyperframes-player>` integration for hover-to-play video cards works. Feature is disabled (empty `motion_templates` array) pending further design.
+
+## How to Test
+
+```bash
+cd /Users/vanceingalls/src/wt/hyperframes/one
+
+# Ensure templates have files (git checkout if empty)
+ls skills/hyperframes/templates/presentations/8-bit-orbit/template.html || \
+  (cd /tmp/beautiful-html-templates && git checkout -- templates/)
+
+# Generate picker for a prompt
+cat > /tmp/test-data.json << 'EOF'
+{
+  "palettes": [
+    {"name":"Default", "bg":"__DEFAULT__"},
+    {"name":"Brand Purple", "bg":"#0F0A1A", "fg":"#FFFFFF", "ac":"#7C3AED", "mt":"#9CA3AF"}
+  ],
+  "prompt_text": {
+    "headline": "MYAPP",
+    "sub": "Your Product Tagline",
+    "taglines": {"bold":"BUILD SOMETHING","editorial":"The Future","playful":"Let's go.","dark":"SHIP IT.","technical":"FROM CODE TO PROD","warm":"Made With Care"},
+    "headlines": ["Feature One","Feature Two"],
+    "body": ["Description of the product."],
+    "stats": ["10M+","99%"],
+    "statLabels": ["Users","Uptime"],
+    "labels": ["FEATURE","API"],
+    "smalls": ["Try Free","Learn More"]
+  },
+  "prompt_desc": "Product launch video",
+  "motion_templates": []
+}
+EOF
+
+# Build picker
+cat /tmp/test-data.json | python3 skills/hyperframes/scripts/build-template-picker.py \
+  --template skills/hyperframes/templates/template-picker.html \
+  --templates-dir skills/hyperframes/templates/presentations \
+  --output /tmp/test-project/.hyperframes/template-picker.html
+
+# Copy templates for serving
+cp -r skills/hyperframes/templates/presentations /tmp/test-project/templates
+
+# Generate pick-design.html (use Python — see previous session's generation script pattern)
+# ... inject ARCHITECTURES/PALETTES/TYPEPAIRS/MOODBOARDS/PROMPT into design-picker.html template
+
+# Serve
+cd /tmp/test-project && python3 -m http.server 8724
+# Open http://localhost:8724/.hyperframes/pick-design.html
+```
+
+## Key Files to Read
+
+| File | Purpose |
+|------|---------|
+| `skills/hyperframes/templates/design-picker.html` | Main picker — Phase 1 iframe + Phase 2 fine-tune. Contains `handleTemplatePick()`, `applyOverrideToIframe()`, `renderPreview()`, shader background module. ~2700 lines. |
+| `skills/hyperframes/templates/template-picker.html` | Template grid — palette bar, card rendering, text injection, transition animation. ~720 lines. Placeholders: `__PALETTES_JSON__`, `__PROMPT_TEXT_JSON__`, `__TEMPLATES_JSON__`, `__PROMPT_DESC__`. |
+| `skills/hyperframes/scripts/build-template-picker.py` | Build script — reads template index, extracts CSS vars + preview HTML, injects data. |
+| `skills/hyperframes/scripts/tokenize-templates.py` | Converts templates to `--tp-*` contract. Run once to tokenize; templates are already tokenized in repo. |
+| `skills/hyperframes/references/design-picker.md` | Skill reference — includes "Alternative: Template-based picker" section with full flow docs. |
+
+## Recommended Next Steps (Priority Order)
+
+1. **Fix scrolling** — The #1 blocker. Either embed picker content directly (no iframe) or fix iframe height calculation.
+2. **Verify end-to-end palette override** — After scroll fix, test that selecting a palette in Phase 2 actually changes the template preview's colors via `--tp-*` tokens.
+3. **Fix blank template cards** — Improve `extract_preview()` regex to handle all 34 template structures.
+4. **Wire shader backgrounds** — When a shader preset is selected, set the template's `--tp-bg` to `transparent` so the canvas shows through.
+5. **Clean up** — Delete `template-picker-app/` React scaffold if not continuing that path. Fix producer dist format issues.
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
@@ -436,6 +436,29 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
 
   </Tab>
   <Tab title="Preview">
+    ### `pick`
+
+    <Note>
+      Experimental. Hidden behind a feature flag. Set `HYPERFRAMES_DESIGN_PICKER=1` (or `true` / `on` / `yes`) to enable. Always enabled when running from the monorepo for contributors.
+    </Note>
+
+    Open the design picker in your browser to choose a template and create a `design.md`:
+
+    ```bash
+    HYPERFRAMES_DESIGN_PICKER=1 npx hyperframes pick
+    HYPERFRAMES_DESIGN_PICKER=1 npx hyperframes pick --port 8723
+    HYPERFRAMES_DESIGN_PICKER=1 npx hyperframes pick --build-only
+    ```
+
+    | Flag | Description |
+    |------|-------------|
+    | `--port` | Port to serve the picker on (default: 8723) |
+    | `--build-only` | Build the picker HTML without serving it |
+
+    Builds `.hyperframes/pick-design.html` from the installed skill template, starts a local HTTP server, and opens the picker. Requires the HyperFrames skills (`npx hyperframes skills`) and `python3` installed.
+
+    The picker walks you through palette, typography, corners, density, depth, motion, and an optional shader background. Export the resulting `design.md` and paste it into your project root.
+
     ### `preview`
 
     Start a live preview server with hot reload:
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		skills/hyperframes/templates/presentations/*/deck-stage.js