htmlcraft 0.0.0-stage → 0.1.0

package/dist/skill/references/authoring.md

@@ -0,0 +1,160 @@
+# Authoring decks for the htmlcraft editor and MCP server
+
+These notes cover how to write decks that stay pleasant to edit by hand, by an
+agent, and in the visual editor. The contract itself lives in
+[contract.md](contract.md).
+
+## Start from structure, then style
+
+1. Create the deck with `create_deck` or `htmlcraft new`. Both produce a valid
+   document with slide ids, the canvas size, and the real runtime.
+2. Add or replace content as top-level objects. Each object owns its position,
+   size, and typography.
+3. Add a `<style>` block for the shared visual language.
+4. Validate, then open the editor for human review.
+
+Prefer one object per visual block over deeply nested layout. The editor and
+MCP tools address top-level objects, so a flat structure is easier to edit and
+survives round trips with fewer surprises.
+
+## Editor-friendly structure
+
+- Give every top-level object an explicit `data-ppt-el`. Do not rely on a
+  generated id when a later call needs to address the object.
+- Keep each object self-contained: position it absolutely inside the slide and
+  set an explicit width. Text without a width can overflow the canvas.
+- Use real text nodes for content. Text inside CSS `::before`/`::after`,
+  background images, or SVG `<text>` is not editable through `set_text`.
+- Prefer semantic elements (`h1`, `h2`, `p`, `ul`, `table`, `figure`) so the
+  outline reports useful summaries and tags.
+- Tables are real `<table>` elements with `<thead>`/`<tbody>`; put
+  `data-ppt-el` on the table.
+- A `data-ppt-group` wrapper groups related objects. Do not nest group
+  wrappers.
+- Notes are a direct-child `<aside data-ppt-notes hidden>` of the slide. One
+  aside per slide is enough.
+
+Example object:
+
+```html
+<div data-ppt-el="e3" style="position: absolute; left: 140px; top: 300px; width: 900px;">
+  <h2 style="margin: 0; font-size: 56px;">Why it matters</h2>
+  <p style="margin: 24px 0 0; font-size: 30px; line-height: 1.5; color: #4a4f59;">
+    Keep the message in a real paragraph so it can be edited in place.
+  </p>
+</div>
+```
+
+## Styling freedom
+
+- Put shared rules in a `<style>` block: colors, type scale, shared object
+  classes, print rules.
+- Use inline styles for object-specific position, size, and one-off styling.
+  `set_style` edits these properties and accepts `null` to remove one.
+- CSS custom properties, gradients, shadows, filters, masks, transforms,
+  flexbox, grid, inline SVG, and CSS animations are all allowed.
+- Web fonts must use a `data:` or absolute URL.
+- Keep the fixed canvas in mind. Do not use `position: fixed` or full-height
+  `100vh`/`100dvh`/`100svh`/`100lvh` layouts; validation warns (`fixed-layout`)
+  because they may not export reliably. Other viewport units are not detected
+  by the validator but still scale with the browser window, so avoid them for
+  layout. Use absolute positioning inside the 1600x900 (or chosen) canvas.
+- Animations that run on their own are preserved. There is no animation
+  timeline or trigger authoring in v1.
+
+`set_slide_background` accepts exactly one of `color`, `gradient`, or `image`.
+A color uses the `background` shorthand; a gradient or image uses
+`background-image`, and the other form is cleared.
+
+## Content edits
+
+- `set_text` replaces an element's text content and escapes HTML. Use it for
+  ordinary copy.
+- `set_element_html` replaces inner HTML. Use it for deliberate markup changes,
+  then validate immediately.
+- `update_slide_html` replaces a whole slide's inner HTML. Read the slide first
+  with `read_slide`; recreating the objects by hand risks losing ids, notes, and
+  styles.
+- `add_element` inserts exactly one top-level element. Provide `data-ppt-el` in
+  the fragment when you need a stable id; otherwise the returned `elementId`
+  tells you the generated id.
+- Removing an element uses a target. The slide itself cannot be removed this
+  way; use `delete_slide`, and remember the last slide cannot be deleted.
+- Slide order changes use `move_slide` or `set_slide_order`; the latter must
+  list every slide id exactly once.
+
+Targets for element tools are exactly one of:
+
+```json
+{ "elementId": "e3" }
+{ "selector": ".card > h2" }
+{ "path": [1, 0] }
+```
+
+`elementId` matches `data-ppt-el` within the slide. `selector` must match
+exactly one element inside the slide. `path` is child indices starting at the
+slide element. Missing or ambiguous targets produce stable error codes; read
+the outline before guessing.
+
+## Notes, transitions, charts, tables, and images
+
+- `set_notes` writes or clears the direct-child notes aside. An empty string
+  removes it.
+- `set_transition` accepts `none`, `fade`, or `slide`.
+- Chart data lives in `data-ppt-chart` on a `<figure>` as JSON with `type`
+  (`bar`, `line`, or `pie`), `labels`, and `series` (`{ name, values }`
+  entries). Optional fields are `title`, `colors`, `legend`, and
+  `valueLabels`. Labels and each series' values must have the same length, and
+  the rendered SVG is derived from the attribute. Use `update_chart` rather
+  than editing the SVG. Invalid JSON is a validation error.
+- Tables are real `<table>` elements. `add_table` creates one with a header
+  row within the 50-row and 20-column core limits.
+- `add_image` accepts a data URL, an absolute http(s) URL, or a local path.
+  Local files are embedded as data URLs after MIME and 8 MB checks; remote
+  URLs are validated but never fetched. Keep assets self-contained.
+
+## Round-trip rules
+
+- Slide ids are unique, non-empty, and stable. Do not renumber slides to
+  reorder them; use `move_slide` or `set_slide_order`.
+- Object ids are unique within a slide. Do not recycle an id for a different
+  object.
+- Never write `data-ppt-editing` or `data-ppt-frame-slide`; validation rejects
+  saved files containing them.
+- Keep the deck self-contained: no relative asset URLs, no external
+  stylesheet dependency, no layout that depends on JavaScript.
+- Keep one runtime script with `data-ppt-runtime="1"` and the real body.
+- Export should not change the meaning of the deck. Notes, transitions, chart
+  JSON, and object ids survive export.
+
+## Revision and conflict discipline
+
+Reads and writes are revision-checked. The MCP server remembers the last
+revision per file; a host-attached editor also tracks the file revision. If the
+file changes between your read and write, the write fails with
+`code: "conflict"` and the file is left untouched.
+
+On conflict:
+
+1. Re-read with `get_outline` or `read_slide`.
+2. Decide how to reconcile the external change. Preserve edits you did not
+   intend to replace.
+3. Retry the mutation.
+
+Do not bypass a conflict by rewriting the entire deck unless the user
+explicitly asks for that.
+
+## Review and export
+
+- Use `open_editor` (MCP) or `htmlcraft open <file>` (CLI) for human review. The
+  URL contains the deck's capability token; treat it as a secret. The token is
+  recorded per deck and reused by later opens until `htmlcraft stop` rotates it;
+  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 visit exchanges the token for a 30-day session cookie.
+- Re-read after a person edits in the editor, because their writes create new
+  revisions.
+- Run `validate_deck` or `htmlcraft validate` before exporting.
+- `export_deck` writes `<name>.export.html` for `format: "html"`, or a PDF /
+  one PNG per slide for `pdf` / `png`. `outDir` resolves against the deck
+  directory and must stay inside it.

