htmlcraft 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 htmlppt contributors
+
+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.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# htmlcraft
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Visual editor, CLI, and MCP server for self-contained HTML presentations. A deck
+is one HTML file: slides are ordinary DOM elements, styles are ordinary CSS, and
+every object keeps a stable id so the editor and AI agents can address it.
+
+This package bundles the editor assets and the `htmlcraft` agent skill, so it works
+without a build step or extra downloads.
+
+## Install
+
+```bash
+npm install -g htmlcraft
+# or run without installing
+npx -y htmlcraft --help
+```
+
+## CLI
+
+```bash
+npx htmlcraft new deck.html --slides 3
+npx htmlcraft validate deck.html
+npx htmlcraft open deck.html
+npx htmlcraft stop deck.html
+npx htmlcraft export deck.html --format html
+npx htmlcraft export deck.html --format pdf
+npx htmlcraft export deck.html --format png --out dist/png
+```
+
+`htmlcraft open` starts a local editor on `127.0.0.1` with a capability token
+recorded for that deck. Later `open` calls for the same deck reuse the recorded
+port and token, so the printed tokenized URL keeps working across a host
+restart; `htmlcraft stop` rotates the token, and replacing a stale-build host
+rotates it too because `open` stops the broken host first, so a URL bookmarked
+before the replacement needs the newly printed one. The first tokenized visit
+exchanges the token for an HttpOnly, `SameSite=Strict` session cookie with a
+30-day `Max-Age`, so the browser stays signed in to that deck. Add
+`--no-browser` to only print the URL. The editor's
+Export menu writes HTML, PDF, or PNG next to the deck; unsaved edits are also
+mirrored to IndexedDB so a crash can offer recovery. Without a host, the editor
+falls back to upload/download mode. PDF and PNG export use a locally installed
+Chrome, Edge, or Chromium; set `HTMLCRAFT_CHROMIUM` to choose one explicitly. The
+CLI refuses to overwrite the source deck.
+
+## MCP
+
+Add the server to an MCP client:
+
+```json
+{
+  "mcpServers": {
+    "htmlcraft": {
+      "command": "npx",
+      "args": ["-y", "htmlcraft", "mcp"]
+    }
+  }
+}
+```
+
+If you installed the package globally, `"command": "htmlcraft-mcp"` works too.
+
+The server exposes deck tools (`create_deck`, `validate_deck`, `set_text`,
+`open_editor`, and more) plus the `htmlcraft://contract` and
+`htmlcraft://authoring` resources. Reference material ships in `dist/skill/`.
+
+## Requirements
+
+- Node.js 20 or newer.
+- Chrome, Edge, or Chromium for PDF/PNG export; set `HTMLCRAFT_CHROMIUM` to choose
+  one explicitly.
+- No telemetry and no remote calls: the editor and MCP server only touch the
+  deck you open.
+
+## License
+
+MIT. See [LICENSE](LICENSE); third-party notices are in
+[THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md); report vulnerabilities as
+described in [SECURITY.md](SECURITY.md).

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security
+
+htmlcraft runs locally. The editor host binds to `127.0.0.1` and requires the
+per-deck capability token minted by the first `htmlcraft open`. `open` records the
+token and port in a local credential store and reuses them for that deck until
+`htmlcraft stop` rotates the token. A stale-build replacement rotates it too,
+because `open` stops the broken host first, so a URL bookmarked before the
+replacement needs the newly printed one. The tokenized first visit sets an
+HttpOnly, `SameSite=Strict` session cookie with a 30-day `Max-Age`. It serves
+only the opened deck and the packaged editor assets, and confines HTML/PDF/PNG
+exports to the deck directory. Deck previews use an iframe sandbox without
+script execution; unsaved drafts live only in the editor origin's IndexedDB and
+never contain the session token.
+PDF/PNG rendering runs Chromium with JavaScript disabled and blocks file,
+network-navigation, frame, worker, and script requests. The MCP server uses
+stdio only. Direct mode reads and writes the paths you give it; host-attached
+mode routes through the token-authenticated host. The package has no telemetry
+and makes no remote calls except loading a deck's own image, font, and
+stylesheet assets.
+
+See the repository `SECURITY.md` for the full threat model.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a security problem. Report it privately through
+the repository's GitHub Security Advisories ("Report a vulnerability") with:
+
+- the htmlcraft version and operating system,
+- reproduction steps or a minimal deck,
+- the impact you observed.
+
+Please allow time for a fix before public disclosure.