From 506cf9e7ff474c78bbb88242d617e2eaee0e826f Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 09:02:27 -0400
Subject: [PATCH 01/17] =?UTF-8?q?docs:=20Phase=201=20design=20=E2=80=94=20?=
 =?UTF-8?q?segment-aligned=20model=20+=20side-by-side=20viewer?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Batch translate+align (few calls, not per-sentence), precomputed word-align for
<1s click, HTML side-by-side viewer with block/sentence/word sync highlight,
per-document budget tracking (admin), iOS download fix. Includes guardrails
audit with 8 🔴 acceptance criteria (XSS-safe render, /api/result hardening,
align validation, schemaVersion cache, segment cap, admin-gated usage).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...6-06-03-hebrew-translator-phase1-design.md | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 docs/plans/2026-06-03-hebrew-translator-phase1-design.md

diff --git a/docs/plans/2026-06-03-hebrew-translator-phase1-design.md b/docs/plans/2026-06-03-hebrew-translator-phase1-design.md
new file mode 100644
index 0000000..f9e0d21
--- /dev/null
+++ b/docs/plans/2026-06-03-hebrew-translator-phase1-design.md
@@ -0,0 +1,87 @@
+# Hebrew Translator — Phase 1 Design: segment-aligned model + side-by-side viewer
+
+**Date:** 2026-06-03
+**Status:** Approved (design-lock)
+**Builds on:** `2026-06-01-hebrew-translator-production-design.md` (Phase 0 live).
+
+## Scope (locked)
+Phase 1 delivers the **alignment foundation + a synchronized side-by-side viewer**, plus per-document budget tracking and the iOS download fix. Pixel-faithful file output (PDF overlay, DOCX in-place) is the **next** phase.
+
+| Decision | Value |
+|----------|-------|
+| Formats (fidelity files) | both PDF+DOCX — but **next phase**; Phase 1 = viewer |
+| Highlight granularity | all three: block → sentence → word |
+| Word alignment source | LLM, **precomputed in the batch pass** (not lazy) — required by <1s click latency |
+| Viewer rendering | HTML panes (source RTL / target LTR), not pixel-faithful |
+| Budget tracking | per-document tokens + cost + actual model, admin-gated |
+
+## 1. Foundation — `TranslationDocument` (canonical intermediate)
+Pipeline becomes extract → structure → batch-translate(+align) → `TranslationDocument` JSON:
+```jsonc
+{ schemaVersion: 1, sourceLang, targetLang,
+  usage: { byModel: { "gemini-2.0-flash": {calls,in,out,total,costUsd} }, totals: {...} },
+  blocks: [ { id:"b1", type:"paragraph", sentences:[
+    { id:"b1s1", source:"שלום עולם", target:"Hello world",
+      srcTokens:["שלום","עולם"], tgtTokens:["Hello","world"],
+      align:[ {src:[0],tgt:[0]}, {src:[1],tgt:[1]} ] } ] } ] }
+```
+
+**Pipeline:**
+1. Extract (pdf-parse / mammoth) → blocks.
+2. Split blocks → sentences via `Intl.Segmenter` (sentence granularity); NFC-normalize Hebrew first.
+3. Tokenize source per sentence via `Intl.Segmenter` (word granularity) → `srcTokens` (server is the source of truth for tokens).
+4. **Batch translate + align**: group sentences into chunks (≈15-20 segments / ~1.5k tokens, respecting block boundaries). One LLM call per chunk returns `[{id, target, align}, …]`. A few calls per document, not per-sentence.
+5. Assemble `TranslationDocument`; store by random token (TTL) in the result store.
+
+**Why precompute align:** <1s click latency forbids per-click LLM round-trips (first click would miss cache). Block/sentence highlight is free (shared ids, 1:1); word-align rides along in the same batch calls.
+
+**Caching:** per chunk/sentence, key = `model + promptVersion + schemaVersion + langs + hash(text)`. Distinct namespace from Phase-0 string cache (value shape changed → collision = crash).
+
+## 2. Viewer (frontend — new result screen)
+- API: `GET /api/result/:token` → `TranslationDocument` (minus admin-only `usage`). `Cache-Control: private, no-store`.
+- Two scrollable panes: **left = source** (`dir="rtl"`, `unicode-bidi: plaintext` per segment), **right = target** (LTR). Each word is a span carrying `data-block / data-sentence / data-token`.
+- Interaction (bidirectional, from either pane):
+  - hover/click a **word** → highlight aligned word(s) in the other pane via `align`;
+  - click a **sentence** → highlight the paired sentence both sides;
+  - **block** → highlight the block.
+- **Rendered only via React text nodes** — never `dangerouslySetInnerHTML` for document content (XSS).
+- Client renders the server's `srcTokens`/`tgtTokens` **as-is** (never re-tokenizes) so align indices line up.
+- Keeps a **Download** button.
+
+## 3. Budget tracking (admin)
+- `LiteLLMProvider` returns `usage {model, promptTokens, completionTokens, totalTokens, costUsd}` from the response (`usage` + `x-litellm-response-cost` / `_hidden_params`). Capture the **actual** model (fallback-aware), not the alias.
+- Worker aggregates across batch calls → `usage.byModel` + totals, stored with the result.
+- Admin: per-document panel (`model · in/out tokens · $cost`) + `GET /api/admin/usage` (recent jobs). Gated by `ADMIN_KEY` env (minimal gate until real auth exists). Usage stripped from the public result payload.
+
+## 4. iOS download fix
+Replace blob + `a.download` with a direct anchor to the attachment URL (server already sends `Content-Disposition: attachment`) — reliable on iOS Safari.
+
+## 5. Error handling (graceful degradation)
+- Malformed batch JSON → per-item parse; bad item degrades to sentence-level (no crash), job continues.
+- align out-of-range / not covering tokens → drop word-level for that sentence; sentence/block highlight still works.
+- Sentence segmentation failure → whole block as one sentence.
+- Keep Phase-0 guardrails (refusal/length-ratio).
+
+## 6. Testing
+Unit: `Intl.Segmenter` sentence/word wrappers, align validator (out-of-range→drop), `TranslationDocument` builder, usage aggregator. Adapter: structured-output mock (incl. malformed item). Integration: fixture → valid `TranslationDocument`. Frontend: clicking a word highlights the paired token; XSS fixture (text with `<script>`) renders inert. E2E optional (Playwright-MCP flaky here).
+
+## 7. Best practices & guardrails (design-guardrails-audit, 2026-06-03)
+🔴 = Phase-1 acceptance criteria.
+
+1. 🔴 **XSS-safe rendering** — React text nodes only; zero `dangerouslySetInnerHTML` for doc/LLM content; lint/test guard. (Client currently clean — keep it.)
+2. 🔴 **`/api/result/:token` hardening** — UUID token, format-validated, TTL, `Cache-Control: private, no-store` (payload holds full document text). Mirror download token pattern (`api/translate.js:74,229,238`).
+3. 🔴 **align validation** — strict vs `srcTokens`/`tgtTokens`; invalid → graceful degrade, never crash.
+4. 🔴 **structured-output robustness** — malformed JSON → per-item fallback, job survives.
+5. 🔴 **consistent tokenization server↔client** — client renders server tokens as-is; NFC + `Intl.Segmenter`; correct RTL/bidi in source pane.
+6. 🔴 **cache `schemaVersion`** — no collision with Phase-0 string cache.
+7. 🔴 **segment cap** — bound segments/JSON size; on truncation, explicit `log` (no silent cap).
+8. 🔴 **budget data admin-gated** — `ADMIN_KEY`; usage never in public payload.
+
+🟡: per-document cost/RPM logging (correlation id=jobId, content redacted); cross-sentence context within chunks for coherence; cost accuracy via actual-model capture; in-flight cache dedup; DOM perf on very large docs (cap/virtualize).
+🟢: scroll-sync panes; temperature=0 for align determinism.
+
+Cross-cutting: align-quality eval fixture (in-range + coverage + 1:1 sentences); fail-fast schema validation.
+
+## 8. Phase boundaries (YAGNI)
+**In:** TranslationDocument pipeline (batch translate+align), side-by-side HTML viewer (3-level highlight), budget tracking (admin), iOS download fix, light UI refresh of the result/upload screens.
+**Out (next phase):** pixel-faithful PDF overlay, DOCX in-place file output, scroll-sync, real user auth.

From ccd636d4ad9731ef12fd2b6b252cd5d8fe6d1036 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 09:04:22 -0400
Subject: [PATCH 02/17] =?UTF-8?q?docs:=20Phase=201=20design=20=E2=80=94=20?=
 =?UTF-8?q?usage=20records=20forward-compatible=20for=20per-user=20admin?=
 =?UTF-8?q?=20monitoring?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/plans/2026-06-03-hebrew-translator-phase1-design.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/plans/2026-06-03-hebrew-translator-phase1-design.md b/docs/plans/2026-06-03-hebrew-translator-phase1-design.md
