Skip to content

Realistic watercolor drawings

TypeScript paintwatercolor
82.2 KB
Raw Blame
import { BRUSH_PRESETS, buildBrush, type Brush } from './brushes';
import { GL, type DoubleTarget, type Format, type Program, type Rect, type Target } from './gl';
import { History, type StepInfo, type StepKind } from './history';
import { DEFAULT_PAPER, linearRGB, PAPERS, type PaperPreset } from './papers';
import * as S from './shaders';
import { pigmentFromHex, type Pigment } from './spectral';

export type Tool = 'brush' | 'water' | 'pen' | 'lift';

/** All sliders are normalised 0..1. */
export interface Params {
  size: number;
  water: number;       // how much water the brush carries
  load: number;        // pigment concentration on the brush
  flow: number;        // strength of the water's motion
  bleed: number;       // diffusion of pigment through wet paper
  dry: number;         // drying speed
  edge: number;        // tide-line darkening at drying edges
  granulation: number; // pigment settling into the paper grain
}

export const DEFAULT_PARAMS: Params = {
  size: 0.5, water: 0.6, load: 0.5, flow: 0.45, bleed: 0.5, dry: 0.4, edge: 0.5, granulation: 0.45,
};

export interface EngineCallbacks {
  /** The undo history changed: every step (oldest first) and how many of them are applied. */
  onHistoryChange?(steps: StepInfo[], index: number): void;
  /** Paper or reference state changed from inside the engine (undo, redo, a project opened). */
  onDocumentChange?(state: DocState): void;
  /** The active tool changed for the current stroke (pencil barrel / finger-as-water). */
  onStrokeTool?(tool: Tool | null): void;
  /** The view was zoomed or panned (`zoom` 1 = one document texel per CSS pixel). */
  onViewChange?(zoom: number, docSize: [number, number]): void;
}

export type ExportFormat = 'png' | 'jpeg' | 'webp';
export type ExportBackground = 'transparent' | 'paper' | 'white';
/** `texture` false exports the paper (or white) as a flat sheet; true uses the on-screen texture strength. */
export interface ExportOptions { format: ExportFormat; background: ExportBackground; quality?: number; texture?: boolean }

/** Placement of the reference image in document uv (y up): origin and size. */
export interface RefRect { x: number; y: number; w: number; h: number }

export type LayerId = 'inkA' | 'inkB' | 'fixedA' | 'fixedB' | 'wet';

/**
 * The paint layers as half floats (RGBA for ink and fixed, one channel for wet), cropped
 * to `rect`, the texel rect holding everything ever painted (null: a blank sheet).
 */
export interface WholeDoc { w: number; h: number; rect: Rect | null; layers: Record<LayerId, Uint16Array> }

/** Document-level state that undo tracks besides the paint. */
export interface DocState {
  paperId: string;
  paperStrength: number;
  reference: { image: HTMLCanvasElement | null; rect: RefRect; opacity: number; visible: boolean };
}

/** Everything needed to bring a painting back exactly as it is. */
export interface DocumentSnapshot {
  whole: WholeDoc;
  paper: { id: string; seed: number; origin: [number, number]; scale: number; strength: number };
  wet: { wetAgo: number; wetPeak: number; active: Rect | null; painted: Rect | null };
  reference: DocState['reference'];
  view: { zoom: number; pan: [number, number]; fitted: boolean };
}

/** How the display shader composites: on screen (with the reference) or for an export. */
const MODE = { screen: 0, paper: 1, transparent: 2, white: 3 } as const;
const MAX_REF_SIDE = 4096;

interface Sample { x: number; y: number; p: number; t: number; tx: number; ty: number }

interface Stroke {
  pointerId: number;
  pointerType: string;
  tool: Tool;
  started: boolean;
  ending: boolean;
  x: number; y: number;       // where the drawn stroke currently ends (uv)
  cx: number; cy: number;     // latest smoothed sample: the curve's control point, drawn up to on the next sample
  pr: number;                 // pressure at (x, y), so pressure ramps along each curve
  t: number;                 // time of last sample (ms)
  speed: number;              // doc heights / second
  simPressure: number;        // pressure stand-in for mice and fingers
  carry: number;              // distance travelled since the last stamp (doc heights)
  travelled: number;
  moved: boolean;             // received movement this frame
  dx: number; dy: number;     // smoothed direction (aspect-corrected, unit-ish)
  angle: number;              // tip angle of the last dab (radians, doc frame)
  azimuth: number | null;     // pen tilt direction, when the pen is tilted enough to tell
}

const DEG = Math.PI / 180;
const SCRIPT_POINTER = -1;

interface StepMeta {
  wetAgo: number; wetPeak: number; active: Rect | null; painted: Rect | null;
  doc: DocState;
  /** Boundary (resize) steps: the whole sheet as it was, and where its paper sat. */
  whole?: WholeDoc; paperOrigin?: [number, number];
}
const STROKE_LABEL: Record<Tool, string> = { brush: 'Brush stroke', water: 'Water', pen: 'Pen', lift: 'Lift' };

const HALF_FLOAT_RG: Format = { internal: WebGL2RenderingContext.RG16F, format: WebGL2RenderingContext.RG, type: WebGL2RenderingContext.HALF_FLOAT };
const HALF_FLOAT_R: Format = { internal: WebGL2RenderingContext.R16F, format: WebGL2RenderingContext.RED, type: WebGL2RenderingContext.HALF_FLOAT };
const HALF_FLOAT_RGBA: Format = { internal: WebGL2RenderingContext.RGBA16F, format: WebGL2RenderingContext.RGBA, type: WebGL2RenderingContext.HALF_FLOAT };
const RGBA8: Format = { internal: WebGL2RenderingContext.RGBA8, format: WebGL2RenderingContext.RGBA, type: WebGL2RenderingContext.UNSIGNED_BYTE };
const FLOAT_RG: Format = { internal: WebGL2RenderingContext.RG32F, format: WebGL2RenderingContext.RG, type: WebGL2RenderingContext.FLOAT };
const FILL_WATER_LEAD = 10;    // px the water runs ahead of the pigment in a bucket fill
const FILL_WIDTH = 24;         // px over which a bucket fill's front ramps up
const FILL_JITTER = 3;         // px the paper grain roughens a bucket fill's front

const SIM_BASE = 256;          // short side of the velocity / pressure grid
const PRESSURE_ITERATIONS = 20;
const SCREEN_DOC_LONG = 2048;   // a "screen" sheet follows the window, within these limits
const SCREEN_DOC_SHORT = 1536;
const MAX_DOC_LONG = 3072;     // pigment / water grid limits (live state: ~56 bytes per texel)
const MAX_DOC_PIXELS = 4_200_000;   // (plus an undo atlas of ~52 bytes per texel)
export const MIN_DOC_SIDE = 256;
export const MIN_ZOOM = 0.02;
export const MAX_ZOOM = 32;
const FIT_PADDING = 24;        // CSS px around the sheet when zoomed to fit
const PAN_KEEP = 48;           // CSS px of the sheet that always stays on screen
const FIX_DURATION = 1.2;
const WET_THRESHOLD = 0.004;   // below this nothing moves, so the sim can sleep
const MASK_BLOCK = 16;         // texels per wet-mask cell
const MASK_EVERY = 10;         // frames between wet-mask readbacks that trim the active rect
const MASK_MARGIN = MASK_BLOCK + 8;
const PROTECT_MARGIN = 24;     // texels around a dab / fill band saved for undo, where its water and pigment spread to
const DESK = [1, 1, 1];      // the table the sheet lies on (sRGB)
const PAPER_UNITS = 1100;      // paper features are drawn for a sheet this many texels tall

const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));

/** A sheet size within the memory limits: the same shape, scaled down if too big. */
export function clampDocSize(w: number, h: number, maxSide = MAX_DOC_LONG): [number, number] {
  w = Math.max(MIN_DOC_SIDE, Math.round(w) || MIN_DOC_SIDE);
  h = Math.max(MIN_DOC_SIDE, Math.round(h) || MIN_DOC_SIDE);
  const s = Math.min(1, Math.min(MAX_DOC_LONG, maxSide) / Math.max(w, h), Math.sqrt(MAX_DOC_PIXELS / (w * h)));
  return [Math.max(MIN_DOC_SIDE, Math.round(w * s)), Math.max(MIN_DOC_SIDE, Math.round(h * s))];
}

const union = (a: Rect | null, b: Rect): Rect =>
  a ? { x0: Math.min(a.x0, b.x0), y0: Math.min(a.y0, b.y0), x1: Math.max(a.x1, b.x1), y1: Math.max(a.y1, b.y1) } : { ...b };

export class WatercolorEngine {
  params: Params = { ...DEFAULT_PARAMS };
  tool: Tool = 'brush';
  pigment: Pigment = pigmentFromHex('#2338a8');
  brush: Brush = buildBrush(BRUSH_PRESETS[0]);
  /** Once an Apple Pencil / stylus is seen, fingers paint with clear water. */
  fingerIsWater = true;
  /** When false, pointers on the paper are ignored (another tool, e.g. text, is driving it). */
  interactive = true;
  /** Footprint scale of the scripted stroke in progress (see scriptBegin). */
  private scriptScale = 1;
  private nav = false;

  private tipTextures = new Map<string, WebGLTexture>();
  private paperPreset: PaperPreset = DEFAULT_PAPER;
  private paperSeed = 0;
  private paperStrength = 1;
  private paperScale = 1;                           // paper units per texel, fixed when the sheet is made
  private paperOrigin: [number, number] = [0, 0];   // where the sheet sits in the paper's field (texels)
  // reference image: shown under the paint on screen only, never exported
  private ref: { tex: WebGLTexture; aspect: number; src: HTMLCanvasElement } | null = null;
  private refRect: RefRect = { x: 0, y: 0, w: 1, h: 1 };
  private refOpacity = 0.5;
  private refVisible = true;
  private lastDir: [number, number] = [1, 0];      // direction of the last stroke, for the first dab
  private lastAngle = 0;                            // tip angle shown by the hover cursor

  private g: GL;
  private gl: WebGL2RenderingContext;
  private programs: Record<string, Program>;
  private canvasSize: [number, number] = [1, 1];
  private dpr = 1;
  private view = { x: 0, y: 0, w: 1, h: 1 };   // document placement in canvas px
  private zoomLevel = 1;                        // 1 = one document texel per CSS px
  private pan: [number, number] = [0, 0];       // sheet centre from canvas centre (canvas px, y up)
  private fitMode = true;                       // keep the sheet fitted as the window changes

  // document state
  private dw = 1; private dh = 1;
  private velocity!: DoubleTarget;
  private pressure!: DoubleTarget;
  private divergence!: Target;
  private curl!: Target;
  private ink!: DoubleTarget;
  private fixed!: Target;
  private wet!: DoubleTarget;
  private paper!: Target;
  private wetMask!: Target;                    // coarse "is there water here" map, read back to bound the sim
  private maskPixels = new Uint8Array(0);
  private maskCounter = 0;
  private history!: History;

  // simulation bookkeeping
  private active: Rect | null = null;          // document texels the sim must process
  private painted: Rect | null = null;         // where mobile pigment may exist (since the last fix)
  private everPainted: Rect | null = null;     // where any pigment, mobile or fixed, may exist
  private dirty: Rect | null = null;           // document texels to redraw
  private dirtyAll = true;
  private lastWet = -Infinity;                 // ms timestamp of the last water added
  private wetPeak = 0;
  private minAwakeUntil = 0;
  private fixTimer = 0;
  private flowSpeed = 0;                       // upper bound on water speed (sim texels / s)
  private growCarry = 0;                       // fractional texels the active rect still has to grow
  private brushNow = { x: 0, y: 0, r: 0 };
  private raf = 0;
  private lastFrame = 0;
  private seenEvictions = 0;           // history.evictions as of the last onHistoryChange

