@mkterswingman/5mghost-wonder 0.0.1

package/dist/wecom/export.js

@@ -0,0 +1,236 @@
+// src/wecom/export.ts
+// WeCom document export client.
+// Implements the three-step flow:
+//   1. POST /v1/export/export_office → operationId
+//   2. GET  /v1/export/query_progress (poll until Done)
+//   3. GET  {file_url} → write to disk
+//
+// All three document types (sheet/doc/slide) share this same flow.
+// URL parsing is in ./url.ts; cookie management is in ./cookies.ts (P1-03).
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+/** Error thrown by exportWecomDoc() */
+export class ExportError extends Error {
+    kind;
+    detail;
+    constructor(kind, message, detail) {
+        super(message);
+        this.kind = kind;
+        this.detail = detail;
+        this.name = "ExportError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build the Cookie header string from an array of CookieEntry.
+ * Format: "name1=value1; name2=value2; ..."
+ */
+function buildCookieHeader(cookies) {
+    // W-02: strip `;` and `\n` from values to prevent Cookie header injection.
+    return cookies
+        .map((c) => `${c.name}=${String(c.value).replace(/[;\n]/g, "")}`)
+        .join("; ");
+}
+/**
+ * Extract the TOK cookie value to use as the xsrf query parameter.
+ * The WeCom export API requires xsrf={TOK} on all GET requests.
+ * Returns empty string if TOK is not present (will result in 401).
+ */
+function buildXsrfToken(cookies) {
+    return cookies.find((c) => c.name === "TOK")?.value ?? "";
+}
+// ---------------------------------------------------------------------------
+// Step 1
+// ---------------------------------------------------------------------------
+/**
+ * Step 1: POST /v1/export/export_office to create an export task.
+ * Returns the operationId needed for polling.
+ */
+async function createExportTask(docId, cookieHeader, sourceUrl) {
+    const body = new URLSearchParams({
+        docId,
+        version: "1",
+        exportType: "1",
+    }).toString();
+    let res;
+    try {
+        res = await fetch("https://doc.weixin.qq.com/v1/export/export_office", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Cookie: cookieHeader,
+                Referer: sourceUrl,
+            },
+            body,
+        });
+    }
+    catch (err) {
+        throw new ExportError("network_error", `export_office fetch failed: ${String(err)}`, err);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let data;
+    try {
+        data = await res.json();
+    }
+    catch (err) {
+        throw new ExportError("export_api_error", `export_office response not JSON (HTTP ${res.status})`, err);
+    }
+    // API returns error_code on auth failure or unsupported types
+    if (data.error_code) {
+        throw new ExportError("export_api_error", `export_office error: code=${data.error_code} msg=${data.error_msg ?? ""}`, data);
+    }
+    // operationId may be at top-level or nested under data.*
+    const operationId = data.operationId ?? data.data?.operationId;
+    if (!operationId) {
+        throw new ExportError("no_operation_id", `export_office returned no operationId: ${JSON.stringify(data)}`, data);
+    }
+    return operationId;
+}
+/**
+ * Step 2: Poll GET /v1/export/query_progress until status === "Done".
+ *
+ * Interval schedule: the first request fires immediately (no leading wait).
+ * Subsequent waits use an exponential backoff at 500ms → 1000ms → 2000ms → 3000ms
+ * (capped), unless the caller passes an explicit non-default pollIntervalMs,
+ * in which case that fixed interval is used (useful for tests).
+ *
+ * Throws ExportError if:
+ *   - status === "Failed"
+ *   - HTTP error during poll
+ *   - maxPollAttempts exceeded without Done
+ *   - Done but no file_url in response
+ */
+async function pollExportProgress(operationId, xsrf, cookieHeader, sourceUrl, maxPollAttempts, pollIntervalMs) {
+    // Use the supplied interval only when the caller passes a non-default value
+    // (typical: a test pins a short, deterministic interval).
+    const useFixedInterval = pollIntervalMs !== DEFAULT_POLL_INTERVAL_MS;
+    for (let attempt = 0; attempt < maxPollAttempts; attempt++) {
+        if (attempt > 0) {
+            let waitMs;
+            if (useFixedInterval) {
+                waitMs = pollIntervalMs;
+            }
+            else if (attempt === 1)
+                waitMs = 500;
+            else if (attempt === 2)
+                waitMs = 1000;
+            else if (attempt === 3)
+                waitMs = 2000;
+            else
+                waitMs = 3000;
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+        }
+        const pollUrl = `https://doc.weixin.qq.com/v1/export/query_progress` +
+            `?operationId=${encodeURIComponent(operationId)}&xsrf=${encodeURIComponent(xsrf)}`;
+        let res;
+        try {
+            res = await fetch(pollUrl, {
+                headers: { Cookie: cookieHeader, Referer: sourceUrl },
+            });
+        }
+        catch (err) {
+            throw new ExportError("network_error", `query_progress fetch failed (attempt ${attempt + 1}): ${String(err)}`, err);
+        }
+        if (!res.ok) {
+            throw new ExportError("poll_http_error", `query_progress HTTP ${res.status} (attempt ${attempt + 1})`, { status: res.status });
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let data;
+        try {
+            data = await res.json();
+        }
+        catch {
+            // Non-JSON response on a transient error — retry
+            continue;
+        }
+        // Fields may be at top-level or nested under data.*
+        const status = data.data?.status ?? data.status ?? "";
+        const progress = data.data?.progress ?? data.progress ?? 0;
+        const fileUrl = data.data?.file_url ?? data.file_url ?? "";
+        const fileName = data.data?.file_name ?? data.file_name ?? `${operationId}.bin`;
+        if (status === "Failed") {
+            throw new ExportError("poll_failed", `Export task failed (progress=${progress}%): ${JSON.stringify(data)}`, data);
+        }
+        if (status === "Done" || progress >= 100) {
+            if (!fileUrl) {
+                throw new ExportError("no_file_url", `Export Done but no file_url in response: ${JSON.stringify(data)}`, data);
+            }
+            return { fileUrl, fileName };
+        }
+        // status is still in-progress — continue polling
+    }
+    throw new ExportError("poll_timeout", `Export did not complete after ${maxPollAttempts} attempts (~${Math.round((maxPollAttempts * pollIntervalMs) / 1000)}s)`, { maxPollAttempts, pollIntervalMs });
+}
+// ---------------------------------------------------------------------------
+// Step 3
+// ---------------------------------------------------------------------------
+/**
+ * Step 3: Download the exported file from the COS pre-signed URL to disk.
+ * COS URLs are public pre-signed — no Cookie or auth header needed.
+ * Returns the absolute path of the written file.
+ */
+async function downloadExportedFile(fileUrl, fileName, saveDir) {
+    let res;
+    try {
+        res = await fetch(fileUrl);
+    }
+    catch (err) {
+        throw new ExportError("network_error", `Download fetch failed: ${String(err)}`, err);
+    }
+    if (!res.ok) {
+        throw new ExportError("download_http_error", `Download HTTP ${res.status} for: ${fileUrl}`, { status: res.status, url: fileUrl });
+    }
+    let buffer;
+    try {
+        buffer = await res.arrayBuffer();
+    }
+    catch (err) {
+        throw new ExportError("download_http_error", `Failed to read download response body: ${String(err)}`, err);
+    }
+    try {
+        mkdirSync(saveDir, { recursive: true });
+    }
+    catch (err) {
+        throw new ExportError("write_error", `Failed to create save directory "${saveDir}": ${String(err)}`, err);
+    }
+    const filePath = join(saveDir, fileName);
+    try {
+        writeFileSync(filePath, Buffer.from(buffer));
+    }
+    catch (err) {
+        throw new ExportError("write_error", `Failed to write file to "${filePath}": ${String(err)}`, err);
+    }
+    return { filePath, fileSizeBytes: buffer.byteLength };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Default poll config */
+const DEFAULT_MAX_POLL_ATTEMPTS = 60; // 60 × 2s = 2 minutes max
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+/**
+ * Export a WeCom document to a local file.
+ *
+ * Orchestrates the three-step flow:
+ *   1. Create export task (POST /v1/export/export_office)
+ *   2. Poll progress     (GET  /v1/export/query_progress)
+ *   3. Download file     (GET  {COS file_url})
+ *
+ * All three document types (sheet / doc / slide) use the same flow.
+ *
+ * @throws ExportError with a typed `kind` field on any failure
+ */
+export async function exportWecomDoc(input) {
+    const { docId, docType, sourceUrl, cookies, saveDir, maxPollAttempts = DEFAULT_MAX_POLL_ATTEMPTS, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, } = input;
+    const cookieHeader = buildCookieHeader(cookies);
+    const xsrf = buildXsrfToken(cookies);
+    // Step 1: Create export task
+    const operationId = await createExportTask(docId, cookieHeader, sourceUrl);
+    // Step 2: Poll until Done
+    const { fileUrl, fileName } = await pollExportProgress(operationId, xsrf, cookieHeader, sourceUrl, maxPollAttempts, pollIntervalMs);
+    // Step 3: Download
+    const { filePath, fileSizeBytes } = await downloadExportedFile(fileUrl, fileName, saveDir);
+    return { filePath, fileName, fileSizeBytes, docType };
+}

package/dist/wecom/url.js

@@ -0,0 +1,45 @@
+// src/wecom/url.ts
+// Parse a doc.weixin.qq.com URL into its docId and type.
+// Known-unsupported types return an "unsupported" result (not null)
+// so callers can produce a friendly hint instead of a generic "invalid URL".
+/**
+ * Parse a WeCom document URL.
+ *
+ * Supported URL patterns:
+ *   https://doc.weixin.qq.com/sheet/e3_{docId}?...   → sheet
+ *   https://doc.weixin.qq.com/doc/w3_{docId}?...     → doc
+ *   https://doc.weixin.qq.com/doc/e2_{docId}?...     → doc
+ *   https://doc.weixin.qq.com/slide/p3_{docId}?...   → slide
+ *
+ * Known unsupported (export API hangs or not applicable):
+ *   https://doc.weixin.qq.com/smartpage/a1_{docId}   → kind="smartpage"
+ *   https://doc.weixin.qq.com/mind/m4_{docId}        → kind="mind"
+ */
+export function parseWecomUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return { ok: false, reason: "invalid" };
+    }
+    const seg = u.pathname.split("/").filter(Boolean);
+    const kind = seg[0];
+    const docId = seg[1];
+    if (!kind || !docId)
+        return { ok: false, reason: "invalid" };
+    switch (kind) {
+        case "sheet":
+            return { ok: true, docId, docType: "sheet" };
+        case "doc":
+            return { ok: true, docId, docType: "doc" };
+        case "slide":
+            return { ok: true, docId, docType: "slide" };
+        case "smartpage":
+            return { ok: false, reason: "unsupported", kind: "smartpage" };
+        case "mind":
+            return { ok: false, reason: "unsupported", kind: "mind" };
+        default:
+            return { ok: false, reason: "invalid" };
+    }
+}

package/dist/wecom/url.test.js

@@ -0,0 +1,64 @@
+// src/wecom/url.test.ts
+// Run with: node --loader ts-node/esm src/wecom/url.test.ts
+// Or after build: node dist/wecom/url.test.js
+import assert from "assert/strict";
+import { parseWecomUrl } from "./url.js";
+// --- Happy paths ---
+const sheet = parseWecomUrl("https://doc.weixin.qq.com/sheet/e3_AbcXxx?scode=foo&xsrf=bar");
+assert.ok(sheet.ok, "sheet URL should parse");
+if (sheet.ok) {
+    assert.equal(sheet.docType, "sheet");
+    assert.equal(sheet.docId, "e3_AbcXxx");
+}
+const docW3 = parseWecomUrl("https://doc.weixin.qq.com/doc/w3_YyyZzz");
+assert.ok(docW3.ok, "w3_ doc URL should parse");
+if (docW3.ok) {
+    assert.equal(docW3.docType, "doc");
+    assert.equal(docW3.docId, "w3_YyyZzz");
+}
+const docE2 = parseWecomUrl("https://doc.weixin.qq.com/doc/e2_AnotherDoc");
+assert.ok(docE2.ok, "e2_ doc URL should parse");
+if (docE2.ok) {
+    assert.equal(docE2.docType, "doc");
+    assert.equal(docE2.docId, "e2_AnotherDoc");
+}
+const slide = parseWecomUrl("https://doc.weixin.qq.com/slide/p3_SlideId?foo=1");
+assert.ok(slide.ok, "slide URL should parse");
+if (slide.ok) {
+    assert.equal(slide.docType, "slide");
+    assert.equal(slide.docId, "p3_SlideId");
+}
+// --- Unsupported types (new: friendly hint path) ---
+const smartpage = parseWecomUrl("https://doc.weixin.qq.com/smartpage/a1_SmartId");
+assert.equal(smartpage.ok, false);
+if (!smartpage.ok) {
+    assert.equal(smartpage.reason, "unsupported");
+    if (smartpage.reason === "unsupported") {
+        assert.equal(smartpage.kind, "smartpage");
+    }
+}
+const mind = parseWecomUrl("https://doc.weixin.qq.com/mind/m4_MindId");
+assert.equal(mind.ok, false);
+if (!mind.ok) {
+    assert.equal(mind.reason, "unsupported");
+    if (mind.reason === "unsupported") {
+        assert.equal(mind.kind, "mind");
+    }
+}
+// --- Invalid cases ---
+const wrongHost = parseWecomUrl("https://example.com/sheet/e3_Abc");
+// Different domain — we don't enforce domain here, pathname will still parse
+assert.ok(wrongHost.ok || !wrongHost.ok, "wrong domain should not throw");
+const noPath = parseWecomUrl("https://doc.weixin.qq.com/");
+assert.equal(noPath.ok, false);
+if (!noPath.ok)
+    assert.equal(noPath.reason, "invalid");
+const malformed = parseWecomUrl("not-a-url");
+assert.equal(malformed.ok, false);
+if (!malformed.ok)
+    assert.equal(malformed.reason, "invalid");
+const emptyString = parseWecomUrl("");
+assert.equal(emptyString.ok, false);
+if (!emptyString.ok)
+    assert.equal(emptyString.reason, "invalid");
+console.log("✅ parseWecomUrl: all assertions passed");

package/dist/xlsx/drawing.js

@@ -0,0 +1,131 @@
+// src/xlsx/drawing.ts
+// Phase 2 (02-04): Parse xl/drawings/drawingN.xml + rels, extract images to saveDir/media/.
+import { XMLParser } from "fast-xml-parser";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
+/**
+ * Parse one drawing XML + its rels, extract image files, return anchor mapping.
+ *
+ * @param zip         JSZip instance (already-opened xlsx zip)
+ * @param drawingPath zip-internal drawing path, e.g. "xl/drawings/drawing1.xml"
+ * @param saveDir     output directory; images written to saveDir/media/
+ * @returns           DrawingImage array, in XML appearance order
+ */
+export async function parseDrawing(zip, drawingPath, saveDir) {
+    // Step 1: build rId → zip image path from rels
+    const rIdToZipPath = await buildRelsMap(zip, drawingPath);
+    // Step 2: parse drawing.xml anchors
+    const drawingXml = (await zip.file(drawingPath)?.async("string")) ?? null;
+    if (!drawingXml) {
+        console.warn(`[drawing] drawing not found in zip: ${drawingPath}`);
+        return [];
+    }
+    const anchors = parseAnchors(drawingXml);
+    // Step 3 + 4: extract images and assemble results
+    await mkdir(`${saveDir}/media`, { recursive: true });
+    const results = [];
+    for (const anchor of anchors) {
+        const zipImagePath = rIdToZipPath.get(anchor.rId);
+        if (!zipImagePath) {
+            console.warn(`[drawing] rId "${anchor.rId}" not found in rels for ${drawingPath}`);
+            continue;
+        }
+        const data = (await zip.file(zipImagePath)?.async("nodebuffer")) ?? null;
+        if (!data) {
+            console.warn(`[drawing] image not found in zip: ${zipImagePath}`);
+            continue;
+        }
+        const filename = basename(zipImagePath);
+        await writeFile(`${saveDir}/media/${filename}`, data);
+        results.push({ row: anchor.row, col: anchor.col, path: `media/${filename}` });
+    }
+    return results;
+}
+/**
+ * Parse drawing.xml and return raw anchor entries (row, col, rId).
+ * Handles both oneCellAnchor and twoCellAnchor; always uses <from> coords.
+ */
+function parseAnchors(xml) {
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        // Strip namespace prefixes from element names (xdr:from → from, a:blip → blip).
+        // Attribute names are NOT stripped, so @_r:embed stays @_r:embed.
+        removeNSPrefix: true,
+        isArray: (name) => name === "oneCellAnchor" || name === "twoCellAnchor",
+    });
+    const doc = parser.parse(xml);
+    // Root element: <xdr:wsDr> → after removeNSPrefix → "wsDr"
+    const root = doc?.wsDr;
+    const entries = [];
+    for (const anchorType of ["oneCellAnchor", "twoCellAnchor"]) {
+        const list = root?.[anchorType] ?? [];
+        for (const item of list) {
+            const entry = extractAnchor(item);
+            if (entry)
+                entries.push(entry);
+        }
+    }
+    return entries;
+}
+function extractAnchor(anchor) {
+    // <xdr:from> → "from" after removeNSPrefix
+    const from = anchor["from"];
+    if (!from)
+        return null;
+    const row = Number(from["row"]);
+    const col = Number(from["col"]);
+    if (!Number.isFinite(row) || !Number.isFinite(col))
+        return null;
+    // <xdr:pic> → "pic"; shapes/charts lack this element → skip
+    const pic = anchor["pic"];
+    if (!pic)
+        return null;
+    // <xdr:blipFill> → "blipFill" → <a:blip> → "blip"
+    const blipFill = pic["blipFill"];
+    const blip = blipFill?.["blip"];
+    if (!blip)
+        return null;
+    // removeNSPrefix strips namespace prefixes from attributes too:
+    // r:embed → @_embed, r:link → @_link
+    const rId = blip["@_embed"] ??
+        blip["@_link"];
+    if (!rId)
+        return null;
+    return { row, col, rId };
+}
+/**
+ * Build rId → zip-internal image path from the drawing's .rels file.
+ *
+ * rels path: "xl/drawings/_rels/drawingN.xml.rels"
+ * Target is relative to drawingDir ("xl/drawings/"), e.g. "media/image1.png"
+ * → resolved zip path: "xl/drawings/media/image1.png"
+ */
+async function buildRelsMap(zip, drawingPath) {
+    const parts = drawingPath.split("/");
+    const filename = parts[parts.length - 1];
+    const drawingDir = parts.slice(0, -1).join("/");
+    const relsPath = `${drawingDir}/_rels/${filename}.rels`;
+    const relsXml = (await zip.file(relsPath)?.async("string")) ?? null;
+    if (!relsXml) {
+        console.warn(`[drawing] rels not found: ${relsPath}`);
+        return new Map();
+    }
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        isArray: (name) => name === "Relationship",
+    });
+    const doc = parser.parse(relsXml);
+    const relationships = doc?.Relationships?.Relationship ?? [];
+    const map = new Map();
+    for (const rel of relationships) {
+        const r = rel;
+        const id = r["@_Id"];
+        const target = r["@_Target"]; // e.g. "media/image1.png", relative to drawingDir
+        if (id && target) {
+            map.set(id, `${drawingDir}/${target}`);
+        }
+    }
+    return map;
+}

