strom-research 1.0.0

package/dist/gedcom/lines.js

@@ -0,0 +1,91 @@
+// GEDCOM line writing: levels, the 255-byte limit, CONC/CONT splitting.
+//
+// CONC continues the same line (joined with nothing), CONT starts a new line.
+// Splits never sit next to a space: a value that begins or ends with a space
+// gets trimmed by some readers and two words silently glue together.
+export const MAX_LINE_BYTES = 255;
+/** Tags whose value may be a pointer (@X@) — everywhere else an "@" is text and is doubled. */
+const POINTER_TAGS = new Set(["FAMC", "FAMS", "HUSB", "WIFE", "CHIL", "SOUR", "REPO", "ASSO", "SUBM", "SUBN", "OBJE", "NOTE", "ALIA", "ANCI", "DESI"]);
+/** GEDCOM 5.5.1 writes a literal "@" as "@@" (so "@I1@ BIRT" in a note is not a pointer). */
+export function escapeAt(tag, value) {
+    if (POINTER_TAGS.has(tag) && /^@[^@\s]+@$/.test(value))
+        return value;
+    return value.replace(/@/g, "@@");
+}
+const utf8 = (s) => Buffer.byteLength(s, "utf8");
+/** Longest prefix of `s` (in whole code points) that fits in `bytes`. */
+function fit(s, bytes) {
+    let used = 0;
+    let i = 0;
+    for (const ch of s) {
+        const b = utf8(ch);
+        if (used + b > bytes)
+            break;
+        used += b;
+        i += ch.length;
+    }
+    return i;
+}
+/** Split one paragraph into chunks of at most `bytes`, never cutting next to a space. */
+export function splitParagraph(text, bytes) {
+    const out = [];
+    let rest = text;
+    while (utf8(rest) > bytes) {
+        let cut = fit(rest, bytes);
+        // never next to a space, never between the two halves of an escaped "@@", never
+        // between a letter and its accent (a combining mark with no precomposed form)
+        while (cut > 1 && (rest[cut - 1] === " " || rest[cut] === " " || (rest[cut - 1] === "@" && rest[cut] === "@") || /^\p{M}/u.test(rest.slice(cut))))
+            cut--;
+        if (cut <= 1)
+            cut = fit(rest, bytes); // a run of spaces: nothing better possible
+        out.push(rest.slice(0, cut));
+        rest = rest.slice(cut);
+    }
+    out.push(rest);
+    return out;
+}
+export class GedWriter {
+    lines = [];
+    // Text is written composed (NFC): "č" as one letter, as every reader compares it —
+    // whatever form it came in (macOS file names, copied text are often decomposed).
+    line(level, tag, value) {
+        const v = value === undefined || value === null ? "" : escapeAt(tag, String(value).normalize("NFC").replace(/[\r\n]+/g, " ").trim());
+        this.lines.push(v ? `${level} ${tag} ${v}` : `${level} ${tag}`);
+    }
+    /** A line whose value is already escaped (continuations of a text). */
+    raw(level, tag, v) {
+        this.lines.push(v ? `${level} ${tag} ${v}` : `${level} ${tag}`);
+    }
+    /** A record header: "0 @I1@ INDI". */
+    record(xref, tag, value) {
+        this.lines.push(value ? `0 ${xref} ${tag} ${value}` : `0 ${xref} ${tag}`);
+    }
+    /** A tag with free text of any length: CONT for line breaks, CONC for long lines. */
+    text(level, tag, text) {
+        const paragraphs = text
+            .normalize("NFC")
+            .replace(/\r\n?/g, "\n")
+            .split("\n")
+            .map((p) => p.replace(/\s+/g, " ").trim().replace(/@/g, "@@"));
+        paragraphs.forEach((para, i) => {
+            const lineTag = i === 0 ? tag : "CONT";
+            const lvl = i === 0 ? level : level + 1;
+            const first = splitParagraph(para, MAX_LINE_BYTES - utf8(`${lvl} ${lineTag} `))[0] ?? "";
+            this.raw(lvl, lineTag, first);
+            const rest = para.slice(first.length);
+            for (const chunk of splitParagraph(rest, MAX_LINE_BYTES - utf8(`${level + 1} CONC `)))
+                if (chunk)
+                    this.raw(level + 1, "CONC", chunk);
+        });
+    }
+    toString() {
+        return this.lines.join("\n") + "\n";
+    }
+}
+/** Reassemble a text value from a tag line and its CONC/CONT children (for tests and import). */
+export function joinText(value, continuation) {
+    let out = value;
+    for (const c of continuation)
+        out += c.tag === "CONT" ? `\n${c.value}` : c.value;
+    return out;
+}

