@pixerate/editor 0.108.0 → 0.110.0

package/dist/{compositor-Kt_M4ruo.d.ts → render-tjzKaik-.d.ts}

@@ -1,4 +1,4 @@
-import { B as BlendMode, R as RasterRect, a as TiledSurface, M as MaskSurface, P as PixelSurface, T as TileKey } from './surface-CkKOHGPm.js';
+import { B as BlendMode, R as RasterRect, a as TiledSurface, M as MaskSurface, b as PixelSurface, T as TileKey } from './surface-C8RRg_Bh.js';
 import { H as Homography, V as Vec2 } from './types-CwMPoRMU.js';
 
 /**
@@ -832,4 +832,138 @@ declare class RasterCompositor<L extends CompositorLayer = CompositorLayer, S ex
 /** Tiles that differ between two surfaces (by tile identity), as tile keys. */
 declare function changedTiles(a: TiledSurface, b: TiledSurface): TileKey[];
 
-export { TransformTooLargeError as $, type GradientColorStop as A, type BevelContour as B, type CompositorLayer as C, DEFAULT_GLOBAL_LIGHT as D, type EffectPattern as E, type GradientOpacityStop as F, type GroupBlendMode as G, type GradientOverlayEffect as H, type Interpolation as I, type GradientStyle as J, INTERPOLATIONS as K, type LayerLocks as L, type InnerGlowEffect as M, type InnerShadowEffect as N, LAYER_EFFECT_KINDS as O, LayerEffectError as P, MAX_EFFECT_REACH as Q, type RasterLayer as R, MAX_TRANSFORM_PIXELS as S, type OuterGlowEffect as T, type PatternOverlayEffect as U, PatternPlacement as V, PatternTile as W, type ResampleOptions as X, type SatinEffect as Y, type StrokeEffect as Z, type StrokePosition as _, type RasterGroupLayer as a, blendTile as a0, builtinPattern as a1, builtinPatternIds as a2, changedTiles as a3, compositeSurfaceOver as a4, defaultEffectGradient as a5, defaultLayerEffect as a6, effectColorHex as a7, effectReach as a8, effectsFingerprint as a9, type CompositorProfile as aA, type GroupIn as aB, type PixelFilterSpec as aC, type RasterNode as aD, effectsMargin as aa, effectsScale as ab, findLayer as ac, flattenLayers as ad, hasActiveEffects as ae, hashNoise as af, insertLayer as ag, isInterpolation as ah, isLayerEffectKind as ai, isLayerLocked as aj, keysWeight as ak, layerEffectFields as al, layerEffectLabel as am, mapLayer as an, mergeLayerEffect as ao, newEffectId as ap, normalizeLayerEffects as aq, parseEffectColor as ar, reduceSurface as as, scaleLayerEffect as at, transformSurface as au, transformedBounds as av, validateEffectGradient as aw, validateLayerEffect as ax, validateLayerEffects as ay, warpSurface as az, type RasterPixelLayer as b, RasterCompositor as c, type RasterSources as d, type RasterLayerBase as e, type RasterMask as f, type GlobalLight as g, type LayerLocation as h, type LayerEffect as i, type LayerEffects as j, type CompositorOptions as k, type LayerEffectKind as l, type BevelEmbossEffect as m, type BevelStyle as n, type BevelTechnique as o, type BevelTexture as p, type ColorOverlayEffect as q, type CompositeCallOptions as r, type CompositeStats as s, type ContourPoint as t, type DropShadowEffect as u, type EffectContour as v, type EffectFill as w, type EffectGradient as x, type EffectPatternRef as y, type GlowTechnique as z };
+/**
+ * CPU renderer for layer effects.
+ *
+ * Render order, bottom to top (Photoshop's layer-style stack read upwards): drop shadows, outer
+ * glows, then the layer itself (content at fill opacity) with pattern, gradient and colour
+ * overlays, satin, inner glows, inner shadows, the inside part of strokes and inner bevels on
+ * top. The outside part of strokes and outer bevels go beneath the layer, onto the backdrop.
+ * Exterior effects blend straight into the backdrop with their own modes; the layer blends with
+ * its mode and, in a mode other than Normal, is merged into the backdrop before the interior
+ * effects paint over it (Photoshop's "Blend Interior Effects as Group" off). Emboss and pillow
+ * emboss then shade the composited result. Layer opacity applies to the whole stack; fill
+ * opacity only to the layer's own pixels.
+ *
+ * Every map depends only on the layer's shape (its alpha after the mask), the effect settings
+ * and the global light, never on the backdrop. {@link buildEffectMaps} computes them once over the
+ * layer's whole region; {@link compositeLayerEffects} paints any part of that region (a tile) from
+ * them, pixel by pixel, so a tiled render equals a whole-image render.
+ *
+ * Distances: a stroke's outer edge uses the 5 × 5 chamfer below 20 px and an exact Euclidean
+ * transform from there (the chamfer's octagonal level sets facet wide strokes); inside strokes and
+ * spread / choke keep the chamfer; precise glows and chiselled bevels use the exact transform.
+ * Soft falloffs are two box blurs (a tent).
+ */
+
+interface EffectRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Outside stroke width from which the outer edge uses the exact Euclidean transform. */
+declare const STROKE_CHAMFER_MAX = 20;
+/** A contour as a 0..1 LUT (corner points split the spline), or `null` for linear. */
+declare function contourLut(c: EffectContour | undefined): Float32Array | null;
+/** Where a bevel paints: inside the shape, outside it, or both (emboss styles). */
+type BevelPaint = 'inner' | 'outer' | 'both';
+interface EffectContext {
+    light: GlobalLight;
+    /** A pattern tile by id, or `null` when missing (pattern effects then paint nothing). */
+    pattern(id: string): PatternTile | null;
+}
+/** Effect maps of one layer over its region: see {@link buildEffectMaps}. */
+interface EffectMaps {
+    /** The region the maps cover (document space). */
+    rect: EffectRect;
+    /** The enabled effects, Scale Effects applied, in list order. */
+    items: LayerEffect[];
+    /** Pixel bounds of the shape (alpha above half a step), or `null` when the shape is empty. */
+    bounds: EffectRect | null;
+    shape: Float32Array;
+    /** Per item: the maps it paints through. */
+    per: Float32Array[][];
+    bevelPaint: (BevelPaint | null)[];
+    din: Float32Array | null;
+    dout: Float32Array | null;
+    doutExact: Float32Array | null;
+    /** Frames of gradient strokes by item index. */
+    frames: Map<number, EffectRect>;
+    /** Approximate size in bytes (cache budgeting). */
+    bytes: number;
+}
+/** The enabled effects of `effects` with Scale Effects applied (empty when the master switch is off). */
+declare function activeEffectItems(effects: LayerEffects | undefined | null): LayerEffect[];
+/**
+ * Whether every map pixel of `items` depends only on the shape within the effects' margin, so a
+ * tile is unchanged while the layer is unchanged within its margin. Not local: anything laid out
+ * over the layer's bounds (aligned gradient overlays, gradient strokes, linked patterns) and noise
+ * (it speckles any coverage above zero, which picks up the blur's float noise from far away).
+ */
+declare function effectsAreLocal(items: readonly LayerEffect[]): boolean;
+/**
+ * Builds every map `items` paints through from the layer's alpha `shape` (0..1) over `rect`.
+ * `rect` should cover the layer's shape plus the effects' margin.
+ */
+declare function buildEffectMaps(items: LayerEffect[], shape: Float32Array, rect: EffectRect, ctx: EffectContext): EffectMaps;
+/**
+ * `prev` brought up to date for a shape over `rect` that differs from the one it was built from only
+ * inside `changed` (document rects), or `null` when a full {@link buildEffectMaps} is the better
+ * deal (the change covers much of the region) or the effects are not local
+ * ({@link effectsAreLocal}). `items` must be the ones `prev` was built with, reaching at most
+ * `margin` px, and `shapeOver(r)` returns the new shape over `r`.
+ *
+ * Every map pixel within `margin` of a change, or outside `prev.rect`, is rebuilt from the shape
+ * within `margin` of it (a window of the change grown by twice the margin) and pasted in; the rest
+ * is kept. A local map pixel depends only on the shape within the margin and the blur sums exactly,
+ * so the result paints exactly what a full build over `rect` would. `prev`'s buffers are reused
+ * when `rect` is unchanged.
+ */
+declare function patchEffectMaps(prev: EffectMaps, items: LayerEffect[], rect: EffectRect, changed: readonly EffectRect[], margin: number, shapeOver: (r: EffectRect) => Float32Array, ctx: EffectContext): EffectMaps | null;
+/** Gradient parameter `t` (0..1) at pixel centre `(x, y)` of a gradient laid out in `frame`. */
+declare function gradientT(style: GradientStyle, angle: number, scale: number, reverse: boolean, offset: {
+    x: number;
+    y: number;
+}, frame: EffectRect, x: number, y: number): number;
+/**
+ * The colours an effect fill paints over `rect`, as straight float RGBA (0..1, `width × height`
+ * pixels, row by row): a solid colour, a gradient laid out in `frame` (when aligned with the layer)
+ * or `canvas`, or a pattern tiled from `anchor` (when linked). Shape layers paint with it, so their
+ * fills and strokes match the overlays of layer effects.
+ */
+declare function effectFillColors(fill: EffectFill, rect: EffectRect, frame: EffectRect, canvas: EffectRect, anchor: {
+    x: number;
+    y: number;
+}, ctx: EffectContext): Float32Array;
+interface EffectCompositeInput {
+    /** The accumulator (straight RGBA over `rect`); receives the layer and its effects. */
+    backdrop: Uint8ClampedArray;
+    /** The layer's pixels over `rect` (straight RGBA, mask applied to alpha, clipped layers applied). */
+    content: Uint8ClampedArray;
+    rect: EffectRect;
+    maps: EffectMaps;
+    blend: BlendMode;
+    /** Layer opacity: the whole stack. */
+    opacity: number;
+    /** Fill opacity: the layer's own pixels only. */
+    fillOpacity: number;
+    /** The canvas (unaligned gradients span it). */
+    canvas: EffectRect;
+    ctx: EffectContext;
+}
+/** Composites a layer's content and its effects onto `backdrop` in place (see the module comment for the order). */
+declare function compositeLayerEffects(input: EffectCompositeInput): void;
+/**
+ * Renders one layer with its effects over a whole region in one pass (no tiles): the reference
+ * the per-tile compositor is checked against, and a convenience for one-off renders.
+ */
+declare function renderLayerEffects(effects: LayerEffects, layer: {
+    content: Uint8ClampedArray;
+    rect: EffectRect;
+    blend: BlendMode;
+    opacity: number;
+    fillOpacity?: number;
+}, backdrop: Uint8ClampedArray, canvas: EffectRect, ctx: EffectContext): void;
+
+export { type StrokeEffect as $, type EffectRect as A, type BevelContour as B, type CompositorLayer as C, DEFAULT_GLOBAL_LIGHT as D, type EffectFill as E, type GlowTechnique as F, type GroupBlendMode as G, type GradientColorStop as H, type Interpolation as I, type GradientOpacityStop as J, type GradientOverlayEffect as K, type LayerLocks as L, type GradientStyle as M, INTERPOLATIONS as N, type InnerGlowEffect as O, type InnerShadowEffect as P, LAYER_EFFECT_KINDS as Q, type RasterLayer as R, LayerEffectError as S, MAX_EFFECT_REACH as T, MAX_TRANSFORM_PIXELS as U, type OuterGlowEffect as V, type PatternOverlayEffect as W, PatternPlacement as X, PatternTile as Y, type ResampleOptions as Z, type SatinEffect as _, type RasterGroupLayer as a, type StrokePosition as a0, TransformTooLargeError as a1, blendTile as a2, builtinPattern as a3, builtinPatternIds as a4, changedTiles as a5, compositeSurfaceOver as a6, defaultEffectGradient as a7, defaultLayerEffect as a8, effectColorHex as a9, validateLayerEffect as aA, validateLayerEffects as aB, warpSurface as aC, type CompositorProfile as aD, type EffectCompositeInput as aE, type EffectMaps as aF, type GroupIn as aG, type PixelFilterSpec as aH, type RasterNode as aI, STROKE_CHAMFER_MAX as aJ, activeEffectItems as aK, buildEffectMaps as aL, compositeLayerEffects as aM, contourLut as aN, effectFillColors as aO, effectsAreLocal as aP, gradientT as aQ, patchEffectMaps as aR, effectReach as aa, effectsFingerprint as ab, effectsMargin as ac, effectsScale as ad, findLayer as ae, flattenLayers as af, hasActiveEffects as ag, hashNoise as ah, insertLayer as ai, isInterpolation as aj, isLayerEffectKind as ak, isLayerLocked as al, keysWeight as am, layerEffectFields as an, layerEffectLabel as ao, mapLayer as ap, mergeLayerEffect as aq, newEffectId as ar, normalizeLayerEffects as as, parseEffectColor as at, reduceSurface as au, renderLayerEffects as av, scaleLayerEffect as aw, transformSurface as ax, transformedBounds as ay, validateEffectGradient as az, type RasterPixelLayer as b, RasterCompositor as c, type RasterSources as d, type RasterLayerBase as e, type RasterMask as f, type GlobalLight as g, type EffectPattern as h, type LayerLocation as i, type LayerEffect as j, type LayerEffects as k, type CompositorOptions as l, type LayerEffectKind as m, type EffectContext as n, type BevelEmbossEffect as o, type BevelStyle as p, type BevelTechnique as q, type BevelTexture as r, type ColorOverlayEffect as s, type CompositeCallOptions as t, type CompositeStats as u, type ContourPoint as v, type DropShadowEffect as w, type EffectContour as x, type EffectGradient as y, type EffectPatternRef as z };

