diff --git a/external_plugins/frontend-slides/.zcode-plugin/plugin.json b/external_plugins/frontend-slides/.zcode-plugin/plugin.json new file mode 100644 index 00000000..6efd8f9f --- /dev/null +++ b/external_plugins/frontend-slides/.zcode-plugin/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "frontend-slides", + "description": "Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Zero dependencies, 12 curated style presets, 34 bold design systems, PPT conversion, PDF export, and Vercel deploy.", + "description_i18n": { + "en": "Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Zero dependencies, 12 curated style presets, 34 bold design systems, PPT conversion, PDF export, and Vercel deploy.", + "zh-CN": "从零创建或从 PowerPoint 转换生成精美、带动画的 HTML 演示文稿。零依赖,12 种精选样式预设、34 套大胆设计系统,支持 PPT 转换、PDF 导出与 Vercel 部署。" + }, + "version": "2.1.0", + "author": { + "name": "Zara Zhang", + "url": "https://github.com/zarazhangrui" + }, + "keywords": [ + "presentations", + "slides", + "html", + "design", + "powerpoint", + "templates", + "deck" + ], + "skills": "./skills" +} diff --git a/external_plugins/frontend-slides/LICENSE b/external_plugins/frontend-slides/LICENSE new file mode 100644 index 00000000..746da689 --- /dev/null +++ b/external_plugins/frontend-slides/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Zara Zhang + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/external_plugins/frontend-slides/README.md b/external_plugins/frontend-slides/README.md new file mode 100644 index 00000000..99c28ed4 --- /dev/null +++ b/external_plugins/frontend-slides/README.md @@ -0,0 +1,38 @@ +# Frontend Slides + +[中文文档](./README_CN.md) + +Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Based on [zarazhangrui/frontend-slides](https://github.com/zarazhangrui/frontend-slides) v2.1.0 (MIT), packaged for the official ZCode plugins marketplace. + +## What you get + +- **Zero dependencies** — each deck is a single self-contained HTML file +- **Style discovery** — the agent shows 3 visual style previews; you pick your favorite +- **12 safe presets + 34 bold design systems** — no generic "AI slop" aesthetics +- **PPT conversion** — extract text/images from .pptx and rebuild as web slides +- **Export & share** — PDF export and Vercel deploy scripts included + +## Install + +After the plugin is accepted into the official marketplace, install it from **ZCode → Settings → Plugin Marketplace → zcode-plugins-official**. + +## Usage + +Ask naturally in chat, or type `/frontend-slides`: + +- "Create a pitch deck for my AI startup" +- "Convert my presentation.pptx to a web slideshow" +- "Export the deck we just built to PDF" + +The skill asks about purpose, length and content density, shows 3 style previews, then generates a fixed 16:9 (1920×1080) deck that runs in any browser. + +## Requirements and side effects + +- **Network access:** the generated decks load web fonts (Google Fonts / Fontshare) at view time. Optional: PPT conversion needs Python + `python-pptx` (`pip install python-pptx`); PDF export needs Node.js (Playwright installs on first run); Vercel deploy needs a Vercel account. The plugin itself makes no network calls. +- **File writes:** decks are written to your current workspace; previews live in `.frontend-slides/` and are cleaned up after delivery. +- **Command execution:** the bundled scripts run `python`/`npx` only when you explicitly ask for PPT conversion, PDF export, or deploy. +- **No hooks, no MCP servers, no telemetry.** + +## Third-party material + +All skill content originates from [zarazhangrui/frontend-slides](https://github.com/zarazhangrui/frontend-slides) and is included under the MIT license (see [LICENSE](./LICENSE), © Zara Zhang). Packaging for ZCode by [@tahatehran](https://github.com/tahatehran). \ No newline at end of file diff --git a/external_plugins/frontend-slides/README_CN.md b/external_plugins/frontend-slides/README_CN.md new file mode 100644 index 00000000..4a780fc9 --- /dev/null +++ b/external_plugins/frontend-slides/README_CN.md @@ -0,0 +1,38 @@ +# Frontend Slides + +[English](./README.md) + +从零创建或从 PowerPoint 转换生成精美、带动画的 HTML 演示文稿。基于 [zarazhangrui/frontend-slides](https://github.com/zarazhangrui/frontend-slides) v2.1.0(MIT 许可),打包为 ZCode 官方插件市场的插件。 + +## 功能 + +- **零依赖** — 每份演示文稿都是单个自包含 HTML 文件 +- **风格发现** — agent 生成 3 个视觉风格预览,你只需挑选喜欢的 +- **12 种安全预设 + 34 套大胆设计系统** — 拒绝千篇一律的"AI 味"设计 +- **PPT 转换** — 从 .pptx 提取文字/图片并重建为网页幻灯片 +- **导出与分享** — 内置 PDF 导出和 Vercel 部署脚本 + +## 安装 + +插件被官方市场收录后,可在 **ZCode → 设置 → 插件市场 → zcode-plugins-official** 中安装。 + +## 使用 + +直接在对话中用自然语言提出,或输入 `/frontend-slides`: + +- “为我的 AI 创业项目做一个 pitch deck” +- “把我的 presentation.pptx 转换成网页幻灯片” +- “把刚做好的演示文稿导出为 PDF” + +该 skill 会询问用途、篇幅和内容密度,展示 3 个风格预览,然后生成 16:9(1920×1080)固定画布、可在任意浏览器运行的演示文稿。 + +## 依赖与副作用 + +- **网络访问:** 生成的幻灯片在查看时加载网络字体(Google Fonts / Fontshare)。可选:PPT 转换需要 Python + `python-pptx`(`pip install python-pptx`);PDF 导出需要 Node.js(Playwright 首次运行时自动安装);Vercel 部署需要 Vercel 账号。插件本身不发起任何网络请求。 +- **文件写入:** 幻灯片写入当前工作区;预览存放在 `.frontend-slides/`,交付后自动清理。 +- **命令执行:** 自带脚本仅在你明确要求 PPT 转换、PDF 导出或部署时运行 `python`/`npx`。 +- **无钩子、无 MCP 服务器、无遥测。** + +## 第三方内容 + +所有 skill 内容来自 [zarazhangrui/frontend-slides](https://github.com/zarazhangrui/frontend-slides),依据 MIT 许可包含(见 [LICENSE](./LICENSE),© Zara Zhang)。ZCode 打包由 [@tahatehran](https://github.com/tahatehran) 完成。 \ No newline at end of file diff --git a/external_plugins/frontend-slides/skills/frontend-slides/SKILL.md b/external_plugins/frontend-slides/skills/frontend-slides/SKILL.md new file mode 100644 index 00000000..9b8374bf --- /dev/null +++ b/external_plugins/frontend-slides/skills/frontend-slides/SKILL.md @@ -0,0 +1,380 @@ +--- +name: frontend-slides +description: Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices. +--- + +# Frontend Slides + +Create zero-dependency, animation-rich HTML presentations that run entirely in the browser. + +## Core Principles + +1. **Zero Dependencies** — Single HTML files with inline CSS/JS. No npm, no build tools. +2. **Show, Don't Tell** — Generate visual previews, not abstract choices. People discover what they want by seeing it. +3. **Distinctive Design** — No generic "AI slop." Every presentation must feel custom-crafted. +4. **Progressive Disclosure** — Read lightweight style indexes first. For bold templates, use small preview cards for style previews and load the full `design.md` only after the user picks that template. +5. **Fixed 16:9 Stage (NON-NEGOTIABLE)** — Every deck uses a 1920×1080 slide canvas scaled as a whole to the viewport. Slides must stay 16:9 on every screen, including phones. Do not reflow slide content to fit the device. + +## Design Aesthetics + +You tend to converge toward generic, "on distribution" outputs. In frontend design, this creates what users call the "AI slop" aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight. + +Focus on: + +- Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics. +- Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration. +- Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. +- Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic. + +Avoid generic AI-generated aesthetics: + +- Overused font families (Inter, Roboto, Arial, system fonts) +- Cliched color schemes (particularly purple gradients on white backgrounds) +- Predictable layouts and component patterns +- Cookie-cutter design that lacks context-specific character + +Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box! + +## Fixed Stage Rules + +These invariants apply to EVERY slide in EVERY presentation: + +- Every deck has a viewport wrapper that fills the browser window. +- Every slide is authored inside a fixed 1920×1080 stage. +- The stage scales uniformly to fit the viewport. It may letterbox/pillarbox; it must not re-layout content. +- Do not use responsive breakpoints to rearrange slide content for phones. +- Use fixed internal slide measurements at the 1920×1080 design size. +- Slide visibility must be controlled by `.active` / `.visible` using `visibility`, `opacity`, and `pointer-events` from `viewport-base.css`. Do not use `display: none` / `display: block` for slide switching; later layout classes such as `.slide-content { display: flex; }` can override them and make every slide visible at once. +- Use `clamp()` only for non-slide UI outside the stage, or for small fallback previews where a full stage is impractical. +- Include `prefers-reduced-motion` support +- Never negate CSS functions directly (`-clamp()`, `-min()`, `-max()` are silently ignored) — use `calc(-1 * clamp(...))` instead + +**When generating, read `viewport-base.css` and include its full contents in every presentation.** + +### Content Density Modes + +Ask the user whether this is primarily a reading deck or a speaking deck, then design around that answer: + +| Density mode | Best for | Design behavior | +| ------------- | -------- | --------------- | +| **Low density / speaker-led** | Public talks, keynote-style sharing, live explanation | One idea per slide, large type, strong visual hierarchy, generous negative space, 1-3 bullets max, more slides if needed | +| **High density / reading-first** | Reports, handouts, async review, detailed internal docs | More self-contained slides, structured grids/tables/annotations, 4-8 bullets or 4-6 cards when readable, tighter but still intentional spacing | + +Baseline limits still apply: no scrolling, no overflow, no overlapping panels, and no text below comfortable reading size. If content exceeds the selected density mode, split it into more slides instead of shrinking until it becomes cramped. + +--- + +## Phase 0: Detect Mode + +Determine what the user wants: + +- **Mode A: New Presentation** — Create from scratch. Go to Phase 1. +- **Mode B: PPT Conversion** — Convert a .pptx file. Go to Phase 4. +- **Mode C: Enhancement** — Improve an existing HTML presentation. Read it, understand it, enhance. **Follow Mode C modification rules below.** + +### Mode C: Modification Rules + +When enhancing existing presentations, fixed-stage fitting is the biggest risk: + +1. **Before adding content:** Count existing elements, check against density limits +2. **Adding images:** Fit them inside the 1920×1080 slide canvas. If slide already has max content, split into two slides +3. **Adding text:** Max 4-6 bullets per slide. Exceeds limits? Split into continuation slides +4. **After ANY modification, verify:** the slide stage remains 16:9, no text overflows its card, no panels overlap, and screenshots look correct at 1280×720 plus one phone viewport +5. **Proactively reorganize:** If modifications will cause overflow, automatically split content and inform the user. Don't wait to be asked + +**When adding images to existing slides:** Move image to a new slide or reduce other content first. Never add images without checking if existing content already fills the 1920×1080 slide stage. + +--- + +## Phase 1: Content Discovery (New Presentations) + +**Ask ALL questions together** so the user fills everything out at once. If the current environment provides a native structured-question UI, use it; otherwise ask in one concise message with clearly numbered choices: + +**Question 1 — Purpose** (header: "Purpose"): +What is this presentation for? Options: Pitch deck / Teaching-Tutorial / Conference talk / Internal presentation + +**Question 2 — Length** (header: "Length"): +Approximately how many slides? Options: Short 5-10 / Medium 10-20 / Long 20+ + +**Question 3 — Content** (header: "Content"): +Do you have content ready? Options: All content ready / Rough notes / Topic only + +**Question 4 — Density** (header: "Density"): +How dense should the deck feel? Options: + +- "Low density / speaker-led" — Big ideas, fewer words, more visual breathing room +- "High density / reading-first" — More self-contained detail for async reading + +**Do not ask about inline editing during Phase 1.** Users should not have to choose editing behavior before seeing a draft. Inline editing is a post-draft affordance: include it by default unless the user explicitly asks for a locked/export-only file. + +Remember the user's density choice. It affects slide count, typography scale, amount of text per slide, layout density, and whether to favor cinematic presenter slides or self-contained reading slides. + +If user has content, ask them to share it. + +### Step 1.2: Image Evaluation (if images provided) + +If user selected "No images" → skip to Phase 2. + +If user provides an image folder: + +1. **Scan** — List all image files (.png, .jpg, .svg, .webp, etc.) +2. **Inspect each image** — Use the agent's available image-understanding capability. If image reading is unavailable, use filenames/metadata and ask the user to clarify only when needed +3. **Evaluate** — For each: what it shows, USABLE or NOT USABLE (with reason), what concept it represents, dominant colors +4. **Co-design the outline** — Curated images inform slide structure alongside text. This is NOT "plan slides then add images" — design around both from the start (e.g., 3 screenshots → 3 feature slides, 1 logo → title/closing slide) +5. **Confirm the outline** using the same structured-question mechanism when available: "Does this slide outline and image selection look right?" Options: Looks good / Adjust images / Adjust outline + +**Logo in previews:** If a usable logo was identified, embed it (base64) into each style preview in Phase 2 — the user sees their brand styled three different ways. + +--- + +## Phase 2: Style Discovery + +**This is the "show, don't tell" phase.** Most people can't articulate design preferences in words. + +### Step 2.0: Generate 3 Style Previews Directly + +Based on purpose, audience, mood, and content density, generate 3 distinct single-slide HTML previews showing typography, colors, animation, and overall aesthetic. + +Do not ask the user whether they want options or a preset picker. The default discovery experience is always visual comparison. + +If the user already gave a vibe, use it. If they did not, infer the likely mood from the occasion, audience, content, and stakes. Keep the options diverse enough that the user can react visually instead of needing to articulate taste up front. + +If the user explicitly names a preset or bold template, honor that as one option and generate the remaining preview slots around it. + +Read [STYLE_PRESETS.md](STYLE_PRESETS.md) for safe preset candidates. If [bold-template-pack/selection-index.json](bold-template-pack/selection-index.json) exists, read that compact index too, but do not read any `design.md` files yet. + +| Mood | Suggested Presets | +| ------------------- | -------------------------------------------------- | +| Impressed/Confident | Bold Signal, Electric Studio, Dark Botanical | +| Excited/Energized | Creative Voltage, Neon Cyber, Split Pastel | +| Calm/Focused | Notebook Tabs, Paper & Ink, Swiss Modern | +| Inspired/Moved | Dark Botanical, Vintage Editorial, Pastel Geometry | + +**Preview mix rules:** + +- Generate 3 previews by default: 1 safe preset from `STYLE_PRESETS.md`, at least 1 bold template from `bold-template-pack/selection-index.json`, and 1 wildcard. +- The wildcard may be either a second bold template or a self-generated custom design. Choose whichever creates the strongest, most useful contrast for the user's occasion, audience, mood, and content. +- Do not force every expressive option to come from the template library. If the brief has a sharper, more specific design opportunity than the available templates, use the wildcard slot to design freely. +- For conservative or high-stakes decks, make the safe preset especially restrained; choose a calm, higher-formality bold template; make the wildcard either another restrained template or a custom design that feels authoritative rather than decorative. +- For expressive decks, keep the safe preset as a readable fallback; choose one strong bold template; make the wildcard adventurous, context-specific, and clearly different from both other previews. +- If bold template matches feel weak, use the wildcard as a custom design or fall back to another safe preset instead of forcing a template. + +**Custom wildcard design rules:** + +- Follow the Design Aesthetics section above: no generic "AI slop", no default font/color/layout choices, no purple-gradient-on-white clichés, no cookie-cutter dashboard/card look. +- Match the user's stated occasion, audience, mood/vibe, and content density. The custom design should feel authored for this deck, not merely "stylish." +- Make a deliberate visual thesis: distinctive typography, a committed palette, a recognizable layout system, and one strong atmospheric or graphic device. +- Keep it feasible for a full deck. The preview must imply a design system that can expand into section, content, quote, comparison, and closing slides. +- Use fixed 1920×1080 stage rules and pass the same preview authenticity checks as every other option. +- Never render "custom", "wildcard", "AI-generated", or design-process labels on the slide itself. + +**Bold template selection rules:** + +- Match user purpose and mood against `mood`, `tone`, `best_for`, `avoid_for`, `formality`, `density`, and `scheme`. +- Treat `best_for` examples as soft signals, not strict industry filters. +- Keep the three previews genuinely different from each other. +- After choosing bold template candidate(s), read only those candidate(s)' `preview.md` files from the `preview_md` paths in the selection index. +- Use `preview.md` only for title-slide previews. Do not read full `design.md` files until the user picks the final template. +- Do not read or copy `template.html` unless the selected final `design.md` is missing a critical implementation detail. + +**Preview authenticity rules (NON-NEGOTIABLE):** + +- Every style preview must look like a real first slide from the user's deck, not a diagnostic card. +- Never render internal workflow text on a slide: no `preview`, `generated from`, `preview.md`, `template`, `preset`, `style option`, `Option A/B/C`, file names, paths, or source-doc labels. +- Never render template names or slug names on the slide itself. Template/style names belong only in the message to the user. +- Never render user requirement notes as slide content, such as "sharp and provocative", "safe option", "bold option", "for internal sharing", or "audience: ...", unless the user explicitly wants that exact phrase to appear in the deck. +- If the slide needs chrome, use real deck chrome only: the deck title, section title, date, author, company, page number, or a genuine content phrase from the user's material. +- Before opening previews, inspect the visible text and revise if any internal metadata appears. + +Save previews to `.frontend-slides/slide-previews/` (style-a.html, style-b.html, style-c.html). Each should be self-contained and compact, showing one animated title slide. + +Open each preview automatically for the user. + +### Step 2.1: User Picks + +Ask (header: "Style"): +Which style preview do you prefer? Options: Style A: [Name] / Style B: [Name] / Style C: [Name] / Mix elements + +If "Mix elements", ask for specifics. + +--- + +## Phase 3: Generate Presentation + +Generate the full presentation using content from Phase 1 (text, or text + curated images) and style from Phase 2. + +If images were provided, the slide outline already incorporates them from Step 1.2. If not, CSS-generated visuals (gradients, shapes, patterns) provide visual interest — this is a fully supported first-class path. + +Apply the user's density choice throughout the deck: + +- **Low density / speaker-led:** Use more slides with fewer ideas per slide. Favor large headings, short phrases, visual metaphors, section beats, quote/statement slides, and presenter-friendly pacing. +- **High density / reading-first:** Make slides more self-contained. Use structured grids, comparison tables, annotated diagrams, captions, and concise explanatory copy. Keep hierarchy strong so it feels designed, not like a document pasted onto slides. + +If the user's stated needs are mixed, choose the closer of the two modes instead of inventing a middle option: live audience persuasion defaults low-density; async circulation or detailed review defaults high-density. + +Never let high density become visual clutter. If a high-density slide starts to overflow, split it or redesign it into a clearer structure. + +If the user selected a bold template from `bold-template-pack`, read that one template's full `design.md` before generating. Do not read the other bold templates. Treat `design.md` as the design recipe: + +- Preserve its fonts, palette, decorative vocabulary, spacing rhythm, and component grammar. +- Generate the final deck as a fixed 1920×1080 stage scaled uniformly to the viewport, regardless of whether the source template originally used `deck-stage.js` or viewport-fluid CSS. +- Treat viewport-fluid values in `design.md` as design proportions to translate into 1920×1080 stage coordinates. Do not keep them as live viewport reflow rules in the final deck. +- Keep the output as a single self-contained Frontend Slides HTML file. +- Do not copy demo slide content or mimic the source template too literally. +- Use `template.html` only as a last-resort implementation reference for the selected template. +- After generating, verify both content overflow and panel overlap in rendered browser screenshots. `scrollHeight` checks alone are not enough because grid panels can visually cover each other. + +If the user selected a self-generated custom wildcard, treat that preview's CSS and layout as the design recipe: + +- Preserve its fonts, palette, decorative vocabulary, spacing rhythm, grid logic, and component grammar. +- Expand the same visual system across the full deck. Do not switch to a preset or bold template after the user has chosen the custom direction. +- Design any missing slide layouts from that system rather than importing patterns from another style. +- Keep the output fixed-stage, single-file, and visually verified like every other deck. + +**Before generating, read these supporting files:** + +- [html-template.md](html-template.md) — HTML architecture and JS features +- [viewport-base.css](viewport-base.css) — Mandatory CSS (include in full) +- [animation-patterns.md](animation-patterns.md) — Animation reference for the chosen feeling + +**Key requirements:** + +- Single self-contained HTML file, all CSS/JS inline +- Include the FULL contents of viewport-base.css in the ` + + +
+
+
+

