generated from coulomb/repo-seed
tegwick
d06a456c2a
- INTENT.md: declare umbrella as the home for shared contracts; document umbrella-first MVP decision (code lives here until subsystems stabilize) - wiki/SharedContracts.md: vocabulary, state enums, relation types, selector taxonomy, event vocabulary, viewer adapter contract, canonical text normalization, rect-registry contract - wiki/DependencyMap.md: allowed dependency edges; folder layout + lint-rule strategy during umbrella-first phase - history/2026-05-24-initial-assessment.md: alignment review, technical risks, and the umbrella-first pivot rationale - workplans/CE-WP-0001..0004: four ralph-compatible workplans covering foundations, PDF review slice, form binding + visual guide, and citation card export — implementing PRD §20 end-to-end Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
165 lines
4.2 KiB
Markdown
165 lines
4.2 KiB
Markdown
---
|
|
id: CE-WP-0004
|
|
type: workplan
|
|
title: "Citation card export — Markdown and HTML renderers, sidebar export"
|
|
domain: citation_evidence
|
|
repo: citation-evidence
|
|
repo_id: a677c189-b4e2-4f2a-9e48-faa482c277e6
|
|
status: todo
|
|
owner: Bernd
|
|
created: 2026-05-24
|
|
updated: 2026-05-24
|
|
depends_on_workplan: CE-WP-0002
|
|
spec_refs:
|
|
- 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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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`):
|
|
|
|
```markdown
|
|
> {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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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.
|