HTML Deck

A visual editor for the HTML files in your workspace: slide decks, reports, and pages written by
you or by an AI agent.

Click text to edit it, restyle it, move blocks, add effects and present. The file is patched
only where you changed it, so a save with no edits is byte-identical.

Editor in 🇬🇧 English · 🇻🇳 Tiếng Việt · 🇨🇳 简体中文 · 🇹🇼 繁體中文  ·  Works with plain HTML · slide decks ·
Reveal.js · Tailwind CSS · inline SVG · anime.js and other animation code

Why

• Edits stay minimal. HTML Deck patches the source text where you made a change and leaves
  everything else as it was, including formatting, comments and the agent's own markup. That keeps
  diffs small and reviewable.
• Works with your agent. Pin a note on any element ("make this shorter"), or drag across a slide
  to sweep several blocks and leave one note for the area, then ask Claude Code or Codex to apply
  your HTML Deck notes. The agent reads them, edits the HTML and marks them done.
• Presents the real thing. Presentation runs the deck's own scripts and animations in a
  separate frame, so presenting never touches the document you are editing.
• Local and dependency-free. One Python 3.11+ standard-library server on 127.0.0.1. Nothing
  leaves your machine.

AI Feedback: pin notes for your agent	Present with the deck's own animations
Diagrams: retype a label inside an inline SVG, the rest of the drawing stays as it was

Install

HTML Deck needs Python 3.11+ and nothing else. The npm package and the plugins find Python and run
it for you. It works on Linux, macOS and Windows.

Use it with an agent

In Claude Code or Codex:

1. Ask the agent to open your HTML file in HTML Deck, e.g. "open my deck in HTML Deck". Claude
   Code also has /htmldeck [file].
2. Edit in the browser, and pin AI Feedback notes where you want the agent to change something.
3. Ask the agent to "apply my HTML Deck notes".

Run it yourself

htmldeck                                # workspace = current folder
htmldeck --file <file>.html             # open that document first
htmldeck --root <folder> --port 6789 --no-browser

<file>.html is any HTML document in your workspace: a deck, a report, a page.

To try it on the sample deck (a 17-slide quarterly marketing report with anime.js charts) in a
clone of this repo, run htmldeck --root samples --file marketing-report.html. The same folder
has architecture.html, a page with an SVG diagram whose labels you can edit.

The workspace is the folder HTML Deck runs in, or the folder given with --root. Every path is
relative to it, and nothing outside it is served or written, except the file passed with --file.
Each save keeps a timestamped backup in .htmldeck_bak/ next to the document.

Save ▾ also saves a copy of the document to share:

• HTML: a single file that includes all its images, styles, scripts and fonts, so it opens
  anywhere, even offline. Resources loaded from the web (a CDN script, web fonts) are included
  too, unless you clear that option. From a terminal, run
  python -m htmldeck.export --file <file>.html --remote.
• PDF: the document as a PDF file: a deck, a report or any page.

Review notes live beside each document in .htmldeck_notes/<name>.json, so AI Feedback works
on documents opened from the workspace's Files list (not on a file opened from the computer or
dropped in). The request copied from the editor carries the exact command for the agent to run,
on macOS, Linux and Windows (PowerShell) alike. With HtmlDeck installed, scripts and agents can
also read and resolve notes with:

htmldeck-notes --file <file>.html             # list open notes
htmldeck-notes --file <file>.html --prompt    # the same, as a request ready to paste to an agent
htmldeck-notes --file <file>.html --done <id> # mark one done

A region note (drag from the slide background to select several blocks, then AI Feedback on
the group's toolbar) also records the area in CSS pixels of its slide or section and the elements
in it. Versions before 0.1.1 read it as a
note on the whole slide, and drop the region if they rewrite the notes file.

What it supports

python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
npm install
npm run check        # eslint (editor modules) + pytest (server) + browser spec

• htmldeck/server.py: HTTP server, workspace guards, save/backup/notes API, preview origin.
• htmldeck/web/: the editor, as native ES modules with no bundler. js/core holds the model,
  serializer and history; js/runtime holds provenance and motion freeze; also js/policy,
  js/formats (Reveal), js/present and js/fx (the effects runtime, which is also inlined
  into documents).
• tests/spec/characterization.spec.mjs: black-box Playwright spec over fixtures in a temporary
  workspace. To run it on another workspace's files too:
  HTMLDECK_REAL_ROOT=… HTMLDECK_REAL_FILES="a.html,b.html" npm run spec.
• tools/align-report.mjs: npm run align -- <workspace> reports what share of a workspace's
  HTML files save as an in-place patch. The rest still save correctly, through a full rewrite that
  the editor asks you to confirm.
• Plugin: .claude-plugin/, .codex-plugin/, .agents/plugins/ (marketplaces),
  skills/htmldeck/ (also the /htmldeck [file] command), and scripts/htmldeck-run[.cmd], which runs this copy with any
  Python 3.11+.
• npm wrapper: packaging/npm/ bundles htmldeck/ at pack time and runs it with the user's
  Python.
• Release: run python tools/bump_version.py X.Y.Z, commit, then tag vX.Y.Z and push the tag.
  .github/workflows/release.yml publishes to PyPI, then npm, then creates the GitHub Release.

License

MIT © Avis