html2pptx-local-mcp 1.1.20 → 1.1.21

package/public/skills/html2pptx/references/automation-contract.md

@@ -0,0 +1,68 @@
+# Automation Contract
+
+Use this reference when an agent needs the current public automation surface.
+
+## Public REST Routes
+
+- `GET /api/export/plans`
+  - Returns public plan metadata and the recommended commercial tier.
+- `POST /api/export/jobs`
+  - Creates a commercial export job.
+- `GET /api/export/jobs/{jobId}`
+  - Returns the current job state.
+
+## Authentication
+
+Use either:
+
+- `Authorization: Bearer <api_key>`
+- `x-api-key: <api_key>`
+
+## Expected payload
+
+```json
+{
+  "html": "<section class=\"slide\">...</section>",
+  "css": ".slide { width: 1600px; min-height: 900px; }",
+  "fileName": "deck.pptx",
+  "autoEmbedFonts": false,
+  "metadata": {
+    "channel": "agent"
+  }
+}
+```
+
+## Job lifecycle
+
+Typical states:
+
+- `queued`
+- `processing`
+- `completed`
+- `failed`
+
+Completed jobs may include:
+
+- `fileName`
+- `mimeType`
+- `fileBase64`
+
+For agent-facing summaries, do not dump `fileBase64` unless explicitly required. Public API and MCP sanitize untrusted SVG and rasterize it before export.
+
+## MCP mapping
+
+The public stdio MCP server in this repo wraps the same REST routes:
+
+- `html2pptx_list_export_plans`
+- `html2pptx_create_export_job`
+- `html2pptx_get_export_job`
+- `html2pptx_wait_for_export_job`
+
+### MCP response format
+
+The MCP server defaults to `responseFormat: "both"`, returning:
+
+1. **`resource` content block** — embedded PPTX as `blob` (base64), MCP spec compliant
+2. **`text` content block** — `Download: <presigned URL>` for clients that cannot handle blob resources
+
+This ensures compatibility with Claude Code and other MCP clients. Agents should extract the download URL from the text block and use `curl -s -L -o <fileName> "<url>"` to save the file locally.

package/public/skills/html2pptx/references/input-contract.md

