@pixerate/editor 0.106.0 → 0.108.0

package/dist/paint-editor/index.js

@@ -4,7 +4,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-4X5MIVCE.js";
+} from "../chunk-SOROZ2BF.js";
 import {
   RasterCompositor,
   bytesToBase64,
@@ -17,7 +17,7 @@ import {
   mapLayer,
   parseDataUrl,
   pngDataUrl
-} from "../chunk-67FRIOPZ.js";
+} from "../chunk-G4BIYE6R.js";
 import "../chunk-GX332W2C.js";
 import {
   CoverageMap,
@@ -35,9 +35,10 @@ import {
   normalizeBrush,
   normalizeMixer,
   rasterizeDab
-} from "../chunk-DS7KDKPX.js";
+} from "../chunk-3PHA3UKI.js";
 import {
   BLEND_MODES,
+  PAINTERLY_BLEND_MODES,
   TILE,
   TiledSurface,
   contentBounds,
@@ -45,12 +46,20 @@ import {
   fillRect,
   finishTile,
   isBlendMode,
+  isPainterlyBlendMode,
   readPixel,
   readRegion,
+  standardBlendMode,
   surfaceFromPixels,
   tileKey,
   tilesInRect
-} from "../chunk-HEW6KDNI.js";
+} from "../chunk-WMBIJCHA.js";
+import {
+  PerformanceQueue,
+  PresenceStore,
+  realPresenceClock,
+  tweenPresenceCursor
+} from "../chunk-B6DSIEXA.js";
 import "../chunk-KKREERP2.js";
 
 // src/paint-editor/noise.ts
@@ -2713,6 +2722,7 @@ var PaintEditorController = class {
     else this.emit([]);
     return result;
   }
+  /** Checks stroke samples (finite x and y, pressure 0..1) and returns them; throws a sentence naming the bad point. */
   checkPoints(points) {
     if (!Array.isArray(points) || !points.length) throw new PaintEditorError("points is empty; give at least one {x, y} in document pixels.");
     const out = [];
@@ -2936,9 +2946,22 @@ var PaintEditorController = class {
       offset: { x: 0, y: 0 }
     };
     const merged = this.compositePixels({ paper: true }).data;
-    const result = exportPsd({ width, height, layers: [paperLayer, ...this.doc.layers], merged, resolution: dpi });
-    const pigment = flattenLayers(this.doc.layers).filter((l) => l.blend === "pigment");
-    if (pigment.length) result.warnings.push(`Pigment blending has no PSD equivalent; ${pigment.map((l) => `"${l.name}"`).join(", ")} ${pigment.length === 1 ? "was" : "were"} written as Normal, so ${pigment.length === 1 ? "it looks" : "they look"} different in Photoshop.`);
+    const changed = /* @__PURE__ */ new Map();
+    const toStandard = (layers2) => layers2.map((l) => {
+      const blend = l.blend === "pass-through" ? l.blend : standardBlendMode(l.blend);
+      if (blend !== l.blend) changed.set(l.blend, [...changed.get(l.blend) ?? [], l.name]);
+      const next = blend === l.blend ? l : { ...l, blend };
+      return next.type === "group" ? { ...next, children: toStandard(next.children) } : next;
+    });
+    const layers = toStandard(this.doc.layers);
+    const result = exportPsd({ width, height, layers: [paperLayer, ...layers], merged, resolution: dpi });
+    for (const [mode, names] of changed) {
+      const label = BLEND_MODES.find((m) => m.id === mode)?.label ?? mode;
+      const std = BLEND_MODES.find((m) => m.id === standardBlendMode(mode))?.label ?? standardBlendMode(mode);
+      const list = names.map((n) => `"${n}"`).join(", ");
+      const one = names.length === 1;
+      result.warnings.push(`${label} blending has no PSD equivalent; ${list} ${one ? "was" : "were"} written as ${std}, the nearest Photoshop mode, so ${one ? "it looks" : "they look"} different in Photoshop (the merged image is exact).`);
+    }
     return result;
   }
   /** `render_preview` as a base64 PNG. */
@@ -3234,6 +3257,169 @@ function resampleInto(src, rect, width, height) {
   return { width, height, data: out };
 }
 
