@pixerate/editor 0.277.0 → 0.278.0

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

@@ -23,7 +23,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 ColorScheme, type ColorValue } 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';
@@ -206,8 +206,8 @@ export interface LiveStrokeUpdate {
     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;
+    /** A new colour #rrggbb, or a light / dark pair (replaces gradient or effect paint). */
+    color?: ColorValue;
     /** 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). */
@@ -275,8 +275,12 @@ export interface PaintPreviewPlacement {
 export interface PaintStrokeInit {
     /** Default the active layer. */
     layerId?: string;
-    /** Default the editor colour. */
-    color?: string;
+    /**
+     * Default the editor colour. A light / dark pair (`DualColor`) is recorded with the stroke
+     * (`RecordedStroke.dualColor`): on a stroke layer the document draws its light side and the view
+     * the viewer's (`setColorScheme`); on a pixel layer it paints the scheme's side.
+     */
+    color?: ColorValue;
     /**
      * What this stroke paints with, instead of the editor's paint: a colour, gradient paint
      * (`@pixerate/editor/paint` `PaintSource`), or effect paint (render it first with
@@ -1062,9 +1066,29 @@ export declare class PaintEditorController {
     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.
+     * resolves to the new side, and stroke layers show their dual-colour strokes in it. Only the
+     * view changes: the document, history and change listeners don't hear of it.
      */
     setColorScheme(scheme: ColorScheme): void;
+    /**
+     * Stroke layers in the colour scheme: the document keeps every stroke layer drawn with each
+     * stroke's `color` (a dual-colour stroke's light side), so saved and shared documents never
+     * depend on who is looking. The view (display, image exports, the base a pointer stroke paints
+     * on) draws dual-colour strokes in the scheme's side instead. One cached surface per layer,
+     * brought up to date from the strokes that changed since it was drawn.
+     */
+    private schemeViews;
+    private schemeCopies;
+    /** Set while a stroke is painted for the document rather than the view (`runStroke` on a stroke layer): dual colours take this side. */
+    private paintScheme;
+    /** A stroke as the scheme shows it: itself, or (a dual-colour stroke) a copy in the scheme's side. */
+    private schemeStroke;
+    /** A stroke layer's surface in the scheme, or `null` when the document's pixels already show it. */
+    private schemeSurface;
+    /** `layers` with each stroke layer that holds dual-colour strokes shown in the scheme. */
+    private schemeLayers;
+    /** The paint colour's light / dark pair for a stroke with `brushId`, when the colour came from one (a brush's own or default colour, or `setColor`). */
+    private dualPaint;
     /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
     setColorLocked(locked: boolean): void;
     /**
@@ -1075,8 +1099,12 @@ export declare class PaintEditorController {
     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;
+    /**
+     * Sets the paint colour (and goes back to one colour from gradient paint). A light / dark pair
+     * paints the colour scheme's side, follows `setColorScheme`, and is recorded with each stroke
+     * painted in it. Returns the colour as #rrggbb.
+     */
+    setColor(color: ColorValue): string;
     /**
      * Sets what strokes paint with: one colour (`{ type: 'color', color }` or `#rrggbb`), or gradient
      * paint (`{ type: 'gradient', stops, space?, map?, softness? }`, see `@pixerate/editor/paint`),
@@ -1775,6 +1803,10 @@ export declare class PaintEditorController {
     liveStrokeArea(id: string): RasterRect | null;
     /** Commits a layer's new stroke list with its redrawn pixels, recorded for replays (one undo step). */
     private commitLiveStrokes;
+    /**
+     * The document with a layer's strokes set and its pixels redrawn. With `record` false (the same
+     * strokes drawn for the colour scheme) the pixel lock doesn't apply and no event is recorded for replays.
+     */
     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;

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

@@ -23,7 +23,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 ColorScheme, type ColorValue } 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';
@@ -206,8 +206,8 @@ export interface LiveStrokeUpdate {
     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;
+    /** A new colour #rrggbb, or a light / dark pair (replaces gradient or effect paint). */
+    color?: ColorValue;
     /** 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). */
@@ -275,8 +275,12 @@ export interface PaintPreviewPlacement {
 export interface PaintStrokeInit {
     /** Default the active layer. */
     layerId?: string;
-    /** Default the editor colour. */
-    color?: string;
+    /**
+     * Default the editor colour. A light / dark pair (`DualColor`) is recorded with the stroke
+     * (`RecordedStroke.dualColor`): on a stroke layer the document draws its light side and the view
+     * the viewer's (`setColorScheme`); on a pixel layer it paints the scheme's side.
+     */
+    color?: ColorValue;
     /**
      * What this stroke paints with, instead of the editor's paint: a colour, gradient paint
      * (`@pixerate/editor/paint` `PaintSource`), or effect paint (render it first with
@@ -1062,9 +1066,29 @@ export declare class PaintEditorController {
     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.
+     * resolves to the new side, and stroke layers show their dual-colour strokes in it. Only the
+     * view changes: the document, history and change listeners don't hear of it.
      */
     setColorScheme(scheme: ColorScheme): void;
+    /**
+     * Stroke layers in the colour scheme: the document keeps every stroke layer drawn with each
+     * stroke's `color` (a dual-colour stroke's light side), so saved and shared documents never
+     * depend on who is looking. The view (display, image exports, the base a pointer stroke paints
+     * on) draws dual-colour strokes in the scheme's side instead. One cached surface per layer,
+     * brought up to date from the strokes that changed since it was drawn.
+     */
+    private schemeViews;
+    private schemeCopies;
+    /** Set while a stroke is painted for the document rather than the view (`runStroke` on a stroke layer): dual colours take this side. */
+    private paintScheme;
+    /** A stroke as the scheme shows it: itself, or (a dual-colour stroke) a copy in the scheme's side. */
+    private schemeStroke;
+    /** A stroke layer's surface in the scheme, or `null` when the document's pixels already show it. */
+    private schemeSurface;
+    /** `layers` with each stroke layer that holds dual-colour strokes shown in the scheme. */
+    private schemeLayers;
+    /** The paint colour's light / dark pair for a stroke with `brushId`, when the colour came from one (a brush's own or default colour, or `setColor`). */
+    private dualPaint;
     /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
     setColorLocked(locked: boolean): void;
     /**
@@ -1075,8 +1099,12 @@ export declare class PaintEditorController {
     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;
+    /**
+     * Sets the paint colour (and goes back to one colour from gradient paint). A light / dark pair
+     * paints the colour scheme's side, follows `setColorScheme`, and is recorded with each stroke
+     * painted in it. Returns the colour as #rrggbb.
+     */
+    setColor(color: ColorValue): string;
     /**
      * Sets what strokes paint with: one colour (`{ type: 'color', color }` or `#rrggbb`), or gradient
      * paint (`{ type: 'gradient', stops, space?, map?, softness? }`, see `@pixerate/editor/paint`),
@@ -1775,6 +1803,10 @@ export declare class PaintEditorController {
     liveStrokeArea(id: string): RasterRect | null;
     /** Commits a layer's new stroke list with its redrawn pixels, recorded for replays (one undo step). */
     private commitLiveStrokes;
+    /**
+     * The document with a layer's strokes set and its pixels redrawn. With `record` false (the same
+     * strokes drawn for the colour scheme) the pixel lock doesn't apply and no event is recorded for replays.
+     */
     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;