Maintainer decision, 2026-07-29: adopts TRSL V1C1 as this repo's
preliminary governing license, per target-revenue's
workplans/TREV-WP-0008-governance-and-pilot-rollout.md T05. Full
specialist legal review is deferred until out of beta (target-revenue
SCOPE.md §1). No Phase is yet declared for this repo.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Cut review mode over to the extracted citation-work package instead of a local
src/work/ implementation.
- Add @citation-evidence/work as a link: dependency
- Repoint the @work alias (tsconfig + vite) to ../citation-work/src/work and
allow vite fs access to the sibling
- Remove the local src/work/ implementation (now owned by citation-work)
Typecheck, lint, and the full test suite (51 tests) pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Cut over the binder subsystem to the extracted @citation-evidence/
evidence-binder repo. The @binder alias (tsconfig + vite) now points at
../evidence-binder/src, the duplicate src/binder/ tree is deleted, and
vite fs.allow is widened to serve the sibling checkout.
No app code changed — all imports were already via the @binder alias.
typecheck + lint green, 58 tests passing.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the in-repo src/anchor/ slice with a dependency on the extracted
@citation-evidence/evidence-anchor package (link:../evidence-anchor).
- package.json: add the link dependency
- repoint all @anchor/{index,selectors,types} imports and vi.mock targets to
the package barrel; the node-env anchor-source-roundtrip test uses the pure
./selectors and ./types subpaths (no pdfjs pulled into a node environment)
- drop the @anchor alias from tsconfig paths and vite resolve
- delete src/anchor/ (behavior now owned by evidence-anchor)
Verified green: pnpm typecheck, pnpm test (26 files / 95 tests), pnpm build.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the unfilled template with the umbrella's actual boundary:
app/viewer/session + anchoring/evidence/binders in scope; headless
ingest (evidence-source) and contracts (citation-engine) out of scope.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the local src/source PDF slice with the standalone
@citation-evidence/evidence-source package (link:../evidence-source).
- src/source/index.ts is now a thin façade re-exporting the ingest core
and browser upload helpers from the package
- viewer-url stays local (viewer concern) but takes PdfByteStore from
the package
- extracted ingest/extract/fingerprint/byte-store/upload files removed
- anchor-source round-trip integration test now exercises the package
across the repo boundary
Full suite (125 tests), typecheck, and lint all green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sync AGENTS.md, CLAUDE.md, and .claude/rules from updated project_rules
templates: workplan-first session protocol, legacy terminology footnote,
and GET /workplans/ examples.
Honest first-pass maturity vector grounded in README/docs/tests present
in this repo; no invented evidence. Flagged for human review before
publish. See reuse-surface history/2026-07-06-coverage-classification.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Align agent files with on-disk workplan prefixes (infer from workplan ids)
- Set workplan domain to registered domain_slug; add topic_slug where applicable
- Repair frontmatter delimiter formatting; migrate legacy task status literals
- Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
Verify sibling citation-engine checkout, link dependency resolution,
toolchain, and absence of stale in-repo engine copies. Prints actionable
fix hints when the installation layout is wrong.
Capture mode state lived only in React memory and was lost when
reopening a session or remounting EngineProvider.
- Add per-session localStorage capture snapshot (schema, values, links)
- Restore on session mount; persist on field/schema/link changes
- Seed binder links from storage without spurious bus events
- Clean up capture key when session is deleted
- Integration test for reload persistence
PdfLoader reloads the PDF when its document prop is a new object each
render. Memoize the loader config on pdfUrl only.
Also stabilize SpikeHighlightContainer via context (no remount on focus
change) and narrow scroll-effect deps to highlight id signature.
- Wire fieldValues state in FormsApp so controlled inputs persist typed data
- Add runScrollToHighlightJob with rAF retries when utils/highlights not ready
- Re-trigger scroll when highlights update after PDF load
- Tests: scroll-job unit test, forms-field-values integration tests
- Workplan CE-WP-0008 marked done
The version of pdf_viewer.css bundled with react-pdf-highlighter-plus
is only a minimal *override* (≈40 lines: opacity, z-index, blend
mode). It's missing the foundational rules that PDF.js's TextLayer
relies on — `position: absolute`, `inset: 0`, and the entire
`--scale-factor` CSS-variable machinery that PDF.js 4.x uses to
position each glyph.
Without those rules, each text-layer span gets rendered with default
positioning context and `font-size: calc(<base> * var(--scale-factor))`
collapses to 0 → spans either pile up at the top-left of the page or
land at wrong y-coordinates regardless of where the glyph actually
sits on the canvas. The reported symptom ("origin seems to be the top
of the page always") matches exactly.
Importing `pdfjs-dist/web/pdf_viewer.css` first, then the library's
overrides on top, gives PDF.js the CSS it expects.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Strong likelihood that the "text layer is misplaced / body text not
selectable" symptoms across multiple PDFs come from PDF.js falling
back to substitute font metrics. Without the cmaps directory (CID
character maps for non-Latin fonts) and the standard_fonts directory
(Helvetica/Times/Courier metrics for unembedded standard fonts), the
canvas glyphs use embedded font data while the text-layer span
positions are computed from fallback metrics. The two diverge — text
spans land in the wrong place, or text content can't be decoded at
all, leaving the body unselectable.
Both directories are now copied into the served root by
vite-plugin-static-copy and passed to pdfjs.getDocument() as
`cMapUrl: "/cmaps/"` + `cMapPacked: true` + `standardFontDataUrl:
"/standard_fonts/"` via PdfLoader's `document` prop (which accepts a
full DocumentInitParameters object).
If this is the right diagnosis, the textLayer overlay should now line
up with the visible glyphs on the same PDFs that were producing
fragmented captures. If the body text is still unselectable, the PDF
genuinely lacks a text layer for those glyphs (image-only content)
and OCR would be the only path forward.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The previous iteration left inactive document cards on a
white-with-grey-border style and only flipped to light-blue on
activation. The intent (matching the evidence-card pattern of
always-yellow with a thicker border when active) was to always-blue
with a thin/thick dark-blue border.
Inactive: 1px #0050b3 on #e8f0ff
Active: 3px #0050b3 on #e8f0ff
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Three UX iterations rolled into one:
1. Unified evidence form
- New EvidenceFormBody is the single source for "citation +
commentary" editing. Both InlineCaptureForm (creating fresh
evidence from a selection) and the EvidenceCard edit mode render
this body with their own save/cancel labels + badge/helper text.
- The capture form now exposes the citation as an editable
textarea — pre-filled with the selection text — so the user can
refine a partial capture before saving without re-selecting.
- Old testid prefixes are unchanged for the inline-capture flow
(`inline-capture-quote/commentary/save/cancel`); edit-mode
testids are now `evidence-edit-<id>-{quote,commentary,save,cancel}`.
2. Active document card
- The blue background alone was the only "this is open" cue. Added
a 3px #0050b3 border (matching the evidence-card thick-border
pattern, but in the documents-are-blue palette) plus a
`data-active` attribute.
3. PDF layer-hide diagnostics
- New debug flags `hideCanvas`, `hideTextLayer`, `hideAnnotationLayer`,
`hideXfaLayer` — applied as `.ce-hide-<layer>` classes on the viewer
wrapper, each `display: none`-ing the matching PDF.js layer.
- SessionMenu groups the toggles under a "PDF diagnostics" header
with a new shared DebugCheckbox helper. The existing "Debug text
layer" highlight toggle now lives in the same group.
- Lets the user isolate stacking issues by elimination — e.g.
"hide text layer, can I now see the canvas content underneath?".
Tests
- citation-card-export-e2e + session-export-reimport switched from
placeholder/role-name lookups to the inline-capture testids so
they survive form-copy changes.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Click "Create session" with the input empty and a name of the form
`YYMMDD-session-NNN` is generated automatically: today's date as
two-digit year/month/day, then a zero-padded counter that starts at
000 and increments past the highest existing match for the same day.
Added:
- `computeNextDefaultName(existing, now?)` pure helper exported from
`@engine/services/sessions`.
- `SessionService.nextDefaultName(now?)` method that wraps it
against the current repo.
- Both create call sites (CreateFirstSession empty state +
SessionMenu's New session form) fall back to `service.nextDefaultName()`
when the trimmed input is empty.
- 5 new unit tests covering today-only counting, max-not-count
increment, and trimmed/wrong-shape filtering.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Significant UX iteration:
Visual palette
- Debug text-layer overlay flips from yellow to light grey so it no
longer collides with the evidence highlight colour.
- New highlight-styles.css matches the sidebar's #fff8d6/#e0c050
palette so a passage marked in the document and its sidebar card
speak the same visual language.
- Active (focused) evidence: same fill, thick #b78b1c outline on both
the highlight and the sidebar card. Library's red --scrolledTo
box-shadow is suppressed.
Activation model
- Click an evidence card in the sidebar → activates that item +
scrolls the viewer to the passage + thickens the borders (existing
behaviour, now visually clearer).
- Click a highlight in the document → activates the evidence that
owns that annotation. New `findByAnnotationId()` on EvidenceService
is the reverse lookup. Wired through a new `onHighlightClicked`
prop on PdfSpikeViewer + `activeAnnotationId` prop that drives the
data-ce-active attribute on the highlight wrapper.
Inline edit
- Each evidence card has a ✎ button that flips the card into an
inline form with the citation (quote) and commentary fields.
- Saving calls a new `AnnotationService.updateQuote()` +
existing `EvidenceService.updateCommentary()`. The selectors are
untouched, so the marked passage in the document stays put — the
inline hint says so explicitly.
- New `AnnotationUpdated` event added to the engine event vocabulary
(SharedContracts.md §4 updated).
Capture form placement
- The yellow "New annotation" toolbar that lived above the viewer is
gone. A new InlineCaptureForm component is now slotted into the
sidebar between the cards that bracket the new selection in
document flow (sorted by page + y of the first PdfRectSelector).
If the new selection is before all existing evidence it appears at
the top; if after all of them, at the bottom.
- The legacy AnnotationToolbar.tsx is removed; the public surface
re-exports `InlineCaptureForm` instead.
Test updates
- tests/integration/citation-card-export-e2e.dom.test.tsx: switched
to the seed-session helper (matches the other E2Es) since the
fixture-button click path is gone.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The first cut of "Debug text layer" only painted direct `<span>`
children of `.textLayer`. PDF.js 4.x wraps marked content in nested
spans/divs, so the entire selectable area wasn't visible — making it
hard to tell whether a region is "no text layer at all" vs. "text
layer present but small/dense".
Changes:
- CSS now targets every descendant of `.textLayer`, dims the canvas
underneath, and outlines the `.textLayer` container itself so its
full extent is obvious.
- TextHighlight rectangles flip to green in debug mode so saved
highlights don't get washed out by the debug yellow.
- The viewer now logs:
[ce] viewer highlights — which annotations rendered, which
were skipped, with rects + page
[ce] scrollToAnnotation — whether the target was found in
the highlights array when an
activation arrived
This is the diagnostic loop for the "viewport scrolls but the
highlight doesn't appear" report — if highlight count is > 0 in the
first log but the green rectangle is off-screen, the saved rects
inherited the same text-layer misalignment that caused the partial
selection captures in the first place.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
PDF text selection misbehaviour (some glyphs unselectable, selections
jumping to other positions) is almost always caused by misalignment
between the visible canvas-rendered glyphs and the invisible text
layer that PDF.js overlays for selection. There's no way to see this
without devtools — which makes it hard for end users to tell whether
a specific PDF is OCR-noisy, has bad font fallbacks, or has no text
layer at all.
This adds a developer-facing toggle in the SessionMenu ("Debug text
layer") that:
- paints every text-layer span yellow with a blue outline so it's
obvious where text is selectable and where it isn't, and
- logs every onSelection event to the browser console with the
captured text, page, normalized rects, and the selectors the
pipeline derived from it.
Preference persists in localStorage under
`citation-evidence:debug:textLayer`. Surfaced via a new
`useDebugFlag()` hook in @work so the SessionMenu (app layer) and the
ViewerShell (work layer) can both subscribe without breaching the
boundary plugin.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
UX gaps that surfaced while running the demo:
- ViewerShell hardcoded `/fixtures/pdfs/<title>` for the PDF URL,
ignoring the `document.uri` blob URL that uploaded PDFs carry. The
viewer either 404'd or — worse — silently served a fixture whose
filename happened to collide. Prefer document.uri when present.
- SessionMenu only let you delete the *active* session. Added a small
per-row "✕" button next to every session in the Switch-to list so a
user can drop a session's data without first switching to it. Same
click-to-confirm pattern as the existing Delete action.
- Added a "Reset all data…" affordance in both the SessionMenu and the
empty-state landing. Calls a new `clearAllSessionData()` helper that
wipes every `citation-evidence:*` key from localStorage, then forces
a reload so all in-memory caches start fresh.
- `attachSessionPersister.writeOnDelete` was leaking the per-session
`active-document-id:v1` key on every session delete. Now removed
alongside the engine snapshot key.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The PDF.js library refuses to open documents without a worker URL.
Production builds were throwing "No GlobalWorkerOptions.workerSrc
specified" on any upload because neither the source-layer ingest
(extract.ts) nor the viewer adapter ever set one — they relied on the
host application to do it, and the browser bootstrap didn't.
main.tsx now imports the worker via Vite's `?url` suffix so the file
is bundled into the build, and sets GlobalWorkerOptions.workerSrc
once before any PDF code runs. Added src/vite-env.d.ts so TypeScript
knows about the `?url` import suffix.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
