@pixerate/editor 0.205.0 → 0.207.0

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

@@ -14,3 +14,5 @@ export * from './mask-files.cjs';
 export * from './path.cjs';
 export * from './magnetic.cjs';
 export * from './segment/index.cjs';
+export * from './refine-edits.cjs';
+export * from './select-and-mask.cjs';

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

@@ -14,3 +14,5 @@ export * from './mask-files.js';
 export * from './path.js';
 export * from './magnetic.js';
 export * from './segment/index.js';
+export * from './refine-edits.js';
+export * from './select-and-mask.js';

package/dist/image-editor/selection/refine-edits.d.cts

@@ -0,0 +1,50 @@
+/**
+ * The Select and Mask workspace's strokes as plain data, so an agent can send what a person
+ * paints: Quick Selection strokes (grow to the region's edges), Brush strokes (paint the
+ * selection in or out directly), Refine Edge Brush strokes (mark where the edge should be
+ * re-estimated from the image, e.g. over hair), Lasso outlines and Object Selection boxes.
+ */
+import type { CropBox, ImagePoint } from '../types.cjs';
+import { type PixelBuffer, type SelectionMask } from './mask.cjs';
+/** One stroke in the workspace, in natural image pixels. */
+export type RefineEdit = {
+    kind: 'quick-select';
+    points: ImagePoint[];
+    size?: number;
+    mode?: 'add' | 'subtract';
+} | {
+    kind: 'brush';
+    points: ImagePoint[];
+    size?: number;
+    mode?: 'add' | 'subtract';
+    hardness?: number;
+} | {
+    kind: 'refine-brush';
+    points: ImagePoint[];
+    size?: number;
+} | {
+    kind: 'lasso';
+    points: ImagePoint[];
+    mode?: 'add' | 'subtract';
+} | {
+    kind: 'object';
+    rect?: CropBox;
+    point?: ImagePoint;
+    mode?: 'add' | 'subtract';
+};
+export declare const REFINE_EDIT_KINDS: readonly ["quick-select", "brush", "refine-brush", "lasso", "object"];
+/**
+ * Coverage of a round brush of diameter `size` dragged along `points` (one point is a dab), over
+ * a `width × height` image. `hardness` 0..1 (default 1): the solid share of the radius; the rest
+ * fades out. The edge is anti-aliased either way.
+ */
+export declare function brushStrokeMask(width: number, height: number, points: readonly ImagePoint[], size: number, hardness?: number): SelectionMask;
+/**
+ * Applies `edits` in order to `selection` (`null` starts empty) over `pixels` (needed for
+ * Quick Selection strokes). Returns the edited selection and the Refine Edge Brush's painted
+ * area (`null` when there were no such strokes), for `refineSelection`.
+ */
+export declare function applyRefineEdits(pixels: PixelBuffer | null, selection: SelectionMask | null, edits: readonly RefineEdit[], width: number, height: number): {
+    selection: SelectionMask | null;
+    refineBrush: SelectionMask | null;
+};

package/dist/image-editor/selection/refine-edits.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The Select and Mask workspace's strokes as plain data, so an agent can send what a person
+ * paints: Quick Selection strokes (grow to the region's edges), Brush strokes (paint the
+ * selection in or out directly), Refine Edge Brush strokes (mark where the edge should be
+ * re-estimated from the image, e.g. over hair), Lasso outlines and Object Selection boxes.
+ */
+import type { CropBox, ImagePoint } from '../types.js';
+import { type PixelBuffer, type SelectionMask } from './mask.js';
+/** One stroke in the workspace, in natural image pixels. */
+export type RefineEdit = {
+    kind: 'quick-select';
+    points: ImagePoint[];
+    size?: number;
+    mode?: 'add' | 'subtract';
+} | {
+    kind: 'brush';
+    points: ImagePoint[];
+    size?: number;
+    mode?: 'add' | 'subtract';
+    hardness?: number;
+} | {
+    kind: 'refine-brush';
+    points: ImagePoint[];
+    size?: number;
+} | {
+    kind: 'lasso';
+    points: ImagePoint[];
+    mode?: 'add' | 'subtract';
+} | {
+    kind: 'object';
+    rect?: CropBox;
+    point?: ImagePoint;
+    mode?: 'add' | 'subtract';
+};
+export declare const REFINE_EDIT_KINDS: readonly ["quick-select", "brush", "refine-brush", "lasso", "object"];
+/**
+ * Coverage of a round brush of diameter `size` dragged along `points` (one point is a dab), over
+ * a `width × height` image. `hardness` 0..1 (default 1): the solid share of the radius; the rest
+ * fades out. The edge is anti-aliased either way.
+ */
+export declare function brushStrokeMask(width: number, height: number, points: readonly ImagePoint[], size: number, hardness?: number): SelectionMask;
+/**
+ * Applies `edits` in order to `selection` (`null` starts empty) over `pixels` (needed for
+ * Quick Selection strokes). Returns the edited selection and the Refine Edge Brush's painted
+ * area (`null` when there were no such strokes), for `refineSelection`.
+ */
+export declare function applyRefineEdits(pixels: PixelBuffer | null, selection: SelectionMask | null, edits: readonly RefineEdit[], width: number, height: number): {
+    selection: SelectionMask | null;
+    refineBrush: SelectionMask | null;
+};

