citation-evidence/workplans/CE-WP-0004-citation-card-export.md

id, type, title, domain, repo, repo_id, status, owner, created, updated, depends_on_workplan, spec_refs

id	type	title	domain	repo	repo_id	status	owner	created	updated	depends_on_workplan	spec_refs
CE-WP-0004	workplan	Citation card export — Markdown and HTML renderers, sidebar export	citation_evidence	citation-evidence	a677c189-b4e2-4f2a-9e48-faa482c277e6	todo	Bernd	2026-05-24	2026-05-24	CE-WP-0002	wiki/ProductRequirementsDocument.md wiki/ArchitectureOverview.md wiki/SharedContracts.md

CE-WP-0004 — Citation Card Export

The final step of the MVP scenario: turn an evidence item into a portable Markdown or HTML citation card.

After this workplan, a user can:

1. Click "Export" on an evidence item in the sidebar.
2. Choose Markdown or HTML.
3. Get a clipboard-ready citation card with quote, source label, commentary, and a link back to source context.

This workplan can run in parallel with CE-WP-0003 once CE-WP-0002 is done — it touches different code paths.

Dependency Order

T01 (CitationCard type + open-context URL convention)
  └─ T02 (Markdown renderer)
  └─ T03 (HTML renderer)
       └─ T04 (sidebar Export button + copy-to-clipboard)
            └─ T05 (E2E test of PRD scenario step 10)

---

T01 — CitationCard type + open-context URL convention

id: CE-WP-0004-T01
priority: high
status: todo

Under src/shared/:

• src/shared/citation-card.ts — CitationCard per Architecture §4.7
• src/shared/open-context-url.ts — function openContextUrl(annotationId) returning a URL of the form /viewer?document=<docId>&annotation=<annId> (per Architecture §14.3)

The URL is the deep link that an exported card uses to reopen the source context in this MVP. When persistence becomes real (post-MVP), the URL scheme stays the same.

---

T02 — Markdown citation card renderer

id: CE-WP-0004-T02
priority: high
status: todo
depends_on: [T01]

Under src/engine/rendering/:

• markdown.ts — renderCitationCardMarkdown(evidenceItem, document, annotation): string

Output format (lock this in docs/decisions/ADR-0007-citation-card-format.md):

> {quote}

— *{sourceLabel}* · [Open source]({openContextUrl})

{commentary}

Where sourceLabel is document.title if present, else the filename, else the document URI.

Unit tests: snapshot a few rendered cards against fixtures.

---

T03 — HTML citation card renderer

id: CE-WP-0004-T03
priority: high
status: todo
depends_on: [T01]

Under src/engine/rendering/:

• html.ts — renderCitationCardHtml(evidenceItem, document, annotation): string

Output: a single <aside class="citation-card"> element with <blockquote>, <cite>, <a> (open context), and <div class="commentary">. Inline styles avoided — host page provides CSS. Sanitize commentary as plain text (no raw HTML pass-through).

Web component <citation-card> from Architecture §14.2 is not in scope here — it ships in a later workplan.

---

T04 — Sidebar Export button + copy-to-clipboard

id: CE-WP-0004-T04
priority: medium
status: todo
depends_on: [T02, T03]

Add to src/work/EvidenceSidebar.tsx:

• Per evidence item: an "Export" affordance (icon button or menu)
• On click: small popover with two buttons, "Copy as Markdown" and "Copy as HTML"
• On click: render via T02/T03 and write to clipboard with the standard navigator.clipboard API; show a transient confirmation toast

Keyboard shortcut Cmd/Ctrl+Shift+C exports the active evidence item as Markdown (the most common action).

---

T05 — E2E test of PRD scenario step 10

id: CE-WP-0004-T05
priority: medium
status: todo
depends_on: [T04]

Extend the Playwright E2E:

10. After the earlier steps, click Export → Copy as Markdown on the saved evidence item.
11. Read the clipboard; assert it contains the quote text, the document title, the commentary, and a URL matching the /viewer?document=...&annotation=... shape.

If this passes, MVP scenario steps 1-10 are all green and the umbrella-first MVP is done for the first reference scenario from PRD §20.

The next workplan (post-MVP) would be CE-WP-0005 to either extract the first stable subsystem (likely citation-engine) into its own repo or to add Markdown/HTML document support.