package/dist/xlsx/metadata.js

@@ -0,0 +1,34 @@
+// src/xlsx/metadata.ts
+// Phase 1: Extract tab names from a downloaded .xlsx file.
+// Phase 2 will add cell/merge/image parsing via --tab.
+import JSZip from "jszip";
+import { XMLParser } from "fast-xml-parser";
+import { readFile } from "node:fs/promises";
+/**
+ * Extract metadata from a downloaded xlsx file.
+ * Phase 1 scope: tab names from xl/workbook.xml only — no cell parsing.
+ *
+ * @param filePath  Absolute path to the xlsx file
+ * @param fileName  Original file name (with extension), used to derive title
+ */
+export async function extractXlsxMetadata(filePath, fileName) {
+    const buffer = await readFile(filePath);
+    const zip = await JSZip.loadAsync(buffer);
+    const workbookXml = await zip.file("xl/workbook.xml")?.async("string");
+    if (!workbookXml) {
+        throw new Error("xl/workbook.xml not found in xlsx archive");
+    }
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        parseAttributeValue: false,
+        // Ensure single-sheet files still produce an array (not a bare object)
+        isArray: (name) => name === "sheet",
+    });
+    const parsed = parser.parse(workbookXml);
+    // workbook > sheets > sheet[]
+    const sheets = parsed?.workbook?.sheets?.sheet ?? [];
+    const tabs = sheets.map((s) => ({ name: s["@_name"] ?? "" }));
+    const title = fileName.replace(/\.xlsx$/i, "");
+    return { type: "sheet", title, file: filePath, tabs };
+}

