simdra 0.1.0

package/dist/core/microsharp/index.d.ts

@@ -0,0 +1,546 @@
+import type { ResampleKernelName, BlurPrecisionName } from '../../zig/simdra.zig';
+/** Output formats stb_image_write can encode (plus `raw` for decoded pixels). */
+export type ImageFormat = 'png' | 'jpeg' | 'bmp' | 'raw';
+/** Sharp-shaped resampling kernel. simdra implements all eight in
+ *  `effects/SmResampler.zig` so each name maps to its own filter. */
+export type ResizeKernel = ResampleKernelName;
+/** Sharp's `fit` modes. */
+export type ResizeFit = 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+/** Sharp's `position`. Anchor strings + gravity aliases + content-aware
+ *  strategies. `'centre'` and `'center'` are equivalent (sharp parity). */
+export type ResizePosition = 'centre' | 'center' | 'top' | 'right' | 'bottom' | 'left' | 'top right' | 'right top' | 'right bottom' | 'bottom right' | 'bottom left' | 'left bottom' | 'left top' | 'top left' | 'north' | 'east' | 'south' | 'west' | 'northeast' | 'southeast' | 'southwest' | 'northwest' | 'entropy' | 'attention';
+export interface BackgroundColor {
+    r: number;
+    g: number;
+    b: number;
+    alpha?: number;
+}
+export type BackgroundInput = string | BackgroundColor;
+export interface ResizeOptions {
+    width?: number;
+    height?: number;
+    fit?: ResizeFit;
+    position?: ResizePosition;
+    background?: BackgroundInput;
+    kernel?: ResizeKernel;
+    withoutEnlargement?: boolean;
+    withoutReduction?: boolean;
+    /** Accepted for sharp parity but has no effect — simdra has no
+     *  shrink-on-load decoder integration. */
+    fastShrinkOnLoad?: boolean;
+}
+export type ExtendWithMode = 'background' | 'copy' | 'repeat' | 'mirror';
+/** Sharp's extend() argument: per-edge counts + fill mode + background. */
+export interface ExtendOptions {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    extendWith?: ExtendWithMode;
+    background?: BackgroundInput;
+}
+export interface ExtractRegion {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface TrimOptions {
+    background?: BackgroundInput;
+    /** Allowed per-channel difference from `background`; default 10. */
+    threshold?: number;
+    /** Accepted for sharp parity — silently ignored (libvips-specific
+     *  hint that doesn't map to our threshold metric). */
+    lineArt?: boolean;
+}
+/** Sharp's composite blend mode strings (libvips/cairo names). Mapped
+ *  internally to simdra's HTML5-shaped enum. `dest` is identity (no
+ *  draw). `clear` and `saturate` throw — simdra has no equivalent. */
+export type CompositeBlend = 'clear' | 'source' | 'over' | 'in' | 'out' | 'atop' | 'dest' | 'dest-over' | 'dest-in' | 'dest-out' | 'dest-atop' | 'xor' | 'add' | 'saturate' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'colour-dodge' | 'color-dodge' | 'colour-burn' | 'color-burn' | 'hard-light' | 'soft-light' | 'difference' | 'exclusion';
+/** Channel index or sharp-style channel name. */
+export type ChannelSelector = 0 | 1 | 2 | 3 | 'red' | 'green' | 'blue' | 'alpha';
+/** Bitwise band-boolean op for `bandbool()`. `eor` is libvips's name
+ *  for XOR; both `xor` and `eor` are accepted at the JS layer. */
+export type BandBoolOp = 'and' | 'or' | 'eor' | 'xor';
+/** Sharp's gravity strings for composite placement. Same set as
+ *  `ResizePosition` minus the content-aware strategies. */
+export type CompositeGravity = 'centre' | 'center' | 'top' | 'right' | 'bottom' | 'left' | 'top right' | 'right top' | 'top left' | 'left top' | 'bottom right' | 'right bottom' | 'bottom left' | 'left bottom' | 'north' | 'east' | 'south' | 'west' | 'northeast' | 'southeast' | 'southwest' | 'northwest';
+/** Sharp-style raw-pixel descriptor — sibling of `input`, not nested.
+ *  When set, `input` is treated as raw RGBA bytes of the given dims. */
+export interface CompositeRawDescriptor {
+    width: number;
+    height: number;
+    /** Currently must be `4` (RGBA). 1-channel grey, 2-channel grey+alpha,
+     *  and 3-channel RGB inputs are rejected — the blend kernels operate
+     *  on RGBA8 only. */
+    channels: number;
+}
+/** "Create" input for a composite overlay — a flat-colour rectangle
+ *  built on the fly. Mirrors sharp's `{ input: { create: ... } }`. */
+export interface CompositeCreateInput {
+    width: number;
+    height: number;
+    channels: 3 | 4;
+    background: BackgroundInput;
+}
+export type CompositeOverlayInput = Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array> | Response | {
+    create: CompositeCreateInput;
+};
+export interface CompositeImage {
+    /** Encoded image bytes, a stream/blob/response producing them, or a
+     *  `{ create }` flat-colour rectangle. To pass raw RGBA pixels, set
+     *  `input` to the byte buffer AND provide a sibling `raw: {width,
+     *  height, channels}` (sharp parity). */
+    input: CompositeOverlayInput;
+    /** Sharp-style raw-pixel descriptor — sibling of `input`. When set,
+     *  `input` is interpreted as RGBA bytes of the given dimensions
+     *  rather than as encoded image bytes. */
+    raw?: CompositeRawDescriptor;
+    /** Blend mode (libvips/cairo name); default `'over'` (source-over). */
+    blend?: CompositeBlend;
+    /** Anchor for placement when `top`/`left` aren't given. Default
+     *  `'centre'`. Ignored when both `top` and `left` are provided. */
+    gravity?: CompositeGravity;
+    /** Explicit pixel offset from the top edge. Pairs with `left` to
+     *  override `gravity`. */
+    top?: number;
+    /** Explicit pixel offset from the left edge. Pairs with `top` to
+     *  override `gravity`. */
+    left?: number;
+    /** Tile the overlay across the base bitmap. */
+    tile?: boolean;
+    /** Sharp's premultiplied flag — accepted for compatibility but not
+     *  applied: simdra always uses non-premultiplied bytes at the
+     *  bitmap layer. The blend math is done in-channel by the canvas
+     *  blit kernels, which is the libvips-equivalent semantic. */
+    premultiplied?: boolean;
+    /** Accepted but ignored — simdra doesn't parse EXIF orientation. */
+    autoOrient?: boolean;
+    /** Accepted but ignored — simdra doesn't decode multi-frame inputs
+     *  in the composite path. */
+    animated?: boolean;
+    /** Accepted but ignored — DPI is meaningful only for vector inputs
+     *  (SVG/PDF) we don't decode. */
+    density?: number;
+}
+/** Per-call PNG options scoped to what stb_image_write exposes. */
+export interface PngOptions {
+    /** stb's compression level (0 = fastest/largest, 9 = slowest/smallest).
+     *  Wraps stb's process-global `stbi_write_png_compression_level` under
+     *  a mutex on the Zig side, so concurrent encodes from different
+     *  pthreads (native build) don't race on the level. */
+    compressionLevel?: number;
+}
+/** Per-call JPEG options scoped to what stb_image_write exposes. */
+export interface JpegOptions {
+    /** HTML5-style 0.0–1.0 quality. Mapped to stb's 1–100 scale internally. */
+    quality?: number;
+}
+/** Source-format names returned from `metadata().format` (signature sniff). */
+export type ImageFormatName = 'png' | 'jpeg' | 'bmp' | 'gif' | 'unknown';
+/** Output info attached to `toBuffer({ resolveWithObject: true })`. Shape
+ *  is intentionally narrower than sharp's — only fields that have an
+ *  honest answer with stb_image_write's encoders are populated.
+ *  `premultiplied`, crop offsets, attention focal points, animation
+ *  metadata, and `textAutofitDpi` are libvips features and are not set. */
+export interface OutputInfo {
+    format: ImageFormat;
+    size: number;
+    width: number;
+    height: number;
+    /** PNG = 4 (RGBA preserved), JPEG = 3 (alpha dropped — JPEG can't store
+     *  alpha), BMP = 4 (32-bit V4 with alpha mask), raw = 4 (RGBA pixels). */
+    channels: number;
+}
+/** Options for the `toBuffer()` terminal. */
+export interface ToBufferOptions {
+    /** When `true`, the terminal resolves with `{ data, info }` instead of
+     *  just `data`. Mirrors sharp's option of the same name. */
+    resolveWithObject?: boolean;
+}
+/**
+ * Header-only metadata, mirroring sharp's `metadata()` semantics — populated
+ * from stb_image's `stbi_info_from_memory` + `stbi_is_16_bit_from_memory`
+ * fast path with no pixel decode and no allocation.
+ *
+ * The fields are limited to what stb_image's public API actually exposes;
+ * sharp's libvips-backed extras (ICC, EXIF, density, orientation, pages,
+ * isProgressive, …) are not surfaced because the decoder doesn't read them.
+ */
+export interface Metadata {
+    /** Container detected by signature sniff. `'unknown'` if no match. */
+    format: ImageFormatName;
+    /** Pixel width as stored in the file header. */
+    width: number;
+    /** Pixel height as stored in the file header. */
+    height: number;
+    /** Source channel count: 1 grey, 2 grey+alpha, 3 RGB, 4 RGBA. */
+    channels: number;
+    /** True iff `channels === 2 || channels === 4`. */
+    hasAlpha: boolean;
+    /** Bits per channel sample (8 or 16) per stb_image. */
+    bitsPerSample: number;
+    /** Total input size in bytes (sharp parity for `Buffer` / stream input). */
+    size: number;
+}
+export type MicroSharpInput = Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array> | Response;
+/** Sharp's affine `interpolator` option. Mapped to simdra's two
+ *  bitmap-direct samplers (nearest / bilinear). The libvips-only
+ *  kernels (`nohalo`, `lbb`, `vsqbs`) collapse to `bilinear` — they
+ *  exist in libvips for very-precise resamplers we don't ship. */
+export type AffineInterpolator = 'nearest' | 'bilinear' | 'bicubic' | 'nohalo' | 'lbb' | 'vsqbs';
+export interface RotateOptions {
+    background?: BackgroundInput;
+}
+/** Sharp's `blur(opts)` argument set. Bare `sigma` number is also
+ *  accepted in the method signature. `precision` defaults to
+ *  `'integer'` (matches sharp). */
+export interface BlurOptions {
+    sigma?: number;
+    precision?: BlurPrecisionName;
+    minAmplitude?: number;
+}
+/** Sharp's `sharpen(opts)` argument set. */
+export interface SharpenOptions {
+    sigma?: number;
+    m1?: number;
+    m2?: number;
+    x1?: number;
+    y2?: number;
+    y3?: number;
+}
+/** Sharp's `convolve(kernel)` argument. `kernel` is row-major and must
+ *  have `width * height` entries. `scale` defaults to the sum of
+ *  kernel values; `offset` defaults to 0. */
+export interface ConvolveKernel {
+    width: number;
+    height: number;
+    kernel: ArrayLike<number>;
+    scale?: number;
+    offset?: number;
+}
+export interface NegateOptions {
+    /** Whether to negate the alpha channel. Sharp default: `true`. */
+    alpha?: boolean;
+}
+export interface ThresholdOptions {
+    /** Convert to single-channel greyscale before thresholding (sharp
+     *  default: `true`). When `false`, threshold is applied per RGB
+     *  channel. */
+    greyscale?: boolean;
+    /** Alternative spelling for `greyscale` (sharp parity). */
+    grayscale?: boolean;
+}
+export interface FlattenOptions {
+    /** Background colour to merge alpha against. Sharp default `#000000`. */
+    background?: BackgroundInput;
+}
+export type BooleanOperator = 'and' | 'or' | 'eor';
+export interface BooleanOptions {
+    /** Sharp's raw-pixel descriptor — sibling of `operand`. When set,
+     *  the operand bytes are interpreted as RGBA / RGB / grey of the
+     *  given dimensions rather than encoded image bytes. */
+    raw?: CompositeRawDescriptor;
+}
+export interface NormaliseOptions {
+    /** Percentile below which luma is clipped to 0. Sharp default 1. */
+    lower?: number;
+    /** Percentile above which luma is clipped to 255. Sharp default 99. */
+    upper?: number;
+}
+export interface ClaheOptions {
+    /** Tile width in pixels. Required. */
+    width: number;
+    /** Tile height in pixels. Required. */
+    height: number;
+    /** Contrast-clip slope. Sharp default 3; 0 disables clipping. */
+    maxSlope?: number;
+}
+export interface ModulateOptions {
+    /** Multiplier on V (HSV value). Default 1. */
+    brightness?: number;
+    /** Multiplier on S (HSV saturation). Default 1. */
+    saturation?: number;
+    /** Hue rotation in degrees. Default 0. */
+    hue?: number;
+    /** Additive offset on V (luminance). Default 0. */
+    lightness?: number;
+}
+/** Sharp's `recomb(inputMatrix)` matrix shape: 3×3 (RGB-only) or 4×4
+ *  (full RGBA). Accepts row-major flat lists too. */
+export type RecombMatrix = readonly [
+    readonly [number, number, number],
+    readonly [number, number, number],
+    readonly [number, number, number]
+] | readonly [
+    readonly [number, number, number, number],
+    readonly [number, number, number, number],
+    readonly [number, number, number, number],
+    readonly [number, number, number, number]
+] | ArrayLike<number>;
+export interface AffineOptions {
+    background?: BackgroundInput;
+    idx?: number;
+    idy?: number;
+    odx?: number;
+    ody?: number;
+    interpolator?: AffineInterpolator;
+}
+/** Sharp's `affine(matrix, ...)` — matrix is a length-4 array
+ *  `[a, b, c, d]` (row-major: `[[a, b], [c, d]]`) or a 2×2 nested
+ *  form `[[a, b], [c, d]]`. */
+export type AffineMatrix = readonly [number, number, number, number] | readonly [readonly [number, number], readonly [number, number]];
+export declare class MicroSharpPipeline {
+    private readonly input;
+    private materialized;
+    private outputFormat;
+    private jpegQuality;
+    private pngCompressionLevel;
+    private readonly ops;
+    /** Recorded `pipelineColourspace`. `'b-w'`/`'grey16'` injects a leading
+     *  greyscale at apply time; other recognised values are no-ops on our
+     *  RGBA8 sRGB pipeline (documented in COMPATIBILITY.md). */
+    private pipelineColourspaceSetting;
+    /** Recorded `toColourspace`. Same semantics as the pipeline knob, but
+     *  the greyscale (when triggered) runs *after* all queued ops. */
+    private toColourspaceSetting;
+    constructor(input: MicroSharpInput);
+    /**
+     * Sharp-shaped resize. Three call forms:
+     *   .resize(width, height, opts?)
+     *   .resize(width, opts?) — auto-scales height from source aspect
+     *   .resize({ width, height, ...opts })
+     *
+     * Per sharp: only one resize op survives per pipeline; subsequent
+     * `.resize()` calls replace the recorded op rather than appending.
+     */
+    resize(widthOrOpts?: number | (ResizeOptions & {
+        width?: number;
+        height?: number;
+    }) | null, heightOrOpts?: number | ResizeOptions | null, opts?: ResizeOptions): this;
+    /** Pad / extrude the image. Sharp accepts a number (all four edges)
+     *  or a per-edge object with optional `extendWith` and `background`. */
+    extend(opts: number | ExtendOptions): this;
+    /** Crop a sub-rectangle. Validated against the *current* bitmap at
+     *  apply time, not at queue time. */
+    extract(region: ExtractRegion): this;
+    /** Trim background-coloured edges. Default background = top-left
+     *  pixel of the working bitmap (sharp parity); default threshold = 10. */
+    trim(opts?: TrimOptions): this;
+    /** Composite one or more overlays onto the working bitmap. Each
+     *  entry's `input` is materialized at apply time (so streams, blobs,
+     *  and responses work for overlays just like they do for the
+     *  pipeline's primary input). Overlays are drawn in array order;
+     *  later entries can blend over earlier ones. */
+    composite(images: CompositeImage[]): this;
+    /** Strip alpha — sets α=255 on every pixel. Sharp's docs describe
+     *  this as "the output image is a 3 channel image without an alpha
+     *  channel"; in microsharp the buffer remains 4-channel for
+     *  pipeline-shape invariance, but the result is visibly identical
+     *  (all pixels fully opaque). */
+    removeAlpha(): this;
+    /** Sharp's `ensureAlpha([alpha])`. Microsharp bitmaps always carry
+     *  an alpha channel, so this is a no-op without an argument. With
+     *  an explicit `alpha` (0..1) the channel is set to that constant
+     *  level — useful right after `removeAlpha` to set a non-opaque
+     *  uniform alpha, or to force a known transparency level on a
+     *  decoded source. */
+    ensureAlpha(alpha?: number): this;
+    /** Extract a single channel as a greyscale image. `channel` accepts
+     *  the integer index 0/1/2/3 or sharp's string names
+     *  'red'/'green'/'blue'/'alpha'. The result is RGB = chosen channel,
+     *  α = 255. */
+    extractChannel(channel: ChannelSelector): this;
+    /** Per-pixel bitwise op across R, G, B channels — produces a
+     *  greyscale image where each pixel is `(R op G op B)` broadcast.
+     *  Accepts sharp's `'and'` / `'or'` / `'eor'` (libvips name for
+     *  XOR); plain `'xor'` is also accepted. */
+    bandbool(op: BandBoolOp): this;
+    /** Sharp's `tint(colour)` — recolour using the given RGB tint while
+     *  preserving the per-pixel luminance pattern. Alpha is unchanged
+     *  (sharp spec). The colour can be a CSS string or
+     *  `{ r, g, b, alpha? }` object; the alpha component is parsed for
+     *  compatibility but ignored — the tint operation is RGB-only. */
+    tint(colour: BackgroundInput): this;
+    /** Sharp's `rotate([angle], [opts])`. With no arguments this is the
+     *  back-compat alias for `autoOrient()`. With a finite angle it
+     *  rotates by that many degrees clockwise, padding with `background`
+     *  (default opaque black). Multiples of 90° are byte-exact (lossless
+     *  index permutation); other angles sample through bilinear
+     *  interpolation against the source-bbox AABB. Sharp parity:
+     *  multi-page input is not supported — simdra decodes one frame. */
+    rotate(angle?: number, opts?: RotateOptions): this;
+    /** Sharp's `autoOrient()` — read the EXIF Orientation tag from the
+     *  input bytes and apply the corresponding rotation / mirror. simdra
+     *  parses Orientation only (no full EXIF library); the tag is read
+     *  by `SmBitmap.peekOrientation` against the materialised input
+     *  bytes at apply time. Missing / malformed EXIF → no-op. */
+    autoOrient(): this;
+    /** Sharp's `flip([on])` — mirror vertically (top↔bottom). */
+    flip(on?: boolean): this;
+    /** Sharp's `flop([on])` — mirror horizontally (left↔right). */
+    flop(on?: boolean): this;
+    /** Sharp's `affine(matrix, [opts])`. `matrix` is `[a, b, c, d]`
+     *  (`[[a, b], [c, d]]`) — the linear part of `F(x, y) = M·(x+idx,
+     *  y+idy) + (odx, ody)`. Output dims = forward bbox of the input
+     *  rectangle; the gap is padded with `background` (default opaque
+     *  black). `interpolator` accepts sharp/libvips kernel names; the
+     *  three high-precision kernels libvips ships (`nohalo`/`lbb`/
+     *  `vsqbs`) collapse to `bilinear` here — see COMPATIBILITY.md. */
+    affine(matrix: AffineMatrix, opts?: AffineOptions): this;
+    /** Sharp's `blur([opts])`.
+     *   - No args / `true`: fast 3×3 box blur.
+     *   - `false`: no-op (records nothing).
+     *   - bare `sigma` number: Gaussian blur with the chosen sigma.
+     *   - `{ sigma, precision, minAmplitude }`: same with explicit
+     *     working-precision and kernel-amplitude cutoff.
+     *   `precision` defaults to `'integer'`; `minAmplitude` to `0.2`
+     *   (sharp's defaults). Sigma must be in [0.3, 1000]. */
+    blur(opts?: number | boolean | BlurOptions): this;
+    /** Sharp's `sharpen([opts], [flat], [jagged])`.
+     *   - No args: fast 3×3 unsharp kernel `[[0,-1,0],[-1,5,-1],[0,-1,0]]`.
+     *   - `{ sigma, m1, m2, x1, y2, y3 }`: libvips USM with the flat /
+     *     jagged piecewise gain. Per-channel in 8-bit sRGB (sharp's
+     *     LAB-L pipeline isn't available — documented 🟡 in COMPATIBILITY).
+     *   - Deprecated 2-positional form `sharpen(sigma, flat, jagged)`:
+     *     surfaces with `flat = m1`, `jagged = m2`. Sharp parity. */
+    sharpen(opts?: number | SharpenOptions, flat?: number, jagged?: number): this;
+    /** Sharp's `median([size])`. Square `size × size` window per RGB
+     *  channel; α preserved. `size` defaults to 3 and must be odd. */
+    median(size?: number): this;
+    /** Sharp's `dilate([width])`. Foreground expansion by a separable
+     *  `(2·width+1)`-square max-window. `width` defaults to 1. */
+    dilate(width?: number): this;
+    /** Sharp's `erode([width])`. Foreground shrinking — same shape as
+     *  `dilate`, opposite kernel direction. */
+    erode(width?: number): this;
+    /** Sharp's `convolve(kernel)`. `kernel.kernel` length must equal
+     *  `width · height`; both dims must be odd. `scale` defaults to the
+     *  sum of kernel values; `offset` defaults to 0. Edge mode is
+     *  clamp (libvips's default). */
+    convolve(spec: ConvolveKernel): this;
+    /** Sharp's `gamma([gamma], [gammaOut])`. Applies a single LUT
+     *  `(in/255)^(gIn/gOut)·255` per RGB channel; α preserved. Sharp's
+     *  pre-/post-resize coupling collapses to a single pass without an
+     *  intervening resize — documented 🟡 in COMPATIBILITY.md. Both
+     *  values must be in [1.0, 3.0]; `gOut` defaults to `gIn`. */
+    gamma(g?: number, gOut?: number): this;
+    /** Sharp's `negate([opts])`. RGB inverted; α negated when
+     *  `opts.alpha !== false` (sharp default `true`). */
+    negate(opts?: NegateOptions): this;
+    /** Sharp's `linear([a], [b])`. Per-channel `a·C + b` with output
+     *  clipped to [0, 255]. Both arguments accept a single number (RGB
+     *  broadcast, alpha untouched), a length-3 array (RGB), or a
+     *  length-4 array (RGBA). Defaults: `a=1`, `b=0` per channel. */
+    linear(a?: number | ArrayLike<number>, b?: number | ArrayLike<number>): this;
+    /** Sharp's `threshold([t], [opts])`. `t` defaults to 128; sharp
+     *  accepts 0..255. With `greyscale=true` (default), Rec.601 luma is
+     *  computed first and broadcast. */
+    threshold(t?: number, opts?: ThresholdOptions): this;
+    /** Sharp's `recomb(matrix)`. 3×3 (RGB only, α preserved) or 4×4
+     *  (full RGBA) row-major colour matrix. Accepts nested form
+     *  `[[a,b,c],[d,e,f],[g,h,i]]` or flat `[a,b,c,d,e,f,g,h,i]`. */
+    recomb(matrix: RecombMatrix): this;
+    /** Sharp's `flatten([opts])`. Alpha-blend onto an opaque background
+     *  and drop alpha. Buffer remains 4-channel for pipeline-shape
+     *  invariance (α=255 across the result). */
+    flatten(opts?: FlattenOptions): this;
+    /** Sharp's `unflatten()`. Every pixel where `R=G=B=255` becomes
+     *  fully transparent (α=0); other pixels are unchanged. */
+    unflatten(): this;
+    /** Sharp's `boolean(operand, operator, [opts])`. Per-pixel bitwise
+     *  `and` / `or` / `eor` (libvips name for XOR) across all four
+     *  RGBA bands between this bitmap and `operand`. The operand is
+     *  materialised at apply time (encoded image bytes by default;
+     *  `opts.raw` for pre-decoded pixels — same shape as `joinChannel`). */
+    boolean(operand: CompositeOverlayInput, operator: BooleanOperator | 'xor', opts?: BooleanOptions): this;
+    /** Sharp's `normalise([opts])`. Stretch the luma percentile range
+     *  `[lower, upper]` to `[0, 255]` and broadcast the same affine map
+     *  to all RGB channels. α preserved. Defaults `lower: 1`, `upper: 99`. */
+    normalise(opts?: NormaliseOptions): this;
+    /** Alternative spelling of `normalise()` (sharp parity). */
+    normalize(opts?: NormaliseOptions): this;
+    /** Sharp's `clahe({ width, height, maxSlope? })`. Tile-based local
+     *  histogram equalisation with bilinear interpolation between tile
+     *  centres. `maxSlope` defaults to 3 (sharp parity); 0 disables the
+     *  contrast clip and reduces to plain AHE. */
+    clahe(opts: ClaheOptions): this;
+    /** Sharp's `modulate({ brightness, saturation, hue, lightness })`.
+     *  Applied in HSV space (sharp uses LCh; documented 🟡 in
+     *  COMPATIBILITY.md). All four arguments are optional. α preserved. */
+    modulate(opts?: ModulateOptions): this;
+    /** Sharp's `greyscale([on])`. `on` defaults to `true`; passing `false`
+     *  records nothing (sharp parity). Computes Rec.601 luma in 8-bit
+     *  sRGB space — for a true linear-space conversion sharp recommends
+     *  chaining a future `gamma()` op. */
+    greyscale(on?: boolean): this;
+    /** Alternative spelling of `greyscale()` (sharp parity). */
+    grayscale(on?: boolean): this;
+    /** Sharp's `pipelineColourspace([cs])`. Records the requested input
+     *  colourspace; `b-w` / `grey16` triggers a leading greyscale so the
+     *  rest of the pipeline runs on luma values. Other recognised libvips
+     *  colourspace names are accepted as no-ops because simdra has no
+     *  16-bit / LAB / CMYK pipeline (documented in COMPATIBILITY.md).
+     *  Unrecognised strings throw `RangeError`. */
+    pipelineColourspace(cs?: string): this;
+    /** Alternative spelling of `pipelineColourspace()` (sharp parity). */
+    pipelineColorspace(cs?: string): this;
+    /** Sharp's `toColourspace([cs])`. Records the requested output
+     *  colourspace; `b-w` / `grey16` triggers a tail greyscale (buffer
+     *  stays 4-channel for pipeline-shape invariance). All other
+     *  recognised libvips colourspace names are 8-bit sRGB passthrough
+     *  no-ops. Unrecognised strings throw `RangeError`. */
+    toColourspace(cs?: string): this;
+    /** Alternative spelling of `toColourspace()` (sharp parity). */
+    toColorspace(cs?: string): this;
+    /** Sharp's `joinChannel(image, options?)` — replace this bitmap's
+     *  alpha channel with Rec.601 luma of the joined image's RGB.
+     *
+     *  Microsharp's always-RGBA model can't grow beyond 4 channels, so
+     *  we handle the common case (single mask image → new alpha) rather
+     *  than libvips's full N-band append. Multi-image arrays and
+     *  multi-band joins beyond RGBA aren't supported: pass a single
+     *  Buffer/typed-array, or a `{ raw: { width, height, channels: 1|3|4 } }`
+     *  options descriptor for pre-decoded mask pixels.
+     *
+     *  Greyscale (1-channel) and grey+alpha (1- or 4-channel with
+     *  R=G=B) masks round-trip exactly: luma collapses to R. RGB masks
+     *  are converted via `0.299·R + 0.587·G + 0.114·B`. */
+    joinChannel(image: CompositeOverlayInput | CompositeOverlayInput[], options?: {
+        raw?: {
+            width: number;
+            height: number;
+            channels: number;
+        };
+    }): this;
+    png(opts?: PngOptions): this;
+    /** `quality` is the HTML5 0.0–1.0 range; default 0.92 (Chromium default).
+     *  Accepts either a bare number or sharp's `{ quality }` object form. */
+    jpeg(opts?: number | JpegOptions): this;
+    /** 32-bit BMP V4 (stb's `comp=4` path; preserves alpha via BI_BITFIELDS). */
+    bmp(): this;
+    /** Raw RGBA pixel data. Channel ordering is RGBA, top-to-bottom, no
+     *  padding (forced 4-channel by the stb_image decode path). */
+    raw(): this;
+    /** Force output format. Sharp accepts an object with an `id` attribute
+     *  for libvips-specific format options; we accept the string only. */
+    toFormat(format: ImageFormat): this;
+    toBuffer(opts: ToBufferOptions & {
+        resolveWithObject: true;
+    }): Promise<{
+        data: Uint8Array;
+        info: OutputInfo;
+    }>;
+    toBuffer(opts?: ToBufferOptions): Promise<Uint8Array>;
+    private encodeBitmap;
+    metadata(): Promise<Metadata>;
+    private getInput;
+    /** Run each queued op in order. Each op consumes the previous bitmap
+     *  and returns a fresh one; the consumed bitmap is released
+     *  immediately to keep peak memory bounded. Async because
+     *  `composite` may need to await overlay materialization (decode
+     *  bytes, drain a stream, etc.). */
+    private applyOps;
+    private runOp;
+}
+export declare function microsharp(input: MicroSharpInput): MicroSharpPipeline;