@shbernal/ts-xlsx 3.0.0 → 3.1.0

package/dist/vba/project-editor.js

@@ -1,33 +1,34 @@
-import { readU16 } from './bytes.js';
-import { writeCompoundFile } from './cfb-writer.js';
+import { quoted } from '../errors.js';
+import { readU16, spliceBytes, writeU16 } from './bytes.js';
+import { isStream, writeCompoundFile } from './cfb-writer.js';
 import { CompoundFile } from './cfb.js';
 import { decoderForCodePage, encoderForCodePage } from './codepage.js';
 import { dirRecords, REC_MODULE_NAME, REC_MODULE_STREAMNAME, REC_MODULE_TERMINATOR, REC_MODULES_COUNT, REC_REFERENCE_NAME, REC_REFERENCE_NAME_UNICODE, REC_REFERENCE_REGISTERED, } from './dir-records.js';
 import { VbaAuthorError, VbaParseError } from './errors.js';
 import { compressContainer, decompressContainer } from './ms-ovba.js';
-import { parseVbaProject } from './project.js';
+import { parseVbaProjectIn } from './project.js';
 import { push, u16, u32, utf16le, validateVbaName } from './vba-encoding.js';
 const DIR_STREAM = 'dir';
 const PROJECT_STREAM = 'PROJECT';
 const PROJECTWM_STREAM = 'PROJECTwm';
 const VBA_STORAGE = 'VBA';
 export function removeVbaModule(bin, name) {
-    const project = parseVbaProject(bin);
+    const cfb = new CompoundFile(bin);
+    const project = parseVbaProjectIn(cfb);
     const nameKey = name.toUpperCase();
     const module = project.modules.find((m) => m.name.toUpperCase() === nameKey);
     if (!module)
-        throw new VbaAuthorError(`module '${name}' is not in the VBA project`);
+        throw new VbaAuthorError(`module ${quoted(name)} is not in the VBA project`);
     if (module.kind !== 'procedural' && module.kind !== 'class') {
-        throw new VbaAuthorError(`cannot remove module '${name}': its kind '${module.kind}' is tied to host linkage this ` +
+        throw new VbaAuthorError(`cannot remove module ${quoted(name)}: its kind ${quoted(module.kind)} is tied to host linkage this ` +
             'primitive cannot verify');
     }
-    const cfb = new CompoundFile(bin);
+    const decoder = decoderForCodePage(project.codePage);
     const dirCompressed = cfb.readStream(DIR_STREAM);
     if (!dirCompressed)
         throw new VbaParseError("VBA project has no 'dir' stream");
-    const patchedDir = removeModuleDirRecord(decompressContainer(dirCompressed), module.streamName, project.codePage);
+    const patchedDir = removeModuleDirRecord(decompressContainer(dirCompressed), module.streamName, decoder);
     const replacements = new Map([[DIR_STREAM, compressContainer(patchedDir)]]);
-    const decoder = decoderForCodePage(project.codePage);
     const encode = encoderForCodePage(project.codePage);
     const projectText = cfb.readStream(PROJECT_STREAM);
     if (projectText) {
@@ -44,7 +45,7 @@ export function removeVbaModule(bin, name) {
     const removed = new Set();
     const newTree = removeFromStorage(withReplacements, VBA_STORAGE, module.streamName, removed);
     if (!removed.has(VBA_STORAGE)) {
-        throw new VbaParseError(`module stream '${module.streamName}' is not in the '${VBA_STORAGE}' storage`);
+        throw new VbaParseError(`module stream ${quoted(module.streamName)} is not in the ${quoted(VBA_STORAGE)} storage`);
     }
     return writeCompoundFile(newTree);
 }
@@ -56,7 +57,7 @@ function normalizeReference(ref) {
     validateVbaName(ref.name, 'reference');
     const guidMatch = GUID_PATTERN.exec(ref.guid.trim());
     if (!guidMatch)
-        throw new VbaAuthorError(`invalid reference GUID '${ref.guid}'`);
+        throw new VbaAuthorError(`invalid reference GUID ${quoted(ref.guid)}`);
     const guid = `{${guidMatch.slice(1, 6).join('-').toUpperCase()}}`;
     for (const [field, value] of [
         ['majorVersion', ref.majorVersion],
@@ -71,13 +72,13 @@ function normalizeReference(ref) {
         throw new VbaAuthorError(`reference lcid must be an integer in [0, 0xFFFFFFFF], got ${lcid}`);
     }
     if (ref.path.length === 0 || ref.path.includes('\0') || ref.path.includes('#')) {
-        throw new VbaAuthorError(`invalid reference path '${ref.path}' (must be non-empty and contain no NUL or '#')`);
+        throw new VbaAuthorError(`invalid reference path ${quoted(ref.path)} (must be non-empty and contain no NUL or '#')`);
     }
     const displayName = ref.displayName ?? ref.name;
     if (displayName.length === 0 ||
         displayName.length > MAX_DISPLAY_NAME_CHARS ||
         displayName.includes('\0')) {
-        throw new VbaAuthorError(`invalid reference display name '${displayName}'`);
+        throw new VbaAuthorError(`invalid reference display name ${quoted(displayName)}`);
     }
     const libid = `*\\G${guid}#${ref.majorVersion.toString(16).toUpperCase()}.` +
         `${ref.minorVersion.toString(16).toUpperCase()}#${lcid.toString(16).toUpperCase()}` +
@@ -86,9 +87,8 @@ function normalizeReference(ref) {
 }
 export function addVbaReference(bin, ref) {
     const normalized = normalizeReference(ref);
-    const project = parseVbaProject(bin);
-    const encode = encoderForCodePage(project.codePage);
     const cfb = new CompoundFile(bin);
+    const encode = encoderForCodePage(parseVbaProjectIn(cfb).codePage);
     const dirCompressed = cfb.readStream(DIR_STREAM);
     if (!dirCompressed)
         throw new VbaParseError("VBA project has no 'dir' stream");
@@ -125,15 +125,9 @@ function insertReferenceDirRecords(dir, records) {
     }
     if (insertAt < 0)
         throw new VbaParseError('dir stream is missing MODULES_COUNT');
-    const rec = Uint8Array.from(records);
-    const out = new Uint8Array(dir.length + rec.length);
-    out.set(dir.subarray(0, insertAt), 0);
-    out.set(rec, insertAt);
-    out.set(dir.subarray(insertAt), insertAt + rec.length);
-    return out;
+    return spliceBytes(dir, insertAt, insertAt, Uint8Array.from(records));
 }
-function removeModuleDirRecord(dir, streamName, codePage) {
-    const decoder = decoderForCodePage(codePage);
+function removeModuleDirRecord(dir, streamName, decoder) {
     let countAt = -1;
     let blockStart = -1;
     let removeStart = -1;
@@ -143,7 +137,8 @@ function removeModuleDirRecord(dir, streamName, codePage) {
         if (id === REC_MODULES_COUNT) {
             if (size < 2)
                 throw new VbaParseError('PROJECTMODULES MODULES_COUNT record is malformed');
-            countAt = dataStart;
+            if (countAt < 0)
+                countAt = dataStart;
         }
         else if (id === REC_MODULE_NAME) {
             blockStart = recordStart;
@@ -163,14 +158,17 @@ function removeModuleDirRecord(dir, streamName, codePage) {
     if (countAt < 0)
         throw new VbaParseError('dir stream is missing MODULES_COUNT');
     if (removeStart < 0 || removeEnd < 0) {
-        throw new VbaParseError(`module stream '${streamName}' not found in the dir stream`);
-    }
-    const out = new Uint8Array(dir.length - (removeEnd - removeStart));
-    out.set(dir.subarray(0, removeStart), 0);
-    out.set(dir.subarray(removeEnd), removeStart);
-    const newCount = readU16(out, countAt) - 1;
-    out[countAt] = newCount & 0xff;
-    out[countAt + 1] = (newCount >> 8) & 0xff;
+        throw new VbaParseError(`module stream ${quoted(streamName)} not found in the dir stream`);
+    }
+    if (countAt >= removeStart) {
+        throw new VbaParseError('dir stream declares MODULES_COUNT after a module block');
+    }
+    const count = readU16(dir, countAt);
+    if (count === 0) {
+        throw new VbaParseError('dir stream declares zero modules but carries a module block');
+    }
+    const out = spliceBytes(dir, removeStart, removeEnd);
+    writeU16(out, countAt, count - 1);
     return out;
 }
 function removeProjectStreamLines(text, name, kind) {
@@ -218,20 +216,17 @@ function removeProjectwmRecord(wm, existingModuleCount, name, decoder) {
         }
     }
     if (removeStart < 0 || removeEnd < 0) {
-        throw new VbaParseError(`module '${name}' not found in the PROJECTwm stream`);
+        throw new VbaParseError(`module ${quoted(name)} not found in the PROJECTwm stream`);
     }
-    const out = new Uint8Array(wm.length - (removeEnd - removeStart));
-    out.set(wm.subarray(0, removeStart), 0);
-    out.set(wm.subarray(removeEnd), removeStart);
-    return out;
+    return spliceBytes(wm, removeStart, removeEnd);
 }
 function removeFromStorage(nodes, storageName, streamName, removed) {
     return nodes.map((n) => {
-        if ('data' in n)
+        if (isStream(n))
             return n;
         const children = removeFromStorage(n.children, storageName, streamName, removed);
         if (n.name === storageName && !removed.has(storageName)) {
-            const filtered = children.filter((c) => !('data' in c && c.name === streamName));
+            const filtered = children.filter((c) => !(isStream(c) && c.name === streamName));
             if (filtered.length !== children.length)
                 removed.add(storageName);
             return { name: n.name, children: filtered };
@@ -241,7 +236,7 @@ function removeFromStorage(nodes, storageName, streamName, removed) {
 }
 function replaceStreams(nodes, replacements, applied) {
     return nodes.map((node) => {
-        if ('data' in node) {
+        if (isStream(node)) {
             const data = replacements.get(node.name);
             if (data !== undefined) {
                 applied.add(node.name);

package/dist/vba/project.d.ts

@@ -1,3 +1,4 @@
+import { CompoundFile } from './cfb.ts';
 /** How a module participates in the project: the classification the VBA editor shows. */
 export type VbaModuleKind = 'procedural' | 'document' | 'class' | 'designer';
 export interface VbaModule {
@@ -42,4 +43,13 @@ export interface VbaProjectSignature {
  * carries (`.../office/2006/...` vs `.../2014/...` vs `.../2020/...`).
  */
 export declare function vbaProjectSignatureKind(relType: string): VbaProjectSignatureKind | undefined;
-export declare function parseVbaProject(bin: Uint8Array): VbaProject;
+export declare function parseVbaProject(bin: Uint8Array, maxOutput?: number): VbaProject;
+/**
+ * As {@link parseVbaProject}, over a container the caller has already opened.
+ *
+ * Both project editors parse fail-closed first and then need the container itself, and each was
+ * building a second `CompoundFile` over the same bytes: a second walk of the DIFAT, FAT, mini-FAT,
+ * directory and mini-stream, which is roughly double the cost and double the peak allocation of every
+ * edit. Opening it once and handing it in is the whole of the fix.
+ */
+export declare function parseVbaProjectIn(cfb: CompoundFile, maxOutput?: number): VbaProject;

package/dist/vba/project.js

@@ -1,3 +1,4 @@
+import { quoted } from '../errors.js';
 import { readU16, readU32 } from './bytes.js';
 import { CompoundFile } from './cfb.js';
 import { decoderForCodePage } from './codepage.js';
@@ -15,12 +16,18 @@ const SIGNATURE_KIND_BY_REL_SEGMENT = new Map([
 export function vbaProjectSignatureKind(relType) {
     return SIGNATURE_KIND_BY_REL_SEGMENT.get(relType.slice(relType.lastIndexOf('/') + 1));
 }
-export function parseVbaProject(bin) {
-    const cfb = new CompoundFile(bin);
+function isComplete(module) {
+    return module.streamName !== undefined && module.offset !== undefined;
+}
+export function parseVbaProject(bin, maxOutput = DEFAULT_MAX_PROJECT_OUTPUT) {
+    return parseVbaProjectIn(new CompoundFile(bin), maxOutput);
+}
+export function parseVbaProjectIn(cfb, maxOutput = DEFAULT_MAX_PROJECT_OUTPUT) {
+    const budget = new DecompressionBudget(maxOutput);
     const dirCompressed = cfb.readStream('dir');
     if (!dirCompressed)
         throw new VbaParseError("VBA project has no 'dir' stream");
-    const dir = decompressContainer(dirCompressed);
+    const dir = budget.spend(dirCompressed, 0);
     let codePage = 1252;
     const rawModules = [];
     let pending = {};
@@ -47,7 +54,7 @@ export function parseVbaProject(bin) {
                     pending.offset = readU32(dir, dataStart);
                 break;
             case REC_MODULE_TERMINATOR:
-                if (pending.streamName !== undefined && pending.offset !== undefined)
+                if (isComplete(pending))
                     rawModules.push(pending);
                 pending = {};
                 break;
@@ -65,16 +72,28 @@ export function parseVbaProject(bin) {
             name,
             streamName,
             kind,
-            source: readModuleSource(cfb, streamName, m.offset, decoder),
+            source: readModuleSource(cfb, streamName, m.offset, decoder, budget),
         };
     });
     return { codePage, modules };
 }
-function readModuleSource(cfb, streamName, textOffset, decoder) {
+function readModuleSource(cfb, streamName, textOffset, decoder, budget) {
     const stream = cfb.readStream(streamName);
     if (!stream)
-        throw new VbaParseError(`module stream '${streamName}' not found in container`);
-    return decoder.decode(decompressContainer(stream, textOffset));
+        throw new VbaParseError(`module stream ${quoted(streamName)} not found in container`);
+    return decoder.decode(budget.spend(stream, textOffset));
+}
+const DEFAULT_MAX_PROJECT_OUTPUT = 64 * 1024 * 1024;
+class DecompressionBudget {
+    #remaining;
+    constructor(total) {
+        this.#remaining = total;
+    }
+    spend(stream, start) {
+        const out = decompressContainer(stream, start, this.#remaining);
+        this.#remaining -= out.length;
+        return out;
+    }
 }
 const MODULE_KIND_BY_PROJECT_KEYWORD = new Map([
     ['Document', 'document'],

package/dist/vba/vba-encoding.js

@@ -1,9 +1,11 @@
+import { utf16leBytes } from '../bytes.js';
+import { quoted } from '../errors.js';
 import { MAX_NAME_CHARS } from './cfb-format.js';
 import { VbaAuthorError } from './errors.js';
 const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]*$/;
 export function validateVbaName(name, what) {
     if (!IDENTIFIER.test(name) || name.length > MAX_NAME_CHARS) {
-        throw new VbaAuthorError(`invalid ${what} name '${name}' (must be a VBA identifier ≤ 31 chars)`);
+        throw new VbaAuthorError(`invalid ${what} name ${quoted(name)} (must be a VBA identifier ≤ 31 chars)`);
     }
 }
 export function push(out, id, data) {
@@ -16,8 +18,5 @@ export function u32(n) {
     return [n & 0xff, (n >> 8) & 0xff, (n >> 16) & 0xff, (n >> 24) & 0xff];
 }
 export function utf16le(s) {
-    const out = [];
-    for (let i = 0; i < s.length; i++)
-        out.push(...u16(s.charCodeAt(i)));
-    return out;
+    return [...utf16leBytes(s)];
 }

package/dist/xml/xml-attrs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The SpreadsheetML `_xHHHH_` escape, in the only place it may appear: a complete cell-text value.
+ *
+ * The mirror of `escapeSpreadsheetText` in `./xml.ts`, and it sits here rather than beside it for
+ * the same reason `decodeEntities` sits apart from `escapeText`: the write helpers carry an
+ * `AuthoringError` and a whole serialisation vocabulary the reader has no business importing.
+ *
+ * **One left-to-right pass, and that is load-bearing.** `005F` maps to `_` like any other code
+ * point, with no special case, because a single pass already gives the underscore escape its
+ * meaning: in `_x005F_x0041_` the match at 0 yields `_` and scanning resumes at `x0041_`, which has
+ * no leading underscore left to start an escape. So the value reads back as the literal seven
+ * characters `_x0041_` the author wrote. Decoding `_x005F_` in a pass of its own, before or after
+ * the rest, collapses that to `A` and loses the distinction the encoder went to trouble to keep.
+ * Excel agrees: it reads that cell as `_x0041_`.
+ *
+ * The decode is unconditional, not a repair of characters XML cannot carry. Excel reads
+ * `a_x0009_b` as a tab even though a literal tab would have been perfectly legal there, so a
+ * decoder that only handled the illegal range would disagree with Excel on files Excel wrote.
+ */
+export declare function decodeSpreadsheetText(value: string): string;
+/** An OOXML integer attribute at or above `min` (default: unbounded below); `undefined` when the
+ * attribute is absent, blank, fractional, not a number, or below the floor. Integers past
+ * `Number.MAX_SAFE_INTEGER` read as `undefined` too: no index or count is usable out there, and
+ * arithmetic on one silently lies. */
+export declare function numInteger(val: string | undefined, min?: number): number | undefined;
+/** An OOXML decimal attribute at or above `min` (default: unbounded below); `undefined` when the
+ * attribute is absent, blank, not a number, or below the floor. Infinities are not finite numbers
+ * and read as `undefined`. */
+export declare function numFinite(val: string | undefined, min?: number): number | undefined;
+/** Read an operand's text as a number only when it is a canonical decimal literal (optional sign,
+ * digits, optional fraction). A cell reference, defined name, expression, or exotically-spelled
+ * number (`1E5`, hex) keeps its verbatim text, so it is neither coerced to `NaN` and lost nor
+ * re-spelled into a number that would not re-write byte-clean. Callers layer their own type rules
+ * (a data-validation `list`/`custom` operand stays a string regardless of what it looks like). */
+export declare function coerceNumericLiteral(text: string): string | number;
+/** Narrow an enumerated attribute through its guard; `undefined` when absent or not a member. */
+export declare function enumToken<T extends string>(val: string | undefined, isMember: (candidate: string) => candidate is T): T | undefined;

package/dist/xml/xml-attrs.js

@@ -0,0 +1,30 @@
+export function decodeSpreadsheetText(value) {
+    if (!value.includes('_'))
+        return value;
+    return value.replace(/_x([0-9A-Fa-f]{4})_/g, (_match, hex) => String.fromCharCode(Number.parseInt(hex, 16)));
+}
+export function numInteger(val, min = -Number.MAX_SAFE_INTEGER) {
+    const n = parseAttrNumber(val);
+    if (n === undefined || !Number.isSafeInteger(n) || n < min)
+        return undefined;
+    return n;
+}
+export function numFinite(val, min = -Infinity) {
+    const n = parseAttrNumber(val);
+    if (n === undefined || n < min)
+        return undefined;
+    return n;
+}
+function parseAttrNumber(val) {
+    if (val === undefined || val.trim() === '')
+        return undefined;
+    const n = Number(val);
+    return Number.isFinite(n) ? n : undefined;
+}
+export function coerceNumericLiteral(text) {
+    const trimmed = text.trim();
+    return /^-?\d+(?:\.\d+)?$/.test(trimmed) ? Number(trimmed) : text;
+}
+export function enumToken(val, isMember) {
+    return val !== undefined && isMember(val) ? val : undefined;
+}

package/dist/xml/xml-chars.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The characters an XML 1.0 document cannot carry, whatever escape you reach for.
+ *
+ * Three classes: the C0 controls outside the tab/LF/CR the `Char` production allows, the two
+ * noncharacters at the top of the BMP, and unpaired surrogates. The last are not an XML
+ * problem but a UTF-8 one: the encoder substitutes U+FFFD for a lone surrogate, so the
+ * package validates and the value is quietly gone, which is the same loss by a different
+ * route. U+007F and the C1 controls are deliberately absent: XML 1.1 forbids them, OOXML is
+ * 1.0.
+ *
+ * The `u` flag is load-bearing. It makes the pattern match code points, so an astral
+ * character is one unit that no surrogate range can match, and `[\u{D800}-\u{DFFF}]` means
+ * exactly "a surrogate that is not part of a pair" with no lookaround.
+ */
+export declare const XML_UNREPRESENTABLE: RegExp;
+/** The same rule with the `g` flag, for the escapes that rewrite every occurrence. */
+export declare const XML_UNREPRESENTABLE_GLOBAL: RegExp;
+/**
+ * Whether a code point may appear in an XML 1.0 document at all.
+ *
+ * The reader's question, and the reason this module exists. A numeric character reference names a
+ * code point directly, so a file is free to name one the format has no representation for; decoding
+ * it anyway puts a value in the model that the writer is *guaranteed* to refuse, turning a hostile
+ * file into an `AuthoringError` blaming the caller on the next save.
+ *
+ * A code point outside Unicode entirely is not this function's business -- the caller has already
+ * bounded the number before it can name a character -- so an out-of-range argument is refused here
+ * as well rather than throwing out of `String.fromCodePoint`.
+ */
+export declare function isRepresentableCodePoint(codePoint: number): boolean;
+/**
+ * Drop every code point XML 1.0 cannot carry.
+ *
+ * For text the scanner read out of a document, where there is no verbatim form to fall back to: a
+ * *reference* to an unrepresentable character can be left as the `` the file wrote, but a raw
+ * one has no spelling of its own to keep. Such a character makes the document ill-formed by the
+ * `Char` production, so it was never legally in the file; admitting it would put a value in the
+ * model that the writer must then refuse, which reports a corrupt input as the caller's mistake.
+ */
+export declare function stripUnrepresentable(text: string): string;

package/dist/xml/xml-chars.js

@@ -0,0 +1,12 @@
+export const XML_UNREPRESENTABLE = /[\u{0}-\u{8}\u{B}\u{C}\u{E}-\u{1F}\u{FFFE}\u{FFFF}\u{D800}-\u{DFFF}]/u;
+export const XML_UNREPRESENTABLE_GLOBAL = new RegExp(XML_UNREPRESENTABLE.source, 'gu');
+export function isRepresentableCodePoint(codePoint) {
+    if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff)
+        return false;
+    return !XML_UNREPRESENTABLE.test(String.fromCodePoint(codePoint));
+}
+export function stripUnrepresentable(text) {
+    if (!XML_UNREPRESENTABLE.test(text))
+        return text;
+    return text.replace(XML_UNREPRESENTABLE_GLOBAL, '');
+}

package/dist/xml/xml-namespaces.d.ts

@@ -0,0 +1,31 @@
+import { type XmlAttributes } from './xml-scan.ts';
+/**
+ * The prefix-to-namespace bindings in force at the current point of a scan.
+ *
+ * Properly scoped: a declaration binds only within the element that carries it, so the bindings are
+ * pushed and popped with the element stack. In practice OOXML puts them all on the part's root, but
+ * a reader that assumed so would be making the same kind of assumption this class exists to remove.
+ */
+export declare class NamespaceScope {
+    #private;
+    /** Enter an element, taking any `xmlns` declarations it carries. */
+    open(attrs: XmlAttributes): void;
+    /** Leave an element, restoring whatever its declarations shadowed. */
+    close(): void;
+    /**
+     * The namespace URI a qualified *element* name resolves to, or `undefined` when its prefix is
+     * unbound. An unprefixed element takes the default namespace, which is what makes
+     * `<worksheet xmlns="…main">` and `<x:worksheet xmlns:x="…main">` the same document.
+     */
+    elementNamespace(qualified: string): string | undefined;
+    /** Whether a qualified element name is in `uri`. */
+    isElementIn(qualified: string, uri: string): boolean;
+    /**
+     * An attribute's value looked up by namespace and local name rather than by qualified name.
+     *
+     * An *unprefixed* attribute is in no namespace at all, never the default one, which is why this
+     * only ever matches a prefixed spelling. Every namespaced attribute OOXML uses (`r:id`, `r:embed`,
+     * `xml:space`) is written with a prefix for exactly that reason.
+     */
+    attr(attrs: XmlAttributes, uri: string, local: string): string | undefined;
+}

package/dist/xml/xml-namespaces.js

@@ -0,0 +1,50 @@
+import {} from './xml-scan.js';
+const XMLNS = 'xmlns';
+const XMLNS_PREFIX = 'xmlns:';
+export class NamespaceScope {
+    #bindings = new Map();
+    #undo = [];
+    open(attrs) {
+        let undo;
+        for (const name in attrs) {
+            const prefix = name.startsWith(XMLNS_PREFIX)
+                ? name.slice(XMLNS_PREFIX.length)
+                : name === XMLNS
+                    ? ''
+                    : null;
+            if (prefix === null)
+                continue;
+            (undo ??= []).push([prefix, this.#bindings.get(prefix)]);
+            this.#bindings.set(prefix, attrs[name] ?? '');
+        }
+        this.#undo.push(undo);
+    }
+    close() {
+        const undo = this.#undo.pop();
+        if (undo === undefined)
+            return;
+        for (const [prefix, previous] of undo) {
+            if (previous === undefined)
+                this.#bindings.delete(prefix);
+            else
+                this.#bindings.set(prefix, previous);
+        }
+    }
+    elementNamespace(qualified) {
+        const colon = qualified.indexOf(':');
+        return this.#bindings.get(colon === -1 ? '' : qualified.slice(0, colon));
+    }
+    isElementIn(qualified, uri) {
+        return this.elementNamespace(qualified) === uri;
+    }
+    attr(attrs, uri, local) {
+        for (const [prefix, bound] of this.#bindings) {
+            if (prefix === '' || bound !== uri)
+                continue;
+            const value = attrs[`${prefix}:${local}`];
+            if (value !== undefined)
+                return value;
+        }
+        return undefined;
+    }
+}

package/dist/xml/xml-read.d.ts

@@ -1,19 +1,22 @@
+import { NamespaceScope } from './xml-namespaces.ts';
 import { type XmlAttributes, type XmlEvent } from './xml-scan.ts';
 export interface SaxHandlers {
-    /** An element start. `selfClosing` is true for `<x/>`; no matching {@link onClose} fires for it. */
-    onOpen(name: string, attrs: XmlAttributes, selfClosing: boolean): void;
+    /**
+     * An element start. `selfClosing` is true for `<x/>`; no matching {@link onClose} fires for it.
+     *
+     * `scope` carries the namespace bindings in force here, for the handful of readings whose identity
+     * is a namespace rather than a prefix: an `r:id` under whatever prefix the file bound the
+     * relationships namespace to, or telling an extension element from a main-namespace one in a file
+     * that prefixes the main namespace. Most handlers match on {@link localName} and ignore it.
+     */
+    onOpen(name: string, attrs: XmlAttributes, selfClosing: boolean, scope: NamespaceScope): void;
     /** A run of character data (already entity-decoded; CDATA delivered verbatim). Omit to ignore text. */
     onText?(text: string): void;
     /** An element end (`</x>`); the synthetic end of a self-closing element is *not* reported here.
-     * Omit to ignore closes. */
-    onClose?(name: string): void;
+     * Omit to ignore closes. `scope` is the element's own bindings, still in force: it is popped after
+     * this returns, so a close handler resolves the same namespaces its open handler did. */
+    onClose?(name: string, scope: NamespaceScope): void;
 }
-/**
- * One parse event from {@link xmlEvents}. The payloads match {@link SaxHandlers} exactly: `text`
- * is already entity-decoded (or verbatim CDATA), and a `<x/>` yields one `open` with
- * `selfClosing: true` and no matching `close`. The discriminated `kind` lets a *pull* consumer
- * drive the parse: the shape the streaming reader needs, where a push callback cannot `yield`.
-
 /**
  * What {@link elementSubtrees} is to capture: for each container element's local name, the local name
  * of the children to take verbatim inside it (`'dxfs' -> 'dxf'`). Scoping the child to a container is
@@ -49,12 +52,61 @@ export interface SubtreeCapture {
  * verbatim is broken markup handed on as though it were content.
  */
 export declare function elementSubtrees(source: string, selection: SubtreeSelection): SubtreeCapture;
+/**
+ * Where an element sits in the source: the offsets an editor splices at, and the parsed attributes of
+ * its opening tag.
+ *
+ * `contentStart`/`contentEnd` bound the element's children; for an empty element they are equal and
+ * both sit just past the `/>`, so replacing that range turns `<latin/>` into `<latin>…</latin>` and
+ * a caller that means to replace the *element* uses `start`/`end` instead.
+ */
+export interface ElementRange {
+    /** Offset of the element's `<`. */
+    readonly start: number;
+    /** One past the element's final `>`. */
+    readonly end: number;
+    /** One past the opening tag's `>`. */
+    readonly contentStart: number;
+    /** Offset of the closing tag's `<`, or `end` for an empty element. */
+    readonly contentEnd: number;
+    /** The name as written, namespace prefix included. */
+    readonly name: string;
+    readonly attrs: XmlAttributes;
+}
+/**
+ * Locate the first element reachable by a path of local names, as offsets into the source.
+ *
+ * The primitive for *editing* a part rather than reading one: everything outside the returned range
+ * is spliced through byte for byte, so an edit changes what it names and nothing else -- the
+ * whitespace, the comments, the attribute order, the prefix the source chose. That is a guarantee no
+ * re-serialisation can make, and it is why this returns offsets instead of text.
+ *
+ * The alternative it replaces is a `<container>[\s\S]*?</container>` regular expression, which is a
+ * regular expression parsing XML over untrusted input: it terminates on a `</container>` inside a
+ * comment or a CDATA section, it cannot see an element written `<x></x>` where it expected `<x/>`,
+ * and its container name is interpolated into a pattern where an NCName's legal `.` and `-` are
+ * metacharacters. This scan classifies markup with {@link markupAt}, so a comment is skipped rather
+ * than matched, and compares parsed names rather than raw text.
+ *
+ * Each step of `path` matches at any depth below the previous one, and the *first* match wins, which
+ * is the single block these documents declare. An element that never closes throws
+ * {@link XmlParseError}, on the same grounds as the other truncation cases here: an unterminated
+ * range is not a range.
+ */
+export declare function elementRange(source: string, path: readonly string[]): ElementRange | undefined;
 /** An element start surfaced by {@link openElements}: its qualified `name`, the namespace-stripped
  * `local` name the filter matched on, and its already-decoded `attrs`. */
 export interface OpenElement {
     readonly name: string;
     readonly local: string;
     readonly attrs: XmlAttributes;
+    /**
+     * The namespace bindings in force at this element, for the attributes and elements whose identity
+     * is a namespace rather than a prefix (`r:id`, the x14 extension elements). One shared, mutating
+     * instance rather than a snapshot: it is valid while this element is the current one, which is the
+     * whole of a `for..of` body, and copying it per element would cost every scan for the few that ask.
+     */
+    readonly scope: NamespaceScope;
 }
 /**
  * Yield each element start in `source` as an {@link OpenElement}, optionally restricted to the given
@@ -154,6 +206,16 @@ export declare class TextCapture {
     text(chunk: string): void;
     /** The gathered text when `local` closes the captured element, else `undefined`. Unlatches. */
     close(local: string): string | undefined;
+    /**
+     * Abandon any capture in progress, for a caller whose own container has just ended or begun.
+     *
+     * {@link close} unlatches only for the element that opened the capture, which is the right answer
+     * within one element but not across a boundary the caller owns: markup that opens a `<t>` and is
+     * then truncated leaves the capture armed, and the next container's text lands in the abandoned
+     * buffer instead of where that container wanted it. A caller that resets its own per-container
+     * state resets this with it.
+     */
+    reset(): void;
 }
 /**
  * Yield each named element's text as that element closes, as `{local, text}`.