@pixerate/editor 0.238.0 → 0.240.0

package/dist/gradient/sample.d.cts

@@ -0,0 +1,69 @@
+/**
+ * Gradients from sampled colours: `simplifyGradientStops` reduces a noisy run of colours (pixels
+ * read along a line from a photo, a paint stroke or a shape) to the few stops that reproduce it
+ * within a perceptual tolerance, and `sampleGradientFromLine` reads those colours from any pixel
+ * reader and returns a linear gradient.
+ *
+ * Distances are Euclidean in OKLab (ΔE OK, about 0.02 is a just-noticeable step), against the
+ * OKLab interpolation the returned gradients use, so what is measured is what is drawn.
+ */
+import type { Gradient, GradientStop } from './types.cjs';
+export interface SimplifyGradientStopsOptions {
+    /** Largest perceptual error left between the samples and the stops, in OKLab ΔE (default 0.06). */
+    tolerance?: number;
+    /** Fewest stops to return (default 2, at least 2). */
+    minStops?: number;
+    /** Most stops to return (default 5, at least `minStops`). */
+    maxStops?: number;
+    /**
+     * Samples on each side averaged into each one before fitting, to ignore grain, JPEG noise and
+     * brush texture (default 2; 0 fits the raw samples).
+     */
+    smoothing?: number;
+}
+export interface RawGradientSample {
+    /** Position along the line, 0..1. */
+    offset: number;
+    /** Any CSS colour, or RGBA bytes `[r, g, b, a]` (0..255). */
+    color: string | readonly [number, number, number, number];
+}
+export interface SimplifiedGradientStops {
+    stops: GradientStop[];
+    /** The largest OKLab distance left between a (smoothed) sample and the stops. */
+    maxError: number;
+}
+/**
+ * Like `simplifyGradientStops`, with the largest error left. Throws a sentence when the input
+ * can't make a gradient (fewer than two readable samples, or options out of range).
+ */
+export declare function fitGradientStops(samples: readonly RawGradientSample[], options?: SimplifyGradientStopsOptions): SimplifiedGradientStops;
+/**
+ * Reduces colours sampled along a line (offsets 0..1) to a minimal set of gradient stops. The
+ * first and last stops sit at 0 and 1; stops are added where the colour turns most until every
+ * sample is within `tolerance` (OKLab ΔE) of the OKLab blend between its stops, or `maxStops` is
+ * reached. Samples that can't be read (a bad colour string) are skipped. Throws when fewer than two
+ * samples can be read.
+ */
+export declare function simplifyGradientStops(samples: readonly RawGradientSample[], options?: SimplifyGradientStopsOptions): GradientStop[];
+export interface LineSamplingOptions extends SimplifyGradientStopsOptions {
+    /** Colours read along the line, ends included (default 32, 2..1024). */
+    sampleCount?: number;
+    /** Snap the line's angle to multiples of this many degrees (e.g. 15, for Shift), keeping its length. */
+    snapStep?: number;
+}
+/**
+ * Reads colours along the line from `start` to `end` with `readPixel` (which returns a CSS colour,
+ * RGBA bytes, or null where there is nothing to read) and returns a linear gradient (OKLab
+ * interpolation) whose angle is the line's (CSS degrees) and whose stops are the simplified
+ * colours, offsets measured along the line. Returns null when fewer than two points could be read.
+ */
+export declare function sampleGradientFromLine(readPixel: (point: {
+    x: number;
+    y: number;
+}) => string | readonly [number, number, number, number] | null, start: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}, options?: LineSamplingOptions): Gradient | null;

