@pixerate/editor 0.239.0 → 0.240.0

package/dist/paint-editor/live-strokes.d.cts

@@ -0,0 +1,24 @@
+/**
+ * Live stroke layers: a paint layer whose pixels are always drawn from its recorded strokes, so a
+ * stroke's brush, colour, paint, seed and points can be changed after it is painted
+ * (`PaintEditorController.updateStroke` and the rest). The document keeps the strokes
+ * (`liveStrokes`), and the layer's surface is a cache of them drawn bottom first.
+ *
+ * Only brushes whose result depends on the stroke itself can be redrawn exactly: dab, particle and
+ * bristle brushes, and the Mixer Brush, none of them picking up paint. Wet paint needs the
+ * simulation's history, thick paint has relief channels, stickers are their own objects, and
+ * smudges, blenders, pick-up brushes and erasers read the paint under them.
+ */
+import type { PaintBrush, PaintBrushEngine } from './brushes.cjs';
+import { type RecordedStroke } from './strokes.cjs';
+/** The engines a live stroke layer takes. */
+export declare const LIVE_STROKE_ENGINES: readonly PaintBrushEngine[];
+/** Why a brush can't paint on a live stroke layer, or `null` when it can. */
+export declare function liveStrokeRefusal(brush: PaintBrush): string | null;
+/** A stroke's extent in document pixels: its points and symmetry copies, padded by the brush. */
+export declare function liveStrokeBounds(stroke: RecordedStroke): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};

package/dist/paint-editor/live-strokes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Live stroke layers: a paint layer whose pixels are always drawn from its recorded strokes, so a
+ * stroke's brush, colour, paint, seed and points can be changed after it is painted
+ * (`PaintEditorController.updateStroke` and the rest). The document keeps the strokes
+ * (`liveStrokes`), and the layer's surface is a cache of them drawn bottom first.
+ *
+ * Only brushes whose result depends on the stroke itself can be redrawn exactly: dab, particle and
+ * bristle brushes, and the Mixer Brush, none of them picking up paint. Wet paint needs the
+ * simulation's history, thick paint has relief channels, stickers are their own objects, and
+ * smudges, blenders, pick-up brushes and erasers read the paint under them.
+ */
+import type { PaintBrush, PaintBrushEngine } from './brushes.js';
+import { type RecordedStroke } from './strokes.js';
+/** The engines a live stroke layer takes. */
+export declare const LIVE_STROKE_ENGINES: readonly PaintBrushEngine[];
+/** Why a brush can't paint on a live stroke layer, or `null` when it can. */
+export declare function liveStrokeRefusal(brush: PaintBrush): string | null;
+/** A stroke's extent in document pixels: its points and symmetry copies, padded by the brush. */
+export declare function liveStrokeBounds(stroke: RecordedStroke): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};

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

@@ -34,7 +34,7 @@ export interface PaintPointerEvent extends PointerSample {
     getCoalescedEvents?(): PaintPointerEvent[];
     getPredictedEvents?(): PaintPointerEvent[];
 }
