@pixerate/editor 0.87.0 → 0.89.0

package/dist/surface-fJhkmNQn.d.cts

@@ -0,0 +1,181 @@
+/**
+ * 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.
+ */
+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';
+interface BlendModeInfo {
+    id: BlendMode;
+    label: string;
+    /** Canvas `globalCompositeOperation` with the same maths, when there is one. */
+    canvas: GlobalCompositeOperation | null;
+}
+/** Every blend mode, in Photoshop's menu order. */
+declare const BLEND_MODES: readonly BlendModeInfo[];
+declare function isBlendMode(value: unknown): value is BlendMode;
+/** A stored blend mode, or `normal` for a missing / unknown value. */
+declare function normalizeBlendMode(value: unknown): BlendMode;
+/**
+ * The canvas composite operation that implements `mode` exactly, or `null` when the canvas has
+ * none (draw through {@link blendImageData} instead).
+ */
+declare function canvasCompositeOperation(mode: BlendMode | undefined): GlobalCompositeOperation | null;
+/** Whether a mode works on whole colours (hue, saturation, colour, luminosity, darker / lighter colour). */
+declare function isSeparableBlendMode(mode: BlendMode): boolean;
+/** Separable blend function `B(cb, cs)` of one channel. Non-separable modes return `cs`. */
+declare function blendChannel(mode: BlendMode, cb: number, cs: number): number;
+type Rgb = [number, number, number];
+type Rgba = [number, number, number, number];
+/** Luminosity of the non-separable modes (W3C / ISO 32000 weights). */
+declare function blendLum(c: readonly number[]): number;
+/** `c` with its luminosity moved to `l`, clipped back into gamut towards grey (SetLum + ClipColor). */
+declare function setLum(c: readonly number[], l: number): Rgb;
+/** `B(Cb, Cs)` of a whole colour, including the non-separable modes. */
+declare function blendRgb(mode: BlendMode, cb: readonly number[], cs: readonly number[]): Rgb;
+/**
+ * Composites a straight-alpha `source` over a straight-alpha `backdrop` (both RGBA in 0..1) with a
+ * blend mode and an extra `alpha` (opacity), using the W3C general formula:
+ * `αo = αs + αb(1 − αs)`, `αo·Co = (1 − αs)·αb·Cb + (1 − αb)·αs·Cs + αs·αb·B(Cb, Cs)`.
+ */
+declare function blendPixel(mode: BlendMode, backdrop: readonly number[], source: readonly number[], alpha?: number): Rgba;
+/**
+ * Blends `source` into `backdrop` in place (8-bit straight RGBA of the same size) with
+ * {@link blendPixel}. The scalar fallback for modes the canvas cannot composite.
+ */
+declare function blendImageData(backdrop: ImageData, source: ImageData, mode: BlendMode, alpha?: number): void;
+
+/**
+ * Tiled, sparse, copy-on-write pixel storage (photocraft's `Surface`): 256 px square tiles in a
+ * map keyed by tile coordinate, a default value for every missing tile, and shared tiles.
+ *
+ * - Pixels are 8-bit, straight alpha: RGBA for layers (4 channels, the same as `ImageData`), one
+ *   byte for masks.
+ * - A surface is never mutated. A write returns a new surface that shares every tile it did not
+ *   touch, so undo history and caches can keep old surfaces by reference.
+ * - A tile whose pixels all hold one value is a *uniform* tile; one instance per value is shared,
+ *   so a solid fill or a "hide all" mask costs one tile however large it is.
+ * - Coordinates are document pixels and may be negative or past the canvas (layers can extend
+ *   beyond it, as PSD layer rects do).
+ *
+ * The module has no DOM dependency, so it runs in Node, tests and workers.
+ */
+/** A pixel rectangle (`x`, `y` of the top-left corner, `width`, `height`). */
+interface RasterRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+type CropBox = RasterRect;
+declare const TILE = 256;
+declare const TILE_SHIFT = 8;
+/** A tile coordinate packed into one number (tx, ty in −32768..32767). */
+type TileKey = number;
+declare function tileKey(tx: number, ty: number): TileKey;
+declare function tileCoord(key: TileKey): {
+    tx: number;
+    ty: number;
+};
+/** A tile's pixel rectangle in document space. */
+declare function tileRect(tx: number, ty: number): CropBox;
+/** One tile: TILE × TILE pixels of `channels` bytes. Never mutate `data` after it is shared. */
+interface Tile {
+    readonly data: Uint8ClampedArray;
+    /** The packed value of every pixel when the tile is uniform, else `null`. */
+    readonly uniform: number | null;
+}
+/**
+ * An immutable tiled surface. `channels` is 4 (RGBA) for layers and 1 for masks. Missing tiles
+ * hold `defaultValue` in every byte (0: transparent black for layers; 0 or 255 for masks).
+ */
+declare class TiledSurface {
+    readonly channels: 1 | 4;
+    readonly tiles: ReadonlyMap<TileKey, Tile>;
+    readonly defaultValue: number;
+    /** Unique per instance: a cache key that changes whenever the pixels can have changed. */
+    readonly id: number;
+    private boundsCache;
+    constructor(channels: 1 | 4, tiles: ReadonlyMap<TileKey, Tile>, defaultValue?: number);
+    /** Bounds of the stored (non-default) tiles, tile-aligned; `null` when there are none. */
+    get bounds(): CropBox | null;
+    get tileCount(): number;
+    getTile(tx: number, ty: number): Tile | undefined;
+}
+type PixelSurface = TiledSurface;
+type MaskSurface = TiledSurface;
+/** The shared tile whose every pixel is `value` (packed RGBA, or one byte for masks). */
+declare function uniformTile(channels: 1 | 4, value: number): Tile;
+/** Packs an RGBA colour (0..255 each) the way uniform tiles store it. */
+declare function packRgba(r: number, g: number, b: number, a: number): number;
+/**
+ * Turns freshly written tile data into a stored tile: `null` when it equals the surface default
+ * (the tile is dropped), the shared uniform tile when it is uniform, else a tile owning `data`.
+ */
+declare function finishTile(data: Uint8ClampedArray, channels: 1 | 4, defaultValue: number): Tile | null;
+/** An empty surface (every pixel is `defaultValue`). */
+declare function emptySurface(channels?: 1 | 4, defaultValue?: number): TiledSurface;
+/** A surface filled with one value over `rect` (packed RGBA for layers, a byte for masks). */
+declare function solidSurface(channels: 1 | 4, rect: CropBox, value: number, defaultValue?: number): TiledSurface;
+/**
+ * A surface holding `width × height` interleaved pixels placed at (`x`, `y`) in document space.
+ * Tiles equal to the default are left out; uniform tiles are shared.
+ */
+declare function surfaceFromPixels(pixels: {
+    width: number;
+    height: number;
+    data: ArrayLike<number>;
+}, channels?: 1 | 4, x?: number, y?: number, defaultValue?: number): TiledSurface;
+/** Tile coordinates covering `rect`, row by row. */
+declare function tilesInRect(rect: CropBox): Array<{
+    tx: number;
+    ty: number;
+}>;
+/**
+ * Copies `rect` of the surface into `out` (or a new buffer), `rect.width × rect.height`
+ * interleaved pixels; missing tiles read as the default.
+ */
+declare function readRegion(surface: TiledSurface, rect: CropBox, out?: Uint8ClampedArray): Uint8ClampedArray;
+/** One pixel's bytes (RGBA or the mask byte). */
+declare function readPixel(surface: TiledSurface, x: number, y: number): number[];
+/**
+ * Exact bounds of the pixels that differ from the default (for a layer: non-transparent), or
+ * `null`. Scans the stored tiles; uniform tiles count whole.
+ */
+declare function contentBounds(surface: TiledSurface): CropBox | null;
+/**
+ * A private, mutable copy of the tiles a write touches. `tile(tx, ty)` copies the tile on first
+ * use; `commit()` returns a new surface sharing every untouched tile. Use it for strokes:
+ * edit through the draft while the pointer moves and commit once at pointer-up.
+ */
+declare class SurfaceDraft {
+    readonly base: TiledSurface;
+    private readonly copies;
+    constructor(base: TiledSurface);
+    get channels(): 1 | 4;
+    /** The writable data of tile (tx, ty), copied from the base on first use. */
+    tile(tx: number, ty: number): Uint8ClampedArray;
+    /** Replaces a whole tile with `data` (owned by the draft from now on). */
+    replace(tx: number, ty: number, data: Uint8ClampedArray): void;
+    /** The current data of a tile without copying it (base tile, draft copy or `null` for default). */
+    peek(tx: number, ty: number): Uint8ClampedArray | null;
+    /** Keys of the tiles changed so far. */
+    get touched(): TileKey[];
+    /** A new surface with the draft's tiles; the draft must not be used afterwards. */
+    commit(): TiledSurface;
+}
+/** Writes `rect.width × rect.height` interleaved pixels at `rect`; returns the new surface. */
+declare function writeRegion(surface: TiledSurface, rect: CropBox, data: ArrayLike<number>): TiledSurface;
+/** Fills `rect` with one pixel value (`bytes`, `channels` long). */
+declare function fillRect(surface: TiledSurface, rect: CropBox, bytes: ArrayLike<number>): TiledSurface;
+/** A copy of the surface moved by an integer offset (re-tiles; layers normally move by `offset`). */
+declare function translateSurface(surface: TiledSurface, dx: number, dy: number): TiledSurface;
+/** Bytes held by a surface's non-uniform tiles (uniform tiles are shared and nearly free). */
+declare function surfaceBytes(surface: TiledSurface): number;
+/** Adds every non-uniform tile of `surface` to `into` (for counting bytes shared across states). */
+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 { solidSurface as A, type BlendMode as B, surfaceBytes as C, surfaceFromPixels as D, surfacesEqual as E, tileCoord as F, tileKey as G, tileRect as H, tilesInRect as I, translateSurface as J, uniformTile as K, writeRegion as L, type MaskSurface as M, type PixelSurface as P, type RasterRect as R, SurfaceDraft as S, TiledSurface as T, BLEND_MODES as a, type BlendModeInfo as b, type Rgb as c, type Rgba as d, TILE as e, TILE_SHIFT as f, type Tile as g, type TileKey as h, blendChannel as i, blendImageData as j, blendLum as k, blendPixel as l, blendRgb as m, canvasCompositeOperation as n, collectTiles as o, contentBounds as p, emptySurface as q, fillRect as r, finishTile as s, isBlendMode as t, isSeparableBlendMode as u, normalizeBlendMode as v, packRgba as w, readPixel as x, readRegion as y, setLum as z };

