@pixerate/editor 0.210.0 → 0.211.0

package/dist/image-editor/index.js

@@ -301,6 +301,7 @@ import {
   rasterizeCoverage,
   rasterizeSmartObject,
   readPsd,
+  readShapeComponents,
   referencePoint,
   removeAlpha,
   removeLayer,
@@ -401,7 +402,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-KFIOEOCQ.js";
+} from "../chunk-W3TOZTL7.js";
 import {
   parseCssColor
 } from "../chunk-3CI7FRMK.js";
@@ -1477,8 +1478,9 @@ var ImageEditorRenderer = class {
       ctx.restore();
     }
     const { width: iw, height: ih } = state.imageDimensions;
-    const quickMaskSel = display === "quickMask" && state.quickMaskEditing && !state.selection?.bounds ? this.emptyMask(Math.round(iw), Math.round(ih)) : null;
-    if (state.selection?.bounds && display !== "none" || quickMaskSel || options.draftSelectionPath?.length) {
+    const shownSel = state.selectionPreview !== void 0 ? state.selectionPreview : state.selection;
+    const quickMaskSel = display === "quickMask" && state.quickMaskEditing && !shownSel?.bounds ? this.emptyMask(Math.round(iw), Math.round(ih)) : null;
+    if (shownSel?.bounds && display !== "none" || quickMaskSel || options.draftSelectionPath?.length) {
       ctx.save();
       try {
         applyImageProjectionToContext(ctx, projection);
@@ -1486,8 +1488,8 @@ var ImageEditorRenderer = class {
         ctx.rect(region.x, region.y, region.width, region.height);
         ctx.clip();
         if (quickMaskSel) this.drawQuickMask(ctx, quickMaskSel);
-        else if (state.selection?.bounds && display === "quickMask") this.drawQuickMask(ctx, state.selection);
-        else if (state.selection?.bounds && display === "ants") this.drawAnts(ctx, state.selection, projection.scale / u, options.antsOffset ?? 0);
+        else if (shownSel?.bounds && display === "quickMask") this.drawQuickMask(ctx, shownSel);
+        else if (shownSel?.bounds && display === "ants") this.drawAnts(ctx, shownSel, projection.scale / u, options.antsOffset ?? 0);
         if (options.draftSelectionPath?.length) this.drawDraftPath(ctx, options.draftSelectionPath, projection.scale / u);
       } catch {
       }
@@ -2861,6 +2863,58 @@ function magneticAnchorSpacing(frequency = 57) {
   return 8 + (100 - f);
 }
 
+// src/image-editor/paths.ts
+var WORK_PATH_NAME = "Work Path";
+var counter = 0;
+function newPathId() {
+  counter = (counter + 1) % 1e6;
+  return `path-${Date.now().toString(36)}-${counter.toString(36)}`;
+}
+function pathSvgData(path) {
+  return subpathsToSvgPath(path.components.flatMap((c) => c.subpaths));
+}
+function pathBounds(path) {
+  return vectorMaskBounds({ components: path.components });
+}
+function pathAnchorCount(path) {
+  return path.components.reduce((n, c) => n + c.subpaths.reduce((m, sp) => m + sp.anchors.length, 0), 0);
+}
+function serializePaths(paths) {
+  return paths.map((p) => ({
+    id: p.id,
+    name: p.name,
+    components: JSON.parse(JSON.stringify(p.components)),
+    ...p.fillRule === "evenodd" ? { fillRule: "evenodd" } : {},
+    ...p.work ? { work: true } : {}
+  }));
+}
+function readPaths(stored, problems = []) {
+  if (!Array.isArray(stored)) return [];
+  const out = [];
+  const ids = /* @__PURE__ */ new Set();
+  let work = false;
+  for (const [i, raw] of stored.entries()) {
+    const r = raw;
+    const name = typeof r?.name === "string" && r.name.trim() ? r.name.trim() : `Path ${i + 1}`;
+    try {
+      const components = readShapeComponents(r?.components);
+      let id = typeof r?.id === "string" && r.id ? r.id : newPathId();
+      if (ids.has(id)) id = newPathId();
+      ids.add(id);
+      const path = { id, name, components };
+      if (r?.fillRule === "evenodd") path.fillRule = "evenodd";
+      if (r?.work === true && !work) {
+        path.work = true;
+        work = true;
+      }
+      out.push(path);
+    } catch (err) {
+      problems.push(`Path "${name}" could not be read (${err instanceof Error ? err.message : String(err)}) and was left out.`);
+    }
+  }
+  return out;
+}
+
 // src/image-editor/layers/shape-type-ui.ts
 var DEFAULT_SHAPE_TOOL_OPTIONS = {
   kind: "rect",
@@ -5643,6 +5697,7 @@ var ImageEditorController = class {
       outputOpacity: s.outputOpacity,
       selection: s.selection ?? null,
       ...s.channels?.length ? { channels: s.channels } : {},
+      ...s.paths?.length ? { paths: s.paths } : {},
       source: {
         sourceUrl: s.sourceUrl,
         element: this.imageElement,
@@ -5680,6 +5735,9 @@ var ImageEditorController = class {
     s.selection = entry.selection;
     if (entry.channels?.length) s.channels = entry.channels;
     else delete s.channels;
+    if (entry.paths?.length) s.paths = entry.paths;
+    else delete s.paths;
+    if (s.activePathId && !s.paths?.some((p) => p.id === s.activePathId)) s.activePathId = null;
     if (this.imageElement !== entry.source.element && !this.samplePixelsOverride) this.samplePixels = null;
     this.imageElement = entry.source.element;
     s.sourceUrl = entry.source.sourceUrl;
@@ -6491,6 +6549,138 @@ var ImageEditorController = class {
     const mask = pathToSelection(components, width, height, { ...options, fillRule: path.fillRule ?? options.fillRule });
     return this.setSelection(mask, options.mode ?? "replace");
   }
+  // --- Document paths (the Paths panel) ---
+  /** The document's paths: saved paths and the Work Path, in panel order. */
+  getPaths() {
+    return this.state.paths ?? [];
+  }
+  getPath(id) {
+    return this.state.paths?.find((p) => p.id === id) ?? null;
+  }
+  requirePath(id) {
+    const path = this.getPath(id);
+    if (!path) {
+      const ids = this.getPaths().map((p) => `${p.id} (${p.name})`);
+      throw new LayerOperationError(`There is no path "${id}"; the paths are ${ids.join(", ") || "none (make a work path from a selection, or add one)"}.`);
+    }
+    return path;
+  }
+  /** Selects a path in the Paths panel (or none). View state: no undo step. */
+  setActivePath(id) {
+    if (id !== null) this.requirePath(id);
+    if ((this.state.activePathId ?? null) === id) return;
+    this.state.activePathId = id;
+    this.notify();
+  }
+  commitPaths(next, active) {
+    this.recordHistory();
+    if (next.length) this.state.paths = next;
+    else delete this.state.paths;
+    if (active !== void 0) this.state.activePathId = active;
+    else if (this.state.activePathId && !next.some((p) => p.id === this.state.activePathId)) this.state.activePathId = null;
+    this.notify();
+  }
+  /**
+   * Paths › Make Work Path: the selection's outline, traced, becomes the Work Path (replacing the
+   * last one, unless it was saved). One undo step. Returns the path.
+   */
+  makeWorkPath(options = {}) {
+    const subpaths = this.traceSelection(options);
+    const paths = this.getPaths();
+    const old = paths.find((p) => p.work);
+    const work = { id: old?.id ?? newPathId(), name: WORK_PATH_NAME, components: [{ op: "combine", subpaths }], fillRule: "evenodd", work: true };
+    this.commitPaths(old ? paths.map((p) => p === old ? work : p) : [...paths, work], work.id);
+    return work;
+  }
+  /** A new saved path from geometry (`shape`, `subpaths` or `components`). One undo step. */
+  addPath(input) {
+    const paths = this.getPaths();
+    const path = { id: newPathId(), name: input.name?.trim() || `Path ${paths.filter((p) => !p.work).length + 1}`, components: this.vectorMaskComponents(input) };
+    if (input.fillRule === "evenodd") path.fillRule = "evenodd";
+    this.commitPaths([...paths.filter((p) => !p.work), path, ...paths.filter((p) => p.work)], path.id);
+    return path;
+  }
+  /** Replaces a path's geometry (its name is kept). One undo step. */
+  setPathGeometry(id, input) {
+    const old = this.requirePath(id);
+    const path = { ...old, components: this.vectorMaskComponents(input) };
+    if (input.fillRule === "evenodd") path.fillRule = "evenodd";
+    else if (input.fillRule === "nonzero") delete path.fillRule;
+    this.commitPaths(this.getPaths().map((p) => p.id === id ? path : p));
+    return path;
+  }
+  /** Renames a path; renaming the Work Path saves it (Photoshop's Save Path). One undo step. */
+  renamePath(id, name) {
+    const old = this.requirePath(id);
+    const trimmed = name.trim();
+    if (!trimmed) throw new LayerOperationError("A path needs a name.");
+    const path = { ...old, name: trimmed };
+    delete path.work;
+    this.commitPaths(this.getPaths().map((p) => p.id === id ? path : p));
+    return path;
+  }
+  /** Duplicates a path as a saved path. One undo step. */
+  duplicatePath(id, name) {
+    const old = this.requirePath(id);
+    const copy = { ...old, id: newPathId(), name: name?.trim() || `${old.name} copy`, components: JSON.parse(JSON.stringify(old.components)) };
+    delete copy.work;
+    const paths = this.getPaths();
+    this.commitPaths([...paths.filter((p) => !p.work), copy, ...paths.filter((p) => p.work)], copy.id);
+    return copy;
+  }
+  /** Deletes a path. One undo step. */
+  deletePath(id) {
+    this.requirePath(id);
+    this.commitPaths(this.getPaths().filter((p) => p.id !== id));
+  }
+  /** The area a path fills over the image, as a selection mask. */
+  pathArea(path, options = {}) {
+    const { width, height } = this.naturalSize;
+    return pathToSelection(path.components, width, height, { ...options, fillRule: path.fillRule ?? options.fillRule });
+  }
+  /** Paths › Make Selection: loads a path as the selection, combined by `mode`. One undo step. */
+  loadPathAsSelection(id, options = {}) {
+    if (options.feather !== void 0 && !(options.feather >= 0 && options.feather <= 1e3)) throw new LayerOperationError("feather must be from 0 to 1000 px.");
+    return this.setSelection(this.pathArea(this.requirePath(id), options), options.mode ?? "replace");
+  }
+  /**
+   * Paths › Fill Path: fills the path's area on a pixel layer (default the active one) with a
+   * colour (default the foreground). The selection is not changed. One undo step.
+   */
+  fillPath(id, options = {}) {
+    const area = this.pathArea(this.requirePath(id));
+    if (!area.bounds) throw new LayerOperationError("The path encloses no area to fill.");
+    return this.withSelection(area, () => this.fillPixels({ ...options, useSelection: true }));
+  }
+  /**
+   * Paths › Stroke Path: strokes along the path's outline on a pixel layer (default the active
+   * one), `width` px wide and centred on it. The selection is not changed. One undo step.
+   */
+  strokePath(id, options) {
+    const area = this.pathArea(this.requirePath(id), { antiAlias: true });
+    if (!area.bounds) throw new LayerOperationError("The path encloses no area; stroke a closed path.");
+    return this.withSelection(area, () => this.strokeSelection({ ...options, location: "center" }));
+  }
+  /** Paths › Add Vector Mask: masks a layer (default the active one) with a document path. One undo step. */
+  addVectorMaskFromPath(pathId, layerId) {
+    const path = this.requirePath(pathId);
+    const id = layerId ?? this.state.activeLayerId;
+    if (!id) throw new LayerOperationError("No layer given and none is active; pass layerId (see list_layers).");
+    return this.addVectorMask(id, "path", { components: path.components.map((c) => ({ op: c.op, subpaths: c.subpaths })), ...path.fillRule ? { fillRule: path.fillRule } : {} });
+  }
+  /** Runs `fn` with `mask` as the selection, then puts the selection back, all as one undo step. */
+  withSelection(mask, fn) {
+    return this.asOneStep(() => {
+      const before = this.state.selection ?? null;
+      this.state.selection = mask;
+      try {
+        return fn();
+      } finally {
+        this.state.selection = before;
+        this.notify();
+      }
+    });
+  }
   /** Replaces a vector mask's path (its properties are kept). One undo step. Returns the vector mask. */
   setVectorMaskPath(id, path) {
     const { vm } = this.requireVectorMask(id);
@@ -8511,6 +8701,17 @@ var ImageEditorController = class {
     this.notify();
     return true;
   }
+  /**
+   * Shows `mask` in place of the selection while a gesture runs (Quick Selection as the brush
+   * moves; `null` shows nothing selected), or with `undefined` stops. View state only: no undo
+   * step, not saved.
+   */
+  setSelectionPreview(mask) {
+    if (this.state.selectionPreview === mask) return;
+    if (mask === void 0) delete this.state.selectionPreview;
+    else this.state.selectionPreview = mask;
+    this.notify();
+  }
   /** Select › All. */
   selectAll() {
     const { width, height } = this.naturalSize;
@@ -10482,6 +10683,10 @@ var ImageEditorController = class {
     }));
     if (psdChannels.length) s.channels = psdChannels;
     else delete s.channels;
+    const psdPaths = (result.paths ?? []).map((p) => ({ id: newPathId(), name: p.name, components: p.components, ...p.work ? { work: true } : {} }));
+    if (psdPaths.length) s.paths = psdPaths;
+    else delete s.paths;
+    s.activePathId = null;
     s.selectedAnnotationId = null;
     s.activeLayerId = defaultActiveLayerId(s.layers);
     s.activeTarget = "pixels";
@@ -10679,7 +10884,7 @@ var ImageEditorController = class {
       opacity: c.opacity,
       indicates: c.indicates
     }));
-    const result = exportPsd({ width, height, layers: prepared, merged, mergedDeep, resolution: this.psdResolution, patterns: this.state.patterns, globalLight: this.state.globalLight, depth, alphaChannels, ...color });
+    const result = exportPsd({ width, height, layers: prepared, merged, mergedDeep, resolution: this.psdResolution, patterns: this.state.patterns, globalLight: this.state.globalLight, depth, alphaChannels, paths: this.getPaths(), ...color });
     warnings.push(...result.warnings);
     return { bytes: result.bytes, warnings, psb: result.psb, width, height };
   }
@@ -10753,6 +10958,7 @@ var ImageEditorController = class {
       out = this.serializeState();
       if (this.state.selection?.bounds) out.selection = serializeSelection(this.state.selection);
       if (this.state.channels?.length) out.channels = serializeChannels(this.state.channels);
+      if (this.state.paths?.length) out.paths = serializePaths(this.state.paths);
     } finally {
       if (root) {
         this.state = current;
@@ -10797,6 +11003,10 @@ var ImageEditorController = class {
     const channels = deserializeChannels(data.channels, this.naturalSize, problems);
     if (channels.length) this.state.channels = channels;
     else delete this.state.channels;
+    const paths = readPaths(data.paths, problems);
+    if (paths.length) this.state.paths = paths;
+    else delete this.state.paths;
+    this.state.activePathId = null;
     if (problems.length) this.lastLoadProblems = [...this.lastLoadProblems, ...problems];
     this.notify();
   }
@@ -11773,7 +11983,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_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 SELECT = /^(make_work_path|add_path|set_path_geometry|rename_path|duplicate_path|delete_path|fill_path|stroke_path|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)$/;
@@ -14497,6 +14707,9 @@ var SelectionGesture = class {
   /** The last error (e.g. pixels unavailable for the wand), for the UI to show. */
   error = null;
   pending = Promise.resolve();
+  /** Quick Selection while dragging: the selection before the stroke, how the stroke combines, the pixels. */
+  quick = null;
+  livePreviews = Promise.resolve();
   get active() {
     return this.start !== null || this.polygon !== null || this.magnetic !== null;
   }
@@ -14504,6 +14717,46 @@ var SelectionGesture = class {
   get settled() {
     return this.pending;
   }
+  /** Resolves once no live Quick Selection preview is being computed. */
+  get previewed() {
+    return this.livePreviews;
+  }
+  /** Grows the Quick Selection preview to the stroke so far: one at a time, the newest points following. */
+  growPreview() {
+    const q = this.quick;
+    if (!q) return;
+    if (q.running) {
+      q.dirty = true;
+      return;
+    }
+    q.running = true;
+    this.livePreviews = (async () => {
+      do {
+        q.dirty = false;
+        const stroke = this.points.slice();
+        const options = this.getOptions();
+        try {
+          const pixels = await q.pixels;
+          if (!pixels || this.quick !== q) break;
+          const { mask } = await this.controller.runSelectionJob(
+            {
+              op: "quick",
+              stroke,
+              size: options.quickSize ?? 30,
+              grow: q.mode === "add",
+              enhanceEdge: options.quickEnhance ?? false,
+              selection: q.mode === "add" && q.base?.bounds ? serializeMask(q.base) : null
+            },
+            pixels
+          );
+          if (this.quick === q) this.controller.setSelectionPreview(combineSelections(q.base, mask, q.mode));
+        } catch {
+          break;
+        }
+      } while (q.dirty && this.quick === q);
+      q.running = false;
+    })();
+  }
   /** The anchors of a Magnetic Lasso being drawn (empty otherwise). */
   get magneticAnchors() {
     const m = this.magnetic;
@@ -14515,7 +14768,8 @@ var SelectionGesture = class {
     if (this.polygon) return this.current ? [...this.polygon, this.current] : this.polygon.slice();
     if (!this.start || !this.current) return null;
     const { tool } = this.getOptions();
-    if (tool === "lasso" || tool === "quick") return this.points.length > 1 ? this.points.slice() : null;
+    if (tool === "quick") return null;
+    if (tool === "lasso") return this.points.length > 1 ? this.points.slice() : null;
     const rect = normalizeRect({
       x: this.start.x,
       y: this.start.y,
@@ -14628,6 +14882,18 @@ var SelectionGesture = class {
     this.start = point;
     this.current = point;
     this.points = [point];
+    if (options.tool === "quick") {
+      const picked = selectionModeFromModifiers(modifiers, options.mode);
+      const base = this.controller.getSelection();
+      this.quick = {
+        base,
+        mode: picked === "replace" && base ? "add" : picked,
+        pixels: this.controller.getSamplePixels({ sample: options.quickSampleAll === false ? "active-layer" : "composite" }).catch(() => null),
+        running: false,
+        dirty: false
+      };
+      this.growPreview();
+    }
   }
   /** Pointer move; returns true when the draft changed (re-render). */
   move(point, modifiers = {}) {
@@ -14654,6 +14920,7 @@ var SelectionGesture = class {
       const last = this.points[this.points.length - 1];
       if (Math.hypot(point.x - last.x, point.y - last.y) < 0.5) return false;
       this.points.push(point);
+      if (drawn === "quick") this.growPreview();
     }
     return true;
   }
@@ -14689,7 +14956,8 @@ var SelectionGesture = class {
       this.start = null;
       this.current = null;
       this.points = [];
-      const strokeMode = mode === "replace" && this.controller.getSelection() ? "add" : mode;
+      const strokeMode = this.quick?.mode ?? (mode === "replace" && this.controller.getSelection() ? "add" : mode);
+      this.quick = null;
       this.pending = this.controller.quickSelect([stroke], {
         size: options.quickSize ?? 30,
         mode: strokeMode,
@@ -14700,7 +14968,7 @@ var SelectionGesture = class {
         (err) => {
           this.error = err instanceof Error ? err.message : String(err);
         }
-      );
+      ).finally(() => this.controller.setSelectionPreview(void 0));
       return false;
     }
     const path = this.draftPath;
@@ -14829,6 +15097,10 @@ var SelectionGesture = class {
   }
   /** Abandons a drag (or a polygonal lasso) without changing the selection. */
   cancel() {
+    if (this.quick) {
+      this.quick = null;
+      this.controller.setSelectionPreview(void 0);
+    }
     this.start = null;
     this.current = null;
     this.points = [];
@@ -16945,6 +17217,19 @@ function createImageShapeTools(controller) {
     fillRule: { type: "string", enum: ["nonzero", "evenodd"], description: "Winding rule within a component (default nonzero)." }
   };
   const LAYER = { type: "string", minLength: 1, description: "The layer (see list_layers). Not a shape layer: its path already is its vector mask." };
+  const PATH_ID = { type: "string", minLength: 1, description: "A document path id from list_paths." };
+  const fromPathId = (args) => {
+    if (args.pathId === void 0) return null;
+    const own = Object.keys(PATH_PROPS).filter((k) => args[k] !== void 0);
+    if (own.length) throw new Error(`Give pathId or ${own.join(" / ")}, not both.`);
+    const path = controller.getPath(String(args.pathId));
+    if (!path) throw new Error(`No path "${String(args.pathId)}". Call list_paths for ids.`);
+    return { components: path.components.map((c) => ({ op: c.op, subpaths: c.subpaths })), ...path.fillRule ? { fillRule: path.fillRule } : {} };
+  };
+  const pathSummary = (id) => {
+    const p = controller.getPath(id);
+    return { id: p.id, name: p.name, work: Boolean(p.work), fillRule: p.fillRule ?? "nonzero", anchors: pathAnchorCount(p), bounds: pathBounds(p) };
+  };
   const TRACE_PROPS = {
     tolerance: { type: "number", minimum: 0.1, maximum: 10, description: "How far (px) the path may stray from the selection edge (default 0.5; lower is tighter, more anchors)." },
     cornerRoundness: { type: "number", minimum: 0, maximum: 1, description: "0: straight sides and sharp corners; 1: as smooth as the outline allows (default 0.5)." },
@@ -16976,6 +17261,7 @@ function createImageShapeTools(controller) {
       type: "object",
       $defs: DEFS2,
       properties: {
+        pathId: { ...PATH_ID, description: "A document path from list_paths, instead of shape / subpaths / components." },
         ...PATH_PROPS,
         feather: { type: "number", minimum: 0, maximum: 1e3, description: "Feather radius in px (default 0)." },
         antiAlias: { type: "boolean", description: "Soft edges (default true); false makes every pixel fully in or out." },
@@ -16986,7 +17272,7 @@ function createImageShapeTools(controller) {
     annotations: { title: "Make a selection from a path", ...WRITE8 },
     handler: (args) => {
       const mode = args.mode;
-      controller.pathToSelection(pathSpec(args), { feather: args.feather, antiAlias: args.antiAlias, mode });
+      controller.pathToSelection(fromPathId(args) ?? pathSpec(args), { feather: args.feather, antiAlias: args.antiAlias, mode });
       const sel = controller.getSelection();
       return { empty: !sel, bounds: sel?.bounds ?? null, area: Math.round(sel ? selectionArea(sel) : 0) };
     }
@@ -17008,7 +17294,8 @@ function createImageShapeTools(controller) {
       $defs: DEFS2,
       properties: {
         layerId: LAYER,
-        from: { type: "string", enum: ["path", "selection", "reveal-all", "hide-all"], description: "path (default when a shape, subpaths or components are given), selection (trace the current selection), reveal-all or hide-all (an empty path)." },
+        from: { type: "string", enum: ["path", "selection", "reveal-all", "hide-all"], description: "path (default when a shape, subpaths, components or pathId are given), selection (trace the current selection), reveal-all or hide-all (an empty path)." },
+        pathId: { ...PATH_ID, description: "A document path from list_paths to use as the mask (Paths \u203A Add Vector Mask), instead of shape / subpaths / components." },
         ...PATH_PROPS,
         ...TRACE_PROPS
       },
@@ -17018,7 +17305,7 @@ function createImageShapeTools(controller) {
     annotations: { title: "Add a vector mask", ...WRITE8 },
     handler: (args) => {
       const id = layerArg(args.layerId);
-      const spec = pathSpec(args);
+      const spec = fromPathId(args) ?? pathSpec(args);
       const hasPath = spec.components?.length || spec.shape !== void 0 || spec.subpaths !== void 0;
       const from = args.from ?? (hasPath ? "path" : "reveal-all");
       if (from !== "selection" && TRACE_KEYS.some((k) => args[k] !== void 0)) throw new Error("tolerance, cornerRoundness and minArea apply only to from selection.");
@@ -17086,7 +17373,139 @@ function createImageShapeTools(controller) {
       return { layerId: id, vectorMask: null };
     }
   };
-  return [get, add2, update, setComponent, addComponent, removeComponent, merge, getVectorMask, addVectorMask, setVectorMaskPath, setVectorMaskProps, rasterizeVectorMask, removeVectorMask, selectionToPath, pathToSelection2];
+  const listPaths = {
+    name: "list_paths",
+    title: "List document paths",
+    description: "Paths panel: the document's saved paths and its Work Path (paths kept with the document, on no layer), each with id, name, work (true for the Work Path, which the next make_work_path replaces), fill rule, anchor count and bounds, and which is active. Use the ids with path_to_selection, add_vector_mask, fill_path, stroke_path and the other path tools.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { title: "List document paths", ...READ10 },
+    handler: () => ({ paths: controller.getPaths().map((p) => pathSummary(p.id)), activePathId: controller.getState().activePathId ?? null })
+  };
+  const getPath2 = {
+    name: "get_path",
+    title: "Read a document path",
+    description: "Reads a document path: its summary, svg (compact SVG path data) and components (op, subpaths of anchors with handles, in document pixels), ready to edit and pass back to set_path_geometry.",
+    inputSchema: { type: "object", properties: { pathId: PATH_ID }, required: ["pathId"], additionalProperties: false },
+    annotations: { title: "Read a document path", ...READ10 },
+    handler: ({ pathId }) => {
+      const p = controller.getPath(String(pathId));
+      if (!p) throw new Error(`No path "${String(pathId)}". Call list_paths for ids.`);
+      return { path: { ...pathSummary(p.id), svg: pathSvgData(p), components: p.components } };
+    }
+  };
+  const makeWorkPath = {
+    name: "make_work_path",
+    title: "Make a work path from the selection",
+    description: "Paths \u203A Make Work Path: traces the selection's outline (within tolerance px) into the Work Path, replacing the last Work Path unless it was saved (rename_path saves it). Use it to keep a selection as an editable, resolution-independent outline. One undo step. Returns the path.",
+    inputSchema: { type: "object", properties: { ...TRACE_PROPS }, additionalProperties: false },
+    annotations: { title: "Make a work path from the selection", ...WRITE8 },
+    handler: (args) => ({ path: pathSummary(controller.makeWorkPath(traceOptions(args)).id) })
+  };
+  const addPath = {
+    name: "add_path",
+    title: "Add a document path",
+    description: "Adds a saved document path from a live shape, free subpaths or SVG path data, or components (document pixels), as add_shape_layer takes them. One undo step. Returns the path.",
+    inputSchema: {
+      type: "object",
+      $defs: DEFS2,
+      properties: { name: { type: "string", description: 'The path name (default "Path n").' }, ...PATH_PROPS },
+      additionalProperties: false
+    },
+    annotations: { title: "Add a document path", ...WRITE8 },
+    handler: (args) => {
+      const spec = pathSpec(args);
+      if (!spec.components?.length && spec.shape === void 0 && spec.subpaths === void 0) throw new Error("Give the path as shape, subpaths or components.");
+      return { path: pathSummary(controller.addPath({ ...spec, name: args.name }).id) };
+    }
+  };
+  const setPathGeometry = {
+    name: "set_path_geometry",
+    title: "Replace a document path",
+    description: "Replaces a document path's geometry (shape, subpaths or components, document pixels); its name is kept. Read it with get_path first to change part of it. One undo step. Returns the path.",
+    inputSchema: { type: "object", $defs: DEFS2, properties: { pathId: PATH_ID, ...PATH_PROPS }, required: ["pathId"], additionalProperties: false },
+    annotations: { title: "Replace a document path", ...WRITE_IDEMPOTENT5 },
+    handler: (args) => ({ path: pathSummary(controller.setPathGeometry(String(args.pathId), pathSpec(args)).id) })
+  };
+  const renamePath = {
+    name: "rename_path",
+    title: "Rename or save a path",
+    description: "Renames a document path. Renaming the Work Path saves it (Paths \u203A Save Path), so make_work_path no longer replaces it. One undo step. Returns the path.",
+    inputSchema: { type: "object", properties: { pathId: PATH_ID, name: { type: "string", minLength: 1, description: "The new name." } }, required: ["pathId", "name"], additionalProperties: false },
+    annotations: { title: "Rename or save a path", ...WRITE_IDEMPOTENT5 },
+    handler: ({ pathId, name }) => ({ path: pathSummary(controller.renamePath(String(pathId), String(name)).id) })
+  };
+  const duplicatePath = {
+    name: "duplicate_path",
+    title: "Duplicate a path",
+    description: 'Duplicates a document path as a saved path (default name "<name> copy"). One undo step. Returns the new path.',
+    inputSchema: { type: "object", properties: { pathId: PATH_ID, name: { type: "string", description: "The copy's name." } }, required: ["pathId"], additionalProperties: false },
+    annotations: { title: "Duplicate a path", ...WRITE8 },
+    handler: ({ pathId, name }) => ({ path: pathSummary(controller.duplicatePath(String(pathId), name).id) })
+  };
+  const deletePath = {
+    name: "delete_path",
+    title: "Delete a path",
+    description: "Deletes a document path (undo_image brings it back). Returns the remaining paths.",
+    inputSchema: { type: "object", properties: { pathId: PATH_ID }, required: ["pathId"], additionalProperties: false },
+    annotations: { title: "Delete a path", ...DESTRUCTIVE6 },
+    handler: ({ pathId }) => {
+      controller.deletePath(String(pathId));
+      return { paths: controller.getPaths().map((p) => pathSummary(p.id)) };
+    }
+  };
+  const PAINT_PROPS = {
+    layerId: { type: "string", description: "The pixel layer to paint on (default the active layer)." },
+    color: { type: "string", description: "A CSS colour such as #ff0000 (default the foreground colour)." },
+    opacity: { type: "number", minimum: 0, maximum: 1, description: "Opacity 0..1 (default 1)." }
+  };
+  const fillPath = {
+    name: "fill_path",
+    title: "Fill a path",
+    description: "Paths \u203A Fill Path: fills the area a document path encloses on a pixel layer with a colour. The selection is not changed. One undo step. Returns what was painted.",
+    inputSchema: { type: "object", properties: { pathId: PATH_ID, ...PAINT_PROPS }, required: ["pathId"], additionalProperties: false },
+    annotations: { title: "Fill a path", ...WRITE8 },
+    handler: (args) => controller.fillPath(String(args.pathId), { layerId: args.layerId, color: args.color, opacity: args.opacity })
+  };
+  const strokePath = {
+    name: "stroke_path",
+    title: "Stroke a path",
+    description: "Paths \u203A Stroke Path: strokes along a document path's outline on a pixel layer, width px wide and centred on it. The selection is not changed. One undo step. Returns what was painted.",
+    inputSchema: {
+      type: "object",
+      properties: { pathId: PATH_ID, width: { type: "number", exclusiveMinimum: 0, maximum: 250, description: "Stroke width in px." }, ...PAINT_PROPS },
+      required: ["pathId", "width"],
+      additionalProperties: false
+    },
+    annotations: { title: "Stroke a path", ...WRITE8 },
+    handler: (args) => controller.strokePath(String(args.pathId), { width: args.width, layerId: args.layerId, color: args.color, opacity: args.opacity })
+  };
+  return [
+    get,
+    add2,
+    update,
+    setComponent,
+    addComponent,
+    removeComponent,
+    merge,
+    getVectorMask,
+    addVectorMask,
+    setVectorMaskPath,
+    setVectorMaskProps,
+    rasterizeVectorMask,
+    removeVectorMask,
+    selectionToPath,
+    pathToSelection2,
+    listPaths,
+    getPath2,
+    makeWorkPath,
+    addPath,
+    setPathGeometry,
+    renamePath,
+    duplicatePath,
+    deletePath,
+    fillPath,
+    strokePath
+  ];
 }
 
 // src/image-editor/type-tools.ts
@@ -17733,6 +18152,9 @@ var SelectAndMaskSession = class {
   dragStart = null;
   pixels = null;
   previewPixels = null;
+  /** The layers below the active one, composited (On Layers shows them where nothing is selected). */
+  below = null;
+  belowPreview = null;
   base;
   previewMask = null;
   baseMask = null;
@@ -17764,10 +18186,24 @@ var SelectAndMaskSession = class {
       this.emit();
       return false;
     }
+    this.below = this.layersBelow();
     this.rescale();
     this.recompute();
     return true;
   }
+  /** The visible layers under the active one, composited at full size, or null when there are none. */
+  layersBelow() {
+    const active = this.controller.getState().activeLayerId;
+    const flat = flattenLayers(this.controller.getLayers()).filter((l) => l.type !== "group");
+    const at = flat.findIndex((l) => l.id === active);
+    const ids = (at > 0 ? flat.slice(0, at) : []).filter((l) => l.visible).map((l) => l.id);
+    if (!ids.length) return null;
+    try {
+      return this.controller.compositePixels(void 0, { layerIds: ids });
+    } catch {
+      return null;
+    }
+  }
   subscribe(listener) {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
@@ -17800,6 +18236,7 @@ var SelectAndMaskSession = class {
     const w = Math.max(1, Math.round(px2.width * s));
     const h = Math.max(1, Math.round(px2.height * s));
     this.previewPixels = scalePixels(px2, w, h);
+    this.belowPreview = this.below ? scalePixels(this.below, w, h) : null;
     this.baseMask = this.base?.bounds ? s === 1 ? this.base : resizeSelection(this.base, w, h) : null;
   }
   /**
@@ -17923,6 +18360,20 @@ var SelectAndMaskSession = class {
           }
           break;
         }
+        case "on-layers": {
+          const under = this.belowPreview?.data;
+          let ur = checker;
+          let ug = checker;
+          let ub = checker;
+          if (under) {
+            const ua = under[p + 3] / 255;
+            ur = under[p] * ua + checker * (1 - ua);
+            ug = under[p + 1] * ua + checker * (1 - ua);
+            ub = under[p + 2] * ua + checker * (1 - ua);
+          }
+          o = [r + (ur - r) * hide, g + (ug - g) * hide, b + (ub - b) * hide];
+          break;
+        }
         default:
           o = [r + (checker - r) * hide, g + (checker - g) * hide, b + (checker - b) * hide];
       }
@@ -20250,6 +20701,7 @@ export {
   WGSL_SHADE,
   WGSL_STEP,
   WORKING_SPACE_OPTIONS,
+  WORK_PATH_NAME,
   WORK_SIZE,
   WetGpuEngine,
   WetMedium,
@@ -20715,6 +21167,7 @@ export {
   newEffectId,
   newLayerId,
   newLayerOptions,
+  newPathId,
   normalizeAdjustmentLayer,
   normalizeAdjustmentLayers,
   normalizeAngle,
@@ -20771,8 +21224,11 @@ export {
   parseVersionedDescriptor,
   patchParagraphStyle,
   patchTextStyle,
+  pathAnchorCount,
+  pathBounds,
   pathStrokeCoverage,
   pathStrokeDabs,
+  pathSvgData,
   pathToSelection,
   perDabStrength,
   photoFilterMatrix,
@@ -20825,9 +21281,11 @@ export {
   readAdjustmentControls,
   readDeepRegion,
   readPaintSource,
+  readPaths,
   readPixel,
   readPsd,
   readRegion,
+  readShapeComponents,
   readSourceRegion,
   rectSelection,
   rectToQuad,
@@ -20916,6 +21374,7 @@ export {
   serializeLayers,
   serializeLayersExternal,
   serializeMask,
+  serializePaths,
   serializePatterns,
   serializeSelection,
   setCloneTransformValue,