rtistree 0.5.0

package/docs/decisions/002-composable-scenes-and-history.md

@@ -0,0 +1,28 @@
+# ADR 002: Composable scene sources with a transactional resolved state
+
+Status: accepted for the MVP. Later extensions and superseded limitations are documented in [ADR 003](003-editing-refinement-and-agent-validation.md).
+
+## Context
+
+An agent-friendly scene should not require one enormous file. Background, copy, products, textures, and assets need independent authoring and inspection. At the same time, a render must consume one unambiguous state, and an edit batch must either commit completely or leave that state unchanged.
+
+## Decision
+
+A root YAML/JSON scene can include fragments containing assets, layers, and more includes. Include paths and asset paths are relative to the declaring file. Includes are expanded depth-first in declaration order; local layers follow included layers. IDs share one namespace, and duplicate IDs, missing references, cycles and path escapes are errors. Fragments cannot replace the canvas or verification rules. Those belong to the root manifest.
+
+The loader normalizes this graph into the canonical scene schema. A single scene file remains supported. Modularity is an authoring concern; the renderer sees a complete, validated scene tree and never performs file inclusion itself.
+
+Persist agent edits in a hash-chained append-only journal alongside the authoring sources. The sources remain the baseline; replaying the journal yields the working state. Each transaction contains a resolved snapshot, command list, reason, source and state hashes, asset hashes, and locality measurements. Undo and redo are also journal entries. Writers take an exclusive project lock, validate the candidate scene, render it, check locality for scoped edits, append the record and synchronize it to disk.
+
+Exporting produces a new flat baseline scene with content-addressed raster assets. This is also the supported way to start a new authoring/history cycle. Export does not rewrite the original fragments. A caller may split an exported baseline into fragments before making new agent edits.
+
+## Consequences
+
+- Projects can be organized by semantic responsibility without coupling the renderer to file layout.
+- An edit never partly rewrites several fragments. Rejected patches have no persisted effect.
+- History uses complete state snapshots for transparent recovery and deterministic undo; storage is linear in scene size times edit count. Delta compression and content-addressed state snapshots are future optimizations.
+- Scene-source changes during an active history are rejected, rather than silently rebased. Restore original sources and export before restructuring an edited project.
+- Assets stay external. Export pins hashes, and history records and checks exact asset bytes.
+- Include instances are not templates: including the same IDs twice is an error. Parameterized components and namespaced instances are future capabilities.
+- Operation/mask/tile bounds use global canvas coordinates. Geometric layer bounds use parent coordinates. This makes raster scope contracts easy to measure, but a later semantic move does not automatically move previous world-space paint operations.
+- The final-composite locality guard may reject a child edit beneath a blurred ancestor or a mask dependency. Editing the enclosing composited group is the appropriate alternative. The engine does not silently broaden scope.

package/docs/decisions/003-editing-refinement-and-agent-validation.md

