@flighthq/surface 0.1.0

package/dist/surfaceConvolution.js

@@ -0,0 +1,103 @@
+/**
+ * Applies a convolution kernel to `source` and writes into `out`.
+ * `out` must be at least `source.width * source.height * 4` bytes.
+ *
+ * `out` must not alias `source.surface.data` — convolution reads neighboring
+ * pixels during kernel evaluation; overlapping source and destination produces
+ * undefined results.
+ *
+ * Edge modes:
+ *   - `'clamp'` (default): repeat the nearest edge pixel
+ *   - `'transparent'`: treat out-of-bounds samples as transparent black
+ *   - `'wrap'`: tile the surface toroidally
+ *   - `'mirror'`: reflect the image at boundaries
+ */
+export function convolveSurface(out, source, options) {
+    const { matrix, matrixX, matrixY } = options;
+    if (matrixX <= 0 || matrixY <= 0)
+        throw new Error('Convolution filter matrix dimensions must be positive');
+    if (matrix.length < matrixX * matrixY)
+        throw new Error('Convolution filter matrix does not match its dimensions');
+    const rawDivisor = options.divisor ?? getConvolutionDivisor(matrix, matrixX * matrixY);
+    const divisor = rawDivisor === 0 ? 1 : rawDivisor;
+    const bias = options.bias ?? 0;
+    const edge = options.edge ?? 'clamp';
+    const preserveAlpha = options.preserveAlpha ?? true;
+    const offsetX = Math.floor(matrixX / 2);
+    const offsetY = Math.floor(matrixY / 2);
+    const surfaceWidth = source.surface.width;
+    const surfaceHeight = source.surface.height;
+    const data = source.surface.data;
+    for (let py = 0; py < source.height; py++) {
+        for (let px = 0; px < source.width; px++) {
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            for (let ky = 0; ky < matrixY; ky++) {
+                const rawSampleY = source.y + py + ky - offsetY;
+                const weight_row_start = ky * matrixX;
+                for (let kx = 0; kx < matrixX; kx++) {
+                    const rawSampleX = source.x + px + kx - offsetX;
+                    const weight = matrix[weight_row_start + kx];
+                    let sampleX;
+                    let sampleY;
+                    if (rawSampleY < 0 || rawSampleY >= surfaceHeight || rawSampleX < 0 || rawSampleX >= surfaceWidth) {
+                        if (edge === 'transparent') {
+                            continue;
+                        }
+                        else if (edge === 'wrap') {
+                            sampleX = ((rawSampleX % surfaceWidth) + surfaceWidth) % surfaceWidth;
+                            sampleY = ((rawSampleY % surfaceHeight) + surfaceHeight) % surfaceHeight;
+                        }
+                        else if (edge === 'mirror') {
+                            sampleX = resolveConvolutionMirror(rawSampleX, surfaceWidth);
+                            sampleY = resolveConvolutionMirror(rawSampleY, surfaceHeight);
+                        }
+                        else {
+                            sampleX = rawSampleX < 0 ? 0 : rawSampleX >= surfaceWidth ? surfaceWidth - 1 : rawSampleX;
+                            sampleY = rawSampleY < 0 ? 0 : rawSampleY >= surfaceHeight ? surfaceHeight - 1 : rawSampleY;
+                        }
+                    }
+                    else {
+                        sampleX = rawSampleX;
+                        sampleY = rawSampleY;
+                    }
+                    const i = (sampleY * surfaceWidth + sampleX) * 4;
+                    r += data[i] * weight;
+                    g += data[i + 1] * weight;
+                    b += data[i + 2] * weight;
+                    a += data[i + 3] * weight;
+                }
+            }
+            const di = (py * source.width + px) * 4;
+            out[di] = clampByte(r / divisor + bias);
+            out[di + 1] = clampByte(g / divisor + bias);
+            out[di + 2] = clampByte(b / divisor + bias);
+            if (preserveAlpha) {
+                const cy = Math.max(0, Math.min(surfaceHeight - 1, source.y + py));
+                const cx = Math.max(0, Math.min(surfaceWidth - 1, source.x + px));
+                out[di + 3] = data[(cy * surfaceWidth + cx) * 4 + 3];
+            }
+            else {
+                out[di + 3] = clampByte(a / divisor + bias);
+            }
+        }
+    }
+}
+function clampByte(value) {
+    return Math.max(0, Math.min(255, Math.round(value)));
+}
+function getConvolutionDivisor(matrix, length) {
+    let sum = 0;
+    for (let i = 0; i < length; i++) {
+        sum += matrix[i];
+    }
+    return sum === 0 ? 1 : sum;
+}
+function resolveConvolutionMirror(v, size) {
+    const period = 2 * size;
+    const wrapped = ((v % period) + period) % period;
+    return wrapped < size ? wrapped : period - 1 - wrapped;
+}
+//# sourceMappingURL=surfaceConvolution.js.map

