with buttons
+ - Buttons present: 'Copy RIS', 'Copy BibTeX', 'Download .ris', 'Download .bib', 'Download CSL-JSON'
+ - Each button has type="button"
+
+ Hydration (unit-testable via JSDOM with mocked document):
+ - hydrateBibliography(container) finds all li[data-csl] within the container and appends cite panels
+ - After hydrateBibliography, the container has class 'bibliography-builder-js-ready'
+ - li elements without data-csl are skipped (no panel appended)
+ - li with invalid JSON in data-csl is skipped (no panel, no throw)
+ - li with null or non-object JSON in data-csl is skipped
+
+ Button behavior (unit tests use stubs for downloadTextExport and copyTextToClipboard):
+ - 'Copy RIS' click calls copyTextToClipboard with buildSingleRisContent(cslItem) result
+ - 'Download .ris' click calls downloadTextExport with RIS content and RIS MIME type
+ - 'Download .bib' click awaits buildSingleBibtexContent then calls downloadTextExport
+ - 'Download CSL-JSON' click calls downloadTextExport with CSL-JSON content and CSL-JSON MIME type
+
+
+ TDD red-green-refactor.
+
+ IMPORTANT: Export buildCitePanel and hydrateBibliography as named exports from view.js so they can be tested in isolation. The DOMContentLoaded listener at module scope is the only non-exported code.
+
+ src/view.js structure:
+ 1. Imports: copyTextToClipboard from ./lib/clipboard; downloadTextExport, RIS/BIBTEX/CSL_JSON_EXPORT_MIME_TYPE from ./lib/export; buildSingleRisContent, buildSingleBibtexContent, buildSingleCslJsonContent from ./lib/export-single
+ 2. export function buildCitePanel(cslItem, { copyFn, downloadFn } = {}) — creates and returns the element. Accept copyFn and downloadFn as injectable dependencies for testing (default to copyTextToClipboard and downloadTextExport).
+ 3. export function hydrateBibliography(container, { copyFn, downloadFn } = {}) — finds li[data-csl], parses JSON, appends panel, marks container js-ready.
+ 4. DOMContentLoaded listener calls hydrateBibliography on each .wp-block-bibliography-builder-bibliography element.
+
+ src/view.test.js: Use JSDOM (Jest's default jsdom environment). Mock imports:
+ - jest.mock('./lib/export-single', ...) with sync stubs that return predictable strings
+ - jest.mock('./lib/clipboard', ...) with a stub returning Promise.resolve(true)
+ - jest.mock('./lib/export', ...) returning a stub downloadTextExport and the real MIME type constants
+
+ i18n note: Button labels are hardcoded English in this phase. The open question about data-i18n attributes is deferred — hardcoded labels are acceptable for Phase 2. Track as follow-on.
+
+
+
+
+
+
+ Task 1: TDD — view.js cite panel and hydration logic
+ src/view.js, src/view.test.js
+
+ Per the feature behavior block above — run RED commit then GREEN commit.
+
+
+ Follow TDD cycle strictly:
+
+ RED: Write src/view.test.js with:
+ - Tests for buildCitePanel(cslItem) DOM structure (class, summary text, button count/labels, button types)
+ - Tests for hydrateBibliography(container): panels added to li[data-csl] entries, js-ready class added, li without data-csl skipped, invalid JSON skipped
+ - Tests for button click behavior using injected copyFn/downloadFn stubs (no real async imports needed)
+
+ Mock strategy in test file:
+ ```js
+ jest.mock('./lib/export-single', () => ({
+ buildSingleRisContent: jest.fn(() => 'RIS_CONTENT'),
+ buildSingleBibtexContent: jest.fn(async () => 'BIBTEX_CONTENT'),
+ buildSingleCslJsonContent: jest.fn(() => 'CSL_CONTENT'),
+ }));
+ jest.mock('./lib/clipboard', () => ({
+ copyTextToClipboard: jest.fn(async () => true),
+ }));
+ jest.mock('./lib/export', () => ({
+ downloadTextExport: jest.fn(),
+ RIS_EXPORT_MIME_TYPE: 'application/x-research-info-systems;charset=utf-8',
+ BIBTEX_EXPORT_MIME_TYPE: 'text/x-bibtex;charset=utf-8',
+ CSL_JSON_EXPORT_MIME_TYPE: 'application/vnd.citationstyles.csl+json;charset=utf-8',
+ }));
+ ```
+
+ Run `npm test -- --testPathPattern="src/view.test"` — tests must FAIL.
+ Commit: test(02-03): add failing tests for view.js cite panel hydration
+
+ GREEN: Create src/view.js with buildCitePanel and hydrateBibliography exported, plus DOMContentLoaded listener.
+ Run tests — must PASS.
+ Commit: feat(02-03): implement view.js cite panel hydration
+
+ The DOMContentLoaded listener is not tested directly — it is glue code calling the tested hydrateBibliography function.
+
+
+ npm test -- --testPathPattern="src/view.test" --passWithNoTests=false
+
+
+ - src/view.js exports buildCitePanel and hydrateBibliography
+ - src/view.test.js has tests covering DOM structure, hydration, skip-on-missing-data-csl, skip-on-invalid-JSON, button behavior
+ - All view.test.js tests pass
+ - RED commit then GREEN commit both present
+
+
+
+
+ Task 2: Progressive enhancement CSS in style.scss
+ src/style.scss
+
+ Append to src/style.scss (do not replace existing content):
+
+ ```scss
+ // Cite / Export panel — progressive enhancement
+ // Controls are hidden by default; view.js adds .bibliography-builder-js-ready
+ // to reveal them only when JS has run successfully.
+ .bibliography-builder-cite-controls {
+ display: none;
+ }
+
+ .bibliography-builder-js-ready .bibliography-builder-cite-controls {
+ display: block;
+ }
+
+ .bibliography-builder-cite-panel {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 0.5em;
+ padding: 0.5em 0;
+ }
+
+ .bibliography-builder-cite-panel button {
+ font-size: 0.875em;
+ cursor: pointer;
+ }
+ ```
+
+ This CSS ensures:
+ - No cite controls are visible when JS is disabled (REQ-FE-04: no-JS bibliography fully readable)
+ - Controls appear only after view.js adds bibliography-builder-js-ready (REQ-FE-05: deactivation-resilient)
+ - When plugin is deactivated, bibliography-builder-js-ready is never added, controls remain hidden
+ - Existing bibliography styles are unaffected (additive-only change)
+
+
+ npm run build && echo "Build clean"
+
+
+ - src/style.scss includes .bibliography-builder-cite-controls { display: none }
+ - src/style.scss includes .bibliography-builder-js-ready .bibliography-builder-cite-controls rules
+ - npm run build completes without errors
+ - build/view.js is present in the build output
+ - build/style-index.css includes the cite control rules
+
+
+
+
+
+
+After both tasks:
+- `npm test` — full suite passes (export-single + view + save tests all green)
+- `npm run build` — build/view.js present, no build errors
+- `grep -n "bibliography-builder-cite-controls" build/style-index.css` — CSS rule present in output
+- `ls build/view.js` — viewScript compiled artifact exists
+
+
+
+- src/view.js exists, exports buildCitePanel and hydrateBibliography, has DOMContentLoaded listener
+- src/view.test.js passes: DOM structure, hydration, skip logic, button wiring all covered
+- src/style.scss hides cite controls by default, reveals under js-ready parent
+- npm run build succeeds with build/view.js in output
+- Full Jest suite green
+- No PHP files modified
+
+
+
diff --git a/.planning/phases/02-frontend-cite-and-export-affordances/02-RESEARCH.md b/.planning/phases/02-frontend-cite-and-export-affordances/02-RESEARCH.md
new file mode 100644
index 0000000..03d10d2
--- /dev/null
+++ b/.planning/phases/02-frontend-cite-and-export-affordances/02-RESEARCH.md
@@ -0,0 +1,560 @@
+# Phase 2: Frontend Cite and Export Affordances - Research
+
+**Researched:** 2026-06-04
+**Domain:** WordPress static block, progressive-enhancement frontend interactivity, citation export (BibTeX/RIS/CSL-JSON), Clipboard API, Blob download
+**Confidence:** HIGH
+
+---
+
+
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|-----------------|
+| REQ-FE-01 | Visible per-entry Cite/Export UI on the public bibliography frontend | viewScript + data-attribute hydration pattern; Google Scholar-style cite affordance |
+| REQ-FE-02 | BibTeX, RIS, and CSL-JSON download/copy per entry | `buildBibtexExportContent`, `buildRisExportContent`, `buildCslJsonExportContent` in `src/lib/export.js` are single-entry capable after trivial per-entry extraction; Blob+anchor download pattern |
+| REQ-FE-03 | No render_callback — all output stays in static save() | viewScript hydrates HTML already saved by save.js; no PHP render required for JS-layer behavior |
+| REQ-FE-04 | No-JS bibliography remains fully readable | Existing `` + `` structure is complete text; cite/export controls are additive DOM elements hidden until JS runs or styled as graceful degradation |
+| REQ-FE-05 | Preserves plugin-deactivation resilience | Citation data embedded in `data-csl` attributes is inert HTML; controls can be hidden by default (CSS: `display:none`) and shown by JS; deactivation removes JS but leaves readable bibliography markup intact |
+| REQ-FE-06 | Mendeley/Zotero manual-import acceptance | Visible per-entry RIS and BibTeX download buttons directly serve the gap confirmed in Mendeley testing (non-DOI entries missed by auto-detection) |
+
+
+---
+
+## Summary
+
+This phase adds optional Scholar-like Cite/Export controls to the already-saved static bibliography frontend. The plugin uses a static `save()` function — no PHP `render_callback` — which constrains the approach: all interactive behavior must come from JavaScript that hydrates the saved HTML at runtime.
+
+The cleanest solution for this project is a `viewScript` frontend bundle registered in `block.json`. WordPress automatically enqueues `viewScript` only when the block is present on a page (since WP 6.1), making it zero-cost for posts without bibliography blocks. The script reads per-entry CSL-JSON data from attributes embedded during save and renders Cite/Export controls progressively. The WordPress Interactivity API is available but not required; it introduces a `data-wp-interactive` namespace coupling into saved block markup that becomes dead HTML if the plugin is deactivated — contrary to the deactivation-resilience requirement. Vanilla JS with `data-csl` attributes is the preferred approach.
+
+The existing `src/lib/export.js` already contains `buildBibtexExportContent`, `buildRisExportContent`, `buildCslJsonExportContent`, and `buildCslJsonExportContent`. These functions operate on arrays of citations and sort them by style; they need a thin wrapper to operate on a single CSL item. The existing `copyTextToClipboard` in `src/lib/clipboard.js` already handles the `navigator.clipboard` + `execCommand` fallback and is injectable for testing.
+
+**Primary recommendation:** Add a `viewScript` file (`src/view.js`) that reads per-entry CSL-JSON from `data-csl` attributes, builds a per-entry modal/details panel with Copy and Download buttons (BibTeX, RIS, CSL-JSON), and uses the existing export utilities. Embed per-entry CSL-JSON into the save markup using a `data-csl` attribute on each `
`. Keep controls hidden with CSS until JS initialises them.
+
+---
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| `@citation-js/core` | 0.7.18 (already in deps) | BibTeX generation | Already bundled; `buildBibtexExportContent` uses it async |
+| `@citation-js/plugin-bibtex` | 0.7.18 (already in deps) | BibTeX/BibLaTeX format | Already bundled async chunk `citation-plugin-bibtex.js` |
+| WordPress `viewScript` | WP 6.1+ | Frontend-only JS enqueue | Auto-enqueued when block present; zero overhead otherwise |
+| Clipboard API (`navigator.clipboard`) | Baseline (2025) | Copy text to clipboard | `copyTextToClipboard` in `clipboard.js` already wraps it with fallback |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| `Blob` + `URL.createObjectURL` | Baseline | File download in browser | Already used by `downloadTextExport` in `export.js` |
+| ``/`` HTML | HTML5 native | No-JS-accessible disclosure widget | Use as the cite panel toggle; degrades to always-open without CSS |
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| `viewScript` + vanilla JS | WordPress Interactivity API (`viewScriptModule`) | Interactivity API requires `data-wp-interactive` in saved markup, which becomes dead/inert HTML post-deactivation. Also requires WP 6.5+ minimum. Not worth the constraint for this use case. |
+| `data-csl` attribute per `` | Existing `