claude-token-saver 3.27.0 → 3.28.0

package/src/doc2md.cjs

@@ -27,13 +27,16 @@ const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
+const ledger = require('./doc2md-ledger.cjs');
 
 // Formats where the original is of no use to the model. Images are absent
 // deliberately: markitdown returns nothing for them, and OCR misread resource
 // names in testing (`c5.xlarge` as `c.xlarge`), which is worse than no text at
 // all in a document where those names are the content. The model reads images
 // natively anyway.
-const TARGET_EXTENSIONS = ['.pptx', '.xlsx', '.xls', '.pdf', '.docx'];
+// `.fig` converts through openfig-core in Node rather than markitdown; see
+// fig2md.cjs for why it cannot go through the Python path.
+const TARGET_EXTENSIONS = ['.pptx', '.xlsx', '.xls', '.pdf', '.docx', '.fig'];
 
 // Big enough for real decks and reports, small enough that a hostile file
 // cannot make the converter the expensive part of the turn.
@@ -107,7 +110,13 @@ function isSensitivePath(filePath) {
 function cachePathFor(filePath) {
   const abs = path.resolve(filePath);
   const hash = crypto.createHash('sha256').update(abs).digest('hex').slice(0, 12);
-  const base = path.basename(abs).replace(/[^\w.\-]/g, '_');
+  // Keep letters and digits of any script, so a Korean or Japanese file name
+  // stays readable in the cache directory instead of collapsing into a row of
+  // underscores. Only characters that are awkward in a path are replaced.
+  const base = path.basename(abs)
+    .replace(/[^\p{L}\p{N}._-]/gu, '_')
+    .replace(/_{2,}/g, '_')
+    .slice(0, 80);
   return path.join(cacheDir(), `${base}.${hash}.md`);
 }
 
@@ -129,16 +138,81 @@ function readCache(filePath) {
   }
 }
 
