ofw-mcp 2.7.0 → 2.8.0

package/dist/extract/pdf.js

@@ -0,0 +1,278 @@
+// PDF text-layer extraction.
+//
+// A PDF has no "text" — it has content streams full of positioning operators
+// that draw glyphs. This reads the text-showing operators (Tj/TJ/'/") out of
+// each page's content stream and reassembles a readable transcript. It is not
+// a renderer: exotic font encodings without a ToUnicode map will come back as
+// mojibake, and column layout is approximated by line breaks.
+//
+// What it must never do is fail silently. A scanned PDF has no text layer at
+// all, and the honest answer for one is `textLayer: false` plus a note saying
+// it needs OCR — not an empty string that reads like an empty document.
+import { inflateBounded, DecompressionLimitError, MAX_DECOMPRESSED_BYTES, } from './inflate.js';
+const OBJ_HEADER = /(\d+)\s+\d+\s+obj\b/g;
+function parseObjects(text) {
+    const objects = new Map();
+    for (let m = OBJ_HEADER.exec(text); m !== null; m = OBJ_HEADER.exec(text)) {
+        const start = m.index + m[0].length;
+        const end = text.indexOf('endobj', start);
+        objects.set(Number(m[1]), {
+            num: Number(m[1]),
+            body: text.slice(start, end === -1 ? undefined : end),
+            start,
+        });
+    }
+    OBJ_HEADER.lastIndex = 0;
+    return objects;
+}
+/** Object numbers referenced by `N 0 R` tokens in a fragment. */
+function refsIn(fragment) {
+    return [...fragment.matchAll(/(\d+)\s+\d+\s+R\b/g)].map((m) => Number(m[1]));
+}
+/**
+ * Page objects in reading order: walk the catalog's page tree when it
+ * resolves, otherwise fall back to the order the page objects appear in the
+ * file (which matches reading order for any linearly-written PDF).
+ */
+function orderedPages(objects) {
+    const isPage = (o) => /\/Type\s*\/Page[^s]/.test(o.body);
+    const inFileOrder = [...objects.values()].filter(isPage).sort((a, b) => a.start - b.start);
+    const catalog = [...objects.values()].find((o) => /\/Type\s*\/Catalog/.test(o.body));
+    const rootRef = catalog ? refsIn(/\/Pages\s+[^/>]*/.exec(catalog.body)?.[0] ?? '')[0] : undefined;
+    if (rootRef === undefined)
+        return inFileOrder;
+    const ordered = [];
+    const seen = new Set();
+    const walk = (num) => {
+        // A malformed (or hostile) page tree can contain a cycle; visiting each
+        // object at most once bounds the walk without rejecting the document.
+        if (seen.has(num))
+            return;
+        seen.add(num);
+        const obj = objects.get(num);
+        if (!obj)
+            return;
+        if (isPage(obj)) {
+            ordered.push(obj);
+            return;
+        }
+        const kids = /\/Kids\s*\[([^\]]*)\]/.exec(obj.body)?.[1];
+        if (kids)
+            for (const kid of refsIn(kids))
+                walk(kid);
+    };
+    walk(rootRef);
+    return ordered.length > 0 ? ordered : inFileOrder;
+}
+/** Raw (still-encoded) bytes of a stream object, or null when it has none. */
+function streamBytes(bytes, obj) {
+    const marker = /stream\r?\n/.exec(obj.body);
+    if (!marker)
+        return null;
+    const from = obj.start + marker.index + marker[0].length;
+    // /Length is frequently an indirect reference, so the end-of-stream marker is
+    // the reliable boundary; a direct numeric /Length is used when present.
+    const declared = /\/Length\s+(\d+)(?!\s+\d+\s+R)/.exec(obj.body);
+    if (declared)
+        return bytes.subarray(from, from + Number(declared[1]));
+    const end = bytes.indexOf('endstream', from, 'latin1');
+    return bytes.subarray(from, end === -1 ? undefined : end);
+}
+/** Decode a stream's bytes, honouring FlateDecode. Null for filters we can't read. */
+async function decodeStream(bytes, obj) {
+    const raw = streamBytes(bytes, obj);
+    if (!raw)
+        return null;
+    const filter = /\/Filter\s*(\/\w+|\[[^\]]*\])/.exec(obj.body)?.[1] ?? '';
+    if (filter === '')
+        return raw;
+    if (!filter.includes('FlateDecode'))
+        return null; // LZW/DCT/JPX: not text anyway
+    try {
+        // PDF stream dictionaries say nothing about inflated length, so the cap is
+        // the only thing standing between a crafted stream and the memory budget.
+        return await inflateBounded(raw, 'deflate', MAX_DECOMPRESSED_BYTES, 'PDF stream');
+    }
+    catch (err) {
+        // A truncated or mis-bounded stream must not take the whole document down;
+        // the page simply contributes no text. A cap breach is different in kind —
+        // that is a hostile or absurd file, and silently returning a document with
+        // pages quietly missing would be the worse answer.
+        if (err instanceof DecompressionLimitError)
+            throw err;
+        return null;
+    }
+}
+/** Read a PDF literal string starting at `text[i]` === '(' — returns its end index. */
+function readLiteral(text, i) {
+    let value = '';
+    let depth = 1;
+    let p = i + 1;
+    for (; p < text.length; p++) {
+        const ch = text[p];
+        if (ch === '\\') {
+            const esc = text[++p];
+            const simple = { n: '\n', r: '\r', t: '\t', b: '\b', f: '\f' };
+            if (simple[esc]) {
+                value += simple[esc];
+                continue;
+            }
+            const octal = /^[0-7]{1,3}/.exec(text.slice(p, p + 3))?.[0];
+            if (octal) {
+                value += String.fromCharCode(parseInt(octal, 8));
+                p += octal.length - 1;
+                continue;
+            }
+            if (esc === '\n')
+                continue; // line continuation
+            value += esc;
+            continue;
+        }
+        if (ch === '(') {
+            depth++;
+            value += ch;
+            continue;
+        }
+        if (ch === ')') {
+            depth--;
+            if (depth === 0)
+                break;
+            value += ch;
+            continue;
+        }
+        value += ch;
+    }
+    return { value, next: p };
+}
+/** Decode a `<...>` hex string, as UTF-16BE when it looks like one. */
+function decodeHexString(hex) {
+    const clean = hex.replace(/[^0-9a-fA-F]/g, '');
+    const padded = clean.length % 2 === 1 ? `${clean}0` : clean;
+    const buf = Buffer.from(padded, 'hex');
+    if (buf.length >= 2 && buf.length % 2 === 0 && buf[0] === 0xfe && buf[1] === 0xff) {
+        return buf.subarray(2).swap16().toString('utf16le');
+    }
+    // Simple CID fonts emit 2-byte codes whose high byte is zero; reading those
+    // as latin1 would interleave NULs through every word.
+    if (buf.length % 2 === 0 && buf.length > 0 && buf.every((b, i) => i % 2 === 1 || b === 0)) {
+        return buf.swap16().toString('utf16le');
+    }
+    return buf.toString('latin1');
+}
+/**
+ * Pull the shown text out of a content stream. Text-positioning operators
+ * become line breaks, and the wide negative kerns inside a TJ array become
+ * spaces (that is how most producers encode an inter-word gap).
+ */
+export function textFromContentStream(content) {
+    let out = '';
+    let pending = '';
+    let arrayDepth = 0;
+    for (let i = 0; i < content.length; i++) {
+        const ch = content[i];
+        if (ch === '(') {
+            const { value, next } = readLiteral(content, i);
+            pending += value;
+            i = next;
+            continue;
+        }
+        // `<<` opens a dictionary (marked-content properties, inline images).
+        // Skipping both angle brackets keeps the dictionary's own text from being
+        // read as a hex string.
+        if (ch === '<' && content[i + 1] === '<') {
+            i++;
+            continue;
+        }
+        if (ch === '<') {
+            const end = content.indexOf('>', i);
+            if (end === -1)
+                break;
+            pending += decodeHexString(content.slice(i + 1, end));
+            i = end;
+            continue;
+        }
+        if (ch === '[') {
+            arrayDepth++;
+            continue;
+        }
+        if (ch === ']') {
+            arrayDepth = 0;
+            continue;
+        }
+        if (arrayDepth > 0 && (ch === '-' || (ch >= '0' && ch <= '9'))) {
+            const num = /^-?\d+(\.\d+)?/.exec(content.slice(i));
+            /* v8 ignore next -- the leading char already guarantees a match */
+            if (!num)
+                continue;
+            if (Number(num[0]) <= -100)
+                pending += ' ';
+            i += num[0].length - 1;
+            continue;
+        }
+        if (/[A-Za-z'"*]/.test(ch)) {
+            /* v8 ignore next -- the character class above guarantees this regex matches */
+            const op = /^[A-Za-z*]+|^['"]/.exec(content.slice(i))?.[0] ?? ch;
+            i += op.length - 1;
+            if (op === 'Tj' || op === 'TJ') {
+                out += pending;
+                pending = '';
+                continue;
+            }
+            if (op === "'" || op === '"') {
+                out += `\n${pending}`;
+                pending = '';
+                continue;
+            }
+            if (op === 'Td' || op === 'TD' || op === 'T*' || op === 'ET') {
+                out += '\n';
+                continue;
+            }
+        }
+    }
+    return out;
+}
+/** Collapse the runs of blank lines that positioning operators leave behind. */
+function tidy(text) {
+    return text.replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+/** Extract the text layer of a PDF, page by page. */
+export async function extractPdf(bytes, opts = {}) {
+    const text = bytes.toString('latin1');
+    if (/\/Encrypt\b/.test(text)) {
+        throw new Error('the PDF is encrypted; its text cannot be extracted');
+    }
+    const objects = parseObjects(text);
+    const pageObjects = orderedPages(objects);
+    if (pageObjects.length === 0)
+        throw new Error('no pages found in the PDF');
+    const pages = [];
+    const omitted = [];
+    for (let i = 0; i < pageObjects.length; i++) {
+        const number = i + 1;
+        if (opts.select && !opts.select(i, `page ${number}`)) {
+            omitted.push(`page ${number}`);
+            continue;
+        }
+        const contentsFragment = /\/Contents\s*(\d+\s+\d+\s+R|\[[^\]]*\])/.exec(pageObjects[i].body)?.[1] ?? '';
+        let raw = '';
+        for (const ref of refsIn(contentsFragment)) {
+            const streamObj = objects.get(ref);
+            if (!streamObj)
+                continue;
+            const decoded = await decodeStream(bytes, streamObj);
+            if (decoded)
+                raw += `${decoded.toString('latin1')}\n`;
+        }
+        pages.push({ number, text: tidy(textFromContentStream(raw)) });
+    }
+    const textLayer = pages.some((p) => p.text !== '');
+    return {
+        kind: 'pdf',
+        pages,
+        textLayer,
+        ...(textLayer ? {} : {
+            note: 'This PDF has no extractable text layer — it is most likely a scan or an image-only export. Reading it requires OCR, which this server does not perform.',
+        }),
+        ...(omitted.length ? { omitted } : {}),
+    };
+}

package/dist/extract/presentation.js

@@ -0,0 +1,54 @@
+// PowerPoint (.pptx) text extraction: one entry per slide, plus the speaker
+// notes attached to it.
+//
+// Notes parts are numbered independently of slides (notesSlide2.xml can belong
+// to slide 5), so the notes link is followed through the slide's relationship
+// part rather than guessed from the file name.
+import { readZip } from './zip.js';
+import { decodeXmlEntities, elements } from './xml.js';
+import { readRels } from './ooxml.js';
+const SLIDE_PATH = /^ppt\/slides\/slide(\d+)\.xml$/;
+/** Text of every `<a:p>` paragraph in a slide/notes part, one per line. */
+function slideText(xml) {
+    const lines = [];
+    for (const p of elements(xml, 'a:p')) {
+        let line = '';
+        for (const t of elements(p.inner, 'a:t'))
+            line += decodeXmlEntities(t.inner);
+        if (line !== '')
+            lines.push(line);
+    }
+    return lines.join('\n');
+}
+/** Extract text and speaker notes from every (selected) slide. */
+export async function extractPptx(bytes, opts = {}) {
+    const zip = await readZip(bytes);
+    const paths = zip.names()
+        .map((name) => ({ name, n: Number(SLIDE_PATH.exec(name)?.[1]) }))
+        .filter((e) => Number.isFinite(e.n))
+        // slide10 sorts before slide2 lexically; presentation order is numeric.
+        .sort((a, b) => a.n - b.n);
+    if (paths.length === 0)
+        throw new Error('no slides found in the .pptx archive');
+    const slides = [];
+    const omitted = [];
+    for (let i = 0; i < paths.length; i++) {
+        const { name } = paths[i];
+        const number = i + 1;
+        if (opts.select && !opts.select(i, `slide ${number}`)) {
+            omitted.push(`slide ${number}`);
+            continue;
+        }
+        /* v8 ignore next -- `name` came from zip.names(), so readText cannot be null here */
+        const text = slideText((await zip.readText(name)) ?? '');
+        const notesRel = (await readRels(zip, name)).find((r) => r.type.endsWith('/notesSlide'));
+        const notesXml = notesRel ? await zip.readText(notesRel.target) : null;
+        const notes = notesXml === null ? '' : slideText(notesXml);
+        slides.push({ number, text, ...(notes ? { notes } : {}) });
+    }
+    return {
+        kind: 'presentation',
+        slides,
+        ...(omitted.length ? { omitted } : {}),
+    };
+}

package/dist/extract/spreadsheet.js

@@ -0,0 +1,258 @@
+// Spreadsheet extraction: .xlsx/.xlsm (OOXML) and .csv/.tsv (delimited text).
+//
+// Both land on the same shape — a list of named sheets with a CSV rendering —
+// so a caller reading a custody schedule does not care which one arrived.
+//
+// The values written out are Excel's own CACHED results: a formula cell stores
+// both `<f>` (the formula) and `<v>` (what it last evaluated to), and `<v>` is
+// what the co-parent saw on screen. Dates are the other translation that
+// matters — Excel stores them as bare serial numbers, so a schedule extracted
+// without style lookup reads as a column of five-digit integers.
+import { readZip } from './zip.js';
+import { elements, attr, textOf } from './xml.js';
+import { readRels, findPart, dirOf, resolvePartPath } from './ooxml.js';
+const DEFAULT_MAX_CELLS = 200_000;
+// Built-in number formats that denote a date and/or time (ECMA-376 §18.8.30).
+const BUILTIN_DATE_FORMATS = new Set([14, 15, 16, 17, 18, 19, 20, 21, 22, 45, 46, 47]);
+/** Excel's serial-date epoch as a Unix-epoch offset, in days. */
+const SERIAL_EPOCH_OFFSET = 25569;
+/**
+ * Convert an Excel serial number to an ISO string: `YYYY-MM-DD` for a whole
+ * day, `…THH:MM:SS` when it carries a time, and `HH:MM:SS` for a time-only
+ * value (serial < 1). Returns null when the serial is out of representable
+ * range, so the caller can fall back to printing the raw number.
+ */
+export function excelSerialToIso(serial, date1904) {
+    // The 1904 system counts from a different epoch, exactly 1462 days later.
+    const base = date1904 ? serial + 1462 : serial;
+    // Excel's 1900 system contains a phantom 1900-02-29 (serial 60) inherited
+    // from Lotus 1-2-3, so serials below it are one day ahead of real time.
+    const corrected = Math.floor(base) < 60 ? base + 1 : base;
+    const date = new Date(Math.round((corrected - SERIAL_EPOCH_OFFSET) * 86_400_000));
+    if (Number.isNaN(date.getTime()))
+        return null;
+    const iso = date.toISOString();
+    if (base < 1)
+        return iso.slice(11, 19);
+    return iso.slice(11, 19) === '00:00:00' ? iso.slice(0, 10) : iso.slice(0, 19);
+}
+/** True when a number format renders its value as a date or a time. */
+function isDateFormat(numFmtId, formatCode) {
+    if (BUILTIN_DATE_FORMATS.has(numFmtId))
+        return true;
+    if (!formatCode)
+        return false;
+    // Strip literals and colour/condition brackets before looking for date
+    // tokens, so a currency format like [$-409]#,##0.00 is not read as a date.
+    const bare = formatCode.replace(/"[^"]*"/g, '').replace(/\[[^\]]*\]/g, '').replace(/\\./g, '');
+    return /[ymdhs]/i.test(bare);
+}
+/** Column index (0-based) from a cell reference like `AA12`. */
+function columnIndex(ref) {
+    const m = /^([A-Z]+)/.exec(ref);
+    if (!m)
+        return null;
+    let index = 0;
+    for (const ch of m[1])
+        index = index * 26 + (ch.charCodeAt(0) - 64);
+    return index - 1;
+}
+/** Quote a CSV field per RFC 4180 when it contains a delimiter, quote or newline. */
+function csvField(value) {
+    return /[",\r\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+function toCsv(rows, cols) {
+    return rows
+        .map((row) => Array.from({ length: cols }, (_, i) => csvField(row[i] ?? '')).join(','))
+        .join('\n');
+}
+async function readStyles(zip, dir) {
+    const xml = await zip.readText(`${dir}styles.xml`);
+    if (!xml)
+        return { dateStyles: [] };
+    const custom = new Map();
+    for (const el of elements(xml, 'numFmt')) {
+        const id = Number(attr(el.attrs, 'numFmtId'));
+        const code = attr(el.attrs, 'formatCode');
+        if (Number.isFinite(id) && code !== null)
+            custom.set(id, code);
+    }
+    const dateStyles = [];
+    // Only <cellXfs> maps the `s` attribute; <cellStyleXfs> uses the same <xf>
+    // tag, so scan inside the cellXfs block rather than the whole part.
+    for (const block of elements(xml, 'cellXfs')) {
+        for (const xf of elements(block.inner, 'xf')) {
+            const id = Number(attr(xf.attrs, 'numFmtId') ?? '0');
+            dateStyles.push(isDateFormat(id, custom.get(id)));
+        }
+    }
+    return { dateStyles };
+}
+async function readSharedStrings(zip, dir) {
+    const xml = await zip.readText(`${dir}sharedStrings.xml`);
+    if (!xml)
+        return [];
+    // <si> may hold a single <t> or a sequence of <r> runs each with its own
+    // <t>; concatenating every <t> handles both.
+    return [...elements(xml, 'si')].map((si) => textOf(si.inner, 't'));
+}
+function cellValue(attrs, inner, ctx) {
+    const type = attr(attrs, 't') ?? 'n';
+    if (type === 'inlineStr')
+        return textOf(inner, 't');
+    const raw = textOf(inner, 'v');
+    switch (type) {
+        case 's': {
+            const index = Number(raw);
+            return ctx.shared[index] ?? '';
+        }
+        case 'b':
+            return raw === '1' ? 'TRUE' : 'FALSE';
+        case 'str':
+        case 'e':
+            return raw;
+        default: {
+            const styleIndex = Number(attr(attrs, 's') ?? '-1');
+            const numeric = Number(raw);
+            if (ctx.styles.dateStyles[styleIndex] && raw !== '' && Number.isFinite(numeric)) {
+                return excelSerialToIso(numeric, ctx.date1904) ?? raw;
+            }
+            return raw;
+        }
+    }
+}
+function parseSheet(xml, name, ctx, maxCells) {
+    const rows = [];
+    let cols = 0;
+    let cells = 0;
+    let truncated = false;
+    for (const row of elements(xml, 'row')) {
+        if (cells >= maxCells) {
+            truncated = true;
+            break;
+        }
+        const values = [];
+        for (const cell of elements(row.inner, 'c')) {
+            const ref = attr(cell.attrs, 'r');
+            const index = ref === null ? null : columnIndex(ref);
+            // A cell with no usable reference cannot be placed in a column; dropping
+            // it is better than shifting every later value in the row.
+            if (index === null)
+                continue;
+            values[index] = cellValue(cell.attrs, cell.inner, ctx);
+            cells++;
+            if (index + 1 > cols)
+                cols = index + 1;
+        }
+        rows.push(values);
+    }
+    return { name, rows: rows.length, cols, csv: toCsv(rows, cols), ...(truncated ? { truncated } : {}) };
+}
+/** Extract every (selected) sheet of an .xlsx/.xlsm workbook. */
+export async function extractXlsx(bytes, opts = {}) {
+    const zip = await readZip(bytes);
+    const workbookPath = findPart(zip, 'xl/workbook.xml', 'workbook.xml');
+    if (!workbookPath)
+        throw new Error('no workbook part found in the .xlsx archive');
+    const dir = dirOf(workbookPath);
+    /* v8 ignore next -- findPart only returns a name the archive contains, so readText cannot be null here */
+    const workbookXml = (await zip.readText(workbookPath)) ?? '';
+    const rels = await readRels(zip, workbookPath);
+    const targetById = new Map(rels.map((r) => [r.id, r.target]));
+    const ctx = {
+        shared: await readSharedStrings(zip, dir),
+        styles: await readStyles(zip, dir),
+        date1904: /<workbookPr[^>]*date1904="(1|true)"/i.test(workbookXml),
+    };
+    const maxCells = opts.maxCells ?? DEFAULT_MAX_CELLS;
+    const sheets = [];
+    const omitted = [];
+    let index = 0;
+    for (const el of elements(workbookXml, 'sheet')) {
+        const position = index++;
+        const name = attr(el.attrs, 'name') ?? `Sheet${position + 1}`;
+        if (opts.select && !opts.select(position, name)) {
+            omitted.push(name);
+            continue;
+        }
+        const relId = attr(el.attrs, 'r:id') ?? attr(el.attrs, 'id');
+        // Fall back to the conventional positional path when the rels are absent
+        // or do not name this sheet — some producers omit them entirely.
+        const path = (relId && targetById.get(relId))
+            ?? resolvePartPath(dir, `worksheets/sheet${position + 1}.xml`);
+        const xml = await zip.readText(path);
+        if (xml === null) {
+            omitted.push(`${name} (sheet part not found in the workbook)`);
+            continue;
+        }
+        sheets.push(parseSheet(xml, name, ctx, maxCells));
+    }
+    const truncated = sheets.some((s) => s.truncated);
+    return {
+        kind: 'spreadsheet',
+        sheets,
+        ...(omitted.length ? { omitted } : {}),
+        ...(truncated ? { truncated } : {}),
+    };
+}
+/** Parse delimiter-separated text (RFC 4180 quoting) into rows of fields. */
+function parseDelimitedRows(text, delimiter) {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let quoted = false;
+    let dirty = false; // distinguishes a trailing newline from a trailing empty row
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (quoted) {
+            if (ch !== '"') {
+                field += ch;
+                continue;
+            }
+            if (text[i + 1] === '"') {
+                field += '"';
+                i++;
+                continue;
+            }
+            quoted = false;
+            continue;
+        }
+        if (ch === '"') {
+            quoted = true;
+            dirty = true;
+            continue;
+        }
+        if (ch === delimiter) {
+            row.push(field);
+            field = '';
+            dirty = true;
+            continue;
+        }
+        if (ch === '\r')
+            continue; // CRLF: the \n does the work
+        if (ch === '\n') {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+            dirty = false;
+            continue;
+        }
+        field += ch;
+        dirty = true;
+    }
+    if (dirty || field !== '') {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+/** Extract .csv/.tsv text as a single-sheet spreadsheet. */
+export function extractDelimited(text, name, delimiter) {
+    const rows = parseDelimitedRows(text, delimiter);
+    const cols = rows.reduce((max, r) => Math.max(max, r.length), 0);
+    return {
+        kind: 'spreadsheet',
+        sheets: [{ name, rows: rows.length, cols, csv: toCsv(rows, cols) }],
+    };
+}

package/dist/extract/types.js

@@ -0,0 +1,4 @@
+// The shape every extractor returns. One discriminated union so the download
+// tool can hand back "here is the content" without knowing which format it
+// came from, and so a caller can branch on `kind` instead of on MIME strings.
+export {};

package/dist/extract/xml.js

@@ -0,0 +1,61 @@
+// Just enough XML for OOXML part-reading.
+//
+// The office formats are machine-generated XML with a known, flat shape per
+// part (rows of cells, runs of text), so a scanning reader beats pulling in a
+// DOM parser that has to run in both Node and workerd. The one rule this file
+// exists to enforce is that a tag match is anchored on the FULL tag name:
+// naively scanning for `<w:p` also matches `<w:pPr>`, which silently turns
+// paragraph properties into paragraphs.
+//
+// Known limitation: attribute values containing a literal `>` (legal but never
+// emitted by Word/Excel/PowerPoint) would end an element match early.
+const NAMED_ENTITIES = {
+    amp: '&', lt: '<', gt: '>', quot: '"', apos: "'",
+};
+/** Decode the predefined XML entities plus numeric character references. */
+export function decodeXmlEntities(text) {
+    if (!text.includes('&'))
+        return text;
+    return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body) => {
+        if (body[0] === '#') {
+            const code = body[1] === 'x' || body[1] === 'X'
+                ? parseInt(body.slice(2), 16)
+                : parseInt(body.slice(1), 10);
+            return String.fromCodePoint(code);
+        }
+        // An unrecognized entity is left verbatim: mangling it would be worse than
+        // showing it, and OOXML only emits the five predefined ones.
+        return NAMED_ENTITIES[body] ?? whole;
+    });
+}
+/**
+ * Iterate every `<tag …>…</tag>` (and `<tag …/>`) in document order. Nested
+ * elements of the SAME name are not supported (the match is non-greedy); none
+ * of the parts read here nest — rows, cells, runs and paragraphs are all flat.
+ */
+export function* elements(xml, tag) {
+    // The attribute run is LAZY and stops short of the closing `/`. A greedy
+    // `[^>]*` swallows the slash of a self-closing tag, after which the `>` arm
+    // matches and the scan runs on to the NEXT element's closing tag — merging
+    // two siblings into one. That silently shifted every `<xf/>` style index in a
+    // real workbook, so a General-formatted year printed as a 1905 date.
+    const re = new RegExp(`<${tag}((?:\\s[^>]*?)?)(?:\\s*/>|>([\\s\\S]*?)</${tag}>)`, 'g');
+    for (let m = re.exec(xml); m !== null; m = re.exec(xml)) {
+        yield { attrs: m[1], inner: m[2] ?? '' };
+    }
+}
+/** Read one attribute out of an element's raw attribute text. */
+export function attr(attrs, name) {
+    // The leading (^|\s) keeps `s="1"` from matching inside `style="…"`.
+    const m = new RegExp(`(?:^|\\s)${name}\\s*=\\s*("([^"]*)"|'([^']*)')`).exec(attrs);
+    if (!m)
+        return null;
+    return decodeXmlEntities(m[2] ?? m[3]);
+}
+/** Concatenated, entity-decoded text of every `<tag>` element in `xml`. */
+export function textOf(xml, tag) {
+    let out = '';
+    for (const el of elements(xml, tag))
+        out += decodeXmlEntities(el.inner);
+    return out;
+}