@pixerate/editor 0.149.0 → 0.150.1

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

@@ -4,6 +4,7 @@ export * from './color.cjs';
 export * from './renderer.cjs';
 export * from './controller.cjs';
 export * from './geometry.cjs';
+export * from './canvas-viewport.cjs';
 export * from './document.cjs';
 export * from './blend.cjs';
 export * from './adjustment-layers.cjs';

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

@@ -4,6 +4,7 @@ export * from './color.js';
 export * from './renderer.js';
 export * from './controller.js';
 export * from './geometry.js';
+export * from './canvas-viewport.js';
 export * from './document.js';
 export * from './blend.js';
 export * from './adjustment-layers.js';

package/dist/image-editor/index.js

@@ -52,6 +52,7 @@ import {
   XYZ_D50_TO_SRGB,
   activeAdjustmentLayers,
   activeEffectSmartFilters,
+  activeLayerAfterRemoval,
   activeSmartFilters,
   addLayerEffect,
   addLayerFilter,
@@ -117,6 +118,7 @@ import {
   decodePlanes,
   decodePngDataUrl,
   decodeSelectionRle,
+  defaultActiveLayerId,
   defaultAdjustmentParams,
   defaultShapeName,
   depthMaskAlpha,
@@ -178,6 +180,7 @@ import {
   isDefaultDepthMask,
   isIdentityTransform,
   isLegacyShape,
+  isPaintableLayer,
   isQuarterTurnSwapped,
   isRenderedLayer,
   isSelectionEmpty,
@@ -348,6 +351,7 @@ import {
   updateShapeLayer,
   updateSmartFilter,
   updateTypeLayer,
+  userErrorMessage,
   uvToXy,
   versionedDescriptorBytes,
   vibranceLinear,
@@ -363,7 +367,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-ZQUANEK4.js";
+} from "../chunk-Y64YPIFT.js";
 import {
   parseCssColor
 } from "../chunk-3CI7FRMK.js";
@@ -1245,8 +1249,10 @@ var ImageEditorRenderer = class {
     const { crop, transform, adjustments, depthMask, annotations, selectedAnnotationId, zoom, pan, isOriginalCompared } = state;
     const vpWidth = options.viewportWidth || targetCanvas.width;
     const vpHeight = options.viewportHeight || targetCanvas.height;
-    targetCanvas.width = vpWidth;
-    targetCanvas.height = vpHeight;
+    const ratio = options.pixelRatio && Number.isFinite(options.pixelRatio) && options.pixelRatio > 0 ? options.pixelRatio : 1;
+    targetCanvas.width = Math.max(1, Math.round(vpWidth * ratio));
+    targetCanvas.height = Math.max(1, Math.round(vpHeight * ratio));
+    if (ratio !== 1 && typeof ctx.setTransform === "function") ctx.setTransform(targetCanvas.width / vpWidth, 0, 0, targetCanvas.height / vpHeight, 0, 0);
     ctx.clearRect(0, 0, vpWidth, vpHeight);
     if (isOriginalCompared) {
       this.drawFittedImage(ctx, img, naturalWidth, naturalHeight, vpWidth, vpHeight, zoom, pan, fit);
@@ -4901,8 +4907,8 @@ var ImageEditorController = class {
     this.state.layers = next;
     extra?.();
     if (depth !== 8 && this.bitDepth === depth) this.state.layers = keepDeepLayers(prev, this.state.layers);
-    if (this.state.activeLayerId && !findLayer(next, this.state.activeLayerId)) {
-      this.state.activeLayerId = null;
+    if (this.state.activeLayerId && !findLayer(this.state.layers, this.state.activeLayerId)) {
+      this.state.activeLayerId = activeLayerAfterRemoval(prev, this.state.layers, this.state.activeLayerId);
       this.state.activeTarget = "pixels";
     }
     this.notify();
@@ -6126,27 +6132,28 @@ var ImageEditorController = class {
   /** Resolves and validates what a stroke, fill or clear paints into. */
   paintTarget(layerId, channel, action) {
     const id = layerId ?? this.state.activeLayerId;
-    if (!id) throw new LayerOperationError(`No layer given and none is active; pass layerId (see list_layers) to ${action}.`);
+    if (!id) throw new LayerOperationError(`No layer given and none is active; pass layerId (see list_layers) to ${action}.`, `Pick a layer to ${action} on in the Layers panel.`);
     const layer = requireLayer(this.state.layers, id).layer;
+    const name = layer.name || id;
     const ch = channel ?? (id === this.state.activeLayerId ? this.state.activeTarget : "pixels");
     if (ch === "mask") {
-      if (!layer.mask) throw new LayerOperationError(`Layer "${layer.name || id}" has no mask to ${action}; add one with add_layer_mask, or target pixels.`);
-      if (layer.mask.source) throw new LayerOperationError(`Layer "${layer.name || id}" has a depth mask, which is generated, not painted.`);
+      if (!layer.mask) throw new LayerOperationError(`Layer "${name}" has no mask to ${action}; add one with add_layer_mask, or target pixels.`, `Layer "${name}" has no mask; add a mask or ${action} on its pixels.`);
+      if (layer.mask.source) throw new LayerOperationError(`Layer "${name}" has a depth mask, which is generated, not painted.`);
       requireUnlocked(layer, "all", action);
     } else if (ch === "filter-mask") {
       if (layer.type !== "smart" || !layer.smartFilters?.mask) {
-        throw new LayerOperationError(`Layer "${layer.name || id}" has no smart filter mask to ${action}; add one with set_smart_filter_mask, or target pixels or mask.`);
+        throw new LayerOperationError(`Layer "${name}" has no smart filter mask to ${action}; add one with set_smart_filter_mask, or target pixels or mask.`, `Layer "${name}" has no smart filter mask to ${action}.`);
       }
-      if (!isContentsDecoded(layer.contents)) throw new LayerOperationError(`The contents of "${layer.name || id}" are not decoded here, so its filter mask cannot be painted; run prepareSmartObjects() first.`);
+      if (!isContentsDecoded(layer.contents)) throw new LayerOperationError(`The contents of "${name}" are not decoded here, so its filter mask cannot be painted; run prepareSmartObjects() first.`, `The smart object "${name}" is still loading; try again in a moment.`);
       requireUnlocked(layer, "all", action);
     } else {
-      if (layer.type === "smart") throw new LayerOperationError(`Layer "${layer.name || id}" is a smart object; its pixels come from its contents. Rasterize it (rasterize_smart_object), edit its contents (edit_smart_object_contents), or ${action} on its mask or filter mask.`);
-      if (layer.type === "shape") throw new LayerOperationError(`Layer "${layer.name || id}" is a shape layer; its pixels are drawn from its paths. Rasterize it first (rasterize_layer), or ${action} on its mask (channel mask).`);
-      if (layer.type === "type") throw new LayerOperationError(`Layer "${layer.name || id}" is a type layer; its pixels are drawn from its text. Rasterize it first (rasterize_layer), or ${action} on its mask (channel mask).`);
-      if (layer.type !== "pixel") throw new LayerOperationError(`Layer "${layer.name || id}" is a ${layer.type} layer; ${action} on a pixel layer, or on this layer's mask (channel mask).`);
+      if (layer.type === "smart") throw new LayerOperationError(`Layer "${name}" is a smart object; its pixels come from its contents. Rasterize it (rasterize_smart_object), edit its contents (edit_smart_object_contents), or ${action} on its mask or filter mask.`, `"${name}" is a smart object; rasterize it or edit its contents to ${action} on it.`);
+      if (layer.type === "shape") throw new LayerOperationError(`Layer "${name}" is a shape layer; its pixels are drawn from its paths. Rasterize it first (rasterize_layer), or ${action} on its mask (channel mask).`, `"${name}" is a shape layer; rasterize it to ${action} on it.`);
+      if (layer.type === "type") throw new LayerOperationError(`Layer "${name}" is a type layer; its pixels are drawn from its text. Rasterize it first (rasterize_layer), or ${action} on its mask (channel mask).`, `"${name}" is a type layer; rasterize it to ${action} on it.`);
+      if (layer.type !== "pixel") throw new LayerOperationError(`Layer "${name}" is a ${layer.type} layer; ${action} on a pixel layer, or on this layer's mask (channel mask).`, `"${name}" is not a pixel layer; pick a pixel layer to ${action} on.`);
       requireUnlocked(layer, "pixels", action);
     }
-    if (!layer.visible) throw new LayerOperationError(`Layer "${layer.name || id}" is hidden; show it before you ${action}.`);
+    if (!layer.visible) throw new LayerOperationError(`Layer "${name}" is hidden; show it before you ${action}.`);
     const offset = layer.type === "pixel" ? layer.offset : { x: 0, y: 0 };
     const surface = ch === "mask" ? layer.mask.surface : ch === "filter-mask" ? layer.smartFilters.mask.surface : this.surfaceOf(layer);
     const lockTransparency = ch === "pixels" && Boolean(layer.locks?.transparency);
@@ -6171,7 +6178,7 @@ var ImageEditorController = class {
     if (!STROKE_TOOLS.includes(tool)) throw new LayerOperationError(`Unknown paint tool "${String(tool)}"; use one of ${STROKE_TOOLS.join(", ")}.`);
     const target = this.paintTarget(init.layerId, init.channel, tool === "eraser" ? "erase" : isRetouchTool(tool) ? "retouch" : "paint");
     if (tool === "mixer" && target.channel !== "pixels") {
-      throw new LayerOperationError("The Mixer Brush paints colour on pixels, not on masks; target pixels (channel pixels), or paint the mask with the brush.");
+      throw new LayerOperationError("The Mixer Brush paints colour on pixels, not on masks; target pixels (channel pixels), or paint the mask with the brush.", "The Mixer Brush paints on pixels, not masks; target the layer's pixels, or paint the mask with the Brush.");
     }
     const brush = normalizeBrush({ ...this.state.paint.brush, ...init.brush ?? {} });
     let strokePaint = null;
@@ -6650,8 +6657,12 @@ var ImageEditorController = class {
     const loc = findLayer(this.state.layers, id);
     if (!loc || loc.layer.type !== "adjustment") return false;
     this.recordHistory();
-    this.state.layers = mapLayer(this.state.layers, id, () => null);
-    if (this.state.activeLayerId === id) this.state.activeLayerId = null;
+    const prev = this.state.layers;
+    this.state.layers = mapLayer(prev, id, () => null);
+    if (this.state.activeLayerId === id) {
+      this.state.activeLayerId = activeLayerAfterRemoval(prev, this.state.layers, id);
+      this.state.activeTarget = "pixels";
+    }
     this.notify();
     return true;
   }
@@ -6689,10 +6700,15 @@ var ImageEditorController = class {
     const nodes = this.adjustmentNodes();
     if (!nodes.length) return;
     this.recordHistory();
-    let layers = this.state.layers;
+    const prev = this.state.layers;
+    let layers = prev;
     for (const n of nodes) layers = mapLayer(layers, n.id, () => null);
     this.state.layers = layers;
-    if (nodes.some((n) => n.id === this.state.activeLayerId)) this.state.activeLayerId = null;
+    const active = this.state.activeLayerId;
+    if (active && nodes.some((n) => n.id === active)) {
+      this.state.activeLayerId = activeLayerAfterRemoval(prev, layers, active);
+      this.state.activeTarget = "pixels";
+    }
     this.notify();
   }
   // --- Selection ---
@@ -8009,8 +8025,7 @@ var ImageEditorController = class {
     delete s.legacyOutputBlur;
     s.selection = null;
     s.selectedAnnotationId = null;
-    const pixels = flattenLayers(result.layers).filter((l) => l.type === "pixel");
-    s.activeLayerId = pixels.length ? pixels[pixels.length - 1].id : null;
+    s.activeLayerId = defaultActiveLayerId(s.layers);
     s.activeTarget = "pixels";
     this.psdResolution = result.resolution;
     if (result.patterns.length) s.patterns = result.patterns;
@@ -8338,7 +8353,7 @@ var ImageEditorController = class {
       s.outputOpacity = data.opacity;
       if (typeof data.legacyOutputBlur === "number" && data.legacyOutputBlur >= 0) s.legacyOutputBlur = data.legacyOutputBlur;
       else delete s.legacyOutputBlur;
-      s.activeLayerId = data.activeLayerId && findLayer(s.layers, data.activeLayerId) ? data.activeLayerId : null;
+      s.activeLayerId = data.activeLayerId && findLayer(s.layers, data.activeLayerId) ? data.activeLayerId : defaultActiveLayerId(s.layers);
       const light = data.globalLight;
       if (light && Number.isFinite(light.angle) && Number.isFinite(light.altitude)) s.globalLight = { angle: light.angle, altitude: Math.min(90, Math.max(0, light.altitude)) };
       else delete s.globalLight;
@@ -8365,7 +8380,7 @@ var ImageEditorController = class {
       else delete s.legacyOutputBlur;
       s.crop = data.crop ? { ...data.crop } : null;
       s.transform = { ...data.transform };
-      s.activeLayerId = null;
+      s.activeLayerId = defaultActiveLayerId(s.layers);
       delete s.globalLight;
       delete s.patterns;
       delete s.bitDepth;
@@ -8677,6 +8692,49 @@ function scaleAnnotation(ann, sx, sy) {
   }
 }
 
+// src/image-editor/canvas-viewport.ts
+var DEFAULT_CANVAS_VIEWPORT = { width: 800, height: 500 };
+var MAX_CANVAS_BACKING_SIDE = 8192;
+var currentDevicePixelRatio = () => typeof window !== "undefined" && window.devicePixelRatio > 0 ? window.devicePixelRatio : 1;
+function measureCanvasViewport(el, devicePixelRatio = currentDevicePixelRatio(), fallback = DEFAULT_CANVAS_VIEWPORT) {
+  const width = el.clientWidth || fallback.width;
+  const height = el.clientHeight || fallback.height;
+  const dpr = Number.isFinite(devicePixelRatio) && devicePixelRatio > 0 ? devicePixelRatio : 1;
+  const box = el.getBoundingClientRect();
+  const layoutW = el.offsetWidth || el.clientWidth;
+  const layoutH = el.offsetHeight || el.clientHeight;
+  const sx = layoutW > 0 && box.width > 0 ? box.width / layoutW : 1;
+  const sy = layoutH > 0 && box.height > 0 ? box.height / layoutH : 1;
+  let pixelRatio = dpr * Math.max(sx, sy);
+  pixelRatio = Math.min(pixelRatio, MAX_CANVAS_BACKING_SIDE / Math.max(width, height));
+  return { width, height, pixelRatio: Number.isFinite(pixelRatio) && pixelRatio > 0 ? pixelRatio : 1 };
+}
+function sameCanvasViewport(a, b) {
+  return a.width === b.width && a.height === b.height && Math.abs(a.pixelRatio - b.pixelRatio) < 1e-3;
+}
+function watchCanvasViewport(el, onChange) {
+  let last = measureCanvasViewport(el);
+  const check = () => {
+    const next = measureCanvasViewport(el);
+    if (sameCanvasViewport(next, last)) return;
+    last = next;
+    onChange(next);
+  };
+  const stops = [];
+  if (typeof ResizeObserver !== "undefined" && typeof Element !== "undefined" && el instanceof Element) {
+    const observer = new ResizeObserver(check);
+    observer.observe(el);
+    stops.push(() => observer.disconnect());
+  }
+  if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    for (const type of ["resize", "transitionend", "animationend"]) {
+      window.addEventListener(type, check, true);
+      stops.push(() => window.removeEventListener(type, check, true));
+    }
+  }
+  return () => stops.forEach((stop) => stop());
+}
+
 // src/image-editor/document.ts
 var IMAGE_EDITOR_STATE_VERSION = 3;
 var imageEditorStateMigrations = {};
@@ -9309,6 +9367,29 @@ function withImagePlayback(provider, surface) {
     tools: typeof tools === "function" ? () => tools().map(plan) : tools.map(plan)
   };
 }
+function agentDragDraft(mode, box, image) {
+  if (mode === "select") {
+    return {
+      selectionPath: [
+        { x: box.x, y: box.y },
+        { x: box.x + box.width, y: box.y },
+        { x: box.x + box.width, y: box.y + box.height },
+        { x: box.x, y: box.y + box.height }
+      ]
+    };
+  }
+  if (mode !== "crop" || !image.width || !image.height) return null;
+  const x = Math.max(0, Math.min(image.width, box.x));
+  const y = Math.max(0, Math.min(image.height, box.y));
+  return {
+    crop: {
+      x,
+      y,
+      width: Math.max(1, Math.min(image.width - x, box.width)),
+      height: Math.max(1, Math.min(image.height - y, box.height))
+    }
+  };
+}
 
 // src/image-editor/selection/tool-options.ts
 var SELECTION_TOOLS = [
@@ -10117,13 +10198,13 @@ function createImageLayerTools(controller) {
   const remove = {
     name: "remove_layer",
     title: "Delete a layer",
-    description: "Deletes a layer (a group with its children). Refused for a layer locked with all. Prefer hiding it (set_layer_properties visible false) when it may be wanted back. One undo step. Returns the removed id and the remaining top-level ids.",
+    description: "Deletes a layer (a group with its children). Refused for a layer locked with all. Prefer hiding it (set_layer_properties visible false) when it may be wanted back. Deleting the active layer makes the nearest paintable pixel layer below it active (else the topmost one). One undo step. Returns the removed id, the remaining top-level ids and the active layer id afterwards.",
     inputSchema: { type: "object", properties: { layerId: LAYER_ID2 }, required: ["layerId"], additionalProperties: false },
     annotations: { title: "Delete a layer", ...DESTRUCTIVE },
     handler: ({ layerId }) => {
       const id = exists(layerId);
       controller.removeLayer(id);
-      return { removed: id, layers: controller.getLayers().map((l) => l.id) };
+      return { removed: id, layers: controller.getLayers().map((l) => l.id), activeLayerId: controller.getState().activeLayerId };
     }
   };
   const move = {
@@ -11024,7 +11105,7 @@ var PaintGesture = class {
         return null;
       }
     } catch (err) {
-      this.error = err instanceof Error ? err.message : String(err);
+      this.error = userErrorMessage(err);
       this.stroke = null;
       this.move = null;
     }
@@ -11046,7 +11127,7 @@ var PaintGesture = class {
         this.controller.offsetLayer(m.id, { x, y }, !m.moved);
         m.moved = true;
       } catch (err) {
-        this.error = err instanceof Error ? err.message : String(err);
+        this.error = userErrorMessage(err);
         this.move = null;
       }
     }
@@ -11056,7 +11137,7 @@ var PaintGesture = class {
       try {
         this.stroke.end();
       } catch (err) {
-        this.error = err instanceof Error ? err.message : String(err);
+        this.error = userErrorMessage(err);
       }
     }
     this.stroke = null;
@@ -15202,6 +15283,7 @@ export {
   DEFAULT_AUTO_LEADING,
   DEFAULT_BLENDER,
   DEFAULT_BRUSH,
+  DEFAULT_CANVAS_VIEWPORT,
   DEFAULT_DEPTH_MASK,
   DEFAULT_FLOW,
   DEFAULT_GLOBAL_LIGHT,
@@ -15276,6 +15358,7 @@ export {
   LayerOperationError,
   MAX_BATCH,
   MAX_BRUSH_SIZE,
+  MAX_CANVAS_BACKING_SIDE,
   MAX_EFFECT_REACH,
   MAX_KELVIN,
   MAX_TILT_ACCEL,
@@ -15412,6 +15495,7 @@ export {
   ZlibError,
   activeAdjustmentLayers,
   activeEffectSmartFilters,
+  activeLayerAfterRemoval,
   activeSmartFilters,
   addLayerEffect,
   addLayerFilter,
@@ -15423,6 +15507,7 @@ export {
   adjustmentNodeAsLayer,
   adjustmentNodeFromLegacy,
   adler32,
+  agentDragDraft,
   anchorPoint,
   annotationBlend,
   annotationLayerFor,
@@ -15573,6 +15658,7 @@ export {
   decodeSelectionRle,
   deepBytes,
   deepTile,
+  defaultActiveLayerId,
   defaultAdjustmentParams,
   defaultEffectGradient,
   defaultLayerEffect,
@@ -15727,6 +15813,7 @@ export {
   isLayerLocked,
   isLegacyShape,
   isPaintTool,
+  isPaintableLayer,
   isPainterlyBlendMode,
   isPng,
   isQuarterTurn,
@@ -15791,6 +15878,7 @@ export {
   maskSummary,
   matrixFromCorners,
   matrixFromParams,
+  measureCanvasViewport,
   membraneFill,
   mergeLayerEffect,
   mergeShapeComponents,
@@ -15969,6 +16057,7 @@ export {
   runLayerFilters,
   runLayerFiltersFloat,
   runLayerMenuAction,
+  sameCanvasViewport,
   sampleLut,
   sampleToneLut,
   saturationOf,
@@ -16095,6 +16184,7 @@ export {
   updateShapeLayer,
   updateSmartFilter,
   updateTypeLayer,
+  userErrorMessage,
   uvToXy,
   validateEffectGradient,
   validateLayerEffect,
@@ -16108,6 +16198,7 @@ export {
   warpMeshParamAt,
   warpPresetMesh,
   warpSurface,
+  watchCanvasViewport,
   wbMatrix,
   wetGpuSupport,
   wetSimdSupported,

package/dist/image-editor/layers/ops.d.cts

@@ -6,11 +6,29 @@
 import type { BlendMode } from '../blend.cjs';
 import type { CropBox } from '../types.cjs';
 import { type LayerEffect, type LayerEffectKind, type LayerEffects } from '../../raster/effects/model.cjs';
-import { type ImageLayer, type LayerBlendMode, type LayerFilter, type LayerLocks, type RasterMask } from './model.cjs';
-/** A refused layer operation; the message says why and how to fix it. */
+import { type ImageLayer, type LayerBlendMode, type LayerFilter, type LayerLocks, type PixelLayer, type RasterMask } from './model.cjs';
+/**
+ * A refused layer operation; the message says why and how to fix it (written for agents: it names
+ * tools and arguments). `userMessage`, when given, says the same for a person at the canvas.
+ */
 export declare class LayerOperationError extends Error {
-    constructor(message: string);
+    readonly userMessage?: string;
+    constructor(message: string, userMessage?: string);
 }
+/** The message of a refusal to show a person: a `LayerOperationError`'s `userMessage`, else the message. */
+export declare function userErrorMessage(err: unknown): string;
+/** Whether brush strokes can go on a layer's pixels: a visible pixel layer without its pixels locked. */
+export declare function isPaintableLayer(layer: ImageLayer): layer is PixelLayer;
+/**
+ * The layer a document with no active layer works on: the topmost paintable pixel layer (the
+ * Background of a newly loaded image), else the topmost pixel layer, else `null`.
+ */
+export declare function defaultActiveLayerId(layers: readonly ImageLayer[]): string | null;
+/**
+ * The layer to make active when the active layer `removedId` left the stack (`prev` → `next`):
+ * the nearest paintable layer that was below it, else `defaultActiveLayerId(next)`.
+ */
+export declare function activeLayerAfterRemoval(prev: readonly ImageLayer[], next: readonly ImageLayer[], removedId: string): string | null;
 /** Where a layer goes: above or below a layer (in its group), or at a position in a group. */
 export interface LayerPlacement {
     /** Directly above this layer, in the same group. */

package/dist/image-editor/layers/ops.d.ts

@@ -6,11 +6,29 @@
 import type { BlendMode } from '../blend.js';
 import type { CropBox } from '../types.js';
 import { type LayerEffect, type LayerEffectKind, type LayerEffects } from '../../raster/effects/model.js';
-import { type ImageLayer, type LayerBlendMode, type LayerFilter, type LayerLocks, type RasterMask } from './model.js';
-/** A refused layer operation; the message says why and how to fix it. */
+import { type ImageLayer, type LayerBlendMode, type LayerFilter, type LayerLocks, type PixelLayer, type RasterMask } from './model.js';
+/**
+ * A refused layer operation; the message says why and how to fix it (written for agents: it names
+ * tools and arguments). `userMessage`, when given, says the same for a person at the canvas.
+ */
 export declare class LayerOperationError extends Error {
-    constructor(message: string);
+    readonly userMessage?: string;
+    constructor(message: string, userMessage?: string);
 }
+/** The message of a refusal to show a person: a `LayerOperationError`'s `userMessage`, else the message. */
+export declare function userErrorMessage(err: unknown): string;
+/** Whether brush strokes can go on a layer's pixels: a visible pixel layer without its pixels locked. */
+export declare function isPaintableLayer(layer: ImageLayer): layer is PixelLayer;
+/**
+ * The layer a document with no active layer works on: the topmost paintable pixel layer (the
+ * Background of a newly loaded image), else the topmost pixel layer, else `null`.
+ */
+export declare function defaultActiveLayerId(layers: readonly ImageLayer[]): string | null;
+/**
+ * The layer to make active when the active layer `removedId` left the stack (`prev` → `next`):
+ * the nearest paintable layer that was below it, else `defaultActiveLayerId(next)`.
+ */
+export declare function activeLayerAfterRemoval(prev: readonly ImageLayer[], next: readonly ImageLayer[], removedId: string): string | null;
 /** Where a layer goes: above or below a layer (in its group), or at a position in a group. */
 export interface LayerPlacement {
     /** Directly above this layer, in the same group. */

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

@@ -1,5 +1,6 @@
 import type { AgentToolProvider } from '../tools/registry.cjs';
-import type { PlaybackRect, PlaybackRef, PlaybackStep } from '../tools/playback.cjs';
+import type { PlaybackPoint, PlaybackRect, PlaybackRef, PlaybackStep } from '../tools/playback.cjs';
+import type { PresenceDragBox } from '../tools/presence.cjs';
 import type { ImageEditorController } from './controller.cjs';
 /** The playback kind of an image layer (`{ kind: 'layer', id }`, as in `data-layer-id`). */
 export declare const IMAGE_PLAYBACK_KIND = "layer";
@@ -20,3 +21,21 @@ export declare function planImageToolPlayback(tool: string, args: Record<string,
  * provider's own `playbackSurface`; with neither, it is `image` (where `ImageEditor` attaches itself).
  */
 export declare function withImagePlayback(provider: AgentToolProvider, surface?: string): AgentToolProvider;
+/**
+ * What a canvas draws while an agent drags on it (see `trackPresenceDrag`): in crop mode, the crop
+ * box being pulled out (clamped to the image); in select mode, the marquee as a selection path.
+ * The tool call that follows sets the real crop or selection.
+ */
+export declare function agentDragDraft(mode: string, box: PresenceDragBox, image: {
+    width: number;
+    height: number;
+}): {
+    crop: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+} | {
+    selectionPath: PlaybackPoint[];
+} | null;

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

@@ -1,5 +1,6 @@
 import type { AgentToolProvider } from '../tools/registry.js';
-import type { PlaybackRect, PlaybackRef, PlaybackStep } from '../tools/playback.js';
+import type { PlaybackPoint, PlaybackRect, PlaybackRef, PlaybackStep } from '../tools/playback.js';
+import type { PresenceDragBox } from '../tools/presence.js';
 import type { ImageEditorController } from './controller.js';
 /** The playback kind of an image layer (`{ kind: 'layer', id }`, as in `data-layer-id`). */
 export declare const IMAGE_PLAYBACK_KIND = "layer";
@@ -20,3 +21,21 @@ export declare function planImageToolPlayback(tool: string, args: Record<string,
  * provider's own `playbackSurface`; with neither, it is `image` (where `ImageEditor` attaches itself).
  */
 export declare function withImagePlayback(provider: AgentToolProvider, surface?: string): AgentToolProvider;
+/**
+ * What a canvas draws while an agent drags on it (see `trackPresenceDrag`): in crop mode, the crop
+ * box being pulled out (clamped to the image); in select mode, the marquee as a selection path.
+ * The tool call that follows sets the real crop or selection.
+ */
+export declare function agentDragDraft(mode: string, box: PresenceDragBox, image: {
+    width: number;
+    height: number;
+}): {
+    crop: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+} | {
+    selectionPath: PlaybackPoint[];
+} | null;

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

@@ -7,8 +7,15 @@ import { type PixelSurface } from '../raster/surface.cjs';
 import type { GlobalLight } from '../raster/effects/model.cjs';
 import type { EffectPattern } from '../raster/effects/patterns.cjs';
 export interface RenderOptions {
+    /** The viewport's size in CSS pixels: layout, the projection and overlays use these units. */
     viewportWidth?: number;
     viewportHeight?: number;
+    /**
+     * Backing-store pixels per CSS pixel (default 1): the canvas is sized `viewport × pixelRatio` and
+     * drawn through that scale, so it stays sharp on high-DPI screens and under CSS transforms. See
+     * `measureCanvasViewport`.
+     */
+    pixelRatio?: number;
     showCropOverlay?: boolean;
     showSelectionOverlay?: boolean;
     interactive?: boolean;

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

@@ -7,8 +7,15 @@ import { type PixelSurface } from '../raster/surface.js';
 import type { GlobalLight } from '../raster/effects/model.js';
 import type { EffectPattern } from '../raster/effects/patterns.js';
 export interface RenderOptions {
+    /** The viewport's size in CSS pixels: layout, the projection and overlays use these units. */
     viewportWidth?: number;
     viewportHeight?: number;
+    /**
+     * Backing-store pixels per CSS pixel (default 1): the canvas is sized `viewport × pixelRatio` and
+     * drawn through that scale, so it stays sharp on high-DPI screens and under CSS transforms. See
+     * `measureCanvasViewport`.
+     */
+    pixelRatio?: number;
     showCropOverlay?: boolean;
     showSelectionOverlay?: boolean;
     interactive?: boolean;

package/dist/paint-editor/index.cjs

@@ -7,7 +7,7 @@ var _chunkVKF3PWKRcjs = require('../chunk-VKF3PWKR.cjs');
 
 
 
-var _chunkQCEQIRJQcjs = require('../chunk-QCEQIRJQ.cjs');
+var _chunkPI45JMP7cjs = require('../chunk-PI45JMP7.cjs');
 require('../chunk-A2IS7EHE.cjs');
 
 
@@ -53,7 +53,7 @@ var _chunkJLWLX52Lcjs = require('../chunk-JLWLX52L.cjs');
 
 
 
-var _chunkUJGAA6AKcjs = require('../chunk-UJGAA6AK.cjs');
+var _chunkSWTUM32Hcjs = require('../chunk-SWTUM32H.cjs');
 require('../chunk-RHXW4TA5.cjs');
 
 
@@ -1634,11 +1634,11 @@ function header(state, options) {
   return out;
 }
 function serializePaintDocument(state, options = {}) {
-  const { layers, assets } = _chunkQCEQIRJQcjs.serializeLayers.call(void 0, state.layers);
+  const { layers, assets } = _chunkPI45JMP7cjs.serializeLayers.call(void 0, state.layers);
   return { ...header(state, options), layers, assets };
 }
 async function serializePaintDocumentExternal(state, store, options = {}) {
-  const { layers, assets } = await _chunkQCEQIRJQcjs.serializeLayersExternal.call(void 0, state.layers, store);
+  const { layers, assets } = await _chunkPI45JMP7cjs.serializeLayersExternal.call(void 0, state.layers, store);
   return { ...header(state, options), layers, assets };
 }
 function paintLayersOnly(layers, problems) {
@@ -1675,7 +1675,7 @@ function deserializePaintDocument(raw) {
   const canvas = normalizeCanvas({ width: r.width, height: r.height, dpi: _nullishCoalesce(r.dpi, () => ( void 0)) });
   const paper = _chunkBXMIBMVGcjs.normalizePaper.call(void 0, _nullishCoalesce(r.paper, () => ( {})));
   const assets = r.assets && typeof r.assets === "object" ? r.assets : {};
-  const layers = paintLayersOnly(_chunkQCEQIRJQcjs.deserializeLayers.call(void 0, r.layers, { assets, problems }), problems);
+  const layers = paintLayersOnly(_chunkPI45JMP7cjs.deserializeLayers.call(void 0, r.layers, { assets, problems }), problems);
   const wanted = typeof r.activeLayerId === "string" ? r.activeLayerId : null;
   const activeLayerId = wanted && _chunkHGTDMKNEcjs.findLayer.call(void 0, layers, wanted) ? wanted : _nullishCoalesce(_optionalChain([_chunkHGTDMKNEcjs.flattenLayers.call(void 0, layers), 'access', _70 => _70.filter, 'call', _71 => _71((l) => l.type === "pixel"), 'access', _72 => _72.pop, 'call', _73 => _73(), 'optionalAccess', _74 => _74.id]), () => ( null));
   const wetEvents = Array.isArray(r.wetEvents) ? r.wetEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.clock) && typeof e.kind === "string") : [];
@@ -1689,7 +1689,7 @@ async function deserializePaintDocumentAsync(raw, store) {
   if (!raw || typeof raw !== "object") throw new Error("Not a paint document: expected a JSON object.");
   const r = raw;
   const problems = [];
-  const assets = await _chunkQCEQIRJQcjs.resolveExternalAssets.call(void 0, _nullishCoalesce(r.assets, () => ( {})), store, problems);
+  const assets = await _chunkPI45JMP7cjs.resolveExternalAssets.call(void 0, _nullishCoalesce(r.assets, () => ( {})), store, problems);
   const loaded = deserializePaintDocument({ ...r, assets });
   return { ...loaded, problems: [...problems, ...loaded.problems] };
 }
@@ -5301,7 +5301,7 @@ var PaintEditorController = (_class10 = class _PaintEditorController {
       return next.type === "group" ? { ...next, children: toStandard(next.children) } : next;
     });
     const layers = toStandard(dried);
-    const result = _chunkQCEQIRJQcjs.exportPsd.call(void 0, { width, height, layers: [paperLayer, ...layers], merged, resolution: dpi });
+    const result = _chunkPI45JMP7cjs.exportPsd.call(void 0, { width, height, layers: [paperLayer, ...layers], merged, resolution: dpi });
     for (const [mode, names] of changed) {
       const label = _nullishCoalesce(_optionalChain([_chunkCWM3CUUXcjs.BLEND_MODES, 'access', _268 => _268.find, 'call', _269 => _269((m) => m.id === mode), 'optionalAccess', _270 => _270.label]), () => ( mode));
       const std = _nullishCoalesce(_optionalChain([_chunkCWM3CUUXcjs.BLEND_MODES, 'access', _271 => _271.find, 'call', _272 => _272((m) => m.id === _chunkCWM3CUUXcjs.standardBlendMode.call(void 0, mode)), 'optionalAccess', _273 => _273.label]), () => ( _chunkCWM3CUUXcjs.standardBlendMode.call(void 0, mode)));
@@ -5844,7 +5844,7 @@ function resampleInto(src, rect, width, height) {
 }
 
 // src/paint-editor/presence.ts
-var PaintPresence = class extends _chunkUJGAA6AKcjs.PresenceStore {
+var PaintPresence = class extends _chunkSWTUM32Hcjs.PresenceStore {
 };
 var FRAME = 16;
 function strokeSchedule(points) {
@@ -5888,8 +5888,8 @@ var PaintDirector = class {
     this.controller = controller;
     this.presence = presence;
     this.options = options;
-    this.clock = _nullishCoalesce(options.clock, () => ( _chunkUJGAA6AKcjs.realPresenceClock));
-    this.queue = new (0, _chunkUJGAA6AKcjs.PerformanceQueue)(presence, { clock: this.clock, linger: options.linger });
+    this.clock = _nullishCoalesce(options.clock, () => ( _chunkSWTUM32Hcjs.realPresenceClock));
+    this.queue = new (0, _chunkSWTUM32Hcjs.PerformanceQueue)(presence, { clock: this.clock, linger: options.linger });
   }
   
   
@@ -5924,7 +5924,7 @@ var PaintDirector = class {
       this.presence.set({ id, x: to.x, y: to.y });
       return;
     }
-    await _chunkUJGAA6AKcjs.tweenPresenceCursor.call(void 0, this.presence, this.clock, id, this.where(id), to, this.ms(ms));
+    await _chunkSWTUM32Hcjs.tweenPresenceCursor.call(void 0, this.presence, this.clock, id, this.where(id), to, this.ms(ms));
   }
   async say(id, text, ms) {
     if (!text) return;
@@ -5954,7 +5954,7 @@ var PaintDirector = class {
         await this.glide(id, path[0]);
         this.presence.set({ id, pressed: true });
         try {
-          for (let i = 1; i < path.length; i++) await _chunkUJGAA6AKcjs.tweenPresenceCursor.call(void 0, this.presence, this.clock, id, path[i - 1], path[i], this.ms(i % 2 ? 260 : 90));
+          for (let i = 1; i < path.length; i++) await _chunkSWTUM32Hcjs.tweenPresenceCursor.call(void 0, this.presence, this.clock, id, path[i - 1], path[i], this.ms(i % 2 ? 260 : 90));
         } finally {
           this.presence.set({ id, pressed: false });
         }