@pixerate/editor 0.103.0 → 0.104.0

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

@@ -517,6 +517,8 @@ interface StrokeSessionInit {
     /** The stroke's extra copies as affine maps (recorded with the stroke); `copies` holds all of them as engine copies. */
     affineCopies: readonly Affine[];
     copies: readonly StrokeCopy[];
+    /** Applied to each raw sample before it is painted and recorded (perspective snapping). */
+    inputFilter?: (p: PenPoint) => PenPoint;
     /** Mixer engine: the brush load at the start of the stroke. */
     mixerLoad: MixerLoad;
 }
@@ -657,6 +659,9 @@ interface SerializeOptions {
     strokes?: boolean;
     /** Later-phase fields to write as they were read. */
     extensions?: PaintDocumentExtensions;
+    /** Painting guides (symmetry, perspective, tracing and reference images as PNG data URLs). */
+    guides?: unknown;
+    swatches?: unknown;
 }
 /** The document as JSON with inline PNG data URLs. */
 declare function serializePaintDocument(state: PaintDocumentState, options?: SerializeOptions): SerializedPaintDocument;
@@ -665,6 +670,9 @@ declare function serializePaintDocumentExternal(state: PaintDocumentState, store
 interface LoadedPaintDocument {
     state: PaintDocumentState;
     extensions: PaintDocumentExtensions;
+    /** The saved guides and swatches, as stored (the controller validates them). */
+    guides?: unknown;
+    swatches?: unknown;
     /** What could not be read (the rest still loads). */
     problems: string[];
 }
@@ -837,6 +845,213 @@ declare function renderBrushThumbnail(brush: PaintBrush, options: {
     color: string;
 }): BrushThumbnail;
 
+/**
+ * Painting guides: mirror and kaleidoscope symmetry (every stroke paints its reflected or rotated
+ * copies as one stroke), perspective guides with one to three vanishing points that strokes snap
+ * to, a tracing image under the paint (optionally the source of the stroke colour), and floating
+ * reference images to pick colours from. Geometry only: no pixels, no DOM.
+ */
+
+type SymmetryMode = 'off' | 'vertical' | 'horizontal' | 'dual' | 'diagonal' | 'kaleidoscope';
+declare const SYMMETRY_MODES: readonly SymmetryMode[];
+interface SymmetryGuide {
+    mode: SymmetryMode;
+    /** Centre of the axes in document pixels (default the canvas centre). */
+    center: {
+        x: number;
+        y: number;
+    };
+    /** Turns the axes, degrees clockwise (default 0). */
+    rotation: number;
+    /** Kaleidoscope: number of segments, 2..32 (default 6). */
+    segments: number;
+    /** Kaleidoscope: reflect every other segment as well as rotating (default true), like a real kaleidoscope. */
+    mirror: boolean;
+}
+interface Point2 {
+    x: number;
+    y: number;
+}
+interface PerspectiveGuide {
+    enabled: boolean;
+    /** One to three vanishing points in document pixels (they may lie outside the canvas). */
+    points: Point2[];
+    /** Strokes snap to the guide lines (default true when enabled). */
+    snap: boolean;
+}
+/** A view-only image under the paint, placed over the canvas. */
+interface TracingImage {
+    /** PNG or JPEG data URL. */
+    src: string;
+    /** Natural size of the image in pixels. */
+    width: number;
+    height: number;
+    /** Where it is drawn, in document pixels (default: fitted to the canvas). */
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** 0..1 (default 0.35). */
+    opacity: number;
+    visible: boolean;
+    /** Strokes without an explicit colour take the tracing image's colour where they start. */
+    sampleColors: boolean;
+}
+/** A floating image to look at and pick colours from (shown beside the canvas, never painted). */
+interface ReferenceImage {
+    id: string;
+    name: string;
+    src: string;
+    width: number;
+    height: number;
+    /** Where the panel floats over the viewport, in screen pixels, and its displayed width. */
+    x: number;
+    y: number;
+    displayWidth: number;
+    visible: boolean;
+}
+interface PaintGuides {
+    symmetry: SymmetryGuide;
+    perspective: PerspectiveGuide;
+    tracing: TracingImage | null;
+    references: ReferenceImage[];
+}
+declare function defaultGuides(canvas: {
+    width: number;
+    height: number;
+}): PaintGuides;
+declare const MAX_COORDINATE = 1000000;
+declare function normalizeSymmetry(raw: Partial<SymmetryGuide> | Record<string, unknown>, base: SymmetryGuide): SymmetryGuide;
+/** The axis directions of a mirror mode (radians), as photocraft's `directions`. */
+declare function symmetryAxisAngles(g: SymmetryGuide): number[];
+/**
+ * The extra copies a stroke paints under the symmetry guide, as affine maps (the stroke itself is
+ * not included). Vertical, horizontal and diagonal: one reflection. Dual: two reflections and the
+ * point reflection. Kaleidoscope: rotations by 360°/n, and with `mirror` the reflections between them.
+ */
+declare function symmetryCopies(g: SymmetryGuide): Affine[];
+/** The axes clipped to the canvas, for drawing (photocraft's `segments`). */
+declare function symmetryAxisSegments(g: SymmetryGuide, size: {
+    width: number;
+    height: number;
+}): Array<[Point2, Point2]>;
+declare function normalizePerspective(raw: Partial<PerspectiveGuide> | Record<string, unknown>, base: PerspectiveGuide): PerspectiveGuide;
+/** The line families a perspective guide snaps to at `p`: unit directions. */
+declare function perspectiveDirections(g: PerspectiveGuide, p: Point2): Point2[];
+/** How far the pen must move before a stroke chooses its perspective line (document pixels). */
+declare const SNAP_DECIDE_DISTANCE = 6;
+/**
+ * Snaps one stroke to a perspective guide: once the pen has moved `SNAP_DECIDE_DISTANCE` from
+ * where it started, the stroke picks the guide line through its start that best matches its
+ * direction, and every sample after that is projected onto the line.
+ */
+declare class PerspectiveSnapper {
+    private readonly guide;
+    private start;
+    private dir;
+    constructor(guide: PerspectiveGuide);
+    /** The line the stroke follows, once chosen. */
+    get line(): {
+        from: Point2;
+        direction: Point2;
+    } | null;
+    snap<P extends Point2>(p: P): P;
+}
+/** Guide lines to draw for a perspective guide: rays from each vanishing point through the canvas. */
+declare function perspectiveGuideLines(g: PerspectiveGuide, size: {
+    width: number;
+    height: number;
+}, count?: number): Array<[Point2, Point2]>;
+
+/**
+ * Colour for painters: hex / RGB / HSV / HSL conversions, a colour wheel that is either the
+ * painter's red-yellow-blue wheel (where red's complement is green) or the RGB wheel (where it is
+ * cyan), harmonies on it, and swatches.
+ */
+type Rgb255 = [number, number, number];
+declare function parseHexColor(value: unknown, what?: string): Rgb255;
+declare function rgbToHexColor(r: number, g: number, b: number): string;
+/** RGB 0..255 → HSV with h in degrees 0..360, s and v 0..1. */
+declare function rgbToHsv(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    v: number;
+};
+declare function hsvToRgb(h: number, s: number, v: number): Rgb255;
+/** RGB 0..255 → HSL with h in degrees, s and l 0..1. */
+declare function rgbToHsl(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    l: number;
+};
+declare function hslToRgb(h: number, s: number, l: number): Rgb255;
+/** Which wheel hues live on: `ryb` (painter's: red ↔ green complements) or `rgb` (red ↔ cyan). */
+type ColorWheel = 'ryb' | 'rgb';
+/** A wheel angle (degrees) → an RGB hue. */
+declare function wheelToHue(angle: number, wheel: ColorWheel): number;
+/** An RGB hue → its wheel angle (degrees). */
+declare function hueToWheel(hue: number, wheel: ColorWheel): number;
+type HarmonyKind = 'complementary' | 'split-complementary' | 'analogous' | 'triadic' | 'tetradic' | 'square' | 'monochromatic';
+declare const HARMONY_KINDS: readonly HarmonyKind[];
+interface HarmonyColor {
+    color: string;
+    /** Position on the wheel, degrees. */
+    angle: number;
+}
+/**
+ * The colours of a harmony around `base`, the base first. Hue-based harmonies keep the base's
+ * saturation and value and turn it around the wheel; `analogous` spreads by `spread` degrees
+ * (default 30); `monochromatic` keeps the hue and steps the lightness.
+ */
+declare function colorHarmony(base: string, kind: HarmonyKind, options?: {
+    wheel?: ColorWheel;
+    spread?: number;
+}): HarmonyColor[];
+interface Swatch {
+    color: string;
+    name?: string;
+}
+/** A starting palette of our own generic paint colours. */
+declare const DEFAULT_SWATCHES: readonly Swatch[];
+
+/**
+ * The mixing pad: a small canvas beside the painting to put paint on, smear it with a palette
+ * knife and pick the mixed colour from. Paint is laid with the Mixer Brush in pigment mode and the
+ * knife is a pigment smudge, so blue and yellow pushed together make green. It is scratch space:
+ * not part of the painting and not in its undo history.
+ */
+
+type MixingPadTool = 'paint' | 'knife';
+declare const MIXING_PAD_WIDTH = 360;
+declare const MIXING_PAD_HEIGHT = 220;
+declare class MixingPad {
+    readonly width = 360;
+    readonly height = 220;
+    private surface;
+    /** Increments on every change (for redrawing). */
+    version: number;
+    /** Paints (`paint`, with `color`) or smears (`knife`) through `points` in pad pixels. */
+    stroke(points: readonly PenPoint[], options: {
+        tool: MixingPadTool;
+        color: string;
+        size?: number;
+    }): {
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        } | null;
+    };
+    /** The average colour within `radius` pixels of (x, y), or `null` where the pad is bare. */
+    pick(x: number, y: number, radius?: number): string | null;
+    clear(): void;
+    /** The pad over white, `width × height` RGBA. */
+    pixels(): Uint8ClampedArray;
+}
+
 /**
  * `PaintEditorController`: the natural-media paint editor's state, framework-free.
  *
@@ -887,6 +1102,12 @@ interface PaintEditorState {
     canRedo: boolean;
     undoLabel: string | null;
     redoLabel: string | null;
+    /** Mirror / kaleidoscope, perspective, tracing image and reference images (saved with the document, not undo steps). */
+    guides: PaintGuides;
+    /** The colour swatches (saved with the document, not undo steps). */
+    swatches: readonly Swatch[];
+    /** Changes whenever the mixing pad does. */
+    mixingPadVersion: number;
     /** A stroke is in progress. */
     stroking: boolean;
     /** Increments on every change. */
