konpeki 0.3.1 → 0.4.0

package/docs/development.md

@@ -1,265 +1,52 @@
 # Development
 
-Clone `https://github.com/vcfgdev/konpeki.git` with the required repository access.
-Use [mise](https://mise.jdx.dev/getting-started.html) to install the Node.js and
-pnpm versions pinned in `mise.toml`. On macOS, install mise with `brew install mise`.
-From the repository root:
+Use the versions pinned by `mise.toml`, run commands through `mise exec --`, and
+preserve `pnpm-lock.yaml`.
 
-```sh
-mise trust
-mise install
-mise exec -- pnpm install --frozen-lockfile
-```
-
-Mise manages the toolchain; pnpm manages dependencies through `pnpm-lock.yaml`.
-Run the commands below from that repository root with an activated mise shell,
-or prefix them with `mise exec --` (for example, `mise exec -- pnpm test`).
-No global Node.js or pnpm installation is required. npm for packing and publishing
-comes with the pinned Node.js; use `mise exec -- npm pack` to select it explicitly.
-
-Development and regression checks require a repository checkout, not an npm
-tarball, which excludes tests and review scripts.
-
-## Development server and demo hosting
-
-```sh
-pnpm dev
-```
-
-For a production preview, run `pnpm build` then `pnpm preview`. The build produces
-a static site in `dist` for a root or subdirectory. Use
-`?example=introducing-konpeki` or `?example=custom-visual` to open a bundled editable
-example. Each example has an isolated browser-local working copy that survives
-reload. The Demo Mode menu supports JSON import/download, starting blank and
-resetting the example. These actions never replace another example or the normal
-local draft. Invalid stored data remains untouched until an explicit reset.
-
-Deploy only the static `dist` output for the public playground, not a file-session
-server. Imported documents stay in that browser; there is no account, cloud sync,
-AI generation or Build/notes handoff in standalone mode. Downloaded JSON can be
-opened in a file-backed session with a coding agent. Browser storage is not a
-backup. Hosting shares bundled examples, not private drafts or an AI service.
-No deployment is automatic. In a remote environment, expose a review server
-through its authenticated preview mechanism, not a loopback address.
-
-The source CLI's `preview` chooses the next available port if its default is
-occupied. An explicit `--port <number>` fails rather than silently changing the
-requested port; `--port 0` asks the OS for a free port. `--json` prints one readiness
-record with `type`, `compositionPath` and the exact session-bearing `url` after
-listening. Treat that URL as a capability, not public logging data. This is a
-startup signal, not proof that the browser loaded the right composition.
-
-### GitHub Pages
-
-The public playground is hosted at
-[vcfgdev.github.io/konpeki](https://vcfgdev.github.io/konpeki/?example=introducing-konpeki).
-The example query opens the introduction; the root URL opens the ordinary local
-draft. Each visitor's edits stay in their own browser, not in the deployed site.
-
-`.github/workflows/pages.yml` deploys only when explicitly dispatched on `main`:
-
-```sh
-gh workflow run pages.yml --repo vcfgdev/konpeki --ref main
-```
-
-The workflow uses the pinned mise/pnpm toolchain, runs typecheck and tests, builds
-with the Pages base path, and uploads only `dist`. The deployment job publishes
-that artifact to the `github-pages` environment. Repository **Settings → Pages →
-Source** must be **GitHub Actions**. Ordinary pushes run CI but do not redeploy;
-package releases remain separate. Inspect the public example after deployment,
-including reload, fonts, editing, JSON download and Present.
-
-Existing example working copies survive deployments. Download any edits before
-choosing **Demo Mode → Reset example** to load a newly published example.
-
-## Skill and plugin packaging
-
-`skills/konpeki/` is the canonical portable skill. The repo's
-`.agents/skills/konpeki` symlink enables local discovery without a second
-copy. The root Agent Plugins `plugin.json` and repo marketplace expose the same
-skill to compatible Codex clients; no MCP, hook or hosted AI is involved. Review
-native-client installation separately from the npm smoke test.
-
-The skill dispatches `init` (open only) and `generate` (create/revise, including
-implicit setup). These are agent modes, not CLI subcommands. Its portable
-`scripts/prepare-document.mjs` validates through the resolved CLI and exclusively
-creates a blank file, or validates an existing file without rewriting it. The
-bundled `assets/blank.json` matches `initialDraft(true)` in
-`composition/document.ts`; onboarding tests enforce that contract. Keep scripts
-and assets when copying the skill. No TypeScript import from `node_modules` is
-needed, so a copied skill also supports the existing published runtime.
-
-Its `scripts/ensure-runtime.mjs` pins the release runtime. It performs
-no installation without `--install`, and never updates project dependencies.
-When preparing a new release, deliberately update its pin and the plugin version
-together with the package version after testing the target runtime. The current
-pin is 0.3.1; local CLI/playground changes do not republish that npm version.
-
-## Implementation reference
-
-- `src/` contains the shared canvas application for editing and presentation.
-  The [versioned composition contract](../composition/README.md) preserves
-  content, relationships and visual intent across human and agent revisions.
-- `bin/` contains the file-session CLI and its revision-checked persistence.
-- [AUTHORING.md](../AUTHORING.md) owns design defaults, factual fidelity and review.
-  [Design resources](../design/README.md) provide palettes, themes and semantic
-  patterns; these are choices, not mandatory layouts.
-- `lib/text.tsx` supplies measured `Text` and `Paragraphs` with string or rich-text
-  runs. Overset content is flagged, not automatically shrunk or hidden. Await
-  `fontsReady` from `lib/typeface.ts` before measuring.
-- `lib/slide.tsx` supplies specimen `Panel`, `Relationship` and 1920×1080 `Sheet`
-  components. `Panel` shares one heading/body size; `Relationship` is a short
-  directional glyph. Convert their SVG output to composition vectors for the canvas.
-- `lib/layouts.ts` supplies fixed-gutter regions, not a content-fitting solver.
-- Retained React chart references use Nivo `Bar`, `Line` and `Sankey` with
-  `chartDefaults(palette)` from `lib/charts.ts` spread before chart-specific props.
-  Keep data, dimensions, scales and semantic colors in the deck. Use explicit
-  label colors and `linkBlendMode="normal"` for Sankey.
-
-### React/SVG drawing references
-
-The retained `slides/*/index.tsx` files are presentation-runtime-independent
-drawing references. They are checked as source but are not discovered as routes
-or executed by a second presentation runtime. New decks use composition JSON;
-a trusted build may render React to SVG, then convert supported elements into
-the owning component's editable vector payload.
-
-To migrate the retained architecture reference into the shared canvas:
-
-```sh
-pnpm example:migrate-page slides/architecture/index.tsx all /tmp/architecture-composition.json
-```
-
-Drag the resulting JSON onto the canvas, edit its vectors, and use **Present**.
-Replace `all` with a zero-based page index for one page. This command executes
-trusted local React source; never use it on untrusted JSX. It rejects unsupported
-SVG elements rather than silently flattening them. Review converted typography
-and geometry in the browser; conversion is not a fidelity guarantee.
-The bundled `?example=react-page-migration` preview uses the same format.
-Its working copy autosaves in that browser. Download JSON or use a file-backed
-session to retain edits outside browser storage.
-
-## Package contents
-
-`package.json` explicitly allowlists the npm payload: the source-based Vite
-runtime and file-session CLI, authoring guidance and design resources, and named
-curated examples with editable source and prompts. New example directories are
-not included automatically. Gallery screenshots, tests, research fixtures,
-browser review scripts, original branding assets, lockfiles and UI build output
-stay in the repository.
-
-`npm pack` builds the JavaScript CLI in `runtime/` automatically because Node
-cannot load its TypeScript source from inside `node_modules`. That generated
-CLI is included in the package.
-
-Run `pnpm check:package` before preparing a release. It checks npm's file selection,
-required resources, excluded development files and relative imports. For an
-installation smoke test, use `npm pack --pack-destination <temporary-dir>`, install
-the tarball in an empty project, then run its `konpeki validate` and `konpeki preview`
-commands against a composition outside the installed package. Do not publish
-until that isolated preview works. Publish the tested tarball rather than
-rebuilding during publication. Packing locally does not publish anything.
-
-## Tag releases
-
-`.github/workflows/publish.yml` stages releases on bare version tags such as `0.2.1`
-(no `v` prefix). The tag must equal `package.json`'s version.
-The workflow installs the mise toolchain and frozen dependencies, runs typecheck,
-tests, build and package checks, then installs a tarball in an isolated directory
-to validate a composition and build the packaged canvas. It stages that same
-tarball for maintainer approval; it does not publish directly. Browser review
-remains a pre-release responsibility.
+## Architecture
 
-Before the first tag release, configure **Trusted publishing → GitHub Actions**
-in the `konpeki` package settings on npmjs.com:
+Static HTML and CSS are the only document source. `html/source.ts` validates and
+revises source, `html/server.ts` exposes the authenticated preview and local
+assets, and `html/browser.ts` uses Playwright for inspection and PNG/PDF export.
+The React preview UI lives in `html/preview.tsx`; its small shared board,
+alignment, positioning, and style modules live under `src/`.
 
-- Organization or user: `vcfgdev`
-- Repository: `konpeki`
-- Workflow filename: `publish.yml`
-- Environment name: leave empty
-- Leave **Allow npm publish** unchecked (staged publishing only)
-
-The workflow uses GitHub-hosted runners and OIDC (`id-token: write`); no npm
-token secret is needed. Staged publishing requires npm 11.15.0 or newer and
-Node 22.14.0 or newer; the pinned toolchain meets both requirements.
-npm generates provenance automatically for public repositories;
-private repositories do not receive provenance.
-
-After updating the package version, completing release checks and pushing the
-release commit, explicitly create and push its matching tag:
-
-```sh
-VERSION=0.2.1
-git tag "$VERSION"
-git push origin "$VERSION"
-```
-
-Replace `0.2.1` with the version in `package.json`. Published versions cannot be
-republished. Pushing a matching tag submits the tested package to npm's staging
-area. After the workflow succeeds, review the release in npmjs.com's **Staged
-Packages** tab and click **Approve**, completing 2FA to publish it. Alternatively,
-use an authenticated local CLI:
-
-```sh
-mise exec -- npm stage list konpeki
-mise exec -- npm stage view <stage-id>
-mise exec -- npm stage approve <stage-id>
-```
-
-Approval makes the version public. Reject an incorrect staged release instead
-of approving it (`npm stage reject <stage-id>`).
+`bin/konpeki.mjs` is the HTML-only CLI entry. `scripts/build-cli.mjs` bundles it
+to `runtime/konpeki.mjs` so npm consumers can run it without TypeScript support.
 
 ## Verification
 
 ```sh
-pnpm check
-pnpm test
-pnpm build
-pnpm check:package
-```
-
-With the dev server running and `agent-browser` installed:
-
-```sh
-node scripts/check-canvas.mjs http://localhost:4318 .amp/in/artifacts
-node scripts/check-pages.mjs http://localhost:4318 .amp/in/artifacts/pages
-```
-
-For the Build it lifecycle, `node scripts/check-build.mjs` starts its own
-disposable file session. It checks pending requests, agent refresh, failure
-recovery and reduced motion, and captures the affected states. Add an output
-directory and `--record` to also record the animation.
-
-`node scripts/check-notes.mjs` checks page/vector note scopes, draft isolation,
-reload persistence, CLI claim/finish, clarification and cancellation in a disposable
-file-backed browser session. It accepts a screenshot directory as its first argument.
-
-`node scripts/check-feedback.mjs <output-directory>` checks invalid numeric input,
-blank-canvas commits, page renaming, stable panel geometry, native/vector overflow targets,
-note-save recovery, and file-save/conflict recovery with delayed opens and stale polls
-in a disposable session with injected service failures. It
-also checks notification exits, interrupted re-entry, inert hidden controls and reduced
-motion, and records screenshots and measurements. Run with `--before` on a baseline checkout
-to record the same failure states without asserting the revised behavior.
-
-These checks exercise all five component kinds, empty slides, JSON round trips,
-vector editing/history and fitted line dragging. They capture editor and
-presentation states at two sizes; inspect the images because assertions alone
-do not establish visual correctness.
-
-Documentation changes need link and instruction checks. Deck changes need
-typecheck, build, relevant fixture checks and actual visual inspection. Shared
-component, theme or dependency changes also need the full test suite and
-representative affected decks. A build can report a large-framework-chunk advisory.
-
-Render affected pages at presentation and review sizes after fonts load. Inspect
-text, clipping, relationships, contrast and cross-page consistency. Repair issues
-and inspect fresh captures. Keep browser checks scoped to factual and layout
-contracts, not universal taste. Record untested outputs and limitations with
-the example; screenshots do not prove PDF/PPTX or cross-application fidelity.
-
-When adding examples, preserve the exact creative requests, editable source,
-source facts and reviewed images as described in [AUTHORING.md](../AUTHORING.md).
-Examples demonstrate capabilities; there is no separate benchmark suite or
-aesthetic score. Check font language subsets and license notices when
-redistributing assets; dependencies retain their own licenses.
+mise exec -- pnpm install --frozen-lockfile
+mise exec -- pnpm exec playwright install chromium
+mise exec -- pnpm check
+mise exec -- pnpm test
+mise exec -- pnpm build
+mise exec -- pnpm check:package
+mise exec -- pnpm audit --prod
+```
+
+Before a release, install the generated tarball in a disposable directory and
+exercise runtime discovery, starter preparation, HTML validation, inspection,
+PNG/PDF export, and preview. Audit the installed package too: npm consumers can
+resolve dependencies differently from the repository lockfile. Exercise the
+preview's comment and copy-and-clear flow from that installation, not only a
+source checkout.
+
+## Release
+
+1. Finish the verification above and commit the exact release candidate. Keep
+   `package.json`, `plugin.json` and the skill's runtime version aligned. Describe
+   breaking changes in the README's upgrade section and the release notes.
+2. Obtain explicit approval before pushing or tagging. The release tag must
+   exactly match the package version (`0.4.0`, not `v0.4.0`).
+3. Pushing the approved tag starts **Stage package release**. It checks the code,
+   installs and exercises the tarball, then stages that tarball on npm. A green
+   workflow means staged, not published.
+4. The maintainer reviews and approves the staged package through npm's approval
+   flow. Verify the published version with `npm view konpeki@0.4.0 version` and
+   smoke-test a registry installation before announcing availability.
+
+GitHub release creation and the manual Pages deployment are separate actions;
+neither is authorized by permission to push a tag. Never publish, push, deploy,
+or tag without explicit permission for that action.

package/docs/workflow.md

@@ -1,110 +1,8 @@
-# Canvas workflow
+# Workflow
 
-Start with [Use with your agent](../README.md#use-with-your-agent) and give your
-coding agent a brief in its prompt field. Install the complete skill directory;
-its bootstrap script finds or installs the runtime separately. Skill discovery
-varies by agent: Codex CLI/IDE uses `$konpeki`, while the standalone Claude Code
-skill uses `/konpeki`. Other clients may use skill selection or natural language.
-`init` opens a blank or existing file-backed editor without generating; `generate`
-creates or revises a visual, opens its preview and inspects it, with setup implicit.
-A creation brief without a mode selects generate. Follow-up reviews continue the
-same document without repeating a command. These are skill modes, not terminal
-subcommands. **Build it** is an optional revision handoff, not a required first-run
-step; opening the editor does not start a review listener.
+The canonical authoring and revision loop lives in the
+[Konpeki skill](../skills/konpeki/SKILL.md).
 
-## Documents and exports
-
-New documents live in `slides/<name>/composition.json`, with `PROMPT.md`, source
-notes and reviewed images alongside. Keep the editable composition under version
-control. The canvas is the source of truth for editing and presentation; download
-its JSON for handoff and drag returned JSON onto the canvas to continue.
-
-One page is a complete creation. Presets cover Presentation (1920×1080), Square
-post (1080×1080), Portrait post (1080×1350), Link preview / OG (1200×630), and
-Article header (1600×600). The document contract supports 256–4096 pixels per side.
-Pages in one document may use different sizes. Changing size never stretches
-content and is refused when existing components would fall outside the page.
-Recompose for a new aspect ratio instead of stretching or cropping.
-
-**Export PNG** saves the active page at its declared dimensions without editor
-controls. JSON remains the editable source; PNG is an image. Fresh documents and
-added pages are empty. **Present** uses the same renderer for any page sequence.
-
-Standard Chart, Diagram and Table illustrations are structural drafts. Finished
-artwork can remain owned by its semantic component as editable vector elements.
-Retained React/SVG examples are drawing references, not another deck runtime.
-
-## File-backed editing with an agent
-
-The CLI interface is `konpeki <command>`. After local installation, use
-`npm exec --no -- konpeki <command>` from your workspace. In a repository checkout,
-use the development shim `pnpm konpeki <command>` instead:
-
-```sh
-npm exec --no -- konpeki validate slides/my-visual/composition.json
-npm exec --no -- konpeki preview slides/my-visual/composition.json
-```
-
-`preview` prints a capability-bearing local URL. Open that exact URL. Valid
-browser edits are saved atomically to the composition file; a revision hash
-prevents overwriting concurrent external changes. When an agent updates the same
-file, the canvas loads the valid revision and keeps the previous document in Undo.
-
-An agent waiting for a person's revision request runs:
-
-```sh
-npm exec --no -- konpeki wait slides/my-visual/composition.json
-```
-
-In the file-backed canvas, select a component or an inner vector element and
-write a **Revision note** in the left panel's **Notes** tab. With nothing selected, the note targets
-the page. **Add note** saves feedback without starting a build; add notes to several
-targets, then choose **Build it** to submit them together. Numbered canvas pins
-return to their note and selection. Pins and notes never appear in presentations
-or PNG exports. Direct text, geometry and attribute edits still save normally.
-
-**Build it** saves the composition and submits its exact revision, selected page,
-component and optional vector-element ID, plus all unresolved notes. Without notes,
-it requests a build from the saved composition and selected scope as before.
-`wait` atomically claims one submitted request, marks it working, prints the
-machine-readable v2 request and exits. It does not launch or wake an agent.
-Until claimed, the canvas asks you to contact your coding agent and offers
-**Copy prompt** for the handoff. “Agent working” means claimed, not a live
-agent heartbeat. Only one request per document can be active. Connection errors
-keep an active request locked until completion or cancellation.
-
-The agent must reread the named composition and preserve newer human edits.
-Follow each note's target IDs, not just the active page; never silently retarget
-a deleted element. After validating, rendering and inspecting all requested
-changes, explicitly finish using the ID returned by `wait`:
-
-```sh
-npm exec --no -- konpeki finish slides/my-visual/composition.json <request-id> --message "Updated and checked"
-```
-
-Only this acknowledgement resolves the submitted notes and unlocks editing.
-File changes alone do not complete the request; explicit no-op completion is
-valid when the requested result is already present. If blocked, finish with
-`--status needs-clarification --message "What needs clarification?"` or
-`--status failed --message "What failed"`. Notes stay unresolved for a retry.
-Do not mark a partly applied batch done. **Cancel request** unlocks the editor
-and keeps notes, but cannot stop an agent process; stop that agent before retrying.
-
-Feedback is stored next to the document as `composition.json.review.json`, separate
-from artwork and exports. Retain that file with the composition when moving work.
-Browser reloads and preview restarts preserve notes and request status. To inspect
-or recover an already claimed request after an interruption, run:
-
-```sh
-npm exec --no -- konpeki request slides/my-visual/composition.json
-```
-
-Coordinate with the previous worker before resuming; `wait` does not claim an
-already working request a second time. Do not edit the sidecar manually while a
-preview or agent is updating it. Existing v1 temporary requests are not migrated;
-finish them before upgrading, then resubmit if needed. Browser-local drafts and
-hosted examples do not expose revision notes or **Build it** because no local
-agent owns their files.
-
-Browser screenshots do not establish PDF/PPTX editability, font embedding or
-cross-application fidelity. Inspect every requested export separately.
+Use the [HTML, files, theme, and CLI reference](../html/README.md) for document
+rules and tool behavior, the [authoring floor](../skills/konpeki/floor.md) for
+bans and the review checklist, and [AUTHORING.md](../AUTHORING.md) for judgment.

package/html/README.md

@@ -0,0 +1,140 @@
+# HTML, files, theme, and CLI
+
+This is the reference for Konpeki's source contract and runtime behavior. The
+[skill](../skills/konpeki/SKILL.md) owns workflow, its [floor](../skills/konpeki/floor.md)
+owns bans and defaults, and [AUTHORING.md](../AUTHORING.md) owns editorial and
+visual judgment.
+
+## Document and file contract
+
+- Author static HTML/CSS and inline SVG. Do not author JavaScript, applications,
+  interactive controls, or remote resources.
+- Each page is an explicit direct child of `<body>` with `data-page` and a
+  globally unique, stable `id`. Targetable HTML and SVG elements also need
+  globally unique, stable IDs.
+- CSS defines fixed page width and height, at most 8192 CSS px per side. Pages
+  may differ in size. Page breaks are explicit; overflow is not paginated.
+- Keep images, stylesheets, and licensed fonts beside the HTML with relative
+  paths, or embed them. The only remote exception is Google Fonts from
+  `fonts.googleapis.com/css2` and `fonts.gstatic.com`; it requires network access.
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <link rel="stylesheet" href="theme.css">
+  </head>
+  <body>
+    <main id="page-1" data-page data-size="link">
+      <h1 id="title">A clear headline</h1>
+    </main>
+  </body>
+</html>
+```
+
+## Themes
+
+Link `theme.css` for the default light-blue theme. Read [Use a theme](theme.md)
+for its `--kp-`-prefixed public tokens, complete type roles, page presets, and asset
+requirements. A compatible entry point sets `--kp-theme: 1`; the base alone does
+not. Keep the imported `theme-base.css` and referenced fonts beside the entry
+point. Adapt a copy of the default when a brief brings its own look.
+
+For deliberately unthemed content, set `data-theme="custom"` on its ancestor.
+This skips theme-value checks in that subtree and definition checks on an
+opted-out page, but keeps layout and resource checks. An alternative implementing
+the contract does not need this opt-out.
+
+## Diagnostics
+
+`inspect` detects page and text overflow, clipped text, missing resources,
+inter-element text line-box overlap, and opaque sRGB HTML text contrast against
+solid ancestor backgrounds. Contrast thresholds are 3:1 for large text and
+4.5:1 otherwise. Contrast inspection skips SVG text, gradients, images,
+transparency, and compositing it cannot evaluate reliably.
+
+Floor warnings use the rule ID from the [authoring floor](../skills/konpeki/floor.md)
+as their code. `label-above-headline` flags a short, smaller line directly above
+a title, display or section heading in the same column; running heads repeated
+across A4 pages, full sentences and metric figures are not flagged, and
+`data-kp-allow="label-above-headline"` on the label records a deliberate
+exception. `stranded-word` flags a headline line that holds one word after a fuller
+line, within each `<br>`-separated part; a line a `<br>` isolates is deliberate. The base balances headline roles and
+sets `text-wrap: pretty` on pages to avoid most stranded words.
+
+`small-text` warns below 24 CSS px on screen presets and 11 CSS px on A4,
+including unthemed HTML and SVG text. The default preset is presentation.
+These are computed font-size floors, not a guarantee of legibility after SVG
+viewBox scaling, CSS transforms, or reduction to the final viewing size. Unknown
+custom presets have no assumed floor. Review screen graphics at their intended
+size and print pages at actual size; warnings do not block export.
+
+For opted-in themes, it also checks the active definition and compares used
+size/leading pairs, colors and shape treatments to its tokens. See the [theme diagnostics](theme-authoring.md#verify-a-theme)
+for required roles and contrast pairs. `inspect` includes each page's resolved
+type treatments under `theme.type`, so authors can plan with the actual sizes.
+
+CLI inspection checks which fonts actually drew the text. Installed-font fallback
+is an error, including on unthemed pages. Both CLI and preview check declared
+weight/style coverage; only CLI can audit actual glyph fallback. Load the required
+licensed faces and subsets from Google Fonts, local files, or embedded data
+instead of relying on the machine. The default theme uses Google Fonts and needs
+network access during preview and export; finished PNGs and PDFs do not.
+
+HTML overlap uses estimated line-height boxes rather than raw font rectangles;
+SVG, normal leading and transformed text retain range bounds. These are not glyph
+ink measurements, and automated checks cannot establish factual
+correctness or visual quality. Inspect rendered output. A render with diagnostic
+errors exits nonzero and writes no output.
+
+## CLI
+
+```text
+konpeki validate document.html
+konpeki inspect document.html [--page N] [--details]
+konpeki check document.html
+konpeki render document.html [--page N] [--format png|pdf] [--scale 2] [--output file]
+konpeki preview document.html [--host host] [--port port] [--json]
+konpeki browser install
+```
+
+Pages are one-based. HTML export supports PNG and PDF only. PNG defaults to page
+1; PDF includes all pages unless `--page N` is supplied and preserves mixed page
+sizes. `--scale` affects PNG only. Outputs are exclusive and never overwritten.
+
+Inspection and export require the pinned Chromium installed by `browser install`;
+preview does not. Preview chooses another available port when its default is
+busy, while an explicit `--port` is strict.
+
+Preview comments remain browser-local. **Copy & clear** copies the full local
+document path, comments, and target IDs for pasting into an agent conversation.
+Small moves edit translation only; they do not reorder source. Deletion may
+reflow content. Reread current source and preserve unrelated edits when applying
+feedback.
+
+## Keyboard review
+
+Open **Keyboard shortcuts** (`?`) and enable **Vim review mode**. The preference
+is remembered in this browser. With it off, the existing mouse and comment
+shortcuts are unchanged.
+
+| Context | Keys | Action |
+| --- | --- | --- |
+| Canvas | `f`, then hint letters | Comment on a visible element of the current page |
+| Canvas | `c` / `Shift+C` | Comment on the selection / entire current page |
+| Canvas | `h j k l` | Pan left, down, up, right |
+| Canvas | `[` / `]`, `gg` / `G` | Previous / next page, first / last page; keep zoom |
+| Canvas | `+` or `=`, `-`, `0` | Zoom in, zoom out, fit and center current page |
+| Canvas | `q` | Open all pending comments |
+| Comment | `⌘/Ctrl+Enter` | Add and return to the canvas without changing the viewport |
+| Pending comments | `j` / `k`, `Enter` | Select a comment, reveal its target and notes |
+| Pending comments | `⌘/Ctrl+Enter` | Copy & clear; comments stay intact if copying fails |
+| Review | `Esc` | Back one level, preserving unfinished drafts until reload |
+
+The current page follows navigation and panning. Hints use stable element IDs,
+exclude hidden/offscreen targets, and keep their codes while filtering.
+`Backspace` corrects a hint prefix; `Esc` cancels. Moving the viewport or updating
+the source cancels hints rather than reusing stale geometry. Letter shortcuts are
+suspended inside text inputs and during IME composition. Review mode does not
+add Vim text editing or bare-letter source-deletion commands.