-export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate' | 'sticker';
+export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate' | 'sticker' | 'stroke';
 export declare const PAINT_TOOLS: ReadonlyArray<{
     id: PaintTool;
     label: string;
@@ -63,6 +63,17 @@ export declare class PaintGesture {
     private pen;
     /** Pointer down; returns true when the gesture took the pointer (capture it). */
     down(e: PaintPointerEvent): boolean;
+    /**
+     * The Select stroke tool, on a stroke layer: pressing a stroke picks it and dragging moves it
+     * (one undo step at the drop); pressing where no stroke painted clears the pick.
+     */
+    private strokeDown;
+    /** While a stroke is dragged: how far it has moved (document pixels), to draw its outline there. */
+    get strokeDrag(): {
+        id: string;
+        dx: number;
+        dy: number;
+    } | null;
     /**
      * The Stickers tool: pressing a sticker picks it and dragging moves it (one undo step at the
      * drop); pressing anywhere else places the active brush's first stamp there, at its tip size and
@@ -107,9 +118,16 @@ export declare class PaintCanvasPresenter {
     /** Draws what changed into `ctx` (a canvas the size of the document); returns the tiles drawn. */
     render(ctx: Paint2DContext): number;
 }
-export type GuideOverlayKind = 'symmetry' | 'perspective' | 'snap' | 'stencil' | 'sticker';
-/** Lines to draw over the canvas for the guides and the picked sticker, in document pixels, with a style key. */
-export declare function guideOverlay(controller: PaintEditorController): Array<{
+export type GuideOverlayKind = 'symmetry' | 'perspective' | 'snap' | 'stencil' | 'sticker' | 'stroke';
+/**
+ * Lines to draw over the canvas for the guides, the picked sticker and the picked stroke of a stroke layer (moved by
+ * `drag` while it is dragged), in document pixels, with a style key.
+ */
+export declare function guideOverlay(controller: PaintEditorController, drag?: {
+    id: string;
+    dx: number;
+    dy: number;
+} | null): Array<{
     from: Point2;
     to: Point2;
     kind: GuideOverlayKind;
@@ -238,6 +256,8 @@ export declare const STAMP_LABELS: Readonly<Record<StampKind, string>>;
 /** Toggles one stamp in a sticker brush's set (never leaving it empty). */
 export declare function toggleStamp(stamps: readonly StampKind[], stamp: StampKind): StampKind[];
 /** 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[];
 export declare const STICKER_SLIDERS: readonly SliderControl[];
 /** Stencils a toolbar can lay with one click, centred on the canvas. */
 export declare function quickStencil(kind: 'ruler' | 'circle' | 'ellipse-mask' | 'edge-mask', canvas: {

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

@@ -34,7 +34,7 @@ export interface PaintPointerEvent extends PointerSample {
     getCoalescedEvents?(): PaintPointerEvent[];
     getPredictedEvents?(): PaintPointerEvent[];
 }
-export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate' | 'sticker';
+export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate' | 'sticker' | 'stroke';
 export declare const PAINT_TOOLS: ReadonlyArray<{
     id: PaintTool;
     label: string;
@@ -63,6 +63,17 @@ export declare class PaintGesture {
     private pen;
     /** Pointer down; returns true when the gesture took the pointer (capture it). */
     down(e: PaintPointerEvent): boolean;
+    /**
+     * The Select stroke tool, on a stroke layer: pressing a stroke picks it and dragging moves it
+     * (one undo step at the drop); pressing where no stroke painted clears the pick.
+     */
+    private strokeDown;
+    /** While a stroke is dragged: how far it has moved (document pixels), to draw its outline there. */
+    get strokeDrag(): {
+        id: string;
+        dx: number;
+        dy: number;
+    } | null;
     /**
      * The Stickers tool: pressing a sticker picks it and dragging moves it (one undo step at the
      * drop); pressing anywhere else places the active brush's first stamp there, at its tip size and
@@ -107,9 +118,16 @@ export declare class PaintCanvasPresenter {
     /** Draws what changed into `ctx` (a canvas the size of the document); returns the tiles drawn. */
     render(ctx: Paint2DContext): number;
 }
-export type GuideOverlayKind = 'symmetry' | 'perspective' | 'snap' | 'stencil' | 'sticker';
-/** Lines to draw over the canvas for the guides and the picked sticker, in document pixels, with a style key. */
-export declare function guideOverlay(controller: PaintEditorController): Array<{
+export type GuideOverlayKind = 'symmetry' | 'perspective' | 'snap' | 'stencil' | 'sticker' | 'stroke';
+/**
+ * Lines to draw over the canvas for the guides, the picked sticker and the picked stroke of a stroke layer (moved by
+ * `drag` while it is dragged), in document pixels, with a style key.
+ */
+export declare function guideOverlay(controller: PaintEditorController, drag?: {
+    id: string;
+    dx: number;
+    dy: number;
+} | null): Array<{
     from: Point2;
     to: Point2;
     kind: GuideOverlayKind;
@@ -238,6 +256,8 @@ export declare const STAMP_LABELS: Readonly<Record<StampKind, string>>;
 /** Toggles one stamp in a sticker brush's set (never leaving it empty). */
 export declare function toggleStamp(stamps: readonly StampKind[], stamp: StampKind): StampKind[];
 /** 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[];
 export declare const STICKER_SLIDERS: readonly SliderControl[];
 /** Stencils a toolbar can lay with one click, centred on the canvas. */
 export declare function quickStencil(kind: 'ruler' | 'circle' | 'ellipse-mask' | 'edge-mask', canvas: {

package/package.json

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

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

@@ -40,6 +40,8 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
 - **Strokes are data.** Every stroke is recorded (brush, colour, raw points, seed, symmetry
   copies) and gets a `strokeId`. `replay_strokes` paints recorded strokes again, exactly or
   varied. That is the main way an agent should make many similar marks.
+- **Stroke layers keep strokes editable** (`add_layer {type: "strokes"}`): tune a stroke's brush,
+  colour, seed or points after painting it instead of repainting. See "Stroke layers" below.
 - **Guides** are editor state saved with the document: a symmetry guide makes every stroke paint
   its mirror or kaleidoscope copies (one stroke), a perspective guide snaps strokes to lines
   towards one to three vanishing points, a tracing image sits under the paint (never exported)
@@ -196,11 +198,13 @@ Paint that changes colour as the stroke goes: give a gradient where a colour wou
   bristle draws its own line: press harder to splay the tuft, tilt to flatten it; soft bristles
   bend into curves at turns; a low `bristle.load` runs dry into broken streaks.
 - **Sticker spray** (category `sticker`): stamps (`star`, `leaf`, `confetti`, `flower`, `heart`,
-  `splat`, `sparkle`, `ring`, `dot`) sprayed along the stroke onto an **empty layer**, where each
-  stays an object: `add_stickers` (place them exactly), `sticker_at` (pick one by point), `list_stickers`, `update_sticker` (move, turn, resize, recolour, restamp),
-  `arrange_stickers`, `remove_stickers`. A sticker layer takes no other paint. Stickers are drawn
-  whole, so a spray is refused while a mask stencil is on: hide it (`update_stencil` `enabled`
-  false) first, then remove the stickers you don't want.
+  `splat`, `sparkle`, `ring`, `dot`) sprayed onto an **empty layer**, each staying an object:
+  `add_stickers` (exact places), `sticker_at`, `list_stickers`, `update_sticker`, `arrange_stickers`,
+  `remove_stickers`. A sticker layer takes no other paint; sprays are refused under an enabled
+  mask stencil (hide it with `update_stencil` `enabled` false, then remove unwanted stickers).
+- **Stroke layers**: pixels drawn from the layer's strokes; they take `dab`, `particle`, `bristle`
+  and Mixer Brush strokes that pick up no paint. `list_strokes {live: true}` → `update_stroke` /
+  `edit_stroke_points` / `reorder_stroke` / `remove_strokes`; `rasterize_stroke_layer` once settled.
 - **Stencils**: `add_stencil` lays a `ruler` or `arc` (strokes that start within `snap` px follow
   it exactly: straight lines, circles, rainbows) or a `line` / `shape` mask (paint lands only on
   one side or inside a rect, ellipse or polygon; `invert` for outside). Stencils stay until
@@ -239,9 +243,11 @@ an overlay paints only where it has pixels.
 1. `search_effects` (`use` generator, overlay or title) and `describe_effect` for the controls.
 2. `set_effect_paint` with `effect`, `values` and `time` (ms, default 0). Wait for it: strokes that
    would use it are refused while it renders.
-3. Paint with a dry brush: dab, particle and bristle brushes take the colour per pixel (the most
-   faithful), the Mixer Brush and dab brushes with `behavior.pickup` take it per dab at the dab's
-   centre and mix it with what they pick up. Brush opacity, flow, grain and pressure still apply.
+3. Paint: dab, particle and bristle brushes take the colour per pixel (the most faithful); the
+   Mixer Brush and dab brushes with `behavior.pickup` take it per dab at its centre. Wet and
+   impasto brushes take it per pixel too, shifted by any paint they pick up: in watercolour and
+   gouache the pattern then flows, blooms and granulates with the water; impasto keeps its relief.
+   Sprayed stickers each take the colour at their centre (they stay recolourable).
 4. `set_color` or `set_paint` goes back to colour; `remove_effect` (target and effect `paint`)
    does too, and `update_effect` (target and effect `paint`, `values`) renders new values.
 
@@ -250,7 +256,8 @@ When to use which:
 | Want | Use |
 | --- | --- |
 | The effect inside brushed marks, hand-painted edges | `set_effect_paint` and a dry brush |
-| The effect inside an exact shape, or in wet / thick paint | Paint the shape, dry it, then `fill_layer_with_effect` with `lockTransparency: true` |
+| The effect in a wash that flows, or in thick paint | `set_effect_paint` and a watercolour, gouache, oil or impasto brush |
+| The effect inside an exact shape, unchanged by water | Paint the shape, dry it, then `fill_layer_with_effect` with `lockTransparency: true` |
 | The effect over the whole sheet | `set_paper_effect` or `add_effect_layer` |
 
 ## Canvas-hosted layer
@@ -281,7 +288,7 @@ view), so work with the tools you are given.
 | Tool | Use |
 | --- | --- |
 | `list_layers` | Read the layers top first: id, name, type (`pixel` / `group`), visible, opacity, blend, clipped, locks, `active`, painted `bounds` (null when empty), parent and depth. |
-| `add_layer` | Add an empty pixel layer (or `type: "group"`) above the active layer, above `aboveId`, or at the top of group `parentId`; it becomes active. Returns the layer. Put each pass of a painting on its own layer. |
+| `add_layer` | Add an empty pixel layer (or `type: "group"`, or `type: "strokes"` for a stroke layer whose strokes stay editable) above the active layer, above `aboveId`, or at the top of group `parentId`; it becomes active. Returns the layer. Put each pass of a painting on its own layer. |
 | `update_layer` | Change `name`, `visible`, `opacity` (0..1), `blend`, `clipped` (clip to the layer below) or `locks` (`pixels`, `transparency`: paint only where there is paint, `position`, `all`). Returns the layer. |
 | `list_blend_modes` | Read every blend mode: id, label, group (`standard`, `pigment`, `painterly`), what the pigment and painterly modes do, and the `psd` mode export writes instead. Read before choosing a painterly mode. Changes nothing. |
 | `set_active_layer` | Make a layer the default target of strokes, fills and clears. Editor state. |
@@ -335,7 +342,14 @@ view), so work with the tools you are given.
 | 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` changes, `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. |
-| `list_strokes` | Read the recorded strokes, oldest first (default the last 100): id, layer, brush, colour, point count, seed, bounds. With `ids`, their points too. |
+| `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. |
+| `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. |
+| `update_stroke` | Change a stroke on a stroke layer: `brushId` (keeps its size), `brush` settings, `color`, `paint` (null drops a gradient), `seed`. Redraws exactly. One undo step. Returns the stroke and the changed `bounds`. |
+| `edit_stroke_points` | Replace a stroke's `points`, or `transform` it (`dx`, `dy`, `scale`, `rotate`, `flipX`, about its centre or `origin`). One undo step. Returns the stroke with its points and the changed `bounds`. |
+| `reorder_stroke` | Move a stroke to `index` in its stroke layer (0 = bottom). One undo step. Returns the order. |
+| `remove_strokes` | Delete strokes from stroke layers (their eraser). One undo step. Returns the ids and `bounds`. |
+| `convert_to_stroke_layer` | Make an empty pixel layer a stroke layer. Returns the layer. |
+| `rasterize_stroke_layer` | Turn a stroke layer into a plain pixel layer with the same pixels (strokes no longer editable). Do it before erasing, smudging or filling on it. |
 | `replay_strokes` | Paint recorded `strokeIds` again: exactly, or varied by `dx` / `dy` (px), `rotate` (degrees clockwise), `scale` (brush size follows), `flipX`, `origin`, `pressureScale`, `color`, `brushId`, `layerId`, `repeat` (each copy applies the variation again). One undo step. Returns the new stroke ids, bounds and layers. |
 | `undo_paint` | Undo the last step (a wet stroke's undo puts the wet paint back as it was before it). Returns what was undone and what is next. |
 | `redo_paint` | Redo the step just undone. |
@@ -481,10 +495,11 @@ The host may add the shared document tools (see `pixerate-agent-tools`). A paint
   strokes record it, and replays render it again first, so they need the same provider (an
   error names the effect and provider when it is missing; `color` on `replay_strokes` repaints
   in one colour instead).
-- **Effect paint refuses wet, impasto and sticker brushes** (they carry one colour as pigment,
-  thick paint or stamps). Paint the shape, dry it, and `fill_layer_with_effect` with
-  `lockTransparency: true`. Erasers, blenders and smudges ignore it, and a brush with its own
-  gradient, a stroke `color` or `paint`, or `set_color` / `set_paint` paints colour instead.
+- **Effect paint in wet paint moves with the water**: the pattern bleeds and blooms like any
+  pigment, so fine detail softens. For a crisp pattern in an exact shape, paint the shape, dry it,
+  and `fill_layer_with_effect` with `lockTransparency: true`. Erasers, blenders and smudges ignore
+  effect paint; a brush with its own gradient, a stroke `color` or `paint`, or `set_color` /
+  `set_paint` paints colour instead.
 - **Effect paint is fixed to the canvas, not the stroke**: a replayed or moved stroke shows the
   part of the effect under its new place. Wait for `set_effect_paint` to return before painting;
   strokes are refused while it renders.