  // input
  private stroke: Stroke | null = null;
  private fill: { tex: WebGLTexture; bbox: Rect } | null = null;   // a paint-bucket wash in progress
  private queue: Sample[] = [];
  private pencilSeen = false;
  private hover = { x: 0, y: 0, inside: false, type: 'mouse' };
  private force = { value: 0, t: -Infinity };
  private disposers: (() => void)[] = [];

  /** `size` is the sheet in texels; omitted, the sheet follows the window ("screen"). */
  constructor(private canvas: HTMLCanvasElement, private cursor: HTMLElement | null, private callbacks: EngineCallbacks = {}, size?: [number, number] | null) {
    const gl = canvas.getContext('webgl2', {
      alpha: false, depth: false, stencil: false, antialias: false, preserveDrawingBuffer: true,
      powerPreference: 'high-performance',
    });
    if (!gl) throw new Error('WebGL2 is not available in this browser.');
    if (!gl.getExtension('EXT_color_buffer_float') && !gl.getExtension('EXT_color_buffer_half_float'))
      throw new Error('This GPU cannot render to floating-point textures.');
    this.gl = gl;
    this.g = new GL(gl);
    gl.disable(gl.BLEND);
    this.programs = {
      splat: this.g.program(S.splatFS),
      stamp: this.g.program(S.stampFS),
      fill: this.g.program(S.fillFS),
      advectVelocity: this.g.program(S.advectVelocityFS),
      divergence: this.g.program(S.divergenceFS),
      pressure: this.g.program(S.pressureFS),
      gradient: this.g.program(S.gradientSubtractFS),
      curl: this.g.program(S.curlFS),
      vorticity: this.g.program(S.vorticityFS),
      scale: this.g.program(S.scaleFS),
      advectWet: this.g.program(S.advectWetFS),
      wetMask: this.g.program(S.wetMaskFS),
      advectInk: this.g.program(S.advectInkFS),
      settle: this.g.program(S.settleFS),
      bleach: this.g.program(S.bleachFS),
      lift: this.g.program(S.liftFS),
      paperField: this.g.program(S.paperFieldFS),
      paperLight: this.g.program(S.paperLightFS),
      paperSwatch: this.g.program(S.paperSwatchFS),
      display: this.g.program(S.displayFS),
    };
    this.fitCanvas();
    this.createDocument(size ?? this.screenSize);
    this.attachInput();
    this.schedule();
  }

  /* ------------------------------------------------------------------ setup */

  private fitCanvas() {
    this.dpr = Math.min(window.devicePixelRatio || 1, 2);
    const r = this.canvas.getBoundingClientRect();
    const w = Math.max(2, Math.round(r.width * this.dpr)), h = Math.max(2, Math.round(r.height * this.dpr));
    this.canvas.width = w; this.canvas.height = h;
    this.canvasSize = [w, h];
    if (this.fitMode) this.fitZoom(); else this.updateView();
  }

  /** The zoom that shows the whole sheet with a margin. */
  private fitZoom() {
    const [cw, ch] = this.canvasSize;
    const pad = 2 * FIT_PADDING * this.dpr;
    const z = Math.min((cw - pad) / this.dw, (ch - pad) / this.dh) / this.dpr;
    this.zoomLevel = clamp(z, MIN_ZOOM, MAX_ZOOM);
    this.pan = [0, 0];
    this.fitMode = true;
    this.updateView();
  }

  /** Place the sheet from zoom and pan; everything that maps pointers goes through `view`. */
  private updateView() {
    const [cw, ch] = this.canvasSize;
    const s = this.zoomLevel * this.dpr, w = this.dw * s, h = this.dh * s;
    // keep a strip of the sheet on screen so it can't be lost off the edge
    const keep = PAN_KEEP * this.dpr;
    const mx = Math.max(0, (cw + w) / 2 - keep), my = Math.max(0, (ch + h) / 2 - keep);
    this.pan = [clamp(this.pan[0], -mx, mx), clamp(this.pan[1], -my, my)];
    this.view = { x: (cw - w) / 2 + this.pan[0], y: (ch - h) / 2 + this.pan[1], w, h };
    this.dirtyAll = true;
    this.updateCursor();
    this.callbacks.onViewChange?.(this.zoomLevel, [this.dw, this.dh]);
  }

  /** A sheet the shape of the window, in device pixels, within the "screen" limits. */
  get screenSize(): [number, number] {
    const [cw, ch] = this.canvasSize;
    const s = Math.min(1, SCREEN_DOC_LONG / Math.max(cw, ch), SCREEN_DOC_SHORT / Math.min(cw, ch));
    return clampDocSize(cw * s, ch * s, this.maxSide);
  }

  /** The longest sheet side this GPU allows. */
  get maxSide() { return Math.min(MAX_DOC_LONG, this.gl.getParameter(this.gl.MAX_TEXTURE_SIZE) as number); }

  /** Allocate every document-sized target for a `dw`×`dh` sheet (the old ones are the caller's to free). */
  private allocateTargets() {
    const { gl, g } = this;
    const ar = this.dw / this.dh;
    const sim = ar > 1 ? { w: Math.round(SIM_BASE * ar), h: SIM_BASE } : { w: SIM_BASE, h: Math.round(SIM_BASE / ar) };
    this.velocity = g.double(sim.w, sim.h, [HALF_FLOAT_RG], gl.LINEAR);
    this.pressure = g.double(sim.w, sim.h, [HALF_FLOAT_R], gl.NEAREST);
    this.divergence = g.target(sim.w, sim.h, [HALF_FLOAT_R], gl.NEAREST);
    this.curl = g.target(sim.w, sim.h, [HALF_FLOAT_R], gl.NEAREST);
    this.ink = g.double(this.dw, this.dh, [HALF_FLOAT_RGBA, HALF_FLOAT_RGBA], gl.LINEAR);
    this.fixed = g.target(this.dw, this.dh, [HALF_FLOAT_RGBA, HALF_FLOAT_RGBA], gl.LINEAR);
    this.wet = g.double(this.dw, this.dh, [HALF_FLOAT_R], gl.LINEAR);
    this.paper = g.target(this.dw, this.dh, [RGBA8], gl.LINEAR);
    this.wetMask = g.target(Math.ceil(this.dw / MASK_BLOCK), Math.ceil(this.dh / MASK_BLOCK), [RGBA8], gl.NEAREST);
    this.maskPixels = new Uint8Array(this.wetMask.w * this.wetMask.h * 4);
  }

  private allocateHistory() {
    this.history = new History(this.g, this.dw, this.dh, [
      { formats: [HALF_FLOAT_RGBA, HALF_FLOAT_RGBA, HALF_FLOAT_R], documents: 2 }, // mobile pigment + water
      { formats: [HALF_FLOAT_RGBA, HALF_FLOAT_RGBA], documents: 1 },               // fixed pigment
    ]);
  }

  /** The targets that hold the sheet (not the sim grids, not the history atlases). */
  private docTargets(): Target[] {
    return [this.velocity.read, this.velocity.write, this.pressure.read, this.pressure.write, this.divergence, this.curl,
      this.ink.read, this.ink.write, this.fixed, this.wet.read, this.wet.write, this.paper, this.wetMask];
  }

  /** (Re)create a blank `w`×`h` sheet. Discards the painting. */
  private createDocument([w, h]: [number, number]) {
    const oldAspect = this.aspect;
    [this.dw, this.dh] = clampDocSize(w, h, this.maxSide);
    // a reference placed on paper of another shape would be stretched; fit it afresh
    if (this.ref && Math.abs(this.aspect - oldAspect) > 1e-3) this.fitReference();
    this.g.disposeTargets();
    this.allocateTargets();
    this.allocateHistory();

    this.paperSeed = Math.random();
    this.paperScale = PAPER_UNITS / this.dh;
    this.paperOrigin = [0, 0];
    this.drawPaper(this.paper, this.paperOrigin, this.paperScale);

    this.resetPaintState();
    if (this.fitMode) this.fitZoom(); else this.updateView();
    this.notifyHistory();
  }

  private resetPaintState() {
    this.active = null;
    this.painted = null;
    this.everPainted = null;
    this.dirty = null;
    this.dirtyAll = true;
    this.lastWet = -Infinity;
    this.wetPeak = 0;
    this.fixTimer = 0;
    this.flowSpeed = 0;
  }

  /**
   * Change the sheet to `w`×`h` texels, keeping the painting at its size and centred:
   * a bigger sheet adds blank paper around it, a smaller one crops it. The paper grain
   * stays registered under the paint. The change is one undo step; the steps before it
   * are forgotten (their undo tiles belong to the old sheet).
   */
  resizeDocument(w: number, h: number) {
    [w, h] = clampDocSize(w, h, this.maxSide);
    const ow = this.dw, oh = this.dh;
    if (w === ow && h === oh) return;
    this.stroke = null;
    this.dropFill();
    this.queue = [];
    const { g } = this;
    const ox = Math.round((w - ow) / 2), oy = Math.round((h - oh) / 2);
    const meta: StepMeta = { ...this.currentMeta(), whole: this.captureWhole(), paperOrigin: [...this.paperOrigin] };
    const old = { targets: this.docTargets(), ink: this.ink.read, fixed: this.fixed, wet: this.wet.read };
    this.dw = w; this.dh = h;
    this.allocateTargets();
    this.history.beginBoundary({ kind: 'resize', label: `Resize ${w} × ${h}` }, meta, w, h);

    // the overlap of the old sheet (shifted by ox, oy) and the new one
    const sx = Math.max(0, -ox), sy = Math.max(0, -oy), dx = Math.max(0, ox), dy = Math.max(0, oy);
    const cw = Math.min(ow - sx, w - dx), ch = Math.min(oh - sy, h - dy);
    const copy = (src: Target, dsts: Target[]) => {
      if (cw > 0 && ch > 0) src.views.forEach((v, i) => dsts.forEach(d => g.blit(v, sx, sy, d.views[i], dx, dy, cw, ch)));
    };
    copy(old.ink, [this.ink.read, this.ink.write]);
    copy(old.wet, [this.wet.read, this.wet.write]);
    copy(old.fixed, [this.fixed]);
    old.targets.forEach(t => g.disposeTarget(t));

    this.paperOrigin = [this.paperOrigin[0] - ox, this.paperOrigin[1] - oy];
    this.drawPaper(this.paper, this.paperOrigin, this.paperScale);

    const shift = (r: Rect | null): Rect | null => {
      if (!r) return null;
      const n = { x0: Math.max(0, r.x0 + ox), y0: Math.max(0, r.y0 + oy), x1: Math.min(w, r.x1 + ox), y1: Math.min(h, r.y1 + oy) };
      return n.x1 > n.x0 && n.y1 > n.y0 ? n : null;
    };
    this.active = shift(this.active);
    this.painted = shift(this.painted);
    this.everPainted = shift(this.everPainted);
    this.dirty = null;
    const rr = this.refRect;
    this.refRect = { x: (rr.x * ow + ox) / w, y: (rr.y * oh + oy) / h, w: (rr.w * ow) / w, h: (rr.h * oh) / h };

    if (this.fitMode) this.fitZoom(); else this.updateView();
    this.notifyHistory();
    this.callbacks.onDocumentChange?.(this.docState());
    this.schedule();
  }

  /* ------------------------------------------------- whole-document state */

  /** The paint layers, cropped to where anything was ever painted. */
  private captureWhole(): WholeDoc {
    const r = this.everPainted;
    const { g, dw, dh } = this;
    const read = (fb: WebGLFramebuffer, ch: 1 | 4) => (r ? g.readHalf(fb, dw, dh, ch, r) : new Uint16Array(0));
    return {
      w: dw, h: dh, rect: r ? { ...r } : null,
      layers: {
        inkA: read(this.ink.read.views[0], 4), inkB: read(this.ink.read.views[1], 4),
        fixedA: read(this.fixed.views[0], 4), fixedB: read(this.fixed.views[1], 4),
        wet: read(this.wet.read.views[0], 1),
      },
    };
  }

