@pixerate/editor 0.270.0 → 0.271.0

package/dist/image-editor/index.js

@@ -8,7 +8,7 @@ import {
   parseOpenTypeFont,
   removeAnchorsKeepingShape,
   traceField
-} from "../chunk-THBJHPUL.js";
+} from "../chunk-YNFSH72F.js";
 import {
   ADJUSTMENT_KEYS,
   ADJUSTMENT_KINDS,
@@ -409,7 +409,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-4YSPQGZW.js";
+} from "../chunk-B5W677L7.js";
 import {
   flattenPath,
   rasterizeCoverage
@@ -683,7 +683,7 @@ import {
   warpMeshParamAt,
   warpMeshRows,
   warpPresetMesh
-} from "../chunk-FUDP5QBB.js";
+} from "../chunk-TNHDCP4R.js";
 import {
   IMAGE_PROFILE,
   checkBrush,
@@ -706,7 +706,7 @@ import {
 import "../chunk-SZTI6EER.js";
 import {
   EffectRendererPool
-} from "../chunk-EHLOCVWB.js";
+} from "../chunk-T2URHAJX.js";
 import {
   EffectUnsupportedError,
   EffectsSlot,

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

@@ -378,6 +378,17 @@ export declare class PaintEditorController {
     private paintEpoch;
     /** Rendered effect paints by `effectPaintKey` (most recently used last). */
     private readonly effectPaintPixels;
+    /** Primary path control name (`format: 'svg-path'`) per effect id, learned from `describeEffect`. */
+    private readonly effectPathControls;
+    /** How many renders the running batch needs together (`prepareEffectPaints`; a synchronous replay reads them all). */
+    private effectPaintBatch;
+    /** The hand-painted stroke waiting for its path render (`finishPathStroke`), or `null`. */
+    private pathStroke;
+    /**
+     * The hand-painted path stroke's live preview: the effect rendered along the path drawn so far
+     * (one render at a time; the newest path when it lands), repainted into the stroke as it lands.
+     */
+    private pathPreview;
     private mixerLoad;
     private view;
     private hand;
@@ -739,7 +750,11 @@ export declare class PaintEditorController {
         layerId: string;
         source: PaintEffectSource;
     }>;
-    /** At most this many rendered effect paints are kept (each is canvas-sized). */
+    /**
+     * At most this many rendered effect paints are kept (each is canvas-sized), more only while
+     * something needs them all: a replay's batch, and the path-mapped strokes on stroke layers,
+     * which each have a render of their own and are redrawn synchronously.
+     */
     private static readonly EFFECT_PAINT_CACHE;
     /** The effect paint strokes use (or the one rendering), or `null`. */
     getEffectPaint(): PaintEffectPaint | null;
@@ -748,8 +763,10 @@ export declare class PaintEditorController {
      * size, and brushes then take each pixel's colour (and alpha) from it, fixed to the canvas, as if
      * painting a hidden picture into view. `setColor` and `setPaint` go back to colour. Editor state,
      * not an undo step. Strokes that would paint with it throw while it renders. Returns the paint.
-     * With `map: { by: 'stroke' }` the effect lies along each stroke instead of the canvas; with
-     * `live`, strokes on a stroke layer keep playing it (see `setEffectPlayback`).
+     * With `map: { by: 'stroke' }` the effect lies along each stroke as a strip; with
+     * `map: { by: 'path' }` an effect with a path control (`format: 'svg-path'`) draws itself along
+     * each stroke's centreline in canvas pixels; with `live`, strokes on a stroke layer keep playing
+     * it (see `setEffectPlayback`).
      */
     setEffectPaint(source: {
         effect: string;
@@ -760,15 +777,47 @@ export declare class PaintEditorController {
     }): Promise<PaintEffectPaint>;
     /** The rendered pixels of an effect paint at the current canvas size, or `null` when it has not been rendered. */
     private effectPaintImage;
+    private cacheEffectPaintPixels;
+    private cacheEffectPaintImage;
+    private trimEffectPaints;
+    /** Renders an effect paint on the caller's stack when its renderer is warm and has `renderSync`; otherwise `null`. */
+    private renderEffectPaintSync;
     /** Renders an effect paint at the canvas size into the cache (nothing when it is there already). */
     private renderEffectPaint;
+    /** Renders an effect paint at the canvas size without keeping it. */
+    private renderEffectPaintPixels;
     /**
      * Renders effect paints that are not rendered yet (strokes and replays need them rendered
      * first, since strokes are synchronous). Throws naming the effect and provider when one cannot be.
      */
     prepareEffectPaints(paints: Iterable<PaintEffectPaint>): Promise<void>;
+    /**
+     * Renders the path-mapped effect paint for one or more strokes' points before a synchronous
+     * stroke call runs (`paint_stroke` and `stroke_path` do; `paintStroke` throws without it on a
+     * provider that can't render synchronously). For a stroke layer edit, see `prepareStrokeEdit`.
+     */
+    prepareStrokePathEffect(init: PaintStrokeInit, pointsList: readonly (readonly PenPoint[])[]): Promise<void>;
+    /**
+     * Renders what an edit of a stroke layer's stroke paints with (`updateStroke`, `editStrokePoints`):
+     * a new effect paint, or a path-mapped stroke's new path. Those calls are synchronous, and throw
+     * without it on a provider that can't render synchronously. Bad edits are left for them to refuse.
+     */
+    prepareStrokeEdit(id: string, edit: {
+        paint?: unknown;
+        points?: readonly PenPoint[];
+        transform?: StrokeVariation;
+    }): Promise<void>;
+    /** Whether `prepareStrokeEdit` has to be awaited before this edit can run. */
+    strokeEditNeedsRender(id: string, edit: {
+        paint?: unknown;
+        points?: readonly PenPoint[];
+        transform?: StrokeVariation;
+    }): boolean;
+    private strokeEditPaint;
+    /** A stroke edit's transform as an affine map, checked. */
+    private strokeTransform;
     /** Renders the effect paints of recorded strokes (default all of them) before a replay. */
-    prepareStrokeEffects(strokeIds?: readonly string[]): Promise<void>;
+    prepareStrokeEffects(strokeIds?: readonly string[], variation?: ReplayOptions): Promise<void>;
     /** A small preview of the effect paint (a PNG data URL `size` px wide), or `null` without a rendered one. */
     effectPaintThumbnail(size?: number): string | null;
     /**
@@ -945,8 +994,30 @@ export declare class PaintEditorController {
      * (one undo step) or `cancel()`.
      */
     beginStroke(init?: PaintStrokeInit): PaintStrokeSession;
+    /**
+     * Renders a hand-painted path stroke's effect along the path drawn so far and paints the stroke
+     * again with it when it lands, so the effect follows the pen while it draws. One render at a
+     * time: when one lands, the next takes the newest path. A failed render leaves the preview as it
+     * was; the render on release reports it.
+     */
+    private previewPathStroke;
     /** The current live stroke, if any. */
     get activeStroke(): PaintStrokeSession | null;
+    /**
+     * While a hand-painted stroke waits for its path render (`map: { by: 'path' }`), settles when it
+     * has landed and rejects if it could not (the stroke is dropped); `null` otherwise. Until then
+     * the editor is busy, as during a stroke, and shows the stroke as it was painted.
+     */
+    get strokeRendering(): Promise<void> | null;
+    /** The paint a finished hand-painted stroke must be painted again with, or `null` when it already painted with it. */
+    private pathStrokePaint;
+    /**
+     * Ends a hand-painted stroke with a path-mapped effect. Its whole path isn't known until now, so
+     * the live stroke was only a preview from renders along the path so far (`previewPathStroke`):
+     * nothing of it was committed. Paints it again with the path's own render, as one stroke and one undo step, at
+     * once if that can render synchronously and when the render lands if not.
+     */
+    private finishPathStroke;
     /** Runs a whole stroke against `doc` without touching the editor; returns the new document. */
     private runStroke;
     /** Paints one stroke from data (one undo step). */

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

@@ -378,6 +378,17 @@ export declare class PaintEditorController {
     private paintEpoch;
     /** Rendered effect paints by `effectPaintKey` (most recently used last). */
     private readonly effectPaintPixels;
+    /** Primary path control name (`format: 'svg-path'`) per effect id, learned from `describeEffect`. */
+    private readonly effectPathControls;
+    /** How many renders the running batch needs together (`prepareEffectPaints`; a synchronous replay reads them all). */
+    private effectPaintBatch;
+    /** The hand-painted stroke waiting for its path render (`finishPathStroke`), or `null`. */
+    private pathStroke;
+    /**
+     * The hand-painted path stroke's live preview: the effect rendered along the path drawn so far
+     * (one render at a time; the newest path when it lands), repainted into the stroke as it lands.
+     */
+    private pathPreview;
     private mixerLoad;
     private view;
     private hand;
@@ -739,7 +750,11 @@ export declare class PaintEditorController {
         layerId: string;
         source: PaintEffectSource;
     }>;
-    /** At most this many rendered effect paints are kept (each is canvas-sized). */
+    /**
+     * At most this many rendered effect paints are kept (each is canvas-sized), more only while
+     * something needs them all: a replay's batch, and the path-mapped strokes on stroke layers,
+     * which each have a render of their own and are redrawn synchronously.
+     */
     private static readonly EFFECT_PAINT_CACHE;
     /** The effect paint strokes use (or the one rendering), or `null`. */
     getEffectPaint(): PaintEffectPaint | null;
@@ -748,8 +763,10 @@ export declare class PaintEditorController {
      * size, and brushes then take each pixel's colour (and alpha) from it, fixed to the canvas, as if
      * painting a hidden picture into view. `setColor` and `setPaint` go back to colour. Editor state,
      * not an undo step. Strokes that would paint with it throw while it renders. Returns the paint.
-     * With `map: { by: 'stroke' }` the effect lies along each stroke instead of the canvas; with
-     * `live`, strokes on a stroke layer keep playing it (see `setEffectPlayback`).
+     * With `map: { by: 'stroke' }` the effect lies along each stroke as a strip; with
+     * `map: { by: 'path' }` an effect with a path control (`format: 'svg-path'`) draws itself along
+     * each stroke's centreline in canvas pixels; with `live`, strokes on a stroke layer keep playing
+     * it (see `setEffectPlayback`).
      */
     setEffectPaint(source: {
         effect: string;
@@ -760,15 +777,47 @@ export declare class PaintEditorController {
     }): Promise<PaintEffectPaint>;
     /** The rendered pixels of an effect paint at the current canvas size, or `null` when it has not been rendered. */
     private effectPaintImage;
+    private cacheEffectPaintPixels;
+    private cacheEffectPaintImage;
+    private trimEffectPaints;
+    /** Renders an effect paint on the caller's stack when its renderer is warm and has `renderSync`; otherwise `null`. */
+    private renderEffectPaintSync;
     /** Renders an effect paint at the canvas size into the cache (nothing when it is there already). */
     private renderEffectPaint;
+    /** Renders an effect paint at the canvas size without keeping it. */
+    private renderEffectPaintPixels;
     /**
      * Renders effect paints that are not rendered yet (strokes and replays need them rendered
      * first, since strokes are synchronous). Throws naming the effect and provider when one cannot be.
      */
     prepareEffectPaints(paints: Iterable<PaintEffectPaint>): Promise<void>;
+    /**
+     * Renders the path-mapped effect paint for one or more strokes' points before a synchronous
+     * stroke call runs (`paint_stroke` and `stroke_path` do; `paintStroke` throws without it on a
+     * provider that can't render synchronously). For a stroke layer edit, see `prepareStrokeEdit`.
+     */
+    prepareStrokePathEffect(init: PaintStrokeInit, pointsList: readonly (readonly PenPoint[])[]): Promise<void>;
+    /**
+     * Renders what an edit of a stroke layer's stroke paints with (`updateStroke`, `editStrokePoints`):
+     * a new effect paint, or a path-mapped stroke's new path. Those calls are synchronous, and throw
+     * without it on a provider that can't render synchronously. Bad edits are left for them to refuse.
+     */
+    prepareStrokeEdit(id: string, edit: {
+        paint?: unknown;
+        points?: readonly PenPoint[];
+        transform?: StrokeVariation;
+    }): Promise<void>;
+    /** Whether `prepareStrokeEdit` has to be awaited before this edit can run. */
+    strokeEditNeedsRender(id: string, edit: {
+        paint?: unknown;
+        points?: readonly PenPoint[];
+        transform?: StrokeVariation;
+    }): boolean;
+    private strokeEditPaint;
+    /** A stroke edit's transform as an affine map, checked. */
+    private strokeTransform;
     /** Renders the effect paints of recorded strokes (default all of them) before a replay. */
-    prepareStrokeEffects(strokeIds?: readonly string[]): Promise<void>;
+    prepareStrokeEffects(strokeIds?: readonly string[], variation?: ReplayOptions): Promise<void>;
     /** A small preview of the effect paint (a PNG data URL `size` px wide), or `null` without a rendered one. */
     effectPaintThumbnail(size?: number): string | null;
     /**
@@ -945,8 +994,30 @@ export declare class PaintEditorController {
      * (one undo step) or `cancel()`.
      */
     beginStroke(init?: PaintStrokeInit): PaintStrokeSession;
+    /**
+     * Renders a hand-painted path stroke's effect along the path drawn so far and paints the stroke
+     * again with it when it lands, so the effect follows the pen while it draws. One render at a
+     * time: when one lands, the next takes the newest path. A failed render leaves the preview as it
+     * was; the render on release reports it.
+     */
+    private previewPathStroke;
     /** The current live stroke, if any. */
     get activeStroke(): PaintStrokeSession | null;
+    /**
+     * While a hand-painted stroke waits for its path render (`map: { by: 'path' }`), settles when it
+     * has landed and rejects if it could not (the stroke is dropped); `null` otherwise. Until then
+     * the editor is busy, as during a stroke, and shows the stroke as it was painted.
+     */
+    get strokeRendering(): Promise<void> | null;
+    /** The paint a finished hand-painted stroke must be painted again with, or `null` when it already painted with it. */
+    private pathStrokePaint;
+    /**
+     * Ends a hand-painted stroke with a path-mapped effect. Its whole path isn't known until now, so
+     * the live stroke was only a preview from renders along the path so far (`previewPathStroke`):
+     * nothing of it was committed. Paints it again with the path's own render, as one stroke and one undo step, at
+     * once if that can render synchronously and when the render lands if not.
+     */
+    private finishPathStroke;
     /** Runs a whole stroke against `doc` without touching the editor; returns the new document. */
     private runStroke;
     /** Paints one stroke from data (one undo step). */

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

@@ -25,18 +25,19 @@ export interface PaintEffectPaint {
     /** Which moment of an animated effect, in ms. */
     time: number;
     /**
-     * How the effect lies on the paint: fixed to the canvas (missing, the default), or along each
-     * stroke (`by: 'stroke'`): the effect is rendered as a strip `length` px long and 256 px across,
-     * and each pixel takes the colour at (distance along the stroke, position across the tip).
+     * How the effect lies on the paint: fixed to the canvas (missing, the default), bent along each
+     * stroke (`by: 'stroke'`: rendered as a strip `length` px long and 256 px across), or along the
+     * stroke via the effect's own path control (`by: 'path'`: the stroke's centreline in canvas
+     * pixels is passed to its `format: 'svg-path'` control).
      */
-    map?: PaintEffectStrokeMap;
+    map?: PaintEffectMap;
     /**
      * Live: on a stroke layer the stroke keeps playing the effect (each frame drawn at the editor's
      * effect time); elsewhere it bakes the frame at `time` like any effect paint.
      */
     live?: boolean;
 }
-/** Effect paint laid along the stroke. */
+/** Effect paint laid along the stroke as a bent strip. */
 export interface PaintEffectStrokeMap {
     by: 'stroke';
     /** Strip length: px of stroke per repeat of the effect, 16..4096. */
@@ -44,10 +45,34 @@ export interface PaintEffectStrokeMap {
     /** Past the strip's end: start again, run back (mirror), or hold the last colour (clamp). */
     repeat: 'repeat' | 'mirror' | 'clamp';
 }
+/** Effect paint whose own path control (`format: 'svg-path'`) receives each stroke's centreline in canvas pixels. */
+export interface PaintEffectPathMap {
+    by: 'path';
+}
+export type PaintEffectMap = PaintEffectStrokeMap | PaintEffectPathMap;
 /** How tall a stroke-mapped effect strip is rendered (the position across the tip maps onto it). */
 export declare const EFFECT_STRIP_HEIGHT = 256;
 export declare const EFFECT_MAP_REPEATS: readonly ["repeat", "mirror", "clamp"];
-/** The size an effect paint renders at: the canvas, or its strip. */
+/** Maximum number of centreline points passed to a path effect control; longer strokes are resampled to this count. */
+export declare const MAX_EFFECT_PATH_POINTS = 256;
+/**
+ * The stroke's centreline as `[x0, y0, x1, y1, …]` in canvas pixels for a path control
+ * (`format: 'svg-path'`). Consecutive duplicate points are collapsed, single-point taps are doubled
+ * so path renderers receive a valid segment, and strokes longer than `maxPoints` are evenly
+ * resampled by arc length rather than refused.
+ */
+export declare function strokePathPoints(points: readonly {
+    x: number;
+    y: number;
+}[], maxPoints?: number): number[];
+/** Which control of `values` holds a path when the effect description is not at hand. */
+export declare function inferEffectPathControl(values: Record<string, EffectValue>): string;
+/** A copy of a path-mapped effect paint with the stroke's centreline written into its path control. */
+export declare function withStrokePath(paint: PaintEffectPaint, points: readonly {
+    x: number;
+    y: number;
+}[], control?: string): PaintEffectPaint;
+/** The size an effect paint renders at: the canvas, or its strip when bent along the stroke. */
 export declare function effectPaintSize(p: PaintEffectPaint, canvas: {
     width: number;
     height: number;
@@ -55,8 +80,8 @@ export declare function effectPaintSize(p: PaintEffectPaint, canvas: {
     width: number;
     height: number;
 };
-/** A stroke map checked and rounded; throws a sentence naming the bad field. */
-export declare function readEffectStrokeMap(raw: unknown): PaintEffectStrokeMap | undefined;
+/** A stroke or path map checked and rounded; throws a sentence naming the bad field. */
+export declare function readEffectStrokeMap(raw: unknown): PaintEffectMap | undefined;
 /**
  * Straight-alpha RGBA an effect paint was rendered to: canvas-sized, or (with `map`) the strip
  * laid along each stroke.

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

@@ -25,18 +25,19 @@ export interface PaintEffectPaint {
     /** Which moment of an animated effect, in ms. */
     time: number;
     /**
-     * How the effect lies on the paint: fixed to the canvas (missing, the default), or along each
-     * stroke (`by: 'stroke'`): the effect is rendered as a strip `length` px long and 256 px across,
-     * and each pixel takes the colour at (distance along the stroke, position across the tip).
+     * How the effect lies on the paint: fixed to the canvas (missing, the default), bent along each
+     * stroke (`by: 'stroke'`: rendered as a strip `length` px long and 256 px across), or along the
+     * stroke via the effect's own path control (`by: 'path'`: the stroke's centreline in canvas
+     * pixels is passed to its `format: 'svg-path'` control).
      */
-    map?: PaintEffectStrokeMap;
+    map?: PaintEffectMap;
     /**
      * Live: on a stroke layer the stroke keeps playing the effect (each frame drawn at the editor's
      * effect time); elsewhere it bakes the frame at `time` like any effect paint.
      */
     live?: boolean;
 }
-/** Effect paint laid along the stroke. */
+/** Effect paint laid along the stroke as a bent strip. */
 export interface PaintEffectStrokeMap {
     by: 'stroke';
     /** Strip length: px of stroke per repeat of the effect, 16..4096. */
@@ -44,10 +45,34 @@ export interface PaintEffectStrokeMap {
     /** Past the strip's end: start again, run back (mirror), or hold the last colour (clamp). */
     repeat: 'repeat' | 'mirror' | 'clamp';
 }
+/** Effect paint whose own path control (`format: 'svg-path'`) receives each stroke's centreline in canvas pixels. */
+export interface PaintEffectPathMap {
+    by: 'path';
+}
+export type PaintEffectMap = PaintEffectStrokeMap | PaintEffectPathMap;
 /** How tall a stroke-mapped effect strip is rendered (the position across the tip maps onto it). */
 export declare const EFFECT_STRIP_HEIGHT = 256;
 export declare const EFFECT_MAP_REPEATS: readonly ["repeat", "mirror", "clamp"];
-/** The size an effect paint renders at: the canvas, or its strip. */
+/** Maximum number of centreline points passed to a path effect control; longer strokes are resampled to this count. */
+export declare const MAX_EFFECT_PATH_POINTS = 256;
+/**
+ * The stroke's centreline as `[x0, y0, x1, y1, …]` in canvas pixels for a path control
+ * (`format: 'svg-path'`). Consecutive duplicate points are collapsed, single-point taps are doubled
+ * so path renderers receive a valid segment, and strokes longer than `maxPoints` are evenly
+ * resampled by arc length rather than refused.
+ */
+export declare function strokePathPoints(points: readonly {
+    x: number;
+    y: number;
+}[], maxPoints?: number): number[];
+/** Which control of `values` holds a path when the effect description is not at hand. */
+export declare function inferEffectPathControl(values: Record<string, EffectValue>): string;
+/** A copy of a path-mapped effect paint with the stroke's centreline written into its path control. */
+export declare function withStrokePath(paint: PaintEffectPaint, points: readonly {
+    x: number;
+    y: number;
+}[], control?: string): PaintEffectPaint;
+/** The size an effect paint renders at: the canvas, or its strip when bent along the stroke. */
 export declare function effectPaintSize(p: PaintEffectPaint, canvas: {
     width: number;
     height: number;
@@ -55,8 +80,8 @@ export declare function effectPaintSize(p: PaintEffectPaint, canvas: {
     width: number;
     height: number;
 };
-/** A stroke map checked and rounded; throws a sentence naming the bad field. */
-export declare function readEffectStrokeMap(raw: unknown): PaintEffectStrokeMap | undefined;
+/** A stroke or path map checked and rounded; throws a sentence naming the bad field. */
+export declare function readEffectStrokeMap(raw: unknown): PaintEffectMap | undefined;
 /**
  * Straight-alpha RGBA an effect paint was rendered to: canvas-sized, or (with `map`) the strip
  * laid along each stroke.

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

@@ -80,6 +80,10 @@ export declare class PaintEffectsRenderer {
         width: number;
         height: number;
     }, request: EffectRenderRequest): Promise<EffectPixels>;
+    renderSync(provider: EffectProvider, id: string, size: {
+        width: number;
+        height: number;
+    }, request: EffectRenderRequest): EffectPixels | null;
     dispose(): void;
 }
 /** A saved effect source, or `null` when it is not one. */

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

@@ -80,6 +80,10 @@ export declare class PaintEffectsRenderer {
         width: number;
         height: number;
     }, request: EffectRenderRequest): Promise<EffectPixels>;
+    renderSync(provider: EffectProvider, id: string, size: {
+        width: number;
+        height: number;
+    }, request: EffectRenderRequest): EffectPixels | null;
     dispose(): void;
 }
 /** A saved effect source, or `null` when it is not one. */