@@ -0,0 +1,107 @@
+# Input Contract
+
+Use this reference when deciding whether HTML/CSS is suitable for HTML-to-PPTX export.
+
+## Core Rule
+
+Accept slide-oriented HTML, not arbitrary webpages.
+
+The ideal input is:
+
+- fixed-size
+- static at capture time
+- self-contained
+- visually complete without runtime application logic
+
+## Accept
+
+- One or more `.slide` roots
+- Explicit slide dimensions
+- Normal DOM text content
+- `div`, `section`, `article`, `header`, `footer`
+- `h1`-`h6`, `p`, `span`
+- `ul`, `ol`, `li`
+- `table`, `tr`, `th`, `td`
+- `img`
+- `svg`
+- Basic forms of `input[type="text"]` and `textarea` when treated as simple text
+
+## Accept with Possible Degradation
+
+- `canvas`
+- backdrop blur
+- icon fonts and icon-only elements
+- complex rounded clipping
+- some generated gradient and border effects
+- SVG that is accepted but may be sanitized and rasterized before export on public surfaces
+
+These can export successfully while losing editability.
+
+## Reject or Rewrite First
+
+- `<script>` tags
+- inline event handlers such as `onclick`
+- `javascript:` URLs
+- `iframe`
+- `video`
+- `audio`
+- `embed`
+- `object`
+- app shells with navigation, tabs, drawers, filters, and runtime controls
+- content that requires hydration, async data loading, or external bootstrapping
+- long responsive pages intended for scrolling
+
+## CSS That Usually Works
+
+- `background-color`
+- `background-image: linear-gradient(...)`
+- `color`
+- `opacity`
+- `border-*`
+- `border-radius`
+- `box-shadow`
+- `filter: blur()`
+- `transform: rotate()`
+- `position`
+- `width`, `height`
+- `padding`, `margin`
+- `text-align`
+- `font-family`, `font-size`, `font-weight`, `font-style`, `line-height`
+- final layouts produced by Flexbox or Grid
+
+## Slide Fit Best Practice
+
+Every `.slide` must have `margin: 0; padding: 0; box-sizing: border-box; overflow: hidden; position: relative`. Backgrounds must be applied on the `.slide` itself, not on an inner wrapper. Content padding goes on an inner layout `div`, not on `.slide`. This ensures the slide fills the PowerPoint canvas edge-to-edge with no white gaps.
+
+## Text Alignment Best Practice
+
+Text inside background-colored elements (buttons, badges, cards) MUST NOT be a separate child element when possible. The PPTX converter splits background shapes and text boxes into independent objects, causing misalignment. Preferred approach: put text directly in the background element with explicit `width`, `height`, `text-align: center`, and flexbox centering. If a child element is necessary, give it `width: 100%` and `text-align: center`. Never rely on padding alone to size background elements — always use explicit dimensions.
+
+## CSS That Commonly Causes Trouble
+
+- `transform: scale()`
+- `mix-blend-mode`
+- `mask`
+- `clip-path` chains
+- `background-clip: text`
+- filter stacks beyond simple blur
+- viewport-driven responsive behavior without fixed slide dimensions
+
+## Asset Constraints
+
+Assume that fonts and images must be readable by the browser at export time.
+
+Watch for:
+
+- images without reliable CORS
+- font files without reliable CORS
+- tainted `canvas` output caused by cross-origin drawing
+
+## Verdict Heuristic
+
+Use this shorthand:
+
+- `safe`: fixed-size, static, CORS-safe, mostly standard DOM/CSS
+- `safe with degradation`: export likely succeeds but some regions rasterize
+- `needs rewrite`: structure is web-like or effect-heavy, but content is salvageable
+- `out of scope`: input behaves like an application or unsupported document

package/public/skills/html2pptx/references/japanese-slide-design.md