  /** Put `whole`'s layers into the (blank) current targets; both halves of the ping-pong pairs. */
  private uploadWhole(whole: WholeDoc) {
    const r = whole.rect;
    if (!r) return;
    const { gl, g } = this;
    const w = r.x1 - r.x0, h = r.y1 - r.y0;
    const up = (tex: WebGLTexture, format: number, data: Uint16Array) => g.uploadHalf(tex, r.x0, r.y0, w, h, format, data);
    for (const t of [this.ink.read, this.ink.write]) { up(t.tex[0], gl.RGBA, whole.layers.inkA); up(t.tex[1], gl.RGBA, whole.layers.inkB); }
    up(this.fixed.tex[0], gl.RGBA, whole.layers.fixedA);
    up(this.fixed.tex[1], gl.RGBA, whole.layers.fixedB);
    for (const t of [this.wet.read, this.wet.write]) up(t.tex[0], gl.RED, whole.layers.wet);
    this.everPainted = { ...r };
  }

  /** Replace the sheet with `whole` (another size, usually), keeping the history atlases. */
  private applyWhole(whole: WholeDoc, paperOrigin: [number, number]) {
    const old = this.docTargets();
    this.dw = whole.w; this.dh = whole.h;
    this.allocateTargets();
    old.forEach(t => this.g.disposeTarget(t));
    this.history.resize(this.dw, this.dh);
    this.paperOrigin = [...paperOrigin];
    this.drawPaper(this.paper, this.paperOrigin, this.paperScale);
    this.everPainted = null;
    this.uploadWhole(whole);
    this.dirty = null;
    this.dirtyAll = true;
    if (this.fitMode) this.fitZoom(); else this.updateView();
  }

  private docState(): DocState {
    return {
      paperId: this.paperPreset.id,
      paperStrength: this.paperStrength,
      reference: { image: this.ref?.src ?? null, rect: { ...this.refRect }, opacity: this.refOpacity, visible: this.refVisible },
    };
  }

  /** Paper and reference state as undo tracks it. */
  get documentState(): DocState { return this.docState(); }

  /** Bring paper / reference state back (after undo, redo or a project opened). */
  private applyDocState(d: DocState) {
    const preset = PAPERS.find(p => p.id === d.paperId);
    if (preset && preset !== this.paperPreset) { this.paperPreset = preset; this.drawPaper(this.paper, this.paperOrigin, this.paperScale); }
    this.paperStrength = clamp(d.paperStrength, 0, 1);
    const r = d.reference;
    if (r.image !== (this.ref?.src ?? null)) this.uploadReference(r.image);
    this.refRect = { ...r.rect };
    this.refOpacity = r.opacity;
    this.refVisible = r.visible;
    this.dirtyAll = true;
  }

  /**
   * Record a document-level change that has already been applied (paper, reference) as
   * one undo step; `before` is the state to come back to.
   */
  recordChange(kind: StepKind, label: string, before: DocState) {
    this.dropFill();
    this.history.begin({ kind, label }, { ...this.currentMeta(), doc: before } satisfies StepMeta);
    this.notifyHistory();
  }

  /** The painting as it is now, ready to be saved. */
  snapshot(): DocumentSnapshot {
    const m = this.currentMeta();
    return {
      whole: this.captureWhole(),
      paper: { id: this.paperPreset.id, seed: this.paperSeed, origin: [...this.paperOrigin], scale: this.paperScale, strength: this.paperStrength },
      wet: { wetAgo: m.wetAgo, wetPeak: m.wetPeak, active: m.active, painted: m.painted },
      reference: m.doc.reference,
      view: { zoom: this.zoomLevel, pan: [...this.pan], fitted: this.fitMode },
    };
  }

  /** Replace the painting with a saved one. History starts afresh. */
  restore(s: DocumentSnapshot) {
    const [w, h] = clampDocSize(s.whole.w, s.whole.h, this.maxSide);
    if (w !== s.whole.w || h !== s.whole.h) throw new Error(`This sheet (${s.whole.w} × ${s.whole.h}) is too large for this GPU.`);
    this.stroke = null;
    this.dropFill();
    this.queue = [];
    if (this.ref) { this.gl.deleteTexture(this.ref.tex); this.ref = null; }
    this.g.disposeTargets();
    this.dw = w; this.dh = h;
    this.allocateTargets();
    this.allocateHistory();
    this.resetPaintState();

    this.paperPreset = PAPERS.find(p => p.id === s.paper.id) ?? DEFAULT_PAPER;
    this.paperSeed = s.paper.seed;
    this.paperScale = s.paper.scale || PAPER_UNITS / this.dh;
    this.paperOrigin = [...s.paper.origin];
    this.paperStrength = clamp(s.paper.strength, 0, 1);
    this.drawPaper(this.paper, this.paperOrigin, this.paperScale);

    this.uploadWhole(s.whole);
    const now = performance.now();
    this.lastWet = Number.isFinite(s.wet.wetAgo) ? now - s.wet.wetAgo : -Infinity;
    this.wetPeak = s.wet.wetPeak;
    this.active = s.wet.active ? { ...s.wet.active } : null;
    this.painted = s.wet.painted ? { ...s.wet.painted } : null;
    if (this.active) this.minAwakeUntil = now + 250;

    this.uploadReference(s.reference.image);
    this.refRect = { ...s.reference.rect };
    this.refOpacity = clamp(s.reference.opacity, 0, 1);
    this.refVisible = s.reference.visible;

    this.zoomLevel = clamp(s.view.zoom, MIN_ZOOM, MAX_ZOOM);
    this.pan = [...s.view.pan];
    this.fitMode = s.view.fitted;
    if (this.fitMode) this.fitZoom(); else this.updateView();
    this.notifyHistory();
    this.callbacks.onDocumentChange?.(this.docState());
    this.schedule();
  }

  /* ---------------------------------------------------------------- view */

  /** Current zoom: 1 shows one document texel per CSS pixel. */
  get zoom() { return this.zoomLevel; }

  /** True while the sheet is fitted to the window (it stays fitted as the window changes). */
  get fitted() { return this.fitMode; }

  /** While navigating (e.g. Space held) pointers on the paper pan instead of paint. */
  get navigating() { return this.nav; }
  set navigating(v: boolean) { this.nav = v; this.updateCursor(); }

  /** Zoom by `factor` keeping the document point under (clientX, clientY) in place. */
  zoomAt(clientX: number, clientY: number, factor: number) {
    const r = this.canvas.getBoundingClientRect();
    const [cw, ch] = this.canvasSize;
    const z = clamp(this.zoomLevel * factor, MIN_ZOOM, MAX_ZOOM);
    const k = z / this.zoomLevel;
    if (k === 1) return;
    const px = (clientX - r.left) * this.dpr, py = ch - (clientY - r.top) * this.dpr;
    // the sheet centre moves away from the fixed point by the zoom ratio
    const cx = cw / 2 + this.pan[0], cy = ch / 2 + this.pan[1];
    this.pan = [px - (px - cx) * k - cw / 2, py - (py - cy) * k - ch / 2];
    this.zoomLevel = z;
    this.fitMode = false;
    this.updateView();
    this.schedule();
  }

  /** Zoom to `z` about the middle of the window. */
  zoomTo(z: number) {
    const r = this.canvas.getBoundingClientRect();
    this.zoomAt(r.left + r.width / 2, r.top + r.height / 2, z / this.zoomLevel);
  }

  /** Show the whole sheet. */
  zoomToFit() { this.fitZoom(); this.schedule(); }

  /** Move the sheet by (dx, dy) CSS pixels. */
  panBy(dx: number, dy: number) {
    if (!dx && !dy) return;
    this.pan = [this.pan[0] + dx * this.dpr, this.pan[1] - dy * this.dpr];
    this.fitMode = false;
    this.updateView();
    this.schedule();
  }

  /* ------------------------------------------------------------- public API */

  setParams(p: Partial<Params>) { Object.assign(this.params, p); }

  /** Document width / height. Document uv has y up; x spans `aspect` heights. */
  get aspect() { return this.dw / this.dh; }

  /** Client (CSS px) -> document uv. */
  clientToDoc(clientX: number, clientY: number): [number, number] { return this.toUv({ clientX, clientY }); }

  /** Document uv -> client (CSS px). */
  docToClient(x: number, y: number): [number, number] {
    const r = this.canvas.getBoundingClientRect();
    return [r.left + (this.view.x + x * this.view.w) / this.dpr, r.top + (this.canvasSize[1] - this.view.y - y * this.view.h) / this.dpr];
  }

  /** Document size in texels. */
  get docSize(): [number, number] { return [this.dw, this.dh]; }

  /* ------------------------------------------------- paint-bucket fills (fill) */

  /** Is a bucket fill in progress? */
  get filling() { return this.fill !== null; }

  /** How far (px) past the farthest field distance a fill must run so its roughened front covers everything. */
  get fillMargin() { return FILL_WIDTH + FILL_JITTER + 1; }

  /**
   * The document as a flat image: pigment on plain paper with no relief, grain, edge
   * darkening or wet tint, so areas of one colour read as one colour. RGBA8, row 0 is
   * document y = 0 (uv is y-up, so no flip is needed to index it by texel).
   */
  readFlat(): Uint8Array { return this.readback(true); }

  /**
   * Start a bucket fill: `field` is RG per document texel (distance from the tap in
   * px, -1 outside the area; distance to the area's edge), `bbox` the half-open texel
   * rect around it. Opens one undo step for the whole wash. False while a stroke is
   * still on the paper.
   */
  fillBegin(field: Float32Array, bbox: Rect, label = 'Fill'): boolean {
    if (this.stroke) return false;
    if (field.length !== this.dw * this.dh * 2) throw new Error('fill field does not match the document');
    this.beginStep('fill', label);   // also drops any previous fill
    const tex = this.g.texture(this.dw, this.dh, FLOAT_RG, field, this.gl.NEAREST);
    this.fill = { tex, bbox: { ...bbox } };
    return true;
  }

  /**
   * Deposit the band `from < distance <= to` of the current fill: pigment (if `paint`)
   * and water, feathered over `soft` px at the area's edge. False once the fill is
   * gone (undo, clear, another action), in which case the caller should stop.
   */
  fillStep(from: number, to: number, o: { strength: number; water: number; soft: number; paint: boolean }): boolean {
    const f = this.fill;
    if (!f) return false;
    const { gl, g } = this;
    const P = this.params;
    this.touch(f.bbox);
    const p = this.programs.fill;
    p.bind();
    gl.uniform1i(p.u.uField, g.bindTex(0, f.tex));
    gl.uniform1i(p.u.uPaper, g.bindTex(1, this.paper.tex[0]));
    gl.uniform1f(p.u.uSoft, Math.max(0, o.soft));
    gl.uniform1f(p.u.uGrainThr, 0.5);
    gl.uniform1f(p.u.uJitter, FILL_JITTER);
    gl.uniform1f(p.u.uWidth, FILL_WIDTH);
    gl.enable(gl.BLEND);
    if (o.paint) {
      // a steady stroke's density (brush case of stamp(), full reservoir, medium pressure)
      const conc = 0.15 * Math.exp(P.load * 2.8) * 0.84;
      const amount = conc * o.strength;
      const c = this.pigment.coeffs;
      gl.uniform1i(p.u.uCumulative, 0);
      gl.uniform1f(p.u.uFrom, from);
      gl.uniform1f(p.u.uTo, to);
      gl.uniform1f(p.u.uGrain, 0.12);
      gl.uniform4f(p.u.uColor0, c[0] * amount, c[1] * amount, c[2] * amount, c[3] * amount);
      gl.uniform4f(p.u.uColor1, c[4] * amount, c[5] * amount, c[6] * amount, this.pigment.white * amount * 1.6);
      gl.blendEquation(gl.FUNC_ADD);
      gl.blendFunc(gl.ONE, gl.ONE);
      g.draw(this.ink.read, f.bbox);
    }
    // the water runs a little ahead of the pigment, as a real wash does
    const wetAmt = (0.25 + 0.75 * o.water) * 0.9;
    gl.uniform1i(p.u.uCumulative, 1);
    gl.uniform1f(p.u.uTo, to + FILL_WATER_LEAD);
    gl.uniform1f(p.u.uGrain, 0);
    gl.uniform4f(p.u.uColor0, wetAmt, 0, 0, 0);
    gl.uniform4f(p.u.uColor1, 0, 0, 0, 0);
    gl.blendEquation(gl.MAX);
    g.draw(this.wet.read, f.bbox);
    gl.blendEquation(gl.FUNC_ADD);
    gl.disable(gl.BLEND);
    this.wetPeak = Math.max(this.wetPeak * this.wetDecay(), wetAmt);
    this.lastWet = performance.now();
    this.schedule();
    return true;
  }

