pptx-html-design

English | 中文

AI-generated slides you can finally just edit.

Anyone who has used an AI slide tool knows the feeling: the result is 90% right, but changing one word or swapping one image means re-describing, re-generating, and re-rolling the dice — touch one thing, regenerate everything.

This project's answer is direct: what the AI generates is not a PPT file, but a web page. Open it and edit — changing text is like editing a document (click in and type), swapping an image is like changing an avatar (upload and done), hit save and you're finished. No further conversation with the AI required.

And when you do need a PPT file, export with one click. Need stronger visuals? Have the AI repaint specific pages as full-page artwork to replace the original HTML.

HTML, PPTX, and Image are not three separate formats — they are seamlessly switchable under different conditions, with the editing layer lifted up to HTML.

The editor depends on no framework and is bound to no harness. Through MCP it launches a local web page where editing, annotating, image generation, comparison, design-panel swaps, and export are all one click away.

---

Three Key Design Decisions

1️⃣ HTML as the intermediate medium: spectacular upward, compatible downward

     AI full-page artwork ("baked" pages)   ← upgrade: covers and hero pages can be pushed to the limit
                  ↑
     【HTML slides】← the medium: flexibly generated by AI, manually editable, browser as player
                  ↓
        Standard PPTX file                  ← compatible: send to people on Office / WPS
                  ↓
              PDF                           ← direct byproduct, for archiving and distribution

One body of content, three forms. Day-to-day editing happens in HTML; pages that need extreme visuals get repainted by AI as full-page artwork (the original HTML is kept in a hidden source layer, always revertible); for delivery, export a standard PPTX. The three forms are linked by content fingerprints — change the HTML and the baked pages and export artifacts are automatically marked "stale". You never silently ship an outdated version.

2️⃣ Editable in place, no AI interaction required

The editor is a single zero-dependency web page. Open any generated deck:

• Edit text: click in and type — no "edit mode" to switch into
• Swap images: upload to replace; images land in the deck's assets directory
• Annotate: lasso any element you're unhappy with, write one sentence, and the instruction goes to the AI for a precise fix
• Reorder: drag thumbnails in the table-of-contents sidebar

No AI online, no network needed; saving means writing back to the file itself. Fast, direct, predictable.

3️⃣ MCP standard integration, works with any agent framework

The editor collaborates with AI over the standard MCP (Model Context Protocol), exposing exactly five standard tools — not bound to any specific AI product or framework: Kimi Code, Claude Code, Codex, or any MCP-capable agent plugs in and works.

Without an agent the editor stands alone; with one, every request you submit on the page (briefing, generation, edits, export) becomes a task the AI completes on an isolated copy, published back only after validation passes — the possibility of the AI corrupting your file is eliminated by architecture.

---

What It Does

Scenario	How
Build a deck from scratch	Give the AI your topic and material, pick a style on a visual panel first (29 themes × color variants — swatches, fonts, and motion are WYSIWYG); the AI generates within the frozen style
Rework an existing PPTX	Hand the .pptx to the AI for conversion into web slides, then enter the same editing flow
Export PPTX for delivery	One click produces dual-track artifacts: an editable version (text and charts are native in PowerPoint) + a fidelity version (visuals sealed pixel-perfect), plus a PDF
Embed into your own system	Both slides and editor are iframe-embeddable, talking to the host over a postMessage protocol

The Editor in Action

You never launch the editor by hand: over MCP, the agent automatically pops up this local web page at the moments that need human input — requirements briefing, edit confirmation, export QA. You act on the page and submit; the agent completes the task on an isolated copy and publishes it back. These are real recordings of the human touchpoints in that automated loop:

Edit in place + lasso annotation (click to type, lasso to comment)	Briefing panel: pick style and content item by item, get a structured brief	Export PPTX + comparison QA: side-by-side / swipe split / diff heatmap

Note: the editor itself is a single zero-dependency editor.html and also works standalone — open any generated deck directly, edit, and save back to the file. That is the fallback path, not the main flow.

Two more: view switching and version history

The three clips above cover edit-in-place / lasso annotation / briefing / export QA. These two add the other core capabilities without duplicating them: the editor's main switch, and version protection after a save. Both are real Playwright recordings of the same deck (960 × 540 / 10 fps, with captions and button highlights):

Three views: Edit / Annotate / Delivery share one HTML master; #viewSeg on top is the main switch	Version history: every save creates a git version; refresh the list, roll back any entry (an automatic pre-rollback is kept first)

