opencodekit 0.21.1 → 0.21.3

package/dist/template/.opencode/skill/design-direction-advisor/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: design-direction-advisor
+description: Use when the user's design brief is vague ("make it look good", "design something", "I don't know what style I want", "make me a nice-looking page") OR when no brand context exists. Recommends 3 differentiated directions from 5 design schools × 20 named designer philosophies (Pentagram, Field.io, Kenya Hara, Sagmeister, etc.) with parallel visual demos so the user can choose by seeing, not imagining.
+---
+
+# Design Direction Advisor (Fallback Mode)
+
+> Adapted from `huashu-design`. When you don't have brand context and the user's brief is too vague to execute, **don't guess from generic intuition** — that produces AI slop. Convert ambiguity into structured choice.
+
+## When to Trigger
+
+- Vague briefs: "make it look good", "design something", "make me a page", "I don't know what I want"
+- User explicitly asks: "recommend a style", "give me some directions", "pick a philosophy", "show me different styles"
+- No design context exists: no design system, no brand kit, no Figma, no reference site
+- User says "I don't know what style I want either"
+
+## When to Skip
+
+- User already provided clear references (Figma / screenshots / brand spec) → run `brand-asset-protocol` instead
+- User already specified the direction ("Apple Silicon launch event style") → go directly to execution
+- Small fix or specific tool call ("convert this HTML to PDF") → skip
+- Uncertain → use the lightest version: list 3 directions in 2 sentences each and let the user pick. Don't generate demos prematurely.
+
+## The 8-Phase Flow
+
+### Phase 1 — Deep-Understand the Need
+
+Ask up to **3** focused questions (skip if already clear):
+
+- Target audience?
+- Core message?
+- Emotional tone?
+- Output format? (web page / slide / animation / app mockup)
+
+### Phase 2 — Advisor-Style Restatement (~150 words)
+
+In your own words, restate: the essential need, audience, scenario, emotional tone. End with: _"Based on this understanding, I've prepared 3 design directions for you."_
+
+This forces alignment before generation. If the restatement is wrong, the user corrects you cheaply.
+
+### Phase 3 — Recommend 3 Differentiated Philosophies
+
+Each direction must include:
+
+- **Named designer or studio** — "Kenya Hara-style Eastern minimalism," not just "minimalism"
+- 50-100 words explaining _why this designer fits your brief_
+- 3-4 signature visual features
+- 3-5 vibe keywords
+- Optional reference work
+
+**Differentiation rule (non-negotiable):** the 3 directions must come from **3 different schools** for clear visual contrast.
+
+### The 5 Schools × 20 Philosophies
+
+| School                               | Vibe                                    | Best as                         | Designers (pick 1 per recommendation)                             |
+| ------------------------------------ | --------------------------------------- | ------------------------------- | ----------------------------------------------------------------- |
+| **Information Architecture (01-04)** | Rational, data-driven, restrained       | Safe / professional choice      | Pentagram (Bierut), Stamen Design, Information Architects, Fathom |
+| **Motion Poetics (05-08)**           | Dynamic, immersive, technical aesthetic | Bold / cutting-edge choice      | Locomotive, Active Theory, Field.io, Resn                         |
+| **Minimalism (09-12)**               | Order, whitespace, refinement           | Safe / premium choice           | Experimental Jetset, Müller-Brockmann, Build, Sagmeister & Walsh  |
+| **Experimental Avant-garde (13-16)** | Generative art, visual impact           | Bold / innovative choice        | Zach Lieberman, Raven Kwok, Ash Thorp, Territory Studio           |
+| **Eastern Philosophy (17-20)**       | Warm, poetic, contemplative             | Differentiation / unique choice | Takram, Kenya Hara, Irma Boom, Neo Shen                           |
+
+❌ **Forbidden**: recommending 2 or more from the same school. Insufficient differentiation = user can't tell them apart.
+
+A good triplet typically pairs **one safe + one bold + one differentiating** choice.
+
+### Phase 4 — Show Reference Examples (Visual Anchor)
+
+Before generating live demos, **show 2-3 reference images per direction** if you can fetch them (search the designer's known projects). The user calibrates "yes, that vibe" or "no, not what I meant" against real work, not your description.
+
+Phrasing: _"Before I spin up live demos, here's how each style looks in similar scenarios →"_ then show references.
+
+### Phase 5 — Generate 3 Visual Demos
+
+> **Core principle: seeing beats describing.** Don't make the user imagine — show them.
+
+For each of the 3 directions, generate one demo using the user's **real content/topic**, not lorem ipsum.
+
+- **If parallel subagents are supported:** dispatch 3 in parallel (file-disjoint, see AGENTS.md "Parallel Execution Rules")
+- **If serial:** generate one at a time, all 3 before showing
+
+| Style type        | Demo path                                                         |
+| ----------------- | ----------------------------------------------------------------- |
+| HTML-friendly     | Generate full HTML → screenshot via Playwright                    |
+| AI-image-friendly | Use image generation (e.g. nano-banana-pro) with style DNA prompt |
+| Hybrid            | HTML layout + AI-generated illustrations slotted in               |
+
+Save HTML to `_temp/design-demos/demo-<style>.html`. Screenshot to `_temp/design-demos/demo-<style>.png`. Show all 3 screenshots together.
+
+```bash
+# Reference command
+npx playwright screenshot file:///<absolute-path>.html out.png --viewport-size=1200,900
+```
+
+### Phase 6 — User Chooses
+
+Options to present:
+
+- **Pick one** to deepen
+- **Mix** ("A's palette + C's layout")
+- **Tweak** specific aspects of one
+- **Restart** → return to Phase 3 with refined understanding
+
+### Phase 7 — Generate Production Prompt (if AI image-driven)
+
+Structure: `[design philosophy constraint] + [content description] + [technical params]`
+
+- ✅ Use **specific features**, not style names: "Kenya Hara whitespace + terracotta orange #C04A1A," not "minimalist"
+- ✅ Include HEX colors, ratios, space allocation, output spec
+- ❌ Avoid AI slop list (see `anti-ai-slop` skill)
+
+### Phase 8 — Hand Off to Main Build
+
+Direction confirmed → return to the main implementation flow (`hi-fi-prototype-html`, `frontend-design`, etc.). You now have **explicit design context** — no longer guessing.
+
+## Lightweight Variant (Time-Pressured)
+
+When the user is in a rush:
+
+- Skip Phase 4 references
+- Skip Phase 5 demos
+- Just present 3 named directions in 2 sentences each
+- Let user pick by name
+
+This trades signal-fidelity for speed but still beats "generic AI default."
+
+## Why This Beats "Just Make a Reasonable Default"
+
+1. **Generic default = AI slop** (see `anti-ai-slop`). It dilutes brand identity to the average of all training data.
+2. **Named designer references** give the user concrete vocabulary to push back ("more like Pentagram, less like Sagmeister").
+3. **3 differentiated demos** convert vague preferences into testable choices in one round, instead of N rounds of "looks ok but not quite right."
+4. **The advisor restatement (Phase 2)** catches misunderstandings before any pixel is committed — the cheapest possible correction point.
+
+## Pairs Well With
+
+- `brand-asset-protocol` — runs **after** direction is locked, when brand assets must be sourced
+- `anti-ai-slop` — keeps each demo from collapsing into the AI default
+- `hi-fi-prototype-html` — production target after direction is chosen
+- `brainstorming` — for non-visual, non-design ambiguity

package/dist/template/.opencode/skill/hi-fi-prototype-html/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: hi-fi-prototype-html
+description: Use when building high-fidelity HTML prototypes, interactive product mockups, app/iOS/Android screen demos, or design-variation explorations (NOT production web apps — use frontend-design for that). Enforces Junior Designer mode (show assumptions early, iterate), single-file inline React for double-clickable mockups, real images instead of generic placeholders, and Playwright click-test before delivery.
+---
+
+# Hi-Fi Prototype (HTML as Medium)
+
+> Adapted from `huashu-design`. HTML is your **medium**, not your destination. You are a designer who happens to use HTML, not a developer who happens to be designing.
+
+## When to Use
+
+- **Interactive prototypes** — clickable product mockups for user testing or design review
+- **Design variation exploration** — 3+ side-by-side directions before committing
+- **App / iOS / Android mockups** — single-page or full-flow demos
+- **Concept demos** — convey an interaction or feel before any production code
+- **Information graphics** with hand-tuned typography
+
+**Don't use for**:
+
+- Production web apps with real backends → `frontend-design` + `react-best-practices`
+- SEO/marketing sites → `frontend-design`
+- Component library work → `mockup-to-code` (mockup → production component)
+
+## Core Discipline
+
+### 1. Start From Existing Context — Don't Design From Air
+
+Good hi-fi designs grow from existing context. Before opening a blank file:
+
+- Ask: do you have a design system / UI kit / Figma / brand site / reference screenshots?
+- If yes → run `brand-asset-protocol` to extract real assets
+- If no AND brief is vague → run `design-direction-advisor` first
+- Only as last resort: design from generic intuition (will produce AI slop — see `anti-ai-slop`)
+
+### 2. Junior Designer Mode — Show Assumptions Early, Then Iterate
+
+You are the user's junior designer. The user is the manager.
+
+❌ **Don't** disappear for an hour and reveal a finished file.
+
+✅ **Do** open the HTML with your assumptions written as comments + reasoning + grayblock placeholders. Show this **first**. Get nod. Then write components. Show again at 50% done. Iterate.
+
+```html
+<!-- Assumptions:
+     - Audience: enterprise admins
+     - Style direction: Pentagram-style (per design-direction-advisor)
+     - 3 variations differ in: density, hierarchy, accent color
+     - Real product photos pending from user (Step 1 of brand-asset-protocol)
+-->
+<div class="placeholder">[Hero image — DJI Pocket 4 product render, TBD]</div>
+<div class="placeholder">[Headline copy — TBD from user]</div>
+```
+
+**Why**: misunderstanding the brief is 100× cheaper to fix at this stage than after a finished build.
+
+### 3. Give Variations, Not "The Answer"
+
+When the user says "design X", don't deliver one polished answer. Deliver **3+ variations** spanning:
+
+- by-the-book → novel (a continuum, not all in one corner)
+- different axes: visual, interaction, color, layout, animation
+- let the user mix and match
+
+Implementation:
+
+- Pure visual comparison → side-by-side static layout (`design_canvas`-style grid)
+- Interactive flow with branching options → full prototype with toggles ("Tweaks") for live parameter swap
+
+### 4. Honest Placeholders Beat Bad Implementations
+
+- Missing icon? → gray block + label "[icon]". Don't draw a wonky SVG.
+- Missing data? → `<!-- TBD: real data from user -->`. Don't fabricate plausible-looking numbers.
+- Missing image? → labeled placeholder. Don't AI-draw a face.
+
+**In hi-fi work, an honest placeholder is 10× better than a clumsy attempt at the real thing.**
+
+### 5. System First, Don't Pad Filler
+
+Every element earns its place. Whitespace is a design problem solved by **composition**, not by inventing content.
+
+Especially watch for these "slop" categories (see `anti-ai-slop`):
+
+- **Data slop** — meaningless stats, decorative numbers
+- **Iconography slop** — every heading needs an icon
+- **Gradient slop** — every background gets a gradient
+
+> "One thousand no's for every yes."
+
+## App / iOS Prototype Rules (override generic placeholder rules)
+
+App mockups are **demos at presentation time** — generic gray rectangles and lorem ipsum kill credibility. Different rules apply:
+
+### A. Architecture: Default to Single-File Inline React
+
+**Default**: all JSX/data/styles inside a `<script type="text/babel">…</script>` tag in one HTML file. Reasons:
+
+- `file://` blocks external JS as cross-origin → forces user to spin up an HTTP server → violates "double-click to open" principle
+- Local images must be base64 data URLs (don't assume a server)
+
+**Split files only when**:
+
+- Single file >1000 lines and unmaintainable → split into `components.jsx` + `data.js`, document the `python3 -m http.server` command in delivery notes
+- Multiple subagents need to write different screens in parallel → `index.html` + per-screen HTML, iframe-aggregated, each screen self-contained
+
+| Scenario                          | Architecture             | Delivery                                  |
+| --------------------------------- | ------------------------ | ----------------------------------------- |
+| Single dev, 4-6 screens (default) | Single-file inline React | One `.html`, double-click                 |
+| Single dev, large app (>10 scr)   | Multi-jsx + HTTP server  | Include startup command                   |
+| Multi-agent parallel              | Multi-HTML + iframe      | `index.html` aggregator, each opens alone |
+
+### B. Real Images First, Not "Just Placeholders"
+
+By default, **actively fetch real images**. Don't draw SVG. Don't leave gray blocks. Don't wait for user to ask.
+
+| Use case                          | Source                                                              |
+| --------------------------------- | ------------------------------------------------------------------- |
+| Art / museum / historical content | Wikimedia Commons (public domain), Met Museum Open Access, AIC API  |
+| General lifestyle photography     | Unsplash, Pexels (royalty-free)                                     |
+| User's existing assets            | `~/Downloads`, project `_archive/`, user's configured asset library |
+
+Wikimedia caveat: `curl` via TLS proxy often fails. Use Python `urllib` and a compliant User-Agent (`MyProject/0.1 (https://github.com/you; you@example.com)`). Use the MediaWiki API (`action=query&list=categorymembers`) for batch / `prop=imageinfo&iiurlwidth=` for sized thumbs.
+
+**Honest-image test**: before fetching, ask — _"if I remove this image, is information lost?"_
+
+| Scenario                                                     | Verdict                        | Action                                      |
+| ------------------------------------------------------------ | ------------------------------ | ------------------------------------------- |
+| Essay list cover / profile background / settings page banner | Decoration, no link to content | **Don't add** — equivalent to gradient slop |
+| Museum content portrait / product detail / map card location | Image IS the content           | **Must add** — real image required          |
+| Graph / visualization background texture (very subtle)       | Atmosphere, not focus          | Add at `opacity ≤ 0.08`                     |
+
+❌ Don't pad text essays with Unsplash "inspiration shots." Permission to use real images ≠ license to over-use them.
+
+### C. Two Standard Delivery Forms — Ask First
+
+Multi-screen app prototypes split into two standard forms. **Ask which one** before defaulting:
+
+| Form                                      | When                                                                    | How                                                                                 |
+| ----------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **Overview tile (design review default)** | User wants to see all screens, compare layout, walk through consistency | All screens in parallel, each in its own iPhone frame, no clicks needed             |
+| **Flow demo (single device)**             | User wants to demonstrate a specific user flow (onboarding, purchase)   | One iPhone with `AppPhone` state machine — tabs, buttons, annotations all clickable |
+
+Routing keywords:
+
+- "tile / show all pages / overview / compare / all screens" → overview
+- "demonstrate flow / user path / walk through / clickable / interactive demo" → flow demo
+- Ambiguous → ask. Don't default to flow demo (it's much more work).
+
+**Overview skeleton:**
+
+```jsx
+<div style={{ display: "flex", gap: 32, flexWrap: "wrap", padding: 48, alignItems: "flex-start" }}>
+  {screens.map((s) => (
+    <div key={s.id}>
+      <div style={{ fontSize: 13, color: "#666", marginBottom: 8, fontStyle: "italic" }}>
+        {s.label}
+      </div>
+      <IosFrame>
+        <ScreenComponent data={s} />
+      </IosFrame>
+    </div>
+  ))}
+</div>
+```
+
+**Flow demo skeleton:**
+
+```jsx
+function AppPhone({ initial = "today" }) {
+  const [screen, setScreen] = React.useState(initial);
+  const [modal, setModal] = React.useState(null);
+  // dispatch to the right ScreenComponent, pass onEnter/onClose/onTabChange callbacks
+}
+```
+
+Each Screen takes callback props (`onEnter`, `onClose`, `onTabChange`, `onOpen`, `onAnnotation`) — don't hard-code state. TabBar, buttons, cards get `cursor: pointer` + hover feedback.
+
+### D. Click-Test Before Delivery
+
+Static screenshots only show layout. Interaction bugs only surface when you click. Run a **3-action minimum Playwright test** before saying done:
+
+1. Enter detail view
+2. Trigger a key annotation
+3. Switch tabs
+
+Check `pageerror` count is 0. If not, fix and re-run.
+
+```bash
+npx playwright test prototype.spec.ts
+```
+
+### E. iOS Frame: Use a Pinned-Spec Component, Don't Hand-Code
+
+The iPhone Dynamic Island has fixed pixel dimensions (124×36, top:12, centered). Hand-coding the bezel + status bar + island + home indicator → 99% chance of placement bugs (status bar items get squeezed by the island, content top-padding miscalculated).
+
+**Rule**: bind to a known-good iOS frame component (e.g. an `IosFrame` you keep in a personal asset library). Don't write `.dynamic-island`, `.status-bar`, `.home-indicator`, or the bezel chrome inline.
+
+```jsx
+<IosFrame time="9:41" battery={85}>
+  <YourScreen />
+</IosFrame>
+```
+
+Same rule for Android (`AndroidFrame`), macOS windows (`MacosWindow`), browser windows (`BrowserWindow`).
+
+## Position Questions — Answer Before Designing the System
+
+For every page / screen / shot, answer these **4 position questions** before opening CSS:
+
+- **Narrative role** — hero / transition / data / quote / closer? (every page in a deck differs)
+- **Viewing distance** — 10cm phone / 1m laptop / 10m projector? (drives font size + density)
+- **Visual temperature** — quiet / excited / cool / authoritative / tender / mournful? (drives palette + rhythm)
+- **Capacity check** — sketch 3 five-second thumbnails on paper. Does the content fit?
+
+Then verbalize the design system (palette / type / layout rhythm / component patterns). System serves the answers — don't pick the system first and stuff content in.
+
+🛑 **Checkpoint**: state the 4 answers + the system out loud. Wait for user nod **before** opening CSS.
+
+## Standard Workflow (with Checkpoints)
+
+1. **Understand the need.**
+   - 🔍 If task names a specific real product (DJI Pocket 4, Gemini 3 Pro, etc.): WebSearch first, write facts to `product-facts.md`. Don't guess from memory.
+   - Ask focused clarifying questions — batch them, don't drip-feed.
+   - 🛑 **Checkpoint 1**: send all questions, wait for user to answer in batch.
+   - 🛑 If brief is vague → run `design-direction-advisor` and complete Phase 1-4 first.
+
+2. **Explore resources + extract assets.** Read design system, linked files, screenshots. For specific brands: run `brand-asset-protocol` (5 steps).
+   - 🛑 **Checkpoint 2 (asset self-check)**: physical product → product photo present (not CSS silhouette); digital product → logo + UI screenshot present; colors extracted from real HTML/SVG. Missing → stop and fix.
+
+3. **Answer the 4 position questions, then verbalize the system.**
+   - 🛑 **Checkpoint 3**: state position answers + system. Wait for nod.
+
+4. **Build folder structure.** `<project-name>/` holds main HTML + needed asset copies (don't bulk-copy >20 files).
+
+5. **Junior pass.** HTML opens with assumptions + placeholders + reasoning comments.
+   - 🛑 **Checkpoint 4**: show early (gray blocks + labels are fine). Wait for feedback before writing components.
+
+6. **Full pass.** Fill placeholders, build variations, add Tweaks if needed. **Show again mid-way**, not only at the end.
+
+7. **Verify.** Playwright screenshot + console error check. Send to user.
+   - 🛑 **Checkpoint 5**: open the file in your own browser. Walk through. AI-written prototype code commonly has subtle interaction bugs.
+
+8. **Summary.** Minimal — caveats and next steps only.
+
+**Checkpoint principle**: when you hit a 🛑, stop and explicitly say _"I did X, next I plan Y, confirm?"_ — then **actually wait**. Don't say it and immediately continue.
+
+## Pairs Well With
+
+- `brand-asset-protocol` — extract real brand assets before designing
+- `anti-ai-slop` — actively avoid the AI default aesthetic
+- `design-direction-advisor` — when brief is too vague to start
+- `design-taste-frontend` / `high-end-visual-design` — base aesthetic discipline
+- `frontend-design` — when prototype graduates to production code
+- `playwright` — for the click-test step

package/dist/template/.opencode/skill/html-deck-export/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: html-deck-export
+description: Use when building HTML-based slide decks that need to ship as PDF or editable PPTX. MUST load BEFORE writing the first line of HTML if PPTX (with editable text) is a delivery target — choosing the wrong architecture costs 2-3 hours of rework. Covers multi-file vs single-file deck architecture, browser presentation, PDF export, and the 4 hard constraints for editable PPTX.
+---
+
+# HTML Deck Export
+
+> Adapted from `huashu-design`. The hardest checkpoint isn't "single-file or multi-file" — it's **"what's the final delivery format?"** Get this wrong and you're rewriting 17 pages of HTML.
+
+## The Critical Decision (Before First Line of HTML)
+
+```
+Q: What's the final delivery format?
+├── Browser fullscreen presentation only / local HTML  → maximum visual freedom
+├── PDF (print / share / archive)                      → maximum visual freedom, any architecture exports
+└── Editable PPTX (teammates will edit text)           → 🛑 MUST follow 4 hard constraints from the first line
+```
+
+**Why "editable PPTX" forces decisions early**: PPTX with editable text requires `html2pptx`-style element-by-element DOM translation. That tool needs a structurally constrained HTML (see "4 Hard Constraints" below). Writing visually-rich HTML and converting after is a 2-3 hour rewrite. **From-scratch with constraints adds ~5 minutes per slide.**
+
+### Real-Cost Comparison
+
+| Path                                  | Approach                                               | Result                                                                       | Cost                                                              |
+| ------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| ❌ **Free-form HTML, fix PPTX later** | Single-file deck-stage + lots of SVG / span / gradient | To get editable PPTX: hand-write hundreds of pptxgenjs lines OR rewrite HTML | **2-3 hour rework + ongoing maintenance debt** (HTML edit ≠ PPTX) |
+| ✅ **Path-A constraints from line 1** | Per-page HTML + 4 constraints + 720×405pt              | One command exports 100% editable PPTX, also presents in browser             | **+5 min per slide thinking "how do I wrap text in `<p>`?"**      |
+
+## Opening Questionnaire (paste-ready)
+
+> Before I touch HTML, confirm delivery:
+>
+> - **Browser presentation / PDF** → I can use animations, web components, complex SVG, CSS gradients
+> - **Editable PPTX** (someone will edit text in PowerPoint) → I must follow 4 hard HTML constraints from the start. Visual capabilities reduce (no gradients, no web components, no complex SVG), but export becomes a single command
+>
+> Which?
+
+**Mixed delivery clarifications:**
+
+- "I want HTML presentation **and** editable PPTX" → not actually mixed. Path-A HTML _is_ presentable HTML; just add a deck index. Zero extra cost.
+- "I want PPTX **and** animation/web component" → real conflict. Make the user choose. Don't silently hand-write pptxgenjs (becomes permanent maintenance debt).
+
+## Architecture: Single-File vs Multi-File
+
+After delivery format is locked, pick architecture:
+
+| Architecture             | When                                                 | Pattern                                                                  |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------ |
+| **Multi-file** (default) | ≥10 pages, academic/courseware, multi-agent parallel | Each page is its own HTML; an `index.html`/iframe stitcher combines them |
+| **Single-file**          | ≤10 pages, pitch decks, cross-page state needed      | One HTML with a slide container component (web component or React)       |
+
+**Multi-file advantages**: independent CSS scopes (no specificity wars), trivial parallel work, individual page reload during dev.
+**Single-file advantages**: one file to share, easy state sharing across slides.
+
+### Multi-File Stitcher (skeleton)
+
+```html
+<!-- index.html -->
+<!doctype html>
+<style>
+  body {
+    margin: 0;
+    background: #000;
+  }
+  iframe {
+    display: block;
+    width: 100vw;
+    height: 100vh;
+    border: 0;
+  }
+</style>
+<iframe id="stage" src="01.html"></iframe>
+<script>
+  const slides = ["01.html", "02.html", "03.html", "04.html"];
+  let i = 0;
+  const stage = document.getElementById("stage");
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "ArrowRight" && i < slides.length - 1) i++;
+    if (e.key === "ArrowLeft" && i > 0) i--;
+    stage.src = slides[i];
+  });
+</script>
+```
+
+Each `NN.html` is a fully standalone, double-clickable slide.
+
+### Single-File Pattern (web component or React)
+
+```html
+<deck-stage>
+  <section class="active">Slide 1</section>
+  <section>Slide 2</section>
+</deck-stage>
+<script src="deck_stage.js"></script>
+```
+
+Two **hard constraints** for the web-component pattern:
+
+- The `<script>` tag for the component **must come after** the `</deck-stage>` close tag (else slot rendering breaks)
+- Section's `display: flex` must be on the `.active` class (not the section itself, else inactive slides fight for space)
+
+## The 4 Hard Constraints for Editable PPTX
+
+If you need editable PPTX export (via `html2pptx`-style tooling):
+
+1. **Body fixed at 720pt × 405pt** — _not_ 1920×1080px. Use `pt` units for the deck container (PowerPoint's native unit).
+2. **All text wrapped in `<p>` or `<h1>`–`<h6>`** — never plain `<div>` with text. Never `<span>` as the primary text carrier.
+3. **`<p>` and `<h*>` themselves cannot have background / border / shadow** — put those on an outer `<div>`.
+4. **No `background-image` on `<div>`** — use real `<img>` tags. No CSS gradients. No web components. No complex decorative SVG.
+
+**If your HTML violates any of these**, the editable export will produce broken slides or fail outright. The _image-mode_ PPTX export (slide rendered as an image, embedded in PowerPoint) doesn't have these constraints — but the result is **not editable**.
+
+## Two PPTX Export Modes
+
+| Mode              | Visual fidelity       | Editability                        | When                                                                  |
+| ----------------- | --------------------- | ---------------------------------- | --------------------------------------------------------------------- |
+| **Image mode**    | 100% — pixel-perfect  | None — text is image               | Visual-rich slides, no edits expected, PDF-equivalent in PPTX wrapper |
+| **Editable mode** | Reduced — constraints | Full — text editable in PowerPoint | Teammates will edit text, brand-spec font fallbacks expected          |
+
+Tools (per huashu-design pattern):
+
+- `playwright` for browser rendering (already in this kit)
+- `pptxgenjs` for PPTX object construction
+- `pdf-lib` for multi-page PDF merge
+- `sharp` (only for editable mode image fallbacks)
+
+## PDF Export (Easy Path)
+
+PDF tolerates any HTML architecture. Per-page browser screenshot → merge.
+
+```js
+// scripts/export-deck-pdf.mjs (skeleton)
+import { chromium } from "playwright";
+import { PDFDocument } from "pdf-lib";
+import fs from "fs";
+
+const slides = fs.readdirSync("slides").filter((f) => f.endsWith(".html"));
+const browser = await chromium.launch();
+const ctx = await browser.newContext({ viewport: { width: 1920, height: 1080 } });
+const merged = await PDFDocument.create();
+
+for (const file of slides) {
+  const page = await ctx.newPage();
+  await page.goto(`file://${process.cwd()}/slides/${file}`);
+  const pdfBytes = await page.pdf({ width: "1920px", height: "1080px", printBackground: true });
+  const tmp = await PDFDocument.load(pdfBytes);
+  const pages = await merged.copyPages(tmp, tmp.getPageIndices());
+  pages.forEach((p) => merged.addPage(p));
+  await page.close();
+}
+
+fs.writeFileSync("deck.pdf", await merged.save());
+await browser.close();
+```
+
+**Single-file deck-stage caveat**: shadow-DOM slot rendering can cause "only first slide exports." Use a per-slide URL fragment (`?slide=N`) and force the active slide before `page.pdf()`, or convert to multi-file before exporting.
+
+## Recovery: Rewriting for Editable PPTX After the Fact
+
+You're already mid-build and the user pivots to "we need editable PPTX." Two imperfect options:
+
+| Option                                    | Cost                                             | When                                                         |
+| ----------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
+| **Rewrite HTML to satisfy 4 constraints** | 2-3 hours for a typical 15-20 page deck          | Long-term — it's the only path to ongoing one-command export |
+| **Hand-write pptxgenjs version**          | 1-2 hours initially + permanent dual-maintenance | One-shot delivery — never edited again                       |
+
+**Always tell the user explicitly** which option you're picking and why. Don't silently choose the maintenance-debt path.
+
+## Position Questions for Each Slide
+
+Same as `hi-fi-prototype-html` — answer these before writing any slide:
+
+- **Narrative role** — hero, transition, data, quote, closer?
+- **Viewing distance** — laptop screen at 1m or projector at 10m? Drives font size and density.
+- **Visual temperature** — quiet/excited/cool/authoritative/tender? Drives palette and rhythm.
+- **Capacity check** — sketch 3 five-second thumbnails. Does it fit? (Most overcrowding is caught here.)
+
+## Anti-Patterns
+
+- ❌ Drawing slide chrome (page numbers, progress bars, titles) inside each slide AND in the deck stitcher → both render, double chrome
+- ❌ Using `1920×1080px` units for editable-PPTX target (must be `720pt × 405pt`)
+- ❌ One CSS file shared across multi-file slides — defeats the architecture's main benefit (scope isolation)
+- ❌ Building visual-rich slides "we can convert to PPTX later" — the 2-3 hour rework is real
+
+## Pairs Well With
+
+- `hi-fi-prototype-html` — same checkpoint discipline (4 position questions, junior pass)
+- `brand-asset-protocol` — required for branded decks
+- `anti-ai-slop` — slide decks are slop-prone (gradient backgrounds, emoji bullets)
+- `playwright` — drives PDF / image-mode PPTX export