package/dist/gedcom/parse.js

@@ -0,0 +1,53 @@
+// GEDCOM reader: lines → a node tree, CONC/CONT joined. Tolerant: this reads
+// files written by any program (and by people), not just our own.
+const LINE = /^\s*(\d{1,2})\s+(?:(@[^@\s]+@)\s+)?([A-Za-z0-9_]+)(?:\s(.*))?$/;
+export function parseGedcomText(text) {
+    const problems = [];
+    const records = [];
+    const stack = [];
+    const rows = text.replace(/^/, "").split(/\r\n|\r|\n/);
+    rows.forEach((raw, i) => {
+        if (!raw.trim())
+            return;
+        const m = LINE.exec(raw);
+        if (!m) {
+            problems.push(`line ${i + 1}: not a GEDCOM line`);
+            return;
+        }
+        // "@@" is a literal "@" (5.5.1); a lone pointer value stays as it is.
+        const rawValue = m[4] ?? "";
+        const value = /^@[^@\s]+@$/.test(rawValue) ? rawValue : rawValue.replace(/@@/g, "@");
+        const node = { level: Number(m[1]), tag: m[3].toUpperCase(), value, line: i + 1, children: [] };
+        if (m[2])
+            node.xref = m[2];
+        if (node.tag === "CONC" || node.tag === "CONT") {
+            const parent = stack[node.level - 1];
+            if (parent)
+                parent.value += (node.tag === "CONT" ? "\n" : "") + node.value;
+            return;
+        }
+        stack.length = node.level;
+        if (node.level === 0)
+            records.push(node);
+        else {
+            const parent = stack[node.level - 1];
+            if (!parent) {
+                problems.push(`line ${i + 1}: level ${node.level} without a parent`);
+                return;
+            }
+            parent.children.push(node);
+        }
+        stack[node.level] = node;
+    });
+    return { records, problems };
+}
+export function child(n, tag) {
+    return n.children.find((c) => c.tag === tag);
+}
+export function children(n, tag) {
+    return n.children.filter((c) => c.tag === tag);
+}
+export function val(n, tag) {
+    const c = n ? child(n, tag) : undefined;
+    return c?.value.trim() || undefined;
+}

package/dist/gedcom/validate.js

