@melite/formats 0.0.0-stage → 0.1.4-alpha

package/lib/index.d.ts

@@ -0,0 +1,26 @@
+/** @melite/formats — pure media codecs + math (npz, skins, masks, presets).
+ * Fetch-free by law; three.js types only where geometry demands. */
+export * from "./npz.js";
+export * from "./somaSkin.js";
+export * from "./motionNpz.js";
+export * from "./glbSkin.js";
+export * from "./maskPrep.js";
+export * from "./bodyPresets.js";
+export * from "./poseCodec.js";
+export * from "./motionConstraints.js";
+export * from "./openPoseCanvas.js";
+export * from "./downloads.js";
+export * from "./b64.js";
+export * from "./poseTransforms.js";
+export * from "./psdExport.js";
+export * from "./pngMetaInfo.js";
+export * from "./pngMeta.js";
+export * from "./captionSplitter.js";
+export * from "./promptTags.js";
+export * from "./motionEnvelope.js";
+export * from "./extractVideoFrame.js";
+export * from "./keyframeExtract.js";
+export * from "./handPose.js";
+export * from "./capabilityCards.js";
+export * from "./cardMutations.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,26 @@
+/** @melite/formats — pure media codecs + math (npz, skins, masks, presets).
+ * Fetch-free by law; three.js types only where geometry demands. */
+export * from "./npz.js";
+export * from "./somaSkin.js";
+export * from "./motionNpz.js";
+export * from "./glbSkin.js";
+export * from "./maskPrep.js";
+export * from "./bodyPresets.js";
+export * from "./poseCodec.js";
+export * from "./motionConstraints.js";
+export * from "./openPoseCanvas.js";
+export * from "./downloads.js";
+export * from "./b64.js";
+export * from "./poseTransforms.js";
+export * from "./psdExport.js";
+export * from "./pngMetaInfo.js";
+export * from "./pngMeta.js";
+export * from "./captionSplitter.js";
+export * from "./promptTags.js";
+export * from "./motionEnvelope.js";
+export * from "./extractVideoFrame.js";
+export * from "./keyframeExtract.js";
+export * from "./handPose.js";
+export * from "./capabilityCards.js";
+export * from "./cardMutations.js";
+//# sourceMappingURL=index.js.map

package/lib/keyframeExtract.d.ts

@@ -0,0 +1,46 @@
+/**
+ * keyframeExtract — pick anchor frames from a SOMA-77 motion trajectory.
+ *
+ * Used by Pose Studio's "Auto Keyframes" action (Kimodo-TO (g)) to turn a
+ * generated motion into a sparse set of keyframe constraints without the
+ * user scrubbing and pinning by hand.
+ *
+ * Two regimes:
+ *
+ *   1. Multi-prompt motion → the semantic boundaries are already known:
+ *      each prompt segment's start_frame / end_frame is a natural keyframe
+ *      (the motion changes intent there). No signal processing needed.
+ *
+ *   2. Single-prompt motion → run velocity-minima detection on the joint
+ *      trajectory. Per-frame velocity = total squared displacement of all
+ *      77 joints from the previous frame. Local MINIMA of this signal are
+ *      the holds / extremes (top of a reach, contact frame, pause) — clean,
+ *      readable anchor poses. Local MAXIMA are mid-motion blur frames and
+ *      make BAD anchors, so we explicitly look for minima, not peaks.
+ *
+ * Both paths return frame indices, deduped and sorted, with endpoints and a
+ * minimum spacing enforced.
+ */
+import type { PromptSegmentOutput } from "./textToPose.js";
+export interface ExtractOptions {
+    /** Minimum frames between extracted keyframes (anti-clustering). */
+    minSpacing?: number;
+    /** Always include frame 0 and the last frame as anchors. Default true. */
+    includeEndpoints?: boolean;
+}
+/**
+ * Extract keyframe frame indices from a motion's per-frame joint trajectory.
+ *
+ * @param framesJoints  Per-frame joint positions. Shape: [frame][joint][3].
+ *                       (result.motion.frames_soma77_3d from the pose API.)
+ * @param segments      Optional prompt segments. When present (>1), their
+ *                       boundaries are used directly instead of velocity
+ *                       detection — they ARE the semantic keyframes.
+ */
+export declare function extractKeyframeFrames(framesJoints: number[][][], segments?: PromptSegmentOutput[], opts?: ExtractOptions): number[];
+/**
+ * Per-frame velocity (total squared joint displacement). Exposed for the
+ * optional velocity-curve visualization in the timeline.
+ */
+export declare function frameVelocities(framesJoints: number[][][]): number[];
+//# sourceMappingURL=keyframeExtract.d.ts.map

