rtistree 0.5.0

package/docs/studio.md

@@ -0,0 +1,108 @@
+# Programmable digital art in v0.4
+
+The studio is the escape hatch below scene abstractions. An agent can build an image using paths and gradients, paint pressure-sensitive strokes, calculate pixel colours, sample textures, or write a custom image-processing algorithm. No image-generation model is used by these tools.
+
+Scene layers still describe composition. Programs produce ordinary pinned PNG assets and can replace the source of a raster/image layer. Their exact source, seed, parameters, input snapshots and output hash are saved as a recipe. Rendering, inspecting and opening a scene never runs a program. Re-execution is explicit, and existing edits remain undoable.
+
+## First painting
+
+```sh
+graphics project new study --size 100x100
+graphics studio-help
+```
+
+Save this as `study/programs/rubber.js`:
+
+```js
+const height = (x, y) => 18 * Math.sin(x / 80);
+return art.raster((x, y) => {
+  const grain = (art.fbm(x / 20, y / 20) - 0.5) * 5;
+  return art.light(art.normal(height, x, y), [40 + grain, 47 + grain, 51 + grain, 255], {
+    light: [-0.6, -0.4, 1],
+    specular: 0.06,
+    shininess: 20,
+  });
+});
+```
+
+Save a request as `study/paint.json`:
+
+```json
+{
+  "source": "programs/rubber.js",
+  "asset_id": "rubberPaint",
+  "target": "rubber",
+  "width": 400,
+  "height": 400,
+  "seed": 2020,
+  "parameters": {},
+  "reason": "Paint a curved rubber material using height-field lighting"
+}
+```
+
+```sh
+graphics program study study/paint.json
+graphics render study -o study/output/rubber.png
+graphics program-replay study rubberPaint
+```
+
+Supply exactly one of `source` (a project-local JavaScript file) or `code` (an inline function body). A program receives `art` and `parameters`, runs synchronously and returns one Canvas with the declared dimensions. It cannot import modules through the public API. A new `target` creates a raster layer; an existing target must accept an image source. Omit `target` to register an asset for subsequent mask, region or layer operations. The runner captures the starting scene hash and rejects a concurrent edit before committing.
+
+## Authoring vocabulary
+
+`graphics studio-help` and the MCP `studioHelp` tool expose the complete signatures and a runnable example. TypeScript consumers can use `RasterStudio` from the SDK.
+
+| API                                             | Purpose                                                                         |
+| ----------------------------------------------- | ------------------------------------------------------------------------------- |
+| `canvas`, `getContext('2d')`                    | Native paths, fills, transforms, compositing, gradients and text                |
+| `raster`, `pixels`, `put`                       | Arbitrary pixel functions and dense typed-array editing                         |
+| `brush`                                         | Round dabs with pressure, hardness, per-dab opacity, spacing and seeded scatter |
+| `noise`, `fbm`, `random`                        | Coordinate-addressed textures and repeatable random sequences                   |
+| `polar`, `repeat`, `mix`, `clamp`, `smoothstep` | General coordinate and field construction                                       |
+| `sample`, `warp`, `displace`                    | Bilinear sampling and arbitrary inverse coordinate mappings                     |
+| `normal`, `light`                               | Height-field normals, Lambert diffuse and Blinn–Phong highlights                |
+| `blur`                                          | Softening and intermediate layer preparation                                    |
+| `input`                                         | A mutable Canvas copy of a named frozen input image                             |
+
+Brush pressure affects radius and alpha. Opacity applies to each dab, so strokes accumulate paint. Spacing is measured as a fraction of the requested radius; scatter is also radius-relative. Brushes use the canvas context's current transform. Dabs below 0.01 pixel radius are omitted to avoid degenerate native gradients. These are round brushes, not a complete simulation of paint, bristles or wet media.
+
+Pixel functions use integer pixel-centre coordinates and four finite 0–255 sRGB channels. Native surfaces store premultiplied alpha: fully transparent hidden RGB is not preserved, and semi-transparent samples can round on conversion. Sampling interpolates premultiplied colour to avoid dark fringes. Edge modes are transparent, clamp or repeat. Warp callbacks map **destination coordinates to source coordinates**. Displacement adds its field to the source sampling coordinates.
+
+Height-field lighting is an artistic 2.5D calculation, with the viewer along positive Z. It does not provide ray-traced reflections, refraction, global illumination, occlusion or cast shadows. Those effects can be painted, approximated in code, or supplied as baked assets from an external traditional graphics tool.
+
+## Dense regional edits
+
+`readRasterRegion` / `graphics raster-read PROJECT request.json` read a PNG crop of the composite or an isolated layer. The request contains integer canvas-space `bounds` and an optional `target`. The result includes the scene hash and an asset descriptor ready for `registerAsset`.
+
+`writeRasterRegion` / `graphics raster-write PROJECT request.json` consumes:
+
+```json
+{
+  "target": "rubber",
+  "region_id": "scuff",
+  "source": "output/scuff.png",
+  "bounds": [40, 60, 80, 80],
+  "space": "layer",
+  "composite": "over",
+  "expected_hash": "sha256:REPLACE_WITH_CURRENT_SCENE_HASH",
+  "reason": "Paint a local abrasion without changing the rest of the layer"
+}
+```
+
+The source must be a project-local PNG matching the region's exact dimensions. `replace` clears/replaces the region, including alpha; `over` composites it onto the previous pixels. The command creates or updates a named promoted region at scale 1 and stores an immutable copy of the PNG. `space: layer` captures reference dimensions, so the patch follows later transforms and resizing. `space: canvas` stays at canvas coordinates. Existing layer masks/effects still apply; locality validation rejects changes leaking outside the declared region. Undo/redo restores the prior image.
+
+For a custom filter, register the descriptor returned by the read, pass that asset to `runProgram.inputs`, calculate the new pixels, and write the returned PNG into a region. Use the latest scene hash returned by each mutation. Canvas-space reads cannot automatically become local-space reads of a rotated object; use canvas-space patch coordinates for a direct read/edit/write round trip.
+
+## Reproducibility and execution limits
+
+Recipes live under `recipes/<hash>/`. Each recipe stores the exact JavaScript source text, source hash, parameters, seed, studio version, Node/Skia versions, frozen input PNG hashes and output hash. Inputs are normalised to sRGB before execution. Portable project export copies the recipe and its input snapshots, without executing them. `program-replay` executes a selected recipe and compares the resulting PNG hash; equality is expected on the same pinned runtime/platform, not universally across machines.
+
+Programs execute only when explicitly requested and must be trusted code. A worker and VM provide convenience isolation and cancellation, **not a security sandbox**: native objects expose host methods. The public API does not expose filesystem/network access, and its `Math.random` is seeded; Date/performance are absent. Do not treat these properties as hostile-code containment.
+
+The runner checks a 16-megapixel output limit, 16 input images, an 8,192-pixel edge, 256 KiB source, 64 KiB parameters, and up to 30 seconds of execution. The parent watchdog allows two additional seconds for worker setup. Studio helper allocations are capped at 32 cumulative megapixels including inputs; V8's heap limit is 256 MiB. Native Canvas buffers and arbitrary allocations made through exposed native objects are outside the V8 accounting, so these limits are not an OS memory quota. Scene rendering retains its separate surface budget.
+
+The studio has no live dependency graph. Changing program code, parameters or an input does not automatically rebake dependent assets. Explicit execution replaces a target source through the existing transaction/history mechanism. If execution or commit fails, the scene is unchanged; a late failed commit can leave unreferenced content-addressed artifacts.
+
+## Trial
+
+The [manual wheel trial](../examples/manual-wheel-trial/README.md) used no model-generated or downloaded imagery. Its eight layers were painted with code, geometry, material fields, text and brushes. Source, recipes, initial/refined images, critiques and replay checks are retained. The result demonstrates a reproducible digital illustration; its visual evaluation explicitly leaves photographic realism unachieved.