The remaining controls (style bar, intent buttons in the annotation list, artifact downloads, design-intent panel) are already shown in the three clips above and are not repeated here. Text-level guidance for the style bar and annotation intents lives in the generation skill's SKILL.md.

Two boundaries worth knowing: the editor modifies the HTML master, not the .pptx binary, so a re-export is needed afterwards; "Submit annotation", "Send to AI" and "Export as PPTX" are intent buttons that only enqueue — an agent must claim them before anything runs — while "Copy … instruction" only writes to the clipboard and submits no intent.

Theme Gallery: One Deck × 12 Themes

Screenshots from tests/decks/theme-sampler/ (demo content for "Shanhe Ji", a fictional tea brand; all data is fictional): the same business page rendered under different themes — themes differ systematically in layout, texture, and graphic language, not just color. The 12 most distinctive are shown here (including the two optical-axis F themes and three multi-hue G themes); all 28 live in assets/theme-sampler/.

C3 · Terminal Green · Phosphor	E2 · Blueprint	E3 · Art Deco
C1 · Signal Black · Signal Orange	E7 · Ukiyo-e	E6 · Memphis · Candy Pink
E10 · Star Chart · Midnight Blue-Gold	F1 · Floating Glass · Morning Mist	F2 · Neon Night · Neon Violet
G1 · Emerald Annual · Deep Velvet	G2 · Blush Highlighter	G4 · Indigo Ink · Yellow Pages

Theme DNA: One Brief × 4 Themes × 2 Page Types

From the theme-DNA pilot: the exact same content object (one brand, one claim, one 5-item TOC, one dataset) rendered by 4 themes that each carry a written G10 composition_program contract. Each theme owns how information enters the space — structure changes, not just skin: B1 presses the page into a visible 12-column grid; E5 rides the content on a −12° force band; C3 runs it through terminal windows with ASCII frames; H1 unrolls it as a handscroll with vertical titles and a cinnabar seal.

B1 · Swiss International · TOC	E5 · Constructivism · TOC	C3 · Terminal Green · TOC	H1 · Ink Scroll · TOC
B1 · Claim: giant left column + data spine	E5 · Claim: title carried by the force band	C3 · Claim: verdict printed in a terminal	H1 · Claim: vertical inscription + seal

The pilot covers 6 page types (cover / TOC / low-density claim / high-density analysis / chart / closing) × 4 themes = 24 pages, all rendered from a single content object; each theme's G10 contract lives in its theme.md.

Page Types in Action

Different page forms from the same generation pipeline: cover doubles as clickable TOC, high-density data pages, chart pages, infographic pages.

Cover · chapter navigation (smartforge-c1)	Three-cell contrast data strip (smartforge-c1)	Pipeline (smartforge-c1)
Architecture stack (smartforge-c1)	Chart page · annual overview (charts-a3)	Infographic page · loop diagram (infographic-b2)

Motion in Action

Motion is a built-in vocabulary of the skeleton (8 families, 41 recipes), not post-produced video — these are real recordings of the web pages.

AI illustration ambience (launch-mono-v3)	Typewriter + scramble decode (smartforge-c1)	Split-char text engine (motion-v5)

AI Illustrations & Full-Page Baking

Top row: in-page AI illustrations — images live in assets/ via slots, replace the same-named file to swap. Bottom row: full-page baking with layout restructuring — flat narrative paragraphs are reorganized by AI into a structured infographic (every word preserved), with the original HTML kept in a hidden source layer, always revertible or re-bakable.

In-page AI illustration: product mood shot (launch-mono-v3 · p09)	In-page AI illustration: app UI panel (launch-mono-v3 · p11)
Before: flat narrative HTML page — plain paragraphs, no visual hierarchy (B1 Swiss · imagegen-v2)	After: restructured AI artwork — numbered four-stage infographic, visuals uplifted (source retained)

Going Deeper: How Quality Is Enforced

Design is not left to the AI's improvisation

AI-generated slides are mediocre because the default aesthetic converges on "centered headline + purple-blue gradient + card walls". This project's countermeasure is front-loading decisions: visual identity comes from a curated theme library (you pick, not improvise), layout is driven by content (count the words before choosing a composition), and the AI creates within constraints — constraints don't limit quality, they are the source of it.

Text overflow is gated by math, not by eyeballing

• At build time: capacity planning precedes layout choice; every container is pre-certified using PPT font metrics
• After generation: real Playwright render measurement — zero overflow, zero overlap, compliant font sizes; the script has the final say
• At export: a mathematical certifier reopens the PPTX and computes line by line — ink width, ink-box collisions, line-height floors. Nothing is written to disk unless certification fully passes; failures trigger automatic repair. A PPTX with overflow is never delivered
• Font subsets are embedded into the file, ending "layout breaks on a different machine" for good