@@ -0,0 +1,45 @@
+# ADR 003: Attached edits, adaptive patches, measured verification, and source rebasing
+
+Status: accepted. Extends ADR 001 and supersedes the MVP limitations in ADR 002.
+
+## Delivery order
+
+The user requested: complete the editing API; attach paint to objects; add adaptive refinement and faster rendering; improve verification; improve authoring; then run unscripted agent trials. Implementation and validation followed that order.
+
+## Editing and coordinates
+
+Commands now cover registering/removing assets and fonts; shape, generator, geometry, transform, mask, layout, source, visibility, role and stacking changes; verification rules; and update/removal of individual effects, operations and tiles. Partial style changes preserve unspecified fields. The first interactive trial uncovered a Zod-default regression here; a focused regression test now covers it.
+
+Raster operations, geometric masks, palette tiles and promoted regions accept `space: canvas|layer`. Omission preserves v1 canvas behavior. Commands capture a `reference_size` for layer-relative data. The renderer combines the object's current world transform with its size relative to that reference. Movement, rotation and resizing therefore move its paint. Authors writing files directly should supply `reference_size` when paint must scale with later source edits.
+
+The locality contract is the integer enclosing rectangle of the transformed scope. The painter additionally clips to the transformed footprint. Replacing/removing operations measures the union of the old and new scopes. Parent effects and mask dependencies can still cause scope rejection; edits never silently broaden the permitted area.
+
+## Adaptive detail and rendering
+
+A layer can contain independently addressable promoted regions. Each has an ID, bounds, scale from 1–4, optional external raster source, and a list of patch-local operations. Promotion without a source or edits changes no pixels. Detailed patches are derived from the current semantic surface, supersampled locally, edited, and composited back. Demotion restores the underlying semantic result. Upsampling an imported raster does not invent missing source detail; new paint can use the finer sampling grid.
+
+A bounded LRU cache stores immutable layer surfaces and text diagnostics. Keys cover resolved geometry, descendant/mask dependencies, source content, assets, fonts, and omitted-layer options. Edits invalidate affected surfaces while unchanged layers are reused. This is incremental layer rasterization; a general dirty-tile compositor is still future work.
+
+A viewport fast path allocates region-sized surfaces for simple pointwise scenes. Curves, transforms, raster assets, context filters, promoted patches and other antialias-sensitive cases use full-canvas rendering and an exact crop. Testing demonstrated that clipping a rotated rectangle or ellipse on a smaller Skia device can change boundary pixels, so those cases deliberately retain the original device. `regionMode: full` and `cache: false` expose reference paths for equivalence tests. Draft remains a downsampled render.
+
+## Verification and critique
+
+`pixel-contrast` compares the actual composite to a counterfactual render with the target omitted, sampling solid glyph/shape interiors. `visible-area` measures how much of the target contributes to the final image. These account for opacity and overlying content; the existing declared-colour rule remains separately available. They are engineering measurements with documented sampling limits, not an accessibility certification or an aesthetic score.
+
+Visual critique is an explicit external input from a vision-capable agent or human, bound to both scene and PNG hashes. It contains a reviewer, summary, severity-tagged findings and score. A typed callback integrates a critic into the bounded edit loop; MCP/CLI tools allow an interactive agent to inspect and record its own critique. Unresolved medium/high findings prevent a visual pass. The renderer has no model-provider dependency or credentials. A particular model service is not silently installed or called.
+
+## Authoring and history
+
+Components are file-level parameterized templates. Expansion namespaces instance child IDs and internal mask references, validates parameters, and rejects recursion. The canonical document remains a resolved layer tree. Rebase can propagate nonconflicting template/source edits into working state; instance editing does not write a template back automatically.
+
+Custom font files are project-local, hashed, registered under content-based aliases and copied during export. Layout adds aspect ratios, proportional growth and main-axis justification.
+
+New history records retain the authoring baseline. `rebase` performs a three-way merge of that baseline, the agent's working scene and current authored sources. ID-bearing layer arrays merge by identity. Conflicting paths are errors, not guesses; successful rebases are audited and undoable. Older v0.1 histories without a retained baseline require restoring/exporting their original source before using this workflow.
+
+`compact` compresses the full journal into an immutable gzip archive and starts an appendable active log. A content-hashed pointer and duplicate-record checks make the pointer/log transition recoverable after a crash. Full undo/redo is retained. Compression reduces disk use but does not yet eliminate full replay in memory.
+
+## Agent trials and limits of evidence
+
+Three interactive trials were completed after the engineering work: a reading-club poster using an asset, a marsh illustration from primitives, and local refinement of a supplied rough pear raster. The assistant inspected initial PNGs, recorded findings, chose corrections after inspection, and inspected final PNGs. The benchmark driver contains no corrective patches. Saved audits capture the actual edits, including the caption bug and subsequent repair.
+
+These are same-agent authoring and critique, not blinded or independent human evaluations. The briefs were authored in this task; they are not a held-out test set. Token usage is recorded as unavailable because the host did not expose it. Mechanical results include pixel locality, cold/cache equality and self-contained export equality. This is evidence that the workflow can be exercised end to end, not evidence of general artistic superiority.

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

@@ -0,0 +1,19 @@
+# ADR 004: Physical documents, colour-managed exports and sequential print rendering
+
+Status: accepted for v0.3. Extends the existing TS/CPU-Skia architecture.
+
+The user requested JPEG, TIFF and physically accurate CMYK PDF output, coherent project creation, practical editing features and a harder generated-asset trial. These are implemented as an export/document layer over the existing deterministic scene engine.
+
+Sharp 0.35.4 / its pinned libvips build handles raster encoding and ICC conversion. PDFKit 0.20.2 produces vector paths, font subsets, gradients and PDF page boxes; pdf-lib 1.17.1 independently reads back exported structures. Fontkit checks actual glyph coverage. Fast XML Parser supports a closed static SVG importer; native Skia PathOps handles path booleans. Versions are pinned in the lockfile.
+
+Physical dimensions remain separate from design/raster pixels. An outer transform scales scene geometry for print while preserving attached coordinates and source pixel grids. Print output is bounded by edge, megapixel and surface budgets. Sequential uncached composition releases surfaces as soon as compositing no longer needs them, retaining semantic mask dependencies. This was selected over introducing a general tile compositor whose clipping/filter equivalence would need a separate validation effort.
+
+Colour conversion occurs at input normalisation and export; the working engine remains 8-bit sRGB. The pinned Sharp source explicitly uses perceptual rendering intent, so other intents are rejected instead of accepted as ineffective settings. CMYK requires an explicit project profile. Assigning an output intent is distinguished from converting raster/vector values. Profiles are hashed, embedded and read back; the demo profile is not a printer recommendation.
+
+Hybrid PDF preserves supported text, vectors, gradients and isolation-free groups. Context-sensitive layers fall back to rasters. Gradient interpolation occurs in the output colour space. Ordinary PDF 1.7 is the delivered format; PDF/X certification, spot colours, overprint and higher-precision working pixels are deliberately not claimed. CMYK soft proofs are ICC round trips and do not simulate a specific paper white or monitor calibration.
+
+`rtistree.yaml` owns the scene entry point, output directory and presets. Source scenes remain independently usable. New projects include local schemas and fragments; portable project exports also copy pinned output profiles. Existing JSON scene export remains available explicitly as `--format project`. Mismatched output extensions are errors.
+
+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).

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

