@pixerate/editor 0.260.0 → 0.261.0

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

@@ -57,4 +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,4 +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

@@ -150,7 +150,11 @@ 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
@@ -5221,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) {
@@ -7857,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.");
@@ -11579,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",
@@ -12480,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 },
@@ -13270,6 +13405,7 @@ function uiTables() {
     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: {
@@ -13364,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,
@@ -13407,6 +13544,7 @@ export {
   PARTICLE_KIND_LABELS,
   PARTICLE_RENDERS,
   PARTICLE_RENDER_LABELS,
+  PATH_STROKE_TAPERS,
   PaintCanvasPresenter,
   PaintDabStroke,
   PaintDirector,
@@ -13617,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/ui.d.cts

@@ -250,6 +250,12 @@ export declare function toggleStamp(stamps: readonly StampKind[], stamp: StampKi
  * else adds it while there are fewer than `MAX_DOT_TEXTURES`. Empty means round dots.
  */
 export declare function toggleDotTexture(textures: readonly StampKind[], stamp: StampKind): StampKind[];
+/** Pressure profiles the "Brush a path" panel offers for `strokePath` (`pressure` undefined: even). */
+export declare const PATH_STROKE_TAPERS: ReadonlyArray<{
+    id: string;
+    label: string;
+    pressure?: readonly number[];
+}>;
 /** The sticker panel's sliders for the selected sticker. */
 /** The brush sliders of a picked stroke on a stroke layer (paths into its brush; see `updateStroke`). */
 export declare const STROKE_SLIDERS: readonly SliderControl[];

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

@@ -250,6 +250,12 @@ export declare function toggleStamp(stamps: readonly StampKind[], stamp: StampKi
  * else adds it while there are fewer than `MAX_DOT_TEXTURES`. Empty means round dots.
  */
 export declare function toggleDotTexture(textures: readonly StampKind[], stamp: StampKind): StampKind[];
+/** Pressure profiles the "Brush a path" panel offers for `strokePath` (`pressure` undefined: even). */
+export declare const PATH_STROKE_TAPERS: ReadonlyArray<{
+    id: string;
+    label: string;
+    pressure?: readonly number[];
+}>;
 /** The sticker panel's sliders for the selected sticker. */
 /** The brush sliders of a picked stroke on a stroke layer (paths into its brush; see `updateStroke`). */
 export declare const STROKE_SLIDERS: readonly SliderControl[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.260.0",
+  "version": "0.261.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-paint-editor/SKILL.md

@@ -109,6 +109,7 @@ the pitfalls, and uses the tools below.
 - **Give points a time `t`** (milliseconds, about 8..16 ms apart for natural speed) when using an ink or brush pen: velocity dynamics thin fast strokes. Without `t` there is no velocity effect.
 - **Tilt** (`altitude` near 0.3..0.6 radians with an `azimuth`) turns a pencil into broad side shading; upright points draw a fine line.
 - **Space points** about a third of the brush size apart or closer; the brush fills in dabs between them. Long smooth curves need more points than straight lines.
+- **Brush geometry with `stroke_path`**: for clean curves, circles, outlines and lettering, give SVG path data and a `pressure` taper instead of hundreds of points; the brush keeps its grain and character. Send the shape as one path with several subpaths to keep it one undo step.
 - **Use `rotation: "stroke"`** for flat tips (pastel, charcoal, chisel marker) so the mark turns with the path; `fixed` for calligraphic nibs.
 - **Blending tools**:
   - `blender`: `strength` 0.3..0.6 for soft transitions, `distance` 0.2..0.5 (fraction of the tip) for how far colours travel. Keep `mixing: "pigment"` for painterly blends; `rgb` blends like a soft blur. Work along an edge in short strokes rather than over everything.
@@ -320,6 +321,7 @@ Listing, saving, sharing and previewing brushes are the brush library's tools (`
 | Tool | Use |
 | --- | --- |
 | `paint_stroke` | Paint one stroke through `points` (document px; `pressure` 0..1, `t` ms, `tiltX` / `tiltY` or `altitude` / `azimuth`, `twist`) with `brushId` (default the active brush), optional per-stroke `brush` facet changes (as `set_brush` takes), `color` or `paint` (a gradient for this stroke), `layerId`, `seed`, `snapToPerspective`. The symmetry guide adds its copies; a sampling tracing image supplies the colour when `color` is missing. Returns `layerId`, `bounds`, `dabs`, `strokeId` and, for brushes that pick up paint, `mixerLoad` (what the brush carries now). Refused on locked, hidden or group layers, with the fix in the message. |
+| `stroke_path` | Brush SVG path data (`path`, document px; M, L, C, Q, A, Z…) with the active brush or `brushId` / `brush`, as if drawn along it by hand: each subpath one recorded stroke, sampled every `spacing` px (default 2), with a `pressure` profile spread along each subpath (`[0.2, 1, 0.2]` tapers both ends). One undo step. Returns `layerId`, `bounds`, `dabs` and `strokeIds` (for `replay_strokes`, `update_stroke`). Use it for clean curves, outlines of shapes and lettering guides instead of working out points; use `paint_stroke` when the marks need time or tilt. |
 | `list_strokes` | Read the recorded strokes, oldest first (default the last 100): id, layer, brush, colour, point count, seed, bounds, `live`. With `ids`, their points too; with `layerId`, one layer's. With `live: true`, the editable strokes of stroke layers as they are now, bottom first: the ids for the stroke layer tools. |
 | `get_live_stroke` | Read the stroke the user is painting right now (layer, brush, colour, samples so far; `live: false` when none). For painting along with the user; hosts stream the samples live. |
 | `stroke_at` | Read the top-most stroke of a stroke layer that painted the pixel at `x`, `y`, or null. Use it to pick one stroke among overlapping ones. |

package/skills/pixerate-paint-sketch-to-finish/SKILL.md

@@ -39,7 +39,9 @@ This skill is the method. `pixerate-paint-editor` has the full tool reference.
    reference.
    **Check:** `list_strokes` shows pencil strokes on the Sketch layer.
 3. **Ink.** `add_layer` "Ink" above it; `ink-pen` or `brush-pen`, dark colour, long strokes with
-   points that carry `pressure` (lighter at the ends) and `t` for speed dynamics.
+   points that carry `pressure` (lighter at the ends) and `t` for speed dynamics. For clean
+   geometric lines (curves, circles, panel borders) use `stroke_path` with SVG path data and a
+   `pressure` taper such as `[0.3, 1, 0.3]`.
    **Check:** `pick_color` on a line is dark.
 4. **Hide the sketch.** `update_layer` the Sketch layer `visible: false` (or lower its `opacity`
    while inking, then hide it).
@@ -61,6 +63,7 @@ This skill is the method. `pixerate-paint-editor` has the full tool reference.
 | --- | --- |
 | Sketch | `pencil-hb`, light colour, own layer, hidden at the end |
 | Line art | `ink-pen` (even), `brush-pen` (swelling); own layer on top |
+| Clean geometric lines (curves, circles, borders) | `stroke_path` with SVG path data and a `pressure` taper, on the Ink layer |
 | Flats | `marker` or a flat brush on a layer under the ink |
 | Patterned or textured flats (sky, gradient, galaxy) | `set_effect_paint` with a provider generator, then a flat dry brush on the Flats layer; `set_color` after |
 | Shadows | Clipped layer, `multiply` or `shadow`, a cool colour |
@@ -98,6 +101,7 @@ clipped: true }` → `set_brush` `airbrush` → paint the shadow side.
 - `set_paper`, `fill_layer`: the ground and backgrounds
 - `add_layer`, `update_layer`, `move_layer`, `remove_layer`: one layer per pass; hide, clip, blend
 - `set_brush`, `set_color`, `paint_stroke`, `replay_strokes`: sketch, ink, flats and shading
+- `stroke_path`: clean geometric line art from SVG path data
 - `search_effects`, `describe_effect`, `set_effect_paint`: flats painted with a provider effect
 - `set_symmetry`, `set_perspective_guide`, `set_tracing_image`: construction guides
 - `undo_paint`: take back a step