55 end-to-end automated acceptance checks

Covering render validation, chapter navigation, density metrics, content fingerprints, page baking, dual-track export, the editor's three states, and capacity gates. The real-content benchmark is a 1:1 restoration of a 54-page real business deck. The acceptance system is developer-facing; evidence lives in docs/test_acceptance/.

Editor ↔ Agent bridge, technical notes

• Exactly five MCP tools: open_editor / await_intent / push_update / get_status / close_session
• All tasks are async intents: the agent works on an isolated copy, published atomically after CAS validation
• Durable processing: tasks can be stopped and resumed (resume / rebuild); the source of truth lives in SQLite; page, agent, and service stay in sync over SSE
• Git-protected baseline: dedicated refs and an isolated index — your HEAD and staging area are never touched

Functional Differences from Common Approaches

Dimension	Common practice	This project
Deliverable	PPTX files / image collages / framework-bound players	A single zero-dependency HTML file; the browser is the player
Editing after generation	Regenerate and roll the dice	Edit the original file in place, no AI involved
Design decisions	AI decides unilaterally, style is a lottery	Curated theme library + visual panel: humans pick, AI implements
Overflow prevention	Runtime font shrinking / eyeballing	Capacity planning + render measurement + mathematical certification
PPTX export	Screenshot pasted in (uneditable) / naive conversion (layout drifts)	Native editable + vector fidelity dual tracks; nothing ships unless certified
Full-page AI artwork	Final once generated, nothing left to edit	Baked pages keep a hidden source layer — revert and re-bake any time
AI framework lock-in	Bound to a specific product	Standard MCP; any agent framework can integrate
Quality evidence	"Looks fine to me"	55 automated acceptance checks + fidelity scores + diff heatmaps

Quick Start

The product has exactly two parts: one skill + one MCP bridge. Every script needed for generation, editing, and export lives inside the skill — users never run any test scripts.

The generation side is driven by an AI coding agent:

• With the skills/SlideForge/ skill loaded, the full workflow — from requirements briefing to dual-track export (including render checks, capacity gates, and every export script) — ships with the skill itself.
• Connect the MCP service, and the agent pops up the web page whenever human input is needed.

Install the Skill

Option 1 (recommended) — the npx skills installer, which auto-detects your agent and drops the skill into the right folder (pick SlideForge when prompted):

# Install into the current project
npx skills add DSXiangLi/pptx_fuse_design
# …or install globally, for every project
npx skills add DSXiangLi/pptx_fuse_design -g

Option 2 — manual: copy (or symlink) skills/SlideForge/ into your agent's skill directory; the entry point is SKILL.md. Common user-level skill directories:

Agent	Skill directory
Claude Code	~/.claude/skills/SlideForge/
Kimi Code	~/.agents/skills/SlideForge/
WorkBuddy	~/.workbuddy/skills/SlideForge/ (user-level); or <project root>/.workbuddy/skills/SlideForge/ (project-level, shared with the team)

# Example: Claude Code / Kimi Code (macOS · Linux)
cp -r skills/SlideForge ~/.claude/skills/

# Example: WorkBuddy (Windows PowerShell)
Copy-Item -Recurse skills\SlideForge "$env:USERPROFILE\.workbuddy\skills\"

The skill is pure static files (Markdown reference library + skeleton + scripts) with no installer and no runtime dependencies: copy and it works, delete the directory to uninstall. Optional dependencies for the generation/export scripts are listed under "Optional Dependencies" below.

Optional: image generation (official OpenAI API)

The main flow — content → pages → render/capacity checks → export — needs no credentials. Only the two optional passes (AI illustration, full-page baking) call an image service, always through the skill's own provider (skills/SlideForge/scripts/providers/openai_image.py, stdlib-only) hitting the official OpenAI Images API.

• OPENAI_API_KEY (required); OPENAI_BASE_URL for OpenAI-compatible endpoints; OPENAI_IMAGE_MODEL defaults to gpt-image-2.
• Or use a .env file — the first existing file wins, keys are not merged: ./.env (the deck directory when invoked through the adapter) → <skill dir>/.env → ~/.slideforge/.env. Template: skills/SlideForge/.env.example.
• Keep the default model: the skill's own image gate requires page-level slots to be ≥2560×1440, which the gpt-image-1 family (1024×1024 / 1536×1024 / 1024×1536) cannot produce. The provider fails loudly with guidance rather than upscaling, cropping, or silently degrading.
• Verify the setup without network or billing: python3 skills/SlideForge/scripts/providers/openai_image.py --self-check.