package/examples/hello/README.md

@@ -0,0 +1,14 @@
+# First image
+
+From a directory with `rtistree` installed, copy these three files into your project.
+
+```sh
+npx graphics render scene.json -o hello.png
+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
+```
+
+`restored.png` should match `hello.png` byte for byte on the same runtime and platform.
+`render.mjs` demonstrates the SDK; run it with `node render.mjs`.

package/examples/hello/refine.json

@@ -0,0 +1,10 @@
+{
+  "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 }
+    }
+  ]
+}

package/examples/hello/render.mjs

@@ -0,0 +1,9 @@
+import { Project, rtistreeAgentInstructions, artDirectionGuide } from 'rtistree';
+import { writeFile } from 'node:fs/promises';
+
+const project = await Project.open(new URL('./scene.json', import.meta.url).pathname);
+const result = await project.render();
+await writeFile(new URL('./sdk-output.png', import.meta.url), result.png);
+console.log({ width: result.width, height: result.height, guide: artDirectionGuide.version });
+// Include this string in your agent's instructions when integrating the SDK.
+console.log(rtistreeAgentInstructions);

package/examples/hello/scene.json

@@ -0,0 +1,19 @@
+{
+  "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" }
+    }
+  ]
+}

package/licenses/DM-Serif-Display-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2014 - 2017 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. Copyright 2019 Google LLC. DMSerifDisplay-Italic.ttf: Copyright 2014 - 2017 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. Copyright 2019 Google LLC.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/licenses/Inter-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter) Inter-Italic[opsz,wght].ttf: Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "rtistree",
+  "version": "0.5.0",
+  "description": "Deterministic, agent-operable raster graphics engine",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "check": "npm run build && npm test",
+    "graphics": "node --import tsx src/cli.ts",
+    "demo": "node --import tsx scripts/demo.ts",
+    "schema": "node --import tsx scripts/schema.ts",
+    "format": "prettier --write src tests scripts docs examples schemas README.md package.json tsconfig.json .github .prettierrc.json",
+    "format:check": "prettier --check src tests scripts docs examples schemas README.md package.json tsconfig.json .github .prettierrc.json",
+    "performance": "node --import tsx scripts/performance.ts",
+    "prepack": "npm run build",
+    "package:check": "node scripts/package-smoke.mjs"
+  },
+  "keywords": [
+    "graphics",
+    "mcp",
+    "agents",
+    "raster",
+    "procedural-art",
+    "canvas"
+  ],
+  "type": "module",
+  "dependencies": {
+    "@fontsource/dm-serif-display": "5.3.0",
+    "@fontsource/inter": "5.3.0",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@napi-rs/canvas": "1.0.8",
+    "fast-xml-parser": "5.11.1",
+    "fontkit": "2.0.4",
+    "pdf-lib": "1.17.1",
+    "pdfkit": "0.20.2",
+    "sharp": "0.35.4",
+    "yaml": "2.9.0",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@types/fontkit": "2.0.9",
+    "@types/node": "26.5.0",
+    "@types/pdfkit": "0.17.6",
+    "prettier": "3.9.6",
+    "tsx": "4.23.13",
+    "typescript": "7.0.2"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "graphics": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "schemas",
+    "LICENSE",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
+    "licenses",
+    "examples/hello"
+  ],
+  "license": "MIT",
+  "author": "Colum Ferry",
+  "homepage": "https://rtistree.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Coly010/rtistree.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Coly010/rtistree/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}