pixelkiln 0.26.0 → 0.28.0

package/docs/ARCHITECTURE.md

@@ -182,6 +182,22 @@ provider object ids to remote content hashes for adoption/salvage. Neither is
 authoritative or committed; both can be deleted and rebuilt. Every recovery
 byte is structurally validated before use.
 
+## Pinned editor build
+
+The gallery's in-browser editor is a web export of Pixelorama with PixelKiln's
+bridge extension, built in CI from a build-time overlay on the pinned upstream
+tag (`tools/pixelorama-bridge/`) and published as a GitHub release whose tag
+semantic-release ignores. The package does not carry the 46 MB build; it
+carries `tools/pixelorama-bridge/pin.json` — the release tag plus the SHA-256
+and size of every file — inlined into `src/editor/pin.ts` at bundle time, so
+the shipped code and the build it trusts are one artifact. `installEditor`
+fetches only missing or mismatched files into a per-release directory under
+the user cache, verifies each against the pin before renaming it into place,
+and the gallery serves a file only after the whole directory verified and its
+size still matches; a file that changed on disk is refused rather than served.
+The release tag is part of the served path, so the browser may cache the
+files as immutable, and a new pin is a new path.
+
 ## Provider capability boundary
 
 Providers are selected from a registry by each style's `provider`, falling back

package/docs/ARTIFACTS.md

@@ -126,6 +126,31 @@ Generic JSON retains all provider rules and normalized masks. Tiled and Godot
 translate recognized four-edge/four-corner semantics and reject unknown or
 lossy mappings. See [TILES.md](./TILES.md) for the format contracts.
 
+## Hand-edit companion
+
+A hand edit saved from the gallery's in-browser editor leaves a small record
+beside it, `<edit>.edit.json`, that is not a provenance companion and is not
+transactional:
+
+```json
+{
+  "version": 1,
+  "basedOn": "<sha256 of the generated PNG the edit started from, or null>",
+  "sha256": "<sha256 of the edit as saved>",
+  "editor": "pixelorama@v1.2.2-stable",
+  "protocol": 1,
+  "savedAt": "2026-09-12T10:00:00.000Z",
+  "project": "anvil.pxo"
+}
+```
+
+`basedOn` lets the gallery report `regenerated-since` by comparing hashes
+rather than modification times; `sha256` shows when another tool rewrote the
+edit after the editor did; `project` names the layered Pixelorama file kept
+beside the edit, which the next in-browser edit opens so layers survive. An edit made with a desktop editor has no
+companion and is judged by file times. Commit the companion and the `.pxo`
+with the edit if you want that history; nothing else reads them.
+
 ## Provenance companion
 
 The companion is engine-neutral and versioned:

package/docs/CLI.md

@@ -247,6 +247,39 @@ Single-image PNG assets only for now; structural sets and GIF animations are
 refused with the reason. `--only` must resolve to one asset in one style, so
 add `--style` when the asset is shared.
 
+### `tools`
+
+Prepare the in-browser editor before opening a gallery, or check what is on
+disk.
+
+```bash
+pixelkiln tools status
+pixelkiln tools install editor
+PIXELKILN_TOOLS_DIR=/srv/pixelkiln-tools pixelkiln tools install editor
+```
+
+The editor is a web build of [Pixelorama](https://pixelorama.org) with a small
+PixelKiln bridge extension, about 46 MB, and is not part of the npm package.
+Each PixelKiln release pins one build — its GitHub release tag
+(`editor-pixelorama-<upstream tag>-pk.<n>`) and the SHA-256 and size of every
+file — and `install` fetches only the files that are missing or wrong from
+that release, verifies each against the pinned hash before it lands, and
+leaves nothing partial behind: a file that fails verification is discarded
+and the command fails naming it. `status` reports the pinned version, the
+release, and whether every file is present and verified (`--json` for the
+machine-readable form). Running `install` on a complete build fetches nothing.
+
+The files live outside the project, in a per-release directory under the
+user's cache (`~/Library/Caches/pixelkiln/tools` on macOS, `$XDG_CACHE_HOME`
+or `~/.cache/pixelkiln/tools` on Linux, `%LOCALAPPDATA%\pixelkiln\tools` on
+Windows), so one copy serves every project and an upgrade never overwrites the
+build an older PixelKiln still expects. `PIXELKILN_TOOLS_DIR` moves that root;
+`PIXELKILN_EDITOR_URL` points the download at a mirror or an internal server
+that hosts the same files (they are still verified against the pinned hashes,
+so a mirror cannot substitute a different build). Once installed the editor
+runs entirely offline; the gallery serves it from the local directory with no
+outbound requests.
+
 ### `gallery`
 
 Open a local, read-only gallery of everything the project has generated. Each
