rtistree 0.5.1 → 0.6.0

package/dist/sprites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprites.js","sourceRoot":"","sources":["../src/sprites.ts"],"names":[],"mappings":"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"}

package/dist/studio-reference.js

@@ -34,6 +34,6 @@ export const studioReference = {
         lighting: 'art.normal(heightFn,x,y,strength=1,step=1) → surface normal from central differences. art.light(normal,[r,g,b,a],{light:[x,y,z]?,ambient?,diffuse?,specular?,shininess?}) → RGBA using Lambert diffuse and Blinn–Phong specular, viewer along +Z. Artistic 2.5D shading, not ray tracing.',
     },
     example: 'return art.raster((x,y) => { const n=art.fbm(x/35,y/35); return [35+n*40,40+n*35,45+n*30,255]; });',
-    edits: 'readRasterRegion reads exact canvas-space PNG pixels and a scene hash. writeRasterRegion consumes an exact-size project-local PNG and that expected_hash, with replace/over semantics and canvas/layer coordinates. Layer-space patches capture reference dimensions and follow transforms. Layer effects/masks can change patch appearance; locality guards reject outward leakage.',
+    edits: 'readRasterRegion reads exact canvas-space PNG pixels and a scene hash. writeRasterRegion consumes an exact-size project-local PNG and that expected_hash, with replace/over semantics and canvas/layer coordinates. Layer-space patches capture reference dimensions and follow transforms. Patches follow target effects/operations and precede its mask/opacity; ancestor effects can change appearance; locality guards reject outward leakage.',
 };
 //# sourceMappingURL=studio-reference.js.map

package/dist/studio-reference.js.map

