@particle-academy/holy-sheet 2.10.2 → 2.11.1

package/dist/index.cjs

@@ -521,9 +521,10 @@ var ChartRange = class _ChartRange {
 
 // src/workbook/workbook.ts
 var Workbook = class {
-  constructor(sheets, meta = {}) {
+  constructor(sheets, meta = {}, sourceKind2 = "document") {
     this.sheets = sheets;
     this.meta = meta;
+    this.sourceKind = sourceKind2;
   }
 };
 
@@ -568,6 +569,23 @@ var ArchiveRefused = class _ArchiveRefused extends Error {
     Object.setPrototypeOf(this, _ArchiveRefused.prototype);
   }
 };
+var TEMPLATE_MESSAGES = {
+  macro_enabled: "Macro-enabled templates (.xltm) are refused: re-save it as an .xltx in Excel.",
+  family_mismatch: "This package declares a template of a different kind than its contents.",
+  already_template: "This package is already a template.",
+  already_document: "This package is already a document.",
+  not_convertible: "This package has no single content-type declaration that can be rewritten.",
+  odf_mimetype: "An OpenDocument package must store its mimetype entry first and uncompressed.",
+  bad_target: 'The conversion target must be "document" or "template".'
+};
+var OfficeTemplateRefused = class _OfficeTemplateRefused extends Error {
+  constructor(reason) {
+    super(`Template refused (${reason}): ${TEMPLATE_MESSAGES[reason] ?? reason}`);
+    this.reason = reason;
+    this.name = "OfficeTemplateRefused";
+    Object.setPrototypeOf(this, _OfficeTemplateRefused.prototype);
+  }
+};
 var SchemaException = class _SchemaException extends Error {
   constructor(errors, message) {
     super(message ?? summarize(errors));
@@ -769,7 +787,7 @@ var Normalizer = class {
         address,
         new Cell(
           address,
-          this.coerceValue(rawValue, format, address, sheetName2),
+          this.coerceValue(rawValue, format, address, sheetName2, true),
           cellData?.formula ?? null,
           format,
           comment,
@@ -862,7 +880,7 @@ var Normalizer = class {
       const rawValue = value.value ?? null;
       return new Cell(
         address,
-        this.coerceValue(rawValue, merged, address, sheetName2),
+        this.coerceValue(rawValue, merged, address, sheetName2, true),
         value.formula ?? null,
         merged,
         comment,
@@ -877,7 +895,15 @@ var Normalizer = class {
       columnFormat
     );
   }
-  coerceValue(value, format, address = "?", sheetName2) {
+  /**
+   * `explicit`: the value came from an object cell's `value` key. An explicit
+   * string is the caller saying "this text, exactly", so it is never coerced
+   * to a number: `{value: "+1"}` stays "+1" and `{value: "007"}` stays "007".
+   * Only a date/datetime display format still turns a string into a serial,
+   * because that conversion is what the format asks for. Bare values keep
+   * numeric-string coercion. Mirrors PHP `Normalizer::coerceValue`.
+   */
+  coerceValue(value, format, address = "?", sheetName2, explicit = false) {
     if (value === null || value === void 0) return null;
     const df = format?.displayFormat;
     if (df === "date" || df === "datetime") {
@@ -885,6 +911,9 @@ var Normalizer = class {
         return DateConverter.toSerial(value, df === "datetime");
       }
     }
+    if (explicit && typeof value === "string") {
+      return value;
+    }
     if (typeof value === "string" && isNumericString(value)) {
       return numericStringToNumber(value);
     }
@@ -2624,9 +2653,11 @@ var corrupt = () => {
   throw new ArchiveRefused("archive_corrupt");
 };
 var SourceArchive = class _SourceArchive {
-  constructor(original, parts) {
+  constructor(original, parts, records = [], archiveComment = new Uint8Array()) {
     this.original = original;
     this.parts = parts;
+    this.records = records;
+    this.archiveComment = archiveComment;
   }
   static open(input, options = {}) {
     for (const [key, value] of Object.entries(options)) {
@@ -2635,7 +2666,7 @@ var SourceArchive = class _SourceArchive {
     const limits = { ...DEFAULT_ARCHIVE_LIMITS, ...options };
     if (input.length > limits.maxArchiveBytes) throw new ArchiveRefused("archive_limit");
     const bytes = input.slice();
-    const records = index(bytes, limits);
+    const [records, comment] = index(bytes, limits);
     const parts = /* @__PURE__ */ new Map();
     for (const record of records) {
       const compressed = bytes.subarray(record.start, record.start + record.compressed);
@@ -2648,7 +2679,8 @@ var SourceArchive = class _SourceArchive {
       if (payload.length !== record.size || crc32(payload) !== record.crc) corrupt();
       parts.set(record.name, payload);
     }
-    return new _SourceArchive(bytes, parts);
+    const entries = records.map(({ name, size, crc, local, finish, central, centralLength, flags, method, localExtra }) => ({ name, size, crc, local, finish, central, centralLength, flags, method, localExtra }));
+    return new _SourceArchive(bytes, parts, entries, comment);
   }
   names() {
     return [...this.parts.keys()];
@@ -2659,6 +2691,14 @@ var SourceArchive = class _SourceArchive {
   toBytes() {
     return this.original.slice();
   }
+  /** Verified member records in central-directory order. */
+  entries() {
+    return this.records.map((entry) => ({ ...entry }));
+  }
+  /** The archive comment, verbatim. */
+  comment() {
+    return this.archiveComment.slice();
+  }
 };
 function index(bytes, limits) {
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
@@ -2737,7 +2777,20 @@ function index(bytes, limits) {
       }
       if (!found) corrupt();
     }
-    records.push({ name, method, crc, size, compressed, start });
+    records.push({
+      name,
+      method,
+      crc,
+      size,
+      compressed,
+      start,
+      local,
+      finish,
+      central: at2,
+      centralLength: 46 + nameLength + extraLength + commentLength,
+      flags,
+      localExtra
+    });
     regions.push([local, finish]);
     at2 += 46 + nameLength + extraLength + commentLength;
   }
@@ -2748,7 +2801,7 @@ function index(bytes, limits) {
     if (start < previous) corrupt();
     previous = finish;
   }
-  return records;
+  return [records, bytes.slice(end + 22, end + 22 + u16(end + 20))];
 }
 function partName(bytes, flags) {
   let name;
@@ -2837,6 +2890,472 @@ var FormatSniffer = {
   }
 };
 
+// src/reader/xml.ts
+var XML_NS = "http://www.w3.org/XML/1998/namespace";
+function localName(name) {
+  const idx = name.indexOf(":");
+  return idx >= 0 ? name.slice(idx + 1) : name;
+}
+function unescapeXml(s) {
+  if (s.indexOf("&") < 0) return s;
+  return s.replace(/&(#x?[0-9a-fA-F]+|\w+);/g, (m, ent) => {
+    switch (ent) {
+      case "amp":
+        return "&";
+      case "lt":
+        return "<";
+      case "gt":
+        return ">";
+      case "quot":
+        return '"';
+      case "apos":
+        return "'";
+      default:
+        if (ent[0] === "#") {
+          const code = ent[1] === "x" || ent[1] === "X" ? parseInt(ent.slice(2), 16) : parseInt(ent.slice(1), 10);
+          return Number.isFinite(code) ? String.fromCodePoint(code) : m;
+        }
+        return m;
+    }
+  });
+}
+function findTagEnd(src, from) {
+  let quote2 = "";
+  for (let i = from; i < src.length; i++) {
+    const ch = src[i];
+    if (quote2) {
+      if (ch === quote2) quote2 = "";
+    } else if (ch === '"' || ch === "'") {
+      quote2 = ch;
+    } else if (ch === ">") {
+      return i;
+    }
+  }
+  return src.length;
+}
+var ATTR_RE = /([^\s=/]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+function parseTag(inner) {
+  const trimmed = inner.trim();
+  let i = 0;
+  while (i < trimmed.length && !/\s/.test(trimmed[i])) i++;
+  const name = trimmed.slice(0, i);
+  const attrs = {};
+  const raw = [];
+  const rest = trimmed.slice(i);
+  for (const m of rest.matchAll(ATTR_RE)) {
+    const rawValue = m[3] ?? m[4] ?? "";
+    attrs[localName(m[1])] = unescapeXml(rawValue);
+    raw.push([m[1], rawValue]);
+  }
+  return { name, attrs, raw };
+}
+function parseXml(src, options = {}) {
+  const namespaces = options.namespaces === true;
+  let i = 0;
+  const n = src.length;
+  const root = { name: "#root", attrs: {}, children: [], text: "" };
+  if (namespaces) root.content = [];
+  const stack = [root];
+  const scopes = [{ xml: XML_NS }];
+  const appendText = (text2) => {
+    const top = stack[stack.length - 1];
+    top.text += text2;
+    if (namespaces && text2 !== "") top.content.push(text2);
+  };
+  while (i < n) {
+    if (src[i] === "<") {
+      if (src.startsWith("<!--", i)) {
+        const end2 = src.indexOf("-->", i);
+        i = end2 < 0 ? n : end2 + 3;
+        continue;
+      }
+      if (src.startsWith("<![CDATA[", i)) {
+        const end2 = src.indexOf("]]>", i);
+        appendText(src.slice(i + 9, end2 < 0 ? n : end2));
+        i = end2 < 0 ? n : end2 + 3;
+        continue;
+      }
+      if (src.startsWith("<?", i)) {
+        const end2 = src.indexOf("?>", i);
+        i = end2 < 0 ? n : end2 + 2;
+        continue;
+      }
+      if (src.startsWith("<!", i)) {
+        const end2 = src.indexOf(">", i);
+        i = end2 < 0 ? n : end2 + 1;
+        continue;
+      }
+      if (src[i + 1] === "/") {
+        const end2 = src.indexOf(">", i);
+        if (stack.length > 1) {
+          stack.pop();
+          if (namespaces) scopes.pop();
+        }
+        i = end2 < 0 ? n : end2 + 1;
+        continue;
+      }
+      const end = findTagEnd(src, i + 1);
+      const tagContent = src.slice(i + 1, end);
+      const selfClosing = tagContent.endsWith("/");
+      const { name, attrs, raw } = parseTag(selfClosing ? tagContent.slice(0, -1) : tagContent);
+      const node = { name: localName(name), attrs, children: [], text: "" };
+      const parent = stack[stack.length - 1];
+      parent.children.push(node);
+      let scope;
+      if (namespaces) {
+        scope = resolveNamespaces(node, name, raw, scopes[scopes.length - 1]);
+        parent.content.push(node);
+      }
+      if (!selfClosing) {
+        stack.push(node);
+        if (scope) scopes.push(scope);
+      }
+      i = end + 1;
+    } else {
+      const next = src.indexOf("<", i);
+      const stop = next < 0 ? n : next;
+      appendText(unescapeXml(src.slice(i, stop)));
+      i = stop;
+    }
+  }
+  return root.children[0] ?? null;
+}
+function resolveNamespaces(node, qname, raw, parentScope) {
+  let scope = parentScope;
+  for (const [key, value] of raw) {
+    if (key === "xmlns" || key.startsWith("xmlns:")) {
+      if (scope === parentScope) scope = { ...parentScope };
+      scope[key === "xmlns" ? "" : key.slice(6)] = unescapeXml(value);
+    }
+  }
+  const colon = qname.indexOf(":");
+  node.ns = scope[colon >= 0 ? qname.slice(0, colon) : ""] ?? "";
+  node.content = [];
+  const nsAttrs = {};
+  for (const [key, value] of raw) {
+    if (key === "xmlns" || key.startsWith("xmlns:")) continue;
+    const idx = key.indexOf(":");
+    const normalised = unescapeXml(value.replace(/[\t\n\r]/g, " "));
+    if (idx < 0) {
+      nsAttrs[key] = normalised;
+    } else {
+      nsAttrs[`{${scope[key.slice(0, idx)] ?? ""}}${key.slice(idx + 1)}`] = normalised;
+    }
+  }
+  node.nsAttrs = nsAttrs;
+  return scope;
+}
+function el(node, name) {
+  return node?.children.find((c) => c.name === name);
+}
+function els(node, name) {
+  return node ? node.children.filter((c) => c.name === name) : [];
+}
+function at(node, name) {
+  return node?.attrs[name];
+}
+
+// src/zip/office-template.ts
+var DOCUMENT = "document";
+var TEMPLATE = "template";
+var FAMILY = "spreadsheet";
+var VBA = "application/vnd.ms-office.vbaProject";
+var FAMILIES = {
+  word: {
+    part: "/word/document.xml",
+    document: "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml",
+    template: "application/vnd.openxmlformats-officedocument.wordprocessingml.template.main+xml",
+    macroDocument: "application/vnd.ms-word.document.macroEnabled.main+xml",
+    macroTemplate: "application/vnd.ms-word.template.macroEnabledTemplate.main+xml",
+    odfDocument: "application/vnd.oasis.opendocument.text",
+    odfTemplate: "application/vnd.oasis.opendocument.text-template",
+    odfBody: "text"
+  },
+  presentation: {
+    part: "/ppt/presentation.xml",
+    document: "application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml",
+    template: "application/vnd.openxmlformats-officedocument.presentationml.template.main+xml",
+    macroDocument: "application/vnd.ms-powerpoint.presentation.macroEnabled.main+xml",
+    macroTemplate: "application/vnd.ms-powerpoint.template.macroEnabled.main+xml",
+    odfDocument: "application/vnd.oasis.opendocument.presentation",
+    odfTemplate: "application/vnd.oasis.opendocument.presentation-template",
+    odfBody: "presentation"
+  },
+  spreadsheet: {
+    part: "/xl/workbook.xml",
+    document: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml",
+    template: "application/vnd.openxmlformats-officedocument.spreadsheetml.template.main+xml",
+    macroDocument: "application/vnd.ms-excel.sheet.macroEnabled.main+xml",
+    macroTemplate: "application/vnd.ms-excel.template.macroEnabled.main+xml",
+    odfDocument: "application/vnd.oasis.opendocument.spreadsheet",
+    odfTemplate: "application/vnd.oasis.opendocument.spreadsheet-template",
+    odfBody: "spreadsheet"
+  }
+};
+var OWN = FAMILIES[FAMILY];
+var UTF8 = new TextDecoder("utf-8");
+function filesView(files) {
+  return {
+    read: (name) => Object.prototype.hasOwnProperty.call(files, name) ? files[name] : null,
+    names: () => Object.keys(files)
+  };
+}
+function sourceKind(zip) {
+  const types = zip.read("[Content_Types].xml");
+  if (types !== null) return ooxmlKind(zip, types);
+  const mimetype = zip.read("mimetype");
+  if (mimetype !== null) return odfKind(zip, latin1(mimetype));
+  return DOCUMENT;
+}
+function convert(bytes, to = null) {
+  if (to !== null && to !== DOCUMENT && to !== TEMPLATE) throw new OfficeTemplateRefused("bad_target");
+  const zip = SourceArchive.open(new Uint8Array(bytes));
+  const kind = sourceKind(zip);
+  const target = to ?? (kind === TEMPLATE ? DOCUMENT : TEMPLATE);
+  if (target === kind) throw new OfficeTemplateRefused(`already_${kind}`);
+  const replacements = /* @__PURE__ */ new Map();
+  const types = zip.read("[Content_Types].xml");
+  const mimetypeBytes = zip.read("mimetype");
+  if (types !== null) {
+    const declared = declarations(types);
+    if (declared === null) throw new OfficeTemplateRefused("not_convertible");
+    if (hasVba(zip, declared) || typesOf(declared, OWN.part).includes(OWN.macroDocument)) {
+      throw new OfficeTemplateRefused("macro_enabled");
+    }
+    const [from, value] = target === TEMPLATE ? [OWN.document, OWN.template] : [OWN.template, OWN.document];
+    replacements.set("[Content_Types].xml", fromLatin1(rewriteOverride(latin1(types), OWN.part, from, value)));
+  } else if (mimetypeBytes !== null) {
+    const entries = zip.entries();
+    const first2 = entries[0];
+    const byLocal = [...entries].sort((a, b) => a.local - b.local);
+    if (first2 === void 0 || first2.name !== "mimetype" || byLocal[0].name !== "mimetype" || first2.method !== 0 || first2.localExtra !== 0) {
+      throw new OfficeTemplateRefused("odf_mimetype");
+    }
+    const [from, value] = target === TEMPLATE ? [OWN.odfDocument, OWN.odfTemplate] : [OWN.odfTemplate, OWN.odfDocument];
+    if (latin1(mimetypeBytes) !== from) throw new OfficeTemplateRefused("not_convertible");
+    replacements.set("mimetype", fromLatin1(value));
+    const manifest = zip.read("META-INF/manifest.xml");
+    if (manifest !== null) {
+      const rewritten = rewriteManifestRoot(latin1(manifest), from, value);
+      if (rewritten !== null) replacements.set("META-INF/manifest.xml", fromLatin1(rewritten));
+    }
+  } else {
+    throw new OfficeTemplateRefused("not_convertible");
+  }
+  const out = rebuild(zip, replacements);
+  if (sourceKind(SourceArchive.open(out)) !== target) {
+    throw new Error("Template conversion did not produce the requested kind.");
+  }
+  return out;
+}
+function ooxmlKind(zip, types) {
+  const declared = declarations(types);
+  if (declared === null) return DOCUMENT;
+  let kind = DOCUMENT;
+  for (const [part2, type] of declared) {
+    for (const [name, family] of Object.entries(FAMILIES)) {
+      if (type !== family.template && type !== family.macroTemplate) continue;
+      if (name !== FAMILY || part2 !== asciiLower2(OWN.part)) throw new OfficeTemplateRefused("family_mismatch");
+      if (type === family.macroTemplate) throw new OfficeTemplateRefused("macro_enabled");
+      kind = TEMPLATE;
+    }
+  }
+  if (kind === TEMPLATE && hasVba(zip, declared)) throw new OfficeTemplateRefused("macro_enabled");
+  return kind;
+}
+function odfKind(zip, mimetype) {
+  if (mimetype !== OWN.odfTemplate) {
+    if (mimetype.startsWith("application/vnd.oasis.opendocument.") && mimetype.endsWith("-template")) {
+      throw new OfficeTemplateRefused("family_mismatch");
+    }
+    return DOCUMENT;
+  }
+  const content = dom(zip.read("content.xml"));
+  const body = content !== null ? firstByLocalName(content, "body") : null;
+  const first2 = body?.children[0] ?? null;
+  if (first2 === null || first2.name !== OWN.odfBody) throw new OfficeTemplateRefused("family_mismatch");
+  const root = manifestRootType(dom(zip.read("META-INF/manifest.xml")));
+  if (root !== null && root !== OWN.odfTemplate && root !== OWN.odfDocument) {
+    throw new OfficeTemplateRefused("family_mismatch");
+  }
+  return TEMPLATE;
+}
+function declarations(types) {
+  const root = dom(types);
+  if (root === null) return null;
+  const out = [];
+  for (const el2 of elements(root)) {
+    if (el2.name === "Override") out.push([asciiLower2(el2.attrs["PartName"] ?? ""), el2.attrs["ContentType"] ?? ""]);
+    else if (el2.name === "Default") out.push([`*.${asciiLower2(el2.attrs["Extension"] ?? "")}`, el2.attrs["ContentType"] ?? ""]);
+  }
+  return out;
+}
+function typesOf(declared, part2) {
+  return declared.filter(([name]) => name === asciiLower2(part2)).map(([, type]) => type);
+}
+function hasVba(zip, declared) {
+  if (declared.some(([, type]) => asciiLower2(type) === asciiLower2(VBA))) return true;
+  return zip.names().some((name) => /(^|\/)vbaProject\.bin$/i.test(name));
+}
+function manifestRootType(root) {
+  if (root === null) return null;
+  for (const el2 of elements(root)) {
+    if (el2.name === "file-entry" && el2.attrs["full-path"] === "/") return el2.attrs["media-type"] ?? null;
+  }
+  return null;
+}
+function rewriteOverride(xml, part2, from, to) {
+  const hits = [];
+  for (const tag of xml.matchAll(/<(?:[A-Za-z_][\w.\-]*:)?Override\b[^>]*>/g)) {
+    const name = /\sPartName\s*=\s*(["'])(.*?)\1/s.exec(tag[0]);
+    if (name === null || asciiLower2(name[2]) !== asciiLower2(part2)) continue;
+    const type = /\sContentType\s*=\s*(["'])(.*?)\1/s.exec(tag[0]);
+    if (type !== null && type[2] === from) hits.push(tag.index + type.index + type[0].indexOf(type[1]) + 1);
+  }
+  if (hits.length !== 1) throw new OfficeTemplateRefused("not_convertible");
+  const out = xml.slice(0, hits[0]) + to + xml.slice(hits[0] + from.length);
+  const declared = declarations(out);
+  const after = declared === null ? [] : typesOf(declared, part2);
+  if (after.length !== 1 || after[0] !== to) throw new OfficeTemplateRefused("not_convertible");
+  return out;
+}
+function rewriteManifestRoot(xml, from, to) {
+  const current = manifestRootType(dom(xml));
+  if (current === null) return null;
+  if (current !== from) throw new OfficeTemplateRefused("not_convertible");
+  const hits = [];
+  for (const tag of xml.matchAll(/<(?:[A-Za-z_][\w.\-]*:)?file-entry\b[^>]*>/g)) {
+    if (!/\s(?:[A-Za-z_][\w.\-]*:)?full-path\s*=\s*(["'])\/\1/.test(tag[0])) continue;
+    const type = /\s(?:[A-Za-z_][\w.\-]*:)?media-type\s*=\s*(["'])(.*?)\1/s.exec(tag[0]);
+    if (type !== null && type[2] === from) hits.push(tag.index + type.index + type[0].indexOf(type[1]) + 1);
+  }
+  if (hits.length !== 1) throw new OfficeTemplateRefused("not_convertible");
+  const out = xml.slice(0, hits[0]) + to + xml.slice(hits[0] + from.length);
+  if (manifestRootType(dom(out)) !== to) throw new OfficeTemplateRefused("not_convertible");
+  return out;
+}
+function rebuild(zip, replacements) {
+  const original = zip.toBytes();
+  const view = new DataView(original.buffer, original.byteOffset, original.byteLength);
+  const u16 = (at2) => view.getUint16(at2, true);
+  const u32 = (at2) => view.getUint32(at2, true);
+  const entries = zip.entries();
+  const byLocal = [...entries].sort((a, b) => a.local - b.local);
+  const nameBytes = (entry) => original.subarray(entry.central + 46, entry.central + 46 + u16(entry.central + 28));
+  const chunks = [];
+  const offsets = /* @__PURE__ */ new Map();
+  let length = 0;
+  const push = (chunk) => {
+    chunks.push(chunk);
+    length += chunk.length;
+  };
+  for (const entry of byLocal) {
+    offsets.set(entry.name, length);
+    const data = replacements.get(entry.name);
+    if (data === void 0) {
+      push(original.subarray(entry.local, entry.finish));
+      continue;
+    }
+    const name = nameBytes(entry);
+    const header = new Uint8Array(30 + name.length + data.length);
+    const hv = new DataView(header.buffer);
+    hv.setUint32(0, 67324752, true);
+    hv.setUint16(4, 10, true);
+    hv.setUint16(6, entry.flags & 2048, true);
+    hv.setUint16(8, 0, true);
+    hv.setUint16(10, u16(entry.local + 10), true);
+    hv.setUint16(12, u16(entry.local + 12), true);
+    hv.setUint32(14, crc32(data) >>> 0, true);
+    hv.setUint32(18, data.length, true);
+    hv.setUint32(22, data.length, true);
+    hv.setUint16(26, name.length, true);
+    hv.setUint16(28, 0, true);
+    header.set(name, 30);
+    header.set(data, 30 + name.length);
+    push(header);
+  }
+  const localsLength = length;
+  for (const entry of entries) {
+    const data = replacements.get(entry.name);
+    if (data === void 0) {
+      const record2 = new Uint8Array(entry.centralLength);
+      record2.set(original.subarray(entry.central, entry.central + entry.centralLength));
+      new DataView(record2.buffer, record2.byteOffset, record2.byteLength).setUint32(42, offsets.get(entry.name), true);
+      push(record2);
+      continue;
+    }
+    const name = nameBytes(entry);
+    const at2 = entry.central;
+    const record = new Uint8Array(46 + name.length);
+    const rv = new DataView(record.buffer);
+    rv.setUint32(0, 33639248, true);
+    rv.setUint16(4, u16(at2 + 4), true);
+    rv.setUint16(6, 10, true);
+    rv.setUint16(8, entry.flags & 2048, true);
+    rv.setUint16(10, 0, true);
+    rv.setUint16(12, u16(at2 + 12), true);
+    rv.setUint16(14, u16(at2 + 14), true);
+    rv.setUint32(16, crc32(data) >>> 0, true);
+    rv.setUint32(20, data.length, true);
+    rv.setUint32(24, data.length, true);
+    rv.setUint16(28, name.length, true);
+    rv.setUint16(36, u16(at2 + 36), true);
+    rv.setUint32(38, u32(at2 + 38), true);
+    rv.setUint32(42, offsets.get(entry.name), true);
+    record.set(name, 46);
+    push(record);
+  }
+  const comment = zip.comment();
+  const end = new Uint8Array(22 + comment.length);
+  const ev = new DataView(end.buffer);
+  ev.setUint32(0, 101010256, true);
+  ev.setUint16(8, entries.length, true);
+  ev.setUint16(10, entries.length, true);
+  ev.setUint32(12, length - localsLength, true);
+  ev.setUint32(16, localsLength, true);
+  ev.setUint16(20, comment.length, true);
+  end.set(comment, 22);
+  push(end);
+  const out = new Uint8Array(length);
+  let pos = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, pos);
+    pos += chunk.length;
+  }
+  return out;
+}
+function dom(xml) {
+  if (xml === null) return null;
+  const text2 = typeof xml === "string" ? UTF8.decode(fromLatin1(xml)) : UTF8.decode(xml);
+  if (text2 === "" || /<!DOCTYPE/i.test(text2)) return null;
+  return parseXml(text2);
+}
+function* elements(root) {
+  const stack = [root];
+  while (stack.length > 0) {
+    const el2 = stack.pop();
+    yield el2;
+    for (let i = el2.children.length - 1; i >= 0; i--) stack.push(el2.children[i]);
+  }
+}
+function firstByLocalName(root, local) {
+  for (const el2 of elements(root)) if (el2.name === local) return el2;
+  return null;
+}
+function asciiLower2(s) {
+  return s.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
+}
+function latin1(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 32768) out += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return out;
+}
+function fromLatin1(s) {
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i) & 255;
+  return out;
+}
+
 // src/reader/file-input.ts
 async function readFileBounded(path) {
   const fs = await import('fs');
@@ -3377,6 +3896,7 @@ var WorkbookSchema = {
   fromWorkbook(workbook) {
     const schema = { sheets: workbook.sheets.map(sheetToSchema) };
     if (Object.keys(workbook.meta).length > 0) schema["meta"] = workbook.meta;
+    if (workbook.sourceKind === "template") schema["sourceKind"] = "template";
     return schema;
   }
 };
@@ -3479,171 +3999,6 @@ function commentToObject(c) {
   return out;
 }
 
-// src/reader/xml.ts
-var XML_NS = "http://www.w3.org/XML/1998/namespace";
-function localName(name) {
-  const idx = name.indexOf(":");
-  return idx >= 0 ? name.slice(idx + 1) : name;
-}
-function unescapeXml(s) {
-  if (s.indexOf("&") < 0) return s;
-  return s.replace(/&(#x?[0-9a-fA-F]+|\w+);/g, (m, ent) => {
-    switch (ent) {
-      case "amp":
-        return "&";
-      case "lt":
-        return "<";
-      case "gt":
-        return ">";
-      case "quot":
-        return '"';
-      case "apos":
-        return "'";
-      default:
-        if (ent[0] === "#") {
-          const code = ent[1] === "x" || ent[1] === "X" ? parseInt(ent.slice(2), 16) : parseInt(ent.slice(1), 10);
-          return Number.isFinite(code) ? String.fromCodePoint(code) : m;
-        }
-        return m;
-    }
-  });
-}
-function findTagEnd(src, from) {
-  let quote2 = "";
-  for (let i = from; i < src.length; i++) {
-    const ch = src[i];
-    if (quote2) {
-      if (ch === quote2) quote2 = "";
-    } else if (ch === '"' || ch === "'") {
-      quote2 = ch;
-    } else if (ch === ">") {
-      return i;
-    }
-  }
-  return src.length;
-}
-var ATTR_RE = /([^\s=/]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
-function parseTag(inner) {
-  const trimmed = inner.trim();
-  let i = 0;
-  while (i < trimmed.length && !/\s/.test(trimmed[i])) i++;
-  const name = trimmed.slice(0, i);
-  const attrs = {};
-  const raw = [];
-  const rest = trimmed.slice(i);
-  for (const m of rest.matchAll(ATTR_RE)) {
-    const rawValue = m[3] ?? m[4] ?? "";
-    attrs[localName(m[1])] = unescapeXml(rawValue);
-    raw.push([m[1], rawValue]);
-  }
-  return { name, attrs, raw };
-}
-function parseXml(src, options = {}) {
-  const namespaces = options.namespaces === true;
-  let i = 0;
-  const n = src.length;
-  const root = { name: "#root", attrs: {}, children: [], text: "" };
-  if (namespaces) root.content = [];
-  const stack = [root];
-  const scopes = [{ xml: XML_NS }];
-  const appendText = (text2) => {
-    const top = stack[stack.length - 1];
-    top.text += text2;
-    if (namespaces && text2 !== "") top.content.push(text2);
-  };
-  while (i < n) {
-    if (src[i] === "<") {
-      if (src.startsWith("<!--", i)) {
-        const end2 = src.indexOf("-->", i);
-        i = end2 < 0 ? n : end2 + 3;
-        continue;
-      }
-      if (src.startsWith("<![CDATA[", i)) {
-        const end2 = src.indexOf("]]>", i);
-        appendText(src.slice(i + 9, end2 < 0 ? n : end2));
-        i = end2 < 0 ? n : end2 + 3;
-        continue;
-      }
-      if (src.startsWith("<?", i)) {
-        const end2 = src.indexOf("?>", i);
-        i = end2 < 0 ? n : end2 + 2;
-        continue;
-      }
-      if (src.startsWith("<!", i)) {
-        const end2 = src.indexOf(">", i);
-        i = end2 < 0 ? n : end2 + 1;
-        continue;
-      }
-      if (src[i + 1] === "/") {
-        const end2 = src.indexOf(">", i);
-        if (stack.length > 1) {
-          stack.pop();
-          if (namespaces) scopes.pop();
-        }
-        i = end2 < 0 ? n : end2 + 1;
-        continue;
-      }
-      const end = findTagEnd(src, i + 1);
-      const tagContent = src.slice(i + 1, end);
-      const selfClosing = tagContent.endsWith("/");
-      const { name, attrs, raw } = parseTag(selfClosing ? tagContent.slice(0, -1) : tagContent);
-      const node = { name: localName(name), attrs, children: [], text: "" };
-      const parent = stack[stack.length - 1];
-      parent.children.push(node);
-      let scope;
-      if (namespaces) {
-        scope = resolveNamespaces(node, name, raw, scopes[scopes.length - 1]);
-        parent.content.push(node);
-      }
-      if (!selfClosing) {
-        stack.push(node);
-        if (scope) scopes.push(scope);
-      }
-      i = end + 1;
-    } else {
-      const next = src.indexOf("<", i);
-      const stop = next < 0 ? n : next;
-      appendText(unescapeXml(src.slice(i, stop)));
-      i = stop;
-    }
-  }
-  return root.children[0] ?? null;
-}
-function resolveNamespaces(node, qname, raw, parentScope) {
-  let scope = parentScope;
-  for (const [key, value] of raw) {
-    if (key === "xmlns" || key.startsWith("xmlns:")) {
-      if (scope === parentScope) scope = { ...parentScope };
-      scope[key === "xmlns" ? "" : key.slice(6)] = unescapeXml(value);
-    }
-  }
-  const colon = qname.indexOf(":");
-  node.ns = scope[colon >= 0 ? qname.slice(0, colon) : ""] ?? "";
-  node.content = [];
-  const nsAttrs = {};
-  for (const [key, value] of raw) {
-    if (key === "xmlns" || key.startsWith("xmlns:")) continue;
-    const idx = key.indexOf(":");
-    const normalised = unescapeXml(value.replace(/[\t\n\r]/g, " "));
-    if (idx < 0) {
-      nsAttrs[key] = normalised;
-    } else {
-      nsAttrs[`{${scope[key.slice(0, idx)] ?? ""}}${key.slice(idx + 1)}`] = normalised;
-    }
-  }
-  node.nsAttrs = nsAttrs;
-  return scope;
-}
-function el(node, name) {
-  return node?.children.find((c) => c.name === name);
-}
-function els(node, name) {
-  return node ? node.children.filter((c) => c.name === name) : [];
-}
-function at(node, name) {
-  return node?.attrs[name];
-}
-
 // src/reader/ods-reader.ts
 var MAX_ROWS = 1048576;
 var MAX_COLUMNS = 16384;
@@ -3658,6 +4013,7 @@ var OdsReader = class {
   }
   /** Read an already-unzipped package (name -> bytes). */
   readFiles(files) {
+    const kind = sourceKind(filesView(files));
     const getText = (name) => files[name] ? decoder2.decode(files[name]) : null;
     const content = getText("content.xml");
     if (content === null) throw new Error("[holy-sheet] missing content.xml");
@@ -3672,7 +4028,7 @@ var OdsReader = class {
       if (table.ns === NS.TABLE && table.name === "table") sheets.push(this.readSheet(table, styles));
     }
     const meta = getText("meta.xml");
-    return new Workbook(sheets, meta === null ? {} : readMeta(meta));
+    return new Workbook(sheets, meta === null ? {} : readMeta(meta), kind);
   }
   readSheet(table, styles) {
     const columns = [];
@@ -4338,6 +4694,7 @@ var XlsxReader = class {
   }
   /** Read an already-unzipped package (name -> bytes), so a caller that sniffed it does not unzip twice. */
   readFiles(files) {
+    const kind = sourceKind(filesView(files));
     const getText = (name) => files[name] ? decoder3.decode(files[name]) : null;
     const stylesXml = getText("xl/styles.xml");
     const stylesIndex = stylesXml ? StylesParser.parse(stylesXml) : [];
@@ -4393,7 +4750,7 @@ var XlsxReader = class {
       i++;
     }
     const meta = this.parseDocProps(getText("docProps/core.xml"));
-    return new Workbook(sheets, meta);
+    return new Workbook(sheets, meta, kind);
   }
   parseDocProps(coreXml) {
     if (coreXml === null) return {};
@@ -6331,7 +6688,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.10.2";
+var VERSION = "2.11.1";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }
@@ -6372,6 +6729,32 @@ var Agent = {
   read(input) {
     return readSpreadsheet(toU8(input), null);
   },
+  /**
+   * Turn an Excel `.xltx` / LibreOffice `.ots` template into its `.xlsx` /
+   * `.ods` twin, or back. `to` is `"document"`, `"template"`, or null to flip.
+   * Universal and synchronous: bytes in, bytes out. Mirrors PHP
+   * `Agent::convertTemplate()`.
+   *
+   * Only the declaration moves: the workbook part's content type in
+   * `[Content_Types].xml`, or the ODF `mimetype` entry together with the
+   * manifest's root media-type (ODF 1.3 requires them to agree). Every other
+   * member is copied as its original zip record, byte for byte.
+   *
+   * Throws `OfficeTemplateRefused` (macro-enabled, mismatched, already that
+   * kind), `ArchiveRefused` (archive guard), or `UnsupportedFormatException`
+   * for a package that is not a spreadsheet.
+   */
+  convertTemplate(input, to = null) {
+    const bytes = toU8(input);
+    const zip = SourceArchive.open(bytes);
+    const raw = zip.read("mimetype");
+    const mimetype = raw === null ? null : new TextDecoder().decode(raw).trim();
+    const odf = mimetype !== null && mimetype.startsWith("application/vnd.oasis.opendocument.spreadsheet");
+    if (!odf && (mimetype !== null || zip.read("xl/workbook.xml") === null)) {
+      throw UnsupportedFormatException.unknownPackage(null, mimetype);
+    }
+    return convert(bytes, to);
+  },
   /** Round-trip an xlsx or ods file on disk back to a schema (Node only). */
   async describe(path) {
     const fs = await import('fs');
@@ -6473,6 +6856,10 @@ var HolySheet = class {
   describe(path) {
     return Agent.describe(path);
   }
+  /** {@link Agent.convertTemplate}: .xltx/.ots to .xlsx/.ods and back. */
+  convertTemplate(input, to = null) {
+    return Agent.convertTemplate(input, to);
+  }
   validateAndRepair(schema) {
     return Agent.validateAndRepair(schema);
   }
@@ -6505,6 +6892,7 @@ exports.HolySheet = HolySheet;
 exports.Inference = Inference;
 exports.Normalizer = Normalizer;
 exports.OdsReader = OdsReader;
+exports.OfficeTemplateRefused = OfficeTemplateRefused;
 exports.Repairer = Repairer;
 exports.SchemaException = SchemaException;
 exports.SheetDiff = SheetDiff;