ProxyPrints
diff --git a/‎docs/proposals/proposal-b-bleed-normalization.md‎
Lines changed: 8 additions & 6 deletions b/‎docs/proposals/proposal-b-bleed-normalization.md‎
Lines changed: 8 additions & 6 deletions
diff --git a/‎docs/reports/proposal-b-pr1-bleed-prior-batch-resolution.md‎
Lines changed: 82 additions & 0 deletions b/‎docs/reports/proposal-b-pr1-bleed-prior-batch-resolution.md‎
Lines changed: 82 additions & 0 deletions
diff --git a/‎frontend/src/common/concurrencyLimit.test.ts‎
Lines changed: 66 additions & 0 deletions b/‎frontend/src/common/concurrencyLimit.test.ts‎
Lines changed: 66 additions & 0 deletions
diff --git a/‎frontend/src/common/concurrencyLimit.ts‎
Lines changed: 33 additions & 0 deletions b/‎frontend/src/common/concurrencyLimit.ts‎
Lines changed: 33 additions & 0 deletions
@@ -24,7 +24,7 @@ Core: at PDF export, for each card (full-res bitmap already in hand): MEASURE ac
 ## Implementation notes (added during build, not part of the approved spec above)
 
 - **The "same confidence-fill path" genuinely exists, corrected from an earlier wrong read**: an initial pass over this concluded no per-arbitrary-card confidence lookup existed (only `QuestionFeedItem.tagConfidence`, one-at-a-time from the questionFeed queue) and treated that as a spec contradiction. That was wrong - `store/api.ts`'s `APIGetTagConsensus(backendURL, identifier)` (backing `TagVotePicker.tsx`, a different but genuinely equivalent attribute-voting surface) already does exactly this: a per-card `POST 2/tagConsensus/` returning `TagConsensusEntry[]` with a graded `netPolarity` per tag, including whatever `appropriate-bleed` votes exist. No new endpoint needed after all - the spec's own instruction stands as written.