package/dist/surfaceConvolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceConvolution.js","sourceRoot":"","sources":["../src/surfaceConvolution.ts"],"names":[],"mappings":"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"}

package/dist/surfaceCopy.d.ts

@@ -0,0 +1,23 @@
+import type { SurfaceRegion } from '@flighthq/types';
+import type { ImageChannel } from './surfaceImageChannel';
+/**
+ * Copies one channel of `source` into a channel of `dest`. The copied size is
+ * the overlap of the two regions; pixels outside either surface are skipped.
+ *
+ * Safe to pass the same surface in `dest` and `source` as long as `destChannel`
+ * and `sourceChannel` differ (each pixel writes a different byte than it reads).
+ * Copying a channel to itself is always a no-op regardless of aliasing.
+ */
+export declare function copySurfaceChannel(dest: Readonly<SurfaceRegion>, destChannel: ImageChannel, source: Readonly<SurfaceRegion>, sourceChannel: ImageChannel): void;
+/**
+ * Copies `source` into `dest`. The copied size is the overlap of the two
+ * regions; pixels outside either surface are skipped. When `composite` is
+ * true, `source` is alpha-composited (Porter-Duff source-over) over `dest`
+ * instead of overwriting it.
+ *
+ * Safe to pass the same surface in `dest` and `source` when the regions do not
+ * overlap. Overlapping regions produce undefined results because pixels are
+ * written before all source reads are complete.
+ */
+export declare function copySurfacePixels(dest: Readonly<SurfaceRegion>, source: Readonly<SurfaceRegion>, composite?: boolean): void;
+//# sourceMappingURL=surfaceCopy.d.ts.map

package/dist/surfaceCopy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceCopy.d.ts","sourceRoot":"","sources":["../src/surfaceCopy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC7B,WAAW,EAAE,YAAY,EACzB,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC/B,aAAa,EAAE,YAAY,GAC1B,IAAI,CAiBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC7B,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC/B,SAAS,GAAE,OAAe,GACzB,IAAI,CAkCN"}

package/dist/surfaceCopy.js

@@ -0,0 +1,78 @@
+import { invalidateImageResource } from '@flighthq/image';
+/**
+ * Copies one channel of `source` into a channel of `dest`. The copied size is
+ * the overlap of the two regions; pixels outside either surface are skipped.
+ *
+ * Safe to pass the same surface in `dest` and `source` as long as `destChannel`
+ * and `sourceChannel` differ (each pixel writes a different byte than it reads).
+ * Copying a channel to itself is always a no-op regardless of aliasing.
+ */
+export function copySurfaceChannel(dest, destChannel, source, sourceChannel) {
+    const w = Math.min(dest.width, source.width);
+    const h = Math.min(dest.height, source.height);
+    for (let py = 0; py < h; py++) {
+        const sy = source.y + py;
+        const dy = dest.y + py;
+        if (sy < 0 || sy >= source.surface.height || dy < 0 || dy >= dest.surface.height)
+            continue;
+        for (let px = 0; px < w; px++) {
+            const sx = source.x + px;
+            const dx = dest.x + px;
+            if (sx < 0 || sx >= source.surface.width || dx < 0 || dx >= dest.surface.width)
+                continue;
+            const si = (sy * source.surface.width + sx) * 4;
+            const di = (dy * dest.surface.width + dx) * 4;
+            dest.surface.data[di + destChannel] = source.surface.data[si + sourceChannel];
+        }
+    }
+    invalidateImageResource(dest.surface);
+}
+/**
+ * Copies `source` into `dest`. The copied size is the overlap of the two
+ * regions; pixels outside either surface are skipped. When `composite` is
+ * true, `source` is alpha-composited (Porter-Duff source-over) over `dest`
+ * instead of overwriting it.
+ *
+ * Safe to pass the same surface in `dest` and `source` when the regions do not
+ * overlap. Overlapping regions produce undefined results because pixels are
+ * written before all source reads are complete.
+ */
+export function copySurfacePixels(dest, source, composite = false) {
+    const w = Math.min(dest.width, source.width);
+    const h = Math.min(dest.height, source.height);
+    const sd = source.surface.data;
+    const dd = dest.surface.data;
+    for (let py = 0; py < h; py++) {
+        const sy = source.y + py;
+        const dy = dest.y + py;
+        if (sy < 0 || sy >= source.surface.height || dy < 0 || dy >= dest.surface.height)
+            continue;
+        for (let px = 0; px < w; px++) {
+            const sx = source.x + px;
+            const dx = dest.x + px;
+            if (sx < 0 || sx >= source.surface.width || dx < 0 || dx >= dest.surface.width)
+                continue;
+            const si = (sy * source.surface.width + sx) * 4;
+            const di = (dy * dest.surface.width + dx) * 4;
+            if (composite) {
+                const srcA = sd[si + 3] / 255;
+                const dstA = dd[di + 3] / 255;
+                const outA = srcA + dstA * (1 - srcA);
+                if (outA > 0) {
+                    dd[di] = Math.round((sd[si] * srcA + dd[di] * dstA * (1 - srcA)) / outA);
+                    dd[di + 1] = Math.round((sd[si + 1] * srcA + dd[di + 1] * dstA * (1 - srcA)) / outA);
+                    dd[di + 2] = Math.round((sd[si + 2] * srcA + dd[di + 2] * dstA * (1 - srcA)) / outA);
+                    dd[di + 3] = Math.round(outA * 255);
+                }
+            }
+            else {
+                dd[di] = sd[si];
+                dd[di + 1] = sd[si + 1];
+                dd[di + 2] = sd[si + 2];
+                dd[di + 3] = sd[si + 3];
+            }
+        }
+    }
+    invalidateImageResource(dest.surface);
+}
+//# sourceMappingURL=surfaceCopy.js.map

