@pixerate/editor 0.154.0 → 0.156.0

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

@@ -46,3 +46,4 @@ export { wetSupport, type WetSupport } from '../paint/wet/wasm.cjs';
 export type { WetBackendInfo } from '../paint/wet/world.cjs';
 export * from '../paint/gradient-paint.cjs';
 export * from './playback.cjs';
+export * from './editorDocument.cjs';

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

@@ -46,3 +46,4 @@ export { wetSupport, type WetSupport } from '../paint/wet/wasm.js';
 export type { WetBackendInfo } from '../paint/wet/world.js';
 export * from '../paint/gradient-paint.js';
 export * from './playback.js';
+export * from './editorDocument.js';

package/dist/paint-editor/index.js

@@ -7,7 +7,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-Y64YPIFT.js";
+} from "../chunk-ZQWLWDZI.js";
 import "../chunk-3CI7FRMK.js";
 import {
   EffectRendererPool
@@ -54,7 +54,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-O2ANJFUF.js";
-import "../chunk-FLOGD3QB.js";
+import "../chunk-6UPGM3JB.js";
 import {
   BRUSH_ID,
   BRUSH_ROTATIONS,
@@ -119,7 +119,7 @@ import {
   tiltToOrientation,
   toStrokePoint,
   usesPaintExchange
-} from "../chunk-ORDXMBD4.js";
+} from "../chunk-A5UCR2TO.js";
 import "../chunk-M6DNZNVY.js";
 import "../chunk-WEIK3UYB.js";
 import "../chunk-PWBZH3FK.js";
@@ -189,7 +189,7 @@ import {
   seedFromString,
   solidPaint,
   updatePaintGradientStop
-} from "../chunk-AGZ47XY2.js";
+} from "../chunk-2N2QPO3H.js";
 import "../chunk-ODBT55Q7.js";
 import {
   BLEND_MODES,
@@ -224,6 +224,11 @@ import "../chunk-QGHEDC7B.js";
 import "../chunk-SIFAIGB3.js";
 import "../chunk-CIQIM2IP.js";
 import "../chunk-VDGBHYC7.js";
+import {
+  createEditorAssetRegistry,
+  defineEditorDocument
+} from "../chunk-NHLYK3AX.js";
+import "../chunk-HF5QZS7Z.js";
 import "../chunk-KY3FYKP3.js";
 import "../chunk-2WPNAGHI.js";
 import {
@@ -1352,6 +1357,17 @@ function stencilMask(stencils, width, height) {
   }
   return { width, height, data };
 }
+function translateStencil(s, dx, dy) {
+  const p = (q) => q ? { x: q.x + dx, y: q.y + dy } : void 0;
+  return {
+    ...s,
+    ...s.from ? { from: p(s.from) } : {},
+    ...s.to ? { to: p(s.to) } : {},
+    ...s.center ? { center: p(s.center) } : {},
+    ...s.rect ? { rect: { ...s.rect, x: s.rect.x + dx, y: s.rect.y + dy } } : {},
+    ...s.points ? { points: s.points.map((q) => p(q)) } : {}
+  };
+}
 function scaleStencil(s, k) {
   const p = (q) => q ? { x: q.x * k, y: q.y * k } : void 0;
   return {
@@ -1502,7 +1518,7 @@ var TRACING_NODE_ID = "__tracing";
 var PAPER_EFFECT_NODE_ID = "__paper_effect";
 function paperKey(p, light) {
   const metal = p.metallic ?? 0;
-  return JSON.stringify([p.pattern, p.seed, p.color, p.scale, p.tiling, p.shading, p.dry, metal, metal > 0 && light ? [light.azimuth, light.elevation] : null]);
+  return JSON.stringify([p.pattern, p.seed, p.color, p.scale, p.tiling, p.shading, p.dry, p.offset ?? null, metal, metal > 0 && light ? [light.azimuth, light.elevation] : null]);
 }
 var paperNodes = /* @__PURE__ */ new WeakMap();
 function paperNode(paper, light) {
@@ -1517,7 +1533,7 @@ function paperNode(paper, light) {
 var grainCache = /* @__PURE__ */ new Map();
 var tileCache = /* @__PURE__ */ new Map();
 function paperGrain(paper) {
-  const key = JSON.stringify([paper.pattern, paper.seed, paper.scale, paper.tiling, paper.dry]);
+  const key = JSON.stringify([paper.pattern, paper.seed, paper.scale, paper.tiling, paper.dry, paper.offset ?? null]);
   let g = grainCache.get(key);
   if (!g) {
     g = new PaperGrain(paper, "dry");
@@ -1607,7 +1623,7 @@ function downsampleRgba(data, width, height, tw, th) {
 // src/paint-editor/serialize.ts
 var PAINT_FORMAT = "pixerate-paint";
 var PAINT_SCHEMA_VERSION = 1;
-var KNOWN = /* @__PURE__ */ new Set(["format", "version", "width", "height", "dpi", "paper", "layers", "assets", "activeLayerId", "strokes", "guides", "swatches", "mixingPad", "wet", "wetEvents", "paintEvents"]);
+var KNOWN = /* @__PURE__ */ new Set(["format", "version", "width", "height", "dpi", "paper", "layers", "assets", "activeLayerId", "strokes", "guides", "swatches", "mixingPad", "wet", "wetEvents", "paintEvents", "origin"]);
 function documentExtensions(raw) {
   const out = {};
   for (const [k, v] of Object.entries(raw)) if (!KNOWN.has(k)) out[k] = v;
@@ -1631,6 +1647,7 @@ function header(state, options) {
   if (options.wet !== void 0) out.wet = JSON.parse(JSON.stringify(options.wet));
   if (state.wetEvents?.length) out.wetEvents = JSON.parse(JSON.stringify(state.wetEvents));
   if (state.paintEvents?.length) out.paintEvents = JSON.parse(JSON.stringify(state.paintEvents));
+  if (state.origin && (state.origin.x || state.origin.y)) out.origin = { ...state.origin };
   return out;
 }
 function serializePaintDocument(state, options = {}) {
@@ -1683,6 +1700,8 @@ function deserializePaintDocument(raw) {
   if (wetEvents.length) state.wetEvents = wetEvents;
   const paintEvents = Array.isArray(r.paintEvents) ? r.paintEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.at) && typeof e.layerId === "string" && ["fill", "clear", "flatten", "stickers"].includes(e.kind)) : [];
   if (paintEvents.length) state.paintEvents = paintEvents;
+  const o = r.origin;
+  if (o && typeof o === "object" && Number.isFinite(o.x) && Number.isFinite(o.y) && (o.x || o.y)) state.origin = { x: Math.round(o.x), y: Math.round(o.y) };
   return { state, extensions: documentExtensions(r), guides: r.guides, swatches: r.swatches, mixingPad: r.mixingPad, wet: r.wet, problems };
 }
 async function deserializePaintDocumentAsync(raw, store) {
@@ -2133,7 +2152,10 @@ var PaintWetLayers = class {
   /** The world (made on first use, at the canvas size). */
   ensureWorld() {
     const { width, height } = this.host.canvas();
-    if (this.world && (this.world.width !== width || this.world.height !== height)) throw new Error("The wet world is the wrong size; dry the paint before resizing the canvas.");
+    if (this.world && (this.world.width !== width || this.world.height !== height)) {
+      if (this.world.laneIds().length) throw new Error("The wet world is the wrong size; dry the paint before resizing the canvas.");
+      this.dropWorld();
+    }
     if (!this.world) {
       this.world = new WetWorld(width, height, wetPaperInput(this.host.paper()), { kernel: this.options.kernel, threads: this.options.threads });
       this.world.setTilt(this.tilt);
@@ -2396,9 +2418,16 @@ var PaintWetLayers = class {
       if (this.world) for (const id of this.world.laneIds()) this.world.removeLane(id);
       return;
     }
+    const { width, height } = this.host.canvas();
+    if (this.world && (this.world.width !== width || this.world.height !== height)) this.dropWorld();
     this.ensureWorld().restore(snap);
     this.syncDisplays();
   }
+  dropWorld() {
+    this.world?.destroy();
+    this.world = null;
+    this.driver = null;
+  }
   /** Forgets everything wet (a new canvas, a resize, opening a document). */
   reset() {
     this.world?.destroy();
@@ -3481,6 +3510,20 @@ var PaintEditorController = class _PaintEditorController {
     return d;
   }
   // --- History -------------------------------------------------------------------
+  docRevision = 0;
+  /**
+   * Bumped on every change to the painting (a committed or amended step, undo, redo, opening a
+   * document), not on wet-paint frames or view changes. `createPaintEditorDocument` uses it.
+   */
+  get documentRevision() {
+    return this.docRevision;
+  }
+  /** Why the document cannot be replaced or stepped through right now, or `null`. */
+  busyReason() {
+    if (this.session) return "A stroke is in progress; end or cancel it first.";
+    if (this.wet.busy) return "Wet paint is mid-step; wait a moment (wetIdle()) first.";
+    return null;
+  }
   requireIdle(what) {
     if (this.session) throw new PaintEditorError(`A stroke is in progress; end or cancel it before ${what}.`);
   }
@@ -3494,6 +3537,7 @@ var PaintEditorController = class _PaintEditorController {
     if (this.undoStack.length > this.historyLimit) this.undoStack.shift();
     this.redoStack = [];
     this.doc = next;
+    this.docRevision++;
     this.trimWetHistory();
     this.emit();
   }
@@ -3510,6 +3554,7 @@ var PaintEditorController = class _PaintEditorController {
     last.after = next;
     this.redoStack = [];
     this.doc = next;
+    this.docRevision++;
     this.emit();
   }
   /** Keeps the wet snapshots in history within the wet undo memory, dropping the oldest. */
@@ -3572,6 +3617,8 @@ var PaintEditorController = class _PaintEditorController {
     this.redoStack.push(e);
     const paper = this.doc.paper;
     this.doc = e.before;
+    this.docRevision++;
+    if (e.guides) this.restoreGuides(e.guides.before);
     if (e.wet) {
       if (paper !== this.doc.paper) this.wet.paperChanged();
       this.wet.restore(e.wet.lost ? null : e.wet.before);
@@ -3589,6 +3636,8 @@ var PaintEditorController = class _PaintEditorController {
     this.undoStack.push(e);
     const paper = this.doc.paper;
     this.doc = e.after;
+    this.docRevision++;
+    if (e.guides) this.restoreGuides(e.guides.after);
     if (e.wet) {
       this.wet.restore(e.wet.lost ? null : e.wet.after);
       if (paper !== this.doc.paper) this.wet.paperChanged();
@@ -3596,6 +3645,10 @@ var PaintEditorController = class _PaintEditorController {
     this.emit();
     return e.label;
   }
+  restoreGuides(guides) {
+    if (guides.tracing !== this.guides.tracing) this.tracingVersion++;
+    this.guides = guides;
+  }
   /** Labels of the undo steps, oldest first. */
   historyLabels() {
     return { undo: this.undoStack.map((e) => e.label), redo: this.redoStack.map((e) => e.label).reverse() };
@@ -3616,7 +3669,7 @@ var PaintEditorController = class _PaintEditorController {
       width: options.width ?? this.doc.canvas.width,
       height: options.height ?? this.doc.canvas.height,
       dpi: options.dpi ?? this.doc.canvas.dpi,
-      paper: options.paper === void 0 ? this.doc.paper : this.resolvePaper(options.paper)
+      paper: options.paper === void 0 ? { ...this.doc.paper, offset: void 0 } : this.resolvePaper(options.paper)
     });
     this.extensions = {};
     this.guides = { ...this.guides, symmetry: { ...this.guides.symmetry, center: { x: next.canvas.width / 2, y: next.canvas.height / 2 } }, tracing: null };
@@ -3643,6 +3696,54 @@ var PaintEditorController = class _PaintEditorController {
     this.commit("Canvas size", this.withWetEvents({ ...this.doc, canvas }));
     return canvas;
   }
+  /**
+   * Grows the canvas by `left`, `top`, `right` and `bottom` pixels without moving anything
+   * relative to anything else: the layers (with their masks, relief and stickers), the paper grain,
+   * the effect paper, guides, stencils, the tracing image and the recorded strokes and events all
+   * move by (left, top) in document pixels, `document.origin` moves by (−left, −top), and the view
+   * pans so the picture stays still on screen.
+   *
+   * Wet paint dries first (the wet simulation is canvas-sized), as with `setCanvas`; one undo step
+   * (undo brings back the old size, origin and guides, and the wet paint). Returns the new canvas,
+   * where it sits in the previous document's pixels, and the origin.
+   */
+  extendCanvas(by) {
+    this.requireIdle("extending the canvas");
+    const side = (k) => {
+      const v = by[k] ?? 0;
+      if (!Number.isInteger(v) || v < 0) throw new PaintEditorError(`${k} is ${JSON.stringify(by[k])}; use a whole number of pixels to add, 0 or more.`);
+      return v;
+    };
+    const left = side("left");
+    const top = side("top");
+    const right = side("right");
+    const bottom = side("bottom");
+    if (!(left || top || right || bottom)) throw new PaintEditorError("Nothing to extend: give left, top, right or bottom (pixels to add on that side) above 0.");
+    const was = this.doc.canvas;
+    const width = was.width + left + right;
+    const height = was.height + top + bottom;
+    if (width > MAX_CANVAS_SIDE || height > MAX_CANVAS_SIDE) {
+      throw new PaintEditorError(`The canvas would be ${width}\xD7${height}; the limit is ${MAX_CANVAS_SIDE} px per side. Extend by less (it is ${was.width}\xD7${was.height} now).`);
+    }
+    if (this.wet.world) {
+      this.requireWetIdle("extending the canvas");
+      this.dryLayersFirst(this.wet.wetLayerIds());
+      const settings = [...this.wet.settings];
+      this.wet.reset();
+      for (const [id, s] of settings) this.wet.settings.set(id, s.flow.center ? { ...s, flow: { ...s.flow, center: { x: s.flow.center.x + left, y: s.flow.center.y + top } } } : s);
+    }
+    const next = { ...shiftDocument(this.withWetEvents(this.doc), left, top), canvas: { ...was, width, height } };
+    const m = viewMatrix(this.view, was, { width: 0, height: 0 });
+    const dx = (right - left) / 2;
+    const dy = (bottom - top) / 2;
+    this.view = { ...this.view, pan: { x: this.view.pan.x + m[0] * dx + m[1] * dy, y: this.view.pan.y + m[2] * dx + m[3] * dy } };
+    const guidesBefore = this.guides;
+    if (left || top) this.restoreGuides(shiftGuides(this.guides, left, top));
+    this.commit("Extend canvas", next);
+    if (this.guides !== guidesBefore) this.undoStack[this.undoStack.length - 1].guides = { before: guidesBefore, after: this.guides };
+    const origin = { ...next.origin ?? { x: 0, y: 0 } };
+    return { canvas: { ...next.canvas }, rect: { x: 0 - left, y: 0 - top, width, height }, origin };
+  }
   /** Changes the paper: a library preset (`preset`), and / or any of its settings (one undo step). */
   setPaper(update) {
     this.requireIdle("changing the paper");
@@ -3654,7 +3755,7 @@ var PaintEditorController = class _PaintEditorController {
     }
     const { preset: _p, ...rest } = update;
     if (rest.color !== void 0) parseColor(rest.color, "paper color");
-    const paper = normalizePaper({ ...rest, preset: base.preset }, base);
+    const paper = normalizePaper({ ...rest, preset: base.preset, offset: rest.offset ?? this.doc.paper.offset }, base);
     const changedKeys = Object.keys(rest).filter((k) => k !== "name");
     if (changedKeys.length && update.preset === void 0) paper.preset = base.preset;
     if (this.wet.world) this.beginWetOp();
@@ -5220,6 +5321,7 @@ var PaintEditorController = class _PaintEditorController {
     this.undoStack = [];
     this.redoStack = [];
     this.doc = this.readThick(loaded.state, loaded.extensions, loaded.problems);
+    this.docRevision++;
     delete this.extensions.layerChannels;
     delete this.extensions.lighting;
     delete this.extensions.stickers;
@@ -5815,6 +5917,60 @@ var PaintEditorController = class _PaintEditorController {
   }
 };
 var MAX_IMAGE_SIDE = 8192;
+var movePoint = (p, dx, dy) => ({ x: p.x + dx, y: p.y + dy });
+var moveRect = (r, dx, dy) => ({ ...r, x: r.x + dx, y: r.y + dy });
+function shiftDocument(doc, dx, dy) {
+  if (!dx && !dy) return doc;
+  let layers = doc.layers;
+  for (const l of flattenLayers(doc.layers)) if (l.type === "pixel") layers = mapLayer(layers, l.id, () => ({ ...l, offset: movePoint(l.offset, dx, dy) }));
+  const m = [1, 0, 0, 1, dx, dy];
+  const moveStickers = (list) => list.map((s) => ({ ...s, x: Math.round((s.x + dx) * 100) / 100, y: Math.round((s.y + dy) * 100) / 100 }));
+  const out = {
+    ...doc,
+    layers,
+    paper: { ...doc.paper, offset: movePoint(doc.paper.offset ?? { x: 0, y: 0 }, dx, dy) },
+    origin: movePoint(doc.origin ?? { x: 0, y: 0 }, -dx, -dy),
+    strokes: doc.strokes.map((s) => {
+      const moved = varyStroke(s, m, {});
+      return s.stencils ? { ...moved, stencils: s.stencils.map((x) => translateStencil(x, dx, dy)) } : moved;
+    })
+  };
+  if (doc.stickers) out.stickers = Object.fromEntries(Object.entries(doc.stickers).map(([id, list]) => [id, moveStickers(list)]));
+  if (doc.paintEvents) {
+    out.paintEvents = doc.paintEvents.map((e) => {
+      const list = e.kind === "stickers" ? e.data?.stickers : void 0;
+      return list ? { ...e, data: { ...e.data, stickers: moveStickers(list) } } : e;
+    });
+  }
+  if (doc.wetEvents) {
+    out.wetEvents = doc.wetEvents.map((e) => {
+      const d = e.data;
+      if (!d) return e;
+      if (e.kind === "dry" && typeof d.x === "number") return { ...e, data: moveRect(d, dx, dy) };
+      if (e.kind === "wet-paper" && d.rect) return { ...e, data: { ...d, rect: moveRect(d.rect, dx, dy) } };
+      if (e.kind === "flow" && d.center) return { ...e, data: { ...d, center: movePoint(d.center, dx, dy) } };
+      return e;
+    });
+  }
+  if (doc.paperEffect) {
+    const src = doc.paperEffect.image;
+    const width = src.width + dx;
+    const height = src.height + dy;
+    const data = new Uint8ClampedArray(width * height * 4);
+    for (let y = 0; y < src.height; y++) data.set(src.data.subarray(y * src.width * 4, (y + 1) * src.width * 4), ((y + dy) * width + dx) * 4);
+    out.paperEffect = { ...doc.paperEffect, image: { width, height, data }, version: nextPaperEffectVersion() };
+  }
+  return out;
+}
+function shiftGuides(g, dx, dy) {
+  return {
+    ...g,
+    symmetry: { ...g.symmetry, center: movePoint(g.symmetry.center, dx, dy) },
+    perspective: { ...g.perspective, points: g.perspective.points.map((p) => movePoint(p, dx, dy)) },
+    tracing: g.tracing ? { ...g.tracing, rect: moveRect(g.tracing.rect, dx, dy) } : null,
+    stencils: g.stencils.map((s) => translateStencil(s, dx, dy))
+  };
+}
 function resampleInto(src, rect, width, height) {
   const out = new Uint8ClampedArray(width * height * 4);
   const x0 = Math.max(0, Math.floor(rect.x));
@@ -7143,7 +7299,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "get_canvas_info",
     title: "Get the canvas",
-    description: "Reads the canvas: size in pixels and dpi, the paper (preset, colour, grain depth), the active layer, the active brush id, the paint colour, the view (zoom, rotation, mirror), the hand, how many strokes are recorded, the undo / redo labels, and the blend modes. Call it first.",
+    description: "Reads the canvas: size in pixels and dpi, its origin (where (0, 0) is relative to the canvas it was extended from), the paper (preset, colour, grain depth), the active layer, the active brush id, the paint colour, the view (zoom, rotation, mirror), the hand, how many strokes are recorded, the undo / redo labels, and the blend modes. Call it first.",
     inputSchema: EMPTY3,
     annotations: { title: "Get the canvas", ...READ6 },
     handler: () => {
@@ -7153,6 +7309,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
         width: d.canvas.width,
         height: d.canvas.height,
         dpi: d.canvas.dpi,
+        origin: { ...d.origin ?? { x: 0, y: 0 } },
         paper: { preset: d.paper.preset, name: d.paper.name, color: d.paper.color, depth: d.paper.depth },
         activeLayerId: d.activeLayerId,
         layerCount: c.listLayers().length,
@@ -7206,6 +7363,19 @@ function createPaintEditorToolProvider(controller, options = {}) {
     annotations: { title: "Resize the canvas", ...SET4 },
     handler: (a) => c.setCanvas({ width: a.width, height: a.height, dpi: a.dpi })
   });
+  const EXTEND_SIDE = (side) => ({ type: "integer", minimum: 0, maximum: MAX_CANVAS_SIDE - 1, description: `Pixels to add on the ${side} (default 0).` });
+  add({
+    name: "extend_canvas",
+    title: "Extend the canvas",
+    description: "Grows the canvas by adding pixels on any side, keeping everything painted. Adding on the left or top moves the whole picture (layers, paper grain, guides, stencils, recorded strokes) right or down by that much in document pixels, so coordinates you read before change by (+left, +top). Wet paint dries first. One undo step. Returns the canvas, rect (the new canvas in the previous coordinates: x -left, y -top) and origin.",
+    inputSchema: {
+      type: "object",
+      properties: { left: EXTEND_SIDE("left"), top: EXTEND_SIDE("top"), right: EXTEND_SIDE("right"), bottom: EXTEND_SIDE("bottom") },
+      additionalProperties: false
+    },
+    annotations: { title: "Extend the canvas", ...WRITE5 },
+    handler: (a) => c.extendCanvas({ left: a.left, top: a.top, right: a.right, bottom: a.bottom })
+  });
   add({
     name: "list_papers",
     title: "List papers",
@@ -7810,7 +7980,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "save_document",
     title: "Save the document",
-    description: "Returns the document as JSON (format pixerate-paint, version 1): canvas, paper, layers with PNG data URLs, and the recorded strokes unless strokes is false. Changes nothing.",
+    description: "Deprecated (kept for one minor version): use get_paint_document, which returns the painting with images as asset references, or save_paint_document to store it. Returns the document as JSON (format pixerate-paint, version 1): canvas, paper, layers with PNG data URLs, and the recorded strokes unless strokes is false. Changes nothing.",
     inputSchema: { type: "object", properties: { strokes: { type: "boolean", description: "Include the recorded strokes (default true)." } }, additionalProperties: false },
     annotations: { title: "Save the document", ...READ6 },
     handler: ({ strokes }) => c.toJSON({ strokes })
@@ -7818,7 +7988,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "open_document",
     title: "Open a document",
-    description: "Opens a saved paint document (as save_document returns), replacing the painting and clearing the undo history. Returns the canvas, the layers and anything that could not be read.",
+    description: "Deprecated (kept for one minor version): use load_paint_document or open_saved_paint_document. Opens a saved paint document (as save_document returns), replacing the painting and clearing the undo history. Returns the canvas, the layers and anything that could not be read.",
     inputSchema: { type: "object", properties: { document: { type: "object", description: "The saved document JSON." } }, required: ["document"], additionalProperties: false },
     annotations: { title: "Open a document", ...DESTRUCTIVE3 },
     handler: ({ document }) => {
@@ -8560,6 +8730,37 @@ function createPaintEffectsToolProvider(controller, options = {}) {
     ]
   }), { director: false, surface: options.playbackSurface });
 }
+
+// src/paint-editor/editorDocument.ts
+function createPaintEditorDocument(controller, options = {}) {
+  return defineEditorDocument({
+    kind: "paint",
+    recordsLoads: false,
+    assets: options.assets ?? createEditorAssetRegistry(),
+    get: () => controller.toJSON({ strokes: options.strokes ?? true }),
+    load: (document) => {
+      const problems = controller.loadJSON(document);
+      return { problems: problems.map((message) => ({ section: "painting", message })) };
+    },
+    subscribe: (listener) => {
+      let revision = controller.documentRevision;
+      return controller.subscribe(() => {
+        if (controller.documentRevision === revision) return;
+        revision = controller.documentRevision;
+        listener();
+      });
+    },
+    history: {
+      undo: () => controller.undo() !== null,
+      redo: () => controller.redo() !== null,
+      getState: () => {
+        const s = controller.getState();
+        return { canUndo: s.canUndo, canRedo: s.canRedo, ...s.undoLabel ? { undoName: s.undoLabel } : {}, ...s.redoLabel ? { redoName: s.redoLabel } : {} };
+      }
+    },
+    readOnly: () => controller.busyReason() ?? false
+  });
+}
 export {
   BLEND_MENU_GROUPS,
   BLEND_MODES,
@@ -8699,6 +8900,7 @@ export {
   contactSheet,
   createPaintCompositor,
   createPaintDocument,
+  createPaintEditorDocument,
   createPaintEditorToolProvider,
   createPaintEffectsToolProvider,
   createPaintLayer,
@@ -8848,6 +9050,7 @@ export {
   timeLapseZip,
   toStrokePoint,
   toggleStamp,
+  translateStencil,
   updatePaintGradientStop,
   usesPaintExchange,
   variationAffine,

package/dist/paint-editor/paper.d.cts

@@ -40,6 +40,14 @@ export interface PaperSettings {
     roughness: number;
     /** Metallic paper (gold or silver leaf, pearlescent card): the grain catches the light, 0..1 (default 0). */
     metallic?: number;
+    /**
+     * Where the grain's (0, 0) sits in document pixels (missing = the top-left). `extendCanvas` moves
+     * it with the paint, so the texture stays under what was painted on it.
+     */
+    offset?: {
+        x: number;
+        y: number;
+    };
 }
 type PaperPreset = PaperSettings;
 /** The built-in paper library: generated papers in families. */

package/dist/paint-editor/paper.d.ts

@@ -40,6 +40,14 @@ export interface PaperSettings {
     roughness: number;
     /** Metallic paper (gold or silver leaf, pearlescent card): the grain catches the light, 0..1 (default 0). */
     metallic?: number;
+    /**
+     * Where the grain's (0, 0) sits in document pixels (missing = the top-left). `extendCanvas` moves
+     * it with the paint, so the texture stays under what was painted on it.
+     */
+    offset?: {
+        x: number;
+        y: number;
+    };
 }
 type PaperPreset = PaperSettings;
 /** The built-in paper library: generated papers in families. */

package/dist/paint-editor/stencils.d.cts

@@ -76,5 +76,7 @@ export declare function stencilMask(stencils: readonly Stencil[], width: number,
     height: number;
     data: Uint8Array;
 } | null;
+/** A stencil moved by (dx, dy) document pixels (for a canvas extended to the left or top). */
+export declare function translateStencil(s: Stencil, dx: number, dy: number): Stencil;
 /** A stencil scaled about the origin by `k` (for repainting at a larger size). */
 export declare function scaleStencil(s: Stencil, k: number): Stencil;

package/dist/paint-editor/stencils.d.ts

@@ -76,5 +76,7 @@ export declare function stencilMask(stencils: readonly Stencil[], width: number,
     height: number;
     data: Uint8Array;
 } | null;
+/** A stencil moved by (dx, dy) document pixels (for a canvas extended to the left or top). */
+export declare function translateStencil(s: Stencil, dx: number, dy: number): Stencil;
 /** A stencil scaled about the origin by `k` (for repainting at a larger size). */
 export declare function scaleStencil(s: Stencil, k: number): Stencil;

package/dist/paint-editor/wet.d.cts

@@ -266,6 +266,7 @@ export declare class PaintWetLayers {
     snapshot(): WetSnapshot | null;
     /** Puts a snapshot back (`null`: no wet layers). Returns the layer surfaces it implies. */
     restore(snap: WetSnapshot | null): void;
+    private dropWorld;
     /** Forgets everything wet (a new canvas, a resize, opening a document). */
     reset(): void;
     /** Water overlay tiles (RGBA) over a document rectangle, for the view. */

package/dist/paint-editor/wet.d.ts

@@ -266,6 +266,7 @@ export declare class PaintWetLayers {
     snapshot(): WetSnapshot | null;
     /** Puts a snapshot back (`null`: no wet layers). Returns the layer surfaces it implies. */
     restore(snap: WetSnapshot | null): void;
+    private dropWorld;
     /** Forgets everything wet (a new canvas, a resize, opening a document). */
     reset(): void;
     /** Water overlay tiles (RGBA) over a document rectangle, for the view. */

package/dist/parameters/index.cjs

@@ -1,7 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class;
 
-var _chunk5H2C3QSFcjs = require('../chunk-5H2C3QSF.cjs');
-require('../chunk-L5OWG2NA.cjs');
+var _chunkM4MIZPQIcjs = require('../chunk-M4MIZPQI.cjs');
 require('../chunk-2BSBFBOA.cjs');
 
 
@@ -1328,7 +1327,7 @@ function mapRange(value, from, to, options) {
 // src/parameters/editorDocument.ts
 var isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
 function createParametersEditorDocument(controller) {
-  return _chunk5H2C3QSFcjs.defineEditorDocument.call(void 0, {
+  return _chunkM4MIZPQIcjs.defineEditorDocument.call(void 0, {
     kind: "parameters",
     get: () => controller.toJSON(),
     load: (document, { history }) => {

package/dist/parameters/index.js

@@ -1,7 +1,6 @@
 import {
   defineEditorDocument
-} from "../chunk-GNV54DLO.js";
-import "../chunk-WHKNYFM2.js";
+} from "../chunk-NHLYK3AX.js";
 import "../chunk-HF5QZS7Z.js";
 import {
   HistoryManager

package/dist/persistence/assets.d.cts

@@ -0,0 +1,51 @@
+import type { StorageAdapter } from "./storage.cjs";
+/** Prefix of an asset reference in a document (`pixerate-asset:<length>-<hash>`). */
+export declare const EDITOR_ASSET_PREFIX = "pixerate-asset:";
+/**
+ * Inline binary data kept out of an editor document: PNG data URLs and long base64 strings
+ * (layer pixels, masks, thick-paint channels, patterns…) are replaced by short, content-addressed
+ * references, and the bytes live here. `put` and `get` are synchronous, so an `EditorDocument`
+ * can stay synchronous; `persistEditorAssets` / `preloadEditorAssets` move the bytes to and from
+ * storage around a save or an open.
+ */
+export interface EditorAssetRegistry {
+    /** Stores `data` (once per content) and returns its reference. */
+    put(data: string): string;
+    /** The data for `ref`, or `undefined` when it is not loaded. */
+    get(ref: string): string | undefined;
+    has(ref: string): boolean;
+    /** Puts data read back from storage under its reference. */
+    set(ref: string, data: string): void;
+    readonly size: number;
+}
+/** Whether a string is inline binary data worth keeping out of the document. */
+export declare function isInlineAsset(value: string): boolean;
+export declare function createEditorAssetRegistry(): EditorAssetRegistry;
+/** A deep copy of `value` with every inline asset string replaced by its reference. */
+export declare function externalizeAssets<T>(value: T, registry: EditorAssetRegistry): T;
+/** Every asset reference in a document (or its JSON text). */
+export declare function collectAssetRefs(value: unknown): string[];
+/**
+ * A deep copy of `value` with every asset reference replaced by its data. Throws an error naming the references that are not loaded (and changes nothing).
+ */
+export declare function internalizeAssets<T>(value: T, registry: EditorAssetRegistry): T;
+export interface EditorAssetStorageOptions {
+    /** Key prefix of stored assets (default `pixerate.assets:`); one shared pool, as assets are content-addressed. */
+    prefix?: string;
+}
+/**
+ * Writes the assets `document` (or its JSON text) refers to into `storage`, skipping those
+ * this storage already has. Call before writing the document, so it never points at missing data.
+ */
+export declare function persistEditorAssets(storage: StorageAdapter, registry: EditorAssetRegistry, document: unknown, options?: EditorAssetStorageOptions): Promise<void>;
+/**
+ * Reads the assets `document` (or its JSON text) refers to from `storage` into the registry.
+ * Returns the references that could not be found.
+ */
+export declare function preloadEditorAssets(storage: StorageAdapter, registry: EditorAssetRegistry, document: unknown, options?: EditorAssetStorageOptions): Promise<string[]>;
+/**
+ * `storage` with assets handled: every `set` first writes the assets the value refers to, and
+ * every `get` reads them into the registry before returning. Wrap the storage an autosave or a
+ * document store uses for an editor whose document has `assets`.
+ */
+export declare function withEditorAssets(storage: StorageAdapter, registry: EditorAssetRegistry, options?: EditorAssetStorageOptions): StorageAdapter;

package/dist/persistence/assets.d.ts

@@ -0,0 +1,51 @@
+import type { StorageAdapter } from "./storage.js";
+/** Prefix of an asset reference in a document (`pixerate-asset:<length>-<hash>`). */
+export declare const EDITOR_ASSET_PREFIX = "pixerate-asset:";
+/**
+ * Inline binary data kept out of an editor document: PNG data URLs and long base64 strings
+ * (layer pixels, masks, thick-paint channels, patterns…) are replaced by short, content-addressed
+ * references, and the bytes live here. `put` and `get` are synchronous, so an `EditorDocument`
+ * can stay synchronous; `persistEditorAssets` / `preloadEditorAssets` move the bytes to and from
+ * storage around a save or an open.
+ */
+export interface EditorAssetRegistry {
+    /** Stores `data` (once per content) and returns its reference. */
+    put(data: string): string;
+    /** The data for `ref`, or `undefined` when it is not loaded. */
+    get(ref: string): string | undefined;
+    has(ref: string): boolean;
+    /** Puts data read back from storage under its reference. */
+    set(ref: string, data: string): void;
+    readonly size: number;
+}
+/** Whether a string is inline binary data worth keeping out of the document. */
+export declare function isInlineAsset(value: string): boolean;
+export declare function createEditorAssetRegistry(): EditorAssetRegistry;
+/** A deep copy of `value` with every inline asset string replaced by its reference. */
+export declare function externalizeAssets<T>(value: T, registry: EditorAssetRegistry): T;
+/** Every asset reference in a document (or its JSON text). */
+export declare function collectAssetRefs(value: unknown): string[];
+/**
+ * A deep copy of `value` with every asset reference replaced by its data. Throws an error naming the references that are not loaded (and changes nothing).
+ */
+export declare function internalizeAssets<T>(value: T, registry: EditorAssetRegistry): T;
+export interface EditorAssetStorageOptions {
+    /** Key prefix of stored assets (default `pixerate.assets:`); one shared pool, as assets are content-addressed. */
+    prefix?: string;
+}
+/**
+ * Writes the assets `document` (or its JSON text) refers to into `storage`, skipping those
+ * this storage already has. Call before writing the document, so it never points at missing data.
+ */
+export declare function persistEditorAssets(storage: StorageAdapter, registry: EditorAssetRegistry, document: unknown, options?: EditorAssetStorageOptions): Promise<void>;
+/**
+ * Reads the assets `document` (or its JSON text) refers to from `storage` into the registry.
+ * Returns the references that could not be found.
+ */
+export declare function preloadEditorAssets(storage: StorageAdapter, registry: EditorAssetRegistry, document: unknown, options?: EditorAssetStorageOptions): Promise<string[]>;
+/**
+ * `storage` with assets handled: every `set` first writes the assets the value refers to, and
+ * every `get` reads them into the registry before returning. Wrap the storage an autosave or a
+ * document store uses for an editor whose document has `assets`.
+ */
+export declare function withEditorAssets(storage: StorageAdapter, registry: EditorAssetRegistry, options?: EditorAssetStorageOptions): StorageAdapter;