editmamei 0.20.0 → 0.22.0

package/dist/perception/grounding-warp.js

@@ -0,0 +1,182 @@
+export function curveLength(curve) {
+    let total = 0;
+    for (let k = 0; k < curve.length - 1; k++)
+        total += Math.hypot(curve[k + 1].x - curve[k].x, curve[k + 1].y - curve[k].y);
+    return total;
+}
+export function sampleCurveAtLengths(curve, lengths) {
+    if (curve.length < 2)
+        throw new Error('curve needs at least 2 points');
+    if (curve.some((p) => !Number.isFinite(p.x) || !Number.isFinite(p.y)))
+        throw new Error('curve has non-finite points');
+    const cum = [];
+    const seg = [];
+    let total = 0;
+    for (let k = 0; k < curve.length - 1; k++) {
+        cum.push(total);
+        const l = Math.hypot(curve[k + 1].x - curve[k].x, curve[k + 1].y - curve[k].y);
+        seg.push(l);
+        total += l;
+    }
+    if (total === 0)
+        throw new Error('curve has zero length (all points coincident)');
+    return lengths.map((target) => {
+        const tt = target < 0 ? 0 : target > total ? total : target;
+        let k = 0;
+        while (k < seg.length - 1 && cum[k] + seg[k] < tt)
+            k++;
+        const t = seg[k] > 0 ? (tt - cum[k]) / seg[k] : 0;
+        const a = curve[k];
+        const b = curve[k + 1];
+        const point = { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t };
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const m = Math.hypot(dx, dy) || 1;
+        return { point, normal: { x: -dy / m, y: dx / m } };
+    });
+}
+export function resampleByArcLength(curve, count) {
+    if (count < 2)
+        throw new Error('count must be at least 2');
+    const total = curveLength(curve);
+    const lengths = Array.from({ length: count }, (_, i) => (i / (count - 1)) * total);
+    return sampleCurveAtLengths(curve, lengths);
+}
+export function smoothCurve(curve, iterations) {
+    if (iterations <= 0 || curve.length < 3)
+        return curve.map((p) => ({ x: p.x, y: p.y }));
+    let pts = curve.map((p) => ({ x: p.x, y: p.y }));
+    for (let it = 0; it < iterations; it++) {
+        const next = pts.map((p) => ({ x: p.x, y: p.y }));
+        for (let i = 1; i < pts.length - 1; i++) {
+            next[i] = {
+                x: 0.5 * pts[i].x + 0.25 * pts[i - 1].x + 0.25 * pts[i + 1].x,
+                y: 0.5 * pts[i].y + 0.25 * pts[i - 1].y + 0.25 * pts[i + 1].y,
+            };
+        }
+        pts = next;
+    }
+    return pts;
+}
+export function warpAlongCurve(bounds, curve, opts) {
+    const { runAxis, alongCells, acrossCells } = opts;
+    const horizontal = runAxis === 'horizontal';
+    const alongCount = 3 * alongCells + 1;
+    const acrossCount = 3 * acrossCells + 1;
+    const along = horizontal ? bounds.right - bounds.left : bounds.bottom - bounds.top;
+    const thickness = horizontal ? bounds.bottom - bounds.top : bounds.right - bounds.left;
+    const src = (opts.smooth ?? 0) > 0 ? smoothCurve(curve, opts.smooth) : curve;
+    const total = curveLength(src);
+    const spanLen = (opts.fit ?? 'stretch') === 'preserve' ? Math.min(along, total) : total;
+    const curveCovered = total > 0 ? spanLen / total : 1;
+    const lengths = Array.from({ length: alongCount }, (_, i) => (i / (alongCount - 1)) * spanLen);
+    const samples = sampleCurveAtLengths(src, lengths);
+    const ncx = horizontal ? alongCells : acrossCells;
+    const ncy = horizontal ? acrossCells : alongCells;
+    const ncols = 3 * ncx + 1;
+    const nrows = 3 * ncy + 1;
+    const meshPoints = [];
+    let l = Infinity;
+    let t = Infinity;
+    let r = -Infinity;
+    let b = -Infinity;
+    for (let rj = 0; rj < nrows; rj++) {
+        for (let ci = 0; ci < ncols; ci++) {
+            const alongIdx = horizontal ? ci : rj;
+            const acrossIdx = horizontal ? rj : ci;
+            const s = samples[alongIdx];
+            const v = acrossCount > 1 ? acrossIdx / (acrossCount - 1) : 0.5;
+            const off = (v - 0.5) * thickness;
+            const x = s.point.x + s.normal.x * off;
+            const y = s.point.y + s.normal.y * off;
+            meshPoints.push({ x, y });
+            if (x < l)
+                l = x;
+            if (y < t)
+                t = y;
+            if (x > r)
+                r = x;
+            if (y > b)
+                b = y;
+        }
+    }
+    return {
+        meshPoints,
+        ncx,
+        ncy,
+        ncols,
+        nrows,
+        destBBox: { left: l, top: t, right: r, bottom: b },
+        curveCovered,
+    };
+}
+export function warpRadial(bounds, center, radius, amount, opts) {
+    const cells = opts.cells;
+    const ncx = cells;
+    const ncy = cells;
+    const ncols = 3 * ncx + 1;
+    const nrows = 3 * ncy + 1;
+    const W = bounds.right - bounds.left;
+    const H = bounds.bottom - bounds.top;
+    const meshPoints = [];
+    let maxDisplacement = 0;
+    let l = Infinity;
+    let t = Infinity;
+    let r = -Infinity;
+    let b = -Infinity;
+    for (let rj = 0; rj < nrows; rj++) {
+        for (let ci = 0; ci < ncols; ci++) {
+            const hx = bounds.left + (ci / (ncols - 1)) * W;
+            const hy = bounds.top + (rj / (nrows - 1)) * H;
+            const vx = hx - center.x;
+            const vy = hy - center.y;
+            const rr = Math.hypot(vx, vy);
+            const u = radius > 0 ? rr / radius : 1;
+            let dx = 0;
+            let dy = 0;
+            if (u < 1) {
+                const w = (1 - u * u) ** 2;
+                dx = vx * amount * w;
+                dy = vy * amount * w;
+            }
+            const x = hx + dx;
+            const y = hy + dy;
+            const d = Math.hypot(dx, dy);
+            if (d > maxDisplacement)
+                maxDisplacement = d;
+            meshPoints.push({ x, y });
+            if (x < l)
+                l = x;
+            if (y < t)
+                t = y;
+            if (x > r)
+                r = x;
+            if (y > b)
+                b = y;
+        }
+    }
+    return {
+        meshPoints,
+        ncx,
+        ncy,
+        ncols,
+        nrows,
+        destBBox: { left: l, top: t, right: r, bottom: b },
+        maxDisplacement,
+    };
+}
+export function farEndLift(bounds, pinEdge, target) {
+    if (pinEdge === 'left' || pinEdge === 'right') {
+        return target.y - (bounds.top + bounds.bottom) / 2;
+    }
+    return target.x - (bounds.left + bounds.right) / 2;
+}
+export function activeLayerBounds(context) {
+    const al = context?.activeLayer;
+    const b = al?.bounds;
+    if (!b || ![b.left, b.top, b.right, b.bottom].every((n) => Number.isFinite(n)))
+        throw new Error('could not read the active layer bounds (no active layer?)');
+    if (b.right - b.left <= 0 || b.bottom - b.top <= 0)
+        throw new Error('the active layer has empty bounds — nothing to warp');
+    return { left: b.left, top: b.top, right: b.right, bottom: b.bottom };
+}

