@pixerate/editor 0.200.0 → 0.202.0

package/dist/paint-editor/index.js

@@ -6213,6 +6213,49 @@ function withPaintPlayback(provider, options) {
   };
 }
 
+// src/paint-editor/hosted.ts
+function shiftAt(value, keys, dx, dy) {
+  if (value === null || typeof value !== "object") return value;
+  if (keys.length === 0) {
+    if (Array.isArray(value)) return value;
+    const o = { ...value };
+    if (typeof o.x === "number") o.x += dx;
+    if (typeof o.y === "number") o.y += dy;
+    return o;
+  }
+  const [head, ...rest] = keys;
+  const each = head.endsWith("[]");
+  const key = each ? head.slice(0, -2) : head;
+  const inner = key === "" ? value : value[key];
+  if (inner === void 0) return value;
+  const next = each ? Array.isArray(inner) ? inner.map((v) => shiftAt(v, rest, dx, dy)) : inner : shiftAt(inner, rest, dx, dy);
+  if (key === "") return next;
+  return Array.isArray(value) ? value : { ...value, [key]: next };
+}
+var shiftAll = (value, paths, dx, dy) => paths.reduce((v, p) => shiftAt(v, p === "" ? [] : p.split("."), dx, dy), value);
+var toDocument = (value, paths, origin) => shiftAll(value, paths, -origin.x, -origin.y);
+var fromDocument = (value, paths, origin) => shiftAll(value, paths, origin.x, origin.y);
+function hostedText(text) {
+  return text.replace(/\ba document pixel\b/g, "a canvas point").replace(/\bdocument pixels\b/g, "canvas coordinates").replace(/\bDocument ([xy])\b/g, "Canvas $1").replace(/\bdocument ([xy])\b/g, "canvas $1");
+}
+function hostedSchema(schema) {
+  if (Array.isArray(schema)) return schema.map(hostedSchema);
+  if (schema === null || typeof schema !== "object") return schema;
+  const out = {};
+  for (const [k, v] of Object.entries(schema)) out[k] = k === "description" && typeof v === "string" ? hostedText(v) : hostedSchema(v);
+  return out;
+}
+function lazyController(get) {
+  return new Proxy({}, {
+    get(_, key) {
+      const target = get();
+      const value = Reflect.get(target, key, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+    has: (_, key) => Reflect.has(get(), key)
+  });
+}
+
 // src/paint-editor/sticker-tools.ts
 var READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
@@ -6226,6 +6269,7 @@ function createPaintStickerTools(c) {
       description: "Lists a layer\u2019s stickers bottom first: id, stamp, x, y (centre, document pixels), size (diameter px), rotation (degrees clockwise), color, opacity. Empty for a layer without stickers. Changes nothing.",
       inputSchema: { type: "object", properties: { layerId: LAYER_ID }, additionalProperties: false },
       annotations: { title: "List stickers", ...READ },
+      coordinates: { out: ["stickers[]"] },
       handler: ({ layerId }) => ({ layerId: layerId ?? c.document.activeLayerId, stickers: c.listStickers(layerId) })
     },
     {
@@ -6249,6 +6293,7 @@ function createPaintStickerTools(c) {
         additionalProperties: false
       },
       annotations: { title: "Change a sticker", ...WRITE },
+      coordinates: { in: [""], out: [""] },
       handler: ({ layerId, id, ...update }) => c.updateSticker(layerId, id, update)
     },
     {
@@ -6304,6 +6349,7 @@ var RECT = {
   required: ["x", "y", "width", "height"],
   additionalProperties: false
 };
+var STENCIL_POSITIONS = ["from", "to", "center", "rect", "points[]"];
 var PNG = { type: "string", minLength: 1, description: "The image as a PNG, base64 or a data:image/png URL." };
 var tracingInfo = (t) => t ? { width: t.width, height: t.height, rect: t.rect, opacity: t.opacity, visible: t.visible, sampleColors: t.sampleColors } : null;
 var refInfo = ({ src: _s, ...r }) => r;
@@ -6332,6 +6378,7 @@ function createPaintGuideTools(c) {
       description: "Reads the painting guides: symmetry (mode, centre, rotation, segments, mirror, and how many copies each stroke paints), the perspective guide (vanishing points, snap), the tracing image (size, placement, opacity, visibility, colour sampling), the reference images and the stencils (id, kind, mode, geometry).",
       inputSchema: EMPTY,
       annotations: { title: "Get the painting guides", ...READ2 },
+      coordinates: { out: ["symmetry.center", "perspective.points[]", "tracing.rect", ...STENCIL_POSITIONS.map((p) => `stencils[].${p}`)] },
       handler: () => {
         const g = guides();
         return { symmetry: { ...g.symmetry, copies: symmetryCopies(g.symmetry).length }, perspective: g.perspective, tracing: tracingInfo(g.tracing), references: g.references.map(refInfo), stencils: g.stencils };
@@ -6353,6 +6400,7 @@ function createPaintGuideTools(c) {
         additionalProperties: false
       },
       annotations: { title: "Set mirror or kaleidoscope painting", ...SET },
+      coordinates: { in: ["center"], out: ["center"] },
       handler: (a) => {
         const s = c.setSymmetry(a);
         return { ...s, copies: symmetryCopies(s).length };
@@ -6372,6 +6420,7 @@ function createPaintGuideTools(c) {
         additionalProperties: false
       },
       annotations: { title: "Set the perspective guide", ...SET },
+      coordinates: { in: ["points[]"], out: ["points[]"] },
       handler: (a) => c.setPerspective(a)
     },
     {
@@ -6390,6 +6439,7 @@ function createPaintGuideTools(c) {
         additionalProperties: false
       },
       annotations: { title: "Set a tracing image", ...WRITE2 },
+      coordinates: { in: ["rect"], out: ["rect"] },
       handler: (a) => tracingInfo(c.setTracingImage(a))
     },
     {
@@ -6407,6 +6457,7 @@ function createPaintGuideTools(c) {
         additionalProperties: false
       },
       annotations: { title: "Change the tracing image", ...SET },
+      coordinates: { in: ["rect"], out: ["rect"] },
       handler: (a) => tracingInfo(c.updateTracing(a))
     },
     {
@@ -6700,6 +6751,7 @@ function createPaintGuideTools(c) {
       description: "Lays a stencil on the canvas: a ruler (straight edge to draw along) or an arc (circle or part of one) that pointer and agent strokes starting near it follow exactly, or a line (straight masking edge) or a shape (rect, ellipse or polygon template) that paint lands only inside of (outside with invert). Editor state saved with the document, not an undo step; replays keep the mask they were painted through. Returns the stencil with its id.",
       inputSchema: { type: "object", properties: { kind: { type: "string", enum: ["ruler", "arc", "line", "shape"], description: "ruler, arc, line or shape." }, ...STENCIL_GEOMETRY }, required: ["kind"], additionalProperties: false },
       annotations: { title: "Lay a stencil", ...WRITE2 },
+      coordinates: { in: STENCIL_POSITIONS, out: STENCIL_POSITIONS },
       handler: (a) => c.addStencil(a)
     },
     {
@@ -6708,6 +6760,7 @@ function createPaintGuideTools(c) {
       description: "Moves, reshapes, switches (guide or mask, invert) or hides (enabled false) a stencil by id from get_guides. Returns the stencil.",
       inputSchema: { type: "object", properties: { id: { type: "string", description: "Stencil id from get_guides." }, ...STENCIL_GEOMETRY }, required: ["id"], additionalProperties: false },
       annotations: { title: "Change a stencil", ...SET },
+      coordinates: { in: STENCIL_POSITIONS, out: STENCIL_POSITIONS },
       handler: ({ id, ...update }) => c.updateStencil(id, update)
     },
     {
@@ -6760,6 +6813,7 @@ function createPaintWetTools(c) {
       description: "Reads the wet media: whether any paint is still wet, the simulation clock (steps), whether time is paused, its speed (steps per second), the canvas tilt, the kernel running it (typescript, wasm, wasm-threads with the thread count, and a message when it runs slower than it could, e.g. without cross-origin isolation), and each wet layer: wet cells, where the water is (wetBounds), live tiles, its settings and flow map. Also engine: Engine B, the WebGPU accelerator (mode auto/off, state, reason, adapter, minTiles, activeTiles). Call it after wet strokes to see what is still wet.",
       inputSchema: EMPTY2,
       annotations: { title: "Get the wet paint", ...READ3 },
+      coordinates: { out: ["layers[].wetBounds", "layers[].flow.center"] },
       handler: () => c.wetState()
     },
     {
@@ -6786,6 +6840,7 @@ function createPaintWetTools(c) {
       description: "Dries wet paint at once: everything settles where it is and the water goes, as a hair dryer at full blast would (the same deterministic bake that saving uses). On one layer or every wet layer, optionally only inside rect. Dried washes stay put: later washes glaze over them instead of mixing in. One undo step. Returns dried (each layer id with the rectangle that dried) and stillWet.",
       inputSchema: { type: "object", properties: { layerId: { type: "string", description: "Only this layer (default every wet layer)." }, rect: RECT2 }, additionalProperties: false },
       annotations: { title: "Dry the wet paint", ...WRITE3 },
+      coordinates: { in: ["rect"], out: ["dried[].bounds"] },
       handler: async ({ layerId, rect }) => {
         await c.wetIdle();
         return c.dryPaint({ layerId, rect });
@@ -6801,6 +6856,7 @@ function createPaintWetTools(c) {
         additionalProperties: false
       },
       annotations: { title: "Pre-wet the paper", ...WRITE3 },
+      coordinates: { in: ["rect"], out: ["rect"] },
       handler: async ({ layerId, rect, amount }) => {
         await c.wetIdle();
         return c.wetPaper({ layerId, rect, amount });
@@ -6843,6 +6899,7 @@ function createPaintWetTools(c) {
         additionalProperties: false
       },
       annotations: { title: "Set a flow map", ...SET2 },
+      coordinates: { in: ["center"], out: ["flow.center"] },
       handler: async ({ layerId, ...flow }) => {
         await c.wetIdle();
         return { layerId: layerId ?? c.document.activeLayerId, flow: c.setFlowMap(layerId, flow), stillWet: stillWet() };
@@ -6943,6 +7000,7 @@ function createPaintThickTools(c) {
       description: "Reads a layer\u2019s thick paint: where the relief is (bounds, layer pixels), its highest point (0..255) and the lighting. relief is null when the layer is flat. Changes nothing.",
       inputSchema: { type: "object", properties: { layerId: LAYER_ID3 }, additionalProperties: false },
       annotations: { title: "Read a layer\u2019s relief", ...READ4 },
+      coordinates: { out: ["relief.bounds"] },
       handler: ({ layerId }) => ({ relief: c.reliefOf(layerId), lighting: c.getLighting() })
     },
     {
@@ -7039,7 +7097,7 @@ var TIP = {
   type: "object",
   description: "The tip (the shared brush engine). Missing fields keep their current values.",
   properties: {
-    size: { type: "number", minimum: 1, maximum: MAX_BRUSH_SIZE, description: "Diameter in document pixels." },
+    size: { type: "number", minimum: 1, maximum: MAX_BRUSH_SIZE, description: "Diameter in pixels." },
     hardness: { type: "number", minimum: 0, maximum: 1, description: "Edge hardness, 0 (soft) .. 1 (hard)." },
     spacing: { type: "number", minimum: 0.01, maximum: 10, description: "Dab spacing as a fraction of the diameter (0.05 is smooth, 1 is dotted)." },
     angle: { type: "number", minimum: -360, maximum: 360, description: "Tip angle in degrees, counter-clockwise; with rotation stroke or barrel it is added to the stroke direction or pen rotation." },
@@ -7289,7 +7347,7 @@ function brushSummary(b) {
   };
 }
 function createPaintEditorToolProvider(controller, options = {}) {
-  const c = controller;
+  const c = typeof controller === "function" ? lazyController(controller) : controller;
   const tools = [];
   const add = (t) => tools.push(t);
   const act = async (command, direct) => {
@@ -7301,9 +7359,10 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "get_canvas_info",
     title: "Get the canvas",
-    description: "Reads the canvas: size in pixels and dpi, its origin (where (0, 0) is relative to the canvas it was extended from), the paper (preset, colour, grain depth), the active layer, the active brush id, the paint colour, the view (zoom, rotation, mirror), the hand, how many strokes are recorded, the undo / redo labels, and the blend modes. Call it first.",
+    description: "Reads the canvas: size in pixels and dpi, its origin (where (0, 0) is relative to the canvas it was extended from), bounds (the rectangle the painting covers, in the coordinates every other tool takes), the paper (preset, colour, grain depth), the active layer, the active brush id, the paint colour, the view (zoom, rotation, mirror), the hand, how many strokes are recorded, the undo / redo labels, and the blend modes. Call it first.",
     inputSchema: EMPTY3,
     annotations: { title: "Get the canvas", ...READ6 },
+    coordinates: { out: ["bounds"] },
     handler: () => {
       const s = c.getState();
       const d = s.document;
@@ -7312,6 +7371,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
         height: d.canvas.height,
         dpi: d.canvas.dpi,
         origin: { ...d.origin ?? { x: 0, y: 0 } },
+        bounds: { x: 0, y: 0, width: d.canvas.width, height: d.canvas.height },
         paper: { preset: d.paper.preset, name: d.paper.name, color: d.paper.color, depth: d.paper.depth },
         activeLayerId: d.activeLayerId,
         layerCount: c.listLayers().length,
@@ -7440,6 +7500,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     description: "Lists the layers top first: id, name, type (pixel or group), visibility, opacity, blend, clipping, locks, whether it is active, the painted bounds in document pixels (null when empty), parent and depth.",
     inputSchema: EMPTY3,
     annotations: { title: "List layers", ...READ6 },
+    coordinates: { out: ["layers[].bounds"] },
     handler: () => ({ layers: c.listLayers(), activeLayerId: c.document.activeLayerId })
   });
   add({
@@ -7457,6 +7518,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Add a layer", ...WRITE5 },
+    coordinates: { out: ["bounds"] },
     handler: (a) => c.addLayer({ name: a.name, type: a.type, aboveId: a.aboveId, parentId: a.parentId })
   });
   add({
@@ -7492,6 +7554,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Change a layer", ...SET4 },
+    coordinates: { out: ["bounds"] },
     handler: ({ layerId, ...u }) => c.updateLayer(layerId, u)
   });
   add({
@@ -7516,6 +7579,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     description: "Makes a layer active: strokes, fills and clears without a layerId go to it. Editor state, not an undo step. Returns the layer.",
     inputSchema: { type: "object", properties: { layerId: { type: "string", description: "Layer id from list_layers." } }, required: ["layerId"], additionalProperties: false },
     annotations: { title: "Choose the active layer", ...SET4 },
+    coordinates: { out: ["bounds"] },
     handler: ({ layerId }) => {
       c.setActiveLayer(layerId);
       return c.describeLayer(c.getLayer(layerId));
@@ -7535,6 +7599,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     description: "Copies a layer (a group with its children) directly above it; the copy becomes active. One undo step. Returns the copy.",
     inputSchema: { type: "object", properties: { layerId: { type: "string", description: "Layer id from list_layers." } }, required: ["layerId"], additionalProperties: false },
     annotations: { title: "Duplicate a layer", ...WRITE5 },
+    coordinates: { out: ["bounds"] },
     handler: ({ layerId }) => c.duplicateLayer(layerId)
   });
   add({
@@ -7552,6 +7617,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Reorder a layer", ...WRITE5 },
+    coordinates: { out: ["bounds"] },
     handler: ({ layerId, index, parentId }) => c.moveLayer(layerId, index, parentId)
   });
   add({
@@ -7560,6 +7626,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     description: "Merges a pixel layer into the pixel layer directly below it, which keeps its name, opacity and blend. One undo step. Returns the merged layer.",
     inputSchema: { type: "object", properties: { layerId: { type: "string", description: "The upper layer, from list_layers." } }, required: ["layerId"], additionalProperties: false },
     annotations: { title: "Merge a layer down", ...DESTRUCTIVE3 },
+    coordinates: { out: ["bounds"] },
     handler: ({ layerId }) => c.mergeDown(layerId)
   });
   add({
@@ -7579,6 +7646,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Fill a layer", ...WRITE5 },
+    coordinates: { out: ["bounds"] },
     handler: (a) => act({ kind: "fill", fill: a }, () => c.fillLayer(a))
   });
   add({
@@ -7587,6 +7655,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     description: "Removes every pixel of a pixel layer. One undo step. Returns the layer id and the bounds that were cleared (null if it was empty).",
     inputSchema: { type: "object", properties: { layerId: LAYER_ID4 }, additionalProperties: false },
     annotations: { title: "Clear a layer", ...DESTRUCTIVE3 },
+    coordinates: { out: ["bounds"] },
     handler: ({ layerId }) => c.clearLayer(layerId)
   });
   add({
@@ -7746,6 +7815,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Pick a colour", ...READ6 },
+    coordinates: { in: [""] },
     handler: ({ x, y, layerId }) => c.pickColor(x, y, { layerId })
   });
   add({
@@ -7792,6 +7862,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Paint a brush stroke", ...WRITE5 },
+    coordinates: { in: ["points[]"], out: ["bounds"] },
     handler: async (a) => {
       await c.wetIdle();
       const stroke = { points: a.points, layerId: a.layerId, brushId: a.brushId, brush: a.brush, color: a.color, paint: a.paint, seed: a.seed, snapToPerspective: a.snapToPerspective };
@@ -7812,6 +7883,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "List recorded strokes", ...READ6 },
+    coordinates: { out: ["strokes[].bounds", "strokes[].points[]"] },
     handler: ({ ids, last }) => {
       const all = c.getStrokes();
       const picked = ids ? all.filter((s) => ids.includes(s.id)) : all.slice(-(last ?? 100));
@@ -7869,6 +7941,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Replay strokes, varied", ...WRITE5 },
+    coordinates: { in: ["origin"], out: ["bounds"] },
     handler: (a) => {
       const replay = a;
       return act({ kind: "replay", replay }, () => c.replayStrokes(replay));
@@ -7985,15 +8058,33 @@ function createPaintEditorToolProvider(controller, options = {}) {
   tools.push(...createPaintReplayTools(c));
   tools.push(...createPaintStickerTools(c));
   tools.push(...createPigmentTools());
+  const exclude = new Set(options.exclude ?? []);
+  const description = "Natural-media painting: paper and grain, dry and wet brushes, the brush library, strokes as data, pigment mixing, stencils, guides, layers and export.";
   return withPaintPlayback({
     id: options.id ?? "paint-editor",
     namespace: options.namespace,
     title: "Paint editor",
-    description: "Natural-media painting: paper and grain, dry and wet brushes, the brush library, strokes as data, pigment mixing, stencils, guides, layers and export.",
+    description: options.origin ? `${description} It is a layer of a larger canvas: every position is in canvas coordinates.` : description,
     skill: "pixerate-paint-editor",
-    tools
+    tools: tools.filter((t) => !exclude.has(t.name)).map((t) => hostTool(t, options))
   }, { director: !!options.director, surface: options.playbackSurface });
 }
+function hostTool({ coordinates, ...tool }, { origin, onChange }) {
+  if (!origin && !onChange) return tool;
+  const write = !tool.annotations?.readOnlyHint;
+  const done = (result) => {
+    if (write) onChange?.({ tool: tool.name });
+    return origin && coordinates?.out ? fromDocument(result, coordinates.out, origin) : result;
+  };
+  return {
+    ...tool,
+    ...origin ? { description: hostedText(tool.description ?? ""), inputSchema: hostedSchema(tool.inputSchema) } : {},
+    handler: (args, context) => {
+      const r = tool.handler(origin && coordinates?.in ? toDocument(args, coordinates.in, origin) : args, context);
+      return r instanceof Promise ? r.then(done) : done(r);
+    }
+  };
+}
 
 // src/paint-editor/ui.ts
 var PAINT_TOOLS = [

package/dist/paint-editor/sticker-tools.d.cts

@@ -3,6 +3,6 @@
  * category sticker) stay objects on their layer, which these tools list, move, turn, resize,
  * recolour, reorder and delete. Each change is one undo step and redraws the layer.
  */
-import type { AgentTool } from '../tools/registry.cjs';
+import type { PaintAgentTool } from './hosted.cjs';
 import type { PaintEditorController } from './controller.cjs';
-export declare function createPaintStickerTools(c: PaintEditorController): AgentTool[];
+export declare function createPaintStickerTools(c: PaintEditorController): PaintAgentTool[];

package/dist/paint-editor/sticker-tools.d.ts

@@ -3,6 +3,6 @@
  * category sticker) stay objects on their layer, which these tools list, move, turn, resize,
  * recolour, reorder and delete. Each change is one undo step and redraws the layer.
  */
-import type { AgentTool } from '../tools/registry.js';
+import type { PaintAgentTool } from './hosted.js';
 import type { PaintEditorController } from './controller.js';
-export declare function createPaintStickerTools(c: PaintEditorController): AgentTool[];
+export declare function createPaintStickerTools(c: PaintEditorController): PaintAgentTool[];

package/dist/paint-editor/thick-tools.d.cts

@@ -3,6 +3,6 @@
  * impasto brush; these tools move the light, read and flatten a layer's relief, and switch instant
  * drying of wet strokes.
  */
-import type { AgentTool } from '../tools/registry.cjs';
+import type { PaintAgentTool } from './hosted.cjs';
 import type { PaintEditorController } from './controller.cjs';
-export declare function createPaintThickTools(c: PaintEditorController): AgentTool[];
+export declare function createPaintThickTools(c: PaintEditorController): PaintAgentTool[];

package/dist/paint-editor/thick-tools.d.ts

@@ -3,6 +3,6 @@
  * impasto brush; these tools move the light, read and flatten a layer's relief, and switch instant
  * drying of wet strokes.
  */
-import type { AgentTool } from '../tools/registry.js';
+import type { PaintAgentTool } from './hosted.js';
 import type { PaintEditorController } from './controller.js';
-export declare function createPaintThickTools(c: PaintEditorController): AgentTool[];
+export declare function createPaintThickTools(c: PaintEditorController): PaintAgentTool[];

package/dist/paint-editor/tools.d.cts

@@ -5,6 +5,7 @@
  * `list_papers`, `list_strokes`).
  */
 import type { AgentToolProvider } from '../tools/registry.cjs';
+import { type PaintOrigin } from './hosted.cjs';
 import type { PaintEditorController } from './controller.cjs';
 import type { PaintDirector } from './presence.cjs';
 import type { PresenceActorInfo } from '../animation/presence.cjs';
@@ -25,6 +26,22 @@ export interface PaintEditorToolProviderOptions {
      * Set it when one registry holds several editors of this kind, each attached under its own surface id.
      */
     playbackSurface?: string;
+    /**
+     * Hosts the document as a layer on a larger canvas: where document (0, 0) sits in host
+     * coordinates. Every position the tools take is then a host coordinate and every position they
+     * return is one too (strokes, picks, bounds, guides, stencils, stickers, wet areas); the
+     * descriptions say canvas coordinates. Directors receive document pixels.
+     */
+    origin?: PaintOrigin;
+    /** Bare tool names to leave out (e.g. `new_canvas`, `export_psd` when the host owns the canvas). */
+    exclude?: readonly string[];
+    /** Called after each successful write (every tool not marked read-only), e.g. so the host can save. */
+    onChange?: (info: {
+        tool: string;
+    }) => void;
 }
-/** Agent tools for one paint editor. */
-export declare function createPaintEditorToolProvider(controller: PaintEditorController, options?: PaintEditorToolProviderOptions): AgentToolProvider;
+/**
+ * Agent tools for one paint editor. Pass a getter to create the document lazily: it is first
+ * called when a tool runs, never on registration.
+ */
+export declare function createPaintEditorToolProvider(controller: PaintEditorController | (() => PaintEditorController), options?: PaintEditorToolProviderOptions): AgentToolProvider;

package/dist/paint-editor/tools.d.ts

@@ -5,6 +5,7 @@
  * `list_papers`, `list_strokes`).
  */
 import type { AgentToolProvider } from '../tools/registry.js';
+import { type PaintOrigin } from './hosted.js';
 import type { PaintEditorController } from './controller.js';
 import type { PaintDirector } from './presence.js';
 import type { PresenceActorInfo } from '../animation/presence.js';
@@ -25,6 +26,22 @@ export interface PaintEditorToolProviderOptions {
      * Set it when one registry holds several editors of this kind, each attached under its own surface id.
      */
     playbackSurface?: string;
+    /**
+     * Hosts the document as a layer on a larger canvas: where document (0, 0) sits in host
+     * coordinates. Every position the tools take is then a host coordinate and every position they
+     * return is one too (strokes, picks, bounds, guides, stencils, stickers, wet areas); the
+     * descriptions say canvas coordinates. Directors receive document pixels.
+     */
+    origin?: PaintOrigin;
+    /** Bare tool names to leave out (e.g. `new_canvas`, `export_psd` when the host owns the canvas). */
+    exclude?: readonly string[];
+    /** Called after each successful write (every tool not marked read-only), e.g. so the host can save. */
+    onChange?: (info: {
+        tool: string;
+    }) => void;
 }
-/** Agent tools for one paint editor. */
-export declare function createPaintEditorToolProvider(controller: PaintEditorController, options?: PaintEditorToolProviderOptions): AgentToolProvider;
+/**
+ * Agent tools for one paint editor. Pass a getter to create the document lazily: it is first
+ * called when a tool runs, never on registration.
+ */
+export declare function createPaintEditorToolProvider(controller: PaintEditorController | (() => PaintEditorController), options?: PaintEditorToolProviderOptions): AgentToolProvider;

package/dist/paint-editor/wet-tools.d.cts

@@ -5,7 +5,7 @@
  * wet. Settings (wet parameters, flow maps, tilt) are saved with the document but are not undo
  * steps; drying and wetting the paper are.
  */
-import type { AgentTool } from '../tools/registry.cjs';
+import type { PaintAgentTool } from './hosted.cjs';
 import type { PaintEditorController } from './controller.cjs';
 export declare const WET_PARAM_SCHEMA: {
     readonly viscosity: {
@@ -63,4 +63,4 @@ export declare const WET_PARAM_SCHEMA: {
         readonly description: string;
     };
 };
-export declare function createPaintWetTools(c: PaintEditorController): AgentTool[];
+export declare function createPaintWetTools(c: PaintEditorController): PaintAgentTool[];

package/dist/paint-editor/wet-tools.d.ts

@@ -5,7 +5,7 @@
  * wet. Settings (wet parameters, flow maps, tilt) are saved with the document but are not undo
  * steps; drying and wetting the paper are.
  */
-import type { AgentTool } from '../tools/registry.js';
+import type { PaintAgentTool } from './hosted.js';
 import type { PaintEditorController } from './controller.js';
 export declare const WET_PARAM_SCHEMA: {
     readonly viscosity: {
@@ -63,4 +63,4 @@ export declare const WET_PARAM_SCHEMA: {
         readonly description: string;
     };
 };
-export declare function createPaintWetTools(c: PaintEditorController): AgentTool[];
+export declare function createPaintWetTools(c: PaintEditorController): PaintAgentTool[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.200.0",
+  "version": "0.202.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

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

@@ -255,6 +255,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `quick_select` | Quick Selection: `strokes` (brush paths of `{x, y}`), `size` (diameter, default 30), `mode`, `sampleAllLayers`, `enhanceEdge`. Each stroke grows out to its region's edges; with `replace` the first replaces and the rest add. Paint inside the area, then check and fix with `add` / `subtract` strokes. Returns the summary. |
 | `select_object` | Object Selection (GrabCut): `rect` (a box around the object) or `point` (on it), `mode`, `sampleAllLayers`, `enhanceEdge`. Outside the box is background. Make the box a little larger than the object. Returns the summary. |
 | `select_focus_area` | Select › Focus Area: the in-focus (sharp) parts, edge fitted to the image. `range` 0..100 (higher takes in softer areas), `noise` 0..100 (raise when grain is selected), `softness` px, `mode`. Returns the summary and `noiseLevel`. |
+| `select_sky` | Select › Sky: the sky (blue or overcast, from the top down, with patches through gaps), edge fitted to the skyline. `threshold` 0..100 (higher takes in haze), `softness` px, `mode`. Returns the summary, and `note` when none was found. |
 | `select_polygon` | The lasso: `points` (at least 3 `{x, y}` along the outline, closed automatically), `mode`, `feather`, `antiAlias`; `snapToEdges: {width, contrast}` makes it the Magnetic Lasso (points snap to edges, the outline follows them). Trace a subject's contour, not its box. Returns the summary (plus `outlinePoints` when snapped). |
 | `magic_wand` | Select similar colour from `x`, `y`: `tolerance` 0..255 (default 32), `contiguous` (default true), `distance` `rgb` or `perceptual`, `sampleMerged`, `sample` (`composite` or `active-layer`), `mode`, `feather`. For flat backdrops and solid colours. Returns the summary. |
 | `select_color_range` | Color Range, soft: `samples` (`[{color, x?, y?}]`) or a `preset` (reds … magentas, highlights, midtones, shadows, skinTones); `fuzziness` (samples 0..200, default 40; tone presets' falloff, default 20), `localized` px radius around positioned samples, `invert`, `sample`, `mode`, `feather`. Returns the summary. |

package/skills/pixerate-image-selection-masking/SKILL.md

@@ -99,6 +99,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 | One object among others, where you can box it (a product on a table, a person in a group) | `select_object` with a `rect` a little larger than the object on every side; then `quick_select` add / subtract strokes for what it missed |
 | A subject with a clear outline (product, person, animal) | `select_subject` (with a host model, by description; without one it takes whatever stands out most, so check `method` and the result); else `select_object` around it, or `select_polygon` with `snapToEdges` (12–30 points within `width` of the edge), then `refine_selection` |
 | An area or subject that differs from its surroundings (a shirt, a sky, a car) | `quick_select` with strokes painted inside it, away from the edge (`size` a fraction of its width); `add` / `subtract` strokes where it fell short or leaked |
+| The sky (to replace, recolour, or to leave out with `invert_selection`) | `select_sky`; raise `threshold` for haze or a sunset glow, lower it if pale buildings come in |
 | A sharp subject on a blurred background (shallow depth of field) | `select_focus_area`; raise `range` if parts of the subject are missing, `noise` if grainy background comes in |
 | A low-contrast or busy outline the edges don't follow | `select_polygon` without `snapToEdges`, along the contour (20–60 points) |
 | Flat backdrop or solid colour (studio white, green screen, sky without clouds) | `magic_wand` on the backdrop (`tolerance` 20–40; `distance: "perceptual"` for gradients), then `invert_selection` |
@@ -118,8 +119,8 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
   Add the new background with `add_pixel_layer` and move it under the cutout (`move_layer`).
   `render_preview` and look for a halo; if there is one, load the copy's pixels back as a
   selection, `shrink` 1 px, and mask.
-- **Replace the sky:** `magic_wand` or `select_color_range` `preset: "blues"` on the sky,
-  `add` missed patches, `refine_selection` radius 8–16 along the horizon and trees, then
+- **Replace the sky:** `select_sky` (or `magic_wand` / `select_color_range` `preset: "blues"`
+  if it finds none), `add` missed patches, `refine_selection` radius 8–16 along the horizon and trees, then
   `add_layer_mask` on the new sky layer. Match it with a clipped curves layer (`clipped: true`).
 - **Adjust only part of an image:** select, then `apply_selection_as_mask` with `kind` and
   `params`, and `feather` in proportion to the image (a few px for objects, 50–200 px for
@@ -205,6 +206,7 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
 - `quick_select`: brush strokes that grow out to the region's edges
 - `select_object`: the object in a box or under a point
 - `select_focus_area`: what is in focus
+- `select_sky`: the sky
 - `select_line`: a single row or column
 - `select_layer_transparency`: a layer's own pixels
 - `grow_selection`, `select_similar`: add similar colour, connected or anywhere

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

@@ -265,6 +265,15 @@ for the controls and presets.
   and baked in, at `opacity` strength. Transparent areas stay transparent, and thick paint keeps
   its relief and stays lit by the editor's light. Dry wet paint first (`dry_paint`).
 
+## Canvas-hosted layer
+
+A host can mount the painting as a layer of a larger canvas (`createPaintEditorToolProvider` with
+`origin`). Then every position you pass or read back is a canvas coordinate, not a document
+pixel: stroke points, picks, bounds, guides, stencils, stickers and wet areas alike.
+`get_canvas_info` `bounds` says where the painting lies on that canvas; paint inside it. The
+host may leave out tools it owns (`new_canvas`, `set_canvas`, `extend_canvas`, exports, the
+view), so work with the tools you are given.
+
 ## Tool reference
 
 ### Canvas and paper