@@ -0,0 +1,15 @@
+# ADR 005: Programmable raster authoring with baked, replayable recipes
+
+Status: accepted for v0.4.
+
+The user wants an agent to work like a traditional digital artist, including creating detailed scenes without image-generation models. Additional declarative shapes alone do not provide a practical route to arbitrary textures and painted detail. We therefore add a programmable authoring boundary while retaining the deterministic scene engine.
+
+JavaScript is the authoring language because it can share the existing native Canvas ecosystem and typed SDK. No additional runtime dependency is needed. A synchronous program receives seeded field, brush, sampling, displacement and height-lighting helpers plus a native Canvas context. The agent can implement another algorithm directly when the provided vocabulary is insufficient. The API is available through CLI, SDK and MCP, including inline source and a machine-readable help tool for agents without filesystem access.
+
+Program execution is explicit and produces a baked asset. A recipe pins source text, parameters, seed, input snapshots and output hash. Playback never evaluates project code. This preserves portable scene rendering and the existing history model, and avoids making ordinary scene loading an implicit code-execution boundary. Recipes can be exported and explicitly replayed. A live procedural dependency graph is not introduced in this milestone.
+
+Workers provide cancellation and V8 heap limits; helper allocations and output dimensions are checked separately. The VM is not represented as a security sandbox, because native Canvas objects expose host methods and native allocation is outside V8 accounting. Only trusted code should be executed. A hardened plugin runtime or OS isolation would be a separate design.
+
+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).

package/docs/decisions/006-staged-2d-art-production.md

@@ -0,0 +1,13 @@
+# 006 — Staged 2D art production
+
+Accepted: 2026-09-09.
+
+Keep the CPU Skia/TypeScript engine and its native Canvas and pixel escape hatches. Do not introduce a 3D renderer or image-generation dependency. Build an agent-operated production workflow around the existing painter.
+
+A production plan defines a brief and ordered stages, each with visible acceptance criteria. Candidates freeze the scene, its build graph, the composite, thumbnail, optional detail crops and technical report. An observer supplies hash-bound brief-fidelity and artistic-quality ratings plus evidence for every stage criterion. Technical verification remains separate: an empty rule set is reported as such, and a successful render does not prove good art. Selection restores a candidate through an undoable scene transaction. Advancement requires the selected candidate to remain the current scene. Scores are stage-relative, subjective observations, not calibrated universal art metrics.
+
+Editable raster programs form an explicit DAG. Each node subscribes to named shared parameters and image dependencies. Build keys include exact source, parameters, dimensions, seed, frozen input hashes, runtime and technique version. Unchanged nodes reuse verified outputs; dependants rebuild when their input content changes. A failed node cannot partially update the scene. Rendering never executes code. Builds pin the actual executed source in scene metadata, so candidate selection and portable export retain editable recipes as well as baked pixels.
+
+Keep reusable methods at the technique level: bristle strokes, pressure, dry paint, glazing, scumbling, palette interpolation, atmospheric colour and weave. Subject anatomy and composition belong to authored artwork, not dragon-specific engine commands. Existing raw Canvas paths, arbitrary pixel fields, masks and warps remain available.
+
+Tradeoffs: this is an agent-operated atelier, not a prompt-to-art generator. The caller must plan, draw, inspect and judge. Local worker execution remains trusted-code execution, not a security sandbox. Bristle strokes approximate digital paint; they do not simulate pigment chemistry or wet paint. Cached outputs and candidate journals have no automatic garbage collector yet. Session review state stays local; portable scene export preserves the selected art and inline build graph, not all rejected candidates and reviews.

package/docs/decisions/007-foundation-first-art-direction.md

@@ -0,0 +1,13 @@
+# 007 — Foundation-first art direction and honest failure
+
+Accepted: 2026-09-09.
+
+The previous dragon trial demonstrated prompt compliance and reproducibility but failed the user's artistic standard. Its self-assigned passing quality scores were not credible evidence of good art. More texture did not correct anatomy, gesture or value construction.
+
+Codify the production process in a discoverable machine-readable guide (`artDirectionGuide`, CLI/MCP `studioHelp`) and in `docs/agent-art-workflow.md`. Add enforceable reference-log, alternative-count and reviewer requirements to existing stage plans. Preserve review history. Blocking defects cannot be averaged away by high scores. Revisions must name a parent, a correction hypothesis and a visual comparison.
+
+Add a general named 2D construction graph for points, anchored offsets and curve handles. This supports structural edits across connected contours without hard-coding dragon anatomy into the engine. Retain Canvas and pixel escape hatches. No 3D renderer or image-generation dependency is introduced.
+
+The tool enforces declared workflow facts, not artistic truth. It cannot authenticate reviewer identity, verify that references were studied, distinguish meaningful alternatives from trivial pixel changes, or guarantee artistic excellence. Agent instructions must explicitly acknowledge these limits and prohibit self-declaring human approval.
+
+The follow-up dragon remains a grayscale work in progress, with failed construction/quality criteria and a human checkpoint still pending. The useful result is a stronger, inspectable correction loop; weak artwork must remain reported as weak artwork.