-- **What IS still a real gap, not a contradiction**: `APIGetTagConsensus` needs `document.cookie` (via `getCSRFHeader()`) for its CSRF header, and `document` doesn't exist inside `pdf.worker.ts`'s Web Worker context, where the actual render runs. So this can't be called from inside the worker - it has to run on the MAIN thread (`PDFGenerator.tsx`, which already has cookie/Redux access) as a batch pre-resolution step *before* `pdfRenderService.renderPDF(...)` is invoked, producing a plain `{[identifier]: BleedPrior}` map that gets passed into `PDFProps.bleedPriors` (already wired to accept it - see below). That batch-fetch step itself (N cards, needs a concurrency bound and per-card failure tolerance so one flaky lookup doesn't fail the whole export) is real, separate work that has NOT been built yet - see "Shipped vs. not yet built" below. Interpreted "unresolved" per the literal spec text (a missing entry, or a `netPolarity` that isn't clearly positive) as bucketing with "trimmed" for the fallback (extend full target) - the spec's FALLBACK line is an exhaustive two-way split ("machine says bleed -> X; trimmed or unresolved -> Y"), not three-way.
+- **What IS still a real gap, not a contradiction**: `APIGetTagConsensus` needs `document.cookie` (via `getCSRFHeader()`) for its CSRF header, and `document` doesn't exist inside `pdf.worker.ts`'s Web Worker context, where the actual render runs. So this can't be called from inside the worker - it has to run on the MAIN thread (`PDFGenerator.tsx`, which already has cookie/Redux access) as a batch pre-resolution step _before_ `pdfRenderService.renderPDF(...)` is invoked, producing a plain `{[identifier]: BleedPrior}` map that gets passed into `PDFProps.bleedPriors` (already wired to accept it - see below). That batch-fetch step itself (N cards, needs a concurrency bound and per-card failure tolerance so one flaky lookup doesn't fail the whole export) is real, separate work that has NOT been built yet - see "Shipped vs. not yet built" below. Interpreted "unresolved" per the literal spec text (a missing entry, or a `netPolarity` that isn't clearly positive) as bucketing with "trimmed" for the fallback (extend full target) - the spec's FALLBACK line is an exhaustive two-way split ("machine says bleed -> X; trimmed or unresolved -> Y"), not three-way.
 - Everything else in the spec matched the current codebase directly (dpi is a real field on `CardDocument`, the `BleedEdgeMM`/`CardWidthMM`/`CardHeightMM` constants are exactly what the measurement's px→mm conversion needs, `PDFCardImage`'s existing per-card async image resolution is already the right per-card hook point for "measure, normalize, draw, release").
 - react-pdf's own internal concurrency for resolving multiple `<Image src={async () => ...}>` callbacks across a page is inside the `@react-pdf/renderer` library, not this codebase — not independently controllable or verifiable from here without forking that library. "No per-page Promise.all fan-out" is honored in the sense that matters (the code this session adds does no new fan-out of its own — measurement + extension both happen inside the same single per-card async callback `PDFCardImage` already uses, and nothing new here calls `Promise.all` over multiple cards); it is not a claim that react-pdf's own scheduling was audited or changed.
 - Persistence (decision 4, project state, flag XML rather than build it): not yet touched. No `bleedOverrides` reducer/state exists in `projectSlice` yet, since the manual-override UI itself isn't built (see below) - nothing to persist yet. When the UI lands, per the owner's answer: project state (`projectSlice`), not session-only. XML round-trip: flagging per the owner's explicit instruction rather than building it - `ExportXML.tsx`/`ImportXML.tsx` would need a new optional per-member field (e.g. `<bleedOverride>`) to carry a manual override through a save/reload cycle; not added this pass.
@@ -34,9 +34,11 @@ Core: at PDF export, for each card (full-res bitmap already in hand): MEASURE ac
 
 **Shipped, tested, wired into the real render path** (`frontend/src/features/pdf/bleedNormalize.ts` + `.test.ts`, `bleedExtension.ts` + `.test.ts`, `pdfImage.ts`'s `getPDFImageBlob` split + tests, `PDF.tsx`'s `PDFCardImage`): the full measure → resolve-plan → crop/extend → encode pipeline, all three `ManualOverride` modes, the effective-dpi derivation (source dpi vs. a lower requested `imageDPI`), all 6 required synthetic fixtures plus 2 manual-override tests plus 4 geometry tests plus 4 `pdfImage` tests (26 new tests total, all passing; zero regressions in the pre-existing suite). Every named constant (`PROBE_COUNT`, `RGB_DISTANCE_THRESHOLD`, `IQR_AMBIGUITY_FRACTION`, `OVERSIZED_MULTIPLE`) carries its calibration caveat comment per the spec.
 
+**PR-1 (this pass) — shipped**: the main-thread batch resolution of `bleedPriors` via `APIGetTagConsensus`, bounded concurrency (`frontend/src/common/concurrencyLimit.ts`'s `mapWithConcurrencyLimit`, a general-purpose worker-pool utility - not GoogleDriveService's own private `Semaphore`, to keep this PR's review surface to new files only; default concurrency 6, matching that class's own default), per-card failure tolerance (a single failed lookup degrades to `"unresolved"`, never fails the whole batch), wired into `PDFGenerator.tsx`'s `downloadPDF`/`saveToDrivePDF` (resolved once per export, before the render call, skipped entirely when no remote backend is configured). 13 new tests (6 for the concurrency utility, 7 for the resolution logic itself). Verified against the real render path too: `tests/PDFGenerator.spec.ts`'s full suite (which has no `tagConsensus` mock at all) still passes at the same timing as before this PR, confirming an unmocked/failing lookup degrades gracefully rather than hanging or failing the export.
+
 **Not yet built** (concrete next steps, not silently dropped):
-1. `PDFGenerator.tsx`'s main-thread batch resolution of `bleedPriors` via `APIGetTagConsensus` - until this exists, every card's ambiguous sides use the safe "unresolved" default (extend full target) rather than a real machine-vote lean.
-2. The manual-override UI (Auto / Force bleed / Force trimmed per card) in the export panel, and its `projectSlice` persistence.
-3. The WYSIWYG preview badge ("bleed will be generated") in `PagePreview.tsx`.
-4. The XML optional field for a persisted override, if/when the UI above lands (flagged per the owner's own instruction, not built).
-5. The merge-time server-side calibration pass (~20-30 real catalog images) for the four named constants above.
+
+1. The manual-override UI (Auto / Force bleed / Force trimmed per card) in the export panel, and its `projectSlice` persistence (Proposal B PR-2).
+2. The WYSIWYG preview badge ("bleed will be generated") in `PagePreview.tsx` (Proposal B PR-3).
+3. The XML optional field for a persisted override, if/when PR-2's UI lands (flagged per the owner's own instruction, not built).
+4. The merge-time server-side calibration pass (~20-30 real catalog images) for the four named measurement constants.
@@ -0,0 +1,82 @@
+As of: 2026-07-18
+Task: Proposal B deferred PR-1 — batch prior-resolution
+Branch: `claude/e2-bleed-prior-batch-resolution` (stacked on `claude/proposal-b-bleed-normalization`, PR #66)
+
+## What shipped
+
+The main-thread, concurrency-bounded batch fetch of each export card's `appropriate-bleed`
+machine-vote lean, via the existing `APIGetTagConsensus` endpoint (`store/api.ts` — no new
+endpoint, per the approved spec). This populates `PDFProps.bleedPriors`, which `PDF.tsx`'s
+`PDFCardImage` (built in PR #66) already reads and defaults safely to `"unresolved"` when
+absent — this PR is what actually populates it with real data instead of that default.
+
+**Why main thread, not the render worker**: `APIGetTagConsensus`'s CSRF header needs
+`document.cookie` (`getCSRFHeader()`, `common/cookies.ts`), and `document` doesn't exist inside
+`pdf.worker.ts`'s Web Worker context. The resolved `{[identifier]: BleedPrior}` map is plain,
+structured-clone-safe data — it crosses the main-thread → worker boundary the same way every
+other `PDFProps` field already does, no new plumbing needed there.
+
+### New files
+
+- `frontend/src/common/concurrencyLimit.ts` — `mapWithConcurrencyLimit<T, R>(items, concurrency,
+  fn)`, a general-purpose bounded-concurrency map (worker-pool-over-an-index-cursor, not
+  fixed-size batching — a worker claims the next unclaimed index the instant it's free, rather
+  than waiting for a whole batch to finish). Deliberately a new, separate utility rather than
+  reusing `GoogleDriveService.ts`'s own private `Semaphore` class — that class isn't exported,
+  and extracting/refactoring it would have expanded this PR's review surface into an unrelated
+  file for a small win. 6 tests: order preservation, concurrency actually bounded (not
+  serialized), every item processed exactly once, empty input, concurrency > item count,
+  rejection propagation (no built-in per-item error tolerance — that's the caller's job).
+- `frontend/src/features/pdf/bleedPriorResolution.ts` — `resolveBleedPriors(backendURL,
+  identifiers, concurrency?)`. Deduplicates identifiers, fetches each unique card's
+  `TagConsensusResponse` via `APIGetTagConsensus`, maps the `appropriate-bleed` entry's
+  `netPolarity` to a `BleedPrior`: clearly positive → `"bleed"`, clearly negative → `"trimmed"`,
+  missing entry or zero/near-zero → `"unresolved"` (this 3-way split is for code
+  clarity/debugging — `resolveBleedPlan`'s own fallback already treats `"trimmed"` and
+  `"unresolved"` identically, extending the full target). A single card's lookup failure (network
+  blip, rate limit, an identifier the backend doesn't recognize) is caught internally and degrades
+  that one card to `"unresolved"` — never fails the whole batch. Concurrency defaults to 6,
+  matching `GoogleDriveService`'s own existing default (`BLEED_PRIOR_RESOLUTION_CONCURRENCY`, a
+  named constant, not empirically tuned for this specific endpoint but a reasonable,
+  already-precedented starting point). 7 tests covering every branch of the netPolarity mapping,
+  the failure-tolerance behavior, deduplication, and the empty-input case.
+
+### Changed files
+
+- `frontend/src/features/pdf/PDFGenerator.tsx` — `downloadPDF`/`saveToDrivePDF` both gained a
+  `backendURL: string | null` parameter; each now calls `resolveBleedPriors` once, right before
+  `pdfRenderService.renderPDF(...)`, using `Object.keys(props.cardDocumentsByIdentifier)` as the
+  export's own card set (already deduplicated by that map's construction). Skipped entirely
+  (`bleedPriors` stays `undefined`) when no remote backend is configured — matches
+  `PDFCardImage`'s existing safe default, no special-casing needed downstream. `useDownloadPDF`/
+  `useSaveToDrivePDF` thread the new parameter through; the main component now selects
+  `backendURL` via `selectRemoteBackendURL` (`store/slices/backendSlice.ts`) and passes it to
+  both hooks.
+
+## Verification
+
+- `npx tsc --noEmit`: clean.
+- `npx eslint` on all new/changed files: 0 errors/warnings.
+- `npx prettier@2.7.1 --write`: applied.
+- Full `npx jest --runInBand`: **282/282 passing** (269 from PR #66's own build + 13 new this
+  pass), zero regressions.
+- Full `npx playwright test tests/PDFGenerator.spec.ts`: **4/4 passing**, same timing as before
+  this PR (17–27s per test, no hang, no new failure). This suite has **no `tagConsensus` mock at
+  all** — every card's lookup genuinely fails (unmocked request) during this run, which is
+  exactly the failure-tolerance path `resolveSingleBleedPrior`'s try/catch exists for. Passing
+  cleanly here is real, end-to-end confirmation that an unmocked/failing batch degrades to
+  `"unresolved"` per card rather than hanging or failing the export — not just an assertion in a
+  unit test.
+
+## Deviations
+
+None from the authorized scope. One implementation detail worth flagging: `mapWithConcurrencyLimit`
+was built as a new, separate utility rather than extracting `GoogleDriveService`'s existing
+`Semaphore` — a deliberate choice to keep this PR's diff to new files plus `PDFGenerator.tsx`'s
+own wiring, not a refactor of an unrelated, already-working module. If a shared concurrency
+primitive across both features is wanted later, that's a clean, separate follow-up.
+
+## Open items
+
+None blocking. PR-2 (manual-override UI + persistence) and PR-3 (preview badge) remain queued
+behind this, per the standing order (B PR-2 → PR-3 → C part (b) → E-3 → F).
@@ -0,0 +1,66 @@
+import { mapWithConcurrencyLimit } from "@/common/concurrencyLimit";
+
+describe("mapWithConcurrencyLimit", () => {
+  it("returns results in item order regardless of completion order", async () => {
+    const delays = [30, 10, 20, 0];
+    const results = await mapWithConcurrencyLimit(
+      delays,
+      4,
+      (delayMs, index) =>
+        new Promise<number>((resolve) =>
+          setTimeout(() => resolve(index), delayMs)
+        )
+    );
+    expect(results).toEqual([0, 1, 2, 3]);
+  });
+
+  it("never exceeds the concurrency limit at any point in time", async () => {
+    let active = 0;
+    let maxActive = 0;
+    const items = Array.from({ length: 10 }, (_, i) => i);
+    await mapWithConcurrencyLimit(items, 3, async () => {
+      active++;
+      maxActive = Math.max(maxActive, active);
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      active--;
+    });
+    expect(maxActive).toBeLessThanOrEqual(3);
+    expect(maxActive).toBeGreaterThan(1); // confirms it's genuinely concurrent, not serialized
+  });
+
+  it("processes every item exactly once", async () => {
+    const items = Array.from({ length: 25 }, (_, i) => i);
+    const seen: number[] = [];
+    await mapWithConcurrencyLimit(items, 4, async (item) => {
+      seen.push(item);
+    });
+    expect(seen.slice().sort((a, b) => a - b)).toEqual(items);
+  });
+
+  it("handles an empty input without hanging", async () => {
+    const results = await mapWithConcurrencyLimit(
+      [],
+      4,
+      async () => "unreachable"
+    );
+    expect(results).toEqual([]);
+  });
+
+  it("handles a concurrency limit larger than the item count", async () => {
+    const results = await mapWithConcurrencyLimit(
+      [1, 2],
+      10,
+      async (item) => item * 2
+    );
+    expect(results).toEqual([2, 4]);
+  });
+
+  it("propagates a rejection from fn (no built-in per-item error tolerance)", async () => {
+    await expect(
+      mapWithConcurrencyLimit([1, 2, 3], 2, async (item) => {
+        if (item === 2) throw new Error("boom");
+        return item;
+      })
+    ).rejects.toThrow("boom");
+  });
+});
@@ -0,0 +1,33 @@
+/**
+ * Bounded-concurrency map: runs `fn` over every item in `items`, at most `concurrency` calls
+ * in flight at once, returning results in the same order as `items` regardless of completion
+ * order. A worker-pool-over-an-index-cursor implementation - each of `concurrency` workers
+ * repeatedly claims the next unclaimed index until none remain, rather than chunking `items`
+ * into fixed-size batches (which would leave workers idle once a batch's slowest call is still
+ * running while faster ones in the same batch have already finished).
+ *
+ * Does not itself catch or retry per-item failures - a rejection from `fn` propagates through
+ * Promise.all and fails the whole call, same as a bare Promise.all would. Callers that need "one
+ * item's failure shouldn't fail the batch" (e.g. bleedPriorResolution.ts) catch inside their own
+ * `fn`, not here - keeps this a general-purpose primitive.
+ */
+export async function mapWithConcurrencyLimit<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  fn: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = new Array(items.length);
+  let nextIndex = 0;
+
+  const worker = async (): Promise<void> => {
+    while (nextIndex < items.length) {
+      const index = nextIndex++;
+      results[index] = await fn(items[index], index);
+    }
+  };
+
+  const workerCount = Math.max(1, Math.min(concurrency, items.length));
+  await Promise.all(Array.from({ length: workerCount }, worker));
+
+  return results;
+}