Connect the MCP Bridge (what auto-launches the editor)

The bridge is a stdio MCP server with the fixed name pptx-html-bridge and entry point tools/edit.py --mcp. Installation takes three steps:

Step 1 · Prepare the Python environment

Its only dependency is the official MCP SDK (requires Python ≥ 3.10). A dedicated venv is recommended so your global environment stays clean:

# macOS / Linux
python3 -m venv .venv
.venv/bin/pip install "mcp>=1.28,<2"

# Windows (Git Bash / PowerShell)
python -m venv .venv
.venv\Scripts\python.exe -m pip install "mcp>=1.28,<2"

If you don't mind a global install, a plain pip install "mcp>=1.28,<2" works too — the bridge has no other third-party dependencies.

Self-check (starts no server, no network, no billing):

python3 -c "import mcp; print('mcp ok')"
python3 tools/edit.py --help        # prints usage → the entry point works

Step 2 · Register with your agent

Claude Code, one line (writing the absolute path of the Step-1 venv interpreter as python3 is the most robust):

claude mcp add pptx-html-bridge -- /absolute/path/.venv/bin/python3 /absolute/path/tools/edit.py --mcp

Codex / Kimi Code / Cursor and others: add the equivalent entry to the mcpServers object of your agent's MCP configuration. Prefer an absolute interpreter path for command; on Windows escape JSON paths with \\ (or use forward slashes):

{
  "mcpServers": {
    "pptx-html-bridge": {
      "command": "/absolute/path/.venv/bin/python3",
      "args": ["/absolute/path/tools/edit.py", "--mcp"]
    }
  }
}

WorkBuddy: edit the user-level config ~/.workbuddy/mcp.json (note the filename has no leading dot — it is not .mcp.json) and merge the entry into the existing mcpServers (don't overwrite other servers). Windows example:

{
  "mcpServers": {
    "pptx-html-bridge": {
      "command": "C:\\Users\\<you>\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\<you>\\Desktop\\SlideForge\\tools\\edit.py", "--mcp"]
    }
  }
}

Writing the config does not activate the server automatically: open WorkBuddy's connector management page (top-right entry), find pptx-html-bridge in the custom connectors list, click Trust, then restart the session.

Kimi Code: raise the tool timeout. Kimi Code force-times-out any single MCP tool call after 60 seconds by default (progress notifications do not extend it), which would kill the bridge's long await_intent wait — up to one day — and leave page-submitted requests unclaimed. Add "toolTimeoutMs": 86500000 to the server entry above (or set [mcp] toolTimeoutMs in config.toml, or the KIMI_MCP_TOOL_TIMEOUT_MS env var), then restart the session. Hosts without a 60-second cap don't need this.

Step 3 · Verify

You know it works when the agent sees exactly five tools: open_editor / await_intent / push_update / get_status / close_session.

• On hosts that support MCP Apps, open_editor(open_browser="auto") embeds the editor directly into the chat panel (track A, where the tool surface additionally exposes open_brief and app-related tools);
• otherwise it opens a standalone browser window (track B). The five model-facing tools and the intent protocol are identical across both tracks.

The bridge is not tied to a working directory: open_editor registers the deck path per session, and the page, the daemon, and the agent have independent lifecycles — the daemon can stay resident in the background.

Optional Dependencies

The skill's built-in acceptance and export scripts install on demand: render checks and capacity gates need Playwright (pip install playwright && playwright install chromium); the fidelity-track HTML→PPTX export also needs poppler (pdftocairo).

Project Layout

skills/SlideForge/     [Product] generation skill: workflow + skeleton + reference library + all generation/export scripts
editor.html           [Product] single-file editor: edit / annotate / flip — a three-state workbench
tools/                [Product] MCP bridge: edit.py entry + core + MCP proxy
tests/                [Dev acceptance] regression harness and benchmark decks; not part of the product — users never run these
docs/                 design docs / research / iteration logs / acceptance evidence / lessons learned

Documentation

• Conventions and architecture overview: AGENTS.md at the root
• Design and architecture: docs/design/ (index: docs/design/README.md)
• Bridge manual: docs/howto/editor-agent-bridge.md
• Iteration logs: docs/progress/ · acceptance evidence: docs/test_acceptance/ · research: docs/research/

Current Status

The core pipeline (generate → edit → bridge → dual-track export) is fully green under automated acceptance. Manual items remain: visual inspection in real Office 365 / WPS, and eyeballing real paid image generation. See docs/progress/1003_editor_agent_bridge_handover.md.