@pixerate/editor 0.256.0 → 0.258.0

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

@@ -22,6 +22,7 @@ import { type PaintBrushInput, type PaintBrush } from './brushes.cjs';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.cjs';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.cjs';
 import type { Brush } from '../brushes/types.cjs';
+import type { ColorScheme } from '../color/dual.cjs';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.cjs';
 import { type ImageEncoder, type ImageFormat } from './encode.cjs';
 import type { PenPoint } from './engine.cjs';
@@ -67,6 +68,11 @@ export interface PaintEditorOptions extends Partial<PaintCanvas> {
     brushLibrary?: BrushLibrary;
     /** Saved user brushes to start the default library with (or to add to `brushLibrary`). */
     brushes?: readonly PaintBrush[];
+    /**
+     * The host's colour scheme (default `light`): a brush's light / dark default colour resolves to
+     * its side when the brush is chosen and when a stroke starts. Follow the host with `setColorScheme`.
+     */
+    colorScheme?: ColorScheme;
     /** Paint colour #rrggbb (default #1f2937). */
     color?: string;
     hand?: Hand;
@@ -114,6 +120,10 @@ export interface PaintEditorState {
     brushes: readonly PaintBrush[];
     /** Paint colour #rrggbb. */
     color: string;
+    /** The colour scheme light / dark brush colours resolve for. */
+    colorScheme: ColorScheme;
+    /** Locked: choosing a brush with a default colour keeps the paint colour. */
+    colorLocked: boolean;
     /** The second colour (swap with `swapColors`). */
     secondaryColor: string;
     /**
@@ -194,6 +204,21 @@ export interface PaintLayerInfo {
     /** How many live layer effects (glows, shadows, strokes…) it has, when any (`getLayerEffects`). */
     effects?: number;
 }
+/** A live stroke as it is painted (`onStrokeSample`), for agents that paint along with the user. */
+export interface PaintStrokeSample {
+    /** `begin`: the pen went down. `points`: new samples. `end`: the stroke was recorded. `cancel`: it was abandoned. */
+    phase: 'begin' | 'points' | 'end' | 'cancel';
+    layerId: string;
+    brush: PaintBrush;
+    /** #rrggbb */
+    color: string;
+    /** Every raw sample so far (document pixels), in order. */
+    points: readonly PenPoint[];
+    /** The samples this event added (`points` only). */
+    added: readonly PenPoint[];
+    /** `end`: the recorded stroke's id, or `null` when it painted nothing. */
+    strokeId?: string | null;
+}
 /** One change to the paint history, for hosts and change feeds (`onCommit`). */
 export interface PaintCommitEvent {
     /** `execute`: a new undo step. `merge`: folded into the last one (a slider drag). */
@@ -361,6 +386,7 @@ export declare class PaintEditorController {
     private readonly encodeImage;
     private listeners;
     private commitListeners;
+    private sampleListeners;
     /** Origins set by `withOrigin`, innermost last. */
     private origins;
     /** `group` in progress: commits fold into one step, recorded when it ends. */
@@ -423,6 +449,21 @@ export declare class PaintEditorController {
     private paperEffectNodeCache;
     constructor(options?: PaintEditorOptions);
     subscribe(listener: () => void): () => void;
+    /**
+     * Hears the user's live strokes as they are painted (`beginStroke` sessions, not strokes painted
+     * from data): when the pen goes down, each batch of samples, and the end or cancel. For agents
+     * that paint along in real time. Returns an unsubscribe function.
+     */
+    onStrokeSample(listener: (sample: PaintStrokeSample) => void): () => void;
+    private notifySample;
+    /** The stroke being painted now, or `null`: its layer, brush, colour and samples so far. */
+    getLiveStroke(): {
+        layerId: string;
+        brushId: string;
+        brushName: string;
+        color: string;
+        points: readonly PenPoint[];
+    } | null;
     /** Hears each undo step recorded, merged, undone or redone, with who made it. Returns an unsubscribe function. */
     onCommit(listener: (event: PaintCommitEvent) => void): () => void;
     private notifyCommit;
@@ -825,6 +866,25 @@ export declare class PaintEditorController {
         height?: number;
         color?: string;
     }): BrushThumbnail;
+    private colorScheme;
+    private colorLocked;
+    /** The brush default colour the paint colour came from (resolved again when the scheme changes), or `null`. */
+    private brushColour;
+    /**
+     * The host's colour scheme: a paint colour that came from a brush's light / dark default
+     * resolves to the new side. Editor state, not an undo step.
+     */
+    setColorScheme(scheme: ColorScheme): void;
+    /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
+    setColorLocked(locked: boolean): void;
+    /**
+     * After the user chooses a brush: its solid or light / dark default colour becomes the paint
+     * colour (resolved for the colour scheme), unless the colour is locked. Gradient defaults are the
+     * brush's own paint already; effect defaults stay a suggestion.
+     */
+    private takeBrushColour;
+    /** A brush that always paints its own colour (`colour.own`): that colour, resolved for the scheme now; else `null`. */
+    private ownColour;
     /** Sets the paint colour (and goes back to one colour from gradient paint). */
     setColor(color: string): string;
     /**

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

@@ -22,6 +22,7 @@ import { type PaintBrushInput, type PaintBrush } from './brushes.js';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.js';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.js';
 import type { Brush } from '../brushes/types.js';
+import type { ColorScheme } from '../color/dual.js';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.js';
 import { type ImageEncoder, type ImageFormat } from './encode.js';
 import type { PenPoint } from './engine.js';
@@ -67,6 +68,11 @@ export interface PaintEditorOptions extends Partial<PaintCanvas> {
     brushLibrary?: BrushLibrary;
     /** Saved user brushes to start the default library with (or to add to `brushLibrary`). */
     brushes?: readonly PaintBrush[];
+    /**
+     * The host's colour scheme (default `light`): a brush's light / dark default colour resolves to
+     * its side when the brush is chosen and when a stroke starts. Follow the host with `setColorScheme`.
+     */
+    colorScheme?: ColorScheme;
     /** Paint colour #rrggbb (default #1f2937). */
     color?: string;
     hand?: Hand;
@@ -114,6 +120,10 @@ export interface PaintEditorState {
     brushes: readonly PaintBrush[];
     /** Paint colour #rrggbb. */
     color: string;
+    /** The colour scheme light / dark brush colours resolve for. */
+    colorScheme: ColorScheme;
+    /** Locked: choosing a brush with a default colour keeps the paint colour. */
+    colorLocked: boolean;
     /** The second colour (swap with `swapColors`). */
     secondaryColor: string;
     /**
@@ -194,6 +204,21 @@ export interface PaintLayerInfo {
     /** How many live layer effects (glows, shadows, strokes…) it has, when any (`getLayerEffects`). */
     effects?: number;
 }
+/** A live stroke as it is painted (`onStrokeSample`), for agents that paint along with the user. */
+export interface PaintStrokeSample {
+    /** `begin`: the pen went down. `points`: new samples. `end`: the stroke was recorded. `cancel`: it was abandoned. */
+    phase: 'begin' | 'points' | 'end' | 'cancel';
+    layerId: string;
+    brush: PaintBrush;
+    /** #rrggbb */
+    color: string;
+    /** Every raw sample so far (document pixels), in order. */
+    points: readonly PenPoint[];
+    /** The samples this event added (`points` only). */
+    added: readonly PenPoint[];
+    /** `end`: the recorded stroke's id, or `null` when it painted nothing. */
+    strokeId?: string | null;
+}
 /** One change to the paint history, for hosts and change feeds (`onCommit`). */
 export interface PaintCommitEvent {
     /** `execute`: a new undo step. `merge`: folded into the last one (a slider drag). */
@@ -361,6 +386,7 @@ export declare class PaintEditorController {
     private readonly encodeImage;
     private listeners;
     private commitListeners;
+    private sampleListeners;
     /** Origins set by `withOrigin`, innermost last. */
     private origins;
     /** `group` in progress: commits fold into one step, recorded when it ends. */
@@ -423,6 +449,21 @@ export declare class PaintEditorController {
     private paperEffectNodeCache;
     constructor(options?: PaintEditorOptions);
     subscribe(listener: () => void): () => void;
+    /**
+     * Hears the user's live strokes as they are painted (`beginStroke` sessions, not strokes painted
+     * from data): when the pen goes down, each batch of samples, and the end or cancel. For agents
+     * that paint along in real time. Returns an unsubscribe function.
+     */
+    onStrokeSample(listener: (sample: PaintStrokeSample) => void): () => void;
+    private notifySample;
+    /** The stroke being painted now, or `null`: its layer, brush, colour and samples so far. */
+    getLiveStroke(): {
+        layerId: string;
+        brushId: string;
+        brushName: string;
+        color: string;
+        points: readonly PenPoint[];
+    } | null;
     /** Hears each undo step recorded, merged, undone or redone, with who made it. Returns an unsubscribe function. */
     onCommit(listener: (event: PaintCommitEvent) => void): () => void;
     private notifyCommit;
@@ -825,6 +866,25 @@ export declare class PaintEditorController {
         height?: number;
         color?: string;
     }): BrushThumbnail;
+    private colorScheme;
+    private colorLocked;
+    /** The brush default colour the paint colour came from (resolved again when the scheme changes), or `null`. */
+    private brushColour;
+    /**
+     * The host's colour scheme: a paint colour that came from a brush's light / dark default
+     * resolves to the new side. Editor state, not an undo step.
+     */
+    setColorScheme(scheme: ColorScheme): void;
+    /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
+    setColorLocked(locked: boolean): void;
+    /**
+     * After the user chooses a brush: its solid or light / dark default colour becomes the paint
+     * colour (resolved for the colour scheme), unless the colour is locked. Gradient defaults are the
+     * brush's own paint already; effect defaults stay a suggestion.
+     */
+    private takeBrushColour;
+    /** A brush that always paints its own colour (`colour.own`): that colour, resolved for the scheme now; else `null`. */
+    private ownColour;
     /** Sets the paint colour (and goes back to one colour from gradient paint). */
     setColor(color: string): string;
     /**

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

@@ -18,6 +18,7 @@ import { CoverageMap, type BrushSettings, type Dab, type StrokePoint } from '../
 import type { RasterRect } from '../raster/surface.cjs';
 import type { PaintBrush } from './brushes.cjs';
 import { type EffectPaintPixels } from './effect-paint.cjs';
+import type { StickerArtLookup } from './sticker-art.cjs';
 import { type PaperGrain } from './paper.cjs';
 /** One pen sample in document pixels. Every channel but x and y is optional. */
 export interface PenPoint {
@@ -126,6 +127,8 @@ export interface DryStrokeOptions {
     copies?: readonly StrokeCopy[];
     /** Effect paint: each pixel takes its colour (and alpha) from these canvas-sized pixels. */
     effect?: EffectPaintPixels | null;
+    /** Loaded sticker art, for a stamp tip of a sticker from the sticker library (`brush.stamp`); without it such a tip paints round. */
+    stampArt?: StickerArtLookup;
 }
 /**
  * One dab-engine stroke (dab and eraser brushes): smoothing, the dab walk of every copy, grain and
@@ -144,12 +147,16 @@ export declare class DryStroke {
     private field;
     private lastRaw;
     private lastFed;
+    /** The stamp tip's shape, or `null` for the round computed tip. */
+    private readonly stamp;
     constructor(brush: PaintBrush, options: DryStrokeOptions);
     /** Feeds raw pen samples; returns the document rectangles the new dabs touched. */
     push(points: readonly PenPoint[]): RasterRect[];
     /** Ends the stroke: the smoothed path catches up with the last raw sample; a single tap paints one dab. */
     finish(): RasterRect[];
     private paint;
+    /** Lays one mark (a dab, or a spray droplet of dab `d`): the round tip or the stamp, the paper grain, effect paint. */
+    private mark;
 }
 /** The shared engine's tip for the Mixer Brush engine (it smooths and walks by itself, so smoothing is applied before). */
 export declare function mixerTip(brush: PaintBrush): BrushSettings;

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

@@ -18,6 +18,7 @@ import { CoverageMap, type BrushSettings, type Dab, type StrokePoint } from '../
 import type { RasterRect } from '../raster/surface.js';
 import type { PaintBrush } from './brushes.js';
 import { type EffectPaintPixels } from './effect-paint.js';
+import type { StickerArtLookup } from './sticker-art.js';
 import { type PaperGrain } from './paper.js';
 /** One pen sample in document pixels. Every channel but x and y is optional. */
 export interface PenPoint {
@@ -126,6 +127,8 @@ export interface DryStrokeOptions {
     copies?: readonly StrokeCopy[];
     /** Effect paint: each pixel takes its colour (and alpha) from these canvas-sized pixels. */
     effect?: EffectPaintPixels | null;
+    /** Loaded sticker art, for a stamp tip of a sticker from the sticker library (`brush.stamp`); without it such a tip paints round. */
+    stampArt?: StickerArtLookup;
 }
 /**
  * One dab-engine stroke (dab and eraser brushes): smoothing, the dab walk of every copy, grain and
@@ -144,12 +147,16 @@ export declare class DryStroke {
     private field;
     private lastRaw;
     private lastFed;
+    /** The stamp tip's shape, or `null` for the round computed tip. */
+    private readonly stamp;
     constructor(brush: PaintBrush, options: DryStrokeOptions);
     /** Feeds raw pen samples; returns the document rectangles the new dabs touched. */
     push(points: readonly PenPoint[]): RasterRect[];
     /** Ends the stroke: the smoothed path catches up with the last raw sample; a single tap paints one dab. */
     finish(): RasterRect[];
     private paint;
+    /** Lays one mark (a dab, or a spray droplet of dab `d`): the round tip or the stamp, the paper grain, effect paint. */
+    private mark;
 }
 /** The shared engine's tip for the Mixer Brush engine (it smooths and walks by itself, so smoothing is applied before). */
 export declare function mixerTip(brush: PaintBrush): BrushSettings;