  /** Finish (or stop) the current fill; what has been laid down stays. */
  fillEnd() { this.dropFill(); }

  private dropFill() {
    if (!this.fill) return;
    this.gl.deleteTexture(this.fill.tex);
    this.fill = null;
  }

  /* -------------------------------------------------- scripted strokes (text) */

  /** Is a code-driven stroke in progress? */
  get scripting() { return this.stroke?.pointerId === SCRIPT_POINTER; }

  /**
   * Start a stroke driven by code rather than a pointer; it runs through the same
   * pipeline (spacing, speed thinning, dwell, undo). Returns false while another
   * stroke is still on the paper. A string `step` opens an undo step with that label;
   * pass false to group several strokes (the letters of a word) into one. `maxRadius`
   * (document heights) shrinks a footprint that would be wider than that at full
   * pressure, so a big brush still writes small letters legibly.
   */
  scriptBegin(tool: Tool, x: number, y: number, pressure: number, step: string | false = 'Stroke', maxRadius?: number): boolean {
    if (this.stroke) return false;
    if (step !== false) this.beginStep('script', step);
    this.scriptScale = maxRadius ? Math.min(1, maxRadius / this.radius(tool, 1, 0)) : 1;
    this.stroke = {
      pointerId: SCRIPT_POINTER, pointerType: 'pen', tool, started: false, ending: false,
      x: 0, y: 0, cx: 0, cy: 0, pr: 0, t: performance.now(), speed: 0, simPressure: 0.45, carry: 0, travelled: 0, moved: false,
      dx: this.lastDir[0], dy: this.lastDir[1], angle: this.lastAngle, azimuth: null,
    };
    this.queue.push({ x, y, p: clamp(pressure, 0.02, 1), t: performance.now(), tx: 0, ty: 0 });
    this.schedule();
    return true;
  }

  /** Feed the scripted stroke a sample; `t` is a performance.now() timestamp. False once the stroke is gone (undo, clear). */
  scriptMove(x: number, y: number, pressure: number, t: number): boolean {
    if (!this.scripting) return false;
    this.queue.push({ x, y, p: clamp(pressure, 0.02, 1), t, tx: 0, ty: 0 });
    this.schedule();
    return true;
  }

  scriptEnd() {
    if (!this.scripting) return;
    this.stroke!.ending = true;
    this.schedule();
  }

  setPigment(p: Pigment) { this.pigment = p; }

  /* ------------------------------------------------------------------ paper */

  get paperId() { return this.paperPreset.id; }

  /** How strongly the sheet's relief, fibres and flecks show (0: a flat tint, 1: full), on screen and in textured exports. */
  get paperTexture() { return this.paperStrength; }
  set paperTexture(v: number) {
    v = clamp(v, 0, 1);
    if (v === this.paperStrength) return;
    this.paperStrength = v;
    this.redraw();
  }

  /**
   * Swap the sheet under the painting. Only the paper changes: the paint stays, and
   * granulation and dry brush follow the new tooth from here on.
   */
  setPaper(p: PaperPreset) {
    if (p === this.paperPreset) return;
    this.paperPreset = p;
    this.drawPaper(this.paper, this.paperOrigin, this.paperScale);
    this.redraw();
  }

  /**
   * A preview of a paper at the scale it appears on screen: `w`×`h` device pixels of
   * the sheet with a granulating wash across one corner, as an sRGB canvas.
   */
  paperSwatch(p: PaperPreset, w: number, h: number): HTMLCanvasElement {
    const { gl, g } = this;
    const paper = g.target(w, h, [RGBA8], gl.LINEAR);
    const out = g.target(w, h, [RGBA8], gl.NEAREST);
    // one canvas pixel shows dh / view.h document texels
    this.drawPaper(paper, [w * 0.7, h * 1.3], this.paperScale * (this.dh / this.view.h), p);
    const s = this.programs.paperSwatch;
    s.bind();
    gl.uniform1i(s.u.uPaper, g.bindTex(0, paper.tex[0]));
    this.paperUniforms(s, p, 1);
    g.draw(out);
    const px = new Uint8Array(w * h * 4);
    gl.bindFramebuffer(gl.FRAMEBUFFER, out.fbo);
    gl.readPixels(0, 0, w, h, gl.RGBA, gl.UNSIGNED_BYTE, px);
    g.disposeTarget(paper);
    g.disposeTarget(out);
    const c = document.createElement('canvas');
    c.width = w; c.height = h;
    const ctx = c.getContext('2d')!;
    const img = ctx.createImageData(w, h);
    for (let y = 0; y < h; y++) img.data.set(px.subarray((h - 1 - y) * w * 4, (h - y) * w * 4), y * w * 4);
    ctx.putImageData(img, 0, 0);
    return c;
  }

  /** Generate a paper into `t`: `offset` places it on the sheet (texels), `scale` is paper units per texel. */
  private drawPaper(t: Target, offset: [number, number], scale: number, preset = this.paperPreset) {
    const { gl, g } = this;
    const field = g.target(t.w, t.h, [HALF_FLOAT_RGBA], gl.NEAREST);
    const f = this.programs.paperField;
    f.bind();
    gl.uniform2f(f.u.uRes, t.w, t.h);
    gl.uniform2f(f.u.uOffset, offset[0], offset[1]);
    gl.uniform1f(f.u.uScale, scale);
    gl.uniform1f(f.u.uSeed, this.paperSeed);
    gl.uniform1i(f.u.uKind, preset.kind);
    g.draw(field);
    const l = this.programs.paperLight;
    l.bind();
    gl.uniform1i(l.u.uField, g.bindTex(0, field.tex[0]));
    gl.uniform2f(l.u.uTexel, 1 / t.w, 1 / t.h);
    // the relief is drawn in paper units, so its slope per texel shrinks as texels get smaller
    gl.uniform1f(l.u.uBump, (preset.bump * 1.4) / scale);
    g.draw(t);
    g.disposeTarget(field);
  }

  private paperUniforms(p: Program, preset: PaperPreset, texture: number) {
    const { gl } = this;
    gl.uniform3fv(p.u.uPaperTint, linearRGB(preset.tint));
    gl.uniform3fv(p.u.uFleckTint, linearRGB(preset.fleck));
    gl.uniform1f(p.u.uMottle, preset.mottle);
    gl.uniform1f(p.u.uTexture, texture);
  }

  setTool(t: Tool) { this.tool = t; this.updateCursor(); }

  setBrush(b: Brush) {
    this.brush = b;
    this.lastAngle = b.rotation === 'fixed' ? b.angle * DEG : b.rotation === 'follow' ? Math.atan2(this.lastDir[1], this.lastDir[0]) + b.angle * DEG : 0;
    this.updateCursor();
  }

  /* ------------------------------------------------------- reference image */

  get hasReference() { return this.ref !== null; }

  /** Width / height of the reference image, or 0 without one. */
  get referenceAspect() { return this.ref?.aspect ?? 0; }

  /**
   * Show `img` under the paint (or remove it with null), fitted to the paper, as one
   * undo step. It survives clearing the paper and is never part of an export.
   */
  setReference(img: ImageBitmap | HTMLCanvasElement | null) {
    const before = this.docState();
    let src: HTMLCanvasElement | null = null;
    if (img) {
      const max = Math.min(MAX_REF_SIDE, this.gl.getParameter(this.gl.MAX_TEXTURE_SIZE) as number);
      // kept on the CPU as well, so the Fill tool can find areas on it (see readReferenceFlat)
      const s = Math.min(1, max / Math.max(img.width, img.height));
      src = document.createElement('canvas');
      src.width = Math.max(1, Math.round(img.width * s)); src.height = Math.max(1, Math.round(img.height * s));
      src.getContext('2d')!.drawImage(img, 0, 0, src.width, src.height);
    }
    this.uploadReference(src);
    if (src) this.fitReference();
    this.recordChange('reference', src ? 'Reference added' : 'Reference removed', before);
    this.redraw();
  }

  /** The reference image as the engine keeps it (downscaled), or null. */
  referenceImage(): HTMLCanvasElement | null { return this.ref?.src ?? null; }

