refactor(converter): split the 1130-line converter by what it knows about

document-converter.ts held four unrelated bodies of knowledge around one
class. Each moves to its own file; the class keeps the orchestration and
the package's public surface is unchanged (everything moved is
re-exported from where it was).

  x2t-loading.ts   canStreamWasm, fetchWasmResponse with its retry, and the
                   instantiate error whose `X2T module` prefix a host's
                   open-failure handling matches on. The twin of the vendor
                   loader, so it is the piece most likely to be read next to
                   public/sdkjs/common/wasm/x2t/x2t_helper.js.
  pdf-fonts.ts     the manifest, the XOR key, and writing the faces into the
                   module FS. One of three places that hard-code catalog slot
                   numbers, and now the one where that is stated.
  spreadsheet.ts   SheetJS: CSV in both directions and the HTML table wearing
                   a .xls extension, neither of which x2t can read.
  file-meta.ts     signatures, media types, save-dialog descriptions,
                   saveFileToDisk.

1130 -> 826 lines.

Two tests reached into the class for `PDF_FONT_MANIFEST` and
`decodeCatalogFont` through `as any` on a private static. They import
them now, which is what they wanted in the first place.

`--deny-warnings` earned its keep twice here, on imports that stopped
being used as the code moved out from under them.

Verified: 3423 unit tests, the conversion-heavy E2E specs (CSV, GBK CSV,
HTML-as-xls, ODF round trips, CJK PDF export, the embed regression), and
the full suite at 165.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MKNHFQ1kek1cHeqhbH37Pk

Author: chaxus

CLAUDE.md

@@ -105,7 +105,14 @@ packages/             # pnpm workspace，供 ran 生态三处站点共享（包
                           # 七张表都是完整的（编辑器 UI 语言另由 vendor 45 语言包提供）。
                           # 2026-09-12 从 1263 行的单文件拆开：加一条文案是改七个文件而
                           # 不是同一个文件的七处，加一种语言就是加一个文件
-  converter/            # 格式转换：CSV↔XLSX（SheetJS）、docx-zip 媒体处理、签名嗅探、PDF 字体清单
+  converter/            # 格式转换（2026-09-12 从 1130 行的单文件拆开，公开导出面不变）
+    document-converter.ts # X2TConverter 本体：加载、转换、媒体、退出码分类
+    x2t-loading.ts        # canStreamWasm / fetchWasmResponse（含重试）/ x2tInstantiateError
+                          # ——与 vendor 里的 `x2t_helper.js` 是语义必须一致的孪生
+    pdf-fonts.ts          # `PDF_FONT_MANIFEST` + XOR 解码 + 写进 FS（槽位号三处联动之一）
+    spreadsheet.ts        # SheetJS：CSV↔XLSX、HTML 表格伪装成 .xls
+    file-meta.ts          # 签名嗅探 / MIME / 另存描述 / saveFileToDisk
+    docx-zip.ts           # OOXML zip 媒体提取与预处理
   agent-core/           # LLM 运行时 + 多 Provider（anthropic/openai/gemini/ollama/webllm）+ key 存储
   chat-ui/              # 聊天面板 UI
 types/

packages/converter/src/document-converter.ts