package/dist/skill/references/contract.md

@@ -0,0 +1,177 @@
+# htmlcraft deck contract (htmldeck/v1)
+
+The HTML file is both the authoring format and the saved deck. The validator,
+editor, CLI, and MCP server all read and write this same contract.
+
+## Document
+
+- Start with `<!doctype html>`.
+- Include a non-empty `<title>`. A missing title is a warning
+  (`missing-title`), not an error.
+- The document must have content (`empty-document` error otherwise).
+- The deck must contain at least one slide.
+- The deck is self-contained: keep CSS in a `<style>` block or inline `style`
+  attributes, and keep assets inline or on absolute URLs. No build step is
+  required to open or export it.
+
+## Deck wrapper and slides
+
+- `<main data-ppt-deck>` is the conventional wrapper. The runtime marks it
+  `data-ppt-ready="1"` while presenting.
+- Detection order:
+  1. Elements with `data-slide-id`.
+  2. `.slide`, then `.page`, then `.slide-page`.
+  3. The largest same-parent group of `<section>` elements.
+  4. The body as a single slide with the id `body`.
+- Explicit `data-slide-id` values are required for stable addressing. A slide
+  without one is a warning (`missing-slide-id`) and normalization assigns one.
+- Slide ids must be unique and non-empty. Duplicates are an error
+  (`duplicate-slide-id`).
+- Slides must not be nested inside another slide (`nested-slide` error).
+
+Minimal explicit slide:
+
+```html
+<section class="slide" data-slide-id="s1" data-width="1600" data-height="900">
+  <h1 data-ppt-el="e1">Title</h1>
+</section>
+```
+
+## Canvas
+
+- `data-width` and `data-height` are positive pixel numbers.
+- Omit both to use 1600x900, or set both explicitly.
+- An explicitly invalid value is an error (`invalid-canvas-size`).
+- When the attributes are absent, an inline `width: <n>px; height: <n>px` on
+  the slide is also honored.
+- Different sizes across slides produce the `mixed-canvas-sizes` warning.
+  Keep one canvas size per deck.
+
+## Objects
+
+- Every top-level child of a slide is an object: text blocks, shapes, images,
+  tables, figures, and groups.
+- Put `data-ppt-el="<id>"` on each top-level object. Ids are unique within the
+  slide and stay stable across edits.
+- Nested elements may also carry `data-ppt-el`; they share the same uniqueness
+  rule within the slide. Duplicate ids are an error (`duplicate-element-id`).
+- Normalization assigns a missing top-level `data-ppt-el` id. It does not
+  invent content.
+- A `data-ppt-group` wrapper groups objects. Nested group wrappers are not
+  supported (`unsupported-group-nesting` warning).
+- Objects are edited through inline styles and CSS classes. While a deck is
+  open, the editor's live frame may carry transient editor-only attributes
+  (`data-ppt-editing`, `data-ppt-frame-slide`). They are stripped before save
+  and never persist in saved output; see the artifacts rule under
+  [Round-trip and writes](#round-trip-and-writes).
+
+## Speaker notes
+
+- Notes are a direct child of the slide:
+  `<aside data-ppt-notes hidden>Talk track</aside>`.
+- Notes outside a slide, or nested deeper than a direct child, are an error
+  (`notes-nested-incorrectly`).
+- `set_notes` removes the aside when the notes string is empty.
+
+## Transitions and runtime
+
+- `data-ppt-transition` is optional and must be `none`, `fade`, or `slide`.
+  Any other value is an error (`invalid-transition`).
+- Multi-slide decks should include exactly one runtime:
+  `<script data-ppt-runtime="1">...</script>` in the document.
+- A missing runtime on a multi-slide deck is a warning (`missing-runtime`);
+  the deck is still valid HTML but cannot present itself.
+- The runtime body must be the real runtime script, not an empty marker.
+  `create_deck` and `htmlcraft new` write it. Copy it from
+  `../examples/basic.html` when hand-authoring. Validation checks only that a
+  marker exists on a `<script>` with value `1`; it does not inspect the body,
+  so a comment or an empty script still validates but cannot present.
+- More than one runtime marker is an error (`duplicate-runtime`). A
+  `data-ppt-runtime` attribute whose value is not `1`, or on an element other
+  than `<script>`, is an error (`invalid-runtime-marker`).
+- The runtime handles the first/last slide, arrow keys, space, Page Up/Down,
+  Home/End, the `#/n` URL hash, and print styles. Clicking a noninteractive
+  area advances; links, buttons, form controls, and editable content keep their
+  own behavior. `F` toggles fullscreen and `P` opens the presenter view (notes,
+  next-slide preview, timer, prev/next). Authored `fade`/`slide` transitions
+  animate slide changes unless the viewer prefers reduced motion. Do not replace
+  the runtime with custom navigation unless the user asks and accepts that the
+  editor will not run it.
+
+## Charts
+
+- Chart data lives in `data-ppt-chart` on a figure (or another element) and
+  must be valid JSON (`invalid-chart-json` error otherwise).
+- A typical chart attribute:
+
+```html
+<figure
+  data-ppt-el="e5"
+  data-ppt-chart='{"type":"bar","title":"Revenue","labels":["Q1","Q2"],"series":[{"name":"USD","values":[18,24]}],"colors":["#e8a33d"]}'>
+</figure>
+```
+
+- Keep the JSON small enough to read and edit directly. Treat the attribute as
+  the source of truth: any rendered chart is derived from it, so editing only
+  the rendered output would not change the data.
+
+## Assets and styling
+
+- Use `data:` URIs or absolute URLs for images, fonts, and other assets.
+- Relative `src`/`href` values and relative `url(...)` values produce the
+  `relative-asset` warning. They do not travel with an exported file.
+- Arbitrary CSS is allowed: custom properties, flex/grid inside objects,
+  inline SVG, CSS animations, shadows, gradients, and absolute web fonts.
+- `position: fixed` and full-height units (`100vh`, `100dvh`, `100svh`,
+  `100lvh`) produce the `fixed-layout` warning because they may not export
+  reliably. Other viewport units (for example `50vh`) are not matched by the
+  validator but still scale with the browser window, so avoid them for layout.
+- A `<canvas>` produces the `canvas-content` warning: its drawing cannot be
+  edited visually.
+- Scripts other than the runtime produce the `script-present` warning. The
+  editor does not execute them.
+
+## Round-trip and writes
+
+- Serialization writes `<!doctype html>` followed by the document element. The
+  MCP/editor path removes editor-only attributes before writing:
+  `data-ppt-editing` and `data-ppt-frame-slide` are always rejected by
+  validation (`editor-artifacts` error) if present in a saved file.
+- HTML export adds the generator comment
+  `<!-- Edited with htmlcraft. Format: htmldeck/v1. -->` and, for a multi-slide
+  deck with no runtime and no script at all, appends the runtime.
+- Writes are atomic (temporary file plus rename) and compare against the
+  revision last read or written. A changed file produces a structured
+  `conflict` error; re-read and retry.
+- Normalization may add missing slide/object ids; the editor may also add a
+  relative position to statically positioned slide roots. Unknown HTML and CSS
+  are preserved otherwise.
+
+## Validation summary
+
+Errors make a deck invalid; warnings do not.
+
+| Severity | Code | Meaning |
+| --- | --- | --- |
+| error | `empty-document` | No content in the document. |
+| error | `nested-slide` | A slide is inside another slide. |
+| error | `invalid-canvas-size` | Explicit canvas width/height is not positive. |
+| error | `invalid-transition` | Transition is not none, fade, or slide. |
+| error | `duplicate-element-id` | An element id repeats within a slide. |
+| error | `invalid-chart-json` | `data-ppt-chart` is not valid JSON. |
+| error | `duplicate-slide-id` | A slide id repeats. |
+| error | `invalid-runtime-marker` | Runtime attribute is not `1` on a script. |
+| error | `duplicate-runtime` | More than one runtime script. |
+| error | `notes-nested-incorrectly` | Notes are not a direct child of a slide. |
+| error | `editor-artifacts` | Editor-only attributes are present. |
+| warning | `missing-title` | No `<title>`. |
+| warning | `single-body-fallback` | No slides found; the body is one slide. |
+| warning | `missing-slide-id` | A slide has no `data-slide-id`. |
+| warning | `missing-runtime` | Multiple slides but no runtime. |
+| warning | `script-present` | A non-runtime script is present. |
+| warning | `relative-asset` | A relative asset URL is present. |
+| warning | `fixed-layout` | `position: fixed` or a full-height `100vh` unit is present. |
+| warning | `mixed-canvas-sizes` | Slides use different canvas sizes. |
+| warning | `canvas-content` | A `<canvas>` cannot be edited visually. |
+| warning | `unsupported-group-nesting` | Groups are nested. |
+| info | `slide-count` | Number of detected slides. |