@pixerate/editor 0.200.0 → 0.202.0

package/dist/image-editor/index.js

@@ -3692,14 +3692,14 @@ function toLab(r, g, b) {
 function slicSuperpixels(work, target = 400, compactness = 10, rounds = 5) {
   const { width: w, height: h, rgb } = work;
   const n = w * h;
-  const lab = new Float32Array(n * 3);
-  for (let i = 0; i < n; i++) lab.set(toLab(rgb[i * 3], rgb[i * 3 + 1], rgb[i * 3 + 2]), i * 3);
+  const lab2 = new Float32Array(n * 3);
+  for (let i = 0; i < n; i++) lab2.set(toLab(rgb[i * 3], rgb[i * 3 + 1], rgb[i * 3 + 2]), i * 3);
   const S = Math.max(2, Math.round(Math.sqrt(n / target)));
   const seeds = [];
   for (let y = Math.floor(S / 2); y < h; y += S) {
     for (let x = Math.floor(S / 2); x < w; x += S) {
       const i = y * w + x;
-      seeds.push([lab[i * 3], lab[i * 3 + 1], lab[i * 3 + 2], x, y]);
+      seeds.push([lab2[i * 3], lab2[i * 3 + 1], lab2[i * 3 + 2], x, y]);
     }
   }
   const k = seeds.length;
@@ -3717,7 +3717,7 @@ function slicSuperpixels(work, target = 400, compactness = 10, rounds = 5) {
       for (let y = y0; y <= y1; y++) {
         for (let x = x0; x <= x1; x++) {
           const i = y * w + x;
-          const d = (lab[i * 3] - L) ** 2 + (lab[i * 3 + 1] - A) ** 2 + (lab[i * 3 + 2] - B) ** 2 + m2 * ((x - cx) ** 2 + (y - cy) ** 2);
+          const d = (lab2[i * 3] - L) ** 2 + (lab2[i * 3 + 1] - A) ** 2 + (lab2[i * 3 + 2] - B) ** 2 + m2 * ((x - cx) ** 2 + (y - cy) ** 2);
           if (d < best[i]) {
             best[i] = d;
             label[i] = c;
@@ -3728,9 +3728,9 @@ function slicSuperpixels(work, target = 400, compactness = 10, rounds = 5) {
     const sum = new Float64Array(k * 6);
     for (let i = 0; i < n; i++) {
       const c = label[i];
-      sum[c * 6] += lab[i * 3];
-      sum[c * 6 + 1] += lab[i * 3 + 1];
-      sum[c * 6 + 2] += lab[i * 3 + 2];
+      sum[c * 6] += lab2[i * 3];
+      sum[c * 6 + 1] += lab2[i * 3 + 1];
+      sum[c * 6 + 2] += lab2[i * 3 + 2];
       sum[c * 6 + 3] += i % w;
       sum[c * 6 + 4] += Math.floor(i / w);
       sum[c * 6 + 5]++;
@@ -3748,9 +3748,9 @@ function slicSuperpixels(work, target = 400, compactness = 10, rounds = 5) {
   const size = new Int32Array(count);
   for (let i = 0; i < n; i++) {
     const c = label[i] = remap[label[i]];
-    meanLab[c * 3] += lab[i * 3];
-    meanLab[c * 3 + 1] += lab[i * 3 + 1];
-    meanLab[c * 3 + 2] += lab[i * 3 + 2];
+    meanLab[c * 3] += lab2[i * 3];
+    meanLab[c * 3 + 1] += lab2[i * 3 + 1];
+    meanLab[c * 3 + 2] += lab2[i * 3 + 2];
     centre[c * 2] += i % w;
     centre[c * 2 + 1] += Math.floor(i / w);
     size[c]++;
@@ -3763,8 +3763,8 @@ function slicSuperpixels(work, target = 400, compactness = 10, rounds = 5) {
   return { label, count, lab: meanLab, centre, size };
 }
 function superpixelSaliency(sp, width, height) {
-  const { count, lab, centre, size, label } = sp;
-  const dist = (a, b) => Math.hypot(lab[a * 3] - lab[b * 3], lab[a * 3 + 1] - lab[b * 3 + 1], lab[a * 3 + 2] - lab[b * 3 + 2]);
+  const { count, lab: lab2, centre, size, label } = sp;
+  const dist = (a, b) => Math.hypot(lab2[a * 3] - lab2[b * 3], lab2[a * 3 + 1] - lab2[b * 3 + 1], lab2[a * 3 + 2] - lab2[b * 3 + 2]);
   const onBorder = new Uint8Array(count);
   for (let x = 0; x < width; x++) {
     onBorder[label[x]] = 1;
@@ -4213,6 +4213,127 @@ function focusArea(pixels, options = {}) {
   return { selection: softMaskToSelection(work, mask), noiseLevel: Math.round(sigma * 255 * 10) / 10 };
 }
 
+// src/image-editor/selection/segment/sky.ts
+var SKY_SIZE = 768;
+function lab(r, g, b) {
+  const lin = (v) => {
+    v /= 255;
+    return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  };
+  const R = lin(r);
+  const G = lin(g);
+  const B = lin(b);
+  const f = (t) => t > 8856e-6 ? Math.cbrt(t) : 7.787 * t + 16 / 116;
+  const x = f((0.4124 * R + 0.3576 * G + 0.1805 * B) / 0.95047);
+  const y = f(0.2126 * R + 0.7152 * G + 0.0722 * B);
+  const z = f((0.0193 * R + 0.1192 * G + 0.9505 * B) / 1.08883);
+  return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+}
+var sigmoid = (v) => 1 / (1 + Math.exp(-v));
+function findSky(pixels, options = {}) {
+  const work = workImage(pixels, SKY_SIZE);
+  const { width: w, height: h, rgb, scale } = work;
+  const n = w * h;
+  const L = new Float32Array(n);
+  const A = new Float32Array(n);
+  const B = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    const [l, a, b] = lab(rgb[i * 3], rgb[i * 3 + 1], rgb[i * 3 + 2]);
+    L[i] = l;
+    A[i] = a;
+    B[i] = b;
+  }
+  const luma2 = boxMean(workLuma(work), w, h, 1);
+  const grad = new Float32Array(n);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = y * w + x;
+      const gx = x + 1 < w ? luma2[i + 1] - luma2[i] : 0;
+      const gy = y + 1 < h ? luma2[i + w] - luma2[i] : 0;
+      grad[i] = Math.hypot(gx, gy);
+    }
+  }
+  const roughR = Math.max(1, Math.round(6e-3 * Math.max(w, h)));
+  const rough = boxMean(grad, w, h, roughR);
+  const score = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    const chroma = Math.hypot(A[i], B[i]);
+    const blue = sigmoid((-B[i] - 6) / 4) * sigmoid((L[i] - 35) / 6);
+    const grey = sigmoid((L[i] - 68) / 5) * sigmoid((18 - chroma) / 4);
+    const smooth = Math.exp(-rough[i] / 0.02);
+    const y = Math.floor(i / w) / h;
+    const high = 1 - 0.35 * y;
+    score[i] = Math.max(blue, grey) * smooth * high;
+  }
+  const threshold = Math.min(100, Math.max(0, options.threshold ?? 50));
+  const t = 0.55 - (threshold - 50) * 6e-3;
+  const sky = new Uint8Array(n);
+  const stack = [];
+  const seedRows = Math.max(1, Math.round(h * 0.04));
+  for (let y = 0; y < seedRows; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = y * w + x;
+      if (score[i] >= t) {
+        sky[i] = 1;
+        stack.push(i);
+      }
+    }
+  }
+  if (!stack.length) return { selection: createSelectionMask(pixels.width, pixels.height), reason: "No sky was found along the top of the image." };
+  const low = t * 0.7;
+  while (stack.length) {
+    const p = stack.pop();
+    const x = p % w;
+    for (const q of [x + 1 < w ? p + 1 : -1, x > 0 ? p - 1 : -1, p + w < n ? p + w : -1, p - w]) {
+      if (q < 0 || sky[q] || score[q] < low) continue;
+      if (Math.hypot(L[q] - L[p], A[q] - A[p], B[q] - B[p]) > 6) continue;
+      sky[q] = 1;
+      stack.push(q);
+    }
+  }
+  let count = 0;
+  const mean = [0, 0, 0];
+  for (let i = 0; i < n; i++) {
+    if (!sky[i]) continue;
+    mean[0] += L[i];
+    mean[1] += A[i];
+    mean[2] += B[i];
+    count++;
+  }
+  for (let k = 0; k < 3; k++) mean[k] /= count;
+  let spread = 0;
+  for (let i = 0; i < n; i++) if (sky[i]) spread += (L[i] - mean[0]) ** 2 + (A[i] - mean[1]) ** 2 + (B[i] - mean[2]) ** 2;
+  const limit = Math.max(8, 2.5 * Math.sqrt(spread / count));
+  for (let i = 0; i < n; i++) {
+    if (sky[i] || score[i] < t) continue;
+    if (Math.hypot(L[i] - mean[0], A[i] - mean[1], B[i] - mean[2]) <= limit) sky[i] = 1;
+  }
+  let front = [];
+  for (let i = 0; i < n; i++) if (sky[i]) front.push(i);
+  for (let step = 0; step <= roughR + 1 && front.length; step++) {
+    const next = [];
+    for (const p of front) {
+      const x = p % w;
+      for (const q of [x + 1 < w ? p + 1 : -1, x > 0 ? p - 1 : -1, p + w < n ? p + w : -1, p - w]) {
+        if (q < 0 || sky[q]) continue;
+        if (Math.hypot(L[q] - mean[0], A[q] - mean[1], B[q] - mean[2]) > limit) continue;
+        sky[q] = 1;
+        next.push(q);
+      }
+    }
+    front = next;
+  }
+  if (count < n * 5e-3) return { selection: createSelectionMask(pixels.width, pixels.height), reason: "No sky was found along the top of the image." };
+  let mask = Float32Array.from(sky);
+  const softness = Math.max(0, options.softness ?? 4) * scale;
+  if (softness > 0) {
+    const fitted = guidedFilterColor(workPlanes(work), mask, w, h, Math.max(1, Math.round(softness * 2)), 1e-3);
+    mask = new Float32Array(n);
+    for (let i = 0; i < n; i++) mask[i] = Math.min(1, Math.max(0, fitted[i]));
+  }
+  return { selection: softMaskToSelection(work, mask) };
+}
+
 // src/image-editor/layers/shape-type-ui.ts
 var DEFAULT_SHAPE_TOOL_OPTIONS = {
   kind: "rect",
@@ -5942,10 +6063,10 @@ function colorModePlanes(doc, mode) {
   }
   const t = Transform.create(src, builtinProfile("lab-d50"), { intent: "relative", bpc: false });
   return (rgba, n) => {
-    const lab = new Uint8Array(n * 4);
-    t.convert8(rgba, 4, lab, 4, false);
+    const lab2 = new Uint8Array(n * 4);
+    t.convert8(rgba, 4, lab2, 4, false);
     const planes = [0, 1, 2].map(() => new Uint8Array(n));
-    for (let i = 0; i < n; i++) for (let c = 0; c < 3; c++) planes[c][i] = lab[i * 4 + c];
+    for (let i = 0; i < n; i++) for (let c = 0; c < 3; c++) planes[c][i] = lab2[i * 4 + c];
     return planes;
   };
 }
@@ -9983,6 +10104,19 @@ var ImageEditorController = class {
     this.setSelection(selection, options.mode ?? "replace");
     return { selection: this.state.selection ?? null, noiseLevel };
   }
+  /**
+   * Select › Sky: selects the sky (blue, or bright and grey when overcast; smooth; grown down from
+   * the top of the image, with patches seen through gaps), fitted to its edges, combined with the
+   * selection by `mode` as one undo step. Resolves to the selection and, when no sky was found
+   * (the selection is then unchanged), why.
+   */
+  async selectSky(options = {}) {
+    const pixels = await this.requirePixels({ sample: options.sampleAllLayers === false ? "active-layer" : "composite" });
+    const { selection, reason } = findSky(pixels, options);
+    if (!selection.bounds) return { selection: this.state.selection ?? null, note: reason };
+    this.setSelection(selection, options.mode ?? "replace");
+    return { selection: this.state.selection ?? null };
+  }
   /**
    * Supplies the pixels the selection tools sample (natural size RGBA), e.g. decoded in a worker
    * or in a test; `null` goes back to reading the source image. Without a canvas (Node, workers)
@@ -11500,8 +11634,8 @@ var ImageEditorController = class {
       const values = Array.from(out.subarray(0, t.outputs), (v) => Math.round(Math.min(1, Math.max(0, v)) * 1e4) / 1e4);
       const l = new Float32Array(3);
       toLab2.eval(rgb, l);
-      const lab = [Math.round(l[0] * 1e4) / 100, Math.round((l[1] * 255 - 128) * 100) / 100, Math.round((l[2] * 255 - 128) * 100) / 100];
-      const res = { input, values, lab };
+      const lab2 = [Math.round(l[0] * 1e4) / 100, Math.round((l[1] * 255 - 128) * 100) / 100, Math.round((l[2] * 255 - 128) * 100) / 100];
+      const res = { input, values, lab: lab2 };
       if (dst.colorSpace === "rgb") res.hex = `#${values.map((v) => Math.round(v * 255).toString(16).padStart(2, "0")).join("")}`;
       return res;
     });
@@ -12883,7 +13017,7 @@ var DEPTH_MASK_CONTROLS = [
 // src/image-editor/playback.ts
 var IMAGE_PLAYBACK_KIND = "layer";
 var PAINT = /^(paint_stroke|clone_stamp|heal_brush|spot_heal|dodge|burn|sponge|smudge|blur_stroke|sharpen_stroke|history_brush|set_clone_source|set_clone_transform|fill_pixels|clear_pixels|set_paint|set_retouch_options|load_mixer_brush|clean_mixer_brush)$/;
-var SELECT = /^(select_region|select_subject|select_by_color|select_all|deselect|invert_selection|select_rect|select_ellipse|select_polygon|quick_select|select_object|select_focus_area|select_line|magic_wand|grow_selection|select_similar|reselect|select_layer_transparency|select_color_range|load_selection_from_image|load_selection_from_mask|set_selection_display|modify_selection|refine_selection|transform_selection|apply_selection_as_mask|layer_via_copy|stroke_selection|content_aware_fill|copy_pixels|cut_pixels|paste_pixels|save_selection|load_selection_from_channel|set_channel_properties|duplicate_channel|delete_channel|load_channel_from_image|set_quick_mask|path_to_selection|select_text_shape)$/;
+var SELECT = /^(select_region|select_subject|select_by_color|select_all|deselect|invert_selection|select_rect|select_ellipse|select_polygon|quick_select|select_object|select_focus_area|select_sky|select_line|magic_wand|grow_selection|select_similar|reselect|select_layer_transparency|select_color_range|load_selection_from_image|load_selection_from_mask|set_selection_display|modify_selection|refine_selection|transform_selection|apply_selection_as_mask|layer_via_copy|stroke_selection|content_aware_fill|copy_pixels|cut_pixels|paste_pixels|save_selection|load_selection_from_channel|set_channel_properties|duplicate_channel|delete_channel|load_channel_from_image|set_quick_mask|path_to_selection|select_text_shape)$/;
 var ANNOTATE = /^(add_shape_layer|update_shape|add_shape_component|set_shape_component|remove_shape_component|merge_shape_components|add_text_layer|set_text|set_text_style|set_paragraph_style|set_text_frame|set_text_orientation|convert_text_to_shape)$/;
 var CROP = /^(set_crop|crop_to_selection|reset_crop|set_rotation|flip_image|transform_layer|warp_layer|flip_layer|offset_layer)$/;
 var ADJUST = /^(set_adjustments|add_adjustment_layer|update_adjustment_layer|remove_adjustment_layer|move_adjustment_layer)$/;
@@ -13547,6 +13681,31 @@ function createImageSelectionTools(controller) {
       return { ...summary(controller), noiseLevel };
     }
   };
+  const selectSkyTool = {
+    name: "select_sky",
+    title: "Select the sky",
+    description: "Select \u203A Sky: selects the sky (blue, or bright and grey when overcast, smooth, reaching down from the top of the image, including patches seen through branches or gaps), with the edge fitted to the skyline, combined with the selection by mode. Use it to replace or recolour a sky or to adjust the land without it (invert_selection). Raise threshold to take in haze or a sunset glow, lower it if bright buildings come in. One undoable step. Returns the selection, and a note when no sky was found (the selection is then unchanged).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        threshold: { type: "number", minimum: 0, maximum: 100, description: "How sky-like a pixel must be, 0..100 (default 50): higher takes in less sky-like pixels." },
+        softness: { type: "number", minimum: 0, maximum: 100, description: "Soften the edge over this many natural pixels (default 4; 0 for a hard edge)." },
+        mode: modeSchema,
+        sampleAllLayers: { type: "boolean", description: "Read every layer (default true); false reads only the active pixel layer." }
+      },
+      additionalProperties: false
+    },
+    annotations: writeAnnotations("Select the sky", true),
+    handler: async (args) => {
+      const { note } = await controller.selectSky({
+        threshold: args.threshold === void 0 ? void 0 : num2(args.threshold, 50),
+        softness: args.softness === void 0 ? void 0 : num2(args.softness, 4),
+        mode: parseSelectionMode(args.mode),
+        sampleAllLayers: args.sampleAllLayers
+      });
+      return { ...summary(controller), ...note ? { note } : {} };
+    }
+  };
   const magicWandTool = {
     name: "magic_wand",
     title: "Magic wand",
@@ -14103,6 +14262,7 @@ function createImageSelectionTools(controller) {
     selectObjectTool,
     createImageSubjectSelectionTool(controller),
     selectFocusAreaTool,
+    selectSkyTool,
     lineTool,
     magicWandTool,
     colorRangeTool,
@@ -20816,6 +20976,7 @@ export {
   findAdjustmentControl,
   findLayer,
   findLayerControl,
+  findSky,
   findSubject,
   findWebGpu,
   finishTile,

package/dist/image-editor/selection/segment/index.d.cts

@@ -5,3 +5,4 @@ export * from './grabcut.cjs';
 export * from './subject.cjs';
 export * from './guided.cjs';
 export * from './focus.cjs';
+export * from './sky.cjs';

package/dist/image-editor/selection/segment/index.d.ts

@@ -5,3 +5,4 @@ export * from './grabcut.js';
 export * from './subject.js';
 export * from './guided.js';
 export * from './focus.js';
+export * from './sky.js';

package/dist/image-editor/selection/segment/sky.d.cts

@@ -0,0 +1,21 @@
+/**
+ * Select › Sky without a segmentation model. Sky is smooth, sits at the top of the frame, and is
+ * blue, or bright and grey when overcast. Each pixel gets a score from those three cues; the sky
+ * is grown down from the top rows through high-scoring pixels; patches of the same colour seen
+ * through gaps (between branches, under a bridge) are added; and the edge is fitted to the image
+ * with the colour guided filter.
+ */
+import { type PixelBuffer, type SelectionMask } from '../mask.cjs';
+export interface SkyOptions {
+    /** 0..100 (default 50): higher takes in less sky-like pixels (haze, a sunset glow). */
+    threshold?: number;
+    /** Soften the edge over this many natural pixels (default 4; 0 for a hard edge). */
+    softness?: number;
+}
+export interface FoundSky {
+    selection: SelectionMask;
+    /** Why nothing was selected, when nothing was. */
+    reason?: string;
+}
+/** The sky in `pixels`, as a selection of the whole image (empty, with a reason, when there is none). */
+export declare function findSky(pixels: PixelBuffer, options?: SkyOptions): FoundSky;

package/dist/image-editor/selection/segment/sky.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Select › Sky without a segmentation model. Sky is smooth, sits at the top of the frame, and is
+ * blue, or bright and grey when overcast. Each pixel gets a score from those three cues; the sky
+ * is grown down from the top rows through high-scoring pixels; patches of the same colour seen
+ * through gaps (between branches, under a bridge) are added; and the edge is fitted to the image
+ * with the colour guided filter.
+ */
+import { type PixelBuffer, type SelectionMask } from '../mask.js';
+export interface SkyOptions {
+    /** 0..100 (default 50): higher takes in less sky-like pixels (haze, a sunset glow). */
+    threshold?: number;
+    /** Soften the edge over this many natural pixels (default 4; 0 for a hard edge). */
+    softness?: number;
+}
+export interface FoundSky {
+    selection: SelectionMask;
+    /** Why nothing was selected, when nothing was. */
+    reason?: string;
+}
+/** The sky in `pixels`, as a selection of the whole image (empty, with a reason, when there is none). */
+export declare function findSky(pixels: PixelBuffer, options?: SkyOptions): FoundSky;

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

@@ -3,6 +3,6 @@
  * images) and colour (harmonies, swatches, the mixing pad). Guides, swatches and the pad are
  * editor state saved with the document (the pad is not saved), not undo steps.
  */
-import type { AgentTool } from '../tools/registry.cjs';
+import type { PaintAgentTool } from './hosted.cjs';
 import type { PaintEditorController } from './controller.cjs';
-export declare function createPaintGuideTools(c: PaintEditorController): AgentTool[];
+export declare function createPaintGuideTools(c: PaintEditorController): PaintAgentTool[];

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

@@ -3,6 +3,6 @@
  * images) and colour (harmonies, swatches, the mixing pad). Guides, swatches and the pad are
  * editor state saved with the document (the pad is not saved), not undo steps.
  */
-import type { AgentTool } from '../tools/registry.js';
+import type { PaintAgentTool } from './hosted.js';
 import type { PaintEditorController } from './controller.js';
-export declare function createPaintGuideTools(c: PaintEditorController): AgentTool[];
+export declare function createPaintGuideTools(c: PaintEditorController): PaintAgentTool[];

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

@@ -0,0 +1,34 @@
+import type { AgentTool } from '../tools/registry.cjs';
+import type { PaintEditorController } from './controller.cjs';
+/**
+ * Position fields of a paint tool, as paths: keys joined by `.`, a key ending in `[]` maps over
+ * that array, `''` is the value itself. Each path names an object whose numeric `x` / `y` are a
+ * position (a point, or the top-left of a rect); missing or `null` values are skipped.
+ */
+export interface PaintToolCoordinates {
+    /** Argument fields, given in host coordinates and moved into document pixels. */
+    in?: readonly string[];
+    /** Result fields, in document pixels and moved out into host coordinates. */
+    out?: readonly string[];
+}
+/** A paint tool with its position fields. */
+export type PaintAgentTool = AgentTool & {
+    coordinates?: PaintToolCoordinates;
+};
+export interface PaintOrigin {
+    x: number;
+    y: number;
+}
+/** Host coordinates → document pixels, at the given position fields. */
+export declare const toDocument: <T>(value: T, paths: readonly string[], origin: PaintOrigin) => T;
+/** Document pixels → host coordinates, at the given position fields. */
+export declare const fromDocument: <T>(value: T, paths: readonly string[], origin: PaintOrigin) => T;
+/** Tool prose in host terms: positions are canvas coordinates, not document pixels. */
+export declare function hostedText(text: string): string;
+/** `hostedText` over every `description` in a JSON schema. */
+export declare function hostedSchema<T>(schema: T): T;
+/**
+ * A controller that resolves `get` on every property access, so tools built over it never touch
+ * the document until a handler runs (a host can create the document lazily).
+ */
+export declare function lazyController(get: () => PaintEditorController): PaintEditorController;

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

@@ -0,0 +1,34 @@
+import type { AgentTool } from '../tools/registry.js';
+import type { PaintEditorController } from './controller.js';
+/**
+ * Position fields of a paint tool, as paths: keys joined by `.`, a key ending in `[]` maps over
+ * that array, `''` is the value itself. Each path names an object whose numeric `x` / `y` are a
+ * position (a point, or the top-left of a rect); missing or `null` values are skipped.
+ */
+export interface PaintToolCoordinates {
+    /** Argument fields, given in host coordinates and moved into document pixels. */
+    in?: readonly string[];
+    /** Result fields, in document pixels and moved out into host coordinates. */
+    out?: readonly string[];
+}
+/** A paint tool with its position fields. */
+export type PaintAgentTool = AgentTool & {
+    coordinates?: PaintToolCoordinates;
+};
+export interface PaintOrigin {
+    x: number;
+    y: number;
+}
+/** Host coordinates → document pixels, at the given position fields. */
+export declare const toDocument: <T>(value: T, paths: readonly string[], origin: PaintOrigin) => T;
+/** Document pixels → host coordinates, at the given position fields. */
+export declare const fromDocument: <T>(value: T, paths: readonly string[], origin: PaintOrigin) => T;
+/** Tool prose in host terms: positions are canvas coordinates, not document pixels. */
+export declare function hostedText(text: string): string;
+/** `hostedText` over every `description` in a JSON schema. */
+export declare function hostedSchema<T>(schema: T): T;
+/**
+ * A controller that resolves `get` on every property access, so tools built over it never touch
+ * the document until a handler runs (a host can create the document lazily).
+ */
+export declare function lazyController(get: () => PaintEditorController): PaintEditorController;