@pixerate/editor 0.239.0 → 0.240.0

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

@@ -112,6 +112,8 @@ export interface PaintEditorState {
     mixerLoad: MixerLoad;
     view: PaintView;
     hand: Hand;
+    /** The stroke picked on a stroke layer, on the canvas or in the stroke panel (editor state, not an undo step). */
+    selectedStroke: string | null;
     /** The sticker picked on the canvas or in the sticker panel (editor state, not an undo step). */
     selectedSticker: string | null;
     canUndo: boolean;
@@ -134,6 +136,19 @@ export interface PaintEditorState {
     version: number;
 }
 /** A layer as tools and panels describe it. */
+/** A change to a live stroke (`updateStroke`): every field is optional. */
+export interface LiveStrokeUpdate {
+    /** Another brush preset; the stroke keeps its size. */
+    brushId?: string;
+    /** Brush settings to change (as `setBrush` takes), on top of `brushId` or the stroke's brush. */
+    brush?: Omit<PaintBrushInput, 'id'>;
+    /** A new colour #rrggbb (replaces gradient or effect paint). */
+    color?: string;
+    /** Paint: a colour, gradient paint or effect paint; `null` back to the plain colour. */
+    paint?: unknown;
+    /** Another jitter seed (particles, scatter and texture fall differently). */
+    seed?: number;
+}
 export interface PaintLayerInfo {
     id: string;
     name: string;
@@ -148,6 +163,8 @@ export interface PaintLayerInfo {
     bounds: RasterRect | null;
     parentId: string | null;
     depth: number;
+    /** A live stroke layer (its pixels are drawn from its strokes, which stay editable): how many strokes it has. */
+    liveStrokes?: number;
 }
 export interface PaintStrokeInit {
     /** Default the active layer. */
@@ -277,6 +294,7 @@ export declare class PaintEditorController {
     private mixerLoad;
     private view;
     private hand;
+    private selectedStroke;
     private selectedSticker;
     /** A sticker drag in progress (`previewSticker`): the document before it, so the drop undoes in one step, and the one it showed last. */
     private stickerPreview;
@@ -290,6 +308,8 @@ export declare class PaintEditorController {
     private dirty;
     private seedCounter;
     private strokeCounter;
+    /** The area each stroke painted (document pixels; `null`: nothing), learnt as it is painted or drawn, so a stroke layer edit redraws only where it changes (see `drawLiveStrokes`). */
+    private paintedBounds;
     private guides;
     private swatches;
     private readonly pad;
@@ -403,9 +423,10 @@ export declare class PaintEditorController {
     private paintTarget;
     setActiveLayer(id: string): void;
     /** Adds an empty pixel layer or group above `aboveId` (default: the active layer) and makes it active. */
+    /** Adds a layer above the active one: `pixel` (default), `group`, or `strokes`, a live stroke layer whose strokes stay editable. */
     addLayer(options?: {
         name?: string;
-        type?: 'pixel' | 'group';
+        type?: 'pixel' | 'group' | 'strokes';
         aboveId?: string;
         parentId?: string | null;
     }): PaintLayerInfo;
@@ -1000,6 +1021,75 @@ export declare class PaintEditorController {
     removeStickers(layerId: string | undefined, ids?: readonly string[]): string[];
     /** Sets a layer's stickers (replays). */
     replaceStickers(layerId: string, stickers: readonly Sticker[]): void;
+    /** The document's `liveStrokes` without these layers (as a spread: `{}` when unchanged). */
+    private liveStrokesWithout;
+    private liveStrokeLayer;
+    /** Whether a layer is a live stroke layer. */
+    isLiveStrokeLayer(layerId: string): boolean;
+    /** Makes an empty pixel layer a live stroke layer (one undo step). */
+    convertToLiveStrokes(layerId?: string): PaintLayerInfo;
+    /** A stroke layer's strokes, bottom first. */
+    listLiveStrokes(layerId?: string): RecordedStroke[];
+    /** The stroke layer holding a live stroke, and where. */
+    private findLiveStroke;
+    /**
+     * Changes a live stroke's brush (a preset by `brushId`, keeping the stroke's size, and/or brush
+     * settings), colour, paint or seed, and redraws its layer (one undo step). A new colour replaces
+     * gradient or effect paint. Returns the stroke and the area that changed.
+     */
+    updateStroke(id: string, update: LiveStrokeUpdate): {
+        stroke: RecordedStroke;
+        bounds: RasterRect;
+    };
+    /**
+     * Replaces a live stroke's points, or moves, scales, rotates or flips them (`transform`, about
+     * the stroke's centre unless an origin is given; the brush size scales too), and redraws its
+     * layer (one undo step). Returns the stroke and the area that changed.
+     */
+    editStrokePoints(id: string, edit: {
+        points?: readonly PenPoint[];
+        transform?: StrokeVariation;
+    }): {
+        stroke: RecordedStroke;
+        bounds: RasterRect;
+    };
+    /** Deletes live strokes (one undo step). Returns the ids removed and the area that changed. */
+    removeStrokes(ids: readonly string[]): {
+        removed: string[];
+        bounds: RasterRect | null;
+    };
+    /** Moves a live stroke to `index` in its layer (0 = bottom) and redraws (one undo step). Returns the new order. */
+    reorderStroke(id: string, index: number): string[];
+    /** Turns a stroke layer into a plain pixel layer with the same pixels (one undo step). */
+    rasterizeLiveStrokes(layerId?: string): PaintLayerInfo;
+    /** Sets a layer's live strokes and redraws it (replays). `null` makes it a plain pixel layer. */
+    replaceLiveStrokes(layerId: string, strokes: readonly RecordedStroke[] | null): void;
+    /**
+     * The top-most stroke of a stroke layer (default the active layer) that painted the pixel at
+     * (x, y) document pixels, or `null`. Strokes whose area holds the point are drawn alone, top
+     * first, until one covers it.
+     */
+    liveStrokeAt(layerId: string | undefined, x: number, y: number): RecordedStroke | null;
+    /** Picks a stroke for the stroke panel and canvas (`null` for none). Editor state, not an undo step. */
+    selectStroke(id: string | null): void;
+    /** Where a live stroke painted (document pixels), or `null`. */
+    liveStrokeArea(id: string): RasterRect | null;
+    /** Commits a layer's new stroke list with its redrawn pixels, recorded for replays (one undo step). */
+    private commitLiveStrokes;
+    private withLiveStrokes;
+    /** Where a stroke painted (document pixels): as learnt when it was painted or drawn, else an estimate from its points and brush. */
+    private strokeArea;
+    /** The areas strokes painted, or `null` when one is not known (a full redraw then). */
+    private strokeAreas;
+    /** Draws one stroke onto `surface` of a plain copy of the layer; returns the result and the area it painted. */
+    private drawLiveStroke;
+    /**
+     * A stroke layer's pixels drawn from its strokes, bottom first. With `dirty` (the areas the old
+     * strokes that changed had painted), only the tiles there and under any stroke whose area isn't
+     * known yet are drawn again, from the strokes that reach them (a pixel depends only on the
+     * strokes over it); the other tiles are kept. Without it, or with `null`, every stroke is drawn.
+     */
+    private drawLiveStrokes;
     private stencilCache;
     private nextStencilId;
     /** The mask stencils' coverage over the canvas (cached), or `null` when none masks. */

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

@@ -112,6 +112,8 @@ export interface PaintEditorState {
     mixerLoad: MixerLoad;
     view: PaintView;
     hand: Hand;
+    /** The stroke picked on a stroke layer, on the canvas or in the stroke panel (editor state, not an undo step). */
+    selectedStroke: string | null;
     /** The sticker picked on the canvas or in the sticker panel (editor state, not an undo step). */
     selectedSticker: string | null;
     canUndo: boolean;
@@ -134,6 +136,19 @@ export interface PaintEditorState {
     version: number;
 }
 /** A layer as tools and panels describe it. */
+/** A change to a live stroke (`updateStroke`): every field is optional. */
+export interface LiveStrokeUpdate {
+    /** Another brush preset; the stroke keeps its size. */
+    brushId?: string;
+    /** Brush settings to change (as `setBrush` takes), on top of `brushId` or the stroke's brush. */
+    brush?: Omit<PaintBrushInput, 'id'>;
+    /** A new colour #rrggbb (replaces gradient or effect paint). */
+    color?: string;
+    /** Paint: a colour, gradient paint or effect paint; `null` back to the plain colour. */
+    paint?: unknown;
+    /** Another jitter seed (particles, scatter and texture fall differently). */
+    seed?: number;
+}
 export interface PaintLayerInfo {
     id: string;
     name: string;
@@ -148,6 +163,8 @@ export interface PaintLayerInfo {
     bounds: RasterRect | null;
     parentId: string | null;
     depth: number;
+    /** A live stroke layer (its pixels are drawn from its strokes, which stay editable): how many strokes it has. */
+    liveStrokes?: number;
 }
 export interface PaintStrokeInit {
     /** Default the active layer. */
@@ -277,6 +294,7 @@ export declare class PaintEditorController {
     private mixerLoad;
     private view;
     private hand;
+    private selectedStroke;
     private selectedSticker;
     /** A sticker drag in progress (`previewSticker`): the document before it, so the drop undoes in one step, and the one it showed last. */
     private stickerPreview;
@@ -290,6 +308,8 @@ export declare class PaintEditorController {
     private dirty;
     private seedCounter;
     private strokeCounter;
+    /** The area each stroke painted (document pixels; `null`: nothing), learnt as it is painted or drawn, so a stroke layer edit redraws only where it changes (see `drawLiveStrokes`). */
+    private paintedBounds;
     private guides;
     private swatches;
     private readonly pad;
@@ -403,9 +423,10 @@ export declare class PaintEditorController {
     private paintTarget;
     setActiveLayer(id: string): void;
     /** Adds an empty pixel layer or group above `aboveId` (default: the active layer) and makes it active. */
+    /** Adds a layer above the active one: `pixel` (default), `group`, or `strokes`, a live stroke layer whose strokes stay editable. */
     addLayer(options?: {
         name?: string;
-        type?: 'pixel' | 'group';
+        type?: 'pixel' | 'group' | 'strokes';
         aboveId?: string;
         parentId?: string | null;
     }): PaintLayerInfo;
@@ -1000,6 +1021,75 @@ export declare class PaintEditorController {
     removeStickers(layerId: string | undefined, ids?: readonly string[]): string[];
     /** Sets a layer's stickers (replays). */
     replaceStickers(layerId: string, stickers: readonly Sticker[]): void;
+    /** The document's `liveStrokes` without these layers (as a spread: `{}` when unchanged). */
+    private liveStrokesWithout;
+    private liveStrokeLayer;
+    /** Whether a layer is a live stroke layer. */
+    isLiveStrokeLayer(layerId: string): boolean;
+    /** Makes an empty pixel layer a live stroke layer (one undo step). */
+    convertToLiveStrokes(layerId?: string): PaintLayerInfo;
+    /** A stroke layer's strokes, bottom first. */
+    listLiveStrokes(layerId?: string): RecordedStroke[];
+    /** The stroke layer holding a live stroke, and where. */
+    private findLiveStroke;
+    /**
+     * Changes a live stroke's brush (a preset by `brushId`, keeping the stroke's size, and/or brush
+     * settings), colour, paint or seed, and redraws its layer (one undo step). A new colour replaces
+     * gradient or effect paint. Returns the stroke and the area that changed.
+     */
+    updateStroke(id: string, update: LiveStrokeUpdate): {
+        stroke: RecordedStroke;
+        bounds: RasterRect;
+    };
+    /**
+     * Replaces a live stroke's points, or moves, scales, rotates or flips them (`transform`, about
+     * the stroke's centre unless an origin is given; the brush size scales too), and redraws its
+     * layer (one undo step). Returns the stroke and the area that changed.
+     */
+    editStrokePoints(id: string, edit: {
+        points?: readonly PenPoint[];
+        transform?: StrokeVariation;
+    }): {
+        stroke: RecordedStroke;
+        bounds: RasterRect;
+    };
+    /** Deletes live strokes (one undo step). Returns the ids removed and the area that changed. */
+    removeStrokes(ids: readonly string[]): {
+        removed: string[];
+        bounds: RasterRect | null;
+    };
+    /** Moves a live stroke to `index` in its layer (0 = bottom) and redraws (one undo step). Returns the new order. */
+    reorderStroke(id: string, index: number): string[];
+    /** Turns a stroke layer into a plain pixel layer with the same pixels (one undo step). */
+    rasterizeLiveStrokes(layerId?: string): PaintLayerInfo;
+    /** Sets a layer's live strokes and redraws it (replays). `null` makes it a plain pixel layer. */
+    replaceLiveStrokes(layerId: string, strokes: readonly RecordedStroke[] | null): void;
+    /**
+     * The top-most stroke of a stroke layer (default the active layer) that painted the pixel at
+     * (x, y) document pixels, or `null`. Strokes whose area holds the point are drawn alone, top
+     * first, until one covers it.
+     */
+    liveStrokeAt(layerId: string | undefined, x: number, y: number): RecordedStroke | null;
+    /** Picks a stroke for the stroke panel and canvas (`null` for none). Editor state, not an undo step. */
+    selectStroke(id: string | null): void;
+    /** Where a live stroke painted (document pixels), or `null`. */
+    liveStrokeArea(id: string): RasterRect | null;
+    /** Commits a layer's new stroke list with its redrawn pixels, recorded for replays (one undo step). */
+    private commitLiveStrokes;
+    private withLiveStrokes;
+    /** Where a stroke painted (document pixels): as learnt when it was painted or drawn, else an estimate from its points and brush. */
+    private strokeArea;
+    /** The areas strokes painted, or `null` when one is not known (a full redraw then). */
+    private strokeAreas;
+    /** Draws one stroke onto `surface` of a plain copy of the layer; returns the result and the area it painted. */
+    private drawLiveStroke;
+    /**
+     * A stroke layer's pixels drawn from its strokes, bottom first. With `dirty` (the areas the old
+     * strokes that changed had painted), only the tiles there and under any stroke whose area isn't
+     * known yet are drawn again, from the strokes that reach them (a pixel depends only on the
+     * strokes over it); the other tiles are kept. Without it, or with `null`, every stroke is drawn.
+     */
+    private drawLiveStrokes;
     private stencilCache;
     private nextStencilId;
     /** The mask stencils' coverage over the canvas (cached), or `null` when none masks. */

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

@@ -43,6 +43,11 @@ export interface PaintDocumentState {
     paintEvents?: PaintEvent[];
     /** Sticker layers: each layer's stickers, bottom first (its pixels are drawn from them). */
     stickers?: Readonly<Record<string, Sticker[]>>;
+    /**
+     * Live stroke layers: each layer's strokes, bottom first. Its pixels are drawn from them, so each
+     * stroke's brush, colour and points stay editable (`updateStroke`).
+     */
+    liveStrokes?: Readonly<Record<string, RecordedStroke[]>>;
     /** Thick paint: each layer's height and material channels (layers without relief are missing). */
     thick?: Readonly<Record<string, ThickChannels>>;
     /** Effect layers: the provider effect each one is drawn from (layers that are gone are ignored). */
@@ -61,9 +66,9 @@ export interface PaintDocumentState {
 /** A change a replay repeats besides strokes, recorded with how many strokes came before it. */
 export interface PaintEvent {
     at: number;
-    kind: 'fill' | 'clear' | 'flatten' | 'stickers';
+    kind: 'fill' | 'clear' | 'flatten' | 'stickers' | 'live-strokes';
     layerId: string;
-    /** The fill's options (colour, opacity, grain, pressure, blend), or the layer's stickers after an edit. */
+    /** The fill's options (colour, opacity, grain, pressure, blend), or the layer's stickers or live strokes after an edit. */
     data?: Record<string, unknown>;
 }
 /** A new layer id, unique in this session. */

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

@@ -43,6 +43,11 @@ export interface PaintDocumentState {
     paintEvents?: PaintEvent[];
     /** Sticker layers: each layer's stickers, bottom first (its pixels are drawn from them). */
     stickers?: Readonly<Record<string, Sticker[]>>;
+    /**
+     * Live stroke layers: each layer's strokes, bottom first. Its pixels are drawn from them, so each
+     * stroke's brush, colour and points stay editable (`updateStroke`).
+     */
+    liveStrokes?: Readonly<Record<string, RecordedStroke[]>>;
     /** Thick paint: each layer's height and material channels (layers without relief are missing). */
     thick?: Readonly<Record<string, ThickChannels>>;
     /** Effect layers: the provider effect each one is drawn from (layers that are gone are ignored). */
@@ -61,9 +66,9 @@ export interface PaintDocumentState {
 /** A change a replay repeats besides strokes, recorded with how many strokes came before it. */
 export interface PaintEvent {
     at: number;
-    kind: 'fill' | 'clear' | 'flatten' | 'stickers';
+    kind: 'fill' | 'clear' | 'flatten' | 'stickers' | 'live-strokes';
     layerId: string;
-    /** The fill's options (colour, opacity, grain, pressure, blend), or the layer's stickers after an edit. */
+    /** The fill's options (colour, opacity, grain, pressure, blend), or the layer's stickers or live strokes after an edit. */
     data?: Record<string, unknown>;
 }
 /** A new layer id, unique in this session. */