@pixerate/editor 0.272.0 → 0.273.0

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

@@ -61,3 +61,4 @@ export * from './collaboration.cjs';
 export * from './collaboration-tools.cjs';
 export { samplePath, MAX_PATH_SAMPLES, type PathSampleOptions } from './path-samples.cjs';
 export { createPaintConformanceHost, paintContracts, PAINT_CONTRACT_FORMAT_VERSION, PAINT_DOCUMENT_JSON_SCHEMA } from './contract.cjs';
+export { squaredDistanceTransform, fillRegionMask, findUnfilledRegionsMask, type FillRegionPoint, type FillRegionSummary, type FillRegionMaskOptions, type FillRegionMaskResult, type UnfilledRegion, type FindUnfilledRegionsMaskOptions, } from '../raster/fill.cjs';

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

@@ -61,3 +61,4 @@ export * from './collaboration.js';
 export * from './collaboration-tools.js';
 export { samplePath, MAX_PATH_SAMPLES, type PathSampleOptions } from './path-samples.js';
 export { createPaintConformanceHost, paintContracts, PAINT_CONTRACT_FORMAT_VERSION, PAINT_DOCUMENT_JSON_SCHEMA } from './contract.js';
+export { squaredDistanceTransform, fillRegionMask, findUnfilledRegionsMask, type FillRegionPoint, type FillRegionSummary, type FillRegionMaskOptions, type FillRegionMaskResult, type UnfilledRegion, type FindUnfilledRegionsMaskOptions, } from '../raster/fill.js';

package/dist/paint-editor/index.js

@@ -27,6 +27,11 @@ import {
 import {
   ToolRegistry
 } from "../chunk-K4BGRCSH.js";
+import {
+  fillRegionMask,
+  findUnfilledRegionsMask,
+  squaredDistanceTransform
+} from "../chunk-2A5IKZMU.js";
 import {
   BRUSH_OPTION_CONTROLS,
   createLayerEffectTools,
@@ -221,9 +226,11 @@ import {
   DEFAULT_FLOW,
   DEFAULT_WET_PARAMS,
   MAX_WET_LANES,
+  PIGMENT_UNIT,
   SRGB_TO_LINEAR,
   WET_FLOW_KINDS,
   WET_PARAM_KEYS,
+  WetMedium,
   WetWorld,
   linearToSrgb8,
   normalizeFlow,
@@ -2927,7 +2934,7 @@ function deserializePaintDocument(raw) {
   const wetEvents = Array.isArray(r.wetEvents) ? r.wetEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.clock) && typeof e.kind === "string") : [];
   const state = { canvas, paper, layers, activeLayerId, strokes: readStrokes(r.strokes, problems) };
   if (wetEvents.length) state.wetEvents = wetEvents;
-  const paintEvents = Array.isArray(r.paintEvents) ? r.paintEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.at) && typeof e.layerId === "string" && ["fill", "clear", "flatten", "stickers"].includes(e.kind)) : [];
+  const paintEvents = Array.isArray(r.paintEvents) ? r.paintEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.at) && typeof e.layerId === "string" && ["fill", "fill-region", "clear", "flatten", "stickers", "live-strokes"].includes(e.kind)) : [];
   if (paintEvents.length) state.paintEvents = paintEvents;
   const o = r.origin;
   if (o && typeof o === "object" && Number.isFinite(o.x) && Number.isFinite(o.y) && (o.x || o.y)) state.origin = { x: Math.round(o.x), y: Math.round(o.y) };
