@pixerate/editor 0.255.0 → 0.256.0

package/dist/paint-editor/index.js

@@ -370,8 +370,8 @@ function normalizePaper(raw = {}, base) {
     ...readOffset(r.offset, b.offset)
   };
 }
-function hexToRgb8(hex) {
-  const n = parseInt(hex.slice(1, 7), 16);
+function hexToRgb8(hex2) {
+  const n = parseInt(hex2.slice(1, 7), 16);
   return [n >> 16 & 255, n >> 8 & 255, n & 255];
 }
 function renderPaper(paper, rect, grain = new PaperGrain(paper), light) {
@@ -1929,8 +1929,8 @@ function sampleArt(art, x, y, out) {
 }
 
 // src/paint-editor/stickers.ts
-function hexRgb(hex) {
-  const n = parseInt(hex.slice(1, 7), 16);
+function hexRgb(hex2) {
+  const n = parseInt(hex2.slice(1, 7), 16);
   return [(n >> 16 & 255) / 255, (n >> 8 & 255) / 255, (n & 255) / 255];
 }
 function stickerRect(s) {
@@ -2014,8 +2014,8 @@ function drawArtSticker(medium, s, art) {
   medium.deposit(rect, cov, s.opacity, [r, g, b], null, field);
   return rect;
 }
-function jitterColor(hex, amount, seed, i) {
-  const [r, g, b] = hexRgb(hex);
+function jitterColor(hex2, amount, seed, i) {
+  const [r, g, b] = hexRgb(hex2);
   const lch = oklabToOklch(rgbToOklab({ r, g, b, a: 1 }));
   const l = Math.min(1, Math.max(0, lch.l + (rand01(seed, i, 61) - 0.5) * amount * 0.3));
   const h = lch.h + (rand01(seed, i, 63) - 0.5) * amount * 80;
@@ -2897,7 +2897,7 @@ var PaintStrokeSession = class _PaintStrokeSession {
     const init = this.init;
     const grey = Math.round(init.brush.light.amount * 255);
     const g = grey / 255;
-    const hex = "#" + grey.toString(16).padStart(2, "0").repeat(3);
+    const hex2 = "#" + grey.toString(16).padStart(2, "0").repeat(3);
     const host = {
       update: () => {
       },
@@ -2906,14 +2906,14 @@ var PaintStrokeSession = class _PaintStrokeSession {
       }
     };
     const effect = init.effect ? { source: init.effect.source, pixels: { ...init.effect.pixels, data: greyPixels(init.effect.pixels.data, grey) } } : null;
-    const paint = init.paint ? { ...init.paint, stops: init.paint.stops.map((st) => ({ ...st, color: hex })) } : null;
+    const paint = init.paint ? { ...init.paint, stops: init.paint.stops.map((st) => ({ ...st, color: hex2 })) } : null;
     return new _PaintStrokeSession(host, {
       ...init,
       surface: lightToShadow(light),
       lockTransparency: false,
       brush: lightTwinBrush(init.brush),
       color: [grey, grey, grey, 255],
-      colorHex: hex,
+      colorHex: hex2,
       secondary: [grey, grey, grey, 255],
       inputFilter: void 0,
       mixerLoad: { reservoir: init.mixerLoad.reservoir ? [g, g, g] : null, amount: init.mixerLoad.amount, pickup: null },
@@ -4461,8 +4461,8 @@ var PaintWetLayers = class {
     this.gpu = null;
   }
 };
-function wetPigmentOf(hex, body) {
-  const [r, g, b] = hexToRgb8(hex);
+function wetPigmentOf(hex2, body) {
+  const [r, g, b] = hexToRgb8(hex2);
   return Array.from(pigmentOf([r / 255, g / 255, b / 255], body));
 }
 
@@ -4934,8 +4934,8 @@ var MixingPad = class {
       A += a;
     }
     if (A === 0) return null;
-    const hex = (v) => Math.round(v / A).toString(16).padStart(2, "0");
-    return `#${hex(R)}${hex(G)}${hex(B)}`;
+    const hex2 = (v) => Math.round(v / A).toString(16).padStart(2, "0");
+    return `#${hex2(R)}${hex2(G)}${hex2(B)}`;
   }
   clear() {
     this.surface = emptySurface(4);
@@ -4996,8 +4996,8 @@ var MixingPad = class {
       paints2.map((p) => p.parts)
     );
     const core = normalizePaintBrush({ tip: { ...PAD_BLOB.tip, size: R * 1.1, hardness: 0.55 } }, PAD_BLOB);
-    const hex = "#" + mixed.map((v) => Math.round(v * 255).toString(16).padStart(2, "0")).join("");
-    this.run(core, [{ x: cx, y: cy }], hex);
+    const hex2 = "#" + mixed.map((v) => Math.round(v * 255).toString(16).padStart(2, "0")).join("");
+    this.run(core, [{ x: cx, y: cy }], hex2);
     return { color: this.pick(cx, cy, 2), bounds };
   }
   /** The pad's pixels as a PNG data URL (with alpha), for saving. */
@@ -5699,8 +5699,8 @@ function parseColor(value, what = "color") {
   if (typeof value !== "string" || !HEX3.test(value.trim())) throw new PaintEditorError(`${what} is ${JSON.stringify(value)}; use #rrggbb, e.g. "#2a4b8d".`);
   return value.trim().toLowerCase();
 }
-function rgbaOf(hex) {
-  const [r, g, b] = hexToRgb8(hex);
+function rgbaOf(hex2) {
+  const [r, g, b] = hexToRgb8(hex2);
   return [r, g, b, 255];
 }
 function rgbToHex(r, g, b) {
@@ -5753,6 +5753,13 @@ var PaintEditorController = class _PaintEditorController {
   stickerPreview = null;
   encodeImage;
   listeners = /* @__PURE__ */ new Set();
+  commitListeners = /* @__PURE__ */ new Set();
+  /** Origins set by `withOrigin`, innermost last. */
+  origins = [];
+  /** `group` in progress: commits fold into one step, recorded when it ends. */
+  grouping = null;
+  /** `previewPaint` in progress: nothing is emitted or recorded. */
+  previewing = false;
   version = 0;
   cached = null;
   session = null;
@@ -5860,7 +5867,125 @@ var PaintEditorController = class _PaintEditorController {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
   }
+  /** Hears each undo step recorded, merged, undone or redone, with who made it. Returns an unsubscribe function. */
+  onCommit(listener) {
+    this.commitListeners.add(listener);
+    return () => {
+      this.commitListeners.delete(listener);
+    };
+  }
+  notifyCommit(event) {
+    if (this.previewing) return;
+    for (const l of [...this.commitListeners]) l(event);
+  }
+  /** The origin steps are recorded with now: the innermost `withOrigin`, else `user`. */
+  getOrigin() {
+    return this.origins[this.origins.length - 1] ?? "user";
+  }
+  /**
+   * Records the steps `fn` makes as made by `origin` (`agent:<id>` for an agent). When `fn` returns
+   * a promise, the origin holds until it settles. Satisfies `createOriginMiddleware`'s history target,
+   * so agent tool calls are recorded as the calling agent's.
+   */
+  withOrigin(origin, fn) {
+    this.origins.push(origin);
+    let pending = false;
+    const pop = () => {
+      const i = this.origins.lastIndexOf(origin);
+      if (i >= 0) this.origins.splice(i, 1);
+    };
+    try {
+      const result = fn();
+      if (result && typeof result.then === "function") {
+        pending = true;
+        return Promise.resolve(result).finally(pop);
+      }
+      return result;
+    } finally {
+      if (!pending) pop();
+    }
+  }
+  /**
+   * Runs `fn` as one undo step named `label`: every change it makes (strokes, fills, new layers) is
+   * undone together. Wet paint can't be grouped. Nested groups join the outer one. If `fn` throws,
+   * its changes are put back and nothing is recorded.
+   */
+  group(label, fn) {
+    if (this.grouping) return fn();
+    this.requireIdle("grouping changes");
+    const before = this.doc;
+    const revision = this.docRevision;
+    this.grouping = { label, before, changed: false };
+    let result;
+    try {
+      result = fn();
+    } catch (e) {
+      this.grouping = null;
+      if (this.doc !== before) {
+        this.doc = before;
+        this.docRevision = revision + 1;
+        this.emit();
+      }
+      throw e;
+    }
+    const g = this.grouping;
+    this.grouping = null;
+    if (g.changed && this.doc !== before) {
+      this.undoStack.push({ label, origin: this.getOrigin(), before, after: this.doc });
+      if (this.undoStack.length > this.historyLimit) this.undoStack.shift();
+      this.redoStack = [];
+      this.notifyCommit({ kind: "execute", label, origin: this.getOrigin() });
+      this.emit();
+    }
+    return result;
+  }
+  /**
+   * What `fn` would paint, without changing anything: it runs on a new empty layer (above the
+   * active layer, another one, or at the bottom), and the layer's pixels and the picture with them
+   * come back while the document, history and listeners stay as they were. `fn` gets that layer's id and must paint on it with dry brushes (strokes, replays and
+   * fills); wet paint can't be previewed. For ghost paint an agent suggests (`createPaintProposals`).
+   */
+  previewPaint(fn, placement = {}) {
+    this.requireIdle("previewing");
+    if (this.previewing) throw new PaintEditorError("A preview is already running.");
+    const saved = {
+      doc: this.doc,
+      undo: [...this.undoStack],
+      redo: this.redoStack,
+      revision: this.docRevision,
+      strokeCounter: this.strokeCounter,
+      seedCounter: this.seedCounter,
+      mixerLoad: this.mixerLoad
+    };
+    this.previewing = true;
+    try {
+      const layer = this.addLayer({ name: "Preview", ...placement.aboveId ? { aboveId: placement.aboveId } : {} });
+      if (placement.bottom) this.moveLayer(layer.id, 0, null);
+      fn(layer.id);
+      if (this.wetOp || this.pendingWetEvents.length) throw new PaintEditorError("Wet paint can't be previewed; suggest it with a dry brush.");
+      const found = findLayer(this.doc.layers, layer.id)?.layer;
+      const surface = found && isPixelLayer(found) ? found.surface : null;
+      const bounds = surface ? contentBounds(surface) : null;
+      const box = bounds ? clipToCanvas(bounds, this.doc.canvas) : null;
+      if (!surface || !box) return { bounds: null, pixels: new Uint8ClampedArray(0), composite: new Uint8ClampedArray(0) };
+      const composite = this.exportCompositor.composite(this.renderLayers({ wet: "display" }), box, this.sources());
+      return { bounds: box, pixels: readRegion(surface, box), composite };
+    } finally {
+      this.wetOp = null;
+      this.pendingWetEvents = [];
+      this.doc = saved.doc;
+      this.undoStack = saved.undo;
+      this.redoStack = saved.redo;
+      this.docRevision = saved.revision;
+      this.strokeCounter = saved.strokeCounter;
+      this.seedCounter = saved.seedCounter;
+      this.mixerLoad = saved.mixerLoad;
+      this.cached = null;
+      this.previewing = false;
+    }
+  }
   emit(dirty = "all") {
+    if (this.previewing) return;
     if (dirty === "all" || this.dirty === "all") this.dirty = "all";
     else this.dirty.push(...dirty);
     this.version++;
@@ -5943,7 +6068,13 @@ var PaintEditorController = class _PaintEditorController {
     if (this.session) throw new PaintEditorError(`A stroke is in progress; end or cancel it before ${what}.`);
   }
   commit(label, next, before = this.doc) {
-    const entry = { label, before, after: next };
+    if (this.grouping) {
+      this.grouping.changed = true;
+      this.doc = next;
+      this.docRevision++;
+      return;
+    }
+    const entry = { label, origin: this.getOrigin(), before, after: next };
     if (this.wetOp) {
       entry.wet = { before: this.wetOp.before, after: this.wet.snapshot(), lost: false };
       this.wetOp = null;
@@ -5954,6 +6085,7 @@ var PaintEditorController = class _PaintEditorController {
     this.doc = next;
     this.docRevision++;
     this.trimWetHistory();
+    this.notifyCommit({ kind: "execute", label, origin: entry.origin });
     this.emit();
   }
   /**
@@ -5962,7 +6094,7 @@ var PaintEditorController = class _PaintEditorController {
    */
   commitOrAmend(label, next, commitToHistory) {
     const last = this.undoStack[this.undoStack.length - 1];
-    if (commitToHistory || !last || last.label !== label || last.wet || this.wetOp) {
+    if (commitToHistory || !last || last.label !== label || last.wet || this.wetOp || this.grouping) {
       this.commit(label, next);
       return;
     }
@@ -5970,6 +6102,7 @@ var PaintEditorController = class _PaintEditorController {
     this.redoStack = [];
     this.doc = next;
     this.docRevision++;
+    this.notifyCommit({ kind: "merge", label, origin: last.origin });
     this.emit();
   }
   /** Keeps the wet snapshots in history within the wet undo memory, dropping the oldest. */
@@ -6039,6 +6172,7 @@ var PaintEditorController = class _PaintEditorController {
       this.wet.restore(e.wet.lost ? null : e.wet.before);
       if (paper !== this.doc.paper) this.wet.paperChanged();
     }
+    this.notifyCommit({ kind: "undo", label: e.label, origin: this.getOrigin() });
     this.emit();
     return e.label;
   }
@@ -6057,6 +6191,7 @@ var PaintEditorController = class _PaintEditorController {
       this.wet.restore(e.wet.lost ? null : e.wet.after);
       if (paper !== this.doc.paper) this.wet.paperChanged();
     }
+    this.notifyCommit({ kind: "redo", label: e.label, origin: this.getOrigin() });
     this.emit();
     return e.label;
   }
@@ -7263,6 +7398,7 @@ var PaintEditorController = class _PaintEditorController {
       return l;
     })();
     const brush = this.strokeBrush(init);
+    if (this.previewing && isWetBrush(brush)) throw new PaintEditorError(`Wet paint can't be previewed; the ${brush.name} brush paints wet media. Suggest it with a dry brush.`);
     const effect = this.strokeEffect(init, brush);
     if (brush.light.amount > 0) {
       if (brush.engine === "sticker") throw new PaintEditorError(`The ${brush.name} brush sprays stickers, which don't take light yet; paint light with a dab or particle light brush (glow-gel, neon-marker; list_brush_presets lists them), or set light.amount to 0 (set_brush).`);
@@ -9566,6 +9702,13 @@ function resampleInto(src, rect, width, height) {
   }
   return { width, height, data: out };
 }
+function clipToCanvas(rect, canvas) {
+  const x0 = Math.max(0, rect.x);
+  const y0 = Math.max(0, rect.y);
+  const x1 = Math.min(canvas.width, rect.x + rect.width);
+  const y1 = Math.min(canvas.height, rect.y + rect.height);
+  return x1 > x0 && y1 > y0 ? { x: x0, y: y0, width: x1 - x0, height: y1 - y0 } : null;
+}
 
 // src/paint-editor/presence.ts
 var PaintPresence = class extends PresenceStore {
@@ -10786,8 +10929,8 @@ var POINTS = {
   }
 };
 function loadResult(load) {
-  const hex = (c) => c ? "#" + c.map((v) => Math.round(Math.min(1, Math.max(0, v)) * 255).toString(16).padStart(2, "0")).join("") : null;
-  return { reservoir: hex(load.reservoir), amount: Math.round(load.amount * 1e3) / 1e3, pickup: hex(load.pickup) };
+  const hex2 = (c) => c ? "#" + c.map((v) => Math.round(Math.min(1, Math.max(0, v)) * 255).toString(16).padStart(2, "0")).join("") : null;
+  return { reservoir: hex2(load.reservoir), amount: Math.round(load.amount * 1e3) / 1e3, pickup: hex2(load.pickup) };
 }
 function createPaintEditorToolProvider(controller, options = {}) {
   const c = typeof controller === "function" ? lazyController(controller) : controller;
@@ -12405,6 +12548,392 @@ function createPaintEditorDocument(controller, options = {}) {
     readOnly: () => controller.busyReason() ?? false
   });
 }
+
+// src/paint-editor/collaboration.ts
+var LAYER_FIELDS = ["name", "visible", "opacity", "blend"];
+function createPaintChangeFeed(controller, options = {}) {
+  const now = options.now ?? (() => Date.now());
+  const listeners = /* @__PURE__ */ new Set();
+  let seq = 0;
+  let pending;
+  const take = () => {
+    const state = controller.getState();
+    const doc = state.document;
+    const layers = /* @__PURE__ */ new Map();
+    for (const l of controller.listLayers()) layers.set(l.id, { name: l.name, visible: l.visible, opacity: l.opacity, blend: l.blend });
+    return { doc, strokes: new Map(doc.strokes.map((s) => [s.id, s])), events: doc.paintEvents?.length ?? 0, layers, stroking: state.stroking };
+  };
+  let last = take();
+  const check = () => {
+    const state = controller.getState();
+    if (state.document === last.doc && state.stroking === last.stroking) return null;
+    const next = take();
+    const addedStrokes = [...next.strokes.values()].filter((s) => !last.strokes.has(s.id));
+    const removedStrokes = [...last.strokes.values()].filter((s) => !next.strokes.has(s.id));
+    const allEvents = state.document.paintEvents ?? [];
+    const events = next.events > last.events ? allEvents.slice(last.events) : [];
+    const addedLayers = [];
+    const changedLayers = [];
+    for (const [id, l] of next.layers) {
+      const before = last.layers.get(id);
+      if (!before) addedLayers.push({ id, name: String(l.name) });
+      else {
+        const fields = LAYER_FIELDS.filter((f) => before[f] !== l[f]);
+        if (fields.length) changedLayers.push({ id, name: String(l.name), fields });
+      }
+    }
+    const removedLayers = [...last.layers].filter(([id]) => !next.layers.has(id)).map(([id, l]) => ({ id, name: String(l.name) }));
+    const gestureStarted = next.stroking && !last.stroking;
+    const gestureEnded = !next.stroking && last.stroking;
+    last = next;
+    const edited = addedStrokes.length + removedStrokes.length + events.length + addedLayers.length + removedLayers.length + changedLayers.length > 0;
+    if (!edited && !gestureStarted && !gestureEnded) return null;
+    const commit = edited ? pending : void 0;
+    if (edited) pending = void 0;
+    const change = {
+      seq: ++seq,
+      origin: commit?.origin ?? "user",
+      ...commit ? { commit } : {},
+      addedStrokes,
+      removedStrokes,
+      events,
+      addedLayers,
+      removedLayers,
+      changedLayers,
+      inGesture: next.stroking,
+      ...gestureStarted ? { gestureStarted: true } : {},
+      ...gestureEnded ? { gestureEnded: true } : {},
+      at: now()
+    };
+    listeners.forEach((l) => l(change));
+    return change;
+  };
+  const offCommit = controller.onCommit((event) => {
+    pending = event;
+  });
+  const offState = controller.subscribe(() => {
+    check();
+  });
+  return {
+    check,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    reset() {
+      last = take();
+      pending = void 0;
+    },
+    dispose() {
+      offCommit();
+      offState();
+      listeners.clear();
+    }
+  };
+}
+var HEX4 = /^#[0-9a-f]{6}$/i;
+var DRY_ENGINES = /* @__PURE__ */ new Set(["dab", "particle", "bristle", "mixer"]);
+function suggestionBrushRefusal(brush) {
+  if (!DRY_ENGINES.has(brush.engine)) return `The ${brush.name} brush (${brush.engine}) can't paint a suggestion: suggestions are dry paint on a layer of their own. Use a dab, particle, bristle or mixer brush.`;
+  if (brush.behavior.pickup > 0) return `The ${brush.name} brush picks up paint, which a suggestion on its own layer can't; choose a brush without pickup.`;
+  return null;
+}
+function createPaintProposals(options) {
+  const { controller } = options;
+  const now = options.now ?? (() => Date.now());
+  const maxPoints = options.maxPoints ?? 4e3;
+  let seq = 0;
+  const makeId = options.idGenerator ?? (() => `paint-proposal-${++seq}`);
+  let state = { proposals: [] };
+  const listeners = /* @__PURE__ */ new Set();
+  const set = (proposals) => {
+    state = { proposals };
+    listeners.forEach((l) => l(state));
+  };
+  const find = (id) => {
+    const p = state.proposals.find((x) => x.id === id);
+    if (!p) throw new PaintEditorError(`No pending paint proposal "${id}". Call list_paint_proposals for the ids.`);
+    return p;
+  };
+  const strokeIds = () => new Set(controller.getStrokes().map((s) => s.id));
+  const validate = (input) => {
+    if (!input.title?.trim()) throw new PaintEditorError("A proposal needs a title: what it adds, in a few words.");
+    if (!Array.isArray(input.ops) || !input.ops.length) throw new PaintEditorError("A proposal needs at least one op (stroke, wash or echo).");
+    const place = input.place ?? "top";
+    if (place === "above") {
+      if (!input.layerId) throw new PaintEditorError('place "above" needs layerId: the layer to put the suggestion above (list_layers).');
+      if (!controller.listLayers().some((l) => l.id === input.layerId)) throw new PaintEditorError(`Unknown layer "${input.layerId}". Call list_layers for the ids.`);
+    }
+    const known = strokeIds();
+    let points = 0;
+    input.ops.forEach((op, i) => {
+      const at = `ops[${i}]`;
+      if (op.kind === "stroke") {
+        if (!op.points?.length) throw new PaintEditorError(`${at}: a stroke needs points in document pixels.`);
+        points += op.points.length;
+        if (op.color !== void 0 && !HEX4.test(op.color)) throw new PaintEditorError(`${at}: color "${op.color}" is not #rrggbb.`);
+        const brush = op.brushId ? controller.getBrush(op.brushId) : controller.getState().brush;
+        if (!brush) throw new PaintEditorError(`${at}: unknown brush "${op.brushId}". Call list_brush_presets for the ids.`);
+        const refusal = suggestionBrushRefusal(brush);
+        if (refusal) throw new PaintEditorError(`${at}: ${refusal}`);
+        if (op.size !== void 0 && !(op.size > 0)) throw new PaintEditorError(`${at}: size must be above 0 (document pixels).`);
+      } else if (op.kind === "wash") {
+        if (!HEX4.test(op.color ?? "")) throw new PaintEditorError(`${at}: a wash needs color as #rrggbb.`);
+        if (op.opacity !== void 0 && !(op.opacity > 0 && op.opacity <= 1)) throw new PaintEditorError(`${at}: opacity must be in (0, 1].`);
+      } else if (op.kind === "echo") {
+        if (!op.strokeIds?.length) throw new PaintEditorError(`${at}: an echo needs strokeIds (list_strokes).`);
+        const unknown = op.strokeIds.filter((id) => !known.has(id));
+        if (unknown.length) throw new PaintEditorError(`${at}: unknown stroke ${unknown.map((u) => `"${u}"`).join(", ")}. Call list_strokes for the ids.`);
+        if (op.color !== void 0 && !HEX4.test(op.color)) throw new PaintEditorError(`${at}: color "${op.color}" is not #rrggbb.`);
+        if (op.repeat !== void 0 && !(Number.isInteger(op.repeat) && op.repeat >= 1 && op.repeat <= 50)) throw new PaintEditorError(`${at}: repeat must be a whole number from 1 to 50.`);
+        for (const id of op.strokeIds) {
+          const stroke = controller.getStrokes().find((s) => s.id === id);
+          const refusal = suggestionBrushRefusal(stroke.brush);
+          if (refusal) throw new PaintEditorError(`${at}: stroke "${id}": ${refusal}`);
+          points += stroke.points.length * (op.repeat ?? 1);
+        }
+      } else {
+        throw new PaintEditorError(`${at}: unknown kind "${op.kind}"; use stroke, wash or echo.`);
+      }
+    });
+    if (points > maxPoints) throw new PaintEditorError(`The proposal paints ${points} points; the most is ${maxPoints}. Suggest less, or echo fewer strokes.`);
+  };
+  const paint = (ops, layerId) => {
+    const before = strokeIds();
+    for (const op of ops) {
+      if (op.kind === "stroke") {
+        controller.paintStroke({
+          layerId,
+          points: op.points,
+          ...op.brushId ? { brushId: op.brushId } : {},
+          ...op.color ? { color: op.color } : {},
+          ...op.size ? { brush: { tip: { size: op.size } } } : {},
+          stencils: false
+        });
+      } else if (op.kind === "wash") {
+        controller.fillLayer({ layerId, color: op.color, opacity: op.opacity ?? 0.35, grain: op.grain ?? 0.4 });
+      } else {
+        const { kind: _kind, strokeIds: ids, color, repeat, ...variation } = op;
+        controller.replayStrokes({ strokeIds: ids, layerId, ...color ? { color } : {}, ...repeat ? { repeat } : {}, ...variation });
+      }
+    }
+    return controller.getStrokes().map((s) => s.id).filter((id) => !before.has(id));
+  };
+  const missing = (id) => {
+    const p = state.proposals.find((x) => x.id === id);
+    if (!p) return [];
+    const known = strokeIds();
+    return p.anchors.filter((a) => !known.has(a));
+  };
+  const placementOf = (input) => ({
+    place: input.place ?? "top",
+    ...input.layerId ? { layerId: input.layerId } : {},
+    ...input.layerName ? { layerName: input.layerName } : {}
+  });
+  const topLayerId = () => controller.listLayers().find((l) => l.parentId === null)?.id;
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    propose(input) {
+      validate(input);
+      const placement = placementOf(input);
+      const preview = controller.previewPaint(
+        (layerId) => {
+          paint(input.ops, layerId);
+        },
+        placement.place === "bottom" ? { bottom: true } : { aboveId: placement.place === "above" ? placement.layerId : topLayerId() }
+      );
+      const proposal = {
+        id: makeId(),
+        title: input.title.trim().slice(0, 120),
+        ...input.rationale ? { rationale: input.rationale } : {},
+        origin: input.origin ?? options.origin ?? "agent:anonymous",
+        ops: input.ops.map((op) => ({ ...op })),
+        placement,
+        bounds: preview.bounds,
+        ghost: preview.composite,
+        anchors: [...new Set(input.ops.flatMap((op) => op.kind === "echo" ? op.strokeIds : []))],
+        createdAt: now()
+      };
+      set([...state.proposals, proposal]);
+      return proposal;
+    },
+    accept(id) {
+      const p = find(id);
+      const gone = missing(id);
+      if (gone.length) throw new PaintEditorError(`Paint proposal "${p.title}" echoes strokes that are no longer on the canvas (${gone.join(", ")}); dismiss it or propose it again.`);
+      const placement = p.placement;
+      if (placement.place === "above" && !controller.listLayers().some((l) => l.id === placement.layerId)) {
+        throw new PaintEditorError(`Paint proposal "${p.title}" goes above layer "${placement.layerId}", which is gone; dismiss it or propose it again.`);
+      }
+      const active = controller.getState().document.activeLayerId;
+      const result = controller.withOrigin(
+        p.origin,
+        () => controller.group(p.title, () => {
+          const layer = controller.addLayer({ name: placement.layerName ?? p.title, ...placement.place === "above" ? { aboveId: placement.layerId } : placement.place === "top" ? { aboveId: topLayerId() } : {} });
+          if (placement.place === "bottom") controller.moveLayer(layer.id, 0, null);
+          return { layerId: layer.id, strokeIds: paint(p.ops, layer.id) };
+        })
+      );
+      if (active && controller.listLayers().some((l) => l.id === active)) controller.setActiveLayer(active);
+      set(state.proposals.filter((x) => x.id !== id));
+      return { proposalId: id, layerId: result.layerId, strokeIds: result.strokeIds, label: p.title };
+    },
+    reject(id) {
+      const p = find(id);
+      set(state.proposals.filter((x) => x.id !== id));
+      return p;
+    },
+    clear(origin) {
+      const dropped = state.proposals.filter((p) => !origin || p.origin === origin);
+      if (dropped.length) set(state.proposals.filter((p) => !dropped.includes(p)));
+      return dropped.map((p) => p.id);
+    },
+    get: (id) => state.proposals.find((p) => p.id === id),
+    missing
+  };
+}
+function paintProposalGhost(proposal) {
+  const b = proposal.bounds;
+  if (!b || !b.width || !b.height || proposal.ghost.length !== b.width * b.height * 4) return null;
+  return { x: b.x, y: b.y, width: b.width, height: b.height, data: proposal.ghost };
+}
+
+// src/paint-editor/collaboration-tools.ts
+var READ7 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var WRITE6 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var proposalIdArg = {
+  type: "object",
+  properties: { proposalId: { type: "string", minLength: 1, description: "Id of a pending paint proposal, from propose_paint or list_paint_proposals." } },
+  required: ["proposalId"],
+  additionalProperties: false
+};
+var hex = { type: "string", pattern: "^#[0-9a-fA-F]{6}$" };
+var opSchema = {
+  type: "object",
+  description: `One thing to paint. kind "stroke": a stroke along points with a dry brush. kind "wash": an even wash over the suggestion's layer (a ground, a glaze). kind "echo": strokes already on the canvas painted again, moved, turned, scaled or mirrored (grass along a horizon, rain, hatching).`,
+  properties: {
+    kind: { type: "string", enum: ["stroke", "wash", "echo"], description: "What this op paints (see above)." },
+    points: {
+      type: "array",
+      minItems: 1,
+      description: "stroke: pen samples in document pixels, in drawing order.",
+      items: {
+        type: "object",
+        properties: {
+          x: { type: "number", description: "Document x in pixels." },
+          y: { type: "number", description: "Document y in pixels." },
+          pressure: { type: "number", minimum: 0, maximum: 1, description: "Pen pressure 0..1 (default 0.5)." }
+        },
+        required: ["x", "y"],
+        additionalProperties: false
+      }
+    },
+    brushId: { type: "string", description: "stroke: a dry brush id from list_brush_presets (dab, particle, bristle or mixer without pickup). Default the editor brush." },
+    size: { type: "number", exclusiveMinimum: 0, description: "stroke: brush size in document pixels. Default the brush's." },
+    color: { ...hex, description: "stroke and echo: #rrggbb (stroke default the editor colour; echo default each stroke's colour). wash: required." },
+    opacity: { type: "number", exclusiveMinimum: 0, maximum: 1, description: "wash: 0..1 (default 0.35)." },
+    grain: { type: "number", minimum: 0, maximum: 1, description: "wash: how much it catches the paper grain, 0..1 (default 0.4)." },
+    strokeIds: { type: "array", minItems: 1, items: { type: "string" }, description: "echo: ids of strokes on the canvas (list_strokes)." },
+    dx: { type: "number", description: "echo: move right by this many document pixels (default 0)." },
+    dy: { type: "number", description: "echo: move down by this many document pixels (default 0)." },
+    rotate: { type: "number", description: "echo: turn this many degrees clockwise about the strokes' centre (default 0)." },
+    scale: { type: "number", exclusiveMinimum: 0, description: "echo: scale about the centre; brush size scales too (default 1)." },
+    flipX: { type: "boolean", description: "echo: mirror horizontally about the centre (default false)." },
+    repeat: { type: "integer", minimum: 1, maximum: 50, description: "echo: repeat the move this many times, each on top of the last (default 1)." }
+  },
+  required: ["kind"],
+  additionalProperties: false
+};
+function createPaintProposalToolProvider(proposals, options = {}) {
+  const readOnlyReason = () => {
+    const ro = typeof options.readOnly === "function" ? options.readOnly() : options.readOnly;
+    return ro ? typeof ro === "string" ? ro : "The painting is read-only: paint proposals can be made and rejected but not accepted." : null;
+  };
+  const describe = (p) => ({
+    id: p.id,
+    title: p.title,
+    ...p.rationale ? { rationale: p.rationale } : {},
+    origin: p.origin,
+    ops: p.ops.map((op) => op.kind),
+    placement: p.placement,
+    bounds: p.bounds,
+    anchors: p.anchors,
+    missing: proposals.missing(p.id),
+    createdAt: new Date(p.createdAt).toISOString()
+  });
+  const proposeTool = {
+    name: "propose_paint",
+    title: "Propose paint",
+    description: "Suggests paint without painting it: the user sees it as a ghost over the canvas and accepts or dismisses it, so use it for contributions they did not ask for. Accepted, it is painted on a new layer of its own (on top by default, at the bottom for a ground, or above a layer) as one undo step recorded as yours. Prefer what agents do well: a wash or ground, an echo of the user's strokes, a few deliberate strokes. Dry brushes only. Returns the proposal id, where the ghost sits (bounds, document pixels) and the strokes it builds on. Follow with accept_paint_proposal only when the user asked for it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", minLength: 1, maxLength: 120, description: `What the suggestion adds, in a few words, e.g. "Warm ground behind the figure". The undo step's name once accepted.` },
+        rationale: { type: "string", description: "Why it fits what the user is painting, in one sentence. Shown beside the ghost." },
+        ops: { type: "array", minItems: 1, items: opSchema, description: "What to paint, in order, onto the suggestion's layer." },
+        place: { type: "string", enum: ["top", "bottom", "above"], description: "Where the new layer goes: top (default), bottom (behind everything: grounds and washes), or above layerId." },
+        layerId: { type: "string", description: 'With place "above": the layer to put it above (list_layers).' },
+        layerName: { type: "string", description: "The new layer's name (default the title)." }
+      },
+      required: ["title", "ops"],
+      additionalProperties: false
+    },
+    annotations: { title: "Propose paint", ...WRITE6 },
+    handler: (args, context) => {
+      const origin = context.actor?.id ? `agent:${context.actor.id}` : options.fallbackOrigin;
+      const proposal = proposals.propose({ ...args, ...origin ? { origin } : {} });
+      const { id: _id, missing: _missing, createdAt: _createdAt, ...rest } = describe(proposal);
+      return { proposalId: proposal.id, ...rest };
+    }
+  };
+  const listTool = {
+    name: "list_paint_proposals",
+    title: "List paint proposals",
+    description: "Lists the pending paint proposals (ghost paint not yet on the canvas): id, title, rationale, who proposed it, its op kinds, where it goes, where the ghost sits, the strokes it echoes and any of those since removed (missing: it can no longer be accepted), and whether accepting is allowed. Call before accept_paint_proposal or reject_paint_proposal.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { title: "List paint proposals", ...READ7 },
+    handler: () => ({ proposals: proposals.getState().proposals.map(describe), readOnly: readOnlyReason() })
+  };
+  const acceptTool = {
+    name: "accept_paint_proposal",
+    title: "Accept a paint proposal",
+    description: "Paints a pending proposal on a new layer as one undo step, recorded as made by whoever proposed it, and drops it from the pending list; the user's active layer stays theirs. Refuses, changing nothing, when the painting is read-only or a stroke it echoes was removed. Returns the new layer id, the stroke ids painted and the undo step name.",
+    inputSchema: proposalIdArg,
+    annotations: { title: "Accept a paint proposal", ...WRITE6 },
+    handler: (args) => {
+      const reason = readOnlyReason();
+      if (reason) throw new Error(reason);
+      return proposals.accept(args.proposalId);
+    }
+  };
+  const rejectTool = {
+    name: "reject_paint_proposal",
+    title: "Reject a paint proposal",
+    description: "Dismisses a pending paint proposal: its ghost disappears and the painting and its history are unchanged. Use it to withdraw a suggestion that no longer fits. Returns the dismissed proposal id and title.",
+    inputSchema: proposalIdArg,
+    annotations: { title: "Reject a paint proposal", ...WRITE6 },
+    handler: (args) => {
+      const p = proposals.reject(args.proposalId);
+      return { proposalId: p.id, title: p.title, rejected: true };
+    }
+  };
+  return {
+    id: options.id ?? "paint-proposals",
+    ...options.namespace !== void 0 ? { namespace: options.namespace } : {},
+    title: "Paint proposals",
+    description: "Suggest paint as a ghost the user accepts or dismisses, and accept or reject pending suggestions.",
+    skill: "pixerate-paint-editor",
+    tools: [proposeTool, listTool, acceptTool, rejectTool]
+  };
+}
 export {
   BACKLIGHT_SPILL,
   BLEND_MENU_GROUPS,
@@ -12565,12 +13094,15 @@ export {
   composeAffine,
   contactSheet,
   createPaintBrushLibraryToolProvider,
+  createPaintChangeFeed,
   createPaintCompositor,
   createPaintDocument,
   createPaintEditorDocument,
   createPaintEditorToolProvider,
   createPaintEffectsToolProvider,
   createPaintLayer,
+  createPaintProposalToolProvider,
+  createPaintProposals,
   createPaintReplayTools,
   createPaintStickerTools,
   createPaintThickTools,
@@ -12655,6 +13187,7 @@ export {
   padSampleRadius,
   paintGradientMappingFor,
   paintPlaybackPanel,
+  paintProposalGhost,
   paintSourceColor,
   paintSourceCss,
   paintToMultiColor,