@pixerate/editor 0.208.0 → 0.209.0

package/dist/image-editor/index.js

@@ -5103,6 +5103,7 @@ var ImageEditorController = class {
   /** The segmentation provider behind `selectSubject` (see `setSegmentationProvider`). */
   segmentation = null;
   selectionWorker = null;
+  documentOpener = null;
   /** The effects provider slot (see `setEffectsProvider`). */
   effects = new EffectsSlot();
   /** Renders provider effects: effect smart filter results and effect layers. */
@@ -5114,6 +5115,7 @@ var ImageEditorController = class {
     if (options.effects) this.effects.set(options.effects);
     if (options.segmentation) this.segmentation = options.segmentation;
     if (options.selectionWorker) this.selectionWorker = new SelectionWorkerClient(options.selectionWorker);
+    if (options.openDocument) this.documentOpener = options.openDocument;
     this.maxHistoryDepth = options.maxHistoryDepth ?? 50;
     if (options.textShaper !== void 0) this.textShaperValue = options.textShaper;
     this.maxHistoryBytes = options.maxHistoryBytes ?? 512 * 1024 * 1024;
@@ -5311,6 +5313,70 @@ var ImageEditorController = class {
     this.selectionWorker?.terminate();
     this.selectionWorker = factory ? new SelectionWorkerClient(factory) : null;
   }
+  /** Sets (or with `null` removes) how new documents are opened (see `DocumentOpener`). Not an edit. */
+  setDocumentOpener(opener) {
+    if (this.documentOpener === opener) return;
+    this.documentOpener = opener;
+    this.notify();
+  }
+  /** Whether the host can open new documents (the New Document outputs are available). */
+  get canOpenDocuments() {
+    return this.documentOpener !== null;
+  }
+  /**
+   * A new one-layer document from the selection (or `options.selection`) on a pixel layer
+   * (`layerId`, default the active one), the size of this image: the selected pixels on
+   * transparency, or with `withMask` the whole layer masked by the selection. This document is
+   * not changed. `decontaminate` (0..100) cleans the soft edge's colours as the new-layer
+   * outputs do.
+   */
+  documentFromSelection(options = {}) {
+    const id = options.layerId ?? this.state.activeLayerId;
+    if (!id) throw new LayerOperationError("No layer given and none is active; pass layerId (see list_layers).");
+    const layer = requireLayer(this.state.layers, id).layer;
+    if (layer.type !== "pixel") throw new LayerOperationError(`A new document needs a pixel layer; "${id}" is a ${layer.type} layer.`);
+    const sel = options.selection ?? this.state.selection;
+    if (!sel?.bounds) throw new LayerOperationError("Nothing is selected; select what goes in the new document first.");
+    const { width, height } = this.naturalSize;
+    const surface = this.surfaceOf(layer);
+    let copy;
+    if (options.withMask) {
+      let mask = this.maskFromSelection(sel);
+      if (layer.offset.x || layer.offset.y) mask = { ...mask, surface: translateSurface(mask.surface, -layer.offset.x, -layer.offset.y) };
+      copy = { ...layer, id: newLayerId(), surface, mask };
+    } else {
+      const sb = sel.bounds;
+      const src = { x: sb.x - layer.offset.x, y: sb.y - layer.offset.y, width: sb.width, height: sb.height };
+      const px2 = readRegion(surface, src);
+      const data = sel.data;
+      for (let y = 0; y < sb.height; y++) {
+        for (let x = 0; x < sb.width; x++) px2[(y * sb.width + x) * 4 + 3] = Math.round(px2[(y * sb.width + x) * 4 + 3] * (data[(sb.y + y) * width + sb.x + x] / 255));
+      }
+      copy = { ...layer, id: newLayerId(), surface: surfaceFromPixels({ width: src.width, height: src.height, data: px2 }, 4, src.x, src.y) };
+      delete copy.mask;
+    }
+    delete copy.source;
+    copy.visible = true;
+    const amount = Math.min(100, Math.max(0, options.decontaminate ?? 0)) / 100;
+    if (amount > 0) copy = { ...copy, surface: this.decontaminatedSurface(copy, layer, sel, amount, Math.max(4, options.radius ?? 0)) };
+    const { layers, assets, smartContents } = serializeLayers([copy]);
+    const out = {
+      version: LAYERED_SCHEMA_VERSION,
+      width,
+      height,
+      layers,
+      assets,
+      activeLayerId: copy.id,
+      crop: null,
+      transform: { ...DEFAULT_TRANSFORM },
+      opacity: 1
+    };
+    if (smartContents) out.smartContents = smartContents;
+    if (this.state.bitDepth === 16 || this.state.bitDepth === 32) out.bitDepth = this.state.bitDepth;
+    if (this.state.colorProfile) out.colorProfile = serializeColorProfile(this.state.colorProfile);
+    if (this.state.colorMode) out.colorMode = serializeColorMode(this.state.colorMode);
+    return out;
+  }
   /** Whether the long selections run in a worker. */
   get hasSelectionWorker() {
     return this.selectionWorker !== null;
@@ -8752,8 +8818,12 @@ var ImageEditorController = class {
       throw new Error("Object aware refinement needs a segmentation model (setSegmentationProvider); use refineMode color.");
     }
     const amount = Math.min(100, Math.max(0, options.decontaminate ?? 0)) / 100;
-    const toLayer = output === "new-layer" || output === "new-layer-with-mask";
-    if (amount > 0 && !toLayer) throw new Error("Decontaminate colors writes the cleaned colours to a new layer: use output new-layer or new-layer-with-mask.");
+    const toDocument = output === "new-document" || output === "new-document-with-mask";
+    const toLayer = output === "new-layer" || output === "new-layer-with-mask" || toDocument;
+    if (amount > 0 && !toLayer) throw new Error("Decontaminate colors writes the cleaned colours to a new layer or document: use output new-layer, new-layer-with-mask, new-document or new-document-with-mask.");
+    if (toDocument && !this.documentOpener) {
+      throw new Error("This editor cannot open new documents (no document opener is set); use output new-layer or new-layer-with-mask instead.");
+    }
     let layerId;
     if (output !== "selection") {
       layerId = options.layerId ?? this.state.activeLayerId ?? void 0;
@@ -8778,6 +8848,12 @@ var ImageEditorController = class {
     }
     const refined = refineSelection(pixels, sel, params, edited.refineBrush);
     if (!refined.bounds) throw new Error("Refining left nothing selected; use a smaller shiftEdge or contrast.");
+    if (toDocument) {
+      const document2 = this.documentFromSelection({ layerId, withMask: output === "new-document-with-mask", selection: refined, decontaminate: amount * 100, radius: params.radius });
+      const name = `${requireLayer(this.state.layers, layerId).layer.name || "Layer"} ${output === "new-document" ? "cutout" : "masked"}`;
+      const documentId = await this.documentOpener(document2, { name, from: "select-and-mask" });
+      return { output, layerId, refineMode, ...documentId ? { documentId } : {} };
+    }
     return this.asOneStep(() => {
       this.setSelection(refined);
       if (output === "selection") return { output, refineMode };
@@ -8808,6 +8884,16 @@ var ImageEditorController = class {
     const layer = requireLayer(this.state.layers, id).layer;
     const source = requireLayer(this.state.layers, sourceId).layer;
     if (layer.type !== "pixel" || source.type !== "pixel" || !coverage.bounds) return;
+    const surface = this.decontaminatedSurface(layer, source, coverage, amount, radius);
+    const next = mapLayer(this.state.layers, id, (l) => {
+      const updated = { ...l, surface };
+      delete updated.source;
+      return updated;
+    });
+    this.commitLayers(next);
+  }
+  /** `layer`'s surface with Decontaminate Colors applied along `coverage`'s soft edge, colours read from `source`. */
+  decontaminatedSurface(layer, source, coverage, amount, radius) {
     const { width, height } = this.naturalSize;
     const pad = Math.ceil(radius * 3);
     const b = coverage.bounds;
@@ -8823,12 +8909,7 @@ var ImageEditorController = class {
     for (let y = 0; y < box.height; y++) cov.set(all.subarray((box.y + y) * width + box.x, (box.y + y) * width + box.x + box.width), y * box.width);
     const cleaned = decontaminateColors(original, cov, box.width, box.height, amount, radius);
     for (let i = 3; i < cleaned.length; i += 4) cleaned[i] = rgba[i];
-    const next = mapLayer(this.state.layers, id, (l) => {
-      const updated = { ...l, surface: writeRegion(surface, src, cleaned) };
-      delete updated.source;
-      return updated;
-    });
-    this.commitLayers(next);
+    return writeRegion(surface, src, cleaned);
   }
   /**
    * Loads a selection from a mask image (an AI segmentation, a saved mask): a data URL / URL or
@@ -11805,7 +11886,9 @@ var REFINE_OUTPUTS = [
   { id: "selection", label: "Selection" },
   { id: "layer-mask", label: "Layer Mask" },
   { id: "new-layer", label: "New Layer" },
-  { id: "new-layer-with-mask", label: "New Layer with Layer Mask" }
+  { id: "new-layer-with-mask", label: "New Layer with Layer Mask" },
+  { id: "new-document", label: "New Document", needsDocuments: true },
+  { id: "new-document-with-mask", label: "New Document with Layer Mask", needsDocuments: true }
 ];
 function describeSelection(mask) {
   if (!mask || !mask.bounds) return "No selection";
@@ -12027,11 +12110,11 @@ function createImageSelectionTools(controller) {
         shiftEdge: { type: "number", minimum: -100, maximum: 100, description: "Move the edge out (+) or in (-), in percent." },
         output: {
           type: "string",
-          enum: ["selection", "layer-mask", "new-layer", "new-layer-with-mask"],
-          description: "Where the result goes (default selection). layer-mask keeps every pixel and is easiest to revise; new-layer-with-mask too, on a copy."
+          enum: ["selection", "layer-mask", "new-layer", "new-layer-with-mask", "new-document", "new-document-with-mask"],
+          description: "Where the result goes (default selection). layer-mask keeps every pixel and is easiest to revise; new-layer-with-mask too, on a copy. new-document and new-document-with-mask hand a new one-layer document to the host (only when the host can open documents; this one is unchanged) and return its documentId."
         },
         layerId: { type: "string", description: "The layer for layer outputs (default the active layer; see list_layers). New-layer outputs need a pixel layer." },
-        decontaminate: { type: "number", minimum: 0, maximum: 100, description: "Decontaminate Colors amount 0-100 (default 0), only with output new-layer or new-layer-with-mask." },
+        decontaminate: { type: "number", minimum: 0, maximum: 100, description: "Decontaminate Colors amount 0-100 (default 0), only with the new-layer and new-document outputs." },
         edits: {
           type: "array",
           description: "Strokes applied before refining, in order.",
@@ -17877,7 +17960,7 @@ var SelectAndMaskSession = class {
     remembered = s.remember ? { ...s, params: { ...s.params } } : null;
     return this.controller.refineSelectionTo(s.params, s.output, {
       edits: [...this.editsList],
-      decontaminate: s.output === "new-layer" || s.output === "new-layer-with-mask" ? s.decontaminate : 0,
+      decontaminate: s.output === "selection" || s.output === "layer-mask" ? 0 : s.decontaminate,
       refineMode: s.refineMode
     });
   }

package/dist/image-editor/selection/tool-options.d.cts

@@ -81,8 +81,10 @@ export interface RefineEdgeControl {
 export declare const REFINE_EDGE_CONTROLS: readonly RefineEdgeControl[];
 /** Select and Mask's outputs, in menu order. */
 export declare const REFINE_OUTPUTS: readonly {
-    id: 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask';
+    id: 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask' | 'new-document' | 'new-document-with-mask';
     label: string;
+    /** Needs a host that can open documents (`controller.canOpenDocuments`). */
+    needsDocuments?: boolean;
 }[];
 /** A one-line status: "No selection" or "W × H px selected (n % of the image)". */
 export declare function describeSelection(mask: SelectionMask | null | undefined): string;

package/dist/image-editor/selection/tool-options.d.ts

@@ -81,8 +81,10 @@ export interface RefineEdgeControl {
 export declare const REFINE_EDGE_CONTROLS: readonly RefineEdgeControl[];
 /** Select and Mask's outputs, in menu order. */
 export declare const REFINE_OUTPUTS: readonly {
-    id: 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask';
+    id: 'selection' | 'layer-mask' | 'new-layer' | 'new-layer-with-mask' | 'new-document' | 'new-document-with-mask';
     label: string;
+    /** Needs a host that can open documents (`controller.canOpenDocuments`). */
+    needsDocuments?: boolean;
 }[];
 /** A one-line status: "No selection" or "W × H px selected (n % of the image)". */
 export declare function describeSelection(mask: SelectionMask | null | undefined): string;

package/dist/image-editor/types.d.cts

@@ -456,7 +456,21 @@ export interface ImageEditorOptions {
      * Without one they run on the page. Change it later with `setSelectionWorker`.
      */
     selectionWorker?: SelectionWorkerFactory | null;
+    /**
+     * Opens a new image document the editor made (Select and Mask's New Document outputs) the way
+     * the host shows documents: a tab, a window, a file. Without it those outputs are unavailable.
+     * Change it later with `setDocumentOpener`.
+     */
+    openDocument?: DocumentOpener | null;
 }
+/**
+ * Opens a new image document for the host: `document` loads with `loadJSON`; `info.name` is a
+ * suggested name. May return the new document's id (handed back to the caller and to agents).
+ */
+export type DocumentOpener = (document: SerializedImageEditorState, info: {
+    name: string;
+    from: 'select-and-mask';
+}) => string | void | Promise<string | void>;
 export interface InpaintOptions {
     prompt: string;
     imageDataUrl: string;

package/dist/image-editor/types.d.ts

@@ -456,7 +456,21 @@ export interface ImageEditorOptions {
      * Without one they run on the page. Change it later with `setSelectionWorker`.
      */
     selectionWorker?: SelectionWorkerFactory | null;
+    /**
+     * Opens a new image document the editor made (Select and Mask's New Document outputs) the way
+     * the host shows documents: a tab, a window, a file. Without it those outputs are unavailable.
+     * Change it later with `setDocumentOpener`.
+     */
+    openDocument?: DocumentOpener | null;
 }
+/**
+ * Opens a new image document for the host: `document` loads with `loadJSON`; `info.name` is a
+ * suggested name. May return the new document's id (handed back to the caller and to agents).
+ */
+export type DocumentOpener = (document: SerializedImageEditorState, info: {
+    name: string;
+    from: 'select-and-mask';
+}) => string | void | Promise<string | void>;
 export interface InpaintOptions {
     prompt: string;
     imageDataUrl: string;

package/package.json

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

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

@@ -269,7 +269,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `grow_selection` | Select › Grow: add connected pixels within `tolerance` (default 32) of a selected colour; follows colour, not distance. `sample`, `sampleMerged`. Fails when nothing is selected. Returns the summary. |
 | `select_similar` | Select › Similar: add every pixel in the image within `tolerance` of a selected colour, connected or not. Fails when nothing is selected. Returns the summary. |
 | `reselect` | Bring back the last selection `deselect` cleared (one undo step). Fails when there is none. Returns the summary. |
-| `refine_selection` | Select and Mask: snap the selection edge to image edges within `radius` px (0..64, default 8), with `smartRadius`, `smooth` 0..100, `feather` px, `contrast` 0..100 and `shiftEdge` -100..100 %, then `output` to `selection` (default), `layer-mask`, `new-layer` or `new-layer-with-mask` (on `layerId`, default active; new layers hide the source), with `decontaminate` 0..100 for new layers. `edits` (`quick-select`, `brush`, `lasso`, `object` add/subtract; `refine-brush` over hair) apply first; `refineMode: "object"` uses the host model. One step; returns `refineMode`, `layerId` / `newLayerId`. Use on hair, fur, foliage or a coarse AI mask. |
+| `refine_selection` | Select and Mask: snap the selection edge to image edges within `radius` px (0..64, default 8), with `smartRadius`, `smooth` 0..100, `feather` px, `contrast` 0..100 and `shiftEdge` -100..100 %, then `output` to `selection` (default), `layer-mask`, `new-layer`, `new-layer-with-mask` (on `layerId`, default active; new layers hide the source), or `new-document` / `new-document-with-mask` (host must open documents; returns `documentId`), with `decontaminate` 0..100 for new layers and documents. `edits` (`quick-select`, `brush`, `lasso`, `object` add/subtract; `refine-brush` over hair) apply first; `refineMode: "object"` uses the host model. One step; returns `refineMode`, `layerId` / `newLayerId`. Use on hair, fur, foliage or a coarse AI mask. |
 | `update_adjustment_layer` | Change a layer's `enabled` (false hides it without deleting), `blend`, `opacity` (0..1) or `name` in one undo step. Returns the layer. Its parameters change with `set_adjustments`. Toggle `enabled` to compare a layer's effect before and after. |
 | `move_adjustment_layer` | Move a layer to index `to` (0 = bottom, applied first; past the top means top). Order matters: a curves layer above a hue/saturation layer works on its output. Fails when the layer is already there. Returns the ids bottom to top. |
 | `remove_adjustment_layer` | Delete a layer and its mask. Prefer hiding it with `update_adjustment_layer` when the user may want it back. Returns the remaining ids. |