+/** `31854740` → `30.4MB`, for the banner and the hook's one-line summary. */
+function humanBytes(n) {
+  const bytes = Number(n) || 0;
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/**
+ * The header stamped onto every conversion.
+ *
+ * Without it a conversion is an anonymous .md in a directory nobody opened on
+ * purpose, and the reader has no way to tell that this tool produced it, from
+ * what, or when. Four lines of provenance answer all of that at the top of the
+ * file the model is about to read, and cost about 60 tokens.
+ */
+function banner(sourcePath, saving) {
+  const src = fs.statSync(sourcePath);
+  const lines = [
+    '<!--',
+    'claude-token-saver doc2md 가 변환한 파일입니다. 직접 편집하지 마십시오.',
+    `원본: ${path.resolve(sourcePath)} (${humanBytes(src.size)})`,
+    `변환: ${new Date().toISOString()} · Markdown ${humanBytes(Buffer.byteLength(saving.markdown, 'utf8'))} · 약 ${saving.tokens.toLocaleString('en-US')} 토큰`,
+  ];
+  if (saving.usd > 0) {
+    const savedTokens = Math.max(0, saving.baseline - saving.tokens);
+    // The alternative differs by format, so the sentence names it: a PDF
+    // would have been attached, a zip document would have been unpacked.
+    const alternative = path.extname(sourcePath).toLowerCase() === '.pdf'
+      ? '원본을 첨부하면'
+      : '압축을 풀어 본문 XML을 읽으면';
+    lines.push(
+      `${alternative} 약 ${saving.baseline.toLocaleString('en-US')} 토큰이 드는데, `
+      + `변환본은 ${saving.tokens.toLocaleString('en-US')} 토큰입니다. `
+      + `약 ${savedTokens.toLocaleString('en-US')} 토큰, $${saving.usd.toFixed(2)} 을 아꼈습니다(추정).`,
+    );
+  }
+  lines.push('-->', '');
+  return lines.join('\n');
+}
+
 function writeCache(filePath, markdown, extra) {
   ensureCacheDir();
   const cacheFile = cachePathFor(filePath);
   const src = fs.statSync(filePath);
-  fs.writeFileSync(cacheFile, markdown, { encoding: 'utf8', mode: 0o600 });
+  const ext = path.extname(filePath).toLowerCase();
+  const saving = Object.assign(
+    ledger.estimateSaving({
+      ext,
+      pages: (extra && extra.pages) || 0,
+      markupBytes: (extra && extra.markupBytes) || 0,
+      markdown,
+    }),
+    { markdown },
+  );
+  fs.writeFileSync(cacheFile, banner(filePath, saving) + markdown, { encoding: 'utf8', mode: 0o600 });
+  ledger.recordConversion(userDataDir(), {
+    key: path.resolve(filePath),
+    ts: Date.now(),
+    usd: saving.usd,
+    ext,
+    tokens: saving.tokens,
+    baseline: saving.baseline,
+  });
   const meta = Object.assign({
     source: path.resolve(filePath),
     size: src.size,
     mtimeMs: src.mtimeMs,
     convertedAt: new Date().toISOString(),
+    // Carried in the metadata so the hook can report what the conversion cost
+    // and saved without re-reading and re-measuring the markdown.
+    markdownBytes: Buffer.byteLength(markdown, 'utf8'),
+    tokens: saving.tokens,
+    baselineTokens: saving.baseline,
+    savedUsd: saving.usd,
   }, extra || {});
   fs.writeFileSync(metaPathFor(cacheFile), JSON.stringify(meta, null, 2), { encoding: 'utf8', mode: 0o600 });
   return { cacheFile, meta };
@@ -193,6 +267,12 @@ function managedPython() {
 
 const MARKITDOWN_SPEC = 'markitdown[pptx,pdf,xlsx,docx]';
 
+// Editing libraries, installed alongside the converter. Reading is doc2md's
+// own job; editing is the agent's, done per-request with a short script
+// against a COPY of the document. These are the libraries those scripts need,
+// pre-installed so "swap the chart on slide 23" does not stall on pip.
+const EDIT_LIBS = ['python-pptx', 'python-docx', 'openpyxl'];
+
 /**
  * Build the managed venv and install markitdown into it.
  *
@@ -217,8 +297,8 @@ function installConverter({ onProgress = () => {} } = {}) {
     }
   }
 
-  onProgress(`installing ${MARKITDOWN_SPEC}`);
-  const install = spawnSync(target, ['-m', 'pip', 'install', '--quiet', MARKITDOWN_SPEC], {
+  onProgress(`installing ${MARKITDOWN_SPEC} + ${EDIT_LIBS.join(', ')}`);
+  const install = spawnSync(target, ['-m', 'pip', 'install', '--quiet', MARKITDOWN_SPEC, ...EDIT_LIBS], {
     encoding: 'utf8',
     timeout: 900_000,
   });
@@ -246,6 +326,30 @@ function installConverter({ onProgress = () => {} } = {}) {
  * Every failure is a reason to leave the original Read alone, never to break
  * it. That is the whole contract with the hook.
  */
+/**
+ * Bridge from this synchronous pipeline to the async fig converter: run it in
+ * a child process and read one JSON object from stdout, exactly the contract
+ * the Python converter already speaks. Costs a process spawn, buys the same
+ * timeout and isolation the other formats get.
+ */
+function spawnFigConvert(fig2md, filePath) {
+  const runner = path.join(__dirname, 'fig2md-runner.cjs');
+  const run = spawnSync(process.execPath, [runner, filePath, userDataDir()], {
+    encoding: 'utf8',
+    timeout: CONVERT_TIMEOUT_MS,
+    maxBuffer: MAX_MARKDOWN_BYTES * 4,
+  });
+  if (run.error && run.error.code === 'ETIMEDOUT') return { ok: false, reason: 'timeout' };
+  if (run.status !== 0) {
+    return { ok: false, reason: 'convert-failed', detail: (run.stderr || '').slice(0, 300) };
+  }
+  try {
+    return JSON.parse(run.stdout);
+  } catch {
+    return { ok: false, reason: 'convert-failed', detail: 'fig converter produced no JSON' };
+  }
+}
+
 function convert(filePath, { converter = CONVERTER, python: pythonOverride = null } = {}) {
   if (!isTargetPath(filePath)) return { ok: false, reason: 'not-target' };
   if (isSensitivePath(filePath)) return { ok: false, reason: 'sensitive' };
@@ -263,6 +367,17 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
   const cached = readCache(filePath);
   if (cached) return { ok: true, cached: true, cacheFile: cached.cacheFile, meta: cached.meta };
 
+  // Figma files take the Node converter; everything else goes to markitdown.
+  if (path.extname(filePath).toLowerCase() === '.fig') {
+    const fig2md = require('./fig2md.cjs');
+    const result = spawnFigConvert(fig2md, filePath);
+    if (!result.ok) return result;
+    const written = writeCache(filePath, result.markdown, {
+      note: result.note, truncated: false, rows: 0, pages: 0, markupBytes: 0,
+    });
+    return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
+  }
+
   // The override exists so tests can drive a stub converter with any Python at
   // all: the normal search insists the interpreter can import markitdown,
   // which would make the whole path untestable without the real package.
@@ -299,6 +414,8 @@ function convert(filePath, { converter = CONVERTER, python: pythonOverride = nul
     note: payload.note || null,
     truncated: !!payload.truncated || clipped,
     rows: payload.rows || 0,
+    pages: payload.pages || 0,
+    markupBytes: payload.markup_bytes || 0,
     clipped,
   });
   return { ok: true, cached: false, cacheFile: written.cacheFile, meta: written.meta };
@@ -449,6 +566,24 @@ function documentPathsIn(text) {
 // conversion. The rest are named in the note so nothing disappears quietly.
 const MAX_PROMPT_CONVERSIONS = 3;
 
+/**
+ * The one line that makes a conversion visible: what came in, what went out,
+ * and what not attaching the original was worth.
+ *
+ * The sizes matter more than they look. A 30MB deck that becomes 90KB of
+ * Markdown is the whole argument for this feature, and without the figures
+ * the model has nothing concrete to tell the user it happened.
+ */
+function conversionSummary(sourcePath, meta = {}) {
+  const parts = [];
+  try {
+    parts.push(`${humanBytes(fs.statSync(sourcePath).size)} → ${humanBytes(meta.markdownBytes || 0)}`);
+  } catch { /* the size is a nicety, not the point */ }
+  if (meta.tokens) parts.push(`약 ${Number(meta.tokens).toLocaleString('en-US')} 토큰`);
+  if (meta.savedUsd > 0) parts.push(`첨부 대비 약 $${Number(meta.savedUsd).toFixed(2)} 절감(추정)`);
+  return parts.join(', ');
+}
+
 /**
  * Context to inject for a UserPromptSubmit payload, or null.
  *
@@ -471,6 +606,7 @@ function contextForPrompt(payload, opts = {}) {
     const result = convert(p, opts);
     if (result.ok) {
       lines.push(`  ${name} → ${result.cacheFile}`);
+      lines.push(`      ${conversionSummary(p, result.meta)}`);
       if (result.meta && result.meta.note) lines.push(`      ${result.meta.note}`);
       if (result.meta && result.meta.clipped) {
         lines.push('      변환 결과가 너무 커서 뒷부분을 잘랐습니다. 전체가 필요하면 원본을 직접 다루십시오.');
@@ -479,6 +615,10 @@ function contextForPrompt(payload, opts = {}) {
       lines.push(lang === 'ko'
         ? `  ${name}: 변환기가 없어 변환하지 못했습니다. 설치: ${INSTALL_HINT}`
         : `  ${name}: no converter installed. Install it with: ${INSTALL_HINT}`);
+    } else if (result.reason === 'no-figparser') {
+      lines.push(lang === 'ko'
+        ? `  ${name}: .fig 파서가 없어 변환하지 못했습니다. 설치: claude-token-saver doc2md install-converter`
+        : `  ${name}: no .fig parser installed. Install it with: claude-token-saver doc2md install-converter`);
     } else if (result.reason === 'sensitive') {
       lines.push(lang === 'ko'
         ? `  ${name}: 파일명이 민감 문서 패턴에 걸려 변환하지 않았습니다.`
@@ -500,12 +640,14 @@ function contextForPrompt(payload, opts = {}) {
       '[doc2md] 이 프롬프트에 문서 경로가 있어 Markdown 으로 변환해 두었습니다.',
       ...lines,
       '원본 대신 위 변환본을 Read 하십시오. pptx·xlsx·docx 는 Read 도구가 이진 파일이라며 거부하므로 원본을 직접 열 수 없습니다.',
+    '변환이 일어났다는 사실은 사용자에게도 보여야 하므로, 답변 첫 줄에 변환한 문서마다 다음 형식으로 한 줄씩 출력하십시오: `📄 [claude-token-saver] doc2md: <파일명> (<원본 크기> → <Markdown 크기>, 약 <토큰> 토큰)`. 절감액이 함께 안내됐다면 그 금액도 같은 줄 끝에 덧붙이십시오.',
       '경로가 주어지지 않은 문서를 열어야 할 때는 `claude-token-saver doc2md <경로>` 를 실행해 변환본 경로를 얻으십시오.',
     ].join('\n')
     : [
       '[doc2md] This prompt names document paths, which have been converted to Markdown:',
       ...lines,
       'Read the conversions above rather than the originals: Read refuses pptx/xlsx/docx as binary files, so the originals cannot be opened directly.',
+    'The user cannot see that any of this happened, so open your reply with one line per converted document: `📄 [claude-token-saver] doc2md: <name> (<source size> → <markdown size>, ~<tokens> tokens)`, adding the saving above if one was reported.',
       'For a document whose path was not given here, run `claude-token-saver doc2md <path>` to get its conversion.',
     ].join('\n');
 }
@@ -523,15 +665,66 @@ function sessionNote(lang = 'en') {
       '[doc2md] 문서(pptx·xlsx·pdf·docx)를 다룰 때의 규칙입니다.',
       '  문서를 열어야 하는데 Read 가 이진 파일이라며 거부하면, `claude-token-saver doc2md <경로>` 를 실행하고 그 결과로 나온 .md 를 Read 하십시오.',
       '  사용자가 문서를 메시지에 직접 첨부했다면, 첨부는 내용 전체가 컨텍스트에 실려 토큰을 크게 씁니다. 다음부터는 첨부 대신 파일 경로를 적어 달라고 안내하십시오. 경로로 주면 변환본만 읽습니다.',
+      '  변환은 단방향입니다. 변환본 .md 를 고쳐도 원본에는 반영되지 않습니다. 문서 수정 요청을 받으면: ① 원본을 복사하고 ② 복사본을 스크립트로 수정하십시오. pptx·docx·xlsx 는 도구 venv 파이썬에 python-pptx·python-docx·openpyxl 이 준비되어 있고(`claude-token-saver doc2md` 상태 출력에 경로가 나옵니다), .fig 는 openfig-core 로 편집·재인코드합니다. ③ 수정한 복사본을 doc2md 로 재변환해 변경이 들어갔는지 검증하십시오. 차트·이미지 같은 시각 요소는 변환본에 안 잡히므로 텍스트 검증만으로 완료를 단정하지 마십시오.',
     ].join('\n');
   }
   return [
     '[doc2md] Handling documents (pptx/xlsx/pdf/docx):',
     '  If Read refuses a document as a binary file, run `claude-token-saver doc2md <path>` and Read the .md it prints.',
     '  If the user attached a document to their message, its full contents were billed into the context. Tell them that naming the file path instead is far cheaper, since only the converted Markdown gets read.',
+    '  Conversions are one-way: editing the cached .md changes nothing in the source. When asked to modify a document: ① copy the original, ② edit the COPY with a script — the managed venv python has python-pptx/python-docx/openpyxl, and .fig edits go through openfig-core — then ③ re-convert the copy with doc2md to verify the change landed. Charts and images do not appear in conversions, so text verification alone does not prove visual edits.',
   ].join('\n');
 }
 
+/**
+ * Guard for Edit/Write. Two writes are refused, for different reasons.
+ *
+ * A write to a conversion in the cache: the conversion is one-way, so an edit
+ * there changes nothing the user cares about — and worse, the cache still
+ * matches the source's mtime, so the corrupted copy would be served on every
+ * later read while looking exactly like the document. The deny explains where
+ * the work should go instead.
+ *
+ * A write to the original document: Edit and Write emit text, and a pptx or
+ * .fig overwritten with text is destroyed, not edited. Nothing this tool
+ * ships can write those formats back.
+ */
+function decideForWrite(context) {
+  if (!context || (context.tool_name !== 'Edit' && context.tool_name !== 'Write')) return null;
+  const toolInput = context.tool_input;
+  const filePath = toolInput && typeof toolInput.file_path === 'string' ? toolInput.file_path : '';
+  if (!filePath) return null;
+  const abs = path.resolve(filePath);
+
+  if (abs.startsWith(cacheDir() + path.sep)) {
+    let source = null;
+    try {
+      source = JSON.parse(fs.readFileSync(metaPathFor(abs), 'utf8')).source;
+    } catch { /* the deny stands on its own */ }
+    return {
+      deny: true,
+      reason: '[doc2md] 이 파일은 변환 캐시입니다. 여기를 고쳐도 원본 문서에는 아무것도 반영되지 않고, '
+        + '캐시만 오염된 채 다음 읽기부터 계속 서빙됩니다.\n'
+        + (source ? `  원본: ${source}\n` : '')
+        + '  문서 수정이 목적이라면: 원본을 복사한 뒤(cp) 복사본을 스크립트로 수정하십시오. '
+        + `pptx·docx·xlsx 는 ${managedPython()} 에 python-pptx·python-docx·openpyxl 이 설치되어 있고, `
+        + '.fig 는 doc2md-fig 의 openfig-core 로 편집·재인코드할 수 있습니다. '
+        + '수정 후 복사본을 `claude-token-saver doc2md <복사본>` 으로 재변환해 의도한 변경이 들어갔는지 확인하십시오. 원본은 절대 직접 수정하지 마십시오.',
+    };
+  }
+
+  if (isTargetPath(abs)) {
+    return {
+      deny: true,
+      reason: `[doc2md] ${path.basename(abs)} 는 이진 문서입니다. Edit/Write 는 텍스트를 쓰므로 이 파일을 파괴합니다. `
+        + '수정하려면 원본을 복사한 뒤(cp) 복사본을 스크립트로 고치십시오. '
+        + `pptx·docx·xlsx 는 ${managedPython()} 의 python-pptx·python-docx·openpyxl, .fig 는 openfig-core 를 쓰고, `
+        + '수정 후 `claude-token-saver doc2md <복사본>` 재변환으로 결과를 검증하십시오.',
+    };
+  }
+  return null;
+}
+
 /** The decision rendered as the JSON Claude Code expects on stdout. */
 function formatHookOutput(decision) {
   if (!decision) return null;
@@ -565,5 +758,6 @@ module.exports = {
   writeCache,
   convert,
   decideForRead,
+  decideForWrite,
   formatHookOutput,
 };

package/src/fig2md-runner.cjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Child-process shim between the synchronous doc2md pipeline and the async
+ * fig converter. Prints the conversion result as one JSON object on stdout,
+ * exactly like the Python converter does, so the caller treats both the same.
+ *
+ * Usage: node fig2md-runner.cjs <file.fig> <userDataDir>
+ */
+
+'use strict';
+
+const { convertFig } = require('./fig2md.cjs');
+
+const [file, userDataDir] = process.argv.slice(2);
+convertFig(file, userDataDir)
+  .then((result) => { process.stdout.write(JSON.stringify(result)); })
+  .catch((e) => {
+    process.stdout.write(JSON.stringify({
+      ok: false, reason: 'convert-failed', detail: String(e && e.message || e).slice(0, 300),
+    }));
+  });

package/src/fig2md.cjs

@@ -0,0 +1,182 @@
+/**
+ * fig2md — Markdown rendering of a Figma `.fig` export.
+ *
+ * Planning documents increasingly live in Figma rather than PowerPoint, and a
+ * `.fig` handed to the model is even more opaque than a pptx: the container
+ * is a zip, but the payload inside (`canvas.fig`) is Figma's binary kiwi
+ * format, so there is no XML to fall back on. Without a converter the file is
+ * simply unreadable.
+ *
+ * markitdown does not speak this format, so the conversion runs in Node with
+ * [openfig-core] (MIT, three small pure-JS dependencies). The parser is not
+ * bundled: this package deliberately ships with zero dependencies, so
+ * openfig-core is installed on demand into the tool's own state directory —
+ * the same arrangement as the markitdown venv, for the same reason.
+ *
+ * Verified 2026-09-06 against real files: a community Bootstrap UI kit
+ * (8.1MB, 4,155 nodes, 1,312 of them text) and a 52MB Tailwind kit, each
+ * converting in under a second, plus a round-trip fixture whose Korean text
+ * nodes came back byte-identical. Both .fig vintages parse — the current
+ * zip container and the older bare fig-kiwi stream.
+ *
+ * [openfig-core]: https://github.com/OpenFig-org/openfig-core
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const FIG_PARSER_SPEC = 'openfig-core@^0.4.1';
+
+/** Where the on-demand parser install lives, under the tool's state dir. */
+function managedFigDir(userDataDir) {
+  return path.join(userDataDir, 'doc2md-fig');
+}
+
+function loadParser(userDataDir) {
+  try {
+    // eslint-disable-next-line import/no-dynamic-require
+    return require(path.join(managedFigDir(userDataDir), 'node_modules', 'openfig-core', 'dist', 'index.cjs'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Install openfig-core into the managed directory. Mirrors the markitdown
+ * venv install: network once, probe as the acceptance test.
+ */
+function installFigParser(userDataDir, { onProgress = () => {} } = {}) {
+  const dir = managedFigDir(userDataDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const pkgJson = path.join(dir, 'package.json');
+  if (!fs.existsSync(pkgJson)) {
+    fs.writeFileSync(pkgJson, JSON.stringify({ name: 'doc2md-fig', private: true }) + '\n');
+  }
+  onProgress(`installing ${FIG_PARSER_SPEC}`);
+  const r = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', FIG_PARSER_SPEC], {
+    cwd: dir,
+    encoding: 'utf8',
+    timeout: 300_000,
+  });
+  if (r.status !== 0) {
+    return { ok: false, reason: 'npm-failed', detail: (r.stderr || '').slice(0, 400) };
+  }
+  if (!loadParser(userDataDir)) {
+    return { ok: false, reason: 'import-failed', detail: 'installed, but openfig-core does not load' };
+  }
+  return { ok: true, dir };
+}
+
+/**
+ * Node name plus type, indented by depth: the skeleton lines of the outline.
+ */
+function heading(node, depth) {
+  const name = String(node.name || '').trim() || '(이름 없음)';
+  return `${'#'.repeat(Math.min(depth + 2, 6))} ${name}`;
+}
+
+/**
+ * Walk the parsed document and render an outline.
+ *
+ * The traversal follows `childrenMap` (guid → ordered children), which is how
+ * the parser exposes hierarchy. Containers become headings, TEXT nodes become
+ * body lines, and everything visual (vectors, rectangles, images) is counted
+ * rather than listed: in a planning document the words are the content, and
+ * two hundred `Rectangle 173` lines would drown them.
+ */
+function renderMarkdown(doc, sourceName) {
+  const guidKey = (g) => `${g.sessionID}:${g.localID}`;
+  const lines = [];
+  const skipped = Object.create(null);
+  let textNodes = 0;
+
+  const CONTAINERS = new Set(['DOCUMENT', 'CANVAS', 'FRAME', 'GROUP', 'SECTION', 'COMPONENT', 'COMPONENT_SET', 'INSTANCE', 'SLIDE', 'SYMBOL']);
+
+  function walk(node, depth) {
+    if (!node || node.phase === 'REMOVED' || node.visible === false) return;
+    const type = node.type || '?';
+    if (type === 'TEXT') {
+      textNodes += 1;
+      const text = String(node.textData?.characters || '').trim();
+      const name = String(node.name || '').trim();
+      // The layer name usually repeats the text's first line; only show it
+      // when it says something the text does not.
+      if (name && text && !text.startsWith(name) && !name.startsWith(text.slice(0, 20))) {
+        lines.push(`- **${name}**: ${text.replace(/\n/g, ' / ')}`);
+      } else if (text) {
+        lines.push(`- ${text.replace(/\n/g, ' / ')}`);
+      }
+      return;
+    }
+    if (CONTAINERS.has(type)) {
+      if (type !== 'DOCUMENT') {
+        lines.push('', heading(node, depth), '');
+      }
+      const children = doc.childrenMap?.get?.(guidKey(node.guid))
+        || doc.childrenMap?.[guidKey(node.guid)]
+        || [];
+      for (const child of children) walk(child, depth + (type === 'DOCUMENT' ? 0 : 1));
+      return;
+    }
+    skipped[type] = (skipped[type] || 0) + 1;
+  }
+
+  const root = (doc.nodes || []).find((n) => n.type === 'DOCUMENT');
+  if (root) walk(root, 0);
+
+  const title = doc.meta?.file_name || sourceName;
+  const head = [`# ${title}`];
+  const skippedText = Object.entries(skipped)
+    .sort((a, b) => b[1] - a[1])
+    .map(([t, n]) => `${t} ${n}개`)
+    .join(', ');
+  if (skippedText) {
+    head.push('', `(텍스트 외 시각 요소는 생략했습니다: ${skippedText}. 시각 확인이 필요하면 Figma에서 원본을 여십시오.)`);
+  }
+  return { markdown: [...head, ...lines, ''].join('\n'), textNodes };
+}
+
+/**
+ * Convert one `.fig` file. Same result contract as the Python converter:
+ * `{ ok, markdown, note, truncated, rows, pages, markup_bytes }` or
+ * `{ ok: false, reason, detail }`.
+ *
+ * `markup_bytes` is 0 on purpose. The office formats price their alternative
+ * as "unzip and wade through the XML", but a .fig unzips to another binary —
+ * there is no readable fallback, so there is no honest baseline to claim and
+ * these conversions count as documents handled rather than money saved.
+ */
+async function convertFig(filePath, userDataDir) {
+  const parser = loadParser(userDataDir);
+  if (!parser) return { ok: false, reason: 'no-figparser' };
+  let doc;
+  try {
+    const buf = fs.readFileSync(filePath);
+    // Two vintages of the same extension: current exports are a zip wrapping
+    // canvas.fig, older ones are the bare fig-kiwi stream (magic "fig-kiwi").
+    // Verified on a real 8.4MB community kit that only the binary path reads.
+    doc = buf[0] === 0x50 && buf[1] === 0x4b
+      ? await parser.parseFig(buf)
+      : await parser.parseFigBinary(buf);
+  } catch (e) {
+    return { ok: false, reason: 'convert-failed', detail: String(e.message || e).slice(0, 300) };
+  }
+  const { markdown, textNodes } = renderMarkdown(doc, path.basename(filePath, '.fig'));
+  if (!textNodes) {
+    // A design file with no words converts to an empty outline, which would
+    // read as "the document says nothing" — a worse claim than "unreadable".
+    return { ok: false, reason: 'no-text', detail: 'the file has no text nodes' };
+  }
+  return { ok: true, markdown, note: null, truncated: false, rows: 0, pages: 0, markup_bytes: 0 };
+}
+
+module.exports = {
+  FIG_PARSER_SPEC,
+  managedFigDir,
+  installFigParser,
+  convertFig,
+  renderMarkdown,
+};

package/src/formatters/statusline.js

@@ -261,7 +261,7 @@ export function formatNoSession({ caps = null, model = null, windowLabel = '', v
  * @param {boolean} [opts.verbose=false] - longer layout with labels
  * @param {boolean} [opts.timer=true] - show TTL countdown segment
  * @param {'text'|'icon'} [opts.mode='text'] - label style. 'icon' uses 🧠 ⏳ 💰 instead of word labels.
- * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, version, harness, korean, model, hit, ttl, saved, delegated, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
+ * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, version, harness, korean, model, hit, ttl, saved, delegated, doc2md, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
  * @param {boolean} [opts.singleLine=false] - force the legacy one-line layout. By default, when the delegation ledger has lifetime savings, the routing totals lead on their own first line and everything else moves to line 2 (Claude Code renders multi-line statuslines; `--single-line` is the escape hatch for terminals that only show the first line).
  */
 export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null, singleLine = false } = {}) {
@@ -350,6 +350,32 @@ export function formatReport(data, { color = true, verbose = false, timer = true
       ? `${c(YELLOW)}🔀 ${unresolvedRuns} unresolved${c(RESET)}`
       : null);
 
+  // Document conversions — the same kind of number as "Routing saved", earned
+  // a different way: a document read as Markdown instead of attached whole.
+  // Kept as its own chip rather than folded into the routing total, because a
+  // single figure could not tell the reader which habit earned it.
+  //
+  // Conversions that saved nothing measurable still show as a count. For
+  // pptx/xlsx/docx the honest saving is zero — the client extracts much the
+  // same text — and a chip that disappeared on those would read as "doc2md
+  // did nothing" on the very formats it is the only way to open.
+  //   icon:  "📄 $0.42"   verbose: "📄 Doc2md saved $0.42 · 12 docs"
+  //   text:  "Doc2md saved $0.42"
+  const doc2md = data.doc2mdTotals;
+  const doc2mdUsd = Number(doc2md && doc2md.total) || 0;
+  const doc2mdDocs = Number(doc2md && doc2md.docs) || 0;
+  const doc2mdLabel = isIcon
+    ? (verbose ? '📄 Doc2md saved' : '📄')
+    : 'Doc2md saved';
+  let doc2mdSeg = null;
+  if (doc2mdUsd > 0) {
+    doc2mdSeg = `${c(GREEN)}${doc2mdLabel}${c(RESET)} ${formatMoney(doc2mdUsd)}`
+      + (verbose ? ` ${c(GRAY)}· ${doc2mdDocs} docs${c(RESET)}` : '');
+  } else if (doc2mdDocs > 0) {
+    const label = isIcon ? '📄' : 'Doc2md';
+    doc2mdSeg = `${c(GRAY)}${label} ${doc2mdDocs} docs${c(RESET)}`;
+  }
+
   // Routing-savings headline line (multi-line layout). The lifetime sum from
   // the delegation ledger — the number the whole tool exists to grow, so it
   // gets line 1 to itself while the diagnostics move to line 2.
@@ -388,6 +414,24 @@ export function formatReport(data, { color = true, verbose = false, timer = true
       (pairText ? `  ${c(GRAY)}|${c(RESET)}  ${pairText}` : '');
   }
 
+  // Doc2md's own headline line, same anatomy as the routing one: a green
+  // lifetime total, then a gray per-format breakdown. Only built when there
+  // is money to report — a bare document count stays an inline chip, since a
+  // whole line for "3 docs" would be all frame and no figure.
+  //   icon:  "📄 Doc2md saved $1.8 | pptx 1× $1.55 · pdf 2× $0.27"
+  let doc2mdLine = null;
+  if (!singleLine && doc2mdUsd > 0) {
+    const head = isIcon ? '📄 Doc2md saved' : 'Doc2md saved';
+    const byExt = Array.isArray(doc2md.byExt) ? doc2md.byExt : [];
+    const extText = byExt
+      .map((r) => `${c(GRAY)}${r.ext} ${r.docs}× ${formatMoney(r.usd)}${c(RESET)}`)
+      .join(` ${c(GRAY)}·${c(RESET)} `);
+    doc2mdLine =
+      `${c(GREEN)}${c(BOLD)}${head}${c(RESET)} ` +
+      `${c(GREEN)}${formatMoney(doc2mdUsd)}${c(RESET)}` +
+      (extText ? `  ${c(GRAY)}|${c(RESET)}  ${extText}` : '');
+  }
+
   // Period label honors hour-precision configs (`mode 6h` → "6h", `mode 1d` → "1d").
   // Fall back to legacy `${days}d` when callers haven't supplied a label.
   const periodLabel = options.windowLabel || `${options.days}d`;
@@ -628,6 +672,8 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // When the totals headline owns line 1, the inline session chip would
   // repeat the same story on line 2 — drop it there.
   if (delegateSeg && want('delegated') && !totalsLine) segs.push(delegateSeg);
+  // Only when it did not already earn a headline line above.
+  if (doc2mdSeg && want('doc2md') && !doc2mdLine) segs.push(doc2mdSeg);
   if (want('hit')) segs.push(hitSeg);
   if (want('ttl')) segs.push(ttlSeg);
   for (const { key, seg } of usageSegs) {
@@ -646,8 +692,17 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // allowed — --no-color/NO_COLOR consumers expect escape-free output.
   const eol = color ? '\x1b[K' : '';
   const rest = segs.join(' · ') + eol;
+  // Each savings source that earned real money gets a headline line, ordered
+  // biggest saver first — the top line is the one the eye lands on, so it
+  // goes to whichever habit is actually paying for the tool. The diagnostics
+  // line always closes.
+  const headlines = [];
   if (totalsLine && want('delegated')) {
-    return totalsLine + eol + '\n' + rest;
+    headlines.push({ usd: Number(totals && totals.total) || 0, line: totalsLine });
+  }
+  if (doc2mdLine && want('doc2md')) {
+    headlines.push({ usd: doc2mdUsd, line: doc2mdLine });
   }
-  return rest;
+  headlines.sort((a, b) => b.usd - a.usd);
+  return headlines.map((h) => h.line + eol + '\n').join('') + rest;
 }