package/dist/perception/sky-mask-transfer.js

@@ -15,10 +15,10 @@ function encodeMaskJpeg(mask, w, h) {
     }
     return encode({ data: rgba, width: w, height: h }, 92).data;
 }
-function buildLoadScript(maskPath, docW, docH) {
+function buildLoadScript(maskPath, docW, docH, selType) {
     return `
     ${getContextInfo}
-    function __skyRestoreComposite(d) {
+    function __restoreComposite(d) {
       try {
         app.activeDocument = d;
         var ref = new ActionReference();
@@ -28,11 +28,27 @@ function buildLoadScript(maskPath, docW, docH) {
         app.executeAction(app.charIDToTypeID('slct'), desc, DialogModes.NO);
       } catch (eRC) {}
     }
+    function __selExists(d) {
+      try {
+        var r = new ActionReference();
+        r.putProperty(app.charIDToTypeID('Prpr'), app.stringIDToTypeID('selection'));
+        r.putEnumerated(app.charIDToTypeID('Dcmn'), app.charIDToTypeID('Ordn'), app.charIDToTypeID('Trgt'));
+        return app.executeActionGet(r).hasKey(app.stringIDToTypeID('selection'));
+      } catch (eSe) { return false; }
+    }
     if (app.documents.length === 0) { throw new Error('No active document'); }
     var orig = app.activeDocument;
+    var combine = '${selType}';
 
-    // Bring the upscaled mask onto the clipboard FIRST, so no document switch sits
-    // between the channel setup and the paste below.
+    // Save the prior selection (combine ops only) BEFORE the mask setup deselects it.
+    var priorCh = null;
+    if (combine !== 'REPLACE' && __selExists(orig)) {
+      priorCh = orig.channels.add();
+      orig.selection.store(priorCh);
+    }
+
+    // Bring the upscaled mask onto the clipboard, then paste it INTO a fresh full-canvas
+    // alpha channel on the original (selectAll + paste-into keeps it aligned to canvas).
     var maskDoc = app.open(new File(${jsLit(maskPath)}));
     maskDoc.resizeImage(
       UnitValue(${jsNum(docW, 1)}, 'px'),
@@ -44,34 +60,50 @@ function buildLoadScript(maskPath, docW, docH) {
     maskDoc.selection.copy();
     maskDoc.close(SaveOptions.DONOTSAVECHANGES);
 
-    // Paste the doc-sized mask INTO a full-canvas alpha channel on the original. With
-    // the alpha channel the explicit active channel, paste writes grayscale into it (no
-    // new layer). selectAll + paste-into keeps the doc-sized clipboard aligned to canvas.
     app.activeDocument = orig;
-    var ch = orig.channels.add();
-    orig.activeChannels = [ch];
+    var maskCh = orig.channels.add();
+    orig.activeChannels = [maskCh];
     orig.selection.selectAll();
     orig.paste(true);
     orig.selection.deselect();
 
-    // Load the channel as the working selection (white = sky), then drop the temp channel.
-    orig.selection.load(ch, SelectionType.REPLACE);
-    try { ch.remove(); } catch (eRm) {}
-    __skyRestoreComposite(orig);
+    // Load the mask (REPLACE), then re-combine with the saved prior selection.
+    orig.selection.load(maskCh, SelectionType.REPLACE);
+    if (priorCh) {
+      if (combine === 'EXTEND') {
+        orig.selection.load(priorCh, SelectionType.EXTEND);      // mask ∪ prior
+      } else if (combine === 'DIMINISH') {
+        orig.selection.load(priorCh, SelectionType.REPLACE);     // = prior
+        orig.selection.load(maskCh, SelectionType.DIMINISH);     // prior − mask
+      } else if (combine === 'INTERSECT') {
+        orig.selection.load(priorCh, SelectionType.REPLACE);     // = prior
+        orig.selection.load(maskCh, SelectionType.INTERSECT);    // prior ∩ mask
+      }
+      try { priorCh.remove(); } catch (eP) {}
+    }
+    try { maskCh.remove(); } catch (eRm) {}
+    __restoreComposite(orig);
     return { ok: true };
   `;
 }
-export async function loadSkyMaskAsSelection(connection, mask, maskW, maskH, docW, docH) {
+const SELECTION_TYPE_ENUM = {
+    replace: 'REPLACE',
+    add: 'EXTEND',
+    subtract: 'DIMINISH',
+    intersect: 'INTERSECT',
+};
+export async function loadMaskAsSelection(connection, mask, maskW, maskH, docW, docH, selectionType = 'replace') {
     const jpg = encodeMaskJpeg(mask, maskW, maskH);
     const dir = process.platform === 'darwin'
-        ? await TempDir.createWithRoot(userOwnedTempRoot(), 'editmamei-sky-')
-        : await TempDir.create('editmamei-sky-');
+        ? await TempDir.createWithRoot(userOwnedTempRoot(), 'editmamei-mask-')
+        : await TempDir.create('editmamei-mask-');
     try {
-        const maskPath = dir.path('skymask.jpg');
+        const maskPath = dir.path('mask.jpg');
         await fs.writeFile(maskPath, jpg);
-        await runScript(connection, buildLoadScript(maskPath, docW, docH));
+        await runScript(connection, buildLoadScript(maskPath, docW, docH, SELECTION_TYPE_ENUM[selectionType]));
     }
     finally {
         await dir.cleanup();
     }
 }
+export const loadSkyMaskAsSelection = loadMaskAsSelection;

package/dist/tools/adjustment-tools.js

@@ -626,8 +626,8 @@ export function createAdjustmentTools(connection, snippetClient) {
     return [
         {
             tool: {
-                name: 'photoshop_apply_adjustment',
-                description: "Apply a DESTRUCTIVE tonal adjustment that Photoshop does NOT offer as an adjustment layer — chosen via `type`. Runs on a DUPLICATE of the active layer by default (auto-duplicate-first per Bundle O — the original is preserved; revert by deleting the copy); pass `apply_to_active_layer: true` to bake in place. Auto-rasterizes text/smart-object layers. `shadows_highlights` recovers blown highlights + crushed shadows in one pass (defaults match Adobe's dialog: 35 shadow amount, +20 color correction); `equalize` stretches/flattens the histogram (parameter-free); `color_lookup` bakes a 3DLUT grade (cl_lut_name required — leaf name of a file in Presets/3DLUTs/ or an absolute .cube/.3dl/.look path). For EDITABLE tonal/color work, prefer photoshop_add_adjustment_layer.",
+                name: 'ps_apply_adjustment',
+                description: "Apply a DESTRUCTIVE tonal adjustment that Photoshop does NOT offer as an adjustment layer — chosen via `type`. Runs on a DUPLICATE of the active layer by default (auto-duplicate-first per Bundle O — the original is preserved; revert by deleting the copy); pass `apply_to_active_layer: true` to bake in place. Auto-rasterizes text/smart-object layers. `shadows_highlights` recovers blown highlights + crushed shadows in one pass (defaults match Adobe's dialog: 35 shadow amount, +20 color correction); `equalize` stretches/flattens the histogram (parameter-free); `color_lookup` bakes a 3DLUT grade (cl_lut_name required — leaf name of a file in Presets/3DLUTs/ or an absolute .cube/.3dl/.look path). For EDITABLE tonal/color work, prefer ps_add_adjustment_layer.",
                 inputSchema: APPLY_ADJUSTMENT_INPUT_SCHEMA,
                 outputSchema: {
                     type: 'object',
@@ -659,7 +659,7 @@ export function createAdjustmentTools(connection, snippetClient) {
         },
         {
             tool: {
-                name: 'photoshop_add_adjustment_layer',
+                name: 'ps_add_adjustment_layer',
                 description: "Create a non-destructive adjustment layer above the active layer. Supports the full real-Photoshop tonal/color surface: Curves (with S-curve presets), Levels, Hue/Saturation, Brightness/Contrast, Black & White (with optional tint), Color Balance, Photo Filter (preset or custom color), Vibrance, Channel Mixer, Selective Color, Gradient Map (preset), Exposure (stops + offset + gamma), Color Lookup (3DLUT presets or custom file path), and Invert. Values are editable, maskable, and removable. This is the canonical entry point for ALL tonal/color adjustments; the old destructive bake tools (auto_levels / auto_contrast / desaturate / invert) were removed on 2026-05-31 — if you genuinely need a pixel bake, follow this call with `photoshop_merge_visible_layers`. Optionally clips the adjustment to only affect the layer directly below it. If a selection is active at call time, the new layer is automatically masked by it (toggle with mask_from_selection / mask_inverted). For destructive ops that don't have an adjustment-layer equivalent in Photoshop (Shadows/Highlights — single-pass shadow/highlight recovery), use `photoshop_apply_shadows_highlights` which auto-duplicates the active layer to keep the original intact. Returns context — the new adjustment layer becomes active.",
                 inputSchema: addAdjustmentLayerSchema,
                 outputSchema: {

package/dist/tools/brush-tools.js

@@ -1,6 +1,8 @@
 import { SUPPORTED_BRUSH_TOOLS } from '../api/brush-tool-names.js';
 import { runScript } from '../utils/run-script.js';
 import { validateArgs } from '../utils/validate.js';
+import { OnnxLandmarkDetectionClient } from '../detection/landmark-detection-client.js';
+import { resolveExpectedPlacement, PLACEMENT_SCHEMA } from '../perception/grounding-locate.js';
 const TOOLS_REQUIRING_SOURCE = ['clone_stamp', 'healing_brush'];
 const applyBrushStrokeSchema = {
     type: 'object',
@@ -10,6 +12,14 @@ const applyBrushStrokeSchema = {
             enum: SUPPORTED_BRUSH_TOOLS,
             description: 'Which brush-family tool to dispatch. Headline retouch options: `healing_brush` and `clone_stamp` (both REQUIRE `source_point` — set the sample location, then stroke the path); `burn` darkens; `dodge` lightens; `blur` smooths; `sharpen` enhances local contrast; `smudge` pushes pixels in the stroke direction. Paint family: `brush` (the standard paintbrush — honors `foreground_color`), `pencil` (hard-edge), `eraser`. Specialty: `pattern_stamp`, `art_history_brush`, `history_brush`, `color_replacement`, `background_eraser`, `sponge`.',
         },
+        placement: {
+            ...PLACEMENT_SCHEMA,
+            description: 'ANCHOR-RELATIONAL stroke path (preferred over supplying pixels): a PATH relation — `along` a traced edge ' +
+                'or a Pro face-mesh landmark curve, `offset-curve`, or `segment` between two anchors — so the stroke traces ' +
+                'the resolved, gate-verified curve (the FULL polyline, not just endpoints: paint along the jaw / horizon / ' +
+                'under-eye). Strokes ONLY if the gate PASSES. When set, `path` is ignored; tool/brush_size/source_point/' +
+                'colors/dynamics/jitter still apply. See ps_resolve_placement for the anchors + relation vocabulary.',
+        },
         path: {
             type: 'array',
             description: "Ordered list of anchor points the stroke traces. **Minimum 2 anchors.** Each anchor is `{x, y}` for a sharp corner OR `{x, y, in: [hx, hy], out: [hx, hy]}` for a smooth bezier point. The `in` and `out` handles MUST be positioned **tangent** to the curve at the anchor — `in` placed in the direction of the PREVIOUS anchor in the array, `out` placed in the direction of the NEXT anchor. Handles placed RADIALLY (toward/away from the shape's center) produce loops + concave curves instead of smooth convex ones. Mix corner + smooth points freely. Coordinates are document pixels; (0, 0) is top-left. Partial handles (only `in` OR only `out`) degrade to a sharp corner. **Recipes for common natural-stroke shapes** (compute these client-side and emit the resulting `[{x, y}, ...]` array): (1) **Hand-drawn straight line A→B with sketchy feel**: sample 8-30 evenly-spaced corner anchors along the line, then perturb each interior anchor by ±2-5px on the perpendicular axis — OR pass clean anchors and use `jitter_px` to apply the perturbation server-side (preferred — cheaper, deterministic). (2) **Sine wave A→B, amplitude a, periods n**: for i in 0..N, x_i = A.x + (i/N)*(B.x - A.x), y_i = A.y + a * sin((i/N) * 2π * n). Use 20-40 anchors for a smooth wave. (3) **Parabolic arc A→B peaking height h above midline**: for i in 0..N, t = i/N, x_i = lerp(A.x, B.x, t), y_i = lerp(A.y, B.y, t) - 4*h*t*(1-t). (4) **Canonical clockwise circle of radius r around (cx, cy)** with k = r * 0.5523: TOP `{x: cx, y: cy-r, in: [cx-k, cy-r], out: [cx+k, cy-r]}`, RIGHT `{x: cx+r, y: cy, in: [cx+r, cy-k], out: [cx+r, cy+k]}`, BOTTOM `{x: cx, y: cy+r, in: [cx+k, cy+r], out: [cx-k, cy+r]}`, LEFT `{x: cx-r, y: cy, in: [cx-r, cy+k], out: [cx-r, cy-k]}` — close with `closed: true`. (5) **Many short overlapping strokes for ink-on-paper texture**: chain multiple `apply_brush_stroke` calls along the same trajectory with small position offsets and varying `brush_size`; reads more natural than one long stroke.",
@@ -62,7 +72,7 @@ const applyBrushStrokeSchema = {
         },
         source_point: {
             type: 'object',
-            description: 'Sample point for `clone_stamp` / `healing_brush` — the pixel location PS samples from while the stroke progresses. REQUIRED for those two tools. Ignored for all others. `layer_name` defaults to the active layer at call time when omitted.',
+            description: 'Sample point for `clone_stamp` / `healing_brush` — the pixel location PS samples from while the stroke progresses. REQUIRED for those two tools (unless `source_placement` names it instead). Ignored for all others. `layer_name` defaults to the active layer at call time when omitted.',
             properties: {
                 x: { type: 'number', description: 'Source x in document pixels.' },
                 y: { type: 'number', description: 'Source y in document pixels.' },
@@ -73,6 +83,10 @@ const applyBrushStrokeSchema = {
             },
             required: ['x', 'y'],
         },
+        source_placement: {
+            ...PLACEMENT_SCHEMA,
+            description: 'Grounded alternative to `source_point` for `clone_stamp` / `healing_brush`: NAME the sample location (resolves to a POINT via the grounding resolver + objective gate — e.g. an `extremum` for the cleanest/smoothest nearby skin, a `grid` intersection, or a landmark point) instead of guessing pixels. Resolves to a POINT relation (centroid / midpoint / offset / extremum / grid / landmark point); the resolved point supplies `source_point` and WINS over an explicit `source_point`. Strokes only if the source gate PASSES.',
+        },
         foreground_color: {
             type: 'object',
             description: "RGB foreground color for paint-family tools (`brush`, `pencil`). The retouch family (`burn`/`dodge`/`blur`/`sharpen`/`smudge`/`clone_stamp`/`healing_brush`) ignores foreground color — setting it on those tools is harmless but pointless. The user's previous foreground color is restored after the stroke completes.",
@@ -101,14 +115,14 @@ const applyBrushStrokeSchema = {
             default: false,
         },
     },
-    required: ['tool', 'path', 'brush_size'],
+    required: ['tool', 'brush_size'],
 };
-export function createBrushTools(connection, snippetClient) {
+export function createBrushTools(connection, snippetClient, client = new OnnxLandmarkDetectionClient()) {
     return [
         {
             tool: {
-                name: 'photoshop_apply_brush_stroke',
-                description: 'Paint along a caller-supplied path with one of PS\'s 16 brush-family tools — the retouch tools (`healing_brush`, `clone_stamp`, `burn`, `dodge`, `blur`, `sharpen`, `smudge`), the paint family (`brush`, `pencil`, `eraser`), and the specialty tools (`pattern_stamp`, `art_history_brush`, `history_brush`, `color_replacement`, `background_eraser`, `sponge`). The `path` parameter takes a list of anchor points with optional bezier handles, so the same tool handles straight-line strokes, freeform curves, and closed shapes — all by varying the path geometry. **Reach for this when**: (a) cloning out a distraction along a specific shape (clone_stamp with a source_point + a path tracing the unwanted edge); (b) healing a scratch or seam (healing_brush with source_point); (c) dodging / burning to redirect tonal balance along a contour; (d) painting a freehand line into the canvas (brush + foreground_color). Active layer must be a normal pixel layer (background auto-promotes); rasterize adjustment/shape/text/smart-object layers first. Auto-duplicates per Bundle O — the original is preserved and a "Brush Stroke (<name>)" copy receives the paint. **Brush dynamics**: hardness, opacity, and flow are independently settable via `hardness_pct` / `opacity_pct` / `flow_pct` (the live tool options are mutated before stroking and restored to the user\'s prior state in `finally`). Sampled brushes (custom shape-stamp presets) silently ignore hardness/diameter mutations — vary their character via `brush_preset` instead.',
+                name: 'ps_apply_brush_stroke',
+                description: 'Paint along a path with one of PS\'s 16 brush-family tools — supply the path EITHER as an anchor-relational `placement` (preferred: a path relation → the stroke traces a resolved, gate-verified curve along a traced edge / landmark / between two anchors, no pixel-guessing) OR as an explicit `path` list of anchor points — the retouch tools (`healing_brush`, `clone_stamp`, `burn`, `dodge`, `blur`, `sharpen`, `smudge`), the paint family (`brush`, `pencil`, `eraser`), and the specialty tools (`pattern_stamp`, `art_history_brush`, `history_brush`, `color_replacement`, `background_eraser`, `sponge`). The `path` parameter takes a list of anchor points with optional bezier handles, so the same tool handles straight-line strokes, freeform curves, and closed shapes — all by varying the path geometry. **Reach for this when**: (a) cloning out a distraction along a specific shape (clone_stamp with a source_point + a path tracing the unwanted edge); (b) healing a scratch or seam (healing_brush with source_point); (c) dodging / burning to redirect tonal balance along a contour; (d) painting a freehand line into the canvas (brush + foreground_color). Active layer must be a normal pixel layer (background auto-promotes); rasterize adjustment/shape/text/smart-object layers first. Auto-duplicates per Bundle O — the original is preserved and a "Brush Stroke (<name>)" copy receives the paint. **Brush dynamics**: hardness, opacity, and flow are independently settable via `hardness_pct` / `opacity_pct` / `flow_pct` (the live tool options are mutated before stroking and restored to the user\'s prior state in `finally`). Sampled brushes (custom shape-stamp presets) silently ignore hardness/diameter mutations — vary their character via `brush_preset` instead.',
                 inputSchema: applyBrushStrokeSchema,
                 outputSchema: {
                     type: 'object',
@@ -132,6 +146,24 @@ export function createBrushTools(connection, snippetClient) {
                         target_was_copy: { type: 'boolean' },
                         target_layer_name: { type: 'string' },
                         original_layer_name: { type: 'string' },
+                        stroke_envelope: {
+                            type: 'object',
+                            description: 'The doc-pixel bbox the stroke should occupy (path bbox + brush radius) — the objective target to verify stroke occupancy against.',
+                        },
+                        placement: {
+                            type: 'object',
+                            description: 'Present when the stroke path came from anchor-relational placement: the resolved curve + gate verdict.',
+                            properties: {
+                                target: { type: 'string' },
+                                gate: { type: 'object' },
+                                anchors: { type: 'object' },
+                                points: { type: 'number' },
+                            },
+                        },
+                        source_placement: {
+                            type: 'object',
+                            description: 'Present when the clone/heal sample point came from a source_placement: the resolved point + gate verdict.',
+                        },
                         context: { type: 'object' },
                     },
                 },
@@ -141,37 +173,58 @@ export function createBrushTools(connection, snippetClient) {
                     idempotentHint: false,
                 },
             },
-            handler: async (args) => applyBrushStroke(connection, snippetClient, args),
+            handler: async (args) => applyBrushStroke(connection, snippetClient, client, args),
         },
     ];
 }
-async function applyBrushStroke(connection, snippetClient, rawArgs) {
+async function applyBrushStroke(connection, snippetClient, client, rawArgs) {
     try {
         const args = validateArgs(applyBrushStrokeSchema, rawArgs);
         const tool = args.tool;
-        const path = args.path;
-        const brush_size = args.brush_size;
-        const brush_preset = args.brush_preset;
-        const source_point = args.source_point;
-        const foreground_color = args.foreground_color;
-        const closed = args.closed ?? false;
-        const jitter_px = args.jitter_px ?? 0;
-        const hardness_pct = args.hardness_pct;
-        const opacity_pct = args.opacity_pct;
-        const flow_pct = args.flow_pct;
-        const apply_to_active_layer = args.apply_to_active_layer ?? false;
-        if (TOOLS_REQUIRING_SOURCE.includes(tool) && !source_point) {
+        if (TOOLS_REQUIRING_SOURCE.includes(tool) &&
+            !args.source_point &&
+            !args.source_placement) {
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `${tool} requires source_point ({x, y, layer_name?}) — set the sample location ` +
-                            `before stroking. (Healing brush and clone stamp both need to know what to copy from.)`,
+                        text: `${tool} requires a sample location — set source_point ({x, y, layer_name?}) or name it ` +
+                            `via source_placement (resolved + gated) before stroking. (Healing brush and clone stamp ` +
+                            `both need to know what to copy from.)`,
                     },
                 ],
                 isError: true,
             };
         }
+        let path;
+        let placementInfo;
+        if (args.placement) {
+            const rp = await resolveExpectedPlacement(connection, client, args.placement, 'path', `${tool} stroke`);
+            path = rp.curve.map((p) => ({ x: p.x, y: p.y }));
+            placementInfo = { target: rp.target, anchors: rp.anchors, points: rp.curve.length };
+        }
+        else {
+            path = args.path;
+            if (!Array.isArray(path) || path.length < 2) {
+                throw new Error('path needs at least 2 anchors, or a placement (anchors + a path relation).');
+            }
+        }
+        const brush_size = args.brush_size;
+        const brush_preset = args.brush_preset;
+        let source_point = args.source_point;
+        let sourcePlacementInfo;
+        if (args.source_placement) {
+            const sp = await resolveExpectedPlacement(connection, client, args.source_placement, 'point', `${tool} source`);
+            source_point = { x: sp.point.x, y: sp.point.y };
+            sourcePlacementInfo = { target: sp.target, point: sp.point };
+        }
+        const foreground_color = args.foreground_color;
+        const closed = args.closed ?? false;
+        const jitter_px = args.jitter_px ?? 0;
+        const hardness_pct = args.hardness_pct;
+        const opacity_pct = args.opacity_pct;
+        const flow_pct = args.flow_pct;
+        const apply_to_active_layer = args.apply_to_active_layer ?? false;
         const pathToStroke = jitter_px > 0 ? applyJitter(path, jitter_px) : path;
         const script = await snippetClient.build('applyBrushStroke', {
             tool,
@@ -192,15 +245,50 @@ async function applyBrushStroke(connection, snippetClient, rawArgs) {
         const targetSuffix = result.target_was_copy
             ? ` on copy "${result.target_layer_name}"`
             : ` on layer "${result.target_layer_name}"`;
+        const placementSuffix = placementInfo ? ' via placement (gate PASS)' : '';
+        const xs = pathToStroke.map((a) => a.x);
+        const ys = pathToStroke.map((a) => a.y);
+        const rad = result.brush_size / 2;
+        const strokeEnvelope = {
+            left: Math.round(Math.min(...xs) - rad),
+            top: Math.round(Math.min(...ys) - rad),
+            right: Math.round(Math.max(...xs) + rad),
+            bottom: Math.round(Math.max(...ys) + rad),
+        };
+        const structured = {
+            ...result,
+            stroke_envelope: strokeEnvelope,
+        };
+        if (placementInfo) {
+            structured.placement = {
+                target: placementInfo.target,
+                gate: { pass: true },
+                anchors: placementInfo.anchors,
+                points: placementInfo.points,
+            };
+        }
+        if (sourcePlacementInfo) {
+            structured.source_placement = {
+                target: sourcePlacementInfo.target,
+                gate: { pass: true },
+                point: {
+                    x: Math.round(sourcePlacementInfo.point.x),
+                    y: Math.round(sourcePlacementInfo.point.y),
+                },
+            };
+        }
+        const srcPlaceSuffix = sourcePlacementInfo ? ' [source via placement, gate PASS]' : '';
         return {
             content: [
                 {
                     type: 'text',
                     text: `${tool} stroke (${result.anchors} anchors, size ${result.brush_size}px${presetSuffix})` +
-                        `${sourceSuffix}${targetSuffix}.`,
+                        `${sourceSuffix}${srcPlaceSuffix}${targetSuffix}${placementSuffix}. Expected envelope ` +
+                        `[${strokeEnvelope.left},${strokeEnvelope.top},${strokeEnvelope.right},${strokeEnvelope.bottom}] — ` +
+                        `verify occupancy there (ps_get_preview / ps_compare_regions).`,
                 },
             ],
-            structuredContent: result,
+            structuredContent: structured,
         };
     }
     catch (error) {