@@ -0,0 +1,76 @@
+import { isHtmlDocument, isZipContainer, saveFileToDisk as ranutsSaveFileToDisk } from 'ranuts/utils';
+import 'ranui/message';
+import { t } from '@ranuts/shared/i18n';
+import { getDocumentMimeType } from '@ranuts/shared/document-utils';
+
+/**
+ * What a file is, and how it leaves the browser.
+ *
+ * Signatures, media types and the descriptions a save dialog shows -- the
+ * facts about a document that the converter needs but that have nothing to do
+ * with running x2t.
+ */
+// Serialized editor documents start with a 4-byte engine signature.
+const EDITOR_BIN_SIGNATURES = new Set(['DOCY', 'XLSY', 'PPTY', 'VSDY']);
+
+export function hasEditorBinSignature(bin: Uint8Array): boolean {
+  if (bin.length < 4) return false;
+  return EDITOR_BIN_SIGNATURES.has(String.fromCharCode(bin[0]!, bin[1]!, bin[2]!, bin[3]!));
+}
+
+// Byte sniffing lives in ranuts (ecosystem first): a ZIP container is what the
+// v9 engine's offline save trigger emits instead of an editor bin, and the HTML
+// sniff catches "this .xls is really an HTML <table>", which the bundled
+// x2t.wasm cannot import at all (its HTML importer is stubbed out).
+export { isHtmlDocument, isZipContainer };
+
+const FILE_DESCRIPTION_MAP: Record<string, string> = {
+  docx: 'Word Document',
+  doc: 'Word 97-2003 Document',
+  odt: 'OpenDocument Text',
+  pdf: 'PDF Document',
+  xlsx: 'Excel Workbook',
+  xls: 'Excel 97-2003 Workbook',
+  ods: 'OpenDocument Spreadsheet',
+  pptx: 'PowerPoint Presentation',
+  ppt: 'PowerPoint 97-2003 Presentation',
+  odp: 'OpenDocument Presentation',
+  txt: 'Text Document',
+  rtf: 'Rich Text Format',
+  csv: 'CSV File',
+};
+
+/**
+ * Save a finished file to the user's disk. Adapter over ranuts'
+ * `saveFileToDisk` (File System Access API with an anchor fallback): this
+ * build adds the document-flavoured type description the picker shows and the
+ * ranui success toast. A dismissed dialog resolves without a toast; any other
+ * failure rejects so the caller can surface it. Shared by the convert-and-
+ * download path and the v9 file-stream save path (lib/onlyoffice-editor.ts).
+ */
+export async function saveFileToDisk(data: Blob | Uint8Array, fileName: string, mimeType?: string): Promise<void> {
+  const extension = fileName.split('.').pop()?.toLowerCase() || '';
+  const written = await ranutsSaveFileToDisk(data, fileName, {
+    mimeType: mimeType || getDocumentMimeType(fileName),
+    description: FILE_DESCRIPTION_MAP[extension] || 'Document',
+  });
+  if (!written) return;
+  // ranui/message registers a global `window.message` toast API (untyped).
+  (window as unknown as { message?: { success?: (msg: string) => void } }).message?.success?.(
+    `${t('fileSavedSuccess')}${fileName}`,
+  );
+}
+
+export const MIME_MAP: Record<string, string> = {
+  gif: 'image/gif',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  svg: 'image/svg+xml',
+  webp: 'image/webp',
+  bmp: 'image/bmp',
+  tiff: 'image/tiff',
+  tif: 'image/tiff',
+  emf: 'image/x-emf',
+  wmf: 'image/x-wmf',
+};

packages/converter/src/file-meta.ts

