htmldeck 0.1.0__tar.gz

htmldeck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

htmldeck-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: htmldeck
+Version: 0.1.0
+Summary: Edit and present the HTML documents (decks, reports, pages) of a workspace — in place, without rewriting the file.
+Author-email: Avis <hunganh.freeze@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/avis309/html-deck
+Project-URL: Repository, https://github.com/avis309/html-deck
+Project-URL: Issues, https://github.com/avis309/html-deck/issues
+Keywords: html,slides,presentation,editor,reveal.js,claude-code,codex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: Presentation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# 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.
+
+[![CI](https://github.com/avis309/html-deck/actions/workflows/ci.yml/badge.svg)](https://github.com/avis309/html-deck/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/htmldeck)](https://pypi.org/project/htmldeck/)
+[![npm](https://img.shields.io/npm/v/@avis309/htmldeck)](https://www.npmjs.com/package/@avis309/htmldeck)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+<img src="https://raw.githubusercontent.com/avis309/html-deck/main/.github/assets/edit.png" alt="Editing a slide title in HTML Deck" width="900">
+
+</div>
+
+## 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"), 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.
+
+<table>
+  <tr>
+    <td width="50%"><img src="https://raw.githubusercontent.com/avis309/html-deck/main/.github/assets/feedback.png" alt="AI Feedback panel with a pinned note"></td>
+    <td width="50%"><img src="https://raw.githubusercontent.com/avis309/html-deck/main/.github/assets/present.png" alt="Presenting a deck"></td>
+  </tr>
+  <tr>
+    <td align="center"><b>AI Feedback</b>: pin notes for your agent</td>
+    <td align="center"><b>Present</b> with the deck's own animations</td>
+  </tr>
+</table>
+
+## Install
+
+| Where | Command |
+|---|---|
+| Claude Code | `/plugin marketplace add avis309/html-deck` then `/plugin install htmldeck@htmldeck` |
+| Codex | `codex plugin marketplace add avis309/html-deck` then `codex plugin add htmldeck@htmldeck` |
+| uv | `uvx htmldeck` (one-off) · `uv tool install htmldeck` |
+| pipx / pip | `pipx install htmldeck` · `pip install htmldeck` |
+| npm | `npx @avis309/htmldeck` (one-off) · `npm i -g @avis309/htmldeck` |
+
+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 slides/q3.html 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
+
+```bash
+cd ~/my-workspace
+htmldeck                             # workspace = current folder
+htmldeck --file decks/q3.html        # open a document first
+htmldeck --root ~/my-workspace --port 8765 --no-browser
+```
+
+To try it on the sample deck from the screenshots (24 slides with anime.js scenes) in a clone of
+this repo, run `htmldeck --root samples --file ai-foundation-deck.html`.
+
+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.
+
+Review notes live beside each document in `.htmldeck_notes/<name>.json`. Scripts and agents read
+and resolve them with:
+
+```bash
+htmldeck-notes --file decks/q3.html            # list open notes
+htmldeck-notes --file decks/q3.html --done ID  # mark one done
+```
+
+## 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.
+- **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.
+
+<details>
+<summary><b>Develop</b></summary>
+
+```bash
+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/`, `commands/`, 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.
+
+</details>
+
+## License
+
+[MIT](LICENSE) © Avis

htmldeck-0.1.0/README.md

@@ -0,0 +1,135 @@
+<div align="center">
+
+# 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.
+
+[![CI](https://github.com/avis309/html-deck/actions/workflows/ci.yml/badge.svg)](https://github.com/avis309/html-deck/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/htmldeck)](https://pypi.org/project/htmldeck/)
+[![npm](https://img.shields.io/npm/v/@avis309/htmldeck)](https://www.npmjs.com/package/@avis309/htmldeck)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+<img src="https://raw.githubusercontent.com/avis309/html-deck/main/.github/assets/edit.png" alt="Editing a slide title in HTML Deck" width="900">
+
+</div>
+
+## 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"), 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.
+
+<table>
+  <tr>
+    <td width="50%"><img src="https://raw.githubusercontent.com/avis309/html-deck/main/.github/assets/feedback.png" alt="AI Feedback panel with a pinned note"></td>
+    <td width="50%"><img src="https://raw.githubusercontent.com/avis309/html-deck/main/.github/assets/present.png" alt="Presenting a deck"></td>
+  </tr>
+  <tr>
+    <td align="center"><b>AI Feedback</b>: pin notes for your agent</td>
+    <td align="center"><b>Present</b> with the deck's own animations</td>
+  </tr>
+</table>
+
+## Install
+
+| Where | Command |
+|---|---|
+| Claude Code | `/plugin marketplace add avis309/html-deck` then `/plugin install htmldeck@htmldeck` |
+| Codex | `codex plugin marketplace add avis309/html-deck` then `codex plugin add htmldeck@htmldeck` |
+| uv | `uvx htmldeck` (one-off) · `uv tool install htmldeck` |
+| pipx / pip | `pipx install htmldeck` · `pip install htmldeck` |
+| npm | `npx @avis309/htmldeck` (one-off) · `npm i -g @avis309/htmldeck` |
+
+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 slides/q3.html 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
+
+```bash
+cd ~/my-workspace
+htmldeck                             # workspace = current folder
+htmldeck --file decks/q3.html        # open a document first
+htmldeck --root ~/my-workspace --port 8765 --no-browser
+```
+
+To try it on the sample deck from the screenshots (24 slides with anime.js scenes) in a clone of
+this repo, run `htmldeck --root samples --file ai-foundation-deck.html`.
+
+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.
+
+Review notes live beside each document in `.htmldeck_notes/<name>.json`. Scripts and agents read
+and resolve them with:
+
+```bash
+htmldeck-notes --file decks/q3.html            # list open notes
+htmldeck-notes --file decks/q3.html --done ID  # mark one done
+```
+
+## 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.
+- **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.
+
+<details>
+<summary><b>Develop</b></summary>
+
+```bash
+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/`, `commands/`, 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.
+
+</details>
+
+## License
+
+[MIT](LICENSE) © Avis

htmldeck-0.1.0/htmldeck/__main__.py

@@ -0,0 +1,4 @@
+"""``python -m htmldeck`` — start the editor for the workspace in the current folder."""
+from htmldeck.server import main
+
+main()

htmldeck-0.1.0/htmldeck/notes.py

@@ -0,0 +1,86 @@
+"""List (or resolve) review notes pinned in the HTML editor, for an agent to act on.
+
+Notes live beside the document in ``.htmldeck_notes/<name>.json``. Each carries the CSS
+selector of the element, the source line at the time it was pinned, and a text snippet;
+this runner re-locates the line in the current file so it stays useful after edits.
+
+Run (in the workspace, or with --root):
+  htmldeck-notes --file output/deck.html
+  htmldeck-notes --file output/deck.html --done <id>
+  (or python -m htmldeck.notes ...)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from htmldeck.server import EditorError, apply_note_ops, display_path, notes_path, read_notes, utf8_stdio
+
+
+def current_line(source: str, note: dict) -> int | None:
+    """Line of the note's snippet nearest to where it was pinned, else the pinned line."""
+    snippet = " ".join(note.get("text", "").split())[:40]
+    pinned = note.get("line")
+    lines = []
+    idx = source.find(snippet) if snippet else -1
+    while idx >= 0:
+        lines.append(source.count("\n", 0, idx) + 1)
+        idx = source.find(snippet, idx + 1)
+    if not lines:
+        return pinned
+    return min(lines, key=lambda n: abs(n - pinned)) if pinned else lines[0]
+
+
+def format_notes(target: Path, notes: list[dict], show_all: bool, root: Path | None = None) -> str:
+    root = root or Path.cwd()
+    source = target.read_text(encoding="utf-8") if target.is_file() else ""
+    shown = [n for n in notes if show_all or n.get("status") == "open"]
+    if not shown:
+        return f"Không có ghi chú {'nào' if show_all else 'đang mở'} cho {display_path(target, root)}."
+    lines = [f"# Ghi chú cần sửa — {display_path(target, root)} ({len(shown)})", ""]
+    for i, n in enumerate(shown, 1):
+        where = [f"dòng {current_line(source, n) or '?'}"]
+        if n.get("slide") is not None:
+            where.append(f"slide {n['slide'] + 1}")
+        lines.append(f"{i}. [{n['status']}] id={n['id']} · {' · '.join(where)} · <{n.get('tag', '?')}>")
+        lines.append(f"   selector: {n.get('selector', '')}")
+        if n.get("text"):
+            lines.append(f"   đoạn chữ: \"{n['text'][:160]}\"")
+        lines.append(f"   → {n['note']}")
+        lines.append("")
+    return "\n".join(lines).rstrip()
+
+
+def main(argv: list[str] | None = None):
+    parser = argparse.ArgumentParser(description="List review notes left in the HTML editor")
+    parser.add_argument("--root", default=".", help="Workspace folder (default: the current folder)")
+    parser.add_argument("--file", required=True, help="HTML document the notes belong to")
+    parser.add_argument("--all", action="store_true", help="Include notes already marked done")
+    parser.add_argument("--done", metavar="ID", action="append", default=[], help="Mark a note as done (repeatable)")
+    args = parser.parse_args(argv)
+    utf8_stdio()
+
+    root = Path(args.root).expanduser().resolve()
+    target = Path(args.file).expanduser()
+    target = (target if target.is_absolute() else root / target).resolve()
+    notes = read_notes(target)
+    if args.done:
+        known = {n["id"] for n in notes}
+        missing = [i for i in args.done if i not in known]
+        if missing:
+            print(f"Không tìm thấy ghi chú: {', '.join(missing)}", file=sys.stderr)
+            sys.exit(1)
+        try:
+            apply_note_ops(target, [{"op": "update", "id": i, "patch": {"status": "done"}} for i in args.done], root)
+        except EditorError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            sys.exit(1)
+        print(f"Đã đánh dấu xong {len(args.done)} ghi chú → {display_path(notes_path(target), root)}")
+        return
+    print(format_notes(target, notes, args.all, root))
+
+
+if __name__ == "__main__":
+    main()