package/dist/image-editor/selection/refine.d.cts

@@ -42,10 +42,12 @@ export declare function guidedFilterColor(guide: readonly [Float32Array, Float32
 export declare function edgeWidth(guide: readonly [Float32Array, Float32Array, Float32Array], w: number, h: number, r: number): Float32Array;
 /**
  * Refines soft coverage `m` (`w × h`, 0..1) with `guide` (three 0..1 planes, required when
- * `radius > 0`): edge-aware re-estimation in a band around the edge, then smooth, feather,
- * contrast and shift edge, in that order.
+ * `radius > 0` or a `band` is given): edge-aware re-estimation in a band around the edge, then
+ * smooth, feather, contrast and shift edge, in that order. `band` (0..1 per pixel, the Refine
+ * Edge Brush) adds to the band where it is painted, so hair or fur far from the edge is
+ * re-estimated too.
  */
-export declare function refineCoverage(guide: readonly [Float32Array, Float32Array, Float32Array] | null, m: Float32Array, w: number, h: number, params?: RefineEdgeParams): Float32Array;
+export declare function refineCoverage(guide: readonly [Float32Array, Float32Array, Float32Array] | null, m: Float32Array, w: number, h: number, params?: RefineEdgeParams, band?: ArrayLike<number> | null): Float32Array;
 /** Three 0..1 planes of a window of an RGBA buffer. */
 export declare function guidePlanes(pixels: PixelBuffer, win?: CropBox): [Float32Array, Float32Array, Float32Array];
 /**
@@ -53,7 +55,7 @@ export declare function guidePlanes(pixels: PixelBuffer, win?: CropBox): [Float3
  * same size). Work is confined to the mask's bounds grown by {@link refineEdgeHalo}, so a small
  * selection on a large image stays cheap.
  */
-export declare function refineSelection(pixels: PixelBuffer | null, mask: SelectionMask, params?: RefineEdgeParams): SelectionMask;
+export declare function refineSelection(pixels: PixelBuffer | null, mask: SelectionMask, params?: RefineEdgeParams, refineBrush?: SelectionMask | null): SelectionMask;
 /**
  * Decontaminate Colors: along a soft edge, a pixel's colour is part subject and part the old
  * background (C = αF + (1 − α)B), which shows as a fringe once the subject is on a new background.

package/dist/image-editor/selection/refine.d.ts

@@ -42,10 +42,12 @@ export declare function guidedFilterColor(guide: readonly [Float32Array, Float32
 export declare function edgeWidth(guide: readonly [Float32Array, Float32Array, Float32Array], w: number, h: number, r: number): Float32Array;
 /**
  * Refines soft coverage `m` (`w × h`, 0..1) with `guide` (three 0..1 planes, required when
- * `radius > 0`): edge-aware re-estimation in a band around the edge, then smooth, feather,
- * contrast and shift edge, in that order.
+ * `radius > 0` or a `band` is given): edge-aware re-estimation in a band around the edge, then
+ * smooth, feather, contrast and shift edge, in that order. `band` (0..1 per pixel, the Refine
+ * Edge Brush) adds to the band where it is painted, so hair or fur far from the edge is
+ * re-estimated too.
  */
-export declare function refineCoverage(guide: readonly [Float32Array, Float32Array, Float32Array] | null, m: Float32Array, w: number, h: number, params?: RefineEdgeParams): Float32Array;
+export declare function refineCoverage(guide: readonly [Float32Array, Float32Array, Float32Array] | null, m: Float32Array, w: number, h: number, params?: RefineEdgeParams, band?: ArrayLike<number> | null): Float32Array;
 /** Three 0..1 planes of a window of an RGBA buffer. */
 export declare function guidePlanes(pixels: PixelBuffer, win?: CropBox): [Float32Array, Float32Array, Float32Array];
 /**
@@ -53,7 +55,7 @@ export declare function guidePlanes(pixels: PixelBuffer, win?: CropBox): [Float3
  * same size). Work is confined to the mask's bounds grown by {@link refineEdgeHalo}, so a small
  * selection on a large image stays cheap.
  */
-export declare function refineSelection(pixels: PixelBuffer | null, mask: SelectionMask, params?: RefineEdgeParams): SelectionMask;
+export declare function refineSelection(pixels: PixelBuffer | null, mask: SelectionMask, params?: RefineEdgeParams, refineBrush?: SelectionMask | null): SelectionMask;
 /**
  * Decontaminate Colors: along a soft edge, a pixel's colour is part subject and part the old
  * background (C = αF + (1 − α)B), which shows as a fringe once the subject is on a new background.

package/dist/image-editor/selection/select-and-mask.d.cts

@@ -0,0 +1,126 @@
+/**
+ * The Select and Mask workspace without a UI: its settings, strokes, preview and view modes, shared
+ * by the React and Svelte workspaces. Everything it holds is plain data (the strokes are
+ * `RefineEdit`s), and OK runs the same `refineSelectionTo` call an agent makes with `edits`, so
+ * the workspace and an agent produce the same result in one undo step.
+ *
+ * The preview is computed on a copy reduced to {@link PREVIEW_SIZE} px (or at full size with High
+ * Quality Preview) and drawn as RGBA in the chosen view mode.
+ */
+import type { ImageEditorController, RefineOutput, RefineOutputResult } from '../controller.cjs';
+import type { ImagePoint } from '../types.cjs';
+import { type RefineEdgeParams } from './refine.cjs';
+import { type RefineEdit } from './refine-edits.cjs';
+export type SelectAndMaskView = 'onion-skin' | 'marching-ants' | 'overlay' | 'on-black' | 'on-white' | 'black-white' | 'on-layers';
+export type SelectAndMaskTool = 'quick-select' | 'refine-brush' | 'brush' | 'object' | 'lasso' | 'hand' | 'zoom';
+/** The view modes with Photoshop's keys, in menu order. */
+export declare const SELECT_AND_MASK_VIEWS: readonly {
+    id: SelectAndMaskView;
+    label: string;
+    key: string;
+    opacity: number;
+}[];
+/** The workspace tools with Photoshop's keys. */
+export declare const SELECT_AND_MASK_TOOLS: readonly {
+    id: SelectAndMaskTool;
+    label: string;
+    key: string;
+}[];
+export interface SelectAndMaskSettings {
+    params: Required<RefineEdgeParams>;
+    output: RefineOutput;
+    /** Decontaminate Colors amount 0..100 (new-layer outputs). */
+    decontaminate: number;
+    refineMode: 'color' | 'object';
+    view: SelectAndMaskView;
+    /** How strongly the view shows what is not selected, 0..1. */
+    opacity: number;
+    /** Show only the area the refinement changes. */
+    showEdge: boolean;
+    /** Show the selection as it was, before the workspace. */
+    showOriginal: boolean;
+    /** Update the preview while painting (otherwise on release). */
+    realTime: boolean;
+    /** Preview at full size instead of a reduced copy. */
+    highQuality: boolean;
+    /** Keep these settings for the next time the workspace opens. */
+    remember: boolean;
+    tool: SelectAndMaskTool;
+    /** Brush diameter in natural pixels. */
+    brushSize: number;
+    brushMode: 'add' | 'subtract';
+}
+export declare const DEFAULT_SELECT_AND_MASK_SETTINGS: SelectAndMaskSettings;
+/** Long side of the reduced preview. */
+export declare const PREVIEW_SIZE = 1024;
+export declare class SelectAndMaskSession {
+    readonly controller: ImageEditorController;
+    private settingsValue;
+    private readonly editsList;
+    /** The edit being painted, shown in the preview but not yet in `edits`. */
+    private live;
+    private dragStart;
+    private pixels;
+    private previewPixels;
+    private base;
+    private previewMask;
+    private baseMask;
+    private readonly listeners;
+    /** Why the preview could not be made (no pixels), for the UI. */
+    error: string | null;
+    /** A note for the UI, such as object aware refinement applying only on OK. */
+    note: string | null;
+    /** Bumped each time the preview changes, so a UI can redraw. */
+    revision: number;
+    constructor(controller: ImageEditorController);
+    get settings(): SelectAndMaskSettings;
+    get edits(): readonly RefineEdit[];
+    /** Reads the image and makes the first preview. Resolves to false when the pixels are unavailable. */
+    open(): Promise<boolean>;
+    subscribe(listener: () => void): () => void;
+    private emit;
+    /** Preview size and the scale from natural pixels to it. */
+    get previewSize(): {
+        width: number;
+        height: number;
+        scale: number;
+    };
+    /** Changes settings; the preview follows. Choosing a view also sets its usual opacity. */
+    update(changes: Partial<SelectAndMaskSettings>): void;
+    private rescale;
+    /** Recomputes the preview mask from the base selection, the strokes and the settings. */
+    recompute(): void;
+    /** Coverage 0..1 of the preview at (x, y) in preview pixels (for tests and hover readouts). */
+    coverageAt(x: number, y: number): number;
+    /** The preview drawn in the current view mode: RGBA at {@link previewSize}. */
+    render(): Uint8ClampedArray;
+    /**
+     * Pointer down at `point` (natural pixels) with the current tool: starts a stroke (Quick
+     * Selection, brushes, lasso) or a box (Object Selection). Alt (or the subtract mode) removes.
+     * Hand and Zoom are the UI's own; they return false here.
+     */
+    begin(point: ImagePoint, modifiers?: {
+        altKey?: boolean;
+    }): boolean;
+    /** Pointer move while a stroke is down. */
+    move(point: ImagePoint): void;
+    /** Pointer up: the stroke becomes an edit (one step of the workspace's own undo). */
+    end(): void;
+    /** Removes the last stroke (Ctrl/⌘+Z in the workspace). Returns false when there is none. */
+    undoEdit(): boolean;
+    /** Clears the strokes and goes back to the default settings (Reset). */
+    reset(): void;
+    /**
+     * Photoshop's keys in the workspace: a view letter, F (next view), X (all views off and on:
+     * Show Original), J (Show Edge), P (Show Original), a tool letter, [ and ] (brush size).
+     * Returns true when the key was used.
+     */
+    handleKey(key: string): boolean;
+    /**
+     * OK: applies the strokes and settings to the image as one undo step (the same call an agent
+     * makes) and remembers the settings when asked to.
+     */
+    commit(): Promise<RefineOutputResult>;
+}
+/** Forgets the remembered workspace settings. */
+export declare function forgetSelectAndMaskSettings(): void;

package/dist/image-editor/selection/select-and-mask.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The Select and Mask workspace without a UI: its settings, strokes, preview and view modes, shared
+ * by the React and Svelte workspaces. Everything it holds is plain data (the strokes are
+ * `RefineEdit`s), and OK runs the same `refineSelectionTo` call an agent makes with `edits`, so
+ * the workspace and an agent produce the same result in one undo step.
+ *
+ * The preview is computed on a copy reduced to {@link PREVIEW_SIZE} px (or at full size with High
+ * Quality Preview) and drawn as RGBA in the chosen view mode.
+ */
+import type { ImageEditorController, RefineOutput, RefineOutputResult } from '../controller.js';
+import type { ImagePoint } from '../types.js';
+import { type RefineEdgeParams } from './refine.js';
+import { type RefineEdit } from './refine-edits.js';
+export type SelectAndMaskView = 'onion-skin' | 'marching-ants' | 'overlay' | 'on-black' | 'on-white' | 'black-white' | 'on-layers';
+export type SelectAndMaskTool = 'quick-select' | 'refine-brush' | 'brush' | 'object' | 'lasso' | 'hand' | 'zoom';
+/** The view modes with Photoshop's keys, in menu order. */
+export declare const SELECT_AND_MASK_VIEWS: readonly {
+    id: SelectAndMaskView;
+    label: string;
+    key: string;
+    opacity: number;
+}[];
+/** The workspace tools with Photoshop's keys. */
+export declare const SELECT_AND_MASK_TOOLS: readonly {
+    id: SelectAndMaskTool;
+    label: string;
+    key: string;
+}[];
+export interface SelectAndMaskSettings {
+    params: Required<RefineEdgeParams>;
+    output: RefineOutput;
+    /** Decontaminate Colors amount 0..100 (new-layer outputs). */
+    decontaminate: number;
+    refineMode: 'color' | 'object';
+    view: SelectAndMaskView;
+    /** How strongly the view shows what is not selected, 0..1. */
+    opacity: number;
+    /** Show only the area the refinement changes. */
+    showEdge: boolean;
+    /** Show the selection as it was, before the workspace. */
+    showOriginal: boolean;
+    /** Update the preview while painting (otherwise on release). */
+    realTime: boolean;
+    /** Preview at full size instead of a reduced copy. */
+    highQuality: boolean;
+    /** Keep these settings for the next time the workspace opens. */
+    remember: boolean;
+    tool: SelectAndMaskTool;
+    /** Brush diameter in natural pixels. */
+    brushSize: number;
+    brushMode: 'add' | 'subtract';
+}
+export declare const DEFAULT_SELECT_AND_MASK_SETTINGS: SelectAndMaskSettings;
+/** Long side of the reduced preview. */
+export declare const PREVIEW_SIZE = 1024;
+export declare class SelectAndMaskSession {
+    readonly controller: ImageEditorController;
+    private settingsValue;
+    private readonly editsList;
+    /** The edit being painted, shown in the preview but not yet in `edits`. */
+    private live;
+    private dragStart;
+    private pixels;
+    private previewPixels;
+    private base;
+    private previewMask;
+    private baseMask;
+    private readonly listeners;
+    /** Why the preview could not be made (no pixels), for the UI. */
+    error: string | null;
+    /** A note for the UI, such as object aware refinement applying only on OK. */
+    note: string | null;
+    /** Bumped each time the preview changes, so a UI can redraw. */
+    revision: number;
+    constructor(controller: ImageEditorController);
+    get settings(): SelectAndMaskSettings;
+    get edits(): readonly RefineEdit[];
+    /** Reads the image and makes the first preview. Resolves to false when the pixels are unavailable. */
+    open(): Promise<boolean>;
+    subscribe(listener: () => void): () => void;
+    private emit;
+    /** Preview size and the scale from natural pixels to it. */
+    get previewSize(): {
+        width: number;
+        height: number;
+        scale: number;
+    };
+    /** Changes settings; the preview follows. Choosing a view also sets its usual opacity. */
+    update(changes: Partial<SelectAndMaskSettings>): void;
+    private rescale;
+    /** Recomputes the preview mask from the base selection, the strokes and the settings. */
+    recompute(): void;
+    /** Coverage 0..1 of the preview at (x, y) in preview pixels (for tests and hover readouts). */
+    coverageAt(x: number, y: number): number;
+    /** The preview drawn in the current view mode: RGBA at {@link previewSize}. */
+    render(): Uint8ClampedArray;
+    /**
+     * Pointer down at `point` (natural pixels) with the current tool: starts a stroke (Quick
+     * Selection, brushes, lasso) or a box (Object Selection). Alt (or the subtract mode) removes.
+     * Hand and Zoom are the UI's own; they return false here.
+     */
+    begin(point: ImagePoint, modifiers?: {
+        altKey?: boolean;
+    }): boolean;
+    /** Pointer move while a stroke is down. */
+    move(point: ImagePoint): void;
+    /** Pointer up: the stroke becomes an edit (one step of the workspace's own undo). */
+    end(): void;
+    /** Removes the last stroke (Ctrl/⌘+Z in the workspace). Returns false when there is none. */
+    undoEdit(): boolean;
+    /** Clears the strokes and goes back to the default settings (Reset). */
+    reset(): void;
+    /**
+     * Photoshop's keys in the workspace: a view letter, F (next view), X (all views off and on:
+     * Show Original), J (Show Edge), P (Show Original), a tool letter, [ and ] (brush size).
+     * Returns true when the key was used.
+     */
+    handleKey(key: string): boolean;
+    /**
+     * OK: applies the strokes and settings to the image as one undo step (the same call an agent
+     * makes) and remembers the settings when asked to.
+     */
+    commit(): Promise<RefineOutputResult>;
+}
+/** Forgets the remembered workspace settings. */
+export declare function forgetSelectAndMaskSettings(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.205.0",
+  "version": "0.207.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. One step; returns `layerId` / `newLayerId`. Use on hair, fur, foliage or after 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` 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. |
 | `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. |

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

@@ -57,7 +57,12 @@ This skill is the method. `pixerate-image-editor` has the full tool reference.
      `layerId` (white adds, black removes, a soft brush feathers; `blur_stroke` softens a part
      of the edge), then `set_quick_mask` `enabled: false`.
    - `refine_selection` snaps to real edges: radius 2–4 for hard edges, 8–20 for hair and fur;
-     `smartRadius: true` for mixed edges.
+     `smartRadius: true` for mixed edges. For flyaway hair beyond the radius, add `edits` with a
+     `refine-brush` stroke along it (size covering the strands); fix misses and leaks in the same
+     call with `quick-select`, `brush` or `lasso` strokes, or an `object` box (`mode:
+     "subtract"` to remove). These are the Select and Mask workspace's own tools, so a person
+     can open the same edits in the workspace. With a host model, `refineMode: "object"`
+     refines from the model's outline.
    - `shiftEdge` −10..−30 % tightens a refined edge that picked up background.
    **Check:** `percent` changed by roughly what you intended (a few percent at most for a
    cleanup).