@@ -4115,7 +4122,18 @@ async function replayPainting(source, target, options = {}) {
       const e = item.event;
       if (!target.getLayer(e.layerId)) continue;
       if (e.kind === "fill") target.fillLayer({ layerId: e.layerId, ...e.data });
-      else if (e.kind === "clear") target.clearLayer(e.layerId);
+      else if (e.kind === "fill-region") {
+        const d = e.data ?? {};
+        if (d.wet) await target.wetIdle();
+        const pts = d.points ? d.points.map((p) => ({ x: p.x * s, y: p.y * s })) : d.x !== void 0 && d.y !== void 0 ? [{ x: d.x * s, y: d.y * s }] : [];
+        target.fillRegion({
+          ...d,
+          layerId: e.layerId,
+          points: pts,
+          ...d.closeGap !== void 0 ? { closeGap: Math.min(32, d.closeGap * s) } : {},
+          ...d.expand !== void 0 ? { expand: Math.max(-16, Math.min(16, d.expand * s)) } : {}
+        });
+      } else if (e.kind === "clear") target.clearLayer(e.layerId);
       else if (e.kind === "live-strokes") {
         const d = e.data;
         if (d?.rasterized) target.replaceLiveStrokes(e.layerId, null);
@@ -5502,6 +5520,252 @@ var PaintEditorController = class _PaintEditorController {
     this.commit("Fill layer", this.withPaintEvent(this.withWetEvents({ ...this.doc, layers: mapLayer(this.doc.layers, l.id, () => ({ ...l, surface })), ...light ? { light } : {} }), { kind: "fill", layerId: l.id, data: { color, opacity, grain: grainAmount, pressure, blend } }));
     return { layerId: l.id, bounds: rect };
   }
+  /**
+   * Flood-fills one or more contiguous regions on a pixel layer (one undo step), sampling boundaries
+   * from the layer itself (`reference: 'layer'`), all visible layers (`'all'` / `'composite'`), or a
+   * specific reference layer id (e.g. an ink line-art layer above a flats layer). Closes line-art gaps
+   * up to `closeGap` px and expands (`> 0`, bleeding under lines) or contracts (`< 0`) by `expand` px.
+   * With `wet: true`, pours a watercolour wash into the region on the layer's wet layer.
+   */
+  fillRegion(options) {
+    this.requireIdle("filling");
+    const fillTarget = this.paintTarget(options.layerId, "fill");
+    if (this.doc.stickers?.[fillTarget.id]?.length) throw new PaintEditorError(`Layer "${fillTarget.name}" is a sticker layer; fill another layer (add_layer).`);
+    if (this.doc.liveStrokes?.[fillTarget.id]) throw new PaintEditorError(`Layer "${fillTarget.name}" is a stroke layer (its pixels are drawn from its strokes); fill another layer (add_layer), or rasterize it first (rasterize_stroke_layer).`);
+    const { width, height } = this.doc.canvas;
+    const pts = [];
+    if (options.points !== void 0) {
+      if (!Array.isArray(options.points) || !options.points.length) {
+        throw new PaintEditorError("points is empty; give at least one {x, y} in document pixels.");
+      }
+      for (let i = 0; i < options.points.length; i++) {
+        const p = options.points[i];
+        if (!p || !Number.isFinite(p.x) || !Number.isFinite(p.y)) {
+          throw new PaintEditorError(`points[${i}] needs finite x and y in document pixels.`);
+        }
+        pts.push({ x: p.x, y: p.y });
+      }
+    }
+    if (options.x !== void 0 || options.y !== void 0) {
+      if (!Number.isFinite(options.x) || !Number.isFinite(options.y)) {
+        throw new PaintEditorError("x and y must be finite numbers in document pixels.");
+      }
+      if (!options.points) pts.push({ x: options.x, y: options.y });
+    }
+    if (!pts.length) {
+      throw new PaintEditorError("Pass x and y (or points) in document pixels to fill a region.");
+    }
+    for (const p of pts) {
+      const px = Math.floor(p.x);
+      const py = Math.floor(p.y);
+      if (px < 0 || py < 0 || px >= width || py >= height) {
+        throw new PaintEditorError(`(${p.x}, ${p.y}) is outside the ${width}\xD7${height} canvas.`);
+      }
+    }
+    const refSpec = options.reference ?? "layer";
+    if (refSpec !== "layer" && refSpec !== "all" && refSpec !== "composite") {
+      this.requireLayer(refSpec);
+    }
+    const color = options.color === void 0 ? this.color : parseColor(options.color);
+    const opacity = options.opacity ?? 1;
+    if (!(Number.isFinite(opacity) && opacity >= 0 && opacity <= 1)) throw new PaintEditorError(`opacity ${opacity} is out of range; use 0..1.`);
+    const blend = options.blend ?? options.blendMode ?? "normal";
+    if (!isBlendMode(blend)) throw new PaintEditorError(`Unknown blend mode "${blend}".`);
+    const tolerance = options.tolerance ?? 32;
+    if (!(Number.isFinite(tolerance) && tolerance >= 0 && tolerance <= 255)) throw new PaintEditorError(`tolerance ${tolerance} is out of range; use 0..255.`);
+    const closeGap = options.closeGap ?? 0;
+    if (!(Number.isFinite(closeGap) && closeGap >= 0 && closeGap <= 32)) throw new PaintEditorError(`closeGap ${closeGap} is out of range; use 0..32 px.`);
+    const expand2 = options.expand ?? 0;
+    if (!(Number.isFinite(expand2) && expand2 >= -16 && expand2 <= 16)) throw new PaintEditorError(`expand ${expand2} is out of range; use -16..16 px.`);
+    const antialias = options.antialias ?? true;
+    if (typeof antialias !== "boolean") throw new PaintEditorError("antialias must be true or false.");
+    const grainAmount = options.grain ?? 0;
+    if (!(Number.isFinite(grainAmount) && grainAmount >= 0 && grainAmount <= 1)) throw new PaintEditorError(`grain ${grainAmount} is out of range; use 0..1.`);
+    const pressure = options.pressure ?? 0.5;
+    if (!(Number.isFinite(pressure) && pressure >= 0 && pressure <= 1)) throw new PaintEditorError(`pressure ${pressure} is out of range; use 0..1.`);
+    const wet = options.wet === true;
+    if (wet && this.previewing) throw new PaintEditorError("Wet paint can't be previewed; suggest a dry fill instead.");
+    if (wet && !this.wet.wetLayerIds().includes(fillTarget.id) && this.wet.wetLayerIds().length >= MAX_WET_LANES) {
+      throw new PaintEditorError(`At most ${MAX_WET_LANES} layers can hold wet paint at once; dry one first (dry_paint).`);
+    }
+    const refPixels = refSpec === "layer" ? this.compositePixels({ layerIds: [fillTarget.id], paper: false, wet: "display" }).data : refSpec === "all" || refSpec === "composite" ? this.compositePixels({ paper: false, wet: "display" }).data : this.compositePixels({ layerIds: [refSpec], paper: false, wet: "display" }).data;
+    const filled = fillRegionMask(refPixels, width, height, {
+      points: pts,
+      tolerance,
+      closeGap,
+      expand: expand2,
+      antialias
+    });
+    const eventData = {
+      points: pts.map((p) => ({ x: p.x, y: p.y })),
+      reference: refSpec,
+      color,
+      opacity,
+      blend,
+      tolerance,
+      closeGap,
+      expand: expand2,
+      antialias,
+      grain: grainAmount,
+      pressure,
+      ...wet ? { wet: true } : {}
+    };
+    if (!filled.bounds || filled.pixelCount === 0) {
+      return {
+        layerId: fillTarget.id,
+        bounds: null,
+        pixelCount: 0,
+        leaked: false,
+        regions: filled.regions,
+        ...wet ? { wet: this.wet.isWet(fillTarget.id) } : {}
+      };
+    }
+    const rect = filled.bounds;
+    const depth = grainAmount * this.doc.paper.depth;
+    const grain = depth > 0 ? paperGrain(this.doc.paper) : null;
+    if (wet) {
+      this.requireWetIdle("filling");
+      const before = this.doc;
+      let l2 = fillTarget;
+      if (l2.offset.x || l2.offset.y) {
+        const moved = { ...l2, surface: translateSurface(l2.surface, l2.offset.x, l2.offset.y), offset: { x: 0, y: 0 } };
+        this.doc = { ...this.doc, layers: mapLayer(this.doc.layers, l2.id, () => moved) };
+        l2 = moved;
+      }
+      this.beginWetOp();
+      const world = this.wet.ensureLane(l2.id);
+      const [r, g, b] = hexToRgb8(color);
+      const medium = new WetMedium(world, l2.id, {
+        water: 0.9 * Math.max(0.25, opacity),
+        mass: PIGMENT_UNIT * 2.5 * opacity,
+        body: 0,
+        light: 0
+      });
+      const subCov = new Float32Array(rect.width * rect.height);
+      for (let yy = 0, k = 0; yy < rect.height; yy++) {
+        const py = rect.y + yy;
+        const row = py * width;
+        for (let xx = 0; xx < rect.width; xx++, k++) {
+          const px = rect.x + xx;
+          let v = filled.mask[row + px];
+          if (v > 0 && grain) v *= grainCatch(grain.at(px + 0.5, py + 0.5), depth, pressure);
+          subCov[k] = Math.round(v * 4096) / 4096;
+        }
+      }
+      medium.deposit(rect, subCov, 1, [r / 255, g / 255, b / 255], null);
+      if (this.wet.instantDry) {
+        this.wet.dry(l2.id);
+        this.logWet({ kind: "dry", layerId: l2.id });
+      } else {
+        this.wet.syncDisplays();
+      }
+      const afterLayer = this.getLayer(l2.id);
+      this.commit(
+        "Fill region",
+        this.withPaintEvent(this.withWetEvents({ ...this.doc, layers: mapLayer(this.doc.layers, l2.id, () => ({ ...afterLayer })) }), {
+          kind: "fill-region",
+          layerId: l2.id,
+          data: eventData
+        }),
+        before
+      );
+      return {
+        layerId: l2.id,
+        bounds: rect,
+        pixelCount: filled.pixelCount,
+        leaked: filled.leaked,
+        regions: filled.regions,
+        wet: this.wet.isWet(l2.id)
+      };
+    }
+    this.dryLayersFirst([fillTarget.id]);
+    const l = this.paintTarget(options.layerId, "fill");
+    const coverage = new CoverageMap();
+    const vals = new Float32Array(rect.width * rect.height);
+    for (let yy = 0, k = 0; yy < rect.height; yy++) {
+      const py = rect.y + yy;
+      const row = py * width;
+      for (let xx = 0; xx < rect.width; xx++, k++) {
+        const px = rect.x + xx;
+        let v = filled.mask[row + px];
+        if (v > 0 && grain) v *= grainCatch(grain.at(px + 0.5, py + 0.5), depth, pressure);
+        vals[k] = v;
+      }
+    }
+    coverage.accumulate(rect, vals, 1);
+    const apply = {
+      mode: "paint",
+      color: rgbaOf(color),
+      background: rgbaOf(this.doc.paper.color),
+      opacity,
+      blend,
+      lockTransparency: isLayerLocked(l, "transparency"),
+      selection: null,
+      offset: l.offset
+    };
+    const surface = this.applyCoverage(l, coverage, rect, apply);
+    this.commit(
+      "Fill region",
+      this.withPaintEvent(this.withWetEvents({ ...this.doc, layers: mapLayer(this.doc.layers, l.id, () => ({ ...l, surface })) }), {
+        kind: "fill-region",
+        layerId: l.id,
+        data: eventData
+      })
+    );
+    return {
+      layerId: l.id,
+      bounds: rect,
+      pixelCount: filled.pixelCount,
+      leaked: filled.leaked,
+      regions: filled.regions
+    };
+  }
+  /**
+   * Finds enclosed unfilled regions from a reference layer or the visible composite (without paper),
+   * closing line-art gaps up to `closeGap` px and returning each region's interior seed `point`,
+   * `centroid`, `bounds`, `pixelCount`, and `touchesEdge` flag.
+   */
+  findUnfilledRegions(options = {}) {
+    if (options.layerId !== void 0) {
+      const l = this.requireLayer(options.layerId);
+      if (!isPixelLayer(l)) throw new PaintEditorError(`Layer "${l.name}" is a group; pass a pixel layer inside it.`);
+    }
+    const refSpec = options.reference ?? "all";
+    if (refSpec !== "layer" && refSpec !== "all" && refSpec !== "composite") {
+      this.requireLayer(refSpec);
+    }
+    const tolerance = options.tolerance ?? 32;
+    if (!(Number.isFinite(tolerance) && tolerance >= 0 && tolerance <= 255)) throw new PaintEditorError(`tolerance ${tolerance} is out of range; use 0..255.`);
+    const closeGap = options.closeGap ?? 0;
+    if (!(Number.isFinite(closeGap) && closeGap >= 0 && closeGap <= 32)) throw new PaintEditorError(`closeGap ${closeGap} is out of range; use 0..32 px.`);
+    const minArea = options.minArea ?? 16;
+    if (!(Number.isInteger(minArea) && minArea >= 1 && minArea <= 1e7)) throw new PaintEditorError(`minArea ${minArea} is out of range; use a whole number of pixels, 1 or more.`);
+    const maxRegions = options.maxRegions ?? 100;
+    if (!(Number.isInteger(maxRegions) && maxRegions >= 1 && maxRegions <= 1e3)) throw new PaintEditorError(`maxRegions ${maxRegions} is out of range; use 1..1000.`);
+    const includeEdge = options.includeEdge ?? false;
+    if (typeof includeEdge !== "boolean") throw new PaintEditorError("includeEdge must be true or false.");
+    const { width, height } = this.doc.canvas;
+    let refPixels;
+    if (refSpec === "all" || refSpec === "composite") {
+      refPixels = this.compositePixels({ paper: false, wet: "display" }).data;
+    } else if (refSpec === "layer") {
+      const targetId = options.layerId ?? this.doc.activeLayerId;
+      if (!targetId) throw new PaintEditorError("There is no active layer; pass layerId or reference.");
+      refPixels = this.compositePixels({ layerIds: [targetId], paper: false, wet: "display" }).data;
+    } else {
+      refPixels = this.compositePixels({ layerIds: [refSpec], paper: false, wet: "display" }).data;
+    }
+    const targetPixels = options.layerId !== void 0 && options.layerId !== refSpec && refSpec !== "layer" ? this.compositePixels({ layerIds: [options.layerId], paper: false, wet: "display" }).data : void 0;
+    const regions = findUnfilledRegionsMask(refPixels, width, height, {
+      target: targetPixels,
+      tolerance,
+      closeGap,
+      minArea,
+      includeEdge,
+      maxRegions
+    });
+    return { regions };
+  }
   applyCoverage(l, coverage, rect, apply) {
     const base = l.surface;
     const tiles = new Map(base.tiles);
@@ -8825,7 +9089,19 @@ function shiftDocument(doc, dx, dy) {
       const list = e.kind === "stickers" ? e.data?.stickers : void 0;
       if (list) return { ...e, data: { ...e.data, stickers: moveStickers(list) } };
       const strokes = e.kind === "live-strokes" ? e.data?.strokes : void 0;
-      return strokes ? { ...e, data: { ...e.data, strokes: strokes.map(moveStroke) } } : e;
+      if (strokes) return { ...e, data: { ...e.data, strokes: strokes.map(moveStroke) } };
+      if (e.kind === "fill-region" && e.data) {
+        const d = e.data;
+        return {
+          ...e,
+          data: {
+            ...e.data,
+            ...typeof d.x === "number" && typeof d.y === "number" ? { x: d.x + dx, y: d.y + dy } : {},
+            ...Array.isArray(d.points) ? { points: d.points.map((p) => movePoint(p, dx, dy)) } : {}
+          }
+        };
+      }
+      return e;
     });
   }
   if (doc.wetEvents) {
@@ -9029,6 +9305,17 @@ var PaintDirector = class {
         }
         return c.fillLayer(command.fill);
       }
+      case "fill-region": {
+        await this.say(id, command.note, 500);
+        const pts = command.fill.points?.length ? command.fill.points : command.fill.x !== void 0 && command.fill.y !== void 0 ? [{ x: command.fill.x, y: command.fill.y }] : [];
+        for (const p of pts) {
+          await this.glide(id, p, 240);
+          this.presence.set({ id, pressed: true });
+          await this.clock.wait(this.ms(90));
+          this.presence.set({ id, pressed: false });
+        }
+        return c.fillRegion(command.fill);
+      }
       case "replay": {
         await this.say(id, command.note, 500);
         const source = c.getStrokes().filter((s) => command.replay.strokeIds?.includes(s.id));
@@ -9144,7 +9431,7 @@ function planPaintToolPlayback(tool, _args) {
   if (control) steps.push({ type: "target", ref: control }, { type: "press" }, { type: "release" });
   return steps.length ? steps : null;
 }
-var DIRECTED = /* @__PURE__ */ new Set(["paint_stroke", "stroke_path", "fill_layer", "replay_strokes"]);
+var DIRECTED = /* @__PURE__ */ new Set(["paint_stroke", "stroke_path", "fill_layer", "fill_region", "replay_strokes"]);
 function withPaintPlayback(provider, options) {
   const plan = (tool) => {
     if (tool.plan || tool.playback !== void 0) return tool;
@@ -10479,6 +10766,77 @@ function createPaintEditorToolProvider(controller, options = {}) {
     coordinates: { out: ["bounds"] },
     handler: (a) => act({ kind: "fill", fill: a }, () => c.fillLayer(a))
   });
+  add({
+    name: "fill_region",
+    title: "Fill a region (bucket / flats)",
+    description: 'Flood-fills one or more enclosed regions on a pixel layer from a seed point (x, y) or a batch of seed points (points). Set reference to a line-art layer id from list_layers (or "all" / "composite" for all visible layers, or "layer" for the target layer itself) to drop flat colours onto a flats layer under the ink without touching the line art. closeGap (0..32 px) bridges small gaps in the line art so flats do not leak; expand (-16..16 px, e.g. 1..2 px) bleeds the fill under anti-aliased line edges so no halo shows; wet pours a watercolour wash into the region on the wet layer. One undo step. Returns layerId, bounds, pixelCount, regions, and leaked (true when the fill touched the canvas border).',
+    inputSchema: {
+      type: "object",
+      properties: {
+        x: { type: "number", description: "Seed point x in document pixels (pass x and y, or points)." },
+        y: { type: "number", description: "Seed point y in document pixels (pass x and y, or points)." },
+        points: {
+          type: "array",
+          minItems: 1,
+          maxItems: 500,
+          description: "Multiple seed points in document pixels, filled together as one undo step.",
+          items: {
+            type: "object",
+            properties: {
+              x: { type: "number", description: "Document x in pixels." },
+              y: { type: "number", description: "Document y in pixels." }
+            },
+            required: ["x", "y"],
+            additionalProperties: false
+          }
+        },
+        layerId: LAYER_ID4,
+        reference: {
+          type: "string",
+          description: 'Which pixels stop the fill: "layer" (default, the target layer itself), "all" or "composite" (all visible layers without paper), or a layer id from list_layers (e.g. an ink line-art layer above the flats layer).'
+        },
+        color: { ...COLOR3, description: "Fill colour #rrggbb (default the paint colour)." },
+        opacity: { type: "number", minimum: 0, maximum: 1, description: "Opacity 0..1 (default 1)." },
+        blend: { type: "string", enum: BLEND_MODES.map((m) => m.id), description: "Blend mode (default normal; see list_blend_modes)." },
+        blendMode: { type: "string", enum: BLEND_MODES.map((m) => m.id), description: "Alias for blend (default normal; see list_blend_modes)." },
+        tolerance: { type: "number", minimum: 0, maximum: 255, description: "Colour and alpha similarity tolerance 0..255 (default 32)." },
+        closeGap: { type: "number", minimum: 0, maximum: 32, description: "Close gaps in line art up to this width in pixels, 0..32 (default 0)." },
+        expand: { type: "number", minimum: -16, maximum: 16, description: "Expand (> 0, bleed under lines to hide anti-aliased halos) or contract (< 0) the filled region in pixels, -16..16 (default 0)." },
+        antialias: { type: "boolean", description: "Soften boundary edges (default true)." },
+        grain: { type: "number", minimum: 0, maximum: 1, description: "Paper grain response 0..1 (default 0: flat)." },
+        pressure: { type: "number", minimum: 0, maximum: 1, description: "With grain: how far into the valleys, 0..1 (default 0.5)." },
+        wet: { type: "boolean", description: "Pour a wet watercolour wash into the region on the wet layer instead of dry pixels (default false)." }
+      },
+      additionalProperties: false
+    },
+    annotations: { title: "Fill a region (bucket / flats)", ...WRITE5 },
+    coordinates: { in: ["", "points[]"], out: ["bounds", "regions[].point", "regions[].bounds"] },
+    handler: (a) => act({ kind: "fill-region", fill: a }, () => c.fillRegion(a))
+  });
+  add({
+    name: "find_unfilled_regions",
+    title: "Find enclosed unfilled regions",
+    description: 'Finds enclosed unfilled regions from a reference line-art layer (reference: layerId) or the visible composite ("all" / "composite", the default), closing line-art gaps up to closeGap px. When layerId is given, regions already painted on that target layer are excluded. Changes nothing. Returns regions sorted largest first, each with an interior seed point {x, y} ready for fill_region, centroid, bounds, pixelCount (area), and touchesEdge.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        layerId: { type: "string", description: "Target flats layer id from list_layers; regions already painted on it are excluded (optional)." },
+        reference: {
+          type: "string",
+          description: 'Which pixels define the line-art barriers: "all" or "composite" (default, all visible layers without paper), "layer" (the target or active layer), or a layer id from list_layers (e.g. an ink line-art layer).'
+        },
+        tolerance: { type: "number", minimum: 0, maximum: 255, description: "Alpha/colour threshold 0..255 above which a reference pixel counts as line art (default 32)." },
+        closeGap: { type: "number", minimum: 0, maximum: 32, description: "Close small gaps in line art up to this width in pixels, 0..32 (default 0)." },
+        minArea: { type: "integer", minimum: 1, maximum: 1e7, description: "Ignore regions smaller than this many pixels (default 16)." },
+        includeEdge: { type: "boolean", description: "Include regions that touch the canvas border (default false: only enclosed shapes)." },
+        maxRegions: { type: "integer", minimum: 1, maximum: 1e3, description: "Most regions to return, largest first (default 100)." }
+      },
+      additionalProperties: false
+    },
+    annotations: { title: "Find enclosed unfilled regions", ...READ6 },
+    coordinates: { out: ["regions[].point", "regions[].centroid", "regions[].bounds"] },
+    handler: (a) => c.findUnfilledRegions(a)
+  });
   add({
     name: "clear_layer",
     title: "Clear a layer",
@@ -11110,6 +11468,7 @@ function createPaintBrushLibraryToolProvider(controller, options = {}) {
 // src/paint-editor/ui.ts
 var PAINT_TOOLS = [
   { id: "brush", label: "Brush", key: "b" },
+  { id: "fill", label: "Fill", key: "g" },
   { id: "eyedropper", label: "Eyedropper", key: "i" },
   { id: "sticker", label: "Stickers", key: "s" },
   { id: "stroke", label: "Select stroke", key: "v" },
@@ -11124,6 +11483,8 @@ var PaintGesture = class {
   controller;
   box;
   tool = "brush";
+  /** Options the Fill tool (`tool === 'fill'`) passes to `fillRegion` (click to fill; drag horizontally to adjust tolerance). */
+  fillOptions = { reference: "all", tolerance: 32, closeGap: 4, expand: 1, antialias: true };
   /** The last refusal (a hidden or locked layer), for the editor to show. */
   error = null;
   /** The predicted tail of the current stroke in document pixels (draw it as a thin preview). */
@@ -11166,6 +11527,7 @@ var PaintGesture = class {
       this.pick(e);
       return false;
     }
+    if (tool === "fill") return this.fillDown(e);
     if (tool === "sticker") return this.stickerDown(e);
     try {
       const p = this.pen(e);
@@ -11235,6 +11597,18 @@ var PaintGesture = class {
     if (p.x < 0 || p.y < 0 || p.x >= width || p.y >= height) return;
     this.controller.setColor(this.controller.pickColor(p.x, p.y).color);
   }
+  fillDown(e) {
+    const p = this.doc(e);
+    const baseTolerance = this.fillOptions.tolerance ?? 32;
+    try {
+      const filled = this.controller.fillRegion({ ...this.fillOptions, tolerance: baseTolerance, x: p.x, y: p.y });
+      this.mode = { kind: "fill", pointerId: e.pointerId, startX: e.clientX, p, baseTolerance, lastTolerance: baseTolerance, committed: filled.bounds !== null };
+      return true;
+    } catch (err) {
+      this.error = err instanceof Error ? err.message : String(err);
+      return false;
+    }
+  }
   move(e) {
     if (e.pointerType === "pen") this.penAt = { x: e.clientX, y: e.clientY };
     const m = this.mode;
@@ -11255,6 +11629,21 @@ var PaintGesture = class {
       m.to = this.doc(e);
       return;
     }
+    if (m.kind === "fill") {
+      const dx = e.clientX - m.startX;
+      if (Math.abs(dx) < 4) return;
+      const nextTol = Math.max(0, Math.min(255, Math.round(m.baseTolerance + dx * 0.5)));
+      if (nextTol === m.lastTolerance) return;
+      m.lastTolerance = nextTol;
+      try {
+        if (m.committed) this.controller.undo();
+        m.committed = false;
+        m.committed = this.controller.fillRegion({ ...this.fillOptions, tolerance: nextTol, x: m.p.x, y: m.p.y }).bounds !== null;
+      } catch (err) {
+        this.error = err instanceof Error ? err.message : String(err);
+      }
+      return;
+    }
     if (m.kind === "sticker") {
       const p = this.doc(e);
       m.at = { x: round2(p.x + m.dx), y: round2(p.y + m.dy) };
@@ -11316,6 +11705,7 @@ var PaintGesture = class {
     this.penDown = false;
     this.predicted = [];
     if (this.mode?.kind === "stroke") this.controller.activeStroke?.cancel();
+    if (this.mode?.kind === "fill" && this.mode.committed) this.controller.undo();
     if (this.mode?.kind === "sticker") this.controller.cancelStickerPreview();
     this.mode = null;
   }
@@ -12686,6 +13076,8 @@ export {
   emptiedLayers,
   emptyThickChannels,
   engineBrushSourceIds,
+  fillRegionMask,
+  findUnfilledRegionsMask,
   fitZoom,
   grainCatch,
   grainHeights,
@@ -12809,6 +13201,7 @@ export {
   serializePaintDocument,
   serializePaintDocumentExternal,
   solidPaint,
+  squaredDistanceTransform,
   stampCoverage,
   standardBlendMode,
   startWetClock,

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

@@ -1,7 +1,7 @@
 import { PresenceStore, type PresenceActor, type PresenceActorInfo, type PresenceClock, type PresenceState } from '../animation/presence.cjs';
 import type { MixerLoad } from '../paint/mixer.cjs';
 import type { RasterRect } from '../raster/surface.cjs';
-import { type FillLayerOptions, type PaintEditorController, type PaintStrokeInit, type ReplayOptions } from './controller.cjs';
+import { type FillLayerOptions, type FillRegionOptions, type PaintEditorController, type PaintStrokeInit, type ReplayOptions } from './controller.cjs';
 import type { PenPoint } from './engine.cjs';
 export type PaintPresenceActor = PresenceActor;
 export type PaintPresenceState = PresenceState;
@@ -35,6 +35,10 @@ export type PaintAgentCommand = {
     kind: 'fill';
     fill: FillLayerOptions;
     note?: string;
+} | {
+    kind: 'fill-region';
+    fill: FillRegionOptions;
+    note?: string;
 } | {
     kind: 'replay';
     replay: ReplayOptions;

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

@@ -1,7 +1,7 @@
 import { PresenceStore, type PresenceActor, type PresenceActorInfo, type PresenceClock, type PresenceState } from '../animation/presence.js';
 import type { MixerLoad } from '../paint/mixer.js';
 import type { RasterRect } from '../raster/surface.js';
-import { type FillLayerOptions, type PaintEditorController, type PaintStrokeInit, type ReplayOptions } from './controller.js';
+import { type FillLayerOptions, type FillRegionOptions, type PaintEditorController, type PaintStrokeInit, type ReplayOptions } from './controller.js';
 import type { PenPoint } from './engine.js';
 export type PaintPresenceActor = PresenceActor;
 export type PaintPresenceState = PresenceState;
@@ -35,6 +35,10 @@ export type PaintAgentCommand = {
     kind: 'fill';
     fill: FillLayerOptions;
     note?: string;
+} | {
+    kind: 'fill-region';
+    fill: FillRegionOptions;
+    note?: string;
 } | {
     kind: 'replay';
     replay: ReplayOptions;

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

@@ -11,7 +11,7 @@
 import type { MixerLoad } from '../paint/exchange.cjs';
 import { type BlendModeInfo } from '../raster/blend.cjs';
 import type { ImpastoTool, WetMediumKind, WetTool } from './brushes.cjs';
-import type { PaintEditorController } from './controller.cjs';
+import type { FillRegionOptions, PaintEditorController } from './controller.cjs';
 import type { PenPoint } from './engine.cjs';
 import { type Point2 } from './guides.cjs';
 import { type StencilInput } from './stencils.cjs';
@@ -35,7 +35,7 @@ export interface PaintPointerEvent extends PointerSample {
     getCoalescedEvents?(): PaintPointerEvent[];
     getPredictedEvents?(): PaintPointerEvent[];
 }
-export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate' | 'sticker' | 'stroke';
+export type PaintTool = 'brush' | 'fill' | 'eyedropper' | 'pan' | 'rotate' | 'sticker' | 'stroke';
 export declare const PAINT_TOOLS: ReadonlyArray<{
     id: PaintTool;
     label: string;
@@ -52,6 +52,8 @@ export declare class PaintGesture {
     private readonly controller;
     private readonly box;
     tool: PaintTool;
+    /** Options the Fill tool (`tool === 'fill'`) passes to `fillRegion` (click to fill; drag horizontally to adjust tolerance). */
+    fillOptions: Omit<FillRegionOptions, 'x' | 'y' | 'points'>;
     /** The last refusal (a hidden or locked layer), for the editor to show. */
     error: string | null;
     /** The predicted tail of the current stroke in document pixels (draw it as a thin preview). */
@@ -82,6 +84,7 @@ export declare class PaintGesture {
      */
     private stickerDown;
     private pick;
+    private fillDown;
     move(e: PaintPointerEvent): void;
     up(e: PaintPointerEvent): void;
     cancel(): void;

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

@@ -11,7 +11,7 @@
 import type { MixerLoad } from '../paint/exchange.js';
 import { type BlendModeInfo } from '../raster/blend.js';
 import type { ImpastoTool, WetMediumKind, WetTool } from './brushes.js';
-import type { PaintEditorController } from './controller.js';
+import type { FillRegionOptions, PaintEditorController } from './controller.js';
 import type { PenPoint } from './engine.js';
 import { type Point2 } from './guides.js';
 import { type StencilInput } from './stencils.js';
@@ -35,7 +35,7 @@ export interface PaintPointerEvent extends PointerSample {
     getCoalescedEvents?(): PaintPointerEvent[];
     getPredictedEvents?(): PaintPointerEvent[];
 }
-export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate' | 'sticker' | 'stroke';
+export type PaintTool = 'brush' | 'fill' | 'eyedropper' | 'pan' | 'rotate' | 'sticker' | 'stroke';
 export declare const PAINT_TOOLS: ReadonlyArray<{
     id: PaintTool;
     label: string;
@@ -52,6 +52,8 @@ export declare class PaintGesture {
     private readonly controller;
     private readonly box;
     tool: PaintTool;
+    /** Options the Fill tool (`tool === 'fill'`) passes to `fillRegion` (click to fill; drag horizontally to adjust tolerance). */
+    fillOptions: Omit<FillRegionOptions, 'x' | 'y' | 'points'>;
     /** The last refusal (a hidden or locked layer), for the editor to show. */
     error: string | null;
     /** The predicted tail of the current stroke in document pixels (draw it as a thin preview). */
@@ -82,6 +84,7 @@ export declare class PaintGesture {
      */
     private stickerDown;
     private pick;
+    private fillDown;
     move(e: PaintPointerEvent): void;
     up(e: PaintPointerEvent): void;
     cancel(): void;