docs(plan): add frontend COINs demo plan

Plan for the /demos/coins interactive page: query-structure picker,
dataset and algorithm selectors, SVG query-graph with per-node and
per-edge searchable dropdown pills that grow to fit entity/relation
names and reflow the graph to avoid overlap, and a results dashboard
covering top-K predictions, community-rank callout, and step-by-step
timing vs baseline. Exercises all seven COINs backend endpoints with
every documented input/output field.

.claude/plans/frontend_coins_demo.md

@@ -0,0 +1,194 @@
+# Frontend COINs Demo: Interactive Query Builder + Reasoning Dashboard
+
+Interactive Vue page at `/demos/coins` that lets the user pick a dataset, query structure, and embedding algorithm, fill anchors/relations/variables into a visual query template via searchable dropdowns, click "Reason", and view a dashboard with ranked entity predictions plus COINs-specific stats (community rank, step timing, speedup vs baseline). Exercises **every** COINs backend endpoint and every documented input/output field.
+
+## Context
+
+The backend exposes seven COINs endpoints under `/api/v1/coins/` (`src/backend/api/views/coins.py`, fully spec'd in `docs/api.yaml`): `GET /datasets`, `GET /datasets/{id}/entities`, `GET /datasets/{id}/relations`, `GET /datasets/{id}/sample-triples`, `GET /models`, `GET /query-structures`, `POST /predict`. The frontend (`src/frontend/`, Vue 3 + Vite + Fomantic-UI + axios + Pinia) currently only ships Home and CV. The Home page has a "Coming soon" `DemoPreviewCard` for COINs and already uses `sampleTriples('nell', ...)` in `FactOfTheDay.vue`, plus the SVG motif-rendering pattern in `components/background/FloatingMotif.vue` — both are the visual/technical reference for this demo. Plan `.claude/plans/backend_coins.md` describes the inference semantics (community rank `rank_c`, `c_err`, Prop. 3.1 speedup) that the dashboard surfaces to the user. This demo is the first of three research demos; `/demos/<slug>` namespacing leaves room for MultiProxAn and KG-Anomaly.
+
+## Assumptions and Constraints
+
+- Stack stays Vue 3 + Vite + vue-router 4 + Pinia + axios + Fomantic-UI CSS. **No new heavy deps** — the query-structure visualization is hand-rolled SVG (query templates have ≤5 nodes / ≤3 edges, mirroring the `FloatingMotif.vue` style).
+- All calls go through `src/frontend/src/api/client.js` (`/api/v1` base URL, `apiError()` for messages). All COINs calls live in `src/frontend/src/api/coins.js` (extending the two existing functions).
+- The backend enforces a **global inference lock** (`INFERENCE_BUSY` → HTTP 429). The UI must serialize `POST /coins/predict` per tab and surface 429 with a friendly retry hint.
+- Entity/relation lists are **large** (NELL ~66 k entities, Freebase ~14 k, WordNet ~41 k). Searchable dropdowns must use server-side search via `?q=&page=&page_size=` with debounced typing (≥200 ms) — never load the full list client-side.
+- Algorithm support varies by structure (only `q2b` supports `2p/3p/2i/3i/ip/pi`; `transe/distmult/complex/rotate/kbgat` only `1p`) and by dataset (`models.available_datasets`). The UI filters selectable algorithms by both.
+- Green palette and dark-mode CSS custom properties from `styles/tokens.css` drive all new styles. Respect `prefers-reduced-motion`. Responsive from 320 px up.
+- **Docs hygiene (per CLAUDE.md):** this plan does not change backend endpoints, so no backend-docs updates needed. If inference shape changes later, update `docs/api.yaml`, `docs/postman/`, and `src/backend/README.md` in the same commit.
+
+## Scope
+
+**In scope**
+- New route `/demos/coins` with one view and one Pinia store.
+- Query-builder UI: dataset selector, query-structure selector (cards), algorithm selector (filtered), hand-rolled SVG query-graph visualization with entity/relation dropdowns positioned over nodes/edges, top-K slider, "Reason" button.
+- Reusable `SearchableEntityDropdown` / `SearchableRelationDropdown` components (server-side paginated search with debounce).
+- Reusable `QueryStructurePicker` cards that render each template via the shared SVG renderer.
+- Results dashboard: human-readable `query_description`, top-K predictions list (rank, intra-community rank, entity name, score), **Community rank callout** explaining `rank_c`, **Timing panel** with step1/step2/total bars and speedup multiplier + baseline estimate, loading + 429/error states.
+- API wrappers for the five new COINs endpoints; update the existing `sampleTriples` and add `getDatasets`.
+- Nav: add "Demos" link in `NavBar.vue` pointing to `/demos/coins` (single entry now; becomes a dropdown when other demos ship).
+- Home page wiring: update the COINs `DemoPreviewCard` to link to `/demos/coins` and drop the "Coming soon" label.
+- Manual browser verification against a locally running backend (GPU box available per user memory).
+
+**Out of scope**
+- MultiProxAn and KG-Anomaly demos.
+- Unit/e2e tests (manual browser verification only, matching the existing frontend-plan precedent).
+- Persisting query state across reloads / shareable URLs (nice-to-have for a later iteration).
+- Advanced KG subgraph visualization around the predicted entity (target node only; no neighbour expansion).
+
+## Design
+
+### New directory layout
+
+```
+src/frontend/src/
+├── api/
+│   └── coins.js                 # extended: datasets, entities, relations, sampleTriples, models, queryStructures, predict
+├── components/
+│   └── coins/
+│       ├── QueryStructurePicker.vue   # grid of cards, each renders template via QueryGraph
+│       ├── QueryGraph.vue             # shared SVG renderer: nodes + edges from a structure spec, with <slot> overlays per node/edge for dropdowns/labels
+│       ├── SearchableEntityDropdown.vue   # debounced server-side entity search; emits {id, name, label}
+│       ├── SearchableRelationDropdown.vue # debounced server-side relation search
+│       ├── AlgorithmSelector.vue      # filters registry by query_structure + dataset
+│       ├── ResultsDashboard.vue       # composes the three panels below
+│       ├── QueryDescription.vue       # renders response.query_description as a labelled chain
+│       ├── PredictionList.vue         # ranked top-K with rank/intra_community_rank/score
+│       ├── CommunityRankCallout.vue   # rank_c explainer card
+│       └── TimingPanel.vue            # step1/step2/total bars, speedup multiplier, baseline
+├── stores/
+│   └── coinsDemo.js              # Pinia: dataset, queryStructure, algorithm, anchors, variables, relations, topK, result, loading, error
+├── views/
+│   └── demos/
+│       └── CoinsView.vue         # composes selector row + QueryGraph (in edit mode) + Reason button + ResultsDashboard
+└── router/
+    └── index.js                  # adds `/demos/coins` route
+```
+
+### Data flow
+
+1. **On mount** of `CoinsView.vue`, fire in parallel:
+   - `GET /coins/datasets` → populates dataset selector (shows `name`, `num_entities`, `num_relations`, `description` tooltip).
+   - `GET /coins/models` → registry of `{algorithm, name, description, supported_query_structures, available_datasets}`.
+   - `GET /coins/query-structures` → array of `{id, name, description, nodes[], edges[]}` consumed by both `QueryStructurePicker` and `QueryGraph`.
+2. User picks **dataset** → store commits it. Anchors/variables cleared (entity IDs are dataset-scoped).
+3. User picks **query structure** (`QueryStructurePicker` cards, each a mini `QueryGraph` render). Store resets `anchors`, `variables`, `relations` to the exact node/edge IDs defined in the chosen structure.
+4. `AlgorithmSelector` recomputes the allowed list: `models.filter(m => m.supported_query_structures.includes(currentStructure) && m.available_datasets.includes(currentDataset))`. Auto-selects the first (typically `q2b` for multi-hop, `rotate` for `1p`).
+5. Main edit area renders `QueryGraph` with the chosen structure. Over each **anchor node** it slots a `SearchableEntityDropdown` (required). Over each **variable node** it slots a `SearchableEntityDropdown` with a "Let model pick" toggle that deletes the key from `variables` when off. Over each **edge** it slots a `SearchableRelationDropdown` (required). Target node is rendered as a distinct "?" badge (never editable).
+6. Dropdown search → `GET /coins/datasets/{id}/entities?q=&page=1&page_size=50` (or `/relations`). Debounced 250 ms, pagination via "Load more". Request cancels if input changes (axios `AbortController`).
+7. Under the graph: a `FactOfTheDay`-style **"Prefill with a random triple"** link → `GET /coins/datasets/{id}/sample-triples?count=1&seed=<ISO date>` (reusing the existing seeded-daily convention), which fills `a`/`r1` for a `1p` query (skipped when structure ≠ `1p`). Uses the existing `sampleTriples` function.
+8. Top-K slider 1–10, defaults 10. "Reason" button disabled until all required anchor/relation slots are filled. Click → `POST /coins/predict` with the **exact** payload:
+   ```json
+   {
+     "dataset_id": "...",
+     "algorithm": "...",
+     "query_structure": "...",
+     "anchors": { "a|a1|a2|a3": entity_id, ... },
+     "variables": { "v1|v2": entity_id, ... },
+     "relations": { "r1|r2|r3": relation_id, ... },
+     "top_k": 10
+   }
+   ```
+   `variables` is only included for pinned entries.
+9. Response drives `ResultsDashboard`:
+   - **`QueryDescription.vue`** renders `response.query_description`.
+   - **`PredictionList.vue`** lists each prediction with `rank`, `intra_community_rank`, `entity_name`, `score` (as a progress bar 0–1), linked to a `GET /coins/datasets/{id}/entities?q=<name>` detail peek.
+   - **`CommunityRankCallout.vue`** surfaces `timing.rank_c` with copy "Found in community #N out of the partitioned KG". If `rank_c == 0` the panel says "No valid KG answers" and the inference-error path is hit instead.
+   - **`TimingPanel.vue`** renders two horizontal bars (`step1_ms`, `step2_ms` with `step1_label`/`step2_label` captions), a third bar for `baseline_estimate_ms` (with `baseline_label`), and a headline "×{speedup.toFixed(1)} faster than full-graph inference (Prop. 3.1)". `total_ms` shown as the sum.
+10. Error handling: `INFERENCE_BUSY` (429) → yellow banner "Another query is running — retry in a moment"; `INFERENCE_ERROR` (422) → red banner with `error.message` (typical case: no valid KG answers); `MODEL_UNAVAILABLE` (503) → banner suggesting a different algorithm. All via the existing `apiError()` helper.
+
+### API wrappers (`src/frontend/src/api/coins.js`)
+
+Extend the file to export:
+- `listDatasets()` → `GET /coins/datasets`
+- `searchEntities(datasetId, { q, page, pageSize, signal })` → `GET /coins/datasets/{id}/entities`
+- `searchRelations(datasetId, { q, page, pageSize, signal })` → `GET /coins/datasets/{id}/relations`
+- `sampleTriples(datasetId, count, seed)` — existing, untouched
+- `listModels()` → `GET /coins/models`
+- `listQueryStructures()` → `GET /coins/query-structures`
+- `predict(payload, { signal })` → `POST /coins/predict`
+
+All pass `signal` through to axios for cancellation. All return `response.data` unchanged.
+
+### `QueryGraph.vue` layout strategy
+
+Use the `nodes[]` and `edges[]` from `GET /coins/query-structures` directly. For each of the 7 structures, assign fixed 2D **direction unit vectors** (not fixed pixel coordinates) keyed by `node.id` — the component computes a geometric skeleton in `viewBox` units, but the dropdown pills are the source of truth for pixel positions. Render:
+- `<line>` per edge, arrow marker reused from `FloatingMotif.vue`'s `motif-arrow` pattern. Edge endpoints are recomputed each layout pass from the actual bounding boxes of the node pills (see below).
+- A `<foreignObject>` per node and per edge exposing `<slot name="node-{id}" :node="node">` / `<slot name="edge-{id}" :edge="edge">`. The slot contents — the dropdown pills — are plain HTML and size themselves to their label text. Falls back to a small `<circle>` + text label when no slot is provided, so `QueryStructurePicker` cards render clean compact mini-previews.
+
+### Responsive pill sizing and layout
+
+Entity and relation names vary by orders of magnitude (WordNet: "domestic_dog_NN_1"; Freebase: long multi-word labels; NELL: "concept_athletecoach_thomaspace"). The pills **must grow with their label** and the graph **must reflow** so pills never overlap.
+
+- Each `SearchableEntityDropdown` / `SearchableRelationDropdown` renders as an **inline-block pill** (`.ui.label`-derived) with `width: max-content; max-width: min(40ch, 90vw); white-space: normal; overflow-wrap: anywhere; padding: 0.4em 0.8em`. Empty state shows a placeholder ("Pick entity", "Pick relation") so the pill has a sensible minimum size. Filled state shows `label || name`, truncated with a tooltip (`title=name`) only when it exceeds `max-width`.
+- `QueryGraph.vue` uses a **two-pass layout**:
+  1. Initial pass places each node at its direction unit-vector × a base spacing (e.g. 160 px) inside the `viewBox`; edges are routed straight.
+  2. After the DOM paints, a `ResizeObserver` attached to every pill measures actual bounding boxes; the component then expands the skeleton along each edge until no two pill boxes overlap (padded by 16 px), recomputes the `viewBox` to fit, and reroutes edge endpoints to the pill box edges (intersect line with rectangle) instead of a circle. The container's `height` follows the final `viewBox` height.
+- The `ResizeObserver` fires on: initial mount, each dropdown selection change, window resize, and font-load (prevents FOUT-triggered overlap). Throttle via `requestAnimationFrame` to one reflow per frame.
+- Below 600 px width, the SVG viewBox falls back to a vertical stack of pills connected by short down-arrows (a "flow" mode) instead of the 2D layout — this keeps long labels legible on phones without horizontal scrolling. The `FloatingMotif` arrow marker is reused unchanged.
+- `QueryStructurePicker` cards render `QueryGraph` in **preview mode** with short static labels ("Anchor", "?"), bypassing the two-pass reflow (fixed coord map) so cards stay compact and uniform.
+
+### `stores/coinsDemo.js` shape
+
+```js
+state: {
+  datasets: [], models: [], structures: [],
+  datasetId: '', queryStructure: '', algorithm: '',
+  anchors: {}, variables: {}, relations: {},
+  topK: 10,
+  loading: false, error: '',
+  result: null
+}
+```
+
+Getters: `selectedStructure`, `allowedAlgorithms`, `canReason` (all required anchor/relation slots filled).
+Actions: `loadRegistry()`, `setStructure()`, `reason()`.
+
+### Styling
+
+Reuse CSS vars from `styles/tokens.css` (`--primary`, `--primary-soft`, `--motif-stroke`, `--motif-fill`, `--surface`, `--text-muted`, `--shadow-md`). SVG nodes mirror `FloatingMotif` stroke/fill tokens. Dropdowns use Fomantic `.ui.search` + a custom result list driven by Vue. Timing bars use `.ui.progress` overridden to green palette.
+
+## Critical files to modify
+
+- **Create**: all files under `src/frontend/src/components/coins/`, `src/frontend/src/views/demos/CoinsView.vue`, `src/frontend/src/stores/coinsDemo.js`.
+- **Edit**: `src/frontend/src/api/coins.js` (add six endpoint wrappers), `src/frontend/src/router/index.js` (add `/demos/coins` route), `src/frontend/src/components/layout/NavBar.vue` (add "Demos" link), `src/frontend/src/views/HomeView.vue` or the COINs `DemoPreviewCard` instance (drop "coming soon", add `to="/demos/coins"`).
+
+## Reusable references
+
+- `src/frontend/src/api/client.js` — axios instance + `apiError()`.
+- `src/frontend/src/api/coins.js:1-13` — existing `sampleTriples`; the new functions follow the same shape.
+- `src/frontend/src/components/home/FactOfTheDay.vue` — canonical loading/error/success pattern (mirror it for the predict flow and dropdown fetches).
+- `src/frontend/src/components/background/FloatingMotif.vue` — SVG node/edge/arrow styling, CSS-var palette, circular-ish layout scaffold to adapt per structure.
+- `src/frontend/src/components/layout/PageSection.vue` — wraps the query-builder and dashboard blocks on the demo view.
+- `src/frontend/src/components/home/SystemStatus.vue` — parallel-fetch + badge-status pattern for the registry-load step.
+- `src/frontend/src/styles/tokens.css` — palette tokens.
+- `docs/api.yaml` — authoritative request/response shapes (keep open while wiring `predict`).
+
+## Implementation Steps
+
+1. **API layer**: extend `src/frontend/src/api/coins.js` with `listDatasets`, `searchEntities`, `searchRelations`, `listModels`, `listQueryStructures`, `predict`. Thread `AbortSignal` through each. Manual smoke test via browser devtools against local backend.
+2. **Pinia store**: create `src/frontend/src/stores/coinsDemo.js` with state/getters/actions described above. Add `loadRegistry()` firing the three parallel fetches.
+3. **Router + nav**: register `/demos/coins` in `router/index.js` (lazy-loaded). Add "Demos" link to `NavBar.vue`. Point the COINs `DemoPreviewCard` on Home to `/demos/coins` and drop the "Coming soon" label.
+4. **Shared `QueryGraph.vue`**: renders any structure (node+edge spec in → SVG out) with per-node and per-edge slots and a small hard-coded coord map for the 7 structures. Re-use `FloatingMotif`'s arrow marker and CSS vars.
+5. **`QueryStructurePicker.vue`**: grid of cards, each showing a mini `QueryGraph` (no slots, labels-only) + the structure's `name` and `description`. Emits the chosen ID.
+6. **`SearchableEntityDropdown.vue` / `SearchableRelationDropdown.vue`**: controlled input with 250 ms debounce, axios cancel on keystroke, "Load more" pager. Fomantic `.ui.search` styling. Emit `{id, name, label}`; display `label || name`. Pills size to content per the responsive rules above.
+7. **`AlgorithmSelector.vue`**: plain dropdown, options derived from `store.allowedAlgorithms` getter. Shows `name` with `description` tooltip.
+8. **`CoinsView.vue`**: composes the top selector row (dataset + structure picker + algorithm + top-K slider + "Prefill random" link for `1p`), the main `QueryGraph` in edit mode (slots wired to the dropdowns), and the bottom "Reason" button that calls `store.reason()`. Handles the three error classes with banner components.
+9. **Dashboard panels**: `QueryDescription.vue`, `PredictionList.vue`, `CommunityRankCallout.vue`, `TimingPanel.vue`. Compose them in `ResultsDashboard.vue`. Bars via `.ui.progress` with inline-style widths proportional to `total_ms` (or `baseline_estimate_ms` as the denominator, whichever is larger, for a fair visual).
+10. **Responsive + dark-mode pass**: verify ≤768 px stacks vertically; SVG viewBox scales; dropdowns full-width on mobile; reflow kicks in below 600 px. Toggle `data-theme="dark"` and confirm palette.
+11. **Polish**: accessibility labels on every SVG overlay (`aria-label`), `prefers-reduced-motion` respected, keyboard navigation through dropdowns.
+
+## Verification
+
+1. Start the backend locally on the GPU box: `python src/backend/manage.py runserver 0.0.0.0:8000` (checkpoints download on first boot). Confirm `GET http://localhost:8000/api/v1/health` returns all datasets loaded.
+2. Run the frontend: `cd src/frontend && npm run dev`. Open `http://localhost:5173/demos/coins`.
+3. For each of the 7 query structures (`1p, 2p, 3p, 2i, 3i, ip, pi`):
+   - Pick dataset (rotate through `wordnet`, `freebase`, `nell`).
+   - Verify `AlgorithmSelector` shows only compatible algorithms (only `q2b` for multi-hop; all for `1p`).
+   - Fill anchors and relations via the searchable dropdowns (verify `?q=` filtering and pagination).
+   - For structures with variables (`2p/3p/ip/pi`), test **both** letting the backend sample (omit key) and pinning a variable.
+   - Click "Reason". Dashboard renders `query_description`, exactly `top_k` predictions with monotonic `rank`, non-zero `timing.total_ms`, and a `speedup ≥ 1`.
+4. Seeded-daily prefill on `1p`: click "Prefill with a random triple" → anchor + relation populate from the day's seeded `sample-triples` call.
+5. 429 path: in one tab hold a long-running `predict`; fire a second in another tab → friendly "retry shortly" banner, no crash.
+6. 422 path: craft a query with no valid KG answers (e.g., mismatched entity/relation combo) → red banner with `INFERENCE_ERROR` message; no results list rendered.
+7. Responsive: resize to 375 px width, confirm SVG scales and controls stack. Toggle dark mode, confirm palette. Pick a long-named entity (e.g. NELL `concept_athletecoach_thomaspace`) and verify the pill grows and the graph reflows without overlap.
+8. Postman: cross-check `POST /coins/predict` request body captured from devtools matches an example from `docs/api.yaml` / `docs/postman/` to confirm field names (`anchors`, `variables`, `relations`, `query_structure`, `top_k`).