hoi4-agent-tools 4.0.4 → 4.1.0

package/dist/hoi4_agent_tools/map/reference-labels.js

@@ -0,0 +1,238 @@
+/** Offline English OCR for reference artwork. No image paths, URLs, commands or model paths
+ * are accepted from callers. The pinned Tesseract worker protocol is used directly because
+ * its public createWorker promise hides the worker handle until initialization completes;
+ * owning the thread from creation lets us terminate stalled initialization as well as OCR.
+ * The synthetic integration test must pass before changing the pinned OCR dependencies.
+ */
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { Worker } from 'node:worker_threads';
+import sharp from 'sharp';
+import { z } from 'zod';
+import { compareCodeUnits } from '../core/canonical.js';
+import { ServiceError } from '../core/result.js';
+const MAX_BYTES = 32 * 1024 * 1024;
+const MAX_PIXELS = 40_000_000;
+const MAX_OCR_SIDE = 2560;
+const MAX_LABELS = 512;
+const MAX_TSV_BYTES = 2 * 1024 * 1024;
+const OCR_TIMEOUT_MS = 30_000;
+const require = createRequire(import.meta.url);
+let active = false;
+function hasRasterSignature(image) {
+    return (image.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ||
+        image.subarray(0, 3).equals(Buffer.from([255, 216, 255])) ||
+        ['GIF87a', 'GIF89a'].includes(image.subarray(0, 6).toString('ascii')) ||
+        (image.subarray(0, 4).toString('ascii') === 'RIFF' &&
+            image.subarray(8, 12).toString('ascii') === 'WEBP') ||
+        image.subarray(0, 4).equals(Buffer.from([73, 73, 42, 0])) ||
+        image.subarray(0, 4).equals(Buffer.from([77, 77, 0, 42])));
+}
+const packetSchema = z.object({
+    jobId: z.string(),
+    status: z.enum(['resolve', 'reject', 'progress']),
+    data: z.unknown(),
+});
+/** Validate and normalize the engine's TSV instead of trusting its untyped nested output. */
+export function parseReferenceLabelTsv(tsv, width, height) {
+    if (Buffer.byteLength(tsv) > MAX_TSV_BYTES ||
+        !Number.isSafeInteger(width) ||
+        !Number.isSafeInteger(height) ||
+        width <= 0 ||
+        height <= 0) {
+        return { labels: [], warnings: ['Reference text output exceeded safe bounds.'] };
+    }
+    const lines = new Map();
+    const uncertainLines = new Set();
+    let rejected = 0;
+    for (const row of tsv.split(/\r?\n/).slice(1)) {
+        if (!row.trim())
+            continue;
+        const fields = row.split('\t');
+        if (fields[0] !== '5')
+            continue;
+        const key = fields.slice(1, 5).join(':');
+        const text = fields.slice(11).join(' ').normalize('NFC').trim();
+        const [left, top, wordWidth, wordHeight, confidence] = fields.slice(6, 11).map(Number);
+        if (fields.length < 12 ||
+            !text ||
+            left === undefined ||
+            top === undefined ||
+            wordWidth === undefined ||
+            wordHeight === undefined ||
+            confidence === undefined ||
+            ![left, top, wordWidth, wordHeight, confidence].every(Number.isFinite) ||
+            left < 0 ||
+            top < 0 ||
+            wordWidth <= 0 ||
+            wordHeight <= 0 ||
+            left + wordWidth > width ||
+            top + wordHeight > height ||
+            confidence < 70 ||
+            confidence > 100 ||
+            !/^[\p{L}\p{M}\d][\p{L}\p{M}\d.,'’()-]*$/u.test(text) ||
+            text.length > 80) {
+            rejected++;
+            uncertainLines.add(key);
+            continue;
+        }
+        const group = lines.get(key) ?? [];
+        group.push({ text, confidence, left, top, width: wordWidth, height: wordHeight });
+        lines.set(key, group);
+    }
+    const labels = [];
+    for (const [key, words] of lines) {
+        // A readable half of an uncertain multiword name is not a reliable place name.
+        if (uncertainLines.has(key))
+            continue;
+        words.sort((a, b) => a.left - b.left || a.top - b.top);
+        const groups = [];
+        for (const word of words) {
+            const group = groups.at(-1);
+            const previous = group?.at(-1);
+            if (!previous ||
+                word.left - (previous.left + previous.width) > 2.5 * Math.max(previous.height, word.height)) {
+                groups.push([word]);
+            }
+            else
+                group.push(word);
+        }
+        for (const group of groups) {
+            const text = group.map((word) => word.text).join(' ');
+            const confidence = group.reduce((sum, word) => sum + word.confidence, 0) / group.length;
+            if (confidence < 80 || text.length < 2 || text.length > 80 || !/[\p{L}]/u.test(text)) {
+                rejected++;
+                continue;
+            }
+            const left = Math.min(...group.map((word) => word.left));
+            const top = Math.min(...group.map((word) => word.top));
+            const right = Math.max(...group.map((word) => word.left + word.width));
+            const bottom = Math.max(...group.map((word) => word.top + word.height));
+            labels.push({
+                text,
+                confidence: Math.round(confidence * 100) / 100,
+                x: (left + right) / (2 * width),
+                y: (top + bottom) / (2 * height),
+                width: (right - left) / width,
+                height: (bottom - top) / height,
+            });
+        }
+    }
+    labels.sort((a, b) => a.y - b.y || a.x - b.x || compareCodeUnits(a.text, b.text));
+    const warnings = [];
+    if (rejected > 0)
+        warnings.push(`${rejected} uncertain or invalid reference text fragment(s) were omitted.`);
+    if (labels.length > MAX_LABELS)
+        warnings.push('Reference text was limited to 512 labels.');
+    if (labels.length === 0)
+        warnings.push('No reliable English labels were readable in the reference image.');
+    return { labels: labels.slice(0, MAX_LABELS), warnings };
+}
+/** One active OCR thread per process; contention is retryable instead of changing generated
+ * names. No queue retains reference image bytes. Worker stdout is never forwarded.
+ */
+export async function extractReferenceLabels(image) {
+    if (!Buffer.isBuffer(image) || image.length === 0 || image.length > MAX_BYTES) {
+        return { labels: [], warnings: ['Reference text image exceeded safe byte bounds.'] };
+    }
+    if (!hasRasterSignature(image)) {
+        return {
+            labels: [],
+            warnings: ['Reference text recognition requires a supported raster image.'],
+        };
+    }
+    if (active)
+        throw new ServiceError('MAP_REFERENCE_OCR_BUSY', 'Offline reference text recognition is busy; retry the request.', { retryable: true });
+    active = true;
+    let worker;
+    let timer;
+    try {
+        const decoded = sharp(image, { limitInputPixels: MAX_PIXELS, animated: false });
+        const metadata = await decoded.metadata();
+        if (!['png', 'jpeg', 'webp', 'tiff', 'gif'].includes(metadata.format) ||
+            !metadata.width ||
+            !metadata.height) {
+            return {
+                labels: [],
+                warnings: ['Reference text recognition requires a supported raster image.'],
+            };
+        }
+        const { data: png, info } = await decoded
+            .flatten({ background: '#ffffff' })
+            .resize(MAX_OCR_SIDE, MAX_OCR_SIDE, { fit: 'inside', withoutEnlargement: true })
+            .png()
+            .toBuffer({ resolveWithObject: true });
+        // Paths resolve only fixed, installed, shrinkwrap-pinned package resources. Missing model
+        // data fails closed; we never let Tesseract choose its default remote language URL.
+        const model = await readFile(require.resolve('@tesseract.js-data/eng/4.0.0_best_int/eng.traineddata.gz'));
+        worker = new Worker(require.resolve('tesseract.js/src/worker-script/node/index.js'), {
+            stdout: true,
+            stderr: true,
+            resourceLimits: { maxOldGenerationSizeMb: 192 },
+            execArgv: [],
+        });
+        // Drain diagnostics without forwarding OCR input, recognized names, paths or stdout.
+        worker.stdout.resume();
+        worker.stderr.resume();
+        const currentWorker = worker;
+        let sequence = 0;
+        let rejectPending;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new ServiceError('MAP_REFERENCE_OCR_TIMEOUT', 'Offline reference text recognition exceeded its time limit; retry the request.', { retryable: true })), OCR_TIMEOUT_MS);
+        });
+        currentWorker.on('error', () => rejectPending?.(new Error('OCR worker failed')));
+        currentWorker.on('exit', () => rejectPending?.(new Error('OCR worker exited')));
+        const send = (action, payload) => {
+            const jobId = `reference-${sequence++}`;
+            return new Promise((resolve, reject) => {
+                rejectPending = reject;
+                const receive = (raw) => {
+                    const packet = packetSchema.safeParse(raw);
+                    if (!packet.success || packet.data.jobId !== jobId || packet.data.status === 'progress')
+                        return;
+                    currentWorker.off('message', receive);
+                    rejectPending = undefined;
+                    if (packet.data.status === 'reject')
+                        reject(new Error('OCR recognition failed'));
+                    else
+                        resolve(packet.data.data);
+                };
+                currentWorker.on('message', receive);
+                currentWorker.postMessage({ workerId: 'reference-labels', jobId, action, payload });
+            });
+        };
+        const recognize = async () => {
+            await send('load', { options: { lstmOnly: true, logging: false } });
+            await send('loadLanguage', {
+                langs: [{ code: 'eng', data: model }],
+                options: { cacheMethod: 'none', gzip: true, lstmOnly: true },
+            });
+            await send('initialize', { langs: 'eng', oem: 1, config: {} });
+            await send('setParameters', {
+                params: { tessedit_pageseg_mode: '11', user_defined_dpi: '300' },
+            });
+            return send('recognize', { image: png, options: {}, output: { text: false, tsv: true } });
+        };
+        const result = await Promise.race([recognize(), timeout]);
+        const output = z.object({ tsv: z.string().max(MAX_TSV_BYTES) }).safeParse(result);
+        if (!output.success)
+            throw new Error('Unsupported OCR output');
+        return parseReferenceLabelTsv(output.data.tsv, info.width, info.height);
+    }
+    catch (error) {
+        if (error instanceof ServiceError)
+            throw error;
+        throw new ServiceError('MAP_REFERENCE_OCR_UNAVAILABLE', 'Offline reference text recognition could not complete; verify the installed OCR dependencies and retry the request.', { retryable: true });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        try {
+            if (worker)
+                await worker.terminate();
+        }
+        finally {
+            active = false;
+        }
+    }
+}