package/docs/decisions/008-agent-onboarding-and-trial-lessons.md

@@ -0,0 +1,48 @@
+# Agent onboarding and procedural asset lessons
+
+## Context
+
+The foundation-first guide was available through `studioHelp` and the SDK, but
+new agents had to discover and request it. The Verdigris Watch trial also exposed
+gaps in the guide: technically valid assets could have reversed walking motion,
+contradictory prop perspective, excessive joint bend and crossed limb chains.
+These failures needed subject-specific observation, not additional surface detail.
+
+## Decision
+
+Keep compact instructions, structured guidance, calibration cases and a starter
+production plan in `src/art-direction.ts`. Ship these through the existing npm
+`dist` and `docs` entries without requiring source examples or a provider-specific
+skill installation.
+
+- MCP includes the compact rules in initialization instructions, a discoverable
+  JSON resource and pointers in authoring tool descriptions. `studioHelp` returns
+  the same complete guide.
+- CLI exposes `art-guide` without requiring a project, and advertises it in help.
+- SDK exports the guide and compact instructions. The host supplies them to its
+  agent; importing a graphics library does not itself change an LLM's context.
+- A starter plan uses existing alternative, reference, criterion and review gates.
+  It does not implicitly require human approval for every task.
+
+The guide distinguishes technical correctness, functional behaviour and visual
+acceptance. It requires representative samples, actual image/loop inspection,
+shared construction, parent-linked revisions and faithful retention of feedback.
+General lessons are embedded; a particular knight pose or colour palette is not
+prescribed for unrelated tasks.
+
+## Limits
+
+Instructions are context, not model training or enforcement. Clients can omit
+them and agents can ignore them. The existing production API enforces declared
+review gates, hashes and blocking issues only for callers using that workflow.
+Low-level rendering remains available. Neither transport nor workflow can prove
+that a reviewer looked at an image or judged it well. Motion formulas are examples
+for ordinary forward walking, not universal criteria for all animation.
+
+## Verification
+
+Interface tests connect a fresh MCP client, read initialization instructions,
+discover and read the resource, and compare it with `studioHelp`, CLI output and
+the SDK guide. The starter plan is exercised through the production API and cannot
+select an unreviewed candidate. A package check verifies that compiled guidance
+and documentation are present in the distributable.

package/docs/engine-overview.md

