rtistree 0.5.0

package/docs/getting-started.md

@@ -0,0 +1,107 @@
+# Make your first image
+
+Rtistree runs locally on Node.js 22 or newer. It needs no GPU or model API key.
+Start in an empty directory:
+
+```sh
+mkdir my-art
+cd my-art
+npm init -y
+npm install https://github.com/Coly010/rtistree/releases/download/v0.5.0/rtistree-0.5.0.tgz
+```
+
+This installs the checked release tarball from GitHub. npm registry publication is pending;
+the installed package and `graphics` executable are the same.
+
+## Render a scene
+
+Save this as `scene.json`:
+
+```json
+{
+  "version": 1,
+  "canvas": { "width": 640, "height": 400, "background": "#14251f" },
+  "layers": [
+    {
+      "id": "disc",
+      "type": "vector",
+      "bounds": [360, 60, 200, 200],
+      "shape": { "type": "ellipse", "fill": "#95b85c" }
+    },
+    {
+      "id": "title",
+      "type": "text",
+      "bounds": [48, 275, 544, 80],
+      "content": "Hello, Rtistree.",
+      "style": { "font": "inter", "size": 44, "weight": "bold", "colour": "#edf3e8" }
+    }
+  ]
+}
+```
+
+Or copy the same scene from `node_modules/rtistree/examples/hello/scene.json`.
+
+```sh
+npx graphics render scene.json -o hello.png
+npx graphics inspect scene.json
+```
+
+Open `hello.png`: a green disc and a title on a dark background. An adjacent evidence JSON
+records the scene hash, dimensions, fonts and renderer/runtime information.
+
+## Change one part
+
+Save this as `refine.json`:
+
+```json
+{
+  "reason": "Brighten the disc while preserving the title and background",
+  "commands": [
+    {
+      "type": "applyRasterOperation",
+      "target": "disc",
+      "operation": { "type": "brightness", "bounds": [360, 60, 200, 200], "amount": 0.15 }
+    }
+  ]
+}
+```
+
+```sh
+npx graphics apply scene.json refine.json
+npx graphics render scene.json -o brighter.png
+npx graphics undo scene.json
+npx graphics render scene.json -o restored.png
+```
+
+The disc becomes brighter. Undo restores the first image. Changes are journaled beside
+the scene; the original authoring file remains intact. On the same runtime and platform,
+`restored.png` should have the same bytes as `hello.png`.
+
+## Export a portable project
+
+```sh
+npx graphics export scene.json -o portable/scene.json
+npx graphics render portable/scene.json -o portable.png
+```
+
+The export includes referenced assets and fonts. Keep the exported directory together.
+
+## Use the SDK
+
+Save this as `render.mjs` beside `scene.json`:
+
+```js
+import { Project } from 'rtistree';
+import { writeFile } from 'node:fs/promises';
+
+const project = await Project.open('./scene.json');
+const result = await project.render();
+await writeFile('sdk-output.png', result.png);
+```
+
+Run `node render.mjs`. The SDK and CLI use the same engine.
+
+## Next steps
+
+Read [agent setup](agent-setup.md) to connect an MCP client, or the [scene format](scene-format.md)
+to add layers, text, assets and masks. For generated painting programs, use the [studio guide](studio.md).

package/docs/next-milestone.md

