zorya-classifier 0.1.0 → 0.2.1

package/dist/features/segmentation/mask.js

@@ -0,0 +1,89 @@
+export function validateMask(mask, image, roi, seed) {
+    const pixels = image.width * image.height;
+    if (!Number.isSafeInteger(pixels) ||
+        pixels < 1 ||
+        pixels > 16_777_216 ||
+        image.data.length !== pixels * 4 ||
+        mask.format !== 'binary-u8' ||
+        mask.width !== image.width ||
+        mask.height !== image.height ||
+        mask.data.length !== pixels ||
+        !inside(roi, image.width, image.height) ||
+        !inside(seed, image.width, image.height) ||
+        !intersects(roi, seed))
+        throw new TypeError('Segmentation dimensions or bounds do not match the canonical image');
+    let left = image.width;
+    let top = image.height;
+    let right = -1;
+    let bottom = -1;
+    let intersectsSeed = false;
+    for (let y = 0; y < image.height; y++) {
+        for (let x = 0; x < image.width; x++) {
+            const value = mask.data[y * image.width + x];
+            if (value !== 0 && value !== 1)
+                throw new TypeError('Mask values must be binary 0 or 1');
+            if (value !== 1)
+                continue;
+            if (x < roi.left || y < roi.top || x >= roi.left + roi.width || y >= roi.top + roi.height)
+                throw new TypeError('Mask contains pixels outside the hard ROI');
+            const alpha = image.data[(y * image.width + x) * 4 + 3];
+            if (alpha === undefined || alpha === 0)
+                continue;
+            left = Math.min(left, x);
+            top = Math.min(top, y);
+            right = Math.max(right, x);
+            bottom = Math.max(bottom, y);
+            if (x >= seed.left &&
+                y >= seed.top &&
+                x < seed.left + seed.width &&
+                y < seed.top + seed.height)
+                intersectsSeed = true;
+        }
+    }
+    if (right < left || !intersectsSeed)
+        return undefined;
+    return { left, top, width: right - left + 1, height: bottom - top + 1 };
+}
+export function cropMask(mask, box) {
+    const data = new Uint8Array(box.width * box.height);
+    for (let y = 0; y < box.height; y++) {
+        const from = (box.top + y) * mask.width + box.left;
+        data.set(mask.data.subarray(from, from + box.width), y * box.width);
+    }
+    return { data, width: box.width, height: box.height, format: 'binary-u8' };
+}
+export function maskedRgba(image, mask, box) {
+    const output = new Uint8Array(box.width * box.height * 4);
+    for (let y = 0; y < box.height; y++) {
+        for (let x = 0; x < box.width; x++) {
+            const sourceIndex = (box.top + y) * image.width + box.left + x;
+            if (mask.data[sourceIndex] !== 1)
+                continue;
+            const source = sourceIndex * 4;
+            const target = (y * box.width + x) * 4;
+            output[target] = image.data[source] ?? 0;
+            output[target + 1] = image.data[source + 1] ?? 0;
+            output[target + 2] = image.data[source + 2] ?? 0;
+            output[target + 3] = image.data[source + 3] ?? 0;
+        }
+    }
+    return output;
+}
+function inside(rect, width, height) {
+    return (Number.isSafeInteger(rect.left) &&
+        Number.isSafeInteger(rect.top) &&
+        Number.isSafeInteger(rect.width) &&
+        Number.isSafeInteger(rect.height) &&
+        rect.left >= 0 &&
+        rect.top >= 0 &&
+        rect.width > 0 &&
+        rect.height > 0 &&
+        rect.left + rect.width <= width &&
+        rect.top + rect.height <= height);
+}
+function intersects(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);
+}

package/dist/features/segmentation/packed-mask.d.ts