@@ -0,0 +1,174 @@
+# Rtistree
+
+A deterministic raster graphics engine that agents can inspect, edit, verify, and replay. A persistent scene is the source of truth; PNG, JPEG, TIFF, PDF and SVG are outputs.
+
+Version 0.4 adds a programmable digital-art studio: seeded raster programs, pressure brushes, texture fields, warps, displacement, height-field lighting and dense regional edits. Programs bake to pinned assets with portable, replayable recipes; normal rendering never executes code. See the [studio guide](studio.md), [decision](decisions/005-programmable-digital-art.md) and [wheel trial made without image generation](../examples/manual-wheel-trial/README.md).
+
+TypeScript provides the scene schema, transactions, CLI, and MCP tool server. The next-stage implementation includes attached painting, adaptive patches, incremental layer rendering, visual critique and source rebasing. **Native CPU Skia** performs rendering through `@napi-rs/canvas`. No browser, WebGL, GPU, model API key, or external service is required.
+
+![Poster rendered by Rtistree](previews/poster.png)
+
+## Print production and new projects
+
+Version 0.3 adds physical documents, ICC-managed CMYK exports, embedded PDF fonts/vector geometry, project creation, source crops/perspective, mask algebra, tonal adjustments, clone/heal, path booleans and richer typography. See the [production guide](production.md), [recorded decisions](decisions/004-print-production-and-projects.md) and [masked generated-asset print trial](../examples/print-trial/README.md).
+
+```sh
+graphics project new artwork --size A3 --orientation landscape --ppi 300 --bleed 3mm
+graphics render artwork --preset screen
+# Configure the printer/paper ICC profile in rtistree.yaml before CMYK export.
+graphics preflight artwork --preset print
+graphics export artwork --preset print --format pdf
+```
+
+Print PDFs encode exact trim/bleed dimensions and are reopened for validation. PDF/X certification, spot colours and overprint are not claimed. The engine remains an 8-bit sRGB working renderer with explicit colour-managed output.
+
+## Run it
+
+Requires Node.js 22 or newer. Dependencies and bundled fonts are pinned in `package-lock.json`.
+
+```sh
+npm ci
+npm run build
+npm test
+npm run demo
+```
+
+The demo renders a poster, measures an underlit region, applies a local correction, and checks replay, undo, redo, and a self-contained export. It writes before/after images and evidence into `examples/poster/renders/`, plus a landscape into `examples/landscape/renders/`. Every demo run uses a fresh working project and leaves the example's authoring files untouched.
+
+The recorded poster benchmark changes **4,704 pixels inside a 56 × 84 region, zero pixels outside**, improves rule verification from fail to pass, and reproduces identical PNG bytes after reopen, undo/redo, and export. This establishes mechanical correctness, not a general measure of artistic quality. See [recorded evidence](previews/benchmark.json).
+
+Use the executable after building:
+
+```sh
+node dist/cli.js render examples/poster/scene.yaml -o /tmp/poster.png
+node dist/cli.js inspect examples/poster/scene.yaml
+node dist/cli.js inspect-region examples/poster/scene.yaml 755 610 56 84
+node dist/cli.js apply examples/poster/scene.yaml examples/poster/refine.json
+node dist/cli.js verify examples/poster/scene.yaml
+node dist/cli.js render examples/poster/scene.yaml -o /tmp/refined.png
+node dist/cli.js undo examples/poster/scene.yaml
+node dist/cli.js redo examples/poster/scene.yaml
+node dist/cli.js export examples/poster/scene.yaml -o /tmp/rtistree-export/scene.json
+```
+
+`npm run graphics -- …` runs the same CLI from source. Installing the package exposes the `graphics` executable. `graphics --help` lists commands. JSON goes to stdout; errors go to stderr. Verification failures exit with code 2, other failures with code 1.
+
+## Compose a project from files
+
+A manifest can reference as many independently authored fragments as needed:
+
+```yaml
+version: 1
+canvas:
+  width: 1024
+  height: 1024
+  background: '#102c31'
+include:
+  - layers/background.yaml
+  - layers/product.yaml
+  - layers/typography.yaml
+```
+
+Each fragment contains `layers`, optional `assets`, and optional nested `include` paths. Paths resolve relative to the declaring file and must stay inside the project. Layer and asset IDs share a project namespace. Included layers compose in declaration order, followed by local layers; sibling `z` values determine paint order. Groups preserve hierarchy.
+
+The [poster example](../examples/poster/scene.yaml) uses this format. [Scene format documentation](scene-format.md) describes coordinates, layout, operations, and validation.
+
+## Agent interface
+
+Art-direction guidance ships with the engine. MCP clients receive concise rules
+at connection time and can read the full versioned guide through `studioHelp` or
+the `rtistree://guides/art-direction` resource. CLI agents use `graphics art-guide`
+without opening a project. SDK hosts can include `rtistreeAgentInstructions` in
+their agent context and expose `artDirectionGuide`.
+
+The guide includes representative-sample workflows, connected figure construction,
+shared prop perspective, ground-contact animation checks, lessons from failed
+asset trials and a starter production plan using existing review gates. Technical,
+functional and visual acceptance are separate. This makes the knowledge available
+to new agents; it does not guarantee that every client presents it or every model
+follows it. See [the agent workflow](agent-art-workflow.md).
+
+Start the MCP server with a scene:
+
+```sh
+node dist/cli.js serve /absolute/path/to/scene.yaml
+```
+
+Configure an MCP client to launch `node`, with the absolute path to `dist/cli.js`, `serve`, and the absolute scene path as arguments. Transport is stdio; the server writes only protocol messages to stdout.
+
+Tools: `inspectScene`, `inspectLayer`, `inspectRegion`, `render`, `renderRegion`, `apply`, `undo`, `redo`, `verify`, `history`, `recordCritique`, `readCritique`, `rebase`, `compactHistory`, `exportArtwork`, `preflight`, `softProof`, `studioHelp`, `runProgram`, `replayProgram`, `readRasterRegion`, `writeRasterRegion`. Image tools return PNG image content so a vision-capable agent can inspect the result. `apply` advertises a typed command schema and requires an explanation. Supply the scene hash returned by inspection to reject stale edits.
+
+```json
+{
+  "reason": "Brighten the underlit detail without changing the surrounding composition",
+  "expected_hash": "sha256:…",
+  "commands": [
+    {
+      "type": "applyRasterOperation",
+      "target": "cover",
+      "operation": {
+        "type": "brightness",
+        "bounds": [755, 610, 56, 84],
+        "amount": 0.06
+      }
+    }
+  ]
+}
+```
+
+The SDK also exposes `Project`, `SkiaRenderer`, `parseScene`, layout and verification functions, and `runIterations(project, editingAgent, options)`. The injected agent receives the scene, PNG, and verifier report and returns a patch or `null`. Iteration budgets, stale-state checks, stall thresholds, and cancellation bound the loop. An optional typed `critic` callback adds visual feedback; `requireCritique: true` requires a current critique before passing, and unresolved medium/high findings prevent success. Model choice and vision critique stay outside the renderer; there is no built-in LLM or diffusion service.
+
+## Persistence and reproducibility
+
+Authoring fragments remain intact. Successful mutations append a transaction to `history/<scene-filename>.operations.jsonl`. Each record stores its commands, reason, full resolved state, previous-record hash, input/output scene hashes, asset hashes, and measured locality. Reads replay this journal over the original scene. Undo/redo append records rather than deleting history. Full state snapshots favor correctness and recovery over storage efficiency in this MVP.
+
+A failed batch leaves the scene unchanged. A project lock prevents concurrent writers; an expected scene hash handles stale agents. Incomplete or altered journal records are rejected. If a writer crashes, inspect the PID in the `.lock` file before removing the stale lock. After manual source edits, run `graphics rebase scene.yaml` to merge nonconflicting changes into the working state. Conflicts report exact paths without committing. `graphics compact scene.yaml` compresses history while retaining every undo/redo state. New histories retain their source baseline; legacy histories require restoring/exporting the original source before rebasing. Changed raster asset bytes are also rejected after history exists.
+
+Exports copy raster assets and custom fonts into content-addressed files and pin their hashes. Every PNG has a `.evidence.json` sidecar recording renderer/backend/runtime versions, scene hash, asset hashes, bundled font hashes, dimensions, quality, and PNG hash. Byte identity is tested on the same pinned runtime and platform. Cross-platform Skia byte identity is **not** promised.
+
+## Implemented scope
+
+- JSON/YAML scenes and recursive multi-file composition; strict validation and JSON Schema generation.
+- Groups, semantic roles, shapes and SVG-style paths, text wrapping, local PNG/JPEG/WebP assets, gradients, seeded noise, transforms, row/column layouts, anchors, percentages, opacity, and nine blend modes.
+- Rectangle, ellipse, polygon and semantic-alpha masks; feathering, layer blur, and adjustment layers.
+- Scoped fill, paint/erase strokes, blur, brightness, contrast, saturation, hue shifts, noise, colour replacement, direct pixels, and palette tiles. Binary rasters remain external assets.
+- Exact region crops, structural/color inspection, append-only transactions, undo/redo, self-contained export, CLI, and MCP.
+- Text overflow, declared contrast, safe-area, overlap, copy/role and region-luma rules, issue heatmaps, measured edit locality, and bounded agent iterations.
+
+The remaining extensions are automatic quadtree subdivision, a general dirty-tile compositor, advanced SVG import, mesh warp/smudge, general segmentation, provider-specific model integrations, learned asset generation, and animation. Draft still downsamples after rendering. Safe pointwise region scenes use smaller viewport surfaces; antialias-sensitive scenes fall back to a full composite and exact crop.
+
+## Next-stage examples and agent trials
+
+See [the new API and workflows](evolution.md) and [ADR 003](decisions/003-editing-refinement-and-agent-validation.md). New features include mutable effects/operations, object-relative paint, promoted patches at 1–4× resolution, layer caching, rendered contrast/visibility rules, hash-bound visual critiques, component instances, custom fonts, source rebasing and compressed history.
+
+Three interactive trials are recorded in [agent-trials/results.json](../examples/agent-trials/results.json), with before/after images, briefs, complete audit snapshots and portable final scenes. Corrections were selected after inspecting the images. The visual scores are same-agent judgments; these are not independent quality evaluations, and token usage was unavailable. All three final scenes passed their configured checks and reproduced after export. The pear trial preserved every checked nonfruit pixel.
+
+```sh
+node dist/cli.js render examples/agent-trials/reading-club/final/scene.json -o /tmp/reading-club.png
+node dist/cli.js render examples/agent-trials/pear/final/scene.json -o /tmp/pear.png
+npm run performance
+```
+
+The performance probe records cache counters and local timings in `docs/previews/performance.json`. Its 16-layer edit reuses 15 surfaces and rasterizes one, while matching an uncached render exactly.
+
+See [architecture decisions](decisions/001-runtime-and-renderer.md), [multi-file persistence decision](decisions/002-composable-scenes-and-history.md), and the original [architecture proposal](../agentic-raster-graphics-architecture.md).
+
+## Development
+
+```sh
+npm run check
+npm run format:check
+npm run schema
+```
+
+Subsystems are separate modules in `src/`: schema, loader, layout, assets, paint, renderer, commands, project transactions, verification, workflow, CLI and MCP. The `Renderer` interface makes backend replacement independent of scene authoring or agent logic. The original proposal's package boundaries are module boundaries until independent packaging has a concrete benefit.
+
+Bundled fonts are Inter and DM Serif Display from Fontsource, under their bundled SIL Open Font Licenses. They cover Latin text; custom project fonts can supply broader script coverage. Arbitrary system-font fallback remains disabled. Example artwork and book-cover raster are built from this engine's own primitives; regenerate the cover with `node --import tsx scripts/create-fixtures.ts`.
+
+## Staged 2D art production
+
+Dependency-aware painting pipelines, immutable candidate comparisons, hash-bound visual reviews and gated production stages are available through the CLI, SDK and MCP. Seeded oil/filbert/scumble/ink brushes complement native Canvas paths and raw pixels. See [the atelier workflow](atelier.md) and the hand-authored dragon trial in `examples/dragon-oil-trial`. No image-generation or 3D dependency is used.
+
+Read [Art direction for agents](agent-art-workflow.md) before making art. The foundation-first protocol, named 2D construction guides, explicit blocking issues and parent-linked revisions are also discoverable through `graphics studio-help`. The [grayscale dragon study](../examples/dragon-foundation/README.md) demonstrates the process and records its unresolved artistic failures.
+
+The [dragon head lighting experiment](../examples/dragon-head-study/README.md) uses the existing 2D tools for an original head, reflected green fire and two local revisions. It remains below the supplied artistic quality reference; code-only reproduction is verified separately from that verdict.