@@ -358,6 +391,27 @@ based on an older generation because the art was regenerated since — plus
 **Open in editor** and **Detach edit**. A card whose edit differs from the
 generated art shows the edit, since that is what ships, with a ✎ mark.
 
+`--edit` also offers **Edit in browser**: a pinned build of
+[Pixelorama](https://pixelorama.org) that the gallery serves itself, opened in
+a slide-out sheet with the sprite and the style's palette loaded. See
+[`tools`](#tools) for what is fetched, where it lives, and how it is verified;
+the header shows whether it is installed and, if not, an **Install editor**
+button that fetches it once with a progress bar — nothing is downloaded without
+that click or `tools install editor`. **Save to project** (or ⌘S / Ctrl+S in
+the editor) hands the flattened image back to the page, which writes the same
+`edits/` file `pixelkiln edit` would and declares it; the sheet stays open for
+the next change, **Save & close** does both, and closing with unsaved changes
+asks first. A browser save also keeps Pixelorama's layered `.pxo` beside the
+edit — the next **Edit in browser** hands it back, so layers and frames come
+back as they were (the flattened PNG is used only if the file cannot be read,
+and the sheet says which) — and writes `<edit>.edit.json` recording the
+editor, the time, and the hash of the generation the edit was based on, so
+`regenerated-since` is decided by hash rather than file times for those edits. The record shows the
+editor and the layer file; **Open in desktop editor** and **Detach edit** work
+on the same file. The editor page runs same-origin under its own
+content-security policy and never sees the gallery's session token — the page
+does the write. `--no-editor` hides all of it and serves none of its routes.
+
 A PixelLab `map` or `1dir` record also links to its account object (**Open in
 pixellab ↗**), where PixelLab's own editor can change it; with `--budget`
 (any amount — `--budget 0` allows provider contact and no spend) the record
@@ -636,7 +690,8 @@ Print the package version. `-v` is an alias.
 | `--check` | plan/audit/cache | Exit nonzero when selected state is unsafe. |
 | `--yes`, `-y` | confirmed operations | Skip an interactive confirmation. For `refine approve`, it records an already-completed human review; it does not replace one. |
 | `--no-open` | pick/salvage/gallery/edit | Do not automatically open the browser, or the editor for `edit`. |
-| `--edit` | gallery | Let the page change asset prompts, sizes, category, and tags, and add assets. Rewrites the manifest only; never contacts a provider or spends. |
+| `--edit` | gallery | Let the page change asset prompts, sizes, category, and tags, and add assets. Rewrites the manifest only; never contacts a provider or spends. Also offers the in-browser editor. |
+| `--no-editor` | gallery | With `--edit`, do not offer, install, or serve the in-browser editor. |
 | `--tag` | fetch/adopt | Also push tags after the command's primary work. |
 | `--refresh` | fetch | Re-download downloaded outputs and replace files whose object changed upstream; never generates, never overwrites a local edit without `--force`. |
 | `--claims <paths>` | salvage | Other project lockfiles; repeatable and comma-separated. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelkiln",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Manifest-driven pixel-art generation, review, recovery, and packaging with deterministic provenance.",
   "type": "module",
   "sideEffects": false,