@@ -0,0 +1,273 @@
+# Japanese Slide Design Reference
+
+Use this reference when generating slides for Japanese audiences or when the user's request is in Japanese. These rules override generic defaults with Japan-specific typography, structure, and information design guidelines.
+
+## Core Principles
+
+1. **Conclusion first** — show the answer/proposal before the reasoning
+2. **1 slide = 1 message** — if there are multiple claims, split into separate slides
+3. **Density is contextual** — presentation mode (projecting) vs. handout mode (reading) have different text limits
+4. **Alignment and grid** — Japanese audiences expect consistent alignment and visual hierarchy
+5. **Restraint in color** — 3 colors max (base + main + accent), avoid raw/saturated primary colors
+
+## Character Count Limits
+
+| Element | Max characters | Notes |
+|---------|---------------|-------|
+| Slide title | 9-13 | Instant perception limit. Noun ending (体言止め) |
+| Slide message (assertion) | 50 | One sentence, written as a complete claim |
+| Single bullet / line | 40 | ~10 seconds to comprehend |
+| Total per slide (presentation mode) | 105 | Target for projected slides |
+| Total per slide (handout mode) | 200-285 | Use cards/boxes to organize density |
+| Line length (projection) | 20-30 chars | For text read at a glance |
+| Line length (reading) | 35-40 chars | For explanatory text |
+
+## Slide Anatomy
+
+Each slide has 3 distinct text layers:
+
+1. **Title** (top) — short, objective, noun-ending. Labels the content, no claims. Example: "売上推移" not "売上が減少"
+2. **Message** (below title) — one sentence, max 50 chars, contains the assertion with a comparison target and quantified difference. Example: "前年比15%増、目標を3ヶ月前倒しで達成"
+3. **Body** — bullets, diagrams, or data supporting the message
+
+## Deck Structure (Conclusion-First)
+
+```
+表紙 → サマリー → アジェンダ(3-5項目) → 背景 → 課題 → 提案(結論) → 根拠 → 実行計画 → リスク → 結論・次アクション → 付録
+```
+
+| Section | Recommended visual |
+|---------|-------------------|
+| Background/Context | Bullet points |
+| Problem/Issue | Graphs (quantitative evidence) |
+| Solution/Proposal | Diagrams (flow, process, structure) |
+| Effect/Benefit | Diagrams + graphs combined |
+
+## Typography
+
+### Font Stack
+
+```css
+font-family: "Noto Sans JP", "BIZ UDPGothic", "Hiragino Kaku Gothic ProN", sans-serif;
+```
+
+- **Noto Sans JP** — primary (open source, cross-platform)
+- **BIZ UDPGothic** — fallback (universal-design font, high readability)
+- Gothic (sans-serif) for all business slides. Mincho (serif) only for formal/literary contexts
+- When mixing Japanese and Latin, declare Latin font first: `"Inter", "Noto Sans JP", sans-serif`
+
+### Font Sizes (1600x900px slides)
+
+| Role | Size | Weight | line-height |
+|------|------|--------|-------------|
+| Slide title | 48-64px | 700 | 1.2-1.3 |
+| Section heading | 36-44px | 700 | 1.3 |
+| Body text | 24-30px | 400 | 1.6-1.7 |
+| Caption / footnote | 16-18px | 400 | 1.4 |
+| Data callout (big number) | 56-80px | 700 | 1.1 |
+| Unit label (next to number) | 24-28px | 700 | - |
+
+**Rules:**
+- Maximum 3 font sizes per slide
+- Japanese body text needs `line-height: 1.6` minimum (1.7 recommended). English-designed layouts with 1.4 will feel cramped
+- `letter-spacing: 0.05em` for body, `0.02em` for headings
+- Numbers should be large, units one size smaller: `<span style="font-size:56px">+15</span><span style="font-size:26px">%</span>`
+- Never go below 16px on any slide element
+
+### Japanese Typesetting CSS
+
+```css
+.slide {
+  line-break: strict;          /* kinsoku shori (禁則処理) */
+  word-break: normal;          /* never use break-all for Japanese */
+  overflow-wrap: break-word;   /* fallback for long strings */
+  font-feature-settings: "palt" 1; /* tighter punctuation spacing */
+}
+```
+
+### Kinsoku — Prohibited Line Breaks
+
+Characters that must NOT start a line:
+```
+）〕］｝〉》」』】、。，．？！ー・ぁぃぅぇぉっゃゅょァィゥェォッャュョ
+```
+
+Characters that must NOT end a line:
+```
+（〔［｛〈《「『【
+```
+
+### Punctuation Rules
+
+- Use **full-width** punctuation in Japanese text (、。「」) — half-width causes baseline misalignment
+- Exception: `?` and `!` may use half-width for visual tension
+- Replace parentheses with `|` vertical bars or `[]` brackets where possible for cleaner appearance
+
+## Color
+
+### Palette Rule
+
+3 colors maximum: **base + main + accent**
+
+- Avoid pure/raw colors (原色) — use slightly gray-toned versions
+- Avoid pure black (`#000000`) — use dark navy or charcoal (`#1a1a1a`, `#15286d`, `#1e293b`)
+- Accent color only for critical emphasis points
+
+### Contrast (WCAG AA + DADS)
+
+| Element | Minimum ratio |
+|---------|--------------|
+| All text (any size) | 4.5:1 |
+| Non-text UI elements (icons, borders) | 3:1 |
+| Brand colors used as text | 4.5:1 (adjust brightness if needed) |
+
+Note: Japan Digital Agency (DADS) removes the large-text exemption. Even 48px+ headings must meet 4.5:1.
+
+### Do NOT rely on color alone
+
+- Comparison/status must use labels + shape + icon, not just color
+- Charts with thin lines: add text annotations near data points
+- If brand color fails contrast, adjust brightness while keeping hue
+
+## Layout
+
+### Safe Margins
+
+For 1600x900px slides: **64-80px horizontal, 48-64px vertical** (approximately 5% of dimensions)
+
+### Alignment
+
+- Left-align Japanese body text — never full-justify on slides (causes ugly gaps)
+- Use Z-pattern (left-to-right, top-to-bottom) as default reading flow
+- All elements must align to a consistent grid across slides
+
+### Grid System
+
+12-column grid with ~24px gutters works well for 1600x900:
+
+```css
+.grid { display: grid; grid-template-columns: repeat(12, 1fr); column-gap: 24px; }
+.col4 { grid-column: span 4; }
+.col6 { grid-column: span 6; }
+.col8 { grid-column: span 8; }
+```
+
+### Controlling Line Length
+
+Use `max-width` to prevent lines from running too long:
+
+```css
+.body { max-width: 1100px; }  /* ~30-35 chars at 30px */
+.reading { max-width: 1300px; } /* ~38-40 chars at 30px */
+```
+
+## Icons and Images
+
+- Icons are **supplementary** — meaning must be conveyed by text, not icon alone
+- One icon = one concept (do not pack multiple ideas into one icon)
+- Use a single icon family consistently (do not mix outline and filled styles)
+- Prefer rounded, simple shapes for approachable feel
+- Minimum icon size: 20px for slides
+
+## Japanese Base CSS Template
+
+```css
+.slide {
+  width: 1600px;
+  height: 900px;
+  margin: 0; padding: 0;
+  box-sizing: border-box;
+  overflow: hidden;
+  position: relative;
+  background: #ffffff;
+  color: #1a1a1a;
+  font-family: "Noto Sans JP", "BIZ UDPGothic", "Hiragino Kaku Gothic ProN", sans-serif;
+  line-break: strict;
+  word-break: normal;
+  font-feature-settings: "palt" 1;
+}
+.slide-inner {
+  position: absolute;
+  top: 0; left: 0;
+  width: 100%; height: 100%;
+  padding: 64px 80px;
+  box-sizing: border-box;
+}
+.title {
+  font-size: 56px;
+  font-weight: 700;
+  line-height: 1.25;
+  letter-spacing: 0.02em;
+  white-space: nowrap;
+}
+.message {
+  margin-top: 16px;
+  font-size: 28px;
+  font-weight: 500;
+  line-height: 1.5;
+  max-width: 1200px;
+}
+.h2 {
+  font-size: 40px;
+  font-weight: 700;
+  line-height: 1.3;
+  letter-spacing: 0.02em;
+}
+.body {
+  font-size: 28px;
+  line-height: 1.7;
+  letter-spacing: 0.05em;
+  max-width: 1100px;
+}
+.note {
+  font-size: 18px;
+  line-height: 1.5;
+  color: #595959;
+}
+.num {
+  font-size: 56px;
+  font-weight: 700;
+  line-height: 1.1;
+}
+.unit {
+  font-size: 26px;
+  font-weight: 700;
+  margin-left: 4px;
+}
+.cards {
+  display: flex;
+  gap: 20px;
+}
+.card {
+  flex: 1;
+  min-width: 0;
+  background: #f5f5f5;
+  border-radius: 16px;
+  padding: 24px;
+  box-sizing: border-box;
+}
+```
+
+## Pre-Export Checklist (Japanese-Specific)
+
+**Text quality:**
+- [ ] Each slide has exactly 1 message
+- [ ] Titles use noun endings (体言止め), messages are sentences
+- [ ] No slide exceeds 105 chars (presentation mode) or 285 chars (handout mode)
+- [ ] No bullet line exceeds 40 chars
+- [ ] No unnatural line breaks (kinsoku violations)
+- [ ] Punctuation is full-width (、。「」)
+
+**Typography:**
+- [ ] Body text line-height is 1.6+
+- [ ] Font sizes follow 3-tier hierarchy
+- [ ] Numbers are large, units are smaller
+- [ ] All text has white-space:nowrap where appropriate
+- [ ] Text containers have explicit width/min-width in px
+
+**Visual:**
+- [ ] Color palette is 3 colors or fewer
+- [ ] All text contrast is 4.5:1+
+- [ ] No meaning conveyed by color alone
+- [ ] Consistent alignment across all slides
+- [ ] Safe margins maintained (64-80px)