package/lib/keyframeExtract.js

@@ -0,0 +1,89 @@
+/**
+ * Extract keyframe frame indices from a motion's per-frame joint trajectory.
+ *
+ * @param framesJoints  Per-frame joint positions. Shape: [frame][joint][3].
+ *                       (result.motion.frames_soma77_3d from the pose API.)
+ * @param segments      Optional prompt segments. When present (>1), their
+ *                       boundaries are used directly instead of velocity
+ *                       detection — they ARE the semantic keyframes.
+ */
+export function extractKeyframeFrames(framesJoints, segments, opts = {}) {
+    if (!framesJoints?.length)
+        return [];
+    const total = framesJoints.length;
+    const minSpacing = opts.minSpacing ?? Math.max(2, Math.floor(total / 12));
+    const includeEndpoints = opts.includeEndpoints ?? true;
+    let raw;
+    if (segments && segments.length > 1) {
+        // Multi-prompt: segment boundaries are the keyframes.
+        raw = new Set();
+        for (const seg of segments) {
+            raw.add(seg.start_frame);
+            raw.add(seg.end_frame);
+        }
+        // Also include the peak if provided — it's often a strong anchor.
+    }
+    else {
+        // Single-prompt (or no segments): velocity-minima detection.
+        raw = new Set(velocityMinima(framesJoints));
+    }
+    // Enforce endpoints.
+    if (includeEndpoints) {
+        raw.add(0);
+        raw.add(total - 1);
+    }
+    // Dedupe + sort + enforce min spacing (greedy — keep first, skip too-close).
+    const sorted = Array.from(raw).sort((a, b) => a - b)
+        .filter(f => f >= 0 && f < total);
+    const out = [];
+    for (const f of sorted) {
+        if (out.length === 0 || f - out[out.length - 1] >= minSpacing) {
+            out.push(f);
+        }
+        else if (f === total - 1) {
+            // Always keep the last frame even if close to the previous — it's
+            
+            // non-empty and f - prev < minSpacing with f === total - 1, so the
+            // end-anchor unconditionally replaces its too-close predecessor.
+            out[out.length - 1] = f;
+        }
+    }
+    return out;
+}
+/**
+ * Per-frame velocity (total squared joint displacement). Exposed for the
+ * optional velocity-curve visualization in the timeline.
+ */
+export function frameVelocities(framesJoints) {
+    const v = new Array(framesJoints.length).fill(0);
+    for (let f = 1; f < framesJoints.length; f++) {
+        const a = framesJoints[f - 1];
+        const b = framesJoints[f];
+        let sum = 0;
+        const n = Math.min(a.length, b.length);
+        for (let j = 0; j < n; j++) {
+            const aj = a[j], bj = b[j];
+            const dx = bj[0] - aj[0];
+            const dy = bj[1] - aj[1];
+            const dz = bj[2] - aj[2];
+            sum += dx * dx + dy * dy + dz * dz;
+        }
+        v[f] = sum;
+    }
+    v[0] = v[1] ?? 0;
+    return v;
+}
+/** Local minima of the velocity curve → holds / extremes = good anchors. */
+function velocityMinima(framesJoints) {
+    const v = frameVelocities(framesJoints);
+    const minima = [];
+    // A frame is a local minimum if it's lower than its neighbors. Use a
+    // smoothing window of 2 to avoid jitter-induced false minima.
+    for (let f = 2; f < v.length - 2; f++) {
+        if (v[f] < v[f - 1] && v[f] < v[f + 1] && v[f] < v[f - 2] && v[f] < v[f + 2]) {
+            minima.push(f);
+        }
+    }
+    return minima;
+}
+//# sourceMappingURL=keyframeExtract.js.map

