@pixerate/editor 0.103.0 → 0.105.0

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

@@ -1,9 +1,9 @@
-import { R as RasterLayer, a as RasterGroupLayer, b as RasterPixelLayer, C as CompositorLayer, c as RasterCompositor, d as RasterSources, L as LayerLocks } from '../compositor-B1ZrKR89.js';
-import { B as BrushSettings, M as MixerSettings, C as CoverageMap, D as Dab, S as StrokePoint, a as MixerLoad } from '../mixer-DG_9Yu2W.js';
-export { b as MAX_BRUSH_SIZE } from '../mixer-DG_9Yu2W.js';
-import { R as RasterRect, a as TiledSurface, B as BlendMode } from '../surface-AfHCH7BR.js';
-export { b as Tile } from '../surface-AfHCH7BR.js';
-import { I as ImageEditorAssetStore, S as SerializedLayer, P as PsdExportResult } from '../export-BLpMyCYg.js';
+import { R as RasterLayer, a as RasterGroupLayer, b as RasterPixelLayer, C as CompositorLayer, c as RasterCompositor, d as RasterSources, L as LayerLocks } from '../compositor-BsYYllvR.js';
+import { B as BrushSettings, M as MixerSettings, C as CoverageMap, D as Dab, S as StrokePoint, a as MixerLoad } from '../mixer-Cu5a9Bzd.js';
+export { b as MAX_BRUSH_SIZE } from '../mixer-Cu5a9Bzd.js';
+import { R as RasterRect, a as TiledSurface, B as BlendMode } from '../surface-BBJN9wxg.js';
+export { b as BLEND_MODES, c as Tile, i as isBlendMode } from '../surface-BBJN9wxg.js';
+import { I as ImageEditorAssetStore, S as SerializedLayer, P as PsdExportResult } from '../export-iMrop3Jm.js';
 import { a as AgentToolProvider } from '../registry-D-4fit9C.js';
 import '../types-CwMPoRMU.js';
 import '../warp-CWHZzE3x.js';
@@ -203,12 +203,14 @@ interface PaintBrush {
 }
 declare function normalizeDynamics(raw?: Partial<BrushDynamics>, base?: BrushDynamics): BrushDynamics;
 declare const BRUSH_ID: RegExp;
-/** A brush with every field in range; missing fields come from `base` (default: a plain round dab brush). */
-declare function normalizePaintBrush(raw?: Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer'>> & {
+/** Brush settings to change or read: any subset of a brush, its tip, dynamics and mixer. */
+type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer'>> & {
     tip?: Partial<BrushSettings>;
     dynamics?: Partial<BrushDynamics>;
     mixer?: Partial<MixerSettings>;
-}, base?: PaintBrush): PaintBrush;
+};
+/** A brush with every field in range; missing fields come from `base` (default: a plain round dab brush). */
+declare function normalizePaintBrush(raw?: PaintBrushInput, base?: PaintBrush): PaintBrush;
 /** The built-in brush library. */
 declare const BUILTIN_BRUSHES: readonly PaintBrush[];
 declare const DEFAULT_BRUSH_ID = "pencil-6b";
@@ -517,6 +519,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 +661,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 +672,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[];
 }
@@ -815,6 +825,17 @@ type ImageEncoder = (image: {
 }, format: 'image/jpeg' | 'image/webp', quality: number) => Promise<Uint8Array>;
 /** An encoder through `OffscreenCanvas`, or `null` where there is none (Node, tests). */
 declare function defaultImageEncoder(): ImageEncoder | null;
