claude-token-saver 3.29.0 → 3.30.1

package/README.en.md

@@ -452,7 +452,28 @@ Planning documents are moving from PowerPoint to Figma, so the same hook catches
 
 The result is an outline: pages and frames become headings, text nodes become body lines, and shapes are counted rather than listed — in a planning document the words are the content, and two hundred `Rectangle 173` lines would drown them. A file with no text at all is refused rather than dressed up as an empty document.
 
-Verified 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. Both `.fig` vintages parse — the current zip container and the older bare fig-kiwi stream. No savings are claimed: a `.fig` unzips to another binary, so there is no readable fallback to price against.
+Verified 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. Both `.fig` vintages parse — the current zip container and the older bare fig-kiwi stream.
+
+**`.fig` saves the most of any format.** Unlike the Office containers, `Read` does not refuse a `.fig`: the extension means nothing to it, so it pulls the binary in as text and the context window fills with tokenised noise. Measured against the same 42,760-token control:
+
+| File | Size | Extra tokens for a Read | Conversion |
+|---|---|---|---|
+| plan.fig | 26KB | +44,195 | 100 tokens |
+| bootstrap-kit.fig | 8.1MB | +43,994 | 18,397 tokens |
+
+Two files three hundred times apart in size cost the same, because Read truncates long before the file ends — you pay for a whole document and receive a fraction of one. The baseline is therefore a flat 44,000 tokens. For comparison, the same probe on a pptx cost +317 tokens and on a docx +185: a refusal message, and nothing else.
+
+#### Why the baseline does not scale with file size
+
+A baseline has to be what would actually have been spent without the converter. Intuition says a bigger file burns more, but the `Read` tool has a cap (2,000 lines by default, plus a per-line character limit), and a binary file hits it almost immediately: even the 26KB file was already truncated, which is why two files 300× apart came out 201 tokens apart. Had the 8.1MB file gone in whole it would have been millions of tokens — money nobody could have spent, since it does not fit in a 200k context window. Claiming to have saved unspendable money is flattery, not measurement.
+
+The same principle runs through every baseline here:
+
+- **`.fig`, flat 44,000** — set below both measurements (44,195 and 43,994). A model could burn size-proportional tokens by re-Reading at successive offsets, but one Read is what a sane agent does once the bytes turn out to be binary noise, so one Read is the honest counterfactual.
+- **PDF, 2,500 per page** — below both measured values (2,542 and 2,934).
+- **Office formats, the file's actual XML size** — the one case where proportional is right, because a person really does end up reading that XML; it is measured per file rather than applied as a ratio.
+
+The common rule: wherever an estimate and a measurement diverge, the lower number wins. A figure the user can trust is worth more than one that flatters the tool.
 
 ### Editing a document: copy, then script
 

package/README.md

@@ -448,7 +448,28 @@ PDF 는 첨부하면 모델이 내용을 그대로 읽습니다. 대신 페이
 
 변환 결과는 페이지·프레임 계층을 헤딩으로, 텍스트 노드를 본문으로 정리한 아웃라인입니다. 도형·벡터 같은 시각 요소는 나열하지 않고 개수만 남깁니다. 기획서에서 내용은 글이고, `Rectangle 173` 이 이백 줄 나오면 글이 묻히기 때문입니다. 텍스트가 하나도 없는 파일(순수 그래픽)은 빈 문서로 꾸미지 않고 변환 불가로 알립니다.
 