@@ -0,0 +1,61 @@
+# Proposed next milestone: print documents and coherent projects
+
+Status: delivered as the v0.3 milestone. This document retains the original proposal; see [the production guide](production.md) and [ADR 004](decisions/004-print-production-and-projects.md) for the implemented scope, selected backends and explicit limits.
+
+## Recommended order
+
+1. Introduce a project manifest, physical document model, and `graphics project new` together.
+2. Add JPEG, TIFF and physically sized PDF exports, with colour management and output validation.
+3. Preserve text and vector geometry in PDF; add practical compositing, selection and path tools.
+4. Run a more demanding generated-asset integration trial, including subject extraction or seamless extension, and print the result through the new export pipeline.
+
+The first generated-asset fitting trial is already recorded in [the example](../examples/generated-asset-trial/README.md). It uses one built-in image-generation call followed by deterministic Rtistree composition. It establishes asset ingestion, aspect-preserving placement, editable surrounding content and exact preservation of the placed photograph. It does not establish seamless photographic outpainting, segmentation or print readiness.
+
+## Project creation
+
+Proposed syntax (not current commands):
+
+```sh
+graphics project new alpine --size A3 --orientation landscape --ppi 300 --bleed 3mm --output-dir output
+graphics render alpine --preset screen
+graphics export alpine --preset print
+graphics preflight alpine --preset print
+```
+
+Create a project manifest describing the scene entry point, output directory and export presets; a scene referencing layer fragments; `assets/`, `fonts/`, `profiles/`, `layers/`, `history/`, and the designated output directory. Include a useful starter scene, schema references, a short project README, and ignore rules for generated artifacts. Relative paths resolve consistently from the project root. Creating a project must not overwrite an existing one. Existing scene-file commands remain usable.
+
+The output setting must apply to CLI renders, MCP renders, region inspections, exports and reports. The existing `export` command means a portable scene bundle; preserve that meaning explicitly, for example as `--format project`, while adding image/document export options.
+
+## Physical dimensions and print
+
+Keep physical trim dimensions authoritative, independently of pixel dimensions. Support mm, inches and points, bleed, safe margins and a raster sampling resolution. A3 landscape has a 420 by 297 mm trim size. Pixel dimensions necessarily round at a requested ppi; that rounding must not change the PDF's physical trim size. Keep PDF page dimensions at full precision and test read-back within a stated tolerance, such as 0.01 mm.
+
+Record the PDF MediaBox, TrimBox and BleedBox correctly; actually render artwork into the bleed. Offer crop marks as an explicit option outside trim. Report effective ppi of placed source images and whether the requested output resamples them. The file can encode exact size, but downstream printer/viewer scaling remains outside the engine's control.
+
+The current schema caps canvas dimensions at 4,096 pixels and the renderer holds full-canvas layer surfaces. A3 at 300 ppi is about 4,961 by 3,508 pixels before bleed. Print therefore needs a bounded-memory strategy and expanded dimension support, not merely a new encoder or a higher schema limit. Tiled rendering must retain context for filters and match reference crops.
+
+## Colour and formats
+
+CMYK requires a characterised output condition. Store the printer/paper ICC profile as a hashed project asset, distinguish profile assignment from conversion, record rendering intent, and embed the matching output profile. An RGB working preview with an explicit conversion at export is a sensible first stage; it is not a native CMYK editing engine. Preserve imported profile information and define input conversion explicitly.
+
+For PDF, the output intent describes the printing condition; it does not by itself convert every object to CMYK. A CMYK-only preset must also inspect the emitted image and vector colour spaces. PDF/X-4 is a useful eventual target and permits colour-managed content beyond CMYK; claim compliance only after independent validation. See the [PDF Association's requirements](https://pdfa.org/technical-side-and-requirements-of-pdfx/).
+
+JPEG should expose quality, chroma subsampling, explicit alpha flattening and ICC metadata. TIFF should offer lossless compression, resolution tags and RGB/CMYK output. Writing an 8-bit render into a higher-bit-depth container would not provide a higher-precision editing pipeline. PNG remains the convenient lossless screen output.
+
+Sharp/libvips is a strong candidate for raster encoding and ICC conversion: its documented API includes JPEG/TIFF and profile transformation/attachment. Evaluate the exact pinned build before selecting it. PDF needs a separate writer capable of physical page boxes and appropriate colour objects. See [Sharp output documentation](https://sharp.pixelplumbing.com/api-output/).
+
+A flattened raster PDF is a useful first delivery, with its resolution limits made explicit. The production typography milestone should preserve vector paths and embedded/subset fonts wherever supported, rasterizing effects or groups that require it. It should then address K-only small black text, rich-black policy, total ink coverage and soft proofing. Spot colours and overprint can follow a specific print use case.
+
+Export acceptance checks should reopen actual files to verify format signatures, dimensions, resolution tags, profiles and channels. PDF checks additionally inspect physical boxes, font embedding and image placement resolution. Preflight reports should reference the scene hash, actual output hash, profile hash and export settings. Lossy JPEG needs tolerance-based decoded comparison rather than equality with source pixels.
+
+## Editing features worth adding
+
+Prioritise operations that help an agent integrate and revise real artwork:
+
+- Source crop rectangles, focal-point placement, reusable linked assets, perspective transforms and editable clipping paths.
+- Mask algebra, feather/grow/shrink controls, colour-range selection, and a way to import externally generated segmentation masks.
+- Levels, curves, white balance and reusable adjustment stacks; then clone/heal tools for local repairs.
+- Path booleans, editable control points, stroke joins/caps/dashes, SVG import/export, alignment and distribution.
+- Rich text runs, tracking, kerning controls, paragraph styles and stronger font diagnostics.
+
+The generated-image trial exposed one small authoring weakness: the folio used spaces for alignment. Separate aligned objects or tab stops would make that layout more robust. A larger next trial should test a masked photographic subject, matched shadows/colour, and multiple aspect ratios. PSD/AI round-tripping, a GUI toolbox, advanced liquify and automatic image tracing can wait until a concrete workflow justifies their complexity.

package/docs/previews/a3-production.json

@@ -0,0 +1,36 @@
+{
+  "trim_mm": [420, 297],
+  "pixels": [5031, 3579],
+  "density": 300,
+  "channels": 4,
+  "pdf": {
+    "format": "pdf",
+    "pages": [
+      {
+        "media": {
+          "x": 0,
+          "y": 0,
+          "width": 1243.559055,
+          "height": 894.897638
+        },
+        "trim": {
+          "x": 26.503937,
+          "y": 26.503937,
+          "width": 1190.551181,
+          "height": 841.889764
+        },
+        "bleed": {
+          "x": 18,
+          "y": 18,
+          "width": 1207.559055,
+          "height": 858.897638
+        }
+      }
+    ],
+    "images": [],
+    "embedded_fonts": ["/CZZZZZ+DMSerifDisplay-Regular"],
+    "profile_hashes": ["sha256:156e7c14f244cfc4ed83a755ca4803d80e15dd249b40fae82cb127d3902e15c7"],
+    "output_intents": 1
+  },
+  "status": "pass"
+}

package/docs/previews/benchmark.json

@@ -0,0 +1,42 @@
+{
+  "before": {
+    "status": "fail",
+    "score": 0.9375,
+    "issues": [
+      {
+        "id": "issue-1",
+        "category": "composition",
+        "severity": "medium",
+        "region": [755, 610, 56, 84],
+        "message": "Rendered region luma is outside the requested range.",
+        "measured": 0.4914004455115222,
+        "expected": 0.52
+      }
+    ]
+  },
+  "after": {
+    "status": "pass",
+    "score": 1
+  },
+  "iterations": 1,
+  "locality": {
+    "changed_pixels": 4704,
+    "outside_changed_pixels": 0,
+    "changed_bounds": [755, 610, 56, 84],
+    "scopes": [[755, 610, 56, 84]]
+  },
+  "reopened_identical": true,
+  "undo_identical": true,
+  "redo_identical": true,
+  "export_identical": true,
+  "renderer": {
+    "name": "rtistree-skia",
+    "version": "0.2.0",
+    "backend": "@napi-rs/canvas@1.0.8",
+    "node": "v24.14.0",
+    "platform": "darwin",
+    "arch": "arm64"
+  },
+  "scene_hash": "sha256:80c2bd4d6de618e31d54f5b547ad72682713a7f0241ff51a15b1639bb1347149",
+  "png_hash": "sha256:65ba24cef903f57275c743ec04acc37f0fc38d9fe848b7bdcc7970298fbb0bde"
+}

package/docs/previews/performance.json

@@ -0,0 +1,24 @@
+{
+  "scene": [1024, 1024],
+  "layers": 16,
+  "cold_ms": 165.842292,
+  "warm_ms": 92.88699999999997,
+  "incremental_ms": 84.64695799999998,
+  "fresh_ms": 89.01799999999997,
+  "incremental_statistics": {
+    "rasterized_layers": 1,
+    "cached_layers": 15,
+    "cache_bytes": 71303168
+  },
+  "viewport_ms": 1.833167000000003,
+  "full_crop_ms": 4.616415999999958,
+  "viewport_statistics": {
+    "rasterized_layers": 16,
+    "cached_layers": 0,
+    "cache_bytes": 72351744,
+    "viewport_pixels": 16384
+  },
+  "incremental_identical": true,
+  "region_identical": true,
+  "note": "Single local measurements, including PNG encoding; not a throughput guarantee."
+}

package/docs/production.md

@@ -0,0 +1,107 @@
+# Projects, print production and editing in v0.3
+
+## Start a project
+
+```sh
+graphics project new alpine --size A3 --orientation landscape --ppi 300 --bleed 3mm --output-dir output
+graphics render alpine --preset screen
+graphics preflight alpine --preset print
+```
+
+`project new` accepts A3, A4, A5, Letter, or a custom pair such as `160x100` (mm) or `8.5inx11in`. It creates `rtistree.yaml`, a scene with layer fragments, assets/fonts/profiles/history directories, local JSON Schemas, a README and a designated output directory. The destination must be new. Existing scene-file commands remain available; opening a configured entry-point scene also discovers its project settings.
+
+Generated projects start with an sRGB screen preset and a CMYK print preset. Before using the print preset, copy your printer/paper ICC file into `profiles/` and set `presets.print.profile`. Set `profile_hash` to its SHA-256 digest to pin it. CMYK export rejects missing, invalid, changed or non-CMYK profiles. The demo profile is for exercising the pipeline, not a recommendation for a printing process.
+
+Project paths are local to the project root. CLI/MCP renders and artwork exports use `output_dir`; CLI verification and preflight reports use it too. History and critique records remain persistent project state. Explicit CLI `--output` paths override artifact destinations.
+
+## Physical document model
+
+The scene can contain:
+
+```yaml
+document:
+  width: 160
+  height: 100
+  unit: mm
+  ppi: 300
+  bleed: 3
+  safe_margin: 6
+```
+
+Units are `mm`, `in`, or `pt`; bleed and safe margin use the same unit. Canvas coordinates remain design coordinates. The physical trim dimensions are authoritative and must have substantially the same aspect ratio as the canvas (ratio tolerance 0.002). PDF page boxes use full-precision physical dimensions; rounded raster dimensions do not redefine the trim. Export checks read the PDF back within 0.01 mm of the declared size.
+
+Print rendering applies an outer affine transform, preserving source crops, object-relative paint, direct pixels and palette grids. Effects and mask feathering are scaled to maintain their physical appearance. Unbounded procedural backgrounds extend through the bleed. Other artwork must be authored to extend beyond trim when needed. Crop marks are optional and sit outside the bleed.
+
+The renderer accepts edges up to 8,192 pixels. Print preflight also enforces a 32-megapixel output ceiling and a surface budget based on nesting and retained mask dependencies. Uncached composition releases completed layer surfaces rather than retaining every layer. This supports A3 at 300 ppi: 5,031 by 3,579 pixels with 3 mm bleed, as recorded in [the A3 check](previews/a3-production.json). It is not an unlimited-memory or general tiled renderer.
+
+## Formats and colour
+
+```sh
+graphics export alpine --preset print --format pdf
+graphics export alpine --preset print --format tiff
+graphics export alpine --preset screen --format jpeg
+graphics export alpine --format svg -o alpine/output/artwork.svg
+graphics proof alpine --preset print
+graphics export alpine --format project -o /tmp/alpine-copy/scene.json
+```
+
+Known artwork extensions are inferred for `export` and full `render`. Region renders remain PNG. A filename extension must agree with the actual format. Portable scene export keeps its original meaning with `--format project` or a JSON/YAML destination, and copies configured print profiles/presets when exporting a project.
+
+| Format  | Implemented output                                                                                                                     |
+| ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| PNG     | Lossless sRGB, alpha, ICC profile                                                                                                      |
+| JPEG    | sRGB or CMYK, quality 1–100, 4:4:4 or 4:2:0, explicit flattening background                                                            |
+| TIFF    | 8-bit sRGB or CMYK, lossless LZW, resolution tags and ICC profile                                                                      |
+| PDF 1.7 | Exact physical boxes, optional crop marks, sRGB or ICC-managed CMYK, embedded/subset fonts, vector paths and gradients where supported |
+| SVG     | Vector geometry and text outlines; losslessly embedded raster fallbacks for compositing/effects                                        |
+
+The pinned Sharp/libvips encoder uses **perceptual** ICC conversion. This is the only accepted rendering intent, and it is recorded in evidence. Imported profiled rasters and TIFFs are explicitly converted to the sRGB working space. Original source bytes remain pinned and unchanged.
+
+For CMYK PDF, raster image streams contain four-channel samples and reference the embedded ICC profile; vector colours are converted through that profile and the document has the corresponding output intent. Pure `#000000` vector text/shapes use K-only black by default; set `black: profile` to use the profile conversion. This policy does not rewrite black inside photographic assets.
+
+Hybrid PDF retains supported top-level text, paths, shapes, gradients and isolation-free groups. Effects, masks and context-dependent compositing use raster fallbacks at the document resolution. `mode: raster` explicitly produces a flattened page. Gradient endpoints are converted to the output colour space and interpolated there, so PDF gradients may differ slightly from a per-pixel converted screen raster.
+
+`proof` produces an sRGB PNG after a round trip through the chosen CMYK profile. It is useful for inspecting gamut changes, and does not simulate a calibrated monitor or paper white. TIFF/JPEG ink reporting measures decoded CMYK values. PDF ink reporting samples constituent raster/vector colours; it is not a RIP-based analysis of transparency/overprint interactions. Over-limit ink and low effective ppi appear as warnings.
+
+**PDF/X compliance is not asserted.** Spot colours, overprint, a high-bit-depth working pipeline and printer-specific certification remain future work. Export evidence identifies these limits and never labels an ordinary PDF as certified PDF/X.
+
+## Preflight and evidence
+
+Preflight checks physical geometry, render capacity, output profiles, font glyph coverage, text overflow, safe margins and effective image resolution including crop/fit placement. Perspective placements report that their resolution estimate is pre-warp. Low-resolution sources and safe-margin crossings are warnings; invalid geometry/profiles and missing glyphs are errors. Preflight exits 2 for errors and persists its report.
+
+Each artwork export has a `.evidence.json` containing the scene hash, output hash, resolved settings, ICC hash, backend versions and inspection of the actual encoded bytes. Raster inspection reads format, dimensions, channels, profile and density. PDF inspection reads page boxes, image colour-space declarations, embedded font descriptors and profile streams. This complements visual proof inspection; it does not replace press validation.
+
+## New editing operations
+
+Commands are available through `apply` in the CLI, SDK and MCP. See generated command/patch schemas for complete inputs.
+
+| Command or field                         | Behaviour                                                                          |
+| ---------------------------------------- | ---------------------------------------------------------------------------------- |
+| `setDocument`                            | Set or clear physical document settings in history                                 |
+| `setCrop`                                | Set a source-pixel rectangle and optional normalised focal point                   |
+| `setPerspective`                         | Map an image into four convex local corners using inverse projective sampling      |
+| `setAffine`                              | Set an invertible six-number local affine matrix                                   |
+| `setPath`                                | Edit move/line/quadratic/cubic/close segments with explicit control points         |
+| `booleanPath`                            | Union, intersect, subtract or XOR sibling vector operands into a new editable path |
+| `setTextRuns`                            | Styled text spans with colour and regular/bold weight                              |
+| `setParagraphStyle`, `useParagraphStyle` | Reuse and update named text styles                                                 |
+| `setAdjustmentStack`                     | Replace a non-destructive operation stack with locality validation                 |
+
+Multiple image layers can reference one registered asset. Replacing an asset registration with a new immutable source updates those linked uses; edits to already-pinned bytes are still rejected. Existing alignment and distribution commands remain available.
+
+Shapes support stroke caps, joins, dash arrays and dash offsets. Text styles support tracking and kerning control. Rich runs must concatenate exactly to `content`; `setTextRuns` maintains both. Paragraph styles define shared font/size/colour/spacing values. Custom font files should represent the intended face; a weight flag does not select another face inside a custom font collection.
+
+Masks now support editable SVG-style paths, image alpha/luminance/colour-range selections, and union/intersection/subtraction/XOR. Combined masks use one coordinate space; children inherit the outer space and reference size. The processing order is selection/algebra, inversion, grow/shrink, then feathering. Image masks reference an asset directly, making external segmentation masks usable without a visible mask layer.
+
+New scoped operations are levels, piecewise-linear RGB/channel curves, white balance, clone and heal. Cloning samples a frozen copy of the target using `source_offset`. Healing adds a local mean-colour correction to that cloned texture; this is a deterministic colour-matched clone, not a Poisson or learned healing algorithm. All operate non-destructively through the existing history and scoped-pixel checks.
+
+## SVG interchange and trial
+
+```sh
+graphics import-svg drawing.svg -o drawing.scene.json
+graphics export drawing.scene.json --format svg -o drawing.svg
+```
+
+The importer supports static paths, rectangles, circles, ellipses, lines, polygons, polylines, groups, transforms and basic stroke/fill styling. Unsupported elements/attributes, remote resources, scripts and entities are rejected rather than silently dropped. Text, filters and arbitrary CSS are not imported. Exported text is outlined; complex export fallbacks are embedded images. Full round-trip equivalence for arbitrary SVG is not promised.
+
+The [print trial](../examples/print-trial/README.md) generates a ceramic vase/leaf photograph, extracts its silhouette using the new masks, adds a contact shadow and colour adjustment, adapts it to two aspect ratios, and exports CMYK PDF/TIFF/JPEG. The source, exact prompt, edits, critiques, final scenes and output evidence are retained.

package/docs/releasing.md

@@ -0,0 +1,60 @@
+# Release process
+
+The repository is `Coly010/rtistree`, the npm package is `rtistree`, and the website's
+canonical origin is `https://rtistree.dev`. The package is MIT licensed to Colum Ferry.
+
+## Validate a release
+
+1. Update `package.json`, its lockfile and `CHANGELOG.md` together. Keep the website version
+   label and package instructions aligned with the release.
+2. Run `npm ci`, `npm run check`, `npm run format:check` and `npm run package:check`.
+3. Run `npm ci --prefix website` and `npm run build --prefix website`.
+4. Review the tarball inventory, documentation commands and example sources. The package
+   intentionally includes only the small hello example; larger trials are repository assets.
+5. Commit the validated source and tag the matching version, for example `v0.5.0`.
+
+## First npm publication
+
+The owner must authenticate with `npm login` and complete any npm 2FA challenge.
+Confirm `npm whoami` is the intended owner. Build and inspect the package before publishing:
+
+```sh
+npm pack
+npm publish rtistree-0.5.0.tgz --access public
+```
+
+Do not republish a version number. If a command's outcome is uncertain, check the npm
+registry before retrying. Never commit npm tokens or configure long-lived tokens in workflows.
+
+## Subsequent releases with trusted publishing
+
+In the npm package settings, configure a GitHub Actions trusted publisher:
+
+- Owner: `Coly010`
+- Repository: `rtistree`
+- Workflow filename: `release.yml`
+
+After configuring the npm trusted publisher, set the GitHub repository Actions variable
+`NPM_TRUSTED_PUBLISHING_ENABLED` to `true`. Without it, release validation runs but npm
+publication is skipped. This permits the initial GitHub tarball release before npm sign-in.
+
+The release workflow checks the tag against the package version, validates the engine,
+website and packaged installation, then publishes the same checked tarball with provenance.
+It runs on publication of a GitHub release. Configure trust before publishing the next release.
+For the bootstrap release, publish npm first and let the workflow skip an already-published version.
+
+See https://docs.npmjs.com/trusted-publishers/ for current npm account requirements.
+
+## Website
+
+The website is an Astro/Starlight static build in `website/`. `docs/` is the source of truth;
+the content sync script generates Starlight pages, remaps repository links and copies curated
+assets. Generated files are ignored by Git but included when preparing a standalone Sites source snapshot.
+
+`npm run build --prefix website` produces `website/dist`. This is portable static output.
+The Sites project ID is in `website/.openai/hosting.json`; never replace it on redeployment.
+Use the Sites publishing flow to save and deploy the validated source and static archive.
+The `website.yml` workflow validates and uploads a deployable static artifact for each change.
+
+Custom-domain DNS must use the exact records returned by the hosting provider. Do not infer
+an apex A record from a preview hostname. Confirm domain and TLS status after the DNS change.

package/docs/scene-format.md

@@ -0,0 +1,126 @@
+# Scene format v1
+
+The examples in this document are the implemented format. The original proposal is exploratory; unsupported fields are rejected, not silently interpreted. Generate machine-readable schemas with `npm run schema` or `graphics schema`.
+
+The [production guide](production.md) describes v0.3 physical documents, exports, affine and perspective transforms, extended masks, adjustments, path commands and typography.
+
+The [studio guide](studio.md) describes v0.4 programmable assets and dense editing. Assets may carry a `recipe: {source, hash}` reference to a frozen program manifest. Promoted regions accept `composite: replace|over` (default replacement). Programs are executed explicitly and baked; scenes never execute referenced recipes while rendering.
+
+## Files and assets
+
+Root documents contain `version: 1`, `canvas`, `layers` and/or `include`, optional `assets`, `metadata`, and `verification: {rules: [...]}`. Fragments contain `include`, `assets`, `fonts`, `components` and `layers`. JSON and YAML can be mixed. There can be at most 128 included documents and 256 total layers.
+
+```yaml
+assets:
+  portrait:
+    type: image # or generated-image; provenance category only
+    source: ./assets/portrait.png
+    hash: sha256:... # optional on input; checked when supplied
+```
+
+PNG, JPEG, WebP and TIFF assets are supported. ICC-tagged input is normalised to sRGB. The separate `import-svg` command converts a closed static geometry subset into scene layers. No URL loading or external resource resolution is permitted. Asset paths must resolve inside the root scene directory, including after symlink resolution. File size is limited to 64 MiB and decoded dimensions to 32 megapixels. Large rasters belong in binary image files, not YAML arrays.
+
+## Coordinates and layout
+
+`canvas` uses integer `width` and `height`, each from 1 to 8192, `colour_space: srgb`, and a `#RRGGBB` or `#RRGGBBAA` background. A conservative total-surface memory budget can reject large scenes with many retained layers. Physical document dimensions are separate from these design pixels.
+
+Geometry uses `bounds: [x, y, width, height]` **relative to the parent**. Omitted bounds fill the parent's content area. A layer may override dimensions using numeric `width`/`height` or percentages, and `anchor` can be `top-left`, `center`, `top-right`, `bottom-left`, or `bottom-right`. Rotation is in degrees about the box center; scale is a positive `[x, y]` pair. Parent transforms apply to descendants.
+
+```yaml
+- id: product-row
+  type: group
+  bounds: [40, 40, 944, 500]
+  layout: { type: horizontal, padding: 24, gap: 32, align: center }
+  children:
+    - id: left
+      type: vector
+      width: 50%
+      height: 320
+      shape: { type: rectangle, fill: '#f2ce94', radius: 8 }
+    - id: right
+      type: vector
+      width: 50%
+      height: 320
+      shape: { type: ellipse, fill: '#638379' }
+```
+
+Flow layouts support horizontal/vertical directions, padding, gaps and cross-axis start/center/end alignment. Percentages on the flow axis use space remaining after padding and gaps. Flow layout overrides child positions and anchors. Direct move/resize/alignment commands require an absolute-layout parent; change the authoring layout to control flow sizing. An optional `aspect_ratio` derives height from width when height is omitted. Positive `grow` weights share remaining flow space; `justify` supports start, center, end and space-between. Automatic asset dimensions and arbitrary constraints are not implemented.
+
+**Masks, paint paths, raster scopes, pixel locations and palette tiles default to canvas coordinates.** Set `space: layer` and a `reference_size` to attach them to an object. Commands capture the reference size automatically; movement, rotation and resizing then transform the edit. This explicit separation permits exact locality measurements. Layer masks use the rendered alpha of the target layer for `semantic-object`; hidden targets have empty alpha.
+
+## Layers
+
+Common fields: `id`, `name`, `role`, `visible`, `opacity`, `blend_mode`, `z`, `bounds`, `transform`, `mask`, `effects`, `operations`, `tiles`. Children are embedded layer objects on a `group`, not string references. Positive `z` paints later among siblings. Equal values preserve declaration order.
+
+| Type                    | Required or relevant fields                                                               |
+| ----------------------- | ----------------------------------------------------------------------------------------- |
+| group                   | `children`, optional `layout`                                                             |
+| vector                  | `shape`                                                                                   |
+| text                    | `content`, optional `style`                                                               |
+| asset / generated-asset | `source` asset ID; `fit: contain`, `cover`, or `stretch`                                  |
+| procedural              | `generator`                                                                               |
+| raster                  | optional `source` asset ID, `tiles`, `operations`; initially transparent without a source |
+| adjustment              | `operations`, optional mask and opacity; operates on already composed siblings            |
+
+Shapes are `rectangle` (optional radius), `ellipse`, or `path` with SVG path data in `d`. All require `fill`; transparent fill is `#00000000`. Optional `stroke` and `stroke_width` add an outline. Paths use local coordinates in the layer's box; they are not automatically normalized to that box.
+
+Text is retained as semantic content. It wraps at whitespace and respects explicit newlines. `style` supports `font: inter|display`, `size`, `weight: regular|bold`, `colour`, `line_height` as a multiplier, and `align: left|center|right`. `display` uses DM Serif Display regular; its bold variant is not supplied. Text is clipped to its box, and the verifier reports overflow. Bundled Latin fonts provide reproducible typography; a custom font can be registered in the scene fonts map and selected by its ID.
+
+Generators: `solid` (`colour`); `gradient` (`from`, `to`, `angle`, with 0° horizontal and 90° vertical); `noise` (`seed`, `amount`, optional base `colour`). Every random generator requires an integer seed. Noise is sampled in a stable row-major order.
+
+Blend modes: normal, multiply, screen, overlay, darken, lighten, difference, soft-light, hard-light. Compositing and colour adjustments use Skia's sRGB path; this is not a linear-light color grading engine.
+
+## Effects, masks and raster operations
+
+Layer effects currently support `{type: blur, radius: 8}`. Rendering order is geometry/children → effects → palette tiles → raster operations → promoted regions → layer mask → opacity → sibling blending. Adjustment layers apply scoped operations to the existing composite, then mix the result by their mask and opacity.
+
+Mask types:
+
+```yaml
+mask: { type: rectangle, bounds: [100, 100, 200, 200], feather: 8 }
+```
+
+The exact mask type token is **`rectangle`**, alongside `ellipse`, `polygon` (`points: [[x,y], ...]`), and `semantic-object` (`target: layer-id`). All accept `feather` in pixels. The feather is applied before intersection with a raster operation's hard bounds. Semantic mask references are checked for dependency cycles, including parent/child cycles. Adjustment layers cannot be semantic mask targets.
+
+Every raster operation requires a `bounds` rectangle and accepts an optional `mask`. Bounds use half-open canvas pixel coordinates: a pixel at `(x,y)` is in scope when `left <= x < right` and `top <= y < bottom`. Integer bounds are recommended. Filters and soft strokes are hard-clipped to this region, so provide enough padding for a smooth falloff.
+
+| Operation     | Parameters                                                      |
+| ------------- | --------------------------------------------------------------- |
+| fill          | `colour`; source-over fill                                      |
+| paintStroke   | `path`, `radius`, `colour`, optional `opacity`, `hardness`      |
+| eraseStroke   | `path`, `radius`, optional `opacity`, `hardness`; removes alpha |
+| brightness    | `amount` from −1 to 1; additive channel offset                  |
+| contrast      | `amount` from −1 to 1; contrast around the channel midpoint     |
+| saturation    | `amount` from −1 to 1; −1 gives monochrome                      |
+| hueShift      | `degrees` from −360 to 360                                      |
+| noise         | `amount` from 0 to 1, explicit integer `seed`                   |
+| blur          | `radius`; samples full layer context, changes only scope        |
+| colourReplace | `from`, `to`, optional `tolerance` from 0 to 1                  |
+| setPixels     | `pixels: [{x, y, colour}, ...]`; maximum 4096 sparse pixels     |
+
+Brush hardness is implemented by a deterministic Gaussian blur of the stroke. Colour adjustments preserve alpha. `setPixels` replaces RGBA values. Pixels outside bounds are ignored; feathered masks blend premultiplied colors. For transactional edits, the final composite is compared before and after; any changed pixel outside the command's scope rejects the whole transaction. Direct `applyCommand` is a pure structural helper; use `Project.apply` to enforce the rendered locality guarantee.
+
+## Palette tiles
+
+Tiles have canvas bounds, a single-character palette, and rows of keys. Rows must have equal widths, every key must exist, and grids are limited to 256 × 256. Scaling uses nearest-neighbor sampling.
+
+```yaml
+- id: detail
+  type: raster
+  tiles:
+    - bounds: [320, 280, 32, 32]
+      palette: { A: '#00000000', B: '#f2be81', C: '#b75c40' }
+      pixels: ['AABB', 'ABBC', 'BBCC', 'BCCB']
+```
+
+`replaceTile` replaces a tile with exactly matching bounds or appends a new one. Transparent tile pixels composite over underlying layer content. Palette tiles remain compact grids. Separately, `promoteRegion`, `updateRegion` and `demoteRegion` manage patches with 1–4× resolution and optional external raster sources; see [evolution](evolution.md).
+
+## Commands and verification
+
+`apply` accepts `{reason, expected_hash?, commands: [...]}`. Commands include add/remove/move/resize layer, set opacity/blend/text/style, group siblings, align/distribute siblings, apply effect, apply raster operation, and replace tile. See `graphics schema --kind command` for exact fields. Removing referenced mask or verification targets is rejected unless the resulting scene is valid. Grouping can change compositing with interleaved siblings; it is an explicit structural edit without a locality promise.
+
+Verification always checks rendered text overflow. Optional rules cover safe-area, text-overflow, text-equals, required-role, contrast, no-overlap and region-luma. Luma is a mean weighted sRGB channel value in [0,1], not perceptual luminance. `contrast` uses declared foreground and explicit background colours. `pixel-contrast` and `visible-area` use counterfactual rendered samples through `verifyRendered` / `Project.verify`. Geometry checks use transformed bounding boxes, not exact silhouettes. A heatmap marks issue bounds. All reports state these limitations.
+
+`render-region` requires an integer rectangle fully inside the canvas and equals an exact crop of the full render. `draft` halves both output dimensions after rendering; preview and final currently use the same full-quality pipeline. PNG output includes renderer evidence in a sidecar. Canonical scene hashes omit timestamps; history includes timestamps for audit purposes without influencing pixel output.
+
+The [evolution guide](evolution.md) documents the expanded command surface, coordinates, components, fonts, adaptive regions, critiques, rebase, compaction, and agent trials.