@@ -0,0 +1,5 @@
+import { type PackedBinaryMask } from '../../entities/object-proposals.js';
+/** Pack row-major binary pixels into bytes, least-significant bit first. */
+export declare function packBinaryMask(mask: Uint8Array, width: number, height: number): PackedBinaryMask;
+/** Validate and unpack an owned LSB-first mask into one byte per source pixel. */
+export declare function unpackBinaryMask(mask: PackedBinaryMask): Uint8Array;

package/dist/features/segmentation/packed-mask.js

@@ -0,0 +1,53 @@
+import { ClassifierError } from '../../entities/errors.js';
+import { objectProposalLimits } from '../../entities/object-proposals.js';
+/** Pack row-major binary pixels into bytes, least-significant bit first. */
+export function packBinaryMask(mask, width, height) {
+    const pixels = checkedPixelCount(width, height);
+    if (!(mask instanceof Uint8Array) || mask.length !== pixels)
+        throw new ClassifierError('INVALID_INPUT', 'Binary mask dimensions do not match its pixels');
+    const data = new Uint8Array(Math.ceil(pixels / 8));
+    if (data.byteLength > objectProposalLimits.packedBytes)
+        throw new ClassifierError('RESOURCE_LIMIT', 'Packed binary mask exceeds its byte limit');
+    for (let index = 0; index < pixels; index++) {
+        const value = mask[index];
+        if (value !== 0 && value !== 1)
+            throw new ClassifierError('INVALID_RESPONSE', 'Binary mask pixels must be zero or one');
+        if (value === 1)
+            data[index >> 3] = (data[index >> 3] ?? 0) | (1 << (index & 7));
+    }
+    return { data, width, height, format: 'binary-lsb0' };
+}
+/** Validate and unpack an owned LSB-first mask into one byte per source pixel. */
+export function unpackBinaryMask(mask) {
+    if (typeof mask !== 'object' ||
+        mask === null ||
+        mask.format !== 'binary-lsb0' ||
+        !(mask.data instanceof Uint8Array))
+        throw new ClassifierError('INVALID_RESPONSE', 'Packed mask format is invalid');
+    const pixels = checkedPixelCount(mask.width, mask.height, 'INVALID_RESPONSE');
+    const expectedBytes = Math.ceil(pixels / 8);
+    if (mask.data.length !== expectedBytes || mask.data.byteLength > objectProposalLimits.packedBytes)
+        throw new ClassifierError('INVALID_RESPONSE', 'Packed mask length does not match its dimensions');
+    const unusedBits = expectedBytes * 8 - pixels;
+    if (unusedBits > 0) {
+        const allowed = (1 << (8 - unusedBits)) - 1;
+        const last = mask.data[expectedBytes - 1];
+        if (last === undefined || (last & ~allowed) !== 0)
+            throw new ClassifierError('INVALID_RESPONSE', 'Packed mask has nonzero padding bits');
+    }
+    const output = new Uint8Array(pixels);
+    for (let index = 0; index < pixels; index++)
+        output[index] = ((mask.data[index >> 3] ?? 0) >> (index & 7)) & 1;
+    return output;
+}
+function checkedPixelCount(width, height, errorCode = 'INVALID_INPUT') {
+    const pixels = width * height;
+    if (!Number.isSafeInteger(width) ||
+        !Number.isSafeInteger(height) ||
+        width < 1 ||
+        height < 1 ||
+        !Number.isSafeInteger(pixels) ||
+        pixels > objectProposalLimits.imagePixels)
+        throw new ClassifierError(errorCode, 'Binary mask dimensions exceed the proposal limit');
+    return pixels;
+}

package/dist/index.d.ts

@@ -2,4 +2,9 @@ export { createClassifier } from './app/create-classifier.js';
 export type { Classifier, ClassifierOptions } from './app/create-classifier.js';
 export { ClassifierError } from './entities/errors.js';
 export type { ErrorCode } from './entities/errors.js';
