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.

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. Scripts and agents read and resolve them 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

• Formats: plain HTML pages and reports; decks of .slide blocks; hand-written Reveal.js decks, including vertical stacks, fragments, notes and backgrounds. Reveal's Markdown slides are read-only.
• SVG diagrams: click a label in an inline <svg> (a <text> or <tspan>) and type over it; only that text changes in the file. Click a shape to select the whole diagram, for example to pin AI Feedback on it.
• Safe editing: content that the page's own scripts create or change is locked, and the editor shows why. Animations are frozen while editing. You also get undo/redo and draft recovery.
• Effects: set data-fx entrance effects (fade, zoom, slide, count-up) from the toolbar. HTML Deck also manages scenes, the document's own animation code. "Enable FX in the file" adds a small inline runtime, so effects still run when the file is opened on its own.
• Isolation: presentations run on a second origin that has no access to the editor's API. The edit view blocks remote scripts (from a CDN, for example) unless you trust the file. Workspace files opened directly on the editor origin are sandboxed.

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

License

MIT © Avis