package/dist/gradient/sample.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Gradients from sampled colours: `simplifyGradientStops` reduces a noisy run of colours (pixels
+ * read along a line from a photo, a paint stroke or a shape) to the few stops that reproduce it
+ * within a perceptual tolerance, and `sampleGradientFromLine` reads those colours from any pixel
+ * reader and returns a linear gradient.
+ *
+ * Distances are Euclidean in OKLab (ΔE OK, about 0.02 is a just-noticeable step), against the
+ * OKLab interpolation the returned gradients use, so what is measured is what is drawn.
+ */
+import type { Gradient, GradientStop } from './types.js';
+export interface SimplifyGradientStopsOptions {
+    /** Largest perceptual error left between the samples and the stops, in OKLab ΔE (default 0.06). */
+    tolerance?: number;
+    /** Fewest stops to return (default 2, at least 2). */
+    minStops?: number;
+    /** Most stops to return (default 5, at least `minStops`). */
+    maxStops?: number;
+    /**
+     * Samples on each side averaged into each one before fitting, to ignore grain, JPEG noise and
+     * brush texture (default 2; 0 fits the raw samples).
+     */
+    smoothing?: number;
+}
+export interface RawGradientSample {
+    /** Position along the line, 0..1. */
+    offset: number;
+    /** Any CSS colour, or RGBA bytes `[r, g, b, a]` (0..255). */
+    color: string | readonly [number, number, number, number];
+}
+export interface SimplifiedGradientStops {
+    stops: GradientStop[];
+    /** The largest OKLab distance left between a (smoothed) sample and the stops. */
+    maxError: number;
+}
+/**
+ * Like `simplifyGradientStops`, with the largest error left. Throws a sentence when the input
+ * can't make a gradient (fewer than two readable samples, or options out of range).
+ */
+export declare function fitGradientStops(samples: readonly RawGradientSample[], options?: SimplifyGradientStopsOptions): SimplifiedGradientStops;
+/**
+ * Reduces colours sampled along a line (offsets 0..1) to a minimal set of gradient stops. The
+ * first and last stops sit at 0 and 1; stops are added where the colour turns most until every
+ * sample is within `tolerance` (OKLab ΔE) of the OKLab blend between its stops, or `maxStops` is
+ * reached. Samples that can't be read (a bad colour string) are skipped. Throws when fewer than two
+ * samples can be read.
+ */
+export declare function simplifyGradientStops(samples: readonly RawGradientSample[], options?: SimplifyGradientStopsOptions): GradientStop[];
+export interface LineSamplingOptions extends SimplifyGradientStopsOptions {
+    /** Colours read along the line, ends included (default 32, 2..1024). */
+    sampleCount?: number;
+    /** Snap the line's angle to multiples of this many degrees (e.g. 15, for Shift), keeping its length. */
+    snapStep?: number;
+}
+/**
+ * Reads colours along the line from `start` to `end` with `readPixel` (which returns a CSS colour,
+ * RGBA bytes, or null where there is nothing to read) and returns a linear gradient (OKLab
+ * interpolation) whose angle is the line's (CSS degrees) and whose stops are the simplified
+ * colours, offsets measured along the line. Returns null when fewer than two points could be read.
+ */
+export declare function sampleGradientFromLine(readPixel: (point: {
+    x: number;
+    y: number;
+}) => string | readonly [number, number, number, number] | null, start: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}, options?: LineSamplingOptions): Gradient | null;

package/dist/image-editor/index.cjs

@@ -1,6 +1,10 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4; var _class5; var _class6; var _class7; var _class8; var _class9; var _class10; var _class11; var _class12; var _class13; var _class14; var _class15; var _class16; var _class17; var _class18;
 
 
+var _chunkS6OT6CTScjs = require('../chunk-S6OT6CTS.cjs');
+
+
+
 
 
 
@@ -17538,7 +17542,50 @@ function createImagePaintTools(controller) {
       return { color, foreground: controller.getState().paint.foreground };
     }
   };
-  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2];
+  const sampleGradient = {
+    name: "sample_gradient",
+    title: "Sample a gradient along a line",
+    description: "Reads the composite colours along a line from start to end (document pixels), smooths away grain and fits the fewest gradient stops that reproduce them within tolerance. Changes nothing. Returns a linear gradient (CSS angle of the line, oklab interpolation, stops with offsets along the line), its CSS, and how many points could be read. Pass the gradient to a gradient tool (set_gradient) or its stops as paint (set_paint).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        start: { type: "object", properties: { x: { type: "number", description: "Document x in pixels." }, y: { type: "number", description: "Document y in pixels." } }, required: ["x", "y"], additionalProperties: false, description: "Where the gradient starts (offset 0)." },
+        end: { type: "object", properties: { x: { type: "number", description: "Document x in pixels." }, y: { type: "number", description: "Document y in pixels." } }, required: ["x", "y"], additionalProperties: false, description: "Where it ends (offset 1)." },
+        sampleCount: { type: "integer", minimum: 2, maximum: 1024, description: "Points read along the line, ends included (default 32)." },
+        sampleSize: { type: "integer", minimum: 1, maximum: 101, description: "Square averaged at each point, in pixels (default 3)." },
+        tolerance: { type: "number", exclusiveMinimum: 0, maximum: 1, description: "Largest error left, OKLab \u0394E (default 0.06; 0.02 is a just-noticeable step)." },
+        maxStops: { type: "integer", minimum: 2, maximum: 64, description: "Most stops (default 5)." },
+        snapStep: { type: "number", exclusiveMinimum: 0, maximum: 180, description: "Snap the line to multiples of this many degrees, keeping its length (default no snapping)." }
+      },
+      required: ["start", "end"],
+      additionalProperties: false
+    },
+    annotations: { title: "Sample a gradient along a line", ...READ4 },
+    handler: (args) => {
+      const start = args.start;
+      const end = args.end;
+      const size = _nullishCoalesce(args.sampleSize, () => ( 3));
+      let read = 0;
+      let gradient;
+      try {
+        gradient = _chunkS6OT6CTScjs.sampleGradientFromLine.call(void 0, 
+          (p) => {
+            const c = controller.sampleColor(p, { size, setForeground: false });
+            if (c) read++;
+            return c;
+          },
+          start,
+          end,
+          { sampleCount: args.sampleCount, tolerance: args.tolerance, maxStops: args.maxStops, snapStep: args.snapStep }
+        );
+      } catch (e) {
+        throw new (0, _chunkBBUE3UJLcjs.LayerOperationError)(e.message);
+      }
+      if (!gradient) throw new (0, _chunkBBUE3UJLcjs.LayerOperationError)(`Fewer than two points along the line could be read: it runs outside the canvas or over transparent pixels. Read the canvas size with get_image_info and draw the line across visible pixels.`);
+      return { gradient, css: _chunkS6OT6CTScjs.gradientToCss.call(void 0, gradient), pointsRead: read };
+    }
+  };
+  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2, sampleGradient];
 }
 
 // src/image-editor/color-tools.ts