package/dist/hoi4_agent_tools/map/reference-preparation.js

@@ -0,0 +1,247 @@
+import { readReferenceImageSource } from '../core/bounded-source.js';
+import { extractReferenceLabels } from './reference-labels.js';
+import { extractReferenceWorld } from './reference-world.js';
+import { ServiceError } from '../core/result.js';
+/** Analyze only bounded, authorized sources; the transaction retains the original source hashes. */
+export async function prepareReferenceWorld(resolver, workspaceId, operation, principal, signal) {
+    const reference = operation.reference;
+    if (reference === undefined)
+        throw new ServiceError('MAP_REFERENCE_REQUIRED', 'Reference preparation requires imagePath');
+    const images = [];
+    const load = async (relativePath) => {
+        const image = await readReferenceImageSource(resolver, workspaceId, relativePath, principal, signal);
+        images.push(image);
+        return image;
+    };
+    const main = await load(reference.imagePath);
+    if (reference.crop !== undefined &&
+        (reference.crop.x + reference.crop.width > main.originalWidth ||
+            reference.crop.y + reference.crop.height > main.originalHeight))
+        throw new ServiceError('MAP_REFERENCE_CROP_BLOCKED', 'Reference crop exceeds the original image bounds');
+    const political = reference.politicalImagePath === undefined
+        ? undefined
+        : await load(reference.politicalImagePath);
+    const terrain = reference.terrainImagePath === undefined ? undefined : await load(reference.terrainImagePath);
+    const height = reference.heightImagePath === undefined ? undefined : await load(reference.heightImagePath);
+    const crop = reference.crop === undefined
+        ? undefined
+        : {
+            x: Math.floor((reference.crop.x * main.workingWidth) / main.originalWidth),
+            y: Math.floor((reference.crop.y * main.workingHeight) / main.originalHeight),
+            width: Math.max(1, Math.round((reference.crop.width * main.workingWidth) / main.originalWidth)),
+            height: Math.max(1, Math.round((reference.crop.height * main.workingHeight) / main.originalHeight)),
+        };
+    const text = await extractReferenceLabels(main.bytes);
+    signal?.throwIfAborted();
+    const textMasks = text.labels
+        .slice(0, Math.max(0, 256 - (reference.ignoreMasks?.length ?? 0)))
+        .map((label) => {
+        const left = Math.max(0, label.x - label.width / 2 - 3 / main.workingWidth), right = Math.min(1, label.x + label.width / 2 + 3 / main.workingWidth);
+        const top = Math.max(0, label.y - label.height / 2 - 3 / main.workingHeight), bottom = Math.min(1, label.y + label.height / 2 + 3 / main.workingHeight);
+        return [
+            { x: left, y: top },
+            { x: right, y: top },
+            { x: right, y: bottom },
+            { x: left, y: bottom },
+        ];
+    });
+    const surface = await extractReferenceWorld(main.bytes, {
+        width: operation.width ?? 5_632,
+        height: operation.height ?? 2_048,
+        seed: operation.seed ?? 1,
+        ...(reference.mode === undefined ? {} : { mode: reference.mode }),
+        ...(crop === undefined ? {} : { crop }),
+        ignoreMasks: [...(reference.ignoreMasks ?? []), ...textMasks],
+        ...(reference.annotations === undefined ? {} : { annotations: reference.annotations }),
+        ...(reference.riverAnnotations === undefined
+            ? {}
+            : { riverAnnotations: reference.riverAnnotations }),
+        ...(reference.palette === undefined ? {} : { palette: reference.palette }),
+        ...(reference.coastDetail === undefined ? {} : { coastDetail: reference.coastDetail }),
+        ...(political === undefined ? {} : { politicalImageBytes: political.bytes }),
+        ...(terrain === undefined ? {} : { terrainImageBytes: terrain.bytes }),
+        ...(height === undefined ? {} : { heightImageBytes: height.bytes }),
+    });
+    signal?.throwIfAborted();
+    const warnings = [
+        ...surface.diagnostics,
+        ...text.warnings,
+        'Reference interpretation uses visual heuristics. Terrain, borders, labels and generated demographic values are approximations; review the offline previews.',
+        ...(textMasks.length === 0
+            ? []
+            : [
+                'Recognized text bounds are excluded from terrain classification; nearby coastlines may need review.',
+            ]),
+    ];
+    const toTarget = (x, y) => ({
+        x: ((x * main.workingWidth - (crop?.x ?? 0)) / (crop?.width ?? main.workingWidth)) *
+            surface.referenceBounds.width +
+            surface.referenceBounds.x,
+        y: ((y * main.workingHeight - (crop?.y ?? 0)) / (crop?.height ?? main.workingHeight)) *
+            surface.referenceBounds.height +
+            surface.referenceBounds.y,
+    });
+    const nearestLand = (x, y) => {
+        const cx = Math.round(x), cy = Math.round(y);
+        const radius = Math.max(2, Math.round(Math.min(surface.width, surface.height) * 0.02));
+        let best;
+        for (let dy = -radius; dy <= radius; dy++)
+            for (let dx = -radius; dx <= radius; dx++) {
+                const px = cx + dx, py = cy + dy, distance = dx * dx + dy * dy;
+                if (px < 0 ||
+                    py < 0 ||
+                    px >= surface.width ||
+                    py >= surface.height ||
+                    surface.kind[py * surface.width + px] !== 1)
+                    continue;
+                if (best === undefined || distance < best.distance)
+                    best = { x: px, y: py, distance };
+            }
+        return best;
+    };
+    const reviewedLabels = (reference.labels ?? []).map((label) => ({ ...label, ...toTarget(label.x, label.y) }));
+    const nearReviewed = (point) => reviewedLabels.some((reviewed) => Math.hypot(reviewed.x - point.x, reviewed.y - point.y) <
+        Math.min(surface.width, surface.height) * 0.025);
+    // An explicit review is authoritative, including an empty list. OCR still helps mask ink,
+    // but must not reintroduce discarded or uncertain names outside the supplied label set.
+    const automaticText = reference.labels === undefined ? text.labels : [];
+    const labels = automaticText
+        .filter(({ text: label }) => !/\b(?:map|world|sea|ocean|bay|strait|channel|flow|belt|signature|north|south|east|west|compass)\b/iu.test(label))
+        .slice(0, 200)
+        .flatMap((label) => {
+        const point = toTarget(label.x, label.y);
+        const land = nearestLand(point.x, point.y);
+        return land === undefined ? [] : [{ name: label.text, x: land.x, y: land.y }];
+    });
+    const reviewedCountries = reviewedLabels.filter((label) => label.kind === 'country');
+    const countryNames = [...reviewedCountries, ...labels.filter((label) => !nearReviewed(label))];
+    const defaults = ['Aster', 'Brum', 'Corvel', 'Doran', 'Evin', 'Faron', 'Galen', 'Haven'];
+    const politicalRegionAt = (point) => {
+        const x = Math.floor(point.x), y = Math.floor(point.y);
+        if (x < 0 || y < 0 || x >= surface.width || y >= surface.height)
+            return undefined;
+        const pixel = y * surface.width + x;
+        if (surface.kind[pixel] !== 1)
+            return undefined;
+        const id = surface.country[pixel];
+        return id === 0 ? undefined : id;
+    };
+    let countries;
+    if (operation.countries !== undefined)
+        countries = operation.countries;
+    else if (surface.inferredCountries.length > 1) {
+        countries = surface.inferredCountries.slice(0, 200).map((country, index) => ({
+            tag: `X${(index + 1).toString(36).toUpperCase().padStart(2, '0')}`,
+            name: country.name,
+            color: country.color,
+        }));
+        const centres = new Map();
+        for (let pixel = 0; pixel < surface.country.length; pixel++) {
+            const id = surface.country[pixel];
+            if (id === 0)
+                continue;
+            const centre = centres.get(id) ?? { x: 0, y: 0, n: 0 };
+            centre.x += pixel % surface.width;
+            centre.y += Math.floor(pixel / surface.width);
+            centre.n++;
+            centres.set(id, centre);
+        }
+        const used = new Set();
+        for (const [index, country] of countries.entries()) {
+            const regionId = surface.inferredCountries[index].id;
+            const centre = centres.get(regionId);
+            if (centre === undefined)
+                continue;
+            const label = countryNames
+                .filter((label) => !used.has(label.name) && politicalRegionAt(label) === regionId)
+                .sort((a, b) => Math.hypot(a.x - centre.x / centre.n, a.y - centre.y / centre.n) -
+                Math.hypot(b.x - centre.x / centre.n, b.y - centre.y / centre.n))[0];
+            if (label !== undefined) {
+                country.name = label.name;
+                used.add(label.name);
+            }
+            else
+                warnings.push(`Political region ${regionId} had no reliable name label within its borders; ${country.name} was retained.`);
+        }
+        warnings.push('Flat political colors define inferred countries; text within each region is an uncertain country-name candidate.');
+    }
+    else {
+        const count = reviewedCountries.length || Math.max(4, Math.min(8, countryNames.length || 4));
+        countries = Array.from({ length: count }, (_, index) => ({
+            tag: `X${(index + 1).toString(36).toUpperCase().padStart(2, '0')}`,
+            name: countryNames[index]?.name ?? defaults[index],
+        }));
+        warnings.push('Political borders were not reliably encoded; generated countries and ownership use deterministic defaults.');
+    }
+    const automaticLabels = automaticText
+        .filter(({ text: label }) => !/\b(?:map|world|signature|compass|north|south|east|west|flow|belt)\b/iu.test(label))
+        .map((label) => ({
+        ...toTarget(label.x, label.y),
+        name: label.text,
+        kind: /\b(?:sea|ocean|bay|strait|channel)\b/iu.test(label.text)
+            ? 'sea'
+            : /\b(?:mountain|mountains|range)\b/iu.test(label.text)
+                ? 'mountain'
+                : 'city',
+    }));
+    const geographicLabels = [
+        ...reviewedLabels,
+        ...automaticLabels.filter((label) => !reviewedLabels.some((reviewed) => Math.hypot(reviewed.x - label.x, reviewed.y - label.y) <
+            Math.min(surface.width, surface.height) * 0.025)),
+    ].slice(0, 2048);
+    const cityInputs = reference.cities === undefined
+        ? geographicLabels
+            .filter((label) => label.kind === 'city')
+            .map(({ name, x, y }) => ({ name, x, y }))
+        : reference.cities.map((city) => ({ ...city, ...toTarget(city.x, city.y) }));
+    const cities = cityInputs.flatMap((city) => {
+        if ('countryTag' in city &&
+            city.countryTag !== undefined &&
+            !countries.some((country) => country.tag === city.countryTag))
+            throw new ServiceError('MAP_REFERENCE_CITY_COUNTRY_INVALID', 'City countryTag must name a generated country');
+        const land = nearestLand(city.x, city.y);
+        if (land === undefined) {
+            warnings.push(`City ${city.name} is outside nearby land and was omitted.`);
+            return [];
+        }
+        return [{ ...city, x: land.x, y: land.y }];
+    });
+    for (const [index, country] of countries.entries()) {
+        let candidates = cities;
+        if (surface.inferredCountries.length > 1) {
+            const color = country.color;
+            const matches = color === undefined
+                ? []
+                : surface.inferredCountries
+                    .map((region) => ({
+                    id: region.id,
+                    distance: (region.color.r - color.r) ** 2 +
+                        (region.color.g - color.g) ** 2 +
+                        (region.color.b - color.b) ** 2,
+                }))
+                    .sort((a, b) => a.distance - b.distance || a.id - b.id);
+            const regionId = matches[0] !== undefined &&
+                matches[0].distance <= 3 * 24 ** 2 &&
+                (matches[1] === undefined || matches[0].distance < matches[1].distance)
+                ? matches[0].id
+                : undefined;
+            if (regionId === undefined)
+                continue;
+            candidates = cities.filter((city) => city.countryTag === undefined && politicalRegionAt(city) === regionId);
+        }
+        const city = candidates.find(({ name }) => name === country.name) ??
+            (surface.inferredCountries.length > 1 ? candidates[0] : candidates[index]);
+        if (city !== undefined && city.countryTag === undefined)
+            city.countryTag = country.tag;
+    }
+    return {
+        prepared: {
+            surface,
+            countries,
+            cities,
+            labels: geographicLabels,
+            diagnostics: [...new Set(warnings)],
+        },
+        images,
+    };
+}