}
+ */
+export async function loadBDHPublishedClaims() {
+ return apiFetch('/data/precomputed/bdh_published_claims.json', { method: 'GET' });
+}
diff --git a/frontend/src/components/AccuracyPanel.jsx b/frontend/src/components/AccuracyPanel.jsx
new file mode 100644
index 0000000..71802e3
--- /dev/null
+++ b/frontend/src/components/AccuracyPanel.jsx
@@ -0,0 +1,317 @@
+/**
+ * AccuracyPanel.jsx
+ * Single responsibility: Display needle retrieval accuracy — model_answers[] vs.
+ * ground_truth_answers[] (live), plus the precomputed accuracy-vs-budget curve
+ * with a PrecomputedBadge, per CONTROLS_SPEC §2.2 and §2.3.
+ *
+ * Every readout shows a live value beside its ground-truth/baseline counterpart.
+ * Both sourced entirely from the live API response — no hardcoded comparison numbers.
+ */
+
+import React, { useMemo } from 'react';
+import PrecomputedBadge from './PrecomputedBadge';
+
+// ─── Chart dimensions ────────────────────────────────────────────────────────
+const CURVE_W = 280;
+const CURVE_H = 90;
+const PAD = { top: 8, right: 12, bottom: 22, left: 36 };
+
+// ─── Styles ──────────────────────────────────────────────────────────────────
+const s = {
+ wrapper: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '12px',
+ },
+ header: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: '8px',
+ },
+ title: { fontSize: '12px', color: '#e0e0f0', fontWeight: 600 },
+ liveLabel: {
+ display: 'inline-block',
+ background: '#001f0f',
+ border: '1px solid #3dffa0',
+ color: '#3dffa0',
+ fontSize: '10px',
+ padding: '2px 8px',
+ borderRadius: '3px',
+ },
+ scoreRow: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: '10px',
+ fontSize: '12px',
+ color: '#aaaacc',
+ },
+ scoreBig: (val) => ({
+ fontSize: '22px',
+ fontWeight: 700,
+ color: val >= 0.8 ? '#3dffa0' : val >= 0.5 ? '#ffb347' : '#ff6b6b',
+ }),
+ tableHeader: {
+ display: 'grid',
+ gridTemplateColumns: '28px 1fr 1fr',
+ gap: '4px',
+ fontSize: '10px',
+ textTransform: 'uppercase',
+ letterSpacing: '0.08em',
+ color: '#666',
+ padding: '0 4px',
+ marginBottom: '2px',
+ },
+ needleRow: {
+ display: 'grid',
+ gridTemplateColumns: '28px 1fr 1fr',
+ gap: '4px',
+ padding: '4px',
+ borderRadius: '4px',
+ background: '#13131c',
+ marginBottom: '3px',
+ alignItems: 'center',
+ fontSize: '11px',
+ },
+ answerChip: (correct) => ({
+ padding: '2px 8px',
+ borderRadius: '3px',
+ background: correct ? 'rgba(61,255,160,0.1)' : 'rgba(255,107,107,0.1)',
+ border: `1px solid ${correct ? '#3dffa0' : '#ff6b6b'}`,
+ color: correct ? '#3dffa0' : '#ff6b6b',
+ fontSize: '10px',
+ fontFamily: 'monospace',
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ }),
+ correctChip: {
+ padding: '2px 8px',
+ borderRadius: '3px',
+ background: 'rgba(123,140,255,0.1)',
+ border: '1px solid #7b8cff',
+ color: '#c0c8ff',
+ fontSize: '10px',
+ fontFamily: 'monospace',
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ curveSection: {
+ borderTop: '1px solid #2a2a3a',
+ paddingTop: '10px',
+ },
+ curveTitleRow: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: '6px',
+ marginBottom: '6px',
+ fontSize: '11px',
+ color: '#ccc',
+ flexWrap: 'wrap',
+ },
+ chartBox: {
+ background: '#0d0d12',
+ border: '1px solid #2a2a3a',
+ borderRadius: '5px',
+ overflow: 'hidden',
+ },
+ emptyNote: {
+ fontSize: '10px',
+ color: '#555',
+ padding: '8px 0',
+ },
+};
+
+/**
+ * AccuracyPanel
+ *
+ * Props:
+ * modelAnswers {string[]} Live — from /simulate { model_answers }
+ * correctAnswers {string[]} Ground truth — from /simulate { ground_truth_answers }
+ * liveAccuracyScore {number} Live — from /simulate { accuracy_score }
+ * currentBudgetSize {number} Current budget for live dot placement on curve
+ * accuracyVsBudget {object[]} Precomputed curve [{budget, accuracy}] — from accuracy_vs_budget.json
+ *
+ * @see CONTROLS_SPEC.md §2.2, §2.3
+ */
+function AccuracyPanel({
+ modelAnswers = [],
+ correctAnswers = [],
+ liveAccuracyScore = null,
+ currentBudgetSize = 64,
+ accuracyVsBudget = [],
+}) {
+ const pct = liveAccuracyScore !== null ? Math.round(liveAccuracyScore * 100) : null;
+
+ // Build curve SVG points from precomputed data
+ const { curvePoints, livePoint } = useMemo(() => {
+ if (!accuracyVsBudget || accuracyVsBudget.length === 0) {
+ return { curvePoints: '', livePoint: null };
+ }
+
+ const usableW = CURVE_W - PAD.left - PAD.right;
+ const usableH = CURVE_H - PAD.top - PAD.bottom;
+ const maxBudget = Math.max(...accuracyVsBudget.map((d) => d.budget), currentBudgetSize, 1);
+
+ const pts = accuracyVsBudget
+ .map(({ budget, accuracy }) => {
+ const x = PAD.left + (budget / maxBudget) * usableW;
+ const y = PAD.top + usableH - accuracy * usableH;
+ return `${x.toFixed(1)},${y.toFixed(1)}`;
+ })
+ .join(' ');
+
+ // Live dot position
+ const lx = PAD.left + (currentBudgetSize / maxBudget) * usableW;
+ const ly =
+ liveAccuracyScore !== null
+ ? PAD.top + usableH - liveAccuracyScore * usableH
+ : null;
+
+ return {
+ curvePoints: pts,
+ livePoint: ly !== null ? { x: lx, y: ly } : null,
+ };
+ }, [accuracyVsBudget, currentBudgetSize, liveAccuracyScore]);
+
+ const hasData = modelAnswers.length > 0;
+ const hasCurve = accuracyVsBudget.length > 0;
+
+ return (
+
+
+ {/* ── Section A header ── */}
+
+ Needle Retrieval Accuracy
+ LIVE
+
+
+ {/* ── Overall score ── */}
+ {pct !== null && (
+
+ {pct}%
+
+ {modelAnswers.filter((a, i) => a === correctAnswers[i]).length} of{' '}
+ {correctAnswers.length} needles correctly retrieved
+
+
+ )}
+
+ {/* ── Section A: Needle table (CONTROLS_SPEC §2.2) ── */}
+ {hasData ? (
+ <>
+
+ #
+ Model output
+ Correct answer
+
+ {correctAnswers.map((correct, i) => {
+ const model = modelAnswers[i] ?? '—';
+ const isCorrect = model === correct;
+ return (
+
+
+ {i + 1}
+
+
+ {isCorrect ? '✓ ' : '✗ '}{model}
+
+
+ {correct}
+
+
+ );
+ })}
+
+ ) : (
+
Run a simulation to see needle retrieval results.
+ )}
+
+ {/* ── Section B: Accuracy-vs-budget curve (CONTROLS_SPEC §2.3) ── */}
+
+
+
Accuracy vs. Budget
+ {/* CONTROLS_SPEC §3 placement #1 — mandatory PrecomputedBadge on the curve */}
+
+
+
+ {hasCurve ? (
+
+
+ {/* Axes */}
+ 50%
+
+ );
+ })()}
+
+ {/* Axis labels */}
+ 100%
+ Budget →
+
+ {/* Precomputed curve (orange) */}
+
+ Current
+
+
+ )}
+
+
+ ) : (
+
+ Precomputed curve not yet loaded — check backend /data/precomputed/ endpoint.
+
+ )}
+
+ {/* Legend */}
+
+
+
+
+
This run ({currentBudgetSize} tok)
+
+
+
+
+
+
+
+ BDH Recurrent — Fixed-Size State
+
+
+ {/* Two-column comparison: live (our toy) vs. published (paper) */}
+
+
+ {/* Left — live results from our simulator */}
+
+
Our toy simulator LIVE
+
+ Cache size
+ {cacheSize}
+
+
+ Retrieval accuracy
+ {accuracy}
+
+
+ Memory growth
+ O(1) — flat
+
+
+
+ {/* Right — published claims (precomputed) */}
+
+
+ BDH paper
+ {/* CONTROLS_SPEC §3 placement #2 — mandatory */}
+
+
+ {publishedClaims?.claims ? (
+ publishedClaims.claims.map((c, i) => (
+
+ {c.label}
+ {c.value}
+
+ ))
+ ) : (
+
+ Precomputed data not loaded yet — check /data/precomputed/bdh_published_claims.json
+
+ )}
+
+
+
+ {/* BDH mechanism diagram / explanation */}
+
+
How BDH's fixed-size state works
+
+ Instead of appending a new row to a KV cache for every token, BDH maintains
+ a fixed synaptic weight matrix W of
+ constant size. When a new key–value pair (k, v) arrives, it is written
+ into W by a local Hebbian update:
+
+
+ W ← W + k·vᵀ (no append, no eviction — just overwrite)
+
+
+ Reading is a matrix lookup: v̂ = W·q.
+ Older associations are overwritten ("forgotten") by interference, not by eviction.
+ This is why memory is O(1) — the state never grows.
+
+
+
+ {/* Scale disclaimer */}
+
+ Our toy simulator demonstrates the O(1) memory property only. The BDH paper's
+ published accuracy numbers are from a full-scale model — orders of magnitude
+ larger than our toy. This comparison is illustrative, not quantitative.
+
+
+
+ );
+}
+
+/**
+ * CacheHeatmap
+ *
+ * Props:
+ * aliveTokenIndices {number[]} Indices of tokens still in cache — from /simulate response
+ * sequenceLength {number} Total sequence length — determines grid columns
+ * needlePositions {number[]} Token indices that are needle facts
+ * cachePolicy {string} Active policy — drives annotation text
+ * isLoading {boolean} Show loading state while simulation is in-flight
+ *
+ * @see CONTROLS_SPEC.md §2.4
+ */
+function CacheHeatmap({
+ aliveTokenIndices = [],
+ sequenceLength = 128,
+ needlePositions = [],
+ cachePolicy = 'full',
+ isLoading = false,
+}) {
+ // Number of grid columns — cap at 64 for readability, group wider sequences
+ const cols = useMemo(() => {
+ if (sequenceLength <= 64) return sequenceLength;
+ if (sequenceLength <= 128) return 64;
+ return 64; // always 64 columns max; multiple rows for longer seqs
+ }, [sequenceLength]);
+
+ const aliveSet = useMemo(() => new Set(aliveTokenIndices), [aliveTokenIndices]);
+ const needleSet = useMemo(() => new Set(needlePositions), [needlePositions]);
+
+ const aliveCount = aliveTokenIndices.length;
+ const evictedCount = sequenceLength - aliveCount;
+ const needlesAlive = needlePositions.filter((n) => aliveSet.has(n)).length;
+
+ // Build cell state arrays
+ const policyCells = useMemo(() =>
+ Array.from({ length: sequenceLength }, (_, i) => {
+ const isNeedle = needleSet.has(i);
+ const isAlive = aliveSet.has(i);
+ if (isNeedle && isAlive) return 'needle_alive';
+ if (isNeedle && !isAlive) return 'needle_evicted';
+ return isAlive ? 'alive' : 'evicted';
+ }),
+ [sequenceLength, aliveSet, needleSet]
+ );
+
+ const baselineCells = useMemo(() =>
+ Array.from({ length: sequenceLength }, (_, i) =>
+ needleSet.has(i) ? 'baseline_needle' : 'baseline'
+ ),
+ [sequenceLength, needleSet]
+ );
+
+ if (isLoading) {
+ return (
+
+ Simulating…
+
+ );
+ }
+
+ return (
+
+
+ {/* Header */}
+
+
+ Token Cache State
+
+ LIVE
+
+ {cachePolicy.replace('_', ' ').replace(/\b\w/g, c => c.toUpperCase())}
+
+
+
+ {/* Per-policy annotation — Agent 2: makes each policy visually distinct */}
+
+ {POLICY_DESCRIPTIONS[cachePolicy] || 'Unknown policy.'}
+
+
+ {/* Stats row */}
+
+ In cache: {aliveCount}
+ Evicted: {evictedCount}
+
+ Needles retained:{' '}
+
+ {needlesAlive}/{needlePositions.length}
+
+
+
+
+ {/* Policy row — current cache state */}
+
+
Current policy ↓
+
+ {policyCells.map((state, i) => (
+
+
+
+ {/* Divider */}
+
vs. Full Cache baseline
+
+ {/* Baseline row — all tokens alive */}
+
+
Full cache baseline — all alive ↓
+
+ {baselineCells.map((state, i) => (
+
+
+
+ {/* Legend */}
+
+ {[
+ { color: CELL_COLORS.alive, label: 'In cache' },
+ { color: CELL_COLORS.evicted, label: 'Evicted' },
+ { color: CELL_COLORS.needle_alive, label: 'Needle (in cache)' },
+ { color: CELL_COLORS.needle_evicted, label: 'Needle (evicted!)' },
+ ].map(({ color, label }) => (
+
+ ))}
+
+
+
+ Live cache state — per CONTROLS_SPEC §2.4
+
+
+ {/* ── Not yet implemented placeholder ── */}
+
ComprehensionCheck — not yet implemented
+
+ {/*
+ Day 3 implementation notes:
+ - Render QUESTIONS one at a time (or both at once — UX TBD with Docs/Design lead).
+ - On both correct: call onPass() → GuidedWalkthrough advances to step 5, sandbox unlocks.
+ - On incorrect: show explanation, allow retry with no penalty.
+ - Questions should NOT have correct answers hardcoded visibly in the DOM.
+ */}
+
+
+ {/* ── 1.1 Cache Policy ── */}
+
+
Cache Policy
+
+ {POLICIES.map(({ value, label, desc }) => (
+
handlePolicyChange(value)}
+ style={s.policyBtn(cachePolicy === value, value)}
+ disabled={isLoading}
+ >
+ {label}
+ {desc}
+
+ ))}
+
+ {/* CONTROLS_SPEC §1.1 — cachePolicy → POST /simulate { policy } */}
+
+
+ {/* ── 1.2 Budget Size ── */}
+
+
+ Budget Size
+ {isBudgetDisabled && (n/a for Full Cache) }
+
+
+ 8
+ {budgetSize} tokens
+ 512
+
+
+ {isBudgetDisabled && (
+
Enable eviction policy to use budget control.
+ )}
+ {/* CONTROLS_SPEC §1.2 — budgetSize → POST /simulate { budget } */}
+
+
+ {/* ── 1.3 Sequence Length ── */}
+
+
Sequence Length
+
+ 32
+ {sequenceLength} tokens
+ 512
+
+
+ {/* CONTROLS_SPEC §1.3 — sequenceLength → POST /simulate { seq_len } */}
+
+
+ {/* ── 1.4 Needle Count ── */}
+
+
Needle Count
+
+
handleNeedleChange(-1)}
+ style={s.stepperBtn}
+ disabled={needleCount <= 1 || isLoading}
+ aria-label="Decrease needle count"
+ >
+ −
+
+
{needleCount}
+
handleNeedleChange(1)}
+ style={s.stepperBtn}
+ disabled={needleCount >= 5 || isLoading}
+ aria-label="Increase needle count"
+ >
+ +
+
+
needle{needleCount !== 1 ? 's' : ''} (1–5)
+
+ {/* CONTROLS_SPEC §1.4 — needleCount → POST /simulate { num_needles } */}
+
+
+ {/* ── Manual Run button (for when sliders don't auto-trigger) ── */}
+
runSimulation()}
+ style={isLoading ? s.loadingRunBtn : s.runBtn}
+ disabled={isLoading}
+ aria-label="Run simulation"
+ >
+ {isLoading ? 'Simulating…' : '▶ Run Simulation'}
+
+
+
+
⚠ Component Error:
+
+ {this.state.error.message}
+
+
this.setState({ error: null })}
+ style={{
+ marginTop: '12px', padding: '6px 16px', background: '#3a0000',
+ border: '1px solid #ff6b6b', color: '#ff6b6b', cursor: 'pointer',
+ borderRadius: '4px', fontFamily: 'inherit',
+ }}
+ >
+ Retry
+
+
Full Cache , nothing is ever deleted. Every new token adds one row
+ to the cache. Watch the memory chart: as sequence length grows, the cache grows with it
+ — linearly, one step at a time. This is the cost of "perfect memory."
+ `,
+ hint: 'Drag the Sequence Length slider right and watch the memory chart climb.',
+ highlightControl: 'sequenceLength',
+ },
+ {
+ id: 2,
+ title: 'Sliding Window — Simple Eviction, Clear Trade-off',
+ controlOverrides: {
+ cachePolicy: 'sliding_window',
+ sequenceLength: 128,
+ budgetSize: 64,
+ needleCount: 2,
+ },
+ narration: `
+ Sliding Window (StreamingLLM — Xiao et al., arXiv:2309.17453) caps memory by keeping only the
+ most recent budget tokens. The cache stops growing once it reaches the budget —
+ the memory chart plateaus while the full-cache baseline keeps climbing.
+ But look at the heat-map: the tokens from the beginning of the sequence are gone.
+ If one of the needle facts was buried early in the text, the model can no longer see it.
+ Lower the budget and watch accuracy drop — that's the trade-off made explicit.
+ `,
+ hint: 'Lower the Budget slider and watch needles disappear from the heat-map.',
+ highlightControl: 'budgetSize',
+ },
+ {
+ id: 3,
+ title: 'Heavy Hitter — Smarter Eviction, Different Failure Mode',
+ controlOverrides: {
+ cachePolicy: 'heavy_hitter',
+ sequenceLength: 128,
+ budgetSize: 64,
+ needleCount: 2,
+ },
+ narration: `
+ Heavy Hitter (H2O — Zhang et al., arXiv:2306.14048) evicts differently: instead of discarding the
+ oldest tokens, it scores every token by how much cumulative attention it has received
+ and keeps the top budget "heavy hitters."
+ Tokens that were attended to often — including the needle facts — tend to survive.
+ Compare the heat-map with Sliding Window: the alive cells are no longer a contiguous
+ recent window; they are scattered wherever the model "cared" most.
+ Accuracy at the same budget is often higher than Sliding Window — but the eviction
+ pattern is harder to predict, and a needle buried in an unattended region can still be lost.
+ `,
+ hint: 'Switch back to Sliding Window at the same budget and compare the heat-map patterns.',
+ highlightControl: 'cachePolicy',
+ },
+ {
+ id: 4,
+ title: 'BDH — Removing the Growth Entirely',
+ controlOverrides: {
+ cachePolicy: 'bdh_recurrent',
+ sequenceLength: 128,
+ budgetSize: 64,
+ needleCount: 2,
+ },
+ narration: `
+ Learning objective: Understand how BDH (Yıldız et al., arXiv:2509.26507)
+ eliminates cache growth entirely by architectural design, not eviction.
+ BDH Recurrent takes a different architectural approach. Instead of
+ appending to a growing list of keys and values, it maintains a fixed-size state
+ that is overwritten by a local Hebbian update rule as each new token arrives.
+ Memory never grows — it is O(1) regardless of sequence length. The memory chart is flat
+ from the first token to the last.
+ But this comes with a different failure mode: not eviction, but interference .
+ New information overwrites old information in-place. The model can't "look back" at a
+ specific earlier token — it can only recall what survived successive overwrites.
+ Note on BDH-CQ: The same paper introduces a BDH-CQ (contrastive-query)
+ variant. Its relationship to standard KV cache eviction is indirect — this module teaches
+ the core BDH memory model only, not BDH-CQ specifically.
+ `,
+ hint: 'Compare the BDH memory chart with Full Cache — flat vs. linear growth.',
+ highlightControl: 'cachePolicy',
+ },
+ {
+ id: 5,
+ title: 'Trade-offs — The Full Picture',
+ controlOverrides: null, // sandbox mode — no forced override
+ narration: `
+ You have now seen all four approaches:
+ Full Cache — perfect memory, unbounded cost.
+ Sliding Window — bounded cost, loses early context predictably.
+ Heavy Hitter — bounded cost, keeps attended tokens, unpredictable gaps.
+ BDH Recurrent — O(1) memory, forgetting via interference, not eviction.
+
+
+ {/* Step indicator dots */}
+
+ {STEPS.map((step, idx) => {
+ const dotState =
+ idx + 1 < walkthroughStep ? 'done' :
+ idx + 1 === walkthroughStep ? 'active' : 'pending';
+ return (
+
+ {idx > 0 &&
}
+
+ {idx + 1 < walkthroughStep ? '✓' : step.id}
+
+
+ );
+ })}
+
+
+ {/* Narration */}
+
+
+ Step {walkthroughStep}: {currentStep.title}
+
+
+ {currentStep.hint && (
+
💡 {currentStep.hint}
+ )}
+
+
+ {/* Navigation */}
+
+
+ ← Back
+
+
+ {isLoading ? '…' : isLastStep ? 'Done' : 'Next →'}
+
+ {!sandboxUnlocked && walkthroughStep < STEPS.length && (
+
+ Skip to sandbox
+
+ )}
+
+
+
+ Simulating…
+
+ );
+ }
+
+ const hasData = cacheSizeHistory.length > 0;
+
+ return (
+
+
+ {/* Header */}
+
+ Memory Footprint
+ LIVE
+ {isMock && (
+
+ DEMO MODE — backend not connected
+
+ )}
+
+
+ {/* Stats */}
+
+ Policy cache size: {lastLive} tokens
+ Full-cache baseline: {lastBaseline} tokens
+ {cachePolicy !== 'full' && (
+
+ Memory saved:{' '}
+ 0 ? '#3dffa0' : '#aaa' }}>
+ {savingsPct}%
+
+
+ )}
+
+
+ {/* SVG Chart */}
+
+
+ {/* Grid lines */}
+ {yTicks.map(({ y, val }) => (
+
+
+ {val}
+
+
+ ))}
+
+ {/* X axis ticks */}
+ {xTicks.map(({ x, val }) => (
+
+ {val}
+
+ ))}
+
+ {/* Axis labels */}
+
+ Tokens in cache
+
+
+ Generation step
+
+
+ {/* Axes */}
+
+ Run a simulation to see data
+
+ )}
+
+
+
+ {/* Legend */}
+
+
+
+
+ Live policy ({cachePolicy.replace('_', ' ')})
+
+
+
+
+ Full-cache baseline (reference)
+
+
+
+
+ Live — computed this run · CONTROLS_SPEC §2.1
+
+
+ {text}
+
+ );
+}
+
+export default PrecomputedBadge;
diff --git a/frontend/src/components/Sandbox.jsx b/frontend/src/components/Sandbox.jsx
new file mode 100644
index 0000000..c4e75b2
--- /dev/null
+++ b/frontend/src/components/Sandbox.jsx
@@ -0,0 +1,451 @@
+/**
+ * Sandbox.jsx
+ * Single responsibility: Render the free-play mode view where all four controls
+ * (cachePolicy, budgetSize, sequenceLength, needleCount) are unlocked simultaneously,
+ * without guided walkthrough constraints, per PRD §4.3.
+ *
+ * Day 4: Fully implemented. Uses the SAME simulationStore + api/client.js as the
+ * guided flow — Sandbox is NOT a separate code path. It is the same live wiring
+ * with the walkthrough's narrative rails removed.
+ */
+
+import React from 'react';
+import { useSimulation } from '../state/simulationStore';
+import CacheHeatmap from './CacheHeatmap';
+import MemoryChart from './MemoryChart';
+import AccuracyPanel from './AccuracyPanel';
+import BDHModule from './BDHModule';
+
+// ─── Styles ──────────────────────────────────────────────────────────────────
+const s = {
+ // Locked overlay
+ lockedWrapper: {
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ justifyContent: 'center',
+ padding: '32px 20px',
+ background: '#0f0f14',
+ borderTop: '1px solid #2a2a3a',
+ gap: '12px',
+ textAlign: 'center',
+ },
+ lockIcon: { fontSize: '28px' },
+ lockTitle: { fontSize: '14px', color: '#e0e0f0', fontWeight: 600 },
+ lockDesc: { fontSize: '12px', color: '#888', maxWidth: '360px', lineHeight: 1.6 },
+
+ // Unlocked sandbox
+ sandboxWrapper: {
+ background: '#0f0f14',
+ borderTop: '2px solid #7b8cff',
+ },
+ sandboxHeader: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: '12px',
+ padding: '10px 20px',
+ background: '#16161f',
+ borderBottom: '1px solid #2a2a44',
+ flexWrap: 'wrap',
+ },
+ sandboxTitle: {
+ fontSize: '13px',
+ fontWeight: 700,
+ color: '#c0c8ff',
+ letterSpacing: '0.04em',
+ },
+ sandboxTag: {
+ fontSize: '10px',
+ background: 'rgba(123,140,255,0.12)',
+ border: '1px solid #7b8cff',
+ color: '#7b8cff',
+ padding: '2px 10px',
+ borderRadius: '12px',
+ },
+ backBtn: {
+ marginLeft: 'auto',
+ fontSize: '11px',
+ background: 'transparent',
+ border: '1px solid #444',
+ color: '#888',
+ padding: '4px 12px',
+ borderRadius: '4px',
+ cursor: 'pointer',
+ fontFamily: 'inherit',
+ whiteSpace: 'nowrap',
+ },
+ // Sandbox body — same 3-col layout, but controls have NO budget-disable rule for full policy
+ sandboxBody: {
+ display: 'grid',
+ gridTemplateColumns: '260px 1fr 300px',
+ minHeight: '500px',
+ },
+ // Mobile: single column
+ sandboxBodyMobile: {
+ display: 'flex',
+ flexDirection: 'column',
+ },
+ controlsPane: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '16px',
+ padding: '16px',
+ background: '#13131c',
+ borderRight: '1px solid #2a2a3a',
+ overflowY: 'auto',
+ },
+ sectionTitle: {
+ fontSize: '11px',
+ textTransform: 'uppercase',
+ letterSpacing: '0.12em',
+ color: '#7b8cff',
+ borderBottom: '1px solid #2a2a44',
+ paddingBottom: '4px',
+ marginBottom: '6px',
+ },
+ policyGrid: {
+ display: 'grid',
+ gridTemplateColumns: '1fr 1fr',
+ gap: '4px',
+ },
+ policyBtn: (selected) => ({
+ border: `1px solid ${selected ? '#7b8cff' : '#333'}`,
+ background: selected ? 'rgba(123,140,255,0.14)' : '#1a1a26',
+ color: selected ? '#c0c8ff' : '#888',
+ padding: '9px 6px',
+ borderRadius: '4px',
+ fontSize: '11px',
+ textAlign: 'center',
+ cursor: 'pointer',
+ lineHeight: 1.3,
+ minHeight: '44px', // touch-friendly
+ display: 'flex',
+ flexDirection: 'column',
+ alignItems: 'center',
+ justifyContent: 'center',
+ fontFamily: 'inherit',
+ }),
+ slider: {
+ width: '100%',
+ accentColor: '#7b8cff',
+ cursor: 'pointer',
+ minHeight: '28px', // touch-friendly
+ },
+ sliderRow: {
+ display: 'flex',
+ justifyContent: 'space-between',
+ fontSize: '11px',
+ color: '#aaa',
+ marginBottom: '6px',
+ },
+ sliderVal: { color: '#7b8cff', fontWeight: 600 },
+ stepperRow: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: '12px',
+ },
+ stepperBtn: {
+ width: '44px', height: '44px', // touch-friendly
+ border: '1px solid #444',
+ background: '#1e1e2e',
+ color: '#ccc',
+ borderRadius: '4px',
+ fontSize: '22px',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ cursor: 'pointer',
+ fontFamily: 'inherit',
+ },
+ stepperVal: {
+ fontSize: '20px',
+ color: '#e0e0f0',
+ minWidth: '28px',
+ textAlign: 'center',
+ fontWeight: 600,
+ },
+ runBtn: {
+ background: '#7b8cff',
+ color: '#fff',
+ border: 'none',
+ borderRadius: '5px',
+ padding: '11px 0',
+ fontSize: '13px',
+ fontWeight: 600,
+ cursor: 'pointer',
+ width: '100%',
+ fontFamily: 'inherit',
+ minHeight: '44px',
+ },
+ centerPane: {
+ display: 'flex',
+ flexDirection: 'column',
+ borderLeft: '1px solid #2a2a3a',
+ borderRight: '1px solid #2a2a3a',
+ overflowY: 'auto',
+ },
+ rightPane: {
+ display: 'flex',
+ flexDirection: 'column',
+ background: '#13131c',
+ overflowY: 'auto',
+ padding: '16px',
+ gap: '16px',
+ },
+ freeplayNote: {
+ fontSize: '10px',
+ color: '#555',
+ fontStyle: 'italic',
+ },
+};
+
+const POLICIES = [
+ { value: 'full', label: 'Full Cache', desc: 'No eviction' },
+ { value: 'sliding_window', label: 'Sliding Win.', desc: 'Recency window' },
+ { value: 'heavy_hitter', label: 'Heavy Hitter', desc: 'Top-k attention' },
+ { value: 'bdh_recurrent', label: 'BDH', desc: 'Fixed-size state' },
+];
+
+/**
+ * SandboxControls — same 4 controls as ControlPanel but:
+ * 1. Budget is NEVER disabled (even for full policy) — sandbox is free-play
+ * 2. Touch-friendly hit targets (minHeight: 44px)
+ * 3. No walkthrough narration or step constraints
+ */
+function SandboxControls() {
+ const { state, dispatch, runSimulation } = useSimulation();
+ const { cachePolicy, budgetSize, sequenceLength, needleCount } = state.controls;
+ const { isLoading } = state.ui;
+
+ const setPolicy = (val) => {
+ dispatch({ type: 'SET_CONTROL', payload: { field: 'cachePolicy', value: val } });
+ runSimulation({ cachePolicy: val });
+ };
+
+ const onBudgetChange = (e) =>
+ dispatch({ type: 'SET_CONTROL', payload: { field: 'budgetSize', value: Number(e.target.value) } });
+ const onBudgetCommit = (e) => runSimulation({ budgetSize: Number(e.target.value) });
+
+ const onSeqChange = (e) =>
+ dispatch({ type: 'SET_CONTROL', payload: { field: 'sequenceLength', value: Number(e.target.value) } });
+ const onSeqCommit = (e) => runSimulation({ sequenceLength: Number(e.target.value) });
+
+ const onNeedle = (delta) => {
+ const val = Math.min(5, Math.max(1, needleCount + delta));
+ dispatch({ type: 'SET_CONTROL', payload: { field: 'needleCount', value: val } });
+ runSimulation({ needleCount: val });
+ };
+
+ return (
+
+
+
Sandbox — Free Play
+
All controls unlocked. No narration constraints.
+
+
+ {/* Policy */}
+
+
Cache Policy
+
+ {POLICIES.map(({ value, label, desc }) => (
+
setPolicy(value)}
+ disabled={isLoading}
+ >
+ {label}
+ {desc}
+
+ ))}
+
+
+
+ {/* Budget — NEVER disabled in Sandbox */}
+
+
Budget Size
+
+ 8
+ {budgetSize} tokens
+ 512
+
+
+
+ Budget active for all policies in Sandbox mode
+
+
+
+ {/* Sequence Length */}
+
+
Sequence Length
+
+ 32
+ {sequenceLength} tokens
+ 512
+
+
+
+
+ {/* Needle Count */}
+
+
Needle Count
+
+
onNeedle(-1)}
+ disabled={needleCount <= 1 || isLoading}
+ aria-label="Decrease needle count"
+ >−
+
{needleCount}
+
onNeedle(1)}
+ disabled={needleCount >= 5 || isLoading}
+ aria-label="Increase needle count"
+ >+
+
(1–5)
+
+
+
+ {/* Run */}
+
runSimulation()}
+ disabled={isLoading}
+ aria-label="Run simulation in sandbox"
+ >
+ {isLoading ? 'Simulating…' : '▶ Run Simulation'}
+
+
+
🔒
+
Sandbox Locked
+
+ Complete the guided walkthrough (steps 1–4) to unlock free-play mode,
+ where every control is available simultaneously with no constraints.
+
+
+
+ {/* Sandbox header */}
+
+ 🧪 Sandbox
+ Free Play — all controls unlocked
+
+ Same live backend, no walkthrough constraints
+
+
+ ← Back to walkthrough
+
+
+
+ {/* Error state if any */}
+ {ui.errorMessage && (
+
+ Error: {ui.errorMessage}
+
+ )}
+
+ {/* 3-column body — same layout as guided, same data from same store */}
+
+
+ {/* Left: controls (all unlocked) */}
+
+
+ {/* Center: Heatmap + MemoryChart — same components, same store props */}
+
+
+ {/* Right: AccuracyPanel + BDHModule — same components */}
+
+
+ {showBDH && (
+
+ )}
+
+
+
+
+
+
+);
diff --git a/frontend/src/state/simulationStore.jsx b/frontend/src/state/simulationStore.jsx
new file mode 100644
index 0000000..e2a8f9e
--- /dev/null
+++ b/frontend/src/state/simulationStore.jsx
@@ -0,0 +1,230 @@
+/**
+ * state/simulationStore.jsx ← renamed from .js (contained JSX)
+ *
+ * Single responsibility: Hold and expose the current simulation state.
+ * Variable names exactly match CONTROLS_SPEC.md §5.
+ *
+ * DEMO MODE: When the backend at localhost:8000 is unreachable, the store
+ * falls back to deterministic mock data so the UI is fully demoable without
+ * a running backend. The mock fallback is clearly labelled with isMock=true
+ * in ui state — components surface a "DEMO MODE" badge (not PrecomputedBadge).
+ */
+
+import React, { createContext, useContext, useReducer, useCallback } from 'react';
+import { simulate, loadAccuracyVsBudget, loadBDHPublishedClaims } from '../api/client';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Initial state
+// ─────────────────────────────────────────────────────────────────────────────
+export const DEFAULT_CONTROLS = {
+ cachePolicy: 'full',
+ budgetSize: 64,
+ sequenceLength: 128,
+ needleCount: 2,
+};
+
+const EMPTY_RESULT = {
+ cacheSizeTokens: null,
+ fullCacheBaselineTokens: null,
+ aliveTokenIndices: [],
+ modelAnswers: [],
+ correctAnswers: [],
+ accuracyScore: null,
+ cacheSizeHistory: [],
+ baselineHistory: [],
+ needlePositions: [],
+};
+
+export const INITIAL_STATE = {
+ controls: { ...DEFAULT_CONTROLS },
+ result: { ...EMPTY_RESULT },
+ precomputed: { accuracyVsBudget: [], bdhPublishedClaims: null },
+ ui: {
+ walkthroughStep: 1,
+ sandboxUnlocked: false,
+ isLoading: false,
+ errorMessage: null,
+ isMock: false,
+ },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Mock data generator (demo fallback when backend is unreachable)
+// ─────────────────────────────────────────────────────────────────────────────
+function buildMockResult(controls) {
+ const { cachePolicy, budgetSize, sequenceLength, needleCount } = controls;
+ const seqLen = sequenceLength;
+
+ // Full-cache baseline always grows linearly
+ const baselineHistory = Array.from({ length: seqLen }, (_, i) => i + 1);
+
+ let aliveTokenIndices = [];
+ let cacheSizeHistory = [];
+
+ if (cachePolicy === 'full') {
+ aliveTokenIndices = Array.from({ length: seqLen }, (_, i) => i);
+ cacheSizeHistory = baselineHistory.slice();
+ } else if (cachePolicy === 'sliding_window') {
+ const start = Math.max(0, seqLen - budgetSize);
+ aliveTokenIndices = Array.from({ length: seqLen - start }, (_, i) => start + i);
+ cacheSizeHistory = Array.from({ length: seqLen }, (_, i) => Math.min(i + 1, budgetSize));
+ } else if (cachePolicy === 'heavy_hitter') {
+ // Scatter alive tokens — high-attention tokens survive
+ const stride = Math.max(1, Math.floor(seqLen / budgetSize));
+ aliveTokenIndices = Array.from({ length: Math.min(budgetSize, seqLen) }, (_, i) => i * stride);
+ cacheSizeHistory = Array.from({ length: seqLen }, (_, i) => Math.min(i + 1, budgetSize));
+ } else if (cachePolicy === 'bdh_recurrent') {
+ // Fixed-size — flat memory, spread tokens
+ const count = Math.min(budgetSize, seqLen);
+ const stride = Math.max(1, Math.floor(seqLen / count));
+ aliveTokenIndices = Array.from({ length: count }, (_, i) => i * stride);
+ cacheSizeHistory = Array.from({ length: seqLen }, () => budgetSize);
+ }
+
+ // Needle positions: evenly spread through sequence
+ const needlePositions = Array.from(
+ { length: needleCount },
+ (_, i) => Math.floor((i + 1) * seqLen / (needleCount + 1))
+ );
+
+ // Accuracy: needles in alive set = retrieved
+ const aliveSet = new Set(aliveTokenIndices);
+ const retrieved = needlePositions.filter(p => aliveSet.has(p)).length;
+ const accuracyScore = needlePositions.length > 0 ? retrieved / needlePositions.length : 1;
+
+ const answers = ['Paris', 'Newton', 'DNA', 'Einstein', 'Curie'];
+ const modelAnswers = needlePositions.map((p, i) =>
+ aliveSet.has(p) ? answers[i % answers.length] : '?'
+ );
+ const correctAnswers = needlePositions.map((_, i) => answers[i % answers.length]);
+
+ return {
+ cache_size_tokens: aliveTokenIndices.length,
+ full_cache_baseline_tokens: seqLen,
+ alive_token_indices: aliveTokenIndices,
+ model_answers: modelAnswers,
+ ground_truth_answers: correctAnswers,
+ accuracy_score: accuracyScore,
+ cache_size_history: cacheSizeHistory,
+ baseline_history: baselineHistory,
+ needle_positions: needlePositions,
+ };
+}
+
+// Mock precomputed accuracy-vs-budget curve
+function buildMockCurve() {
+ return Array.from({ length: 32 }, (_, i) => ({
+ budget: (i + 1) * 16,
+ accuracy: Math.min(0.98, 0.3 + 0.022 * (i + 1)),
+ }));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Reducer
+// ─────────────────────────────────────────────────────────────────────────────
+function reducer(state, action) {
+ switch (action.type) {
+ case 'SET_CONTROL':
+ return { ...state, controls: { ...state.controls, [action.payload.field]: action.payload.value } };
+ case 'SET_CONTROLS_BATCH':
+ return { ...state, controls: { ...state.controls, ...action.payload } };
+ case 'SET_LOADING':
+ return { ...state, ui: { ...state.ui, isLoading: action.payload, errorMessage: null } };
+ case 'SET_RESULT': {
+ const r = action.payload;
+ return {
+ ...state,
+ result: {
+ cacheSizeTokens: r.cache_size_tokens ?? null,
+ fullCacheBaselineTokens: r.full_cache_baseline_tokens ?? null,
+ aliveTokenIndices: r.alive_token_indices ?? [],
+ modelAnswers: r.model_answers ?? [],
+ correctAnswers: r.ground_truth_answers ?? [],
+ accuracyScore: r.accuracy_score ?? null,
+ cacheSizeHistory: r.cache_size_history ?? [],
+ baselineHistory: r.baseline_history ?? [],
+ needlePositions: r.needle_positions ?? [],
+ },
+ ui: { ...state.ui, isLoading: false, errorMessage: null, isMock: action.isMock ?? false },
+ };
+ }
+ case 'SET_ERROR':
+ return { ...state, ui: { ...state.ui, isLoading: false, errorMessage: action.payload } };
+ case 'SET_PRECOMPUTED':
+ return { ...state, precomputed: { ...state.precomputed, ...action.payload } };
+ case 'ADVANCE_WALKTHROUGH':
+ return { ...state, ui: { ...state.ui, walkthroughStep: Math.min(state.ui.walkthroughStep + 1, 5) } };
+ case 'BACK_WALKTHROUGH':
+ return { ...state, ui: { ...state.ui, walkthroughStep: Math.max(state.ui.walkthroughStep - 1, 1) } };
+ case 'SET_WALKTHROUGH_STEP':
+ return { ...state, ui: { ...state.ui, walkthroughStep: action.payload } };
+ case 'UNLOCK_SANDBOX':
+ return { ...state, ui: { ...state.ui, sandboxUnlocked: true } };
+ default:
+ return state;
+ }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Context
+// ─────────────────────────────────────────────────────────────────────────────
+const SimulationContext = createContext(null);
+
+export function SimulationProvider({ children }) {
+ const [state, dispatch] = useReducer(reducer, INITIAL_STATE);
+
+ const runSimulation = useCallback(async (overrides = {}) => {
+ const controls = { ...state.controls, ...overrides };
+ dispatch({ type: 'SET_LOADING', payload: true });
+ try {
+ // ── Try real backend first ──────────────────────────────────────────
+ const response = await simulate({
+ policy: controls.cachePolicy,
+ budget: controls.budgetSize,
+ seq_len: controls.sequenceLength,
+ num_needles: controls.needleCount,
+ });
+ dispatch({ type: 'SET_RESULT', payload: response, isMock: false });
+
+ // Load precomputed curve (once only)
+ if (state.precomputed.accuracyVsBudget.length === 0) {
+ try {
+ const curve = await loadAccuracyVsBudget();
+ const bdh = await loadBDHPublishedClaims();
+ dispatch({ type: 'SET_PRECOMPUTED', payload: { accuracyVsBudget: curve, bdhPublishedClaims: bdh } });
+ } catch (_) { /* precomputed optional */ }
+ }
+ } catch (_backendErr) {
+ // ── Backend unreachable → use mock data for demo ────────────────────
+ const mockResult = buildMockResult(controls);
+ dispatch({ type: 'SET_RESULT', payload: mockResult, isMock: true });
+
+ if (state.precomputed.accuracyVsBudget.length === 0) {
+ dispatch({ type: 'SET_PRECOMPUTED', payload: {
+ accuracyVsBudget: buildMockCurve(),
+ bdhPublishedClaims: { claims: [
+ { label: 'Memory growth', value: 'O(1) — constant' },
+ { label: 'Benchmark accuracy', value: '~89% (arXiv)' },
+ ]},
+ }});
+ }
+ }
+ }, [state.controls, state.precomputed.accuracyVsBudget.length]);
+
+ const applyWalkthroughStep = useCallback(async (controlOverrides) => {
+ dispatch({ type: 'SET_CONTROLS_BATCH', payload: controlOverrides });
+ await runSimulation(controlOverrides);
+ }, [runSimulation]);
+
+ return (
+
+ {children}
+
+ );
+}
+
+export function useSimulation() {
+ const ctx = useContext(SimulationContext);
+ if (!ctx) throw new Error('useSimulation must be used inside ');
+ return ctx;
+}
diff --git a/frontend/src/styles/index.css b/frontend/src/styles/index.css
new file mode 100644
index 0000000..6688577
--- /dev/null
+++ b/frontend/src/styles/index.css
@@ -0,0 +1,279 @@
+/* styles/index.css
+ * Global CSS resets, design tokens, and mobile-responsive layout rules.
+ * Day 4: Full mobile polish — audited at 375px and 414px.
+ *
+ * Mobile audit findings:
+ * - 3-column grid (260px + 1fr + 300px) breaks below ~800px — switched to stack
+ * - Heat-map cells at 64 cols × 2px gap become sub-3px at 375px — collapse to 32 cols
+ * - Sliders need minHeight 44px touch target (iOS HIG)
+ * - Guided walkthrough banner needs to stack vertically on narrow screens
+ * - Top bar claim pill hidden on phone — too dense, shows title only
+ * - Sandbox 3-col grid collapses to single column on mobile
+ */
+
+/* ── Google Fonts ─────────────────────────────────────────────────────── */
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');
+
+/* ── Design Tokens ────────────────────────────────────────────────────── */
+:root {
+ /* Colors */
+ --color-bg-base: #0f0f14;
+ --color-bg-surface: #13131c;
+ --color-bg-elevated: #1a1a28;
+ --color-border: #2a2a3a;
+ --color-text-primary: #e0e0f0;
+ --color-text-secondary: #aaaacc;
+ --color-text-muted: #666680;
+
+ /* Accent colors */
+ --color-accent-primary: #7b8cff; /* live controls, active states */
+ --color-accent-live: #3dffa0; /* LIVE badge, alive tokens */
+ --color-accent-needle: #ff6b6b; /* needle token highlight */
+ --color-accent-precomp: #f5a623; /* PrecomputedBadge orange */
+ --color-accent-correct: #3dffa0;
+ --color-accent-wrong: #ff6b6b;
+
+ /* Typography */
+ --font-ui: 'Inter', system-ui, sans-serif;
+ --font-mono: 'JetBrains Mono', 'Courier New', monospace;
+
+ /* Spacing */
+ --space-xs: 4px;
+ --space-sm: 8px;
+ --space-md: 16px;
+ --space-lg: 24px;
+ --space-xl: 40px;
+
+ /* Border radius */
+ --radius-sm: 4px;
+ --radius-md: 6px;
+ --radius-lg: 12px;
+
+ /* Touch target minimum (iOS HIG) */
+ --touch-min: 44px;
+}
+
+/* ── Reset ────────────────────────────────────────────────────────────── */
+*, *::before, *::after {
+ box-sizing: border-box;
+ margin: 0;
+ padding: 0;
+}
+
+html, body, #root {
+ height: 100%;
+ width: 100%;
+}
+
+body {
+ font-family: var(--font-ui);
+ background: var(--color-bg-base);
+ color: var(--color-text-primary);
+ font-size: 14px;
+ line-height: 1.5;
+ -webkit-font-smoothing: antialiased;
+ /* prevent horizontal scroll on mobile */
+ overflow-x: hidden;
+}
+
+/* ── Touch target: all interactive elements ────────────────────────────── */
+button, input[type="range"] {
+ min-height: var(--touch-min);
+ touch-action: manipulation;
+}
+
+/* Range inputs specifically */
+input[type="range"] {
+ -webkit-appearance: none;
+ appearance: none;
+ height: 6px;
+ border-radius: 3px;
+ background: var(--color-border);
+ outline: none;
+ cursor: pointer;
+ /* Vertically centered in its 44px touch zone via padding */
+ padding: 19px 0;
+}
+
+input[type="range"]::-webkit-slider-thumb {
+ -webkit-appearance: none;
+ appearance: none;
+ width: 20px;
+ height: 20px;
+ border-radius: 50%;
+ background: var(--color-accent-primary);
+ cursor: pointer;
+ border: 2px solid #0f0f14;
+ box-shadow: 0 0 0 3px rgba(123,140,255,0.2);
+}
+
+input[type="range"]::-moz-range-thumb {
+ width: 20px;
+ height: 20px;
+ border-radius: 50%;
+ background: var(--color-accent-primary);
+ cursor: pointer;
+ border: 2px solid #0f0f14;
+}
+
+/* ── App layout grid — responsive ─────────────────────────────────────── */
+
+/* Desktop: 3-column fixed */
+#app-shell {
+ display: flex;
+ flex-direction: column;
+ min-height: 100vh;
+}
+
+/* Main 3-column grid */
+.main-grid {
+ display: grid;
+ grid-template-columns: 260px 1fr 300px;
+ flex: 1;
+ overflow: hidden;
+}
+
+/* ── Guided Walkthrough banner mobile ─────────────────────────────────── */
+#guided-walkthrough {
+ /* on narrow screens, stack narration below dots+buttons */
+ flex-wrap: wrap;
+}
+
+/* ── Top bar — hide claim pill on narrow screens ──────────────────────── */
+@media (max-width: 600px) {
+ .topbar-claim-pill {
+ display: none !important;
+ }
+ .topbar-track-tag {
+ display: none !important;
+ }
+}
+
+/* ── Tablet/mobile breakpoint: below 800px ────────────────────────────── */
+@media (max-width: 800px) {
+ .main-grid,
+ #sandbox .sandbox-body {
+ grid-template-columns: 1fr !important;
+ display: flex !important;
+ flex-direction: column !important;
+ }
+
+ /* Control panel becomes horizontal drawer at top on mobile */
+ #control-panel {
+ border-right: none !important;
+ border-bottom: 1px solid var(--color-border) !important;
+ min-width: unset !important;
+ flex-direction: row !important;
+ flex-wrap: wrap !important;
+ gap: 12px !important;
+ padding: 12px !important;
+ overflow-x: auto !important;
+ }
+
+ #control-panel > div {
+ flex: 0 0 auto;
+ min-width: 140px;
+ }
+
+ /* Heat-map: reduce columns so cells remain tappable at 375px */
+ /* CacheHeatmap uses gridTemplateColumns via inline style;
+ this rule overrides the min cell size for legibility */
+ #cache-heatmap .heatmap-grid {
+ grid-template-columns: repeat(32, 1fr) !important;
+ }
+
+ /* Walkthrough banner stacks on mobile */
+ #guided-walkthrough {
+ flex-direction: column !important;
+ gap: 8px !important;
+ padding: 10px 12px !important;
+ }
+
+ /* Step dots go horizontal, centered */
+ .step-dots-row {
+ justify-content: center !important;
+ }
+
+ /* Sandbox columns collapse */
+ #sandbox {
+ flex-direction: column !important;
+ }
+
+ #sandbox .sandbox-body {
+ flex-direction: column !important;
+ }
+
+ #sandbox .controls-pane {
+ border-right: none !important;
+ border-bottom: 1px solid var(--color-border) !important;
+ }
+
+ /* AccuracyPanel curve SVG scales correctly */
+ #accuracy-panel svg {
+ width: 100% !important;
+ height: auto !important;
+ }
+
+ /* MemoryChart SVG scales */
+ #memory-chart svg {
+ width: 100% !important;
+ }
+}
+
+/* ── Phone breakpoint: 375px ─────────────────────────────────────────── */
+@media (max-width: 430px) {
+ body {
+ font-size: 13px;
+ }
+
+ /* Policy button grid: single column on very narrow screens */
+ .policy-grid-2col {
+ grid-template-columns: 1fr 1fr !important;
+ }
+
+ /* Stepper buttons remain 44px */
+ .stepper-btn {
+ width: var(--touch-min) !important;
+ height: var(--touch-min) !important;
+ }
+
+ /* Walkthrough nav buttons wrap */
+ .walkthrough-nav {
+ flex-wrap: wrap !important;
+ gap: 6px !important;
+ }
+
+ /* BDH two-col comparison stacks on very small screens */
+ #bdh-module .cols-grid {
+ grid-template-columns: 1fr !important;
+ }
+}
+
+/* ── Scrollbar styling (non-blocking) ─────────────────────────────────── */
+::-webkit-scrollbar {
+ width: 6px;
+ height: 6px;
+}
+::-webkit-scrollbar-track { background: #0f0f14; }
+::-webkit-scrollbar-thumb {
+ background: #2a2a3a;
+ border-radius: 3px;
+}
+::-webkit-scrollbar-thumb:hover { background: #3a3a5a; }
+
+/* ── Loading shimmer animation ────────────────────────────────────────── */
+@keyframes shimmer {
+ 0% { opacity: 0.4; }
+ 50% { opacity: 0.7; }
+ 100% { opacity: 0.4; }
+}
+
+.loading-shimmer {
+ animation: shimmer 1.2s ease-in-out infinite;
+}
+
+/* ── Utility: no horizontal overflow anywhere ─────────────────────────── */
+#app-shell, #sandbox, #guided-walkthrough {
+ max-width: 100vw;
+ overflow-x: hidden;
+}
diff --git a/frontend/vite.config.js b/frontend/vite.config.js
new file mode 100644
index 0000000..167e5ca
--- /dev/null
+++ b/frontend/vite.config.js
@@ -0,0 +1,25 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+// https://vitejs.dev/config/
+export default defineConfig(({ mode }) => ({
+ plugins: [react()],
+
+ // GitHub Pages serves the app at /CacheQuake/ (repo name).
+ // Set base to '/' when using a custom domain or Netlify/Vercel.
+ base: mode === 'production' ? '/CacheQuake/' : '/',
+
+ optimizeDeps: {
+ entries: ['src/index.jsx'],
+ },
+
+ server: {
+ port: 5173,
+ proxy: {
+ '/simulate': 'http://localhost:8000',
+ '/step': 'http://localhost:8000',
+ '/compare': 'http://localhost:8000',
+ '/data': 'http://localhost:8000',
+ },
+ },
+}));
diff --git a/frontend/wireframe.html b/frontend/wireframe.html
new file mode 100644
index 0000000..bdc2732
--- /dev/null
+++ b/frontend/wireframe.html
@@ -0,0 +1,815 @@
+
+
+
+ Memory Under Pressure — Wireframe
+
+
+
+
+
+
+
+ Memory Under Pressure
+
+ "A Transformer's KV cache grows linearly because it stores an exact copy of the past.
+ Eviction/compression cap that growth by trading exactness for a bounded budget.
+ BDH removes the growth entirely with a fixed-size overwriting state."
+
+ DataForge 2026 · Pathway × Rime
+
+
+
+
+
Guided path
+
+
1
+
+
2
+
+
3
+
+
4
+
+
5
+
+
+ Step 2 — Watch it grow:
+ The full cache (policy = Full) stores every token forever.
+ Drag the Sequence Length slider right — watch the memory chart climb linearly.
+ [GuidedWalkthrough.jsx — narration panel]
+
+
+
← Back
+
Next →
+
Skip to sandbox
+
+
+
+ GuidedWalkthrough.jsx — narration sits in this horizontal banner above all controls & readouts.
+ Steps 1–5 advance linearly; "Skip to sandbox" unlocks all controls (Sandbox.jsx).
+ ComprehensionCheck.jsx activates before step 5 unlock.
+
+
+
+
+
+
+
+
ControlPanel.jsx
+
+
+
+
Cache Policy
+
+
Full Cache
+
Sliding Window
+
Heavy Hitter
+
BDH Recurrent
+
+
+ CONTROLS_SPEC §1.1 — cachePolicy: enum "full" | "sliding_window" |
+ "heavy_hitter" | "bdh_recurrent". Maps to POST /simulate { policy }.
+ Default: "full".
+
+
+
+
+
+
+ Budget Size
+ [disabled — Full Cache]
+
+
+
+ 8 tokens
+ 64 tokens
+ 512 tokens
+
+
+
+
+ CONTROLS_SPEC §1.2 — budgetSize: integer 8–512 step 8.
+ Maps to POST /simulate { budget }. Greyed out (pointer-events:none)
+ when cachePolicy === "full".
+
+
+
+
+
+
Sequence Length
+
+
+ 32
+ 128 tokens
+ 512
+
+
+
+
+ CONTROLS_SPEC §1.3 — sequenceLength: integer 32–512 step 16.
+ Maps to POST /simulate { seq_len }. Increasing this is the primary
+ demonstration of linear KV cache growth.
+
+
+
+
+
+
Needle Count
+
+
−
+
2
+
+
+
needles (1–5)
+
+
+ CONTROLS_SPEC §1.4 — needleCount: integer 1–5.
+ Maps to POST /simulate { num_needles }. Controls how many facts
+ needle_haystack.py embeds in the sequence.
+
+
+
+
+
+ [ Sandbox.jsx — unlocked after guided steps ]
+
+ Sandbox.jsx — collapsed here during guided walkthrough.
+ Unlocked by ComprehensionCheck.jsx after step 4.
+ All four controls enabled with no narration overrides.
+
+
+
+
+
+
+
+
+
+ CacheHeatmap.jsx
+ LIVE
+
+
+ Which past tokens are still "alive" in the KV cache?
+
+
+
+
+ Current policy (Heavy Hitter) ↓
+
+
+
+
+
vs. Full Cache baseline
+
+ Full cache — all tokens alive ↓
+
+
+
+
+
+
+
+ CONTROLS_SPEC §2.4 — alive_token_indices[] (live) vs. all-alive baseline.
+ Red cells mark needle positions. Visual: "what did you lose?"
+ Label: "Live cache state" — no PrecomputedBadge here.
+
+
+
+
+
+
+ MemoryChart.jsx
+ LIVE
+
+
+ Memory footprint: live policy vs. full-cache baseline
+
+
+
+
+
+
+
+
+
+
Full-cache baseline
+
+
+
+ Generation step →
+
+
+ Tokens in cache ↑
+
+
+
+ CONTROLS_SPEC §2.1 — cache_size_tokens (live, colored line) vs.
+ full_cache_baseline_tokens (dashed grey line). Ratio live/baseline
+ shows savings. Both values from /simulate response — no PrecomputedBadge.
+
+
+
+
+
+
+
+
+
+
+ AccuracyPanel.jsx
+ LIVE
+
+
+ Needle retrieval: model answer vs. ground truth
+
+
+
+
+ Needle Model output Correct answer
+
+
+
+
#1
+
Token_42
+
Token_42
+
+
+
#2
+
Token_17
+
Token_99
+
+
+
+
+
+ Accuracy vs. budget curve
+ PRECOMPUTED
+
+
+
+
+
+
+ Budget (tokens) →
+
+
+ ● Current run
+
+
+
+ CONTROLS_SPEC §2.3 — Precomputed curve from accuracy_vs_budget.json (orange)
+ + live point at current budgetSize (blue dot).
+ PrecomputedBadge.jsx required here: "Precomputed sweep — not this run."
+
+
+
+
+
+
+
+ BDHModule.jsx
+ LIVE (our toy)
+ PRECOMPUTED (published)
+
+
+ BDH Fixed-Size Recurrent State — comparison
+
+
+
+
+
Our toy simulator
+
Memory 64 tok
+
Accuracy 50%
+
Growth Flat
+
+ LIVE
+
+
+
+
BDH paper claims
+
Memory Fixed
+
Long-ctx ↑ pub.
+
Growth O(1)
+
+ PUBLISHED
+
+
+
+
+
+ ⚠ Our toy simulator ≠ the BDH model. The comparison is illustrative only.
+ Published numbers are from arXiv:2509.26507 — not reproduced by our team.
+
+
+ CONTROLS_SPEC §2.5 — Left col: live /simulate response (bdh_recurrent policy).
+ Right col: bdh_published_claims.json — PrecomputedBadge.jsx required:
+ "Published result (arXiv:2509.26507) — not reproduced by our team."
+
+
+
+
+
+
+
+
+
+