-실제 파일로 검증했습니다: 피그마 커뮤니티의 Bootstrap UI kit(8.1MB, 노드 4,155개, 텍스트 1,312개)와 Tailwind kit(52MB)이 각각 0.2초 안에 71.9KB·44KB 아웃라인으로 변환됐고, 한국어 텍스트 왕복도 무손실이었습니다. `.fig` 는 두 세대가 있습니다. 요즘 익스포트는 zip 컨테이너, 옛 익스포트는 fig-kiwi 바이너리 원형인데 둘 다 처리합니다. 절감액은 청구하지 않습니다. `.fig` 는 압축을 풀어도 또 바이너리라 비교할 대안 자체가 없고, 변환이 유일한 읽기 경로입니다.
+실제 파일로 검증했습니다: 피그마 커뮤니티의 Bootstrap UI kit(8.1MB, 노드 4,155개, 텍스트 1,312개)와 Tailwind kit(52MB)이 각각 0.2초 안에 71.9KB·44KB 아웃라인으로 변환됐고, 한국어 텍스트 왕복도 무손실이었습니다. `.fig` 는 두 세대가 있습니다. 요즘 익스포트는 zip 컨테이너, 옛 익스포트는 fig-kiwi 바이너리 원형인데 둘 다 처리합니다.
+
+**`.fig` 의 절감이 가장 큽니다.** 오피스 형식과 달리 `Read` 가 `.fig` 를 거부하지 않습니다. 확장자를 모르니 이진 파일을 그대로 텍스트로 읽어들이고, 컨텍스트가 토큰화된 잡음으로 찹니다. 같은 42,760 토큰 대조군으로 측정했습니다.
+
+| 파일 | 크기 | Read 가 더 쓴 토큰 | 변환본 |
+|---|---|---|---|
+| plan.fig | 26KB | +44,195 | 100 토큰 |
+| bootstrap-kit.fig | 8.1MB | +43,994 | 18,397 토큰 |
+
+크기가 300배 차이인데 비용이 같습니다. Read 가 상한에서 자르기 때문인데, 바꿔 말하면 **문서 전체 값을 치르고 일부만 받습니다.** 그래서 기준선은 파일 크기와 무관한 44,000 토큰 고정입니다. 참고로 같은 방법으로 재보니 pptx 는 +317, docx 는 +185 토큰이었습니다. 거부 메시지 한 줄이 전부입니다.
+
+#### 왜 파일 크기에 비례시키지 않는가
+
+기준선은 "변환이 없었으면 실제로 나갔을 비용"이어야 합니다. 직관으로는 파일이 클수록 더 태울 것 같지만, `Read` 도구에는 상한이 있어(기본 2,000줄, 줄당 문자 제한) 이진 파일은 그 지점에서 잘립니다. 26KB 파일조차 이미 상한을 넘기므로, 크기가 300배 차이 나는 두 파일이 201 토큰 차이로 같은 값이 나왔습니다. 8.1MB 가 통째로 들어갔다면 수백만 토큰인데, 그 돈은 200k 컨텍스트에 물리적으로 들어가지 않아 애초에 아무도 지불할 수 없습니다. 지불할 수 없는 돈을 아꼈다고 적으면 부풀리기가 됩니다.
+
+이 원칙은 세 곳에 일관되게 적용됩니다.
+
+- **`.fig` 44,000 고정** — 실측 두 값(44,195·43,994)보다 낮게 잡습니다. 모델이 offset 을 바꿔 가며 반복 Read 하면 크기에 비례해 태울 수는 있지만, 첫 Read 에서 이진 잡음임이 드러나면 정상적인 에이전트는 더 읽지 않으므로 1회 Read 가 현실적인 대안입니다.
+- **PDF 페이지당 2,500** — 실측치 2,542·2,934 를 밑도는 값입니다.
+- **오피스 형식은 파일별 실제 XML 크기** — 이쪽은 사람이 정말 그 XML 을 읽게 되므로 비례가 맞고, 계수 대신 파일마다 잽니다.
+
+공통 규칙: 기준선이 추정과 실측 사이에서 갈리면 항상 낮은 쪽을 택합니다. 도구를 돋보이게 하는 숫자보다 사용자가 신뢰할 수 있는 숫자가 가치 있습니다.
 
 ### 문서를 수정해야 할 때: 복사본 + 스크립트
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.29.0",
+  "version": "3.30.1",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/src/doc2md-ledger.cjs

@@ -31,9 +31,11 @@
  *
  * pptx/xlsx/docx: unpacking the container. These never reach the model as
  * attachments at all — the same probe on a docx added 78 tokens and the model
- * replied that it had no file, and Read refuses the format outright. What a
- * reader does instead is unzip the archive and wade through its XML, where
- * tags and style attributes outweigh the text many times over:
+ * replied that it had no file. Read refuses them too, measured the same way:
+ * a Read of the 31.8MB deck cost +317 tokens and of the 185KB docx +185, which
+ * is a refusal message and nothing more. What a reader does instead is unzip
+ * the archive and wade through its XML, where tags and style attributes
+ * outweigh the text many times over:
  *
  *   aws-summit-seoul.pptx   2.1MB of slide XML   ~540,429 tokens   23.8× the conversion
  *   우리은행이력서.docx      312KB of body XML    ~78,113 tokens    ~46× the conversion