package/public/skills/html2pptx/references/rewrite-patterns.md

@@ -0,0 +1,218 @@
+# Rewrite Patterns
+
+Use this reference when converting web markup into slide-safe HTML/CSS.
+
+## Pattern 1: Page to Slide
+
+Problem:
+
+- full webpage
+- header, sidebar, footer, scroll regions
+- no single export root
+
+Rewrite:
+
+- create one `.slide` root
+- move only presentation content into the slide
+- remove navigation and utility chrome
+- give the slide explicit width and height
+
+## Pattern 2: Runtime Chart to Static Graphic
+
+Problem:
+
+- chart library renders to `canvas`
+- chart appears only after runtime boot
+
+Rewrite:
+
+- replace with inline `svg` when possible
+- otherwise replace with pre-rendered image
+- if the chart is simple, rebuild it using normal DOM bars or a semantic `table`
+
+Prefer SVG over canvas when editability matters.
+
+## Pattern 3: Responsive Layout to Fixed Layout
+
+Problem:
+
+- layout depends on viewport width
+- breakpoints change content flow
+
+Rewrite:
+
+- choose one explicit slide size
+- pin widths, heights, padding, and gaps for that size
+- author for the slide, not for arbitrary screens
+
+## Pattern 4: Decorative Web Effects to Export-Safe Effects
+
+Problem:
+
+- heavy blur stacks
+- blend modes
+- masking
+- layered clipping
+
+Rewrite:
+
+- replace with standard `linear-gradient(...)`
+- replace blend effects with explicit color values
+- replace masked shapes with simple rounded blocks or inline SVG
+- keep decorative effects visually similar but structurally simpler
+
+## Pattern 5: App UI to Presentation Card
+
+Problem:
+
+- tabs, filters, dropdowns, buttons, badges, and control chrome dominate the markup
+
+Rewrite:
+
+- keep the information-bearing state only
+- turn controls into static labels when they explain context
+- remove affordances that imply interaction
+- present the resulting state as cards, tables, summaries, or diagrams
+
+## Pattern 6: Unsafe Input to Safe Input
+
+Problem:
+
+- scripts
+- event handlers
+- `javascript:` URLs
+
+Rewrite:
+
+- remove executable code entirely
+- keep only presentational markup and safe asset URLs
+- ensure the exported preview document can render deterministically without running app logic
+
+## Pattern 8: Pixel-Perfect Slide Fit
+
+Problem:
+
+- slide background does not fill the full PowerPoint canvas
+- unwanted white margins or gaps appear around the slide edges
+- padding on `.slide` pushes the background inward, leaving blank areas
+
+Rewrite:
+
+- set `margin: 0; padding: 0; box-sizing: border-box; overflow: hidden` on every `.slide`
+- apply backgrounds (color, gradient, image) directly on the `.slide` element
+- use an inner `div` with `position: absolute; top: 0; left: 0; width: 100%; height: 100%` for content padding
+- never put content padding directly on the `.slide` when it has a background
+- set `position: relative` on `.slide` so absolute children are scoped correctly
+- use only fixed `px` units — never `%`, `vw`, `vh`, `em`, or `rem` for layout dimensions
+
+## Pattern 7: Text Centering in Background-Colored Elements
+
+Problem:
+
+- text inside buttons, badges, or cards with `background-color`/`background` drifts to a wrong position in PPTX
+- the PPTX converter maps the background `div` to a shape and the inner `span` to a separate text box — they become independent objects
+- flexbox centering on the parent does not propagate into the PPTX text box
+- padding-only sizing causes shape and text to misalign
+
+Rewrite:
+
+- do NOT nest `<span>` inside a background `<div>` for buttons — put text directly in the background element
+- if nesting is needed, give the inner text element `width: 100%` and `text-align: center`
+- always use explicit `width` and `height` on the background element (not padding-only sizing)
+- add `text-align: center` and `display: flex; justify-content: center; align-items: center` to the container
+
+This pattern applies to ALL elements where background and text must stay together: buttons, stat cards, badges, tags, CTAs, labels, progress indicators, etc.
+
+## Pattern 9: Styled Tables — `<table>` vs div+flexbox
+
+Problem:
+
+- `<table>` with gradient backgrounds on `<th>` or `<td>` causes text to disappear or shrink to ~6pt in PPTX
+- nested `<span>` and `<br/>` inside table cells lose content during conversion
+- `border-collapse: separate` and complex cell styling break in native PPTX tables
+
+Root cause: the PPTX converter maps `<table>` to a native PPTX table object, which does not support CSS gradients, and handles inline element nesting poorly.
+
+Rewrite:
+
+- for simple data tables with solid-color backgrounds and plain text, keep `<table>`
+- for styled grids with gradient headers, rich cell content (bold titles + bullet lists), or per-cell border-radius, use div+flexbox rows instead
+- each "row" is a `display: flex` container; each "cell" is a fixed-width div
+- put text directly in the div (Pattern 7 applies) or use `<p>` tags for multi-line content — avoid `<span>` + `<br/>` combos
+- apply background colors/gradients on the div, not on table elements
+
+## Pattern 10: Text Wrapping and Splitting Prevention
+
+Problem:
+
+- text in flexbox/grid children wraps unexpectedly in PPTX output
+- short text like year numbers ("2022") splits into "202" + "2"
+- Japanese headings split mid-word
+- headings, labels, stats, or single-line text gets broken across lines
+- ALL flex/grid layouts are affected, not just `space-between`
+
+Root cause: the PPTX converter calculates text box width from the HTML layout. Without explicit sizing, auto-sized children may receive far less width than the text needs — even `flex: 1` children can get narrow text boxes.
+
+Rewrite:
+
+- add `white-space: nowrap` on EVERY single-line text element (headings, labels, years, stats, names, badges)
+- give ALL flex/grid children an explicit `width` or `min-width` in px — never rely on `flex: 1` alone
+- for equal columns, calculate: `(container width - total gaps) / number of columns` and set explicitly
+- for large font text (40px+), ensure the container is at least `(char count × font-size × 0.7)` px wide for Latin, `(char count × font-size × 1.1)` px wide for Japanese/CJK
+- when in doubt, make the container wider than you think necessary — extra space is invisible, but truncated text is broken
+
+This pattern is the single most common cause of PPTX conversion defects. Apply it to ALL layouts: timelines, grids, stat cards, headers, footers, comparison columns, navigation rows, and any element containing text.
+
+## Template Skeleton
+
+Use this as a default starting point:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      body {
+        margin: 0;
+        background: #f3f4f6;
+      }
+
+      .slide {
+        width: 1600px;
+        height: 900px;
+        box-sizing: border-box;
+        padding: 56px;
+        background: #ffffff;
+        color: #111827;
+        font-family: Inter, Arial, sans-serif;
+      }
+    </style>
+  </head>
+  <body>
+    <section class="slide">
+      <h1>Title</h1>
+      <p>Slide-safe content.</p>
+    </section>
+  </body>
+</html>
+```
+
+## Rewrite Priorities
+
+Apply fixes in this order:
+
+1. make the export root explicit
+2. remove runtime dependencies
+3. fix unsupported assets and CORS risks
+4. simplify unsupported CSS effects
+5. improve editability by replacing raster-prone regions
+
+## Response Pattern
+
+When rewriting for a user, prefer this structure:
+
+- `What changed`
+- `Why it is safer for PPTX export`
+- `What may still rasterize`
+- `Rewritten HTML/CSS`