zorya-classifier 0.1.0 → 0.2.1

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

@@ -0,0 +1,371 @@
+import sharp from 'sharp';
+import { ClassifierError, assertActive } from '../../entities/errors.js';
+import { objectProposalLimits } from '../../entities/object-proposals.js';
+import { unpackBinaryMask } from '../../features/segmentation/packed-mask.js';
+const columns = 4;
+const rows = 3;
+const tileWidth = 300;
+const tileHeight = 240;
+const sheetWidth = columns * tileWidth;
+const sheetHeight = rows * tileHeight;
+const previewWidth = 142;
+const previewHeight = 200;
+const previewTop = 28;
+const previewLeft = 4;
+/** Generic, bounded rendering for already-validated object mask aliases. */
+export function createSharpObjectProposalPresentation() {
+    return {
+        async render(input) {
+            const signal = input.signal;
+            assertSignal(signal);
+            const callerImage = input.image;
+            assertImage(callerImage);
+            const callerSeedRegion = input.seedRegion;
+            assertRect(callerSeedRegion, callerImage.width, callerImage.height, 'seedRegion');
+            const image = {
+                data: new Uint8Array(callerImage.data),
+                width: callerImage.width,
+                height: callerImage.height,
+                format: callerImage.format,
+            };
+            const seedRegion = { ...callerSeedRegion };
+            const proposals = input.proposals;
+            if (!Array.isArray(proposals) ||
+                proposals.length < 1 ||
+                proposals.length > objectProposalLimits.candidates)
+                throw invalid('Expected 1..36 object proposals');
+            // Own every buffer synchronously, before the first Sharp await.
+            const source = image.data;
+            let previousAlias = -1;
+            for (const proposal of proposals) {
+                const match = typeof proposal.id === 'string' ? /^C(\d{2})$/.exec(proposal.id) : null;
+                const alias = match ? Number(match[1]) : -1;
+                if (alias < 0 || alias >= objectProposalLimits.candidates || alias <= previousAlias)
+                    throw invalid('Proposal aliases must be unique and retain source order');
+                previousAlias = alias;
+            }
+            const snapshots = proposals.map((proposal) => snapshotProposal(proposal, image));
+            if (snapshots.reduce((sum, item) => sum + item.data.byteLength, 0) >
+                objectProposalLimits.packedBytes)
+                throw invalid('Packed proposal data exceeds the byte limit');
+            assertActive(signal);
+            const output = [];
+            let totalBytes = 0;
+            const pushPng = (bytes) => {
+                assertActive(signal);
+                if (bytes.byteLength > objectProposalLimits.presentationBytes)
+                    throw invalid('Proposal presentation image exceeds the byte limit');
+                totalBytes += bytes.byteLength;
+                if (totalBytes > objectProposalLimits.presentationBytes)
+                    throw invalid('Proposal presentation exceeds the total byte limit');
+                output.push(new Uint8Array(bytes));
+            };
+            const seedSvg = Buffer.from(`<svg width="${image.width}" height="${image.height}" xmlns="http://www.w3.org/2000/svg"><rect x="${seedRegion.left}" y="${seedRegion.top}" width="${seedRegion.width}" height="${seedRegion.height}" fill="none" stroke="#1677ff" stroke-width="2"/></svg>`);
+            const seedPng = await encode(sharp(source, {
+                raw: { width: image.width, height: image.height, channels: 4 },
+                limitInputPixels: objectProposalLimits.imagePixels,
+            })
+                .composite([{ input: seedSvg }])
+                .png({ compressionLevel: 6 }), signal);
+            pushPng(seedPng);
+            if (snapshots.length === 1) {
+                const proposal = snapshots[0];
+                if (!proposal)
+                    throw invalid('Singleton proposal disappeared during presentation');
+                const raster = unpackBinaryMask({
+                    data: proposal.data,
+                    width: image.width,
+                    height: image.height,
+                    format: 'binary-lsb0',
+                });
+                const overlay = makeOverlay(source, raster, image.width, image.height, proposal.bounds);
+                const overlayPng = await encode(sharp(overlay, {
+                    raw: { width: image.width, height: image.height, channels: 4 },
+                    limitInputPixels: objectProposalLimits.imagePixels,
+                }).png({ compressionLevel: 6 }), signal);
+                pushPng(overlayPng);
+                if (output.length !== 2)
+                    throw invalid('Singleton presentation returned an invalid image count');
+                return output;
+            }
+            const sourcePreview = await encode(sharp(source, {
+                raw: { width: image.width, height: image.height, channels: 4 },
+                limitInputPixels: objectProposalLimits.imagePixels,
+            })
+                .resize(previewWidth, previewHeight, {
+                fit: 'contain',
+                background: { r: 20, g: 24, b: 32, alpha: 1 },
+            })
+                .png(), signal);
+            const sheetCount = Math.ceil(snapshots.length / 12);
+            for (let sheetIndex = 0; sheetIndex < sheetCount; sheetIndex++) {
+                assertActive(signal);
+                const sheet = Buffer.alloc(sheetWidth * sheetHeight * 4, 0);
+                const layers = [];
+                const countOnSheet = Math.min(12, snapshots.length - sheetIndex * 12);
+                for (let position = 0; position < countOnSheet; position++) {
+                    const proposal = snapshots[sheetIndex * 12 + position];
+                    if (!proposal)
+                        throw invalid('Proposal list changed during presentation');
+                    assertActive(signal);
+                    const tileX = (position % columns) * tileWidth;
+                    const tileY = Math.floor(position / columns) * tileHeight;
+                    const rectangle = proposal.bounds
+                        ? `RECT [${proposal.bounds.left}, ${proposal.bounds.top}, ${proposal.bounds.width}, ${proposal.bounds.height}]`
+                        : 'RECT empty';
+                    const title = svg(tileWidth, 40, `<rect width="300" height="40" fill="#f2f4f7"/><text x="8" y="16" font-family="sans-serif" font-size="14" fill="#111">${proposal.id}</text><text x="8" y="33" font-family="sans-serif" font-size="12" fill="#111">${rectangle}</text>`);
+                    layers.push({ input: title, left: tileX, top: tileY });
+                    const raster = unpackBinaryMask({
+                        data: proposal.data,
+                        width: image.width,
+                        height: image.height,
+                        format: 'binary-lsb0',
+                    });
+                    const bounds = proposal.bounds;
+                    if (bounds !== null) {
+                        const maskOverlay = makeOverlay(source, raster, image.width, image.height, bounds);
+                        const overlayPreview = await encode(sharp(maskOverlay, {
+                            raw: { width: image.width, height: image.height, channels: 4 },
+                            limitInputPixels: objectProposalLimits.imagePixels,
+                        })
+                            .resize(previewWidth, previewHeight, {
+                            fit: 'contain',
+                            background: { r: 20, g: 24, b: 32, alpha: 1 },
+                        })
+                            .png(), signal);
+                        assertActive(signal);
+                        layers.push({
+                            input: sourcePreview,
+                            left: tileX + previewLeft,
+                            top: tileY + previewTop + 12,
+                        });
+                        layers.push({
+                            input: overlayPreview,
+                            left: tileX + previewLeft,
+                            top: tileY + previewTop + 12,
+                        });
+                        const cutout = makeCutout(source, raster, image.width, image.height, bounds);
+                        const cutoutPng = await encode(sharp(cutout.data, {
+                            raw: { width: cutout.width, height: cutout.height, channels: 4 },
+                        })
+                            .resize(previewWidth, previewHeight, {
+                            fit: 'contain',
+                            background: { r: 20, g: 24, b: 32, alpha: 0 },
+                        })
+                            .png(), signal);
+                        assertActive(signal);
+                        layers.push({
+                            input: cutoutPng,
+                            left: tileX + previewLeft + previewWidth + 8,
+                            top: tileY + previewTop + 12,
+                        });
+                    }
+                    else {
+                        layers.push({
+                            input: sourcePreview,
+                            left: tileX + previewLeft,
+                            top: tileY + previewTop + 12,
+                        });
+                        layers.push({
+                            input: svg(previewWidth, previewHeight, '<rect width="142" height="200" fill="#f2f4f7"/><text x="71" y="104" text-anchor="middle" font-family="sans-serif" font-size="16" fill="#555">empty</text>'),
+                            left: tileX + previewLeft + previewWidth + 8,
+                            top: tileY + previewTop + 12,
+                        });
+                    }
+                }
+                const sheetPng = await encode(sharp(sheet, {
+                    raw: { width: sheetWidth, height: sheetHeight, channels: 4 },
+                })
+                    .composite(layers)
+                    .png({ compressionLevel: 6 }), signal);
+                pushPng(sheetPng);
+            }
+            if (output.length !== sheetCount + 1 ||
+                output.length > objectProposalLimits.presentationImages)
+                throw invalid('Proposal presentation returned an invalid image count');
+            return output;
+        },
+    };
+}
+function assertSignal(signal) {
+    if (!(signal instanceof AbortSignal))
+        throw invalid('signal must be an AbortSignal');
+    assertActive(signal);
+}
+function assertImage(image) {
+    if (image.format !== 'rgba8' ||
+        !Number.isSafeInteger(image.width) ||
+        !Number.isSafeInteger(image.height) ||
+        image.width < 1 ||
+        image.height < 1 ||
+        image.width * image.height > objectProposalLimits.imagePixels ||
+        image.data.length !== image.width * image.height * 4)
+        throw invalid('Expected canonical RGBA image within proposal limits');
+}
+function assertRect(rect, width, height, name) {
+    if (!rect ||
+        !Number.isSafeInteger(rect.left) ||
+        !Number.isSafeInteger(rect.top) ||
+        !Number.isSafeInteger(rect.width) ||
+        !Number.isSafeInteger(rect.height) ||
+        rect.left < 0 ||
+        rect.top < 0 ||
+        rect.width < 1 ||
+        rect.height < 1 ||
+        rect.left + rect.width > width ||
+        rect.top + rect.height > height)
+        throw invalid(`${name} is outside the source image`);
+}
+function snapshotProposal(proposal, image) {
+    const id = proposal.id;
+    const mask = proposal.mask;
+    const expectedBytes = Math.ceil((image.width * image.height) / 8);
+    if (!/^C(?:0[0-9]|[12][0-9]|3[0-5])$/.test(id) ||
+        !mask ||
+        mask.format !== 'binary-lsb0' ||
+        mask.width !== image.width ||
+        mask.height !== image.height ||
+        !(mask.data instanceof Uint8Array) ||
+        mask.data.byteLength !== expectedBytes)
+        throw invalid('Object proposal aliases or packed mask dimensions are invalid');
+    const data = new Uint8Array(mask.data);
+    const decoded = unpackBinaryMask({
+        data,
+        width: image.width,
+        height: image.height,
+        format: 'binary-lsb0',
+    });
+    const bounds = maskBounds(decoded, image.width, image.height);
+    if (bounds === null) {
+        if (proposal.region !== null)
+            throw invalid('Empty proposal must have a null pixel region');
+    }
+    else if (proposal.region !== null) {
+        assertRect(proposal.region, image.width, image.height, 'proposal region');
+        if (proposal.region.left !== bounds.left ||
+            proposal.region.top !== bounds.top ||
+            proposal.region.width !== bounds.width ||
+            proposal.region.height !== bounds.height)
+            throw invalid('Proposal region does not match packed mask support');
+    }
+    return {
+        id,
+        data,
+        region: bounds ? { ...bounds } : null,
+        bounds: bounds ? { ...bounds } : null,
+    };
+}
+function maskBounds(mask, width, height) {
+    let left = width;
+    let top = height;
+    let right = -1;
+    let bottom = -1;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            if (mask[y * width + x] === 0)
+                continue;
+            if (x < left)
+                left = x;
+            if (x > right)
+                right = x;
+            if (y < top)
+                top = y;
+            if (y > bottom)
+                bottom = y;
+        }
+    }
+    return right < left || bottom < top
+        ? null
+        : { left, top, width: right - left + 1, height: bottom - top + 1 };
+}
+function makeOverlay(source, mask, width, height, bounds) {
+    const output = new Uint8Array(source.length);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const index = y * width + x;
+            const offset = index * 4;
+            output[offset] = source[offset];
+            output[offset + 1] = source[offset + 1];
+            output[offset + 2] = source[offset + 2];
+            output[offset + 3] = source[offset + 3];
+            if (mask[index] === 0)
+                continue;
+            const edge = x === 0 ||
+                y === 0 ||
+                x === width - 1 ||
+                y === height - 1 ||
+                mask[index - 1] === 0 ||
+                mask[index + 1] === 0 ||
+                mask[index - width] === 0 ||
+                mask[index + width] === 0;
+            if (edge) {
+                output[offset] = 0;
+                output[offset + 1] = 255;
+                output[offset + 2] = 255;
+                output[offset + 3] = 255;
+            }
+            else {
+                output[offset] = Math.round(source[offset] * 0.65 + 255 * 0.35);
+                output[offset + 1] = Math.round(source[offset + 1] * 0.65 + 32 * 0.35);
+                output[offset + 2] = Math.round(source[offset + 2] * 0.65 + 32 * 0.35);
+            }
+        }
+    }
+    if (bounds !== null) {
+        const right = bounds.left + bounds.width - 1;
+        const bottom = bounds.top + bounds.height - 1;
+        for (let x = bounds.left; x <= right; x++) {
+            paintRectanglePixel(output, width, x, bounds.top);
+            paintRectanglePixel(output, width, x, bottom);
+        }
+        for (let y = bounds.top; y <= bottom; y++) {
+            paintRectanglePixel(output, width, bounds.left, y);
+            paintRectanglePixel(output, width, right, y);
+        }
+    }
+    return output;
+}
+function paintRectanglePixel(output, width, x, y) {
+    const offset = (y * width + x) * 4;
+    output[offset] = 255;
+    output[offset + 1] = 220;
+    output[offset + 2] = 0;
+    output[offset + 3] = 255;
+}
+function makeCutout(source, mask, width, height, bounds) {
+    const data = new Uint8Array(bounds.width * bounds.height * 4);
+    for (let y = 0; y < bounds.height; y++) {
+        for (let x = 0; x < bounds.width; x++) {
+            const sourceIndex = (bounds.top + y) * width + bounds.left + x;
+            const outputIndex = (y * bounds.width + x) * 4;
+            if (mask[sourceIndex] === 0)
+                continue;
+            data[outputIndex] = source[sourceIndex * 4];
+            data[outputIndex + 1] = source[sourceIndex * 4 + 1];
+            data[outputIndex + 2] = source[sourceIndex * 4 + 2];
+            data[outputIndex + 3] = source[sourceIndex * 4 + 3];
+        }
+    }
+    return { data, width: bounds.width, height: bounds.height };
+}
+function svg(width, height, body) {
+    return Buffer.from(`<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${body}</svg>`);
+}
+async function encode(pipeline, signal) {
+    try {
+        const bytes = await pipeline.toBuffer();
+        assertActive(signal);
+        return bytes;
+    }
+    catch (error) {
+        if (error instanceof ClassifierError)
+            throw error;
+        throw new ClassifierError('PROVIDER', 'Object proposal presentation failed');
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+function invalid(message) {
+    return new ClassifierError('INVALID_RESPONSE', message);
+}

package/dist/infrastructure/segmentation/verify-asset.d.ts

@@ -0,0 +1,4 @@
+export declare function verifyPinnedAsset(path: string, expected: {
+    bytes: number;
+    sha256: string;
+}, label: string): Promise<void>;

package/dist/infrastructure/segmentation/verify-asset.js

@@ -0,0 +1,32 @@
+import { createHash } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { ClassifierError } from '../../entities/errors.js';
+export async function verifyPinnedAsset(path, expected, label) {
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size !== expected.bytes)
+            throw new ClassifierError('UNSUPPORTED', `${label} asset is missing or has the wrong size`);
+        const bytes = Buffer.alloc(expected.bytes);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = await handle.read(bytes, offset, bytes.length - offset, null);
+            if (!read.bytesRead)
+                throw new ClassifierError('UNSUPPORTED', `${label} asset read was incomplete`);
+            offset += read.bytesRead;
+        }
+        if ((await handle.read(Buffer.alloc(1), 0, 1, null)).bytesRead !== 0)
+            throw new ClassifierError('UNSUPPORTED', `${label} asset changed while being read`);
+        if (createHash('sha256').update(bytes).digest('hex') !== expected.sha256)
+            throw new ClassifierError('UNSUPPORTED', `${label} asset SHA256 does not match the pinned artifact`);
+    }
+    catch (error) {
+        if (error instanceof ClassifierError)
+            throw error;
+        throw new ClassifierError('UNSUPPORTED', `${label} asset cannot be read`);
+    }
+    finally {
+        await handle?.close();
+    }
+}