index f9e0d21..28055a9 100644
--- a/docs/plans/2026-06-03-hebrew-translator-phase1-design.md
+++ b/docs/plans/2026-06-03-hebrew-translator-phase1-design.md
@@ -52,6 +52,7 @@ Pipeline becomes extract → structure → batch-translate(+align) → `Translat
 - `LiteLLMProvider` returns `usage {model, promptTokens, completionTokens, totalTokens, costUsd}` from the response (`usage` + `x-litellm-response-cost` / `_hidden_params`). Capture the **actual** model (fallback-aware), not the alias.
 - Worker aggregates across batch calls → `usage.byModel` + totals, stored with the result.
 - Admin: per-document panel (`model · in/out tokens · $cost`) + `GET /api/admin/usage` (recent jobs). Gated by `ADMIN_KEY` env (minimal gate until real auth exists). Usage stripped from the public result payload.
+- **Forward-compatible for multi-user:** each usage record carries an `owner` field (`anon`/null now; a real userId once auth exists) plus `jobId` and timestamp, stored append-only so a **future admin panel can aggregate consumption per user / per period** when accounts arrive. The admin usage endpoint is built to group by `owner` (today: one bucket). No user system in Phase 1 — only the data shape + aggregation are future-proofed (YAGNI: no auth UI now).
 
 ## 4. iOS download fix
 Replace blob + `a.download` with a direct anchor to the attachment URL (server already sends `Content-Disposition: attachment`) — reliable on iOS Safari.

From 5d04484845ea974df843632b3a88de586e2975d9 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 09:06:32 -0400
Subject: [PATCH 03/17] docs: Phase 1 implementation plan (16 tasks, TDD)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...hebrew-translator-phase1-implementation.md | 210 ++++++++++++++++++
 1 file changed, 210 insertions(+)
 create mode 100644 docs/plans/2026-06-03-hebrew-translator-phase1-implementation.md

diff --git a/docs/plans/2026-06-03-hebrew-translator-phase1-implementation.md b/docs/plans/2026-06-03-hebrew-translator-phase1-implementation.md
new file mode 100644
index 0000000..e2f8f89
--- /dev/null
+++ b/docs/plans/2026-06-03-hebrew-translator-phase1-implementation.md
@@ -0,0 +1,210 @@
+# Hebrew Translator — Phase 1 Implementation Plan (segment-aligned model + side-by-side viewer)
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Produce a segment-aligned `TranslationDocument` from each upload and a synchronized side-by-side HTML viewer (block/sentence/word highlight), plus per-document budget tracking (admin) and the iOS download fix.
+
+**Architecture:** Extract → split into blocks→sentences (Intl.Segmenter) → whitespace-tokenize → **batch** translate+align (few LLM calls per doc, chunked) → `TranslationDocument` JSON stored by token → React viewer renders both panes from the JSON and highlights via the alignment map. Usage (tokens/cost/actual model) captured per LLM call and aggregated per job.
+
+**Tech Stack:** Node ≥18 (`Intl.Segmenter`), Express, Bull/Redis, vitest, React (CRA)+MUI, LiteLLM proxy (Gemini primary).
+
+**Design:** `docs/plans/2026-06-03-hebrew-translator-phase1-design.md`. Acceptance criteria = the 8 🔴 in design §7.
+
+**Branch:** `feat/phase1-viewer` (design committed). **Test:** `npm test -- <path>` (server), client tests via CRA.
+
+> **Decisions baked in:** tokenization = whitespace split (`text.split(/\s+/)`) — server emits `srcTokens`/`tgtTokens`, client renders them as-is (never re-tokenizes). `Intl.Segmenter` used only for sentence splitting. Word/sentence/block highlight; word-align precomputed in the batch pass.
+
+---
+
+### Task 0: Sync base (resolve stale local main)
+
+Local `main` is behind remote (missing PR #9 font+speed). Before coding, sync so Phase 1 builds on the deployed state.
+
+```bash
+git checkout main && git pull origin main          # needs network; remote main = PR#9 merged
+git checkout feat/phase1-viewer && git rebase main # bring font/speed under the design commits
+npm test                                            # baseline green (server suite)
+ls server/assets/fonts/DejaVuSans.ttf               # must exist (PR#9)
+grep -c translateBlock server/core/translation/Translator.js  # >0 (PR#9 parallelization)
+```
+If network blocks GitHub, do it over the working VPN path first. Do NOT start Task 1 until `DejaVuSans.ttf` is present and `translateBlock` exists.
+
+---
+
+### Task 1: Sentence + token helpers
+
+**Files:** Create `server/services/segmenter.js`, `server/services/__tests__/segmenter.test.js`.
+
+**Step 1 — failing test:**
+```javascript
+import { describe, it, expect } from 'vitest';
+import { splitSentences, tokenize, nfc } from '../segmenter.js';
+
+it('splits into sentences', () => {
+  const s = splitSentences('Hello world. How are you? Fine.');
+  expect(s.length).toBe(3);
+});
+it('tokenizes on whitespace, drops empties', () => {
+  expect(tokenize('  שלום   עולם ')).toEqual(['שלום','עולם']);
+});
+it('nfc-normalizes', () => {
+  expect(nfc('é')).toBe('é');
+});
+```
+**Step 2:** `npm test -- server/services/__tests__/segmenter` → FAIL.
+**Step 3 — implement:** `nfc(s)=s.normalize('NFC')`; `tokenize(s)=nfc(s).trim().split(/\s+/).filter(Boolean)`; `splitSentences(s, locale='und')` using `Intl.Segmenter(locale,{granularity:'sentence'})` → array of trimmed non-empty sentence strings (fallback: if Segmenter unavailable, split on `/(?<=[.!?。])\s+/`).
+**Step 4:** PASS. **Step 5:** commit `feat: sentence/token segmentation helpers`.
+
+---
+
+### Task 2: Alignment validator
+
+**Files:** Create `server/services/align.js`, `server/services/__tests__/align.test.js`.
+
+**Step 1 — failing test:**
+```javascript
+import { describe, it, expect } from 'vitest';
+import { validateAlign } from '../align.js';
+const src=['a','b'], tgt=['x','y'];
+it('keeps valid pairs', () => {
+  expect(validateAlign([{src:[0],tgt:[0]},{src:[1],tgt:[1]}], src, tgt))
+    .toEqual([{src:[0],tgt:[0]},{src:[1],tgt:[1]}]);
+});
+it('drops out-of-range groups, returns [] not throw', () => {
+  expect(validateAlign([{src:[5],tgt:[0]}], src, tgt)).toEqual([]);
+});
+it('returns [] for malformed input', () => {
+  expect(validateAlign(null, src, tgt)).toEqual([]);
+  expect(validateAlign('nope', src, tgt)).toEqual([]);
+});
+```
+**Step 2:** FAIL. **Step 3 — implement:** `validateAlign(align, srcTokens, tgtTokens)` → if not array return `[]`; keep only groups where `src`/`tgt` are arrays of integers all within `[0,len)`; drop others. Never throw. **Step 4:** PASS. **Step 5:** commit `feat: alignment validator (graceful degradation)`.
+
+---
+
+### Task 3: TranslationDocument builder (pre-translation structure)
+
+**Files:** Create `server/services/translationDocument.js` + test.
+
+`buildSegments(blocks)` → for each block, split into sentences, assign ids `b{n}s{m}`, attach `srcTokens` (tokenize). Returns `{ blocks:[{id,type,sentences:[{id, source, srcTokens}]}] }` and a flat `segments` list (refs) for batching. `SCHEMA_VERSION=1` exported.
+
+Test: a 2-paragraph input → 2 blocks, correct sentence ids, srcTokens populated. Commit `feat: TranslationDocument segment builder`.
+
+---
+
+### Task 4: LiteLLM batch translate+align adapter
+
+**Files:** Modify `server/adapters/ai/LiteLLMProvider.js`; test `server/adapters/ai/__tests__/litellmBatch.test.js`.
+
+Add `async translateBatchAligned(segments, from, to)` where `segments=[{id, source, srcTokens}]`. Build ONE chat call: system prompt instructs "translate he→{to}; return ONLY JSON array `[{id, target, align}]`; `align` = list of `{src:[srcTokenIdx],tgt:[tgtTokenIdx]}`; src indices refer to the provided 0-based token list." Provide each segment as `id` + indexed source tokens. `temperature:0`, JSON response.
+Returns `{ items: [{id, target, align}], usage: {model, promptTokens, completionTokens, totalTokens, costUsd} }` — parse `data.usage`, actual model from `data.model`, cost from response header `x-litellm-response-cost` or `data._hidden_params?.response_cost` (default 0).
+**Robustness:** parse JSON defensively; per-item validate (has id+target string); malformed/missing items → omitted (caller falls back to source). Malformed whole response → `{items:[], usage}`.
+
+Test (mock global.fetch): returns array → parsed items + usage; one malformed item → skipped, others kept; non-JSON → `items:[]` no throw; assert request body model alias = 'translate'. Commit `feat: LiteLLM batch translate+align with usage capture`.
+
+---
+
+### Task 5: Usage aggregator
+
+**Files:** Create `server/services/usage.js` + test.
+
+`newUsage()` → empty; `addCall(usage, {model,promptTokens,completionTokens,totalTokens,costUsd})` accumulates into `byModel[model]` (`calls,in,out,total,costUsd`) and `totals`. `finalize(usage,{owner,jobId,ts})` stamps metadata. Test accumulation across 2 calls of same+different model. Commit `feat: per-job usage/cost aggregator`.
+
+---
+
+### Task 6: Wire pipeline in worker (chunked batch → TranslationDocument + usage + result store)
+
+**Files:** Modify `server/api/translate.js` (queue processor); create `server/services/resultStore.js` + test.
+
+- `resultStore`: `save(token, doc, ttlMs)` / `get(token)` using ioredis (key `result:<token>`, JSON, TTL); in-memory Map fallback if no redis. Test save/get/expire.
+- Processor: extract (existing `documentProcessor.processDocument`) → `buildSegments` → chunk flat segments (≤18 segments OR ~1500 src tokens per chunk, respect order) → for each chunk `provider.translateBatchAligned` (bounded concurrency, reuse pattern) → map items back by id, `validateAlign`, tokenize target → fill sentences (`target`,`tgtTokens`,`align`); missing item → `target=source`, `align=[]` → accumulate usage.
+- **Segment cap:** if total segments > `MAX_SEGMENTS` (env, default 1500) → truncate remainder to source-only and `log` a warning (no silent cap).
+- Build final `TranslationDocument` (schemaVersion, langs, blocks, usage.finalize({owner:'anon',jobId})). `resultStore.save(token, doc)`. Also keep generating the downloadable file (existing path) for the Download button.
+- `completed` socket event includes `resultToken` (the result store key) alongside `downloadUrl`.
+
+No new unit test for the whole processor (needs redis/LLM); covered by integration + manual. Commit `feat: chunked batch pipeline -> TranslationDocument + usage + result store`.
+
+---
+
+### Task 7: `GET /api/result/:token` (hardened)
+
+**Files:** Modify `server/api/translate.js`; test `server/api/__tests__/result.test.js` (supertest).
+
+Validate `:token` against `/^[0-9a-fA-F-]{8,}$/` → 400 else; `resultStore.get` → 404 if missing; strip `usage` from payload; set `Cache-Control: private, no-store`; return `{schemaVersion,sourceLang,targetLang,blocks}`.
+Tests: bad token → 400; missing → 404; present → 200 with blocks and **no `usage`**; header set. Commit `feat: hardened /api/result/:token (no usage leak, no-store)`.
+
+---
+
+### Task 8: `GET /api/admin/usage` (ADMIN_KEY gate)
+
+**Files:** Modify `server/api/translate.js` (or new `server/api/admin.js` mounted in index.js); test.
+
+Require header `x-admin-key === process.env.ADMIN_KEY` (and ADMIN_KEY set) → else 401/404. Return recent jobs' usage grouped by `owner` (read from a `usagelog` list in resultStore/redis, capped length). 
+Tests: no/invalid key → 401; valid key → 200 with grouped usage. Commit `feat: admin usage endpoint (ADMIN_KEY gated, per-owner)`.
+
+---
+
+### Task 9 (frontend): fetch result + viewer state
+
+**Files:** Modify `client/src/App.js`.
+
+On `translation:complete`, store `resultToken`; fetch `GET ${API_URL}/api/result/<token>` → `translationDoc` state. Render `<SideBySideViewer doc={translationDoc}/>` when present (alongside existing download). Commit `feat(client): fetch TranslationDocument on completion`.
+
+---
+
+### Task 10 (frontend): SideBySideViewer (XSS-safe render)
+
+**Files:** Create `client/src/components/SideBySideViewer.js` + `client/src/components/__tests__/SideBySideViewer.test.js` (RTL/jest via CRA).
+
+Render two panes from `doc.blocks`. Left source `dir="rtl"` with `style={{unicodeBidi:'plaintext'}}` per sentence; right target LTR. Each token: `<span data-b data-s data-t onMouseEnter/onClick>{token}</span>` joined by spaces. **All text via React children (never `dangerouslySetInnerHTML`).**
+Tests: renders block/sentence/token counts; **XSS fixture**: a token `"<img src=x onerror=alert(1)>"` appears as literal text (query by text), no HTML injected. Commit `feat(client): side-by-side viewer, XSS-safe`.
+
+---
+
+### Task 11 (frontend): synchronized highlighting
+
+**Files:** Modify `SideBySideViewer.js` + test.
+
+State `active={blockId,sentenceId,tokenIdx,side}`. Hover/click token → compute paired token indices via the sentence's `align` (both directions: clicking a src token → tgt tokens where group.src includes idx, and vice versa) → apply `.hl` class to matched spans on the other side; clicking sentence gap → highlight whole paired sentence; block → block. If `align` empty → fall back to sentence-level highlight.
+Test: given a doc with `align:[{src:[0],tgt:[0]}]`, simulate hover on src token 0 → target token 0 gets highlight class; sentence click highlights all target tokens of paired sentence. Commit `feat(client): bidirectional block/sentence/word highlight`.
+
+---
+
+### Task 12 (frontend): admin usage panel
+
+**Files:** Modify `client/src/App.js` / new `client/src/components/UsagePanel.js`.
+
+If an admin key is present (e.g., `localStorage.adminKey` or `?adminKey=`), fetch `/api/result/<token>` admin variant or `/api/admin/usage` with `x-admin-key` and show `model · in/out tokens · $cost` for the current doc. Hidden for non-admin. Commit `feat(client): admin usage panel`.
+
+---
+
+### Task 13: iOS download fix
+
+**Files:** Modify `client/src/App.js` (`handleDownload`) / `DocumentPreview.js`.
+
+Replace blob+`a.download` with a direct anchor: `const a=document.createElement('a'); a.href=`${API_URL}${documentUrl}`; a.download=''; a.click();` (server sends `Content-Disposition: attachment`). Removes the iOS blob-inline behaviour. Commit `fix(client): direct attachment download (iOS Safari)`.
+
+---
+
+### Task 14: light UI refresh + tests/CI green
+
+Tidy result screen layout around the viewer (MUI), responsive two-pane (stack on mobile). Run `npm test` (server) + client tests green. Commit `chore: UI polish + green tests`.
+
+---
+
+### Task 15: deploy + verify
+
+Merge `feat/phase1-viewer` → `main` (PR); on sec: `git pull && docker compose -f docker-compose.prod.yml up -d --build app` (+ set `ADMIN_KEY`, `MAX_SEGMENTS` env). Verify on https://translator.creatman.site: upload the geotech PDF → viewer renders side-by-side; hover a word → pair highlights; sentence/block highlight; admin panel shows tokens/cost; download works on iOS. Log decision to memory.
+
+---
+
+## Acceptance criteria (design §7 🔴)
+- [ ] Viewer renders only via React text nodes; XSS fixture inert (Task 10)
+- [ ] `/api/result/:token` UUID-validated, TTL, `private,no-store`, usage stripped (Task 7)
+- [ ] align strictly validated; invalid → sentence-level, no crash (Tasks 2,6,11)
+- [ ] batch structured-output malformed → per-item fallback, job survives (Task 4,6)
+- [ ] client renders server tokens as-is; NFC; RTL/bidi correct (Tasks 1,10)
+- [ ] cache key carries schemaVersion; no Phase-0 collision (Task 4/6)
+- [ ] segment cap with explicit log (Task 6)
+- [ ] budget admin-gated (ADMIN_KEY); never in public payload (Tasks 7,8)
+- [ ] few LLM calls per doc (chunked), not per-sentence (Task 6)

From 6ab4dcee472fe7288292a5d4b189ceacef55de3c Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 13:58:37 -0400
Subject: [PATCH 04/17] feat: sentence/token segmentation helpers
 (Intl.Segmenter + NFC)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 server/services/__tests__/segmenter.test.js | 19 +++++++
 server/services/segmenter.js                | 56 +++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 server/services/__tests__/segmenter.test.js
 create mode 100644 server/services/segmenter.js

diff --git a/server/services/__tests__/segmenter.test.js b/server/services/__tests__/segmenter.test.js
new file mode 100644
index 0000000..c57fe52
--- /dev/null
+++ b/server/services/__tests__/segmenter.test.js
@@ -0,0 +1,19 @@
+import { describe, it, expect } from 'vitest';
+import { splitSentences, tokenize, nfc } from '../segmenter.js';
+
+describe('segmenter', () => {
+  it('splits into sentences', () => {
+    const s = splitSentences('Hello world. How are you? Fine.');
+    expect(s.length).toBe(3);
+  });
+  it('tokenizes on whitespace, drops empties', () => {
+    expect(tokenize('  שלום   עולם ')).toEqual(['שלום', 'עולם']);
+  });
+  it('nfc-normalizes', () => {
+    // decomposed e + combining acute -> precomposed é
+    expect(nfc('é')).toBe('é');
+  });
+  it('splitSentences returns [] for empty/whitespace', () => {
+    expect(splitSentences('   ')).toEqual([]);
+  });
+});
diff --git a/server/services/segmenter.js b/server/services/segmenter.js
new file mode 100644
index 0000000..e7397b1
--- /dev/null
+++ b/server/services/segmenter.js
@@ -0,0 +1,56 @@
+/**
+ * Sentence and token segmentation helpers.
+ *
+ * Pure functions with no external dependencies. Uses the built-in
+ * Intl.Segmenter (Node >= 18) for locale-aware sentence boundaries, with a
+ * regex fallback. All input is NFC-normalized to keep Hebrew/Latin combining
+ * marks stable across the pipeline.
+ */
+
+/**
+ * Unicode NFC-normalize a value (coerced to string).
+ * @param {*} s
+ * @returns {string}
+ */
+function nfc(s) {
+  return String(s || '').normalize('NFC');
+}
+
+/**
+ * Split text into whitespace-delimited tokens, dropping empties.
+ * @param {string} s
+ * @returns {string[]}
+ */
+function tokenize(s) {
+  return nfc(s).trim().split(/\s+/).filter(Boolean);
+}
+
+/**
+ * Split text into sentences.
+ * Prefers Intl.Segmenter (granularity: 'sentence'); falls back to a
+ * terminator-based regex when Segmenter is unavailable.
+ * @param {string} s
+ * @param {string} [locale='und']
+ * @returns {string[]}
+ */
+function splitSentences(s, locale = 'und') {
+  const text = nfc(s).trim();
+  if (!text) return [];
+
+  if (typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function') {
+    const seg = new Intl.Segmenter(locale, { granularity: 'sentence' });
+    const out = [];
+    for (const part of seg.segment(text)) {
+      const trimmed = part.segment.trim();
+      if (trimmed) out.push(trimmed);
+    }
+    return out;
+  }
+
+  return text
+    .split(/(?<=[.!?。…])\s+/)
+    .map(x => x.trim())
+    .filter(Boolean);
+}
+
+module.exports = { nfc, tokenize, splitSentences };

From 2ce4bb081edb5f38ea09ade253b1cb3413168eae Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 14:00:10 -0400
Subject: [PATCH 05/17] feat: alignment validator (graceful degradation, never
 throws)

---
 server/services/__tests__/align.test.js | 28 +++++++++++++++++++
 server/services/align.js                | 37 +++++++++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 server/services/__tests__/align.test.js
 create mode 100644 server/services/align.js

diff --git a/server/services/__tests__/align.test.js b/server/services/__tests__/align.test.js
new file mode 100644
index 0000000..68be68e
--- /dev/null
+++ b/server/services/__tests__/align.test.js
@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { validateAlign } from '../align.js';
+
+const src = ['a', 'b'], tgt = ['x', 'y'];
+
+describe('validateAlign', () => {
+  it('keeps valid pairs', () => {
+    expect(validateAlign([{ src: [0], tgt: [0] }, { src: [1], tgt: [1] }], src, tgt))
+      .toEqual([{ src: [0], tgt: [0] }, { src: [1], tgt: [1] }]);
+  });
+  it('drops out-of-range groups, returns [] not throw', () => {
+    expect(validateAlign([{ src: [5], tgt: [0] }], src, tgt)).toEqual([]);
+    expect(validateAlign([{ src: [0], tgt: [9] }], src, tgt)).toEqual([]);
+  });
+  it('returns [] for malformed input', () => {
+    expect(validateAlign(null, src, tgt)).toEqual([]);
+    expect(validateAlign('nope', src, tgt)).toEqual([]);
+    expect(validateAlign([{ src: 'x', tgt: [0] }], src, tgt)).toEqual([]);
+    expect(validateAlign([{}], src, tgt)).toEqual([]);
+  });
+  it('keeps valid groups and drops invalid ones in the same array', () => {
+    expect(validateAlign([{ src: [0], tgt: [0] }, { src: [9], tgt: [0] }], src, tgt))
+      .toEqual([{ src: [0], tgt: [0] }]);
+  });
+  it('drops non-integer indices', () => {
+    expect(validateAlign([{ src: [0.5], tgt: [0] }], src, tgt)).toEqual([]);
+  });
+});
diff --git a/server/services/align.js b/server/services/align.js
new file mode 100644
index 0000000..2d1a9c6
--- /dev/null
+++ b/server/services/align.js
@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * Validate and sanitize an LLM-emitted alignment array.
+ *
+ * The LLM emits `align` as an array of `{ src: [tokenIdx...], tgt: [tokenIdx...] }`
+ * groups linking source-sentence tokens to translation tokens. This output is
+ * untrusted: indices may be out of range, non-integer, or the whole structure
+ * may be malformed. This function keeps only valid groups and never throws.
+ * Callers can fall back to sentence-level highlighting when the result is empty.
+ *
+ * @param {unknown} align - candidate alignment array from the LLM
+ * @param {unknown} srcTokens - source-sentence tokens
+ * @param {unknown} tgtTokens - translation tokens
+ * @returns {Array<{src: number[], tgt: number[]}>} sanitized groups (possibly empty)
+ */
+function validateAlign(align, srcTokens, tgtTokens) {
+  if (!Array.isArray(align)) return [];
+
+  const sLen = Array.isArray(srcTokens) ? srcTokens.length : 0;
+  const tLen = Array.isArray(tgtTokens) ? tgtTokens.length : 0;
+
+  const validIdxArray = (a, len) =>
+    Array.isArray(a) &&
+    a.length > 0 &&
+    a.every((i) => Number.isInteger(i) && i >= 0 && i < len);
+
+  const out = [];
+  for (const g of align) {
+    if (g && validIdxArray(g.src, sLen) && validIdxArray(g.tgt, tLen)) {
+      out.push({ src: g.src, tgt: g.tgt });
+    }
+  }
+  return out;
+}
+
+module.exports = { validateAlign };

From 0166df728ccb74eccc2bf86df358b5de5f4342ee Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 14:41:43 -0400
Subject: [PATCH 06/17] feat: TranslationDocument segment builder
 (blocks->sentences, flat refs)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../__tests__/translationDocument.test.js     | 29 ++++++++++
 server/services/translationDocument.js        | 57 +++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100644 server/services/__tests__/translationDocument.test.js
 create mode 100644 server/services/translationDocument.js

diff --git a/server/services/__tests__/translationDocument.test.js b/server/services/__tests__/translationDocument.test.js
new file mode 100644
index 0000000..7a7bea5
--- /dev/null
+++ b/server/services/__tests__/translationDocument.test.js
@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { buildSegments, SCHEMA_VERSION } from '../translationDocument.js';
+
+describe('translationDocument', () => {
+  it('builds blocks->sentences with ids and srcTokens', () => {
+    const blocks = [
+      { type: 'text', content: 'שלום עולם. מה שלומך?' },
+      { type: 'text', content: 'Single line' },
+    ];
+    const { blocks: out, segments } = buildSegments(blocks);
+    expect(out.length).toBe(2);
+    expect(out[0].id).toBe('b0');
+    expect(out[0].sentences.length).toBe(2);            // two Hebrew sentences
+    expect(out[0].sentences[0].id).toBe('b0s0');
+    expect(out[0].sentences[0].srcTokens.length).toBeGreaterThan(0);
+    expect(out[1].sentences[0].id).toBe('b1s0');
+    // flat segments references same objects
+    expect(segments.length).toBe(3);
+    expect(segments[0]).toBe(out[0].sentences[0]);
+  });
+
+  it('skips empty blocks', () => {
+    const { blocks } = buildSegments([{ type: 'text', content: '   ' }, { type: 'text', content: 'Hi.' }]);
+    expect(blocks.length).toBe(1);
+    expect(blocks[0].id).toBe('b1'); // index preserved from original position
+  });
+
+  it('exports SCHEMA_VERSION', () => { expect(SCHEMA_VERSION).toBe(1); });
+});
diff --git a/server/services/translationDocument.js b/server/services/translationDocument.js
new file mode 100644
index 0000000..e6e78b0
--- /dev/null
+++ b/server/services/translationDocument.js
@@ -0,0 +1,57 @@
+/**
+ * TranslationDocument segment builder (pre-translation structure).
+ *
+ * Turns extracted blocks (paragraphs) into a segment-aligned structure:
+ * each block is split into sentences, every sentence gets a stable id and its
+ * source word tokens. A flat `segments` array references the same sentence
+ * objects so later stages can batch-translate and have results flow back into
+ * the block structure (shared object identity).
+ *
+ * Translation/alignment fields are filled in by a later task.
+ */
+
+const { splitSentences, tokenize } = require('./segmenter');
+
+/** Schema version for the produced structure. */
+const SCHEMA_VERSION = 1;
+
+/**
+ * Build the pre-translation segment structure from extracted blocks.
+ *
+ * Blocks whose content has no sentences (empty/whitespace-only) are skipped,
+ * but the original 0-based index is preserved in the generated block id.
+ *
+ * @param {Array<{type?:string,content?:string}>} blocks
+ * @returns {{blocks: Array<{id:string,type:string,sentences:Array<{id:string,source:string,srcTokens:string[]}>}>, segments: Array<{id:string,source:string,srcTokens:string[]}>}}
+ */
+function buildSegments(blocks) {
+  const outBlocks = [];
+  const segments = [];
+
+  const input = Array.isArray(blocks) ? blocks : [];
+
+  input.forEach((block, n) => {
+    const sentencesText = splitSentences(block && block.content);
+    if (sentencesText.length === 0) return; // skip empty blocks
+
+    const sentences = sentencesText.map((source, m) => ({
+      id: `b${n}s${m}`,
+      source,
+      srcTokens: tokenize(source),
+    }));
+
+    outBlocks.push({
+      id: `b${n}`,
+      type: (block && block.type) || 'paragraph',
+      sentences,
+    });
+
+    for (const sentence of sentences) {
+      segments.push(sentence);
+    }
+  });
+
+  return { blocks: outBlocks, segments };
+}
+
+module.exports = { SCHEMA_VERSION, buildSegments };

From af5a9f4a93c3c0e06751e08fdaef2c1597fd0b0e Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 14:48:18 -0400
Subject: [PATCH 07/17] feat: LiteLLM batch translate+align with usage/cost
 capture

---
 server/adapters/ai/LiteLLMProvider.js         | 118 ++++++++++++++++++
 .../ai/__tests__/litellmBatch.test.js         |  53 ++++++++
 2 files changed, 171 insertions(+)
 create mode 100644 server/adapters/ai/__tests__/litellmBatch.test.js

diff --git a/server/adapters/ai/LiteLLMProvider.js b/server/adapters/ai/LiteLLMProvider.js
index 5609252..ae0f663 100644
--- a/server/adapters/ai/LiteLLMProvider.js
+++ b/server/adapters/ai/LiteLLMProvider.js
@@ -106,6 +106,124 @@ If text contains mixed languages, translate only the ${langNames[from]} parts.`;
     }
   }
 
