zorya-classifier 0.0.0-stage → 0.2.0

package/dist/infrastructure/raster.js

@@ -0,0 +1,216 @@
+import sharp from 'sharp';
+import { z } from 'zod';
+import { limits, parse, pixelRectSchema } from '../entities/contracts.js';
+import { ClassifierError, assertActive } from '../entities/errors.js';
+function contains(outer, inner) {
+    return (inner.left >= outer.left &&
+        inner.top >= outer.top &&
+        inner.left + inner.width <= outer.left + outer.width &&
+        inner.top + inner.height <= outer.top + outer.height);
+}
+async function normalizeImage(bytes, signal) {
+    assertActive(signal);
+    const pipeline = sharp(bytes, { limitInputPixels: limits.imagePixels, failOn: 'error' });
+    try {
+        const metadata = await pipeline.metadata();
+        assertActive(signal);
+        if (!['png', 'jpeg', 'webp'].includes(metadata.format ?? '') || (metadata.pages ?? 1) !== 1)
+            throw new ClassifierError('INVALID_INPUT', 'Use a single PNG, JPEG or WebP image');
+        const normalized = await pipeline
+            .rotate()
+            .ensureAlpha()
+            .png()
+            .toBuffer({ resolveWithObject: true });
+        assertActive(signal);
+        if (normalized.data.byteLength > limits.imageBytes ||
+            normalized.info.width > 16384 ||
+            normalized.info.height > 16384)
+            throw new ClassifierError('RESOURCE_LIMIT', 'Decoded source exceeds image byte or side limits');
+        return { bytes: normalized.data, width: normalized.info.width, height: normalized.info.height };
+    }
+    catch (error) {
+        assertActive(signal);
+        if (error instanceof ClassifierError)
+            throw error;
+        throw new ClassifierError('INVALID_INPUT', 'Image cannot be decoded within pixel limits');
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+async function cropImage(image, region, signal, scale = 1) {
+    assertActive(signal);
+    if (!contains({ left: 0, top: 0, width: image.width, height: image.height }, region))
+        throw new ClassifierError('INVALID_INPUT', 'ROI lies outside oriented source image');
+    const pipeline = sharp(image.bytes, { limitInputPixels: limits.imagePixels })
+        .extract(region)
+        .resize(region.width * scale, region.height * scale, { kernel: 'nearest' });
+    try {
+        const data = await pipeline.png().toBuffer();
+        assertActive(signal);
+        return { bytes: data, width: region.width * scale, height: region.height * scale };
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+async function imageState(image, signal) {
+    assertActive(signal);
+    const scale = Math.min(1568 / Math.max(image.width, image.height), Math.max(1, 280 / Math.min(image.width, image.height)));
+    const width = Math.max(1, Math.round(image.width * scale)), height = Math.max(1, Math.round(image.height * scale));
+    const outWidth = Math.max(280, width), outHeight = Math.max(280, height);
+    const left = Math.floor((outWidth - width) / 2), top = Math.floor((outHeight - height) / 2);
+    const pipeline = sharp(image.bytes, { limitInputPixels: limits.imagePixels })
+        .resize(width, height, { kernel: 'nearest' })
+        .extend({
+        left,
+        top,
+        right: outWidth - width - left,
+        bottom: outHeight - height - top,
+        background: '#000000',
+    });
+    try {
+        const bytes = await pipeline.png().toBuffer();
+        assertActive(signal);
+        if (bytes.length > limits.imageBytes)
+            throw new ClassifierError('RESOURCE_LIMIT', 'Prepared image is too large');
+        const part = {
+            type: 'image_url',
+            image_url: { url: `data:image/png;base64,${bytes.toString('base64')}`, detail: 'high' },
+        };
+        return [
+            part,
+            JSON.stringify({
+                sourceImageTransform: {
+                    source: { width: image.width, height: image.height },
+                    output: { width: outWidth, height: outHeight },
+                    content: { left, top, width, height },
+                    scaleX: width / image.width,
+                    scaleY: height / image.height,
+                },
+            }),
+        ];
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+async function renderGrid(image, region, cells, labels, signal) {
+    const crop = await cropImage(image, region, signal);
+    const scale = Math.min(1512 / Math.max(crop.width, crop.height), Math.max(1, 900 / Math.min(crop.width, crop.height)));
+    const width = Math.max(1, Math.round(crop.width * scale)), height = Math.max(1, Math.round(crop.height * scale));
+    const rectangles = cells
+        .map((cell) => {
+        const label = labels.get(cell.id);
+        if (!label || !/^[PC][0-9]{2,3}$/.test(label))
+            throw new ClassifierError('INVALID_INPUT', 'Invalid grid label');
+        const x = ((cell.region.left - region.left) * width) / region.width, y = ((cell.region.top - region.top) * height) / region.height;
+        const w = (cell.region.width * width) / region.width, h = (cell.region.height * height) / region.height;
+        const font = Math.max(3, Math.min(18, w / (label.length * 0.7), h / 2));
+        return `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="none" stroke="white" stroke-width="1"/><rect x="${x + 1}" y="${y + 1}" width="${Math.min(w - 1, font * label.length * 0.7)}" height="${font + 2}" fill="#111827" fill-opacity="0.78"/><text x="${x + 2}" y="${y + font}" font-family="DejaVu Sans,sans-serif" font-size="${font}" fill="white">${label}</text>`;
+    })
+        .join('');
+    const svg = Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">${rectangles}</svg>`);
+    const pipeline = sharp(crop.bytes, { limitInputPixels: limits.imagePixels })
+        .resize(width, height, { kernel: 'nearest' })
+        .composite([{ input: svg }]);
+    try {
+        const bytes = await pipeline.png().toBuffer();
+        assertActive(signal);
+        return { bytes, width, height };
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+export function createSharpRaster() {
+    return { normalize: normalizeImage, crop: cropImage, imageState, grid: renderGrid };
+}
+/** Decode an oriented raster into the canonical RGBA8 pixel layout used by adapters. */
+export async function readCanonicalPixels(image, signal) {
+    assertActive(signal);
+    if (!Number.isSafeInteger(image.width) ||
+        !Number.isSafeInteger(image.height) ||
+        image.width < 1 ||
+        image.height < 1 ||
+        image.width > 16384 ||
+        image.height > 16384 ||
+        image.width * image.height > limits.imagePixels)
+        throw new ClassifierError('RESOURCE_LIMIT', 'Raster dimensions exceed pixel limits');
+    const pipeline = sharp(image.bytes, { limitInputPixels: limits.imagePixels, failOn: 'error' })
+        .rotate()
+        .ensureAlpha()
+        .raw();
+    try {
+        const result = await pipeline.toBuffer({ resolveWithObject: true });
+        assertActive(signal);
+        if (result.info.width !== image.width ||
+            result.info.height !== image.height ||
+            result.info.channels !== 4 ||
+            result.data.byteLength !== image.width * image.height * 4)
+            throw new ClassifierError('INVALID_INPUT', 'Raster dimensions do not match decoded pixels');
+        return { data: result.data, width: result.info.width, height: result.info.height };
+    }
+    catch (error) {
+        assertActive(signal);
+        if (error instanceof ClassifierError)
+            throw error;
+        throw new ClassifierError('INVALID_INPUT', 'Raster cannot be decoded as canonical RGBA8');
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+/** Vision adapter that retains the existing sharp imageState layout for every supplied view. */
+export function createVisionRepresentation(raster) {
+    return {
+        async prepare(input) {
+            assertActive(input.signal);
+            if (input.views.length > 9)
+                throw new ClassifierError('RESOURCE_LIMIT', 'A representation request may contain at most nine views', {
+                    component: 'representation',
+                });
+            const state = [];
+            const metadata = { profile: 'vision', bytes: 0, views: [] };
+            for (const view of input.views) {
+                assertActive(input.signal);
+                const parts = await raster.imageState(view.image, input.signal);
+                state.push(...parts);
+                const imagePart = parts.find((part) => typeof part !== 'string');
+                const transformPart = parts.find((part) => typeof part === 'string');
+                if (imagePart?.type !== 'image_url' || !transformPart)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Vision raster did not produce an image and transform');
+                const payload = imagePart.image_url.url.slice('data:image/png;base64,'.length);
+                metadata.bytes += Buffer.from(payload, 'base64').byteLength;
+                let json;
+                try {
+                    json = JSON.parse(transformPart);
+                }
+                catch {
+                    throw new ClassifierError('INVALID_RESPONSE', 'Vision raster returned invalid transform JSON');
+                }
+                const transform = parse(z.object({
+                    sourceImageTransform: z.object({
+                        output: z.object({
+                            width: z.number().int().positive().max(16384),
+                            height: z.number().int().positive().max(16384),
+                        }),
+                        content: pixelRectSchema,
+                    }),
+                }), json, 'INVALID_RESPONSE');
+                if (!contains({ left: 0, top: 0, ...transform.sourceImageTransform.output }, transform.sourceImageTransform.content))
+                    throw new ClassifierError('INVALID_RESPONSE', 'Vision raster content lies outside output');
+                metadata.views.push({
+                    id: view.id,
+                    sourceRegion: view.sourceRegion,
+                    width: transform.sourceImageTransform.output.width,
+                    height: transform.sourceImageTransform.output.height,
+                    scaleX: transform.sourceImageTransform.content.width / view.sourceRegion.width,
+                    scaleY: transform.sourceImageTransform.content.height / view.sourceRegion.height,
+                    content: transform.sourceImageTransform.content,
+                });
+            }
+            return { state, metadata };
+        },
+    };
+}

package/dist/infrastructure/segmentation/box-presentation.d.ts

@@ -0,0 +1,2 @@
+import type { SegmentationBoxPresentationPort } from '../../entities/segmentation-verification.js';
+export declare function createSharpSegmentationBoxPresentation(): SegmentationBoxPresentationPort;

package/dist/infrastructure/segmentation/box-presentation.js

@@ -0,0 +1,136 @@
+import sharp from 'sharp';
+import { z } from 'zod';
+import { limits, pixelRectSchema } from '../../entities/contracts.js';
+import { ClassifierError, assertActive } from '../../entities/errors.js';
+const rasterSchema = z
+    .object({
+    data: z.instanceof(Uint8Array),
+    width: z.number().int().positive().max(16384),
+    height: z.number().int().positive().max(16384),
+    format: z.literal('rgba8'),
+})
+    .strict();
+const inputSchema = z
+    .object({
+    image: rasterSchema,
+    region: pixelRectSchema,
+    seedRegion: pixelRectSchema,
+    roi: pixelRectSchema,
+    target: z.string().trim().min(1).max(2000),
+    exclusions: z.array(z.string().trim().min(1).max(500)).max(16),
+    signal: z.custom((value) => value instanceof AbortSignal),
+})
+    .strict();
+function inside(rect, width, height) {
+    return rect.left + rect.width <= width && rect.top + rect.height <= height;
+}
+function overlaps(first, second) {
+    return (first.left < second.left + second.width &&
+        second.left < first.left + first.width &&
+        first.top < second.top + second.height &&
+        second.top < first.top + first.height);
+}
+function cloneRect(rect) {
+    return { left: rect.left, top: rect.top, width: rect.width, height: rect.height };
+}
+function snapshot(value) {
+    const parsed = inputSchema.safeParse(value);
+    if (!parsed.success)
+        throw new ClassifierError('INVALID_INPUT', 'Invalid segmentation box presentation input', {
+            paths: parsed.error.issues.map((issue) => issue.path.join('.')),
+        });
+    const input = parsed.data;
+    const pixels = input.image.width * input.image.height;
+    if (!Number.isSafeInteger(pixels) ||
+        pixels < 1 ||
+        pixels > limits.imagePixels ||
+        input.image.data.byteLength !== pixels * 4 ||
+        !inside(input.region, input.image.width, input.image.height) ||
+        !inside(input.seedRegion, input.image.width, input.image.height) ||
+        !inside(input.roi, input.image.width, input.image.height) ||
+        input.region.left < input.roi.left ||
+        input.region.top < input.roi.top ||
+        input.region.left + input.region.width > input.roi.left + input.roi.width ||
+        input.region.top + input.region.height > input.roi.top + input.roi.height ||
+        !overlaps(input.seedRegion, input.region) ||
+        !overlaps(input.seedRegion, input.roi))
+        throw new ClassifierError('INVALID_INPUT', 'Box, seed, image, and hard ROI geometry disagree');
+    const image = {
+        data: Uint8Array.from(input.image.data),
+        width: input.image.width,
+        height: input.image.height,
+        format: 'rgba8',
+    };
+    return {
+        image,
+        region: cloneRect(input.region),
+        seedRegion: cloneRect(input.seedRegion),
+        roi: cloneRect(input.roi),
+        target: input.target,
+        exclusions: [...input.exclusions],
+        signal: input.signal,
+    };
+}
+function overlaySvg(input) {
+    const { image, region, seedRegion, roi } = input;
+    const boxStroke = Math.min(3, region.width, region.height);
+    const x = region.left + boxStroke / 2;
+    const y = region.top + boxStroke / 2;
+    const w = Math.max(0, region.width - boxStroke);
+    const h = Math.max(0, region.height - boxStroke);
+    const roiStroke = Math.min(2, roi.width, roi.height);
+    const roiX = roi.left + roiStroke / 2;
+    const roiY = roi.top + roiStroke / 2;
+    const roiW = Math.max(0, roi.width - roiStroke);
+    const roiH = Math.max(0, roi.height - roiStroke);
+    // Use the same pixel-center convention as the native seed point: (size - 1) / 2.
+    const cx = seedRegion.left + (seedRegion.width - 1) / 2;
+    const cy = seedRegion.top + (seedRegion.height - 1) / 2;
+    const seedSize = Math.min(seedRegion.width, seedRegion.height);
+    const crossArm = Math.min(5, Math.max(0.5, (seedSize - 1) / 2));
+    const crossStroke = Math.min(2, Math.max(1, seedSize));
+    return Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${image.width}" height="${image.height}"><rect x="${x}" y="${y}" width="${w}" height="${h}" fill="none" stroke="#ff00ff" stroke-width="${boxStroke}"/><rect x="${roiX}" y="${roiY}" width="${roiW}" height="${roiH}" fill="none" stroke="#ffbf00" stroke-width="${roiStroke}" stroke-dasharray="7 5"/><path d="M ${cx - crossArm} ${cy} H ${cx + crossArm} M ${cx} ${cy - crossArm} V ${cy + crossArm}" fill="none" stroke="#00ffff" stroke-width="${crossStroke}"/></svg>`);
+}
+export function createSharpSegmentationBoxPresentation() {
+    return {
+        async render(value) {
+            const input = snapshot(value);
+            const owned = input.image.data;
+            let pipeline;
+            const abort = () => pipeline?.destroy();
+            let listenerAdded = false;
+            try {
+                assertActive(input.signal);
+                pipeline = sharp(owned, {
+                    raw: { width: input.image.width, height: input.image.height, channels: 4 },
+                    limitInputPixels: limits.imagePixels,
+                    failOn: 'error',
+                })
+                    .composite([{ input: overlaySvg(input) }])
+                    .png({ compressionLevel: 6 });
+                input.signal.addEventListener('abort', abort, { once: true });
+                listenerAdded = true;
+                const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+                assertActive(input.signal);
+                if (info.width !== input.image.width ||
+                    info.height !== input.image.height ||
+                    data.byteLength < 1 ||
+                    data.byteLength > limits.imageBytes)
+                    throw new ClassifierError('RESOURCE_LIMIT', 'Rendered box presentation exceeds image limits');
+                return { bytes: Uint8Array.from(data), width: info.width, height: info.height };
+            }
+            catch (error) {
+                assertActive(input.signal);
+                if (error instanceof ClassifierError)
+                    throw error;
+                throw new ClassifierError('PROVIDER', 'Box presentation renderer failed');
+            }
+            finally {
+                if (listenerAdded)
+                    input.signal.removeEventListener('abort', abort);
+                pipeline?.destroy();
+                owned.fill(0);
+            }
+        },
+    };
+}

package/dist/infrastructure/segmentation/cutout-raster.d.ts

@@ -0,0 +1,3 @@
+import type { CutoutRasterPort } from '../../entities/cutout-raster.js';
+/** Sharp-backed decoder/encoder isolated behind the extraction raster port. */
+export declare function createSharpCutoutRaster(): CutoutRasterPort;

package/dist/infrastructure/segmentation/cutout-raster.js

@@ -0,0 +1,79 @@
+import sharp from 'sharp';
+import { ClassifierError, assertActive } from '../../entities/errors.js';
+const maxPixels = 16_777_216;
+/** Sharp-backed decoder/encoder isolated behind the extraction raster port. */
+export function createSharpCutoutRaster() {
+    return {
+        async rgba(image, signal) {
+            assertActive(signal);
+            validateRasterImage(image);
+            const pipeline = sharp(image.bytes, { limitInputPixels: maxPixels, failOn: 'error' });
+            try {
+                const output = await pipeline
+                    .toColourspace('srgb')
+                    .ensureAlpha()
+                    .raw()
+                    .toBuffer({ resolveWithObject: true });
+                assertActive(signal);
+                if (output.info.width !== image.width ||
+                    output.info.height !== image.height ||
+                    output.info.channels !== 4 ||
+                    output.data.length !== image.width * image.height * 4)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Cutout raster decoder returned invalid canonical RGBA pixels');
+                return {
+                    data: new Uint8Array(output.data),
+                    width: image.width,
+                    height: image.height,
+                    format: 'rgba8',
+                };
+            }
+            catch (error) {
+                if (error instanceof ClassifierError)
+                    throw error;
+                throw new ClassifierError('INVALID_RESPONSE', 'Cutout raster decoder failed');
+            }
+            finally {
+                pipeline.destroy();
+            }
+        },
+        async png(image, signal) {
+            assertActive(signal);
+            validateRgbaRaster(image);
+            const pipeline = sharp(image.data, {
+                raw: { width: image.width, height: image.height, channels: 4 },
+            });
+            try {
+                const png = await pipeline.png().toBuffer();
+                assertActive(signal);
+                return new Uint8Array(png);
+            }
+            catch (error) {
+                if (error instanceof ClassifierError)
+                    throw error;
+                throw new ClassifierError('PROVIDER', 'Cutout PNG encoder failed');
+            }
+            finally {
+                pipeline.destroy();
+            }
+        },
+    };
+}
+function validateRasterImage(image) {
+    if (!Number.isSafeInteger(image.width) ||
+        !Number.isSafeInteger(image.height) ||
+        image.width < 1 ||
+        image.height < 1 ||
+        image.width * image.height > maxPixels ||
+        image.bytes.byteLength < 1)
+        throw new ClassifierError('INVALID_RESPONSE', 'Raster normalizer returned invalid source data');
+}
+function validateRgbaRaster(image) {
+    if (image.format !== 'rgba8' ||
+        !Number.isSafeInteger(image.width) ||
+        !Number.isSafeInteger(image.height) ||
+        image.width < 1 ||
+        image.height < 1 ||
+        image.width * image.height > maxPixels ||
+        image.data.length !== image.width * image.height * 4)
+        throw new ClassifierError('INVALID_RESPONSE', 'Extraction returned invalid canonical RGBA pixels');
+}

package/dist/infrastructure/segmentation/grabcut/index.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { SegmentationPort } from '../../../entities/segmentation.js';
+declare const optionsSchema: z.ZodObject<{
+    assetPath: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    assetPath: string;
+}, {
+    assetPath: string;
+}>;
+export type GrabCutSegmenterOptions = z.input<typeof optionsSchema>;
+/** Explicit pinned OpenCV GrabCut adapter. The supplied native asset is never downloaded. */
+export declare function createGrabCutSegmenter(options: GrabCutSegmenterOptions): Promise<SegmentationPort>;
+export {};

package/dist/infrastructure/segmentation/grabcut/index.js

@@ -0,0 +1,118 @@
+import { performance } from 'node:perf_hooks';
+import { ClassifierError, assertActive } from '../../../entities/errors.js';
+import { z } from 'zod';
+import { limits, pixelRectSchema } from '../../../entities/contracts.js';
+import { NativeChildPool } from '../native-child.js';
+import { nativeErrorReplySchema, nativeSegmentationReplySchema } from '../native-protocol.js';
+import { verifyPinnedAsset } from '../verify-asset.js';
+import { probeBackend } from '../probe-backend.js';
+const optionsSchema = z.object({ assetPath: z.string().min(1).max(4096) }).strict();
+/** Explicit pinned OpenCV GrabCut adapter. The supplied native asset is never downloaded. */
+export async function createGrabCutSegmenter(options) {
+    const checked = optionsSchema.safeParse(options);
+    if (!checked.success)
+        throw new ClassifierError('INVALID_INPUT', 'Invalid GrabCut options');
+    const parsed = checked.data;
+    await verifyPinnedAsset(parsed.assetPath, {
+        bytes: 10_964_323,
+        sha256: '63366510248adf3a7eddf3e793dd825404efb7df3749f4d6f8557c7fa4ca8aa0',
+    }, 'OpenCV.js');
+    const workerUrl = new URL(import.meta.url.endsWith('.ts') ? '../native-worker.ts' : '../native-worker.js', import.meta.url);
+    await probeBackend(workerUrl, 'grabcut', { assetPath: parsed.assetPath });
+    const pool = new NativeChildPool({
+        workerUrl,
+        maxActive: 1,
+        maxWaiting: 2,
+        jobTimeoutMs: 10_000,
+        abortGraceMs: 250,
+        encode: (job) => Buffer.from(JSON.stringify({ id: job.id, ...job.payload })),
+        decode: (raw, id) => {
+            const error = nativeErrorReplySchema.safeParse(raw);
+            if (error.success) {
+                if (error.data.id !== id)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Native child error ID mismatch');
+                throw new ClassifierError(error.data.code, error.data.message);
+            }
+            const reply = nativeSegmentationReplySchema.safeParse(raw);
+            if (!reply.success || reply.data.id !== id)
+                throw new ClassifierError('INVALID_RESPONSE', 'Native child returned an invalid or mismatched reply');
+            return reply.data;
+        },
+    });
+    return {
+        async segment(input) {
+            const started = performance.now();
+            assertActive(input.signal);
+            let image;
+            const raw = await pool.runLazy(input.signal, () => {
+                image = snapshotInput(input);
+                return {
+                    kind: 'grabcut',
+                    width: image.width,
+                    height: image.height,
+                    rgba: Buffer.from(image.data).toString('base64'),
+                    seedRegion: image.seedRegion,
+                    wholeRegion: image.wholeRegion,
+                    roi: image.roi,
+                    prompt: image.prompt,
+                    assetPath: parsed.assetPath,
+                };
+            });
+            const reply = nativeSegmentationReplySchema.parse(raw);
+            const mask = Buffer.from(reply.mask, 'base64');
+            if (reply.width !== image.width ||
+                reply.height !== image.height ||
+                mask.length !== image.width * image.height ||
+                mask.toString('base64') !== reply.mask)
+                throw new ClassifierError('INVALID_RESPONSE', 'Native child mask dimensions or encoding are invalid');
+            return {
+                status: 'segmented',
+                mask: {
+                    data: new Uint8Array(mask),
+                    width: image.width,
+                    height: image.height,
+                    format: 'binary-u8',
+                },
+                metadata: {
+                    method: reply.method,
+                    backend: 'grabcut',
+                    durationMs: Math.max(0, performance.now() - started),
+                    input: { width: image.width, height: image.height },
+                },
+            };
+        },
+        settle: () => pool.settle(),
+        dispose: () => pool.dispose(),
+    };
+}
+function snapshotInput(input) {
+    const image = input.image;
+    const pixels = image.width * image.height;
+    const prompt = input.prompt ?? 'whole-region';
+    if (image.format !== 'rgba8' ||
+        !Number.isSafeInteger(image.width) ||
+        !Number.isSafeInteger(image.height) ||
+        !Number.isSafeInteger(pixels) ||
+        image.width < 1 ||
+        image.height < 1 ||
+        pixels > limits.imagePixels ||
+        image.data.length !== pixels * 4)
+        throw new ClassifierError('INVALID_INPUT', 'Segmentation requires canonical RGBA8 within the image pixel limit');
+    if ((prompt !== 'whole-region' && prompt !== 'seed-region') ||
+        !pixelRectSchema.safeParse(input.seedRegion).success ||
+        !pixelRectSchema.safeParse(input.wholeRegion).success ||
+        !pixelRectSchema.safeParse(input.roi).success)
+        throw new ClassifierError('INVALID_INPUT', 'Segmentation regions must be positive integer rectangles');
+    for (const region of [input.seedRegion, input.wholeRegion, input.roi])
+        if (region.left + region.width > image.width || region.top + region.height > image.height)
+            throw new ClassifierError('INVALID_INPUT', 'Segmentation region lies outside the source image');
+    return {
+        data: new Uint8Array(image.data),
+        width: image.width,
+        height: image.height,
+        seedRegion: { ...input.seedRegion },
+        wholeRegion: { ...input.wholeRegion },
+        roi: { ...input.roi },
+        prompt,
+    };
+}

package/dist/infrastructure/segmentation/grabcut/worker-inference.d.ts

@@ -0,0 +1,47 @@
+import type { NativeSegmentationReply, NativeSegmentationRequest } from '../native-protocol.js';
+export declare function probeGrabCut(assetPath: string): Promise<void>;
+export declare function initializeGrabCutMask(input: {
+    flags: Uint8Array;
+    width: number;
+    height: number;
+    seedRegion: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    wholeRegion: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    roi: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    prompt: 'whole-region' | 'seed-region';
+    labels: {
+        background: number;
+        foreground: number;
+        probableBackground: number;
+        probableForeground: number;
+    };
+}): void;
+/** Run native GrabCut, then reacquire Mat.data before copying its post-call flags. */
+export declare function runGrabCutAndCopyMask(mat: {
+    data?: unknown;
+}, width: number, height: number, roi: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, runNative: () => void, labels: {
+    foreground: number;
+    probableForeground: number;
+}): Uint8Array;
+export declare function runGrabCutTask(request: Extract<NativeSegmentationRequest, {
+    kind: 'grabcut';
+}>): Promise<NativeSegmentationReply>;