@pixerate/editor 0.138.0 → 0.139.0

package/dist/vector/index.js

@@ -38,7 +38,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-OV7253FC.js";
+} from "../chunk-NI6RORDS.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -47,6 +47,7 @@ import {
   VECTOR_BLEND_MODES,
   VECTOR_BLEND_MODE_LABELS,
   VECTOR_BLEND_SPACINGS,
+  VECTOR_BRUSHSTROKE_MAX_SEED,
   VECTOR_BRUSHSTROKE_SCALE,
   VECTOR_CHARACTER_STYLE_KEYS,
   VECTOR_CONNECTOR_ROUTES,
@@ -259,6 +260,7 @@ import {
   pressureWidthProfile,
   puckerBloatPaths,
   pullWarpMesh,
+  randomVectorBrushstrokeSeed,
   rectSubpath,
   removeAnchors,
   removeVectorFreeformPoint,
@@ -286,6 +288,7 @@ import {
   sampleVectorGradientAt,
   sampleVectorPaintDefAt,
   sanitizeVectorBrushstroke,
+  sanitizeVectorBrushstrokePaper,
   sanitizeVectorConnector,
   sanitizeVectorEffects,
   sanitizeVectorFills,
@@ -356,6 +359,7 @@ import {
   vectorBoxMatrix,
   vectorBrushstrokeBrush,
   vectorBrushstrokeBrushes,
+  vectorBrushstrokeCharacterError,
   vectorBrushstrokeImages,
   vectorBrushstrokeReach,
   vectorChildAppearanceShapes,
@@ -503,7 +507,7 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-V45ZTW4R.js";
+} from "../chunk-TJBYBSTN.js";
 import "../chunk-CPSMARTX.js";
 import {
   createProvenance
@@ -539,7 +543,9 @@ import {
   resolveEffectValues
 } from "../chunk-QFSTQHZY.js";
 import "../chunk-4FX5ACVG.js";
-import "../chunk-PQFVLOMR.js";
+import {
+  GRAIN_PATTERNS
+} from "../chunk-PQFVLOMR.js";
 import "../chunk-63AZAUSN.js";
 import {
   bytesToBase64,
@@ -3938,7 +3944,7 @@ function getVectorAppearancePanel(state) {
     ...isVectorBrushstrokeLayer(l) ? (() => {
       const b = l.brush;
       const preset = vectorBrushstrokeBrush(b.brushId);
-      return { brushstroke: { brushId: b.brushId, name: preset.name, size: b.size ?? preset.tip.size } };
+      return { brushstroke: { brushId: b.brushId, name: preset.name, size: b.size ?? preset.tip.size, ...b.seed !== void 0 ? { seed: b.seed } : {}, grain: b.seed !== void 0 && b.paper !== null } };
     })() : (l.kind ?? "paint") !== "paint" ? { unknownKind: String(l.kind) } : {},
     editing: edit.target === kind && (edit.layer === null ? index === count - 1 : edit.layer === index)
   });
@@ -8793,12 +8799,15 @@ var VectorEditorController = class _VectorEditorController {
    * brush `brushId` from the paint editor's library (`vectorBrushstrokeBrushes`), `size` document
    * units across (default the brush's own), an optional `pressure` profile along the length, in
    * `color` (default the top stroke's paint, else black) at `opacity`. At the top of the stroke
-   * stack or at `index`. One undo step.
+   * stack or at `index`. A `seed` gives it the brush's character (jitter and the grain of `paper`,
+   * `null` for none); without one it renders plain. One undo step.
    */
   addBrushstroke(brush, options = {}) {
     const clean = sanitizeVectorBrushstroke(brush);
     if (!clean) return { ok: false, message: `Unknown brush "${brush?.brushId}": use one of ${vectorBrushstrokeBrushes().map((b) => b.id).join(", ")}.` };
     if (brush.size !== void 0 && !(brush.size > 0 && brush.size <= 500)) return { ok: false, message: "size must be above 0 and at most 500 (document units)." };
+    const characterError = vectorBrushstrokeCharacterError(brush);
+    if (characterError) return { ok: false, message: characterError };
     if (options.color !== void 0 && !parseVectorColor(options.color)) return { ok: false, message: `"${options.color}" is not a colour.` };
     if (options.opacity !== void 0 && !(options.opacity >= 0 && options.opacity <= 1)) return { ok: false, message: "opacity must be from 0 to 1." };
     return this.editStacks("stroke", options.ids, "Add Brushstroke", (stack, path) => {
@@ -8811,15 +8820,18 @@ var VectorEditorController = class _VectorEditorController {
   }
   /**
    * Changes brushstroke layer `index` (in the stroke stack, 0 is the bottom) of the selected (or
-   * given) paths: another brush, size, pressure profile (null removes it), colour or opacity.
-   * Fails, changing nothing, when that layer is not a brushstroke. With `merge`, consecutive edits
-   * fold into one undo step.
+   * given) paths: another brush, size, pressure profile (null removes it), colour or opacity, the
+   * character `seed` (null removes it: plain dabs) or the `paper` (replaced whole: `null` for no
+   * grain, `{}` for the default paper). Fails, changing nothing, when that layer is not a
+   * brushstroke. With `merge`, consecutive edits fold into one undo step.
    */
   setBrushstroke(index, patch, options = {}) {
     if (patch.brushId !== void 0 && !vectorBrushstrokeBrush(patch.brushId)) return { ok: false, message: `Unknown brush "${patch.brushId}": use one of ${vectorBrushstrokeBrushes().map((b) => b.id).join(", ")}.` };
     if (patch.size !== void 0 && patch.size !== null && !(patch.size > 0 && patch.size <= 500)) return { ok: false, message: "size must be above 0 and at most 500 (document units)." };
     if (patch.color !== void 0 && !parseVectorColor(patch.color)) return { ok: false, message: `"${patch.color}" is not a colour.` };
     if (patch.opacity !== void 0 && !(patch.opacity >= 0 && patch.opacity <= 1)) return { ok: false, message: "opacity must be from 0 to 1." };
+    const characterError = vectorBrushstrokeCharacterError({ ...patch.seed !== null && patch.seed !== void 0 ? { seed: patch.seed } : {}, ...patch.paper !== void 0 ? { paper: patch.paper } : {} });
+    if (characterError) return { ok: false, message: characterError };
     const merge = options.merge === true ? `brushstroke:${index}` : options.merge || void 0;
     return this.editStacks(
       "stroke",
@@ -8833,6 +8845,9 @@ var VectorEditorController = class _VectorEditorController {
         else if (patch.size !== void 0) brush.size = patch.size;
         if (patch.pressure === null) delete brush.pressure;
         else if (patch.pressure !== void 0) brush.pressure = patch.pressure;
+        if (patch.seed === null) delete brush.seed;
+        else if (patch.seed !== void 0) brush.seed = patch.seed;
+        if (patch.paper !== void 0) brush.paper = patch.paper;
         const next = { ...layer, brush: sanitizeVectorBrushstroke(brush) ?? layer.brush, ...patch.color ? { paint: patch.color } : {}, ...patch.opacity !== void 0 ? { opacity: patch.opacity } : {} };
         return stack.map((l, i) => i === index ? next : l);
       },
@@ -16279,6 +16294,17 @@ function createVectorCommands(controller, options = {}) {
       }
     }
   ];
+  const BRUSH_SEED = { type: "integer", minimum: 0, maximum: VECTOR_BRUSHSTROKE_MAX_SEED };
+  const BRUSH_PAPER = {
+    type: "object",
+    properties: {
+      pattern: { type: "string", enum: [...GRAIN_PATTERNS], description: 'Grain pattern (default "sanded", a fine even tooth; "rough" and "cold-pressed" for watercolour paper, "canvas" and "linen" for a weave).' },
+      seed: { ...BRUSH_SEED, description: "Grain seed: another seed gives another sheet of the same paper (default 1)." },
+      scale: { type: "number", minimum: 0.25, maximum: 8, description: "Grain scale: 1 is the pattern's natural size, 2 twice as coarse (default 1)." },
+      depth: { type: "number", minimum: 0, maximum: 1, description: "How deep the grain is 0\u20131, times the brush's own grain response (default 0.5)." }
+    },
+    additionalProperties: false
+  };
   const brushstrokeCommands = () => [
     {
       ...base,
@@ -16295,7 +16321,7 @@ function createVectorCommands(controller, options = {}) {
       id: `${prefix}addBrushstroke`,
       label: "Add Brushstroke\u2026",
       keywords: ["brushstroke", "brush", "natural media", "pencil line", "chalk", "sketchy", "hand-drawn", "ink stroke"],
-      description: "Paints paths (`ids`, default the selection; groups: every path inside) with a natural-media brush along their outline, as a stroke layer of kind brushstroke: `brushId` from vector.listBrushes, `size` (document units), an optional `pressure` profile (0\u20131 values spread from start to end, e.g. [0.2, 1, 0.2] for a tapered stroke), `color` and `opacity`. The path stays editable; the strokes follow it. One undo step. Returns { paths: [{ id, strokes }] } (the brushstroke is a stroke layer; change it with vector.setBrushstroke, remove it with vector.removeStroke).",
+      description: "Paints paths (`ids`, default the selection; groups: every path inside) with a natural-media brush along their outline, as a stroke layer of kind brushstroke: `brushId` from vector.listBrushes, `size` (document units), an optional `pressure` profile (0\u20131 values spread from start to end, e.g. [0.2, 1, 0.2] for a tapered stroke), `color` and `opacity`. Pass a `seed` for the brush's character (seeded size, angle, opacity and scatter jitter plus a paper grain: what makes pencil, pastel and charcoal look real), with `paper` to choose the grain or null for none; without a seed the brush paints plain, even dabs. The path stays editable; the strokes follow it. One undo step. Returns { paths: [{ id, strokes }] } (the brushstroke is a stroke layer; change it with vector.setBrushstroke, remove it with vector.removeStroke).",
       params: {
         type: "object",
         properties: {
@@ -16305,7 +16331,9 @@ function createVectorCommands(controller, options = {}) {
           pressure: { type: "array", items: { type: "number", minimum: 0, maximum: 1 }, minItems: 1, maxItems: 64, description: "Pressure 0\u20131 along the length, spread evenly from start to end (default: full pressure)." },
           color: { type: "string", description: "CSS colour (default: the path's stroke colour, else black)." },
           opacity: { type: "number", minimum: 0, maximum: 1, description: "Layer opacity 0\u20131 (default 1)." },
-          index: { type: "integer", minimum: 0, description: "Position in the stroke stack, 0 the bottom (default: on top)." }
+          index: { type: "integer", minimum: 0, description: "Position in the stroke stack, 0 the bottom (default: on top)." },
+          seed: { ...BRUSH_SEED, description: "Character seed 0\u20132147483647: turns on the brush's jitter and paper grain; the same seed always renders the same stroke (default: none, plain dabs)." },
+          paper: { anyOf: [BRUSH_PAPER, { type: "null" }], description: "With `seed`: the paper the grain comes from { pattern, seed, scale, depth }, or null for jitter without grain (default: the sanded paper)." }
         },
         required: ["brushId"],
         additionalProperties: false
@@ -16316,7 +16344,13 @@ function createVectorCommands(controller, options = {}) {
         const targets = params.ids ?? controller.getState().selection;
         check2(
           controller.addBrushstroke(
-            { brushId: params.brushId, ...params.size !== void 0 ? { size: params.size } : {}, ...params.pressure ? { pressure: params.pressure } : {} },
+            {
+              brushId: params.brushId,
+              ...params.size !== void 0 ? { size: params.size } : {},
+              ...params.pressure ? { pressure: params.pressure } : {},
+              ...params.seed !== void 0 ? { seed: params.seed } : {},
+              ...params.paper !== void 0 ? { paper: params.paper } : {}
+            },
             { ...params.ids ? { ids: params.ids } : {}, ...params.index !== void 0 ? { index: params.index } : {}, ...params.color ? { color: params.color } : {}, ...params.opacity !== void 0 ? { opacity: params.opacity } : {} }
           )
         );
@@ -16333,7 +16367,7 @@ function createVectorCommands(controller, options = {}) {
       id: `${prefix}setBrushstroke`,
       label: "Edit Brushstroke\u2026",
       keywords: ["brushstroke", "brush", "size", "pressure", "taper"],
-      description: "Changes the brushstroke at stroke layer `index` of path `id` (vector.getAppearance lists strokes; 0 is the bottom): `brushId`, `size` (null: the brush's own), `pressure` (null: full pressure), `color`, `opacity`. Pass at least one. One undo step. Returns { id, strokes }.",
+      description: "Changes the brushstroke at stroke layer `index` of path `id` (vector.getAppearance lists strokes; 0 is the bottom): `brushId`, `size` (null: the brush's own), `pressure` (null: full pressure), `color`, `opacity`, `seed` (turns the brush's character on; null: plain dabs) and `paper` (replaced whole; null: no grain; {}: the default paper). Pass at least one. One undo step. Returns { id, strokes }.",
       params: {
         type: "object",
         properties: {
@@ -16343,7 +16377,9 @@ function createVectorCommands(controller, options = {}) {
           size: { type: ["number", "null"], description: "Diameter in document units, or null for the brush's own." },
           pressure: { type: ["array", "null"], items: { type: "number", minimum: 0, maximum: 1 }, description: "Pressure profile 0\u20131 from start to end, or null for full pressure." },
           color: { type: "string", description: "CSS colour." },
-          opacity: { type: "number", minimum: 0, maximum: 1, description: "Layer opacity 0\u20131." }
+          opacity: { type: "number", minimum: 0, maximum: 1, description: "Layer opacity 0\u20131." },
+          seed: { anyOf: [BRUSH_SEED, { type: "null" }], description: "Character seed 0\u20132147483647 (jitter and paper grain; a new seed gives a new take on the same stroke), or null for plain dabs." },
+          paper: { anyOf: [BRUSH_PAPER, { type: "null" }], description: "The paper the grain comes from { pattern, seed, scale, depth } (applies with a seed), null for no grain, or {} for the default sanded paper." }
         },
         required: ["id", "index"],
         additionalProperties: false
@@ -16351,7 +16387,7 @@ function createVectorCommands(controller, options = {}) {
       undoable: true,
       run: (_ctx, params) => {
         const { id, index, ...patch } = params;
-        if (!Object.keys(patch).length) fail("Pass at least one of brushId, size, pressure, color, opacity.");
+        if (!Object.keys(patch).length) fail("Pass at least one of brushId, size, pressure, color, opacity, seed, paper.");
         layerIndex(id, "stroke", index);
         check2(controller.setBrushstroke(index, patch, { ids: [id] }));
         return stackResult(id, "stroke");
@@ -18571,6 +18607,7 @@ export {
   VECTOR_BLEND_MODE_MENU,
   VECTOR_BLEND_SPACINGS,
   VECTOR_BLEND_SPACING_LABELS,
+  VECTOR_BRUSHSTROKE_MAX_SEED,
   VECTOR_BRUSHSTROKE_SCALE,
   VECTOR_BUILDER_HATCH_GAP,
   VECTOR_CHARACTER_STYLE_KEYS,
@@ -18907,6 +18944,7 @@ export {
   pullWarpMesh as pullVectorMesh,
   purgeVectorConstraints,
   quantizeVectorTraceColors,
+  randomVectorBrushstrokeSeed,
   recognizeInkShape,
   rectSubpath,
   refineMorphContour,
@@ -18946,6 +18984,7 @@ export {
   sampleVectorGradientAt,
   sampleVectorPaintDefAt,
   sanitizeVectorBrushstroke,
+  sanitizeVectorBrushstrokePaper,
   sanitizeVectorConnector,
   sanitizeVectorEffects,
   sanitizeVectorFills,
@@ -19041,6 +19080,7 @@ export {
   vectorBoxMatrix,
   vectorBrushstrokeBrush,
   vectorBrushstrokeBrushes,
+  vectorBrushstrokeCharacterError,
   vectorBrushstrokeImages,
   vectorBrushstrokeReach,
   vectorBuilderErasedEdges,