package/lib/maskPrep.d.ts

@@ -0,0 +1,88 @@
+/**
+ * maskPrep — mask preparation (ported from the retired python
+ * implementation; the lockstep fixtures are gone — the deterministic
+ * loops below are the authority now).
+ *
+ * Where it runs:
+ *   • Mask Studio "Prep preview" (view-only — shows the EFFECTIVE mask
+ *     the Inpaint card will consume; the studio itself writes RAW masks).
+ *   • Canvas Inpaint Studio (live preview before commit).
+ *
+ * Numbers are IEEE-754 float64 on both sides; accumulation order is fixed
+ * (kernel index ascending) so sequences match Python exactly.
+ *
+ * NO GPU, no ComfyUI calls — pure geometry, same as the Python module.
+ */
+export interface MaskPrep {
+    /** >0 dilate, <0 erode (px, exact Euclidean disk, binarize at 0.5) */
+    grow: number;
+    /** gaussian falloff radius px (sigma = radius/2). 0 = off */
+    feather: number;
+    /** re-binarize at >= t AFTER feather. 0 (or negative) = disabled sentinel */
+    threshold: number;
+    /** 1 - m, applied LAST */
+    invert: boolean;
+}
+export declare function isIdentityPrep(p: MaskPrep): boolean;
+export interface OutpaintSpec {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    overlap: number;
+}
+/** Latent alignment: padded canvas dims round up to a multiple of this. */
+export declare const DEFAULT_ALIGNMENT = 8;
+/** Row-major float64 mask, 1.0 = regenerate. Shape: {h, w}. */
+export interface MaskMat {
+    w: number;
+    h: number;
+    data: Float64Array;
+}
+export declare function matFromNested(rows: number[][]): MaskMat;
+export declare function matToNested(m: MaskMat): number[][];
+export declare function cloneMat(m: MaskMat): MaskMat;
+/** Half-width of the disk per row offset dy ∈ [-r, r]: floor(sqrt(r²-dy²)). */
+export declare function diskRowHalfWidths(radius: number): number[];
+/** Dilate/erode the ≥0.5 region by an exact disk. Eroding to empty
+ *  THROWS (no silent fallback — mirror of the Python hard error). */
+export declare function growMask(m: MaskMat, px: number): MaskMat;
+/** sigma = radius/2, truncated at ±ceil(3σ), renormalized. */
+export declare function gaussianKernel(radius: number): Float64Array;
+/** Gaussian feather (columns then rows — same axis order as Python). */
+export declare function featherMask(m: MaskMat, radius: number): MaskMat;
+export declare function thresholdMask(m: MaskMat, t: number): MaskMat;
+export declare function invertMask(m: MaskMat): MaskMat;
+export declare function coverage(m: MaskMat): number;
+export interface PrepReport {
+    applied: string[];
+}
+/** FIXED chain: grow → feather → threshold → invert. */
+export declare function applyPrep(m: MaskMat, prep: MaskPrep): {
+    mask: MaskMat;
+    report: PrepReport;
+};
+export declare function roundToMultiple(value: number, multiple?: number): number;
+export interface OutpaintGeometry {
+    newW: number;
+    newH: number;
+    offX: number;
+    offY: number;
+    mask: MaskMat;
+    actualRight: number;
+    actualBottom: number;
+}
+/** Derive padded-canvas geometry + regenerate mask (border ∪ overlap). */
+export declare function deriveOutpaint(origW: number, origH: number, spec: OutpaintSpec, alignment?: number): OutpaintGeometry;
+/** Overlap seam-kill on an ALREADY-padded canvas (client composite).
+ *  Original rect = (left, top) .. (w-right, h-bottom). */
+export declare function applyOutpaintOverlap(m: MaskMat, spec: OutpaintSpec): MaskMat;
+/** Place wired 1:1 at (offX, offY) and union (max). */
+export declare function unionMaskAt(canvasMask: MaskMat, wired: MaskMat, offX: number, offY: number): MaskMat;
+/** Extract a mask from ImageData. channel: "alpha" (RGBA canvas carrier)
+ *  or "red" (white-on-black studio carrier). Values → [0,1] float64. */
+export declare function maskFromImageData(img: ImageData, channel?: "alpha" | "red"): MaskMat;
+/** Composite a mask into ImageData as tinted RGBA (premultiplied by the
+ *  caller's tint color) — the studio overlay renderer. */
+export declare function tintMaskToImageData(m: MaskMat, img: ImageData, r: number, g: number, b: number, alpha?: number): void;
+//# sourceMappingURL=maskPrep.d.ts.map