+  /**
+   * Build the system prompt for batch translation + word alignment.
+   * @private
+   */
+  buildBatchSystemPrompt(from, to) {
+    const langNames = { he: 'Hebrew', en: 'English', ru: 'Russian', ar: 'Arabic' };
+    const fromName = langNames[from] || from;
+    const toName = langNames[to] || to;
+
+    return `You are a professional translator ${fromName}->${toName}. ` +
+      `You are given an array of segments, each with an id and its source word tokens (0-indexed). ` +
+      `Return ONLY a JSON object {"items":[{"id":"...","target":"...","align":[{"src":[i],"tgt":[j]}]}]} ` +
+      `where target is the translation and align maps source token indices to target token indices ` +
+      `(target tokens = target split on spaces, 0-indexed). Preserve numbers/dates. Return one item per input id.`;
+  }
+
+  /**
+   * Strip ```json ... ``` (or plain ``` ... ```) fences from a string.
+   * @private
+   */
+  stripFences(content) {
+    let s = String(content).trim();
+    if (s.startsWith('```')) {
+      // remove opening fence (with optional language tag) and trailing fence
+      s = s.replace(/^```[a-zA-Z]*\s*\n?/, '').replace(/\n?```\s*$/, '').trim();
+    }
+    return s;
+  }
+
+  /**
+   * Translate many segments in ONE call and return per-segment word alignments,
+   * plus token usage / cost / the actual model used (differs from alias on fallback).
+   *
+   * @param {Array<{id:string, source:string, srcTokens:string[]}>} segments
+   * @param {string} from
+   * @param {string} to
+   * @returns {Promise<{items:Array<{id:string,target:string,align:any[]}>, usage:object}>}
+   */
+  async translateBatchAligned(segments, from, to) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    let response;
+    try {
+      const userPayload = (segments || []).map((s) => ({
+        id: s.id,
+        source: s.source,
+        srcTokens: s.srcTokens
+      }));
+
+      response = await fetch(`${this.baseURL}/chat/completions`, {
+        method: 'POST',
+        headers: this.buildHeaders(),
+        body: JSON.stringify({
+          model: this.model,
+          messages: [
+            { role: 'system', content: this.buildBatchSystemPrompt(from, to) },
+            { role: 'user', content: JSON.stringify(userPayload) }
+          ],
+          temperature: 0,
+          response_format: { type: 'json_object' }
+        }),
+        signal: controller.signal
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`LiteLLM API error: ${response.status} - ${error}`);
+      }
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === 'AbortError') {
+        throw new Error('Batch translation request timed out');
+      }
+      throw error;
+    }
+
+    const data = await response.json();
+
+    const headerCost = response.headers?.get
+      ? response.headers.get('x-litellm-response-cost')
+      : null;
+
+    const usage = {
+      model: data.model || this.model,
+      promptTokens: data.usage?.prompt_tokens || 0,
+      completionTokens: data.usage?.completion_tokens || 0,
+      totalTokens: data.usage?.total_tokens || 0,
+      costUsd: Number(headerCost ?? data._hidden_params?.response_cost ?? 0) || 0
+    };
+
+    // Parse the model's JSON content defensively. A 200 with junk content must
+    // NOT crash the job — return empty items and let the caller proceed.
+    let items = [];
+    try {
+      const content = data.choices?.[0]?.message?.content;
+      if (typeof content === 'string') {
+        const parsed = JSON.parse(this.stripFences(content));
+        const arr = Array.isArray(parsed) ? parsed : parsed?.items;
+        if (Array.isArray(arr)) {
+          items = arr
+            .filter((it) => it && typeof it.id === 'string' && typeof it.target === 'string')
+            .map((it) => ({
+              id: it.id,
+              target: it.target,
+              align: Array.isArray(it.align) ? it.align : []
+            }));
+        }
+      }
+    } catch {
+      items = [];
+    }
+
+    return { items, usage };
+  }
+
   /**
    * Detect language via the LiteLLM `detect` alias.
    * @param {string} text
diff --git a/server/adapters/ai/__tests__/litellmBatch.test.js b/server/adapters/ai/__tests__/litellmBatch.test.js
new file mode 100644
index 0000000..8d1fc13
--- /dev/null
+++ b/server/adapters/ai/__tests__/litellmBatch.test.js
@@ -0,0 +1,53 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import LiteLLMProvider from '../LiteLLMProvider.js';
+
+const makeRes = (body, { cost = '0.0001' } = {}) => ({
+  ok: true, status: 200,
+  headers: { get: (h) => (h.toLowerCase() === 'x-litellm-response-cost' ? cost : null) },
+  json: async () => body,
+  text: async () => JSON.stringify(body),
+});
+
+let p;
+beforeEach(() => { p = new LiteLLMProvider({ baseURL: 'http://litellm:4000', apiKey: 'sk', model: 'translate' }); });
+afterEach(() => vi.restoreAllMocks());
+
+describe('LiteLLMProvider.translateBatchAligned', () => {
+  it('parses items + usage from a batch response', async () => {
+    global.fetch = vi.fn(async () => makeRes({
+      model: 'gemini/gemini-2.0-flash',
+      usage: { prompt_tokens: 100, completion_tokens: 40, total_tokens: 140 },
+      choices: [{ message: { content: JSON.stringify({ items: [
+        { id: 'b0s0', target: 'Hello world', align: [{ src: [0], tgt: [0] }] }
+      ] }) } }],
+    }));
+    const out = await p.translateBatchAligned([{ id: 'b0s0', source: 'שלום עולם', srcTokens: ['שלום','עולם'] }], 'he', 'en');
+    expect(out.items).toHaveLength(1);
+    expect(out.items[0].target).toBe('Hello world');
+    expect(out.usage.model).toBe('gemini/gemini-2.0-flash');
+    expect(out.usage.totalTokens).toBe(140);
+    expect(out.usage.costUsd).toBeCloseTo(0.0001);
+    expect(global.fetch.mock.calls[0][0]).toBe('http://litellm:4000/chat/completions');
+  });
+
+  it('skips malformed items, keeps valid ones', async () => {
+    global.fetch = vi.fn(async () => makeRes({
+      usage: {}, choices: [{ message: { content: JSON.stringify({ items: [
+        { id: 'b0s0', target: 'ok' }, { id: 'b0s1' /* no target */ }, { target: 'no id' }
+      ] }) } }],
+    }));
+    const out = await p.translateBatchAligned([{ id:'b0s0', source:'a', srcTokens:['a'] }], 'he', 'en');
+    expect(out.items).toEqual([{ id: 'b0s0', target: 'ok', align: [] }]);
+  });
+
+  it('returns items:[] on non-JSON content (200), does not throw', async () => {
+    global.fetch = vi.fn(async () => makeRes({ usage:{}, choices: [{ message: { content: 'not json at all' } }] }));
+    const out = await p.translateBatchAligned([{ id:'b0s0', source:'a', srcTokens:['a'] }], 'he', 'en');
+    expect(out.items).toEqual([]);
+  });
+
+  it('throws on non-ok HTTP', async () => {
+    global.fetch = vi.fn(async () => ({ ok: false, status: 500, text: async () => 'boom', headers: { get: () => null } }));
+    await expect(p.translateBatchAligned([{ id:'b0s0', source:'a', srcTokens:['a'] }], 'he', 'en')).rejects.toThrow();
+  });
+});