-export type { ClassifyInput, LocateInput, ClassificationResult, LocalizationResult, ClassDefinition, ChoiceSelection, DecisionPort, DecisionRequest, DecisionResult, DecisionState, DecisionMetadata, PixelRect, RefinementPort, RefinementResult, } from './entities/contracts.js';
+export type { ClassifyInput, LocateInput, ClassificationResult, LocalizationResult, ClassDefinition, ChoiceSelection, DecisionPort, DecisionRequest, DecisionResult, DecisionState, DecisionMetadata, PixelRect, RefinementPort, RefinementResult, LocalizationMetadata, Representation, } from './entities/contracts.js';
+export type { RegionLocateInput, WholeObjectLocateInput, AnyLocateInput, BoundaryInterval, ObjectBounds, WholeObjectLocated, WholeObjectFailure, WholeObjectLocalizationResult, } from './entities/whole-object.js';
+export type { RgbaRaster, RepresentationView, RepresentationMetadata, ImageRepresentationPort, } from './entities/representation.js';
+export type { BinaryMask, SegmentationInput, SegmentationMetadata, SegmentationResult, SegmentationPort, ExtractionResult, ExtractInput, } from './entities/segmentation.js';
+export type { SegmentationBoxCheckInput, SegmentationBoxCheckResult, SegmentationBoxVerdict, SegmentationBoxCheckPort, SegmentationBoxPresentationPort, SegmentationVerification, } from './entities/segmentation-verification.js';
+export type { PackedBinaryMask, ObjectProposal, ObjectProposalInput, ObjectProposalBatch, ObjectProposalPort, } from './entities/object-proposals.js';

package/dist/infrastructure/boundary-view.d.ts

@@ -0,0 +1,2 @@
+import type { BoundaryViewPort } from '../entities/boundary-view.js';
+export declare function createSharpBoundaryView(): BoundaryViewPort;

package/dist/infrastructure/boundary-view.js