  /** Put `src` on the GPU as the reference (or drop it with null); placement is left alone. */
  private uploadReference(src: HTMLCanvasElement | null) {
    const { gl } = this;
    if (this.ref?.src === src) return;
    if (this.ref) { gl.deleteTexture(this.ref.tex); this.ref = null; }
    if (!src) return;
    const tex = gl.createTexture()!;
    gl.activeTexture(gl.TEXTURE0);
    gl.bindTexture(gl.TEXTURE_2D, tex);
    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, gl.RGBA, gl.UNSIGNED_BYTE, src);
    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
    this.ref = { tex, aspect: src.width / src.height, src };
  }

  /** The reference placed as large as fits, centred on the paper. */
  fitReference() {
    if (!this.ref) return;
    const k = this.ref.aspect / this.aspect;   // the image's width / height in uv units
    const w = k > 1 ? 1 : k, h = k > 1 ? 1 / k : 1;
    this.referenceRect = { x: (1 - w) / 2, y: (1 - h) / 2, w, h };
  }

  /**
   * The reference as placed on the paper, at document resolution, over plain white
   * (where it does not cover the paper, and through any transparency). Same layout as
   * readFlat: RGBA8, opaque, row 0 is document y = 0. Null without a reference.
   */
  readReferenceFlat(): Uint8Array | null {
    if (!this.ref) return null;
    const { dw, dh } = this, r = this.refRect;
    const c = document.createElement('canvas');
    c.width = dw; c.height = dh;
    const ctx = c.getContext('2d', { willReadFrequently: true })!;
    ctx.fillStyle = '#fff';
    ctx.fillRect(0, 0, dw, dh);
    // canvas rows run top-down, document uv runs bottom-up
    ctx.drawImage(this.ref.src, r.x * dw, (1 - r.y - r.h) * dh, r.w * dw, r.h * dh);
    const top = ctx.getImageData(0, 0, dw, dh).data;
    const out = new Uint8Array(dw * dh * 4), row = dw * 4;
    for (let y = 0; y < dh; y++) out.set(top.subarray((dh - 1 - y) * row, (dh - y) * row), y * row);
    for (let i = 3; i < out.length; i += 4) out[i] = 255;
    return out;
  }

  get referenceRect(): RefRect { return { ...this.refRect }; }
  set referenceRect(r: RefRect) {
    const c = this.refRect;
    if (r.x === c.x && r.y === c.y && r.w === c.w && r.h === c.h) return;
    this.refRect = { ...r };
    this.redraw();
  }

  get referenceOpacity() { return this.refOpacity; }
  set referenceOpacity(v: number) {
    v = clamp(v, 0, 1);
    if (v === this.refOpacity) return;
    this.refOpacity = v;
    this.redraw();
  }

  /** Does the Fill tool find its areas on the reference (traced) rather than on the paint? */
  referenceForFill = false;

  get referenceVisible() { return this.refVisible; }
  set referenceVisible(v: boolean) { if (v !== this.refVisible) { this.refVisible = v; this.redraw(); } }

  private redraw() { this.dirtyAll = true; this.schedule(); }

  /** Drop the GPU copy of a brush tip (after a custom brush is removed or replaced). */
  forgetBrush(id: string) {
    const t = this.tipTextures.get(id);
    if (t) { this.gl.deleteTexture(t); this.tipTextures.delete(id); }
  }

  private tipTexture(b: Brush): WebGLTexture {
    let t = this.tipTextures.get(b.id);
    if (t) return t;
    const { gl } = this;
    t = gl.createTexture()!;
    gl.activeTexture(gl.TEXTURE0);
    gl.bindTexture(gl.TEXTURE_2D, t);
    gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
    gl.texImage2D(gl.TEXTURE_2D, 0, gl.R8, b.tipSize, b.tipSize, 0, gl.RED, gl.UNSIGNED_BYTE, b.tipData);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
    this.tipTextures.set(b.id, t);
    return t;
  }

  /** Dry everything and bake the mobile pigment into the paper. */
  fix() {
    if (!this.painted || this.fixTimer > 0) return;
    this.beginStep('dry', 'Dry');
    // the fixed layer only ever changes here, so it is only snapshotted here
    this.history.protect(1, this.painted, this.fixed.views);
    this.fixTimer = FIX_DURATION;
    // mobile pigment only exists where strokes have been, so only that needs settling
    this.touch(this.painted);
    this.schedule();
  }

  /** Wipe the paint as one undo step. The sheet (and its grain) stays. */
  clear() {
    this.stroke = null;
    this.queue = [];
    if (!this.everPainted && !this.fill) return;   // already blank
    this.beginStep('clear', 'Clear');
    if (this.everPainted) {
      this.history.protect(0, this.everPainted, this.snapshotLayers());
      this.history.protect(1, this.everPainted, this.fixed.views);
    }
    for (const t of this.docTargets()) if (t !== this.paper) this.g.clearTarget(t);
    this.resetPaintState();
    this.notifyHistory();
    this.schedule();
  }

  /** Take back the stroke in progress as if it never happened (a touch that became a pinch). */
  abortStroke() {
    const s = this.stroke;
    if (!s) return;
    this.stroke = null;
    this.queue = [];
    if (s.pointerId !== SCRIPT_POINTER) this.callbacks.onStrokeTool?.(null);
    if (this.history.canUndo) { this.travel('undo'); this.history.discardRedo(); this.notifyHistory(); }
  }

  undo() { if (this.history.canUndo) this.travel('undo'); }

  redo() { if (this.history.canRedo) this.travel('redo'); }

  /** Undo or redo until `index` steps are applied. */
  jumpTo(index: number) {
    const { index: now, list } = this.history.entries();
    index = clamp(Math.round(index), 0, list.length);
    for (let i = now; i > index && this.history.canUndo; i--) this.travel('undo', false);
    for (let i = now; i < index && this.history.canRedo; i++) this.travel('redo', false);
    this.notifyHistory();
  }

  get canUndo() { return this.history.canUndo; }
  get canRedo() { return this.history.canRedo; }

  /** Step through history in either direction. */
  private travel(dir: 'undo' | 'redo', notify = true) {
    this.stroke = null;
    this.dropFill();
    this.queue = [];
    this.fixTimer = 0;
    const next = dir === 'undo' ? this.history.peekUndo() : this.history.peekRedo();
    const metaNow: StepMeta = this.currentMeta();
    if (next?.boundary) { metaNow.whole = this.captureWhole(); metaNow.paperOrigin = [...this.paperOrigin]; }
    this.sleep();
    const ink = this.ink, wet = this.wet;
    const layers = [
      [[ink.read.views[0], ink.write.views[0]], [ink.read.views[1], ink.write.views[1]], [wet.read.views[0], wet.write.views[0]]],
      [[this.fixed.views[0]], [this.fixed.views[1]]],
    ];
    const res = dir === 'undo' ? this.history.undo(layers, metaNow) : this.history.redo(layers, metaNow);
    if (!res) return;
    const meta = res.meta as StepMeta;
    const now = performance.now();
    if (meta.whole) {
      this.applyWhole(meta.whole, meta.paperOrigin ?? [0, 0]);
      this.painted = meta.painted ? { ...meta.painted } : null;
    }
    if (res.info.kind !== 'paper' && res.info.kind !== 'reference') {
      // the restored water keeps drying from where it was when the step began
      this.lastWet = now - meta.wetAgo;
      this.wetPeak = meta.wetPeak;
      this.active = meta.active ? { ...meta.active } : null;
    }
    if (res.rect) {
      this.dirty = union(this.dirty, res.rect);
      this.painted = union(this.painted, res.rect);
      this.everPainted = union(this.everPainted, res.rect);
    }
    this.applyDocState(meta.doc);
    this.callbacks.onDocumentChange?.(this.docState());
    if (notify) this.notifyHistory();
    this.schedule();
  }

  private notifyHistory() {
    this.seenEvictions = this.history.evictions;
    const { list, index } = this.history.entries();
    this.callbacks.onHistoryChange?.(list, index);
  }

  private currentMeta(): StepMeta {
    return {
      wetAgo: performance.now() - this.lastWet, wetPeak: this.wetPeak,
      active: this.active ? { ...this.active } : null, painted: this.painted ? { ...this.painted } : null,
      doc: this.docState(),
    };
  }

  /**
   * Render the document at full resolution as an image file. The reference image is
   * never included. JPEG has no alpha, so a transparent JPEG is put on white.
   */
  async exportImage(o: ExportOptions): Promise<Blob> {
    const { dw, dh } = this;
    const bg = o.format === 'jpeg' && o.background === 'transparent' ? 'white' : o.background;
    const px = this.readback(false, MODE[bg], o.texture ?? true);
    const c = document.createElement('canvas');
    c.width = dw; c.height = dh;
    const ctx = c.getContext('2d')!;
    const img = ctx.createImageData(dw, dh);
    const row = dw * 4;
    for (let y = 0; y < dh; y++) img.data.set(px.subarray((dh - 1 - y) * row, (dh - y) * row), y * row);
    ctx.putImageData(img, 0, 0);
    const type = `image/${o.format}`;
    return new Promise((resolve, reject) => c.toBlob(b => {
      if (!b) reject(new Error('export failed'));
      else if (b.type !== type) reject(new Error(`This browser cannot save ${o.format.toUpperCase()}`));
      else resolve(b);
    }, type, o.quality));
  }

  /** The composited document at full resolution as RGBA8 bytes, bottom row first. */
  private readback(flat: boolean, mode: number = MODE.paper, texture = true): Uint8Array {
    const { gl, g, dw, dh } = this;
    const out = g.target(dw, dh, [RGBA8], gl.NEAREST);
    this.drawDisplay(out, { x: 0, y: 0, w: dw, h: dh }, null, flat, mode, texture);
    const px = new Uint8Array(dw * dh * 4);
    gl.bindFramebuffer(gl.FRAMEBUFFER, out.fbo);
    gl.readPixels(0, 0, dw, dh, gl.RGBA, gl.UNSIGNED_BYTE, px);
    g.disposeTarget(out);
    return px;
  }

  resize() {
    this.fitCanvas();
    this.schedule();
  }

  destroy() {
    cancelAnimationFrame(this.raf);
    this.dropFill();
    this.disposers.forEach(d => d());
    this.tipTextures.forEach(t => this.gl.deleteTexture(t));
    this.tipTextures.clear();
    if (this.ref) this.gl.deleteTexture(this.ref.tex);
    this.ref = null;
    this.g.disposeTargets();
  }

  /* ------------------------------------------------------------------ input */

  private toUv(e: { clientX: number; clientY: number }): [number, number] {
    const r = this.canvas.getBoundingClientRect();
    const cx = (e.clientX - r.left) * this.dpr;
    const cy = this.canvasSize[1] - (e.clientY - r.top) * this.dpr;
    return [(cx - this.view.x) / this.view.w, (cy - this.view.y) / this.view.h];
  }

  private attachInput() {
    const c = this.canvas;
    const on = <K extends keyof HTMLElementEventMap>(el: HTMLElement | Window, type: K, fn: (e: HTMLElementEventMap[K]) => void, opts?: AddEventListenerOptions) => {
      el.addEventListener(type, fn as EventListener, opts);
      this.disposers.push(() => el.removeEventListener(type, fn as EventListener, opts));
    };

    on(c, 'pointerdown', e => {
      e.preventDefault();
      if (!this.interactive || this.nav || e.button === 1) return;
      if (this.stroke) return;                       // one stroke at a time (palm rejection)
      if (e.pointerType === 'pen') this.pencilSeen = true;
      try { c.setPointerCapture(e.pointerId); } catch { /* pointer already gone */ }
      let tool = this.tool;
      if (e.pointerType === 'touch' && this.pencilSeen && this.fingerIsWater) tool = 'water';
      if (e.pointerType === 'pen' && e.buttons & 32) tool = 'lift';          // eraser end
      else if (e.pointerType === 'pen' && e.buttons & 2) tool = tool === 'water' ? 'brush' : 'water'; // barrel button
      this.stroke = {
        pointerId: e.pointerId, pointerType: e.pointerType, tool, started: false, ending: false,
        x: 0, y: 0, cx: 0, cy: 0, pr: 0, t: e.timeStamp, speed: 0, simPressure: 0.45, carry: 0, travelled: 0, moved: false,
        dx: this.lastDir[0], dy: this.lastDir[1], angle: this.lastAngle, azimuth: null,
      };
      if (tool !== this.tool) this.callbacks.onStrokeTool?.(tool);
      this.beginStep('stroke', STROKE_LABEL[tool]);
      this.pushSample(e);
      this.trackHover(e);
      this.schedule();
    });

    on(c, 'pointermove', e => {
      if (e.pointerType === 'pen') this.pencilSeen = true;
      this.trackHover(e);
      if (!this.stroke || e.pointerId !== this.stroke.pointerId) return;
      const events = e.getCoalescedEvents?.() ?? [];
      for (const s of events.length ? events : [e]) this.pushSample(s);
      this.schedule();
    });

    const end = (e: PointerEvent) => {
      if (!this.stroke || e.pointerId !== this.stroke.pointerId) return;
      this.stroke.ending = true;
      this.schedule();
    };
    on(c, 'pointerup', end);
    on(c, 'pointercancel', end);
    on(c, 'pointerleave', () => { this.hover.inside = false; this.updateCursor(); });
    on(c, 'contextmenu', e => e.preventDefault());
    on(window, 'blur', () => { if (this.stroke) this.stroke.ending = true; });

    // macOS Force Touch trackpads report pressure through a WebKit-only event
    on(c, 'webkitmouseforcechanged' as keyof HTMLElementEventMap, (e: Event) => {
      const f = (e as unknown as { webkitForce?: number }).webkitForce;
      if (typeof f === 'number') this.force = { value: clamp((f - 1) / 1.7, 0.04, 1), t: performance.now() };
    });
  }

  private pushSample(e: PointerEvent) {
    const [x, y] = this.toUv(e);
    let p = -1;
    if (e.pointerType === 'pen') p = e.pressure > 0 ? Math.pow(e.pressure, 0.8) : 0.5;
    else if (e.pointerType === 'mouse' && performance.now() - this.force.t < 3000) p = this.force.value;
    this.queue.push({ x, y, p, t: e.timeStamp, tx: e.tiltX || 0, ty: e.tiltY || 0 });
  }

  private trackHover(e: PointerEvent) {
    this.hover.x = e.clientX; this.hover.y = e.clientY;
    this.hover.inside = true; this.hover.type = e.pointerType;
    this.updateCursor();
  }

  private updateCursor() {
    const el = this.cursor;
    if (!el) return;
    if (!this.hover.inside || this.hover.type === 'touch' || !this.interactive || this.nav) { el.style.opacity = '0'; return; }
    const tool = this.stroke?.tool ?? this.tool;
    const r = this.radius(tool, this.stroke ? this.pressureOf(this.stroke, -1) : 0.4, 0);
    const shaped = tool === 'brush' || tool === 'water';
    const b = this.brush;
    const d = Math.max(4, (2 * r * this.view.h) / this.dpr);
    const h = shaped ? Math.max(3, d * b.aspect) : d;
    // doc uv has y up, the screen has y down, so the angle flips
    const angle = shaped && b.rotation !== 'random' ? -(this.stroke?.angle ?? this.lastAngle) : 0;
    el.style.opacity = '1';
    el.style.width = `${d}px`;
    el.style.height = `${h}px`;
    el.style.transform = `translate(${this.hover.x - d / 2}px, ${this.hover.y - h / 2}px) rotate(${angle}rad)`;
    el.style.borderRadius = shaped && b.aspect < 0.6 ? `${h * 0.4}px / 50%` : '50%';
    el.dataset.tool = tool;
  }

  /* -------------------------------------------------------------- strokes */

  private sizeMult() { return Math.pow(3, (this.params.size - 0.5) * 2) * (this.scripting ? this.scriptScale : 1); }

  /** Footprint radius in document heights. */
  private radius(tool: Tool, pr: number, speed: number) {
    const m = this.sizeMult();
    switch (tool) {
      case 'pen': return (0.0016 + 0.0042 * pr) * clamp(1.12 - speed * 0.3, 0.55, 1.12) * m;
      case 'brush': return this.brushRadius(pr, speed);
      case 'water': return this.brushRadius(pr, speed) * 1.3 * (1 + Math.min(speed, 2.5) * 0.12);
      case 'lift': return (0.012 + 0.03 * pr) * m;
    }
  }

  /** Half the long axis of the current brush's footprint, in document heights. */
  private brushRadius(pr: number, speed: number) {
    const b = this.brush;
    const t = Math.pow(clamp(pr, 0, 1), b.pressureSize);
    // preset sizes describe the full footprint; 0.8 keeps a hard-pressed stroke on a desktop screen sane
    return (b.size[0] + (b.size[1] - b.size[0]) * t) * clamp(1 - speed * b.speedThin, 0.4, 1) * this.sizeMult() * 0.8;
  }

  /** Tip angle for the next dab, in the document frame. */
  private brushAngle(s: Stroke) {
    const b = this.brush;
    let a: number;
    if (b.rotation === 'random') a = Math.random() * Math.PI * 2;
    else if (b.rotation === 'follow') a = Math.atan2(s.dy, s.dx) + b.angle * DEG;
    else a = s.azimuth ?? b.angle * DEG;
    if (b.angleJitter) a += (Math.random() - 0.5) * 2 * b.angleJitter * DEG;
    s.angle = a;
    if (b.rotation !== 'random') this.lastAngle = a;
    return a;
  }

  private pressureOf(s: Stroke, p: number) { return p >= 0 ? p : s.simPressure; }

  private processInput(dt: number) {
    const s = this.stroke;
    if (!s) return;
    s.moved = false;
    const aspect = this.dw / this.dh;
    for (const q of this.queue) {
      // a tilted pen tells us which way it leans; a vertical one tells us nothing
      if (Math.hypot(q.tx, q.ty) > 12) s.azimuth = Math.atan2(-q.ty, q.tx);
      if (!s.started) {
        s.started = true;
        s.x = s.cx = q.x; s.y = s.cy = q.y; s.t = q.t;
        s.pr = this.pressureOf(s, q.p);
        this.stamp(s, q.x, q.y, s.pr, 0, 0, 1);
        continue;
      }
      const sdt = Math.max(q.t - s.t, 1) / 1000;
      s.t = q.t;
      // light smoothing; mice get a little more than styluses
      const k = s.pointerType === 'mouse' ? 0.5 : 0.65;
      const nx = s.cx + (q.x - s.cx) * k, ny = s.cy + (q.y - s.cy) * k;
      const len = Math.hypot((nx - s.cx) * aspect, ny - s.cy);
      s.speed += (len / sdt - s.speed) * (1 - Math.exp(-sdt * 10));
      const target = clamp(1.18 - s.speed * 0.95, 0.12, 1);
      s.simPressure += (target - s.simPressure) * (1 - Math.exp(-sdt * 6));
      const pr = this.pressureOf(s, q.p);
      const vx = (nx - s.cx) / sdt, vy = (ny - s.cy) / sdt;
      if (s.pointerId === SCRIPT_POINTER) {
        // scripted glyphs keep their corners
        this.trace(s, nx, ny, nx, ny, pr, vx, vy);
      } else {
        // a fast mouse reports sparse samples (~8ms apart, often 50px+); curving through
        // their midpoints keeps the stroke round instead of a visible polyline
        this.trace(s, s.cx, s.cy, (s.cx + nx) / 2, (s.cy + ny) / 2, pr, vx, vy);
      }
      s.cx = nx; s.cy = ny;
      if (len > 0) s.moved = true;
    }
    this.queue = [];
    // the curve trails half a sample behind; catch up once the pointer rests or lifts
    if (s.started && (!s.moved || s.ending) && (s.x !== s.cx || s.y !== s.cy)) this.trace(s, s.cx, s.cy, s.cx, s.cy, s.pr, 0, 0);
    // resting in place: pigment keeps soaking in, water keeps pooling
    if (!s.moved && s.started && !s.ending) this.stamp(s, s.x, s.y, this.pressureOf(s, -1), 0, 0, 0, dt);
    if (s.ending) {
      this.stroke = null;
      if (s.pointerId !== SCRIPT_POINTER) this.callbacks.onStrokeTool?.(null);
    }
  }

  /**
   * Lay dabs along the quadratic from the stroke's end (s.x, s.y) through control (qx, qy)
   * to (ex, ey), every `spacing` of arc length so deposits don't depend on event rate.
   * Pressure ramps from s.pr to `pr`; direction follows the curve's tangent.
   */
  private trace(s: Stroke, qx: number, qy: number, ex: number, ey: number, pr: number, vx: number, vy: number) {
    const aspect = this.dw / this.dh;
    const x0 = s.x, y0 = s.y, pr0 = s.pr;
    const approx = Math.hypot((qx - x0) * aspect, qy - y0) + Math.hypot((ex - qx) * aspect, ey - qy);
    if (approx < 1e-7) return;
    const fine = this.radius(s.tool, Math.max(pr0, pr), s.speed) * this.spacingFrac(s.tool);
    const n = clamp(Math.ceil(approx / Math.max(fine, 1e-5)), 1, 48);
    let px = x0, py = y0;
    for (let i = 1; i <= n; i++) {
      const u = i / n, w = 1 - u;
      const cx = w * w * x0 + 2 * w * u * qx + u * u * ex;
      const cy = w * w * y0 + 2 * w * u * qy + u * u * ey;
      const dx = (cx - px) * aspect, dy = cy - py;
      const len = Math.hypot(dx, dy);
      const p = pr0 + (pr - pr0) * u;
      if (len > 1e-5) {
        // direction smoothing scaled by distance, so a jittery stylus doesn't spin a flat brush
        const kd = 1 - Math.exp(-len / (this.radius(s.tool, p, s.speed) * 1.5 + 1e-4));
        s.dx += (dx / len - s.dx) * kd; s.dy += (dy / len - s.dy) * kd;
        const m = Math.hypot(s.dx, s.dy) || 1;
        s.dx /= m; s.dy /= m;
        this.lastDir = [s.dx, s.dy];
      }
      const spacing = this.radius(s.tool, p, s.speed) * this.spacingFrac(s.tool);
      let pos = 0;
      while (len - pos >= spacing - s.carry) {
        pos += spacing - s.carry;
        s.carry = 0;
        const t = pos / len;
        this.stamp(s, px + (cx - px) * t, py + (cy - py) * t, p, vx, vy, 1);
      }
      s.carry += len - pos;
      s.travelled += len;
      px = cx; py = cy;
    }
    s.x = ex; s.y = ey; s.pr = pr;
  }

  /** Dab spacing as a fraction of the footprint radius. */
  private spacingFrac(tool: Tool) {
    const b = this.brush;
    // flat tips need tighter spacing: the footprint is thin across one axis
    return tool === 'brush' || tool === 'water' ? b.spacing * Math.sqrt(b.aspect) : 0.5;
  }

  /** One dab of the current tool. `moving` = 0 with `dt` set means a dwell. */
  private stamp(s: Stroke, x: number, y: number, pr: number, vx: number, vy: number, moving: number, dt = 0) {
    const P = this.params;
    const r = this.radius(s.tool, pr, s.speed);
    const dwell = moving ? 1 : dt * 8;
    switch (s.tool) {
      case 'brush': {
        const b = this.brush;
        // the brush empties as it travels; a dry brush skips the valleys of the paper
        const reservoir = 0.25 + 0.75 * Math.exp(-s.travelled / ((1.5 + 3 * P.water) * b.capacity));
        const dryness = clamp(b.grain + (1 - b.grain) * clamp((0.5 - reservoir) * 2.5, 0, 1) * 0.6, 0, 1);
        const grainThr = 0.74 - 0.45 * pr - 0.05 * P.water;   // pressing harder reaches into the valleys
        const conc = 0.15 * Math.exp(P.load * 2.8) * reservoir * (0.6 + 0.4 * pr) * b.load;
        // spacing / profile integral -> ~conc in the stroke, normalised for sparse tips
        const norm = clamp(Math.sqrt(0.5 / b.tipMean), 0.7, 2.2);
        const amount = conc * Math.min(b.spacing, 1) / 1.8 * norm * dwell;
        const wet = (0.25 + 0.75 * P.water) * (0.7 + 0.3 * pr) * b.water * (0.4 + 0.6 * reservoir);
        const c = this.pigment.coeffs;
        const c0 = [c[0] * amount, c[1] * amount, c[2] * amount, c[3] * amount];
        const c1 = [c[4] * amount, c[5] * amount, c[6] * amount, this.pigment.white * amount * 1.6];
        this.eachDab(s, x, y, r, (dx, dy, dr, angle) => {
          this.brushInk(dx, dy, dr, angle, c0, c1, dryness, grainThr);
          // soft brushes wet a little beyond the tip; textured ones keep their edges
          this.brushWet(dx, dy, dr * (1 + 0.12 * b.wetRound), angle, wet, b.wetRound, dryness, grainThr);
        });
        if (moving) this.splatVelocity(x, y, r * 1.2, vx, vy, (15 + P.flow * 95) * 0.25 * b.flow);
        break;
      }
      case 'water': {
        const b = this.brush;
        const reservoir = 0.25 + 0.75 * Math.exp(-s.travelled / ((3 + 4 * P.water) * b.capacity));
        const amp = (0.35 + 0.65 * P.water) * (0.5 + 0.5 * pr) * clamp(b.water, 0.6, 1.5) * (0.7 + 0.3 * reservoir);
        const dryness = b.grain * 0.7;
        const grainThr = 0.55 - 0.3 * pr;
        this.eachDab(s, x, y, r, (dx, dy, dr, angle) => {
          this.brushWet(dx, dy, dr, angle, amp, Math.max(b.wetRound, 0.3), dryness, grainThr);
        });
        this.brushNow = { x, y, r };
        if (moving) this.splatVelocity(x, y, r * 1.15, vx, vy, (15 + P.flow * 95) * b.flow);
        else {
          const a = Math.random() * Math.PI * 2, m = (6 + 26 * P.flow) * pr;
          this.splatVelocityRaw(x, y, r * 0.9, Math.cos(a) * m, Math.sin(a) * m);
        }
        break;
      }
      case 'pen': {
        const dens = (0.9 + 1.6 * pr) * clamp(1.25 - s.speed * 0.45, 0.6, 1.25) * (0.5 + P.load);
        const amount = dens * 0.5 / 1.8 * dwell;
        const c = this.pigment.coeffs;
        this.splatInk(x, y, r, [c[0] * amount, c[1] * amount, c[2] * amount, c[3] * amount],
          [c[4] * amount, c[5] * amount, c[6] * amount, this.pigment.white * amount * 3], 2);
        this.splatWet(x, y, r * 2.6, 0.13, 1);   // fresh ink is faintly wet, so it feathers a little
        break;
      }
      case 'lift': {
        const amount = Math.min(0.9, 0.22 * dwell);
        this.lift(x, y, r, amount);
        break;
      }
    }
  }

  /* --------------------------------------------------------------- splats */

  /** Run `fn` for every dab of a stamp: one for most brushes, a scattered burst for spatter. */
  private eachDab(s: Stroke, x: number, y: number, r: number, fn: (x: number, y: number, r: number, angle: number) => void) {
    const b = this.brush;
    const aspect = this.dw / this.dh;
    for (let i = 0; i < b.dabs; i++) {
      let dx = x, dy = y, dr = r;
      if (b.scatter > 0) {
        const a = Math.random() * Math.PI * 2, m = Math.sqrt(Math.random()) * b.scatter * r;
        dx += (Math.cos(a) * m) / aspect; dy += Math.sin(a) * m;
      }
      if (b.sizeJitter > 0) dr *= clamp(1 + (Math.random() * 2 - 1) * b.sizeJitter, 0.15, 2);
      fn(dx, dy, dr, this.brushAngle(s));
    }
  }

  private drawStamp(t: Target, x: number, y: number, r: number, angle: number, c0: number[], c1: number[], round: number, grain: number, grainThr: number) {
    const { gl, g } = this;
    const b = this.brush;
    const p = this.programs.stamp;
    p.bind();
    gl.uniform1i(p.u.uTip, g.bindTex(0, this.tipTexture(b)));
    gl.uniform1i(p.u.uPaper, g.bindTex(1, this.paper.tex[0]));
    gl.uniform1f(p.u.uAspect, t.w / t.h);
    gl.uniform2f(p.u.uPoint, x, y);
    gl.uniform1f(p.u.uRadius, r);
    gl.uniform1f(p.u.uTipAspect, b.aspect);
    gl.uniform2f(p.u.uAxis, Math.cos(angle), Math.sin(angle));
    gl.uniform1f(p.u.uRound, round);
    gl.uniform1f(p.u.uGrain, grain);
    gl.uniform1f(p.u.uGrainThr, grainThr);
    gl.uniform4fv(p.u.uColor0, c0);
    gl.uniform4fv(p.u.uColor1, c1);
    g.draw(t, this.stampRect(x, y, r, t.w, t.h, Math.sqrt(1 + b.aspect * b.aspect) * 1.02));
  }

  private brushInk(x: number, y: number, r: number, angle: number, c0: number[], c1: number[], grain: number, grainThr: number) {
    const { gl } = this;
    this.touch(this.stampRect(x, y, r, this.dw, this.dh, 1.5));
    gl.enable(gl.BLEND);
    gl.blendEquation(gl.FUNC_ADD);
    gl.blendFunc(gl.ONE, gl.ONE);
    this.drawStamp(this.ink.read, x, y, r, angle, c0, c1, 0, grain, grainThr);
    gl.disable(gl.BLEND);
  }

  private brushWet(x: number, y: number, r: number, angle: number, amount: number, round: number, grain: number, grainThr: number) {
    const { gl } = this;
    this.touch(this.stampRect(x, y, r, this.dw, this.dh, 1.5));
    gl.enable(gl.BLEND);
    gl.blendEquation(gl.MAX);
    this.drawStamp(this.wet.read, x, y, r, angle, [amount, 0, 0, 0], [0, 0, 0, 0], round, grain, grainThr);
    gl.blendEquation(gl.FUNC_ADD);
    gl.disable(gl.BLEND);
    this.wetPeak = Math.max(this.wetPeak * this.wetDecay(), amount);
    this.lastWet = performance.now();
  }

  /** Rect (in texels of a w×h grid) covered by a stamp of radius r (doc heights). */
  private stampRect(x: number, y: number, r: number, w: number, h: number, extent: number): Rect {
    const e = Math.ceil(r * extent * h) + 2;
    const cx = Math.round(x * w), cy = Math.round(y * h);
    return { x0: clamp(cx - e, 0, w), y0: clamp(cy - e, 0, h), x1: clamp(cx + e, 0, w), y1: clamp(cy + e, 0, h) };
  }

  /**
   * Grow the simulated region. With `save`, the tiles around `rect` are saved for undo
   * first: a step restores what its own dabs and fills touched (plus a margin for what
   * spread from them), while the rest of the sheet simply keeps drying. That keeps a
   * step's cost proportional to the stroke, not to everything that happens to be wet.
   */
  private touch(rect: Rect, wake = true, save = true) {
    if (rect.x1 <= rect.x0 || rect.y1 <= rect.y0) return;
    const next = union(this.active, rect);
    if (save) {
      const m = PROTECT_MARGIN;
      this.history.protect(0, { x0: Math.max(0, rect.x0 - m), y0: Math.max(0, rect.y0 - m), x1: Math.min(this.dw, rect.x1 + m), y1: Math.min(this.dh, rect.y1 + m) }, this.snapshotLayers());
    }
    this.active = next;
    this.painted = union(this.painted, rect);
    this.everPainted = union(this.everPainted, rect);
    this.dirty = union(this.dirty, rect);
    if (wake) this.minAwakeUntil = Math.max(this.minAwakeUntil, performance.now() + 250);
  }

  private snapshotLayers() {
    return [this.ink.read.views[0], this.ink.read.views[1], this.wet.read.views[0]];
  }

  private drawSplat(t: Target, x: number, y: number, r: number, c0: number[], c1: number[], hardness: number, extent: number) {
    const { gl, g } = this;
    const p = this.programs.splat;
    p.bind();
    gl.uniform1f(p.u.uAspect, t.w / t.h);
    gl.uniform2f(p.u.uPoint, x, y);
    gl.uniform1f(p.u.uRadius, r);
    gl.uniform1f(p.u.uHardness, hardness);
    gl.uniform4fv(p.u.uColor0, c0);
    gl.uniform4fv(p.u.uColor1, c1);
    g.draw(t, this.stampRect(x, y, r, t.w, t.h, extent));
  }

  private splatInk(x: number, y: number, r: number, c0: number[], c1: number[], hardness: number) {
    const { gl } = this;
    const extent = hardness > 1.4 ? 2.2 : 3.2;
    this.touch(this.stampRect(x, y, r, this.dw, this.dh, extent));
    gl.enable(gl.BLEND);
    gl.blendEquation(gl.FUNC_ADD);
    gl.blendFunc(gl.ONE, gl.ONE);
    this.drawSplat(this.ink.read, x, y, r, c0, c1, hardness, extent);
    gl.disable(gl.BLEND);
  }

  private splatWet(x: number, y: number, r: number, amount: number, hardness: number) {
    const { gl } = this;
    const extent = hardness > 1.4 ? 2.2 : 3.2;
    this.touch(this.stampRect(x, y, r, this.dw, this.dh, extent));
    gl.enable(gl.BLEND);
    gl.blendEquation(gl.MAX);
    this.drawSplat(this.wet.read, x, y, r, [amount, 0, 0, 0], [0, 0, 0, 0], hardness, extent);
    gl.blendEquation(gl.FUNC_ADD);
    gl.disable(gl.BLEND);
    this.wetPeak = Math.max(this.wetPeak * this.wetDecay(), amount);
    this.lastWet = performance.now();
  }

  private splatVelocity(x: number, y: number, r: number, vx: number, vy: number, force: number) {
    let fx = vx * force, fy = vy * force;
    const m = Math.hypot(fx, fy), vmax = 240;
    if (m > vmax) { fx *= vmax / m; fy *= vmax / m; }
    this.flowSpeed = Math.max(this.flowSpeed, Math.min(m, vmax));
    this.splatVelocityRaw(x, y, r, fx, fy);
  }

  private splatVelocityRaw(x: number, y: number, r: number, fx: number, fy: number) {
    const { gl } = this;
    gl.enable(gl.BLEND);
    gl.blendEquation(gl.FUNC_ADD);
    gl.blendFunc(gl.ONE, gl.ONE);
    this.drawSplat(this.velocity.read, x, y, r, [fx, fy, 0, 0], [0, 0, 0, 0], 1, 3);
    gl.disable(gl.BLEND);
  }

  private lift(x: number, y: number, r: number, amount: number) {
    const { gl, g } = this;
    const rect = this.stampRect(x, y, r, this.dw, this.dh, 2);
    this.touch(rect);
    const p = this.programs.lift;
    p.bind();
    gl.uniform1f(p.u.uAspect, this.dw / this.dh);
    gl.uniform2f(p.u.uPoint, x, y);
    gl.uniform1f(p.u.uRadius, r);
    gl.enable(gl.BLEND);
    gl.blendEquation(gl.FUNC_ADD);
    gl.blendFunc(gl.ZERO, gl.ONE_MINUS_SRC_COLOR);
    gl.uniform1f(p.u.uAmount, amount);
    g.draw(this.ink.read, rect);
    gl.uniform1f(p.u.uAmount, amount * 0.8);   // the tissue soaks up water too
    g.draw(this.wet.read, rect);
    gl.disable(gl.BLEND);
  }

  /* ----------------------------------------------------------- simulation */

  private dryTau() { return this.fixTimer > 0 ? 0.25 : 2 + (1 - this.params.dry) * 16; }

  private wetDecay() { return Math.exp(-(performance.now() - this.lastWet) / 1000 / this.dryTau()); }

  /** Time (ms) until standing water everywhere has dried below the threshold. */
  private wetUntil() {
    if (this.wetPeak <= WET_THRESHOLD) return this.lastWet;
    return this.lastWet + this.dryTau() * Math.log(this.wetPeak / WET_THRESHOLD) * 1000;
  }

  private beginStep(kind: StepKind, label: string) {
    this.dropFill();   // a new action ends a running fill; its remaining bands never land in this step
    this.history.begin({ kind, label }, this.currentMeta());
    this.notifyHistory();
  }

  private step(dt: number) {
    const { gl, g, programs: P } = this;
    const fixing = this.fixTimer > 0;
    if (fixing) {
      this.fixTimer -= dt;
      if (this.fixTimer <= 0) {
        // everything has flash-dried: let the sim sleep so the next stroke starts
        // from a small active region (and a small undo snapshot)
        this.wetPeak = 0;
        this.minAwakeUntil = 0;
        this.painted = null;
      }
    }
    const vel = this.velocity;
    const simTexel = [1 / vel.w, 1 / vel.h];
    const texel = [1 / this.dw, 1 / this.dh];
    const flow = this.params.flow;
    const rect = this.active!;

    P.advectVelocity.bind();
    gl.uniform1i(P.advectVelocity.u.uVelocity, g.bindTex(0, vel.read.tex[0]));
    gl.uniform1i(P.advectVelocity.u.uWet, g.bindTex(1, this.wet.read.tex[0]));
    gl.uniform2fv(P.advectVelocity.u.uTexel, simTexel);
    gl.uniform1f(P.advectVelocity.u.uDt, dt);
    gl.uniform1f(P.advectVelocity.u.uDissipation, Math.exp(-dt * (3.0 - flow * 2.4)) * (fixing ? Math.exp(-dt * 7) : 1));
    g.draw(vel.write); vel.swap();

    P.curl.bind();
    gl.uniform1i(P.curl.u.uVelocity, g.bindTex(0, vel.read.tex[0]));
    gl.uniform2fv(P.curl.u.uTexel, simTexel);
    g.draw(this.curl);

    P.vorticity.bind();
    gl.uniform1i(P.vorticity.u.uVelocity, g.bindTex(0, vel.read.tex[0]));
    gl.uniform1i(P.vorticity.u.uCurl, g.bindTex(1, this.curl.tex[0]));
    gl.uniform2fv(P.vorticity.u.uTexel, simTexel);
    gl.uniform1f(P.vorticity.u.uCurlAmount, 4 + flow * 22);
    gl.uniform1f(P.vorticity.u.uDt, dt);
    g.draw(vel.write); vel.swap();

    P.divergence.bind();
    gl.uniform1i(P.divergence.u.uVelocity, g.bindTex(0, vel.read.tex[0]));
    gl.uniform2fv(P.divergence.u.uTexel, simTexel);
    g.draw(this.divergence);

    P.scale.bind();
    gl.uniform1i(P.scale.u.uTex, g.bindTex(0, this.pressure.read.tex[0]));
    gl.uniform1f(P.scale.u.uValue, 0.8);
    g.draw(this.pressure.write); this.pressure.swap();

    P.pressure.bind();
    gl.uniform1i(P.pressure.u.uDivergence, g.bindTex(1, this.divergence.tex[0]));
    gl.uniform2fv(P.pressure.u.uTexel, simTexel);
    for (let i = 0; i < PRESSURE_ITERATIONS; i++) {
      gl.uniform1i(P.pressure.u.uPressure, g.bindTex(0, this.pressure.read.tex[0]));
      g.draw(this.pressure.write); this.pressure.swap();
    }

    P.gradient.bind();
    gl.uniform1i(P.gradient.u.uPressure, g.bindTex(0, this.pressure.read.tex[0]));
    gl.uniform1i(P.gradient.u.uVelocity, g.bindTex(1, vel.read.tex[0]));
    gl.uniform2fv(P.gradient.u.uTexel, simTexel);
    g.draw(vel.write); vel.swap();

    // water: dries on a timescale set by the DRY slider (flash-dries while fixing)
    P.advectWet.bind();
    gl.uniform1i(P.advectWet.u.uVelocity, g.bindTex(0, vel.read.tex[0]));
    gl.uniform1i(P.advectWet.u.uWet, g.bindTex(1, this.wet.read.tex[0]));
    gl.uniform2fv(P.advectWet.u.uSimTexel, simTexel);
    gl.uniform2fv(P.advectWet.u.uTexel, texel);
    gl.uniform1f(P.advectWet.u.uDt, dt);
    gl.uniform1f(P.advectWet.u.uDecay, Math.exp(-dt / this.dryTau()));
    gl.uniform1f(P.advectWet.u.uSpread, 0.12);
    g.draw(this.wet.write, rect); this.wet.swap();

    // fixing: bleach under white gouache, then settle mobile pigment into the paper
    const settle = fixing ? 1 - Math.exp(-dt * 5) : 0;
    if (fixing) {
      gl.enable(gl.BLEND);
      gl.blendEquation(gl.FUNC_ADD);
      gl.blendFunc(gl.ZERO, gl.SRC_COLOR);
      P.bleach.bind();
      gl.uniform1i(P.bleach.u.uInkB, g.bindTex(0, this.ink.read.tex[1]));
      gl.uniform1f(P.bleach.u.uSettle, settle);
      g.draw(this.fixed, rect);
      gl.blendFunc(gl.ONE, gl.ONE);
      P.settle.bind();
      gl.uniform1i(P.settle.u.uInkA, g.bindTex(0, this.ink.read.tex[0]));
      gl.uniform1i(P.settle.u.uInkB, g.bindTex(1, this.ink.read.tex[1]));
      gl.uniform1f(P.settle.u.uSettle, settle);
      g.draw(this.fixed, rect);
      gl.disable(gl.BLEND);
    }

    // pigment: flows, bleeds and gathers at drying edges, only where wet
    const p = P.advectInk;
    p.bind();
    gl.uniform1i(p.u.uVelocity, g.bindTex(0, vel.read.tex[0]));
    gl.uniform1i(p.u.uInkA, g.bindTex(1, this.ink.read.tex[0]));
    gl.uniform1i(p.u.uInkB, g.bindTex(2, this.ink.read.tex[1]));
    gl.uniform1i(p.u.uWet, g.bindTex(3, this.wet.read.tex[0]));
    gl.uniform2fv(p.u.uSimTexel, simTexel);
    gl.uniform2fv(p.u.uTexel, texel);
    gl.uniform1f(p.u.uDt, dt);
    gl.uniform1f(p.u.uBleed, this.params.bleed);
    gl.uniform1f(p.u.uEdge, this.params.edge * 1.4);
    gl.uniform1f(p.u.uAspect, this.dw / this.dh);
    gl.uniform1f(p.u.uKeep, 1 - settle);
    gl.uniform3f(p.u.uBrush, this.brushNow.x, this.brushNow.y, this.brushNow.r);
    g.draw(this.ink.write, rect); this.ink.swap();

    this.dirty = union(this.dirty, rect);
  }

  /**
   * The active rect grows blindly each frame so the wet front can creep; left alone it
   * would cover the sheet in a minute, and every undo step would have to save all of
   * it. Now and then, find where there is actually water and cut the rect down to that.
   */
  private trimActive() {
    const a = this.active;
    if (!a) return;
    const { gl, g } = this;
    const m = this.wetMask;
    const p = this.programs.wetMask;
    p.bind();
    gl.uniform1i(p.u.uWet, g.bindTex(0, this.wet.read.tex[0]));
    gl.uniform2f(p.u.uBlock, 1 / m.w, 1 / m.h);
    gl.uniform1f(p.u.uThreshold, WET_THRESHOLD);
    g.draw(m);
    gl.bindFramebuffer(gl.FRAMEBUFFER, m.fbo);
    gl.readPixels(0, 0, m.w, m.h, gl.RGBA, gl.UNSIGNED_BYTE, this.maskPixels);
    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
    let x0 = m.w, y0 = m.h, x1 = -1, y1 = -1;
    const px = this.maskPixels;
    for (let y = 0; y < m.h; y++) for (let x = 0; x < m.w; x++) {
      if (!px[(y * m.w + x) * 4]) continue;
      if (x < x0) x0 = x; if (x > x1) x1 = x; if (y < y0) y0 = y; if (y > y1) y1 = y;
    }
    let next: Rect | null = null;
    if (x1 >= 0) {
      const wet = {
        x0: Math.max(0, x0 * MASK_BLOCK - MASK_MARGIN), y0: Math.max(0, y0 * MASK_BLOCK - MASK_MARGIN),
        x1: Math.min(this.dw, (x1 + 1) * MASK_BLOCK + MASK_MARGIN), y1: Math.min(this.dh, (y1 + 1) * MASK_BLOCK + MASK_MARGIN),
      };
      const r = { x0: Math.max(a.x0, wet.x0), y0: Math.max(a.y0, wet.y0), x1: Math.min(a.x1, wet.x1), y1: Math.min(a.y1, wet.y1) };
      if (r.x1 > r.x0 && r.y1 > r.y0) next = r;
    }
    if (next && next.x0 === a.x0 && next.y0 === a.y0 && next.x1 === a.x1 && next.y1 === a.y1) return;
    // the part being dropped was updated into alternating halves: make them agree before it is left alone
    const w = a.x1 - a.x0, h = a.y1 - a.y0;
    for (const d of [this.ink, this.wet])
      d.read.views.forEach((v, i) => g.blit(v, a.x0, a.y0, d.write.views[i], a.x0, a.y0, w, h));
    if (next) this.active = next; else this.sleep();
  }

  /** Make both halves of the ping-pong buffers identical, then stop simulating. */
  private sleep() {
    const rect = this.active;
    if (rect) {
      const { g } = this;
      const w = rect.x1 - rect.x0, h = rect.y1 - rect.y0;
      for (const d of [this.ink, this.wet])
        d.read.views.forEach((v, i) => g.blit(v, rect.x0, rect.y0, d.write.views[i], rect.x0, rect.y0, w, h));
    }
    for (const d of [this.velocity, this.pressure]) { this.g.clearTarget(d.read); this.g.clearTarget(d.write); }
    this.active = null;
    this.wetPeak = 0;
    this.flowSpeed = 0;
  }

  /* -------------------------------------------------------------- display */

  private drawDisplay(target: Target | null, view: { x: number; y: number; w: number; h: number }, scissor: Rect | null, flat = false, mode: number = MODE.screen, texture = true) {
    const { gl, g } = this;
    const p = this.programs.display;
    p.bind();
    gl.uniform1i(p.u.uInkA, g.bindTex(0, this.ink.read.tex[0]));
    gl.uniform1i(p.u.uInkB, g.bindTex(1, this.ink.read.tex[1]));
    gl.uniform1i(p.u.uFixedA, g.bindTex(2, this.fixed.tex[0]));
    gl.uniform1i(p.u.uFixedB, g.bindTex(3, this.fixed.tex[1]));
    gl.uniform1i(p.u.uWet, g.bindTex(4, this.wet.read.tex[0]));
    gl.uniform1i(p.u.uPaper, g.bindTex(5, this.paper.tex[0]));
    gl.uniform4f(p.u.uView, view.x, view.y, view.w, view.h);
    gl.uniform2f(p.u.uTexel, 1 / this.dw, 1 / this.dh);
    gl.uniform1f(p.u.uGranulation, this.params.granulation * 0.55);
    gl.uniform1f(p.u.uEdgeDarken, 0.8);
    gl.uniform1f(p.u.uFlat, flat ? 1 : 0);
    gl.uniform3fv(p.u.uDesk, DESK);
    gl.uniform1i(p.u.uMode, mode);
    this.paperUniforms(p, this.paperPreset, texture ? this.paperStrength : 0);
    const ref = mode === MODE.screen && !flat && this.refVisible ? this.ref : null;
    gl.uniform1f(p.u.uRefOpacity, ref ? this.refOpacity : 0);
    // the sampler needs a texture bound either way; the paper stands in when there is none
    gl.uniform1i(p.u.uRef, g.bindTex(6, ref ? ref.tex : this.paper.tex[0]));
    const r = this.refRect;
    gl.uniform4f(p.u.uRefRect, r.x, r.y, r.w, r.h);
    // the shadow grows with the sheet on screen, within a range that always reads as paper on a desk
    const shadow = mode === MODE.screen && !target ? clamp(Math.min(view.w, view.h) / this.dpr * 0.05, 14, 48) * this.dpr : 0;
    gl.uniform1f(p.u.uShadow, shadow);
    gl.uniform1f(p.u.uDpr, this.dpr);
    g.draw(target, scissor, this.canvasSize);
  }

  private render() {
    if (!this.dirtyAll && !this.dirty) return;
    let rect: Rect | null = null;
    if (!this.dirtyAll && this.dirty) {
      const v = this.view, d = this.dirty;
      rect = {
        x0: Math.floor(v.x + (d.x0 / this.dw) * v.w) - 2, y0: Math.floor(v.y + (d.y0 / this.dh) * v.h) - 2,
        x1: Math.ceil(v.x + (d.x1 / this.dw) * v.w) + 2, y1: Math.ceil(v.y + (d.y1 / this.dh) * v.h) + 2,
      };
    }
    this.drawDisplay(null, this.view, rect);
    this.dirty = null;
    this.dirtyAll = false;
  }

  /* ------------------------------------------------------------ main loop */

  private schedule() {
    if (!this.raf) {
      this.lastFrame = performance.now();
      this.raf = requestAnimationFrame(this.frame);
    }
  }

  private frame = (now: number) => {
    this.raf = 0;
    const dt = clamp((now - this.lastFrame) / 1000, 1 / 240, 1 / 30);
    this.lastFrame = now;
    this.brushNow.r = 0;

    this.processInput(dt);

    const awake = this.active !== null &&
      (this.stroke !== null || this.fixTimer > 0 || now < this.minAwakeUntil || now < this.wetUntil());
    if (awake) {
      // Grow the simulated region as fast as the wet front can move: slow diffusive
      // creep plus a share of the (decaying) flow speed
      this.flowSpeed *= Math.exp(-dt * (3.0 - this.params.flow * 2.4));
      // (velocity is masked to ~0 at the wet front, so the front itself only creeps)
      this.growCarry += 0.4 + Math.min(3, 0.15 * this.flowSpeed * dt * (this.dw / this.velocity.w));
      const grow = Math.floor(this.growCarry);
      if (grow > 0) {
        this.growCarry -= grow;
        const a = this.active!;
        this.touch({ x0: Math.max(0, a.x0 - grow), y0: Math.max(0, a.y0 - grow), x1: Math.min(this.dw, a.x1 + grow), y1: Math.min(this.dh, a.y1 + grow) }, false, false);
      }
      this.step(dt);
      if (this.fixTimer <= 0 && ++this.maskCounter >= MASK_EVERY) { this.maskCounter = 0; this.trimActive(); }
    }
    this.render();
    // a stroke that ran the undo memory dry dropped old steps: the list should say so
    if (this.history.evictions !== this.seenEvictions) this.notifyHistory();
    if (!awake && this.active) this.sleep();
    if (awake || this.stroke) this.schedule();
  };
}