package/dist/xlsx/parse-tab.js

@@ -0,0 +1,124 @@
+// src/xlsx/parse-tab.ts
+// Phase 2 (02-06): Assemble a complete TabOutput from one xlsx tab.
+// Orchestrates: openXlsx → parseWorkbook → parseSharedStrings →
+//               buildStylesLookup → parseSheet → parseDrawing → merge.
+import path from "node:path";
+import { openXlsx } from "./unzip.js";
+import { parseWorkbook } from "./workbook.js";
+import { parseSharedStrings } from "./shared-strings.js";
+import { buildStylesLookup } from "./styles.js";
+import { parseSheet } from "./sheet.js";
+import { parseDrawing } from "./drawing.js";
+/**
+ * Parse a single named tab from an xlsx file.
+ *
+ * @param xlsxPath  Absolute path to the xlsx file.
+ * @param tabName   Tab name (exact, case-sensitive).
+ * @param saveDir   Directory where extracted images are written (saveDir/media/).
+ */
+export async function parseTab(xlsxPath, tabName, saveDir) {
+    // Step 1: open zip
+    const zip = await openXlsx(xlsxPath);
+    // Step 2: locate tab
+    const workbookInfo = await parseWorkbook(zip);
+    const tab = workbookInfo.tabs.find((t) => t.name === tabName);
+    if (!tab) {
+        const names = workbookInfo.tabs.map((t) => t.name).join(", ");
+        throw new Error(`Tab "${tabName}" not found. Available tabs: ${names}`);
+    }
+    // sheetPath is xl-relative, e.g. "worksheets/sheet10.xml"
+    const xlSheetPath = `xl/${tab.sheetPath}`; // "xl/worksheets/sheet10.xml"
+    // Step 3: parallel load of shared strings + styles
+    const [sharedStringsXml, stylesXml, sheetXml] = await Promise.all([
+        zip.readEntry("xl/sharedStrings.xml"),
+        zip.readEntry("xl/styles.xml"),
+        zip.readEntry(xlSheetPath),
+    ]);
+    if (!sheetXml) {
+        throw new Error(`Sheet XML not found in zip: ${xlSheetPath}`);
+    }
+    const sharedStrings = sharedStringsXml
+        ? parseSharedStrings(sharedStringsXml)
+        : [];
+    const getFormatCode = buildStylesLookup(stylesXml ?? "");
+    // Step 4: parse sheet cells + merges
+    const sheetData = parseSheet(sheetXml, sharedStrings, getFormatCode);
+    // Step 5: resolve drawing rels
+    const sheetDir = path.posix.dirname(xlSheetPath); // "xl/worksheets"
+    const sheetFile = path.posix.basename(xlSheetPath); // "sheet10.xml"
+    const sheetRelsPath = `${sheetDir}/_rels/${sheetFile}.rels`;
+    let drawingImages = [];
+    const relsXml = await zip.readEntry(sheetRelsPath);
+    if (relsXml) {
+        const drawingTarget = extractDrawingTarget(relsXml);
+        if (drawingTarget) {
+            // Resolve target relative to sheetDir
+            const drawingZipPath = path.posix.normalize(path.posix.join(sheetDir, drawingTarget));
+            // Step 6: extract images
+            drawingImages = await parseDrawing(zip.rawJSZip, drawingZipPath, saveDir);
+        }
+    }
+    const cellKey = (row, col) => `${row}:${col}`;
+    const cellMap = new Map();
+    for (const c of sheetData.cells) {
+        const cell = { row: c.row, col: c.col };
+        if (c.text !== undefined)
+            cell.text = c.text;
+        if (c.value !== undefined)
+            cell.value = c.value;
+        if (c.format !== undefined)
+            cell.format = c.format;
+        cellMap.set(cellKey(c.row, c.col), cell);
+    }
+    // Step 7b: merge images into cells
+    for (const img of drawingImages) {
+        const key = cellKey(img.row, img.col);
+        const existing = cellMap.get(key);
+        if (existing) {
+            // Only set image if not already set (keep first anchor order)
+            if (!existing.image) {
+                existing.image = { path: img.path };
+            }
+        }
+        else {
+            cellMap.set(key, { row: img.row, col: img.col, image: { path: img.path } });
+        }
+    }
+    // Step 7c: compute maxRow / maxCol
+    let maxRow = 0;
+    let maxCol = 0;
+    for (const cell of cellMap.values()) {
+        if (cell.row > maxRow)
+            maxRow = cell.row;
+        if (cell.col > maxCol)
+            maxCol = cell.col;
+    }
+    for (const m of sheetData.merges) {
+        if (m.endRow > maxRow)
+            maxRow = m.endRow;
+        if (m.endCol > maxCol)
+            maxCol = m.endCol;
+    }
+    // Step 7d: sort cells row-asc, col-asc
+    const cells = Array.from(cellMap.values()).sort((a, b) => a.row !== b.row ? a.row - b.row : a.col - b.col);
+    return {
+        tab: tabName,
+        maxRow,
+        maxCol,
+        cells,
+        merges: sheetData.merges,
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract the drawing Target from a sheet rels XML string.
+ * Returns undefined when no drawing relationship exists.
+ */
+function extractDrawingTarget(relsXml) {
+    // Fast path: regex is sufficient and avoids a full XML parse dependency here.
+    // Matches: Type="...../drawing" Target="<value>"
+    const match = relsXml.match(/Type="[^"]*\/drawing"\s[^>]*Target="([^"]+)"/) ?? relsXml.match(/Target="([^"]+)"[^>]*Type="[^"]*\/drawing"/);
+    return match?.[1];
+}