package/dist/surfaceCopy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceCopy.js","sourceRoot":"","sources":["../src/surfaceCopy.ts"],"names":[],"mappings":"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"}

package/dist/surfaceCoverage.d.ts

@@ -0,0 +1,11 @@
+import type { Surface } from '@flighthq/types';
+/**
+ * Returns the fraction of pixels (0..1) that differ from `backgroundColor` by more than
+ * `channelTolerance` on at least one RGBA channel. This is the "did anything render" signal: a blank
+ * frame (the whole surface still the clear colour, or fully transparent) returns ~0; a populated
+ * frame returns a meaningful fraction. `backgroundColor` is a packed 0xRRGGBBAA value — pass the
+ * render state's clear colour. `channelTolerance` (0..255) absorbs antialiasing fringe around the
+ * cleared edges so a genuinely empty frame does not creep above zero.
+ */
+export declare function getSurfaceCoverage(source: Readonly<Surface>, backgroundColor: number, channelTolerance?: number): number;
+//# sourceMappingURL=surfaceCoverage.d.ts.map

package/dist/surfaceCoverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceCoverage.d.ts","sourceRoot":"","sources":["../src/surfaceCoverage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,EACzB,eAAe,EAAE,MAAM,EACvB,gBAAgB,GAAE,MAAU,GAC3B,MAAM,CAqBR"}

package/dist/surfaceCoverage.js

@@ -0,0 +1,29 @@
+/**
+ * Returns the fraction of pixels (0..1) that differ from `backgroundColor` by more than
+ * `channelTolerance` on at least one RGBA channel. This is the "did anything render" signal: a blank
+ * frame (the whole surface still the clear colour, or fully transparent) returns ~0; a populated
+ * frame returns a meaningful fraction. `backgroundColor` is a packed 0xRRGGBBAA value — pass the
+ * render state's clear colour. `channelTolerance` (0..255) absorbs antialiasing fringe around the
+ * cleared edges so a genuinely empty frame does not creep above zero.
+ */
+export function getSurfaceCoverage(source, backgroundColor, channelTolerance = 0) {
+    const br = (backgroundColor >>> 24) & 0xff;
+    const bg = (backgroundColor >> 16) & 0xff;
+    const bb = (backgroundColor >> 8) & 0xff;
+    const ba = backgroundColor & 0xff;
+    const data = source.data;
+    const totalPixels = source.width * source.height;
+    if (totalPixels === 0)
+        return 0;
+    let covered = 0;
+    for (let i = 0; i < data.length; i += 4) {
+        if (Math.abs(data[i] - br) > channelTolerance ||
+            Math.abs(data[i + 1] - bg) > channelTolerance ||
+            Math.abs(data[i + 2] - bb) > channelTolerance ||
+            Math.abs(data[i + 3] - ba) > channelTolerance) {
+            covered++;
+        }
+    }
+    return covered / totalPixels;
+}
+//# sourceMappingURL=surfaceCoverage.js.map