@@ -0,0 +1,183 @@
+// GEDCOM 5.5.1 validator, independent of the exporter: it reads the text as
+// any importer would. Runs after every export and on any file:
+// `strom gedcom validate <file>`.
+import { normalizeDate } from "../core/gdate.js";
+import { isGedcomAge } from "../core/age.js";
+import { MAX_LINE_BYTES } from "./lines.js";
+const LINE = /^(\d{1,2}) (?:(@[^@ ]+@) )?([A-Za-z0-9_]+)(?: (.*))?$/;
+const EVENT_DETAIL = ["TYPE", "DATE", "PLAC", "AGE", "SOUR", "NOTE", "ASSO", "_WITN", "CAUS", "ADDR", "AGNC", "RELI", "OBJE", "HUSB", "WIFE"];
+const INDI_EVENTS = [
+    "BIRT", "DEAT", "BAPM", "CHR", "CHRA", "CONF", "FCOM", "BARM", "BASM", "ORDN", "EDUC", "GRAD", "OCCU", "RESI", "EMIG", "IMMI",
+    "NATU", "RELI", "TITL", "NATI", "ADOP", "WILL", "PROB", "BURI", "CREM", "CENS", "EVEN", "RETI", "BLES", "CAST", "DSCR", "IDNO",
+    "NCHI", "NMR", "PROP", "SSN", "FACT",
+];
+const FAM_EVENTS = ["MARR", "DIV", "MARB", "MARC", "MARL", "MARS", "ANUL", "DIVF", "ENGA", "CENS", "EVEN", "NCHI"];
+/** Allowed child tags by parent context ("INDI", "INDI.BIRT", …). CONC/CONT are allowed under anything with text. */
+const CHILDREN = {
+    HEAD: ["SOUR", "DEST", "DATE", "SUBM", "SUBN", "FILE", "COPR", "GEDC", "CHAR", "LANG", "PLAC", "NOTE"],
+    "HEAD.SOUR": ["VERS", "NAME", "CORP", "DATA"],
+    "HEAD.GEDC": ["VERS", "FORM"],
+    "HEAD.DATE": ["TIME"],
+    INDI: ["NAME", "SEX", "FAMC", "FAMS", "NOTE", "SOUR", "REFN", "ASSO", "ALIA", "OBJE", "RESN", "RIN", "CHAN", "_STORY", ...INDI_EVENTS],
+    "INDI.NAME": ["TYPE", "GIVN", "SURN", "NPFX", "NSFX", "NICK", "SPFX", "SOUR", "NOTE"],
+    "INDI.FAMC": ["PEDI", "NOTE"],
+    "INDI.FAMS": ["NOTE"],
+    "FAM.CHIL": ["_FREL", "_MREL"],
+    "INDI.ASSO": ["RELA", "SOUR", "NOTE"],
+    FAM: ["HUSB", "WIFE", "CHIL", "NOTE", "SOUR", "REFN", "OBJE", "RIN", "CHAN", "_STORY", ...FAM_EVENTS],
+    SOUR: ["TITL", "AUTH", "ABBR", "PUBL", "TEXT", "REPO", "NOTE", "REFN", "DATA", "OBJE", "RIN", "CHAN"],
+    "SOUR.REPO": ["CALN", "NOTE"],
+    REPO: ["NAME", "ADDR", "NOTE", "REFN", "RIN", "CHAN"],
+    SUBM: ["NAME", "ADDR", "LANG", "NOTE", "RIN", "CHAN"],
+    NOTE: ["SOUR", "REFN", "RIN", "CHAN"],
+    EVENT: EVENT_DETAIL,
+    CITATION: ["PAGE", "QUAY", "NOTE", "DATA", "EVEN"],
+    "CITATION.DATA": ["DATE", "TEXT"],
+    PLAC: ["MAP", "FORM", "NOTE"],
+    MAP: ["LATI", "LONG"],
+    "EVENT.ASSO": ["RELA", "NOTE"],
+    "EVENT.HUSB": ["AGE"],
+    "EVENT.WIFE": ["AGE"],
+    _STORY: ["TYPE", "TITL", "STAT", "TEXT", "DATA", "NOTE"],
+    _WITN: ["RELA", "NOTE"],
+    ADDR: ["CONT", "ADR1", "ADR2", "ADR3", "CITY", "STAE", "POST", "CTRY"],
+};
+const TEXT_TAGS = new Set(["NOTE", "TEXT", "TITL", "PAGE", "AUTH", "PUBL", "_STORY", "DATA", "COPR", "ADDR", "CAUS"]);
+const EXTENSIONS = new Set(["_STORY", "_WITN", "_FREL", "_MREL"]);
+/** Context of the children of the last tag in `anc` (the ancestors of a line). */
+function contextOf(anc) {
+    const record = anc[0];
+    const parent = anc[anc.length - 1];
+    const depth = anc.length; // level of the child line
+    if (depth === 1)
+        return record;
+    if (parent === "SOUR" && record !== "HEAD" && !(record === "SOUR" && depth === 1))
+        return "CITATION";
+    if (parent === "PLAC")
+        return "PLAC";
+    if (parent === "MAP")
+        return "MAP";
+    if (parent === "_STORY")
+        return "_STORY";
+    if (parent === "_WITN")
+        return "_WITN";
+    if (parent === "ADDR")
+        return "ADDR";
+    if (parent === "DATA" && anc[depth - 2] === "SOUR")
+        return "CITATION.DATA";
+    if (depth === 2) {
+        if (record === "INDI" && INDI_EVENTS.includes(parent))
+            return "EVENT";
+        if (record === "FAM" && FAM_EVENTS.includes(parent))
+            return "EVENT";
+        return `${record}.${parent}`;
+    }
+    if (depth === 3 && parent === "ASSO")
+        return "EVENT.ASSO";
+    if (depth === 3 && (parent === "HUSB" || parent === "WIFE") && record === "FAM")
+        return `EVENT.${parent}`;
+    return undefined;
+}
+export function validateGedcom(text, opts = {}) {
+    const out = [];
+    const add = (level, line, message) => out.push({ level, line, message });
+    if (text.charCodeAt(0) === 0xfeff)
+        add("warn", 1, "file starts with a byte-order mark");
+    const rows = text.replace(/\r\n?/g, "\n").replace(/\n$/, "").split("\n");
+    const defined = new Map();
+    const pointers = [];
+    const stack = [];
+    let prevLevel = -1;
+    let charDeclared = false;
+    const headTags = new Set();
+    rows.forEach((raw, i) => {
+        const n = i + 1;
+        if (Buffer.byteLength(raw, "utf8") > MAX_LINE_BYTES)
+            add("error", n, `line is ${Buffer.byteLength(raw, "utf8")} bytes (max ${MAX_LINE_BYTES})`);
+        const m = LINE.exec(raw);
+        if (!m)
+            return void add("error", n, `not a GEDCOM line: ${raw.slice(0, 60)}`);
+        const level = Number(m[1]);
+        const xref = m[2];
+        const tag = m[3];
+        const value = m[4];
+        if (level > prevLevel + 1)
+            add("error", n, `level jumps from ${prevLevel} to ${level}`);
+        prevLevel = level;
+        stack.length = level;
+        if (level === 0) {
+            if (xref) {
+                if (defined.has(xref))
+                    add("error", n, `${xref} is defined twice`);
+                defined.set(xref, tag);
+            }
+            if (!["HEAD", "TRLR", "INDI", "FAM", "SOUR", "REPO", "NOTE", "SUBM", "SUBN", "OBJE"].includes(tag) && !tag.startsWith("_"))
+                add("error", n, `unknown record type ${tag}`);
+        }
+        else {
+            const ctx = contextOf(stack.slice(0, level));
+            const allowed = ctx ? CHILDREN[ctx] : undefined;
+            const parentTag = stack[level - 1];
+            if (tag === "CONC" || tag === "CONT") {
+                if (!TEXT_TAGS.has(parentTag) && !["CONC", "CONT"].includes(parentTag))
+                    add("warn", n, `${tag} under ${parentTag}`);
+            }
+            else if (allowed && !allowed.includes(tag))
+                add(tag.startsWith("_") ? "warn" : "error", n, `${tag} is not expected under ${ctx}`);
+        }
+        stack[level] = tag;
+        if (tag.startsWith("_") && (opts.strict || !EXTENSIONS.has(tag)))
+            add(opts.strict ? "error" : "warn", n, `non-standard tag ${tag}`);
+        if (value !== undefined && value !== value.trim() && tag !== "CONC")
+            add("warn", n, `value of ${tag} starts or ends with a space`);
+        if (tag === "CONC" && value !== undefined && (value.startsWith(" ") || value.endsWith(" ")))
+            add("warn", n, "CONC value starts or ends with a space (readers may trim it)");
+        if (value && /^@[^@ ]+@$/.test(value) && tag !== "CONC" && tag !== "CONT" && tag !== "NOTE")
+            pointers.push({ xref: value, line: n, tag });
+        else if (value && value.replace(/@@/g, "").includes("@") && !/^@#D[A-Z ]+@/.test(value))
+            add("error", n, `${tag}: a literal "@" must be written "@@" (otherwise readers take it for a pointer)`);
+        if (tag === "AGE" && value !== undefined && !isGedcomAge(value))
+            add("error", n, `AGE "${value}" is not a GEDCOM age (27y, 27y 3m, <1y, INFANT, STILLBORN, CHILD)`);
+        if (tag === "AGE" && stack[0] === "FAM" && level === 2)
+            add("error", n, "AGE of a family event belongs under HUSB or WIFE");
+        if (opts.strict && tag === "ASSO" && level > 1)
+            add("error", n, "ASSO under an event is GEDCOM 7; in 5.5.1 it belongs to the individual (1 ASSO)");
+        if (level === 1 && stack[0] === "HEAD")
+            headTags.add(tag);
+        if (tag === "CHAR" && level === 1) {
+            charDeclared = true;
+            if (value !== "UTF-8")
+                add("error", n, `CHAR ${value} — Strom Research writes UTF-8`);
+        }
+        if (tag === "DATE" && value && stack[level - 1] !== "HEAD" && normalizeDate(value) !== value)
+            add("error", n, `invalid date "${value}"`);
+        if (tag === "SEX" && value && !["M", "F", "U"].includes(value))
+            add("error", n, `SEX must be M, F or U, not "${value}"`);
+        if (tag === "QUAY" && value && !/^[0-3]$/.test(value))
+            add("error", n, `QUAY must be 0–3, not "${value}"`);
+        if (tag === "PEDI" && value && !["adopted", "birth", "foster", "sealing"].includes(value))
+            add(opts.strict ? "error" : "warn", n, `PEDI "${value}" is not GEDCOM 5.5.1 (adopted, birth, foster, sealing)`);
+        if (tag === "NAME" && level === 1 && stack[0] === "INDI" && value && (value.split("/").length - 1) % 2 !== 0)
+            add("error", n, `NAME "${value}": unbalanced surname slashes`);
+    });
+    if (rows[0] !== "0 HEAD")
+        add("error", 1, "file must start with 0 HEAD");
+    if (rows[rows.length - 1] !== "0 TRLR")
+        add("error", rows.length, "file must end with 0 TRLR");
+    if (!charDeclared)
+        add("error", 1, "HEAD has no 1 CHAR UTF-8");
+    for (const t of ["SOUR", "GEDC", "SUBM"])
+        if (!headTags.has(t))
+            add(opts.strict ? "error" : "warn", 1, `HEAD has no ${t} (required by GEDCOM 5.5.1)`);
+    if (headTags.has("SUBM") && ![...defined.values()].includes("SUBM"))
+        add(opts.strict ? "error" : "warn", 1, "the SUBM record named in HEAD is missing");
+    for (const p of pointers) {
+        const target = defined.get(p.xref);
+        if (!target)
+            add("error", p.line, `${p.tag} points to ${p.xref}, which is not defined`);
+    }
+    return out;
+}
+export function hasGedErrors(findings) {
+    return findings.some((f) => f.level === "error");
+}

package/dist/image/image.js

@@ -0,0 +1,223 @@
+// Raster images in memory and what is done with scans: crop, scale, contrast,
+// rotation, a grid to point at places. Pure TypeScript, no dependencies —
+// the codecs are in jpeg.ts and png.ts.
+export function blank(width, height, channels, value = 255) {
+    return { width, height, channels, data: new Uint8Array(width * height * channels).fill(value) };
+}
+/** Cut out a rectangle (clamped to the image). */
+export function crop(img, x, y, w, h) {
+    const x0 = Math.max(0, Math.min(img.width - 1, Math.round(x)));
+    const y0 = Math.max(0, Math.min(img.height - 1, Math.round(y)));
+    const cw = Math.max(1, Math.min(img.width - x0, Math.round(w)));
+    const ch = Math.max(1, Math.min(img.height - y0, Math.round(h)));
+    const c = img.channels;
+    const out = new Uint8Array(cw * ch * c);
+    for (let row = 0; row < ch; row++) {
+        const from = ((y0 + row) * img.width + x0) * c;
+        out.set(img.data.subarray(from, from + cw * c), row * cw * c);
+    }
+    return { width: cw, height: ch, channels: c, data: out };
+}
+/** Resize to w × h: area averaging when shrinking (no aliasing on fine script), bilinear when enlarging. */
+export function resize(img, w, h) {
+    w = Math.max(1, Math.round(w));
+    h = Math.max(1, Math.round(h));
+    if (w === img.width && h === img.height)
+        return img;
+    const c = img.channels;
+    const out = new Uint8Array(w * h * c);
+    const sx = img.width / w;
+    const sy = img.height / h;
+    if (sx >= 1 && sy >= 1) {
+        // Each output pixel is the mean of the source area it covers (with fractional edges).
+        const acc = new Float64Array(c);
+        for (let oy = 0; oy < h; oy++) {
+            const fy0 = oy * sy;
+            const fy1 = fy0 + sy;
+            for (let ox = 0; ox < w; ox++) {
+                const fx0 = ox * sx;
+                const fx1 = fx0 + sx;
+                acc.fill(0);
+                let total = 0;
+                for (let yy = Math.floor(fy0); yy < Math.min(img.height, Math.ceil(fy1)); yy++) {
+                    const wy = Math.min(fy1, yy + 1) - Math.max(fy0, yy);
+                    for (let xx = Math.floor(fx0); xx < Math.min(img.width, Math.ceil(fx1)); xx++) {
+                        const wgt = wy * (Math.min(fx1, xx + 1) - Math.max(fx0, xx));
+                        const p = (yy * img.width + xx) * c;
+                        for (let k = 0; k < c; k++)
+                            acc[k] += img.data[p + k] * wgt;
+                        total += wgt;
+                    }
+                }
+                const o = (oy * w + ox) * c;
+                for (let k = 0; k < c; k++)
+                    out[o + k] = Math.round(acc[k] / total);
+            }
+        }
+        return { width: w, height: h, channels: c, data: out };
+    }
+    for (let oy = 0; oy < h; oy++) {
+        const fy = Math.max(0, Math.min(img.height - 1, (oy + 0.5) * sy - 0.5));
+        const y0 = Math.floor(fy);
+        const y1 = Math.min(img.height - 1, y0 + 1);
+        const ty = fy - y0;
+        for (let ox = 0; ox < w; ox++) {
+            const fx = Math.max(0, Math.min(img.width - 1, (ox + 0.5) * sx - 0.5));
+            const x0 = Math.floor(fx);
+            const x1 = Math.min(img.width - 1, x0 + 1);
+            const tx = fx - x0;
+            const o = (oy * w + ox) * c;
+            for (let k = 0; k < c; k++) {
+                const a = img.data[(y0 * img.width + x0) * c + k];
+                const b = img.data[(y0 * img.width + x1) * c + k];
+                const d = img.data[(y1 * img.width + x0) * c + k];
+                const e = img.data[(y1 * img.width + x1) * c + k];
+                out[o + k] = Math.round((a * (1 - tx) + b * tx) * (1 - ty) + (d * (1 - tx) + e * tx) * ty);
+            }
+        }
+    }
+    return { width: w, height: h, channels: c, data: out };
+}
+export function toRgb(img) {
+    if (img.channels === 3)
+        return img;
+    const out = new Uint8Array(img.width * img.height * 3);
+    for (let i = 0, p = 0; i < img.data.length; i++, p += 3)
+        out[p] = out[p + 1] = out[p + 2] = img.data[i];
+    return { width: img.width, height: img.height, channels: 3, data: out };
+}
+/** Put a picture into another at x, y (its top left corner), clipped at the edges; same channels. */
+export function paste(into, img, x, y) {
+    const c = into.channels;
+    const x0 = Math.max(0, x);
+    const x1 = Math.min(into.width, x + img.width);
+    if (x1 <= x0)
+        return;
+    for (let row = Math.max(0, y); row < Math.min(into.height, y + img.height); row++) {
+        const from = ((row - y) * img.width + (x0 - x)) * c;
+        into.data.set(img.data.subarray(from, from + (x1 - x0) * c), (row * into.width + x0) * c);
+    }
+}
+export function toGrey(img) {
+    if (img.channels === 1)
+        return img;
+    const out = new Uint8Array(img.width * img.height);
+    for (let i = 0, p = 0; i < out.length; i++, p += 3)
+        out[i] = Math.round(0.299 * img.data[p] + 0.587 * img.data[p + 1] + 0.114 * img.data[p + 2]);
+    return { width: img.width, height: img.height, channels: 1, data: out };
+}
+/**
+ * Stretch the contrast between two percentiles of brightness. Done on the
+ * part being read, never on the whole scan (a dark margin would flatten the
+ * ink of the column — a lesson from reading faded registers).
+ */
+export function stretch(img, lowPct = 1, highPct = 99) {
+    const c = img.channels;
+    const hist = new Uint32Array(256);
+    const n = img.width * img.height;
+    for (let i = 0; i < n; i++) {
+        const p = i * c;
+        const lum = c === 1 ? img.data[p] : Math.round(0.299 * img.data[p] + 0.587 * img.data[p + 1] + 0.114 * img.data[p + 2]);
+        hist[lum]++;
+    }
+    const at = (pct) => {
+        let acc = 0;
+        // at least one pixel: 0 % is the darkest value present, 100 % the lightest
+        const target = Math.max(1, Math.ceil((pct / 100) * n));
+        for (let v = 0; v < 256; v++) {
+            acc += hist[v];
+            if (acc >= target)
+                return v;
+        }
+        return 255;
+    };
+    const lo = at(lowPct);
+    const hi = Math.max(lo + 1, at(highPct));
+    const map = new Uint8Array(256);
+    for (let v = 0; v < 256; v++)
+        map[v] = Math.max(0, Math.min(255, Math.round(((v - lo) * 255) / (hi - lo))));
+    const out = new Uint8Array(img.data.length);
+    for (let i = 0; i < out.length; i++)
+        out[i] = map[img.data[i]];
+    return { ...img, data: out };
+}
+/** Rotate by 90, 180 or 270 degrees clockwise. */
+export function rotate(img, degrees) {
+    const { width: w, height: h, channels: c } = img;
+    const nw = degrees === 180 ? w : h;
+    const nh = degrees === 180 ? h : w;
+    const out = new Uint8Array(img.data.length);
+    for (let y = 0; y < h; y++)
+        for (let x = 0; x < w; x++) {
+            const [nx, ny] = degrees === 90 ? [h - 1 - y, x] : degrees === 180 ? [w - 1 - x, h - 1 - y] : [y, w - 1 - x];
+            const s = (y * w + x) * c;
+            const d = (ny * nw + nx) * c;
+            for (let k = 0; k < c; k++)
+                out[d + k] = img.data[s + k];
+        }
+    return { width: nw, height: nh, channels: c, data: out };
+}
+/** 3×5 pixel digits for grid labels. */
+const DIGITS = ["111101101101111", "010110010010111", "111001111100111", "111001111001111", "101101111001001", "111100111001111", "111100111101111", "111001001001001", "111101111101111", "111101111001111"];
+function label(img, text, x, y, scale) {
+    const c = img.channels;
+    const put = (px, py, v) => {
+        if (px < 0 || py < 0 || px >= img.width || py >= img.height)
+            return;
+        const p = (py * img.width + px) * c;
+        for (let k = 0; k < c; k++)
+            img.data[p + k] = v[k] ?? v[0];
+    };
+    const fg = c === 3 ? [200, 0, 0] : [0];
+    const bg = [255, 255, 255];
+    const cw = 4 * scale;
+    // white box behind, so the digits stay readable on ink
+    for (let py = y - scale; py < y + 6 * scale; py++)
+        for (let px = x - scale; px < x + text.length * cw; px++)
+            put(px, py, bg);
+    [...text].forEach((ch, i) => {
+        const bits = DIGITS[Number(ch)];
+        if (!bits)
+            return;
+        for (let r = 0; r < 5; r++)
+            for (let col = 0; col < 3; col++)
+                if (bits[r * 3 + col] === "1")
+                    for (let dy = 0; dy < scale; dy++)
+                        for (let dx = 0; dx < scale; dx++)
+                            put(x + i * cw + col * scale + dx, y + r * scale + dy, fg);
+    });
+}
+/**
+ * A grid of tenths with labels 0–10 along the edges: the agent reads off where
+ * something is ("x 0.3–0.5, y 0.6–0.7") and asks for exactly that crop.
+ */
+export function grid(img, parts = 10) {
+    const out = { ...img, data: new Uint8Array(img.data) };
+    const c = out.channels;
+    const line = c === 3 ? [220, 0, 0] : [0];
+    const scale = Math.max(1, Math.round(Math.min(img.width, img.height) / 400));
+    const put = (x, y) => {
+        const p = (y * out.width + x) * c;
+        for (let k = 0; k < c; k++)
+            out.data[p + k] = line[k] ?? line[0];
+    };
+    for (let i = 1; i < parts; i++) {
+        const x = Math.round((i * out.width) / parts);
+        const y = Math.round((i * out.height) / parts);
+        for (let yy = 0; yy < out.height; yy += i % 5 === 0 ? 1 : 2)
+            for (let t = 0; t < (i % 5 === 0 ? scale + 1 : scale); t++)
+                if (x + t < out.width)
+                    put(x + t, yy);
+        for (let xx = 0; xx < out.width; xx += i % 5 === 0 ? 1 : 2)
+            for (let t = 0; t < (i % 5 === 0 ? scale + 1 : scale); t++)
+                if (y + t < out.height)
+                    put(xx, y + t);
+    }
+    for (let i = 0; i <= parts; i++) {
+        const x = Math.min(out.width - 8 * scale, Math.round((i * out.width) / parts) + 2 * scale);
+        const y = Math.min(out.height - 8 * scale, Math.round((i * out.height) / parts) + 2 * scale);
+        label(out, String(i), x, 2 * scale, scale);
+        label(out, String(i), 2 * scale, y, scale);
+    }
+    return out;
+}

package/dist/image/index.js

@@ -0,0 +1,114 @@
+// Reading and writing image files by their content, not their name.
+import fs from "node:fs";
+import { decodeJpeg } from "./jpeg-decode.js";
+import { encodeJpeg } from "./jpeg-encode.js";
+import { decodePng, encodePng } from "./png.js";
+export function formatOf(bytes) {
+    const b = (i) => bytes[i] ?? -1;
+    if (b(0) === 0xff && b(1) === 0xd8)
+        return "jpeg";
+    if (b(0) === 0x89 && b(1) === 0x50 && b(2) === 0x4e && b(3) === 0x47)
+        return "png";
+    if ((b(0) === 0x49 && b(1) === 0x49 && b(2) === 0x2a) || (b(0) === 0x4d && b(1) === 0x4d && b(3) === 0x2a))
+        return "tiff";
+    if (b(0) === 0x47 && b(1) === 0x49 && b(2) === 0x46)
+        return "gif";
+    if (b(0) === 0x52 && b(1) === 0x49 && b(2) === 0x46 && b(3) === 0x46 && b(8) === 0x57 && b(9) === 0x45)
+        return "webp";
+    if (b(4) === 0x66 && b(5) === 0x74 && b(6) === 0x79 && b(7) === 0x70 && [0x68, 0x6d].includes(b(8)))
+        return "heic";
+    if (b(0) === 0x25 && b(1) === 0x50 && b(2) === 0x44 && b(3) === 0x46)
+        return "pdf";
+    return "unknown";
+}
+export class ImageFormatError extends Error {
+}
+/** Decode a JPEG or PNG; anything else gets a clear message about what to do. */
+export function decodeImage(bytes) {
+    const f = formatOf(bytes);
+    if (f === "jpeg")
+        return decodeJpeg(bytes);
+    if (f === "png")
+        return decodePng(bytes);
+    throw new ImageFormatError(f === "unknown" ? "not an image strom can read (JPEG or PNG)" : `${f.toUpperCase()} cannot be cropped by strom yet — only JPEG and PNG; convert the file (any image viewer can save it as JPEG)`);
+}
+export function encodeImage(img, format, quality = 88) {
+    return format === "png" ? encodePng(img) : encodeJpeg(img, quality);
+}
+/** Width and height without decoding the whole image (JPEG SOF / PNG IHDR). */
+export function imageSize(bytes) {
+    const f = formatOf(bytes);
+    if (f === "png") {
+        const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        return { width: v.getUint32(16), height: v.getUint32(20) };
+    }
+    if (f === "jpeg") {
+        let p = 2;
+        while (p + 9 < bytes.length) {
+            if (bytes[p] !== 0xff) {
+                p++;
+                continue;
+            }
+            const m = bytes[p + 1];
+            if (m >= 0xc0 && m <= 0xcf && m !== 0xc4 && m !== 0xc8 && m !== 0xcc)
+                return { height: (bytes[p + 5] << 8) | bytes[p + 6], width: (bytes[p + 7] << 8) | bytes[p + 8] };
+            if (m === 0xd8 || m === 0x01 || (m >= 0xd0 && m <= 0xd7)) {
+                p += 2;
+                continue;
+            }
+            p += 2 + ((bytes[p + 2] << 8) | bytes[p + 3]);
+        }
+    }
+    return undefined;
+}
+/**
+ * Width and height of an image file, read from its header without loading it: a JPEG is walked
+ * segment by segment, so metadata of any size before the frame (EXIF, ICC, thumbnails) does not matter.
+ */
+export function imageSizeOfFile(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+        const at = (pos, n) => {
+            const b = Buffer.alloc(n);
+            return b.subarray(0, fs.readSync(fd, b, 0, n, pos));
+        };
+        const head = at(0, 32);
+        const f = formatOf(head);
+        if (f === "png")
+            return head.length >= 24 ? { width: head.readUInt32BE(16), height: head.readUInt32BE(20) } : undefined;
+        if (f !== "jpeg")
+            return undefined;
+        const size = fs.fstatSync(fd).size;
+        let pos = 2;
+        for (let i = 0; i < 10_000 && pos + 4 <= size; i++) {
+            const m = at(pos, 4);
+            if (m[0] !== 0xff)
+                return undefined;
+            const marker = m[1];
+            if (marker === 0xff) {
+                pos++; // fill byte
+                continue;
+            }
+            if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+                pos += 2;
+                continue;
+            }
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                const sof = at(pos + 5, 4);
+                return sof.length === 4 ? { height: sof.readUInt16BE(0), width: sof.readUInt16BE(2) } : undefined;
+            }
+            if (marker === 0xd9 || marker === 0xda)
+                return undefined; // the image data came before any frame
+            pos += 2 + m.readUInt16BE(2);
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}