package/docs/evolution.md

@@ -0,0 +1,179 @@
+# Editing and agent workflows
+
+## Complete edits
+
+`apply` is still a transaction containing `reason`, optional `expected_hash` and `commands`. The generated [command schema](../schemas/command.schema.json) is authoritative.
+
+| Area             | Commands                                                                                                                   |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Inputs           | registerAsset, removeAsset, registerFont, removeFont                                                                       |
+| Composition      | addLayer, removeLayer, moveLayer, resizeLayer, setGeometry, setTransform, setZ, groupLayers, align, distribute             |
+| Appearance       | setShape, setGenerator, setSource, setMask, setLayout, setVisibility, setRole, setOpacity, setBlendMode, setText, setStyle |
+| Effects          | applyEffect, updateEffect, removeEffect                                                                                    |
+| Raster edits     | applyRasterOperation, updateRasterOperation, removeRasterOperation, replaceTile, removeTile                                |
+| Adaptive patches | promoteRegion, updateRegion, demoteRegion                                                                                  |
+| Verification     | setVerification                                                                                                            |
+
+Update/removal commands address zero-based indices reported by `inspectLayer`. Promoted regions use stable IDs. Asset/font registration uses project-relative file paths and is validated before commit. Null clears a mask, layout, transform or role. Partial style updates preserve all omitted properties.
+
+## Object-relative painting
+
+```json
+{
+  "reason": "Add a highlight that follows the product",
+  "commands": [
+    {
+      "type": "applyRasterOperation",
+      "target": "product",
+      "operation": {
+        "type": "paintStroke",
+        "space": "layer",
+        "bounds": [8, 8, 80, 100],
+        "path": [
+          [20, 24],
+          [35, 72]
+        ],
+        "radius": 8,
+        "hardness": 0.4,
+        "colour": "#ffe0ad",
+        "opacity": 0.5
+      }
+    }
+  ]
+}
+```
+
+The command captures the layer's current size in `reference_size`. Moving, scaling or rotating the object carries the paint with it. Direct scene authors can explicitly supply the reference dimensions. The default remains `space: canvas` for backward compatibility. Geometric masks can choose their own space. Semantic masks always sample the target's rendered alpha. Feather radii remain raster-pixel radii.
+
+## Adaptive regions
+
+```json
+{
+  "type": "promoteRegion",
+  "target": "product",
+  "region": {
+    "id": "surface-detail",
+    "space": "layer",
+    "bounds": [20, 30, 64, 64],
+    "scale": 4,
+    "operations": [
+      {
+        "type": "paintStroke",
+        "bounds": [0, 0, 64, 64],
+        "path": [
+          [4, 12],
+          [54, 42]
+        ],
+        "radius": 0.6,
+        "colour": "#f0d7a2"
+      }
+    ]
+  }
+}
+```
+
+The patch is 256 × 256 samples, but occupies 64 × 64 logical units. Its operations use patch-local coordinates. An optional `source` refers to a registered raster asset for explicit high-resolution content. Maximum patch size is 16 megapixels. Promotion with no source or operations changes nothing; demotion removes the patch and reveals the semantic result. Patches execute after ordinary operations and before the layer mask/opacity.
+
+`SkiaRenderer` caches immutable layer surfaces with a configurable byte budget. `clearCache()` discards them; `render(..., {cache:false})` gives a fresh reference. `statistics` records reuse, rasterization and memory. Region rendering uses a conservative viewport fast path and falls back for curves, transforms, assets and context filters; `regionMode: full` requests the reference path explicitly.
+
+## Pixel measurements and visual review
+
+```yaml
+verification:
+  rules:
+    - { type: pixel-contrast, target: headline, minimum: 4.5, percentile: 0.1 }
+    - { type: visible-area, target: product, minimum: 0.7 }
+```
+
+Use `Project.verify()` or `verifyRendered(scene, root, renderer)` for these rules. They render the final image with and without a target and sample the target's solid interiors. Occlusion, opacity and background effects therefore influence the measurements. `visible-area` measures detectable contribution, so a shape matching its background can have zero visible contribution even if it is geometrically present.
+
+For visual critique, render and inspect the PNG, then submit:
+
+```json
+{
+  "scene_hash": "sha256:...",
+  "png_hash": "sha256:...",
+  "reviewer": "Your vision agent",
+  "method": "vision-agent",
+  "summary": "The title is readable, but the product competes with the background.",
+  "score": 0.65,
+  "issues": [
+    {
+      "id": "separation",
+      "category": "composition",
+      "severity": "medium",
+      "target": "product",
+      "message": "The product silhouette is difficult to read.",
+      "suggestion": "Reduce background contrast behind it."
+    }
+  ]
+}
+```
+
+`graphics critique scene.yaml critique.json` or the MCP `recordCritique` tool stores it. Stale scene/PNG hashes are rejected. `readCritique` returns only the current critique. A callback of type `VisualCritic` can perform this review in `runIterations`; use `requireCritique: true` to require it for success. Visual and rule scores inform stall detection; unresolved medium/high visual findings prevent a pass. The adapter is provider-neutral and requires the caller to supply the actual vision-capable reviewer. No synthetic review is substituted when one is absent.
+
+## Components and fonts
+
+```yaml
+components:
+  badge:
+    parameters: { label: NEW, colour: '#d9aa72' }
+    layers:
+      - id: plate
+        type: vector
+        bounds: [0, 0, 120, 40]
+        shape: { type: rectangle, fill: '{{colour}}', radius: 4 }
+      - id: label
+        type: text
+        bounds: [8, 12, 104, 24]
+        content: '{{label}}'
+        style: { size: 12, align: center }
+layers:
+  - { use: badge, id: new-badge, bounds: [40, 40, 120, 40] }
+  - use: badge
+    id: sale-badge
+    bounds: [190, 40, 120, 40]
+    params: { label: SALE, colour: '#8db1a1' }
+```
+
+Components can live in included fragments. Instance children become `new-badge-plate`, `new-badge-label`, etc. Internal semantic mask targets are namespaced as well. Exact `{{parameter}}` substitutions retain value types; embedded substitutions allow scalars. Unknown parameters/components, duplicate IDs and recursive definitions fail validation. Instance placement accepts bounds, transform, role and z. The canonical scene is fully expanded and remains editable.
+
+```yaml
+fonts:
+  brand-display:
+    source: fonts/BrandDisplay.otf
+    hash: sha256:...
+```
+
+Choose `style.font: brand-display`. Fonts are registered under content-based aliases; changing a font file without updating its expected hash fails. History checks custom-font provenance, and exports copy font files. A custom file supplies one face; register a separate ID for another weight. Bundled names are reserved.
+
+Layout supports `aspect_ratio`, positive `grow` weights and `layout.justify: start|center|end|space-between`. Aspect ratio derives height when height is unspecified. Main-axis growth divides space remaining after fixed children and gaps. Existing absolute and percentage layouts continue to work.
+
+## Source changes and compressed history
+
+After changing a source fragment or a component definition:
+
+```sh
+graphics rebase scene.yaml
+```
+
+This merges disjoint source and agent changes using the retained authoring baseline. Conflicts report paths such as `/layers/headline/style/colour` and leave history untouched. Resolve the conflicting source fields and retry, or export the working scene into a new project. Rebase is audited and undoable. Histories created before baseline retention require their original source to be restored and exported first.
+
+```sh
+graphics compact scene.yaml
+```
+
+Compaction compresses full records into an immutable gzip archive with a content-hashed pointer, then starts an empty active log. Every undo/redo state remains accessible. It reduces storage; replay still reads all records. Missing/tampered archives fail closed. Do not delete archives referenced by the pointer.
+
+## Interactive benchmarks
+
+`BenchmarkSession` requires visual review before each checkpoint. Briefs describe the objective and optional allowed region; the driver does not contain a solution or choose an edit.
+
+```sh
+graphics benchmark scene.yaml brief.json before
+# Inspect, critique, apply edits, then inspect and critique again.
+graphics benchmark scene.yaml brief.json after
+graphics benchmark scene.yaml brief.json finish
+```
+
+The report records actual edit/command counts, rule results, visual scores, locality, uncached equality and self-contained export equality. Token counts are nullable rather than guessed. The [recorded trials](../examples/agent-trials/results.json) were performed interactively by the assistant in this task, with self-authored briefs and same-agent visual critique. They establish a usable end-to-end workflow; broader held-out evaluation and independent human review remain future evidence to collect.