package/dist/surfaceCoverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceCoverage.js","sourceRoot":"","sources":["../src/surfaceCoverage.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAyB,EACzB,eAAuB,EACvB,mBAA2B,CAAC;IAE5B,MAAM,EAAE,GAAG,CAAC,eAAe,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAC3C,MAAM,EAAE,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IAC1C,MAAM,EAAE,GAAG,CAAC,eAAe,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;IACzC,MAAM,EAAE,GAAG,eAAe,GAAG,IAAI,CAAC;IAClC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IACzB,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;IACjD,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAEhC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,IACE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,gBAAgB;YACzC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,gBAAgB;YAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,gBAAgB;YAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,gBAAgB,EAC7C,CAAC;YACD,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,OAAO,GAAG,WAAW,CAAC;AAC/B,CAAC"}

package/dist/surfaceCrop.d.ts

@@ -0,0 +1,33 @@
+import type { RectangleLike, Surface, SurfaceEdgeMode } from '@flighthq/types';
+/**
+ * Allocates a new `Surface` containing the pixels of `source` cropped to
+ * `rect`. `rect` coordinates are relative to the `source` surface origin
+ * (not to a region offset). Pixels of `rect` that fall outside the surface
+ * are filled with transparent black.
+ *
+ * Returns a new `Surface` with the same `colorSpace`, `alphaType`, and
+ * `format` as `source`, with dimensions equal to `rect.width × rect.height`.
+ */
+export declare function cropSurface(source: Readonly<Surface>, rect: Readonly<RectangleLike>): Surface;
+/**
+ * Allocates a new `Surface` with `source` padded by `left`, `top`, `right`,
+ * and `bottom` pixels on each side. Added pixels are filled according to
+ * `edgeMode`:
+ * - `'transparent'` (default): filled with transparent black.
+ * - `'clamp'`: border pixels of `source` are repeated.
+ * - `'wrap'`: `source` is tiled.
+ * - `'mirror'`: `source` is mirrored at the edges.
+ *
+ * When `edgeMode` is `'transparent'`, the optional `fillColor` (packed RGBA,
+ * e.g. `0xffffffff` for opaque white) overrides the default transparent fill.
+ * It is ignored for all other edge modes.
+ */
+export declare function extendSurface(source: Readonly<Surface>, left: number, top: number, right: number, bottom: number, edgeMode?: SurfaceEdgeMode, fillColor?: number): Surface;
+/**
+ * Allocates a new `Surface` with the transparent border of `source` removed.
+ * Finds the tightest bounding box of all pixels with alpha > 0 and returns a
+ * new surface cropped to that box. If the entire surface is transparent,
+ * returns a 1×1 transparent surface.
+ */
+export declare function trimSurface(source: Readonly<Surface>): Surface;
+//# sourceMappingURL=surfaceCrop.d.ts.map

package/dist/surfaceCrop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceCrop.d.ts","sourceRoot":"","sources":["../src/surfaceCrop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE/E;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,GAAG,OAAO,CAiC7F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,EACzB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,eAA+B,EACzC,SAAS,SAAI,GACZ,OAAO,CAkDT;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,OAAO,CAgC9D"}

package/dist/surfaceCrop.js