Presentation Title

+

Subtitle or author

+
+ +
+
+

Slide Title

+

Content...

+
+
+ + +
+
+ + + + +``` + +## Required JavaScript Features + +Every presentation must include: + +1. **SlidePresentation Class** — Main controller with: + - Keyboard navigation (arrows, space, page up/down) + - Touch/swipe support + - Mouse wheel navigation + - Optional progress indicator or page count, kept outside the slide stage + +2. **Stage Scaling** — For fixed 16:9 presentation behavior: + - Keep all slides at 1920×1080 inside `.deck-stage` + - Scale the whole stage with one transform + - Letterbox/pillarbox as needed; never reflow slide content per device + +3. **Optional Enhancements** (match to chosen style): + - Custom cursor with trail + - Particle system background (canvas) + - Parallax effects + - 3D tilt on hover + - Magnetic buttons + - Counter animations + +4. **Inline Editing** (included by default after draft generation): + - Edit toggle button (hidden by default, revealed via hover hotzone or `E` key) + - Auto-save to localStorage + - Export/save file functionality + - See "Inline Editing Implementation" section below + +## Inline Editing Implementation + +Inline editing is a lightweight post-draft affordance. Do not ask the user whether they want it during the pre-generation Q&A. Include it by default unless the user explicitly asks for a locked/export-only presentation or no editing controls. + +**Do NOT use CSS `~` sibling selector for hover-based show/hide.** The CSS-only approach (`edit-hotzone:hover ~ .edit-toggle`) fails because `pointer-events: none` on the toggle button breaks the hover chain: user hovers hotzone -> button becomes visible -> mouse moves toward button -> leaves hotzone -> button disappears before click. + +**Required approach: JS-based hover with 400ms delay timeout.** + +HTML: +```html +
+ +``` + +CSS (visibility controlled by JS classes only): +```css +/* Do NOT use CSS ~ sibling selector for this! + pointer-events: none breaks the hover chain. + Must use JS with delay timeout. */ +.edit-hotzone { + position: fixed; top: 0; left: 0; + width: 80px; height: 80px; + z-index: 10000; + cursor: pointer; +} +.edit-toggle { + opacity: 0; + pointer-events: none; + transition: opacity 0.3s ease; + z-index: 10001; +} +.edit-toggle.show, +.edit-toggle.active { + opacity: 1; + pointer-events: auto; +} +``` + +JS (three interaction methods): +```javascript +// 1. Click handler on the toggle button +document.getElementById('editToggle').addEventListener('click', () => { + editor.toggleEditMode(); +}); + +// 2. Hotzone hover with 400ms grace period +const hotzone = document.querySelector('.edit-hotzone'); +const editToggle = document.getElementById('editToggle'); +let hideTimeout = null; + +hotzone.addEventListener('mouseenter', () => { + clearTimeout(hideTimeout); + editToggle.classList.add('show'); +}); +hotzone.addEventListener('mouseleave', () => { + hideTimeout = setTimeout(() => { + if (!editor.isActive) editToggle.classList.remove('show'); + }, 400); +}); +editToggle.addEventListener('mouseenter', () => { + clearTimeout(hideTimeout); +}); +editToggle.addEventListener('mouseleave', () => { + hideTimeout = setTimeout(() => { + if (!editor.isActive) editToggle.classList.remove('show'); + }, 400); +}); + +// 3. Hotzone direct click +hotzone.addEventListener('click', () => { + editor.toggleEditMode(); +}); + +// 4. Keyboard shortcut (E key, skip when editing text) +document.addEventListener('keydown', (e) => { + if ((e.key === 'e' || e.key === 'E') && !e.target.getAttribute('contenteditable')) { + editor.toggleEditMode(); + } +}); +``` + +## Image Pipeline (Skip If No Images) + +If user chose "No images" in Phase 1, skip this entirely. If images were provided, process them before generating HTML. + +**Dependency:** `pip install Pillow` + +### Image Processing + +```python +from PIL import Image, ImageDraw + +# Circular crop (for logos on modern/clean styles) +def crop_circle(input_path, output_path): + img = Image.open(input_path).convert('RGBA') + w, h = img.size + size = min(w, h) + left, top = (w - size) // 2, (h - size) // 2 + img = img.crop((left, top, left + size, top + size)) + mask = Image.new('L', (size, size), 0) + ImageDraw.Draw(mask).ellipse([0, 0, size, size], fill=255) + img.putalpha(mask) + img.save(output_path, 'PNG') + +# Resize (for oversized images that inflate HTML) +def resize_max(input_path, output_path, max_dim=1200): + img = Image.open(input_path) + img.thumbnail((max_dim, max_dim), Image.LANCZOS) + img.save(output_path, quality=85) +``` + +| Situation | Operation | +|-----------|-----------| +| Square logo on rounded aesthetic | `crop_circle()` | +| Image > 1MB | `resize_max(max_dim=1200)` | +| Wrong aspect ratio | Manual crop with `img.crop()` | + +Save processed images with `_processed` suffix. Never overwrite originals. + +### Image Placement + +**Use direct file paths** (not base64) — presentations are viewed locally: + +```html + +Screenshot +``` + +```css +.slide-image { + max-width: 100%; + max-height: min(50vh, 400px); + object-fit: contain; + border-radius: 8px; +} +.slide-image.screenshot { + border: 1px solid rgba(255, 255, 255, 0.1); + border-radius: 12px; + box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3); +} +.slide-image.logo { + max-height: min(30vh, 200px); +} +``` + +**Adapt border/shadow colors to match the chosen style's accent.** Never repeat the same image on multiple slides (except logos on title + closing). + +**Placement patterns:** Logo centered on title slide. Screenshots in two-column layouts with text. Full-bleed images as slide backgrounds with text overlay (use sparingly). + +--- + +## Code Quality + +**Comments:** Every section needs clear comments explaining what it does and how to modify it. + +**Accessibility:** +- Semantic HTML (`
`, `