git:20261016.a2420d5 to git:20261019.353d5b7

1 added, 1 removed. Audit A to A.

# Pixelbolt

To **use** Pixelbolt for artwork, start with [the pixel art skill](skills/pixel-art/SKILL.md), [the authoring guide](docs/agent-guide.md) and [schema.json](schema.json). [llms.txt](llms.txt) indexes the public documentation; [README.md](README.md) includes CLI and MCP setup. The instructions below apply when **contributing to the toolkit**.

This is an agent-first pixel art toolkit. Keep the core and runtime free of dependencies. Use standard Node.js APIs for the CLI, PNG/APNG encoding, ZIP and the local server. No build step is required.

- `src/core.js`: browser-compatible recipe validation/rasterization/atlas packing, inspection (contact sheets, palette-key grids) and revision comparison.

- `src/craft.js`: browser-compatible pixel-art helpers shared by the renderer, patches and compilers: ordered, noise and value-noise dither, De-Corner/De-Stray cleanup, RotSprite-style rotation, rewrite rules, easing, seeded hashing and engine-independent trigonometry. Keep new randomness seeded and new maths polynomial so output stays identical across JavaScript engines.

- `src/font.js`: browser-compatible built-in pixel font (printable ASCII, western European accented letters, common symbols) and text layout for the `text` drawing operation. Glyph changes change rendered pixels, so treat them as format changes: regenerate examples and review.

- `src/fx.js`: browser-compatible `pixelforge-fx` compiler that bakes seeded particle emitters into ordinary recipes.

- - `src/fluid.js`: browser-compatible `pixelforge-fluid` compiler: stable-fluids gases and FLIP liquids on a one-cell-per-pixel grid, baked into palette `grid` operations. Same determinism rules as `craft.js` (only + − × ÷ and sqrt, seeded hashing, fixed steps and iterations); the golden hashes in `test/fluid.test.js` and the GIFs from `showcase/fluid/build.mjs` change with any change to its output, so regenerate both deliberately.

+ - `src/fluid.js`: browser-compatible `pixelforge-fluid` compiler: stable-fluids gases and FLIP/APIC liquids on a one-cell-per-pixel grid, with implicit stress-form viscosity, yield stress and adhesion, baked into palette `grid` operations. Same determinism rules as `craft.js` (only + − × ÷ and sqrt, seeded hashing, fixed steps and iterations); the golden hashes in `test/fluid.test.js` and the GIFs from `showcase/fluid/build.mjs` change with any change to its output, so regenerate both deliberately.

- `src/patch.js`: browser-compatible targeted recipe edits and canvas-coordinate painting addressed by error-style paths.

- `src/autotile.js`: browser-compatible blob/cardinal neighbour masks, template quarter layout and tilemap legends (variants, weights, neighbour rules), shared by scene tilemaps, the recipe `tilemap` operation and the autotile compiler in `src/authoring.js`. It imports `craft.js`, so copies of it (Tidewatch's game) need both.

- `src/authoring.js`: browser-compatible compilers whose output is an ordinary recipe: poses, autotile templates and normal passes derived from a colour recipe (`compileNormals`; deterministic, no trigonometry).

- `src/resolve.js`: Node-side resolution of shared palette files, scene asset references and a normals source's recipe; the renderer itself never reads files.

- `src/revisions.js`: immutable on-disk MCP recipe snapshots under the configured output directory.

- `src/export.js`, `src/png.js`: deterministic file exports.

- `src/gif.js`: browser-compatible GIF89a export for sharing, used by the CLI, MCP and studio. Exact colours only: it never quantizes or dithers, and reports what GIF cannot keep (partial alpha, sub-10 ms timing) instead of hiding it. `framesGIF` writes frames made elsewhere at a frame rate, with a colour table per frame when the loop needs more than 256 colours.

- `src/frame-folder.js`: Node-side reading of a folder of numbered PNG frames for `gif-frames`: number order, gaps, other files and mixed sequences are reported, not guessed. It reads the folder and never writes to it.

- `src/sequence.js`: numbered PNG frames for video editors, from recipes and scenes: exact frame-rate fractions, whole-number enlargement onto a video-sized canvas (contained, or covering it and cropped), a sidecar and the ffmpeg command for an alpha video. It encodes no video itself; keep it that way.

- `src/mcp.js`, `src/server.js`: agent and studio interfaces.

- `src/runtime.js`: exported Canvas animation player.

- `studio/`: plain HTML/CSS/JS preview studio; it shares the core renderer. `studio/fluid.html` and `fluid-lab.js` (the Fluid lab) compile fluid presets in the browser with `src/fluid.js`. `studio/draft.js` keeps one unsaved recipe in the browser's own storage; draft recovery must stay in the browser, never a server endpoint.

- `packaging/`: launcher scripts, START HERE and notices for the portable builds: `common/` for every system (START HERE.txt is one text with `#if windows|macos|linux` blocks), `windows/` batch files, `unix/` shell scripts for macOS and Linux, `macos/` double-click `.command` files. `scripts/build-studio.mjs` packs them with the `npm pack` file list and the pinned official Node.js runtime into a reproducible archive per target under `dist/`; `scripts/verify-studio.mjs` tests a built archive on its own system.

- `scripts/qa-studio.mjs`: walks the studio in an installed Edge or Chrome, headless with a throwaway profile, over the DevTools protocol with Node's own WebSocket. No browser-automation dependency; run it after studio changes. Packaging adds nothing to `package.json`'s dependencies or `files`, and its scripts only print or serve: they never edit a user's configuration.

- `schema.json`, `poses.schema.json`, `scene.schema.json`, `autotile.schema.json`, `fx.schema.json`, `fluid.schema.json`, `normals.schema.json`: generated with `node scripts/generate-schema.js`.

- `examples/`: generated with `node scripts/generate-examples.js`.

Run `npm test` after functional changes. Keep the schema, authoring reference and runtime validation aligned. Binary export changes should also be checked with an independent image decoder. Do not replace the text-first workflow with a UI-only drawing tool.

Never silently overwrite source recipes or generated assets. MCP renders create unique folders. The preview server must stay on loopback with an explicit asset allowlist and no arbitrary file-writing endpoints.

## Commit and push workflow

The repository owner authorizes agents working on this project to commit completed changes and push directly to `main` by default. After reviewing the diff and passing the relevant checks (including `npm test` for functional changes), commit and push without asking for routine confirmation or opening a pull request. This is the standing workflow for this small project unless the user requests a different approach.

Before committing, inspect existing uncommitted changes and preserve them. Include changes from other agents when the user has authorized combining that work; otherwise leave unrelated work untouched. Fetch before pushing and integrate upstream changes without discarding local work. Never force-push, rewrite published history, reset away changes or delete branches as part of this authorization. Report the resulting commit and push status; if pushing fails, explain the concrete blocker.