@shbernal/ts-xlsx 2.1.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';
@@ -7,20 +8,26 @@ import { decompressContainer } from './ms-ovba.js';
 export const VBA_PROJECT_REL_TYPE = 'http://schemas.microsoft.com/office/2006/relationships/vbaProject';
 export const VBA_PROJECT_CONTENT_TYPE = 'application/vnd.ms-office.vbaProject';
 export const VBA_PROJECT_PART_PATH = 'xl/vbaProject.bin';
-const SIGNATURE_KIND_BY_REL_SEGMENT = {
-    vbaProjectSignature: 'legacy',
-    vbaProjectSignatureAgile: 'agile',
-    vbaProjectSignatureV3: 'v3',
-};
+const SIGNATURE_KIND_BY_REL_SEGMENT = new Map([
+    ['vbaProjectSignature', 'legacy'],
+    ['vbaProjectSignatureAgile', 'agile'],
+    ['vbaProjectSignatureV3', 'v3'],
+]);
 export function vbaProjectSignatureKind(relType) {
-    return SIGNATURE_KIND_BY_REL_SEGMENT[relType.slice(relType.lastIndexOf('/') + 1)];
+    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,34 +72,46 @@ 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'],
+    ['Module', 'procedural'],
+    ['Class', 'class'],
+    ['BaseClass', 'designer'],
+]);
 function readProjectStreamKinds(cfb, decoder) {
     const kinds = new Map();
     const stream = cfb.readStream('PROJECT');
     if (!stream)
         return kinds;
     const text = decoder.decode(stream);
-    const keyword = {
-        Document: 'document',
-        Module: 'procedural',
-        Class: 'class',
-        BaseClass: 'designer',
-    };
     for (const line of text.split(/\r\n|\r|\n/)) {
         const eq = line.indexOf('=');
         if (eq < 0)
             continue;
-        const kind = keyword[line.slice(0, eq)];
+        const kind = MODULE_KIND_BY_PROJECT_KEYWORD.get(line.slice(0, eq));
         if (kind === undefined)
             continue;
         const name = (line.slice(eq + 1).split('/')[0] ?? '').trim();

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_]*$/;
-const MAX_NAME_CHARS = 31;
 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;
+    }
+}