package/lib/maskPrep.js

@@ -0,0 +1,386 @@
+/**
+ * maskPrep — mask preparation (ported from the retired python
+ * implementation; the lockstep fixtures are gone — the deterministic
+ * loops below are the authority now).
+ *
+ * Where it runs:
+ *   • Mask Studio "Prep preview" (view-only — shows the EFFECTIVE mask
+ *     the Inpaint card will consume; the studio itself writes RAW masks).
+ *   • Canvas Inpaint Studio (live preview before commit).
+ *
+ * Numbers are IEEE-754 float64 on both sides; accumulation order is fixed
+ * (kernel index ascending) so sequences match Python exactly.
+ *
+ * NO GPU, no ComfyUI calls — pure geometry, same as the Python module.
+ */
+export function isIdentityPrep(p) {
+    return (p.grow === 0 &&
+        p.feather === 0 &&
+        p.threshold <= 0 &&
+        !p.invert);
+}
+/** Latent alignment: padded canvas dims round up to a multiple of this. */
+export const DEFAULT_ALIGNMENT = 8;
+export function matFromNested(rows) {
+    const h = rows.length;
+    const w = h > 0 ? rows[0].length : 0;
+    const data = new Float64Array(h * w);
+    for (let y = 0; y < h; y++) {
+        const row = rows[y];
+        if (row.length !== w)
+            throw new Error("ragged matrix");
+        for (let x = 0; x < w; x++)
+            data[y * w + x] = row[x];
+    }
+    return { w, h, data };
+}
+export function matToNested(m) {
+    const out = [];
+    for (let y = 0; y < m.h; y++) {
+        const row = new Array(m.w);
+        for (let x = 0; x < m.w; x++)
+            row[x] = m.data[y * m.w + x];
+        out.push(row);
+    }
+    return out;
+}
+export function cloneMat(m) {
+    return { w: m.w, h: m.h, data: new Float64Array(m.data) };
+}
+// ── Exact Euclidean disk ─────────────────────────────────────────────────
+/** Half-width of the disk per row offset dy ∈ [-r, r]: floor(sqrt(r²-dy²)). */
+export function diskRowHalfWidths(radius) {
+    const r = radius | 0;
+    const out = [];
+    for (let dy = -r; dy <= r; dy++) {
+        out.push(Math.floor(Math.sqrt(r * r - dy * dy)));
+    }
+    return out;
+}
+/** Horizontal sliding-window OR (half-width k) via prefix sums, O(h·w). */
+function horizDilateBool(b, w, h, k) {
+    if (k <= 0)
+        return b.slice();
+    const pw = w + 2 * k;
+    const padded = new Int32Array(h * pw); // 0-filled = False padding
+    for (let y = 0; y < h; y++) {
+        for (let x = 0; x < w; x++)
+            padded[y * pw + k + x] = b[y * w + x];
+    }
+    const out = new Uint8Array(h * w);
+    for (let y = 0; y < h; y++) {
+        // running prefix along the padded row
+        let csum = 0;
+        const cpre = new Int32Array(pw + 1);
+        for (let t = 0; t < pw; t++) {
+            csum += padded[y * pw + t];
+            cpre[t + 1] = csum;
+        }
+        for (let x = 0; x < w; x++) {
+            // window covers padded [x, x+2k] → cpre[x+2k+1] - cpre[x]
+            out[y * w + x] =
+                cpre[x + 2 * k + 1] - cpre[x] > 0 ? 1 : 0;
+        }
+    }
+    return out;
+}
+/** Exact disk dilation/erosion. Erode = ~dilate(~b); outside behaves as
+ *  mask material for erosion (lenient edges — GrowMask parity). */
+function diskMorph(b, w, h, radius, erode) {
+    const r = radius | 0;
+    if (r <= 0)
+        return b.slice();
+    const src = new Uint8Array(b.length);
+    if (erode)
+        for (let i = 0; i < b.length; i++)
+            src[i] = b[i] ? 0 : 1;
+    else
+        src.set(b);
+    const acc = new Uint8Array(h * w);
+    const hw = diskRowHalfWidths(r);
+    for (let dy = -r; dy <= r; dy++) {
+        const k = hw[dy + r];
+        
+
+        if (k < 0)
+            continue;
+        const row = horizDilateBool(src, w, h, k);
+        if (dy === 0) {
+            for (let i = 0; i < acc.length; i++)
+                if (row[i])
+                    acc[i] = 1;
+        }
+        else if (dy > 0) {
+            for (let y = dy; y < h; y++) {
+                const ai = y * w, ri = (y - dy) * w;
+                for (let x = 0; x < w; x++)
+                    if (row[ri + x])
+                        acc[ai + x] = 1;
+            }
+        }
+        else {
+            for (let y = 0; y < h + dy; y++) {
+                const ai = y * w, ri = (y - dy) * w;
+                for (let x = 0; x < w; x++)
+                    if (row[ri + x])
+                        acc[ai + x] = 1;
+            }
+        }
+    }
+    if (!erode)
+        return acc;
+    const out = new Uint8Array(b.length);
+    for (let i = 0; i < acc.length; i++)
+        out[i] = acc[i] ? 0 : 1;
+    return out;
+}
+/** Dilate/erode the ≥0.5 region by an exact disk. Eroding to empty
+ *  THROWS (no silent fallback — mirror of the Python hard error). */
+export function growMask(m, px) {
+    px = px | 0;
+    if (px === 0)
+        return cloneMat(m);
+    const b = new Uint8Array(m.w * m.h);
+    for (let i = 0; i < b.length; i++)
+        b[i] = m.data[i] >= 0.5 ? 1 : 0;
+    let outB;
+    if (px > 0) {
+        outB = diskMorph(b, m.w, m.h, px, false);
+    }
+    else {
+        outB = diskMorph(b, m.w, m.h, -px, true);
+        let any2 = false;
+        for (let i = 0; i < outB.length; i++)
+            if (outB[i]) {
+                any2 = true;
+                break;
+            }
+        if (!any2) {
+            throw new Error(`maskPrep: grow(${px}) eroded the mask to NOTHING — the ` +
+                `regenerate region vanished. Reduce the shrink (grow < 0) or ` +
+                `paint a larger region. NO SILENT FALLBACK.`);
+        }
+    }
+    const data = new Float64Array(outB.length);
+    for (let i = 0; i < outB.length; i++)
+        data[i] = outB[i];
+    return { w: m.w, h: m.h, data };
+}
+// ── Feather ──────────────────────────────────────────────────────────────
+/** sigma = radius/2, truncated at ±ceil(3σ), renormalized. */
+export function gaussianKernel(radius) {
+    const sigma = radius / 2;
+    const k = Math.max(1, Math.ceil(3 * sigma));
+    const xs = [];
+    for (let x = -k; x <= k; x++)
+        xs.push(x);
+    const g = new Float64Array(xs.length);
+    let sum = 0;
+    for (let i = 0; i < xs.length; i++) {
+        const x = xs[i];
+        g[i] = Math.exp(-(x * x) / (2 * sigma * sigma));
+        sum += g[i];
+    }
+    for (let i = 0; i < g.length; i++)
+        g[i] = g[i] / sum;
+    return g;
+}
+/** 1D convolution along an axis, replicate edges, fixed accumulation
+ *  order (kernel index ascending) — the parity-critical loop. */
+function convAxisReplicate(m, kernel, axis) {
+    const { w, h, data } = m;
+    const k = (kernel.length - 1) >> 1;
+    const out = new Float64Array(w * h);
+    if (axis === 1) {
+        for (let y = 0; y < h; y++) {
+            const rowIn = new Float64Array(w + 2 * k);
+            for (let t = 0; t < k; t++)
+                rowIn[t] = data[y * w];
+            for (let x = 0; x < w; x++)
+                rowIn[k + x] = data[y * w + x];
+            for (let t = 0; t < k; t++)
+                rowIn[k + w + t] = data[y * w + w - 1];
+            for (let x = 0; x < w; x++) {
+                let acc = 0;
+                for (let i = 0; i < kernel.length; i++) {
+                    acc += kernel[i] * rowIn[i + x];
+                }
+                out[y * w + x] = acc;
+            }
+        }
+    }
+    else {
+        for (let x = 0; x < w; x++) {
+            const colIn = new Float64Array(h + 2 * k);
+            for (let t = 0; t < k; t++)
+                colIn[t] = data[x];
+            for (let y = 0; y < h; y++)
+                colIn[k + y] = data[y * w + x];
+            for (let t = 0; t < k; t++)
+                colIn[k + h + t] = data[(h - 1) * w + x];
+            for (let y = 0; y < h; y++) {
+                let acc = 0;
+                for (let i = 0; i < kernel.length; i++) {
+                    acc += kernel[i] * colIn[i + y];
+                }
+                out[y * w + x] = acc;
+            }
+        }
+    }
+    return { w, h, data: out };
+}
+/** Gaussian feather (columns then rows — same axis order as Python). */
+export function featherMask(m, radius) {
+    radius = radius | 0;
+    if (radius <= 0)
+        return cloneMat(m);
+    const kernel = gaussianKernel(radius);
+    let out = convAxisReplicate(m, kernel, 1);
+    out = convAxisReplicate(out, kernel, 0);
+    return out;
+}
+// ── Threshold / invert / coverage ────────────────────────────────────────
+export function thresholdMask(m, t) {
+    if (t <= 0)
+        return cloneMat(m);
+    const data = new Float64Array(m.data.length);
+    for (let i = 0; i < data.length; i++)
+        data[i] = m.data[i] >= t ? 1 : 0;
+    return { w: m.w, h: m.h, data };
+}
+export function invertMask(m) {
+    const data = new Float64Array(m.data.length);
+    for (let i = 0; i < data.length; i++)
+        data[i] = 1 - m.data[i];
+    return { w: m.w, h: m.h, data };
+}
+export function coverage(m) {
+    let s = 0;
+    for (let i = 0; i < m.data.length; i++)
+        s += m.data[i];
+    return s / m.data.length;
+}
+/** FIXED chain: grow → feather → threshold → invert. */
+export function applyPrep(m, prep) {
+    let out = cloneMat(m);
+    const applied = [];
+    if (prep.grow) {
+        out = growMask(out, prep.grow);
+        applied.push(`grow(${prep.grow}px)`);
+    }
+    if (prep.feather) {
+        out = featherMask(out, prep.feather);
+        applied.push(`feather(${prep.feather}px)`);
+    }
+    if (prep.threshold > 0) {
+        out = thresholdMask(out, prep.threshold);
+        applied.push(`threshold(${prep.threshold})`);
+    }
+    if (prep.invert) {
+        out = invertMask(out);
+        applied.push("invert");
+    }
+    return { mask: out, report: { applied: applied.length ? applied : ["identity"] } };
+}
+// ── Outpaint ─────────────────────────────────────────────────────────────
+export function roundToMultiple(value, multiple = DEFAULT_ALIGNMENT) {
+    if (multiple <= 0)
+        throw new Error("alignment multiple must be > 0");
+    return (Math.ceil(value / multiple)) * multiple;
+}
+/** Derive padded-canvas geometry + regenerate mask (border ∪ overlap). */
+export function deriveOutpaint(origW, origH, spec, alignment = DEFAULT_ALIGNMENT) {
+    if (origW <= 0 || origH <= 0)
+        throw new Error("original dims must be positive");
+    if (spec.top < 0 || spec.right < 0 || spec.bottom < 0 || spec.left < 0) {
+        throw new Error("outpaint pads must be >= 0");
+    }
+    if (spec.overlap < 0)
+        throw new Error("overlap must be >= 0");
+    const newW = roundToMultiple(origW + spec.left + spec.right, alignment);
+    const newH = roundToMultiple(origH + spec.top + spec.bottom, alignment);
+    const offX = spec.left, offY = spec.top;
+    const keep = new Uint8Array(newW * newH);
+    for (let y = offY; y < offY + origH; y++) {
+        for (let x = offX; x < offX + origW; x++)
+            keep[y * newW + x] = 1;
+    }
+    const border = new Uint8Array(keep.length);
+    for (let i = 0; i < keep.length; i++)
+        border[i] = keep[i] ? 0 : 1;
+    const grown = spec.overlap > 0
+        ? diskMorph(border, newW, newH, spec.overlap, false)
+        : border;
+    const data = new Float64Array(grown.length);
+    for (let i = 0; i < grown.length; i++)
+        data[i] = grown[i];
+    return {
+        newW, newH, offX, offY,
+        mask: { w: newW, h: newH, data },
+        actualRight: newW - offX - origW,
+        actualBottom: newH - offY - origH,
+    };
+}
+/** Overlap seam-kill on an ALREADY-padded canvas (client composite).
+ *  Original rect = (left, top) .. (w-right, h-bottom). */
+export function applyOutpaintOverlap(m, spec) {
+    const { w, h } = m;
+    if (spec.top + spec.bottom > h || spec.left + spec.right > w) {
+        throw new Error(`maskPrep: pads (t${spec.top}/r${spec.right}/b${spec.bottom}/` +
+            `l${spec.left}) exceed canvas ${w}x${h}`);
+    }
+    const keep = new Uint8Array(w * h);
+    for (let y = spec.top; y < h - spec.bottom; y++) {
+        for (let x = spec.left; x < w - spec.right; x++)
+            keep[y * w + x] = 1;
+    }
+    const border = new Uint8Array(w * h);
+    for (let i = 0; i < keep.length; i++)
+        border[i] = keep[i] ? 0 : 1;
+    const grown = spec.overlap > 0
+        ? diskMorph(border, w, h, spec.overlap, false)
+        : border;
+    const data = new Float64Array(w * h);
+    for (let i = 0; i < data.length; i++) {
+        data[i] = m.data[i] > grown[i] ? m.data[i] : grown[i];
+    }
+    return { w, h, data };
+}
+/** Place wired 1:1 at (offX, offY) and union (max). */
+export function unionMaskAt(canvasMask, wired, offX, offY) {
+    const out = cloneMat(canvasMask);
+    for (let y = 0; y < wired.h; y++) {
+        for (let x = 0; x < wired.w; x++) {
+            const v = wired.data[y * wired.w + x];
+            const i = (offY + y) * out.w + (offX + x);
+            if (v > out.data[i])
+                out.data[i] = v;
+        }
+    }
+    return out;
+}
+// ── ImageData bridge (studio/canvas preview source) ──────────────────────
+/** Extract a mask from ImageData. channel: "alpha" (RGBA canvas carrier)
+ *  or "red" (white-on-black studio carrier). Values → [0,1] float64. */
+export function maskFromImageData(img, channel = "alpha") {
+    const { width: w, height: h, data } = img;
+    const out = new Float64Array(w * h);
+    const stride = 4; // ImageData is always RGBA
+    const off = channel === "alpha" ? 3 : 0;
+    for (let i = 0; i < w * h; i++)
+        out[i] = data[i * stride + off] / 255;
+    return { w, h, data: out };
+}
+/** Composite a mask into ImageData as tinted RGBA (premultiplied by the
+ *  caller's tint color) — the studio overlay renderer. */
+export function tintMaskToImageData(m, img, r, g, b, alpha = 128) {
+    for (let i = 0; i < m.w * m.h; i++) {
+        const v = m.data[i];
+        const o = i * 4;
+        img.data[o] = Math.round(img.data[o] * (1 - v) + r * v);
+        img.data[o + 1] = Math.round(img.data[o + 1] * (1 - v) + g * v);
+        img.data[o + 2] = Math.round(img.data[o + 2] * (1 - v) + b * v);
+        img.data[o + 3] = Math.round(img.data[o + 3] * (1 - v) + alpha * v);
+    }
+}
+//# sourceMappingURL=maskPrep.js.map