@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/io/ooxml/xml-scan.js

@@ -1,616 +1,616 @@
-// Forward, single-pass, byte-offset-preserving XML scanner (ADR-0020 Karar 1).
-//
-// WHY THIS FILE EXISTS: §3.5's provenance model needs, for every anchor, the
-// exact BYTE RANGE it occupies in the untouched word/document.xml — not a
-// character index, not a DOM reference. No browser API gives that:
-//   - DOMParser is absent in Node (test/ssr-safety.test.js proves this on
-//     every src/ import), and even where present it returns a tree whose
-//     nodes carry no source offset at all — it does not solve the problem,
-//     it just re-creates option (a)'s flaw (two independent walks that must
-//     stay in lockstep) behind a different parser.
-//   - XMLSerializer's parse->serialize round-trip is not byte-preserving
-//     (entity spelling, attribute quoting, insignificant whitespace) — the
-//     exact thing §3.5 forbids for export.
-// So this scanner produces node AND offset from the SAME event, in one pass
-// — B1's bug class (two lists, indexed together, silently drifting apart)
-// is structurally impossible here, not merely tested against.
-//
-// BYTE OFFSETS, NOT CHARACTER INDICES: this scanner walks bytes.Uint8Array,
-// never decoding to a JS string until a leaf value (text/CDATA/attribute) is
-// fully delimited. UTF-8 was designed so that every ASCII structural byte
-// (<, >, /, =, ", ', &, ;, whitespace, all < 0x80) never appears as part of a
-// multi-byte sequence's lead or continuation byte (those are always >= 0x80)
-// — so scanning for structural bytes is correct UTF-8-wide without decoding
-// a single character. Measured 2026-08-27: multi-byte UTF-8 (Turkish, e.g.
-// "tankları" = 8 chars / 9 bytes, AA01.docx offset 7605) is real in this
-// corpus. A scanner built on string indexOf/length would silently misalign
-// on exactly this content — the bug §3.5 calls "sessizce kayar."
-//
-// SCOPE: this ONE module (per this piece's own instruction) covers scanning
-// AND the reject checks ADR-0020 Karar 1/Karar 4 name for this layer —
-// folding what Karar 8's file table called `xml-reject.js` into this file.
-// No model transformation, no mc:AlternateContent interpretation (item 4:
-// this scanner parses Choice AND Fallback identically and does not choose
-// between them — that is drawingml.js's job, a later piece).
-
-const LT = 0x3c; // <
-const GT = 0x3e; // >
-const SLASH = 0x2f; // /
-const QUESTION = 0x3f; // ?
-const BANG = 0x21; // !
-const EQUALS = 0x3d; // =
-const DQUOTE = 0x22; // "
-const SQUOTE = 0x27; // '
-const AMP = 0x26; // &
-const SEMI = 0x3b; // ;
-const HASH = 0x23; // #
-const COLON = 0x3a; // :
-const DASH = 0x2d; // -
-const DOT = 0x2e; // .
-const UNDERSCORE = 0x5f; // _
-const SPACE = 0x20;
-const TAB = 0x09;
-const CR = 0x0d;
-const LF = 0x0a;
-
-const XML_PREFIX_URI = "http://www.w3.org/XML/1998/namespace"; // xml: is predefined, never declared
-
-const PREDEFINED_ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
-
-const decoder = new TextDecoder("utf-8", { fatal: true });
-
-/**
- * @typedef {object} XmlAttribute
- * @property {string} prefix       raw prefix as written, "" if unprefixed
- * @property {string} localName
- * @property {string} uri          "" for an unprefixed attribute — per the XML
- *   Namespaces spec, an unprefixed attribute is NEVER in the default
- *   namespace, unlike an unprefixed ELEMENT
- * @property {string} value        entity-decoded
- */
-
-/**
- * @typedef {object} XmlElement
- * @property {"element"} kind
- * @property {string} prefix
- * @property {string} localName
- * @property {string} uri          resolved namespace URI
- * @property {number} start        offset of this element's opening '<'
- * @property {number} end          offset one past the closing '>' (own end
- *   tag, or the same self-closing tag's own '>')
- * @property {number} contentStart offset right after the opening tag's '>'
- *   (== end for a self-closing element — no content)
- * @property {number} contentEnd   offset of the '<' starting the closing tag
- *   (== contentStart for a self-closing element)
- * @property {XmlAttribute[]} attributes
- * @property {XmlNode[]} children
- */
-
-/**
- * @typedef {object} XmlText
- * @property {"text"} kind
- * @property {number} start
- * @property {number} end
- * @property {string} value        entity-decoded
- */
-
-/**
- * @typedef {object} XmlCData
- * @property {"cdata"} kind
- * @property {number} start
- * @property {number} end
- * @property {string} value        raw — CDATA content is never entity-decoded
- */
-
-/**
- * @typedef {object} XmlComment
- * @property {"comment"} kind
- * @property {number} start
- * @property {number} end
- */
-
-/** @typedef {XmlElement | XmlText | XmlCData | XmlComment} XmlNode */
-
-/**
- * @param {XmlElement} element
- * @param {string} uri
- * @param {string} localName
- * @returns {string | undefined}
- */
-export function getAttr(element, uri, localName) {
-  for (const a of element.attributes) {
-    if (a.uri === uri && a.localName === localName) return a.value;
-  }
-  return undefined;
-}
-
-/**
- * @param {XmlNode} node
- * @param {string} uri
- * @param {string} localName
- * @returns {boolean}
- */
-export function isElement(node, uri, localName) {
-  return node.kind === "element" && node.uri === uri && node.localName === localName;
-}
-
-/**
- * The FIRST direct child matching (uri, localName) — mirrors
- * ElementTree's `.find()` (direct children only, not descendants).
- * @param {XmlElement} element
- * @param {string} uri
- * @param {string} localName
- * @returns {XmlElement | undefined}
- */
-export function findChild(element, uri, localName) {
-  return /** @type {XmlElement | undefined} */ (
-    element.children.find((c) => isElement(c, uri, localName))
-  );
-}
-
-/**
- * Every direct child matching (uri, localName), in document order — mirrors
- * ElementTree's `.findall()` (direct children only, not descendants).
- * @param {XmlElement} element
- * @param {string} uri
- * @param {string} localName
- * @returns {XmlElement[]}
- */
-export function findChildren(element, uri, localName) {
-  return /** @type {XmlElement[]} */ (element.children.filter((c) => isElement(c, uri, localName)));
-}
-
-/**
- * @param {number} b
- * @returns {boolean}
- */
-function isNameStartByte(b) {
-  return (b >= 0x41 && b <= 0x5a) || (b >= 0x61 && b <= 0x7a) || b === UNDERSCORE;
-}
-/**
- * @param {number} b
- * @returns {boolean}
- */
-function isNameByte(b) {
-  return isNameStartByte(b) || (b >= 0x30 && b <= 0x39) || b === DASH || b === DOT || b === COLON;
-}
-/**
- * @param {number} b
- * @returns {boolean}
- */
-function isWhitespaceByte(b) {
-  return b === SPACE || b === TAB || b === CR || b === LF;
-}
-
-/**
- * @param {Uint8Array} bytes
- * @param {number} offset
- * @param {string} literal  ASCII only
- * @returns {boolean}
- */
-function matchesAscii(bytes, offset, literal) {
-  if (offset + literal.length > bytes.length) return false;
-  for (let i = 0; i < literal.length; i++) {
-    if (bytes[offset + i] !== literal.charCodeAt(i)) return false;
-  }
-  return true;
-}
-
-/**
- * Decodes XML character escapes in an already UTF-8-decoded string. Manual
- * single pass (not replace-then-recheck): a bare, unescaped '&' is a
- * well-formedness violation and must be REJECTED, but a numeric reference
- * that legitimately decodes TO '&' (e.g. `&#38;`) must not be mistaken for
- * one — a replace-then-scan-for-leftover-& approach cannot tell those apart.
- * @param {string} text
- * @param {number} baseOffset  byte offset of the start of `text`, for error messages
- * @returns {string}
- */
-function decodeEntities(text, baseOffset) {
-  if (text.indexOf("&") < 0) return text;
-  let out = "";
-  let i = 0;
-  while (i < text.length) {
-    const ch = text[i];
-    if (ch !== "&") {
-      out += ch;
-      i++;
-      continue;
-    }
-    const semi = text.indexOf(";", i + 1);
-    const body = semi >= 0 ? text.slice(i + 1, semi) : "";
-    if (semi >= 0 && Object.prototype.hasOwnProperty.call(PREDEFINED_ENTITIES, body)) {
-      out += PREDEFINED_ENTITIES[/** @type {keyof typeof PREDEFINED_ENTITIES} */ (body)];
-      i = semi + 1;
-      continue;
-    }
-    if (semi >= 0 && /^#[0-9]+$/.test(body)) {
-      out += String.fromCodePoint(Number.parseInt(body.slice(1), 10));
-      i = semi + 1;
-      continue;
-    }
-    if (semi >= 0 && /^#x[0-9a-fA-F]+$/.test(body)) {
-      out += String.fromCodePoint(Number.parseInt(body.slice(2), 16));
-      i = semi + 1;
-      continue;
-    }
-    throw new Error(
-      `xml-scan: hatalı biçimli XML — kaçışsız veya tanınmayan '&' (yaklaşık bayt ${baseOffset}) — ` +
-        "geçerli kaçışlar: &amp; &lt; &gt; &quot; &apos; ve sayısal (&#NNN; / &#xHHH;)",
-    );
-  }
-  return out;
-}
-
-/**
- * @param {string | null} declaredEncoding  the XML declaration's own encoding attribute, or null if absent
- * @returns {void}
- */
-export function rejectNonUtf8Encoding(declaredEncoding) {
-  if (declaredEncoding === null) return;
-  const normalized = declaredEncoding.toLowerCase();
-  if (normalized !== "utf-8" && normalized !== "utf8") {
-    throw new Error(
-      `xml-scan: UTF-8 dışı kodlama bildirimi (${JSON.stringify(declaredEncoding)}) — reddediliyor, ` +
-        "bu bayt dizisi UTF-8 olarak yorumlanacak ve başka bir kodlama tahmin edilmeyecek",
-    );
-  }
-}
-
-/**
- * @param {Uint8Array} bytes
- * @param {number} offset  where the offending '<!' sequence starts
- * @returns {never}
- */
-export function rejectDoctype(bytes, offset) {
-  throw new Error(
-    `xml-scan: DOCTYPE/ENTITY bildirimi bulundu (bayt ${offset}) — dış varlık (XXE) riski, reddediliyor`,
-  );
-}
-
-/**
- * @param {string} prefix
- * @param {number} offset
- * @returns {never}
- */
-function rejectUnresolvedPrefix(prefix, offset) {
-  throw new Error(`xml-scan: çözülemeyen ad alanı öneki ${JSON.stringify(prefix + ":")} (bayt ${offset})`);
-}
-
-/**
- * Scans a decompressed word/document.xml byte buffer into a single-pass,
- * offset-carrying tree. Pure, synchronous, no platform globals.
- * @param {Uint8Array} bytes
- * @returns {{ root: XmlElement, declaredEncoding: string | null }}
- */
-export function scanXml(bytes) {
-  const len = bytes.length;
-  let pos = 0;
-  /** @type {Map<string, string>[]} */
-  const nsScopes = [new Map([["xml", XML_PREFIX_URI]])];
-  let declaredEncoding = null;
-
-  /**
-   * @param {string} message
-   * @returns {never}
-   */
-  function fail(message) {
-    throw new Error(`xml-scan: hatalı biçimli XML — ${message} (bayt ${pos})`);
-  }
-
-  function skipWs() {
-    while (pos < len && isWhitespaceByte(bytes[pos])) pos++;
-  }
-
-  function readName() {
-    const start = pos;
-    if (pos >= len || !isNameStartByte(bytes[pos])) fail("beklenen isim bulunamadı");
-    pos++;
-    while (pos < len && isNameByte(bytes[pos])) pos++;
-    return decoder.decode(bytes.subarray(start, pos));
-  }
-
-  /**
-   * @param {string} qname
-   * @returns {{prefix: string, localName: string}}
-   */
-  function splitQName(qname) {
-    const idx = qname.indexOf(":");
-    return idx < 0 ? { prefix: "", localName: qname } : { prefix: qname.slice(0, idx), localName: qname.slice(idx + 1) };
-  }
-
-  /**
-   * @param {string} prefix
-   * @returns {string}
-   */
-  function resolveElementUri(prefix) {
-    if (prefix === "") {
-      for (let i = nsScopes.length - 1; i >= 0; i--) {
-        const v = nsScopes[i].get("");
-        if (v !== undefined) return v;
-      }
-      return ""; // no default namespace declared — legal, means "no namespace"
-    }
-    for (let i = nsScopes.length - 1; i >= 0; i--) {
-      const v = nsScopes[i].get(prefix);
-      if (v !== undefined) return v;
-    }
-    return rejectUnresolvedPrefix(prefix, pos);
-  }
-
-  /**
-   * @param {string} prefix
-   * @returns {string}
-   */
-  function resolveAttrUri(prefix) {
-    if (prefix === "") return ""; // unprefixed attribute: NEVER in a default namespace
-    for (let i = nsScopes.length - 1; i >= 0; i--) {
-      const v = nsScopes[i].get(prefix);
-      if (v !== undefined) return v;
-    }
-    return rejectUnresolvedPrefix(prefix, pos);
-  }
-
-  function skipComment() {
-    const start = pos;
-    pos += 4; // "<!--"
-    const end = indexOfAscii(bytes, "-->", pos);
-    if (end < 0) fail("yorum kapanmıyor (-->)");
-    pos = end + 3;
-    /** @type {XmlComment} */
-    const node = { kind: "comment", start, end: pos };
-    return node;
-  }
-
-  function readCData() {
-    const start = pos;
-    pos += 9; // "<![CDATA["
-    const end = indexOfAscii(bytes, "]]>", pos);
-    if (end < 0) fail("CDATA kapanmıyor (]]>)");
-    const value = decoder.decode(bytes.subarray(pos, end));
-    pos = end + 3;
-    /** @type {XmlCData} */
-    const node = { kind: "cdata", start, end: pos, value };
-    return node;
-  }
-
-  function skipProcessingInstruction() {
-    pos += 2; // "<?"
-    const end = indexOfAscii(bytes, "?>", pos);
-    if (end < 0) fail("işleme talimatı kapanmıyor (?>)");
-    pos = end + 2;
-  }
-
-  function readAttributeValue() {
-    const quote = bytes[pos];
-    if (quote !== DQUOTE && quote !== SQUOTE) fail("öznitelik değeri tırnaksız");
-    pos++;
-    const start = pos;
-    while (pos < len && bytes[pos] !== quote) {
-      if (bytes[pos] === LT) fail("öznitelik değeri içinde kaçışsız '<'");
-      pos++;
-    }
-    if (pos >= len) fail("öznitelik değeri kapanmıyor");
-    const raw = decoder.decode(bytes.subarray(start, pos));
-    pos++; // closing quote
-    return decodeEntities(raw, start);
-  }
-
-  function readTagAttributes() {
-    /** @type {{qname: string, value: string, offset: number}[]} */
-    const raw = [];
-    for (;;) {
-      const before = pos;
-      skipWs();
-      if (pos >= len) fail("etiket kapanmıyor");
-      if (bytes[pos] === SLASH || bytes[pos] === GT) break;
-      if (pos === before) fail("öznitelikler arasında boşluk bekleniyor");
-      const attrOffset = pos;
-      const qname = readName();
-      skipWs();
-      if (bytes[pos] !== EQUALS) fail("öznitelikte '=' bekleniyor");
-      pos++;
-      skipWs();
-      const value = readAttributeValue();
-      raw.push({ qname, value, offset: attrOffset });
-    }
-    return raw;
-  }
-
-  function parseElement() {
-    const start = pos;
-    pos++; // '<'
-    const qname = readName();
-    const { prefix, localName } = splitQName(qname);
-    const rawAttrs = readTagAttributes();
-
-    // New namespace scope: collect this element's own xmlns declarations
-    // before resolving ANYTHING (including the element's own prefix) — a
-    // tag may declare the very namespace its own prefix uses.
-    /** @type {Map<string, string>} */
-    const scope = new Map();
-    for (const { qname: aqname, value } of rawAttrs) {
-      if (aqname === "xmlns") scope.set("", value);
-      else if (aqname.startsWith("xmlns:")) scope.set(aqname.slice(6), value);
-    }
-    nsScopes.push(scope);
-
-    const uri = resolveElementUri(prefix);
-    /** @type {XmlAttribute[]} */
-    const attributes = [];
-    for (const { qname: aqname, value, offset } of rawAttrs) {
-      if (aqname === "xmlns" || aqname.startsWith("xmlns:")) continue; // declarations aren't data attributes
-      const split = splitQName(aqname);
-      const savedPos = pos;
-      pos = offset;
-      const attrUri = resolveAttrUri(split.prefix);
-      pos = savedPos;
-      attributes.push({ prefix: split.prefix, localName: split.localName, uri: attrUri, value });
-    }
-
-    skipWs();
-    const selfClosing = bytes[pos] === SLASH;
-    if (selfClosing) pos++;
-    if (bytes[pos] !== GT) fail("etiket '>' ile kapanmıyor");
-    pos++;
-
-    /** @type {XmlElement} */
-    const element = {
-      kind: "element",
-      prefix,
-      localName,
-      uri,
-      start,
-      end: pos,
-      contentStart: pos,
-      contentEnd: pos,
-      attributes,
-      children: [],
-    };
-
-    if (!selfClosing) {
-      element.children = parseContent(qname);
-      element.contentEnd = pos; // set by parseContent just before the closing tag
-      pos = skipClosingTag(qname);
-      element.end = pos;
-    }
-
-    nsScopes.pop();
-    return element;
-  }
-
-  /**
-   * @param {string} expectedQName
-   * @returns {number}
-   */
-  function skipClosingTag(expectedQName) {
-    const closeStart = pos;
-    pos += 2; // "</"
-    const qname = readName();
-    if (qname !== expectedQName) {
-      fail(`kapanış etiketi <${expectedQName}> ile eşleşmiyor, bulundu </${qname}> (bayt ${closeStart})`);
-    }
-    skipWs();
-    if (bytes[pos] !== GT) fail("kapanış etiketi '>' ile bitmiyor");
-    pos++;
-    return pos;
-  }
-
-  function readText() {
-    const start = pos;
-    while (pos < len && bytes[pos] !== LT) pos++;
-    const raw = decoder.decode(bytes.subarray(start, pos));
-    const value = decodeEntities(raw, start);
-    /** @type {XmlText} */
-    const node = { kind: "text", start, end: pos, value };
-    return node;
-  }
-
-  /**
-   * @param {string} parentQName
-   * @returns {XmlNode[]}
-   */
-  function parseContent(parentQName) {
-    /** @type {XmlNode[]} */
-    const children = [];
-    for (;;) {
-      if (pos >= len) fail(`<${parentQName}> hiç kapanmadan girdi bitti`);
-      if (bytes[pos] !== LT) {
-        children.push(readText());
-        continue;
-      }
-      if (bytes[pos + 1] === SLASH) {
-        break; // closing tag for the current element — let the caller consume it
-      }
-      if (bytes[pos + 1] === BANG) {
-        if (matchesAscii(bytes, pos, "<!--")) {
-          children.push(skipComment());
-          continue;
-        }
-        if (matchesAscii(bytes, pos, "<![CDATA[")) {
-          children.push(readCData());
-          continue;
-        }
-        if (matchesAscii(bytes, pos, "<!DOCTYPE")) rejectDoctype(bytes, pos);
-        fail("bilinmeyen '<!' yapısı");
-      }
-      if (bytes[pos + 1] === QUESTION) {
-        skipProcessingInstruction();
-        continue;
-      }
-      children.push(parseElement());
-    }
-    return children;
-  }
-
-  // ---- XML declaration (optional, must be first if present) ----
-  if (matchesAscii(bytes, 0, "<?xml") && isWhitespaceByte(bytes[5])) {
-    const declEnd = indexOfAscii(bytes, "?>", 5);
-    if (declEnd < 0) fail("XML bildirimi kapanmıyor (?>)");
-    const declText = decoder.decode(bytes.subarray(5, declEnd));
-    const encMatch = /encoding\s*=\s*["']([^"']+)["']/.exec(declText);
-    if (encMatch) declaredEncoding = encMatch[1];
-    pos = declEnd + 2;
-  }
-  rejectNonUtf8Encoding(declaredEncoding);
-
-  // ---- misc before the root element ----
-  /** @type {XmlElement | null} */
-  let root = null;
-  while (pos < len) {
-    skipWs();
-    if (pos >= len) break;
-    if (bytes[pos] !== LT) fail("kök elementten önce beklenmeyen içerik");
-    if (bytes[pos + 1] === BANG) {
-      if (matchesAscii(bytes, pos, "<!--")) {
-        skipComment();
-        continue;
-      }
-      if (matchesAscii(bytes, pos, "<!DOCTYPE")) rejectDoctype(bytes, pos);
-      fail("bilinmeyen '<!' yapısı");
-    }
-    if (bytes[pos + 1] === QUESTION) {
-      skipProcessingInstruction();
-      continue;
-    }
-    root = parseElement();
-    break;
-  }
-  if (root === null) fail("kök element bulunamadı");
-
-  // ---- misc after the root element (comments/PIs/whitespace only) ----
-  while (pos < len) {
-    skipWs();
-    if (pos >= len) break;
-    if (bytes[pos] !== LT) fail("kök elementten sonra beklenmeyen içerik");
-    if (matchesAscii(bytes, pos, "<!--")) {
-      skipComment();
-      continue;
-    }
-    if (bytes[pos + 1] === QUESTION) {
-      skipProcessingInstruction();
-      continue;
-    }
-    fail("kök elementten sonra ikinci bir element");
-  }
-
-  return { root, declaredEncoding };
-}
-
-/**
- * @param {Uint8Array} bytes
- * @param {string} literal  ASCII only
- * @param {number} from
- * @returns {number}
- */
-function indexOfAscii(bytes, literal, from) {
-  const first = literal.charCodeAt(0);
-  outer: for (let i = from; i <= bytes.length - literal.length; i++) {
-    if (bytes[i] !== first) continue;
-    for (let j = 1; j < literal.length; j++) {
-      if (bytes[i + j] !== literal.charCodeAt(j)) continue outer;
-    }
-    return i;
-  }
-  return -1;
-}
+// Forward, single-pass, byte-offset-preserving XML scanner (ADR-0020 Karar 1).
+//
+// WHY THIS FILE EXISTS: §3.5's provenance model needs, for every anchor, the
+// exact BYTE RANGE it occupies in the untouched word/document.xml — not a
+// character index, not a DOM reference. No browser API gives that:
+//   - DOMParser is absent in Node (test/ssr-safety.test.js proves this on
+//     every src/ import), and even where present it returns a tree whose
+//     nodes carry no source offset at all — it does not solve the problem,
+//     it just re-creates option (a)'s flaw (two independent walks that must
+//     stay in lockstep) behind a different parser.
+//   - XMLSerializer's parse->serialize round-trip is not byte-preserving
+//     (entity spelling, attribute quoting, insignificant whitespace) — the
+//     exact thing §3.5 forbids for export.
+// So this scanner produces node AND offset from the SAME event, in one pass
+// — B1's bug class (two lists, indexed together, silently drifting apart)
+// is structurally impossible here, not merely tested against.
+//
+// BYTE OFFSETS, NOT CHARACTER INDICES: this scanner walks bytes.Uint8Array,
+// never decoding to a JS string until a leaf value (text/CDATA/attribute) is
+// fully delimited. UTF-8 was designed so that every ASCII structural byte
+// (<, >, /, =, ", ', &, ;, whitespace, all < 0x80) never appears as part of a
+// multi-byte sequence's lead or continuation byte (those are always >= 0x80)
+// — so scanning for structural bytes is correct UTF-8-wide without decoding
+// a single character. Measured 2026-08-27: multi-byte UTF-8 (Turkish, e.g.
+// "tankları" = 8 chars / 9 bytes, AA01.docx offset 7605) is real in this
+// corpus. A scanner built on string indexOf/length would silently misalign
+// on exactly this content — the bug §3.5 calls "sessizce kayar."
+//
+// SCOPE: this ONE module (per this piece's own instruction) covers scanning
+// AND the reject checks ADR-0020 Karar 1/Karar 4 name for this layer —
+// folding what Karar 8's file table called `xml-reject.js` into this file.
+// No model transformation, no mc:AlternateContent interpretation (item 4:
+// this scanner parses Choice AND Fallback identically and does not choose
+// between them — that is drawingml.js's job, a later piece).
+
+const LT = 0x3c; // <
+const GT = 0x3e; // >
+const SLASH = 0x2f; // /
+const QUESTION = 0x3f; // ?
+const BANG = 0x21; // !
+const EQUALS = 0x3d; // =
+const DQUOTE = 0x22; // "
+const SQUOTE = 0x27; // '
+const AMP = 0x26; // &
+const SEMI = 0x3b; // ;
+const HASH = 0x23; // #
+const COLON = 0x3a; // :
+const DASH = 0x2d; // -
+const DOT = 0x2e; // .
+const UNDERSCORE = 0x5f; // _
+const SPACE = 0x20;
+const TAB = 0x09;
+const CR = 0x0d;
+const LF = 0x0a;
+
+const XML_PREFIX_URI = "http://www.w3.org/XML/1998/namespace"; // xml: is predefined, never declared
+
+const PREDEFINED_ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+/**
+ * @typedef {object} XmlAttribute
+ * @property {string} prefix       raw prefix as written, "" if unprefixed
+ * @property {string} localName
+ * @property {string} uri          "" for an unprefixed attribute — per the XML
+ *   Namespaces spec, an unprefixed attribute is NEVER in the default
+ *   namespace, unlike an unprefixed ELEMENT
+ * @property {string} value        entity-decoded
+ */
+
+/**
+ * @typedef {object} XmlElement
+ * @property {"element"} kind
+ * @property {string} prefix
+ * @property {string} localName
+ * @property {string} uri          resolved namespace URI
+ * @property {number} start        offset of this element's opening '<'
+ * @property {number} end          offset one past the closing '>' (own end
+ *   tag, or the same self-closing tag's own '>')
+ * @property {number} contentStart offset right after the opening tag's '>'
+ *   (== end for a self-closing element — no content)
+ * @property {number} contentEnd   offset of the '<' starting the closing tag
+ *   (== contentStart for a self-closing element)
+ * @property {XmlAttribute[]} attributes
+ * @property {XmlNode[]} children
+ */
+
+/**
+ * @typedef {object} XmlText
+ * @property {"text"} kind
+ * @property {number} start
+ * @property {number} end
+ * @property {string} value        entity-decoded
+ */
+
+/**
+ * @typedef {object} XmlCData
+ * @property {"cdata"} kind
+ * @property {number} start
+ * @property {number} end
+ * @property {string} value        raw — CDATA content is never entity-decoded
+ */
+
+/**
+ * @typedef {object} XmlComment
+ * @property {"comment"} kind
+ * @property {number} start
+ * @property {number} end
+ */
+
+/** @typedef {XmlElement | XmlText | XmlCData | XmlComment} XmlNode */
+
+/**
+ * @param {XmlElement} element
+ * @param {string} uri
+ * @param {string} localName
+ * @returns {string | undefined}
+ */
+export function getAttr(element, uri, localName) {
+  for (const a of element.attributes) {
+    if (a.uri === uri && a.localName === localName) return a.value;
+  }
+  return undefined;
+}
+
+/**
+ * @param {XmlNode} node
+ * @param {string} uri
+ * @param {string} localName
+ * @returns {boolean}
+ */
+export function isElement(node, uri, localName) {
+  return node.kind === "element" && node.uri === uri && node.localName === localName;
+}
+
+/**
+ * The FIRST direct child matching (uri, localName) — mirrors
+ * ElementTree's `.find()` (direct children only, not descendants).
+ * @param {XmlElement} element
+ * @param {string} uri
+ * @param {string} localName
+ * @returns {XmlElement | undefined}
+ */
+export function findChild(element, uri, localName) {
+  return /** @type {XmlElement | undefined} */ (
+    element.children.find((c) => isElement(c, uri, localName))
+  );
+}
+
+/**
+ * Every direct child matching (uri, localName), in document order — mirrors
+ * ElementTree's `.findall()` (direct children only, not descendants).
+ * @param {XmlElement} element
+ * @param {string} uri
+ * @param {string} localName
+ * @returns {XmlElement[]}
+ */
+export function findChildren(element, uri, localName) {
+  return /** @type {XmlElement[]} */ (element.children.filter((c) => isElement(c, uri, localName)));
+}
+
+/**
+ * @param {number} b
+ * @returns {boolean}
+ */
+function isNameStartByte(b) {
+  return (b >= 0x41 && b <= 0x5a) || (b >= 0x61 && b <= 0x7a) || b === UNDERSCORE;
+}
+/**
+ * @param {number} b
+ * @returns {boolean}
+ */
+function isNameByte(b) {
+  return isNameStartByte(b) || (b >= 0x30 && b <= 0x39) || b === DASH || b === DOT || b === COLON;
+}
+/**
+ * @param {number} b
+ * @returns {boolean}
+ */
+function isWhitespaceByte(b) {
+  return b === SPACE || b === TAB || b === CR || b === LF;
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @param {number} offset
+ * @param {string} literal  ASCII only
+ * @returns {boolean}
+ */
+function matchesAscii(bytes, offset, literal) {
+  if (offset + literal.length > bytes.length) return false;
+  for (let i = 0; i < literal.length; i++) {
+    if (bytes[offset + i] !== literal.charCodeAt(i)) return false;
+  }
+  return true;
+}
+
+/**
+ * Decodes XML character escapes in an already UTF-8-decoded string. Manual
+ * single pass (not replace-then-recheck): a bare, unescaped '&' is a
+ * well-formedness violation and must be REJECTED, but a numeric reference
+ * that legitimately decodes TO '&' (e.g. `&#38;`) must not be mistaken for
+ * one — a replace-then-scan-for-leftover-& approach cannot tell those apart.
+ * @param {string} text
+ * @param {number} baseOffset  byte offset of the start of `text`, for error messages
+ * @returns {string}
+ */
+function decodeEntities(text, baseOffset) {
+  if (text.indexOf("&") < 0) return text;
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch !== "&") {
+      out += ch;
+      i++;
+      continue;
+    }
+    const semi = text.indexOf(";", i + 1);
+    const body = semi >= 0 ? text.slice(i + 1, semi) : "";
+    if (semi >= 0 && Object.prototype.hasOwnProperty.call(PREDEFINED_ENTITIES, body)) {
+      out += PREDEFINED_ENTITIES[/** @type {keyof typeof PREDEFINED_ENTITIES} */ (body)];
+      i = semi + 1;
+      continue;
+    }
+    if (semi >= 0 && /^#[0-9]+$/.test(body)) {
+      out += String.fromCodePoint(Number.parseInt(body.slice(1), 10));
+      i = semi + 1;
+      continue;
+    }
+    if (semi >= 0 && /^#x[0-9a-fA-F]+$/.test(body)) {
+      out += String.fromCodePoint(Number.parseInt(body.slice(2), 16));
+      i = semi + 1;
+      continue;
+    }
+    throw new Error(
+      `xml-scan: hatalı biçimli XML — kaçışsız veya tanınmayan '&' (yaklaşık bayt ${baseOffset}) — ` +
+        "geçerli kaçışlar: &amp; &lt; &gt; &quot; &apos; ve sayısal (&#NNN; / &#xHHH;)",
+    );
+  }
+  return out;
+}
+
+/**
+ * @param {string | null} declaredEncoding  the XML declaration's own encoding attribute, or null if absent
+ * @returns {void}
+ */
+export function rejectNonUtf8Encoding(declaredEncoding) {
+  if (declaredEncoding === null) return;
+  const normalized = declaredEncoding.toLowerCase();
+  if (normalized !== "utf-8" && normalized !== "utf8") {
+    throw new Error(
+      `xml-scan: UTF-8 dışı kodlama bildirimi (${JSON.stringify(declaredEncoding)}) — reddediliyor, ` +
+        "bu bayt dizisi UTF-8 olarak yorumlanacak ve başka bir kodlama tahmin edilmeyecek",
+    );
+  }
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @param {number} offset  where the offending '<!' sequence starts
+ * @returns {never}
+ */
+export function rejectDoctype(bytes, offset) {
+  throw new Error(
+    `xml-scan: DOCTYPE/ENTITY bildirimi bulundu (bayt ${offset}) — dış varlık (XXE) riski, reddediliyor`,
+  );
+}
+
+/**
+ * @param {string} prefix
+ * @param {number} offset
+ * @returns {never}
+ */
+function rejectUnresolvedPrefix(prefix, offset) {
+  throw new Error(`xml-scan: çözülemeyen ad alanı öneki ${JSON.stringify(prefix + ":")} (bayt ${offset})`);
+}
+
+/**
+ * Scans a decompressed word/document.xml byte buffer into a single-pass,
+ * offset-carrying tree. Pure, synchronous, no platform globals.
+ * @param {Uint8Array} bytes
+ * @returns {{ root: XmlElement, declaredEncoding: string | null }}
+ */
+export function scanXml(bytes) {
+  const len = bytes.length;
+  let pos = 0;
+  /** @type {Map<string, string>[]} */
+  const nsScopes = [new Map([["xml", XML_PREFIX_URI]])];
+  let declaredEncoding = null;
+
+  /**
+   * @param {string} message
+   * @returns {never}
+   */
+  function fail(message) {
+    throw new Error(`xml-scan: hatalı biçimli XML — ${message} (bayt ${pos})`);
+  }
+
+  function skipWs() {
+    while (pos < len && isWhitespaceByte(bytes[pos])) pos++;
+  }
+
+  function readName() {
+    const start = pos;
+    if (pos >= len || !isNameStartByte(bytes[pos])) fail("beklenen isim bulunamadı");
+    pos++;
+    while (pos < len && isNameByte(bytes[pos])) pos++;
+    return decoder.decode(bytes.subarray(start, pos));
+  }
+
+  /**
+   * @param {string} qname
+   * @returns {{prefix: string, localName: string}}
+   */
+  function splitQName(qname) {
+    const idx = qname.indexOf(":");
+    return idx < 0 ? { prefix: "", localName: qname } : { prefix: qname.slice(0, idx), localName: qname.slice(idx + 1) };
+  }
+
+  /**
+   * @param {string} prefix
+   * @returns {string}
+   */
+  function resolveElementUri(prefix) {
+    if (prefix === "") {
+      for (let i = nsScopes.length - 1; i >= 0; i--) {
+        const v = nsScopes[i].get("");
+        if (v !== undefined) return v;
+      }
+      return ""; // no default namespace declared — legal, means "no namespace"
+    }
+    for (let i = nsScopes.length - 1; i >= 0; i--) {
+      const v = nsScopes[i].get(prefix);
+      if (v !== undefined) return v;
+    }
+    return rejectUnresolvedPrefix(prefix, pos);
+  }
+
+  /**
+   * @param {string} prefix
+   * @returns {string}
+   */
+  function resolveAttrUri(prefix) {
+    if (prefix === "") return ""; // unprefixed attribute: NEVER in a default namespace
+    for (let i = nsScopes.length - 1; i >= 0; i--) {
+      const v = nsScopes[i].get(prefix);
+      if (v !== undefined) return v;
+    }
+    return rejectUnresolvedPrefix(prefix, pos);
+  }
+
+  function skipComment() {
+    const start = pos;
+    pos += 4; // "<!--"
+    const end = indexOfAscii(bytes, "-->", pos);
+    if (end < 0) fail("yorum kapanmıyor (-->)");
+    pos = end + 3;
+    /** @type {XmlComment} */
+    const node = { kind: "comment", start, end: pos };
+    return node;
+  }
+
+  function readCData() {
+    const start = pos;
+    pos += 9; // "<![CDATA["
+    const end = indexOfAscii(bytes, "]]>", pos);
+    if (end < 0) fail("CDATA kapanmıyor (]]>)");
+    const value = decoder.decode(bytes.subarray(pos, end));
+    pos = end + 3;
+    /** @type {XmlCData} */
+    const node = { kind: "cdata", start, end: pos, value };
+    return node;
+  }
+
+  function skipProcessingInstruction() {
+    pos += 2; // "<?"
+    const end = indexOfAscii(bytes, "?>", pos);
+    if (end < 0) fail("işleme talimatı kapanmıyor (?>)");
+    pos = end + 2;
+  }
+
+  function readAttributeValue() {
+    const quote = bytes[pos];
+    if (quote !== DQUOTE && quote !== SQUOTE) fail("öznitelik değeri tırnaksız");
+    pos++;
+    const start = pos;
+    while (pos < len && bytes[pos] !== quote) {
+      if (bytes[pos] === LT) fail("öznitelik değeri içinde kaçışsız '<'");
+      pos++;
+    }
+    if (pos >= len) fail("öznitelik değeri kapanmıyor");
+    const raw = decoder.decode(bytes.subarray(start, pos));
+    pos++; // closing quote
+    return decodeEntities(raw, start);
+  }
+
+  function readTagAttributes() {
+    /** @type {{qname: string, value: string, offset: number}[]} */
+    const raw = [];
+    for (;;) {
+      const before = pos;
+      skipWs();
+      if (pos >= len) fail("etiket kapanmıyor");
+      if (bytes[pos] === SLASH || bytes[pos] === GT) break;
+      if (pos === before) fail("öznitelikler arasında boşluk bekleniyor");
+      const attrOffset = pos;
+      const qname = readName();
+      skipWs();
+      if (bytes[pos] !== EQUALS) fail("öznitelikte '=' bekleniyor");
+      pos++;
+      skipWs();
+      const value = readAttributeValue();
+      raw.push({ qname, value, offset: attrOffset });
+    }
+    return raw;
+  }
+
+  function parseElement() {
+    const start = pos;
+    pos++; // '<'
+    const qname = readName();
+    const { prefix, localName } = splitQName(qname);
+    const rawAttrs = readTagAttributes();
+
+    // New namespace scope: collect this element's own xmlns declarations
+    // before resolving ANYTHING (including the element's own prefix) — a
+    // tag may declare the very namespace its own prefix uses.
+    /** @type {Map<string, string>} */
+    const scope = new Map();
+    for (const { qname: aqname, value } of rawAttrs) {
+      if (aqname === "xmlns") scope.set("", value);
+      else if (aqname.startsWith("xmlns:")) scope.set(aqname.slice(6), value);
+    }
+    nsScopes.push(scope);
+
+    const uri = resolveElementUri(prefix);
+    /** @type {XmlAttribute[]} */
+    const attributes = [];
+    for (const { qname: aqname, value, offset } of rawAttrs) {
+      if (aqname === "xmlns" || aqname.startsWith("xmlns:")) continue; // declarations aren't data attributes
+      const split = splitQName(aqname);
+      const savedPos = pos;
+      pos = offset;
+      const attrUri = resolveAttrUri(split.prefix);
+      pos = savedPos;
+      attributes.push({ prefix: split.prefix, localName: split.localName, uri: attrUri, value });
+    }
+
+    skipWs();
+    const selfClosing = bytes[pos] === SLASH;
+    if (selfClosing) pos++;
+    if (bytes[pos] !== GT) fail("etiket '>' ile kapanmıyor");
+    pos++;
+
+    /** @type {XmlElement} */
+    const element = {
+      kind: "element",
+      prefix,
+      localName,
+      uri,
+      start,
+      end: pos,
+      contentStart: pos,
+      contentEnd: pos,
+      attributes,
+      children: [],
+    };
+
+    if (!selfClosing) {
+      element.children = parseContent(qname);
+      element.contentEnd = pos; // set by parseContent just before the closing tag
+      pos = skipClosingTag(qname);
+      element.end = pos;
+    }
+
+    nsScopes.pop();
+    return element;
+  }
+
+  /**
+   * @param {string} expectedQName
+   * @returns {number}
+   */
+  function skipClosingTag(expectedQName) {
+    const closeStart = pos;
+    pos += 2; // "</"
+    const qname = readName();
+    if (qname !== expectedQName) {
+      fail(`kapanış etiketi <${expectedQName}> ile eşleşmiyor, bulundu </${qname}> (bayt ${closeStart})`);
+    }
+    skipWs();
+    if (bytes[pos] !== GT) fail("kapanış etiketi '>' ile bitmiyor");
+    pos++;
+    return pos;
+  }
+
+  function readText() {
+    const start = pos;
+    while (pos < len && bytes[pos] !== LT) pos++;
+    const raw = decoder.decode(bytes.subarray(start, pos));
+    const value = decodeEntities(raw, start);
+    /** @type {XmlText} */
+    const node = { kind: "text", start, end: pos, value };
+    return node;
+  }
+
+  /**
+   * @param {string} parentQName
+   * @returns {XmlNode[]}
+   */
+  function parseContent(parentQName) {
+    /** @type {XmlNode[]} */
+    const children = [];
+    for (;;) {
+      if (pos >= len) fail(`<${parentQName}> hiç kapanmadan girdi bitti`);
+      if (bytes[pos] !== LT) {
+        children.push(readText());
+        continue;
+      }
+      if (bytes[pos + 1] === SLASH) {
+        break; // closing tag for the current element — let the caller consume it
+      }
+      if (bytes[pos + 1] === BANG) {
+        if (matchesAscii(bytes, pos, "<!--")) {
+          children.push(skipComment());
+          continue;
+        }
+        if (matchesAscii(bytes, pos, "<![CDATA[")) {
+          children.push(readCData());
+          continue;
+        }
+        if (matchesAscii(bytes, pos, "<!DOCTYPE")) rejectDoctype(bytes, pos);
+        fail("bilinmeyen '<!' yapısı");
+      }
+      if (bytes[pos + 1] === QUESTION) {
+        skipProcessingInstruction();
+        continue;
+      }
+      children.push(parseElement());
+    }
+    return children;
+  }
+
+  // ---- XML declaration (optional, must be first if present) ----
+  if (matchesAscii(bytes, 0, "<?xml") && isWhitespaceByte(bytes[5])) {
+    const declEnd = indexOfAscii(bytes, "?>", 5);
+    if (declEnd < 0) fail("XML bildirimi kapanmıyor (?>)");
+    const declText = decoder.decode(bytes.subarray(5, declEnd));
+    const encMatch = /encoding\s*=\s*["']([^"']+)["']/.exec(declText);
+    if (encMatch) declaredEncoding = encMatch[1];
+    pos = declEnd + 2;
+  }
+  rejectNonUtf8Encoding(declaredEncoding);
+
+  // ---- misc before the root element ----
+  /** @type {XmlElement | null} */
+  let root = null;
+  while (pos < len) {
+    skipWs();
+    if (pos >= len) break;
+    if (bytes[pos] !== LT) fail("kök elementten önce beklenmeyen içerik");
+    if (bytes[pos + 1] === BANG) {
+      if (matchesAscii(bytes, pos, "<!--")) {
+        skipComment();
+        continue;
+      }
+      if (matchesAscii(bytes, pos, "<!DOCTYPE")) rejectDoctype(bytes, pos);
+      fail("bilinmeyen '<!' yapısı");
+    }
+    if (bytes[pos + 1] === QUESTION) {
+      skipProcessingInstruction();
+      continue;
+    }
+    root = parseElement();
+    break;
+  }
+  if (root === null) fail("kök element bulunamadı");
+
+  // ---- misc after the root element (comments/PIs/whitespace only) ----
+  while (pos < len) {
+    skipWs();
+    if (pos >= len) break;
+    if (bytes[pos] !== LT) fail("kök elementten sonra beklenmeyen içerik");
+    if (matchesAscii(bytes, pos, "<!--")) {
+      skipComment();
+      continue;
+    }
+    if (bytes[pos + 1] === QUESTION) {
+      skipProcessingInstruction();
+      continue;
+    }
+    fail("kök elementten sonra ikinci bir element");
+  }
+
+  return { root, declaredEncoding };
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @param {string} literal  ASCII only
+ * @param {number} from
+ * @returns {number}
+ */
+function indexOfAscii(bytes, literal, from) {
+  const first = literal.charCodeAt(0);
+  outer: for (let i = from; i <= bytes.length - literal.length; i++) {
+    if (bytes[i] !== first) continue;
+    for (let j = 1; j < literal.length; j++) {
+      if (bytes[i + j] !== literal.charCodeAt(j)) continue outer;
+    }
+    return i;
+  }
+  return -1;
+}