From e3eab2103d968d56ec63c47e44276e8224a12b97 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 14:50:20 -0400
Subject: [PATCH 08/17] feat: per-job usage/cost aggregator (byModel + totals +
 owner)

---
 server/services/__tests__/usage.test.js | 30 ++++++++++
 server/services/usage.js                | 79 +++++++++++++++++++++++++
 2 files changed, 109 insertions(+)
 create mode 100644 server/services/__tests__/usage.test.js
 create mode 100644 server/services/usage.js

diff --git a/server/services/__tests__/usage.test.js b/server/services/__tests__/usage.test.js
new file mode 100644
index 0000000..775334d
--- /dev/null
+++ b/server/services/__tests__/usage.test.js
@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest';
+import { newUsage, addCall, finalize } from '../usage.js';
+
+describe('usage aggregator', () => {
+  it('accumulates across calls of same and different models', () => {
+    const u = newUsage();
+    addCall(u, { model:'gemini/gemini-2.0-flash', promptTokens:100, completionTokens:40, totalTokens:140, costUsd:0.001 });
+    addCall(u, { model:'gemini/gemini-2.0-flash', promptTokens:50,  completionTokens:10, totalTokens:60,  costUsd:0.0005 });
+    addCall(u, { model:'openrouter/anthropic/claude-sonnet-4', promptTokens:20, completionTokens:5, totalTokens:25, costUsd:0.01 });
+    expect(u.byModel['gemini/gemini-2.0-flash']).toEqual({ calls:2, in:150, out:50, total:200, costUsd:0.0015 });
+    expect(u.byModel['openrouter/anthropic/claude-sonnet-4'].calls).toBe(1);
+    expect(u.totals).toEqual({ calls:3, in:170, out:55, total:225, costUsd:0.0115 });
+  });
+
+  it('handles missing fields gracefully', () => {
+    const u = newUsage();
+    addCall(u, {});
+    expect(u.byModel['unknown'].calls).toBe(1);
+    expect(u.totals.total).toBe(0);
+  });
+
+  it('finalize stamps owner/jobId/ts', () => {
+    const u = finalize(newUsage(), { owner:'anon', jobId:'1', ts: 123 });
+    expect(u.owner).toBe('anon'); expect(u.jobId).toBe('1'); expect(u.ts).toBe(123);
+  });
+
+  it('finalize defaults owner to anon', () => {
+    expect(finalize(newUsage(), {}).owner).toBe('anon');
+  });
+});
diff --git a/server/services/usage.js b/server/services/usage.js
new file mode 100644
index 0000000..67a914a
--- /dev/null
+++ b/server/services/usage.js
@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * Per-job usage / cost aggregator.
+ *
+ * Phase 1 captures token usage + cost per LLM batch call (see
+ * `LiteLLMProvider.translateBatchAligned`, which returns a `usage` object of the
+ * shape `{ model, promptTokens, completionTokens, totalTokens, costUsd }`).
+ *
+ * This module folds many such per-call usages into a per-document total,
+ * grouped by the actual model used, and stamps owner / job metadata so a future
+ * per-user admin panel can attribute spend.
+ *
+ * No clock is read here: `finalize` takes `ts` as input so callers stay
+ * deterministic and testable.
+ */
+
+/** Shape of a fresh per-bucket accumulator. */
+function emptyBucket() {
+  return { calls: 0, in: 0, out: 0, total: 0, costUsd: 0 };
+}
+
+/** Create an empty usage accumulator. */
+function newUsage() {
+  return { byModel: {}, totals: emptyBucket() };
+}
+
+/** Coerce a possibly-missing numeric field to a finite number, else 0. */
+function num(v) {
+  return Number.isFinite(v) ? v : 0;
+}
+
+/**
+ * Accumulate a single per-call usage record into `usage`.
+ * Missing fields are treated as 0; a missing model is bucketed as 'unknown'.
+ * Mutates and returns `usage`.
+ *
+ * @param {{byModel: object, totals: object}} usage
+ * @param {{model?: string, promptTokens?: number, completionTokens?: number, totalTokens?: number, costUsd?: number}} call
+ */
+function addCall(usage, call) {
+  const c = call || {};
+  const model = c.model || 'unknown';
+  const inTok = num(c.promptTokens);
+  const outTok = num(c.completionTokens);
+  const totalTok = num(c.totalTokens);
+  const cost = num(c.costUsd);
+
+  if (!usage.byModel[model]) usage.byModel[model] = emptyBucket();
+
+  for (const bucket of [usage.byModel[model], usage.totals]) {
+    bucket.calls += 1;
+    bucket.in += inTok;
+    bucket.out += outTok;
+    bucket.total += totalTok;
+    bucket.costUsd += cost;
+  }
+
+  return usage;
+}
+
+/**
+ * Stamp owner / job metadata onto a usage object and return a shallow copy.
+ * `ts` is passed in (never read from a clock here) for testability.
+ *
+ * @param {{byModel: object, totals: object}} usage
+ * @param {{owner?: string, jobId?: string|number|null, ts?: number|null}} meta
+ */
+function finalize(usage, meta) {
+  const m = meta || {};
+  return {
+    ...usage,
+    owner: m.owner ?? 'anon',
+    jobId: m.jobId ?? null,
+    ts: m.ts ?? null,
+  };
+}
+
+module.exports = { newUsage, addCall, finalize };