package/dist/image-editor/index.js

@@ -1,3 +1,7 @@
+import {
+  gradientToCss,
+  sampleGradientFromLine
+} from "../chunk-KMPM5JM5.js";
 import {
   bendSegment,
   loadOpenTypeFont,
@@ -17538,7 +17542,50 @@ function createImagePaintTools(controller) {
       return { color, foreground: controller.getState().paint.foreground };
     }
   };
-  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2];
+  const sampleGradient = {
+    name: "sample_gradient",
+    title: "Sample a gradient along a line",
+    description: "Reads the composite colours along a line from start to end (document pixels), smooths away grain and fits the fewest gradient stops that reproduce them within tolerance. Changes nothing. Returns a linear gradient (CSS angle of the line, oklab interpolation, stops with offsets along the line), its CSS, and how many points could be read. Pass the gradient to a gradient tool (set_gradient) or its stops as paint (set_paint).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        start: { type: "object", properties: { x: { type: "number", description: "Document x in pixels." }, y: { type: "number", description: "Document y in pixels." } }, required: ["x", "y"], additionalProperties: false, description: "Where the gradient starts (offset 0)." },
+        end: { type: "object", properties: { x: { type: "number", description: "Document x in pixels." }, y: { type: "number", description: "Document y in pixels." } }, required: ["x", "y"], additionalProperties: false, description: "Where it ends (offset 1)." },
+        sampleCount: { type: "integer", minimum: 2, maximum: 1024, description: "Points read along the line, ends included (default 32)." },
+        sampleSize: { type: "integer", minimum: 1, maximum: 101, description: "Square averaged at each point, in pixels (default 3)." },
+        tolerance: { type: "number", exclusiveMinimum: 0, maximum: 1, description: "Largest error left, OKLab \u0394E (default 0.06; 0.02 is a just-noticeable step)." },
+        maxStops: { type: "integer", minimum: 2, maximum: 64, description: "Most stops (default 5)." },
+        snapStep: { type: "number", exclusiveMinimum: 0, maximum: 180, description: "Snap the line to multiples of this many degrees, keeping its length (default no snapping)." }
+      },
+      required: ["start", "end"],
+      additionalProperties: false
+    },
+    annotations: { title: "Sample a gradient along a line", ...READ4 },
+    handler: (args) => {
+      const start = args.start;
+      const end = args.end;
+      const size = args.sampleSize ?? 3;
+      let read = 0;
+      let gradient;
+      try {
+        gradient = sampleGradientFromLine(
+          (p) => {
+            const c = controller.sampleColor(p, { size, setForeground: false });
+            if (c) read++;
+            return c;
+          },
+          start,
+          end,
+          { sampleCount: args.sampleCount, tolerance: args.tolerance, maxStops: args.maxStops, snapStep: args.snapStep }
+        );
+      } catch (e) {
+        throw new LayerOperationError(e.message);
+      }
+      if (!gradient) throw new LayerOperationError(`Fewer than two points along the line could be read: it runs outside the canvas or over transparent pixels. Read the canvas size with get_image_info and draw the line across visible pixels.`);
+      return { gradient, css: gradientToCss(gradient), pointsRead: read };
+    }
+  };
+  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2, sampleGradient];
 }
 
 // src/image-editor/color-tools.ts

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. */