package/dist/infrastructure/text-representation.d.ts

@@ -0,0 +1,23 @@
+import type { PixelRect } from '../entities/contracts.js';
+import type { ImageRepresentationPort, RepresentationView } from '../entities/representation.js';
+export interface TextPixelView {
+    id: string;
+    role: RepresentationView['role'];
+    sourceRegion: PixelRect;
+    width: number;
+    height: number;
+    /** Clean, resized, row-major RGBA8. Grid labels remain separately available as metadata. */
+    data: Uint8Array;
+    grid?: RepresentationView['grid'];
+}
+export interface TextRepresentationEncoder {
+    readonly profile: string;
+    /** Hard UTF-8 upper bound for one encoded view at these dimensions. */
+    maxEncodedBytes(width: number, height: number): number;
+    encode(view: TextPixelView, signal: AbortSignal): Promise<string>;
+}
+/**
+ * Build request-wide text representations from clean canonical pixels. The injected encoder
+ * is intentionally internal so research codecs do not become public package exports.
+ */
+export declare function createTextRepresentation(encoder: TextRepresentationEncoder): ImageRepresentationPort;

package/dist/infrastructure/text-representation.js

@@ -0,0 +1,226 @@
+import sharp from 'sharp';
+import { limits } from '../entities/contracts.js';
+import { ClassifierError, assertActive } from '../entities/errors.js';
+import { representationLimits } from '../entities/representation.js';
+import { readCanonicalPixels } from './raster.js';
+function isContained(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 key(region) {
+    return `${region.left},${region.top},${region.width},${region.height}`;
+}
+function dimensions(region, maxSide) {
+    const scale = Math.min(1, maxSide / Math.max(region.width, region.height));
+    return {
+        width: Math.max(1, Math.round(region.width * scale)),
+        height: Math.max(1, Math.round(region.height * scale)),
+    };
+}
+function assertGridGeometry(view, width, height) {
+    if (!view.grid)
+        return;
+    const map = (rect) => ({
+        left: Math.round(((rect.left - view.sourceRegion.left) * width) / view.sourceRegion.width),
+        top: Math.round(((rect.top - view.sourceRegion.top) * height) / view.sourceRegion.height),
+        width: Math.round((rect.width * width) / view.sourceRegion.width),
+        height: Math.round((rect.height * height) / view.sourceRegion.height),
+    });
+    const mapped = view.grid.cells.map((cell) => map(cell.region));
+    if (view.grid.cells.some((cell) => !isContained(view.sourceRegion, cell.region)))
+        throw new ClassifierError('INVALID_INPUT', 'Grid geometry lies outside its source region');
+    if (mapped.some((rect) => rect.width < 1 || rect.height < 1))
+        throw new ClassifierError('RESOURCE_LIMIT', 'Distinct grid geometry is indistinguishable at the allocated resolution', { component: 'representation' });
+    const sourceKeys = new Set(view.grid.cells.map((cell) => key(cell.region)));
+    const mappedKeys = new Set(mapped.map((rect) => key(rect)));
+    if (sourceKeys.size !== mappedKeys.size)
+        throw new ClassifierError('RESOURCE_LIMIT', 'Distinct grid geometry collapses at the allocated resolution', {
+            component: 'representation',
+        });
+}
+async function cleanPixels(source, sourcePixels, view, width, height, signal) {
+    const region = view.sourceRegion;
+    if (!isContained({ left: 0, top: 0, width: source.width, height: source.height }, region))
+        throw new ClassifierError('INVALID_INPUT', 'Representation view lies outside the oriented source');
+    const raw = Buffer.from(sourcePixels.buffer, sourcePixels.byteOffset, sourcePixels.byteLength);
+    const pipeline = sharp(raw, {
+        raw: { width: source.width, height: source.height, channels: 4 },
+        limitInputPixels: limits.imagePixels,
+    })
+        .extract(region)
+        .resize(width, height, { kernel: 'nearest' })
+        .raw();
+    try {
+        const result = await pipeline.toBuffer({ resolveWithObject: true });
+        assertActive(signal);
+        if (result.info.channels !== 4 || result.data.byteLength !== width * height * 4)
+            throw new ClassifierError('INVALID_RESPONSE', 'Sharp returned an invalid canonical pixel view');
+        return {
+            id: view.id,
+            role: view.role,
+            sourceRegion: region,
+            width,
+            height,
+            data: result.data,
+            ...(view.grid ? { grid: view.grid } : {}),
+        };
+    }
+    finally {
+        pipeline.destroy();
+    }
+}
+function aliasesFor(view) {
+    return {
+        id: view.id,
+        role: view.role,
+        sourceRegion: view.sourceRegion,
+        ...(view.grid ? { grid: view.grid } : {}),
+    };
+}
+function gridMetadata(grid) {
+    if (!grid)
+        return undefined;
+    return {
+        cells: grid.cells.map((cell) => ({
+            id: cell.id,
+            column: cell.column,
+            row: cell.row,
+            region: cell.region,
+            label: grid.labels.get(cell.id) ?? null,
+        })),
+    };
+}
+function makePlan(groups, maxSide, encoder) {
+    const plan = [];
+    let totalBytes = 0;
+    for (const group of groups) {
+        const size = dimensions(group.sourceRegion, maxSide);
+        const metadataText = JSON.stringify({
+            representationView: {
+                id: group.aliases[0]?.id ?? group.primary.id,
+                aliases: group.aliases.map((alias) => ({
+                    id: alias.id,
+                    role: alias.role,
+                    sourceRegion: alias.sourceRegion,
+                })),
+                sourceRegion: group.sourceRegion,
+                dimensions: size,
+                scaleX: size.width / group.sourceRegion.width,
+                scaleY: size.height / group.sourceRegion.height,
+                grid: group.aliases.flatMap((alias) => {
+                    const value = gridMetadata(alias.grid);
+                    return value === undefined ? [] : [{ viewId: alias.id, cells: value.cells }];
+                }),
+            },
+        });
+        const bound = encoder.maxEncodedBytes(size.width, size.height);
+        const metadataBytes = Buffer.byteLength(metadataText, 'utf8');
+        if (!Number.isSafeInteger(bound) ||
+            bound < 0 ||
+            bound > representationLimits.partCharacters ||
+            metadataText.length > representationLimits.partCharacters)
+            return undefined;
+        totalBytes += metadataBytes + bound;
+        plan.push({ group, ...size, metadataText, maxEncodedBytes: bound });
+    }
+    return totalBytes <= representationLimits.totalBytes ? plan : undefined;
+}
+function buildGroups(views) {
+    const groups = new Map();
+    for (const view of views) {
+        const regionKey = key(view.sourceRegion);
+        const prior = groups.get(regionKey);
+        if (!prior) {
+            groups.set(regionKey, {
+                sourceRegion: view.sourceRegion,
+                primary: view,
+                aliases: [aliasesFor(view)],
+            });
+        }
+        else {
+            prior.aliases.push(aliasesFor(view));
+        }
+    }
+    return [...groups.values()];
+}
+/**
+ * Build request-wide text representations from clean canonical pixels. The injected encoder
+ * is intentionally internal so research codecs do not become public package exports.
+ */
+export function createTextRepresentation(encoder) {
+    return {
+        async prepare(input) {
+            assertActive(input.signal);
+            if (input.views.length > representationLimits.maxViews)
+                throw new ClassifierError('RESOURCE_LIMIT', 'A representation request may contain at most nine views', {
+                    component: 'representation',
+                });
+            const groups = buildGroups(input.views);
+            for (const group of groups) {
+                if (!isContained({ left: 0, top: 0, width: input.source.width, height: input.source.height }, group.sourceRegion))
+                    throw new ClassifierError('INVALID_INPUT', 'Representation view lies outside the oriented source');
+            }
+            let plan;
+            for (let side = representationLimits.maxSide; side >= 1 && plan === undefined; side -= 1)
+                plan = makePlan(groups, side, encoder);
+            if (!plan)
+                throw new ClassifierError('RESOURCE_LIMIT', 'No bounded text representation allocation fits the request', {
+                    component: 'representation',
+                });
+            for (const item of plan)
+                for (const alias of item.group.aliases)
+                    if (alias.grid)
+                        assertGridGeometry({ ...item.group.primary, sourceRegion: item.group.sourceRegion, grid: alias.grid }, item.width, item.height);
+            const decoded = await readCanonicalPixels(input.source, input.signal);
+            const pixelViews = [];
+            for (const item of plan)
+                pixelViews.push(await cleanPixels(input.source, decoded.data, item.group.primary, item.width, item.height, input.signal));
+            const state = [];
+            const metadata = { profile: encoder.profile, bytes: 0, views: [] };
+            for (let index = 0; index < pixelViews.length; index += 1) {
+                const view = pixelViews[index];
+                const allocation = plan[index];
+                if (!view || !allocation)
+                    throw new ClassifierError('INVALID_RESPONSE', 'Text representation allocation was incomplete');
+                assertActive(input.signal);
+                state.push(allocation.metadataText);
+                metadata.bytes += Buffer.byteLength(allocation.metadataText, 'utf8');
+                let text;
+                try {
+                    text = await encoder.encode(view, input.signal);
+                }
+                catch (error) {
+                    if (error instanceof ClassifierError && error.code === 'RESOURCE_LIMIT')
+                        throw new ClassifierError(error.code, error.message, {
+                            ...error.details,
+                            component: 'representation',
+                        });
+                    throw error;
+                }
+                const bytes = Buffer.byteLength(text, 'utf8');
+                if (text.length > representationLimits.partCharacters || bytes > allocation.maxEncodedBytes)
+                    throw new ClassifierError('RESOURCE_LIMIT', 'Encoder output exceeds its declared per-view bound', {
+                        component: 'representation',
+                    });
+                if (metadata.bytes + bytes > representationLimits.totalBytes)
+                    throw new ClassifierError('RESOURCE_LIMIT', 'Encoded request exceeds the aggregate UTF-8 byte limit', {
+                        component: 'representation',
+                    });
+                metadata.bytes += bytes;
+                state.push(text);
+                metadata.views.push({
+                    id: view.id,
+                    sourceRegion: view.sourceRegion,
+                    width: view.width,
+                    height: view.height,
+                    scaleX: view.width / view.sourceRegion.width,
+                    scaleY: view.height / view.sourceRegion.height,
+                    content: { left: 0, top: 0, width: view.width, height: view.height },
+                });
+            }
+            return { state, metadata };
+        },
+    };
+}

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

@@ -61,4 +61,4 @@ export interface VisionChatOptions {
     maxResponseBytes?: number;
 }
 /** Ordinary text/image chat completion, with no native classifier/Decisions requirement. */
-export declare function createVisionChat(input: unknown): DecisionPort;
+export declare function createVisionChat(input: unknown, modality?: 'vision' | 'text'): DecisionPort;