From 41f31bbbb559b8e2e21a3e8df57b5cfc1e2e9038 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 14:53:07 -0400
Subject: [PATCH 09/17] feat: pipeline assembly (chunking +
 buildTranslationDocument, segment cap)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 server/services/__tests__/pipeline.test.js |  53 +++++++
 server/services/pipeline.js                | 159 +++++++++++++++++++++
 2 files changed, 212 insertions(+)
 create mode 100644 server/services/__tests__/pipeline.test.js
 create mode 100644 server/services/pipeline.js

diff --git a/server/services/__tests__/pipeline.test.js b/server/services/__tests__/pipeline.test.js
new file mode 100644
index 0000000..6abc4b4
--- /dev/null
+++ b/server/services/__tests__/pipeline.test.js
@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { chunkSegments, buildTranslationDocument } from '../pipeline.js';
+
+const seg = (id, toks) => ({ id, source: toks.join(' '), srcTokens: toks });
+
+describe('chunkSegments', () => {
+  it('splits by count', () => {
+    const segs = Array.from({length:40}, (_,i)=>seg('s'+i, ['a']));
+    const chunks = chunkSegments(segs, { maxPerChunk: 18, maxTokens: 9999 });
+    expect(chunks.length).toBe(3); // 18,18,4
+    expect(chunks[0].length).toBe(18);
+  });
+  it('splits by token budget', () => {
+    const segs = [seg('a', Array(1000).fill('x')), seg('b', Array(1000).fill('y'))];
+    const chunks = chunkSegments(segs, { maxPerChunk: 18, maxTokens: 1500 });
+    expect(chunks.length).toBe(2);
+  });
+});
+
+describe('buildTranslationDocument', () => {
+  const fakeBatch = async (chunk) => ({
+    items: chunk.map(s => ({ id: s.id, target: s.srcTokens.map(t=>t.toUpperCase()).join(' '), align: s.srcTokens.map((_,i)=>({src:[i],tgt:[i]})) })),
+    usage: { model:'fake', promptTokens:10, completionTokens:5, totalTokens:15, costUsd:0.001 },
+  });
+  it('fills targets, tgtTokens, validated align; aggregates usage', async () => {
+    const { blocks } = { blocks: [{ id:'b0', type:'paragraph', sentences:[ seg('b0s0',['ab','cd']) ] }] };
+    const segments = blocks[0].sentences;
+    const doc = await buildTranslationDocument({ blocks, segments }, fakeBatch, { sourceLang:'he', targetLang:'en' });
+    const s = doc.blocks[0].sentences[0];
+    expect(s.target).toBe('AB CD');
+    expect(s.tgtTokens).toEqual(['AB','CD']);
+    expect(s.align).toEqual([{src:[0],tgt:[0]},{src:[1],tgt:[1]}]);
+    expect(doc.schemaVersion).toBe(1);
+    expect(doc.usage.totals.total).toBe(15);
+    expect(doc.usage.owner).toBe('anon');
+  });
+  it('passes through untranslated when item missing', async () => {
+    const emptyBatch = async () => ({ items: [], usage: null });
+    const blocks = [{ id:'b0', type:'paragraph', sentences:[ seg('b0s0',['x']) ] }];
+    const doc = await buildTranslationDocument({ blocks, segments: blocks[0].sentences }, emptyBatch, { sourceLang:'he', targetLang:'en' });
+    expect(doc.blocks[0].sentences[0].target).toBe('x');
+    expect(doc.blocks[0].sentences[0].align).toEqual([]);
+  });
+  it('applies segment cap and calls onCap', async () => {
+    let capInfo = null;
+    const blocks = [{ id:'b0', type:'paragraph', sentences: Array.from({length:5},(_,i)=>seg('b0s'+i,['w'])) }];
+    const doc = await buildTranslationDocument({ blocks, segments: blocks[0].sentences }, fakeBatch,
+      { sourceLang:'he', targetLang:'en', maxSegments: 3, onCap: (i)=>{capInfo=i;} });
+    expect(capInfo).toEqual({ total:5, cap:3 });
+    expect(doc.blocks[0].sentences[0].target).toBe('W');   // translated
+    expect(doc.blocks[0].sentences[4].target).toBe('w');   // capped -> source
+  });
+});
diff --git a/server/services/pipeline.js b/server/services/pipeline.js
new file mode 100644
index 0000000..4e59aa0
--- /dev/null
+++ b/server/services/pipeline.js
@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * Translation pipeline assembly core.
+ *
+ * Pure, side-effect-light orchestration that turns a pre-translation segment
+ * structure (from `translationDocument.buildSegments`) into a complete
+ * `TranslationDocument` by calling a batch-translate function.
+ *
+ * Two concerns:
+ *  - `chunkSegments`: pack ordered segments into translation chunks bounded by
+ *    both a segment count and a source-token budget.
+ *  - `buildTranslationDocument`: cap, chunk, translate with bounded concurrency,
+ *    fold results back into the shared segment/block objects, and aggregate
+ *    usage into a finalized document.
+ *
+ * The translate function is injected (in prod it wraps
+ * `LiteLLMProvider.translateBatchAligned`; in tests a fake), keeping this module
+ * deterministic and unit-testable.
+ */
+
+const { tokenize } = require('./segmenter');
+const { validateAlign } = require('./align');
+const { newUsage, addCall, finalize } = require('./usage');
+const { SCHEMA_VERSION } = require('./translationDocument');
+
+/**
+ * Pack ordered segments into chunks, starting a new chunk when adding the next
+ * segment would exceed either `maxPerChunk` (count) or `maxTokens` (accumulated
+ * srcTokens length). A single segment whose token count alone exceeds the budget
+ * still occupies its own chunk.
+ *
+ * @param {Array<{srcTokens?: string[]}>} segments
+ * @param {{maxPerChunk?: number, maxTokens?: number}} [opts]
+ * @returns {Array<Array<object>>}
+ */
+function chunkSegments(segments, { maxPerChunk = 18, maxTokens = 1500 } = {}) {
+  const out = [];
+  const list = Array.isArray(segments) ? segments : [];
+
+  let current = [];
+  let curTokens = 0;
+
+  for (const seg of list) {
+    const segTokens = Array.isArray(seg.srcTokens) ? seg.srcTokens.length : 0;
+
+    if (
+      current.length > 0 &&
+      (current.length + 1 > maxPerChunk || curTokens + segTokens > maxTokens)
+    ) {
+      out.push(current);
+      current = [];
+      curTokens = 0;
+    }
+
+    current.push(seg);
+    curTokens += segTokens;
+  }
+
+  if (current.length > 0) out.push(current);
+  return out;
+}
+
+/**
+ * Process chunks through `translateBatch` in waves of `concurrency`, returning
+ * the flat array of per-chunk results in chunk order.
+ */
+async function translateChunks(chunks, translateBatch, concurrency) {
+  const width = Math.max(1, concurrency | 0);
+  const results = [];
+
+  for (let i = 0; i < chunks.length; i += width) {
+    const wave = chunks.slice(i, i + width);
+    const settled = await Promise.all(
+      wave.map((chunk) =>
+        translateBatch(
+          chunk.map((s) => ({ id: s.id, source: s.source, srcTokens: s.srcTokens })),
+        ),
+      ),
+    );
+    for (const r of settled) results.push(r);
+  }
+
+  return results;
+}
+
+/**
+ * Build a complete TranslationDocument from a segment structure.
+ *
+ * Mutates the shared segment objects in place (they share identity with the
+ * sentences inside `blocks`), so block sentences reflect the translation.
+ *
+ * @param {{blocks: Array<object>, segments: Array<{id:string,source:string,srcTokens:string[]}>}} structure
+ * @param {(chunk: Array<{id:string,source:string,srcTokens:string[]}>) => Promise<{items:Array<{id:string,target?:string,align?:unknown}>, usage?:object}>} translateBatch
+ * @param {{sourceLang?:string,targetLang?:string,maxSegments?:number,concurrency?:number,owner?:string,jobId?:string|number|null,ts?:number|null,onCap?:(info:{total:number,cap:number})=>void}} [opts]
+ * @returns {Promise<object>} the finalized translation document
+ */
+async function buildTranslationDocument(structure, translateBatch, opts = {}) {
+  const { blocks = [], segments = [] } = structure || {};
+  const {
+    sourceLang,
+    targetLang,
+    maxSegments = 1500,
+    concurrency = 3,
+    owner = 'anon',
+    jobId = null,
+    ts = null,
+    onCap = null,
+  } = opts;
+
+  // Segment cap: only the first `maxSegments` are translated; the rest pass
+  // through as source.
+  let toTranslate = segments;
+  if (segments.length > maxSegments) {
+    toTranslate = segments.slice(0, maxSegments);
+    if (typeof onCap === 'function') {
+      onCap({ total: segments.length, cap: maxSegments });
+    }
+  }
+
+  // Chunk + translate with bounded concurrency.
+  const chunks = chunkSegments(toTranslate, opts);
+  const chunkResults = await translateChunks(chunks, translateBatch, concurrency);
+
+  // Aggregate usage and build id -> item map.
+  const usage = newUsage();
+  const byId = new Map();
+  for (const result of chunkResults) {
+    if (result && result.usage) addCall(usage, result.usage);
+    const items = result && Array.isArray(result.items) ? result.items : [];
+    for (const item of items) {
+      if (item && item.id != null) byId.set(item.id, item);
+    }
+  }
+
+  // Fold results back into every segment (capped ones get the pass-through path).
+  for (const seg of segments) {
+    const item = byId.get(seg.id);
+    if (item && typeof item.target === 'string') {
+      seg.target = item.target;
+      seg.tgtTokens = tokenize(item.target);
+      seg.align = validateAlign(item.align, seg.srcTokens, seg.tgtTokens);
+    } else {
+      seg.target = seg.source;
+      seg.tgtTokens = [...seg.srcTokens];
+      seg.align = [];
+    }
+  }
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    sourceLang,
+    targetLang,
+    blocks,
+    usage: finalize(usage, { owner, jobId, ts }),
+  };
+}
+
+module.exports = { chunkSegments, buildTranslationDocument };

From 9f28030f5b2c35dd7f0e709d7772d6ac989e87f5 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 14:56:05 -0400
Subject: [PATCH 10/17] feat: result store + wire batch-aligned pipeline into
 worker (resultToken)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 server/api/translate.js                       | 42 +++++++---
 server/services/__tests__/resultStore.test.js | 24 ++++++
 server/services/resultStore.js                | 79 +++++++++++++++++++
 3 files changed, 134 insertions(+), 11 deletions(-)
 create mode 100644 server/services/__tests__/resultStore.test.js
 create mode 100644 server/services/resultStore.js

diff --git a/server/api/translate.js b/server/api/translate.js
index 6f05a9b..c7650b4 100644
--- a/server/api/translate.js
+++ b/server/api/translate.js
@@ -7,14 +7,20 @@ const crypto = require('crypto');
 const fs = require('fs').promises;
 const { v4: uuidv4 } = require('uuid');
 const DocumentProcessor = require('../documentProcessor');
-const { createTranslator } = require('../core/translation');
 const { toBlocks } = require('../services/textDocument');
+const { buildSegments } = require('../services/translationDocument');
+const { buildTranslationDocument } = require('../services/pipeline');
+const LiteLLMProvider = require('../adapters/ai/LiteLLMProvider');
+const { saveResult } = require('../services/resultStore');
 const { validateMagicBytes } = require('../middleware/fileValidation');
 const { emitToSession } = require('../socket/rooms');
 
 // Инициализируем сервисы
 const documentProcessor = new DocumentProcessor();