@@ -919,8 +1140,15 @@ interface PaintStrokeInit {
     brush?: Parameters<typeof normalizePaintBrush>[0];
     /** Jitter seed (default: a new one per stroke). */
     seed?: number;
-    /** Extra copies of the stroke as affine maps (mirror / kaleidoscope). */
+    /** Extra copies of the stroke as affine maps (default: the symmetry guide's). */
     copies?: readonly Affine[];
+    /** Snap the samples to the perspective guide (default true for `beginStroke`, false for `paintStroke`). */
+    snapToPerspective?: boolean;
+    /** Where the stroke starts, for taking its colour from the tracing image before the first sample (`beginStroke`). */
+    start?: {
+        x: number;
+        y: number;
+    };
 }
 interface LayerUpdate {
     name?: string;
@@ -988,6 +1216,13 @@ declare class PaintEditorController {
     private dirty;
     private seedCounter;
     private strokeCounter;
+    private guides;
+    private swatches;
+    private readonly pad;
+    private tracingVersion;
+    private tracingCache;
+    private readonly imagePixels;
+    private nextReferenceId;
     private readonly viewCompositor;
     private readonly exportCompositor;
     constructor(options?: PaintEditorOptions);
@@ -1154,6 +1389,8 @@ declare class PaintEditorController {
     private currentLayers;
     /** View-only layers between the paper and the paint (the painting guides add the tracing image). */
     protected underlayLayers(): ViewLayer[];
+    /** The tracing image resampled onto the canvas (cached until it or the canvas changes). */
+    private tracingNode;
     private renderLayers;
     /**
      * Composites the viewport stack (paper, view-only underlays, layers with the live stroke) tile by
@@ -1210,10 +1447,79 @@ declare class PaintEditorController {
         width: number;
         height: number;
     };
+    private setGuides;
+    /** Mirror and kaleidoscope painting: every new stroke paints its copies too (one stroke, one undo step). */
+    setSymmetry(update: Partial<SymmetryGuide>): SymmetryGuide;
+    /** Perspective guides with one to three vanishing points that pointer strokes snap to. */
+    setPerspective(update: Partial<PerspectiveGuide>): PerspectiveGuide;
+    /** An image from a PNG (base64 or data URL) or from RGBA pixels, stored as a PNG data URL. */
+    private importImage;
+    private decodeImage;
+    /**
+     * Puts an image under the paint to trace over: view only, never in exports. Placed to fit the
+     * canvas unless `rect` is given; `sampleColors` makes strokes take their colour from it.
+     */
+    setTracingImage(options: {
+        png?: string;
+        pixels?: PixelImage;
+        rect?: TracingImage['rect'];
+        opacity?: number;
+        sampleColors?: boolean;
+    }): TracingImage;
+    /** Changes the tracing image's opacity, visibility, placement or colour sampling. */
+    updateTracing(update: Partial<Pick<TracingImage, 'opacity' | 'visible' | 'sampleColors' | 'rect'>>, base?: TracingImage | null): TracingImage;
+    clearTracingImage(): void;
+    /** The tracing image's colour at a document pixel, or `null` outside it or where it is clear. */
+    sampleTracingColor(x: number, y: number): string | null;
+    /** Adds a floating reference image to look at and pick colours from. */
+    addReferenceImage(options: {
+        png?: string;
+        pixels?: PixelImage;
+        name?: string;
+        x?: number;
+        y?: number;
+        displayWidth?: number;
+    }): ReferenceImage;
+    private requireReference;
+    /** Moves, resizes, renames, shows or hides a reference image. */
+    updateReferenceImage(id: string, update: Partial<Pick<ReferenceImage, 'name' | 'x' | 'y' | 'displayWidth' | 'visible'>>): ReferenceImage;
+    removeReferenceImage(id: string): void;
+    /** A reference image's pixels (decoded once). */
+    referencePixels(id: string): PixelImage;
+    /** The colour of a reference image at its pixel (x, y). */
+    pickReferenceColor(id: string, x: number, y: number): string;
+    private readGuides;
+    /** Colour harmonies around a colour (default the paint colour) on the painter's RYB wheel or the RGB wheel. */
+    harmony(kind: HarmonyKind, options?: {
+        color?: string;
+        wheel?: ColorWheel;
+        spread?: number;
+    }): HarmonyColor[];
+    addSwatch(color: string, name?: string): Swatch[];
+    removeSwatch(index: number): Swatch[];
+    setSwatches(swatches: readonly Swatch[]): Swatch[];
+    get mixingPad(): MixingPad;
+    /** Paints (`paint`) or smears with the palette knife (`knife`) on the mixing pad, in pad pixels. */
+    mixingPadStroke(points: readonly PenPoint[], options?: {
+        tool?: MixingPadTool;
+        color?: string;
+        size?: number;
+    }): {
+        bounds: RasterRect | null;
+    };
+    /** Picks the mixed colour on the pad (averaged over `radius` px); with `setColor` it becomes the paint colour. */
+    mixingPadPick(x: number, y: number, options?: {
+        radius?: number;
+        setColor?: boolean;
+    }): string | null;
+    clearMixingPad(): void;
     /** A layer's tile surface (live while stroking), for thumbnails. */
     layerSurface(id: string): TiledSurface | null;
 }
 
+/** Largest tracing or reference image side, in pixels. */
+declare const MAX_IMAGE_SIDE = 8192;
+
 /**
  * Agent tools for the paint editor (`createPaintEditorToolProvider`). Strict schemas, every
  * argument described, all four annotations. Each write is one undo step (or editor state, said so)
@@ -1230,4 +1536,4 @@ interface PaintEditorToolProviderOptions {
 /** Agent tools for one paint editor. */
 declare function createPaintEditorToolProvider(controller: PaintEditorController, options?: PaintEditorToolProviderOptions): AgentToolProvider;
 
-export { type Affine, BRUSH_ID, BRUSH_ROTATIONS, BUILTIN_BRUSHES, type BrushDynamics, type BrushLibraryFile, type BrushRotation, type BrushThumbnail, DEFAULT_BRUSH_ID, DEFAULT_DPI, DEFAULT_DYNAMICS, DEFAULT_PAPER, DEFAULT_VIEW, DryStroke, type DryStrokeOptions, type FillLayerOptions, GRAIN_PATTERNS, GRAIN_TILE, type GrainPattern, type GrainTuning, type Hand, IDENTITY_AFFINE, IDENTITY_COPY, type ImageEncoder, type ImageFormat, type ImageNode, type LayerUpdate, type Linear2, type LoadedPaintDocument, MAX_CANVAS_SIDE, MAX_ZOOM, MIN_CANVAS_SIDE, MIN_ZOOM, PAINT_BRUSH_CATEGORIES, PAINT_BRUSH_ENGINES, PAINT_FORMAT, PAINT_SCHEMA_VERSION, PAPER_FAMILIES, PAPER_LIBRARY, PAPER_NODE_ID, type PaintAssetStore, type PaintBrush, type PaintBrushCategory, type PaintBrushEngine, type PaintCanvas, PaintDocumentError, type PaintDocumentExtensions, type PaintDocumentState, PaintEditorController, PaintEditorError, type PaintEditorOptions, type PaintEditorState, type PaintEditorToolProviderOptions, type PaintGroupLayer, type PaintLayer, type PaintLayerInfo, type PaintPixelLayer, type PaintStrokeInit, type PaintStrokeResult, PaintStrokeSession, type PaintView, type PaperFamily, PaperGrain, type PaperNode, type PaperSettings, type PaperTiling, type PenDab, PenDabWalker, type PenPoint, PenSmoother, type PixelImage, type PointerSample, type RecordedStroke, type RenderOptions, type ReplayOptions, type SerializeOptions, type SerializedPaintDocument, type StrokeCopy, type StrokeSessionHost, type StrokeSessionInit, type StrokeVariation, TRACING_NODE_ID, TileableNoise, type ViewLayer, affineCopy, applyAffine, brushToJSON, clonePaper, composeAffine, createPaintCompositor, createPaintDocument, createPaintEditorToolProvider, createPaintLayer, defaultImageEncoder, deserializePaintDocument, deserializePaintDocumentAsync, documentExtensions, documentToScreen, downsampleRgba, fitZoom, grainCatch, grainHeights, hash2, hexToRgb8, invertAffine, isPalmTouch, mapPenPoint, mix32, mixerLoadForStroke, mixerTip, newPaintLayerId, normalizeBrushStroke, normalizeCanvas, normalizeDynamics, normalizePaintBrush, normalizePaper, normalizeRotation, normalizeView, paperGrain, paperKey, paperNode, paperPreset, parseBrushLibrary, penOrientation, pointerToPenPoint, rand01, randSigned, renderBrushThumbnail, renderPaper, samplePressure, screenToDocument, seedFromString, serializePaintDocument, serializePaintDocumentExternal, strokeBounds, thumbnailStroke, tiltToOrientation, toStrokePoint, variationAffine, varyStroke, viewCssTransform, viewMatrix, viewPenToDocument };
+export { type Affine, BRUSH_ID, BRUSH_ROTATIONS, BUILTIN_BRUSHES, type BrushDynamics, type BrushLibraryFile, type BrushRotation, type BrushThumbnail, type ColorWheel, DEFAULT_BRUSH_ID, DEFAULT_DPI, DEFAULT_DYNAMICS, DEFAULT_PAPER, DEFAULT_SWATCHES, DEFAULT_VIEW, DryStroke, type DryStrokeOptions, type FillLayerOptions, GRAIN_PATTERNS, GRAIN_TILE, type GrainPattern, type GrainTuning, HARMONY_KINDS, type Hand, type HarmonyColor, type HarmonyKind, IDENTITY_AFFINE, IDENTITY_COPY, type ImageEncoder, type ImageFormat, type ImageNode, type LayerUpdate, type Linear2, type LoadedPaintDocument, MAX_CANVAS_SIDE, MAX_COORDINATE, MAX_IMAGE_SIDE, MAX_ZOOM, MIN_CANVAS_SIDE, MIN_ZOOM, MIXING_PAD_HEIGHT, MIXING_PAD_WIDTH, MixingPad, type MixingPadTool, PAINT_BRUSH_CATEGORIES, PAINT_BRUSH_ENGINES, PAINT_FORMAT, PAINT_SCHEMA_VERSION, PAPER_FAMILIES, PAPER_LIBRARY, PAPER_NODE_ID, type PaintAssetStore, type PaintBrush, type PaintBrushCategory, type PaintBrushEngine, type PaintCanvas, PaintDocumentError, type PaintDocumentExtensions, type PaintDocumentState, PaintEditorController, PaintEditorError, type PaintEditorOptions, type PaintEditorState, type PaintEditorToolProviderOptions, type PaintGroupLayer, type PaintGuides, type PaintLayer, type PaintLayerInfo, type PaintPixelLayer, type PaintStrokeInit, type PaintStrokeResult, PaintStrokeSession, type PaintView, type PaperFamily, PaperGrain, type PaperNode, type PaperSettings, type PaperTiling, type PenDab, PenDabWalker, type PenPoint, PenSmoother, type PerspectiveGuide, PerspectiveSnapper, type PixelImage, type Point2, type PointerSample, type RecordedStroke, type ReferenceImage, type RenderOptions, type ReplayOptions, type Rgb255, SNAP_DECIDE_DISTANCE, SYMMETRY_MODES, type SerializeOptions, type SerializedPaintDocument, type StrokeCopy, type StrokeSessionHost, type StrokeSessionInit, type StrokeVariation, type Swatch, type SymmetryGuide, type SymmetryMode, TRACING_NODE_ID, TileableNoise, type TracingImage, type ViewLayer, affineCopy, applyAffine, brushToJSON, clonePaper, colorHarmony, composeAffine, createPaintCompositor, createPaintDocument, createPaintEditorToolProvider, createPaintLayer, defaultGuides, defaultImageEncoder, deserializePaintDocument, deserializePaintDocumentAsync, documentExtensions, documentToScreen, downsampleRgba, fitZoom, grainCatch, grainHeights, hash2, hexToRgb8, hslToRgb, hsvToRgb, hueToWheel, invertAffine, isPalmTouch, mapPenPoint, mix32, mixerLoadForStroke, mixerTip, newPaintLayerId, normalizeBrushStroke, normalizeCanvas, normalizeDynamics, normalizePaintBrush, normalizePaper, normalizePerspective, normalizeRotation, normalizeSymmetry, normalizeView, paperGrain, paperKey, paperNode, paperPreset, parseBrushLibrary, parseHexColor, penOrientation, perspectiveDirections, perspectiveGuideLines, pointerToPenPoint, rand01, randSigned, renderBrushThumbnail, renderPaper, rgbToHexColor, rgbToHsl, rgbToHsv, samplePressure, screenToDocument, seedFromString, serializePaintDocument, serializePaintDocumentExternal, strokeBounds, symmetryAxisAngles, symmetryAxisSegments, symmetryCopies, thumbnailStroke, tiltToOrientation, toStrokePoint, variationAffine, varyStroke, viewCssTransform, viewMatrix, viewPenToDocument, wheelToHue };