@@ -8,6 +8,8 @@
 export {
   X2TConverter,
   canStreamWasm,
+  decodeCatalogFont,
+  PDF_FONT_MANIFEST,
   fetchWasmResponse,
   hasEditorBinSignature,
   isHtmlDocument,

packages/converter/src/index.ts

@@ -0,0 +1,107 @@
+import { BASE_PATH } from '@ranuts/shared/document-utils';
+import type { EmscriptenModule } from '@ranuts/shared/document-types';
+
+/**
+ * The fonts an exported PDF needs, and where they come from.
+ *
+ * Without them x2t writes a PDF whose text is invisible. They are read from
+ * the indexed catalog (public/fonts/{index}) -- the same files the editor
+ * loads, so they are usually already in the HTTP cache -- and de-obfuscated
+ * before being written under the alias names x2t matches against.
+ *
+ * The slot numbers here are one of three places in the repository that hard-code
+ * them (the others are public/landing-prefetch.js and
+ * test/e2e/landing-prefetch.spec.ts). Changing the catalog means changing all
+ * three; test/unit/font-catalog-licensing.test.ts checks this one against what
+ * is actually on disk.
+ */
+
+/** Same 16-byte key bin/font-catalog.mjs and the vendor's fetchFonts use. */
+const CATALOG_FONT_XOR_KEY = [160, 102, 214, 32, 20, 150, 71, 250, 149, 105, 184, 80, 176, 65, 73, 72];
+
+/**
+ * PDF-export font manifest: catalog file index -> alias file names x2t
+ * matches against inside m_sFontDir. One decoded byte set is written once
+ * per alias. Indexes come from __fonts_infos in public/sdkjs/common/
+ * AllFonts.js (file position, then __fonts_files lookup). Keep Arial and
+ * other western families on their own files -- aliasing them to the CJK
+ * fallback garbles latin text and digits. The CJK alias entries carry the
+ * literal zh font names documents reference; they are data, not UI copy.
+ */
+export const PDF_FONT_MANIFEST: ReadonlyArray<{ file: string; aliases: string[] }> = [
+  // The aliases are the names x2t looks for; the slot behind each one is an
+  // open-licensed face after bin/font-license-sweep.mjs (the proprietary
+  // originals are no longer in the catalog). Liberation and Carlito are
+  // metric-compatible with the names they answer to, so an exported PDF
+  // keeps the same line and page breaks.
+  { file: '062', aliases: ['Arial.ttf', 'LiberationSans-Regular.ttf'] },
+  { file: '059', aliases: ['Arial_Bold.ttf'] },
+  { file: '061', aliases: ['Arial_Italic.ttf'] },
+  { file: '060', aliases: ['Arial_Bold_Italic.ttf'] },
+  { file: '112', aliases: ['Calibri.ttf', 'Carlito.ttf'] },
+  { file: '109', aliases: ['Calibri_Bold.ttf', 'Carlito_Bold.ttf'] },
+  { file: '111', aliases: ['Calibri_Italic.ttf', 'Carlito_Italic.ttf'] },
+  { file: '110', aliases: ['Calibri_Bold_Italic.ttf', 'Carlito_Bold_Italic.ttf'] },
+  { file: '070', aliases: ['Times_New_Roman.ttf', 'Times New Roman.ttf'] },
+  { file: '067', aliases: ['Times_New_Roman_Bold.ttf'] },
+  { file: '069', aliases: ['Times_New_Roman_Italic.ttf'] },
+  { file: '068', aliases: ['Times_New_Roman_Bold_Italic.ttf'] },
+  { file: '058', aliases: ['Courier_New.ttf', 'Courier New.ttf'] },
+  // Names the previous implementation fetched directly (kept for the same
+  // default-latin coverage).
+  { file: '117', aliases: ['DejaVuSans.ttf'] },
+  { file: '050', aliases: ['DejaVuSans-Bold.ttf'] },
+  // CJK. Serif answers to the Song/Ming names a document's body text uses,
+  // sans to the Hei/YaHei names; PingFang maps to the sans as the closest
+  // match. Both are TrueType on purpose: x2t embeds no glyphs at all for
+  // CFF-flavoured faces, so a pan-CJK OTF here exports a PDF whose Chinese
+  // is blank while its Latin survives (measured both ways round).
+  { file: '269', aliases: ['SimSun.ttf', 'NSimSun.ttf', '宋体.ttf', 'NotoSerifSC-Regular.ttf'] },
+  { file: '270', aliases: ['SimSun_Bold.ttf'] },
+  {
+    file: '267',
+    aliases: [
+      'Microsoft YaHei.ttf',
+      '微软雅黑.ttf',
+      'PingFang SC.ttf',
+      'SimHei.ttf',
+      '黑体.ttf',
+      'DroidSansFallback.ttf',
+      'Droid Sans Fallback.ttf',
+      'NotoSansSC-Regular.ttf',
+    ],
+  },
+  { file: '268', aliases: ['Microsoft YaHei_Bold.ttf', 'SimHei_Bold.ttf'] },
+];
+
+/** Undo the catalog XOR obfuscation, returning a plain TTF byte copy. */
+export function decodeCatalogFont(bytes: Uint8Array): Uint8Array {
+  const out = new Uint8Array(bytes);
+  const n = Math.min(32, out.length);
+  for (let i = 0; i < n; i++) {
+    out[i] ^= CATALOG_FONT_XOR_KEY[i % CATALOG_FONT_XOR_KEY.length]!;
+  }
+  return out;
+}
+
+/**
+ * Write every manifest face into the module's FS, once per session. A face
+ * that cannot be fetched is skipped rather than failing the export: the PDF
+ * still renders with the ones that arrived.
+ */
+export async function loadFontsForPdf(module: EmscriptenModule): Promise<void> {
+  await Promise.all(
+    PDF_FONT_MANIFEST.map(async ({ file, aliases }) => {
+      try {
+        const res = await fetch(`${BASE_PATH}fonts/${file}`);
+        if (!res.ok) return;
+        const bytes = decodeCatalogFont(new Uint8Array(await res.arrayBuffer()));
+        for (const alias of aliases) {
+          module.FS.writeFile(`/working/fonts/${alias}`, bytes);
+        }
+      } catch {
+        // Non-fatal -- the PDF may still render with the remaining fonts.
+      }
+    }),
+  );
+}

packages/converter/src/pdf-fonts.ts

@@ -0,0 +1,75 @@
+import { decodeTextBytes } from 'ranuts/utils';
+import { BASE_PATH } from '@ranuts/shared/document-utils';
+
+/**
+ * The spreadsheet shapes x2t cannot read, handled by SheetJS instead.
+ *
+ * Two of them: CSV, which the v9 engine will not open at all (it is converted
+ * to XLSX on the way in and back to CSV on the way out), and the "HTML table
+ * saved with a .xls extension" that web systems export, which x2t cannot
+ * import either -- its HTML importer is stubbed out.
+ *
+ * Both decode through `decodeTextBytes`: a non-fatal utf-8 TextDecoder never
+ * throws (invalid sequences become U+FFFD), so strict decoding is the only way
+ * to detect a legacy encoding at all. Excel on zh-CN Windows still exports CSV
+ * in the ANSI code page, which is why gb18030 is tried before latin1.
+ */
+
+const XLSX_MIME = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+
+/**
+ * SheetJS, loaded on demand and shared by the page.
+ *
+ * Cached on `window` rather than per converter: it is a global the script tag
+ * defines, and a second converter would otherwise append a second tag for a
+ * library that is already there.
+ */
+export async function loadXlsxLibrary(): Promise<any> {
+  if (typeof window !== 'undefined' && (window as any).XLSX) return (window as any).XLSX;
+
+  return new Promise((resolve, reject) => {
+    const script = document.createElement('script');
+    script.src = `${BASE_PATH}libs/sheetjs/xlsx.full.min.js`;
+    script.onload = () => {
+      if (typeof window !== 'undefined' && (window as any).XLSX) resolve((window as any).XLSX);
+      else reject(new Error('Failed to load xlsx library'));
+    };
+    script.onerror = () => reject(new Error('Failed to load xlsx library from local file'));
+    document.head.appendChild(script);
+  });
+}
+
+/** CSV in, a real XLSX File out, because the engine will not read CSV. */
+export async function convertCsvToXlsx(csvData: Uint8Array, fileName: string): Promise<File> {
+  try {
+    const XLSX = await loadXlsxLibrary();
+    const workbook = XLSX.read(decodeTextBytes(csvData), { type: 'string', raw: false });
+    const xlsxBuffer = XLSX.write(workbook, { type: 'array', bookType: 'xlsx' });
+    return new File([xlsxBuffer], fileName.replace(/\.csv$/i, '.xlsx'), { type: XLSX_MIME });
+  } catch (error) {
+    throw new Error(
+      `Failed to convert CSV to XLSX: ${error instanceof Error ? error.message : 'Unknown error'}. ` +
+        'Please convert your CSV file to XLSX format manually and try again.',
+    );
+  }
+}
+
+/**
+ * An HTML-table document masquerading as a spreadsheet (.xls/.xlsx exports
+ * from web systems) into a real XLSX. SheetJS parses `<table>` markup
+ * natively; x2t cannot import it at all.
+ */
+export async function convertHtmlTableToXlsx(htmlData: Uint8Array, fileName: string): Promise<File> {
+  try {
+    const XLSX = await loadXlsxLibrary();
+    const workbook = XLSX.read(decodeTextBytes(htmlData), { type: 'string', raw: false });
+    if (!workbook.SheetNames || workbook.SheetNames.length === 0) throw new Error('no table found');
+    const xlsxBuffer = XLSX.write(workbook, { type: 'array', bookType: 'xlsx' });
+    return new File([xlsxBuffer], fileName.replace(/\.[^.]+$/, '') + '.xlsx', { type: XLSX_MIME });
+  } catch (error) {
+    throw new Error(
+      `Failed to convert HTML table to XLSX: ${error instanceof Error ? error.message : 'Unknown error'}. ` +
+        'The file is an HTML page saved with a spreadsheet extension; open it in a spreadsheet application and save it as XLSX.',
+    );
+  }
+}

packages/converter/src/spreadsheet.ts

@@ -0,0 +1,83 @@
+/**
+ * Getting the x2t module into the engine, and saying so when that fails.
+ *
+ * Kept in step with `fetchWasmResponse` in the vendor-side loader
+ * (public/sdkjs/common/wasm/x2t/x2t_helper.js): the site's editor frame runs
+ * that copy, this one serves consumers of the package that load x2t on the
+ * page itself. test/unit/x2t-helper-loading.test.ts and
+ * test/unit/converter-wasm-loading.test.ts drive the two against the real
+ * files, separately, for that reason.
+ */
+/**
+ * Whether the module can be compiled straight off the network, without the
+ * decompressed 42 MB ever existing as one buffer. Checked up front so a
+ * failure of the streaming path itself is never retried through the buffered
+ * one (see installStreamingInstantiate).
+ */
+export const canStreamWasm = (): boolean =>
+  typeof WebAssembly !== 'undefined' && typeof WebAssembly.instantiateStreaming === 'function';
+
+/** Total tries for the x2t WASM fetch, and the step of the linear backoff. */
+const WASM_FETCH_ATTEMPTS = 3;
+const WASM_FETCH_BACKOFF_MS = 500;
+
+/**
+ * Whether a status means "the server failed", as opposed to "the file is not
+ * there". Only the first is worth asking again.
+ */
+const isTransientStatus = (status: number): boolean => status >= 500 || status === 408 || status === 429;
+
+const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Fetch the x2t WASM, asking again when the answer was transient.
+ *
+ * This is a 9.4 MB asset off a CDN and one bad answer to it costs the whole
+ * open: Cloudflare Pages served a 500 for exactly this file mid-run on
+ * 2026-08-20 (PR #159) and the editor reported the document as unopenable. The
+ * recovery a host has above this -- rebuilding the whole editor and re-fetching
+ * everything -- is far more expensive than asking twice more, and in that run
+ * it landed in the same bad window.
+ *
+ * Retried only when the server says it failed (5xx / 408 / 429) or the fetch
+ * itself rejected (a dropped connection, an offline moment); a 404 or a 403 is
+ * a deployment fact, and retrying only delays the error the user has to see.
+ * Nothing is retained between attempts, so this adds nothing to the peak the
+ * streaming path exists to keep down.
+ *
+ * Kept in step with `fetchWasmResponse` in the vendor-side loader
+ * (public/sdkjs/common/wasm/x2t/x2t_helper.js).
+ */
+export async function fetchWasmResponse(wasmPath: string): Promise<Response> {
+  for (let attempt = 1; ; attempt += 1) {
+    let response: Response;
+    try {
+      response = await fetch(wasmPath);
+    } catch (error) {
+      if (attempt >= WASM_FETCH_ATTEMPTS) throw error;
+      console.warn('[x2t] retrying the WASM fetch after', error);
+      await wait(WASM_FETCH_BACKOFF_MS * attempt);
+      continue;
+    }
+    if (response.ok) return response;
+    const failure = new Error(`Failed to fetch x2t WASM at '${wasmPath}' (${response.status})`);
+    if (attempt >= WASM_FETCH_ATTEMPTS || !isTransientStatus(response.status)) throw failure;
+    console.warn('[x2t] retrying the WASM fetch after', failure.message);
+    await wait(WASM_FETCH_BACKOFF_MS * attempt);
+  }
+}
+
+/**
+ * The error a failed streaming instantiation reports.
+ *
+ * The `X2T module` prefix is the entry condition a host's open-failure
+ * handling matches on (the site's own guard is
+ * lib/onlyoffice/open-failure.ts); the original wording is kept after it
+ * because that is what the same host reads to tell a refused wasm heap from a
+ * dropped download. Without the prefix nothing claims the failure at all:
+ * `loadScript()` has already resolved by the time the hook runs, emscripten's
+ * success callback is simply never called, and the user watches a spinner
+ * until the init timeout fires.
+ */
+export const x2tInstantiateError = (error: unknown): Error =>
+  new Error(`X2T module failed to instantiate: ${error instanceof Error ? error.message : String(error)}`);

packages/converter/src/x2t-loading.ts

@@ -3,7 +3,9 @@ import {
   CANVAS_PDF_INPUT_FORMAT,
   X2TConverter,
   hasEditorBinSignature,
+  decodeCatalogFont,
   isHtmlDocument,
+  PDF_FONT_MANIFEST,
   isZipContainer,
 } from '@ranuts/converter';
 
@@ -144,7 +146,7 @@ describe('X2TConverter', () => {
     it('decodeCatalogFont restores the TTF magic and leaves bytes past 32 untouched', () => {
       const { plain, wire } = makeCatalogBytes();
 
-      const decoded = (new X2TConverter() as any).decodeCatalogFont(wire) as Uint8Array;
+      const decoded = decodeCatalogFont(wire);
 
       expect(Array.from(decoded)).toEqual(Array.from(plain));
       // Input is not mutated (decode returns a copy).
@@ -189,7 +191,7 @@ describe('X2TConverter', () => {
     it('is non-fatal when a font fetch fails: remaining fonts still load', async () => {
       const { wire } = makeCatalogBytes();
       // Fail whichever slot happens to back Arial, without naming it.
-      const manifest = (X2TConverter as any).PDF_FONT_MANIFEST as { file: string; aliases: string[] }[];
+      const manifest = PDF_FONT_MANIFEST;
       const arialSlot = manifest.find((entry) => entry.aliases.includes('Arial.ttf'))!.file;
       const fetchMock = vi.fn().mockImplementation(async (url: string) => {
         if (String(url).endsWith(`fonts/${arialSlot}`)) throw new Error('network down');