@pixerate/editor 0.259.0 → 0.261.0

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

@@ -57,3 +57,5 @@ export type { StickerProvider, StickerRef, StickerSummary } from '../stickers/ty
 export * from './sticker-art.cjs';
 export * from './collaboration.cjs';
 export * from './collaboration-tools.cjs';
+export { samplePath, MAX_PATH_SAMPLES, type PathSampleOptions } from './path-samples.cjs';
+export { paintContracts, PAINT_CONTRACT_FORMAT_VERSION, PAINT_DOCUMENT_JSON_SCHEMA } from './contract.cjs';

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

@@ -57,3 +57,5 @@ export type { StickerProvider, StickerRef, StickerSummary } from '../stickers/ty
 export * from './sticker-art.js';
 export * from './collaboration.js';
 export * from './collaboration-tools.js';
+export { samplePath, MAX_PATH_SAMPLES, type PathSampleOptions } from './path-samples.js';
+export { paintContracts, PAINT_CONTRACT_FORMAT_VERSION, PAINT_DOCUMENT_JSON_SCHEMA } from './contract.js';

package/dist/paint-editor/index.js

@@ -11,7 +11,7 @@ import {
   mergeBrushPatch,
   multiColorSliders,
   patchBrushValue
-} from "../chunk-ICTPLVSR.js";
+} from "../chunk-X2EXYY4J.js";
 import {
   createStickerTools,
   describeStickerRef
@@ -20,20 +20,18 @@ import {
   toVideoFfmpeg
 } from "../chunk-MWUZCEFT.js";
 import {
+  BRUSH_OPTION_CONTROLS,
   createLayerEffectTools,
   deserializeLayers,
   exportPsd,
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-SSFMWJDK.js";
-import "../chunk-ZNA3IQZF.js";
-import {
-  brushColourHex
-} from "../chunk-FJBQTZS4.js";
-import "../chunk-3CI7FRMK.js";
+} from "../chunk-D4TE5JNW.js";
+import "../chunk-WJ4WQJCC.js";
 import {
   LAYER_EFFECT_KINDS,
+  LAYER_EFFECT_MENU,
   LayerEffectError,
   RasterCompositor,
   defaultLayerEffect,
@@ -42,12 +40,13 @@ import {
   insertLayer,
   isLayerEffectKind,
   isLayerLocked,
+  layerEffectControls,
   layerEffectLabel,
   mapLayer,
   mergeLayerEffect,
   newEffectId,
   validateLayerEffects
-} from "../chunk-3PPJRMIG.js";
+} from "../chunk-3O47TPGX.js";
 import "../chunk-OHKOFKBY.js";
 import "../chunk-ZIF4UJJ6.js";
 import {
@@ -74,7 +73,8 @@ import {
   pigmentOf,
   pointerPressure,
   wetSupport
-} from "../chunk-WQCNC4DK.js";
+} from "../chunk-XC6DPRYI.js";
+import "../chunk-VWEWY4FY.js";
 import "../chunk-HVQVHUTV.js";
 import {
   writeZip
@@ -85,7 +85,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-IVSWRVB4.js";
-import "../chunk-YQ4PQTBB.js";
+import "../chunk-6NZL24W4.js";
 import {
   BRUSH_ID,
   BRUSH_PRESETS,
@@ -140,7 +140,7 @@ import {
   parseBrushLibrary,
   resolveBrush,
   usesPaintExchange
-} from "../chunk-SMTUQWGY.js";
+} from "../chunk-5IW65VQ6.js";
 import {
   STAMP_KINDS,
   StickersSlot,
@@ -150,8 +150,16 @@ import {
   stickerIdFor
 } from "../chunk-APX63ILU.js";
 import "../chunk-M6DNZNVY.js";
-import "../chunk-WEIK3UYB.js";
+import {
+  bezierPathToSvg,
+  flattenChain,
+  pathToContours
+} from "../chunk-WEIK3UYB.js";
 import "../chunk-PWBZH3FK.js";
+import {
+  brushColourHex
+} from "../chunk-FJBQTZS4.js";
+import "../chunk-3CI7FRMK.js";
 import {
   StickerError
 } from "../chunk-SZTI6EER.js";
@@ -268,6 +276,7 @@ import "../chunk-SIFAIGB3.js";
 import "../chunk-CIQIM2IP.js";
 import "../chunk-VDGBHYC7.js";
 import {
+  EDITOR_DOCUMENT_FORMAT,
   createEditorAssetRegistry,
   defineEditorDocument
 } from "../chunk-XBQX76CT.js";
@@ -653,6 +662,18 @@ function brushStickerRefs(brush) {
   const refs = brush.engine === "sticker" ? [...brush.sticker.stamps] : brush.engine === "particle" ? [...brush.particle.dotTextures] : brush.engine === "dab" && brush.stamp ? [brush.stamp] : [];
   return [...new Set(refs.filter((r) => r.includes(":") && !r.startsWith("editor:")))];
 }
+function sprayDroplets(d, spray, seed) {
+  const count = 1 + Math.round(spray.density * 31);
+  const key = d.index * 131 + Math.round(d.travel * 8);
+  const out = [];
+  for (let i = 0; i < count; i++) {
+    const n = key * 64 + i;
+    const a = rand01(seed, n, 61) * Math.PI * 2;
+    const rr = Math.sqrt(rand01(seed, n, 67)) * d.radius;
+    out.push({ ...d, x: d.x + Math.cos(a) * rr, y: d.y + Math.sin(a) * rr, radius: Math.max(0.5, d.radius * spray.size * (0.6 + 0.8 * rand01(seed, n, 71))), roundness: 1, angle: rand01(seed, n, 73) * Math.PI * 2 });
+  }
+  return out;
+}
 
 // src/paint-editor/engine.ts
 function penOrientation(p) {
@@ -921,14 +942,7 @@ var DryStroke = class {
         this.mark(d, d, rects);
         continue;
       }
-      const count = 1 + Math.round(spray.density * 31);
-      const key = d.index * 131 + Math.round(d.travel * 8);
-      for (let i = 0; i < count; i++) {
-        const a = rand01(seed, key * 64 + i, 61) * Math.PI * 2;
-        const rr = Math.sqrt(rand01(seed, key * 64 + i, 67)) * d.radius;
-        const drop = { ...d, x: d.x + Math.cos(a) * rr, y: d.y + Math.sin(a) * rr, radius: Math.max(0.5, d.radius * spray.size * (0.6 + 0.8 * rand01(seed, key * 64 + i, 71))), roundness: 1, angle: rand01(seed, key * 64 + i, 73) * Math.PI * 2 };
-        this.mark(drop, d, rects);
-      }
+      for (const drop of sprayDroplets(d, spray, seed)) this.mark(drop, d, rects);
     }
     return rects;
   }
@@ -1019,6 +1033,7 @@ var PaintDabStroke = class {
   constructor(brush, options) {
     this.brush = brush;
     this.options = options;
+    this.stamp = brush.engine === "dab" && brush.stamp ? stampSampler(brush.stamp, options.stampArt) : null;
     this.smoother = new PenSmoother(brush.tip.smoothing, brush.pressureSmoothing);
     this.copies = options.copies?.length ? options.copies : [IDENTITY_COPY];
     const exchanging = brush.engine === "mixer" || brush.engine === "dab";
@@ -1062,6 +1077,8 @@ var PaintDabStroke = class {
   paint = [0, 0, 0];
   lastRaw = null;
   lastFed = null;
+  /** The stamp tip's shape (dab brushes), or `null` for the round computed tip. */
+  stamp;
   /** What copy 0's brush carries after the dabs so far (mixer and wet-capable dab brushes). */
   get load() {
     return this.states[0].exchange?.load ?? null;
@@ -1094,8 +1111,9 @@ var PaintDabStroke = class {
     return rects;
   }
   paintDabs(copy, dabs, rects) {
-    for (const d of dabs) {
-      const rect = dabRect(d, this.brush.tip.hardness);
+    const spray = this.brush.engine === "dab" ? this.brush.spray : null;
+    for (const d of spray ? dabs.flatMap((dab) => sprayDroplets(dab, spray, (this.options.seed ?? 0) + copy * 7919)) : dabs) {
+      const rect = this.stamp ? stampDabRect(d) : dabRect(d, this.brush.tip.hardness);
       if (rect.width <= 0 || rect.height <= 0) continue;
       this.dab(copy, d, rect);
       rects.push(rect);
@@ -1111,7 +1129,8 @@ var PaintDabStroke = class {
     }
     const tip = this.tip.subarray(0, n);
     tip.fill(0);
-    rasterizeDab({ ...d, alpha: 1 }, this.brush.tip.hardness, rect, tip);
+    if (this.stamp) rasterizeStampDab({ ...d, alpha: 1 }, this.stamp, d.index, rect, tip);
+    else rasterizeDab({ ...d, alpha: 1 }, this.brush.tip.hardness, rect, tip);
     if (!(this.depth > 0 && this.options.grain)) return { tip, cov: tip };
     const cov = this.cov.subarray(0, n);
     const grain = this.options.grain;
@@ -2958,7 +2977,8 @@ var PaintStrokeSession = class _PaintStrokeSession {
         seed: init.seed,
         copies: this.copies,
         paint: init.paint ?? null,
-        effect
+        effect,
+        stampArt: init.stampArt
       });
     } else {
       const opts = { grain: init.grain, paperDepth: init.paperDepth, seed: init.seed, copies: this.copies, paint: init.paint ?? null, effect, stampArt: init.stampArt };
@@ -5205,6 +5225,55 @@ function engineChanges(base, next) {
   return rest;
 }
 
+// src/paint-editor/path-samples.ts
+var FLATTEN_TOLERANCE = 0.1;
+var MAX_PATH_SAMPLES = 2e4;
+function profileAt(profile, t) {
+  if (profile.length === 1) return profile[0];
+  const at = t * (profile.length - 1);
+  const i = Math.min(profile.length - 2, Math.floor(at));
+  return profile[i] + (profile[i + 1] - profile[i]) * (at - i);
+}
+function samplePath(d, options = {}) {
+  const spacing = options.spacing ?? 2;
+  if (!(spacing >= 0.25 && spacing <= 100)) throw new Error(`spacing ${spacing} is out of range; use 0.25..100 document pixels.`);
+  const profile = options.pressure;
+  if (profile && (!profile.length || profile.some((p) => !(p >= 0 && p <= 1)))) throw new Error("pressure needs one or more values from 0 to 1, e.g. [0.2, 1, 0.2] for a taper.");
+  let contours;
+  try {
+    contours = pathToContours(d);
+  } catch (e) {
+    throw new Error(`path is not SVG path data (${e instanceof Error ? e.message : String(e)}); give e.g. "M 10 10 C 40 0 80 60 120 30".`);
+  }
+  const out = [];
+  for (const contour of contours) {
+    if (!contour.segments.length) continue;
+    const line = flattenChain(contour.segments, FLATTEN_TOLERANCE);
+    if (contour.closed && line.length) line.push(line[0]);
+    const lengths = [0];
+    for (let i = 1; i < line.length; i++) lengths.push(lengths[i - 1] + Math.hypot(line[i][0] - line[i - 1][0], line[i][1] - line[i - 1][1]));
+    const total = lengths[lengths.length - 1];
+    const n = Math.max(1, Math.ceil(total / spacing));
+    if (n + 1 > MAX_PATH_SAMPLES) throw new Error(`The path is ${Math.round(total)} px long: too many samples at spacing ${spacing}; use a larger spacing (at least ${Math.ceil(total / (MAX_PATH_SAMPLES - 1))}).`);
+    const points = [];
+    let j = 0;
+    for (let k = 0; k <= n; k++) {
+      const at = total * k / n;
+      while (j < line.length - 2 && lengths[j + 1] < at) j++;
+      const span = lengths[j + 1] - lengths[j] || 1;
+      const f = line.length > 1 ? Math.min(1, Math.max(0, (at - lengths[j]) / span)) : 0;
+      const a = line[j];
+      const b = line[Math.min(j + 1, line.length - 1)];
+      const x = Math.round((a[0] + (b[0] - a[0]) * f) * 1e3) / 1e3;
+      const y = Math.round((a[1] + (b[1] - a[1]) * f) * 1e3) / 1e3;
+      points.push(profile ? { x, y, pressure: Math.round(profileAt(profile, k / n) * 1e3) / 1e3 } : { x, y });
+    }
+    out.push(points);
+  }
+  if (!out.length) throw new Error('path has no segments to brush; give SVG path data such as "M 10 10 L 200 80".');
+  return out;
+}
+
 // src/paint-editor/live-strokes.ts
 var LIVE_STROKE_ENGINES = ["dab", "particle", "bristle", "mixer"];
 function liveStrokeRefusal(brush) {
@@ -7841,6 +7910,47 @@ var PaintEditorController = class _PaintEditorController {
     else this.emit([]);
     return result;
   }
+  /**
+   * Brushes vector path data (SVG `d`, document pixels) with the active brush, or `brushId` /
+   * `brush`, as if drawn by hand: one recorded stroke per subpath, sampled every `spacing` px
+   * with an optional `pressure` profile along each. All of it is one undo step. A given `seed`
+   * seeds the first subpath; the next ones take the following seeds.
+   */
+  strokePath(init) {
+    this.requireIdle("painting");
+    if (typeof init.path !== "string" || !init.path.trim()) throw new PaintEditorError('path is empty; give SVG path data in document pixels, e.g. "M 10 10 C 40 0 80 60 120 30".');
+    let subpaths;
+    try {
+      subpaths = samplePath(init.path, init);
+    } catch (e) {
+      throw new PaintEditorError(e instanceof Error ? e.message : String(e));
+    }
+    const { path: _path, spacing: _spacing, pressure: _pressure, ...stroke } = init;
+    const before = this.doc;
+    let doc = this.doc;
+    let bounds = null;
+    let dabs = 0;
+    const strokeIds = [];
+    let last = null;
+    try {
+      subpaths.forEach((points, i) => {
+        last = this.runStroke(doc, { ...stroke, ...stroke.seed !== void 0 ? { seed: stroke.seed + i } : {}, start: points[0] }, points);
+        doc = last.doc;
+        bounds = unionRect(bounds, last.result.bounds);
+        dabs += last.result.dabs;
+        if (last.result.strokeId) strokeIds.push(last.result.strokeId);
+      });
+    } catch (e) {
+      this.wetOp = null;
+      throw e;
+    }
+    const run = last;
+    if (run?.result.mixerLoad) this.keepLoad(run.brush, run.result.mixerLoad);
+    if (doc !== before || this.wetOp) this.commit(`${run?.brush.name ?? "Brush"} path stroke`, this.withWetEvents(doc), before);
+    else this.emit([]);
+    const layerId = run?.result.layerId ?? stroke.layerId ?? this.doc.activeLayerId ?? "";
+    return { layerId, bounds, dabs, strokeIds, ...run?.result.mixerLoad ? { mixerLoad: run.result.mixerLoad } : {}, ...run?.result.wet !== void 0 ? { wet: run.result.wet } : {} };
+  }
   /** 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.");
@@ -11563,6 +11673,41 @@ function createPaintEditorToolProvider(controller, options = {}) {
       return r.mixerLoad ? { ...r, mixerLoad: loadResult(r.mixerLoad) } : r;
     }
   });
+  add({
+    name: "stroke_path",
+    title: "Brush along a path",
+    description: "Brushes vector path data (SVG path d in document pixels: M, L, H, V, C, S, Q, T, A and Z) on a pixel layer with a library brush or the active one, as if drawn by hand along it: the outline of a shape, a lettering guide, a curve from a vector tool. Each subpath becomes one recorded stroke, sampled every spacing px, with an optional pressure profile spread along each subpath (a taper such as [0.2, 1, 0.2]); closed subpaths end where they start. Brushes behave as in paint_stroke (grain, pick-up, wet and thick paint, guides off). One undo step for the whole path. Returns the layer id, changed bounds, dab count and the recorded strokeIds (for replay_strokes, update_stroke).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", minLength: 1, description: 'SVG path data in document pixels, e.g. "M 40 200 C 120 40 280 40 360 200". Several subpaths paint several strokes.' },
+        spacing: { type: "number", minimum: 0.25, maximum: 100, description: "Distance between samples along the path in document pixels (default 2); the brush spaces its own dabs, so this only sets how closely curves are followed." },
+        pressure: { type: "array", minItems: 1, maxItems: 64, items: { type: "number", minimum: 0, maximum: 1 }, description: "Pen pressure along each subpath, spread evenly from start to end (default full pressure); [0.2, 1, 0.2] tapers both ends." },
+        layerId: LAYER_ID4,
+        brushId: { type: "string", description: "Brush id from list_brush_presets (default the active brush)." },
+        brush: { type: "object", description: "Facets to change for this stroke only, laid over brushId or the active brush (as set_brush takes them).", properties: BRUSH_PATCH_PROPERTIES, additionalProperties: false },
+        color: { ...COLOR3, description: "Paint colour #rrggbb (default the paint colour)." },
+        paint: { ...PAINT_SOURCE_JSON_SCHEMA, description: "What the strokes paint with instead of the editor's paint: a colour, or gradient paint that changes colour as each stroke goes." },
+        seed: { type: "integer", minimum: 0, description: "Jitter seed of the first subpath, the next ones take the following seeds (default new ones); the same seed and path give the same marks." }
+      },
+      required: ["path"],
+      additionalProperties: false
+    },
+    annotations: { title: "Brush along a path", ...WRITE5 },
+    coordinates: { out: ["bounds"] },
+    handler: async (a) => {
+      await c.wetIdle();
+      const base = a.brushId ? c.getBrush(a.brushId) : c.getState().brush;
+      const brush = a.brush ? c.brushChanges(a.brush, a.brushId) : void 0;
+      if (base) {
+        const refs = brushStickerRefs(normalizePaintBrush({ ...brush ?? {}, id: base.id }, base));
+        if (refs.length) await c.prepareStickers(refs);
+      }
+      const path = options.origin && typeof a.path === "string" && a.path.trim() ? bezierPathToSvg(a.path, { offset: { x: -options.origin.x, y: -options.origin.y } }) : a.path;
+      const r = c.strokePath({ path, spacing: a.spacing, pressure: a.pressure, layerId: a.layerId, brushId: a.brushId, brush, color: a.color, paint: a.paint, seed: a.seed });
+      return r.mixerLoad ? { ...r, mixerLoad: loadResult(r.mixerLoad) } : r;
+    }
+  });
   add({
     name: "get_live_stroke",
     title: "Get the stroke being painted",
@@ -12178,44 +12323,47 @@ var PaintGesture = class {
   }
 };
 var round2 = (v) => Math.round(v * 100) / 100;
+var PAINT_SHORTCUTS = [
+  { id: "undo", label: "Undo", group: "edit", keys: ["Mod+Z"], tool: "undo_paint" },
+  { id: "redo", label: "Redo", group: "edit", keys: ["Mod+Shift+Z", "Mod+Y"], tool: "redo_paint" },
+  ...PAINT_TOOLS.map((t) => ({ id: `tool.${t.id}`, label: t.label, group: "tools", keys: [t.key.toUpperCase()] })),
+  { id: "brush.smaller", label: "Smaller brush", group: "brush", keys: ["["], tool: "set_brush" },
+  { id: "brush.larger", label: "Larger brush", group: "brush", keys: ["]"], tool: "set_brush" },
+  { id: "colour.swap", label: "Swap colours", group: "colour", keys: ["X"] },
+  { id: "view.mirror", label: "Mirror the view", group: "view", keys: ["M"], tool: "set_view" },
+  { id: "view.reset", label: "Reset the view", group: "view", keys: ["Escape"], tool: "set_view" }
+];
+function paintShortcutFor(e) {
+  if (!e.key) return null;
+  const parts = [...e.ctrlKey || e.metaKey ? ["Mod"] : [], ...e.shiftKey && (e.ctrlKey || e.metaKey) ? ["Shift"] : []];
+  const key = e.key.length === 1 ? e.key.toUpperCase() : e.key[0].toUpperCase() + e.key.slice(1).toLowerCase();
+  const combo = [...parts, key].join("+");
+  return PAINT_SHORTCUTS.find((s) => s.keys.includes(combo)) ?? null;
+}
 function handlePaintShortcut(controller, gesture, e) {
-  const mod = e.ctrlKey || e.metaKey;
-  const key = e.key.toLowerCase();
-  if (mod && key === "z") {
-    if (controller.getState().stroking) return true;
-    if (e.shiftKey) controller.redo();
-    else controller.undo();
-    return true;
-  }
-  if (mod && key === "y") {
-    controller.redo();
+  const shortcut = paintShortcutFor(e);
+  if (!shortcut) return false;
+  const id = shortcut.id;
+  if (id === "undo" || id === "redo") {
+    if (controller.getState().stroking && !(id === "redo" && e.key.toLowerCase() === "y")) return true;
+    if (id === "undo") controller.undo();
+    else controller.redo();
     return true;
   }
-  if (mod) return false;
-  const tool = PAINT_TOOLS.find((t) => t.key === key);
-  if (tool) {
-    gesture.tool = tool.id;
+  if (id.startsWith("tool.")) {
+    gesture.tool = id.slice(5);
     return true;
   }
-  const brush = controller.getState().brush;
-  if (key === "[" || key === "]") {
+  if (id === "brush.smaller" || id === "brush.larger") {
+    const brush = controller.getState().brush;
     const step = Math.max(1, Math.round(brush.tip.size * 0.15));
-    controller.setBrush({ tip: { size: Math.max(1, brush.tip.size + (key === "]" ? step : -step)) } });
-    return true;
-  }
-  if (key === "x") {
-    controller.swapColors();
-    return true;
-  }
-  if (key === "m") {
-    controller.setView({ mirror: !controller.getState().view.mirror });
+    controller.setBrush({ tip: { size: Math.max(1, brush.tip.size + (id === "brush.larger" ? step : -step)) } });
     return true;
   }
-  if (key === "escape") {
-    controller.resetView();
-    return true;
-  }
-  return false;
+  if (id === "colour.swap") controller.swapColors();
+  else if (id === "view.mirror") controller.setView({ mirror: !controller.getState().view.mirror });
+  else if (id === "view.reset") controller.resetView();
+  return true;
 }
 var PaintCanvasPresenter = class {
   constructor(controller) {
@@ -12461,6 +12609,12 @@ function toggleDotTexture(textures, stamp) {
   if (textures.includes(stamp)) return textures.filter((s) => s !== stamp);
   return textures.length < MAX_DOT_TEXTURES ? [...textures, stamp] : [...textures];
 }
+var PATH_STROKE_TAPERS = [
+  { id: "even", label: "Even" },
+  { id: "both", label: "Taper both ends", pressure: [0.2, 1, 0.2] },
+  { id: "in", label: "Fade in", pressure: [0.2, 1] },
+  { id: "out", label: "Fade out", pressure: [1, 0.2] }
+];
 var STROKE_SLIDERS = [
   { path: "tip.size", label: "Size", min: 1, max: 400, step: 1 },
   { path: "tip.opacity", label: "Opacity", min: 0, max: 1, step: 0.01 },
@@ -13171,6 +13325,127 @@ function createPaintProposalToolProvider(proposals, options = {}) {
     tools: [proposeTool, listTool, acceptTool, rejectTool]
   };
 }
+
+// src/paint-editor/contract.ts
+var PAINT_CONTRACT_FORMAT_VERSION = 1;
+var POINT2 = { type: "object", properties: { x: { type: "number", description: "Document x in pixels." }, y: { type: "number", description: "Document y in pixels." } }, required: ["x", "y"] };
+var PAINT_DOCUMENT_JSON_SCHEMA = {
+  type: "object",
+  description: "A saved painting, as the paint editor's save tools and autosave write it.",
+  properties: {
+    format: { type: "string", const: EDITOR_DOCUMENT_FORMAT, description: `Always "${EDITOR_DOCUMENT_FORMAT}".` },
+    kind: { type: "string", const: "paint", description: 'Always "paint".' },
+    formatVersion: { type: "integer", minimum: 1, description: "Version of the envelope for this kind; readers migrate older ones." },
+    name: { type: "string", description: "Display name, when it has one." },
+    document: {
+      type: "object",
+      description: "The painting (`SerializedPaintDocument`).",
+      properties: {
+        format: { type: "string", const: PAINT_FORMAT, description: `Always "${PAINT_FORMAT}".` },
+        version: { type: "integer", minimum: 1, maximum: PAINT_SCHEMA_VERSION, description: `Painting version (${PAINT_SCHEMA_VERSION}; version 1 strokes hold flat engine brushes and are migrated).` },
+        width: { type: "integer", minimum: 1, description: "Canvas width in pixels." },
+        height: { type: "integer", minimum: 1, description: "Canvas height in pixels." },
+        dpi: { type: "number", exclusiveMinimum: 0, description: "Pixels per inch." },
+        paper: {
+          type: "object",
+          description: "The paper settings; the paper is regenerated from them, never stored as pixels.",
+          properties: {
+            preset: { type: "string", description: "The paper preset it started from (custom when none)." },
+            name: { type: "string", description: "Display name." },
+            pattern: { type: "string", description: "Grain pattern id." },
+            seed: { type: "number", description: "Grain seed." },
+            color: { type: "string", description: "Paper colour #rrggbb." },
+            scale: { type: "number", description: "Grain scale (0.25 to 8)." },
+            depth: { type: "number", minimum: 0, maximum: 1, description: "Grain depth for dry media." }
+          },
+          required: ["preset", "pattern", "seed", "color"]
+        },
+        layers: {
+          type: "array",
+          description: "Bottom to top: the image editor's serialized layers (pixel layers keep their pixels in `assets`).",
+          items: { type: "object", properties: { id: { type: "string", description: "Layer id." }, name: { type: "string", description: "Layer name." }, type: { type: "string", description: "pixel, group, \u2026" } }, required: ["id", "type"] }
+        },
+        assets: { type: "object", additionalProperties: { type: "string" }, description: "Asset id \u2192 PNG data URL or an external reference." },
+        activeLayerId: { type: ["string", "null"], description: "The active layer." },
+        strokes: {
+          type: "array",
+          description: "Recorded strokes, oldest first (missing when saved without them).",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string", description: "Stroke id." },
+              layerId: { type: "string", description: "The layer it painted on." },
+              color: { type: "string", description: "The paint colour as recorded at stroke start." },
+              seed: { type: "number", description: "Seed of its jitter and grain, so a replay is exact." },
+              points: { type: "array", items: POINT2, description: "The samples, with pressure, tilt and time when recorded." },
+              brush: { $ref: "../brushes/brush.schema.json", description: "The facet brush it painted with." }
+            },
+            required: ["id", "layerId", "points", "brush"]
+          }
+        }
+      },
+      required: ["format", "version", "width", "height", "dpi", "paper", "layers", "assets", "activeLayerId"]
+    }
+  },
+  required: ["format", "kind", "formatVersion", "document"]
+};
+function toolList(provider) {
+  const tools = typeof provider.tools === "function" ? provider.tools() : provider.tools;
+  return {
+    id: provider.id,
+    title: provider.title,
+    ...provider.skill ? { skill: provider.skill } : {},
+    tools: tools.map((t) => ({ name: t.name, title: t.title, description: t.description, inputSchema: t.inputSchema, annotations: t.annotations }))
+  };
+}
+function uiTables() {
+  return {
+    tools: PAINT_TOOLS,
+    brushOptions: BRUSH_OPTION_CONTROLS,
+    blendMenu: BLEND_MENU_GROUPS,
+    layerEffects: LAYER_EFFECT_MENU.map(({ kind, label }) => ({ kind, label, controls: layerEffectControls(defaultLayerEffect(kind, kind)) })),
+    sliders: { paper: PAPER_SLIDERS, wet: WET_PARAM_SLIDERS, wetTilt: WET_TILT_SLIDERS, wetSpeed: WET_SPEED_SLIDER, light: LIGHT_SLIDERS, stroke: STROKE_SLIDERS, sticker: STICKER_SLIDERS },
+    pathStrokeTapers: PATH_STROKE_TAPERS,
+    padSampleSizes: PAD_SAMPLE_SIZES,
+    wetGpu: WET_GPU_OPTIONS,
+    labels: {
+      wetTools: WET_TOOL_LABELS,
+      wetMedia: WET_MEDIUM_LABELS,
+      impastoTools: IMPASTO_TOOL_LABELS,
+      particleKinds: PARTICLE_KIND_LABELS,
+      particleRenders: PARTICLE_RENDER_LABELS,
+      ribbonPairs: RIBBON_PAIR_LABELS,
+      dotTextureOrders: DOT_TEXTURE_ORDER_LABELS,
+      dotRotations: DOT_ROTATION_LABELS,
+      stamps: STAMP_LABELS
+    }
+  };
+}
+function paintContracts(options) {
+  const controller = new PaintEditorController({ width: 64, height: 64 });
+  controller.setEffectsProvider(options.effects);
+  const providers = [
+    createPaintEditorToolProvider(controller),
+    createPaintEffectsToolProvider(controller),
+    createPaintBrushLibraryToolProvider(controller),
+    createPaintProposalToolProvider(createPaintProposals({ controller }))
+  ].map(toolList);
+  const document = createPaintEditorDocument(controller);
+  const files = {
+    "document.schema.json": { $schema: "https://json-schema.org/draft/2020-12/schema", $id: "document.schema.json", ...PAINT_DOCUMENT_JSON_SCHEMA },
+    "tools.json": { providers },
+    "commands.json": PAINT_SHORTCUTS.map((s) => ({ ...s, params: { type: "object", properties: {}, additionalProperties: false } })),
+    "ui.json": uiTables()
+  };
+  files["manifest.json"] = {
+    domain: "paint",
+    formatVersion: PAINT_CONTRACT_FORMAT_VERSION,
+    document: { kind: document.kind, formatVersion: document.formatVersion, format: PAINT_FORMAT, version: PAINT_SCHEMA_VERSION },
+    counts: { providers: providers.length, tools: providers.reduce((n, p) => n + p.tools.length, 0), commands: PAINT_SHORTCUTS.length, layerEffects: LAYER_EFFECT_KINDS.length },
+    files: Object.keys(files).sort()
+  };
+  return files;
+}
 export {
   BACKLIGHT_SPILL,
   BLEND_MENU_GROUPS,
@@ -13225,6 +13500,7 @@ export {
   MAX_DOT_TEXTURES,
   MAX_IMAGE_SIDE,
   MAX_LIVE_EFFECT_SOURCES,
+  MAX_PATH_SAMPLES,
   MAX_STICKER_STAMPS,
   MAX_ZOOM,
   MIN_CANVAS_SIDE,
@@ -13238,6 +13514,8 @@ export {
   PAINT_BRUSH_CATEGORIES,
   PAINT_BRUSH_ENGINES,
   PAINT_COLOR_JSON_SCHEMA,
+  PAINT_CONTRACT_FORMAT_VERSION,
+  PAINT_DOCUMENT_JSON_SCHEMA,
   PAINT_EFFECT_PLACES,
   PAINT_FORMAT,
   PAINT_GRADIENT_FULL_SPEED,
@@ -13251,6 +13529,7 @@ export {
   PAINT_GRADIENT_SPACES,
   PAINT_GRADIENT_SPACE_LABELS,
   PAINT_SCHEMA_VERSION,
+  PAINT_SHORTCUTS,
   PAINT_SOURCE_JSON_SCHEMA,
   PAINT_TARGET,
   PAINT_TOOLS,
@@ -13265,6 +13544,7 @@ export {
   PARTICLE_KIND_LABELS,
   PARTICLE_RENDERS,
   PARTICLE_RENDER_LABELS,
+  PATH_STROKE_TAPERS,
   PaintCanvasPresenter,
   PaintDabStroke,
   PaintDirector,
@@ -13425,9 +13705,11 @@ export {
   overPixels,
   padSampleRadius,
   paintAgentStrokePoints,
+  paintContracts,
   paintGradientMappingFor,
   paintPlaybackPanel,
   paintProposalGhost,
+  paintShortcutFor,
   paintSourceColor,
   paintSourceCss,
   paintToMultiColor,
@@ -13473,6 +13755,7 @@ export {
   sampleArt,
   sampleEffectAt,
   sampleEffectField,
+  samplePath,
   samplePressure,
   scalePaintGradient,
   scaleStencil,

package/dist/paint-editor/path-samples.d.cts

@@ -0,0 +1,19 @@
+/**
+ * Pen samples along vector path data, so a path can be brushed like a hand-drawn stroke
+ * (`strokePath`, the `stroke_path` tool): each subpath becomes one stroke, sampled at an even
+ * spacing, with an optional pressure profile spread along its length (a taper).
+ */
+import type { PenPoint } from './engine.cjs';
+/** The most samples one subpath may have (the stroke tools' point limit). */
+export declare const MAX_PATH_SAMPLES = 20000;
+export interface PathSampleOptions {
+    /** Distance between samples in document pixels (default 2). */
+    spacing?: number;
+    /** Pressure along each subpath, spread evenly from its start to its end (default full pressure). */
+    pressure?: readonly number[];
+}
+/**
+ * Samples SVG path data (document pixels) into pen points, one array per subpath. Closed
+ * subpaths end where they start. Throws a sentence when the path has nothing to brush.
+ */
+export declare function samplePath(d: string, options?: PathSampleOptions): PenPoint[][];

package/dist/paint-editor/path-samples.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pen samples along vector path data, so a path can be brushed like a hand-drawn stroke
+ * (`strokePath`, the `stroke_path` tool): each subpath becomes one stroke, sampled at an even
+ * spacing, with an optional pressure profile spread along its length (a taper).
+ */
+import type { PenPoint } from './engine.js';
+/** The most samples one subpath may have (the stroke tools' point limit). */
+export declare const MAX_PATH_SAMPLES = 20000;
+export interface PathSampleOptions {
+    /** Distance between samples in document pixels (default 2). */
+    spacing?: number;
+    /** Pressure along each subpath, spread evenly from its start to its end (default full pressure). */
+    pressure?: readonly number[];
+}
+/**
+ * Samples SVG path data (document pixels) into pen points, one array per subpath. Closed
+ * subpaths end where they start. Throws a sentence when the path has nothing to brush.
+ */
+export declare function samplePath(d: string, options?: PathSampleOptions): PenPoint[][];

package/dist/paint-editor/stamp-tip.d.cts

@@ -43,3 +43,20 @@ export declare function brushStickerRefs(brush: {
         dotTextures: readonly string[];
     };
 }): string[];
+/**
+ * Spray marks: the droplets of dab `d`, spread evenly over its disc, each a fraction `size` of
+ * the tip (with ±40% variation) and turned at random. Seeded by the stroke `seed`, the dab's
+ * index and its travel, so replays lay the same droplets.
+ */
+export declare function sprayDroplets<D extends {
+    x: number;
+    y: number;
+    radius: number;
+    roundness: number;
+    angle: number;
+    index: number;
+    travel: number;
+}>(d: D, spray: {
+    density: number;
+    size: number;
+}, seed: number): D[];