@@ -0,0 +1,263 @@
+import sharp from 'sharp';
+import { z } from 'zod';
+import { limits, pixelRectSchema } from '../entities/contracts.js';
+import { ClassifierError, assertActive } from '../entities/errors.js';
+const sourceSchema = z
+    .object({
+    bytes: z
+        .custom((v) => v instanceof Uint8Array)
+        .refine((v) => v.byteLength > 0 && v.byteLength <= limits.imageBytes),
+    width: z.number().int().positive().max(16384),
+    height: z.number().int().positive().max(16384),
+})
+    .strict();
+const candidateSchema = z
+    .object({
+    id: z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^[A-Za-z][A-Za-z0-9_-]*$/),
+    display: z
+        .string()
+        .min(1)
+        .max(8)
+        .regex(/^[A-Za-z0-9_-]+$/),
+    interval: z
+        .object({
+        start: z.number().int().nonnegative().safe(),
+        endExclusive: z.number().int().positive().safe(),
+    })
+        .strict()
+        .refine((v) => v.start < v.endExclusive),
+})
+    .strict();
+const inputSchema = z
+    .object({
+    source: sourceSchema,
+    sourceRegion: pixelRectSchema,
+    axis: z.enum(['left', 'right', 'top', 'bottom']),
+    candidates: z.array(candidateSchema).min(1).max(16),
+    signal: z.custom((v) => v instanceof AbortSignal),
+})
+    .strict();
+const maxContentSide = 1280;
+const maxOutputSide = 1567;
+const axisGutter = 210;
+const outerGutter = 10;
+const maxRenderedBytes = limits.imageBytes;
+function contained(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);
+}
+function escapeXml(value) {
+    return value.replace(/[&<>"']/gu, (char) => {
+        switch (char) {
+            case '&':
+                return '&amp;';
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case '"':
+                return '&quot;';
+            default:
+                return '&apos;';
+        }
+    });
+}
+function failInput(message) {
+    throw new ClassifierError('INVALID_INPUT', message, { component: 'boundary-view' });
+}
+function validate(input) {
+    const parsed = inputSchema.safeParse(input);
+    if (!parsed.success)
+        failInput('Invalid boundary-view request');
+    const value = parsed.data;
+    if (value.source.width * value.source.height > limits.imagePixels)
+        throw new ClassifierError('RESOURCE_LIMIT', 'Source raster exceeds pixel limits', {
+            component: 'boundary-view',
+        });
+    const full = { left: 0, top: 0, width: value.source.width, height: value.source.height };
+    if (!contained(full, value.sourceRegion))
+        failInput('Source region lies outside the oriented image');
+    const xAxis = value.axis === 'left' || value.axis === 'right';
+    const axisSize = xAxis ? value.source.width : value.source.height;
+    const axisStart = xAxis ? value.sourceRegion.left : value.sourceRegion.top;
+    const axisEnd = axisStart + (xAxis ? value.sourceRegion.width : value.sourceRegion.height);
+    const ids = new Set();
+    const displays = new Set();
+    let priorEnd = -1;
+    for (const candidate of value.candidates) {
+        if (ids.has(candidate.id) || displays.has(candidate.display))
+            failInput('Boundary candidate IDs and display labels must be unique');
+        ids.add(candidate.id);
+        displays.add(candidate.display);
+        if (candidate.interval.endExclusive > axisSize)
+            failInput('Boundary interval lies outside the oriented source');
+        if (candidate.interval.start < axisStart || candidate.interval.endExclusive > axisEnd)
+            failInput('Boundary interval lies outside the source region');
+        if (candidate.interval.start < priorEnd)
+            failInput('Boundary intervals must be ordered and non-overlapping');
+        priorEnd = candidate.interval.endExclusive;
+    }
+    return value;
+}
+function svgOverlay(axis, candidates, region, contentWidth, contentHeight, contentLeft, contentTop, outputWidth, outputHeight) {
+    const vertical = axis === 'left' || axis === 'right';
+    const axisLength = vertical ? region.width : region.height;
+    const outputLength = vertical ? contentWidth : contentHeight;
+    const sourceOffset = vertical ? region.left : region.top;
+    const unit = outputLength / axisLength;
+    const strokes = [];
+    // Presentation is tied to the coordinate dimension, never to the semantic side being located.
+    const color = vertical ? '#ff6b5f' : '#49d6a1';
+    const title = vertical ? 'X coordinates' : 'Y coordinates';
+    strokes.push(vertical
+        ? `<text x="${outputWidth - outerGutter - 2}" y="${outerGutter + 10}" text-anchor="end" font-family="DejaVu Sans,sans-serif" font-size="9" fill="#f3f4f6">${title}</text>`
+        : `<text x="${outerGutter}" y="${outerGutter + 10}" font-family="DejaVu Sans,sans-serif" font-size="9" fill="#f3f4f6">${title}</text>`);
+    const positions = candidates.map((candidate) => {
+        const begin = (candidate.interval.start - sourceOffset) * unit;
+        const end = (candidate.interval.endExclusive - sourceOffset) * unit;
+        return (begin + end) / 2;
+    });
+    const labelBaselines = vertical
+        ? (() => {
+            const pitch = 12;
+            const lanes = [];
+            const rightEdges = [];
+            return candidates.map((candidate, index) => {
+                const center = contentLeft + (positions[index] ?? 0);
+                const width = candidate.display.length * 7 + 6;
+                let lane = rightEdges.findIndex((right) => right + 3 <= center - width / 2);
+                if (lane < 0) {
+                    lane = rightEdges.length;
+                    rightEdges.push(Number.NEGATIVE_INFINITY);
+                }
+                rightEdges[lane] = center + width / 2;
+                lanes[index] = lane;
+                return contentTop - 5 - (lane + 1) * pitch;
+            });
+        })()
+        : (() => {
+            const min = outerGutter + 10;
+            const max = outputHeight - outerGutter - 3;
+            const pitch = 12;
+            const desired = positions.map((position) => contentTop + position + 4);
+            const placed = desired.map((position) => Math.max(min, Math.min(max, position)));
+            for (let index = 1; index < placed.length; index++)
+                placed[index] = Math.max(placed[index] ?? min, (placed[index - 1] ?? min) + pitch);
+            if ((placed.at(-1) ?? max) > max) {
+                placed[placed.length - 1] = max;
+                for (let index = placed.length - 2; index >= 0; index--)
+                    placed[index] = Math.min(placed[index] ?? max, (placed[index + 1] ?? max) - pitch);
+            }
+            return placed;
+        })();
+    for (const [index, candidate] of candidates.entries()) {
+        const start = (candidate.interval.start - sourceOffset) * unit;
+        const end = (candidate.interval.endExclusive - sourceOffset) * unit;
+        const lo = Math.min(start, end);
+        const hi = Math.max(start, end);
+        const midpoint = (lo + hi) / 2;
+        const label = escapeXml(candidate.display);
+        if (vertical) {
+            const center = contentLeft + midpoint;
+            const halfWidth = candidate.display.length * 3.5 + 3;
+            const labelCenter = Math.max(contentLeft + halfWidth, Math.min(contentLeft + contentWidth - halfWidth, center));
+            const baseline = labelBaselines[index] ?? contentTop - 17;
+            strokes.push(`<rect x="${contentLeft + lo}" y="${contentTop}" width="${Math.max(1, hi - lo)}" height="${contentHeight}" fill="${color}" fill-opacity="0.045"/>`, `<line x1="${contentLeft + start}" y1="${contentTop}" x2="${contentLeft + start}" y2="${contentTop + contentHeight}" stroke="${color}" stroke-opacity="0.9" stroke-width="2"/>`, `<line x1="${contentLeft + end}" y1="${contentTop}" x2="${contentLeft + end}" y2="${contentTop + contentHeight}" stroke="${color}" stroke-opacity="0.9" stroke-width="2"/>`, `<path d="M ${center} ${contentTop} L ${center} ${baseline + 4} L ${labelCenter} ${baseline + 4}" fill="none" stroke="${color}" stroke-width="1"/>`, `<text x="${labelCenter}" y="${baseline}" text-anchor="middle" font-family="DejaVu Sans,sans-serif" font-size="10" font-weight="bold" fill="${color}">${label}</text>`);
+        }
+        else {
+            const midpointY = contentTop + midpoint;
+            const baseline = labelBaselines[index] ?? midpointY + 4;
+            const elbowX = contentLeft - 12 - index * 3;
+            const labelX = contentLeft - 82;
+            strokes.push(`<rect x="${contentLeft}" y="${contentTop + lo}" width="${contentWidth}" height="${Math.max(1, hi - lo)}" fill="${color}" fill-opacity="0.045"/>`, `<line x1="${contentLeft}" y1="${contentTop + start}" x2="${contentLeft + contentWidth}" y2="${contentTop + start}" stroke="${color}" stroke-opacity="0.9" stroke-width="2"/>`, `<line x1="${contentLeft}" y1="${contentTop + end}" x2="${contentLeft + contentWidth}" y2="${contentTop + end}" stroke="${color}" stroke-opacity="0.9" stroke-width="2"/>`, `<path d="M ${contentLeft} ${midpointY} L ${elbowX} ${midpointY} L ${elbowX} ${baseline} L ${labelX + 4} ${baseline}" fill="none" stroke="${color}" stroke-width="1"/>`, `<text x="${labelX}" y="${baseline}" text-anchor="end" font-family="DejaVu Sans,sans-serif" font-size="10" font-weight="bold" fill="${color}">${label}</text>`);
+        }
+    }
+    const sourceBounds = `<rect x="${contentLeft}" y="${contentTop}" width="${contentWidth}" height="${contentHeight}" fill="none" stroke="#f3f4f6" stroke-opacity="0.65" stroke-width="1"/>`;
+    return Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${outputWidth}" height="${outputHeight}">${sourceBounds}${strokes.join('')}</svg>`);
+}
+async function render(input) {
+    assertActive(input.signal);
+    const value = validate(input);
+    assertActive(value.signal);
+    // Sharp retains its input through an asynchronous pipeline; take ownership before awaiting.
+    const ownedBytes = Buffer.from(value.source.bytes);
+    const candidates = value.candidates.map((candidate) => ({
+        id: candidate.id,
+        display: candidate.display,
+        interval: { ...candidate.interval },
+    }));
+    const { sourceRegion: region } = value;
+    const scale = Math.min(maxContentSide / Math.max(region.width, region.height), Math.max(1, 768 / Math.min(region.width, region.height)));
+    const contentWidth = Math.max(1, Math.round(region.width * scale));
+    const contentHeight = Math.max(1, Math.round(region.height * scale));
+    const vertical = value.axis === 'left' || value.axis === 'right';
+    const contentLeft = vertical ? outerGutter : axisGutter;
+    const contentTop = vertical ? axisGutter : outerGutter;
+    const outputWidth = Math.max(280, contentLeft + contentWidth + outerGutter);
+    const outputHeight = Math.max(280, contentTop + contentHeight + outerGutter);
+    if (outputWidth > maxOutputSide || outputHeight > maxOutputSide)
+        throw new ClassifierError('RESOURCE_LIMIT', 'Boundary view exceeds output side limit', {
+            component: 'boundary-view',
+        });
+    const pixels = outputWidth * outputHeight;
+    if (pixels > limits.imagePixels)
+        throw new ClassifierError('RESOURCE_LIMIT', 'Boundary view exceeds output pixel limit', {
+            component: 'boundary-view',
+        });
+    const overlay = svgOverlay(value.axis, candidates, region, contentWidth, contentHeight, contentLeft, contentTop, outputWidth, outputHeight);
+    if (overlay.byteLength > 128 * 1024)
+        throw new ClassifierError('RESOURCE_LIMIT', 'Boundary overlay exceeds byte budget', {
+            component: 'boundary-view',
+        });
+    let pipeline;
+    try {
+        assertActive(value.signal);
+        pipeline = sharp(ownedBytes, { limitInputPixels: limits.imagePixels, failOn: 'error' })
+            .extract(region)
+            .resize(contentWidth, contentHeight, { kernel: 'nearest' })
+            .extend({
+            left: contentLeft,
+            top: contentTop,
+            right: outputWidth - contentLeft - contentWidth,
+            bottom: outputHeight - contentTop - contentHeight,
+            background: { r: 17, g: 24, b: 39, alpha: 1 },
+        })
+            .composite([{ input: overlay }]);
+        const result = await pipeline.png().toBuffer();
+        assertActive(value.signal);
+        if (result.byteLength > maxRenderedBytes)
+            throw new ClassifierError('RESOURCE_LIMIT', 'Rendered boundary view exceeds byte limit', {
+                component: 'boundary-view',
+            });
+        return {
+            image: { bytes: result, width: outputWidth, height: outputHeight },
+            sourceRegion: { ...region },
+            content: { left: contentLeft, top: contentTop, width: contentWidth, height: contentHeight },
+            scaleX: contentWidth / region.width,
+            scaleY: contentHeight / region.height,
+            candidates,
+        };
+    }
+    catch (error) {
+        assertActive(value.signal);
+        if (error instanceof ClassifierError)
+            throw error;
+        throw new ClassifierError('INVALID_INPUT', 'Boundary view could not be rendered', {
+            component: 'boundary-view',
+        });
+    }
+    finally {
+        pipeline?.destroy();
+        ownedBytes.fill(0);
+        overlay.fill(0);
+    }
+}
+export function createSharpBoundaryView() {
+    return { render };
+}

