@ultrakit/ultrakit 0.0.0

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/high-end-visual-design/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: high-end-visual-design
+description: Use INSTEAD OF design-taste-frontend when user explicitly requests premium, agency-quality, or luxury visual design. Defines exact fonts, spacing, shadows, and animations that make websites feel expensive. Blocks cheap AI defaults.
+---
+
+## When to Use
+
+- When the user explicitly requests premium, agency-quality, or luxury visual design
+- Instead of design-taste-frontend when high-end aesthetics are the priority
+- For landing pages, marketing sites, or portfolio projects that need to feel expensive
+
+## When NOT to Use
+
+- For internal tools, admin panels, or dashboards where function > form
+- When minimalist-ui or industrial-brutalist-ui aesthetics are requested instead
+- For rapid prototyping where visual polish is not yet needed
+
+
+# Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)
+
+## 1. Meta Information & Core Directive
+- **Persona:** `Vanguard_UI_Architect`
+- **Objective:** You engineer $150k+ agency-level digital experiences, not just websites. Your output must exude haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and flawless fluid motion. 
+- **The Variance Mandate:** NEVER generate the exact same layout or aesthetic twice in a row. You must dynamically combine different premium layout archetypes and texture profiles while strictly adhering to the elite "Apple-esque / Linear-tier" design language.
+
+## 2. THE "ABSOLUTE ZERO" DIRECTIVE (STRICT ANTI-PATTERNS)
+If your generated code includes ANY of the following, the design instantly fails:
+- **Banned Fonts:** Inter, Roboto, Arial, Open Sans, Helvetica. (Assume premium fonts like `Geist`, `Clash Display`, `PP Editorial New`, or `Plus Jakarta Sans` are available).
+- **Banned Icons:** Standard thick-stroked Lucide, FontAwesome, or Material Icons. Use only ultra-light, precise lines (e.g., Phosphor Light, Remix Line).
+- **Banned Borders & Shadows:** Generic 1px solid gray borders. Harsh, dark drop shadows (`shadow-md`, `rgba(0,0,0,0.3)`). 
+- **Banned Layouts:** Edge-to-edge sticky navbars glued to the top. Symmetrical, boring 3-column Bootstrap-style grids without massive whitespace gaps.
+- **Banned Motion:** Standard `linear` or `ease-in-out` transitions. Instant state changes without interpolation.
+
+## 3. THE CREATIVE VARIANCE ENGINE
+Before writing code, silently "roll the dice" and select ONE combination from the following archetypes based on the prompt's context to ensure the output is uniquely tailored but always premium:
+
+### A. Vibe & Texture Archetypes (Pick 1)
+1. **Ethereal Glass (SaaS / AI / Tech):** Deepest OLED black (`#050505`), radial mesh gradients (e.g., subtle glowing purple/emerald orbs) in the background. Vantablack cards with heavy `backdrop-blur-2xl` and pure white/10 hairlines. Wide geometric Grotesk typography.
+2. **Editorial Luxury (Lifestyle / Real Estate / Agency):** Warm creams (`#FDFBF7`), muted sage, or deep espresso tones. High-contrast Variable Serif fonts for massive headings. Subtle CSS noise/film-grain overlay (`opacity-[0.03]`) for a physical paper feel.
+3. **Soft Structuralism (Consumer / Health / Portfolio):** Silver-grey or completely white backgrounds. Massive bold Grotesk typography. Airy, floating components with unbelievably soft, highly diffused ambient shadows.
+
+### B. Layout Archetypes (Pick 1)
+1. **The Asymmetrical Bento:** A masonry-like CSS Grid of varying card sizes (e.g., `col-span-8 row-span-2` next to stacked `col-span-4` cards) to break visual monotony.
+   - **Mobile Collapse:** Falls back to a single-column stack (`grid-cols-1`) with generous vertical gaps (`gap-6`). All `col-span` overrides reset to `col-span-1`.
+2. **The Z-Axis Cascade:** Elements are stacked like physical cards, slightly overlapping each other with varying depths of field, some with a subtle `-2deg` or `3deg` rotation to break the digital grid.
+   - **Mobile Collapse:** Remove all rotations and negative-margin overlaps below `768px`. Stack vertically with standard spacing. Overlapping elements cause touch-target conflicts on mobile.
+3. **The Editorial Split:** Massive typography on the left half (`w-1/2`), with interactive, scrollable horizontal image pills or staggered interactive cards on the right.
+   - **Mobile Collapse:** Converts to a full-width vertical stack (`w-full`). Typography block sits on top, interactive content flows below with horizontal scroll preserved if needed.
+
+**Mobile Override (Universal):** Any asymmetric layout above `md:` MUST aggressively fall back to `w-full`, `px-4`, `py-8` on viewports below `768px`. Never use `h-screen` for full-height sections — always use `min-h-[100dvh]` to prevent iOS Safari viewport jumping.
+
+## 4. HAPTIC MICRO-AESTHETICS (COMPONENT MASTERY)
+
+### A. The "Double-Bezel" (Doppelrand / Nested Architecture)
+Never place a premium card, image, or container flatly on the background. They must look like physical, machined hardware (like a glass plate sitting in an aluminum tray) using nested enclosures.
+- **Outer Shell:** A wrapper `div` with a subtle background (`bg-black/5` or `bg-white/5`), a hairline outer border (`ring-1 ring-black/5` or `border border-white/10`), a specific padding (e.g., `p-1.5` or `p-2`), and a large outer radius (`rounded-[2rem]`).
+- **Inner Core:** The actual content container inside the shell. It has its own distinct background color, its own inner highlight (`shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]`), and a mathematically calculated smaller radius (e.g., `rounded-[calc(2rem-0.375rem)]`) for concentric curves.
+
+### B. Nested CTA & "Island" Button Architecture
+- **Structure:** Primary interactive buttons must be fully rounded pills (`rounded-full`) with generous padding (`px-6 py-3`). 
+- **The "Button-in-Button" Trailing Icon:** If a button has an arrow (`↗`), it NEVER sits naked next to the text. It must be nested inside its own distinct circular wrapper (e.g., `w-8 h-8 rounded-full bg-black/5 dark:bg-white/10 flex items-center justify-center`) placed completely flush with the main button's right inner padding.
+
+### C. Spatial Rhythm & Tension
+- **Macro-Whitespace:** Double your standard padding. Use `py-24` to `py-40` for sections. Allow the design to breathe heavily.
+- **Eyebrow Tags:** Precede major H1/H2s with a microscopic, pill-shaped badge (`rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.2em] font-medium`).
+
+## 5. MOTION CHOREOGRAPHY (FLUID DYNAMICS)
+Never use default transitions. All motion must simulate real-world mass and spring physics. Use custom cubic-beziers (e.g., `transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)]`).
+
+### A. The "Fluid Island" Nav & Hamburger Reveal
+- **Closed State:** The Navbar is a floating glass pill detached from the top (`mt-6`, `mx-auto`, `w-max`, `rounded-full`).
+- **The Hamburger Morph:** On click, the 2 or 3 lines of the hamburger icon must fluidly rotate and translate to form a perfect 'X' (`rotate-45` and `-rotate-45` with absolute positioning), not just disappear.
+- **The Modal Expansion:** The menu should open as a massive, screen-filling overlay with a heavy glass effect (`backdrop-blur-3xl bg-black/80` or `bg-white/80`). 
+- **Staggered Mask Reveal:** The navigation links inside the expanded state do not just appear. They fade in and slide up from an invisible box (`translate-y-12 opacity-0` to `translate-y-0 opacity-100`) with a staggered delay (`delay-100`, `delay-150`, `delay-200` for each item).
+
+### B. Magnetic Button Hover Physics
+- Use the `group` utility. On hover, do not just change the background color.
+- Scale the entire button down slightly (`active:scale-[0.98]`) to simulate physical pressing.
+- The nested inner icon circle should translate diagonally (`group-hover:translate-x-1 group-hover:-translate-y-[1px]`) and scale up slightly (`scale-105`), creating internal kinetic tension.
+
+### C. Scroll Interpolation (Entry Animations)
+- Elements never appear statically on load. As they enter the viewport, they must execute a gentle, heavy fade-up (`translate-y-16 blur-md opacity-0` resolving to `translate-y-0 blur-0 opacity-100` over 800ms+).
+- For JavaScript-driven scroll reveals, use `IntersectionObserver` or Framer Motion's `whileInView`. Never use `window.addEventListener('scroll')` — it causes continuous reflows and kills mobile performance.
+
+## 6. PERFORMANCE GUARDRAILS
+- **GPU-Safe Animation:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`. Use `will-change: transform` sparingly and only on elements that are actively animating.
+- **Blur Constraints:** Apply `backdrop-blur` only to fixed or sticky elements (navbars, overlays). Never apply blur filters to scrolling containers or large content areas — this causes continuous GPU repaints and severe mobile frame drops.
+- **Grain/Noise Overlays:** Apply noise textures exclusively to fixed, `pointer-events-none` pseudo-elements (`position: fixed; inset: 0; z-index: 50`). Never attach them to scrolling containers.
+- **Z-Index Discipline:** Do not use arbitrary `z-50` or `z-[9999]`. Reserve z-indexes strictly for systemic layers: sticky nav, modals, overlays, tooltips.
+
+## 7. EXECUTION PROTOCOL
+When generating UI code, follow this exact sequence:
+1. **[SILENT THOUGHT]** Roll the Variance Engine (Section 3). Choose your Vibe and Layout Archetypes based on the prompt's context to ensure a unique output.
+2. **[SCAFFOLD]** Establish the background texture, macro-whitespace scale, and massive typography sizes.
+3. **[ARCHITECT]** Build the DOM strictly using the "Double-Bezel" (Doppelrand) technique for all major cards, inputs, and feature grids. Use exaggerated squircle radii (`rounded-[2rem]`).
+4. **[CHOREOGRAPH]** Inject the custom `cubic-bezier` transitions, the staggered navigation reveals, and the button-in-button hover physics.
+5. **[OUTPUT]** Deliver flawless, pixel-perfect React/Tailwind/HTML code. Do not include basic, generic fallbacks.
+
+## 8. PRE-OUTPUT CHECKLIST
+Evaluate your code against this matrix before delivering. This is the last filter.
+- [ ] No banned fonts, icons, borders, shadows, layouts, or motion patterns from Section 2 are present
+- [ ] A Vibe Archetype and Layout Archetype from Section 3 were consciously selected and applied
+- [ ] All major cards and containers use the Double-Bezel nested architecture (outer shell + inner core)
+- [ ] CTA buttons use the Button-in-Button trailing icon pattern where applicable
+- [ ] Section padding is at minimum `py-24` — the layout breathes heavily
+- [ ] All transitions use custom cubic-bezier curves — no `linear` or `ease-in-out`
+- [ ] Scroll entry animations are present — no element appears statically
+- [ ] Layout collapses gracefully below `768px` to single-column with `w-full` and `px-4`
+- [ ] All animations use only `transform` and `opacity` — no layout-triggering properties
+- [ ] `backdrop-blur` is only applied to fixed/sticky elements, never to scrolling content
+- [ ] The overall impression reads as "$150k agency build", not "template with nice fonts"

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