package/dist/surface-fJhkmNQn.d.ts

@@ -0,0 +1,181 @@
+/**
+ * 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.
+ */
+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';
+interface BlendModeInfo {
+    id: BlendMode;
+    label: string;
+    /** Canvas `globalCompositeOperation` with the same maths, when there is one. */
+    canvas: GlobalCompositeOperation | null;
+}
+/** Every blend mode, in Photoshop's menu order. */
+declare const BLEND_MODES: readonly BlendModeInfo[];
+declare function isBlendMode(value: unknown): value is BlendMode;
+/** A stored blend mode, or `normal` for a missing / unknown value. */
+declare function normalizeBlendMode(value: unknown): BlendMode;
+/**
+ * The canvas composite operation that implements `mode` exactly, or `null` when the canvas has
+ * none (draw through {@link blendImageData} instead).
+ */
+declare function canvasCompositeOperation(mode: BlendMode | undefined): GlobalCompositeOperation | null;
+/** Whether a mode works on whole colours (hue, saturation, colour, luminosity, darker / lighter colour). */
+declare function isSeparableBlendMode(mode: BlendMode): boolean;
+/** Separable blend function `B(cb, cs)` of one channel. Non-separable modes return `cs`. */
+declare function blendChannel(mode: BlendMode, cb: number, cs: number): number;
+type Rgb = [number, number, number];
+type Rgba = [number, number, number, number];
+/** Luminosity of the non-separable modes (W3C / ISO 32000 weights). */
+declare function blendLum(c: readonly number[]): number;
+/** `c` with its luminosity moved to `l`, clipped back into gamut towards grey (SetLum + ClipColor). */
+declare function setLum(c: readonly number[], l: number): Rgb;
+/** `B(Cb, Cs)` of a whole colour, including the non-separable modes. */
+declare function blendRgb(mode: BlendMode, cb: readonly number[], cs: readonly number[]): Rgb;
+/**
+ * Composites a straight-alpha `source` over a straight-alpha `backdrop` (both RGBA in 0..1) with a
+ * blend mode and an extra `alpha` (opacity), using the W3C general formula:
+ * `αo = αs + αb(1 − αs)`, `αo·Co = (1 − αs)·αb·Cb + (1 − αb)·αs·Cs + αs·αb·B(Cb, Cs)`.
+ */
+declare function blendPixel(mode: BlendMode, backdrop: readonly number[], source: readonly number[], alpha?: number): Rgba;
+/**
+ * Blends `source` into `backdrop` in place (8-bit straight RGBA of the same size) with
+ * {@link blendPixel}. The scalar fallback for modes the canvas cannot composite.
+ */
+declare function blendImageData(backdrop: ImageData, source: ImageData, mode: BlendMode, alpha?: number): void;
+
+/**
+ * Tiled, sparse, copy-on-write pixel storage (photocraft's `Surface`): 256 px square tiles in a
+ * map keyed by tile coordinate, a default value for every missing tile, and shared tiles.
+ *
+ * - Pixels are 8-bit, straight alpha: RGBA for layers (4 channels, the same as `ImageData`), one
+ *   byte for masks.
+ * - A surface is never mutated. A write returns a new surface that shares every tile it did not
+ *   touch, so undo history and caches can keep old surfaces by reference.
+ * - A tile whose pixels all hold one value is a *uniform* tile; one instance per value is shared,
+ *   so a solid fill or a "hide all" mask costs one tile however large it is.
+ * - Coordinates are document pixels and may be negative or past the canvas (layers can extend
+ *   beyond it, as PSD layer rects do).
+ *
+ * The module has no DOM dependency, so it runs in Node, tests and workers.
+ */
+/** A pixel rectangle (`x`, `y` of the top-left corner, `width`, `height`). */
+interface RasterRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+type CropBox = RasterRect;
+declare const TILE = 256;
+declare const TILE_SHIFT = 8;
+/** A tile coordinate packed into one number (tx, ty in −32768..32767). */
+type TileKey = number;
+declare function tileKey(tx: number, ty: number): TileKey;
+declare function tileCoord(key: TileKey): {
+    tx: number;
+    ty: number;
+};
+/** A tile's pixel rectangle in document space. */
+declare function tileRect(tx: number, ty: number): CropBox;
+/** One tile: TILE × TILE pixels of `channels` bytes. Never mutate `data` after it is shared. */
+interface Tile {
+    readonly data: Uint8ClampedArray;
+    /** The packed value of every pixel when the tile is uniform, else `null`. */
+    readonly uniform: number | null;
+}
+/**
+ * An immutable tiled surface. `channels` is 4 (RGBA) for layers and 1 for masks. Missing tiles
+ * hold `defaultValue` in every byte (0: transparent black for layers; 0 or 255 for masks).
+ */
+declare class TiledSurface {
+    readonly channels: 1 | 4;
+    readonly tiles: ReadonlyMap<TileKey, Tile>;
+    readonly defaultValue: number;
+    /** Unique per instance: a cache key that changes whenever the pixels can have changed. */
+    readonly id: number;
+    private boundsCache;
+    constructor(channels: 1 | 4, tiles: ReadonlyMap<TileKey, Tile>, defaultValue?: number);
+    /** Bounds of the stored (non-default) tiles, tile-aligned; `null` when there are none. */
+    get bounds(): CropBox | null;
+    get tileCount(): number;
+    getTile(tx: number, ty: number): Tile | undefined;
+}
+type PixelSurface = TiledSurface;
+type MaskSurface = TiledSurface;
+/** The shared tile whose every pixel is `value` (packed RGBA, or one byte for masks). */
+declare function uniformTile(channels: 1 | 4, value: number): Tile;
+/** Packs an RGBA colour (0..255 each) the way uniform tiles store it. */
+declare function packRgba(r: number, g: number, b: number, a: number): number;
+/**
+ * Turns freshly written tile data into a stored tile: `null` when it equals the surface default
+ * (the tile is dropped), the shared uniform tile when it is uniform, else a tile owning `data`.
+ */
+declare function finishTile(data: Uint8ClampedArray, channels: 1 | 4, defaultValue: number): Tile | null;
+/** An empty surface (every pixel is `defaultValue`). */
+declare function emptySurface(channels?: 1 | 4, defaultValue?: number): TiledSurface;
+/** A surface filled with one value over `rect` (packed RGBA for layers, a byte for masks). */
+declare function solidSurface(channels: 1 | 4, rect: CropBox, value: number, defaultValue?: number): TiledSurface;
+/**
+ * A surface holding `width × height` interleaved pixels placed at (`x`, `y`) in document space.
+ * Tiles equal to the default are left out; uniform tiles are shared.
+ */
+declare function surfaceFromPixels(pixels: {
+    width: number;
+    height: number;
+    data: ArrayLike<number>;
+}, channels?: 1 | 4, x?: number, y?: number, defaultValue?: number): TiledSurface;
+/** Tile coordinates covering `rect`, row by row. */
+declare function tilesInRect(rect: CropBox): Array<{
+    tx: number;
+    ty: number;
+}>;
+/**
+ * Copies `rect` of the surface into `out` (or a new buffer), `rect.width × rect.height`
+ * interleaved pixels; missing tiles read as the default.
+ */
+declare function readRegion(surface: TiledSurface, rect: CropBox, out?: Uint8ClampedArray): Uint8ClampedArray;
+/** One pixel's bytes (RGBA or the mask byte). */
+declare function readPixel(surface: TiledSurface, x: number, y: number): number[];
+/**
+ * Exact bounds of the pixels that differ from the default (for a layer: non-transparent), or
+ * `null`. Scans the stored tiles; uniform tiles count whole.
+ */
+declare function contentBounds(surface: TiledSurface): CropBox | null;
+/**
+ * A private, mutable copy of the tiles a write touches. `tile(tx, ty)` copies the tile on first
+ * use; `commit()` returns a new surface sharing every untouched tile. Use it for strokes:
+ * edit through the draft while the pointer moves and commit once at pointer-up.
+ */
+declare class SurfaceDraft {
+    readonly base: TiledSurface;
+    private readonly copies;
+    constructor(base: TiledSurface);
+    get channels(): 1 | 4;
+    /** The writable data of tile (tx, ty), copied from the base on first use. */
+    tile(tx: number, ty: number): Uint8ClampedArray;
+    /** Replaces a whole tile with `data` (owned by the draft from now on). */
+    replace(tx: number, ty: number, data: Uint8ClampedArray): void;
+    /** The current data of a tile without copying it (base tile, draft copy or `null` for default). */
+    peek(tx: number, ty: number): Uint8ClampedArray | null;
+    /** Keys of the tiles changed so far. */
+    get touched(): TileKey[];
+    /** A new surface with the draft's tiles; the draft must not be used afterwards. */
+    commit(): TiledSurface;
+}
+/** Writes `rect.width × rect.height` interleaved pixels at `rect`; returns the new surface. */
+declare function writeRegion(surface: TiledSurface, rect: CropBox, data: ArrayLike<number>): TiledSurface;
+/** Fills `rect` with one pixel value (`bytes`, `channels` long). */
+declare function fillRect(surface: TiledSurface, rect: CropBox, bytes: ArrayLike<number>): TiledSurface;
+/** A copy of the surface moved by an integer offset (re-tiles; layers normally move by `offset`). */
+declare function translateSurface(surface: TiledSurface, dx: number, dy: number): TiledSurface;
+/** Bytes held by a surface's non-uniform tiles (uniform tiles are shared and nearly free). */
+declare function surfaceBytes(surface: TiledSurface): number;
+/** Adds every non-uniform tile of `surface` to `into` (for counting bytes shared across states). */
+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 { solidSurface as A, type BlendMode as B, surfaceBytes as C, surfaceFromPixels as D, surfacesEqual as E, tileCoord as F, tileKey as G, tileRect as H, tilesInRect as I, translateSurface as J, uniformTile as K, writeRegion as L, type MaskSurface as M, type PixelSurface as P, type RasterRect as R, SurfaceDraft as S, TiledSurface as T, BLEND_MODES as a, type BlendModeInfo as b, type Rgb as c, type Rgba as d, TILE as e, TILE_SHIFT as f, type Tile as g, type TileKey as h, blendChannel as i, blendImageData as j, blendLum as k, blendPixel as l, blendRgb as m, canvasCompositeOperation as n, collectTiles as o, contentBounds as p, emptySurface as q, fillRect as r, finishTile as s, isBlendMode as t, isSeparableBlendMode as u, normalizeBlendMode as v, packRgba as w, readPixel as x, readRegion as y, setLum as z };