@@ -0,0 +1,174 @@
+import { createEntity } from '@flighthq/entity';
+/**
+ * Allocates a new `Surface` containing the pixels of `source` cropped to
+ * `rect`. `rect` coordinates are relative to the `source` surface origin
+ * (not to a region offset). Pixels of `rect` that fall outside the surface
+ * are filled with transparent black.
+ *
+ * Returns a new `Surface` with the same `colorSpace`, `alphaType`, and
+ * `format` as `source`, with dimensions equal to `rect.width × rect.height`.
+ */
+export function cropSurface(source, rect) {
+    const sw = source.width;
+    const sh = source.height;
+    const rx = Math.round(rect.x);
+    const ry = Math.round(rect.y);
+    const rw = Math.max(0, Math.round(rect.width));
+    const rh = Math.max(0, Math.round(rect.height));
+    const data = new Uint8ClampedArray(rw * rh * 4);
+    const sd = source.data;
+    for (let py = 0; py < rh; py++) {
+        const sy = ry + py;
+        if (sy < 0 || sy >= sh)
+            continue;
+        for (let px = 0; px < rw; px++) {
+            const sx = rx + px;
+            if (sx < 0 || sx >= sw)
+                continue;
+            const si = (sy * sw + sx) * 4;
+            const di = (py * rw + px) * 4;
+            data[di] = sd[si];
+            data[di + 1] = sd[si + 1];
+            data[di + 2] = sd[si + 2];
+            data[di + 3] = sd[si + 3];
+        }
+    }
+    return createEntity({
+        alphaType: source.alphaType,
+        colorSpace: source.colorSpace,
+        data,
+        format: source.format,
+        height: rh,
+        source: null,
+        version: 0,
+        width: rw,
+    });
+}
+/**
+ * Allocates a new `Surface` with `source` padded by `left`, `top`, `right`,
+ * and `bottom` pixels on each side. Added pixels are filled according to
+ * `edgeMode`:
+ * - `'transparent'` (default): filled with transparent black.
+ * - `'clamp'`: border pixels of `source` are repeated.
+ * - `'wrap'`: `source` is tiled.
+ * - `'mirror'`: `source` is mirrored at the edges.
+ *
+ * When `edgeMode` is `'transparent'`, the optional `fillColor` (packed RGBA,
+ * e.g. `0xffffffff` for opaque white) overrides the default transparent fill.
+ * It is ignored for all other edge modes.
+ */
+export function extendSurface(source, left, top, right, bottom, edgeMode = 'transparent', fillColor = 0) {
+    const sw = source.width;
+    const sh = source.height;
+    const dw = sw + left + right;
+    const dh = sh + top + bottom;
+    const data = new Uint8ClampedArray(dw * dh * 4);
+    const sd = source.data;
+    const fr = (fillColor >>> 24) & 0xff;
+    const fg = (fillColor >> 16) & 0xff;
+    const fb = (fillColor >> 8) & 0xff;
+    const fa = fillColor & 0xff;
+    for (let py = 0; py < dh; py++) {
+        for (let px = 0; px < dw; px++) {
+            const sx = px - left;
+            const sy = py - top;
+            const di = (py * dw + px) * 4;
+            if (sx >= 0 && sx < sw && sy >= 0 && sy < sh) {
+                const si = (sy * sw + sx) * 4;
+                data[di] = sd[si];
+                data[di + 1] = sd[si + 1];
+                data[di + 2] = sd[si + 2];
+                data[di + 3] = sd[si + 3];
+            }
+            else {
+                const cx = resolveEdge(sx, sw, edgeMode);
+                const cy = resolveEdge(sy, sh, edgeMode);
+                if (cx !== null && cy !== null) {
+                    const si = (cy * sw + cx) * 4;
+                    data[di] = sd[si];
+                    data[di + 1] = sd[si + 1];
+                    data[di + 2] = sd[si + 2];
+                    data[di + 3] = sd[si + 3];
+                }
+                else {
+                    data[di] = fr;
+                    data[di + 1] = fg;
+                    data[di + 2] = fb;
+                    data[di + 3] = fa;
+                }
+            }
+        }
+    }
+    return createEntity({
+        alphaType: source.alphaType,
+        colorSpace: source.colorSpace,
+        data,
+        format: source.format,
+        height: dh,
+        source: null,
+        version: 0,
+        width: dw,
+    });
+}
+/**
+ * Allocates a new `Surface` with the transparent border of `source` removed.
+ * Finds the tightest bounding box of all pixels with alpha > 0 and returns a
+ * new surface cropped to that box. If the entire surface is transparent,
+ * returns a 1×1 transparent surface.
+ */
+export function trimSurface(source) {
+    const sw = source.width;
+    const sh = source.height;
+    const sd = source.data;
+    let minX = sw;
+    let minY = sh;
+    let maxX = -1;
+    let maxY = -1;
+    for (let py = 0; py < sh; py++) {
+        for (let px = 0; px < sw; px++) {
+            const a = sd[(py * sw + px) * 4 + 3];
+            if (a > 0) {
+                if (px < minX)
+                    minX = px;
+                if (px > maxX)
+                    maxX = px;
+                if (py < minY)
+                    minY = py;
+                if (py > maxY)
+                    maxY = py;
+            }
+        }
+    }
+    if (maxX < 0) {
+        return createEntity({
+            alphaType: source.alphaType,
+            colorSpace: source.colorSpace,
+            data: new Uint8ClampedArray(4),
+            format: source.format,
+            height: 1,
+            source: null,
+            version: 0,
+            width: 1,
+        });
+    }
+    return cropSurface(source, { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 });
+}
+function resolveEdge(v, size, mode) {
+    if (v >= 0 && v < size)
+        return v;
+    switch (mode) {
+        case 'clamp':
+            return Math.max(0, Math.min(size - 1, v));
+        case 'wrap':
+            return ((v % size) + size) % size;
+        case 'mirror': {
+            const period = 2 * size;
+            const wrapped = ((v % period) + period) % period;
+            return wrapped < size ? wrapped : period - 1 - wrapped;
+        }
+        default:
+            // 'transparent'
+            return null;
+    }
+}
+//# sourceMappingURL=surfaceCrop.js.map