+// src/paint-editor/presence.ts
+var PaintPresence = class extends PresenceStore {
+};
+var FRAME = 16;
+function strokeSchedule(points) {
+  if (points.length < 2) return points.map(() => 1);
+  const t0 = points[0].t;
+  const t1 = points[points.length - 1].t;
+  if (points.every((p) => Number.isFinite(p.t)) && t1 > t0) {
+    return points.map((p) => Math.min(1, Math.max(0, (p.t - t0) / (t1 - t0))));
+  }
+  const acc = [0];
+  for (let i = 1; i < points.length; i++) acc.push(acc[i - 1] + Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y));
+  const total = acc[acc.length - 1];
+  return total > 0 ? acc.map((d) => d / total) : points.map(() => 1);
+}
+function strokeDuration(points, max = 1800) {
+  const t0 = points[0]?.t;
+  const t1 = points[points.length - 1]?.t;
+  let ms;
+  if (points.every((p) => Number.isFinite(p.t)) && t1 > t0) ms = t1 - t0;
+  else {
+    let length = 0;
+    for (let i = 1; i < points.length; i++) length += Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
+    ms = length / 1.5;
+  }
+  return Math.min(max, Math.max(250, ms));
+}
+function sweepPath(rect, rows = 4) {
+  const inset = Math.min(rect.width, rect.height) * 0.08;
+  const left = rect.x + inset;
+  const right = rect.x + rect.width - inset;
+  const out = [];
+  for (let r = 0; r < rows; r++) {
+    const y = rect.y + inset + (rect.height - 2 * inset) * (r + 0.5) / rows;
+    out.push(r % 2 ? { x: right, y } : { x: left, y }, r % 2 ? { x: left, y } : { x: right, y });
+  }
+  return out;
+}
+var centre = (r) => ({ x: r.x + r.width / 2, y: r.y + r.height / 2 });
+var PaintDirector = class {
+  constructor(controller, presence, options = {}) {
+    this.controller = controller;
+    this.presence = presence;
+    this.options = options;
+    this.clock = options.clock ?? realPresenceClock;
+    this.queue = new PerformanceQueue(presence, { clock: this.clock, linger: options.linger });
+  }
+  controller;
+  presence;
+  options;
+  clock;
+  queue;
+  /** Acts out `commands` in order for `actor`. Resolves with one result per command. */
+  perform(actor, commands) {
+    return this.queue.run(actor, async () => {
+      const results = [];
+      for (const command of commands) {
+        try {
+          results.push({ ok: true, command, result: await this.performOne(actor.id, command) });
+        } catch (error) {
+          results.push({ ok: false, command, message: error instanceof Error ? error.message : String(error) });
+        }
+      }
+      return results;
+    });
+  }
+  ms(n) {
+    return Math.round(n / Math.max(0.1, this.options.speed ?? 1));
+  }
+  where(id) {
+    const a = this.presence.get(id);
+    return { x: a?.x ?? 0, y: a?.y ?? 0 };
+  }
+  /** Glides to `to`; an actor that just appeared starts there instead of the corner. */
+  async glide(id, to, ms = 380) {
+    const a = this.presence.get(id);
+    if (!a || a.x === 0 && a.y === 0) {
+      this.presence.set({ id, x: to.x, y: to.y });
+      return;
+    }
+    await tweenPresenceCursor(this.presence, this.clock, id, this.where(id), to, this.ms(ms));
+  }
+  async say(id, text, ms) {
+    if (!text) return;
+    this.presence.set({ id, message: text });
+    await this.clock.wait(this.ms(ms));
+  }
+  async performOne(id, command) {
+    const c = this.controller;
+    switch (command.kind) {
+      case "say":
+        await this.say(id, command.text, 900);
+        return void 0;
+      case "point":
+        await this.say(id, command.note, 500);
+        await this.glide(id, command.at);
+        this.presence.set({ id, pressed: true });
+        await this.clock.wait(this.ms(110));
+        this.presence.set({ id, pressed: false });
+        return void 0;
+      case "stroke":
+        await this.say(id, command.note, 500);
+        return this.stroke(id, command.stroke);
+      case "fill": {
+        await this.say(id, command.note, 500);
+        const { width, height } = c.getState().document.canvas;
+        const path = sweepPath({ x: 0, y: 0, width, height });
+        await this.glide(id, path[0]);
+        this.presence.set({ id, pressed: true });
+        try {
+          for (let i = 1; i < path.length; i++) await tweenPresenceCursor(this.presence, this.clock, id, path[i - 1], path[i], this.ms(i % 2 ? 260 : 90));
+        } finally {
+          this.presence.set({ id, pressed: false });
+        }
+        return c.fillLayer(command.fill);
+      }
+      case "replay": {
+        await this.say(id, command.note, 500);
+        const source = c.getStrokes().filter((s) => command.replay.strokeIds?.includes(s.id));
+        const first = source[0]?.points[0];
+        if (first) await this.glide(id, first);
+        const result = c.replayStrokes(command.replay);
+        if (result.bounds) await this.glide(id, centre(result.bounds), 520);
+        return result;
+      }
+    }
+  }
+  /** Paints a stroke live: begins it, pushes its points frame by frame as the cursor reaches them, then ends it (one undo step). */
+  async stroke(id, init) {
+    const c = this.controller;
+    const points = c.checkPoints(init.points);
+    const { points: _points, ...rest } = init;
+    const session = c.beginStroke({ snapToPerspective: false, start: points[0], ...rest });
+    try {
+      await this.glide(id, points[0]);
+      this.presence.set({ id, pressed: true });
+      const at = strokeSchedule(points);
+      const duration = this.ms(strokeDuration(points, this.options.maxStrokeMs));
+      let next = 0;
+      const frames = Math.max(1, Math.round(duration / FRAME));
+      for (let f = 1; f <= frames; f++) {
+        const t = f / frames;
+        const from = next;
+        while (next < points.length && at[next] <= t + 1e-9) next++;
+        if (next > from) {
+          session.push(points.slice(from, next));
+          const p = points[next - 1];
+          this.presence.set({ id, x: p.x, y: p.y });
+        }
+        if (f < frames) await this.clock.wait(duration / frames);
+      }
+      if (next < points.length) session.push(points.slice(next));
+      this.presence.set({ id, pressed: false });
+      return session.end();
+    } catch (error) {
+      if (c.activeStroke === session) session.cancel();
+      this.presence.set({ id, pressed: false });
+      throw error;
+    }
+  }
+};
+
 // src/paint-editor/guide-tools.ts
 var READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
