diff --git a/SKILL.md b/SKILL.md index 9b8374bf..110dccf7 100644 --- a/SKILL.md +++ b/SKILL.md @@ -249,12 +249,17 @@ If the user selected a self-generated custom wildcard, treat that preview's CSS ## Phase 4: PPT Conversion -When converting PowerPoint files: +When converting PowerPoint files, read [references/ppt-conversion.md](references/ppt-conversion.md) and follow that workflow. -1. **Extract content** — Run `python scripts/extract-pptx.py ` (install python-pptx if needed: `pip install python-pptx`) -2. **Confirm with user** — Present extracted slide titles, content summaries, and image counts -3. **Style selection** — Proceed to Phase 2 for style discovery -4. **Generate HTML** — Convert to chosen style, preserving all text, images (from assets/), slide order, and speaker notes (as HTML comments) +Core loop: + +1. Run `python scripts/extract-pptx.py `. +2. Inspect `extracted-slides.json` plus extracted assets. +3. Summarize slide titles, content, image counts, tables/charts, and any extraction uncertainty for the user. +4. Proceed to Phase 2 for visual style discovery. +5. Generate a fixed-stage HTML deck that preserves text, images, slide order, and speaker notes as HTML comments. + +If a source slide is too dense for a 1920×1080 stage, split it into multiple HTML slides instead of shrinking content until it becomes cramped. --- @@ -273,94 +278,15 @@ When converting PowerPoint files: ## Phase 6: Share & Export (Optional) -After delivery, **ask the user:** _"Would you like to share this presentation? I can deploy it to a live URL (works on any device including phones) or export it as a PDF."_ - -Options: - -- **Deploy to URL** — Shareable link that works on any device -- **Export to PDF** — Universal file for email, Slack, print -- **Both** -- **No thanks** - -If the user declines, stop here. If they choose one or both, proceed below. - -### 6A: Deploy to a Live URL (Vercel) - -This deploys the presentation to Vercel — a free hosting platform. The link works on any device (phones, tablets, laptops) and stays live until the user takes it down. - -**If the user has never deployed before, guide them step by step:** - -1. **Check if Vercel CLI is installed** — Run `npx vercel --version`. If not found, install Node.js first (`brew install node` on macOS, or download from https://nodejs.org). - -2. **Check if user is logged in** — Run `npx vercel whoami`. - - If NOT logged in, explain: _"Vercel is a free hosting service. You need an account to deploy. Let me walk you through it:"_ - - Step 1: Ask user to go to https://vercel.com/signup in their browser - - Step 2: They can sign up with GitHub, Google, email — whatever is easiest - - Step 3: Once signed up, run `vercel login` and follow the prompts (it opens a browser window to authorize) - - Step 4: Confirm login with `vercel whoami` - - Wait for the user to confirm they're logged in before proceeding. - -3. **Deploy** — Run the deploy script: - - ```bash - bash scripts/deploy.sh - ``` - - The script accepts either a folder (with index.html) or a single HTML file. - -4. **Share the URL** — Tell the user: - - The live URL (from the script output) - - That it works on any device — they can text it, Slack it, email it - - To take it down later: visit https://vercel.com/dashboard and delete the project - - The Vercel free tier is generous — they won't be charged - -**⚠ Deployment gotchas:** - -- **Local images/videos must travel with the HTML.** The deploy script auto-detects files referenced via `src="..."` in the HTML and bundles them. But if the presentation references files via CSS `background-image` or unusual paths, those may be missed. **Before deploying, verify:** open the deployed URL and check that all images load. If any are broken, the safest fix is to put the HTML and all its assets into a single folder and deploy the folder instead of a standalone HTML file. -- **Prefer folder deployments when the presentation has many assets.** If the presentation lives in a folder with images alongside it (e.g., `my-deck/index.html` + `my-deck/logo.png`), deploy the folder directly: `bash scripts/deploy.sh ./my-deck/`. This is more reliable than deploying a single HTML file because the entire folder contents are uploaded as-is. -- **Filenames with spaces work but can cause issues.** The script handles spaces in filenames, but Vercel URLs encode spaces as `%20`. If possible, avoid spaces in image filenames. If the user's images have spaces, the script handles it — but if images still break, renaming files to use hyphens instead of spaces is the fix. -- **Redeploying updates the same URL.** Running the deploy script again on the same presentation overwrites the previous deployment. The URL stays the same — no need to share a new link. - -### 6B: Export to PDF - -This captures each slide as a screenshot and combines them into a PDF. Perfect for email attachments, embedding in documents, or printing. - -**Note:** Animations and interactivity are not preserved — the PDF is a static snapshot. This is normal and expected; mention it to the user so they're not surprised. - -1. **Run the export script:** - - ```bash - bash scripts/export-pdf.sh [output.pdf] - ``` - - If no output path is given, the PDF is saved next to the HTML file. - -2. **What happens behind the scenes** (explain briefly to the user): - - A headless browser opens the presentation at 1920×1080 (standard widescreen) - - It screenshots each slide one by one - - All screenshots are combined into a single PDF - - The script needs Playwright (a browser automation tool) — it will install automatically if missing - -3. **If Playwright installation fails:** - - The most common issue is Chromium not downloading. Run: `npx playwright install chromium` - - If that fails too, it may be a network/firewall issue. Ask the user to try on a different network. +After delivery, ask the user: _"Would you like to share this presentation? I can deploy it to a live URL, export it as a PDF, do both, or leave it as HTML."_ -4. **Deliver the PDF** — The script auto-opens it. Tell the user: - - The file location and size - - That it works everywhere — email, Slack, Notion, Google Docs, print - - Animations are replaced by their final visual state (still looks great, just static) +If the user declines, stop. If they choose deployment or PDF export, read [references/share-export.md](references/share-export.md) and use the bundled scripts: -**⚠ PDF export gotchas:** +- **Deploy to URL:** `bash scripts/deploy.sh ` +- **Export to PDF:** `bash scripts/export-pdf.sh [output.pdf]` +- **Compact PDF:** `bash scripts/export-pdf.sh [output.pdf] --compact` -- **First run is slow.** The script installs Playwright and downloads a Chromium browser (~150MB) into a temp directory. This happens once per run. Warn the user it may take 30-60 seconds the first time — subsequent exports within the same session are faster. -- **Slides must use `class="slide"`.** The export script finds slides by querying `.slide` elements. If the presentation uses a different class name, the script will report "0 slides found" and fail. All presentations generated by this skill use `.slide`, so this only matters for externally-created HTML. -- **Local images must be loadable via HTTP.** The script starts a local server and loads the HTML through it (so Google Fonts and relative image paths work). If images use absolute filesystem paths (e.g., `src="/Users/name/photo.png"`) instead of relative paths (e.g., `src="photo.png"`), they won't load. Generated presentations always use relative paths, but converted or user-provided decks might not — check and fix if needed. -- **Local images appear in the PDF** as long as they are in the same directory as (or relative to) the HTML file. The export script serves the HTML's parent directory over HTTP, so relative paths like `src="photo.png"` resolve correctly — including filenames with spaces. If images still don't appear, check: (1) the image files actually exist at the referenced path, (2) the paths are relative, not absolute filesystem paths like `/Users/name/photo.png`. -- **Large presentations produce large PDFs.** Each slide is captured as a full 1920×1080 PNG screenshot. An 18-slide deck can produce a ~20MB PDF. If the PDF exceeds 10MB, ask the user: _"The PDF is [size]. Would you like me to compress it? It'll look slightly less sharp but the file will be much smaller."_ If yes, re-run the export with the `--compact` flag: - ```bash - bash scripts/export-pdf.sh [output.pdf] --compact - ``` - This renders at 1280×720 instead of 1920×1080, typically cutting file size by 50-70% with minimal visual difference. +Do not deploy a deck publicly without explicit user approval. Set expectations that PDFs are static snapshots: animations, inline editing, keyboard navigation, and browser interactivity are not preserved. --- @@ -375,6 +301,8 @@ This captures each slide as a screenshot and combines them into a PDF. Perfect f | [viewport-base.css](viewport-base.css) | Mandatory fixed-stage CSS — copy into every presentation | Phase 3 (generation) | | [html-template.md](html-template.md) | HTML structure, JS features, code quality standards | Phase 3 (generation) | | [animation-patterns.md](animation-patterns.md) | CSS/JS animation snippets and effect-to-feeling guide | Phase 3 (generation) | -| [scripts/extract-pptx.py](scripts/extract-pptx.py) | Python script for PPT content extraction | Phase 4 (conversion) | +| [references/ppt-conversion.md](references/ppt-conversion.md) | Detailed PPT conversion workflow and JSON interpretation guidance | Phase 4 (conversion) | +| [references/share-export.md](references/share-export.md) | Deployment and PDF export guidance, gotchas, and delivery messaging | Phase 6 (sharing/export) | +| [scripts/extract-pptx.py](scripts/extract-pptx.py) | Python script for PPT content/layout extraction | Phase 4 (conversion) | | [scripts/deploy.sh](scripts/deploy.sh) | Deploy slides to Vercel for instant sharing | Phase 6 (sharing) | -| [scripts/export-pdf.sh](scripts/export-pdf.sh) | Export slides to PDF | Phase 6 (sharing) | +| [scripts/export-pdf.sh](scripts/export-pdf.sh) | Export slides to static PDF | Phase 6 (export) | diff --git a/plugins/frontend-slides/skills/frontend-slides/SKILL.md b/plugins/frontend-slides/skills/frontend-slides/SKILL.md index 9b8374bf..110dccf7 100644 --- a/plugins/frontend-slides/skills/frontend-slides/SKILL.md +++ b/plugins/frontend-slides/skills/frontend-slides/SKILL.md @@ -249,12 +249,17 @@ If the user selected a self-generated custom wildcard, treat that preview's CSS ## Phase 4: PPT Conversion -When converting PowerPoint files: +When converting PowerPoint files, read [references/ppt-conversion.md](references/ppt-conversion.md) and follow that workflow. -1. **Extract content** — Run `python scripts/extract-pptx.py ` (install python-pptx if needed: `pip install python-pptx`) -2. **Confirm with user** — Present extracted slide titles, content summaries, and image counts -3. **Style selection** — Proceed to Phase 2 for style discovery -4. **Generate HTML** — Convert to chosen style, preserving all text, images (from assets/), slide order, and speaker notes (as HTML comments) +Core loop: + +1. Run `python scripts/extract-pptx.py `. +2. Inspect `extracted-slides.json` plus extracted assets. +3. Summarize slide titles, content, image counts, tables/charts, and any extraction uncertainty for the user. +4. Proceed to Phase 2 for visual style discovery. +5. Generate a fixed-stage HTML deck that preserves text, images, slide order, and speaker notes as HTML comments. + +If a source slide is too dense for a 1920×1080 stage, split it into multiple HTML slides instead of shrinking content until it becomes cramped. --- @@ -273,94 +278,15 @@ When converting PowerPoint files: ## Phase 6: Share & Export (Optional) -After delivery, **ask the user:** _"Would you like to share this presentation? I can deploy it to a live URL (works on any device including phones) or export it as a PDF."_ - -Options: - -- **Deploy to URL** — Shareable link that works on any device -- **Export to PDF** — Universal file for email, Slack, print -- **Both** -- **No thanks** - -If the user declines, stop here. If they choose one or both, proceed below. - -### 6A: Deploy to a Live URL (Vercel) - -This deploys the presentation to Vercel — a free hosting platform. The link works on any device (phones, tablets, laptops) and stays live until the user takes it down. - -**If the user has never deployed before, guide them step by step:** - -1. **Check if Vercel CLI is installed** — Run `npx vercel --version`. If not found, install Node.js first (`brew install node` on macOS, or download from https://nodejs.org). - -2. **Check if user is logged in** — Run `npx vercel whoami`. - - If NOT logged in, explain: _"Vercel is a free hosting service. You need an account to deploy. Let me walk you through it:"_ - - Step 1: Ask user to go to https://vercel.com/signup in their browser - - Step 2: They can sign up with GitHub, Google, email — whatever is easiest - - Step 3: Once signed up, run `vercel login` and follow the prompts (it opens a browser window to authorize) - - Step 4: Confirm login with `vercel whoami` - - Wait for the user to confirm they're logged in before proceeding. - -3. **Deploy** — Run the deploy script: - - ```bash - bash scripts/deploy.sh - ``` - - The script accepts either a folder (with index.html) or a single HTML file. - -4. **Share the URL** — Tell the user: - - The live URL (from the script output) - - That it works on any device — they can text it, Slack it, email it - - To take it down later: visit https://vercel.com/dashboard and delete the project - - The Vercel free tier is generous — they won't be charged - -**⚠ Deployment gotchas:** - -- **Local images/videos must travel with the HTML.** The deploy script auto-detects files referenced via `src="..."` in the HTML and bundles them. But if the presentation references files via CSS `background-image` or unusual paths, those may be missed. **Before deploying, verify:** open the deployed URL and check that all images load. If any are broken, the safest fix is to put the HTML and all its assets into a single folder and deploy the folder instead of a standalone HTML file. -- **Prefer folder deployments when the presentation has many assets.** If the presentation lives in a folder with images alongside it (e.g., `my-deck/index.html` + `my-deck/logo.png`), deploy the folder directly: `bash scripts/deploy.sh ./my-deck/`. This is more reliable than deploying a single HTML file because the entire folder contents are uploaded as-is. -- **Filenames with spaces work but can cause issues.** The script handles spaces in filenames, but Vercel URLs encode spaces as `%20`. If possible, avoid spaces in image filenames. If the user's images have spaces, the script handles it — but if images still break, renaming files to use hyphens instead of spaces is the fix. -- **Redeploying updates the same URL.** Running the deploy script again on the same presentation overwrites the previous deployment. The URL stays the same — no need to share a new link. - -### 6B: Export to PDF - -This captures each slide as a screenshot and combines them into a PDF. Perfect for email attachments, embedding in documents, or printing. - -**Note:** Animations and interactivity are not preserved — the PDF is a static snapshot. This is normal and expected; mention it to the user so they're not surprised. - -1. **Run the export script:** - - ```bash - bash scripts/export-pdf.sh [output.pdf] - ``` - - If no output path is given, the PDF is saved next to the HTML file. - -2. **What happens behind the scenes** (explain briefly to the user): - - A headless browser opens the presentation at 1920×1080 (standard widescreen) - - It screenshots each slide one by one - - All screenshots are combined into a single PDF - - The script needs Playwright (a browser automation tool) — it will install automatically if missing - -3. **If Playwright installation fails:** - - The most common issue is Chromium not downloading. Run: `npx playwright install chromium` - - If that fails too, it may be a network/firewall issue. Ask the user to try on a different network. +After delivery, ask the user: _"Would you like to share this presentation? I can deploy it to a live URL, export it as a PDF, do both, or leave it as HTML."_ -4. **Deliver the PDF** — The script auto-opens it. Tell the user: - - The file location and size - - That it works everywhere — email, Slack, Notion, Google Docs, print - - Animations are replaced by their final visual state (still looks great, just static) +If the user declines, stop. If they choose deployment or PDF export, read [references/share-export.md](references/share-export.md) and use the bundled scripts: -**⚠ PDF export gotchas:** +- **Deploy to URL:** `bash scripts/deploy.sh ` +- **Export to PDF:** `bash scripts/export-pdf.sh [output.pdf]` +- **Compact PDF:** `bash scripts/export-pdf.sh [output.pdf] --compact` -- **First run is slow.** The script installs Playwright and downloads a Chromium browser (~150MB) into a temp directory. This happens once per run. Warn the user it may take 30-60 seconds the first time — subsequent exports within the same session are faster. -- **Slides must use `class="slide"`.** The export script finds slides by querying `.slide` elements. If the presentation uses a different class name, the script will report "0 slides found" and fail. All presentations generated by this skill use `.slide`, so this only matters for externally-created HTML. -- **Local images must be loadable via HTTP.** The script starts a local server and loads the HTML through it (so Google Fonts and relative image paths work). If images use absolute filesystem paths (e.g., `src="/Users/name/photo.png"`) instead of relative paths (e.g., `src="photo.png"`), they won't load. Generated presentations always use relative paths, but converted or user-provided decks might not — check and fix if needed. -- **Local images appear in the PDF** as long as they are in the same directory as (or relative to) the HTML file. The export script serves the HTML's parent directory over HTTP, so relative paths like `src="photo.png"` resolve correctly — including filenames with spaces. If images still don't appear, check: (1) the image files actually exist at the referenced path, (2) the paths are relative, not absolute filesystem paths like `/Users/name/photo.png`. -- **Large presentations produce large PDFs.** Each slide is captured as a full 1920×1080 PNG screenshot. An 18-slide deck can produce a ~20MB PDF. If the PDF exceeds 10MB, ask the user: _"The PDF is [size]. Would you like me to compress it? It'll look slightly less sharp but the file will be much smaller."_ If yes, re-run the export with the `--compact` flag: - ```bash - bash scripts/export-pdf.sh [output.pdf] --compact - ``` - This renders at 1280×720 instead of 1920×1080, typically cutting file size by 50-70% with minimal visual difference. +Do not deploy a deck publicly without explicit user approval. Set expectations that PDFs are static snapshots: animations, inline editing, keyboard navigation, and browser interactivity are not preserved. --- @@ -375,6 +301,8 @@ This captures each slide as a screenshot and combines them into a PDF. Perfect f | [viewport-base.css](viewport-base.css) | Mandatory fixed-stage CSS — copy into every presentation | Phase 3 (generation) | | [html-template.md](html-template.md) | HTML structure, JS features, code quality standards | Phase 3 (generation) | | [animation-patterns.md](animation-patterns.md) | CSS/JS animation snippets and effect-to-feeling guide | Phase 3 (generation) | -| [scripts/extract-pptx.py](scripts/extract-pptx.py) | Python script for PPT content extraction | Phase 4 (conversion) | +| [references/ppt-conversion.md](references/ppt-conversion.md) | Detailed PPT conversion workflow and JSON interpretation guidance | Phase 4 (conversion) | +| [references/share-export.md](references/share-export.md) | Deployment and PDF export guidance, gotchas, and delivery messaging | Phase 6 (sharing/export) | +| [scripts/extract-pptx.py](scripts/extract-pptx.py) | Python script for PPT content/layout extraction | Phase 4 (conversion) | | [scripts/deploy.sh](scripts/deploy.sh) | Deploy slides to Vercel for instant sharing | Phase 6 (sharing) | -| [scripts/export-pdf.sh](scripts/export-pdf.sh) | Export slides to PDF | Phase 6 (sharing) | +| [scripts/export-pdf.sh](scripts/export-pdf.sh) | Export slides to static PDF | Phase 6 (export) | diff --git a/plugins/frontend-slides/skills/frontend-slides/references/ppt-conversion.md b/plugins/frontend-slides/skills/frontend-slides/references/ppt-conversion.md new file mode 100644 index 00000000..43b36c4b --- /dev/null +++ b/plugins/frontend-slides/skills/frontend-slides/references/ppt-conversion.md @@ -0,0 +1,60 @@ +# PPT Conversion Reference + +Use this reference only when the user provides a PowerPoint file or asks to convert PPT/PPTX into a Frontend Slides HTML deck. + +## Conversion Workflow + +1. **Extract** + ```bash + python scripts/extract-pptx.py + ``` + If `python-pptx` is missing, install it: + ```bash + python -m pip install python-pptx + ``` + +2. **Inspect the extraction output** + - Read `/extracted-slides.json`. + - Use `slides[*].title`, `slides[*].content`, `slides[*].images`, `slides[*].tables`, `slides[*].charts`, `slides[*].notes`, and `slides[*].shapes`. + - Treat `slide_size` and each shape `geometry` as layout clues, not mandatory pixel-perfect constraints. + +3. **Summarize for the user before redesign** + - Report slide count. + - List each slide title or first meaningful phrase. + - Mention image/table/chart counts. + - Ask for confirmation only when content extraction is ambiguous or incomplete. + +4. **Run normal style discovery** + - Continue to Phase 2 in `SKILL.md`. + - Generate three real title-slide previews using the extracted content, not placeholder copy. + - Do not show template names or internal labels on the preview slides. + +5. **Generate the final HTML deck** + - Preserve all extracted text unless the user approves editing. + - Preserve slide order unless the user asks for restructuring. + - Use extracted images from `assets/`. + - Convert speaker notes into HTML comments near the related slide. + - Convert tables into designed slide-native table/card layouts. + - Convert chart data into CSS/SVG/HTML visualizations when feasible; otherwise summarize the chart clearly and preserve the original chart image if available. + - If one PowerPoint slide is too dense for a fixed 1920×1080 stage, split it into multiple HTML slides and note the split. + +## Layout Interpretation + +The extractor records geometry in EMUs, approximate pixels, and inches. Use it to understand hierarchy: + +- Larger/upper text boxes usually indicate titles. +- Repeated left/top positions often indicate a template grid. +- High z-order can indicate overlay labels, annotations, or callouts. +- Image coordinates help preserve intended visual relationships. + +Do not blindly recreate PowerPoint chrome if it is weak. Frontend Slides should preserve content and intent while improving design quality. + +## Quality Checks + +After generation: + +- Verify every slide remains inside the fixed 1920×1080 stage. +- Check screenshots at 1280×720 and at least one phone viewport. +- Confirm no text overflows, panels overlap, or images stretch incorrectly. +- Confirm image paths are relative and load from the generated HTML location. +- Confirm speaker notes are preserved as comments if notes existed. diff --git a/plugins/frontend-slides/skills/frontend-slides/references/share-export.md b/plugins/frontend-slides/skills/frontend-slides/references/share-export.md new file mode 100644 index 00000000..e16435c9 --- /dev/null +++ b/plugins/frontend-slides/skills/frontend-slides/references/share-export.md @@ -0,0 +1,88 @@ +# Share and Export Reference + +Use this reference only after the HTML deck has been delivered and the user asks to deploy, share, export, or package it. + +## Ask First + +Ask the user which delivery format they want: + +- **Deploy to URL** — public Vercel link that works on any device. +- **Export to PDF** — static file for email, Slack, Notion, print, or archives. +- **Both**. +- **No thanks**. + +Do not deploy to a public URL without explicit user approval. + +## Deploy to Vercel + +Use: + +```bash +bash scripts/deploy.sh +``` + +The script accepts: + +- a folder containing `index.html`, or +- a single `.html` file. + +Prefer folder deployment when the presentation has many local assets. Folder deployment uploads the complete folder as-is and is less fragile than reconstructing asset references from a single HTML file. + +### Before deploying + +- Confirm the deck opens locally. +- Confirm image/video/font paths are relative, not absolute filesystem paths. +- If using a single HTML file, ensure referenced assets live beside it or in common asset folders such as `assets/`, `images/`, `fonts/`, or `media/`. +- If the user has never deployed before, explain that Vercel requires an account and CLI login. + +### After deploying + +Tell the user: + +- the live URL from the script output, +- that the URL works on phones, tablets, and desktops, +- that they can remove it later from the Vercel dashboard, +- that they should visually check the live URL for missing assets. + +## Export to PDF + +Use: + +```bash +bash scripts/export-pdf.sh [output.pdf] +``` + +For a smaller PDF: + +```bash +bash scripts/export-pdf.sh [output.pdf] --compact +``` + +The export script: + +- starts a localhost-only static server, +- opens the deck in Playwright/Chromium, +- screenshots each `.slide`, +- forces reveal animations into a static visible state, +- combines screenshots into a PDF. + +### Set expectations + +Tell the user that the PDF is static. Animations, keyboard navigation, inline editing, and browser interactivity are not preserved. + +### Common fixes + +- **0 slides found:** the HTML must contain `.slide` elements. +- **Missing images:** fix absolute paths; use relative paths beside the HTML or inside an asset folder. +- **First run is slow:** Playwright may need to download Chromium. +- **Large PDF:** rerun with `--compact`, which renders at 1280×720 instead of 1920×1080. +- **Corporate firewall blocks Chromium download:** run `npx playwright install chromium` on an allowed network or use a machine that already has Playwright browsers installed. + +## Final Delivery Message + +After deploy/export, include: + +- file path or live URL, +- slide count, +- known limitations, +- one concise next action, such as "Review the live URL for assets" or "Use compact export if the PDF is too large." diff --git a/references/ppt-conversion.md b/references/ppt-conversion.md new file mode 100644 index 00000000..43b36c4b --- /dev/null +++ b/references/ppt-conversion.md @@ -0,0 +1,60 @@ +# PPT Conversion Reference + +Use this reference only when the user provides a PowerPoint file or asks to convert PPT/PPTX into a Frontend Slides HTML deck. + +## Conversion Workflow + +1. **Extract** + ```bash + python scripts/extract-pptx.py + ``` + If `python-pptx` is missing, install it: + ```bash + python -m pip install python-pptx + ``` + +2. **Inspect the extraction output** + - Read `/extracted-slides.json`. + - Use `slides[*].title`, `slides[*].content`, `slides[*].images`, `slides[*].tables`, `slides[*].charts`, `slides[*].notes`, and `slides[*].shapes`. + - Treat `slide_size` and each shape `geometry` as layout clues, not mandatory pixel-perfect constraints. + +3. **Summarize for the user before redesign** + - Report slide count. + - List each slide title or first meaningful phrase. + - Mention image/table/chart counts. + - Ask for confirmation only when content extraction is ambiguous or incomplete. + +4. **Run normal style discovery** + - Continue to Phase 2 in `SKILL.md`. + - Generate three real title-slide previews using the extracted content, not placeholder copy. + - Do not show template names or internal labels on the preview slides. + +5. **Generate the final HTML deck** + - Preserve all extracted text unless the user approves editing. + - Preserve slide order unless the user asks for restructuring. + - Use extracted images from `assets/`. + - Convert speaker notes into HTML comments near the related slide. + - Convert tables into designed slide-native table/card layouts. + - Convert chart data into CSS/SVG/HTML visualizations when feasible; otherwise summarize the chart clearly and preserve the original chart image if available. + - If one PowerPoint slide is too dense for a fixed 1920×1080 stage, split it into multiple HTML slides and note the split. + +## Layout Interpretation + +The extractor records geometry in EMUs, approximate pixels, and inches. Use it to understand hierarchy: + +- Larger/upper text boxes usually indicate titles. +- Repeated left/top positions often indicate a template grid. +- High z-order can indicate overlay labels, annotations, or callouts. +- Image coordinates help preserve intended visual relationships. + +Do not blindly recreate PowerPoint chrome if it is weak. Frontend Slides should preserve content and intent while improving design quality. + +## Quality Checks + +After generation: + +- Verify every slide remains inside the fixed 1920×1080 stage. +- Check screenshots at 1280×720 and at least one phone viewport. +- Confirm no text overflows, panels overlap, or images stretch incorrectly. +- Confirm image paths are relative and load from the generated HTML location. +- Confirm speaker notes are preserved as comments if notes existed. diff --git a/references/share-export.md b/references/share-export.md new file mode 100644 index 00000000..e16435c9 --- /dev/null +++ b/references/share-export.md @@ -0,0 +1,88 @@ +# Share and Export Reference + +Use this reference only after the HTML deck has been delivered and the user asks to deploy, share, export, or package it. + +## Ask First + +Ask the user which delivery format they want: + +- **Deploy to URL** — public Vercel link that works on any device. +- **Export to PDF** — static file for email, Slack, Notion, print, or archives. +- **Both**. +- **No thanks**. + +Do not deploy to a public URL without explicit user approval. + +## Deploy to Vercel + +Use: + +```bash +bash scripts/deploy.sh +``` + +The script accepts: + +- a folder containing `index.html`, or +- a single `.html` file. + +Prefer folder deployment when the presentation has many local assets. Folder deployment uploads the complete folder as-is and is less fragile than reconstructing asset references from a single HTML file. + +### Before deploying + +- Confirm the deck opens locally. +- Confirm image/video/font paths are relative, not absolute filesystem paths. +- If using a single HTML file, ensure referenced assets live beside it or in common asset folders such as `assets/`, `images/`, `fonts/`, or `media/`. +- If the user has never deployed before, explain that Vercel requires an account and CLI login. + +### After deploying + +Tell the user: + +- the live URL from the script output, +- that the URL works on phones, tablets, and desktops, +- that they can remove it later from the Vercel dashboard, +- that they should visually check the live URL for missing assets. + +## Export to PDF + +Use: + +```bash +bash scripts/export-pdf.sh [output.pdf] +``` + +For a smaller PDF: + +```bash +bash scripts/export-pdf.sh [output.pdf] --compact +``` + +The export script: + +- starts a localhost-only static server, +- opens the deck in Playwright/Chromium, +- screenshots each `.slide`, +- forces reveal animations into a static visible state, +- combines screenshots into a PDF. + +### Set expectations + +Tell the user that the PDF is static. Animations, keyboard navigation, inline editing, and browser interactivity are not preserved. + +### Common fixes + +- **0 slides found:** the HTML must contain `.slide` elements. +- **Missing images:** fix absolute paths; use relative paths beside the HTML or inside an asset folder. +- **First run is slow:** Playwright may need to download Chromium. +- **Large PDF:** rerun with `--compact`, which renders at 1280×720 instead of 1920×1080. +- **Corporate firewall blocks Chromium download:** run `npx playwright install chromium` on an allowed network or use a machine that already has Playwright browsers installed. + +## Final Delivery Message + +After deploy/export, include: + +- file path or live URL, +- slide count, +- known limitations, +- one concise next action, such as "Review the live URL for assets" or "Use compact export if the PDF is too large."