@@ -1 +1 @@
-{"version":3,"file":"studio-reference.js","sourceRoot":"","sources":["../src/studio-reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,mFAAmF;AACnF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,mBAAmB;IAC5B,UAAU,EAAE,gBAAgB;IAC5B,aAAa,EAAE,iBAAiB;IAChC,UAAU,EACR,8YAA8Y;IAChZ,QAAQ,EACN,sWAAsW;IACxW,SAAS,EACP,wPAAwP;IAC1P,MAAM,EAAE;QACN,iBAAiB,EAAE,EAAE;QACrB,MAAM,EAAE,EAAE;QACV,4BAA4B,EAAE,EAAE;QAChC,IAAI,EAAE,IAAI;QACV,UAAU,EAAE,GAAG;QACf,cAAc,EAAE,EAAE;QAClB,UAAU,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC;QACvB,WAAW,EAAE,GAAG;KACjB;IACD,GAAG,EAAE;QACH,MAAM,EACJ,gbAAgb;QAClb,MAAM,EACJ,uRAAuR;QACzR,MAAM,EACJ,iJAAiJ;QACnJ,MAAM,EACJ,sLAAsL;QACxL,KAAK,EACH,oGAAoG;QACtG,KAAK,EACH,0OAA0O;QAC5O,KAAK,EACH,qKAAqK;QACvK,WAAW,EACT,+IAA+I;QACjJ,MAAM,EACJ,qIAAqI;QACvI,IAAI,EAAE,kKAAkK;QACxK,QAAQ,EACN,0HAA0H;QAC5H,IAAI,EAAE,2EAA2E;QACjF,QAAQ,EACN,2RAA2R;KAC9R;IACD,OAAO,EACL,oGAAoG;IACtG,KAAK,EACH,sXAAsX;CACzX,CAAC"}
+{"version":3,"file":"studio-reference.js","sourceRoot":"","sources":["../src/studio-reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,mFAAmF;AACnF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,mBAAmB;IAC5B,UAAU,EAAE,gBAAgB;IAC5B,aAAa,EAAE,iBAAiB;IAChC,UAAU,EACR,8YAA8Y;IAChZ,QAAQ,EACN,sWAAsW;IACxW,SAAS,EACP,wPAAwP;IAC1P,MAAM,EAAE;QACN,iBAAiB,EAAE,EAAE;QACrB,MAAM,EAAE,EAAE;QACV,4BAA4B,EAAE,EAAE;QAChC,IAAI,EAAE,IAAI;QACV,UAAU,EAAE,GAAG;QACf,cAAc,EAAE,EAAE;QAClB,UAAU,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC;QACvB,WAAW,EAAE,GAAG;KACjB;IACD,GAAG,EAAE;QACH,MAAM,EACJ,gbAAgb;QAClb,MAAM,EACJ,uRAAuR;QACzR,MAAM,EACJ,iJAAiJ;QACnJ,MAAM,EACJ,sLAAsL;QACxL,KAAK,EACH,oGAAoG;QACtG,KAAK,EACH,0OAA0O;QAC5O,KAAK,EACH,qKAAqK;QACvK,WAAW,EACT,+IAA+I;QACjJ,MAAM,EACJ,qIAAqI;QACvI,IAAI,EAAE,kKAAkK;QACxK,QAAQ,EACN,0HAA0H;QAC5H,IAAI,EAAE,2EAA2E;QACjF,QAAQ,EACN,2RAA2R;KAC9R;IACD,OAAO,EACL,oGAAoG;IACtG,KAAK,EACH,obAAob;CACvb,CAAC"}

package/docs/agent-art-workflow.md

@@ -59,6 +59,16 @@ hidden backs of its hoops over the near lid, where they looked like handles.
 Both shared geometry and correct occlusion matter. Distinct shaded faces and a
 common palette are insufficient evidence of sound construction.
 
+**Pixel art:** declare the intended display size, palette and transparency policy.
+Keep coordinates, frame dimensions and pivots on integer pixels, use
+nearest-neighbour scaling, and inspect at the actual game size. A declared
+pixel-art contract can catch palette overruns, invalid tile geometry and
+disallowed transforms or blur; the sprite exporter preserves exact RGBA frame
+pixels. It cannot decide whether a one-pixel choice is artistically good.
+Use palette tiles for compact indexed marks and seeded studio programs for dense
+or generated frames. Pack a set only after the individual frames and their
+contact sheet have been inspected.
+
 **Animation:** declare facing, travel direction, ground plane, stride distance,
 cycle duration and contact/recovery phases. Play a full loop against ground
 markers and inspect contact, passing and recovery frames at the intended size.

package/docs/agent-setup.md

@@ -1,5 +1,8 @@
 # Connect an agent
 
+New to Rtistree? Read [Core concepts: an agent is the interface](core-concepts.md)
+for how you, your agent and the engine work together.
+
 Rtistree provides a CLI, an MCP server and a TypeScript SDK. The engine renders locally;
 your host supplies the model and any vision capability.
 
@@ -41,9 +44,11 @@ Example task:
 > visual findings separately. Revise failed criteria before exporting.
 
 The server exposes inspection, rendering, crop inspection, typed edits, undo/redo, verification,
-critiques, program execution, pipelines and staged production. Rendering tools return PNG image
-content; use a vision-capable agent to judge appearance. Structured inspection alone cannot
-establish that an image looks good.
+critiques, program execution, pipelines, sprite-atlas export and staged production. The
+`exportSprites` tool writes an engine-neutral PNG atlas plus JSON frame/animation metadata for
+a scene with a `sprites` manifest. Rendering tools return PNG image content; use a
+vision-capable agent to judge appearance. Structured inspection alone cannot establish that an
+image looks good.
 
 ## CLI agents
 

package/docs/atelier.md

@@ -17,6 +17,13 @@ CLI actions also have SDK equivalents (`buildPipeline`, `production`) and MCP to
 
 ## Editable dependency graph
 
+These examples assume an installed package and an existing scene project; see
+[the first painting](studio.md#first-painting). Save the graph as `pipeline.json`,
+create `programs/ground.js` inside the artwork project, and make that program return
+a Canvas of the requested dimensions. For a minimal ground program, use
+`return art.raster(() => [38, 62, 69, 255]);`. Source paths inside the graph resolve
+from the artwork project root; the CLI request filename resolves from your shell directory.
+
 ```json
 {
   "version": 1,
@@ -46,9 +53,13 @@ CLI actions also have SDK equivalents (`buildPipeline`, `production`) and MCP to
 
 `rtistree pipeline my-project pipeline.json` reports `built` or `cached` for each node. An input can instead use `{ "asset": "registered-asset-id" }`. Source and inline code are mutually exclusive. Only subscribed shared parameters enter a node's key. Per-node parameters override nothing implicitly: an explicit binding takes precedence over a parameter of the same name. A changed node whose PNG is identical need not rebuild its dependants. Node array order defines auto-created layer order; dependency order defines execution order. Existing layer geometry is preserved. Changing output resolution changes cache keys. Removing a node does not remove previously authored layers or assets; use normal scene commands for removal.
 
-All node artifacts are baked before one scene transaction. A failed build can leave unused immutable files in the cache, but never a partially updated scene. Identical builds add no history. Use `expected_hash` with the SDK/MCP to reject a scene changed since inspection.
+All node artifacts are baked before one scene transaction. The CLI takes the graph
+as the request file directly. To pass a previously inspected `expected_hash`, use
+the SDK third argument or MCP’s separate `expected_hash` field. A failed build can leave unused immutable files in the cache, but never a partially updated scene. Identical builds add no history. Use `expected_hash` with the SDK/MCP to reject a scene changed since inspection.
 
 The exact executed graph, including inline source, is stored under `scene.metadata.pipeline_<id>`. After restoring a candidate, use that graph to resume its settings; a working `pipeline.json` file is deliberately not overwritten by selection. Portable export includes the selected graph and registered input assets, so it can rebuild without the original source files.
+It does not copy production sessions, rejected candidates, reviews or edit history; retain
+the original project if you need those records.
 
 ## Production requests
 

package/docs/cli-reference.md

@@ -2,7 +2,7 @@
 
 Installing Rtistree exposes `rtistree` and the compatibility alias `graphics`. In a local npm project, use `npx rtistree`.
 Run `rtistree --help` for the complete installed-version reference. Structured results go to
-stdout as JSON; errors go to stderr. Verification failure exits 2; other errors exit 1.
+stdout as JSON; errors go to stderr. Failed verification/preflight and non-identical recipe replay exit 2; input/runtime errors exit 1.
 
 ## Create a starter
 
@@ -14,33 +14,41 @@ npm run render
 ```
 
 The destination must be a new directory. The starter includes a scene, sample patch, SDK example
-and npm render scripts. No packages are installed and no code is executed by `init` itself.
+and npm render scripts. `init` writes starter files without installing dependencies or executing painting programs.
 
 ## Inspect and edit
 
 ```sh
-rtistree inspect scene.json
-rtistree inspect scene.json --layer title
-rtistree inspect-region scene.json 0 0 100 100
-rtistree render scene.json -o image.png
-rtistree render-region scene.json 0 0 100 100 -o crop.png
-rtistree apply scene.json patch.json
-rtistree undo scene.json
-rtistree redo scene.json
-rtistree history scene.json
+npx rtistree inspect scene.json
+npx rtistree inspect scene.json --layer title
+npx rtistree inspect-region scene.json 0 0 100 100
+npx rtistree render scene.json -o image.png
+npx rtistree render-region scene.json 0 0 100 100 -o crop.png
+npx rtistree sprites scene.json -o output/sprites.png --manifest output/sprites.json
+npx rtistree apply scene.json patch.json
+npx rtistree undo scene.json
+npx rtistree redo scene.json
+npx rtistree history scene.json
 ```
 
 Coordinates are `x y width height` in canvas pixels. A patch contains a reason and a typed
 commands array. Supply the current `expected_hash` when coordinating concurrent edits.
 See [scene format](scene-format.md) for command shapes and coordinate rules.
 
+`sprites` reads a scene or configured project with a sprite manifest and writes a
+deterministically packed atlas plus frame/animation metadata. The atlas output
+must end in `.png`; the optional `--manifest` path must end in `.json`. Pixel-art
+projects can opt into integer, palette and nearest-neighbour guardrails. Use
+`npx rtistree sprites --help` for the exact options supported by the installed
+version.
+
 ## Verify, review and export
 
 ```sh
-rtistree verify scene.json -o report.json --heatmap heatmap.png
-rtistree critique scene.json critique.json
-rtistree export scene.json -o portable/scene.json
-rtistree export scene.json --format png -o image.png
+npx rtistree verify scene.json -o report.json --heatmap heatmap.png
+npx rtistree critique scene.json critique.json
+npx rtistree export scene.json -o portable/scene.json
+npx rtistree export scene.json --format png -o image.png
 ```
 
 Verification measures configured technical constraints. Critiques are authored after inspecting
@@ -50,12 +58,12 @@ described in [print production](production.md).
 ## Studio and production
 
 ```sh
-rtistree art-guide
-rtistree studio-help
-rtistree program scene.json program.json
-rtistree program-replay scene.json asset-id
-rtistree pipeline scene.json pipeline.json
-rtistree production scene.json request.json
+npx rtistree art-guide
+npx rtistree studio-help
+npx rtistree program scene.json program.json
+npx rtistree program-replay scene.json asset-id
+npx rtistree pipeline scene.json pipeline.json
+npx rtistree production scene.json request.json
 ```
 
 Read [studio](studio.md) for program requests and [staged production](atelier.md) for plans,
@@ -64,10 +72,53 @@ candidate captures, reviews and selection. Program execution is for trusted code
 ## Project creation and integration
 
 ```sh
-rtistree project new artwork --size A3 --orientation landscape --ppi 300 --bleed 3mm
-rtistree schema --kind scene
-rtistree schema --kind command
-rtistree serve /absolute/path/to/scene.json
+npx rtistree project new artwork --size A3 --orientation landscape --ppi 300 --bleed 3mm
+npx rtistree schema --kind scene
+npx rtistree schema --kind command
+npx rtistree serve /absolute/path/to/scene.json
 ```
 
 The MCP server uses stdio. See [agent setup](agent-setup.md).
+
+## Additional commands
+
+| Command                                                     | Purpose                                                                             |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `npx rtistree rebase scene.json`                            | Merge manual source changes into journaled state; conflicts fail without committing |
+| `npx rtistree compact scene.json`                           | Compress history while retaining undo and redo                                      |
+| `npx rtistree raster-read scene.json read.json`             | Write an exact crop plus evidence and return an asset descriptor                    |
+| `npx rtistree raster-write scene.json write.json`           | Commit an exact-size PNG patch with a required current hash                         |
+| `npx rtistree sprites scene.json -o output/sprites.png`     | Pack declared sprite frames into an atlas and write animation metadata              |
+| `npx rtistree import-svg drawing.svg -o drawing.scene.json` | Import the supported static SVG subset                                              |
+| `npx rtistree preflight artwork --preset screen`            | Check physical document/export settings and save a report                           |
+| `npx rtistree proof artwork --preset print -o proof.png`    | Make a CMYK round-trip proof; requires a configured ICC profile                     |
+| `npx rtistree benchmark scene.json brief.json before`       | Capture a benchmark checkpoint after recording a current critique                   |
+| `npx rtistree benchmark scene.json brief.json finish`       | Finish after at least two inspected checkpoints                                     |
+
+Dense request shapes are in [studio](studio.md). Source rebasing, critiques and benchmark
+requirements are in [editing workflows](evolution.md). Names such as `patch.json`, `read.json`
+and `critique.json` are request files you author, not files created by `init`.
+
+## Options, paths and output
+
+- `--output` / `-o` chooses an artifact path. Explicit paths and request filenames resolve
+  from the shell's working directory. Asset/program paths inside requests resolve from the
+  artwork project root. Without `-o`, configured projects use `output_dir`; bare scene files
+  use a `renders/` directory alongside the scene.
+- `render --quality draft|preview|final` controls PNG rendering. Draft halves dimensions
+  after rendering; preview and final share the full-quality path. `--layer ID` renders an
+  isolated layer on a full-size transparent canvas. `render-region` requires an integer crop
+  entirely inside the canvas; default/final quality is an exact full-render crop.
+- `inspect-region` also writes `inspection.png` and its evidence unless you supply `-o`.
+- Artwork `export` and full `render` accept `--format`, `--preset` and `--ppi`. Known output
+  extensions are inferred. Print exports additionally accept `--profile` (project-relative
+  ICC file; implies CMYK), `--colour-space srgb|cmyk` and `--crop-marks`. Use `export` for
+  print options; a plain PNG `render` with only `--profile` does not select the export path.
+- `schema --kind scene` describes a resolved scene. Source scenes with includes/components
+  use the packaged `authoring.schema.json`; a patch uses `patch.schema.json`.
+
+JSON is the structured result format; help is plain text and `serve` writes MCP protocol
+messages. The npm/npx launcher can print its own installation notices. `verify` and
+`preflight` failures, and non-identical `program-replay` results, exit 2. Input/runtime/export
+errors exit 1. Warnings alone do not make preflight fail. Program or pipeline build success
+only means execution succeeded; it does not establish visual quality.

package/docs/core-concepts.md

@@ -0,0 +1,95 @@
+# Core concepts: an agent is the interface
+
+Rtistree is designed to be operated through an agent. You describe what you want,
+set constraints and give feedback. The agent uses Rtistree to construct artwork,
+inspect renders and make focused revisions.
+
+The CLI, MCP server and TypeScript SDK are the agent's controls. They are also
+available for direct human use, but learning every command is not the intended
+starting point for someone who wants to make art.
+
+## Three roles
+
+| Role      | Responsibility                                                                                     |
+| --------- | -------------------------------------------------------------------------------------------------- |
+| You       | Set the brief, references, constraints and intended use; judge whether the result meets your needs |
+| The agent | Plan the work, call tools, inspect images, identify defects and revise the artwork                 |
+| Rtistree  | Store the editable scene, render it, apply typed edits, track history and export files             |
+
+Rtistree does not contain a model. Your agent host supplies the model, its context,
+image-viewing capability and tool access. An agent that cannot inspect images can
+still operate the tools, but cannot credibly judge their visual quality.
+
+You can connect an MCP-capable host, give an agent access to the CLI, or integrate
+the SDK into your own application. [Agent setup](agent-setup.md) explains each path.
+The host decides which tools require confirmation and what files the agent can access.
+
+## A conversation becomes an editable scene
+
+A useful starting brief might be:
+
+> Create a square event poster with a bold title, a quiet landscape and room for
+> a date. Keep the title and illustration independently editable. Show me a
+> composition before adding detail.
+
+The agent creates a scene with named layers rather than treating the final PNG as
+its only state. Text, geometry, image assets, masks and adjustments can retain
+separate identities. For painted detail, trusted JavaScript programs can produce
+baked raster assets with saved source, parameters and seeds.
+
+After inspecting the render, you might say:
+
+> The title works. Reduce the contrast behind it and move the sun farther right.
+
+The agent can inspect the relevant layers, change those parts and render again.
+It should preserve the parts you approved and check that the requested revision
+actually helps. Scoped raster edits have an enforced pixel-locality check;
+arbitrary structural edits do not automatically promise that every other pixel
+will remain unchanged.
+
+A painted image is only as editable as its construction. If an agent bakes every
+part into one asset, Rtistree cannot recover meaningful objects from those pixels.
+Ask for independent layers or program parameters for the parts you expect to revise.
+
+## The working loop
+
+1. **Direct:** establish the brief, references, intended size and acceptance criteria.
+2. **Construct:** make a representative composition or asset with useful editable structure.
+3. **Inspect:** open the actual render, including silhouettes, crops or animation frames as relevant.
+4. **Refine:** identify a specific defect, make a focused change and compare the result.
+5. **Deliver:** export the accepted state and keep the source needed for future edits.
+
+This loop is deliberate. A successful command, valid file or reproducible image
+is not proof that the artwork is good. The agent brings drawing and observation
+skills; Rtistree provides tools and records. A stronger agent may use the same
+toolkit better, but the toolkit does not guarantee artistic success.
+
+## Guidance travels with the tool
+
+The package includes art-direction guidance based on recorded trials: connected
+construction, coherent prop perspective, ground contact, representative samples,
+and separate technical, functional and visual assessment.
+
+- MCP supplies compact instructions during connection and exposes the full guide
+  through `studioHelp` and the `rtistree://guides/art-direction` resource.
+- CLI agents can read it with `rtistree art-guide`.
+- SDK hosts can provide `rtistreeAgentInstructions` and `artDirectionGuide` to their agent.
+
+Availability is not automatic compliance: some hosts do not pass server instructions
+to their model. Ask the agent to read the guide before authoring. The
+[art-direction workflow](agent-art-workflow.md) explains the process and optional
+production gates in detail.
+
+## Local work and explicit execution
+
+Ordinary scene loading and rendering use local assets and do not execute painting
+recipes. Program execution, pipeline builds and recipe replay are explicit actions
+for trusted code; the JavaScript VM is not a security sandbox. The agent host's
+model calls may use a remote service even though Rtistree renders locally.
+
+Edits are journaled and can be undone. Portable export saves the current artwork,
+assets and recipes as a new baseline; it does not copy the complete edit history
+or production reviews. Keep the original project when those records matter.
+
+Start by [connecting your agent](agent-setup.md). To understand the mechanics
+first, [make your first image](getting-started.md) with the small CLI walkthrough.

package/docs/decisions/004-print-production-and-projects.md

@@ -16,4 +16,4 @@ Hybrid PDF preserves supported text, vectors, gradients and isolation-free group
 
 The print trial revealed two defects that were fixed during implementation: metadata configuration could overwrite the requested CMYK conversion, and mask inversion after erosion expanded the selected foreground instead of shrinking it. Actual-file tests and visual proof inspection cover these cases. The original engine regression suite remains in place, alongside production and editing tests.
 
-See [the production guide](../production.md) for capabilities and operational limits, [the A3 evidence](../previews/a3-production.json), and [the generated-asset print trial](../../examples/print-trial/README.md).
+See [the production guide](../production.md) for capabilities and operational limits, [the A3 evidence](../previews/a3-production.json), and [the generated-asset print trial](https://github.com/Coly010/rtistree/blob/main/examples/print-trial/README.md).

package/docs/decisions/005-programmable-digital-art.md

@@ -12,4 +12,4 @@ Workers provide cancellation and V8 heap limits; helper allocations and output d
 
 Dense region editing uses existing promoted raster regions, extended with explicit `replace` and `over` semantics. Exact-size PNGs carry dense data instead of JSON pixel arrays. Transactions check stale scene hashes and edit locality. Attached patches follow object transforms. The trial found a near-zero pressure gradient failure; a minimum subpixel dab radius fixes it. Region testing also corrected final print-region copy bounds to use the transformed frame.
 
-The artistic evaluation is kept separate from mechanical verification. The wheel trial reproduces its pixels without external image inputs, but still reads as a synthetic illustration. Successful software tests and deterministic replay are not evidence of human-level artistic skill or photographic realism. See [the studio guide](../studio.md) and [trial](../../examples/manual-wheel-trial/README.md).
+The artistic evaluation is kept separate from mechanical verification. The wheel trial reproduces its pixels without external image inputs, but still reads as a synthetic illustration. Successful software tests and deterministic replay are not evidence of human-level artistic skill or photographic realism. See [the studio guide](../studio.md) and [trial](https://github.com/Coly010/rtistree/blob/main/examples/manual-wheel-trial/README.md).