@pixerate/editor 0.101.0 → 0.103.0

package/dist/raster/index.js

@@ -71,7 +71,7 @@ import {
   validateLayerEffect,
   validateLayerEffects,
   warpSurface
-} from "../chunk-WIR377F6.js";
+} from "../chunk-67FRIOPZ.js";
 import "../chunk-GX332W2C.js";
 import {
   BLEND_MODES,

package/dist/{surface-DIA-XatS.d.cts → surface-AfHCH7BR.d.cts}

@@ -190,4 +190,4 @@ declare function collectTiles(surface: TiledSurface, into: Set<Tile>): void;
 /** True when two surfaces hold the same pixels (cheap when they share tiles). */
 declare function surfacesEqual(a: TiledSurface, b: TiledSurface): boolean;
 
-export { readRegion as A, type BlendMode as B, setLum as C, solidSurface as D, surfaceBytes as E, surfaceFromPixels as F, surfacesEqual as G, tileCoord as H, tileKey as I, tileRect as J, tilesInRect as K, translateSurface as L, type MaskSurface as M, uniformTile as N, writeRegion as O, type PixelSurface as P, type RasterRect as R, SurfaceDraft as S, TiledSurface as T, BLEND_MODES as a, type BlendModeInfo as b, type Rgb as c, type Rgba as d, TILE as e, TILE_SHIFT as f, type Tile as g, type TileKey as h, blendChannel as i, blendImageData as j, blendLum as k, blendPixel as l, blendRgb as m, canvasCompositeOperation as n, collectTiles as o, contentBounds as p, emptySurface as q, fillRect as r, finishTile as s, isBlendMode as t, isSeparableBlendMode as u, mixPigment8 as v, mixPigmentRgb as w, normalizeBlendMode as x, packRgba as y, readPixel as z };
+export { readRegion as A, type BlendMode as B, setLum as C, solidSurface as D, surfaceBytes as E, surfaceFromPixels as F, surfacesEqual as G, tileCoord as H, tileKey as I, tileRect as J, tilesInRect as K, translateSurface as L, type MaskSurface as M, uniformTile as N, writeRegion as O, type PixelSurface as P, type RasterRect as R, SurfaceDraft as S, type TileKey as T, TiledSurface as a, type Tile as b, BLEND_MODES as c, type BlendModeInfo as d, type Rgb as e, type Rgba as f, TILE as g, TILE_SHIFT as h, blendChannel as i, blendImageData as j, blendLum as k, blendPixel as l, blendRgb as m, canvasCompositeOperation as n, collectTiles as o, contentBounds as p, emptySurface as q, fillRect as r, finishTile as s, isBlendMode as t, isSeparableBlendMode as u, mixPigment8 as v, mixPigmentRgb as w, normalizeBlendMode as x, packRgba as y, readPixel as z };

package/dist/{surface-DIA-XatS.d.ts → surface-AfHCH7BR.d.ts}

@@ -190,4 +190,4 @@ declare function collectTiles(surface: TiledSurface, into: Set<Tile>): void;
 /** True when two surfaces hold the same pixels (cheap when they share tiles). */
 declare function surfacesEqual(a: TiledSurface, b: TiledSurface): boolean;
 
-export { readRegion as A, type BlendMode as B, setLum as C, solidSurface as D, surfaceBytes as E, surfaceFromPixels as F, surfacesEqual as G, tileCoord as H, tileKey as I, tileRect as J, tilesInRect as K, translateSurface as L, type MaskSurface as M, uniformTile as N, writeRegion as O, type PixelSurface as P, type RasterRect as R, SurfaceDraft as S, TiledSurface as T, BLEND_MODES as a, type BlendModeInfo as b, type Rgb as c, type Rgba as d, TILE as e, TILE_SHIFT as f, type Tile as g, type TileKey as h, blendChannel as i, blendImageData as j, blendLum as k, blendPixel as l, blendRgb as m, canvasCompositeOperation as n, collectTiles as o, contentBounds as p, emptySurface as q, fillRect as r, finishTile as s, isBlendMode as t, isSeparableBlendMode as u, mixPigment8 as v, mixPigmentRgb as w, normalizeBlendMode as x, packRgba as y, readPixel as z };
+export { readRegion as A, type BlendMode as B, setLum as C, solidSurface as D, surfaceBytes as E, surfaceFromPixels as F, surfacesEqual as G, tileCoord as H, tileKey as I, tileRect as J, tilesInRect as K, translateSurface as L, type MaskSurface as M, uniformTile as N, writeRegion as O, type PixelSurface as P, type RasterRect as R, SurfaceDraft as S, type TileKey as T, TiledSurface as a, type Tile as b, BLEND_MODES as c, type BlendModeInfo as d, type Rgb as e, type Rgba as f, TILE as g, TILE_SHIFT as h, blendChannel as i, blendImageData as j, blendLum as k, blendPixel as l, blendRgb as m, canvasCompositeOperation as n, collectTiles as o, contentBounds as p, emptySurface as q, fillRect as r, finishTile as s, isBlendMode as t, isSeparableBlendMode as u, mixPigment8 as v, mixPigmentRgb as w, normalizeBlendMode as x, packRgba as y, readPixel as z };

package/dist/tools/index.cjs

@@ -14,6 +14,7 @@
 var _chunkQIWFEEWGcjs = require('../chunk-QIWFEEWG.cjs');
 
 
+var _chunkRIWPYSKUcjs = require('../chunk-RIWPYSKU.cjs');
 
 
 
@@ -39,19 +40,18 @@ var _chunkQIWFEEWGcjs = require('../chunk-QIWFEEWG.cjs');
 
 
 
-var _chunkEI2MOVQ3cjs = require('../chunk-EI2MOVQ3.cjs');
 
 
+var _chunkEI2MOVQ3cjs = require('../chunk-EI2MOVQ3.cjs');
 
 
 
 
 
 
-var _chunkVJUVNERTcjs = require('../chunk-VJUVNERT.cjs');
 
 
-var _chunkRIWPYSKUcjs = require('../chunk-RIWPYSKU.cjs');
+var _chunkVJUVNERTcjs = require('../chunk-VJUVNERT.cjs');
 
 
 

package/dist/tools/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/editor/editor/packages/core/dist/tools/index.cjs"],"names":[],"mappings":"AAAA,0GAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wtGAAC","file":"/home/runner/work/editor/editor/packages/core/dist/tools/index.cjs"}
+{"version":3,"sources":["/home/runner/work/editor/editor/packages/core/dist/tools/index.cjs"],"names":[],"mappings":"AAAA,0GAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wtGAAC","file":"/home/runner/work/editor/editor/packages/core/dist/tools/index.cjs"}

package/dist/tools/index.js

@@ -12,6 +12,9 @@ import {
   createToolRegistry,
   toToolResult
 } from "../chunk-PTMIGXZ2.js";
+import {
+  validateJsonSchema
+} from "../chunk-4FX5ACVG.js";
 import {
   CAPTURE_EXCLUDE_SELECTOR,
   CAPTURE_OVERLAY_SELECTORS,
@@ -49,9 +52,6 @@ import {
   toCapturedImageData,
   unionCaptureRects
 } from "../chunk-REOJJIY3.js";
-import {
-  validateJsonSchema
-} from "../chunk-4FX5ACVG.js";
 export {
   CAPTURE_EXCLUDE_SELECTOR,
   CAPTURE_OVERLAY_SELECTORS,

package/dist/vector/index.d.cts

@@ -7,9 +7,10 @@ import { H as HistoryManager } from '../HistoryManager-DeQQMBCj.cjs';
 import { C as CommandSpec } from '../registry-CaR7LC6W.cjs';
 import { S as StrokeJoin, a as StrokeCap, P as PlanarMap, b as PathfinderOperation, c as PathfinderShape } from '../pathfinder-BZL8aSu0.cjs';
 import { b as AnimationEasing } from '../easing-lM0Xo9Ni.cjs';
-export { W as VECTOR_WARP_STYLES, a as VECTOR_WARP_STYLE_LABELS, b as VectorWarpPreset, c as applyVectorHomography, d as dragVectorMeshPoint, e as evalVectorMesh, f as fitVectorMesh, i as isValidVectorMesh, m as mapVectorMeshPoints, o as orderVectorQuad, p as pullVectorMesh, r as removeVectorMeshSplitU, g as removeVectorMeshSplitV, h as resizeVectorMesh, s as solve8, j as splitVectorMeshU, k as splitVectorMeshV, l as vectorHomography, n as vectorHomographyKeepsQuad, q as vectorIdentityMesh, w as vectorMeshColumns, t as vectorMeshControlBounds, u as vectorMeshEditPoints, v as vectorMeshGridCurves, x as vectorMeshParamAt, y as vectorMeshRows, z as vectorWarpPresetGrid, A as vectorWarpPresetMesh } from '../warp-nYs2DPrx.cjs';
+export { a as applyVectorHomography, o as orderVectorQuad, s as solve8, h as vectorHomography, b as vectorHomographyKeepsQuad } from '../homography-CZ-tFjay.cjs';
 import { A as AffineMatrix, V as Vec2 } from '../types-CwMPoRMU.cjs';
 export { H as VectorHomography } from '../types-CwMPoRMU.cjs';
+export { a as VECTOR_WARP_STYLES, b as VECTOR_WARP_STYLE_LABELS, W as VectorWarpPreset, d as dragVectorMeshPoint, e as evalVectorMesh, f as fitVectorMesh, i as isValidVectorMesh, m as mapVectorMeshPoints, p as pullVectorMesh, r as removeVectorMeshSplitU, c as removeVectorMeshSplitV, g as resizeVectorMesh, s as splitVectorMeshU, h as splitVectorMeshV, j as vectorIdentityMesh, w as vectorMeshColumns, k as vectorMeshControlBounds, l as vectorMeshEditPoints, n as vectorMeshGridCurves, o as vectorMeshParamAt, q as vectorMeshRows, t as vectorWarpPresetGrid, u as vectorWarpPresetMesh } from '../warp-D5jz_tN7.cjs';
 import '../types-DsiXGmjo.cjs';
 import '../schema-Di0CS6Pe.cjs';
 

package/dist/vector/index.d.ts

@@ -7,9 +7,10 @@ import { H as HistoryManager } from '../HistoryManager-DWSLd6Tf.js';
 import { C as CommandSpec } from '../registry-rVtFJjRM.js';
 import { S as StrokeJoin, a as StrokeCap, P as PlanarMap, b as PathfinderOperation, c as PathfinderShape } from '../pathfinder-CNtsbCRK.js';
 import { b as AnimationEasing } from '../easing-lM0Xo9Ni.js';
-export { W as VECTOR_WARP_STYLES, a as VECTOR_WARP_STYLE_LABELS, b as VectorWarpPreset, c as applyVectorHomography, d as dragVectorMeshPoint, e as evalVectorMesh, f as fitVectorMesh, i as isValidVectorMesh, m as mapVectorMeshPoints, o as orderVectorQuad, p as pullVectorMesh, r as removeVectorMeshSplitU, g as removeVectorMeshSplitV, h as resizeVectorMesh, s as solve8, j as splitVectorMeshU, k as splitVectorMeshV, l as vectorHomography, n as vectorHomographyKeepsQuad, q as vectorIdentityMesh, w as vectorMeshColumns, t as vectorMeshControlBounds, u as vectorMeshEditPoints, v as vectorMeshGridCurves, x as vectorMeshParamAt, y as vectorMeshRows, z as vectorWarpPresetGrid, A as vectorWarpPresetMesh } from '../warp-B8rAguzs.js';
+export { a as applyVectorHomography, o as orderVectorQuad, s as solve8, h as vectorHomography, b as vectorHomographyKeepsQuad } from '../homography-Ctfjoc1b.js';
 import { A as AffineMatrix, V as Vec2 } from '../types-CwMPoRMU.js';
 export { H as VectorHomography } from '../types-CwMPoRMU.js';
+export { a as VECTOR_WARP_STYLES, b as VECTOR_WARP_STYLE_LABELS, W as VectorWarpPreset, d as dragVectorMeshPoint, e as evalVectorMesh, f as fitVectorMesh, i as isValidVectorMesh, m as mapVectorMeshPoints, p as pullVectorMesh, r as removeVectorMeshSplitU, c as removeVectorMeshSplitV, g as resizeVectorMesh, s as splitVectorMeshU, h as splitVectorMeshV, j as vectorIdentityMesh, w as vectorMeshColumns, k as vectorMeshControlBounds, l as vectorMeshEditPoints, n as vectorMeshGridCurves, o as vectorMeshParamAt, q as vectorMeshRows, t as vectorWarpPresetGrid, u as vectorWarpPresetMesh } from '../warp-CWHZzE3x.js';
 import '../types-DsiXGmjo.js';
 import '../schema-Di0CS6Pe.js';
 

package/dist/{warp-B8rAguzs.d.ts → warp-CWHZzE3x.d.ts}

@@ -1,51 +1,4 @@
-import { H as Homography, V as Vec2, B as Box, Q as Quad, A as AffineMatrix, W as WarpStyle, a as WarpMesh } from './types-CwMPoRMU.js';
-
-/**
- * Perspective (projective) maps between quadrilaterals: Free Distort and Perspective in both the
- * vector and the image editor. Pure maths; degenerate or non-finite input gives `null` instead of
- * NaNs.
- *
- * Ported from ArtCraft (MIT OR Apache-2.0, © ArtCraft Team and contributors; see
- * THIRD_PARTY_NOTICES.md): pdfcraft `crates/geom/src/perspective.rs` (`Homography::from_points`,
- * `Homography::apply`, `solve8`, `order_quad`) and photocraft `crates/algo/src/transform.rs`
- * (`Homography::square_to_quad`, `rect_to_quad`, `inverse`, `mul`, `local_scale`, `front_side`,
- * `warp_output_bounds`, `convex_quad`).
- */
-
-/**
- * Gaussian elimination with partial pivoting on an 8×8 system (the 9th column of each row is the
- * right-hand side). Null when the system is singular.
- */
-declare function solve8(rows: readonly (readonly number[])[]): number[] | null;
-/** The image of `p`, or null where the map sends it to infinity. */
-declare function applyHomography(h: Homography, p: Vec2): Vec2 | null;
-/**
- * The projective map that takes each of `from` to the point at the same index of `to`. Null when
- * three of either set are collinear or a coordinate is not finite.
- */
-declare function homographyFromPoints(from: readonly Vec2[], to: readonly Vec2[]): Homography | null;
-/**
- * Whether `h` maps the whole convex quad `quad` without sending any of it through infinity (the
- * denominator keeps one sign over it): what a usable distortion needs.
- */
-declare function homographyKeepsQuad(h: Homography, quad: readonly Vec2[]): boolean;
-/**
- * The four corners in reading order for a y-down space: top-left, top-right, bottom-right,
- * bottom-left, whatever order they come in. Null unless they form a convex quadrilateral with a
- * non-negligible area.
- */
-declare function orderQuad(points: readonly Vec2[]): Vec2[] | null;
-/** The inverse map, or null for a singular one. */
-declare function invertHomography(m: Homography): Homography | null;
-/** An affine matrix (SVG order) as a homography. */
-declare function homographyFromAffine(m: AffineMatrix): Homography;
-/**
- * The map taking box `r`'s corners onto `quad` (TL, TR, BR, BL), exact for parallelograms (then
- * affine). Null for an empty box, a non-finite or degenerate quad, or a singular result.
- */
-declare function rectToQuad(r: Box, quad: readonly Vec2[]): Homography | null;
-/** Box `r`'s corners as a quad (TL, TR, BR, BL). */
-declare function boxQuad(r: Box): Quad;
+import { W as WarpStyle, a as WarpMesh, V as Vec2, B as Box } from './types-CwMPoRMU.js';
 
 /**
  * Warp geometry shared by the vector editor's envelopes and the image editor's Free Transform
@@ -162,4 +115,4 @@ declare function warpMeshEditPoints(m: WarpMesh): {
 /** The mesh's grid lines (patch borders) as cubics `[p0, p1, p2, p3]`. */
 declare function warpMeshGridCurves(m: WarpMesh): Vec2[][];
 
-export { warpPresetMesh as A, boxQuad as B, homographyFromAffine as C, invertHomography as D, rectToQuad as E, WARP_STYLES as W, WARP_STYLE_LABELS as a, type WarpPreset as b, applyHomography as c, dragWarpMeshPoint as d, evalWarpMesh as e, fitWarpMesh as f, removeWarpMeshSplitV as g, resizeWarpMesh as h, isValidWarpMesh as i, splitWarpMeshU as j, splitWarpMeshV as k, homographyFromPoints as l, mapWarpMeshPoints as m, homographyKeepsQuad as n, orderQuad as o, pullWarpMesh as p, identityWarpMesh as q, removeWarpMeshSplitU as r, solve8 as s, warpMeshControlBounds as t, warpMeshEditPoints as u, warpMeshGridCurves as v, warpMeshColumns as w, warpMeshParamAt as x, warpMeshRows as y, warpPresetGrid as z };
+export { type WarpPreset as W, WARP_STYLES as a, WARP_STYLE_LABELS as b, removeWarpMeshSplitV as c, dragWarpMeshPoint as d, evalWarpMesh as e, fitWarpMesh as f, resizeWarpMesh as g, splitWarpMeshV as h, isValidWarpMesh as i, identityWarpMesh as j, warpMeshControlBounds as k, warpMeshEditPoints as l, mapWarpMeshPoints as m, warpMeshGridCurves as n, warpMeshParamAt as o, pullWarpMesh as p, warpMeshRows as q, removeWarpMeshSplitU as r, splitWarpMeshU as s, warpPresetGrid as t, warpPresetMesh as u, warpMeshColumns as w };

package/dist/{warp-nYs2DPrx.d.cts → warp-D5jz_tN7.d.cts}

@@ -1,51 +1,4 @@
-import { H as Homography, V as Vec2, B as Box, Q as Quad, A as AffineMatrix, W as WarpStyle, a as WarpMesh } from './types-CwMPoRMU.cjs';
-
-/**
- * Perspective (projective) maps between quadrilaterals: Free Distort and Perspective in both the
- * vector and the image editor. Pure maths; degenerate or non-finite input gives `null` instead of
- * NaNs.
- *
- * Ported from ArtCraft (MIT OR Apache-2.0, © ArtCraft Team and contributors; see
- * THIRD_PARTY_NOTICES.md): pdfcraft `crates/geom/src/perspective.rs` (`Homography::from_points`,
- * `Homography::apply`, `solve8`, `order_quad`) and photocraft `crates/algo/src/transform.rs`
- * (`Homography::square_to_quad`, `rect_to_quad`, `inverse`, `mul`, `local_scale`, `front_side`,
- * `warp_output_bounds`, `convex_quad`).
- */
-
-/**
- * Gaussian elimination with partial pivoting on an 8×8 system (the 9th column of each row is the
- * right-hand side). Null when the system is singular.
- */
-declare function solve8(rows: readonly (readonly number[])[]): number[] | null;
-/** The image of `p`, or null where the map sends it to infinity. */
-declare function applyHomography(h: Homography, p: Vec2): Vec2 | null;
-/**
- * The projective map that takes each of `from` to the point at the same index of `to`. Null when
- * three of either set are collinear or a coordinate is not finite.
- */
-declare function homographyFromPoints(from: readonly Vec2[], to: readonly Vec2[]): Homography | null;
-/**
- * Whether `h` maps the whole convex quad `quad` without sending any of it through infinity (the
- * denominator keeps one sign over it): what a usable distortion needs.
- */
-declare function homographyKeepsQuad(h: Homography, quad: readonly Vec2[]): boolean;
-/**
- * The four corners in reading order for a y-down space: top-left, top-right, bottom-right,
- * bottom-left, whatever order they come in. Null unless they form a convex quadrilateral with a
- * non-negligible area.
- */
-declare function orderQuad(points: readonly Vec2[]): Vec2[] | null;
-/** The inverse map, or null for a singular one. */
-declare function invertHomography(m: Homography): Homography | null;
-/** An affine matrix (SVG order) as a homography. */
-declare function homographyFromAffine(m: AffineMatrix): Homography;
-/**
- * The map taking box `r`'s corners onto `quad` (TL, TR, BR, BL), exact for parallelograms (then
- * affine). Null for an empty box, a non-finite or degenerate quad, or a singular result.
- */
-declare function rectToQuad(r: Box, quad: readonly Vec2[]): Homography | null;
-/** Box `r`'s corners as a quad (TL, TR, BR, BL). */
-declare function boxQuad(r: Box): Quad;
+import { W as WarpStyle, a as WarpMesh, V as Vec2, B as Box } from './types-CwMPoRMU.cjs';
 
 /**
  * Warp geometry shared by the vector editor's envelopes and the image editor's Free Transform
@@ -162,4 +115,4 @@ declare function warpMeshEditPoints(m: WarpMesh): {
 /** The mesh's grid lines (patch borders) as cubics `[p0, p1, p2, p3]`. */
 declare function warpMeshGridCurves(m: WarpMesh): Vec2[][];
 
-export { warpPresetMesh as A, boxQuad as B, homographyFromAffine as C, invertHomography as D, rectToQuad as E, WARP_STYLES as W, WARP_STYLE_LABELS as a, type WarpPreset as b, applyHomography as c, dragWarpMeshPoint as d, evalWarpMesh as e, fitWarpMesh as f, removeWarpMeshSplitV as g, resizeWarpMesh as h, isValidWarpMesh as i, splitWarpMeshU as j, splitWarpMeshV as k, homographyFromPoints as l, mapWarpMeshPoints as m, homographyKeepsQuad as n, orderQuad as o, pullWarpMesh as p, identityWarpMesh as q, removeWarpMeshSplitU as r, solve8 as s, warpMeshControlBounds as t, warpMeshEditPoints as u, warpMeshGridCurves as v, warpMeshColumns as w, warpMeshParamAt as x, warpMeshRows as y, warpPresetGrid as z };
+export { type WarpPreset as W, WARP_STYLES as a, WARP_STYLE_LABELS as b, removeWarpMeshSplitV as c, dragWarpMeshPoint as d, evalWarpMesh as e, fitWarpMesh as f, resizeWarpMesh as g, splitWarpMeshV as h, isValidWarpMesh as i, identityWarpMesh as j, warpMeshControlBounds as k, warpMeshEditPoints as l, mapWarpMeshPoints as m, warpMeshGridCurves as n, warpMeshParamAt as o, pullWarpMesh as p, warpMeshRows as q, removeWarpMeshSplitU as r, splitWarpMeshU as s, warpPresetGrid as t, warpPresetMesh as u, warpMeshColumns as w };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.101.0",
+  "version": "0.103.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",
@@ -89,6 +89,11 @@
       "import": "./dist/image-editor/index.js",
       "require": "./dist/image-editor/index.cjs"
     },
+    "./paint-editor": {
+      "types": "./dist/paint-editor/index.d.ts",
+      "import": "./dist/paint-editor/index.js",
+      "require": "./dist/paint-editor/index.cjs"
+    },
     "./commands": {
       "types": "./dist/commands/index.d.ts",
       "import": "./dist/commands/index.js",

package/skills/README.md

@@ -15,6 +15,7 @@ that uses the tools can load the matching skill.
 | [`pixerate-chart`](pixerate-chart/SKILL.md) | Chart specs, data, series, presets, trendlines, Office and Mermaid charts. |
 | [`pixerate-diagram`](pixerate-diagram/SKILL.md) | Mermaid diagrams: nodes, edges, groups, layout. |
 | [`pixerate-image-editor`](pixerate-image-editor/SKILL.md) | Adjustments, adjustment layers, selections and masks. |
+| [`pixerate-paint-editor`](pixerate-paint-editor/SKILL.md) | Natural-media painting: paper and grain, dry-media brushes, the brush library, strokes as data, pigment mixing. |
 | [`pixerate-animation-editor`](pixerate-animation-editor/SKILL.md) | Vector animation: shots, commands, timing, Flair and Lottie. |
 | [`pixerate-video-editor`](pixerate-video-editor/SKILL.md) | Non-linear video editing: tracks, clips, transitions, export. |
 | [`pixerate-generation`](pixerate-generation/SKILL.md) | Planning, estimating and running paid media generation. |

package/skills/pixerate-image-editor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixerate-image-editor
-description: How to colour-correct, composite and retouch a photo in the Pixerate image editor through its agent tools - layers (pixel, adjustment, group and annotation layers with masks, clipping, blend modes, opacity and fill; merge, flatten, layer via copy, filters), live layer effects (shadows, glows, bevels, satin, overlays, strokes), base adjustments (exposure, contrast, white balance, saturation, blur), adjustment layers (curves, levels, hue/saturation, vibrance, color balance, black and white and more), selections (wand, color range, modify, refine edge) and masks, Free Transform (scale, rotate, skew, distort, warp), crop, rotate, flip, Mixer Brush, undo, PSD, histogram and previews. Use when asked to edit, grade, correct, brighten, crop, straighten or mask an image, add a shadow, glow or outline, transform or warp a layer, or open or save a PSD, or when get_adjustments, set_adjustments, list_layers, add_layer_effect, transform_layer, paint_stroke, select_by_color, import_psd or render_preview are available.
+description: description: How to colour-correct, composite and retouch a photo in the Pixerate image editor through its agent tools - layers (pixel, adjustment, group, annotation and smart object layers with masks, clipping, blend modes, opacity and fill; merge, flatten, filters), smart objects (non-destructive transforms, smart filters, linked contents, edit contents), live layer effects (shadows, glows, bevels, overlays, strokes), base adjustments, adjustment layers (curves, levels, hue/saturation and more), selections and masks, Free Transform (scale, rotate, skew, distort, warp), crop, rotate, flip, Mixer Brush, undo, PSD, histogram and previews. Use when asked to edit, grade, correct, crop, straighten or mask an image, add a shadow, glow or outline, transform or warp a layer, make a smart object, or open or save a PSD, or when get_adjustments, set_adjustments, list_layers, add_layer_effect, transform_layer, convert_to_smart_object, paint_stroke, select_by_color, import_psd or render_preview are available.
 ---
 
 # Image editor
@@ -12,9 +12,10 @@ its mask, opacity and blend mode) and every annotation is its own layer on top.
 shows the whole stack. Edits never touch the source pixels. The base controls edit the develop
 filter of the active pixel layer (the Background unless another pixel layer is active); base
 `blur` blurs that layer (or, in documents saved before layers with blur and adjustment layers,
-the output after the layers), and base `opacity` is the output's alpha. Pixel, annotation and
-group layers can carry live effects (shadows, glows, bevels, overlays, strokes). Also an optional
-selection and crop/rotate/flip. See `pixerate-agent-tools` for errors, namespacing and command
+the output after the layers), and base `opacity` is the output's alpha. Pixel, annotation, group
+and smart object layers can carry live effects (shadows, glows, bevels, overlays, strokes). A smart
+object places contents (pixels or a nested layer document) through a transform and smart filters,
+re-rendered from the contents on every change. Also an optional selection and crop/rotate/flip. See `pixerate-agent-tools` for errors, namespacing and command
 batching.
 
 - **Control ids** for base adjustments: `brightness`, `contrast`, `exposure`, `temperature`,
@@ -88,6 +89,33 @@ batching.
    rotation and move into one `transform_layer` call (or one matrix) instead of several.
 5. **Look**: `render_preview`, or `capture_view` at the edges; each call is one undo step.
 
+### Smart objects
+
+1. **Convert before repeated or uncertain changes**: `convert_to_smart_object` (one pixel layer, or
+   several siblings that nest as a layer document). A converted pixel layer looks exactly the same
+   and keeps its id; its filters become smart filters. From then on every transform and filter is
+   re-rendered from the contents, so scaling down and back up, or rotating twelve times, loses
+   nothing.
+2. **Read it**: `get_smart_object` gives the contents (size, kind, instances), the placement
+   (corners, warp, and scale / rotate in percent and degrees of the contents' own size) and the
+   smart filters with their ids.
+3. **Transform**: `set_smart_object_transform` sets the transform absolutely (scale 100 = the
+   contents' own size, `x`, `y` = where its centre goes; or `corners`, `matrix`, and a `warp` in
+   contents pixels, `null` to remove). `transform_layer`, `warp_layer`, `flip_layer` and
+   `rotate_layer_90` also work on a smart object, relative to its current placement, and never
+   degrade it. `offset_layer` moves it by whole pixels.
+4. **Filter non-destructively**: `add_smart_filter` (`develop` or `blur`, each with its own
+   `blend` and `opacity`; kinds can repeat), then `update_smart_filter`, `move_smart_filter`,
+   `remove_smart_filter` and `set_smart_filters_enabled`. `set_smart_filter_mask` limits where the
+   filters show; paint it with `paint_stroke` / `fill_pixels` `channel: "filter-mask"`.
+5. **Contents**: `copy_smart_object` with `linked: true` shares the contents (edit once, both
+   change), `linked: false` makes them independent. `edit_smart_object_contents` opens the
+   contents as their own document: every tool then works inside them until
+   `close_smart_object_contents` (`save: false` discards). `replace_smart_object_contents` swaps
+   in a new image for every linked instance; `export_smart_object_contents` returns the file.
+6. **Finish**: `rasterize_smart_object` only when the user wants plain pixels to paint on; the
+   placement and filters are then gone.
+
 ### Layer effects
 
 1. **Effects are live and per layer**: drop and inner shadows, outer and inner glows,
@@ -224,6 +252,12 @@ batching.
   which `bounds` in the result shows.
 - **Unlink a mask** (`set_layer_mask_properties` `linked: false`) when the pixels should move
   under a fixed mask (a picture inside a frame); link it again afterwards.
+- **Smart objects for anything you may scale again.** Convert first, then transform as often as
+  needed; set exact sizes with `set_smart_object_transform` `scaleX` / `scaleY` (percent of the
+  contents) rather than chaining relative scales. Prefer smart filters over layer filters when
+  the user may want to mask, blend or reorder them later.
+- **Linked or not**: duplicate a smart object `linked: true` for repeated elements that must stay
+  identical (a logo placed twice); use `linked: false` when the copies will be edited apart.
 - **Merge Down only onto an opaque, 100 % lower layer** when the result must look the same:
   the merged layer keeps the lower layer's opacity and blend, so a faded lower layer fades the
   merged content too, and a blend mode on the upper layer stops seeing what was below the lower
@@ -238,7 +272,7 @@ batching.
 | `get_adjustments` | Read the current state: `values` by control id, `process` version (1 or 2), and `layers` bottom to top with id, kind, params, opacity, blend, enabled and mask. Call first, and to find layer ids. |
 | `list_controls` | Get every base control (id, label, section, min, max, step, default, `requiresProcess`), each layer kind's settable controls (plus `opacity`), the blend mode ids and the `layers.<layerId>.<controlId>` path format. Call once per session before writing. |
 | `get_selection` | Read the active selection: `empty`, `bounds` (natural pixels), `area` in pixels, `percent` of the image and a description. Check it after every select or modify step and before masking: a wand that covered 90% of the image is the wrong selection. |
-| `list_layers` | Read the layer stack bottom to top as a tree: id, type (`pixel`, `adjustment`, `group`, `annotation`), name, document `bounds` of pixel layers, visibility, opacity, `fillOpacity`, blend, `clipped`, locks, a `mask` summary, an `effects` summary (master switch, scale, effect ids and kinds), pixel-layer `filters` (the Background's `develop` filter is the base adjustments), adjustment `kind` and `params`, group `children`, and which layer is `active`. Call it to understand a document with more than the Background before changing it; adjustment layer ids work with every adjustment-layer tool. |
+| `list_layers` | Read the layer stack bottom to top as a tree: id, type (`pixel`, `adjustment`, `group`, `annotation`, `smart`; smart objects add their `contents`, `smartFilters` and `filterMask`), name, document `bounds` of pixel layers, visibility, opacity, `fillOpacity`, blend, `clipped`, locks, a `mask` summary, an `effects` summary (master switch, scale, effect ids and kinds), pixel-layer `filters` (the Background's `develop` filter is the base adjustments), adjustment `kind` and `params`, group `children`, and which layer is `active`. Call it to understand a document with more than the Background before changing it; adjustment layer ids work with every adjustment-layer tool. |
 | `list_layer_effects` | Read one layer's effects: `enabled` (master switch), `scale` (Scale Effects), `margin` (px they reach beyond the shape), `fromPsd`, and every effect with `id`, `kind`, `label` and all its settings. Also returns the `globalLight`, the `patterns` pattern effects can use and the effect `kinds`. Call before changing effects you did not add. |
 | `get_image_info` | Read the geometry: source `image` size, `crop` box (source pixels, or null), `rotation` degrees, `flipH` / `flipV`, the `output` size after crop and rotation, the layer count and `canUndo` / `canRedo`. Call before cropping or selecting so coordinates are right. |
 | `get_histogram` | Judge exposure numerically: per channel and luminance `mean`, `p1` and `p99` (0..255), and `clipping` percent at pure black and white per channel. Reads the last render, so call `render_preview` first. `bins` (16, 32, 64 or 256) adds the counts. Cheaper than another image for checking a tonal change. |
@@ -246,6 +280,8 @@ batching.
 | `inspect_psd` | Read a PSD / PSB (`data` base64) without opening it: size, `depth`, `colorMode`, `resolution`, every layer bottom first with `psdKind`, the `type` it would become and `status` (`mapped`, `approximated`, `dropped`) with `notes`, and the import `warnings`. Call before `import_psd`. |
 | `export_psd` | Save the document as an 8-bit RGB PSD (PSB above 30000 px) with layers, groups, adjustment layers and masks. Returns `data` (base64), `size` in bytes, `psb` and `warnings` (crop or rotation not applied, filters and depth masks baked, annotations rasterized or left out, Pigment blends written as Normal). Changes nothing. |
 | `get_transform_frame` | Before a transform: what it would move (`content`, `moved`: pixels, mask, selection), its `frame` (document bounds of the content), `corners` (top-left, top-right, bottom-right, bottom-left) and `center`. `meshColumns` / `meshRows` also return an identity warp `mesh` over the frame to edit for `warp_layer`. Changes nothing. |
+| `get_smart_object` | Read a smart object: `contents` (`id` shared by linked instances, `name`, `kind` raster or document, `width` / `height`, `decoded`, `fileType`, `linkedPath`, `instances`), `placement` (`corners`, `warp` in contents px, `interpolation`, and when `affine` the `scaleX` / `scaleY` in percent of the contents, `rotate`, `skewX`, `center`, `bounds`) and `smartFilters` (`enabled`, `filters` bottom to top with ids, settings, `blend`, `opacity`; kind `psd` is a Photoshop filter kept but not drawn; the filter `mask`). Call before changing a smart object. |
+| `export_smart_object_contents` | Export Contents: the contents as a file (`name`, `mimeType`, `byteLength`, `base64`): the file they came from while unedited, else a PNG (raster) or PSD / PSB (nested document). Changes nothing. |
 | `capture_view` | Inspect detail in natural image pixels (the space of `get_selection` and `select_region`, before crop and rotation): `region` `content` (whole image, default), `selection` or `rect`; small regions are enlarged up to 8× with hard pixel edges, so a 64 px rect shows real pixels. `includeOverlays: true` shades unselected pixels and outlines the crop: use it to check a mask's edge before `apply_selection_as_mask`. Returns the `rect` and `scale`. Use `render_preview` for the final framed result. |
 
 ### Write
@@ -267,7 +303,7 @@ batching.
 | `flip_image` | Mirror the image `horizontal` (left-right) or `vertical`. Avoid flipping images with text, logos or recognisable places. |
 | `undo_image` | Undo the last edit (one tool call is one step). Returns `canUndo` / `canRedo`. |
 | `redo_image` | Redo the edit you just undid. |
-| `set_active_layer` | Make a layer active (`layerId`) and choose the paint `target` (`pixels` or `mask`). Base sliders then edit that pixel layer's develop filter. Not an undo step. Returns the layer. |
+| `set_active_layer` | Make a layer active (`layerId`) and choose the paint `target` (`pixels`, `mask`, or a smart object's `filter-mask`). Base sliders then edit that pixel layer's develop filter. Not an undo step. Returns the layer. |
 | `add_pixel_layer` | Add a pixel layer above the active layer (or at `aboveId` / `belowId` / `parentId` / `index`): empty, `color` `#rrggbb[aa]` over the canvas, or `image` (PNG data URL or base64; other formats only in a browser) at `x`, `y`; with `name`, `opacity`, `blend`. Returns the layer with its id and bounds. |
 | `duplicate_layer` | Copy a layer (groups with their children) directly above it, e.g. before a destructive change. Returns the copy. |
 | `remove_layer` | Delete a layer or group (refused when locked). Prefer hiding with `set_layer_properties`. Returns the remaining top-level ids. |
@@ -279,8 +315,8 @@ batching.
 | `merge_down` | Composite a layer onto the pixel layer below it (masks, fill and filters baked). Destructive; see Best practices. Returns the merged layer. |
 | `merge_visible` | Composite all visible top-level layers into one layer; hidden ones stay. Destructive. |
 | `flatten_image` | Composite everything visible into one Background; hidden layers are discarded. Destructive; do it only when asked. |
-| `offset_layer` | Move a pixel layer and its linked mask to `x`, `y` or by `dx`, `dy` (integers, document px; an unlinked mask stays put). Refused when its position is locked. Returns the offset and bounds. |
-| `transform_layer` | Free Transform a pixel layer (with its linked mask), the selected pixels (`content` `selection`), a copy of them on a new layer (`selection-copy`) or an unlinked mask (`channel` `mask`). Give the transform one way: `scaleX` / `scaleY` (percent), `rotate`, `skewX` / `skewY` (degrees), `dx` / `dy` (px) about `reference` (an anchor or `{x, y}`, default `center`); or `matrix` `[a, b, c, d, e, f]`; or `corners` (the frame's new corners: distort / perspective, kept convex). `interpolation` nearest, bilinear or bicubic (default). One undo step. Returns `layerId` (the new layer for a copy), `moved`, `frame`, `corners` and the new `bounds`. |
+| `offset_layer` | Move a pixel layer or smart object and its linked mask to `x`, `y` (a smart object's top-left corner) or by `dx`, `dy` (integers, document px; an unlinked mask stays put). Refused when its position is locked. Returns the offset and bounds. |
+| `transform_layer` | Free Transform a pixel layer or smart object (with its linked mask; a smart object re-renders from its contents and always moves whole), the selected pixels (`content` `selection`), a copy of them on a new layer (`selection-copy`) or an unlinked mask (`channel` `mask`). Give the transform one way: `scaleX` / `scaleY` (percent), `rotate`, `skewX` / `skewY` (degrees), `dx` / `dy` (px) about `reference` (an anchor or `{x, y}`, default `center`); or `matrix` `[a, b, c, d, e, f]`; or `corners` (the frame's new corners: distort / perspective, kept convex). `interpolation` nearest, bilinear or bicubic (default). One undo step. Returns `layerId` (the new layer for a copy), `moved`, `frame`, `corners` and the new `bounds`. |
 | `warp_layer` | Warp the same targets as `transform_layer` through a preset (`style` arc … twist, `bend` −100..100 default 50, `horizontal` / `vertical` distortion, `orientation`) or a `mesh` (`columns`, `rows`, (3·columns + 1) × (3·rows + 1) `points` in document px; start from `get_transform_frame`'s identity mesh). One undo step. Returns the new `bounds`. |
 | `transform_selection` | Transform only the selection outline (Transform Selection): the same numeric fields, `matrix` or `corners` as `transform_layer`, over the selection's bounds. Pixels do not change. Needs a selection. Returns the new selection `bounds`. |
 | `flip_layer` | Mirror a pixel layer, its selected pixels or a copy (`content`) `horizontal` or `vertical` about the frame's centre, exactly. For the whole image use `flip_image`. Returns the new `bounds`. |
@@ -290,7 +326,20 @@ batching.
 | `apply_layer_mask` | Bake a pixel layer's mask into its alpha and remove it. Destructive. |
 | `remove_layer_mask` | Delete a mask without applying it; disable it instead to keep it. |
 | `layer_via_copy` | Copy the selected pixels of a pixel layer (default the active one) to a new layer above it; `cut: true` removes them from the source. Needs a selection. Returns the new layer. |
-| `rasterize_layer` | Turn an annotation layer into pixels (same id and properties; browser only) or bake a pixel layer's develop / blur filters into its pixels. Do it before painting over an annotation, or when the user wants the filters fixed. Destructive. |
+| `rasterize_layer` | Turn an annotation layer into pixels (same id and properties; browser only), a smart object into a pixel layer (as `rasterize_smart_object`), or bake a pixel layer's develop / blur filters into its pixels. Do it before painting over an annotation, or when the user wants the filters fixed. Destructive. |
+| `convert_to_smart_object` | Convert sibling `layerIds` (default the active layer) to one smart object at the top one's position, optional `name`. One pixel layer keeps its id, look and properties (filters become smart filters); several layers, groups or adjustments nest as a layer document. Returns the `layer` and the `smartObject` summary. |
+| `rasterize_smart_object` | Turn a smart object into a pixel layer holding what it shows now (smart filters baked; same id, mask, effects, opacity, blend). Destructive: the contents and filters are gone. Returns the layer. |
+| `set_smart_object_transform` | Set a smart object's transform absolutely: `corners`, `matrix` (contents → document), or `scaleX` / `scaleY` (percent of the contents), `rotate`, `skewX`, `skewY`, `x`, `y` (where the contents' centre goes; unset numbers keep their values); `warp` preset or mesh in contents px, `null` removes it; `interpolation`. Re-renders from the contents. Returns `placement`, `masksMoved` and `bounds`. |
+| `replace_smart_object_contents` | Replace Contents with `image` (PNG data URL or base64; other formats in a browser) for the smart object and every linked instance; each keeps its scale and rotation about the centre. Returns `contentsId`, the new size and `layerIds` changed. |
+| `copy_smart_object` | Duplicate a smart object above it: `linked: true` shares the contents (edits show in both), `linked: false` (default, New Smart Object via Copy) gives independent contents. Returns the copy and its `contentsId`. |
+| `edit_smart_object_contents` | Open a smart object's contents as their own document (raster contents as one pixel layer, "Layer 0") with their own undo; all tools then act inside them. Returns the size, `layerIds`, `layers` and `editing` (the open path). Always close it. |
+| `close_smart_object_contents` | Close the innermost open contents: `save` true (default) writes them back and re-renders every linked instance (one undo step), false discards. Returns `layerId`, `changed`, `layerIds` and what is still `editing`. |
+| `add_smart_filter` | Add a `develop` (brightness … tint) or `blur` (`radius`) smart filter with its own `blend` and `opacity`, at `index` (default top); kinds may repeat. Returns the `filter` (with id) and the stack. |
+| `update_smart_filter` | Change one smart filter's settings, `enabled`, `blend` or `opacity` (`filterId` from `get_smart_object`); kind `psd` filters take only the last three. Returns the filter and the stack. |
+| `remove_smart_filter` | Remove one smart filter (the filter mask goes with the last one). Returns the stack. |
+| `move_smart_filter` | Move a smart filter to `index` (0 = bottom, applied first). Returns the stack. |
+| `set_smart_filters_enabled` | Switch the whole smart filter stack off or on (`enabled`); each filter keeps its own flag. Returns the stack. |
+| `set_smart_filter_mask` | Set the smart filter mask `from` `reveal-all`, `hide-all`, `selection`, `none` (remove) or `keep` (properties only), with `density`, `feather`, `enabled`, `linked`. Paint it with `channel: "filter-mask"`. Returns the mask summary. |
 | `add_layer_filter` | Add a live `develop` (brightness … tint) or `blur` (`radius`) filter to a pixel layer; one of each kind. Returns the filters with ids. |
 | `update_layer_filter` | Change a filter's values (`filterId` from `list_layers`). Returns the filters. |
 | `remove_layer_filter` | Remove a filter. Returns the remaining filters. |
@@ -327,8 +376,17 @@ batching.
 - `merge_down`, `merge_visible` and `flatten_image` merge annotation layers only in a browser
   (they need a canvas); elsewhere they fail and say so.
 - `paint_stroke`, `fill_pixels` and `clear_pixels` need a visible pixel layer (or a layer with a
-  raster mask and `channel: "mask"`); adjustment, group and annotation layers can only be
-  painted through their masks. A layer with `locks.pixels` refuses paint.
+  raster mask and `channel: "mask"`); adjustment, group, annotation and smart object layers can
+  only be painted through their masks (and a smart object through `channel: "filter-mask"`).
+  To paint a smart object's pixels, `edit_smart_object_contents` or rasterize it. A layer with
+  `locks.pixels` refuses paint.
+- While contents are open (`edit_smart_object_contents`), `list_layers` and every tool see the
+  contents, not the document, and `export_psd` / saving write the document without the open
+  edits. Close with `close_smart_object_contents` before anything else.
+- Smart filters run over the canvas, like layer filters: a blur clamps at the canvas edge, and a
+  smart object is drawn only up to 512 px beyond the canvas. `get_transform_frame` on a smart
+  object returns the contents' rectangle (contents px) as the `frame`, and a warp `mesh` in
+  contents px.
 - `mix_colors` predicts a mix; it does not paint. To paint the mix, pass `blend: "pigment"` to
   `paint_stroke` (in `brush`) or `fill_pixels`, or set it on a layer.
 - `pigment` has no PSD equivalent: `export_psd` writes those layers as Normal (the merged image

package/skills/pixerate-paint-editor/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: pixerate-paint-editor
+description: How to make a picture in the Pixerate paint editor (natural media in the spirit of Painter and Rebelle) through its agent tools - canvas and paper (generated grain, depth, colour, families from cold pressed watercolour to canvas and gesso), layers, dry-media brushes (pencil, pastel, charcoal, airbrush, marker, ink, erasers, blender, smudge, Mixer Brush) with pressure, tilt, barrel rotation and velocity, the brush library, strokes as data that replay and vary, pigment colour mixing, previews and PNG, JPEG, WebP, PSD and JSON output. Use when asked to paint, sketch, draw, shade, block in, texture a layer with paper grain, mix paint colours, vary or repeat strokes, or when paint_stroke, set_paper, list_brushes, replay_strokes, fill_layer or mix_colors are available.
+---
+
+# Paint editor
+
+A canvas (pixels and dpi) over a **paper**, with a stack of layers (pixel layers and groups with
+opacity, blend modes, clipping and locks) on top. The paper is generated from a pattern and a
+seed: its grain is a height map (peaks and valleys) that grain-responsive brushes follow, and it
+is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y down. See
+`pixerate-agent-tools` for errors, namespacing and batching.
+
+- **Brushes** are library presets (`list_brushes`): a tip from the shared engine (size,
+  hardness, spacing, angle, roundness, opacity, flow, blend), a **grain** response, pen dynamics
+  (pressure, tilt, velocity, jitter), a **rotation** mode (`fixed`, `stroke`, `barrel`) and an
+  engine: `dab` (most media), `eraser`, or `mixer` (Mixer Brush, blender, smudge: they pick up and
+  move paint already on the layer).
+- **Grain**: a brush's grain response times the paper's `depth` decides how much light pressure
+  skips the valleys. Pencil, pastel and charcoal are grainy; airbrush, marker and ink are not.
+- **Strokes are data.** Every stroke is recorded (brush, colour, raw points, seed, symmetry
+  copies) and gets a `strokeId`. `replay_strokes` paints recorded strokes again, exactly or
+  varied. That is the main way an agent should make many similar marks.
+- **Undo**: one tool call that changes the painting is one undo step (`undo_paint`). Brush,
+  colour, view, hand and the Mixer Brush load are editor state, not undo steps.
+
+## Working method
+
+1. **Read.** `get_canvas_info` (size, paper, active layer, active brush, colour), then
+   `list_layers`. `render_preview` to see the painting before changing it.
+2. **Choose the ground.** Pick a paper that suits the medium (`list_papers`, `set_paper`, or
+   `new_canvas` with `paper`): cold pressed or rough for broken, sparkling texture, sanded pastel
+   paper for pastel, charcoal paper for charcoal, cotton canvas or gesso for painterly work,
+   smooth bristol for ink. Set `depth` for how much texture you want.
+3. **Block in big shapes first.** Put each pass on its own layer (`add_layer` with a name).
+   `fill_layer` gives a ground colour (flat) or a tonal layer that catches the grain
+   (`grain` 0.6..1, `pressure` 0.2..0.6). Paint large masses with a big soft pastel or airbrush
+   in a few long `paint_stroke`s rather than many small ones.
+4. **Mix colours before painting.** `mix_colors` predicts what paints mixed in given parts look
+   like (Kubelka-Munk: blue and yellow make green, white tints rather than greys). Use the result
+   as the stroke `color`. `set_color` makes it the default.
+5. **Refine** with smaller brushes on new layers: pencil and ink for line, charcoal for value,
+   blender or smudge to soften edges, the Mixer Brush to blend wet into wet.
+6. **Repeat and vary instead of drawing every mark.** Paint one good stroke, then
+   `replay_strokes` it with `dx` / `dy`, `rotate`, `scale`, `flipX`, `color`, `brushId` and
+   `repeat` for hatching, grass, foliage, rows, fans or spirals, in one undo step.
+7. **Check** with `render_preview` after each block of work, not after each stroke.
+   `pick_color` reads exact values. Undo what made it worse.
+8. **Deliver**: `export_image` (PNG, or JPEG / WebP in a browser), `export_psd` for Photoshop,
+   `save_document` to keep the painting with its strokes.
+
+## Best practices
+
+- **Big to small, dark to light (or light to dark), one decision per layer.** Name layers by
+  purpose ("Underpainting", "Shadows", "Line"). Lower a layer's `opacity` instead of repainting.
+- **Pressure is your value control** on grainy media: points with `pressure` 0.2..0.4 give
+  texture-catching, broken marks; 0.8..1 fills the grain. Vary pressure along a stroke (swell in
+  the middle, lighten at the ends) for natural marks.
+- **Give points a time `t`** (milliseconds, about 8..16 ms apart for natural speed) when using an
+  ink or brush pen: velocity dynamics thin fast strokes. Without `t` there is no velocity effect.
+- **Tilt** (`altitude` near 0.3..0.6 radians with an `azimuth`) turns a pencil into broad side
+  shading; upright points draw a fine line.
+- **Space points** about a third of the brush size apart or closer; the brush fills in dabs
+  between them. Long smooth curves need more points than straight lines.
+- **Use `rotation: "stroke"`** for flat tips (pastel, charcoal, chisel marker) so the mark turns
+  with the path; `fixed` for calligraphic nibs.
+- **Blend with flow, not opacity**: blender and smudge work best at flow 0.3..0.6; at full flow
+  the Mixer Brush paints only its own colour.
+- **Pigment for paint, multiply for markers**: tip `blend: "pigment"` mixes subtractively on the
+  canvas; `multiply` darkens where marker strokes overlap. Pigment layers are written as Normal
+  to PSD (the export warns).
+- **Save brushes you build** (`set_brush` then `save_brush`), and share them with
+  `export_brushes` / `import_brushes`.
+
+## Tool reference
+
+### Canvas and paper
+
+| Tool | Use |
+| --- | --- |
+| `get_canvas_info` | Read the canvas size and dpi, paper (preset, colour, depth), active layer, layer count, active brush id, colours, view, hand, number of recorded strokes, undo / redo labels and the blend modes. Call first. |
+| `new_canvas` | Start over with a blank canvas: one empty layer over the paper. `width`, `height` (1..16384 px), `dpi`, `paper` preset id; missing ones keep the current values. Undo brings the old painting back. Returns the size, paper and layer id. |
+| `set_canvas` | Resize the canvas (pixels stay put, anchored top-left) or change its `dpi`. Returns the canvas. |
+| `list_papers` | Read the paper library: id, name, family, grain pattern, colour, depth and the wet-media properties (absorption, permeability, roughness, stored for later wet media). Call before `set_paper`. |
+| `get_paper` | Read every setting of the current paper (pattern, seed, scale, tiling, depth, shading, dry and wet tuning). |
+| `set_paper` | Change the paper: `preset`, then any of `color`, `depth` (0..1), `scale` (0.25..8), `seed` (another sheet), `pattern`, `tiling`, `shading`, `dry` / `wet` tuning (`contrast` 0..3, `invert`). Affects new strokes' grain and how the paper shows; strokes already painted keep their pixels. Returns the paper. |
+
+### Layers
+
+| Tool | Use |
+| --- | --- |
+| `list_layers` | Read the layers top first: id, name, type (`pixel` / `group`), visible, opacity, blend, clipped, locks, `active`, painted `bounds` (null when empty), parent and depth. |
+| `add_layer` | Add an empty pixel layer (or `type: "group"`) above the active layer, above `aboveId`, or at the top of group `parentId`; it becomes active. Returns the layer. Put each pass of a painting on its own layer. |
+| `update_layer` | Change `name`, `visible`, `opacity` (0..1), `blend`, `clipped` (clip to the layer below) or `locks` (`pixels`, `transparency`: paint only where there is paint, `position`, `all`). Returns the layer. |
+| `set_active_layer` | Make a layer the default target of strokes, fills and clears. Editor state. |
+| `remove_layer` | Delete a layer (a group with its children). Prefer hiding it when the user may want it back. |
+| `duplicate_layer` | Copy a layer directly above it (the copy becomes active): try a risky change on a copy. |
+| `move_layer` | Reorder: `index` among siblings (0 = bottom), optionally into `parentId` (or `null` for the top level). |
+| `merge_layer_down` | Merge a pixel layer into the pixel layer directly below (which keeps its settings). |
+| `fill_layer` | Fill a pixel layer with `color` at `opacity`: flat, or with `grain` 0..1 following the paper grain (`pressure` 0..1 decides how far into the valleys, default 0.5). The fastest way to lay a ground or a textured tone. Returns the bounds. |
+| `clear_layer` | Remove every pixel of a layer. Returns the bounds that were cleared. |
+
+### Brushes
+
+| Tool | Use |
+| --- | --- |
+| `list_brushes` | Read the library (built-in and saved): id, name, category, engine, size, grain response, rotation, `builtin`; plus the active brush id and whether it is edited. |
+| `get_brush` | Read every setting of a brush, or of the active brush as edited (no `id`). Read before changing a brush you did not build. |
+| `set_brush` | Choose the active brush (`id`) and / or change it: `tip` (size px, hardness, spacing, angle, roundness, opacity, flow, smoothing, pressureSize, pressureOpacity, blend), `grain`, `pressureSmoothing`, `rotation`, `dynamics` (minSize, pressureFlow, tiltSize, tiltRoundness, tiltOpacity, velocitySize, velocityOpacity, jitters, scatter), `mixer`, `loadsColor`. Editor state. Returns the brush. |
+| `save_brush` | Store the active brush in the user library under `id` (lowercase, digits, dashes) and `name`. Built-in ids are refused. |
+| `remove_brush` | Delete a user brush. Built-in brushes cannot be removed. |
+| `export_brushes` | Get a brush library file (JSON) of `ids`, or of every user brush. |
+| `import_brushes` | Add the brushes of a library file to the user library; taken ids are skipped unless `replace`. Returns `added`, `skipped`, `problems`. |
+| `render_brush_thumbnail` | See what a brush does: a PNG of a test stroke (S-curve, pressure swelling and fading) on the current paper. Cheaper than painting and undoing. |
+
+### Colour
+
+| Tool | Use |
+| --- | --- |
+| `mix_colors` | Predict a paint mix: `colors` with `weight` parts (and optional tinting `strength`). Returns `mixed` (#rrggbb, Kubelka-Munk) and the plain RGB average for comparison. Changes nothing. Use it to choose stroke colours. |
+| `set_color` | Set the default paint `color` (and `secondaryColor`). |
+| `pick_color` | Read the colour at `x`, `y`: of the painting with its paper, or of one layer (with alpha). |
+| `get_mixer_brush` | Read what the Mixer Brush carries: `reservoir`, `amount` left, `pickup`. |
+| `load_mixer_brush` | Fill the Mixer Brush reservoir with a colour (keeps its pickup). |
+| `clean_mixer_brush` | Empty the pickup well (and with `emptyReservoir` the paint). |
+
+### Painting and strokes
+
+| Tool | Use |
+| --- | --- |
+| `paint_stroke` | Paint one stroke through `points` (document px; `pressure` 0..1, `t` ms, `tiltX` / `tiltY` or `altitude` / `azimuth`, `twist`) with `brushId` (default the active brush), optional per-stroke `brush` changes, `color`, `layerId`, `seed`. Returns `layerId`, `bounds`, `dabs`, `strokeId` and for the mixer engine its `mixerLoad`. Refused on locked, hidden or group layers, with the fix in the message. |
+| `list_strokes` | Read the recorded strokes, oldest first (default the last 100): id, layer, brush, colour, point count, seed, bounds. With `ids`, their points too. |
+| `replay_strokes` | Paint recorded `strokeIds` again: exactly, or varied by `dx` / `dy` (px), `rotate` (degrees clockwise), `scale` (brush size follows), `flipX`, `origin`, `pressureScale`, `color`, `brushId`, `layerId`, `repeat` (each copy applies the variation again). One undo step. Returns the new stroke ids, bounds and layers. |
+| `undo_paint` | Undo the last step. Returns what was undone and what is next. |
+| `redo_paint` | Redo the step just undone. |
+
+### View, input and output
+
+| Tool | Use |
+| --- | --- |
+| `set_view` | Rotate (degrees), mirror or zoom the view, or `reset` it. View state only: pixels never resample. Mirroring is a quick check of a drawing's proportions. |
+| `set_hand` | Say which hand holds the pen (`right` / `left`) for palm rejection. |
+| `render_preview` | See the painting (or `layerIds`) as a PNG, longest side `maxSide` (16..2048, default 512), with or without the `paper`. Render after each block of work. |
+| `export_image` | Export PNG (default), JPEG or WebP as base64, at `quality` and `scale` (≤ 1); `paper: false` gives a transparent PNG. JPEG / WebP need a browser canvas. |
+| `export_psd` | Export a PSD with every layer, the paper as a locked bottom layer, and the composite. Returns base64, size, `psb` and `warnings`. |
+| `save_document` | Get the document JSON (canvas, paper, layers as PNG data URLs, strokes unless `strokes: false`). |
+| `open_document` | Open a saved document JSON, replacing the painting and clearing the undo history. Returns the canvas, layers and any `problems`. |
+
+## Pitfalls
+
+- **Stroke-by-stroke drawing is slow and expensive.** Do not draw a detailed picture point by
+  point. Block in with fills and big strokes, then replay and vary a few good strokes.
+- **A hidden or locked layer refuses paint**: show it (`update_layer visible true`) or unlock it.
+  `transparency` lock is not an error: paint only lands where the layer already has paint.
+- **Depth 0 means no grain** whatever the brush; grainy media then look smooth. Smooth bristol
+  has depth 0.
+- **Grain is fixed to the document**, not to the layer: moving content does not move the grain,
+  and two strokes on the same spot catch the same peaks.
+- **Big soft brushes at full flow look flat.** Lower `flow` (airbrush 0.05..0.15) and build up.
+- **JPEG and WebP need a browser**; in Node use PNG. Exports never upscale (`scale` ≤ 1).
+- **Recorded strokes are kept in saved documents**; `save_document` with `strokes: false` when
+  only the pixels matter (smaller JSON).