package/dist/surfaceCrop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceCrop.js","sourceRoot":"","sources":["../src/surfaceCrop.ts"],"names":[],"mappings":"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"}

package/dist/surfaceDisplacement.d.ts

@@ -0,0 +1,48 @@
+import type { SurfaceEdgeMode, SurfaceRegion } from '@flighthq/types';
+export type SurfaceDisplacementMapMode = 'clamp' | 'color' | 'ignore' | 'wrap';
+export interface SurfaceDisplacementMapOptions {
+    /** Map surface whose channels drive the per-pixel displacement. */
+    map: Readonly<SurfaceRegion>;
+    /** Channel index (0=R, 1=G, 2=B, 3=A) of `map` that drives X displacement. Default 0. */
+    componentX?: number;
+    /** Channel index (0=R, 1=G, 2=B, 3=A) of `map` that drives Y displacement. Default 1. */
+    componentY?: number;
+    /**
+     * X displacement scale in pixels. A map value of 128 produces no shift; 0
+     * shifts by -0.5 × scaleX; 255 shifts by +0.5 × scaleX. Default 0.
+     */
+    scaleX?: number;
+    /** Y displacement scale in pixels. Default 0. */
+    scaleY?: number;
+    /** How to handle sample positions that fall outside the source region. Default 'wrap'. */
+    mode?: SurfaceDisplacementMapMode;
+    /**
+     * Standard edge mode — when set, overrides `mode` for standard edge behaviours.
+     * Use for API consistency with other surface geometric ops. Default undefined
+     * (falls back to `mode`).
+     */
+    edgeMode?: SurfaceEdgeMode;
+    /** Packed 0xRRGGBBAA fill used when `mode` is 'color'. Default 0. */
+    fillColor?: number;
+}
+/**
+ * Warps `source` by sampling each output pixel from a displaced source position,
+ * writing into `out`. The displacement for pixel (px, py) is read from `map` at
+ * the aligned position and scaled:
+ *
+ *   dx = (mapValueX / 255 - 0.5) * scaleX
+ *   dy = (mapValueY / 255 - 0.5) * scaleY
+ *
+ * A map value of 128 is approximately neutral (< 0.2px shift). Sampling uses
+ * bilinear interpolation.
+ *
+ * When `edgeMode` is set, it controls out-of-bounds behaviour using the standard
+ * `SurfaceEdgeMode` values (`'clamp'`, `'wrap'`, `'mirror'`, `'transparent'`).
+ * Otherwise `mode` is used: `'wrap'` tiles, `'clamp'` holds the edge, `'ignore'`
+ * keeps the undisplaced source pixel, and `'color'` fills with `fillColor`.
+ *
+ * `out` must be at least `source.width * source.height * 4` bytes and must NOT
+ * alias `source.surface.data` — output pixels read arbitrary source positions.
+ */
+export declare function displaceSurface(out: Uint8ClampedArray, source: Readonly<SurfaceRegion>, options: Readonly<SurfaceDisplacementMapOptions>): void;
+//# sourceMappingURL=surfaceDisplacement.d.ts.map

package/dist/surfaceDisplacement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceDisplacement.d.ts","sourceRoot":"","sources":["../src/surfaceDisplacement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEtE,MAAM,MAAM,0BAA0B,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/E,MAAM,WAAW,6BAA6B;IAC5C,mEAAmE;IACnE,GAAG,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC7B,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,0BAA0B,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,iBAAiB,EACtB,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC/B,OAAO,EAAE,QAAQ,CAAC,6BAA6B,CAAC,GAC/C,IAAI,CAwFN"}