+/**
+ * Decodes an image file (PNG, JPEG, WebP, … whatever the browser reads) into RGBA pixels through
+ * `createImageBitmap` and an `OffscreenCanvas`. Browser and Worker only.
+ */
+declare function decodeImageBlob(blob: Blob): Promise<{
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}>;
+/** Saves bytes as a file through a temporary link. Browser only. */
+declare function downloadBytes(bytes: Uint8Array | string, fileName: string, mimeType: string): void;
 
 /**
  * Brush thumbnails: a test stroke (an S-curve with pressure swelling and fading, at a steady
@@ -837,6 +858,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 +1115,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. */
@@ -916,11 +1150,18 @@ interface PaintStrokeInit {
     /** Default the active brush. */
     brushId?: string;
     /** Changes to the brush for this stroke only. */
-    brush?: Parameters<typeof normalizePaintBrush>[0];
+    brush?: PaintBrushInput;
     /** 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 +1229,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);
@@ -1072,12 +1320,12 @@ declare class PaintEditorController {
      */
     setBrush(update?: {
         id?: string;
-    } & Omit<Parameters<typeof normalizePaintBrush>[0], 'id'>): PaintBrush;
+    } & Omit<PaintBrushInput, 'id'>): PaintBrush;
     /** Saves the active brush (or `brush`) into the user library under `id` / `name`. */
     saveBrush(options: {
         id: string;
         name?: string;
-        brush?: Parameters<typeof normalizePaintBrush>[0];
+        brush?: PaintBrushInput;
     }): PaintBrush;
     removeBrush(id: string): void;
     /** The user's saved brushes. */