-const translator = createTranslator();
+const aiProvider = new LiteLLMProvider();
+
+// Жёсткий предел на число сегментов в одном документе (DoS-guard + бюджет).
+const MAX_SEGMENTS = Number(process.env.MAX_SEGMENTS) || 1500;
 
 // Создаем очередь для обработки документов
 const documentQueue = new Queue('document-processing', {
@@ -39,7 +45,8 @@ documentQueue.on('completed', (job, result) => {
   emitToSession(io, job.data.sessionId, 'translation:complete', {
     jobId: job.id,
     message: 'Перевод завершен',
-    downloadUrl: `/api/download/${result.filename}`
+    downloadUrl: `/api/download/${result.filename}`,
+    resultToken: result.resultToken
   });
 });
 
@@ -58,26 +65,39 @@ documentQueue.process('translate', async (job) => {
     
     // Обновляем прогресс: Начало обработки
     await job.progress(10);
-    
+
     // Обрабатываем документ (плоский текст)
     const processed = await documentProcessor.processDocument(filePath, targetLang);
-    await job.progress(50);
+    await job.progress(40);
 
-    // Разбиваем на блоки и переводим
-    const blocks = toBlocks(processed.content);
-    const translatedBlocks = await translator.translateDocument(blocks, targetLang);
+    // Разбиваем на блоки и сегменты, затем строим TranslationDocument
+    const rawBlocks = toBlocks(processed.content);
+    const { blocks: docBlocks, segments } = buildSegments(rawBlocks);
+    const doc = await buildTranslationDocument(
+      { blocks: docBlocks, segments },
+      (chunk) => aiProvider.translateBatchAligned(chunk, sourceLang || 'he', targetLang),
+      { sourceLang: sourceLang || 'he', targetLang, maxSegments: MAX_SEGMENTS, concurrency: 3,
+        owner: 'anon', jobId: String(job.id), ts: Date.now(),
+        onCap: (info) => console.warn(`Segment cap hit: ${info.total} > ${info.cap} (job ${job.id})`) }
+    );
     await job.progress(80);
 
-    // Генерируем переведенный файл с непредсказуемым именем-токеном
+    // result for the viewer
+    const resultToken = crypto.randomUUID();
+    saveResult(resultToken, doc);
+
+    // downloadable file: flatten translated sentences per block
+    const fileBlocks = doc.blocks.map(b => ({ type: 'text', content: b.sentences.map(s => s.target).join(' ') }));
     const outputPath = path.join(
       path.dirname(filePath),
       `translated_${crypto.randomUUID()}${path.extname(filePath)}`
     );
-    await documentProcessor.generateTranslatedDocument(translatedBlocks, outputPath);
+    await documentProcessor.generateTranslatedDocument(fileBlocks, outputPath);
     await job.progress(100);
-    
+
     return {
       filename: path.basename(outputPath),
+      resultToken,
       success: true
     };
   } catch (error) {
diff --git a/server/services/__tests__/resultStore.test.js b/server/services/__tests__/resultStore.test.js
new file mode 100644
index 0000000..edc1a74
--- /dev/null
+++ b/server/services/__tests__/resultStore.test.js
@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { saveResult, getResult, recentUsage } from '../resultStore.js';
+
+describe('resultStore', () => {
+  it('save/get round-trip', () => {
+    saveResult('tok1', { schemaVersion: 1, blocks: [], usage: { totals: { total: 5 } } }, 1000, 0);
+    expect(getResult('tok1', 500)).toMatchObject({ schemaVersion: 1 });
+  });
+
+  it('expires after ttl', () => {
+    saveResult('tok2', { blocks: [] }, 1000, 0);
+    expect(getResult('tok2', 2000)).toBeNull();
+  });
+
+  it('missing -> null', () => {
+    expect(getResult('nope')).toBeNull();
+  });
+
+  it('recentUsage lists docs with usage', () => {
+    saveResult('tokU', { blocks: [], usage: { totals: { total: 9 } } }, 100000, 0);
+    const r = recentUsage(10).find((x) => x.token === 'tokU');
+    expect(r.usage.totals.total).toBe(9);
+  });
+});
diff --git a/server/services/resultStore.js b/server/services/resultStore.js
new file mode 100644
index 0000000..2d5b40b
--- /dev/null
+++ b/server/services/resultStore.js
@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * In-memory result store for translated documents.
+ *
+ * Single-process app: the Bull worker and the API run in the same Node process,
+ * so this module-level Map is shared between them. Each entry holds the produced
+ * TranslationDocument and an absolute expiry timestamp; expired entries are
+ * lazily evicted on read and proactively cleaned up via a scheduled timer.
+ *
+ * `now` is injectable on the read/write entry points so tests can exercise TTL
+ * behaviour deterministically without real timers.
+ */
+
+const store = new Map();
+
+const DEFAULT_TTL_MS = 15 * 60 * 1000;
+
+/**
+ * Store a translation document under `token` with a TTL.
+ *
+ * @param {string} token
+ * @param {object} doc finalized TranslationDocument
+ * @param {number} [ttlMs] time-to-live in ms
+ * @param {number} [now] current epoch ms (injectable for tests)
+ */
+function saveResult(token, doc, ttlMs = DEFAULT_TTL_MS, now = Date.now()) {
+  store.set(token, { doc, expires: now + ttlMs });
+
+  // Proactive cleanup so the Map doesn't grow unbounded. Guarded so it doesn't
+  // keep the event loop alive and never fires when ttl isn't a real duration.
+  if (ttlMs > 0 && typeof setTimeout === 'function') {
+    const timer = setTimeout(() => {
+      const entry = store.get(token);
+      if (entry && entry.expires <= Date.now()) store.delete(token);
+    }, ttlMs);
+    if (timer && typeof timer.unref === 'function') timer.unref();
+  }
+}
+
+/**
+ * Fetch a stored document by token, or `null` if missing/expired.
+ * Expired entries are deleted on access.
+ *
+ * @param {string} token
+ * @param {number} [now] current epoch ms (injectable for tests)
+ * @returns {object|null}
+ */
+function getResult(token, now = Date.now()) {
+  const entry = store.get(token);
+  if (!entry) return null;
+  if (entry.expires <= now) {
+    store.delete(token);
+    return null;
+  }
+  return entry.doc;
+}
+
+/**
+ * List recently stored docs that carry a `usage` field, most-recent first.
+ * Used by the admin usage endpoint.
+ *
+ * @param {number} [limit]
+ * @returns {Array<{token: string, usage: object}>}
+ */
+function recentUsage(limit = 50) {
+  const out = [];
+  // Map preserves insertion order; iterate newest-first.
+  const entries = Array.from(store.entries()).reverse();
+  for (const [token, entry] of entries) {
+    if (entry && entry.doc && entry.doc.usage) {
+      out.push({ token, usage: entry.doc.usage });
+      if (out.length >= limit) break;
+    }
+  }
+  return out;
+}
+
+module.exports = { saveResult, getResult, recentUsage };

From 1b87a2f020eed0275e36e864551467e4c7eb91c1 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 15:01:14 -0400
Subject: [PATCH 11/17] feat: hardened GET /api/result/:token (token-validated,
 usage stripped, no-store)

---
 server/api/__tests__/result.test.js | 35 +++++++++++++++++++++++++++++
 server/api/translate.js             | 26 ++++++++++++++++++++-
 2 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 server/api/__tests__/result.test.js

diff --git a/server/api/__tests__/result.test.js b/server/api/__tests__/result.test.js
new file mode 100644
index 0000000..1a1d16f
--- /dev/null
+++ b/server/api/__tests__/result.test.js
@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import router from '../translate.js';
+import { createRequire } from 'module';
+
+// translate.js is a CommonJS module that vitest externalizes to native Node
+// (it pulls in bull/multer/etc.). Its `require('../services/resultStore')`
+// therefore resolves to the *native* module instance, not the ESM-transformed
+// copy a plain `import` would give us. To share the same in-memory store the
+// route reads from, we must save through that same native instance.
+const require = createRequire(import.meta.url);
+const { saveResult } = require('../../services/resultStore.js');
+
+const app = express();
+app.use('/api', router);
+
+describe('GET /api/result/:token', () => {
+  it('400 on bad token', async () => {
+    const r = await request(app).get('/api/result/..%2f');
+    expect(r.status).toBe(400);
+  });
+  it('404 on missing', async () => {
+    const r = await request(app).get('/api/result/deadbeef-0000-1111');
+    expect(r.status).toBe(404);
+  });
+  it('200 returns doc without usage, with no-store', async () => {
+    saveResult('aaaabbbb-cccc-dddd', { schemaVersion:1, sourceLang:'he', targetLang:'en', blocks:[{id:'b0'}], usage:{secret:true} });
+    const r = await request(app).get('/api/result/aaaabbbb-cccc-dddd');
+    expect(r.status).toBe(200);
+    expect(r.body.blocks).toHaveLength(1);
+    expect(r.body.usage).toBeUndefined();          // usage stripped
+    expect(r.headers['cache-control']).toMatch(/no-store/);
+  });
+});
diff --git a/server/api/translate.js b/server/api/translate.js
index c7650b4..d70d576 100644
--- a/server/api/translate.js
+++ b/server/api/translate.js
@@ -11,7 +11,7 @@ const { toBlocks } = require('../services/textDocument');
 const { buildSegments } = require('../services/translationDocument');
 const { buildTranslationDocument } = require('../services/pipeline');
 const LiteLLMProvider = require('../adapters/ai/LiteLLMProvider');
-const { saveResult } = require('../services/resultStore');
+const { saveResult, getResult } = require('../services/resultStore');
 const { validateMagicBytes } = require('../middleware/fileValidation');
 const { emitToSession } = require('../socket/rooms');
 
@@ -249,6 +249,10 @@ router.post('/translate', (req, res) => {
 const DOWNLOAD_FILENAME_RE = /^translated_[0-9a-fA-F-]+\.(pdf|docx)$/;
 const DOWNLOAD_TTL_MS = Number(process.env.DOWNLOAD_TTL_MS) || 15 * 60 * 1000;
 
+// Допустимый формат токена результата: hex-символы и дефисы (UUID-подобный),
+// минимум 8 символов. Отсекает path-traversal и любой мусор до обращения в стор.
+const RESULT_TOKEN_RE = /^[0-9a-fA-F-]{8,}$/;
+
 // Маршрут для скачивания переведенного документа
 router.get('/download/:filename', async (req, res) => {
   try {
@@ -284,4 +288,24 @@ router.get('/download/:filename', async (req, res) => {
   }
 });
 
+// Маршрут просмотра результата перевода по токену.
+// Возвращает TranslationDocument без админского поля usage; payload приватный.
+router.get('/result/:token', (req, res) => {
+  const token = req.params.token;
+  if (!RESULT_TOKEN_RE.test(token)) {
+    return res.status(400).json({ success: false, message: 'invalid token' });
+  }
+
+  const doc = getResult(token);
+  if (!doc) {
+    return res.status(404).json({ success: false, message: 'not found' });
+  }
+
+  // Документ содержит полный текст перевода — запрещаем кэширование.
+  res.set('Cache-Control', 'private, no-store');
+  // Снимаем админ-only поле usage перед отдачей наружу.
+  const { usage, ...pub } = doc;
+  res.json(pub);
+});
+
 module.exports = router;
\ No newline at end of file

From a05cf63767fc20fe842126db39f108af9386b2f6 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 15:03:23 -0400
Subject: [PATCH 12/17] feat: ADMIN_KEY-gated /api/admin/usage (per-owner
 aggregation)

---
 server/api/__tests__/adminUsage.test.js | 33 ++++++++++++++++++++++
 server/api/translate.js                 | 37 ++++++++++++++++++++++++-
 2 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 server/api/__tests__/adminUsage.test.js

diff --git a/server/api/__tests__/adminUsage.test.js b/server/api/__tests__/adminUsage.test.js
new file mode 100644
index 0000000..640f662
--- /dev/null
+++ b/server/api/__tests__/adminUsage.test.js
@@ -0,0 +1,33 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+let app;
+beforeAll(() => {
+  process.env.ADMIN_KEY = 'secret123';
+  const router = require('../translate.js');           // CJS instance
+  const { saveResult } = require('../../services/resultStore.js'); // same instance as route
+  saveResult('admintok-1111-2222', { schemaVersion:1, blocks:[], usage:{
+    byModel:{ 'gemini/gemini-2.0-flash': {calls:2,in:150,out:50,total:200,costUsd:0.0015} },
+    totals:{ calls:2,in:150,out:50,total:200,costUsd:0.0015 }, owner:'anon', jobId:'1', ts:1 } });
+  app = express(); app.use('/api', router);
+});
+
+describe('GET /api/admin/usage', () => {
+  it('401 without key', async () => {
+    const r = await request(app).get('/api/admin/usage');
+    expect(r.status).toBe(401);
+  });
+  it('401 with wrong key', async () => {
+    const r = await request(app).get('/api/admin/usage').set('x-admin-key','nope');
+    expect(r.status).toBe(401);
+  });
+  it('200 with valid key, grouped by owner', async () => {
+    const r = await request(app).get('/api/admin/usage').set('x-admin-key','secret123');
+    expect(r.status).toBe(200);
+    expect(r.body.byOwner.anon.total).toBeGreaterThanOrEqual(200);
+    expect(Array.isArray(r.body.jobs)).toBe(true);
+  });
+});
diff --git a/server/api/translate.js b/server/api/translate.js
index d70d576..ca8d8d3 100644
--- a/server/api/translate.js
+++ b/server/api/translate.js
@@ -11,7 +11,7 @@ const { toBlocks } = require('../services/textDocument');
 const { buildSegments } = require('../services/translationDocument');
 const { buildTranslationDocument } = require('../services/pipeline');
 const LiteLLMProvider = require('../adapters/ai/LiteLLMProvider');
-const { saveResult, getResult } = require('../services/resultStore');
+const { saveResult, getResult, recentUsage } = require('../services/resultStore');
 const { validateMagicBytes } = require('../middleware/fileValidation');
 const { emitToSession } = require('../socket/rooms');
 
@@ -308,4 +308,39 @@ router.get('/result/:token', (req, res) => {
   res.json(pub);
 });
 
+// Админский эндпоинт расхода токенов/стоимости, сгруппированный по owner.
+// Гейт строгий: нет ADMIN_KEY в окружении ИЛИ заголовок не совпадает → 401.
+// Это скрывает данные о стоимости от публики и future-proof'ит per-user панель.
+router.get('/admin/usage', (req, res) => {
+  const adminKey = process.env.ADMIN_KEY;
+  if (!adminKey || req.get('x-admin-key') !== adminKey) {
+    return res.status(401).json({ success: false, message: 'unauthorized' });
+  }
+
+  const rows = recentUsage(100);
+  const byOwner = {};
+  for (const { usage } of rows) {
+    const owner = usage.owner || 'anon';
+    const o = byOwner[owner] || (byOwner[owner] = { jobs: 0, calls: 0, in: 0, out: 0, total: 0, costUsd: 0 });
+    o.jobs += 1;
+    o.calls += usage.totals?.calls || 0;
+    o.in += usage.totals?.in || 0;
+    o.out += usage.totals?.out || 0;
+    o.total += usage.totals?.total || 0;
+    o.costUsd += usage.totals?.costUsd || 0;
+  }
+
+  res.set('Cache-Control', 'private, no-store');
+  res.json({
+    byOwner,
+    jobs: rows.map(r => ({
+      token: r.token,
+      owner: r.usage.owner,
+      jobId: r.usage.jobId,
+      totals: r.usage.totals,
+      byModel: r.usage.byModel
+    }))
+  });
+});
+
 module.exports = router;
\ No newline at end of file

From 596366628ed9177ce9528b0914fe1cecfe1dea17 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 15:08:39 -0400
Subject: [PATCH 13/17] feat(client): side-by-side viewer with XSS-safe render
 + sync highlight

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 client/src/components/SideBySideViewer.js     | 179 ++++++++++++++++++
 .../__tests__/SideBySideViewer.test.js        |  37 ++++
 2 files changed, 216 insertions(+)
 create mode 100644 client/src/components/SideBySideViewer.js
 create mode 100644 client/src/components/__tests__/SideBySideViewer.test.js

diff --git a/client/src/components/SideBySideViewer.js b/client/src/components/SideBySideViewer.js
new file mode 100644
index 0000000..a6ede39
--- /dev/null
+++ b/client/src/components/SideBySideViewer.js
@@ -0,0 +1,179 @@
+import React, { useState, useCallback, useMemo } from 'react';
+import { Box, Grid, Paper, Typography } from '@mui/material';
+
+// Build a Set-membership key for a token span.
+const tokenKey = (side, blockId, sentenceId, tokenIdx) =>
+  `${side}:${blockId}:${sentenceId}:${tokenIdx}`;
+
+const HL_COLOR = '#fff59d'; // light yellow highlight
+
+/**
+ * SideBySideViewer
+ * Renders a TranslationDocument as two synchronized panes:
+ *   left  = source (dir="rtl")
+ *   right = target (dir="ltr")
+ *
+ * Security: ALL token/sentence text is rendered as React text children.
+ * dangerouslySetInnerHTML is never used, so any HTML inside a token shows
+ * up as literal text and cannot be injected into the DOM.
+ *
+ * Highlighting: hover/click a token to highlight aligned token(s) on the
+ * other side (word-level when `align` is present, otherwise whole-sentence
+ * fallback). Clicking the sentence wrapper highlights the paired sentence
+ * on both sides.
+ */
+function SideBySideViewer({ doc }) {
+  // Set<string> of highlighted token keys (see tokenKey()).
+  const [highlighted, setHighlighted] = useState(() => new Set());
+
+  // Index sentences by `${blockId}:${sentenceId}` for fast lookup.
+  const sentenceIndex = useMemo(() => {
+    const map = new Map();
+    (doc?.blocks || []).forEach((block) => {
+      (block.sentences || []).forEach((sentence) => {
+        map.set(`${block.id}:${sentence.id}`, { block, sentence });
+      });
+    });
+    return map;
+  }, [doc]);
+
+  // Highlight every token of a sentence on both sides.
+  const highlightWholeSentence = useCallback((blockId, sentence) => {
+    const next = new Set();
+    (sentence.srcTokens || []).forEach((_, i) =>
+      next.add(tokenKey('src', blockId, sentence.id, i))
+    );
+    (sentence.tgtTokens || []).forEach((_, i) =>
+      next.add(tokenKey('tgt', blockId, sentence.id, i))
+    );
+    setHighlighted(next);
+  }, []);
+
+  // Highlight from a single hovered/clicked token.
+  const highlightFromToken = useCallback(
+    (side, blockId, sentence, tokenIdx) => {
+      const next = new Set();
+      // The token itself is always highlighted.
+      next.add(tokenKey(side, blockId, sentence.id, tokenIdx));
+
+      const align = sentence.align;
+      const otherSide = side === 'src' ? 'tgt' : 'src';
+
+      if (!align || align.length === 0) {
+        // Word-level alignment unavailable: fall back to whole paired sentence.
+        highlightWholeSentence(blockId, sentence);
+        // Also re-include the hovered token (already in set above) so the
+        // hovered side keeps its own highlight.
+        return;
+      }
+
+      const fromKey = side === 'src' ? 'src' : 'tgt';
+      const toKey = side === 'src' ? 'tgt' : 'src';
+      align.forEach((group) => {
+        const fromIdxs = group[fromKey] || [];
+        if (fromIdxs.includes(tokenIdx)) {
+          (group[toKey] || []).forEach((j) =>
+            next.add(tokenKey(otherSide, blockId, sentence.id, j))
+          );
+        }
+      });
+
+      setHighlighted(next);
+    },
+    [highlightWholeSentence]
+  );
+
+  const clearHighlight = useCallback(() => {
+    setHighlighted((prev) => (prev.size === 0 ? prev : new Set()));
+  }, []);
+
+  const renderTokens = (side, block, sentence) => {
+    const tokens = side === 'src' ? sentence.srcTokens : sentence.tgtTokens;
+    return (tokens || []).map((tok, i) => {
+      const key = tokenKey(side, block.id, sentence.id, i);
+      const isHl = highlighted.has(key);
+      return (
+        <React.Fragment key={key}>
+          {i > 0 ? ' ' : null}
+          <span
+            data-side={side}
+            data-block={block.id}
+            data-sentence={sentence.id}
+            data-token={i}
+            className={isHl ? 'hl' : undefined}
+            style={{
+              backgroundColor: isHl ? HL_COLOR : undefined,
+              borderRadius: 3,
+              cursor: 'pointer',
+            }}
+            onMouseEnter={() => highlightFromToken(side, block.id, sentence, i)}
+            onMouseLeave={clearHighlight}
+            onClick={(e) => {
+              // Token click acts like hover-highlight; stop it from also
+              // triggering the sentence-level click handler.
+              e.stopPropagation();
+              highlightFromToken(side, block.id, sentence, i);
+            }}
+          >
+            {/* Rendered as a text child => XSS-safe, never HTML. */}
+            {tok}
+          </span>
+        </React.Fragment>
+      );
+    });
+  };
+
+  const renderPane = (side) => {
+    const dir = side === 'src' ? 'rtl' : 'ltr';
+    return (
+      <Box dir={dir} sx={{ p: 2 }}>
+        {(doc?.blocks || []).map((block) => (
+          <Box
+            key={`${side}:${block.id}`}
+            data-block-wrapper={block.id}
+            component="p"
+            sx={{ my: 1, lineHeight: 1.8 }}
+          >
+            {(block.sentences || []).map((sentence) => (
+              <span
+                key={`${side}:${block.id}:${sentence.id}`}
+                data-sentence-wrapper={sentence.id}
+                // Sentence-level click (when not on a token) highlights the
+                // entire paired sentence on both sides.
+                onClick={() => highlightWholeSentence(block.id, sentence)}
+                style={{
+                  // unicodeBidi: plaintext keeps mixed Hebrew + Latin/numbers
+                  // rendering in correct visual order.
+                  unicodeBidi: 'plaintext',
+                }}
+              >
+                {renderTokens(side, block, sentence)}{' '}
+              </span>
+            ))}
+          </Box>
+        ))}
+      </Box>
+    );
+  };
+
+  return (
+    <Paper sx={{ mt: 2, p: 2 }} data-testid="side-by-side-viewer">
+      <Grid container spacing={2}>
+        <Grid item xs={12} md={6}>
+          <Typography variant="subtitle2" gutterBottom>
+            {doc?.sourceLang ? doc.sourceLang.toUpperCase() : 'Source'}
+          </Typography>
+          {renderPane('src')}
+        </Grid>
+        <Grid item xs={12} md={6}>
+          <Typography variant="subtitle2" gutterBottom>
+            {doc?.targetLang ? doc.targetLang.toUpperCase() : 'Target'}
+          </Typography>
+          {renderPane('tgt')}
+        </Grid>
+      </Grid>
+    </Paper>
+  );
+}
+
+export default SideBySideViewer;
diff --git a/client/src/components/__tests__/SideBySideViewer.test.js b/client/src/components/__tests__/SideBySideViewer.test.js
new file mode 100644
index 0000000..f6a5c2a
--- /dev/null
+++ b/client/src/components/__tests__/SideBySideViewer.test.js
@@ -0,0 +1,37 @@
+import React from 'react';
+import { render, screen, fireEvent, within } from '@testing-library/react';
+import SideBySideViewer from '../SideBySideViewer';
+
+const doc = {
+  schemaVersion:1, sourceLang:'he', targetLang:'en',
+  blocks:[{ id:'b0', type:'paragraph', sentences:[
+    { id:'b0s0', source:'שלום עולם', target:'Hello world',
+      srcTokens:['שלום','עולם'], tgtTokens:['Hello','world'],
+      align:[{src:[0],tgt:[0]},{src:[1],tgt:[1]}] }
+  ]}]
+};
+
+test('renders source and target tokens', () => {
+  render(<SideBySideViewer doc={doc} />);
+  expect(screen.getByText('שלום')).toBeInTheDocument();
+  expect(screen.getByText('Hello')).toBeInTheDocument();
+});
+
+test('XSS: a token with HTML is rendered as literal text, not injected', () => {
+  const evil = { schemaVersion:1, sourceLang:'he', targetLang:'en', blocks:[{ id:'b0', type:'paragraph', sentences:[
+    { id:'b0s0', source:'x', target:'<img src=x onerror=alert(1)>',
+      srcTokens:['x'], tgtTokens:['<img','src=x','onerror=alert(1)>'], align:[] }
+  ]}]};
+  const { container } = render(<SideBySideViewer doc={evil} />);
+  expect(container.querySelector('img')).toBeNull();           // no element injected
+  expect(screen.getByText('<img', { exact:false })).toBeInTheDocument(); // literal text present
+});
+
+test('hovering a source token highlights the aligned target token', () => {
+  const { container } = render(<SideBySideViewer doc={doc} />);
+  const srcTok0 = container.querySelector('[data-side="src"][data-block="b0"][data-sentence="b0s0"][data-token="0"]');
+  fireEvent.mouseEnter(srcTok0);
+  const tgtTok0 = container.querySelector('[data-side="tgt"][data-block="b0"][data-sentence="b0s0"][data-token="0"]');
+  // highlighted token gets a non-empty backgroundColor (or hl class)
+  expect(tgtTok0.className.includes('hl') || tgtTok0.style.backgroundColor).toBeTruthy();
+});

From 6085c4b902c625c3d55c92579d6a48feef7ddd6e Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 15:11:48 -0400
Subject: [PATCH 14/17] feat(client): fetch TranslationDocument on completion
 and render side-by-side viewer

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 client/src/App.js      | 13 +++++++++++++
 client/src/App.test.js | 14 +++++++++++---
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/client/src/App.js b/client/src/App.js
index a70cc97..4c4ca42 100644
--- a/client/src/App.js
+++ b/client/src/App.js
@@ -5,6 +5,7 @@ import io from 'socket.io-client';
 import DocumentUpload from './components/DocumentUpload';
 import TranslationProgress from './components/TranslationProgress';
 import DocumentPreview from './components/DocumentPreview';
+import SideBySideViewer from './components/SideBySideViewer';
 
 // API origin: пусто => тот же origin, что и страница (прод, через Traefik).
 // В dev задаётся через client/.env.development (REACT_APP_API_URL=http://localhost:3001).
@@ -20,6 +21,7 @@ function App() {
   });
 
   const [socket, setSocket] = React.useState(null);
+  const [translationDoc, setTranslationDoc] = React.useState(null);
 
   // Стабильный идентификатор сессии: события прогресса приходят только в нашу комнату
   const sessionId = useMemo(
@@ -56,6 +58,13 @@ function App() {
         progress: 100,
         documentUrl: data.downloadUrl
       }));
+
+      if (data.resultToken) {
+        fetch(`${API_URL}/api/result/${data.resultToken}`)
+          .then(r => r.ok ? r.json() : null)
+          .then(doc => { if (doc) setTranslationDoc(doc); })
+          .catch(() => {});
+      }
     });
 
     socket.on('translation:error', (data) => {
@@ -75,6 +84,7 @@ function App() {
 
   const handleFileUpload = async (file, targetLang) => {
     try {
+      setTranslationDoc(null);
       setTranslationState({
         status: 'uploading',
         progress: 0,
@@ -142,6 +152,7 @@ function App() {
   };
 
   const handleReset = () => {
+    setTranslationDoc(null);
     setTranslationState({
       status: 'idle',
       progress: 0,
@@ -183,6 +194,8 @@ function App() {
               onDownload={handleDownload}
             />
           )}
+
+          {translationDoc && <SideBySideViewer doc={translationDoc} />}
         </Box>
       </Container>
     </SnackbarProvider>
diff --git a/client/src/App.test.js b/client/src/App.test.js
index 1f03afe..1cf9dec 100644
--- a/client/src/App.test.js
+++ b/client/src/App.test.js
@@ -1,8 +1,16 @@
 import { render, screen } from '@testing-library/react';
+
+// socket.io-client is mocked so the test never opens a real connection.
+jest.mock('socket.io-client', () => ({
+  __esModule: true,
+  default: () => ({ on: jest.fn(), off: jest.fn(), close: jest.fn() }),
+}));
+
 import App from './App';
 
-test('renders learn react link', () => {
+test('App mounts without crashing', () => {
   render(<App />);
-  const linkElement = screen.getByText(/learn react/i);
-  expect(linkElement).toBeInTheDocument();
+  expect(
+    screen.getByText(/Переводчик документов с иврита/i)
+  ).toBeInTheDocument();
 });

From b07132d0547da24b7319f9185ecf91c581802c6a Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 15:12:40 -0400
Subject: [PATCH 15/17] fix(client): direct attachment download (reliable on
 iOS Safari)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 client/src/App.js | 28 ++++++++++++----------------
 1 file changed, 12 insertions(+), 16 deletions(-)

diff --git a/client/src/App.js b/client/src/App.js
index 4c4ca42..afdc330 100644
--- a/client/src/App.js
+++ b/client/src/App.js
@@ -132,23 +132,19 @@ function App() {
     }
   };
 
-  const handleDownload = async () => {
+  const handleDownload = () => {
     if (!translationState.documentUrl) return;
-    
-    try {
-      const response = await fetch(translationState.documentUrl);
-      const blob = await response.blob();
-      const url = window.URL.createObjectURL(blob);
-      const a = document.createElement('a');
-      a.href = url;
-      a.download = `translated_${translationState.originalName}`;
-      document.body.appendChild(a);
-      a.click();
-      window.URL.revokeObjectURL(url);
-      document.body.removeChild(a);
-    } catch (error) {
-      console.error('Download error:', error);
-    }
+    // Direct anchor to the server's attachment URL (server sends
+    // Content-Disposition: attachment). More reliable than a blob+download on
+    // iOS Safari, which ignores the download attribute for blob: URLs and opens
+    // them inline instead.
+    const a = document.createElement('a');
+    a.href = `${API_URL}${translationState.documentUrl}`;
+    a.download = '';
+    a.rel = 'noopener';
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
   };
 
   const handleReset = () => {

From 890b6833765a567892e08f44bb965dd0136ce9f7 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 15:16:29 -0400
Subject: [PATCH 16/17] feat(client): admin usage panel (tokens/cost/model,
 admin-key gated)

---
 client/src/App.js                             |  8 ++
 client/src/components/UsagePanel.js           | 77 +++++++++++++++++++
 .../components/__tests__/UsagePanel.test.js   | 21 +++++
 3 files changed, 106 insertions(+)
 create mode 100644 client/src/components/UsagePanel.js
 create mode 100644 client/src/components/__tests__/UsagePanel.test.js

diff --git a/client/src/App.js b/client/src/App.js
index afdc330..2b2c40b 100644
--- a/client/src/App.js
+++ b/client/src/App.js
@@ -6,6 +6,7 @@ import DocumentUpload from './components/DocumentUpload';
 import TranslationProgress from './components/TranslationProgress';
 import DocumentPreview from './components/DocumentPreview';
 import SideBySideViewer from './components/SideBySideViewer';
+import UsagePanel from './components/UsagePanel';
 
 // API origin: пусто => тот же origin, что и страница (прод, через Traefik).
 // В dev задаётся через client/.env.development (REACT_APP_API_URL=http://localhost:3001).
@@ -22,6 +23,7 @@ function App() {
 
   const [socket, setSocket] = React.useState(null);
   const [translationDoc, setTranslationDoc] = React.useState(null);
+  const [resultToken, setResultToken] = React.useState(null);
 
   // Стабильный идентификатор сессии: события прогресса приходят только в нашу комнату
   const sessionId = useMemo(
@@ -59,6 +61,8 @@ function App() {
         documentUrl: data.downloadUrl
       }));
 
+      setResultToken(data.resultToken || null);
+
       if (data.resultToken) {
         fetch(`${API_URL}/api/result/${data.resultToken}`)
           .then(r => r.ok ? r.json() : null)
@@ -85,6 +89,7 @@ function App() {
   const handleFileUpload = async (file, targetLang) => {
     try {
       setTranslationDoc(null);
+      setResultToken(null);
       setTranslationState({
         status: 'uploading',
         progress: 0,
@@ -149,6 +154,7 @@ function App() {
 
   const handleReset = () => {
     setTranslationDoc(null);
+    setResultToken(null);
     setTranslationState({
       status: 'idle',
       progress: 0,
@@ -191,6 +197,8 @@ function App() {
             />
           )}
 
+          <UsagePanel resultToken={resultToken} />
+
           {translationDoc && <SideBySideViewer doc={translationDoc} />}
         </Box>
       </Container>
diff --git a/client/src/components/UsagePanel.js b/client/src/components/UsagePanel.js
new file mode 100644
index 0000000..dcf969d
--- /dev/null
+++ b/client/src/components/UsagePanel.js
@@ -0,0 +1,77 @@
+import React from 'react';
+import { Paper, Typography, Box } from '@mui/material';
+
+// Re-derived here so the component is self-contained (same value as App.js).
+const API_URL = process.env.REACT_APP_API_URL || '';
+
+/**
+ * UsagePanel — admin-only cost/usage readout for a finished translation job.
+ *
+ * Security: renders NOTHING unless an admin key is present (localStorage
+ * 'adminKey' or ?adminKey= query param). The public /api/result payload has
+ * usage stripped, so cost data is fetched from the admin-gated endpoint and
+ * must never be shown to public users.
+ */
+function UsagePanel({ resultToken }) {
+  const params = new URLSearchParams(window.location.search);
+  const adminKey = params.get('adminKey') || localStorage.getItem('adminKey');
+
+  const [job, setJob] = React.useState(null);
+
+  React.useEffect(() => {
+    if (!adminKey || !resultToken) {
+      setJob(null);
+      return;
+    }
+    let cancelled = false;
+    fetch(`${API_URL}/api/admin/usage`, { headers: { 'x-admin-key': adminKey } })
+      .then((r) => (r.ok ? r.json() : null))
+      .then((data) => {
+        if (cancelled || !data || !Array.isArray(data.jobs)) return;
+        const match = data.jobs.find((j) => j.token === resultToken) || null;
+        setJob(match);
+      })
+      .catch(() => {
+        // Errors → render nothing for this fetch.
+        if (!cancelled) setJob(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [adminKey, resultToken]);
+
+  // Gate: no admin key or no token → render nothing (public users).
+  if (!adminKey || !resultToken) return null;
+
+  const totals = job && job.totals ? job.totals : null;
+  const byModel = job && job.byModel ? job.byModel : {};
+
+  return (
+    <Paper sx={{ mt: 2, p: 2 }} data-testid="usage-panel">
+      <Typography variant="subtitle2" gutterBottom>
+        Обработка (admin)
+      </Typography>
+      {!totals ? (
+        <Typography variant="body2">—</Typography>
+      ) : (
+        <Box>
+          <Typography variant="body2">
+            Токены: in {totals.in} · out {totals.out} · total {totals.total}
+          </Typography>
+          <Typography variant="body2">
+            Стоимость: ${Number(totals.costUsd || 0).toFixed(4)}
+          </Typography>
+          <Box sx={{ mt: 1 }}>
+            {Object.entries(byModel).map(([model, m]) => (
+              <Typography key={model} variant="caption" component="div" color="text.secondary">
+                {model} · {m.calls} calls · ${Number(m.costUsd || 0).toFixed(4)}
+              </Typography>
+            ))}
+          </Box>
+        </Box>
+      )}
+    </Paper>
+  );
+}
+
+export default UsagePanel;
diff --git a/client/src/components/__tests__/UsagePanel.test.js b/client/src/components/__tests__/UsagePanel.test.js
new file mode 100644
index 0000000..464ff4b
--- /dev/null
+++ b/client/src/components/__tests__/UsagePanel.test.js
@@ -0,0 +1,21 @@
+import React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import UsagePanel from '../UsagePanel';
+
+afterEach(() => { localStorage.clear(); jest.restoreAllMocks(); });
+
+test('renders nothing without admin key', () => {
+  const { container } = render(<UsagePanel resultToken="tok1" />);
+  expect(container.firstChild).toBeNull();
+});
+
+test('shows usage when admin key present', async () => {
+  localStorage.setItem('adminKey', 'secret');
+  global.fetch = jest.fn(async () => ({ ok:true, json: async () => ({
+    byOwner:{}, jobs:[{ token:'tok1', owner:'anon', jobId:'1',
+      totals:{calls:2,in:150,out:50,total:200,costUsd:0.0015},
+      byModel:{ 'gemini/gemini-2.0-flash': {calls:2,in:150,out:50,total:200,costUsd:0.0015} } }] }) }));
+  render(<UsagePanel resultToken="tok1" />);
+  await waitFor(() => expect(screen.getByText(/200/)).toBeInTheDocument());
+  expect(screen.getByText(/gemini/i)).toBeInTheDocument();
+});

From 7197bb0f54712b6f41ad962a589767172dc1ee61 Mon Sep 17 00:00:00 2001
From: Creatman <creatmanick@gmail.com>
Date: Wed, 3 Jun 2026 15:19:13 -0400
Subject: [PATCH 17/17] chore(client): drop unused sentenceIndex memo (lint
 clean); Phase 1 tests green

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 client/src/components/SideBySideViewer.js | 13 +------------
 1 file changed, 1 insertion(+), 12 deletions(-)

diff --git a/client/src/components/SideBySideViewer.js b/client/src/components/SideBySideViewer.js
index a6ede39..8c4f2cc 100644
--- a/client/src/components/SideBySideViewer.js
+++ b/client/src/components/SideBySideViewer.js
@@ -1,4 +1,4 @@
-import React, { useState, useCallback, useMemo } from 'react';
+import React, { useState, useCallback } from 'react';
 import { Box, Grid, Paper, Typography } from '@mui/material';
 
 // Build a Set-membership key for a token span.
@@ -26,17 +26,6 @@ function SideBySideViewer({ doc }) {
   // Set<string> of highlighted token keys (see tokenKey()).
   const [highlighted, setHighlighted] = useState(() => new Set());
 
-  // Index sentences by `${blockId}:${sentenceId}` for fast lookup.
-  const sentenceIndex = useMemo(() => {
-    const map = new Map();
-    (doc?.blocks || []).forEach((block) => {
-      (block.sentences || []).forEach((sentence) => {
-        map.set(`${block.id}:${sentence.id}`, { block, sentence });
-      });
-    });
-    return map;
-  }, [doc]);
-
   // Highlight every token of a sentence on both sides.
   const highlightWholeSentence = useCallback((blockId, sentence) => {
     const next = new Set();