package/dist/infrastructure/openrouter-common.d.ts

@@ -85,6 +85,13 @@ export declare const requestSchema: z.ZodObject<{
         instructions: string;
     }>>;
 }, "strict", z.ZodTypeAny, {
+    state: (string | {
+        type: "image_url";
+        image_url: {
+            url: string;
+            detail: "high";
+        };
+    })[];
     questions: Record<string, {
         type: "choice";
         instructions: string;
@@ -94,6 +101,7 @@ export declare const requestSchema: z.ZodObject<{
         type: "noul";
         instructions: string;
     }>;
+}, {
     state: (string | {
         type: "image_url";
         image_url: {
@@ -101,7 +109,6 @@ export declare const requestSchema: z.ZodObject<{
             detail: "high";
         };
     })[];
-}, {
     questions: Record<string, {
         type: "choice";
         instructions: string;
@@ -111,13 +118,6 @@ export declare const requestSchema: z.ZodObject<{
         type: "noul";
         instructions: string;
     }>;
-    state: (string | {
-        type: "image_url";
-        image_url: {
-            url: string;
-            detail: "high";
-        };
-    })[];
 }>;
 export declare function ownedError(code: ErrorCode, message: string, details?: Readonly<Record<string, unknown>>): ClassifierError;
 export declare function invalid(code: 'INVALID_INPUT' | 'INVALID_RESPONSE', message: string): ClassifierError;

package/dist/infrastructure/openrouter-vision.d.ts

@@ -6,3 +6,6 @@ export interface OpenRouterVisionOptions extends Omit<VisionChatOptions, 'endpoi
 }
 /** Optional OpenRouter routing wrapper over the ordinary chat-completions adapter. */
 export declare function createOpenRouterVision(input: OpenRouterVisionOptions): DecisionPort;
+export type OpenRouterTextOptions = OpenRouterVisionOptions;
+/** Same strict chat protocol; rejects image parts before transport. */
+export declare function createOpenRouterText(input: OpenRouterTextOptions): DecisionPort;

package/dist/infrastructure/openrouter-vision.js

@@ -10,3 +10,8 @@ export function createOpenRouterVision(input) {
     const options = validated(schema, input, 'INVALID_INPUT');
     return createVisionChat({ ...options, endpoint: 'https://openrouter.ai/api/v1/chat/completions' });
 }
+/** Same strict chat protocol; rejects image parts before transport. */
+export function createOpenRouterText(input) {
+    const options = validated(schema, input, 'INVALID_INPUT');
+    return createVisionChat({ ...options, endpoint: 'https://openrouter.ai/api/v1/chat/completions' }, 'text');
+}

package/dist/infrastructure/raster.d.ts

@@ -1,2 +1,11 @@
-import type { RasterPort } from '../entities/contracts.js';
+import type { RasterImage, RasterPort } from '../entities/contracts.js';
+import type { ImageRepresentationPort } from '../entities/representation.js';
 export declare function createSharpRaster(): RasterPort;
+/** Decode an oriented raster into the canonical RGBA8 pixel layout used by adapters. */
+export declare function readCanonicalPixels(image: RasterImage, signal: AbortSignal): Promise<{
+    data: Uint8Array;
+    width: number;
+    height: number;
+}>;
+/** Vision adapter that retains the existing sharp imageState layout for every supplied view. */
+export declare function createVisionRepresentation(raster: RasterPort): ImageRepresentationPort;

package/dist/infrastructure/raster.js

@@ -1,5 +1,6 @@
 import sharp from 'sharp';
-import { limits } from '../entities/contracts.js';
+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 &&
@@ -15,10 +16,16 @@ async function normalizeImage(bytes, signal) {
         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().png().toBuffer({ resolveWithObject: true });
+        const normalized = await pipeline
+            .rotate()
+            .ensureAlpha()
+            .png()
+            .toBuffer({ resolveWithObject: true });
         assertActive(signal);
-        if (normalized.data.byteLength > limits.imageBytes)
-            throw new ClassifierError('RESOURCE_LIMIT', 'Decoded presentation exceeds image byte limit');
+        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) {
@@ -119,3 +126,91 @@ async function renderGrid(image, region, cells, labels, signal) {
 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;