@@ -1154,6 +1402,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 +1460,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 +1549,132 @@ 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 };
+/**
+ * Framework-free UI logic shared by the React and Svelte paint editors, so both behave the same:
+ *
+ * - `PaintGesture` turns pointer events (structurally typed, no DOM import) into strokes (with
+ *   coalesced samples and a predicted tail), colour picks, pans, view rotation and zoom, with palm
+ *   rejection while a pen is down.
+ * - `PaintCanvasPresenter` keeps a document-sized 2D canvas up to date from the compositor,
+ *   uploading only the tiles that changed.
+ * - Guide overlays as line segments, and the slider tables of the brush and paper panels.
+ */
+
+/** The Pointer Event fields the gesture reads. */
+interface PaintPointerEvent extends PointerSample {
+    pointerId: number;
+    clientX: number;
+    clientY: number;
+    button?: number;
+    buttons?: number;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    getCoalescedEvents?(): PaintPointerEvent[];
+    getPredictedEvents?(): PaintPointerEvent[];
+}
+type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate';
+declare const PAINT_TOOLS: ReadonlyArray<{
+    id: PaintTool;
+    label: string;
+    key: string;
+}>;
+/** Where the viewport element is on screen and how big it is (CSS pixels). */
+interface ViewportBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+declare class PaintGesture {
+    private readonly controller;
+    private readonly box;
+    tool: PaintTool;
+    /** The last refusal (a hidden or locked layer), for the editor to show. */
+    error: string | null;
+    /** The predicted tail of the current stroke in document pixels (draw it as a thin preview). */
+    predicted: PenPoint[];
+    private mode;
+    private penAt;
+    private penDown;
+    constructor(controller: PaintEditorController, box: () => ViewportBox);
+    private doc;
+    private pen;
+    /** Pointer down; returns true when the gesture took the pointer (capture it). */
+    down(e: PaintPointerEvent): boolean;
+    private pick;
+    move(e: PaintPointerEvent): void;
+    up(e: PaintPointerEvent): void;
+    cancel(): void;
+    get active(): boolean;
+    /** Wheel: zoom about the pointer (Ctrl / pinch or plain wheel), Shift+wheel rotates the view. */
+    wheel(e: {
+        clientX: number;
+        clientY: number;
+        deltaY: number;
+        shiftKey?: boolean;
+    }): void;
+}
+/** Keyboard shortcuts shared by both editors; returns true when it handled the key. */
+declare function handlePaintShortcut(controller: PaintEditorController, gesture: PaintGesture, e: {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+    target?: unknown;
+}): boolean;
+/** The 2D context methods the presenter uses (a `CanvasRenderingContext2D`). */
+interface Paint2DContext {
+    createImageData(width: number, height: number): {
+        data: Uint8ClampedArray;
+    };
+    putImageData(image: never, dx: number, dy: number, sx?: number, sy?: number, sw?: number, sh?: number): void;
+}
+/** Keeps a document-sized canvas in step with the controller, tile by tile. */
+declare class PaintCanvasPresenter {
+    private readonly controller;
+    private readonly uploaded;
+    private scratch;
+    private size;
+    constructor(controller: PaintEditorController);
+    /** Draws what changed into `ctx` (a canvas the size of the document); returns the tiles drawn. */
+    render(ctx: Paint2DContext): number;
+}
+/** Lines to draw over the canvas for the guides, in document pixels, with a style key. */
+declare function guideOverlay(controller: PaintEditorController): Array<{
+    from: Point2;
+    to: Point2;
+    kind: 'symmetry' | 'perspective' | 'snap';
+}>;
+/** One slider of a panel: a path into the brush (or paper) settings. */
+interface SliderControl {
+    path: string;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+}
+declare const BRUSH_SLIDERS: readonly SliderControl[];
+declare const PAPER_SLIDERS: readonly SliderControl[];
+/** Reads `a.b` from an object. */
+declare function readPath(obj: unknown, path: string): number;
+/** `{a: {b: value}}` for `a.b`, keeping the rest of `obj`'s `a`. */
+declare function patchPath(obj: Record<string, unknown>, path: string, value: number): Record<string, unknown>;
+/** The point on a colour wheel of `radius` (centre 0, 0) for a wheel angle in degrees, red at the top. */
+declare function wheelPoint(angle: number, radius: number): Point2;
+/** The wheel angle (degrees, red at the top, clockwise) of a point relative to the wheel centre. */
+declare function wheelAngle(x: number, y: number): number;
+/**
+ * A hue ring for a colour wheel, `size × size` RGBA: hues at full saturation and value between
+ * `inner` and 1 of the radius, red at the top, laid out on the RYB or RGB wheel.
+ */
+declare function renderColorWheel(size: number, wheel: ColorWheel, inner?: number): {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+};
+/** The colour for a click on the wheel ring at (dx, dy) from its centre, keeping `color`'s saturation and value. */
+declare function wheelPick(dx: number, dy: number, wheel: ColorWheel, color: string): string;
+
+export { type Affine, BRUSH_ID, BRUSH_ROTATIONS, BRUSH_SLIDERS, BUILTIN_BRUSHES, BlendMode, 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, PAINT_TOOLS, PAPER_FAMILIES, PAPER_LIBRARY, PAPER_NODE_ID, PAPER_SLIDERS, type Paint2DContext, type PaintAssetStore, type PaintBrush, type PaintBrushCategory, type PaintBrushEngine, type PaintBrushInput, type PaintCanvas, PaintCanvasPresenter, PaintDocumentError, type PaintDocumentExtensions, type PaintDocumentState, PaintEditorController, PaintEditorError, type PaintEditorOptions, type PaintEditorState, type PaintEditorToolProviderOptions, PaintGesture, type PaintGroupLayer, type PaintGuides, type PaintLayer, type PaintLayerInfo, type PaintPixelLayer, type PaintPointerEvent, type PaintStrokeInit, type PaintStrokeResult, PaintStrokeSession, type PaintTool, 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 SliderControl, type StrokeCopy, type StrokeSessionHost, type StrokeSessionInit, type StrokeVariation, type Swatch, type SymmetryGuide, type SymmetryMode, TRACING_NODE_ID, TileableNoise, type TracingImage, type ViewLayer, type ViewportBox, affineCopy, applyAffine, brushToJSON, clonePaper, colorHarmony, composeAffine, createPaintCompositor, createPaintDocument, createPaintEditorToolProvider, createPaintLayer, decodeImageBlob, defaultGuides, defaultImageEncoder, deserializePaintDocument, deserializePaintDocumentAsync, documentExtensions, documentToScreen, downloadBytes, downsampleRgba, fitZoom, grainCatch, grainHeights, guideOverlay, handlePaintShortcut, 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, patchPath, penOrientation, perspectiveDirections, perspectiveGuideLines, pointerToPenPoint, rand01, randSigned, readPath, renderBrushThumbnail, renderColorWheel, renderPaper, rgbToHexColor, rgbToHsl, rgbToHsv, samplePressure, screenToDocument, seedFromString, serializePaintDocument, serializePaintDocumentExternal, strokeBounds, symmetryAxisAngles, symmetryAxisSegments, symmetryCopies, thumbnailStroke, tiltToOrientation, toStrokePoint, variationAffine, varyStroke, viewCssTransform, viewMatrix, viewPenToDocument, wheelAngle, wheelPick, wheelPoint, wheelToHue };