@@ -3585,7 +3771,11 @@ var TIP = {
     smoothing: { type: "number", minimum: 0, maximum: 0.95, description: "Position smoothing of the input, 0..0.95." },
     pressureSize: { type: "boolean", description: "Pressure scales the size (down to dynamics.minSize)." },
     pressureOpacity: { type: "boolean", description: "Pressure scales the opacity." },
-    blend: { type: "string", enum: BLEND_MODES.map((m) => m.id), description: "How paint combines with the layer. pigment mixes it in like real paint (blue into yellow gives green); multiply darkens like marker ink." }
+    blend: {
+      type: "string",
+      enum: BLEND_MODES.map((m) => m.id),
+      description: "How paint combines with the layer. pigment mixes it in like real paint (blue into yellow gives green); multiply darkens like marker ink; watercolor glazes like a transparent wash; tint, highlight and shadow recolour, light and shade (see list_blend_modes)."
+    }
   },
   additionalProperties: false
 };
@@ -3665,6 +3855,12 @@ function createPaintEditorToolProvider(controller, options = {}) {
   const c = controller;
   const tools = [];
   const add = (t) => tools.push(t);
+  const act = async (command, direct) => {
+    if (!options.director) return direct();
+    const [r] = await options.director.perform(options.actor ?? { id: "agent", name: "Agent" }, [command]);
+    if (!r || !r.ok) throw new Error(r && !r.ok ? r.message : "The director did not run the command.");
+    return r.result;
+  };
   add({
     name: "get_canvas_info",
     title: "Get the canvas",
@@ -3820,7 +4016,11 @@ function createPaintEditorToolProvider(controller, options = {}) {
         name: { type: "string", minLength: 1, description: "New name." },
         visible: { type: "boolean", description: "Show or hide." },
         opacity: { type: "number", minimum: 0, maximum: 1, description: "Layer opacity 0..1." },
-        blend: { type: "string", enum: [...BLEND_MODES.map((m) => m.id), "pass-through"], description: "Blend mode (pass-through for groups only)." },
+        blend: {
+          type: "string",
+          enum: [...BLEND_MODES.map((m) => m.id), "pass-through"],
+          description: "Blend mode (pass-through for groups only). Painterly modes: watercolor (the layer glazes like a transparent wash), tint (recolours keeping lightness), highlight (adds soft coloured light), shadow (shades with ambient fill); see list_blend_modes."
+        },
         clipped: { type: "boolean", description: "Clip to the layer below (paint only shows where it has paint)." },
         locks: {
           type: "object",
@@ -3840,6 +4040,22 @@ function createPaintEditorToolProvider(controller, options = {}) {
     annotations: { title: "Change a layer", ...SET2 },
     handler: ({ layerId, ...u }) => c.updateLayer(layerId, u)
   });
+  add({
+    name: "list_blend_modes",
+    title: "List blend modes",
+    description: "Lists every layer and brush blend mode: id, label, group (standard Photoshop modes, pigment, or painterly), what the pigment and painterly modes do, and the standard mode PSD export writes in their place. Changes nothing. Read it before choosing a painterly mode for update_layer or a brush tip.",
+    inputSchema: EMPTY2,
+    annotations: { title: "List blend modes", ...READ2 },
+    handler: () => ({
+      modes: BLEND_MODES.map((m) => ({
+        id: m.id,
+        label: m.label,
+        group: m.painterly ? "painterly" : m.id === "pigment" ? "pigment" : "standard",
+        ...m.description ? { description: m.description } : {},
+        psd: standardBlendMode(m.id)
+      }))
+    })
+  });
   add({
     name: "set_active_layer",
     title: "Choose the active layer",
@@ -3904,12 +4120,12 @@ function createPaintEditorToolProvider(controller, options = {}) {
         opacity: { type: "number", minimum: 0, maximum: 1, description: "Opacity 0..1 (default 1)." },
         grain: { type: "number", minimum: 0, maximum: 1, description: "Paper grain response 0..1 (default 0: flat)." },
         pressure: { type: "number", minimum: 0, maximum: 1, description: "With grain: how far into the valleys, 0..1 (default 0.5)." },
-        blend: { type: "string", enum: BLEND_MODES.map((m) => m.id), description: "Blend mode (default normal; pigment mixes like paint)." }
+        blend: { type: "string", enum: BLEND_MODES.map((m) => m.id), description: "Blend mode (default normal; pigment mixes like paint, watercolor glazes; see list_blend_modes)." }
       },
       additionalProperties: false
     },
     annotations: { title: "Fill a layer", ...WRITE2 },
-    handler: (a) => c.fillLayer(a)
+    handler: (a) => act({ kind: "fill", fill: a }, () => c.fillLayer(a))
   });
   add({
     name: "clear_layer",
@@ -4092,7 +4308,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "paint_stroke",
     title: "Paint a brush stroke",
-    description: "Paints one stroke through points (document pixels, with optional pressure, time, tilt and barrel rotation) on a pixel layer with a library brush or the active one, optionally changed for this stroke. Grain-responsive brushes follow the paper; the mixer engine (mixer-brush, blender, smudge) picks up and moves paint already on the layer. The symmetry guide adds its mirror copies; with a tracing image that samples colours, a stroke without color takes the image colour at its first point. One undo step. Returns the layer id, changed bounds, dab count, the recorded strokeId (for replay_strokes) and, for the mixer, its load after the stroke.",
+    description: "Paints one stroke through points (document pixels, with optional pressure, time, tilt and barrel rotation) on a pixel layer with a library brush or the active one, optionally changed for this stroke. Grain-responsive brushes follow the paper; the mixer engine (mixer-brush, blender, smudge) picks up and moves paint already on the layer. The symmetry guide adds its mirror copies; with a tracing image that samples colours, a stroke without color takes the image colour at its first point. With an agent cursor (a director), the stroke is painted live along the points at the pace of their times. One undo step. Returns the layer id, changed bounds, dab count, the recorded strokeId (for replay_strokes) and, for the mixer, its load after the stroke.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4108,8 +4324,9 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Paint a brush stroke", ...WRITE2 },
-    handler: (a) => {
-      const r = c.paintStroke({ points: a.points, layerId: a.layerId, brushId: a.brushId, brush: a.brush, color: a.color, seed: a.seed, snapToPerspective: a.snapToPerspective });
+    handler: async (a) => {
+      const stroke = { points: a.points, layerId: a.layerId, brushId: a.brushId, brush: a.brush, color: a.color, seed: a.seed, snapToPerspective: a.snapToPerspective };
+      const r = await act({ kind: "stroke", stroke }, () => c.paintStroke(stroke));
       return r.mixerLoad ? { ...r, mixerLoad: loadResult(r.mixerLoad) } : r;
     }
   });
@@ -4183,7 +4400,10 @@ function createPaintEditorToolProvider(controller, options = {}) {
       additionalProperties: false
     },
     annotations: { title: "Replay strokes, varied", ...WRITE2 },
-    handler: (a) => c.replayStrokes(a)
+    handler: (a) => {
+      const replay = a;
+      return act({ kind: "replay", replay }, () => c.replayStrokes(replay));
+    }
   });
   add({
     name: "set_view",
@@ -4282,7 +4502,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "export_psd",
     title: "Export as PSD",
-    description: 'Writes the painting as an 8-bit RGB PSD (PSB above 30000 px) through the shared PSD writer: every layer and group with its opacity, blend, mask and locks, the paper as a locked "Paper" pixel layer at the bottom, and the composite as the merged image. Changes nothing. Returns the file as base64, its size, whether it is a PSB, and warnings (pigment blending has no PSD equivalent).',
+    description: 'Writes the painting as an 8-bit RGB PSD (PSB above 30000 px) through the shared PSD writer: every layer and group with its opacity, blend, mask and locks, the paper as a locked "Paper" pixel layer at the bottom, and the composite as the merged image. Changes nothing. Returns the file as base64, its size, whether it is a PSB, and warnings (pigment and painterly blend modes have no PSD equivalent: they are written as the nearest standard mode, see list_blend_modes).',
     inputSchema: EMPTY2,
     annotations: { title: "Export as PSD", ...READ2 },
     handler: () => {
@@ -4591,7 +4811,12 @@ function wheelPick(dx, dy, wheel, color) {
   const [nr, ng, nb] = hsvToRgb(wheelToHue(wheelAngle(dx, dy), wheel), s || 1, v || 1);
   return rgbToHexColor(nr, ng, nb);
 }
+var BLEND_MENU_GROUPS = [
+  { label: "Standard", modes: BLEND_MODES.filter((m) => !m.painterly && m.id !== "pigment") },
+  { label: "Paint", modes: BLEND_MODES.filter((m) => m.painterly || m.id === "pigment") }
+];
 export {
+  BLEND_MENU_GROUPS,
   BLEND_MODES,
   BRUSH_ID,
   BRUSH_ROTATIONS,
@@ -4619,6 +4844,7 @@ export {
   MIXING_PAD_HEIGHT,
   MIXING_PAD_WIDTH,
   MixingPad,
+  PAINTERLY_BLEND_MODES,
   PAINT_BRUSH_CATEGORIES,
   PAINT_BRUSH_ENGINES,
   PAINT_FORMAT,
@@ -4629,10 +4855,12 @@ export {
   PAPER_NODE_ID,
   PAPER_SLIDERS,
   PaintCanvasPresenter,
+  PaintDirector,
   PaintDocumentError,
   PaintEditorController,
   PaintEditorError,
   PaintGesture,
+  PaintPresence,
   PaintStrokeSession,
   PaperGrain,
   PenDabWalker,
@@ -4673,6 +4901,7 @@ export {
   hueToWheel,
   invertAffine,
   isBlendMode,
+  isPainterlyBlendMode,
   isPalmTouch,
   mapPenPoint,
   mix32,
@@ -4713,7 +4942,11 @@ export {
   seedFromString,
   serializePaintDocument,
   serializePaintDocumentExternal,
+  standardBlendMode,
   strokeBounds,
+  strokeDuration,
+  strokeSchedule,
+  sweepPath,
   symmetryAxisAngles,
   symmetryAxisSegments,
   symmetryCopies,