@lacspace/image 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Shared types for @lacspace/image.
+ */
+/** A raster format this library can produce. `svg` passes through untouched. */
+type ImageFormat = "png" | "jpeg" | "webp";
+/** A CSS-ish colour: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()/rgba()`, or `transparent`. */
+type Color = string;
+/** One stop in a gradient. `offset` is 0..1; `color` any supported Color. */
+interface GradientStop {
+    offset: number;
+    color: Color;
+}
+interface LinearGradientOptions {
+    /** Angle in degrees, clockwise from the positive x-axis (0 = left→right, 90 = top→bottom). */
+    angle?: number;
+    stops: GradientStop[];
+}
+interface RadialGradientOptions {
+    /** Centre x in 0..1 of the surface width (default 0.5). */
+    cx?: number;
+    /** Centre y in 0..1 of the surface height (default 0.5). */
+    cy?: number;
+    /** Radius in 0..1 of the larger surface dimension (default 0.75). */
+    radius?: number;
+    stops: GradientStop[];
+}
+type PatternKind = "checker" | "grid" | "dots" | "stripes" | "noise";
+interface PatternOptions {
+    /** Cell/line size in px (default 24). */
+    size?: number;
+    /** Foreground colour (default #ffffff22 over the current surface). */
+    color?: Color;
+    /** For `stripes`: angle 0 (vertical) | 90 (horizontal) | 45 (diagonal). Default 45. */
+    angle?: 0 | 45 | 90;
+    /** For `noise`: 0..1 strength (default 0.06). */
+    strength?: number;
+    /** Deterministic seed for `noise` (default 1). */
+    seed?: number;
+}
+type Fit = "cover" | "contain" | "fill" | "stretch";
+interface DrawImageOptions {
+    x?: number;
+    y?: number;
+    /** Target width; defaults to source width (or fills the box when x/y/w/h given). */
+    width?: number;
+    height?: number;
+    /** How to place a source into the target box when both are sized. Default "cover". */
+    fit?: Fit;
+    /** Resampling quality when scaling (default "bilinear"). */
+    resample?: "nearest" | "bilinear";
+}
+/** Anything we can read pixels from. */
+interface PixelSource {
+    width: number;
+    height: number;
+    /** RGBA, row-major, 4 bytes per pixel. */
+    data: Uint8ClampedArray;
+}
+interface EncodeOptions {
+    format: ImageFormat;
+    /** 1..100 for lossy formats (jpeg/webp). Ignored for png. Default 82. */
+    quality?: number;
+    /** Background painted under transparent pixels when flattening to jpeg. Default #ffffff. */
+    background?: Color;
+}
+interface EncodeResult {
+    bytes: Uint8Array;
+    format: ImageFormat;
+    width: number;
+    height: number;
+    /** Effective quality used (lossy formats). */
+    quality?: number;
+    /** Byte length — same as bytes.length, provided for convenience. */
+    size: number;
+}
+interface FitOptions {
+    format: ImageFormat;
+    /** Target ceiling. Accepts a number of bytes or a string like "200kb" / "1.5mb". */
+    maxBytes?: number;
+    maxSize?: string | number;
+    /** Lowest acceptable quality before we start downscaling (default 30). */
+    minQuality?: number;
+    /** Highest quality to try first (default 92). */
+    maxQuality?: number;
+    /** Allow shrinking dimensions if quality alone can't hit the budget (default true). */
+    allowResize?: boolean;
+    /** Smallest scale factor when resizing (default 0.35). */
+    minScale?: number;
+    background?: Color;
+}
+
+/**
+ * Surface — a zero-dependency RGBA pixel buffer with a small, deterministic
+ * drawing API (fills, gradients, patterns, image placement, resize, crop).
+ * Works identically in Node and the browser; nothing here touches the DOM.
+ */
+
+declare class Surface implements PixelSource {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8ClampedArray;
+    constructor(width: number, height: number, data?: Uint8ClampedArray);
+    /** Wrap an existing RGBA source (e.g. a Canvas ImageData) without copying. */
+    static from(src: PixelSource): Surface;
+    private idx;
+    private set;
+    /** Paint the whole surface a solid colour (replaces, does not blend). */
+    fill(color: Color): this;
+    /** Blend a rectangle of colour over the surface. */
+    rect(x: number, y: number, w: number, h: number, color: Color): this;
+    linearGradient(opts: LinearGradientOptions): this;
+    radialGradient(opts: RadialGradientOptions): this;
+    pattern(kind: PatternKind, opts?: PatternOptions): this;
+    /** Bilinear sample of a source at fractional (u,v) in source pixel space. */
+    private static sampleBilinear;
+    /** Place another image/surface onto this one, with fit + resampling. */
+    drawImage(src: PixelSource, o?: DrawImageOptions): this;
+    /** Return a NEW surface resampled to the given dimensions (bilinear). */
+    resize(width: number, height: number): Surface;
+    /** Return a NEW surface cropped to the given rectangle. */
+    crop(x: number, y: number, w: number, h: number): Surface;
+    /** Flatten transparency onto a solid background, returning a NEW opaque surface. */
+    flatten(background?: Color): Surface;
+    /**
+     * Return a NEW surface with each channel reduced to `bits` bits (2..8).
+     * Fewer distinct values compress far better as lossless PNG — the main lever
+     * for hitting a PNG size budget on noisy/photographic content.
+     */
+    posterize(bits: number): Surface;
+    clone(): Surface;
+}
+/** Convenience: a new surface pre-filled with a linear gradient. */
+declare function gradient(width: number, height: number, opts: LinearGradientOptions): Surface;
+/** Convenience: a new surface pre-filled with a radial gradient. */
+declare function radial(width: number, height: number, opts: RadialGradientOptions): Surface;
+/** Convenience: a solid surface with a pattern painted over it. */
+declare function pattern(width: number, height: number, base: Color, kind: PatternKind, opts?: PatternOptions): Surface;
+
+/**
+ * Unified, isomorphic encode(): pick the best available encoder for the format
+ * and runtime. Browser/Worker → native Canvas (all formats). Node → pure-JS PNG
+ * (zlib) and JPEG; WebP needs a Canvas runtime.
+ */
+
+/** Encode an RGBA source to the requested format. */
+declare function encode(source: PixelSource, opts: EncodeOptions): Promise<EncodeResult>;
+
+/**
+ * fit() — encode an image to land at or under a file-size budget.
+ *
+ * Lossy formats (jpeg/webp): binary-search the quality knob for the highest
+ * quality that fits; if even the floor is too big, progressively downscale.
+ * Lossless png: quality can't move bytes, so we downscale toward the budget.
+ *
+ * It is a best-effort ceiling: the result is the closest fit ≤ budget we can
+ * reach within the quality/scale bounds (never padded up to the budget).
+ */
+
+declare function fit(source: PixelSource, opts: FitOptions): Promise<EncodeResult>;
+
+/**
+ * Minimal, dependency-free PNG encoder (8-bit RGBA, non-interlaced).
+ * Compression: `node:zlib` when running in Node (kept external in browser
+ * bundles), otherwise a valid *stored* (uncompressed) DEFLATE stream — so the
+ * output is always a spec-correct PNG everywhere, just larger without zlib.
+ * In the browser the orchestrator prefers Canvas, which compresses properly.
+ */
+
+/** Encode an RGBA source to PNG bytes. `level` 0..9 (zlib), default 9. */
+declare function encodePng(source: PixelSource, level?: number): Promise<Uint8Array>;
+/** Synchronous PNG using the pure stored-deflate path (valid, uncompressed). */
+declare function encodePngSync(source: PixelSource): Uint8Array;
+
+/**
+ * Pure-JS baseline JPEG encoder (4:4:4, no external deps).
+ * Adapted from the classic public-domain JPEG encoder (AAN forward DCT +
+ * standard Huffman tables). Runs identically in Node and the browser and is
+ * the engine the size-budget fitter tunes via the `quality` knob.
+ */
+
+declare function encodeJpeg(source: PixelSource, quality?: number): Uint8Array;
+
+/**
+ * SVG → raster. In the browser we draw the SVG onto a canvas (zero-dep). In
+ * Node, rich SVG text/paths need a real renderer, so we use an OPTIONAL peer
+ * (`sharp`) if it's installed — otherwise we throw a clear, actionable error.
+ * This keeps the package itself zero-dependency while still enabling server-side
+ * raster for teams that opt in.
+ */
+
+interface RasterizeSvgOptions {
+    width?: number;
+    height?: number;
+    /** Painted under the SVG (SVGs are transparent by default). */
+    background?: Color;
+}
+/** Rasterize an SVG string to a Surface (browser: Canvas; Node: optional `sharp`). */
+declare function rasterizeSvg(svg: string, opts?: RasterizeSvgOptions): Promise<Surface>;
+
+/**
+ * Human file-size parsing and formatting. Binary units (1 KB = 1024 bytes) to
+ * match what operating systems and upload limits usually report.
+ */
+/** Parse "200kb", "1.5 MB", "500", 4096 → bytes. Throws on nonsense. */
+declare function parseSize(input: string | number): number;
+/** Format a byte count as a short human string, e.g. 1536 → "1.5 KB". */
+declare function formatBytes(bytes: number, decimals?: number): string;
+
+/**
+ * Isomorphic canvas layer. When a real Canvas is available (browser main thread,
+ * a Worker with OffscreenCanvas), we use it to encode PNG/JPEG/WebP with the
+ * platform's own well-tuned encoders. In Node there is no canvas, so callers
+ * fall back to the pure-JS PNG/JPEG encoders in this package.
+ */
+
+/** Does this runtime expose a usable 2D canvas we can encode from? */
+declare function hasCanvas(): boolean;
+/** True where the platform can actually emit this format via canvas. */
+declare function canvasSupports(format: ImageFormat): Promise<boolean>;
+
+/**
+ * Tiny, dependency-free colour parser → RGBA tuple (0..255 each).
+ * Supports: #rgb, #rgba, #rrggbb, #rrggbbaa, rgb()/rgba(), and "transparent".
+ */
+
+type RGBA = [number, number, number, number];
+declare function parseColor(input: Color): RGBA;
+
+export { type Color, type DrawImageOptions, type EncodeOptions, type EncodeResult, type Fit, type FitOptions, type GradientStop, type ImageFormat, type LinearGradientOptions, type PatternKind, type PatternOptions, type PixelSource, type RGBA, type RadialGradientOptions, type RasterizeSvgOptions, Surface, canvasSupports, encode, encodeJpeg, encodePng, encodePngSync, fit, formatBytes, gradient, hasCanvas, parseColor, parseSize, pattern, radial, rasterizeSvg };