@@ -43,6 +45,21 @@
  * a real fallback — this very session unzipped a pptx to verify a conversion
  * before this ledger existed.
  *
+ * .fig: the file itself. Unlike the Office formats, Read does not refuse a
+ * .fig — the extension means nothing to it, so it pulls the binary in as text
+ * and the context window fills with tokenised noise. Measured against the same
+ * 42,760-token control:
+ *
+ *   plan.fig            26KB    +44,195 tokens   conversion: 100
+ *   bootstrap-kit.fig   8.1MB   +43,994 tokens   conversion: 18,397
+ *
+ * Two files three hundred times apart in size cost the same, because Read
+ * truncates at a cap long before the file ends — which also means the reader
+ * gets a fraction of a document for the price of a whole one. The baseline is
+ * therefore a flat 44,000 tokens rather than anything per-byte. An earlier
+ * version of this file claimed .fig had no measurable baseline at all; that
+ * was an assumption about Read's behaviour that turned out to be wrong.
+ *
  * Erring low is deliberate throughout. A savings figure that flatters the
  * tool is worth less than one the user can trust.
  *
@@ -79,10 +96,10 @@ const ATTACHMENT_BASELINE = {
   '.docx': { markup: true },
   '.xlsx': { markup: true },
   '.xls': { ratio: 1 },
-  // A .fig unzips to another binary (Figma's kiwi format), so unlike the
-  // office containers there is no readable markup to price the fallback
-  // against. Converting is the only way to read it at all; no money claimed.
-  '.fig': { ratio: 1 },
+  // Read swallows a .fig instead of refusing it, at a flat ~44,000 tokens
+  // whatever the file's size (see the header). Rounded down from the two
+  // measurements, both of which landed just under 44,200.
+  '.fig': { fixed: 44_000 },
 };
 
 /**
@@ -106,7 +123,9 @@ function estimateSaving({ ext, pages = 0, markupBytes = 0, markdown = '' }) {
   const tokens = estimateTokens(markdown);
   const rule = ATTACHMENT_BASELINE[String(ext).toLowerCase()] || { ratio: 1 };
   let baseline;
-  if (rule.perPage && pages > 0) {
+  if (rule.fixed) {
+    baseline = rule.fixed;
+  } else if (rule.perPage && pages > 0) {
     baseline = pages * rule.perPage;
   } else if (rule.markup && markupBytes > 0) {
     baseline = Math.ceil(markupBytes / 4);

package/src/doc2md.cjs

@@ -165,10 +165,13 @@ function banner(sourcePath, saving) {
   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을 읽으면';
+    // would have been attached, a zip document unpacked, and a .fig read
+    // straight into the context window, which is the one Read does not
+    // refuse.
+    const ext = path.extname(sourcePath).toLowerCase();
+    const alternative = ext === '.pdf' ? '원본을 첨부하면'
+      : ext === '.fig' ? '원본을 그대로 Read 하면'
+        : '압축을 풀어 본문 XML을 읽으면';
     lines.push(
       `${alternative} 약 ${saving.baseline.toLocaleString('en-US')} 토큰이 드는데, `
       + `변환본은 ${saving.tokens.toLocaleString('en-US')} 토큰입니다. `

package/src/formatters/statusline.js

@@ -425,9 +425,9 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     const byExt = Array.isArray(doc2md.byExt) ? doc2md.byExt : [];
     // Formats that earned money show it; formats with no baseline to measure
     // against are counted instead. Printing "$0.00" next to real amounts reads
-    // as "this format saved nothing", when what it means is that there is no
-    // working alternative to price it against — for .fig there is no readable
-    // fallback at all, so the conversion is the only way to open the file.
+    // as "this format saved nothing", when what it means is that nobody has
+    // measured what the alternative costs. Only .xls sits there now — the
+    // pre-2007 binary, which has no container to price against.
     const paid = byExt.filter((r) => r.usd > 0);
     const unpriced = byExt.filter((r) => !(r.usd > 0));
     const parts = paid.map((r) => `${c(GRAY)}${r.ext} ${r.docs}× ${formatMoney(r.usd)}${c(RESET)}`);