Files

tegwick 779ae0d317 Implement CE-WP-0005 T01-T08: demo app — sessions, uploads, ZIP archive

Turn the MVP into a self-contained demo. Users now:
  1. Land on an empty-state and create a named session.
  2. Drag-drop or pick arbitrary PDFs into that session.
  3. Annotate, build evidence, link to form fields — all session-scoped.
  4. Export the whole session as a single .zip archive (manifest +
     per-document PDFs).
  5. Import a .zip back — into a new session, or merged into an
     existing one (documents deduped by SHA-256 fingerprint;
     annotations/evidence/links added additively).

Architecture:
- New shared types: SessionId, Session, SessionArchiveManifest +
  parseSessionArchiveManifest with schema-version validation.
- SessionService (engine/services/sessions.ts) handles lifecycle
  (create/rename/delete/setActive) + emits 4 new events through its
  own bus; SharedContracts.md §4 lists the additions.
- SessionProvider (work/SessionContext.tsx) owns the cross-session
  state: service, per-session PdfByteStore registry, per-session
  version counter that drives EngineProvider remounts after imports.
- EngineProvider becomes session-aware (sessionId prop drives per-
  session localStorage keys). Bumping engineRevision after
  restoreFromStorage forces consumers to re-render so restored repos
  show up immediately.
- PdfByteStore (source/pdf/byte-store.ts) holds Uint8Array bytes per
  document and mints blob URLs; ingestPdfFromFile is the upload
  entry-point that wraps the existing ingestPdf pipeline.
- ADR-0008 locks the ZIP layout (manifest.json + documents/<id>.pdf),
  the manifest schema (schemaVersion 1), and the merge-on-collision
  policy. JSZip is the only new dependency.
- App.tsx restructured: SessionProvider at the root, EngineProvider
  keyed by ${sessionId}:${version}, hash routing #/s/<id>[/forms/demo],
  SessionMenu top-bar, CreateFirstSession empty state.
- New DocumentRemoved event for per-document delete cleanup in
  CollectionList; engine.documents.remove() is the new service method.

Tests:
- Unit: 16 SessionService lifecycle + persistence tests;
  per-session snapshot round-trip; PdfByteStore + ingestPdfFromFile;
  SessionArchive parser; exportSessionZip + importSessionZip with
  create + merge + corrupt-archive paths.
- DOM: UploadDropzone, session-scoped CollectionList delete,
  SessionMenu create/switch/rename, routing parser.
- E2E: tests/integration/session-export-reimport.dom.test.tsx walks
  the full create → annotate → export → reimport flow and asserts
  the additive merge (deduped doc + doubled evidence rows).
- Legacy E2Es updated to use a seed-session helper instead of the
  removed fixture-button flow.

Known limitation (documented in ADR-0008): re-importing your own
freshly-exported ZIP creates duplicate annotations. Forward pointer
left for an importBundleId follow-up.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-26 14:57:28 +02:00

CE-WP-0001-foundations.md

Implement CE-WP-0001 Foundations: TS scaffold, lint boundaries, normalize v1, fixtures

2026-05-25 00:13:03 +02:00

CE-WP-0002-pdf-review-slice.md

Implement CE-WP-0002 T03-T09: ingest, anchor resolution, engine, UI, persistence, e2e

2026-05-25 10:58:11 +02:00

CE-WP-0003-form-binding-visual-guide.md

Implement CE-WP-0003 T01-T08: form binding + visual guide overlay

2026-05-25 15:53:17 +02:00

CE-WP-0004-citation-card-export.md

Implement CE-WP-0004 T01-T05: citation card export (Markdown + HTML)

2026-05-26 14:43:17 +02:00

CE-WP-0005-demo-sessions-zip-archive.md

Implement CE-WP-0005 T01-T08: demo app — sessions, uploads, ZIP archive

2026-05-26 14:57:28 +02:00

README.md

Establish shared-contracts home, dependency map, MVP workplans, and umbrella-first strategy

2026-05-24 16:42:25 +02:00

README.md

MVP Workplans

These four workplans implement the first reference scenario from wiki/ProductRequirementsDocument.md §20 — end-to-end PDF evidence capture → form binding → citation card export — entirely inside the citation-evidence repository.

Workplan	Title	Status
`CE-WP-0001`	Foundations — scaffold, folders, lint rules, normalize, fixtures	todo
`CE-WP-0002`	PDF review slice — engine types, anchor, source, viewer, sidebar	todo
`CE-WP-0003`	Form binding + visual guide — EvidenceLink, rect registry, overlay	todo
`CE-WP-0004`	Citation card export — Markdown + HTML renderers, sidebar export	todo

Order

Strictly sequential. CE-WP-0002 depends on the folder/lint scaffolding from CE-WP-0001. CE-WP-0003 and CE-WP-0004 depend on the engine types, viewer adapter, and sidebar from CE-WP-0002.

How to run a workplan

/ralph-workplan workplans/CE-WP-0001-foundations.md

Ralph drives the loop and retires automatically when all tasks in the workplan are marked done. See ~/.claude/plugins/ralph-workplan/ralph-workplan.md.

Acceptance for MVP

The first reference scenario from PRD §20 runs end-to-end:

Create a collection
Upload a PDF
Select a passage, add commentary, create an evidence item
Open a side-by-side form
Link the evidence item to a form field
Focus the field → field, evidence card, and PDF passage all highlighted
SVG guide visible between field → card → highlight
Export evidence as a Markdown citation card