package/dist/{surface-CkKOHGPm.d.cts → surface-C8RRg_Bh.d.cts}

@@ -1,3 +1,106 @@
+/**
+ * Pigment-like colour mixing: blue and yellow make green, red and white make pink, as paint does.
+ *
+ * Each sRGB colour is lifted to a smooth reflectance spectrum, the spectra are mixed with the
+ * Kubelka-Munk two-flux model, and the mixed spectrum is turned back into sRGB. Written from the
+ * published literature; no third-party code or data:
+ *
+ * 1. **Spectral uplift.** A colour's reflectance is a sigmoid of a quadratic in wavelength,
+ *    `R(λ) = s(c₀λ² + c₁λ + c₂)` with `s(z) = ½ + z / 2√(1 + z²)` (Jakob & Hanika, "A
+ *    Low-Dimensional Function Space for Efficient Spectral Upsampling", Eurographics 2019). The
+ *    three coefficients are solved per colour with Newton's method so the spectrum reproduces the
+ *    colour. Spectra are precomputed lazily on a 17³ lattice over sRGB and interpolated
+ *    trilinearly in *linear* RGB: colour is linear in reflectance, so an interpolated spectrum
+ *    still reproduces its colour exactly while staying smooth and inside 0..1.
+ * 2. **Mixing.** Each spectrum becomes `K/S = (1 − R)² / 2R` per band. Colours mix with the
+ *    two-constant form `K/S = Σ cᵢSᵢ(K/S)ᵢ / Σ cᵢSᵢ`, where `cᵢ` is the weight times the colour's
+ *    tinting strength and `Sᵢ` its scattering, taken from its luminance (light paints such as
+ *    titanium white scatter strongly, dark ones barely). Back to reflectance with
+ *    `R = 1 + K/S − √((K/S)² + 2·K/S)`.
+ * 3. **Back to sRGB.** The spectrum is weighted by the CIE 1931 2° colour-matching functions
+ *    (the analytic multi-lobe fit of Wyman, Sloan & Shirley, JCGT 2013) under a 6504 K Planckian
+ *    illuminant, converted to linear sRGB and normalised so a perfect white reflector is exactly
+ *    white. Analytic curves keep the CIE's own (CC BY-SA) tables out of the package.
+ *
+ * Everything is plain TypeScript on typed arrays with no DOM: it runs in Node and Workers and is
+ * deterministic. Colours are straight sRGB triples in 0..1, as in `@pixerate/editor/raster`.
+ */
+/** An sRGB colour, each channel 0..1 (gamma-encoded, as in CSS). */
+type PigmentRgb = readonly [number, number, number];
+/** Number of spectral bands. */
+declare const PIGMENT_BANDS = 36;
+/** First band's wavelength in nm; bands are 10 nm apart (380..730 nm). */
+declare const PIGMENT_LAMBDA_MIN = 380;
+declare const PIGMENT_LAMBDA_STEP = 10;
+/** Band centre wavelengths in nm. */
+declare const PIGMENT_WAVELENGTHS: Float32Array;
+/**
+ * The smooth reflectance spectrum (0..1 per band, `PIGMENT_BANDS` bands from 380 nm in 10 nm
+ * steps) of an sRGB colour. `reflectanceToRgb` of the result gives the colour back.
+ */
+declare function rgbToReflectance(r: number, g: number, b: number, out?: Float32Array): Float32Array;
+/** The sRGB colour (0..1, clipped to the gamut) of a reflectance spectrum. */
+declare function reflectanceToRgb(reflectance: ArrayLike<number>, out?: number[]): number[];
+/**
+ * A colour prepared for mixing: its K/S spectrum and its weight in a mix. Make one per brush or
+ * palette colour with `createPigment` and reuse it (`setPigmentColor`) on hot paths.
+ */
+interface Pigment {
+    /** The sRGB colour it was made from (0..1). */
+    readonly rgb: [number, number, number];
+    /** Tinting strength (default 1): how strongly it colours a mix, relative to its weight. */
+    strength: number;
+    /** K/S per band. */
+    readonly ks: Float32Array;
+    /** Scattering from the colour's luminance (floored), before strength. */
+    scatter: number;
+}
+interface PigmentOptions {
+    /**
+     * Tinting strength, > 0 (default 1). A strength of 4 counts each part as four, so a little of
+     * a strong dark pigment tints a lot of white. A colour mixed only with itself is unchanged
+     * whatever its strength.
+     */
+    strength?: number;
+}
+/** Prepares a colour for mixing. */
+declare function createPigment(color: PigmentRgb, options?: PigmentOptions): Pigment;
+/** Re-targets a pigment to another colour without allocating (the per-pixel fast path). */
+declare function setPigmentColor(pigment: Pigment, r: number, g: number, b: number, strength?: number): Pigment;
+/**
+ * Mixes colours like paint. `weights` are parts by amount (any non-negative scale; at least one
+ * positive). Colours may be sRGB triples (0..1) or prepared pigments (which carry a tinting
+ * strength). Returns the mixed sRGB colour (0..1).
+ */
+declare function mixPigments(colors: readonly (PigmentRgb | Pigment)[], weights: readonly number[]): [number, number, number];
+/** Mixes `a` towards `b` like paint: `t = 0` is `a`, `t = 1` is `b`. */
+declare function lerpPigment(a: PigmentRgb | Pigment, b: PigmentRgb | Pigment, t: number): [number, number, number];
+/**
+ * The per-dab fast path: mixes two prepared pigments (`t` of `b` into `a`) and writes the sRGB
+ * result to `out[offset..offset + 2]`, without allocating. Pair it with `setPigmentColor` for the
+ * colour under the brush.
+ */
+declare function lerpPigmentInto(a: Pigment, b: Pigment, t: number, out: {
+    [i: number]: number;
+}, offset?: number): void;
+
+/**
+ * Photoshop blend modes on straight (non-premultiplied) 0..1 colours.
+ *
+ * Formulas follow the W3C Compositing / ISO 32000 definitions, with Photoshop's variants where
+ * they differ (Soft Light, Vivid / Linear / Pin Light, Hard Mix, Linear Burn / Dodge, Subtract,
+ * Divide, Darker / Lighter Color), and the hardened `ClipColor` for the non-separable modes.
+ *
+ * Plus `pigment`, which is not a `B(Cb, Cs)` mode: it replaces the alpha interpolation
+ * `(1 − α)·Cb + α·B` with a Kubelka-Munk paint mix of the two colours (see `lerpPigment`).
+ *
+ * Plus four painterly modes of our own design, which are ordinary `B(Cb, Cs)` modes, so every
+ * caller of `blendRgb` / `blendChannel` (the compositor, adjustment layers, effects, brushes) gets
+ * them for free: `watercolor` (transparent washes, multiplied per wavelength), `tint` (the source's
+ * colour on the backdrop's lightness, gently at the extremes), `highlight` (light added with a
+ * soft shoulder) and `shadow` (light taken away, with ambient fill). See `painterlyRgb`.
+ */
+
 type BlendMode = 'normal' | 'darken' | 'multiply' | 'color-burn' | 'linear-burn' | 'darker-color' | 'lighten' | 'screen' | 'color-dodge' | 'linear-dodge' | 'lighter-color' | 'overlay' | 'soft-light' | 'hard-light' | 'vivid-light' | 'linear-light' | 'pin-light' | 'hard-mix' | 'difference' | 'exclusion' | 'subtract' | 'divide' | 'hue' | 'saturation' | 'color' | 'luminosity' | 'pigment' | 'watercolor' | 'tint' | 'highlight' | 'shadow';
 interface BlendModeInfo {
     id: BlendMode;
@@ -56,6 +159,11 @@ declare const SHADOW_AMBIENT = 0.2;
  * `out[0..2]`. `t ≥ 1` (or equal colours) is `cs` exactly. Colours are 0..1.
  */
 declare function mixPigmentRgb(cb: readonly number[], cs: readonly number[], t: number, out?: number[]): number[];
+/**
+ * The prepared pigment (K/S spectrum) of an 8-bit colour, from the cache every 8-bit pigment
+ * composite shares. Read-only: do not retarget it with `setPigmentColor`.
+ */
+declare function pigment8(r: number, g: number, b: number): Pigment;
 /**
  * {@link mixPigmentRgb} on 8-bit channels, with each colour's spectrum cached: writes the 0..1
  * result to `out[0..2]`. The compositor's and {@link blendImageData}'s per-pixel path.
@@ -208,4 +316,4 @@ declare function collectTiles(surface: TiledSurface, into: Set<Tile>): void;
 /** True when two surfaces hold the same pixels (cheap when they share tiles). */
 declare function surfacesEqual(a: TiledSurface, b: TiledSurface): boolean;
 
-export { mixPigmentRgb as A, type BlendMode as B, normalizeBlendMode as C, packRgba as D, readPixel as E, readRegion as F, setLum as G, solidSurface as H, surfaceBytes as I, surfaceFromPixels as J, surfacesEqual as K, tileCoord as L, type MaskSurface as M, tileKey as N, tileRect as O, type PixelSurface as P, tilesInRect as Q, type RasterRect as R, SHADOW_AMBIENT as S, type TileKey as T, translateSurface as U, uniformTile as V, writeRegion as W, TiledSurface as a, type BlendModeInfo as b, BLEND_MODES as c, PAINTERLY_BLEND_MODES as d, type Tile as e, isPainterlyBlendMode as f, type Rgb as g, type Rgba as h, isBlendMode as i, SurfaceDraft as j, TILE as k, TILE_SHIFT as l, blendChannel as m, blendImageData as n, blendLum as o, blendPixel as p, blendRgb as q, canvasCompositeOperation as r, standardBlendMode as s, collectTiles as t, contentBounds as u, emptySurface as v, fillRect as w, finishTile as x, isSeparableBlendMode as y, mixPigment8 as z };
+export { solidSurface as $, collectTiles as A, type BlendMode as B, contentBounds as C, createPigment as D, emptySurface as E, fillRect as F, finishTile as G, isSeparableBlendMode as H, lerpPigment as I, lerpPigmentInto as J, mixPigment8 as K, mixPigmentRgb as L, type MaskSurface as M, mixPigments as N, normalizeBlendMode as O, type Pigment as P, packRgba as Q, type RasterRect as R, SHADOW_AMBIENT as S, type TileKey as T, pigment8 as U, readPixel as V, readRegion as W, reflectanceToRgb as X, rgbToReflectance as Y, setLum as Z, setPigmentColor as _, TiledSurface as a, surfaceBytes as a0, surfaceFromPixels as a1, surfacesEqual as a2, tileCoord as a3, tileKey as a4, tileRect as a5, tilesInRect as a6, translateSurface as a7, uniformTile as a8, writeRegion as a9, type PixelSurface as b, type BlendModeInfo as c, BLEND_MODES as d, PAINTERLY_BLEND_MODES as e, type Tile as f, isPainterlyBlendMode as g, PIGMENT_BANDS as h, isBlendMode as i, PIGMENT_LAMBDA_MIN as j, PIGMENT_LAMBDA_STEP as k, PIGMENT_WAVELENGTHS as l, type PigmentOptions as m, type PigmentRgb as n, type Rgb as o, type Rgba as p, SurfaceDraft as q, TILE as r, standardBlendMode as s, TILE_SHIFT as t, blendChannel as u, blendImageData as v, blendLum as w, blendPixel as x, blendRgb as y, canvasCompositeOperation as z };

package/dist/{surface-CkKOHGPm.d.ts → surface-C8RRg_Bh.d.ts}

@@ -1,3 +1,106 @@
+/**
+ * Pigment-like colour mixing: blue and yellow make green, red and white make pink, as paint does.
+ *
+ * Each sRGB colour is lifted to a smooth reflectance spectrum, the spectra are mixed with the
+ * Kubelka-Munk two-flux model, and the mixed spectrum is turned back into sRGB. Written from the
+ * published literature; no third-party code or data:
+ *
+ * 1. **Spectral uplift.** A colour's reflectance is a sigmoid of a quadratic in wavelength,
+ *    `R(λ) = s(c₀λ² + c₁λ + c₂)` with `s(z) = ½ + z / 2√(1 + z²)` (Jakob & Hanika, "A
+ *    Low-Dimensional Function Space for Efficient Spectral Upsampling", Eurographics 2019). The
+ *    three coefficients are solved per colour with Newton's method so the spectrum reproduces the
+ *    colour. Spectra are precomputed lazily on a 17³ lattice over sRGB and interpolated
+ *    trilinearly in *linear* RGB: colour is linear in reflectance, so an interpolated spectrum
+ *    still reproduces its colour exactly while staying smooth and inside 0..1.
+ * 2. **Mixing.** Each spectrum becomes `K/S = (1 − R)² / 2R` per band. Colours mix with the
+ *    two-constant form `K/S = Σ cᵢSᵢ(K/S)ᵢ / Σ cᵢSᵢ`, where `cᵢ` is the weight times the colour's
+ *    tinting strength and `Sᵢ` its scattering, taken from its luminance (light paints such as
+ *    titanium white scatter strongly, dark ones barely). Back to reflectance with
+ *    `R = 1 + K/S − √((K/S)² + 2·K/S)`.
+ * 3. **Back to sRGB.** The spectrum is weighted by the CIE 1931 2° colour-matching functions
+ *    (the analytic multi-lobe fit of Wyman, Sloan & Shirley, JCGT 2013) under a 6504 K Planckian
+ *    illuminant, converted to linear sRGB and normalised so a perfect white reflector is exactly
+ *    white. Analytic curves keep the CIE's own (CC BY-SA) tables out of the package.
+ *
+ * Everything is plain TypeScript on typed arrays with no DOM: it runs in Node and Workers and is
+ * deterministic. Colours are straight sRGB triples in 0..1, as in `@pixerate/editor/raster`.
+ */
+/** An sRGB colour, each channel 0..1 (gamma-encoded, as in CSS). */
+type PigmentRgb = readonly [number, number, number];
+/** Number of spectral bands. */
+declare const PIGMENT_BANDS = 36;
+/** First band's wavelength in nm; bands are 10 nm apart (380..730 nm). */
+declare const PIGMENT_LAMBDA_MIN = 380;
+declare const PIGMENT_LAMBDA_STEP = 10;
+/** Band centre wavelengths in nm. */
+declare const PIGMENT_WAVELENGTHS: Float32Array;
+/**
+ * The smooth reflectance spectrum (0..1 per band, `PIGMENT_BANDS` bands from 380 nm in 10 nm
+ * steps) of an sRGB colour. `reflectanceToRgb` of the result gives the colour back.
+ */
+declare function rgbToReflectance(r: number, g: number, b: number, out?: Float32Array): Float32Array;
+/** The sRGB colour (0..1, clipped to the gamut) of a reflectance spectrum. */
+declare function reflectanceToRgb(reflectance: ArrayLike<number>, out?: number[]): number[];
+/**
+ * A colour prepared for mixing: its K/S spectrum and its weight in a mix. Make one per brush or
+ * palette colour with `createPigment` and reuse it (`setPigmentColor`) on hot paths.
+ */
+interface Pigment {
+    /** The sRGB colour it was made from (0..1). */
+    readonly rgb: [number, number, number];
+    /** Tinting strength (default 1): how strongly it colours a mix, relative to its weight. */
+    strength: number;
+    /** K/S per band. */
+    readonly ks: Float32Array;
+    /** Scattering from the colour's luminance (floored), before strength. */
+    scatter: number;
+}
+interface PigmentOptions {
+    /**
+     * Tinting strength, > 0 (default 1). A strength of 4 counts each part as four, so a little of
+     * a strong dark pigment tints a lot of white. A colour mixed only with itself is unchanged
+     * whatever its strength.
+     */
+    strength?: number;
+}
+/** Prepares a colour for mixing. */
+declare function createPigment(color: PigmentRgb, options?: PigmentOptions): Pigment;
+/** Re-targets a pigment to another colour without allocating (the per-pixel fast path). */
+declare function setPigmentColor(pigment: Pigment, r: number, g: number, b: number, strength?: number): Pigment;
+/**
+ * Mixes colours like paint. `weights` are parts by amount (any non-negative scale; at least one
+ * positive). Colours may be sRGB triples (0..1) or prepared pigments (which carry a tinting
+ * strength). Returns the mixed sRGB colour (0..1).
+ */
+declare function mixPigments(colors: readonly (PigmentRgb | Pigment)[], weights: readonly number[]): [number, number, number];
+/** Mixes `a` towards `b` like paint: `t = 0` is `a`, `t = 1` is `b`. */
+declare function lerpPigment(a: PigmentRgb | Pigment, b: PigmentRgb | Pigment, t: number): [number, number, number];
+/**
+ * The per-dab fast path: mixes two prepared pigments (`t` of `b` into `a`) and writes the sRGB
+ * result to `out[offset..offset + 2]`, without allocating. Pair it with `setPigmentColor` for the
+ * colour under the brush.
+ */
+declare function lerpPigmentInto(a: Pigment, b: Pigment, t: number, out: {
+    [i: number]: number;
+}, offset?: number): void;
+
+/**
+ * Photoshop blend modes on straight (non-premultiplied) 0..1 colours.
+ *
+ * Formulas follow the W3C Compositing / ISO 32000 definitions, with Photoshop's variants where
+ * they differ (Soft Light, Vivid / Linear / Pin Light, Hard Mix, Linear Burn / Dodge, Subtract,
+ * Divide, Darker / Lighter Color), and the hardened `ClipColor` for the non-separable modes.
+ *
+ * Plus `pigment`, which is not a `B(Cb, Cs)` mode: it replaces the alpha interpolation
+ * `(1 − α)·Cb + α·B` with a Kubelka-Munk paint mix of the two colours (see `lerpPigment`).
+ *
+ * Plus four painterly modes of our own design, which are ordinary `B(Cb, Cs)` modes, so every
+ * caller of `blendRgb` / `blendChannel` (the compositor, adjustment layers, effects, brushes) gets
+ * them for free: `watercolor` (transparent washes, multiplied per wavelength), `tint` (the source's
+ * colour on the backdrop's lightness, gently at the extremes), `highlight` (light added with a
+ * soft shoulder) and `shadow` (light taken away, with ambient fill). See `painterlyRgb`.
+ */
+
 type BlendMode = 'normal' | 'darken' | 'multiply' | 'color-burn' | 'linear-burn' | 'darker-color' | 'lighten' | 'screen' | 'color-dodge' | 'linear-dodge' | 'lighter-color' | 'overlay' | 'soft-light' | 'hard-light' | 'vivid-light' | 'linear-light' | 'pin-light' | 'hard-mix' | 'difference' | 'exclusion' | 'subtract' | 'divide' | 'hue' | 'saturation' | 'color' | 'luminosity' | 'pigment' | 'watercolor' | 'tint' | 'highlight' | 'shadow';
 interface BlendModeInfo {
     id: BlendMode;
@@ -56,6 +159,11 @@ declare const SHADOW_AMBIENT = 0.2;
  * `out[0..2]`. `t ≥ 1` (or equal colours) is `cs` exactly. Colours are 0..1.
  */
 declare function mixPigmentRgb(cb: readonly number[], cs: readonly number[], t: number, out?: number[]): number[];
+/**
+ * The prepared pigment (K/S spectrum) of an 8-bit colour, from the cache every 8-bit pigment
+ * composite shares. Read-only: do not retarget it with `setPigmentColor`.
+ */
+declare function pigment8(r: number, g: number, b: number): Pigment;
 /**
  * {@link mixPigmentRgb} on 8-bit channels, with each colour's spectrum cached: writes the 0..1
  * result to `out[0..2]`. The compositor's and {@link blendImageData}'s per-pixel path.
@@ -208,4 +316,4 @@ declare function collectTiles(surface: TiledSurface, into: Set<Tile>): void;
 /** True when two surfaces hold the same pixels (cheap when they share tiles). */
 declare function surfacesEqual(a: TiledSurface, b: TiledSurface): boolean;
 
-export { mixPigmentRgb as A, type BlendMode as B, normalizeBlendMode as C, packRgba as D, readPixel as E, readRegion as F, setLum as G, solidSurface as H, surfaceBytes as I, surfaceFromPixels as J, surfacesEqual as K, tileCoord as L, type MaskSurface as M, tileKey as N, tileRect as O, type PixelSurface as P, tilesInRect as Q, type RasterRect as R, SHADOW_AMBIENT as S, type TileKey as T, translateSurface as U, uniformTile as V, writeRegion as W, TiledSurface as a, type BlendModeInfo as b, BLEND_MODES as c, PAINTERLY_BLEND_MODES as d, type Tile as e, isPainterlyBlendMode as f, type Rgb as g, type Rgba as h, isBlendMode as i, SurfaceDraft as j, TILE as k, TILE_SHIFT as l, blendChannel as m, blendImageData as n, blendLum as o, blendPixel as p, blendRgb as q, canvasCompositeOperation as r, standardBlendMode as s, collectTiles as t, contentBounds as u, emptySurface as v, fillRect as w, finishTile as x, isSeparableBlendMode as y, mixPigment8 as z };
+export { solidSurface as $, collectTiles as A, type BlendMode as B, contentBounds as C, createPigment as D, emptySurface as E, fillRect as F, finishTile as G, isSeparableBlendMode as H, lerpPigment as I, lerpPigmentInto as J, mixPigment8 as K, mixPigmentRgb as L, type MaskSurface as M, mixPigments as N, normalizeBlendMode as O, type Pigment as P, packRgba as Q, type RasterRect as R, SHADOW_AMBIENT as S, type TileKey as T, pigment8 as U, readPixel as V, readRegion as W, reflectanceToRgb as X, rgbToReflectance as Y, setLum as Z, setPigmentColor as _, TiledSurface as a, surfaceBytes as a0, surfaceFromPixels as a1, surfacesEqual as a2, tileCoord as a3, tileKey as a4, tileRect as a5, tilesInRect as a6, translateSurface as a7, uniformTile as a8, writeRegion as a9, type PixelSurface as b, type BlendModeInfo as c, BLEND_MODES as d, PAINTERLY_BLEND_MODES as e, type Tile as f, isPainterlyBlendMode as g, PIGMENT_BANDS as h, isBlendMode as i, PIGMENT_LAMBDA_MIN as j, PIGMENT_LAMBDA_STEP as k, PIGMENT_WAVELENGTHS as l, type PigmentOptions as m, type PigmentRgb as n, type Rgb as o, type Rgba as p, SurfaceDraft as q, TILE as r, standardBlendMode as s, TILE_SHIFT as t, blendChannel as u, blendImageData as v, blendLum as w, blendPixel as x, blendRgb as y, canvasCompositeOperation as z };