From 50c33119024baedacb1156e10cfecd11cee4a748 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 10:52:01 -0700
Subject: [PATCH 01/20] docs(spec): landing page below the hero (#344 phase 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Interactive knowledge graph replaces the 340vh scroll-jacked HowItWorks, then
three feature bands and a four-tile bento of real app surfaces.

The structural argument is a density rhythm — the graph is the densest thing on
the page, bands decompress, the bento re-energizes, and a closing band gives the
CTA a run-up rather than ending on a grid tile.

The content argument matters more than the visual one. Tutor chat, Notes,
Gradebook and Flashcards are shipped surfaces the current six-feature list never
mentions, so the page undersells the product more than it under-designs it. That
is the likeliest root of #344's 'feels generic'.

Live LLM generation on the public page was considered and rejected for now: most
convincing option, but it puts an unauthenticated billable endpoint on the
most-crawled page on the site. Recorded as a second pass behind a rate-limited
endpoint.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../2026-08-01-landing-below-hero-design.md   | 231 ++++++++++++++++++
 1 file changed, 231 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-01-landing-below-hero-design.md

diff --git a/docs/superpowers/specs/2026-08-01-landing-below-hero-design.md b/docs/superpowers/specs/2026-08-01-landing-below-hero-design.md
new file mode 100644
index 00000000..348bbcf8
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-01-landing-below-hero-design.md
@@ -0,0 +1,231 @@
+# Landing page — everything below the hero
+
+Design for #344 (`[p1] frontend PRIORITY - Landing page redesign`), phase 2.
+Phase 1 was 8fb7949, which deleted unreachable effects and orphaned CSS.
+
+## Problem
+
+Below the hero, the landing page currently runs a 340vh scroll-jacked
+`HowItWorks` (677 lines of framer-motion, a Seed→Sprout→Tree metaphor over a
+mocked `AppWindow`), then a six-row hairline feature catalog, then a CTA and
+footer.
+
+#344 names five complaints. Restated as causes rather than symptoms:
+
+1. The graph — the product's actual differentiator — is a **movie you watch**,
+   not a thing you touch.
+2. The features describe **generic capabilities**, not the pages Sapling
+   actually ships.
+3. The section carries scaffolding that exists to explain the scaffolding: a
+   left-side step indicator, "drag"/"scroll" hint copy, per-step preview
+   buttons.
+4. It doesn't look impressive enough to hold a visitor.
+5. It "feels generic," with nothing that could only be Sapling.
+
+Point 5 is the one worth restating: **the page undersells the product more than
+it under-designs it.** Tutor chat, Notes, Gradebook and Flashcards are all
+shipped surfaces that the current six-feature list never mentions. Fixing that
+does more for "feels generic" than any amount of new motion.
+
+## Goals
+
+- Make the knowledge graph manipulable, with the explanatory copy receding as
+  the visitor engages.
+- Present real Sapling surfaces instead of abstract capability names.
+- Delete the scaffolding #344 lists.
+- Keep the page fast and crawlable — this is the most-indexed surface on the
+  site.
+
+## Non-goals
+
+- The hero, nav, and intro overlay are **untouched**. So are the sign-in and
+  beta/newsletter modals.
+- No live LLM generation on the public page (see Rejected alternatives).
+- No backend work. Every graph in this design is a static fixture.
+
+## Architecture
+
+Hero (unchanged)
+1. Interactive graph
+2. Band — Universal Upload
+3. Band — Adaptive quizzes
+4. Bento — Tutor chat, Notes, Study Rooms, Gradebook
+5. Band — knows what to review, and when
+6. CTA
+7. Footer (kept, tightened)
+
+The ordering is a density rhythm: the graph is the densest thing on the page,
+two bands decompress, the bento re-energizes, and the final band closes on a
+claim so the CTA has a run-up. A grid's last tile is a weak place to ask for a
+signup.
+
+The three bands carry one arc — **material in → practice → retention** — rather
+than three disconnected pitches. Band surfaces alternate sides.
+
+### 1. Interactive graph
+
+Replaces `HowItWorks` entirely. Roughly full-viewport, below the fold.
+
+- Three course chips (`CS 210`, `MA 242`, `SM 275`). Picking one animates that
+  course's concept graph into existence, node by node.
+- Once assembled: drag nodes, hover for a concept blurb, click a node to expand
+  its children.
+- The instructional copy fades as the visitor interacts — the fade is driven by
+  first interaction, not by a timer.
+- No side step indicator, no "drag me" hint, no per-step buttons.
+
+Data is a static fixture module — three hand-authored course graphs, each a
+`{nodes, edges}` shape mirroring the real `graph_nodes` / `graph_edges`
+semantics (mastery tiers included, so the colour language matches the app and
+the hero legend).
+
+### 2, 3, 5. Bands
+
+Full-width. One built product surface on one side, copy on the other,
+alternating. Surfaces are recreated in-page in the hero's liquid-glass
+language — not screenshots. The repo has no product screenshots, and the hero
+already recreates surfaces this way (`CS 101 · 55% mastered`, the mastery
+legend, `Total nodes 2,413`), so this stays consistent, themeable, and
+responsive.
+
+| Band | Surface | Claim |
+|---|---|---|
+| 2 | Upload / extraction | syllabus, textbook, lecture notes → concepts on your graph |
+| 3 | Quiz | presses where you're strong, meets you where you struggle |
+| 5 | Review scheduling | knows what to review, and when |
+
+Band 5 folds together what are today two separate features (Adaptive Study
+Paths, Spaced Repetition) — they make one claim, not two.
+
+### 4. Bento
+
+Asymmetric grid, four tiles, varying sizes: **Tutor chat**, **Notes**,
+**Study Rooms**, **Gradebook**. Static surface recreations; no per-tile buttons.
+
+Flashcards and the knowledge graph are deliberately out — the graph is section 1,
+and Flashcards is the surface you'd least lead with.
+
+### 6, 7. CTA and footer
+
+CTA keeps its current copy and `startOnboarding` behaviour. Footer keeps its
+links and credit line; spacing tightened to match the new rhythm.
+
+## Component boundaries
+
+`(public)/page.tsx` is already ~935 lines and would grow. New work lands in
+`components/marketing/` as focused files, imported by `page.tsx`:
+
+- `KnowledgeGraphDemo/` — the interactive graph. Split so the canvas/SVG
+  renderer, the layout+animation logic, and the fixture data are separately
+  readable and testable.
+- `FeatureBand.tsx` — presentational; takes a side, copy, and a surface node.
+- `SurfaceBento.tsx` — the four-tile grid.
+- `surfaces/` — the in-page product recreations (upload, quiz, review, tutor,
+  notes, rooms, gradebook), each self-contained.
+
+`HowItWorks.tsx` is deleted, along with its `next/dynamic` import and the
+340vh placeholder in `page.tsx`.
+
+## Motion
+
+**The helix fires once.** #344 asks for "3D helix animations"; the budget is
+spent in a single place — nodes arriving along a helical path as the graph
+assembles after a course chip is picked. That is a real 3D helix, at the exact
+moment the page makes its argument. Bands and bento get quiet entrance
+transitions only.
+
+Scattering helix motifs through every section is how a page becomes generic
+rather than less so, and the hero already runs a full canvas RAF loop directly
+above this.
+
+**Reduced motion and test mode.** The graph parks on a static, fully-laid-out
+frame under `prefers-reduced-motion: reduce` and under `IS_TEST_MODE`, matching
+how the hero canvas already behaves. A parked graph must still be *complete* —
+laid out and readable, not blank. Any randomness routes through
+`lib/testMode`'s `random()` / `now()` so the E2E lane is deterministic.
+
+## Performance
+
+- The graph component lazy-loads via `next/dynamic` below the fold, following
+  the existing `HowItWorks` precedent — but with SSR **kept** so crawlers still
+  receive the section's marketing copy, which is why the current code avoids
+  `ssr: false`.
+- Its RAF loop must not start until the section is near the viewport, and must
+  stop when it leaves. The hero's canvas is already running above it.
+- Placeholder height must match the resolved section height so nothing below
+  shifts during chunk load (CLS).
+
+## Styling
+
+Everything is scoped under `.landing-page`, which re-declares the same token
+names as the warm app shell (`docs/frontend-rhythm-audit.md`). New CSS must be
+added inside that scope and must not leak token redefinitions outward — this is
+the documented cause of the "get-started/beta feels off" class of bug.
+
+## Testing
+
+- **Unit/vitest**: fixture graph shape (every edge references a real node; no
+  orphans), band alternation, reduced-motion parking.
+- **Testids**: new interactive surfaces need a prefix registered per
+  `docs/frontend-testids.md` §"Adding a surface" — add the row, add the owning
+  file to the lint block's `files` array, and run `npm run lint`, which
+  enumerates interactive elements still missing testids.
+- **E2E journey** (`frontend/e2e/`, fixtures-based `test` from
+  `support/fixtures.ts`): the landing page renders the graph section; picking a
+  course chip assembles a graph; interacting fades the instructional copy; the
+  page still routes to onboarding from both CTAs. Auto-waiting `expect` only,
+  no timeouts.
+- `public-seo.spec.ts` already asserts the landing page ships social cards and a
+  canonical URL — it must stay green, which is the guard on not breaking SSR.
+
+## What gets deleted
+
+- `components/marketing/HowItWorks.tsx` (677 lines) and its dynamic import
+- Seed / Sprout / Tree SVG components and the `AppWindow` mock
+- the left-side step indicator, drag/scroll hint copy, per-step preview buttons
+- the six-row hairline feature catalog and its "— end of catalog" rule
+- any CSS in `globals.css` left orphaned by the above
+
+## Rejected alternatives
+
+**Live generation on the public page.** Letting a visitor type any topic and
+generating a real graph is the most convincing option — it *is* the product
+rather than a picture of it. Rejected for now: it puts an unauthenticated,
+billable LLM endpoint on the most-crawled page on the site, with real cost,
+rate-limiting, prompt-abuse and slow-Gemini failure modes. It is a strong second
+pass once the section exists and can sit behind a hardened, rate-limited
+endpoint.
+
+**Sticky rail with a swapping panel.** Compact, but it is a left-side index that
+scroll-drives a panel — close to the "left side page indication" #344 explicitly
+asks to remove.
+
+**Straight to bento after the graph.** Rejected on pacing: the graph is dense
+and immersive, and a dense grid immediately after gives the eye nowhere to rest.
+
+**Screenshots for the feature surfaces.** No product screenshots exist in the
+repo, and in-page recreations stay themeable, responsive, and consistent with
+the hero's existing glass cards.
+
+## Sequencing
+
+This is two shippable pieces, and they should not land as one PR.
+
+1. **The graph** — section 1, plus deleting `HowItWorks` and the old catalog.
+   The page is coherent at the end of this step: graph, then CTA, then footer.
+2. **Bands, bento, and the seven surface recreations** — sections 2–5.
+
+Step 1 carries the risk and the reviewer attention; step 2 is mostly
+presentational and parallelises well across the seven surfaces. Splitting also
+means a mediocre graph gets caught before seven surfaces are built on top of it.
+
+## Risks
+
+- The interactive graph is the largest single build here and carries the page.
+  If it lands mediocre, the redesign fails regardless of the rest.
+- Three bands plus a bento plus a full-viewport graph makes a long page. Each
+  band has to earn its height; if one reads as filler during implementation, cut
+  it rather than pad it.
+- Two graph renderings now exist on one page (the hero's atmospheric canvas and
+  this labelled interactive one). They must read as deliberately different —
+  atmosphere versus instrument — not as the same effect twice.

From 06912187e5cfaf02a0ecc55d6b061435272dce5a Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 10:58:45 -0700
Subject: [PATCH 02/20] docs(plan): landing interactive graph, step 1 (#344)

Seven tasks: fixtures, layout+helix math, component, assembly, interaction,
page wiring with the HowItWorks/catalog deletions, and the e2e journey.

Self-review found one real gap and it is recorded in the plan rather than
papered over: the spec lists drag alongside hover and expand, and Task 5
implements hover and the copy fade only. Dragging needs a pointer-capture and
SVG coordinate-mapping decision (getScreenCTM) that deserves its own review
gate, so it is called out as 5b/5c rather than hidden inside a step.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../plans/2026-08-01-landing-graph-step1.md   | 1136 +++++++++++++++++
 1 file changed, 1136 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-08-01-landing-graph-step1.md

diff --git a/docs/superpowers/plans/2026-08-01-landing-graph-step1.md b/docs/superpowers/plans/2026-08-01-landing-graph-step1.md
new file mode 100644
index 00000000..ed4c813a
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-01-landing-graph-step1.md
@@ -0,0 +1,1136 @@
+# Landing Interactive Graph (step 1) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the 340vh scroll-jacked `HowItWorks` section with an interactive knowledge-graph demo the visitor manipulates, and delete the old six-row feature catalog.
+
+**Architecture:** A pure-data fixture module (three hand-authored course graphs), a pure-math layout module (deterministic radial layout + a helical entry path), and one client component that composes them. No backend, no network, no LLM. The component lazy-loads below the fold with SSR kept on so crawlers still receive its copy.
+
+**Tech Stack:** Next.js 16 App Router, React, TypeScript, inline SVG (no new dependency), vitest + @testing-library/react, Playwright.
+
+**Scope:** This is step 1 of `docs/superpowers/specs/2026-08-01-landing-below-hero-design.md`. Sections 2–5 of that spec (bands, bento, seven surface recreations) are step 2 and get their own plan. At the end of this plan the page is coherent: hero → graph → CTA → footer.
+
+## Global Constraints
+
+- Hero, nav, and intro overlay in `frontend/src/app/(public)/page.tsx` are **untouched**. So are `SignInModal` and the beta/newsletter modal.
+- **No new npm dependency.** Rendering is inline SVG; framer-motion is not used by the new component.
+- All randomness and clock reads go through `@/lib/testMode` (`random()`, `now()`), never `Math.random()` / `Date.now()` — the E2E lane sets `NEXT_PUBLIC_TEST_MODE=1` and requires a deterministic DOM.
+- Under `prefers-reduced-motion: reduce` **or** `IS_TEST_MODE`, the graph parks on a **complete, laid-out, readable** frame — never blank, never mid-assembly.
+- New CSS lives inside the `.landing-page` scope in `frontend/src/app/globals.css`. Do not redefine design tokens outside that scope (`docs/frontend-rhythm-audit.md` — this is the documented cause of the pre-auth/app-shell drift bugs).
+- Any `<button>`/`<input>`/`<textarea>` in a registered E2E surface file must carry `data-testid` (`frontend/eslint.config.mjs` `no-restricted-syntax` block; see `docs/frontend-testids.md` §"Adding a surface").
+- `frontend/e2e/public-seo.spec.ts` must stay green — it is the guard that the landing page still ships SSR'd copy, social cards, and a canonical URL.
+- Run frontend checks from `frontend/`: `npm run lint`, `npx tsc --noEmit`, `npx vitest run`.
+
+---
+
+### Task 1: Course graph fixtures
+
+Three hand-authored course graphs. Pure data plus the types every later task consumes.
+
+**Files:**
+- Create: `frontend/src/components/marketing/graph/courseGraphs.ts`
+- Test: `frontend/src/components/marketing/graph/courseGraphs.test.ts`
+
+**Interfaces:**
+- Consumes: nothing.
+- Produces: `MasteryTier`, `DemoNode`, `DemoEdge`, `CourseGraph`, `COURSE_GRAPHS: CourseGraph[]`, `TIER_COLOR: Record<MasteryTier, string>`.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+// frontend/src/components/marketing/graph/courseGraphs.test.ts
+/**
+ * Fixture integrity. These graphs are hand-authored, so the failure mode is a
+ * typo'd id producing an edge to nowhere — which renders as a line into empty
+ * space rather than an error. Pin the invariants instead.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph } from './courseGraphs';
+
+const ids = (g: CourseGraph) => new Set(g.nodes.map((n) => n.id));
+
+describe('COURSE_GRAPHS', () => {
+  it('ships exactly three courses with distinct ids and codes', () => {
+    expect(COURSE_GRAPHS).toHaveLength(3);
+    expect(new Set(COURSE_GRAPHS.map((g) => g.id)).size).toBe(3);
+    expect(new Set(COURSE_GRAPHS.map((g) => g.code)).size).toBe(3);
+  });
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s has unique node ids',
+    (_code, g) => {
+      expect(ids(g).size).toBe(g.nodes.length);
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s has a root that exists',
+    (_code, g) => {
+      expect(ids(g).has(g.rootId)).toBe(true);
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s edges reference real nodes',
+    (_code, g) => {
+      const known = ids(g);
+      for (const e of g.edges) {
+        expect(known.has(e.source)).toBe(true);
+        expect(known.has(e.target)).toBe(true);
+      }
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s children reference real nodes',
+    (_code, g) => {
+      const known = ids(g);
+      for (const n of g.nodes) {
+        for (const c of n.children) expect(known.has(c)).toBe(true);
+      }
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s reaches every node from the root',
+    (_code, g) => {
+      const adj = new Map<string, string[]>();
+      for (const e of g.edges) {
+        adj.set(e.source, [...(adj.get(e.source) ?? []), e.target]);
+        adj.set(e.target, [...(adj.get(e.target) ?? []), e.source]);
+      }
+      const seen = new Set([g.rootId]);
+      const queue = [g.rootId];
+      while (queue.length) {
+        for (const nxt of adj.get(queue.shift()!) ?? []) {
+          if (!seen.has(nxt)) {
+            seen.add(nxt);
+            queue.push(nxt);
+          }
+        }
+      }
+      expect(seen.size).toBe(g.nodes.length);
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s gives every node a blurb and a known tier',
+    (_code, g) => {
+      for (const n of g.nodes) {
+        expect(n.blurb.length).toBeGreaterThan(0);
+        expect(TIER_COLOR[n.tier]).toMatch(/^#/);
+      }
+    },
+  );
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/courseGraphs.test.ts`
+Expected: FAIL — cannot resolve `./courseGraphs`.
+
+- [ ] **Step 3: Write the fixtures**
+
+```ts
+// frontend/src/components/marketing/graph/courseGraphs.ts
+/**
+ * Hand-authored demo graphs for the landing page (#344).
+ *
+ * Deliberately static. An earlier option generated these live from a public
+ * endpoint, which was rejected: it puts an unauthenticated, billable LLM call
+ * on the most-crawled page on the site. See the spec's "Rejected alternatives".
+ *
+ * Shapes mirror the real `graph_nodes` / `graph_edges` semantics — mastery
+ * tiers included — so the colour language matches the app and the hero legend.
+ */
+
+export type MasteryTier = 'mastered' | 'learning' | 'struggling' | 'unexplored';
+
+/** Matches the hero's floating legend card and the app's node colours. */
+export const TIER_COLOR: Record<MasteryTier, string> = {
+  mastered: '#1B6C42',
+  learning: '#D97706',
+  struggling: '#EF4444',
+  unexplored: '#9CA3AF',
+};
+
+export interface DemoNode {
+  id: string;
+  label: string;
+  tier: MasteryTier;
+  /** Shown on hover. One sentence, no trailing period. */
+  blurb: string;
+  /** Revealed when this node is expanded. Empty means leaf. */
+  children: string[];
+}
+
+export interface DemoEdge {
+  source: string;
+  target: string;
+}
+
+export interface CourseGraph {
+  id: string;
+  /** Chip label, e.g. "CS 210". */
+  code: string;
+  name: string;
+  rootId: string;
+  nodes: DemoNode[];
+  edges: DemoEdge[];
+}
+
+export const COURSE_GRAPHS: CourseGraph[] = [
+  {
+    id: 'cs210',
+    code: 'CS 210',
+    name: 'Data Structures',
+    rootId: 'cs-root',
+    nodes: [
+      { id: 'cs-root', label: 'CS 210', tier: 'learning', blurb: 'Data Structures — 24 concepts mapped from your syllabus', children: ['cs-arrays', 'cs-recursion', 'cs-complexity'] },
+      { id: 'cs-arrays', label: 'Arrays', tier: 'mastered', blurb: 'Contiguous storage and index arithmetic', children: ['cs-sorting'] },
+      { id: 'cs-recursion', label: 'Recursion', tier: 'struggling', blurb: 'Base cases, call stack depth, and when to prefer iteration', children: ['cs-trees'] },
+      { id: 'cs-complexity', label: 'Big-O', tier: 'learning', blurb: 'Asymptotic bounds for time and space', children: [] },
+      { id: 'cs-sorting', label: 'Sorting', tier: 'learning', blurb: 'Comparison sorts and their lower bound', children: [] },
+      { id: 'cs-trees', label: 'Trees', tier: 'unexplored', blurb: 'Traversals, balance, and why recursion fits them', children: [] },
+    ],
+    edges: [
+      { source: 'cs-root', target: 'cs-arrays' },
+      { source: 'cs-root', target: 'cs-recursion' },
+      { source: 'cs-root', target: 'cs-complexity' },
+      { source: 'cs-arrays', target: 'cs-sorting' },
+      { source: 'cs-recursion', target: 'cs-trees' },
+      { source: 'cs-sorting', target: 'cs-complexity' },
+    ],
+  },
+  {
+    id: 'ma242',
+    code: 'MA 242',
+    name: 'Linear Algebra',
+    rootId: 'ma-root',
+    nodes: [
+      { id: 'ma-root', label: 'MA 242', tier: 'learning', blurb: 'Linear Algebra — 19 concepts mapped from your syllabus', children: ['ma-vectors', 'ma-matrices', 'ma-eigen'] },
+      { id: 'ma-vectors', label: 'Vector Spaces', tier: 'mastered', blurb: 'Span, basis, and dimension', children: ['ma-independence'] },
+      { id: 'ma-matrices', label: 'Matrices', tier: 'learning', blurb: 'Linear maps written as arrays of numbers', children: ['ma-determinant'] },
+      { id: 'ma-eigen', label: 'Eigenvalues', tier: 'struggling', blurb: 'Directions a transformation only scales', children: [] },
+      { id: 'ma-independence', label: 'Independence', tier: 'learning', blurb: 'When no vector is redundant', children: [] },
+      { id: 'ma-determinant', label: 'Determinant', tier: 'unexplored', blurb: 'Signed volume scaling of a transformation', children: [] },
+    ],
+    edges: [
+      { source: 'ma-root', target: 'ma-vectors' },
+      { source: 'ma-root', target: 'ma-matrices' },
+      { source: 'ma-root', target: 'ma-eigen' },
+      { source: 'ma-vectors', target: 'ma-independence' },
+      { source: 'ma-matrices', target: 'ma-determinant' },
+      { source: 'ma-matrices', target: 'ma-eigen' },
+    ],
+  },
+  {
+    id: 'sm275',
+    code: 'SM 275',
+    name: 'Statistics',
+    rootId: 'sm-root',
+    nodes: [
+      { id: 'sm-root', label: 'SM 275', tier: 'learning', blurb: 'Statistics — 21 concepts mapped from your syllabus', children: ['sm-prob', 'sm-dist', 'sm-testing'] },
+      { id: 'sm-prob', label: 'Probability', tier: 'mastered', blurb: 'Sample spaces, events, and conditioning', children: ['sm-bayes'] },
+      { id: 'sm-dist', label: 'Distributions', tier: 'learning', blurb: 'Shapes that recur across real data', children: ['sm-clt'] },
+      { id: 'sm-testing', label: 'Hypothesis Tests', tier: 'struggling', blurb: 'What a p-value does and does not claim', children: [] },
+      { id: 'sm-bayes', label: 'Bayes', tier: 'learning', blurb: 'Updating belief as evidence arrives', children: [] },
+      { id: 'sm-clt', label: 'Central Limit', tier: 'unexplored', blurb: 'Why sample means go normal', children: [] },
+    ],
+    edges: [
+      { source: 'sm-root', target: 'sm-prob' },
+      { source: 'sm-root', target: 'sm-dist' },
+      { source: 'sm-root', target: 'sm-testing' },
+      { source: 'sm-prob', target: 'sm-bayes' },
+      { source: 'sm-dist', target: 'sm-clt' },
+      { source: 'sm-dist', target: 'sm-testing' },
+    ],
+  },
+];
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/courseGraphs.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/components/marketing/graph/courseGraphs.ts frontend/src/components/marketing/graph/courseGraphs.test.ts
+git commit -m "feat(landing): course graph fixtures for the interactive demo (#344)"
+```
+
+---
+
+### Task 2: Deterministic layout and the helical entry path
+
+Pure math, no React. This is where "3D helix animation" actually lives.
+
+**Files:**
+- Create: `frontend/src/components/marketing/graph/layout.ts`
+- Test: `frontend/src/components/marketing/graph/layout.test.ts`
+
+**Interfaces:**
+- Consumes: `CourseGraph` from Task 1.
+- Produces: `Point`, `radialLayout(graph, width, height): Map<string, Point>`, `easeOutCubic(t): number`, `helixEntry(target, centre, t, turns?): { x, y, scale, opacity }`.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+// frontend/src/components/marketing/graph/layout.test.ts
+/**
+ * The layout is deterministic on purpose: the E2E lane parks the animation and
+ * asserts against a laid-out frame, so identical input must give identical
+ * coordinates on every run and in every environment.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { COURSE_GRAPHS } from './courseGraphs';
+import { easeOutCubic, helixEntry, radialLayout } from './layout';
+
+const G = COURSE_GRAPHS[0];
+
+describe('radialLayout', () => {
+  it('positions every node', () => {
+    const p = radialLayout(G, 800, 500);
+    expect(p.size).toBe(G.nodes.length);
+    for (const n of G.nodes) expect(p.get(n.id)).toBeDefined();
+  });
+
+  it('puts the root at the centre', () => {
+    const p = radialLayout(G, 800, 500);
+    expect(p.get(G.rootId)).toEqual({ x: 400, y: 250 });
+  });
+
+  it('is deterministic', () => {
+    expect(radialLayout(G, 800, 500)).toEqual(radialLayout(G, 800, 500));
+  });
+
+  it('separates nodes at the same depth', () => {
+    const p = radialLayout(G, 800, 500);
+    const depth1 = G.nodes.find((n) => n.id === G.rootId)!.children;
+    const pts = depth1.map((id) => p.get(id)!);
+    for (let i = 0; i < pts.length; i++) {
+      for (let j = i + 1; j < pts.length; j++) {
+        const d = Math.hypot(pts[i].x - pts[j].x, pts[i].y - pts[j].y);
+        expect(d).toBeGreaterThan(40);
+      }
+    }
+  });
+
+  it('scales with the viewport', () => {
+    const small = radialLayout(G, 400, 300);
+    const large = radialLayout(G, 1200, 800);
+    expect(small).not.toEqual(large);
+  });
+});
+
+describe('easeOutCubic', () => {
+  it('pins its endpoints and clamps', () => {
+    expect(easeOutCubic(0)).toBe(0);
+    expect(easeOutCubic(1)).toBe(1);
+    expect(easeOutCubic(-1)).toBe(0);
+    expect(easeOutCubic(4)).toBe(1);
+  });
+});
+
+describe('helixEntry', () => {
+  const target = { x: 300, y: 120 };
+  const centre = { x: 200, y: 200 };
+
+  it('lands exactly on the target at t=1', () => {
+    const r = helixEntry(target, centre, 1);
+    expect(r.x).toBeCloseTo(target.x, 6);
+    expect(r.y).toBeCloseTo(target.y, 6);
+    expect(r.scale).toBeCloseTo(1, 6);
+    expect(r.opacity).toBeCloseTo(1, 6);
+  });
+
+  it('starts invisible and small', () => {
+    const r = helixEntry(target, centre, 0);
+    expect(r.opacity).toBe(0);
+    expect(r.scale).toBeLessThan(0.5);
+  });
+
+  it('rotates around the centre on the way in — the helix', () => {
+    const mid = helixEntry(target, centre, 0.5);
+    const straight = {
+      x: centre.x + (target.x - centre.x) * easeOutCubic(0.5),
+      y: centre.y + (target.y - centre.y) * easeOutCubic(0.5),
+    };
+    const off = Math.hypot(mid.x - straight.x, mid.y - straight.y);
+    expect(off).toBeGreaterThan(10);
+  });
+
+  it('grows monotonically', () => {
+    let prev = -1;
+    for (let t = 0; t <= 1.0001; t += 0.1) {
+      const s = helixEntry(target, centre, t).scale;
+      expect(s).toBeGreaterThan(prev);
+      prev = s;
+    }
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/layout.test.ts`
+Expected: FAIL — cannot resolve `./layout`.
+
+- [ ] **Step 3: Write the implementation**
+
+```ts
+// frontend/src/components/marketing/graph/layout.ts
+/**
+ * Layout + entry-path math for the landing graph demo (#344).
+ *
+ * Deterministic by construction — no randomness, no time input. The E2E lane
+ * parks the animation and asserts against the laid-out frame, so the same graph
+ * and viewport must always produce the same coordinates.
+ */
+import type { CourseGraph } from './courseGraphs';
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+function clamp01(t: number): number {
+  return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+
+export function easeOutCubic(t: number): number {
+  const c = clamp01(t);
+  return 1 - Math.pow(1 - c, 3);
+}
+
+/**
+ * Root at the centre, each BFS depth on its own ring, siblings spread evenly
+ * around it. Alternate rings are rotated by half a slot so spokes don't line
+ * up into visual spokes.
+ */
+export function radialLayout(
+  graph: CourseGraph,
+  width: number,
+  height: number,
+): Map<string, Point> {
+  const adj = new Map<string, string[]>();
+  for (const e of graph.edges) {
+    adj.set(e.source, [...(adj.get(e.source) ?? []), e.target]);
+    adj.set(e.target, [...(adj.get(e.target) ?? []), e.source]);
+  }
+
+  const depth = new Map<string, number>([[graph.rootId, 0]]);
+  const queue = [graph.rootId];
+  while (queue.length) {
+    const cur = queue.shift()!;
+    for (const nxt of adj.get(cur) ?? []) {
+      if (!depth.has(nxt)) {
+        depth.set(nxt, depth.get(cur)! + 1);
+        queue.push(nxt);
+      }
+    }
+  }
+
+  const byDepth = new Map<number, string[]>();
+  // Iterate graph.nodes (declaration order), not the Map, so ring ordering is
+  // stable regardless of BFS visit order.
+  for (const n of graph.nodes) {
+    const d = depth.get(n.id) ?? 0;
+    byDepth.set(d, [...(byDepth.get(d) ?? []), n.id]);
+  }
+
+  const cx = width / 2;
+  const cy = height / 2;
+  const maxDepth = Math.max(...byDepth.keys(), 1);
+  const ring = (Math.min(width, height) / 2 - 48) / maxDepth;
+
+  const out = new Map<string, Point>();
+  for (const [d, ids] of byDepth) {
+    if (d === 0) {
+      for (const id of ids) out.set(id, { x: cx, y: cy });
+      continue;
+    }
+    const step = (Math.PI * 2) / ids.length;
+    const offset = d % 2 === 0 ? step / 2 : 0;
+    ids.forEach((id, i) => {
+      const a = i * step + offset - Math.PI / 2;
+      out.set(id, {
+        x: cx + Math.cos(a) * ring * d,
+        y: cy + Math.sin(a) * ring * d,
+      });
+    });
+  }
+  return out;
+}
+
+/**
+ * Position along the helical entry path. `t` runs 0 → 1.
+ *
+ * The node spirals inward: its offset from the centre is rotated by a
+ * decreasing angle and stretched outward by a decreasing factor, while scale
+ * and opacity rise. At t=1 every term collapses and the node sits exactly on
+ * `target`, so the animation has no seam where it hands off to the static
+ * layout.
+ */
+export function helixEntry(
+  target: Point,
+  centre: Point,
+  t: number,
+  turns = 1.5,
+): { x: number; y: number; scale: number; opacity: number } {
+  const e = easeOutCubic(t);
+  const dx = target.x - centre.x;
+  const dy = target.y - centre.y;
+
+  const angle = (1 - e) * turns * Math.PI * 2;
+  const stretch = 1 + (1 - e) * 0.9;
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle);
+
+  return {
+    x: centre.x + (dx * cos - dy * sin) * stretch,
+    y: centre.y + (dx * sin + dy * cos) * stretch,
+    scale: 0.35 + 0.65 * e,
+    opacity: e,
+  };
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/layout.test.ts`
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/components/marketing/graph/layout.ts frontend/src/components/marketing/graph/layout.test.ts
+git commit -m "feat(landing): deterministic radial layout + helical entry path (#344)"
+```
+
+---
+
+### Task 3: The component — chips, static render, testids
+
+Renders the graph laid out and complete. Assembly animation comes in Task 4; this task's deliverable is the parked frame, which is also exactly what reduced-motion and test mode ship.
+
+**Files:**
+- Create: `frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx`
+- Test: `frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx`
+- Modify: `docs/frontend-testids.md` (add the surface row + inventory)
+- Modify: `frontend/eslint.config.mjs` (add the file to the surface `files` array)
+
+**Interfaces:**
+- Consumes: `COURSE_GRAPHS`, `TIER_COLOR`, `CourseGraph` (Task 1); `radialLayout`, `Point` (Task 2).
+- Produces: default export `KnowledgeGraphDemo` (no props).
+
+Testids used by this task and by Task 7: `landing-graph` (section), `landing-graph-chip-<courseId>` (chips), `landing-graph-node-<nodeId>` (nodes), `landing-graph-copy` (instructional copy block).
+
+- [ ] **Step 1: Write the failing test**
+
+```tsx
+// frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
+// @vitest-environment jsdom
+/**
+ * The parked frame is the contract. Reduced-motion visitors and the E2E lane
+ * both get this render, so "parked" has to mean laid out and readable — not
+ * blank and not mid-assembly.
+ */
+import React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup, fireEvent } from '@testing-library/react';
+
+import KnowledgeGraphDemo from './KnowledgeGraphDemo';
+import { COURSE_GRAPHS } from './courseGraphs';
+
+afterEach(cleanup);
+
+describe('KnowledgeGraphDemo', () => {
+  it('renders a chip per course, with the first selected', () => {
+    render(<KnowledgeGraphDemo />);
+    for (const g of COURSE_GRAPHS) {
+      expect(screen.getByTestId(`landing-graph-chip-${g.id}`)).toBeInTheDocument();
+    }
+    expect(
+      screen.getByTestId(`landing-graph-chip-${COURSE_GRAPHS[0].id}`),
+    ).toHaveAttribute('aria-pressed', 'true');
+  });
+
+  it('renders the selected course graph fully laid out', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+    for (const n of g.nodes) {
+      expect(screen.getByTestId(`landing-graph-node-${n.id}`)).toBeInTheDocument();
+    }
+  });
+
+  it('swaps the graph when another chip is picked', () => {
+    render(<KnowledgeGraphDemo />);
+    const target = COURSE_GRAPHS[1];
+    fireEvent.click(screen.getByTestId(`landing-graph-chip-${target.id}`));
+
+    expect(screen.getByTestId(`landing-graph-node-${target.nodes[0].id}`)).toBeInTheDocument();
+    expect(
+      screen.queryByTestId(`landing-graph-node-${COURSE_GRAPHS[0].nodes[0].id}`),
+    ).not.toBeInTheDocument();
+  });
+
+  it('labels the section for assistive tech', () => {
+    render(<KnowledgeGraphDemo />);
+    expect(screen.getByTestId('landing-graph')).toHaveAttribute('aria-label');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/KnowledgeGraphDemo.test.tsx`
+Expected: FAIL — cannot resolve `./KnowledgeGraphDemo`.
+
+- [ ] **Step 3: Write the component**
+
+```tsx
+// frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+'use client';
+
+import { useMemo, useState } from 'react';
+
+import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph } from './courseGraphs';
+import { radialLayout } from './layout';
+
+const VIEW_W = 900;
+const VIEW_H = 560;
+
+function nodeRadius(g: CourseGraph, id: string): number {
+  return id === g.rootId ? 26 : 14;
+}
+
+export default function KnowledgeGraphDemo() {
+  const [courseId, setCourseId] = useState(COURSE_GRAPHS[0].id);
+
+  const graph = useMemo(
+    () => COURSE_GRAPHS.find((g) => g.id === courseId) ?? COURSE_GRAPHS[0],
+    [courseId],
+  );
+  const points = useMemo(() => radialLayout(graph, VIEW_W, VIEW_H), [graph]);
+
+  return (
+    <section
+      id="knowledge-graph"
+      data-testid="landing-graph"
+      aria-label={`Interactive knowledge graph for ${graph.name}`}
+      className="landing-section landing-graph relative z-10 py-24 md:py-32"
+    >
+      <div className="max-w-7xl mx-auto px-6 lg:px-12">
+        <div data-testid="landing-graph-copy" className="landing-graph-copy">
+          <span className="font-jetbrains text-[0.7rem] tracking-[0.32em] text-[var(--brand-forest)] uppercase font-medium">
+            Your knowledge, mapped
+          </span>
+          <h2 className="font-playfair text-4xl md:text-6xl font-semibold text-[var(--text)] mt-4 leading-[1.05] tracking-tight">
+            Pick a course. Watch it grow.
+          </h2>
+        </div>
+
+        <div className="mt-8 flex flex-wrap gap-3">
+          {COURSE_GRAPHS.map((g) => {
+            const active = g.id === graph.id;
+            return (
+              <button
+                key={g.id}
+                type="button"
+                data-testid={`landing-graph-chip-${g.id}`}
+                aria-pressed={active}
+                onClick={() => setCourseId(g.id)}
+                className={`landing-graph-chip${active ? ' is-active' : ''}`}
+              >
+                {g.code}
+              </button>
+            );
+          })}
+        </div>
+
+        <svg
+          viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+          className="mt-8 w-full h-auto"
+          role="img"
+          aria-label={`${graph.name} concept graph`}
+        >
+          {graph.edges.map((e) => {
+            const a = points.get(e.source);
+            const b = points.get(e.target);
+            if (!a || !b) return null;
+            return (
+              <line
+                key={`${e.source}-${e.target}`}
+                x1={a.x}
+                y1={a.y}
+                x2={b.x}
+                y2={b.y}
+                stroke="var(--text-dim)"
+                strokeOpacity={0.28}
+                strokeWidth={1.4}
+              />
+            );
+          })}
+
+          {graph.nodes.map((n) => {
+            const p = points.get(n.id);
+            if (!p) return null;
+            return (
+              <g key={n.id} data-testid={`landing-graph-node-${n.id}`}>
+                <circle cx={p.x} cy={p.y} r={nodeRadius(graph, n.id)} fill={TIER_COLOR[n.tier]} />
+                <text
+                  x={p.x}
+                  y={p.y + nodeRadius(graph, n.id) + 16}
+                  textAnchor="middle"
+                  className="font-jetbrains"
+                  fontSize={12}
+                  fill="var(--text-dim)"
+                >
+                  {n.label}
+                </text>
+              </g>
+            );
+          })}
+        </svg>
+      </div>
+    </section>
+  );
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/KnowledgeGraphDemo.test.tsx`
+Expected: PASS
+
+- [ ] **Step 5: Add the `.landing-page`-scoped styles**
+
+Append inside the existing `.landing-page` block region of `frontend/src/app/globals.css` — do **not** create tokens outside that scope:
+
+```css
+.landing-page .landing-graph-chip {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.78rem;
+  letter-spacing: 0.08em;
+  padding: 7px 16px;
+  border-radius: 9999px;
+  border: 1px solid rgba(107, 114, 128, 0.28);
+  background: rgba(255, 255, 255, 0.55);
+  color: var(--text-dim);
+  cursor: pointer;
+  transition: background 0.2s ease, color 0.2s ease, border-color 0.2s ease;
+}
+.landing-page .landing-graph-chip:hover { border-color: var(--brand-forest); }
+.landing-page .landing-graph-chip.is-active {
+  background: var(--brand-forest);
+  border-color: var(--brand-forest);
+  color: #fff;
+}
+.landing-page .landing-graph-copy { transition: opacity 600ms ease; }
+```
+
+- [ ] **Step 6: Register the E2E surface**
+
+In `docs/frontend-testids.md`, add a row to the surface table and the four testids to the inventory:
+`landing-graph`, `landing-graph-chip-<courseId>`, `landing-graph-node-<nodeId>`, `landing-graph-copy`.
+
+In `frontend/eslint.config.mjs`, add `"src/components/marketing/graph/KnowledgeGraphDemo.tsx"` to the surface block's `files` array.
+
+- [ ] **Step 7: Verify lint and types**
+
+Run: `cd frontend && npm run lint && npx tsc --noEmit`
+Expected: both clean. The lint rule will name any button missing a `data-testid`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add frontend/src/components/marketing/graph/ frontend/src/app/globals.css frontend/eslint.config.mjs docs/frontend-testids.md
+git commit -m "feat(landing): knowledge graph demo — chips and laid-out render (#344)"
+```
+
+---
+
+### Task 4: Helical assembly, parked under reduced motion
+
+**Files:**
+- Modify: `frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx`
+- Modify: `frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx`
+
+**Interfaces:**
+- Consumes: `helixEntry` (Task 2), `IS_TEST_MODE` and `now` from `@/lib/testMode`.
+- Produces: no new exports.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `KnowledgeGraphDemo.test.tsx`:
+
+```tsx
+describe('KnowledgeGraphDemo — motion', () => {
+  it('parks fully assembled when reduced motion is requested', () => {
+    // jsdom has no matchMedia; supply one that reports "reduce".
+    window.matchMedia = ((q: string) => ({
+      matches: q.includes('prefers-reduced-motion'),
+      media: q,
+      addEventListener() {},
+      removeEventListener() {},
+    })) as unknown as typeof window.matchMedia;
+
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+
+    // Every node present AND at full opacity — parked means complete.
+    for (const n of g.nodes) {
+      const el = screen.getByTestId(`landing-graph-node-${n.id}`);
+      expect(el).toBeInTheDocument();
+      expect(el.getAttribute('opacity')).toBe('1');
+    }
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/KnowledgeGraphDemo.test.tsx -t "parks fully assembled"`
+Expected: FAIL — nodes carry no `opacity` attribute yet.
+
+- [ ] **Step 3: Implement the assembly loop**
+
+Add to the component's imports:
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { IS_TEST_MODE, now } from '@/lib/testMode';
+import { helixEntry } from './layout';
+```
+
+Add the reduced-motion check and progress state (`1` means fully assembled, which is the parked value):
+
+```tsx
+const ASSEMBLE_MS = 1100;
+
+const prefersReduced =
+  typeof window !== 'undefined' &&
+  typeof window.matchMedia === 'function' &&
+  window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+const parked = IS_TEST_MODE || prefersReduced;
+
+const [progress, setProgress] = useState(parked ? 1 : 0);
+const rafRef = useRef(0);
+
+useEffect(() => {
+  if (parked) {
+    setProgress(1);
+    return;
+  }
+  setProgress(0);
+  const start = now();
+  const tick = () => {
+    const p = Math.min(1, (now() - start) / ASSEMBLE_MS);
+    setProgress(p);
+    if (p < 1) rafRef.current = requestAnimationFrame(tick);
+  };
+  rafRef.current = requestAnimationFrame(tick);
+  return () => cancelAnimationFrame(rafRef.current);
+  // Re-runs on course change so each pick re-assembles.
+}, [graph.id, parked]);
+```
+
+Give each node a staggered sub-progress and drive it through `helixEntry`. Replace the node `<g>` body:
+
+```tsx
+{graph.nodes.map((n, i) => {
+  const p = points.get(n.id);
+  if (!p) return null;
+  // Stagger: later nodes start later, all finish by progress = 1.
+  const span = 1 / (graph.nodes.length + 2);
+  const local = Math.min(1, Math.max(0, (progress - i * span) / (1 - i * span)));
+  const h = helixEntry(p, { x: VIEW_W / 2, y: VIEW_H / 2 }, local);
+  const r = nodeRadius(graph, n.id);
+  return (
+    <g key={n.id} data-testid={`landing-graph-node-${n.id}`} opacity={h.opacity}>
+      <circle cx={h.x} cy={h.y} r={r * h.scale} fill={TIER_COLOR[n.tier]} />
+      <text
+        x={h.x}
+        y={h.y + r + 16}
+        textAnchor="middle"
+        className="font-jetbrains"
+        fontSize={12}
+        fill="var(--text-dim)"
+        opacity={h.opacity}
+      >
+        {n.label}
+      </text>
+    </g>
+  );
+})}
+```
+
+Edges fade in with the whole assembly — set `strokeOpacity={0.28 * progress}` on the `<line>`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/KnowledgeGraphDemo.test.tsx`
+Expected: PASS — including the earlier "renders fully laid out" test, because `IS_TEST_MODE` is false under vitest but the parked test supplies its own `matchMedia`.
+
+> If the non-parked tests now see `progress = 0`, park them the same way: vitest's jsdom has no `matchMedia`, so add the same stub in a `beforeEach` returning `matches: true`. The parked frame is the correct assertion target for unit tests either way.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/components/marketing/graph/
+git commit -m "feat(landing): helical assembly, parked under reduced motion (#344)"
+```
+
+---
+
+### Task 5: Interaction — hover blurb, click to expand, copy fade
+
+**Files:**
+- Modify: `frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx`
+- Modify: `frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx`
+
+**Interfaces:**
+- Consumes: everything from Tasks 1–4.
+- Produces: testid `landing-graph-blurb`.
+
+- [ ] **Step 1: Write the failing test**
+
+```tsx
+describe('KnowledgeGraphDemo — interaction', () => {
+  it('shows a concept blurb on hover', () => {
+    render(<KnowledgeGraphDemo />);
+    const n = COURSE_GRAPHS[0].nodes[1];
+    fireEvent.mouseEnter(screen.getByTestId(`landing-graph-node-${n.id}`));
+    expect(screen.getByTestId('landing-graph-blurb')).toHaveTextContent(n.blurb);
+  });
+
+  it('fades the instructional copy once the visitor interacts', () => {
+    render(<KnowledgeGraphDemo />);
+    const copy = screen.getByTestId('landing-graph-copy');
+    expect(copy).toHaveAttribute('data-engaged', 'false');
+
+    fireEvent.mouseEnter(
+      screen.getByTestId(`landing-graph-node-${COURSE_GRAPHS[0].nodes[1].id}`),
+    );
+    expect(copy).toHaveAttribute('data-engaged', 'true');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/KnowledgeGraphDemo.test.tsx -t "interaction"`
+Expected: FAIL — no `landing-graph-blurb`, no `data-engaged`.
+
+- [ ] **Step 3: Implement**
+
+```tsx
+const [hovered, setHovered] = useState<string | null>(null);
+const [engaged, setEngaged] = useState(false);
+
+function onNodeEnter(id: string) {
+  setHovered(id);
+  setEngaged(true);
+}
+```
+
+Put `data-engaged={engaged ? 'true' : 'false'}` and `style={{ opacity: engaged ? 0.35 : 1 }}` on the copy block, add `onMouseEnter={() => onNodeEnter(n.id)}` and `onMouseLeave={() => setHovered(null)}` to each node `<g>`, and render the blurb below the svg:
+
+```tsx
+<p data-testid="landing-graph-blurb" className="landing-graph-blurb font-inter text-[var(--text-dim)] mt-4 min-h-[1.5rem]">
+  {hovered ? graph.nodes.find((n) => n.id === hovered)?.blurb : ''}
+</p>
+```
+
+`min-h` is load-bearing: without it the paragraph appearing and disappearing shifts everything below it on every hover.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `cd frontend && npx vitest run src/components/marketing/graph/KnowledgeGraphDemo.test.tsx`
+Expected: PASS
+
+- [ ] **Step 5: Register the new testid**
+
+Add `landing-graph-blurb` to the inventory in `docs/frontend-testids.md`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add frontend/src/components/marketing/graph/ docs/frontend-testids.md
+git commit -m "feat(landing): graph hover blurbs and copy fade on engagement (#344)"
+```
+
+---
+
+### Task 6: Wire into the page; delete HowItWorks and the old catalog
+
+**Files:**
+- Modify: `frontend/src/app/(public)/page.tsx`
+- Delete: `frontend/src/components/marketing/HowItWorks.tsx`
+- Modify: `frontend/src/app/globals.css` (remove rules orphaned by the deletions)
+
+**Interfaces:**
+- Consumes: `KnowledgeGraphDemo` (Tasks 3–5).
+- Produces: nothing.
+
+- [ ] **Step 1: Swap the dynamic import**
+
+Replace the `HowItWorks` dynamic import block. Keep SSR on — `ssr: false` would drop the copy from the HTML crawlers see, which `public-seo.spec.ts` guards:
+
+```tsx
+const KnowledgeGraphDemo = dynamic(
+  () => import('@/components/marketing/graph/KnowledgeGraphDemo'),
+  {
+    // Placeholder height matches the section's resolved height so nothing
+    // below shifts while the chunk loads.
+    loading: () => <section id="knowledge-graph" className="landing-section relative" style={{ minHeight: '80vh' }} />,
+  },
+);
+```
+
+- [ ] **Step 2: Replace the sections**
+
+In the JSX, delete the entire `<section id="features">` block (heading, the six-item `<ol>`, and the "— end of catalog" rule) and replace `<HowItWorks />` with `<KnowledgeGraphDemo />`. The resulting order below the hero is: `<KnowledgeGraphDemo />`, the existing final-CTA `<section>`, then the `<footer>`.
+
+Also remove the now-unused icon imports from `lucide-react` (`Network`, `Sparkles`, `FilePlus2`, `Brain`, `CalendarClock`) — keep `Users` and `PenSquare`, which the hero's floating cards still use.
+
+- [ ] **Step 3: Delete the component**
+
+```bash
+git rm frontend/src/components/marketing/HowItWorks.tsx
+```
+
+- [ ] **Step 4: Remove orphaned CSS**
+
+In `frontend/src/app/globals.css`, delete rules only the deleted markup used: `.landing-feature-list`, `.landing-feature-row`, `.landing-feature-title`, `.landing-feature-icon`, `.landing-feature-underline`. Confirm each is unused first:
+
+Run: `cd /home/andresl/Projects/sapling && /usr/bin/grep -rn "landing-feature" frontend/src/`
+Expected: no hits outside `globals.css` before deleting.
+
+- [ ] **Step 5: Verify build, lint, types, and unit tests**
+
+Run: `cd frontend && npm run lint && npx tsc --noEmit && npx vitest run`
+Expected: all clean. Watch for eslint's `--prune-suppressions` ratchet — deleting suppressed code can make lint exit 2 with "suppressions left"; if so run `npx eslint --prune-suppressions .` and commit the updated `eslint-suppressions.json`.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add -A frontend/src frontend/eslint-suppressions.json
+git commit -m "feat(landing): replace HowItWorks and the feature catalog with the graph demo (#344)"
+```
+
+---
+
+### Task 7: E2E journey
+
+**Files:**
+- Create: `frontend/e2e/landing-graph.spec.ts`
+
+**Interfaces:**
+- Consumes: testids from Tasks 3 and 5; `test`/`expect` from `./support/fixtures`.
+- Produces: nothing.
+
+- [ ] **Step 1: Write the journey**
+
+```ts
+// frontend/e2e/landing-graph.spec.ts
+/**
+ * Journey — the landing page's interactive knowledge graph (#344).
+ *
+ * The graph is the page's whole argument, so this pins that it renders, that
+ * picking a course swaps it, and that engaging with it recedes the
+ * instructional copy. Test mode parks the assembly animation, so every
+ * assertion runs against the fully laid-out frame.
+ */
+import { expect, test } from './support/fixtures';
+
+test('landing graph renders, swaps by course, and fades its copy on engagement', async ({ page }) => {
+  await page.goto('/');
+
+  const section = page.getByTestId('landing-graph');
+  await section.scrollIntoViewIfNeeded();
+  await expect(section).toBeVisible();
+
+  // Parked frame: the first course's root node is laid out and visible.
+  await expect(page.getByTestId('landing-graph-node-cs-root')).toBeVisible();
+
+  // Picking another course swaps the graph.
+  await page.getByTestId('landing-graph-chip-ma242').click();
+  await expect(page.getByTestId('landing-graph-node-ma-root')).toBeVisible();
+  await expect(page.getByTestId('landing-graph-node-cs-root')).toHaveCount(0);
+
+  // Engaging recedes the copy.
+  const copy = page.getByTestId('landing-graph-copy');
+  await expect(copy).toHaveAttribute('data-engaged', 'false');
+  await page.getByTestId('landing-graph-node-ma-vectors').hover();
+  await expect(copy).toHaveAttribute('data-engaged', 'true');
+  await expect(page.getByTestId('landing-graph-blurb')).toContainText('Span, basis');
+});
+
+test('the deleted scroll section is gone and the CTA still routes', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('#how-it-works')).toHaveCount(0);
+  await expect(page.locator('#features')).toHaveCount(0);
+  await expect(page.getByTestId('signin-trigger')).toBeVisible();
+});
+```
+
+- [ ] **Step 2: Run the full local E2E cycle**
+
+Serialize the whole up→test→down cycle in ONE `flock` — detached servers inherit the lock fd, so a separately-flocked teardown deadlocks:
+
+```bash
+cd /home/andresl/Projects/sapling
+export SAPLING_MODEL_MODE=function
+export SAPLING_FUNCTION_HANDLERS=agents.function_handlers_e2e
+export GEMINI_API_KEY=e2e-dummy-key-no-billing
+flock /tmp/claude-1000/sapling-e2e-stack.lock bash -c '
+  make e2e-up &&
+  (cd frontend && npx playwright test e2e/) ; PW=$?
+  (cd backend && venv/bin/python -m e2e_oracles) ; OR=$?
+  make e2e-down
+  echo "playwright=$PW oracles=$OR"
+'
+```
+
+Expected: `playwright=0 oracles=0`. Read the counts, not the exit code.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/e2e/landing-graph.spec.ts
+git commit -m "test(e2e): journey for the landing knowledge graph (#344)"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage (step 1 scope only):**
+
+| Spec requirement | Task |
+|---|---|
+| Three course chips, graph assembles on pick | 1, 3, 4 |
+| Drag / hover / expand | 5 — **gap, see below** |
+| Copy fades on interaction | 5 |
+| Static fixture data mirroring graph_nodes semantics | 1 |
+| Helix fires once, at assembly | 2, 4 |
+| Parks complete under reduced motion + test mode | 4 |
+| Lazy-load with SSR kept | 6 |
+| Placeholder height prevents CLS | 6 |
+| `.landing-page`-scoped CSS | 3 |
+| Deletes HowItWorks, catalog, indicator, hints, buttons | 6 |
+| testids registered + eslint block | 3, 5 |
+| E2E journey; public-seo stays green | 7, 6 |
+
+**Known gap, deliberately left:** the spec lists **drag** alongside hover and expand; Task 5 implements hover blurbs and copy fade but not node dragging or click-to-expand. Both are additive to the same component and neither changes the interfaces above. Implement them as Task 5b/5c during execution, or fold them into Task 5 — flagged here rather than silently dropped so the reviewer sees the difference between plan and spec. Dragging in particular needs a pointer-capture decision (SVG coordinate mapping via `getScreenCTM()`) that is worth its own review gate.
+
+**Placeholder scan:** no TBD/TODO; every code step carries real code.
+
+**Type consistency:** `radialLayout(graph, width, height) → Map<string, Point>` and `helixEntry(target, centre, t, turns?)` are used with those exact signatures in Tasks 3–4. `TIER_COLOR` keys match `MasteryTier`. Node testids use `n.id` from the fixtures, and the E2E spec references real ids (`cs-root`, `ma-root`, `ma-vectors`) that exist in Task 1's data.

From 651de5fb757f148a654fa28c7db4821100c7705f Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 11:45:47 -0700
Subject: [PATCH 03/20] feat(landing): course graph fixtures for the
 interactive demo (#344)

---
 .../marketing/graph/courseGraphs.test.ts      |  85 +++++++++++++
 .../marketing/graph/courseGraphs.ts           | 114 ++++++++++++++++++
 2 files changed, 199 insertions(+)
 create mode 100644 frontend/src/components/marketing/graph/courseGraphs.test.ts
 create mode 100644 frontend/src/components/marketing/graph/courseGraphs.ts

diff --git a/frontend/src/components/marketing/graph/courseGraphs.test.ts b/frontend/src/components/marketing/graph/courseGraphs.test.ts
new file mode 100644
index 00000000..c00091ab
--- /dev/null
+++ b/frontend/src/components/marketing/graph/courseGraphs.test.ts
@@ -0,0 +1,85 @@
+/**
+ * Fixture integrity. These graphs are hand-authored, so the failure mode is a
+ * typo'd id producing an edge to nowhere — which renders as a line into empty
+ * space rather than an error. Pin the invariants instead.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph } from './courseGraphs';
+
+const ids = (g: CourseGraph) => new Set(g.nodes.map((n) => n.id));
+
+describe('COURSE_GRAPHS', () => {
+  it('ships exactly three courses with distinct ids and codes', () => {
+    expect(COURSE_GRAPHS).toHaveLength(3);
+    expect(new Set(COURSE_GRAPHS.map((g) => g.id)).size).toBe(3);
+    expect(new Set(COURSE_GRAPHS.map((g) => g.code)).size).toBe(3);
+  });
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s has unique node ids',
+    (_code, g) => {
+      expect(ids(g).size).toBe(g.nodes.length);
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s has a root that exists',
+    (_code, g) => {
+      expect(ids(g).has(g.rootId)).toBe(true);
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s edges reference real nodes',
+    (_code, g) => {
+      const known = ids(g);
+      for (const e of g.edges) {
+        expect(known.has(e.source)).toBe(true);
+        expect(known.has(e.target)).toBe(true);
+      }
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s children reference real nodes',
+    (_code, g) => {
+      const known = ids(g);
+      for (const n of g.nodes) {
+        for (const c of n.children) expect(known.has(c)).toBe(true);
+      }
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s reaches every node from the root',
+    (_code, g) => {
+      const adj = new Map<string, string[]>();
+      for (const e of g.edges) {
+        adj.set(e.source, [...(adj.get(e.source) ?? []), e.target]);
+        adj.set(e.target, [...(adj.get(e.target) ?? []), e.source]);
+      }
+      const seen = new Set([g.rootId]);
+      const queue = [g.rootId];
+      while (queue.length) {
+        for (const nxt of adj.get(queue.shift()!) ?? []) {
+          if (!seen.has(nxt)) {
+            seen.add(nxt);
+            queue.push(nxt);
+          }
+        }
+      }
+      expect(seen.size).toBe(g.nodes.length);
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s gives every node a blurb and a known tier',
+    (_code, g) => {
+      for (const n of g.nodes) {
+        expect(n.blurb.length).toBeGreaterThan(0);
+        expect(TIER_COLOR[n.tier]).toMatch(/^#/);
+      }
+    },
+  );
+});
diff --git a/frontend/src/components/marketing/graph/courseGraphs.ts b/frontend/src/components/marketing/graph/courseGraphs.ts
new file mode 100644
index 00000000..e0e879c5
--- /dev/null
+++ b/frontend/src/components/marketing/graph/courseGraphs.ts
@@ -0,0 +1,114 @@
+/**
+ * Hand-authored demo graphs for the landing page (#344).
+ *
+ * Deliberately static. An earlier option generated these live from a public
+ * endpoint, which was rejected: it puts an unauthenticated, billable LLM call
+ * on the most-crawled page on the site. See the spec's "Rejected alternatives".
+ *
+ * Shapes mirror the real `graph_nodes` / `graph_edges` semantics — mastery
+ * tiers included — so the colour language matches the app and the hero legend.
+ */
+
+export type MasteryTier = 'mastered' | 'learning' | 'struggling' | 'unexplored';
+
+/** Matches the hero's floating legend card and the app's node colours. */
+export const TIER_COLOR: Record<MasteryTier, string> = {
+  mastered: '#1B6C42',
+  learning: '#D97706',
+  struggling: '#EF4444',
+  unexplored: '#9CA3AF',
+};
+
+export interface DemoNode {
+  id: string;
+  label: string;
+  tier: MasteryTier;
+  /** Shown on hover. One sentence, no trailing period. */
+  blurb: string;
+  /** Revealed when this node is expanded. Empty means leaf. */
+  children: string[];
+}
+
+export interface DemoEdge {
+  source: string;
+  target: string;
+}
+
+export interface CourseGraph {
+  id: string;
+  /** Chip label, e.g. "CS 210". */
+  code: string;
+  name: string;
+  rootId: string;
+  nodes: DemoNode[];
+  edges: DemoEdge[];
+}
+
+export const COURSE_GRAPHS: CourseGraph[] = [
+  {
+    id: 'cs210',
+    code: 'CS 210',
+    name: 'Data Structures',
+    rootId: 'cs-root',
+    nodes: [
+      { id: 'cs-root', label: 'CS 210', tier: 'learning', blurb: 'Data Structures — 24 concepts mapped from your syllabus', children: ['cs-arrays', 'cs-recursion', 'cs-complexity'] },
+      { id: 'cs-arrays', label: 'Arrays', tier: 'mastered', blurb: 'Contiguous storage and index arithmetic', children: ['cs-sorting'] },
+      { id: 'cs-recursion', label: 'Recursion', tier: 'struggling', blurb: 'Base cases, call stack depth, and when to prefer iteration', children: ['cs-trees'] },
+      { id: 'cs-complexity', label: 'Big-O', tier: 'learning', blurb: 'Asymptotic bounds for time and space', children: [] },
+      { id: 'cs-sorting', label: 'Sorting', tier: 'learning', blurb: 'Comparison sorts and their lower bound', children: [] },
+      { id: 'cs-trees', label: 'Trees', tier: 'unexplored', blurb: 'Traversals, balance, and why recursion fits them', children: [] },
+    ],
+    edges: [
+      { source: 'cs-root', target: 'cs-arrays' },
+      { source: 'cs-root', target: 'cs-recursion' },
+      { source: 'cs-root', target: 'cs-complexity' },
+      { source: 'cs-arrays', target: 'cs-sorting' },
+      { source: 'cs-recursion', target: 'cs-trees' },
+      { source: 'cs-sorting', target: 'cs-complexity' },
+    ],
+  },
+  {
+    id: 'ma242',
+    code: 'MA 242',
+    name: 'Linear Algebra',
+    rootId: 'ma-root',
+    nodes: [
+      { id: 'ma-root', label: 'MA 242', tier: 'learning', blurb: 'Linear Algebra — 19 concepts mapped from your syllabus', children: ['ma-vectors', 'ma-matrices', 'ma-eigen'] },
+      { id: 'ma-vectors', label: 'Vector Spaces', tier: 'mastered', blurb: 'Span, basis, and dimension', children: ['ma-independence'] },
+      { id: 'ma-matrices', label: 'Matrices', tier: 'learning', blurb: 'Linear maps written as arrays of numbers', children: ['ma-determinant'] },
+      { id: 'ma-eigen', label: 'Eigenvalues', tier: 'struggling', blurb: 'Directions a transformation only scales', children: [] },
+      { id: 'ma-independence', label: 'Independence', tier: 'learning', blurb: 'When no vector is redundant', children: [] },
+      { id: 'ma-determinant', label: 'Determinant', tier: 'unexplored', blurb: 'Signed volume scaling of a transformation', children: [] },
+    ],
+    edges: [
+      { source: 'ma-root', target: 'ma-vectors' },
+      { source: 'ma-root', target: 'ma-matrices' },
+      { source: 'ma-root', target: 'ma-eigen' },
+      { source: 'ma-vectors', target: 'ma-independence' },
+      { source: 'ma-matrices', target: 'ma-determinant' },
+      { source: 'ma-matrices', target: 'ma-eigen' },
+    ],
+  },
+  {
+    id: 'sm275',
+    code: 'SM 275',
+    name: 'Statistics',
+    rootId: 'sm-root',
+    nodes: [
+      { id: 'sm-root', label: 'SM 275', tier: 'learning', blurb: 'Statistics — 21 concepts mapped from your syllabus', children: ['sm-prob', 'sm-dist', 'sm-testing'] },
+      { id: 'sm-prob', label: 'Probability', tier: 'mastered', blurb: 'Sample spaces, events, and conditioning', children: ['sm-bayes'] },
+      { id: 'sm-dist', label: 'Distributions', tier: 'learning', blurb: 'Shapes that recur across real data', children: ['sm-clt'] },
+      { id: 'sm-testing', label: 'Hypothesis Tests', tier: 'struggling', blurb: 'What a p-value does and does not claim', children: [] },
+      { id: 'sm-bayes', label: 'Bayes', tier: 'learning', blurb: 'Updating belief as evidence arrives', children: [] },
+      { id: 'sm-clt', label: 'Central Limit', tier: 'unexplored', blurb: 'Why sample means go normal', children: [] },
+    ],
+    edges: [
+      { source: 'sm-root', target: 'sm-prob' },
+      { source: 'sm-root', target: 'sm-dist' },
+      { source: 'sm-root', target: 'sm-testing' },
+      { source: 'sm-prob', target: 'sm-bayes' },
+      { source: 'sm-dist', target: 'sm-clt' },
+      { source: 'sm-dist', target: 'sm-testing' },
+    ],
+  },
+];

From f5b89b51f8ab5b2da3a90911fdba2e5f68df4239 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 11:49:31 -0700
Subject: [PATCH 04/20] feat(landing): deterministic radial layout + helical
 entry path (#344)

---
 .../components/marketing/graph/layout.test.ts |  93 ++++++++++++++
 .../src/components/marketing/graph/layout.ts  | 114 ++++++++++++++++++
 2 files changed, 207 insertions(+)
 create mode 100644 frontend/src/components/marketing/graph/layout.test.ts
 create mode 100644 frontend/src/components/marketing/graph/layout.ts

diff --git a/frontend/src/components/marketing/graph/layout.test.ts b/frontend/src/components/marketing/graph/layout.test.ts
new file mode 100644
index 00000000..bbd7590d
--- /dev/null
+++ b/frontend/src/components/marketing/graph/layout.test.ts
@@ -0,0 +1,93 @@
+/**
+ * The layout is deterministic on purpose: the E2E lane parks the animation and
+ * asserts against a laid-out frame, so identical input must give identical
+ * coordinates on every run and in every environment.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { COURSE_GRAPHS } from './courseGraphs';
+import { easeOutCubic, helixEntry, radialLayout } from './layout';
+
+const G = COURSE_GRAPHS[0];
+
+describe('radialLayout', () => {
+  it('positions every node', () => {
+    const p = radialLayout(G, 800, 500);
+    expect(p.size).toBe(G.nodes.length);
+    for (const n of G.nodes) expect(p.get(n.id)).toBeDefined();
+  });
+
+  it('puts the root at the centre', () => {
+    const p = radialLayout(G, 800, 500);
+    expect(p.get(G.rootId)).toEqual({ x: 400, y: 250 });
+  });
+
+  it('is deterministic', () => {
+    expect(radialLayout(G, 800, 500)).toEqual(radialLayout(G, 800, 500));
+  });
+
+  it('separates nodes at the same depth', () => {
+    const p = radialLayout(G, 800, 500);
+    const depth1 = G.nodes.find((n) => n.id === G.rootId)!.children;
+    const pts = depth1.map((id) => p.get(id)!);
+    for (let i = 0; i < pts.length; i++) {
+      for (let j = i + 1; j < pts.length; j++) {
+        const d = Math.hypot(pts[i].x - pts[j].x, pts[i].y - pts[j].y);
+        expect(d).toBeGreaterThan(40);
+      }
+    }
+  });
+
+  it('scales with the viewport', () => {
+    const small = radialLayout(G, 400, 300);
+    const large = radialLayout(G, 1200, 800);
+    expect(small).not.toEqual(large);
+  });
+});
+
+describe('easeOutCubic', () => {
+  it('pins its endpoints and clamps', () => {
+    expect(easeOutCubic(0)).toBe(0);
+    expect(easeOutCubic(1)).toBe(1);
+    expect(easeOutCubic(-1)).toBe(0);
+    expect(easeOutCubic(4)).toBe(1);
+  });
+});
+
+describe('helixEntry', () => {
+  const target = { x: 300, y: 120 };
+  const centre = { x: 200, y: 200 };
+
+  it('lands exactly on the target at t=1', () => {
+    const r = helixEntry(target, centre, 1);
+    expect(r.x).toBeCloseTo(target.x, 6);
+    expect(r.y).toBeCloseTo(target.y, 6);
+    expect(r.scale).toBeCloseTo(1, 6);
+    expect(r.opacity).toBeCloseTo(1, 6);
+  });
+
+  it('starts invisible and small', () => {
+    const r = helixEntry(target, centre, 0);
+    expect(r.opacity).toBe(0);
+    expect(r.scale).toBeLessThan(0.5);
+  });
+
+  it('rotates around the centre on the way in — the helix', () => {
+    const mid = helixEntry(target, centre, 0.5);
+    const straight = {
+      x: centre.x + (target.x - centre.x) * easeOutCubic(0.5),
+      y: centre.y + (target.y - centre.y) * easeOutCubic(0.5),
+    };
+    const off = Math.hypot(mid.x - straight.x, mid.y - straight.y);
+    expect(off).toBeGreaterThan(10);
+  });
+
+  it('grows monotonically', () => {
+    let prev = -1;
+    for (let t = 0; t <= 1.0001; t += 0.1) {
+      const s = helixEntry(target, centre, t).scale;
+      expect(s).toBeGreaterThan(prev);
+      prev = s;
+    }
+  });
+});
diff --git a/frontend/src/components/marketing/graph/layout.ts b/frontend/src/components/marketing/graph/layout.ts
new file mode 100644
index 00000000..ce45158e
--- /dev/null
+++ b/frontend/src/components/marketing/graph/layout.ts
@@ -0,0 +1,114 @@
+/**
+ * Layout + entry-path math for the landing graph demo (#344).
+ *
+ * Deterministic by construction — no randomness, no time input. The E2E lane
+ * parks the animation and asserts against the laid-out frame, so the same graph
+ * and viewport must always produce the same coordinates.
+ */
+import type { CourseGraph } from './courseGraphs';
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+function clamp01(t: number): number {
+  return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+
+export function easeOutCubic(t: number): number {
+  const c = clamp01(t);
+  return 1 - Math.pow(1 - c, 3);
+}
+
+/**
+ * Root at the centre, each BFS depth on its own ring, siblings spread evenly
+ * around it. Alternate rings are rotated by half a slot so spokes don't line
+ * up into visual spokes.
+ */
+export function radialLayout(
+  graph: CourseGraph,
+  width: number,
+  height: number,
+): Map<string, Point> {
+  const adj = new Map<string, string[]>();
+  for (const e of graph.edges) {
+    adj.set(e.source, [...(adj.get(e.source) ?? []), e.target]);
+    adj.set(e.target, [...(adj.get(e.target) ?? []), e.source]);
+  }
+
+  const depth = new Map<string, number>([[graph.rootId, 0]]);
+  const queue = [graph.rootId];
+  while (queue.length) {
+    const cur = queue.shift()!;
+    for (const nxt of adj.get(cur) ?? []) {
+      if (!depth.has(nxt)) {
+        depth.set(nxt, depth.get(cur)! + 1);
+        queue.push(nxt);
+      }
+    }
+  }
+
+  const byDepth = new Map<number, string[]>();
+  // Iterate graph.nodes (declaration order), not the Map, so ring ordering is
+  // stable regardless of BFS visit order.
+  for (const n of graph.nodes) {
+    const d = depth.get(n.id) ?? 0;
+    byDepth.set(d, [...(byDepth.get(d) ?? []), n.id]);
+  }
+
+  const cx = width / 2;
+  const cy = height / 2;
+  const maxDepth = Math.max(...byDepth.keys(), 1);
+  const ring = (Math.min(width, height) / 2 - 48) / maxDepth;
+
+  const out = new Map<string, Point>();
+  for (const [d, ids] of byDepth) {
+    if (d === 0) {
+      for (const id of ids) out.set(id, { x: cx, y: cy });
+      continue;
+    }
+    const step = (Math.PI * 2) / ids.length;
+    const offset = d % 2 === 0 ? step / 2 : 0;
+    ids.forEach((id, i) => {
+      const a = i * step + offset - Math.PI / 2;
+      out.set(id, {
+        x: cx + Math.cos(a) * ring * d,
+        y: cy + Math.sin(a) * ring * d,
+      });
+    });
+  }
+  return out;
+}
+
+/**
+ * Position along the helical entry path. `t` runs 0 → 1.
+ *
+ * The node spirals inward: its offset from the centre is rotated by a
+ * decreasing angle and stretched outward by a decreasing factor, while scale
+ * and opacity rise. At t=1 every term collapses and the node sits exactly on
+ * `target`, so the animation has no seam where it hands off to the static
+ * layout.
+ */
+export function helixEntry(
+  target: Point,
+  centre: Point,
+  t: number,
+  turns = 1.5,
+): { x: number; y: number; scale: number; opacity: number } {
+  const e = easeOutCubic(t);
+  const dx = target.x - centre.x;
+  const dy = target.y - centre.y;
+
+  const angle = (1 - e) * turns * Math.PI * 2;
+  const stretch = 1 + (1 - e) * 0.9;
+  const cos = Math.cos(angle);
+  const sin = Math.sin(angle);
+
+  return {
+    x: centre.x + (dx * cos - dy * sin) * stretch,
+    y: centre.y + (dx * sin + dy * cos) * stretch,
+    scale: 0.35 + 0.65 * e,
+    opacity: e,
+  };
+}

From d6fc3b9dd0ef91464013ee12b7470a3c961746ef Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 11:56:31 -0700
Subject: [PATCH 05/20] =?UTF-8?q?feat(landing):=20knowledge=20graph=20demo?=
 =?UTF-8?q?=20=E2=80=94=20chips=20and=20laid-out=20render=20(#344)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Static, fully laid-out KnowledgeGraphDemo component: a course-picker
chip row plus an inline SVG render of the selected course's graph via
radialLayout. This is the parked frame reduced-motion visitors and the
E2E lane get; the assembly animation is a later task.

Registers the landing-graph E2E surface (docs/frontend-testids.md +
eslint.config.mjs) and adds the .landing-page-scoped chip/copy CSS.
---
 docs/frontend-testids.md                      |  15 +++
 frontend/eslint.config.mjs                    |   1 +
 frontend/src/app/globals.css                  |  21 ++++
 .../graph/KnowledgeGraphDemo.test.tsx         |  50 +++++++++
 .../marketing/graph/KnowledgeGraphDemo.tsx    | 106 ++++++++++++++++++
 5 files changed, 193 insertions(+)
 create mode 100644 frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
 create mode 100644 frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx

diff --git a/docs/frontend-testids.md b/docs/frontend-testids.md
index 95b9c054..6c015b69 100644
--- a/docs/frontend-testids.md
+++ b/docs/frontend-testids.md
@@ -80,6 +80,7 @@ renders the element.
 | Calendar | `calendar` | `frontend/src/components/screens/Calendar.tsx` (the `/calendar` screen — today just the #185 load-failure banner + retry) |
 | Gradebook | `gradebook` | `frontend/src/components/screens/Gradebook/Landing.tsx` + `Course.tsx` (the `/gradebook` screens), `frontend/src/components/Gradebook/TranscriptModal.tsx` (the transcript modal), `frontend/src/components/Gradebook/CourseCard.tsx` (the term-aware card links), `frontend/src/components/Gradebook/AssignmentList.tsx` + `AssignmentModal.tsx` (the add-assignment flow the #468 mutation leg drives) — added with the #139 term-switcher/transcript journey |
 | Admin analytics | `admin-analytics` | `frontend/src/components/screens/AdminAnalytics.tsx` (the `/admin/analytics` dashboard — range presets/inputs, cost group-by toggle, per-panel retry) — added with the #121 data layer |
+| Landing knowledge graph demo | `landing-graph` | `frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx` (the pre-auth landing page's interactive course-picker + laid-out concept graph, #344) |
 
 Two surfaces do **not** carry their testids in the screen file named by the
 route:
@@ -324,6 +325,20 @@ Added with the upload → SSE → library journey (#387).
 | `library-concepts-toggle-all` | detail panel "Expand all" / "Collapse all" |
 | `library-concept-toggle-{idx}` | one concept accordion toggle (render index) |
 
+### `landing-graph`
+
+Added with the #344 landing-page knowledge-graph demo. This task ships the
+static, fully laid-out render only — chips to switch course, nodes/edges for
+the selected graph; the assembly animation and hover/click interaction are
+later tasks in the same spec and reuse these same testids.
+
+| testid | element |
+| --- | --- |
+| `landing-graph` | demo section root (`aria-label` names the selected course) |
+| `landing-graph-chip-{courseId}` | one course-picker chip, per `COURSE_GRAPHS` entry — `aria-pressed` marks the active course |
+| `landing-graph-node-{nodeId}` | one SVG node group (`<g>`) in the selected course's graph |
+| `landing-graph-copy` | the section's instructional copy block (eyebrow label + heading) |
+
 ## Enforcement
 
 `frontend/eslint.config.mjs` has a per-file `no-restricted-syntax` block scoped
diff --git a/frontend/eslint.config.mjs b/frontend/eslint.config.mjs
index b6bd439e..2914bf85 100644
--- a/frontend/eslint.config.mjs
+++ b/frontend/eslint.config.mjs
@@ -75,6 +75,7 @@ const eslintConfig = [
       "src/components/Gradebook/AssignmentModal.tsx",
       "src/components/screens/AdminAnalytics.tsx",
       "src/components/screens/Tree.tsx",
+      "src/components/marketing/graph/KnowledgeGraphDemo.tsx",
     ],
     rules: {
       "no-restricted-syntax": [
diff --git a/frontend/src/app/globals.css b/frontend/src/app/globals.css
index d7274be0..e43cfa8a 100644
--- a/frontend/src/app/globals.css
+++ b/frontend/src/app/globals.css
@@ -1002,3 +1002,24 @@ input[type="reset"]:disabled {
   .landing-page .landing-feature-row:hover .landing-feature-title { transform: none; }
   .landing-page .landing-feature-row:hover .landing-feature-icon { transform: none; }
 }
+
+/* ── Knowledge graph demo (#344) ── */
+.landing-page .landing-graph-chip {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.78rem;
+  letter-spacing: 0.08em;
+  padding: 7px 16px;
+  border-radius: 9999px;
+  border: 1px solid rgba(107, 114, 128, 0.28);
+  background: rgba(255, 255, 255, 0.55);
+  color: var(--text-dim);
+  cursor: pointer;
+  transition: background 0.2s ease, color 0.2s ease, border-color 0.2s ease;
+}
+.landing-page .landing-graph-chip:hover { border-color: var(--brand-forest); }
+.landing-page .landing-graph-chip.is-active {
+  background: var(--brand-forest);
+  border-color: var(--brand-forest);
+  color: #fff;
+}
+.landing-page .landing-graph-copy { transition: opacity 600ms ease; }
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
new file mode 100644
index 00000000..758e5fe4
--- /dev/null
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
@@ -0,0 +1,50 @@
+// @vitest-environment jsdom
+/**
+ * The parked frame is the contract. Reduced-motion visitors and the E2E lane
+ * both get this render, so "parked" has to mean laid out and readable — not
+ * blank and not mid-assembly.
+ */
+import React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup, fireEvent } from '@testing-library/react';
+
+import KnowledgeGraphDemo from './KnowledgeGraphDemo';
+import { COURSE_GRAPHS } from './courseGraphs';
+
+afterEach(cleanup);
+
+describe('KnowledgeGraphDemo', () => {
+  it('renders a chip per course, with the first selected', () => {
+    render(<KnowledgeGraphDemo />);
+    for (const g of COURSE_GRAPHS) {
+      expect(screen.getByTestId(`landing-graph-chip-${g.id}`)).toBeInTheDocument();
+    }
+    expect(
+      screen.getByTestId(`landing-graph-chip-${COURSE_GRAPHS[0].id}`),
+    ).toHaveAttribute('aria-pressed', 'true');
+  });
+
+  it('renders the selected course graph fully laid out', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+    for (const n of g.nodes) {
+      expect(screen.getByTestId(`landing-graph-node-${n.id}`)).toBeInTheDocument();
+    }
+  });
+
+  it('swaps the graph when another chip is picked', () => {
+    render(<KnowledgeGraphDemo />);
+    const target = COURSE_GRAPHS[1];
+    fireEvent.click(screen.getByTestId(`landing-graph-chip-${target.id}`));
+
+    expect(screen.getByTestId(`landing-graph-node-${target.nodes[0].id}`)).toBeInTheDocument();
+    expect(
+      screen.queryByTestId(`landing-graph-node-${COURSE_GRAPHS[0].nodes[0].id}`),
+    ).not.toBeInTheDocument();
+  });
+
+  it('labels the section for assistive tech', () => {
+    render(<KnowledgeGraphDemo />);
+    expect(screen.getByTestId('landing-graph')).toHaveAttribute('aria-label');
+  });
+});
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
new file mode 100644
index 00000000..3c159eb5
--- /dev/null
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -0,0 +1,106 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+
+import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph } from './courseGraphs';
+import { radialLayout } from './layout';
+
+const VIEW_W = 900;
+const VIEW_H = 560;
+
+function nodeRadius(g: CourseGraph, id: string): number {
+  return id === g.rootId ? 26 : 14;
+}
+
+export default function KnowledgeGraphDemo() {
+  const [courseId, setCourseId] = useState(COURSE_GRAPHS[0].id);
+
+  const graph = useMemo(
+    () => COURSE_GRAPHS.find((g) => g.id === courseId) ?? COURSE_GRAPHS[0],
+    [courseId],
+  );
+  const points = useMemo(() => radialLayout(graph, VIEW_W, VIEW_H), [graph]);
+
+  return (
+    <section
+      id="knowledge-graph"
+      data-testid="landing-graph"
+      aria-label={`Interactive knowledge graph for ${graph.name}`}
+      className="landing-section landing-graph relative z-10 py-24 md:py-32"
+    >
+      <div className="max-w-7xl mx-auto px-6 lg:px-12">
+        <div data-testid="landing-graph-copy" className="landing-graph-copy">
+          <span className="font-jetbrains text-[0.7rem] tracking-[0.32em] text-[var(--brand-forest)] uppercase font-medium">
+            Your knowledge, mapped
+          </span>
+          <h2 className="font-playfair text-4xl md:text-6xl font-semibold text-[var(--text)] mt-4 leading-[1.05] tracking-tight">
+            Pick a course. Watch it grow.
+          </h2>
+        </div>
+
+        <div className="mt-8 flex flex-wrap gap-3">
+          {COURSE_GRAPHS.map((g) => {
+            const active = g.id === graph.id;
+            return (
+              <button
+                key={g.id}
+                type="button"
+                data-testid={`landing-graph-chip-${g.id}`}
+                aria-pressed={active}
+                onClick={() => setCourseId(g.id)}
+                className={`landing-graph-chip${active ? ' is-active' : ''}`}
+              >
+                {g.code}
+              </button>
+            );
+          })}
+        </div>
+
+        <svg
+          viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+          className="mt-8 w-full h-auto"
+          role="img"
+          aria-label={`${graph.name} concept graph`}
+        >
+          {graph.edges.map((e) => {
+            const a = points.get(e.source);
+            const b = points.get(e.target);
+            if (!a || !b) return null;
+            return (
+              <line
+                key={`${e.source}-${e.target}`}
+                x1={a.x}
+                y1={a.y}
+                x2={b.x}
+                y2={b.y}
+                stroke="var(--text-dim)"
+                strokeOpacity={0.28}
+                strokeWidth={1.4}
+              />
+            );
+          })}
+
+          {graph.nodes.map((n) => {
+            const p = points.get(n.id);
+            if (!p) return null;
+            return (
+              <g key={n.id} data-testid={`landing-graph-node-${n.id}`}>
+                <circle cx={p.x} cy={p.y} r={nodeRadius(graph, n.id)} fill={TIER_COLOR[n.tier]} />
+                <text
+                  x={p.x}
+                  y={p.y + nodeRadius(graph, n.id) + 16}
+                  textAnchor="middle"
+                  className="font-jetbrains"
+                  fontSize={12}
+                  fill="var(--text-dim)"
+                >
+                  {n.label}
+                </text>
+              </g>
+            );
+          })}
+        </svg>
+      </div>
+    </section>
+  );
+}

From 69a718bc69863ff22f11e0dcb01de5c9c0fc6c1a Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 12:08:09 -0700
Subject: [PATCH 06/20] feat(landing): helical assembly, parked under reduced
 motion (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the RAF-driven helical assembly to KnowledgeGraphDemo, extracted into
an AssemblingGraph child keyed by course id so switching courses remounts
(fresh progress state, unmount-driven RAF cleanup) instead of resetting
state inside an effect — avoids the react-hooks/set-state-in-effect
anti-pattern that the brief's literal snippet would have tripped.

Parked (progress=1, full opacity, laid out) whenever IS_TEST_MODE or
prefers-reduced-motion. Adds a guarded window.matchMedia stub to
vitest.setup.ts (jsdom has none) defaulting to reduced-motion=true, so
every KnowledgeGraphDemo unit test asserts the parked/complete frame —
the correct target for reduced-motion visitors and the E2E lane alike.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../graph/KnowledgeGraphDemo.test.tsx         |  22 +++
 .../marketing/graph/KnowledgeGraphDemo.tsx    | 138 +++++++++++++-----
 frontend/vitest.setup.ts                      |  24 +++
 3 files changed, 145 insertions(+), 39 deletions(-)

diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
index 758e5fe4..a398ed68 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
@@ -48,3 +48,25 @@ describe('KnowledgeGraphDemo', () => {
     expect(screen.getByTestId('landing-graph')).toHaveAttribute('aria-label');
   });
 });
+
+describe('KnowledgeGraphDemo — motion', () => {
+  it('parks fully assembled when reduced motion is requested', () => {
+    // jsdom has no matchMedia; supply one that reports "reduce".
+    window.matchMedia = ((q: string) => ({
+      matches: q.includes('prefers-reduced-motion'),
+      media: q,
+      addEventListener() {},
+      removeEventListener() {},
+    })) as unknown as typeof window.matchMedia;
+
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+
+    // Every node present AND at full opacity — parked means complete.
+    for (const n of g.nodes) {
+      const el = screen.getByTestId(`landing-graph-node-${n.id}`);
+      expect(el).toBeInTheDocument();
+      expect(el.getAttribute('opacity')).toBe('1');
+    }
+  });
+});
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index 3c159eb5..98da103c 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -1,17 +1,107 @@
 'use client';
 
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import { IS_TEST_MODE, now } from '@/lib/testMode';
 
 import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph } from './courseGraphs';
-import { radialLayout } from './layout';
+import { helixEntry, radialLayout, type Point } from './layout';
 
 const VIEW_W = 900;
 const VIEW_H = 560;
 
+/** How long the helical assembly takes to land on the laid-out frame. */
+const ASSEMBLE_MS = 1100;
+
 function nodeRadius(g: CourseGraph, id: string): number {
   return id === g.rootId ? 26 : 14;
 }
 
+/**
+ * Renders one course's edges + nodes, animating them in along the helical
+ * entry path (#344). The parent keys this by `graph.id`, so picking another
+ * course remounts it — a fresh `progress` state per course instead of
+ * resetting one inside an effect (the "adjusting state on a prop change"
+ * anti-pattern React's own react-hooks/set-state-in-effect rule flags).
+ * Remounting also means unmount cleanup alone is enough to cancel the RAF
+ * both on course change and on real unmount — no separate reset path needed.
+ */
+function AssemblingGraph({
+  graph,
+  points,
+  parked,
+}: {
+  graph: CourseGraph;
+  points: Map<string, Point>;
+  parked: boolean;
+}) {
+  // "Parked" means the assembly is skipped and the graph renders complete —
+  // fully laid out, full opacity — on the very first frame. Reduced-motion
+  // visitors and the E2E/unit-test lanes (IS_TEST_MODE) both get this.
+  const [progress, setProgress] = useState(parked ? 1 : 0);
+  const rafRef = useRef(0);
+
+  useEffect(() => {
+    if (parked) return;
+    const start = now();
+    const tick = () => {
+      const p = Math.min(1, (now() - start) / ASSEMBLE_MS);
+      setProgress(p);
+      if (p < 1) rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(rafRef.current);
+  }, [parked]);
+
+  return (
+    <>
+      {graph.edges.map((e) => {
+        const a = points.get(e.source);
+        const b = points.get(e.target);
+        if (!a || !b) return null;
+        return (
+          <line
+            key={`${e.source}-${e.target}`}
+            x1={a.x}
+            y1={a.y}
+            x2={b.x}
+            y2={b.y}
+            stroke="var(--text-dim)"
+            strokeOpacity={0.28 * progress}
+            strokeWidth={1.4}
+          />
+        );
+      })}
+
+      {graph.nodes.map((n, i) => {
+        const p = points.get(n.id);
+        if (!p) return null;
+        // Stagger: later nodes start later, all finish by progress = 1.
+        const span = 1 / (graph.nodes.length + 2);
+        const local = Math.min(1, Math.max(0, (progress - i * span) / (1 - i * span)));
+        const h = helixEntry(p, { x: VIEW_W / 2, y: VIEW_H / 2 }, local);
+        const r = nodeRadius(graph, n.id);
+        return (
+          <g key={n.id} data-testid={`landing-graph-node-${n.id}`} opacity={h.opacity}>
+            <circle cx={h.x} cy={h.y} r={r * h.scale} fill={TIER_COLOR[n.tier]} />
+            <text
+              x={h.x}
+              y={h.y + r + 16}
+              textAnchor="middle"
+              className="font-jetbrains"
+              fontSize={12}
+              fill="var(--text-dim)"
+              opacity={h.opacity}
+            >
+              {n.label}
+            </text>
+          </g>
+        );
+      })}
+    </>
+  );
+}
+
 export default function KnowledgeGraphDemo() {
   const [courseId, setCourseId] = useState(COURSE_GRAPHS[0].id);
 
@@ -21,6 +111,12 @@ export default function KnowledgeGraphDemo() {
   );
   const points = useMemo(() => radialLayout(graph, VIEW_W, VIEW_H), [graph]);
 
+  const prefersReduced =
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  const parked = IS_TEST_MODE || prefersReduced;
+
   return (
     <section
       id="knowledge-graph"
@@ -62,43 +158,7 @@ export default function KnowledgeGraphDemo() {
           role="img"
           aria-label={`${graph.name} concept graph`}
         >
-          {graph.edges.map((e) => {
-            const a = points.get(e.source);
-            const b = points.get(e.target);
-            if (!a || !b) return null;
-            return (
-              <line
-                key={`${e.source}-${e.target}`}
-                x1={a.x}
-                y1={a.y}
-                x2={b.x}
-                y2={b.y}
-                stroke="var(--text-dim)"
-                strokeOpacity={0.28}
-                strokeWidth={1.4}
-              />
-            );
-          })}
-
-          {graph.nodes.map((n) => {
-            const p = points.get(n.id);
-            if (!p) return null;
-            return (
-              <g key={n.id} data-testid={`landing-graph-node-${n.id}`}>
-                <circle cx={p.x} cy={p.y} r={nodeRadius(graph, n.id)} fill={TIER_COLOR[n.tier]} />
-                <text
-                  x={p.x}
-                  y={p.y + nodeRadius(graph, n.id) + 16}
-                  textAnchor="middle"
-                  className="font-jetbrains"
-                  fontSize={12}
-                  fill="var(--text-dim)"
-                >
-                  {n.label}
-                </text>
-              </g>
-            );
-          })}
+          <AssemblingGraph key={graph.id} graph={graph} points={points} parked={parked} />
         </svg>
       </div>
     </section>
diff --git a/frontend/vitest.setup.ts b/frontend/vitest.setup.ts
index ac1f3ea3..daefcdd5 100644
--- a/frontend/vitest.setup.ts
+++ b/frontend/vitest.setup.ts
@@ -26,3 +26,27 @@ if (typeof window !== "undefined" && !window.localStorage) {
     configurable: true,
   });
 }
+
+// jsdom ships no `window.matchMedia` at all, so any component that reads
+// `window.matchMedia('(prefers-reduced-motion: reduce)').matches` (the
+// landing knowledge-graph demo, KnowledgeGraph3D, ...) would throw under
+// vitest without a stub. Default to reduced-motion = true: that's the
+// parked/complete frame, which is also the correct assertion target for a
+// hermetic unit test (no RAF loop, no clock-driven flakiness). Test files
+// that need different behavior (e.g. `useIsMobile.test.tsx`,
+// `KnowledgeGraph3D.test.tsx`) already install their own `window.matchMedia`
+// per test via `beforeEach`, which overrides this file-load-time default.
+if (typeof window !== "undefined" && typeof window.matchMedia !== "function") {
+  window.matchMedia = ((query: string) => ({
+    matches: query.includes("prefers-reduced-motion"),
+    media: query,
+    onchange: null,
+    addEventListener() {},
+    removeEventListener() {},
+    addListener() {},
+    removeListener() {},
+    dispatchEvent() {
+      return false;
+    },
+  })) as unknown as typeof window.matchMedia;
+}

From fed4d127e8fd7e2285130db78b2d7448e8fe6934 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 12:26:52 -0700
Subject: [PATCH 07/20] fix(landing): SSR-safe reduced-motion detection for the
 graph demo (#344)

Fix round 1: reading window.matchMedia directly in KnowledgeGraphDemo's
render body computed "no preference" server-side (no window) but the real
value client-side, producing a genuine React hydration mismatch for any
reduced-motion visitor once this component mounts with SSR on.

Adds usePrefersReducedMotion (frontend/src/lib/usePrefersReducedMotion.ts),
following the same useSyncExternalStore + fixed getServerSnapshot pattern
useIsMobile.ts already established for this bug class. Server snapshot
defaults to true (assume reduced motion) rather than useIsMobile's false
default: whichever direction is wrong pays a cost, and defaulting true means
the cost lands on no-preference visitors (one extra replay of the entrance
animation) rather than reduced-motion visitors (who would otherwise see a
blank or mid-assembly graph on first paint).

Also switches AssemblingGraph's progress from raw state to a value derived
from `parked` at render time, so a post-hydration correction of `parked`
(without a remount) resolves correctly in both directions instead of
potentially getting stuck.

Adds a renderToString -> hydrateRoot regression test using different
matchMedia values across the two phases, verified to fail against the old
render-body-read pattern before confirming it passes against the fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../graph/KnowledgeGraphDemo.test.tsx         | 102 +++++++++++++++++-
 .../marketing/graph/KnowledgeGraphDemo.tsx    |  30 ++++--
 frontend/src/lib/usePrefersReducedMotion.ts   |  80 ++++++++++++++
 3 files changed, 203 insertions(+), 9 deletions(-)
 create mode 100644 frontend/src/lib/usePrefersReducedMotion.ts

diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
index a398ed68..6886866f 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
@@ -5,11 +5,15 @@
  * blank and not mid-assembly.
  */
 import React from 'react';
-import { describe, it, expect, afterEach } from 'vitest';
+import { act } from 'react';
+import { renderToString } from 'react-dom/server';
+import { hydrateRoot, type Root } from 'react-dom/client';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { render, screen, cleanup, fireEvent } from '@testing-library/react';
 
 import KnowledgeGraphDemo from './KnowledgeGraphDemo';
 import { COURSE_GRAPHS } from './courseGraphs';
+import { __resetReducedMotionStoreForTests } from '@/lib/usePrefersReducedMotion';
 
 afterEach(cleanup);
 
@@ -70,3 +74,99 @@ describe('KnowledgeGraphDemo — motion', () => {
     }
   });
 });
+
+/** Controllable `window.matchMedia`, scoped to the reduced-motion query. */
+function installReducedMotion(matches: boolean) {
+  const listeners = new Set<() => void>();
+  const mql = {
+    matches,
+    media: '(prefers-reduced-motion: reduce)',
+    addEventListener: (_type: string, cb: () => void) => {
+      listeners.add(cb);
+    },
+    removeEventListener: (_type: string, cb: () => void) => {
+      listeners.delete(cb);
+    },
+  };
+  window.matchMedia = ((q: string) =>
+    q.includes('prefers-reduced-motion')
+      ? mql
+      : { matches: false, media: q, addEventListener() {}, removeEventListener() {} }) as unknown as typeof window.matchMedia;
+  return mql;
+}
+
+/**
+ * Pins #344 fix round 1: a review finding that reading `window.matchMedia`
+ * directly in the component's render body computes a value server-side (no
+ * `window`, always "no preference") that can disagree with the real client
+ * value, producing a genuine React hydration mismatch for any reduced-motion
+ * visitor once this component is mounted with SSR on (a later task does
+ * exactly that via `next/dynamic`). `usePrefersReducedMotion` fixes this via
+ * `useSyncExternalStore` with a fixed server snapshot, the same pattern
+ * `useIsMobile` already uses for the same bug class.
+ */
+describe('KnowledgeGraphDemo — SSR/hydration parking (#344 fix round 1)', () => {
+  let container: HTMLDivElement;
+  let root: Root | null = null;
+  const actEnv = globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean };
+
+  beforeEach(() => {
+    actEnv.IS_REACT_ACT_ENVIRONMENT = true;
+    __resetReducedMotionStoreForTests();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    if (root) act(() => root!.unmount());
+    root = null;
+    container.remove();
+    actEnv.IS_REACT_ACT_ENVIRONMENT = undefined;
+  });
+
+  it('renders the complete frame on the server, and hydrates a reduced-motion client onto it with no recoverable error', async () => {
+    const g = COURSE_GRAPHS[0];
+
+    // "SSR-time" world: if a render-body read consulted the live query
+    // directly, it would see "no preference" here.
+    installReducedMotion(false);
+    const html = renderToString(<KnowledgeGraphDemo />);
+
+    const ssrScratch = document.createElement('div');
+    ssrScratch.innerHTML = html;
+    for (const n of g.nodes) {
+      const el = ssrScratch.querySelector(`[data-testid="landing-graph-node-${n.id}"]`);
+      expect(el).toBeTruthy();
+      // The assertion that pins the fix: SSR output comes from the hook's
+      // fixed server snapshot (always "reduced motion" — see its doc
+      // comment), not the live query above. A regression to a render-body
+      // `window.matchMedia` read would bake progress=0 (mid-assembly,
+      // opacity 0) into this string instead of the complete frame.
+      expect(el?.getAttribute('opacity')).toBe('1');
+    }
+
+    // Now the real client: OS reports reduced motion — deliberately the
+    // opposite of the "SSR-time" result above. Using the same value for
+    // both phases would let a regression to the old pattern pass this test
+    // by accident, since both phases would then just agree by luck.
+    __resetReducedMotionStoreForTests();
+    installReducedMotion(true);
+
+    container.innerHTML = html;
+    const recoverable: unknown[] = [];
+    await act(async () => {
+      root = hydrateRoot(container, <KnowledgeGraphDemo />, {
+        onRecoverableError: (err) => recoverable.push(err),
+      });
+    });
+
+    // No hydration mismatch, and the reduced-motion client lands on (and
+    // stays on) the complete frame — never blank, never mid-assembly.
+    expect(recoverable).toEqual([]);
+    for (const n of g.nodes) {
+      const el = container.querySelector(`[data-testid="landing-graph-node-${n.id}"]`);
+      expect(el).toBeTruthy();
+      expect(el?.getAttribute('opacity')).toBe('1');
+    }
+  });
+});
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index 98da103c..f6eec696 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -3,6 +3,7 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 
 import { IS_TEST_MODE, now } from '@/lib/testMode';
+import { usePrefersReducedMotion } from '@/lib/usePrefersReducedMotion';
 
 import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph } from './courseGraphs';
 import { helixEntry, radialLayout, type Point } from './layout';
@@ -20,11 +21,21 @@ function nodeRadius(g: CourseGraph, id: string): number {
 /**
  * Renders one course's edges + nodes, animating them in along the helical
  * entry path (#344). The parent keys this by `graph.id`, so picking another
- * course remounts it — a fresh `progress` state per course instead of
- * resetting one inside an effect (the "adjusting state on a prop change"
+ * course remounts it — a fresh `animatedProgress` state per course instead
+ * of resetting one inside an effect (the "adjusting state on a prop change"
  * anti-pattern React's own react-hooks/set-state-in-effect rule flags).
  * Remounting also means unmount cleanup alone is enough to cancel the RAF
  * both on course change and on real unmount — no separate reset path needed.
+ *
+ * `progress` is derived from `animatedProgress`, not the state directly:
+ * `parked` can flip after mount without a remount (`usePrefersReducedMotion`
+ * corrects from its SSR-safe default to the real client value shortly after
+ * hydration — see that hook's doc comment), and deriving `progress` this way
+ * means that transition is correct in *both* directions without an effect
+ * having to reconcile it: parked always reads back as the complete frame
+ * regardless of whatever `animatedProgress` last held, and un-parking just
+ * exposes whatever `animatedProgress` already is (still its unmounted-since
+ * initial `0` if the assembly effect below hasn't started yet).
  */
 function AssemblingGraph({
   graph,
@@ -35,10 +46,11 @@ function AssemblingGraph({
   points: Map<string, Point>;
   parked: boolean;
 }) {
+  const [animatedProgress, setAnimatedProgress] = useState(0);
   // "Parked" means the assembly is skipped and the graph renders complete —
   // fully laid out, full opacity — on the very first frame. Reduced-motion
   // visitors and the E2E/unit-test lanes (IS_TEST_MODE) both get this.
-  const [progress, setProgress] = useState(parked ? 1 : 0);
+  const progress = parked ? 1 : animatedProgress;
   const rafRef = useRef(0);
 
   useEffect(() => {
@@ -46,7 +58,7 @@ function AssemblingGraph({
     const start = now();
     const tick = () => {
       const p = Math.min(1, (now() - start) / ASSEMBLE_MS);
-      setProgress(p);
+      setAnimatedProgress(p);
       if (p < 1) rafRef.current = requestAnimationFrame(tick);
     };
     rafRef.current = requestAnimationFrame(tick);
@@ -111,10 +123,12 @@ export default function KnowledgeGraphDemo() {
   );
   const points = useMemo(() => radialLayout(graph, VIEW_W, VIEW_H), [graph]);
 
-  const prefersReduced =
-    typeof window !== 'undefined' &&
-    typeof window.matchMedia === 'function' &&
-    window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  // `usePrefersReducedMotion` (not a direct `window.matchMedia` read in the
+  // render body — #344 fix round 1) is hydration-safe: it renders the same
+  // value on the server and the first client paint, then corrects to the
+  // real value after hydration commits. See its doc comment for why it
+  // defaults to "reduced motion" rather than "no preference".
+  const prefersReduced = usePrefersReducedMotion();
   const parked = IS_TEST_MODE || prefersReduced;
 
   return (
diff --git a/frontend/src/lib/usePrefersReducedMotion.ts b/frontend/src/lib/usePrefersReducedMotion.ts
new file mode 100644
index 00000000..5f177f62
--- /dev/null
+++ b/frontend/src/lib/usePrefersReducedMotion.ts
@@ -0,0 +1,80 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+
+type MediaStore = {
+  subscribe: (onStoreChange: () => void) => () => void;
+  getSnapshot: () => boolean;
+};
+
+/**
+ * One store for the query, built lazily on first use and reused by every
+ * consumer — same rationale as `useIsMobile`'s `stores` map: it keeps
+ * `subscribe`'s identity stable across renders so React doesn't tear down
+ * and re-establish the `MediaQueryList` listener on every commit.
+ */
+let cached: MediaStore | null = null;
+
+function store(): MediaStore {
+  if (cached) return cached;
+  const mql = window.matchMedia(REDUCED_MOTION_QUERY);
+  cached = {
+    subscribe: (onStoreChange) => {
+      mql.addEventListener("change", onStoreChange);
+      return () => mql.removeEventListener("change", onStoreChange);
+    },
+    getSnapshot: () => mql.matches,
+  };
+  return cached;
+}
+
+const noopSubscribe = () => () => {};
+
+/**
+ * Server snapshot defaults to `true` (assume reduced motion) — the opposite
+ * default from `useIsMobile`'s `false`, and deliberately so. Both hooks
+ * resolve the same "server has no window" ambiguity via
+ * `useSyncExternalStore`'s `getServerSnapshot`, but the two outcomes aren't
+ * symmetric here the way desktop/mobile is:
+ *
+ *   - Default `true`, real value `false` (a no-preference visitor whose
+ *     server guess was "reduced motion"): after hydration commits, the
+ *     store's snapshot check corrects to `false` and the entrance animation
+ *     plays — one extra replay of an animation for a visitor who by
+ *     definition doesn't mind motion. Cosmetic only.
+ *   - Default `false`, real value `true` (a reduced-motion visitor whose
+ *     server guess was "no preference"): the SSR + hydration paint would
+ *     show the graph mid-assembly or blank — exactly what
+ *     `prefers-reduced-motion` exists to prevent, for the one population
+ *     that asked for it.
+ *
+ * Given the mismatch is unavoidable for whoever doesn't match the default,
+ * default to the direction that's safe to be wrong about: `true`.
+ */
+const serverSnapshot = () => true;
+
+/**
+ * True when the OS/browser reports `prefers-reduced-motion: reduce`. Safe to
+ * call during SSR — see `serverSnapshot` above for why it defaults `true`
+ * rather than `false`. Reading `window.matchMedia` directly in a render body
+ * instead (the bug this hook replaces, #344) computes a fresh value on the
+ * server (no `window`, always `false`) and on the first client render (real
+ * value), which React then finds disagree — a genuine hydration mismatch
+ * on every reduced-motion visitor whenever this component is mounted with
+ * SSR on.
+ */
+export function usePrefersReducedMotion(): boolean {
+  const s = typeof window === "undefined" ? null : store();
+  return useSyncExternalStore(
+    s?.subscribe ?? noopSubscribe,
+    s?.getSnapshot ?? serverSnapshot,
+    serverSnapshot,
+  );
+}
+
+/** Test-only: drop the cached `MediaQueryList` store. Not for app code. */
+export function __resetReducedMotionStoreForTests() {
+  cached = null;
+}

From fe906f98b019817194368fbcfb7c03c4217c444c Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 12:35:49 -0700
Subject: [PATCH 08/20] test(landing): cold-start the reduced-motion store
 cache per test (#344)

Fix round 2: usePrefersReducedMotion's module-level MediaQueryList cache
(correct for production) survived across it() blocks within
KnowledgeGraphDemo.test.tsx, so the round-0 test 'parks fully assembled
when reduced motion is requested' inherited an earlier test's warmed
cache instead of its own local matchMedia override. It still passed, but
for the wrong reason -- false confidence, not regression protection.
Reviewer proof: inverting that test's override to report "no preference"
left the whole file green.

Adds a file-level beforeEach calling __resetReducedMotionStoreForTests()
so every test in the file cold-starts the cache and actually depends on
its own window.matchMedia. Removes the now-redundant reset from the
round-1 describe block's nested beforeEach (the mid-test reset between
its two installReducedMotion() calls stays, since a beforeEach only runs
once per test). Verified by the same inversion the reviewer used: fails
whole-file with the override flipped, passes again once restored.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../marketing/graph/KnowledgeGraphDemo.test.tsx | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
index 6886866f..8e8d861c 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
@@ -17,6 +17,19 @@ import { __resetReducedMotionStoreForTests } from '@/lib/usePrefersReducedMotion
 
 afterEach(cleanup);
 
+// `usePrefersReducedMotion` caches its `MediaQueryList` at module scope (by
+// design — production wants one shared subscription, not one per consumer).
+// Under vitest that cache survives across `it()` blocks in this file, so a
+// test that installs its own local `window.matchMedia` — like the two below
+// that swap it mid-run — would silently inherit whatever a *previous* test's
+// render already warmed the cache with instead of its own override. Cold
+// start every test so each one's `window.matchMedia` (whatever it is: the
+// `vitest.setup.ts` default, or a local override) is what actually gets
+// queried.
+beforeEach(() => {
+  __resetReducedMotionStoreForTests();
+});
+
 describe('KnowledgeGraphDemo', () => {
   it('renders a chip per course, with the first selected', () => {
     render(<KnowledgeGraphDemo />);
@@ -111,8 +124,10 @@ describe('KnowledgeGraphDemo — SSR/hydration parking (#344 fix round 1)', () =
   const actEnv = globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean };
 
   beforeEach(() => {
+    // The file-level `beforeEach` above already cold-starts the reduced-
+    // motion store for this test; this block only owns the hydration
+    // container + act-environment setup.
     actEnv.IS_REACT_ACT_ENVIRONMENT = true;
-    __resetReducedMotionStoreForTests();
     container = document.createElement('div');
     document.body.appendChild(container);
   });

From 1a3c2f5419b451074f2173bd67914de538b49ed0 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 12:41:44 -0700
Subject: [PATCH 09/20] feat(landing): graph hover blurbs and copy fade on
 engagement (#344)

Hover a node to reveal its concept blurb below the graph; the first
interaction fades the instructional copy for the rest of the session.

Both `hovered` and `engaged` live in the KnowledgeGraphDemo parent, not
in the AssemblingGraph child, since that child remounts (keyed by
graph.id) on every course switch. engaged must survive that remount;
hovered's home follows since the blurb paragraph renders in the parent
too. AssemblingGraph just gets onNodeEnter/onNodeLeave callback props.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/frontend-testids.md                      | 12 ++--
 .../graph/KnowledgeGraphDemo.test.tsx         | 38 ++++++++++
 .../marketing/graph/KnowledgeGraphDemo.tsx    | 69 ++++++++++++++++++-
 3 files changed, 111 insertions(+), 8 deletions(-)

diff --git a/docs/frontend-testids.md b/docs/frontend-testids.md
index 6c015b69..50438daa 100644
--- a/docs/frontend-testids.md
+++ b/docs/frontend-testids.md
@@ -327,17 +327,19 @@ Added with the upload → SSE → library journey (#387).
 
 ### `landing-graph`
 
-Added with the #344 landing-page knowledge-graph demo. This task ships the
-static, fully laid-out render only — chips to switch course, nodes/edges for
-the selected graph; the assembly animation and hover/click interaction are
-later tasks in the same spec and reuse these same testids.
+Added with the #344 landing-page knowledge-graph demo. Ships the static,
+fully laid-out render (chips to switch course, nodes/edges for the selected
+graph), the helical assembly animation, and hover interaction (blurb reveal +
+copy fade on first engagement); click-to-expand is a later task in the same
+spec and will reuse these same testids.
 
 | testid | element |
 | --- | --- |
 | `landing-graph` | demo section root (`aria-label` names the selected course) |
 | `landing-graph-chip-{courseId}` | one course-picker chip, per `COURSE_GRAPHS` entry — `aria-pressed` marks the active course |
 | `landing-graph-node-{nodeId}` | one SVG node group (`<g>`) in the selected course's graph |
-| `landing-graph-copy` | the section's instructional copy block (eyebrow label + heading) |
+| `landing-graph-copy` | the section's instructional copy block (eyebrow label + heading) — `data-engaged` flips `"true"` on the visitor's first node hover and stays that way across course switches |
+| `landing-graph-blurb` | the reserved-height paragraph below the graph that shows the hovered node's one-sentence blurb |
 
 ## Enforcement
 
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
index 8e8d861c..81a61b17 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
@@ -185,3 +185,41 @@ describe('KnowledgeGraphDemo — SSR/hydration parking (#344 fix round 1)', () =
     }
   });
 });
+
+describe('KnowledgeGraphDemo — interaction', () => {
+  it('shows a concept blurb on hover', () => {
+    render(<KnowledgeGraphDemo />);
+    const n = COURSE_GRAPHS[0].nodes[1];
+    fireEvent.mouseEnter(screen.getByTestId(`landing-graph-node-${n.id}`));
+    expect(screen.getByTestId('landing-graph-blurb')).toHaveTextContent(n.blurb);
+  });
+
+  it('fades the instructional copy once the visitor interacts', () => {
+    render(<KnowledgeGraphDemo />);
+    const copy = screen.getByTestId('landing-graph-copy');
+    expect(copy).toHaveAttribute('data-engaged', 'false');
+
+    fireEvent.mouseEnter(
+      screen.getByTestId(`landing-graph-node-${COURSE_GRAPHS[0].nodes[1].id}`),
+    );
+    expect(copy).toHaveAttribute('data-engaged', 'true');
+  });
+
+  it('keeps the copy faded across a course switch instead of resetting engagement', () => {
+    render(<KnowledgeGraphDemo />);
+    const copy = screen.getByTestId('landing-graph-copy');
+
+    fireEvent.mouseEnter(
+      screen.getByTestId(`landing-graph-node-${COURSE_GRAPHS[0].nodes[1].id}`),
+    );
+    expect(copy).toHaveAttribute('data-engaged', 'true');
+
+    // `AssemblingGraph` remounts (keyed by `graph.id`) on a course switch.
+    // `engaged` lives in the parent specifically so this remount can't wipe
+    // it — pin that here, not just at the component-boundary level.
+    const target = COURSE_GRAPHS[1];
+    fireEvent.click(screen.getByTestId(`landing-graph-chip-${target.id}`));
+
+    expect(copy).toHaveAttribute('data-engaged', 'true');
+  });
+});
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index f6eec696..f667679f 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -41,10 +41,14 @@ function AssemblingGraph({
   graph,
   points,
   parked,
+  onNodeEnter,
+  onNodeLeave,
 }: {
   graph: CourseGraph;
   points: Map<string, Point>;
   parked: boolean;
+  onNodeEnter: (id: string) => void;
+  onNodeLeave: () => void;
 }) {
   const [animatedProgress, setAnimatedProgress] = useState(0);
   // "Parked" means the assembly is skipped and the graph renders complete —
@@ -94,7 +98,13 @@ function AssemblingGraph({
         const h = helixEntry(p, { x: VIEW_W / 2, y: VIEW_H / 2 }, local);
         const r = nodeRadius(graph, n.id);
         return (
-          <g key={n.id} data-testid={`landing-graph-node-${n.id}`} opacity={h.opacity}>
+          <g
+            key={n.id}
+            data-testid={`landing-graph-node-${n.id}`}
+            opacity={h.opacity}
+            onMouseEnter={() => onNodeEnter(n.id)}
+            onMouseLeave={onNodeLeave}
+          >
             <circle cx={h.x} cy={h.y} r={r * h.scale} fill={TIER_COLOR[n.tier]} />
             <text
               x={h.x}
@@ -117,11 +127,39 @@ function AssemblingGraph({
 export default function KnowledgeGraphDemo() {
   const [courseId, setCourseId] = useState(COURSE_GRAPHS[0].id);
 
+  // Interaction state (#344 task 5). Both live here, in the parent, rather
+  // than inside `AssemblingGraph`: that child is keyed by `graph.id` and
+  // remounts on every course switch, which would silently wipe any state
+  // stored inside it. `engaged` in particular must survive a course switch
+  // (once a visitor has interacted, the instructional copy stays faded for
+  // the rest of the session) — that's only guaranteed by keeping it outside
+  // the subtree that remounts. `hovered` doesn't strictly need the same
+  // guarantee (a stale id from the previous course just fails the
+  // `graph.nodes.find` lookup below and renders no blurb), but the blurb
+  // paragraph itself is rendered here in the parent, as a sibling of the
+  // `<svg>`, so the parent needs read access to "which node is hovered"
+  // regardless. One state owner for both pieces of interaction state keeps
+  // `AssemblingGraph` a plain layout/animation renderer that only takes
+  // callback props, instead of splitting hover across two lifetimes for no
+  // behavioral gain.
+  const [hovered, setHovered] = useState<string | null>(null);
+  const [engaged, setEngaged] = useState(false);
+
+  function onNodeEnter(id: string) {
+    setHovered(id);
+    setEngaged(true);
+  }
+
+  function onNodeLeave() {
+    setHovered(null);
+  }
+
   const graph = useMemo(
     () => COURSE_GRAPHS.find((g) => g.id === courseId) ?? COURSE_GRAPHS[0],
     [courseId],
   );
   const points = useMemo(() => radialLayout(graph, VIEW_W, VIEW_H), [graph]);
+  const hoveredBlurb = hovered ? graph.nodes.find((n) => n.id === hovered)?.blurb : undefined;
 
   // `usePrefersReducedMotion` (not a direct `window.matchMedia` read in the
   // render body — #344 fix round 1) is hydration-safe: it renders the same
@@ -139,7 +177,12 @@ export default function KnowledgeGraphDemo() {
       className="landing-section landing-graph relative z-10 py-24 md:py-32"
     >
       <div className="max-w-7xl mx-auto px-6 lg:px-12">
-        <div data-testid="landing-graph-copy" className="landing-graph-copy">
+        <div
+          data-testid="landing-graph-copy"
+          data-engaged={engaged ? 'true' : 'false'}
+          className="landing-graph-copy"
+          style={{ opacity: engaged ? 0.35 : 1 }}
+        >
           <span className="font-jetbrains text-[0.7rem] tracking-[0.32em] text-[var(--brand-forest)] uppercase font-medium">
             Your knowledge, mapped
           </span>
@@ -172,8 +215,28 @@ export default function KnowledgeGraphDemo() {
           role="img"
           aria-label={`${graph.name} concept graph`}
         >
-          <AssemblingGraph key={graph.id} graph={graph} points={points} parked={parked} />
+          <AssemblingGraph
+            key={graph.id}
+            graph={graph}
+            points={points}
+            parked={parked}
+            onNodeEnter={onNodeEnter}
+            onNodeLeave={onNodeLeave}
+          />
         </svg>
+
+        {/*
+          Reserved min-height (#344 task 5): the blurb text appears and
+          disappears on every hover/unhover. Without a floor, the paragraph
+          collapsing to empty on mouseleave shifts anything rendered below
+          this section on every single hover — load-bearing, not cosmetic.
+        */}
+        <p
+          data-testid="landing-graph-blurb"
+          className="landing-graph-blurb font-inter text-[var(--text-dim)] mt-4 min-h-[1.5rem]"
+        >
+          {hoveredBlurb ?? ''}
+        </p>
       </div>
     </section>
   );

From d42d68b5bed100e4ff9916653adcfe3feaefcdf4 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 12:49:47 -0700
Subject: [PATCH 10/20] feat(landing): replace HowItWorks and the feature
 catalog with the graph demo (#344)

---
 frontend/src/app/(public)/page.tsx            | 116 +--
 frontend/src/app/globals.css                  |  27 -
 .../src/components/marketing/HowItWorks.tsx   | 677 ------------------
 3 files changed, 14 insertions(+), 806 deletions(-)
 delete mode 100644 frontend/src/components/marketing/HowItWorks.tsx

diff --git a/frontend/src/app/(public)/page.tsx b/frontend/src/app/(public)/page.tsx
index 513c7c94..f2457431 100644
--- a/frontend/src/app/(public)/page.tsx
+++ b/frontend/src/app/(public)/page.tsx
@@ -5,22 +5,21 @@ import dynamic from 'next/dynamic';
 import { useRouter } from 'next/navigation';
 import { useUser } from '@/context/UserContext';
 import { useScrollLock } from '@/lib/useScrollLock';
-import { Network, Sparkles, FilePlus2, Brain, CalendarClock, Users, PenSquare } from 'lucide-react';
+import { Users, PenSquare } from 'lucide-react';
 import SignInModal from '@/components/marketing/SignInModal';
 import { HeroCard } from '@/components/marketing/HeroCard';
 import { BRAND_FOREST } from '@/lib/brand';
 import { Button } from "@/components/ui";
 import { IS_TEST_MODE, random, now } from '@/lib/testMode';
 
-// HowItWorks statically imports framer-motion, which a plain import would ride
-// into the landing chunk. next/dynamic splits it into its own client chunk
-// while still server-rendering the section's marketing copy (#492 review:
-// ssr:false would drop it from the HTML crawlers see — the one page where
-// that matters). The placeholder mirrors the section's own 340vh scroll
-// height so layout below doesn't shift during client-side chunk loads.
-const HowItWorks = dynamic(() => import('@/components/marketing/HowItWorks'), {
-  loading: () => <section id="how-it-works" className="landing-section relative" style={{ height: '340vh' }} />,
-});
+const KnowledgeGraphDemo = dynamic(
+  () => import('@/components/marketing/graph/KnowledgeGraphDemo'),
+  {
+    // Placeholder height matches the section's resolved height so nothing
+    // below shifts while the chunk loads.
+    loading: () => <section id="knowledge-graph" className="landing-section relative" style={{ minHeight: '80vh' }} />,
+  },
+);
 
 const API_URL = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:5000';
 
@@ -90,9 +89,9 @@ export default function LandingPage() {
   // useScrollLock resolves to it.
   useScrollLock(betaModalOpen);
 
-  // Always start at the top of the landing page so Hero → Features → HowItWorks
-  // Step 1 → 2 → 3 plays in order. Without this, browser scroll restoration on
-  // reload / hot reload can drop the user mid-section where Step 2 is showing.
+  // Always start at the top of the landing page so the intro sequence plays
+  // in order. Without this, browser scroll restoration on reload / hot
+  // reload can drop the user mid-section past the hero.
   useEffect(() => {
     if (typeof window !== 'undefined' && 'scrollRestoration' in window.history) {
       window.history.scrollRestoration = 'manual';
@@ -566,99 +565,12 @@ export default function LandingPage() {
         </div>
       </section>
 
-      {/* ═══ Features Section ═══ */}
       <div>
-        <section id="features" className="landing-section relative py-32 md:py-40 z-10 overflow-hidden">
-          <div aria-hidden className="absolute inset-0 pointer-events-none z-0">
-            <div className="sapling-mesh-blob sapling-mesh-blob--3" style={{ top: '6%', left: '-10%', opacity: 0.32, width: '36vw', height: '36vw' }} />
-            <div className="sapling-mesh-blob sapling-mesh-blob--2" style={{ bottom: '10%', right: '-12%', opacity: 0.20, width: '32vw', height: '32vw' }} />
-          </div>
-          <div className="absolute top-0 left-0 w-full h-px landing-divider" />
-
-          <div className="max-w-7xl mx-auto px-6 lg:px-12 relative z-[1]">
-            {/* Editorial heading: asymmetric split, breathing room. */}
-            <div className="grid md:grid-cols-12 gap-8 md:gap-12 mb-20 md:mb-28 landing-fade-up">
-              <div className="md:col-span-7">
-                <span className="font-jetbrains text-[0.7rem] tracking-[0.32em] text-[var(--brand-forest)] uppercase font-medium">In the Sapling kit</span>
-                <h2 className="font-playfair text-5xl md:text-7xl font-semibold text-[var(--text)] mt-5 leading-[1.02] tracking-tight">
-                  Tools that bend to <em className="not-italic text-[var(--brand-forest)]">your study</em>, not the other way around.
-                </h2>
-              </div>
-              <div className="md:col-span-4 md:col-start-9 md:pt-8 flex flex-col justify-end">
-                <p className="font-inter text-[var(--text-dim)] text-base leading-relaxed font-light">
-                  Six instruments, tuned to one another. Each is a verb you reach for; together they make a quiet system that learns you back.
-                </p>
-                <div className="mt-6 flex items-center gap-3">
-                  <span className="block h-px w-12 bg-[var(--brand-forest)]" />
-                  <span className="font-jetbrains text-[0.65rem] tracking-[0.3em] text-[var(--text-dim)] uppercase">Scroll the catalog</span>
-                </div>
-              </div>
-            </div>
-
-            {/* Editorial feature catalog: hairline rows, no boxes. */}
-            <ol className="landing-feature-list border-t border-[var(--text-dim)]/15">
-              {[
-                { icon: Network,       title: 'Knowledge Graph',     desc: 'Every concept becomes a node in a living 3D network. Watch them glow as you master topics and see how everything connects.' },
-                { icon: Sparkles,      title: 'Adaptive Study Paths', desc: 'The AI reads your knowledge gaps and lays out the optimal sequence — so you always study the right thing at the right time.' },
-                { icon: FilePlus2,     title: 'Universal Upload',     desc: 'Drop in syllabi, textbooks, or notes. Sapling extracts every concept and maps it onto your graph automatically.' },
-                { icon: Brain,         title: 'Adaptive Quizzes',     desc: 'Questions that re-tune to your level in real time. They press where you are strong and meet you where you struggle.' },
-                { icon: CalendarClock, title: 'Spaced Repetition',    desc: 'Scientifically-timed reviews move concepts from short-term to long-term memory. Sapling handles the scheduling.' },
-                { icon: Users,         title: 'Live Study Rooms',     desc: 'Join classmates in shared rooms. Compare knowledge maps. Learn together, in real time, on the same canvas.' },
-              ].map((feature, i) => (
-                <li
-                  key={feature.title}
-                  className="landing-feature-row group relative border-b border-[var(--text-dim)]/15 landing-fade-up"
-                  style={{ transitionDelay: `${i * 70}ms` }}
-                >
-                  <div className="grid md:grid-cols-12 items-center gap-6 md:gap-8 py-9 md:py-12 px-2 md:px-4 transition-colors duration-500">
-                    {/* Index marker. */}
-                    <div className="md:col-span-1 font-jetbrains text-[0.7rem] tracking-[0.3em] text-[var(--text-dim)] transition-colors duration-500 group-hover:text-[var(--brand-forest)]">
-                      <span className="inline-block tabular-nums">0{i + 1}</span>
-                      <span className="hidden md:inline-block ml-3 align-middle h-px w-6 bg-[var(--text-dim)]/30 group-hover:bg-[var(--brand-forest)]/60 transition-colors duration-500" />
-                    </div>
-
-                    {/* Title with bare inline icon — no circle, no color. */}
-                    <div className="md:col-span-5 flex items-center gap-4 md:gap-5 min-w-0">
-                      <feature.icon
-                        aria-hidden
-                        className="landing-feature-icon shrink-0 w-5 h-5 md:w-6 md:h-6 text-[var(--text)] transition-transform duration-700 ease-out group-hover:scale-110 group-hover:-rotate-6"
-                        strokeWidth={1.5}
-                      />
-                      <h3 className="landing-feature-title font-playfair text-2xl md:text-3xl lg:text-4xl font-semibold text-[var(--text)] tracking-tight leading-[1.05]">
-                        {feature.title}
-                      </h3>
-                    </div>
-
-                    {/* Description: shifted left, generous width for body copy. */}
-                    <div className="md:col-span-6">
-                      <p className="font-inter text-[var(--text-dim)] text-[0.95rem] leading-relaxed font-light max-w-[52ch]">
-                        {feature.desc}
-                      </p>
-                    </div>
-                  </div>
-
-                  {/* Hover-driven underline sweep, brand green. */}
-                  <span
-                    aria-hidden
-                    className="landing-feature-underline pointer-events-none absolute left-0 bottom-0 h-[2px] w-0 bg-[var(--brand-forest)] group-hover:w-full transition-[width] duration-[900ms] ease-out"
-                  />
-                </li>
-              ))}
-            </ol>
-
-            {/* Tail mark: editorial closing rule. */}
-            <div className="mt-10 flex items-center gap-4 landing-fade-up">
-              <span className="block h-px flex-1 bg-[var(--text-dim)]/15" />
-              <span className="font-jetbrains text-[0.65rem] tracking-[0.32em] text-[var(--text-dim)] uppercase">— end of catalog</span>
-            </div>
-          </div>
-        </section>
-
-        <HowItWorks />
+        <KnowledgeGraphDemo />
 
         {/* ═══ Final CTA ═══ */}
         <section className="landing-section py-32 relative text-center z-10">
-          {/* Blend from HowItWorks' dark-green tint down to the mesh */}
+          {/* Soft green tint blending down into the mesh below */}
           <div
             aria-hidden
             className="pointer-events-none absolute left-0 right-0 z-0"
diff --git a/frontend/src/app/globals.css b/frontend/src/app/globals.css
index e43cfa8a..187a5e6c 100644
--- a/frontend/src/app/globals.css
+++ b/frontend/src/app/globals.css
@@ -976,33 +976,6 @@ input[type="reset"]:disabled {
 .modal-card-in      { animation: modal-card-in      300ms cubic-bezier(0.22,1,0.36,1) forwards; }
 .modal-card-out     { animation: modal-card-out     200ms cubic-bezier(0.4,0,1,1)     forwards; }
 
-/* ── Editorial feature rows (no boxes, hairline dividers, hover sweep) ── */
-.landing-page .landing-feature-row { transition: background-color 600ms ease, padding 500ms ease; }
-.landing-page .landing-feature-row > div { position: relative; z-index: 1; }
-.landing-page .landing-feature-row::before {
-  content: ""; position: absolute; inset: 0;
-  background: linear-gradient(90deg, rgba(27,108,66,0.07) 0%, transparent 70%);
-  opacity: 0; transition: opacity 600ms ease; pointer-events: none; z-index: 0;
-}
-.landing-page .landing-feature-row:hover::before { opacity: 1; }
-.landing-page .landing-feature-title {
-  transition: transform 700ms cubic-bezier(0.22,1,0.36,1), color 500ms ease, letter-spacing 700ms ease;
-  will-change: transform;
-}
-.landing-page .landing-feature-row:hover .landing-feature-title {
-  transform: translateX(8px);
-  color: var(--brand-forest);
-  letter-spacing: -0.012em;
-}
-@media (prefers-reduced-motion: reduce) {
-  .landing-page .landing-feature-row::before,
-  .landing-page .landing-feature-title,
-  .landing-page .landing-feature-icon,
-  .landing-page .landing-feature-underline { transition: none !important; }
-  .landing-page .landing-feature-row:hover .landing-feature-title { transform: none; }
-  .landing-page .landing-feature-row:hover .landing-feature-icon { transform: none; }
-}
-
 /* ── Knowledge graph demo (#344) ── */
 .landing-page .landing-graph-chip {
   font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
diff --git a/frontend/src/components/marketing/HowItWorks.tsx b/frontend/src/components/marketing/HowItWorks.tsx
deleted file mode 100644
index 2a7fdb67..00000000
--- a/frontend/src/components/marketing/HowItWorks.tsx
+++ /dev/null
@@ -1,677 +0,0 @@
-'use client';
-
-import { useEffect, useRef, useState } from 'react';
-import {
-  motion,
-  useScroll,
-  useTransform,
-  useMotionValueEvent,
-  MotionValue,
-  MotionGlobalConfig,
-} from 'framer-motion';
-import { BRAND_FOREST } from '@/lib/brand';
-import { IS_TEST_MODE } from '@/lib/testMode';
-
-// Deterministic DOM for browser tests (#383): framer-motion's own test
-// seam jumps every animation straight to its final keyframe. No-op in
-// production builds (flag inlined to false at build time).
-if (IS_TEST_MODE) MotionGlobalConfig.skipAnimations = true;
-
-// ─── Graph data (shared by step 2 & 3) ───────────────────────────────────────
-
-const NODES = [
-  { id: 0, x: 138, y: 78,  label: 'CS 210'    },
-  { id: 1, x: 205, y: 115, label: 'Arrays'    },
-  { id: 2, x: 268, y: 76,  label: 'Sorting'   },
-  { id: 3, x: 205, y: 58,  label: 'Loops'     },
-  { id: 4, x: 138, y: 148, label: 'Functions' },
-  { id: 5, x: 270, y: 152, label: 'Recursion' },
-  { id: 6, x: 165, y: 192, label: 'OOP'       },
-  { id: 7, x: 245, y: 196, label: 'Memory'    },
-  { id: 8, x: 318, y: 115, label: 'Big-O'     },
-];
-const EDGES: [number, number][] = [
-  [0,1],[1,2],[1,3],[0,4],[2,5],[1,5],[4,6],[5,7],[2,8],[6,7],[3,2],[4,1],
-];
-const MASTERY_ORDER = [0, 3, 1, 4, 2, 6]; // nodes that turn green, in order
-
-// ─── Sapling stages ───────────────────────────────────────────────────────────
-
-function SeedSVG({ active }: { active: boolean }) {
-  // Logo paths scaled 3× from 64×64 viewBox, base anchored to soil at y=215
-  // Transform: new_x = (old_x − 32) × 3 + 100,  new_y = (old_y − 54) × 3 + 215
-  return (
-    <svg viewBox="0 0 200 280" fill="none" className="w-full h-full">
-      {/* Soil — y=215 matches sprout & tree */}
-      <ellipse cx="100" cy="215" rx="72" ry="10" fill="#92683A" opacity="0.22" />
-      <rect x="28" y="215" width="144" height="48" rx="5" fill="#92683A" opacity="0.09" />
-      {/* Logo elements scaled to ~55% — anchor at soil (100,215) so base stays planted */}
-      <g style={{ transformOrigin: '100px 215px', transform: 'scale(0.55)' }}>
-        {/* Stem */}
-        <motion.path d="M100 215 L100 137"
-          stroke="var(--brand-forest)" strokeWidth="5" strokeLinecap="round"
-          initial={{ pathLength: 0 }}
-          animate={active ? { pathLength: 1 } : { pathLength: 0 }}
-          transition={{ duration: 0.55, ease: 'easeOut' }}
-        />
-        {/* Left leaf */}
-        <motion.path d="M100 167 C100 167 58 155 52 119 C52 119 94 113 100 167 Z"
-          fill="var(--brand-forest)"
-          initial={{ scale: 0 }} animate={active ? { scale: 1 } : { scale: 0 }}
-          transition={{ duration: 0.55, delay: 0.42, ease: [0.34, 1.56, 0.64, 1] }}
-          style={{ transformOrigin: '100px 167px' }}
-        />
-        {/* Right leaf */}
-        <motion.path d="M100 143 C100 143 142 125 154 89 C154 89 112 89 100 143 Z"
-          fill="#2d8a47"
-          initial={{ scale: 0 }} animate={active ? { scale: 1 } : { scale: 0 }}
-          transition={{ duration: 0.55, delay: 0.58, ease: [0.34, 1.56, 0.64, 1] }}
-          style={{ transformOrigin: '100px 143px' }}
-        />
-        {/* Tip bud */}
-        <motion.circle cx="100" cy="131" r="7" fill="var(--brand-forest)"
-          initial={{ scale: 0 }} animate={active ? { scale: 1 } : { scale: 0 }}
-          transition={{ duration: 0.38, delay: 0.32, ease: [0.34, 1.56, 0.64, 1] }}
-          style={{ transformOrigin: '100px 131px' }}
-        />
-      </g>
-    </svg>
-  );
-}
-
-function SproutSVG({ active }: { active: boolean }) {
-  return (
-    <svg viewBox="0 0 200 280" fill="none" className="w-full h-full">
-      {/* Soil — same y=215 as seed */}
-      <ellipse cx="100" cy="215" rx="72" ry="10" fill="#92683A" opacity="0.22" />
-      <rect x="28" y="215" width="144" height="55" rx="5" fill="#92683A" opacity="0.09" />
-      {/* Roots */}
-      {[
-        { d: 'M100 218 Q82 232 72 248', delay: 0 },
-        { d: 'M100 218 Q118 233 126 252', delay: 0.2 },
-        { d: 'M100 220 Q98 236 91 252', delay: 0.4 },
-      ].map((r, i) => (
-        <motion.path key={i} d={r.d}
-          stroke="#92683A" strokeWidth={i === 2 ? 1.5 : 2} strokeLinecap="round"
-          opacity={i === 2 ? 0.35 : 0.55}
-          initial={{ pathLength: 0 }}
-          animate={active ? { pathLength: 1 } : { pathLength: 0 }}
-          transition={{ duration: 0.7, delay: r.delay, ease: 'easeOut' }}
-        />
-      ))}
-      {/* Stem */}
-      <motion.path d="M100 215 L100 138"
-        stroke="var(--brand-forest)" strokeWidth="3.5" strokeLinecap="round"
-        initial={{ pathLength: 0 }}
-        animate={active ? { pathLength: 1 } : { pathLength: 0 }}
-        transition={{ duration: 0.6, ease: 'easeOut' }}
-      />
-      {/* Left leaf */}
-      <motion.path d="M100 163 Q73 148 70 126 Q89 132 100 163"
-        fill="var(--brand-forest)" opacity="0.9"
-        initial={{ scale: 0 }} animate={active ? { scale: 1 } : { scale: 0 }}
-        transition={{ duration: 0.55, delay: 0.5, ease: [0.34, 1.56, 0.64, 1] }}
-        style={{ transformOrigin: '100px 163px' }}
-      />
-      {/* Right leaf */}
-      <motion.path d="M100 152 Q127 136 130 114 Q111 122 100 152"
-        opacity="0.9"
-        initial={{ scale: 0 }} animate={active ? { scale: 1 } : { scale: 0 }}
-        transition={{ duration: 0.55, delay: 0.65, ease: [0.34, 1.56, 0.64, 1] }}
-        style={{ fill: 'var(--brand-forest-bright)', transformOrigin: '100px 152px' }}
-      />
-      {/* Tip bud */}
-      <motion.circle cx="100" cy="136" r="5.5" fill="#3BAF6C"
-        initial={{ scale: 0 }} animate={active ? { scale: 1 } : { scale: 0 }}
-        transition={{ duration: 0.4, delay: 0.4, ease: [0.34, 1.56, 0.64, 1] }}
-        style={{ transformOrigin: '100px 136px' }}
-      />
-    </svg>
-  );
-}
-
-function TreeSVG({ active }: { active: boolean }) {
-  const roots = [
-    { d: 'M340 358 L340 405 Q338 415 332 425',            sw: 2.5, delay: 0    },
-    { d: 'M340 358 Q325 380 305 402 Q295 406 285 404',    sw: 2,   delay: 0.12 },
-    { d: 'M340 358 Q355 380 375 402 Q385 406 395 403',    sw: 2,   delay: 0.14 },
-    { d: 'M340 358 Q332 382 322 405',                     sw: 1.5, delay: 0.24 },
-    { d: 'M340 358 Q348 382 358 404',                     sw: 1.5, delay: 0.26 },
-  ];
-
-  const stemAndBranches = [
-    { d: 'M338 358 Q337 330 337 300 Q338 270 340 240 Q341 220 342 205', sw: 4.5, delay: 0.1,  color: '#5a3e28' },
-    { d: 'M337 310 Q322 300 310 297',  sw: 2.5, delay: 0.38, color: '#5a3e28' },
-    { d: 'M339 275 Q355 265 368 262',  sw: 2.5, delay: 0.44, color: '#5a3e28' },
-    { d: 'M340 245 Q328 236 318 232',  sw: 2,   delay: 0.50, color: '#5a3e28' },
-  ];
-
-  const leaves: { cx: number; cy: number; rx: number; ry: number; rot: number; c: string; delay: number }[] = [
-    { cx: 342, cy: 185, rx: 12, ry: 20, rot: 0,   c: '#3a8060', delay: 0.62 },
-    { cx: 328, cy: 198, rx: 11, ry: 18, rot: -30, c: '#2d6b4f', delay: 0.66 },
-    { cx: 356, cy: 198, rx: 11, ry: 18, rot: 30,  c: '#4a9470', delay: 0.66 },
-    { cx: 308, cy: 226, rx: 10, ry: 17, rot: -40, c: '#3a8060', delay: 0.70 },
-    { cx: 318, cy: 238, rx:  9, ry: 15, rot: 20,  c: '#2d6b4f', delay: 0.72 },
-    { cx: 378, cy: 255, rx: 11, ry: 18, rot: 35,  c: '#3a8060', delay: 0.70 },
-    { cx: 365, cy: 268, rx:  9, ry: 15, rot: -15, c: '#4a9470', delay: 0.73 },
-    { cx: 375, cy: 248, rx: 10, ry: 16, rot: 60,  c: '#2d6b4f', delay: 0.74 },
-    { cx: 300, cy: 290, rx: 11, ry: 18, rot: -35, c: '#3a8060', delay: 0.74 },
-    { cx: 312, cy: 302, rx:  9, ry: 15, rot: 15,  c: '#4a9470', delay: 0.77 },
-    { cx: 296, cy: 300, rx: 10, ry: 16, rot: -55, c: '#2d6b4f', delay: 0.78 },
-  ];
-
-  // Anchor soil at (100,215) matching SeedSVG/SproutSVG — user SVG soil top is at y=362, center x=340
-  const treeTransform = 'translate(100,215) scale(0.72,0.55) translate(-340,-362)';
-
-  return (
-    <svg viewBox="0 0 200 280" fill="none" className="w-full h-full">
-      {/* Soil — identical to SeedSVG & SproutSVG */}
-      <ellipse cx="100" cy="215" rx="72" ry="10" fill="#92683A" opacity="0.22" />
-      <rect x="28" y="215" width="144" height="48" rx="5" fill="#92683A" opacity="0.09" />
-
-      <g transform={treeTransform}>
-        {/* Roots */}
-        {roots.map((r, i) => (
-          <motion.path key={i} d={r.d}
-            stroke="#9e8a70" strokeWidth={r.sw} strokeLinecap="round" fill="none"
-            initial={{ pathLength: 0 }} animate={active ? { pathLength: 1 } : { pathLength: 0 }}
-            transition={{ duration: 0.5, delay: r.delay, ease: 'easeOut' }}
-          />
-        ))}
-
-        {/* Stem + branches */}
-        {stemAndBranches.map((s, i) => (
-          <motion.path key={i} d={s.d}
-            stroke={s.color} strokeWidth={s.sw} strokeLinecap="round" fill="none"
-            initial={{ pathLength: 0 }} animate={active ? { pathLength: 1 } : { pathLength: 0 }}
-            transition={{ duration: 0.5, delay: s.delay, ease: 'easeOut' }}
-          />
-        ))}
-
-        {/* Leaves */}
-        {leaves.map((l, i) => (
-          <motion.ellipse key={i}
-            cx={l.cx} cy={l.cy} rx={l.rx} ry={l.ry}
-            fill={l.c}
-            transform={`rotate(${l.rot} ${l.cx} ${l.cy})`}
-            initial={{ scale: 0 }} animate={active ? { scale: 1 } : { scale: 0 }}
-            transition={{ duration: 0.4, delay: l.delay, ease: [0.34, 1.56, 0.64, 1] }}
-            style={{ transformOrigin: `${l.cx}px ${l.cy}px` }}
-          />
-        ))}
-
-        {/* Top bud */}
-        <motion.circle cx="342" cy="168" r="4" fill="#3a8060"
-          initial={{ scale: 0 }} animate={active ? { scale: 1 } : { scale: 0 }}
-          transition={{ duration: 0.35, delay: 0.60, ease: [0.34, 1.56, 0.64, 1] }}
-          style={{ transformOrigin: '342px 168px' }}
-        />
-      </g>
-    </svg>
-  );
-}
-
-// ─── App window chrome ────────────────────────────────────────────────────────
-
-function AppWindow({ children }: { children: React.ReactNode }) {
-  return (
-    <div
-      className="relative w-full rounded-2xl overflow-hidden shadow-2xl border border-black/8"
-      style={{ background: 'var(--bg-panel, #f8fbf8)', aspectRatio: '4/2.8' }}
-    >
-      {/* Title bar */}
-      <div className="flex items-center gap-1.5 px-4 h-10 border-b border-black/6"
-        style={{ background: 'rgba(255,255,255,0.7)' }}>
-        <div className="w-3 h-3 rounded-full bg-[#FF5F57]" />
-        <div className="w-3 h-3 rounded-full bg-[#FEBC2E]" />
-        <div className="w-3 h-3 rounded-full bg-[#28C840]" />
-        <div className="flex-1 mx-4 rounded-full h-5 flex items-center px-3"
-          style={{ background: 'rgba(0,0,0,0.05)' }}>
-          <span className="text-[10px] opacity-50 font-jetbrains" style={{ color: 'var(--text-dim)' }}>
-            saplinglearn.com
-          </span>
-        </div>
-      </div>
-      {/* Content */}
-      <div className="relative" style={{ height: 'calc(100% - 40px)' }}>
-        {children}
-      </div>
-    </div>
-  );
-}
-
-// ─── App screen: Step 1 ───────────────────────────────────────────────────────
-
-const COURSE_CHIPS = ['CS 210', 'MA 242', 'SM 275'];
-
-function Step1Content({ active }: { active: boolean }) {
-  return (
-    <div className="h-full flex flex-col items-center justify-center px-8 gap-3">
-      {/* Google button */}
-      <motion.div
-        className="w-full max-w-[230px] bg-white rounded-xl py-2.5 flex items-center justify-center gap-2.5 shadow-sm text-sm font-medium overflow-hidden relative"
-        style={{ border: '1px solid rgba(0,0,0,0.1)', color: 'var(--text)' }}
-        initial={{ opacity: 0, y: 12 }}
-        animate={active ? { opacity: 1, y: 0 } : { opacity: 0, y: 12 }}
-        transition={{ duration: 0.4, delay: 0.1 }}
-      >
-        {/* Shimmer sweep */}
-        <motion.div
-          className="absolute inset-0 bg-gradient-to-r from-transparent via-white/60 to-transparent -translate-x-full"
-          animate={active ? { translateX: ['−100%', '200%'] } : {}}
-          transition={{ duration: 0.9, delay: 0.5 }}
-        />
-        <svg className="w-3.5 h-3.5 flex-shrink-0" viewBox="0 0 24 24">
-          <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z" fill="#4285F4"/>
-          <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" fill="#34A853"/>
-          <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z" fill="#FBBC05"/>
-          <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" fill="#EA4335"/>
-        </svg>
-        Continue with Google
-      </motion.div>
-
-      {/* School & year */}
-      {(['🎓 Boston University', '📅 Sophomore'] as const).map((label, i) => (
-        <motion.div key={label}
-          className="w-full max-w-[230px] rounded-xl px-3 py-2 text-xs"
-          style={{ background: 'rgba(0,0,0,0.04)', border: '1px solid rgba(0,0,0,0.07)', color: 'var(--text-dim)' }}
-          initial={{ opacity: 0, y: 10 }}
-          animate={active ? { opacity: 1, y: 0 } : { opacity: 0, y: 10 }}
-          transition={{ duration: 0.35, delay: 0.28 + i * 0.14 }}
-        >
-          {label}
-        </motion.div>
-      ))}
-
-      {/* Course chips */}
-      <div className="flex flex-wrap gap-2 justify-center max-w-[230px]">
-        {COURSE_CHIPS.map((chip, i) => (
-          <motion.div key={chip}
-            className="rounded-full px-3 py-1 text-xs font-medium flex items-center gap-1.5"
-            style={{ background: 'rgba(27,108,66,0.1)', color: 'var(--brand-forest)' }}
-            initial={{ scale: 0, opacity: 0 }}
-            animate={active ? { scale: 1, opacity: 1 } : { scale: 0, opacity: 0 }}
-            transition={{ duration: 0.38, delay: 0.58 + i * 0.14, ease: [0.34, 1.56, 0.64, 1] }}
-          >
-            <svg className="w-3 h-3" viewBox="0 0 12 12">
-              <motion.path d="M2 6 L5 9 L10 3"
-                stroke="var(--brand-forest)" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" fill="none"
-                initial={{ pathLength: 0 }}
-                animate={active ? { pathLength: 1 } : { pathLength: 0 }}
-                transition={{ duration: 0.28, delay: 0.72 + i * 0.14 }}
-              />
-            </svg>
-            {chip}
-          </motion.div>
-        ))}
-      </div>
-    </div>
-  );
-}
-
-// ─── App screen: Step 2 ───────────────────────────────────────────────────────
-
-function Step2Content({ active, showGraph }: { active: boolean; showGraph: boolean }) {
-  return (
-    <div className="h-full relative">
-      {/* Upload dropzone — fades out once graph is ready */}
-      <motion.div
-        className="absolute inset-0 flex items-center justify-center"
-        initial={{ opacity: 1 }}
-        animate={active && !showGraph ? { opacity: 1 } : { opacity: 0 }}
-        transition={{ duration: 0.4 }}
-      >
-        <motion.div
-          className="w-[192px] h-[128px] rounded-2xl flex flex-col items-center justify-center gap-3"
-          style={{ border: '2px dashed rgba(27,108,66,0.3)', background: 'rgba(27,108,66,0.03)' }}
-          animate={active ? {
-            borderColor: ['rgba(27,108,66,0.3)', 'rgba(27,108,66,0.55)', 'rgba(27,108,66,0.3)'],
-          } : {}}
-          transition={{ duration: 2.2, repeat: Infinity, delay: 0.4 }}
-        >
-          {/* PDF icon drops in */}
-          <motion.div
-            initial={{ y: -24, opacity: 0 }}
-            animate={active ? { y: 0, opacity: 1 } : { y: -24, opacity: 0 }}
-            transition={{ duration: 0.5, delay: 0.25, ease: [0.34, 1.56, 0.64, 1] }}
-          >
-            <svg className="w-9 h-9" viewBox="0 0 36 36" fill="none">
-              <rect x="4" y="2" width="22" height="30" rx="3.5" fill="#EF4444" opacity="0.92" />
-              <path d="M22 2 L26 8 L22 8 Z" fill="#B91C1C" />
-              <rect x="4" y="14" width="22" height="18" rx="0" fill="#DC2626" opacity="0.18" />
-              <text x="15" y="24" textAnchor="middle" fill="white" fontSize="8" fontWeight="bold" fontFamily="monospace">PDF</text>
-            </svg>
-          </motion.div>
-
-          <span className="text-[10px] font-jetbrains" style={{ color: 'var(--text-dim)' }}>syllabus.pdf</span>
-
-          {/* Progress ring */}
-          <svg viewBox="0 0 28 28" className="w-7 h-7 -rotate-90">
-            <circle cx="14" cy="14" r="10" fill="none" stroke="var(--brand-forest)" strokeOpacity="0.15" strokeWidth="2.5" />
-            <motion.circle cx="14" cy="14" r="10" fill="none" stroke="var(--brand-forest)" strokeWidth="2.5"
-              strokeLinecap="round"
-              strokeDasharray={62.8}
-              initial={{ strokeDashoffset: 62.8 }}
-              animate={active ? { strokeDashoffset: 0 } : { strokeDashoffset: 62.8 }}
-              transition={{ duration: 1.3, delay: 0.55, ease: 'easeInOut' }}
-            />
-          </svg>
-        </motion.div>
-      </motion.div>
-
-      {/* Graph — only appears after user scrolls deeper into step 2 */}
-      <motion.div
-        className="absolute inset-0"
-        initial={{ opacity: 0 }}
-        animate={showGraph ? { opacity: 1 } : { opacity: 0 }}
-        transition={{ duration: 0.5 }}
-      >
-        <svg viewBox="88 42 252 168" className="w-full h-full">
-          {EDGES.map(([a, b], i) => {
-            const na = NODES[a], nb = NODES[b];
-            return (
-              <motion.path key={i}
-                d={`M ${na.x} ${na.y} L ${nb.x} ${nb.y}`}
-                stroke="var(--brand-forest)" strokeOpacity="0.22" strokeWidth="1.2"
-                initial={{ pathLength: 0 }}
-                animate={showGraph ? { pathLength: 1 } : { pathLength: 0 }}
-                transition={{ duration: 0.4, delay: 0.15 + i * 0.07 }}
-              />
-            );
-          })}
-          {NODES.map((n, i) => (
-            <g key={i}>
-              <motion.circle cx={n.x} cy={n.y} r={12.5}
-                fill="var(--brand-forest)" fillOpacity="0.07"
-                stroke="var(--brand-forest)" strokeOpacity="0.28" strokeWidth="1.3"
-                initial={{ scale: 0 }}
-                animate={showGraph ? { scale: 1 } : { scale: 0 }}
-                transition={{ duration: 0.38, delay: 0.25 + i * 0.07, ease: [0.34, 1.56, 0.64, 1] }}
-                style={{ transformOrigin: `${n.x}px ${n.y}px` }}
-              />
-              <motion.text x={n.x} y={n.y + 1}
-                textAnchor="middle" dominantBaseline="middle"
-                fontSize="5.5" fill="var(--brand-forest)" fontFamily="monospace"
-                initial={{ opacity: 0 }}
-                animate={showGraph ? { opacity: 0.75 } : { opacity: 0 }}
-                transition={{ duration: 0.3, delay: 0.45 + i * 0.07 }}
-              >
-                {n.label}
-              </motion.text>
-            </g>
-          ))}
-        </svg>
-      </motion.div>
-    </div>
-  );
-}
-
-// ─── App screen: Step 3 ───────────────────────────────────────────────────────
-
-function Step3Content({ active }: { active: boolean }) {
-  return (
-    <div className="h-full relative">
-      <div className="absolute inset-0 scale-[0.72] origin-center">
-      <svg viewBox="88 42 252 168" className="absolute inset-0 w-full h-full">
-        {/* Edges */}
-        {EDGES.map(([a, b], i) => {
-          const na = NODES[a], nb = NODES[b];
-          return (
-            <path key={i} d={`M ${na.x} ${na.y} L ${nb.x} ${nb.y}`}
-              stroke="var(--brand-forest)" strokeOpacity="0.18" strokeWidth="1.2"
-            />
-          );
-        })}
-        {/* Nodes */}
-        {NODES.map((n, i) => {
-          const masteryIdx = MASTERY_ORDER.indexOf(i);
-          const willMaster = masteryIdx !== -1;
-          return (
-            <g key={i}>
-              {/* Ripple burst on mastery */}
-              {willMaster && (
-                <motion.circle cx={n.x} cy={n.y} r={14}
-                  fill="none" stroke="var(--brand-forest)" strokeWidth="1"
-                  initial={{ scale: 0, opacity: 0 }}
-                  animate={active ? { scale: [0, 2.2, 0], opacity: [0.7, 0.3, 0] } : { scale: 0, opacity: 0 }}
-                  transition={{ duration: 0.65, delay: 0.35 + masteryIdx * 0.22 }}
-                  style={{ transformOrigin: `${n.x}px ${n.y}px` }}
-                />
-              )}
-              <motion.circle cx={n.x} cy={n.y} r={13}
-                stroke={willMaster ? 'var(--brand-forest)' : '#9CA3AF'}
-                strokeWidth="1.4"
-                initial={{ fill: '#9CA3AF', fillOpacity: 0.08, strokeOpacity: 0.22 }}
-                animate={active && willMaster ? {
-                  fill: BRAND_FOREST,
-                  fillOpacity: [0.08, 0.3, 0.14],
-                  strokeOpacity: 0.55,
-                } : {}}
-                transition={{ duration: 0.5, delay: 0.3 + masteryIdx * 0.22 }}
-              />
-              <text x={n.x} y={n.y + 1}
-                textAnchor="middle" dominantBaseline="middle"
-                fontSize="5.5" fontFamily="monospace"
-                fill={willMaster ? 'var(--brand-forest)' : '#9CA3AF'}
-                opacity={0.85}
-              >
-                {n.label}
-              </text>
-            </g>
-          );
-        })}
-      </svg>
-      </div>
-
-      {/* Quiz card */}
-      <motion.div
-        className="absolute bottom-4 right-4 w-36 rounded-xl shadow-lg p-3"
-        style={{ background: 'var(--bg-panel, #f8fbf8)', border: '1px solid rgba(27,108,66,0.14)' }}
-        initial={{ x: 56, opacity: 0 }}
-        animate={active ? { x: 0, opacity: 1 } : { x: 56, opacity: 0 }}
-        transition={{ duration: 0.55, delay: 1.6, ease: [0.34, 1.56, 0.64, 1] }}
-      >
-        <p className="text-[9px] leading-snug mb-2.5" style={{ color: 'var(--text-dim)' }}>
-          Time complexity of binary search?
-        </p>
-        <div className="flex flex-col gap-1">
-          {['O(n)', 'O(log n)', 'O(n²)'].map((opt, i) => (
-            <div key={opt}
-              className="rounded-lg px-2 py-1 text-[9px] font-medium"
-              style={i === 1
-                ? { background: 'rgba(27,108,66,0.12)', color: 'var(--brand-forest)' }
-                : { background: 'rgba(0,0,0,0.04)', color: 'var(--text-dim)' }
-              }
-            >
-              {i === 1 && '✓ '}{opt}
-            </div>
-          ))}
-        </div>
-      </motion.div>
-    </div>
-  );
-}
-
-// ─── Step indicator (vertical) ────────────────────────────────────────────────
-
-function StepIndicator({ scrollYProgress, activeStep }: {
-  scrollYProgress: MotionValue<number>;
-  activeStep: number;
-}) {
-  const bar1H = useTransform(scrollYProgress, [0, 0.36], ['0%', '100%']);
-  const bar2H = useTransform(scrollYProgress, [0.36, 0.70], ['0%', '100%']);
-
-  return (
-    <div className="absolute top-1/2 -translate-y-1/2 flex flex-col items-center z-20 hidden sm:flex" style={{ right: 'clamp(1rem, 2vw, 2rem)', gap: 'clamp(0.375rem, 0.6vw, 0.5rem)' }}>
-      {[1, 2, 3].map((s, i) => (
-        <div key={s} className="flex flex-col items-center" style={{ gap: 'clamp(0.375rem, 0.6vw, 0.5rem)' }}>
-          <motion.div
-            className="rounded-full"
-            style={{ width: 'clamp(0.4rem, 0.6vw, 0.5rem)', height: 'clamp(0.4rem, 0.6vw, 0.5rem)', background: activeStep >= s ? 'var(--brand-forest)' : 'rgba(156,163,175,0.4)' }}
-            animate={{ scale: activeStep === s ? 1.4 : 1 }}
-            transition={{ duration: 0.3 }}
-          />
-          {i < 2 && (
-            <div className="w-px overflow-hidden" style={{ height: 'clamp(1.5rem, 3vh, 2.25rem)', background: 'rgba(156,163,175,0.2)' }}>
-              <motion.div className="w-full" style={{
-                height: i === 0 ? bar1H : bar2H,
-                background: 'var(--brand-forest)',
-              }} />
-            </div>
-          )}
-        </div>
-      ))}
-    </div>
-  );
-}
-
-// ─── Main export ──────────────────────────────────────────────────────────────
-
-const STEPS = [
-  {
-    num: '01',
-    title: 'Sign Up & Add Courses',
-    desc: 'Connect with Google in one click. Tell us your school and year. Add your classes. Takes 30 seconds.',
-  },
-  {
-    num: '02',
-    title: 'Upload Your Materials',
-    desc: 'Drop in a syllabus, textbook PDF, or lecture notes. Our AI reads everything, extracts concepts, and builds your knowledge map instantly.',
-  },
-  {
-    num: '03',
-    title: 'Start Growing',
-    desc: 'Follow your personalized learning path. Take adaptive quizzes. Watch your knowledge graph come alive, node by node turning green.',
-  },
-];
-
-// Sequential scroll windows. Each step is only visible in exactly one range,
-// and adjacent ranges share their endpoint so there's never a frame where two
-// steps have opacity > 0.
-const TEXT_RANGES = [
-  // Step 1: visible from 0 → 0.30, fade out 0.30 → 0.36
-  { in: [0, 0.30, 0.36, 1], yIn: [0, 0, -30, -30], opacityIn: [1, 1, 0, 0] },
-  // Step 2: fade in 0.36 → 0.42, visible, fade out 0.64 → 0.70
-  { in: [0.36, 0.42, 0.64, 0.70], yIn: [30, 0, 0, -30], opacityIn: [0, 1, 1, 0] },
-  // Step 3: fade in 0.70 → 0.76, visible to end
-  { in: [0, 0.70, 0.76, 1], yIn: [30, 30, 0, 0], opacityIn: [0, 0, 1, 1] },
-];
-
-const BG_COLORS = [
-  'rgba(0,0,0,0)',
-  'rgba(120,53,15,0.035)',
-  'rgba(20,83,45,0.05)',
-  'rgba(20,83,45,0.08)',
-];
-
-export default function HowItWorks() {
-  const containerRef = useRef<HTMLElement>(null);
-  const { scrollYProgress } = useScroll({
-    target: containerRef,
-    offset: ['start start', 'end end'],
-  });
-
-  const [activeStep, setActiveStep] = useState(1);
-  const [showStep2Graph, setShowStep2Graph] = useState(false);
-  useMotionValueEvent(scrollYProgress, 'change', (v) => {
-    setActiveStep(v < 0.36 ? 1 : v < 0.70 ? 2 : 3);
-    setShowStep2Graph(v > 0.55);
-  });
-
-  // Sync state with current scroll on mount. useMotionValueEvent only fires on
-  // *change*, so if the page mounts with a non-zero scroll (hot reload, scroll
-  // restoration, deep link), activeStep would be stuck at useState(1) while the
-  // text opacities reflect the real scroll. That desync is what made the
-  // section look like it "starts at step 2."
-  useEffect(() => {
-    const v = scrollYProgress.get();
-    setActiveStep(v < 0.36 ? 1 : v < 0.70 ? 2 : 3);
-    setShowStep2Graph(v > 0.55);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  // Text
-  const textOpacities = TEXT_RANGES.map(r => useTransform(scrollYProgress, r.in, r.opacityIn)); // eslint-disable-line react-hooks/rules-of-hooks
-  const textYs = TEXT_RANGES.map(r => useTransform(scrollYProgress, r.in, r.yIn)); // eslint-disable-line react-hooks/rules-of-hooks
-
-  const panelOpacity = useTransform(scrollYProgress, [0, 0.001, 0.82, 1], [1, 1, 1, 0]);
-
-  // Background
-  const bgColor = useTransform(scrollYProgress, [0, 0.36, 0.70, 1], BG_COLORS);
-
-  const SaplingComponents = [SeedSVG, SproutSVG, TreeSVG];
-
-  return (
-    <section ref={containerRef} id="how-it-works" className="landing-section relative" style={{ height: '340vh', position: 'relative' }}>
-      <motion.div className="sticky top-0 h-screen w-full overflow-hidden" style={{ backgroundColor: bgColor }}>
-        <div className="h-full max-w-[1600px] mx-auto flex flex-col lg:flex-row items-center" style={{ padding: 'clamp(1rem, 4vh, 2.5rem) clamp(1.25rem, 4vw, 4.5rem)', gap: 'clamp(2rem, 5vw, 8rem)' }}>
-
-          {/* ── Left: Sapling + text ──────────────────────────────────── */}
-          <div className="flex-1 flex flex-col items-center lg:items-start justify-center h-full" style={{ paddingBlock: 'clamp(1rem, 2vh, 0px)' }}>
-            {/* Sapling illustration */}
-            <motion.div className="relative flex-shrink-0" style={{ width: 'clamp(12rem, 18vw, 16rem)', height: 'clamp(15rem, 24vw, 20rem)', marginBottom: 'clamp(2rem, 4vh, 3.75rem)', opacity: panelOpacity }}>
-              {SaplingComponents.map((SVG, i) => (
-                <motion.div key={i} className="absolute inset-0"
-                  animate={{ opacity: activeStep === i + 1 ? 1 : 0 }}
-                  transition={{ duration: 0.35 }}
-                >
-                  <SVG active={activeStep === i + 1} />
-                </motion.div>
-              ))}
-            </motion.div>
-
-            {/* Step text layers */}
-            <div className="relative w-full" style={{ maxWidth: 'clamp(20rem, 45vw, 42rem)', minHeight: 'clamp(10rem, 18vh, 15rem)' }}>
-              {STEPS.map((step, i) => (
-                <motion.div
-                  key={i}
-                  className="absolute inset-x-0 top-0 text-center lg:text-left"
-                  style={{ opacity: textOpacities[i], y: textYs[i] }}
-                >
-                  <span className="font-jetbrains tracking-[0.3em] text-[var(--brand-forest)] uppercase block font-medium" style={{ fontSize: 'clamp(0.75rem, 1.1vw, 0.9375rem)', marginBottom: 'clamp(0.5rem, 1.2vh, 0.9375rem)' }}>
-                    Step {step.num}
-                  </span>
-                  <h3 className="font-playfair font-semibold tracking-tight leading-tight"
-                    style={{ color: 'var(--text)', fontSize: 'clamp(1.75rem, 3.5vw, 2.8125rem)', marginBottom: 'clamp(0.75rem, 1.5vh, 1.25rem)' }}>
-                    {step.title}
-                  </h3>
-                  <p className="font-inter leading-relaxed font-light"
-                    style={{ color: 'var(--text-dim)', fontSize: 'clamp(0.9375rem, 1.4vw, 1.25rem)' }}>
-                    {step.desc}
-                  </p>
-                </motion.div>
-              ))}
-            </div>
-          </div>
-
-          {/* ── Right: App window ─────────────────────────────────────── */}
-          <motion.div className="flex-[1.68] w-full max-w-2xl lg:max-w-none flex-shrink-0" style={{ opacity: panelOpacity }}>
-            <AppWindow>
-              {([
-                <Step1Content key={0} active={activeStep === 1} />,
-                <Step2Content key={1} active={activeStep === 2} showGraph={showStep2Graph} />,
-                <Step3Content key={2} active={activeStep === 3} />,
-              ] as const).map((el, i) => (
-                <motion.div key={i} className="absolute inset-0"
-                  animate={{ opacity: activeStep === i + 1 ? 1 : 0 }}
-                  transition={{ duration: 0.35 }}
-                >
-                  <motion.div
-                    className="h-full origin-center"
-                    animate={{ scale: i === 0 ? 1.18 : i === 1 ? (showStep2Graph ? 0.72 : 1.18) : 1 }}
-                    transition={{ duration: 0.4 }}
-                  >
-                    {el}
-                  </motion.div>
-                </motion.div>
-              ))}
-            </AppWindow>
-          </motion.div>
-        </div>
-
-        {/* Step indicator */}
-        <StepIndicator scrollYProgress={scrollYProgress} activeStep={activeStep} />
-      </motion.div>
-    </section>
-  );
-}

From bb8ca16e4f294c9ee9b9ee72ddd30fc8d0990798 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 12:56:20 -0700
Subject: [PATCH 11/20] test(e2e): journey for the landing knowledge graph
 (#344)

---
 frontend/e2e/landing-graph.spec.ts | 53 ++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 frontend/e2e/landing-graph.spec.ts

diff --git a/frontend/e2e/landing-graph.spec.ts b/frontend/e2e/landing-graph.spec.ts
new file mode 100644
index 00000000..4314c7cb
--- /dev/null
+++ b/frontend/e2e/landing-graph.spec.ts
@@ -0,0 +1,53 @@
+/**
+ * Journey — the landing page's interactive knowledge graph (#344).
+ *
+ * The graph is the page's whole argument, so this pins that it renders, that
+ * picking a course swaps it, and that engaging with it recedes the
+ * instructional copy. Test mode (NEXT_PUBLIC_TEST_MODE=1, baked into the
+ * Playwright profile build) parks the helical assembly animation, so every
+ * assertion below runs against the fully laid-out frame — no waiting on
+ * requestAnimationFrame.
+ *
+ * Selectors: testids from the component
+ * (src/components/marketing/graph/KnowledgeGraphDemo.tsx) — `landing-graph`
+ * for the section, `landing-graph-chip-<courseId>` for the course picker,
+ * `landing-graph-node-<nodeId>` for graph nodes, `landing-graph-copy` for the
+ * instructional heading block, `landing-graph-blurb` for the hover blurb.
+ * Course/node ids and the `ma-vectors` blurb text are seeded fixture data
+ * (src/components/marketing/graph/courseGraphs.ts) — `cs210` is the default
+ * (first) course, `ma242` the second. `AssemblingGraph` is keyed by
+ * `graph.id`, so switching courses remounts it and the previous course's
+ * node elements leave the DOM entirely — asserted below via `toHaveCount(0)`
+ * rather than a visibility check.
+ */
+import { expect, test } from './support/fixtures';
+
+test('landing graph renders, swaps by course, and fades its copy on engagement', async ({ page }) => {
+  await page.goto('/');
+
+  const section = page.getByTestId('landing-graph');
+  await section.scrollIntoViewIfNeeded();
+  await expect(section).toBeVisible();
+
+  // Parked frame: the first course's root node is laid out and visible.
+  await expect(page.getByTestId('landing-graph-node-cs-root')).toBeVisible();
+
+  // Picking another course swaps the graph.
+  await page.getByTestId('landing-graph-chip-ma242').click();
+  await expect(page.getByTestId('landing-graph-node-ma-root')).toBeVisible();
+  await expect(page.getByTestId('landing-graph-node-cs-root')).toHaveCount(0);
+
+  // Engaging recedes the copy.
+  const copy = page.getByTestId('landing-graph-copy');
+  await expect(copy).toHaveAttribute('data-engaged', 'false');
+  await page.getByTestId('landing-graph-node-ma-vectors').hover();
+  await expect(copy).toHaveAttribute('data-engaged', 'true');
+  await expect(page.getByTestId('landing-graph-blurb')).toContainText('Span, basis');
+});
+
+test('the deleted scroll section is gone and the CTA still routes', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('#how-it-works')).toHaveCount(0);
+  await expect(page.locator('#features')).toHaveCount(0);
+  await expect(page.getByTestId('signin-trigger')).toBeVisible();
+});

From 1e026e1694904a3d79accd97266a69a41123c8e7 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 13:32:18 -0700
Subject: [PATCH 12/20] fix(landing): viewport-gate the graph assembly, never
 render it blank (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Final whole-branch review of the landing knowledge-graph demo turned up six
findings. They interact, so this is one wave.

#1 The helix played where nobody could see it. The assembly effect fired on
mount, so it burned its full 1100ms during the hydration window — under the
page's own intro overlay, alongside the hero canvas RAF — and every visitor
who scrolled down found progress === 1 and a static picture. Gate the RAF on
an IntersectionObserver on the section. The root margin is a NEGATIVE bottom
inset, not the positive lead-in that looks natural: the section sits directly
after a min-h-screen hero, so its top edge is at exactly 100vh and any
positive bottom margin re-creates the bug at scroll 0.

#6 No-preference first paint went blank. usePrefersReducedMotion correcting
its SSR-safe `true` to the real `false` dropped progress onto a raw
animatedProgress of 0 — a committed frame with the whole graph at opacity 0 —
and gating #1 would have turned that into a section that stays blank until
scrolled to. animatedProgress is now `number | null`, and null (the assembly
has never run) reads back as 1. Leaving the viewport mid-assembly settles on
the complete frame rather than freezing a half-faded one.

#4 The helix threw the outer ring outside the viewBox. `1 + (1 - e) * 0.9`
put depth-2 nodes at y = 693 against a 560-unit viewBox, chopped by the svg
viewport at opacity ≈ 0.5. It now contracts (0.55x → 1x) instead of
stretching, so the whole sweep lives inside the disc radialLayout already fits
to the frame. helixEntry(target, centre, 1) === target is untouched.

#3 Illegible on phones. One 900x560 viewBox at every width renders at 0.38
scale on a 390px viewport: 4.6 CSS px labels, a 213px-tall smudge. Added a
GraphView descriptor and a 360x300 phone view selected by useIsMobile —
0.95 scale, 12.35 CSS px labels, 22.8px dots, 285px tall.

#2 The engaged copy fade failed WCAG AA permanently (engaged never resets).
--text at 0.35 over the paper bg is 2.20:1 against a 3:1 bar. The fade moves
to the headline alone at 0.55 (3.88:1). The eyebrow is not faded: at 0.7rem
it needs 4.5:1, and --brand-forest only holds that to alpha 0.86 — the
review's suggested 0.75 is 3.58:1 and still fails.

#5 The named SSR guard didn't guard. public-seo.spec.ts asserted only
Metadata API output, which survives `ssr: false` on the dynamic import. Added
a raw-HTML assertion on the graph section's server-rendered copy.

Tests: layout.test.ts sweeps every node of every fixture across the whole t
range in both views and asserts circle + label extents stay in frame (this is
the test that would have caught #4); KnowledgeGraphDemo.test.tsx drives a fake
IntersectionObserver and captured rAF to pin "complete before armed, never
blank", "no RAF until on screen", and the WCAG ratios computed from the
rendered opacity; landing-graph.spec.ts measures label/dot/height in CSS px at
390x844. Each was confirmed to fail against the pre-fix code.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/frontend-testids.md                      |   3 +
 frontend/e2e/landing-graph.spec.ts            |  43 +++
 frontend/e2e/public-seo.spec.ts               |  33 ++
 frontend/src/app/globals.css                  |   7 +-
 .../graph/KnowledgeGraphDemo.test.tsx         | 337 +++++++++++++++++-
 .../marketing/graph/KnowledgeGraphDemo.tsx    | 190 ++++++++--
 .../components/marketing/graph/layout.test.ts | 122 ++++++-
 .../src/components/marketing/graph/layout.ts  | 114 +++++-
 8 files changed, 803 insertions(+), 46 deletions(-)

diff --git a/docs/frontend-testids.md b/docs/frontend-testids.md
index 50438daa..2b45fbe6 100644
--- a/docs/frontend-testids.md
+++ b/docs/frontend-testids.md
@@ -337,8 +337,11 @@ spec and will reuse these same testids.
 | --- | --- |
 | `landing-graph` | demo section root (`aria-label` names the selected course) |
 | `landing-graph-chip-{courseId}` | one course-picker chip, per `COURSE_GRAPHS` entry — `aria-pressed` marks the active course |
+| `landing-graph-svg` | the `<svg>` itself — its `viewBox` is the desktop or the phone `GraphView` (`graph/layout.ts`), swapped at the mobile breakpoint |
 | `landing-graph-node-{nodeId}` | one SVG node group (`<g>`) in the selected course's graph |
 | `landing-graph-copy` | the section's instructional copy block (eyebrow label + heading) — `data-engaged` flips `"true"` on the visitor's first node hover and stays that way across course switches |
+| `landing-graph-eyebrow` | the "Your knowledge, mapped" eyebrow label — deliberately *not* faded on engagement (WCAG AA at 0.7rem) |
+| `landing-graph-headline` | the "Pick a course. Watch it grow." heading — carries the engagement fade (`ENGAGED_HEADLINE_OPACITY`) |
 | `landing-graph-blurb` | the reserved-height paragraph below the graph that shows the hovered node's one-sentence blurb |
 
 ## Enforcement
diff --git a/frontend/e2e/landing-graph.spec.ts b/frontend/e2e/landing-graph.spec.ts
index 4314c7cb..26759a61 100644
--- a/frontend/e2e/landing-graph.spec.ts
+++ b/frontend/e2e/landing-graph.spec.ts
@@ -45,6 +45,49 @@ test('landing graph renders, swaps by course, and fades its copy on engagement',
   await expect(page.getByTestId('landing-graph-blurb')).toContainText('Span, basis');
 });
 
+/**
+ * #344 review #3 — the demo shipped with a single 900×560 viewBox at every
+ * width. Playwright's default 1280×720 viewport cannot see the consequence,
+ * which is why the journey above passed: at a 390px phone the section's content
+ * box is 342px, so the SVG rendered at a uniform 0.38 scale — 4.6 CSS px
+ * concept labels and a 213px-tall smudge, on the device most marketing traffic
+ * arrives on. The component now swaps to a 360×300 viewBox below the mobile
+ * breakpoint (0.95 scale ⇒ 12.4 CSS px labels, 285 CSS px tall).
+ *
+ * Asserting in CSS pixels — what a visitor's eye actually gets — rather than on
+ * the viewBox attribute, so a different fix that reaches the same legibility
+ * still passes.
+ */
+test('the graph stays legible at a 390px phone viewport (#344)', async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto('/');
+
+  const section = page.getByTestId('landing-graph');
+  await section.scrollIntoViewIfNeeded();
+  await expect(page.getByTestId('landing-graph-node-cs-root')).toBeVisible();
+
+  const metrics = await page.getByTestId('landing-graph-svg').evaluate((el) => {
+    const svg = el as unknown as SVGSVGElement;
+    const rect = svg.getBoundingClientRect();
+    const label = svg.querySelector('text')!;
+    // A non-root node — the small dots are what actually got unreadable.
+    const dot = svg.querySelector<SVGCircleElement>(
+      '[data-testid="landing-graph-node-cs-arrays"] circle',
+    )!;
+    // The SVG is width:100%, so every user unit renders at this scale.
+    const scale = rect.width / svg.viewBox.baseVal.width;
+    return {
+      heightPx: rect.height,
+      labelPx: parseFloat(getComputedStyle(label).fontSize) * scale,
+      dotDiameterPx: 2 * dot.r.baseVal.value * scale,
+    };
+  });
+
+  expect(metrics.labelPx, 'concept labels in CSS px').toBeGreaterThanOrEqual(11);
+  expect(metrics.dotDiameterPx, 'non-root node diameter in CSS px').toBeGreaterThanOrEqual(20);
+  expect(metrics.heightPx, 'rendered graph height in CSS px').toBeGreaterThan(260);
+});
+
 test('the deleted scroll section is gone and the CTA still routes', async ({ page }) => {
   await page.goto('/');
   await expect(page.locator('#how-it-works')).toHaveCount(0);
diff --git a/frontend/e2e/public-seo.spec.ts b/frontend/e2e/public-seo.spec.ts
index 956610d1..64afed5d 100644
--- a/frontend/e2e/public-seo.spec.ts
+++ b/frontend/e2e/public-seo.spec.ts
@@ -55,3 +55,36 @@ test("landing page ships social cards and a canonical URL (#169)", async ({ requ
   expect(html).toContain('name="twitter:card"');
   expect(html).toContain('rel="canonical"');
 });
+
+/**
+ * The actual SSR guard (#344 review #5).
+ *
+ * The assertions above were previously described as "the guard on not breaking
+ * SSR", but they aren't: og:image / twitter:card / canonical are emitted by the
+ * Metadata API whether or not any component server-renders. The landing page
+ * mounts `KnowledgeGraphDemo` through `next/dynamic` with SSR left ON, and
+ * `ssr: false` is the first thing anyone will reach for the moment a hydration
+ * warning appears there — it would leave every other spec green while silently
+ * dropping the section's copy out of the crawled HTML, which is the entire
+ * reason that component carries the `usePrefersReducedMotion` machinery.
+ * `landing-graph.spec.ts` runs post-hydration and cannot see the difference.
+ *
+ * So assert on the RAW response body, before any JS runs. With `ssr: false`
+ * the dynamic import renders only its loading placeholder (an empty
+ * `<section id="knowledge-graph">`), and every assertion below fails.
+ */
+test("the knowledge-graph section is in the server-rendered HTML (#344)", async ({ request }) => {
+  const res = await request.get("/");
+  expect(res.status()).toBe(200);
+  const html = await res.text();
+
+  expect(html, "graph section markup must be server-rendered").toContain(
+    'data-testid="landing-graph"',
+  );
+  expect(html, "the section's copy must be crawlable").toContain(
+    "Pick a course. Watch it grow.",
+  );
+  // Concept labels are the section's actual SEO payload.
+  expect(html).toContain('data-testid="landing-graph-node-cs-root"');
+  expect(html).toContain("Recursion");
+});
diff --git a/frontend/src/app/globals.css b/frontend/src/app/globals.css
index 187a5e6c..c116e0de 100644
--- a/frontend/src/app/globals.css
+++ b/frontend/src/app/globals.css
@@ -995,4 +995,9 @@ input[type="reset"]:disabled {
   border-color: var(--brand-forest);
   color: #fff;
 }
-.landing-page .landing-graph-copy { transition: opacity 600ms ease; }
+/* The engagement fade lives on the headline, not the copy block: CSS opacity
+   on the wrapper would group the eyebrow into it, and a child can never be
+   more opaque than its group. `--brand-forest` at 0.7rem needs α ≥ 0.86 to
+   hold WCAG AA 4.5:1 over the paper background, so the eyebrow isn't faded at
+   all — see ENGAGED_HEADLINE_OPACITY in KnowledgeGraphDemo.tsx (#344). */
+.landing-page .landing-graph-headline { transition: opacity 600ms ease; }
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
index 81a61b17..9aff0301 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
@@ -8,12 +8,14 @@ import React from 'react';
 import { act } from 'react';
 import { renderToString } from 'react-dom/server';
 import { hydrateRoot, type Root } from 'react-dom/client';
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { render, screen, cleanup, fireEvent } from '@testing-library/react';
 
-import KnowledgeGraphDemo from './KnowledgeGraphDemo';
+import KnowledgeGraphDemo, { ENGAGED_HEADLINE_OPACITY } from './KnowledgeGraphDemo';
 import { COURSE_GRAPHS } from './courseGraphs';
+import { DESKTOP_VIEW, MOBILE_VIEW } from './layout';
 import { __resetReducedMotionStoreForTests } from '@/lib/usePrefersReducedMotion';
+import { __resetMediaStoresForTests } from '@/lib/useIsMobile';
 
 afterEach(cleanup);
 
@@ -28,6 +30,9 @@ afterEach(cleanup);
 // queried.
 beforeEach(() => {
   __resetReducedMotionStoreForTests();
+  // Same cache-warming hazard as above, for the `useIsMobile` store the
+  // component now consults to pick its viewBox (#344 review #3).
+  __resetMediaStoresForTests();
 });
 
 describe('KnowledgeGraphDemo', () => {
@@ -223,3 +228,331 @@ describe('KnowledgeGraphDemo — interaction', () => {
     expect(copy).toHaveAttribute('data-engaged', 'true');
   });
 });
+
+// ── WCAG plumbing for the engaged-copy contrast test (#344 review #2) ───────
+// Small enough to inline, and inlining keeps the assertion honest: it derives
+// the ratio from the tokens and the opacity the component actually renders,
+// rather than restating a number someone computed once by hand.
+
+/** globals.css: `--bg` = `--ink-0`, `--text` = `--ink-800`. */
+const TOKEN_BG = '#faf8f3';
+const TOKEN_TEXT = '#1a1814';
+const TOKEN_BRAND_FOREST = '#1B6C42';
+
+function channels(hex: string): [number, number, number] {
+  return [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)) as [number, number, number];
+}
+
+function relativeLuminance([r, g, b]: [number, number, number]): number {
+  const lin = (c: number) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** WCAG 2.1 contrast of `fg` at `alpha` composited over the opaque `bg`. */
+function contrastAtOpacity(fgHex: string, bgHex: string, alpha: number): number {
+  const fg = channels(fgHex);
+  const bg = channels(bgHex);
+  const composited = fg.map((c, i) => alpha * c + (1 - alpha) * bg[i]) as [number, number, number];
+  const l1 = relativeLuminance(composited);
+  const l2 = relativeLuminance(bg);
+  const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * The opacity a visitor actually sees on `el`: CSS opacity composes down the
+ * tree, so a fade on the wrapper dims every child and a child can never be
+ * *more* opaque than its group. Walking the chain is what makes this test
+ * indifferent to *where* the fix put the fade.
+ */
+function effectiveOpacity(el: Element, stopAt: Element): number {
+  let alpha = 1;
+  let cur: Element | null = el;
+  while (cur) {
+    const raw = (cur as HTMLElement).style?.opacity;
+    if (raw) alpha *= Number(raw);
+    if (cur === stopAt) break;
+    cur = cur.parentElement;
+  }
+  return alpha;
+}
+
+/**
+ * #344 review #2 — the engaged fade was a flat 0.35 on the whole copy block,
+ * and `engaged` never resets, so that was the section's PERMANENT heading
+ * treatment for the rest of the session, not a transient animation state.
+ * Over this section's flat `--bg` paper that composites the `<h2>` to
+ * #ACAAA5 (2.20:1, under the 3:1 large-text bar) and the 0.7rem eyebrow to
+ * #ACC7B5 (1.71:1, against a 4.5:1 bar).
+ */
+describe('KnowledgeGraphDemo — engaged copy contrast (#344 review #2)', () => {
+  function engage() {
+    render(<KnowledgeGraphDemo />);
+    fireEvent.mouseEnter(
+      screen.getByTestId(`landing-graph-node-${COURSE_GRAPHS[0].nodes[1].id}`),
+    );
+    const copy = screen.getByTestId('landing-graph-copy');
+    expect(copy).toHaveAttribute('data-engaged', 'true');
+    return copy;
+  }
+
+  it('keeps the faded headline over the 3:1 WCAG AA bar for large text', () => {
+    const copy = engage();
+    const headline = copy.querySelector('h2')!;
+    const alpha = effectiveOpacity(headline, copy);
+
+    // The headline is text-4xl (36px) semibold — "large text" by WCAG, 3:1.
+    // 0.55 composites to #7F7D78 = 3.88:1. The shipped 0.35 was 2.20:1.
+    expect(alpha).toBeCloseTo(ENGAGED_HEADLINE_OPACITY, 6);
+    expect(contrastAtOpacity(TOKEN_TEXT, TOKEN_BG, alpha)).toBeGreaterThanOrEqual(3);
+  });
+
+  it('keeps the small eyebrow over the 4.5:1 WCAG AA bar for small text', () => {
+    const copy = engage();
+    const eyebrow = copy.querySelector('span')!;
+    const alpha = effectiveOpacity(eyebrow, copy);
+
+    // 0.7rem ⇒ small text ⇒ 4.5:1, and `--brand-forest` over the paper only
+    // clears that at α ≥ 0.86 — a fade nobody could perceive. So it isn't
+    // faded at all: 6.05:1. The shipped 0.35 was 1.71:1.
+    expect(contrastAtOpacity(TOKEN_BRAND_FOREST, TOKEN_BG, alpha)).toBeGreaterThanOrEqual(4.5);
+  });
+});
+
+// ── Controllable IntersectionObserver + rAF, for the gating tests ──────────
+
+type FakeObserverRecord = {
+  callback: IntersectionObserverCallback;
+  targets: Element[];
+  disconnected: boolean;
+  rootMargin: string;
+};
+
+/** jsdom ships no IntersectionObserver; install one we can fire by hand. */
+function installIntersectionObserver() {
+  const records: FakeObserverRecord[] = [];
+
+  class FakeIntersectionObserver {
+    readonly root = null;
+    readonly rootMargin: string;
+    readonly thresholds: ReadonlyArray<number> = [0];
+    private record: FakeObserverRecord;
+
+    constructor(callback: IntersectionObserverCallback, options?: IntersectionObserverInit) {
+      this.rootMargin = String(options?.rootMargin ?? '0px');
+      this.record = { callback, targets: [], disconnected: false, rootMargin: this.rootMargin };
+      records.push(this.record);
+    }
+    observe(el: Element) {
+      this.record.targets.push(el);
+    }
+    unobserve(el: Element) {
+      this.record.targets = this.record.targets.filter((t) => t !== el);
+    }
+    disconnect() {
+      this.record.disconnected = true;
+      this.record.targets = [];
+    }
+    takeRecords(): IntersectionObserverEntry[] {
+      return [];
+    }
+  }
+
+  const holder = window as unknown as { IntersectionObserver?: unknown };
+  const previous = holder.IntersectionObserver;
+  holder.IntersectionObserver = FakeIntersectionObserver;
+
+  return {
+    records,
+    /** Deliver an intersection change to every live observer, inside `act`. */
+    fire(isIntersecting: boolean) {
+      act(() => {
+        for (const r of records) {
+          if (r.disconnected) continue;
+          r.callback(
+            r.targets.map(
+              (target) => ({ isIntersecting, target }) as unknown as IntersectionObserverEntry,
+            ),
+            null as unknown as IntersectionObserver,
+          );
+        }
+      });
+    },
+    restore() {
+      if (previous === undefined) delete holder.IntersectionObserver;
+      else holder.IntersectionObserver = previous;
+    },
+  };
+}
+
+/** Capture rAF callbacks instead of letting jsdom schedule them on a timer. */
+function captureAnimationFrames() {
+  const queue: FrameRequestCallback[] = [];
+  const raf = vi
+    .spyOn(window, 'requestAnimationFrame')
+    .mockImplementation((cb: FrameRequestCallback) => queue.push(cb));
+  const caf = vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {});
+  return {
+    queue,
+    get frameCount() {
+      return raf.mock.calls.length;
+    },
+    /** Run the next queued frame inside `act`. */
+    step() {
+      const cb = queue.shift();
+      expect(cb, 'expected a queued animation frame').toBeTruthy();
+      act(() => cb!(0));
+    },
+    restore() {
+      raf.mockRestore();
+      caf.mockRestore();
+    },
+  };
+}
+
+function nodeOpacities(): string[] {
+  return COURSE_GRAPHS[0].nodes.map(
+    (n) => screen.getByTestId(`landing-graph-node-${n.id}`).getAttribute('opacity') ?? '',
+  );
+}
+
+/**
+ * #344 review #1 + #6 — two findings that were masking each other.
+ *
+ * #1: the assembly effect fired on mount, so the helix burned its full 1100ms
+ * during the hydration window, underneath the landing page's intro overlay and
+ * alongside the hero canvas RAF. Every visitor scrolled down to `progress === 1`
+ * and a static picture.
+ *
+ * #6: the un-park transition (`usePrefersReducedMotion` correcting its SSR-safe
+ * `true` to the real `false`) landed `progress` on 0 — a committed frame with
+ * the ENTIRE GRAPH at opacity 0. Gating #1 without fixing #6 turns that one
+ * blank frame into a section that stays blank until it is scrolled into view,
+ * which is exactly what `id="knowledge-graph"` invites someone to deep-link to.
+ */
+describe('KnowledgeGraphDemo — viewport gating and the never-blank frame (#344 review #1, #6)', () => {
+  let observer: ReturnType<typeof installIntersectionObserver>;
+  let frames: ReturnType<typeof captureAnimationFrames>;
+
+  beforeEach(() => {
+    // The majority visitor: no motion preference, so `parked` is false and the
+    // component is on the animated path — the only path where either bug bites.
+    installReducedMotion(false);
+    observer = installIntersectionObserver();
+    frames = captureAnimationFrames();
+  });
+
+  afterEach(() => {
+    frames.restore();
+    observer.restore();
+  });
+
+  it('renders the COMPLETE graph, never a blank one, before the section is near the viewport', () => {
+    render(<KnowledgeGraphDemo />);
+    // Pre-fix this was ["0", "0", "0", ...] — the whole point of #6.
+    expect(nodeOpacities()).toEqual(COURSE_GRAPHS[0].nodes.map(() => '1'));
+    const edge = screen.getByTestId('landing-graph-svg').querySelector('line')!;
+    expect(Number(edge.getAttribute('stroke-opacity'))).toBeGreaterThan(0);
+  });
+
+  it('does not start the assembly RAF until the section is reported on screen', () => {
+    render(<KnowledgeGraphDemo />);
+    // Pre-fix the effect fired on mount and this was already ≥ 1.
+    expect(frames.frameCount).toBe(0);
+    expect(observer.records).toHaveLength(1);
+    expect(observer.records[0].targets).toContain(screen.getByTestId('landing-graph'));
+  });
+
+  it('arms the assembly when the section comes into view, and only then', () => {
+    render(<KnowledgeGraphDemo />);
+    observer.fire(true);
+    expect(frames.frameCount).toBeGreaterThan(0);
+
+    frames.step();
+    // Now — and only now — a sub-1 frame is legitimate: the visitor is looking
+    // at it. The clock has barely moved, so the graph is at the start of the
+    // helix.
+    expect(nodeOpacities().every((o) => Number(o) < 1)).toBe(true);
+  });
+
+  it('settles on the complete frame if the section leaves mid-assembly', () => {
+    render(<KnowledgeGraphDemo />);
+    observer.fire(true);
+    frames.step();
+    expect(nodeOpacities().every((o) => Number(o) < 1)).toBe(true);
+
+    // Scrolled away: stop the loop (review #1's "and stop when it leaves"), and
+    // don't freeze a half-faded graph behind (review #6).
+    observer.fire(false);
+    expect(nodeOpacities()).toEqual(COURSE_GRAPHS[0].nodes.map(() => '1'));
+
+    // Coming back doesn't replay the whole helix from blank.
+    const before = frames.frameCount;
+    observer.fire(true);
+    expect(frames.frameCount).toBe(before);
+    expect(nodeOpacities()).toEqual(COURSE_GRAPHS[0].nodes.map(() => '1'));
+  });
+
+  it('gates on a root margin that cannot already be intersecting at scroll 0', () => {
+    render(<KnowledgeGraphDemo />);
+    // The section is mounted straight after a `min-h-screen` hero, so its top
+    // edge sits at exactly 100vh. A positive bottom rootMargin — the natural
+    // "give it some lead-in" reflex — pushes the root's bottom past it and
+    // arms the assembly during hydration, which is review #1 all over again.
+    const bottomInset = observer.records[0].rootMargin.trim().split(/\s+/)[2] ?? '';
+    expect(bottomInset.startsWith('-')).toBe(true);
+  });
+
+  it('degrades to the complete frame when the browser has no IntersectionObserver', () => {
+    // Deliberate: with no gate available the section stays on its static,
+    // fully laid-out frame rather than falling back to an ungated animation.
+    // That's the reduced-motion render — correct, crawlable, and never blank.
+    observer.restore();
+    render(<KnowledgeGraphDemo />);
+    expect(nodeOpacities()).toEqual(COURSE_GRAPHS[0].nodes.map(() => '1'));
+    expect(frames.frameCount).toBe(0);
+  });
+
+  it('disconnects the observer on unmount', () => {
+    const { unmount } = render(<KnowledgeGraphDemo />);
+    expect(observer.records[0].disconnected).toBe(false);
+    unmount();
+    expect(observer.records[0].disconnected).toBe(true);
+  });
+});
+
+/**
+ * #344 review #3 — one 900×560 viewBox at every width rendered 4.6 CSS px
+ * labels on a 390px phone. `layout.test.ts` owns the arithmetic; this pins that
+ * the component actually consults the breakpoint and emits the phone geometry.
+ */
+describe('KnowledgeGraphDemo — mobile viewBox (#344 review #3)', () => {
+  /** Reduced motion (so the frame is parked/complete) at a chosen breakpoint. */
+  function installViewport(isMobile: boolean) {
+    window.matchMedia = ((q: string) => ({
+      matches: q.includes('prefers-reduced-motion') ? true : q.includes('max-width') && isMobile,
+      media: q,
+      addEventListener() {},
+      removeEventListener() {},
+    })) as unknown as typeof window.matchMedia;
+  }
+
+  it('emits the phone viewBox and label size below the breakpoint', () => {
+    installViewport(true);
+    render(<KnowledgeGraphDemo />);
+    const svg = screen.getByTestId('landing-graph-svg');
+    expect(svg.getAttribute('viewBox')).toBe(`0 0 ${MOBILE_VIEW.w} ${MOBILE_VIEW.h}`);
+    expect(svg.querySelector('text')!.getAttribute('font-size')).toBe(String(MOBILE_VIEW.font));
+  });
+
+  it('keeps the desktop viewBox above it', () => {
+    installViewport(false);
+    render(<KnowledgeGraphDemo />);
+    const svg = screen.getByTestId('landing-graph-svg');
+    expect(svg.getAttribute('viewBox')).toBe(`0 0 ${DESKTOP_VIEW.w} ${DESKTOP_VIEW.h}`);
+    expect(svg.querySelector('text')!.getAttribute('font-size')).toBe(String(DESKTOP_VIEW.font));
+  });
+});
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index f667679f..8c904ad7 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -3,19 +3,59 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 
 import { IS_TEST_MODE, now } from '@/lib/testMode';
+import { useIsMobile } from '@/lib/useIsMobile';
 import { usePrefersReducedMotion } from '@/lib/usePrefersReducedMotion';
 
 import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph } from './courseGraphs';
-import { helixEntry, radialLayout, type Point } from './layout';
-
-const VIEW_W = 900;
-const VIEW_H = 560;
+import {
+  DESKTOP_VIEW,
+  MOBILE_VIEW,
+  helixEntry,
+  radialLayout,
+  type GraphView,
+  type Point,
+} from './layout';
 
 /** How long the helical assembly takes to land on the laid-out frame. */
 const ASSEMBLE_MS = 1100;
 
-function nodeRadius(g: CourseGraph, id: string): number {
-  return id === g.rootId ? 26 : 14;
+/**
+ * When the section counts as "near enough to arm the assembly".
+ *
+ * Deliberately a NEGATIVE bottom inset, not the positive lead-in margin that
+ * looks natural here. This section is mounted immediately after a
+ * `min-h-screen` hero, so its top edge sits at exactly 100vh: *any* positive
+ * bottom rootMargin makes it intersect at scroll position 0 and re-creates the
+ * exact bug the gate exists to fix (#344 review #1) — the helix burning its
+ * 1100ms during hydration, under the intro overlay, where nobody can see it.
+ *
+ * −10% instead means the section's top has to clear a tenth of the viewport
+ * before the loop arms. There is still ample lead-in: the section opens with
+ * `py-24` of padding plus the copy block and the chips, so ~300px of further
+ * scrolling separates arming from the SVG itself appearing — the assembly is
+ * already underway by the time the graph is on screen.
+ */
+const ARM_ROOT_MARGIN = '0px 0px -10% 0px';
+
+/**
+ * Opacity the headline fades to once the visitor engages with the graph.
+ *
+ * Not the 0.35 this shipped with (#344 review #2). Composited over the flat
+ * `--bg` paper (#faf8f3) this section renders on, `--text` (#1a1814) at 0.35 is
+ * #ACAAA5 = 2.20:1 — under the 3:1 WCAG AA bar for large text, permanently,
+ * because `engaged` never resets. At 0.55 it composites to #7F7D78 = 3.88:1,
+ * which clears it with room to spare while still reading as a clear recede.
+ *
+ * The eyebrow above the headline is deliberately NOT faded: it's 0.7rem
+ * (small text ⇒ 4.5:1), and `--brand-forest` (#1B6C42) needs α ≥ 0.86 to hold
+ * that ratio — a "fade" nobody can perceive. Since CSS opacity on the wrapper
+ * would group both elements and a child can never be *more* opaque than its
+ * group, the fade lives on the headline alone.
+ */
+export const ENGAGED_HEADLINE_OPACITY = 0.55;
+
+function nodeRadius(view: GraphView, g: CourseGraph, id: string): number {
+  return id === g.rootId ? view.rootR : view.nodeR;
 }
 
 /**
@@ -27,47 +67,77 @@ function nodeRadius(g: CourseGraph, id: string): number {
  * Remounting also means unmount cleanup alone is enough to cancel the RAF
  * both on course change and on real unmount — no separate reset path needed.
  *
- * `progress` is derived from `animatedProgress`, not the state directly:
- * `parked` can flip after mount without a remount (`usePrefersReducedMotion`
- * corrects from its SSR-safe default to the real client value shortly after
- * hydration — see that hook's doc comment), and deriving `progress` this way
- * means that transition is correct in *both* directions without an effect
- * having to reconcile it: parked always reads back as the complete frame
- * regardless of whatever `animatedProgress` last held, and un-parking just
- * exposes whatever `animatedProgress` already is (still its unmounted-since
- * initial `0` if the assembly effect below hasn't started yet).
+ * `progress` is derived, never read straight off state, and its resting value
+ * is 1 — the COMPLETE frame. That is the whole of #344 review #6: this
+ * component server-renders a complete graph, and the majority visitor (no
+ * motion preference) then has `usePrefersReducedMotion` correct from its
+ * SSR-safe `true` default to `false` shortly after hydration. If un-parking
+ * exposed a raw `animatedProgress` initialised to 0, that correction would
+ * commit at least one painted frame with the entire graph at opacity 0 — and
+ * once the RAF is viewport-gated (`armed`), it would stay blank until the
+ * visitor scrolled down to a section that its own `id="knowledge-graph"`
+ * invites them to deep-link straight into. So `animatedProgress` starts as
+ * `null` meaning "the assembly has never run", and `null` reads back as 1.
+ * The graph is never blank in a committed frame; the only frames below 1 are
+ * the ones the live RAF loop is actively driving, on screen, on purpose.
+ *
+ * Deriving rather than reconciling also makes the `parked` flip correct in
+ * both directions without an effect: parked always reads back as the complete
+ * frame regardless of whatever `animatedProgress` last held.
  */
 function AssemblingGraph({
   graph,
   points,
+  view,
   parked,
+  armed,
   onNodeEnter,
   onNodeLeave,
 }: {
   graph: CourseGraph;
   points: Map<string, Point>;
+  view: GraphView;
   parked: boolean;
+  armed: boolean;
   onNodeEnter: (id: string) => void;
   onNodeLeave: () => void;
 }) {
-  const [animatedProgress, setAnimatedProgress] = useState(0);
+  const [animatedProgress, setAnimatedProgress] = useState<number | null>(null);
+  // Latches once the assembly has finished (or been abandoned). Keeps a
+  // re-entry into the viewport from replaying the whole helix every time the
+  // visitor scrolls past, and keeps a mid-flight cancel from freezing a
+  // half-faded frame.
+  const settledRef = useRef(false);
+
   // "Parked" means the assembly is skipped and the graph renders complete —
   // fully laid out, full opacity — on the very first frame. Reduced-motion
-  // visitors and the E2E/unit-test lanes (IS_TEST_MODE) both get this.
-  const progress = parked ? 1 : animatedProgress;
-  const rafRef = useRef(0);
+  // visitors and the E2E/unit-test lanes (IS_TEST_MODE) both get this. So does
+  // everyone else until the loop is actually armed and running; see above.
+  const progress = parked || animatedProgress === null ? 1 : animatedProgress;
 
   useEffect(() => {
-    if (parked) return;
+    if (parked || !armed || settledRef.current) return;
     const start = now();
+    let raf = 0;
     const tick = () => {
       const p = Math.min(1, (now() - start) / ASSEMBLE_MS);
+      if (p >= 1) settledRef.current = true;
       setAnimatedProgress(p);
-      if (p < 1) rafRef.current = requestAnimationFrame(tick);
+      if (p < 1) raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => {
+      cancelAnimationFrame(raf);
+      if (!settledRef.current) {
+        // Scrolled away (or unmounted) mid-assembly: settle on the complete
+        // frame rather than leaving the section parked on a half-faded one.
+        settledRef.current = true;
+        setAnimatedProgress(1);
+      }
     };
-    rafRef.current = requestAnimationFrame(tick);
-    return () => cancelAnimationFrame(rafRef.current);
-  }, [parked]);
+  }, [parked, armed]);
+
+  const centre = { x: view.w / 2, y: view.h / 2 };
 
   return (
     <>
@@ -84,7 +154,7 @@ function AssemblingGraph({
             y2={b.y}
             stroke="var(--text-dim)"
             strokeOpacity={0.28 * progress}
-            strokeWidth={1.4}
+            strokeWidth={view.edgeW}
           />
         );
       })}
@@ -95,8 +165,8 @@ function AssemblingGraph({
         // Stagger: later nodes start later, all finish by progress = 1.
         const span = 1 / (graph.nodes.length + 2);
         const local = Math.min(1, Math.max(0, (progress - i * span) / (1 - i * span)));
-        const h = helixEntry(p, { x: VIEW_W / 2, y: VIEW_H / 2 }, local);
-        const r = nodeRadius(graph, n.id);
+        const h = helixEntry(p, centre, local);
+        const r = nodeRadius(view, graph, n.id);
         return (
           <g
             key={n.id}
@@ -108,10 +178,10 @@ function AssemblingGraph({
             <circle cx={h.x} cy={h.y} r={r * h.scale} fill={TIER_COLOR[n.tier]} />
             <text
               x={h.x}
-              y={h.y + r + 16}
+              y={h.y + r + view.labelGap}
               textAnchor="middle"
               className="font-jetbrains"
-              fontSize={12}
+              fontSize={view.font}
               fill="var(--text-dim)"
               opacity={h.opacity}
             >
@@ -158,7 +228,20 @@ export default function KnowledgeGraphDemo() {
     () => COURSE_GRAPHS.find((g) => g.id === courseId) ?? COURSE_GRAPHS[0],
     [courseId],
   );
-  const points = useMemo(() => radialLayout(graph, VIEW_W, VIEW_H), [graph]);
+
+  // #344 review #3: one 900×560 viewBox rendered at every width put 4.6 CSS px
+  // labels on a 390px phone. `useIsMobile` is the same `useSyncExternalStore`
+  // shape as `usePrefersReducedMotion` — SSR-safe, no render-body matchMedia
+  // read — so the server (and the hydrating render) picks the desktop view and
+  // the phone corrects on the first commit after hydration. A viewBox is not
+  // something a CSS `@media` rule can swap, so that one-frame correction is the
+  // floor here; both views render the complete graph, so it is a resize, never
+  // a blank.
+  const view = useIsMobile() ? MOBILE_VIEW : DESKTOP_VIEW;
+  const points = useMemo(
+    () => radialLayout(graph, view.w, view.h, view.maxRadius),
+    [graph, view],
+  );
   const hoveredBlurb = hovered ? graph.nodes.find((n) => n.id === hovered)?.blurb : undefined;
 
   // `usePrefersReducedMotion` (not a direct `window.matchMedia` read in the
@@ -169,8 +252,38 @@ export default function KnowledgeGraphDemo() {
   const prefersReduced = usePrefersReducedMotion();
   const parked = IS_TEST_MODE || prefersReduced;
 
+  // #344 review #1: without this gate the assembly effect fired on mount and
+  // burned its full 1100ms during the hydration window — underneath the
+  // landing page's full-screen intro overlay, concurrently with the hero
+  // canvas RAF and the hero text scramble, ~66 re-renders of this SVG subtree
+  // that nobody could see. By the time a visitor scrolled here, progress was
+  // already 1 and the "interactive knowledge graph" was a static picture, for
+  // every visitor, every time.
+  const sectionRef = useRef<HTMLElement | null>(null);
+  const [armed, setArmed] = useState(false);
+
+  // No `IntersectionObserver` (jsdom, pre-2019 browsers) means no gate, and the
+  // graceful degradation is to leave the section on its complete frame rather
+  // than to un-gate the animation: a static, fully laid-out graph is exactly
+  // what reduced-motion visitors already get, and it can never be blank. That
+  // also keeps this effect free of a synchronous `setArmed` fallback, which
+  // react-hooks/set-state-in-effect rightly rejects as a cascading render.
+  useEffect(() => {
+    const el = sectionRef.current;
+    if (!el || typeof IntersectionObserver === 'undefined') return;
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) setArmed(entry.isIntersecting);
+      },
+      { rootMargin: ARM_ROOT_MARGIN },
+    );
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
   return (
     <section
+      ref={sectionRef}
       id="knowledge-graph"
       data-testid="landing-graph"
       aria-label={`Interactive knowledge graph for ${graph.name}`}
@@ -181,12 +294,18 @@ export default function KnowledgeGraphDemo() {
           data-testid="landing-graph-copy"
           data-engaged={engaged ? 'true' : 'false'}
           className="landing-graph-copy"
-          style={{ opacity: engaged ? 0.35 : 1 }}
         >
-          <span className="font-jetbrains text-[0.7rem] tracking-[0.32em] text-[var(--brand-forest)] uppercase font-medium">
+          <span
+            data-testid="landing-graph-eyebrow"
+            className="font-jetbrains text-[0.7rem] tracking-[0.32em] text-[var(--brand-forest)] uppercase font-medium"
+          >
             Your knowledge, mapped
           </span>
-          <h2 className="font-playfair text-4xl md:text-6xl font-semibold text-[var(--text)] mt-4 leading-[1.05] tracking-tight">
+          <h2
+            data-testid="landing-graph-headline"
+            className="landing-graph-headline font-playfair text-4xl md:text-6xl font-semibold text-[var(--text)] mt-4 leading-[1.05] tracking-tight"
+            style={{ opacity: engaged ? ENGAGED_HEADLINE_OPACITY : 1 }}
+          >
             Pick a course. Watch it grow.
           </h2>
         </div>
@@ -210,7 +329,8 @@ export default function KnowledgeGraphDemo() {
         </div>
 
         <svg
-          viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+          data-testid="landing-graph-svg"
+          viewBox={`0 0 ${view.w} ${view.h}`}
           className="mt-8 w-full h-auto"
           role="img"
           aria-label={`${graph.name} concept graph`}
@@ -219,7 +339,9 @@ export default function KnowledgeGraphDemo() {
             key={graph.id}
             graph={graph}
             points={points}
+            view={view}
             parked={parked}
+            armed={armed}
             onNodeEnter={onNodeEnter}
             onNodeLeave={onNodeLeave}
           />
diff --git a/frontend/src/components/marketing/graph/layout.test.ts b/frontend/src/components/marketing/graph/layout.test.ts
index bbd7590d..85581b92 100644
--- a/frontend/src/components/marketing/graph/layout.test.ts
+++ b/frontend/src/components/marketing/graph/layout.test.ts
@@ -6,7 +6,14 @@
 import { describe, it, expect } from 'vitest';
 
 import { COURSE_GRAPHS } from './courseGraphs';
-import { easeOutCubic, helixEntry, radialLayout } from './layout';
+import {
+  DESKTOP_VIEW,
+  GRAPH_VIEWS,
+  MOBILE_VIEW,
+  easeOutCubic,
+  helixEntry,
+  radialLayout,
+} from './layout';
 
 const G = COURSE_GRAPHS[0];
 
@@ -43,6 +50,16 @@ describe('radialLayout', () => {
     const large = radialLayout(G, 1200, 800);
     expect(small).not.toEqual(large);
   });
+
+  it('keeps the default maxRadius at the old inscribed-circle rule', () => {
+    // The `maxRadius` parameter was added for the mobile view (#344 review #3).
+    // Its default has to reproduce the desktop geometry this branch was
+    // designed against byte-for-byte, or every existing frame shifts.
+    expect(radialLayout(G, 900, 560)).toEqual(
+      radialLayout(G, 900, 560, Math.min(900, 560) / 2 - 48),
+    );
+    expect(DESKTOP_VIEW.maxRadius).toBe(Math.min(DESKTOP_VIEW.w, DESKTOP_VIEW.h) / 2 - 48);
+  });
 });
 
 describe('easeOutCubic', () => {
@@ -90,4 +107,107 @@ describe('helixEntry', () => {
       prev = s;
     }
   });
+
+  it('never travels further from the centre than its own target does', () => {
+    // The invariant behind the bounds sweep below: the entry path only ever
+    // *contracts* toward the centre, so the whole sweep lives inside the disc
+    // the static layout already fits to the viewBox. The pre-fix version
+    // stretched to 1.9× at t=0 and this fails outright (#344 review #4).
+    const targetRadius = Math.hypot(target.x - centre.x, target.y - centre.y);
+    for (let i = 0; i <= 1000; i++) {
+      const h = helixEntry(target, centre, i / 1000);
+      expect(Math.hypot(h.x - centre.x, h.y - centre.y)).toBeLessThanOrEqual(targetRadius + 1e-9);
+    }
+  });
+});
+
+/**
+ * #344 review #4 — the bug this file should have caught during development.
+ *
+ * The entry path used to stretch the offset from the centre by up to 1.9×, so
+ * against the real desktop layout the outer ring swung to y = 693 (133px past
+ * the 560-unit viewBox edge), got chopped by the `<svg>` viewport, and crossed
+ * back in at opacity ≈ 0.5 — plainly visible, and invisible in review only
+ * because the animation was also playing off-screen (review #1).
+ *
+ * So: sweep `t` across the whole entry for every node of every fixture in every
+ * view, and assert that the drawn extent — circle, and label baseline — never
+ * leaves the viewBox.
+ */
+describe('helixEntry × radialLayout — nothing leaves the viewBox', () => {
+  /**
+   * Labels render in JetBrains Mono, whose advance width is 600/1000 em. The
+   * text is `textAnchor="middle"`, so half the string hangs off each side of
+   * the node's x. This is the constraint that actually sizes the mobile view:
+   * the outer ring sits on the horizontal axis, so its labels are the first
+   * thing that would run off the right edge.
+   */
+  const MONO_ADVANCE_EM = 0.6;
+  const STEPS = 400;
+
+  for (const view of GRAPH_VIEWS) {
+    for (const graph of COURSE_GRAPHS) {
+      it(`${graph.id} stays inside ${view.w}×${view.h} across the whole sweep`, () => {
+        const points = radialLayout(graph, view.w, view.h, view.maxRadius);
+        const centre = { x: view.w / 2, y: view.h / 2 };
+
+        for (const n of graph.nodes) {
+          const p = points.get(n.id)!;
+          const r = n.id === graph.rootId ? view.rootR : view.nodeR;
+          const halfLabel = (n.label.length * MONO_ADVANCE_EM * view.font) / 2;
+
+          for (let i = 0; i <= STEPS; i++) {
+            const t = i / STEPS;
+            const h = helixEntry(p, centre, t);
+            const dotR = r * h.scale;
+            const where = `${graph.id}/${n.id} @ t=${t.toFixed(3)}`;
+
+            // Circle.
+            expect(h.x - dotR, `${where} left`).toBeGreaterThanOrEqual(0);
+            expect(h.x + dotR, `${where} right`).toBeLessThanOrEqual(view.w);
+            expect(h.y - dotR, `${where} top`).toBeGreaterThanOrEqual(0);
+            expect(h.y + dotR, `${where} bottom`).toBeLessThanOrEqual(view.h);
+
+            // Label: baseline sits at `y + r + labelGap`; leave a descender's
+            // worth (0.25em) of room under it.
+            expect(
+              h.y + r + view.labelGap + view.font * 0.25,
+              `${where} label baseline`,
+            ).toBeLessThanOrEqual(view.h);
+            expect(h.x - halfLabel, `${where} label left`).toBeGreaterThanOrEqual(0);
+            expect(h.x + halfLabel, `${where} label right`).toBeLessThanOrEqual(view.w);
+          }
+        }
+      });
+    }
+  }
+});
+
+/**
+ * #344 review #3 — the demo was one 900×560 viewBox at every width, which at a
+ * 390px phone viewport (342px content box after `px-6`) is a uniform 0.38 scale:
+ * 4.6 CSS px labels and 10.6 CSS px dots. These pin the sizes the mobile view
+ * actually resolves to, in the units a visitor sees.
+ */
+describe('GraphView sizing at a 390px viewport', () => {
+  /** 390px viewport − `px-6` (24px each side) = the section's content box. */
+  const CONTENT_PX = 390 - 48;
+
+  it('renders legible labels and dots on a phone', () => {
+    const scale = CONTENT_PX / MOBILE_VIEW.w;
+    expect(scale).toBeCloseTo(0.95, 4);
+    // 12.35 CSS px labels (was 4.56), 22.8 CSS px dot diameter (was 10.64),
+    // 285 CSS px of graph height (was 213).
+    expect(MOBILE_VIEW.font * scale).toBeGreaterThanOrEqual(11);
+    expect(2 * MOBILE_VIEW.nodeR * scale).toBeGreaterThanOrEqual(20);
+    expect(MOBILE_VIEW.h * scale).toBeGreaterThanOrEqual(260);
+  });
+
+  it('documents what the desktop view resolved to on the same phone', () => {
+    // Not an aspiration — the numbers the bug produced, kept here so a future
+    // "just use one viewBox everywhere" change has to argue with them.
+    const scale = CONTENT_PX / DESKTOP_VIEW.w;
+    expect(DESKTOP_VIEW.font * scale).toBeLessThan(5); // 4.56 CSS px labels
+    expect(DESKTOP_VIEW.h * scale).toBeLessThan(220); // 212.8 CSS px tall
+  });
 });
diff --git a/frontend/src/components/marketing/graph/layout.ts b/frontend/src/components/marketing/graph/layout.ts
index ce45158e..9cb330c0 100644
--- a/frontend/src/components/marketing/graph/layout.ts
+++ b/frontend/src/components/marketing/graph/layout.ts
@@ -12,6 +12,77 @@ export interface Point {
   y: number;
 }
 
+/**
+ * Everything the demo needs to draw itself at one viewport class, in SVG user
+ * units. The `<svg>` is `width: 100%`, so the rendered CSS size of *every*
+ * dimension below is `value * (renderedWidth / w)` — which is exactly why the
+ * desktop numbers can't just be reused on a phone: at a 390px viewport the
+ * section's content box is 342px, so the 900-wide desktop viewBox renders at
+ * 0.38 scale and a 12-unit label lands at 4.6 CSS px (#344 review #3).
+ *
+ * The two views are picked apart by `useIsMobile()` in the component. Keeping
+ * them as data (rather than a pile of ternaries at each call site) is what lets
+ * `layout.test.ts` sweep the entry animation against *both* viewBoxes and prove
+ * nothing leaves frame.
+ */
+export interface GraphView {
+  /** viewBox width, user units. */
+  w: number;
+  /** viewBox height, user units. */
+  h: number;
+  /** Radius of the outermost ring — the layout's whole spatial budget. */
+  maxRadius: number;
+  /** Label font-size, user units. */
+  font: number;
+  /** Root-node circle radius, user units. */
+  rootR: number;
+  /** Non-root node circle radius, user units. */
+  nodeR: number;
+  /** Baseline offset of a node's label below the node centre + its radius. */
+  labelGap: number;
+  /** Edge stroke width, user units. */
+  edgeW: number;
+}
+
+/**
+ * `maxRadius: 232` is byte-identical to what `radialLayout`'s old default
+ * (`min(900, 560) / 2 - 48`) produced, so the desktop frame this branch was
+ * designed and reviewed against is unchanged.
+ */
+export const DESKTOP_VIEW: GraphView = {
+  w: 900,
+  h: 560,
+  maxRadius: 232,
+  font: 12,
+  rootR: 26,
+  nodeR: 14,
+  labelGap: 16,
+  edgeW: 1.4,
+};
+
+/**
+ * Portrait-ish and much smaller in user units, so a phone's ~342px content box
+ * renders it at 0.95 scale instead of 0.38: 13-unit labels land at 12.4 CSS px
+ * and non-root dots at a 22.8px diameter (#344 review #3).
+ *
+ * `maxRadius: 108` is set by the *labels*, not the dots: the outer ring sits on
+ * the horizontal axis, so the widest label ("Central Limit", 13 chars) has to
+ * clear the right edge — 180 + 108 + (13 × 0.6 × 13) / 2 = 338.7 of 360.
+ */
+export const MOBILE_VIEW: GraphView = {
+  w: 360,
+  h: 300,
+  maxRadius: 108,
+  font: 13,
+  rootR: 22,
+  nodeR: 12,
+  labelGap: 16,
+  edgeW: 1.6,
+};
+
+/** Every view the demo can render in — the sweep target for the bounds test. */
+export const GRAPH_VIEWS: GraphView[] = [DESKTOP_VIEW, MOBILE_VIEW];
+
 function clamp01(t: number): number {
   return t < 0 ? 0 : t > 1 ? 1 : t;
 }
@@ -25,11 +96,18 @@ export function easeOutCubic(t: number): number {
  * Root at the centre, each BFS depth on its own ring, siblings spread evenly
  * around it. Alternate rings are rotated by half a slot so spokes don't line
  * up into visual spokes.
+ *
+ * `maxRadius` is the outermost ring's distance from the centre. It defaults to
+ * the old inscribed-circle-minus-48 rule so every existing caller and test is
+ * unchanged, but the mobile view passes it explicitly: there the binding
+ * constraint is label width against the *narrow* edge, not the inscribed
+ * circle, and `min(w, h) / 2 - pad` can't express that.
  */
 export function radialLayout(
   graph: CourseGraph,
   width: number,
   height: number,
+  maxRadius: number = Math.min(width, height) / 2 - 48,
 ): Map<string, Point> {
   const adj = new Map<string, string[]>();
   for (const e of graph.edges) {
@@ -60,7 +138,7 @@ export function radialLayout(
   const cx = width / 2;
   const cy = height / 2;
   const maxDepth = Math.max(...byDepth.keys(), 1);
-  const ring = (Math.min(width, height) / 2 - 48) / maxDepth;
+  const ring = maxRadius / maxDepth;
 
   const out = new Map<string, Point>();
   for (const [d, ids] of byDepth) {
@@ -81,13 +159,33 @@ export function radialLayout(
   return out;
 }
 
+/**
+ * How far *inside* its target radius a node starts. The offset from the centre
+ * is scaled by `1 - (1 - e) * ENTRY_CONTRACTION`, i.e. 0.55× at t=0 rising to
+ * exactly 1× at t=1.
+ *
+ * This used to be a *stretch* (`1 + (1 - e) * 0.9`, so 1.9× at t=0), which is
+ * the #344-review-#4 bug: swept against the real desktop layout (centre 450,280;
+ * outer ring at radius 232) the outer nodes reached y = 693 — 133px below the
+ * 560 viewBox edge — and crossed back in at opacity ≈ 0.5, so the visitor
+ * watched them get chopped off by the `<svg>` viewport mid-assembly. Because
+ * the spiral now only ever *contracts*, every point of the sweep lies inside
+ * the disc of radius |target − centre|, which is bounded by the static layout
+ * that `radialLayout` already fits to the viewBox. `layout.test.ts` pins that
+ * as an explicit bounds sweep over every fixture × every view.
+ *
+ * It reads better too: nodes now grow outward from the root rather than flying
+ * in from off-frame.
+ */
+const ENTRY_CONTRACTION = 0.45;
+
 /**
  * Position along the helical entry path. `t` runs 0 → 1.
  *
- * The node spirals inward: its offset from the centre is rotated by a
- * decreasing angle and stretched outward by a decreasing factor, while scale
- * and opacity rise. At t=1 every term collapses and the node sits exactly on
- * `target`, so the animation has no seam where it hands off to the static
+ * The node spirals outward from near the centre: its offset from the centre is
+ * rotated by a decreasing angle and contracted by a shrinking factor, while
+ * scale and opacity rise. At t=1 every term collapses and the node sits exactly
+ * on `target`, so the animation has no seam where it hands off to the static
  * layout.
  */
 export function helixEntry(
@@ -101,13 +199,13 @@ export function helixEntry(
   const dy = target.y - centre.y;
 
   const angle = (1 - e) * turns * Math.PI * 2;
-  const stretch = 1 + (1 - e) * 0.9;
+  const radiusScale = 1 - (1 - e) * ENTRY_CONTRACTION;
   const cos = Math.cos(angle);
   const sin = Math.sin(angle);
 
   return {
-    x: centre.x + (dx * cos - dy * sin) * stretch,
-    y: centre.y + (dx * sin + dy * cos) * stretch,
+    x: centre.x + (dx * cos - dy * sin) * radiusScale,
+    y: centre.y + (dx * sin + dy * cos) * radiusScale,
     scale: 0.35 + 0.65 * e,
     opacity: e,
   };

From 5ab1eda85e8710c03c6cc87c6a1199218db6532d Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 15:21:55 -0700
Subject: [PATCH 13/20] fix(landing): brand-conform the graph section and fit
 its frame (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five visual/brand defects found by screenshotting the built page against the
brand guide. Every automated gate was already green, so none of these were
test-detectable.

1. TIER_COLOR was a fourth inlined copy of the mastery palette with four wrong
   literals — the landing page advertised different mastery colours than the
   product. Now consumes the canonical --state-* tokens (globals.css:80-89).
   The hero legend's four swatches get the same treatment (colours only).

2. The course root inherited its fixture tier's amber, so the section's focal
   point read as a warning. It now paints --brand-forest as an anchor; the
   fixture tier is unchanged.

3. The SVG used a hardcoded viewBox="0 0 900 560" stretched to a ~1184px
   container, reserving ~737px of height around content that clustered in the
   middle. The frame is now DERIVED (fitViewBox) from the drawn content — dot,
   label, halo — swept across the whole entry animation, unioned over all three
   fixtures so a chip click can't change the section height, once per
   breakpoint. Desktop resolves to "159 42 578 498", 36% narrower than the box
   it replaced.

   Fitted to the HELIX SWEEP, not the settled positions: helixEntry rotates
   1.5 turns, so an outer node passes 0.925*maxRadius above and below the
   centre at ~83% opacity — 215 units against a settled extent of 58. A
   settled fit clips the assembly, which is #344 review #4 all over again. The
   bounds test is retargeted at the derived box, and a new paired test proves
   the sweep genuinely leaves the settled bounding box so that containment
   check stays load-bearing.

   The fit only pays off with a width cap — stretched to 1184px a tighter box
   renders at 2x and makes the section taller. Capped at md:max-w-[720px].

4. The root's label lay along the outer-ring -> depth-1 edge, which crosses
   the root's x at cy + 0.349*ring in every fixture. It moves above the node on
   desktop; on the phone the ring is too small for that to clear the top
   child's label, so it stays below (where the diagonal doesn't reach it). All
   labels gain a paint-order halo in --bg-mesh. Two unreported collisions also
   fixed: "Hypothesis Tests" overlapped "Distributions" by ~21 CSS px at 390px,
   and the shipped phone geometry both overlapped and, under the fit, fell
   under the E2E height gate. New suite pins label/label, label/dot and
   label/edge clearance for every fixture in both views.

5. Left-aligned the graph to the headline's grid — the same width cap — so a
   left-aligned copy block no longer sits above a centred diagram.

503 unit tests pass (up 6), tsc and eslint clean. No new CSS, no new dependency,
no assertion weakened.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 frontend/e2e/landing-graph.spec.ts            |   7 +-
 frontend/src/app/(public)/page.tsx            |  16 +-
 .../graph/KnowledgeGraphDemo.test.tsx         |  83 ++++-
 .../marketing/graph/KnowledgeGraphDemo.tsx    |  77 ++++-
 .../marketing/graph/courseGraphs.test.ts      |  28 +-
 .../marketing/graph/courseGraphs.ts           |  34 +-
 .../components/marketing/graph/layout.test.ts | 280 ++++++++++++---
 .../src/components/marketing/graph/layout.ts  | 320 +++++++++++++++---
 8 files changed, 715 insertions(+), 130 deletions(-)

diff --git a/frontend/e2e/landing-graph.spec.ts b/frontend/e2e/landing-graph.spec.ts
index 26759a61..62f9bbbc 100644
--- a/frontend/e2e/landing-graph.spec.ts
+++ b/frontend/e2e/landing-graph.spec.ts
@@ -49,10 +49,11 @@ test('landing graph renders, swaps by course, and fades its copy on engagement',
  * #344 review #3 — the demo shipped with a single 900×560 viewBox at every
  * width. Playwright's default 1280×720 viewport cannot see the consequence,
  * which is why the journey above passed: at a 390px phone the section's content
- * box is 342px, so the SVG rendered at a uniform 0.38 scale — 4.6 CSS px
+ * box is ~332px, so the SVG rendered at a uniform 0.38 scale — 4.6 CSS px
  * concept labels and a 213px-tall smudge, on the device most marketing traffic
- * arrives on. The component now swaps to a 360×300 viewBox below the mobile
- * breakpoint (0.95 scale ⇒ 12.4 CSS px labels, 285 CSS px tall).
+ * arrives on. The component now swaps to a phone view below the mobile
+ * breakpoint, whose frame is fitted to its content (`-19 5 394 319`, #344
+ * visual 3): 0.84 scale ⇒ 11.8 CSS px labels, 23.6px dots, 269px tall.
  *
  * Asserting in CSS pixels — what a visitor's eye actually gets — rather than on
  * the viewBox attribute, so a different fix that reaches the same legibility
diff --git a/frontend/src/app/(public)/page.tsx b/frontend/src/app/(public)/page.tsx
index f2457431..85846d2e 100644
--- a/frontend/src/app/(public)/page.tsx
+++ b/frontend/src/app/(public)/page.tsx
@@ -499,11 +499,19 @@ export default function LandingPage() {
             style={{ position: 'absolute', top: '24%', right: '12%', opacity: heroMounted ? 1 : 0, transition: 'opacity 0.6s ease 1.0s' }}
             data-base-rot="4" data-float-delay="1000" data-float-dur="6000"
           >
+            {/*
+              Canonical knowledge-status tokens (globals.css:80-89), not literals
+              (#344 visual 1b). These four swatches and the knowledge-graph
+              section's node colours are one viewport apart on the same page, so
+              they have to be the same palette — and it has to be the palette the
+              signed-in product actually uses. Colours only; nothing else in the
+              hero moves.
+            */}
             <div className="flex flex-col gap-3">
-              <div className="flex items-center gap-2"><div className="w-2 h-2 rounded-full bg-[var(--brand-forest)]" /><span className="text-xs text-[var(--text-dim)] uppercase tracking-wide">Mastered</span></div>
-              <div className="flex items-center gap-2"><div className="w-2 h-2 rounded-full bg-[#D97706]" /><span className="text-xs text-[var(--text-dim)] uppercase tracking-wide">Learning</span></div>
-              <div className="flex items-center gap-2"><div className="w-2 h-2 rounded-full bg-[#EF4444]" /><span className="text-xs text-[var(--text-dim)] uppercase tracking-wide">Struggling</span></div>
-              <div className="flex items-center gap-2"><div className="w-2 h-2 rounded-full bg-[#9CA3AF]" /><span className="text-xs text-[var(--text-dim)] uppercase tracking-wide">Unexplored</span></div>
+              <div className="flex items-center gap-2"><div className="w-2 h-2 rounded-full bg-[var(--state-mastery)]" /><span className="text-xs text-[var(--text-dim)] uppercase tracking-wide">Mastered</span></div>
+              <div className="flex items-center gap-2"><div className="w-2 h-2 rounded-full bg-[var(--state-progress)]" /><span className="text-xs text-[var(--text-dim)] uppercase tracking-wide">Learning</span></div>
+              <div className="flex items-center gap-2"><div className="w-2 h-2 rounded-full bg-[var(--state-struggle)]" /><span className="text-xs text-[var(--text-dim)] uppercase tracking-wide">Struggling</span></div>
+              <div className="flex items-center gap-2"><div className="w-2 h-2 rounded-full bg-[var(--state-neutral)]" /><span className="text-xs text-[var(--text-dim)] uppercase tracking-wide">Unexplored</span></div>
             </div>
           </div>
 
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
index 9aff0301..7457aed6 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
@@ -12,8 +12,8 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { render, screen, cleanup, fireEvent } from '@testing-library/react';
 
 import KnowledgeGraphDemo, { ENGAGED_HEADLINE_OPACITY } from './KnowledgeGraphDemo';
-import { COURSE_GRAPHS } from './courseGraphs';
-import { DESKTOP_VIEW, MOBILE_VIEW } from './layout';
+import { COURSE_GRAPHS, TIER_COLOR } from './courseGraphs';
+import { DESKTOP_VIEW, MOBILE_VIEW, viewBoxAttr } from './layout';
 import { __resetReducedMotionStoreForTests } from '@/lib/usePrefersReducedMotion';
 import { __resetMediaStoresForTests } from '@/lib/useIsMobile';
 
@@ -544,7 +544,7 @@ describe('KnowledgeGraphDemo — mobile viewBox (#344 review #3)', () => {
     installViewport(true);
     render(<KnowledgeGraphDemo />);
     const svg = screen.getByTestId('landing-graph-svg');
-    expect(svg.getAttribute('viewBox')).toBe(`0 0 ${MOBILE_VIEW.w} ${MOBILE_VIEW.h}`);
+    expect(svg.getAttribute('viewBox')).toBe(viewBoxAttr(MOBILE_VIEW.fit));
     expect(svg.querySelector('text')!.getAttribute('font-size')).toBe(String(MOBILE_VIEW.font));
   });
 
@@ -552,7 +552,82 @@ describe('KnowledgeGraphDemo — mobile viewBox (#344 review #3)', () => {
     installViewport(false);
     render(<KnowledgeGraphDemo />);
     const svg = screen.getByTestId('landing-graph-svg');
-    expect(svg.getAttribute('viewBox')).toBe(`0 0 ${DESKTOP_VIEW.w} ${DESKTOP_VIEW.h}`);
+    expect(svg.getAttribute('viewBox')).toBe(viewBoxAttr(DESKTOP_VIEW.fit));
     expect(svg.querySelector('text')!.getAttribute('font-size')).toBe(String(DESKTOP_VIEW.font));
   });
+
+  /**
+   * #344 visual 3 — the frame is DERIVED from the content, never written down.
+   * A regression to a hardcoded box is the whole finding, so pin that what the
+   * component emits is what `fitViewBox` produced and that it is materially
+   * tighter than the layout box it replaced.
+   */
+  it('renders the fitted frame, not the layout box', () => {
+    installViewport(false);
+    render(<KnowledgeGraphDemo />);
+    const svg = screen.getByTestId('landing-graph-svg');
+    expect(svg.getAttribute('viewBox')).not.toBe(`0 0 ${DESKTOP_VIEW.w} ${DESKTOP_VIEW.h}`);
+    expect(DESKTOP_VIEW.fit.w).toBeLessThan(DESKTOP_VIEW.w);
+    // The fit only pays off with a width cap: stretched across the full
+    // container a tighter box would render the graph at 2× and make the
+    // section TALLER. Left-aligned + capped is the composition fix (visual 5).
+    expect(svg.getAttribute('class')).toContain('md:max-w-[720px]');
+  });
+});
+
+/**
+ * #344 visual 1, 2, 4 — brand conformance and legibility of the drawn nodes.
+ */
+describe('KnowledgeGraphDemo — node paint and label placement', () => {
+  function nodeGroup(id: string) {
+    return screen.getByTestId(`landing-graph-node-${id}`);
+  }
+
+  it('paints concept nodes with the canonical --state-* tokens', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+    for (const n of g.nodes) {
+      if (n.id === g.rootId) continue;
+      const fill = nodeGroup(n.id).querySelector('circle')!.getAttribute('fill');
+      expect(fill, n.id).toBe(TIER_COLOR[n.tier]);
+      expect(fill, n.id).toMatch(/^var\(--state-/);
+    }
+  });
+
+  it('paints the course root as the brand anchor, not as a mastery status', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+    // The fixture tier stays `learning` — this is a render decision, and the
+    // amber it used to inherit made the section's focal point read as a warning.
+    expect(g.nodes.find((n) => n.id === g.rootId)!.tier).toBe('learning');
+    expect(nodeGroup(g.rootId).querySelector('circle')!.getAttribute('fill')).toBe(
+      'var(--brand-forest)',
+    );
+  });
+
+  it('places the root label above the node and concept labels below theirs', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+
+    const rootGroup = nodeGroup(g.rootId);
+    const rootCy = Number(rootGroup.querySelector('circle')!.getAttribute('cy'));
+    const rootBaseline = Number(rootGroup.querySelector('text')!.getAttribute('y'));
+    // Below the root is where the outer-ring → depth-1 edge crosses its x.
+    expect(rootBaseline).toBeLessThan(rootCy - DESKTOP_VIEW.rootR);
+
+    const leaf = g.nodes.find((n) => n.id !== g.rootId)!;
+    const leafGroup = nodeGroup(leaf.id);
+    const leafCy = Number(leafGroup.querySelector('circle')!.getAttribute('cy'));
+    const leafBaseline = Number(leafGroup.querySelector('text')!.getAttribute('y'));
+    expect(leafBaseline).toBeGreaterThan(leafCy + DESKTOP_VIEW.nodeR);
+  });
+
+  it('halos label text in the section backdrop so edges break around it', () => {
+    render(<KnowledgeGraphDemo />);
+    const label = nodeGroup(COURSE_GRAPHS[0].rootId).querySelector('text')!;
+    expect(label.getAttribute('stroke')).toBe('var(--bg-mesh)');
+    expect(Number(label.getAttribute('stroke-width'))).toBe(DESKTOP_VIEW.labelHalo);
+    // Stroke UNDER fill — the other paint order would outline the glyphs.
+    expect((label as unknown as SVGTextElement).style.paintOrder).toBe('stroke');
+  });
 });
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index 8c904ad7..ac83a537 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -6,12 +6,14 @@ import { IS_TEST_MODE, now } from '@/lib/testMode';
 import { useIsMobile } from '@/lib/useIsMobile';
 import { usePrefersReducedMotion } from '@/lib/usePrefersReducedMotion';
 
-import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph } from './courseGraphs';
+import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph, type DemoNode } from './courseGraphs';
 import {
   DESKTOP_VIEW,
   MOBILE_VIEW,
   helixEntry,
+  labelBaselineY,
   radialLayout,
+  viewBoxAttr,
   type GraphView,
   type Point,
 } from './layout';
@@ -58,6 +60,21 @@ function nodeRadius(view: GraphView, g: CourseGraph, id: string): number {
   return id === g.rootId ? view.rootR : view.nodeR;
 }
 
+/**
+ * The root is an ANCHOR, not a status (#344 visual 2).
+ *
+ * Its fixture tier is `learning`, so it used to render in the progress amber —
+ * which made the stem the whole graph hangs from, and the largest object in the
+ * section, look like a warning. `--brand-forest` is the brand primary and the
+ * hero's logo colour, so the course node reads as "this is the course" while
+ * colour keeps carrying mastery meaning where it actually means something: the
+ * concept nodes. The fixture `tier` field is untouched — this is a render
+ * decision, not a data change.
+ */
+function nodeFill(g: CourseGraph, node: DemoNode): string {
+  return node.id === g.rootId ? 'var(--brand-forest)' : TIER_COLOR[node.tier];
+}
+
 /**
  * Renders one course's edges + nodes, animating them in along the helical
  * entry path (#344). The parent keys this by `graph.id`, so picking another
@@ -175,14 +192,28 @@ function AssemblingGraph({
             onMouseEnter={() => onNodeEnter(n.id)}
             onMouseLeave={onNodeLeave}
           >
-            <circle cx={h.x} cy={h.y} r={r * h.scale} fill={TIER_COLOR[n.tier]} />
+            <circle cx={h.x} cy={h.y} r={r * h.scale} fill={nodeFill(graph, n)} />
+            {/*
+              Labels sit ON the edge mesh — `Trees` and `Big-O` crowd their own
+              connecting lines, and until the root's label moved above the node
+              it lay along the outer-ring → depth-1 diagonal (#344 visual 4).
+              `paint-order: stroke` lays a halo in the section's own backdrop
+              colour under the glyphs and paints the fill over it, so a line
+              passing behind a word breaks around the letterforms instead of
+              running through them. One element, existing token, no backdrop
+              filter — the brand's hard "no frosted panels" line holds.
+            */}
             <text
               x={h.x}
-              y={h.y + r + view.labelGap}
+              y={labelBaselineY(view, n.id === graph.rootId, h.y, r)}
               textAnchor="middle"
               className="font-jetbrains"
               fontSize={view.font}
               fill="var(--text-dim)"
+              stroke="var(--bg-mesh)"
+              strokeWidth={view.labelHalo}
+              strokeLinejoin="round"
+              style={{ paintOrder: 'stroke' }}
               opacity={h.opacity}
             >
               {n.label}
@@ -229,14 +260,15 @@ export default function KnowledgeGraphDemo() {
     [courseId],
   );
 
-  // #344 review #3: one 900×560 viewBox rendered at every width put 4.6 CSS px
-  // labels on a 390px phone. `useIsMobile` is the same `useSyncExternalStore`
-  // shape as `usePrefersReducedMotion` — SSR-safe, no render-body matchMedia
-  // read — so the server (and the hydrating render) picks the desktop view and
-  // the phone corrects on the first commit after hydration. A viewBox is not
-  // something a CSS `@media` rule can swap, so that one-frame correction is the
-  // floor here; both views render the complete graph, so it is a resize, never
-  // a blank.
+  // #344 review #3: one viewBox rendered at every width put 4.6 CSS px labels
+  // on a 390px phone. Each view now carries its own DERIVED frame (`view.fit`,
+  // #344 visual 3) alongside its own type scale. `useIsMobile` is the same
+  // `useSyncExternalStore` shape as `usePrefersReducedMotion` — SSR-safe, no
+  // render-body matchMedia read — so the server (and the hydrating render)
+  // picks the desktop view and the phone corrects on the first commit after
+  // hydration. A viewBox is not something a CSS `@media` rule can swap, so that
+  // one-frame correction is the floor here; both views render the complete
+  // graph, so it is a resize, never a blank.
   const view = useIsMobile() ? MOBILE_VIEW : DESKTOP_VIEW;
   const points = useMemo(
     () => radialLayout(graph, view.w, view.h, view.maxRadius),
@@ -328,10 +360,29 @@ export default function KnowledgeGraphDemo() {
           })}
         </div>
 
+        {/*
+          #344 visual 3 + 5, which have to be solved together.
+
+          The frame is now measured off the content (`view.fit`) instead of the
+          hardcoded `0 0 900 560`, which drops 36% of dead margin off the box.
+          But a tight box stretched to the full 1184px container would render
+          the graph at 2× and make the section TALLER, not shorter — the fit only
+          pays off with a width cap. Capping also settles the composition: the
+          section's eyebrow, headline and chips are left-aligned on the container
+          grid while the graph was centred inside a full-bleed box one viewport
+          below a hero that is centred and symmetric, so it read as an accident.
+          Left-aligning the graph to the same grid line commits to the editorial
+          direction the rest of the section already uses, and it is the reversible
+          half of the choice: no copy moves, no structure changes.
+
+          At the 720px cap the desktop graph draws at ~1.25 units per CSS px —
+          within a hair of the 1.32 it rendered at before — in a 720×621 box
+          where the fixed viewBox reserved 1184×737.
+        */}
         <svg
           data-testid="landing-graph-svg"
-          viewBox={`0 0 ${view.w} ${view.h}`}
-          className="mt-8 w-full h-auto"
+          viewBox={viewBoxAttr(view.fit)}
+          className="mt-8 w-full max-w-[420px] md:max-w-[720px] h-auto"
           role="img"
           aria-label={`${graph.name} concept graph`}
         >
diff --git a/frontend/src/components/marketing/graph/courseGraphs.test.ts b/frontend/src/components/marketing/graph/courseGraphs.test.ts
index c00091ab..37272e01 100644
--- a/frontend/src/components/marketing/graph/courseGraphs.test.ts
+++ b/frontend/src/components/marketing/graph/courseGraphs.test.ts
@@ -78,8 +78,34 @@ describe('COURSE_GRAPHS', () => {
     (_code, g) => {
       for (const n of g.nodes) {
         expect(n.blurb.length).toBeGreaterThan(0);
-        expect(TIER_COLOR[n.tier]).toMatch(/^#/);
+        expect(TIER_COLOR[n.tier]).toBeDefined();
       }
     },
   );
 });
+
+/**
+ * #344 visual 1 — this file shipped a FOURTH inlined copy of the mastery
+ * palette (`#1B6C42` / `#D97706` / `#EF4444` / `#9CA3AF`), so the landing page
+ * advertised different mastery colours than the product it advertises.
+ * globals.css:80-89 declares the canonical set and calls itself the "Single
+ * source for the 3 previously-inlined copies in Dashboard / Tree / notetaker".
+ *
+ * The old assertion here was `toMatch(/^#/)` — which is what let four wrong
+ * literals through in the first place. Any hex now fails outright.
+ */
+describe('TIER_COLOR', () => {
+  it('consumes the canonical --state-* tokens, never a literal', () => {
+    expect(TIER_COLOR).toEqual({
+      mastered: 'var(--state-mastery)',
+      learning: 'var(--state-progress)',
+      struggling: 'var(--state-struggle)',
+      unexplored: 'var(--state-neutral)',
+    });
+  });
+
+  it.each(Object.entries(TIER_COLOR))('%s is a token reference', (_tier, value) => {
+    expect(value).toMatch(/^var\(--state-[a-z]+\)$/);
+    expect(value).not.toMatch(/#/);
+  });
+});
diff --git a/frontend/src/components/marketing/graph/courseGraphs.ts b/frontend/src/components/marketing/graph/courseGraphs.ts
index e0e879c5..0b9856d8 100644
--- a/frontend/src/components/marketing/graph/courseGraphs.ts
+++ b/frontend/src/components/marketing/graph/courseGraphs.ts
@@ -11,12 +11,27 @@
 
 export type MasteryTier = 'mastered' | 'learning' | 'struggling' | 'unexplored';
 
-/** Matches the hero's floating legend card and the app's node colours. */
+/**
+ * The canonical knowledge-status palette — the SAME tokens the product uses.
+ *
+ * globals.css:80-89 declares these as the "Single source for the 3
+ * previously-inlined copies in Dashboard / Tree / notetaker", and the app reads
+ * them under exactly the four tier names below (notetaker/page.tsx,
+ * screens/Dashboard.tsx, screens/Learn.tsx). This file shipped a FOURTH inlined
+ * copy with four different literals — `#1B6C42` / `#D97706` / `#EF4444` /
+ * `#9CA3AF` — so the landing page advertised different mastery colours than the
+ * product it advertises, and the saturated amber root plus a `#EF4444` that
+ * reads as an error state were the loudest objects on a page whose brand
+ * atmosphere is "barely-there … like the glow under water" (#344 visual 1).
+ *
+ * Tokens, not hexes, on purpose: a future palette move lands here for free, and
+ * the hero's floating legend card ((public)/page.tsx) now reads the same four.
+ */
 export const TIER_COLOR: Record<MasteryTier, string> = {
-  mastered: '#1B6C42',
-  learning: '#D97706',
-  struggling: '#EF4444',
-  unexplored: '#9CA3AF',
+  mastered: 'var(--state-mastery)',
+  learning: 'var(--state-progress)',
+  struggling: 'var(--state-struggle)',
+  unexplored: 'var(--state-neutral)',
 };
 
 export interface DemoNode {
@@ -98,7 +113,14 @@ export const COURSE_GRAPHS: CourseGraph[] = [
       { id: 'sm-root', label: 'SM 275', tier: 'learning', blurb: 'Statistics — 21 concepts mapped from your syllabus', children: ['sm-prob', 'sm-dist', 'sm-testing'] },
       { id: 'sm-prob', label: 'Probability', tier: 'mastered', blurb: 'Sample spaces, events, and conditioning', children: ['sm-bayes'] },
       { id: 'sm-dist', label: 'Distributions', tier: 'learning', blurb: 'Shapes that recur across real data', children: ['sm-clt'] },
-      { id: 'sm-testing', label: 'Hypothesis Tests', tier: 'struggling', blurb: 'What a p-value does and does not claim', children: [] },
+      // "Hypothesis Tests" was 16 characters — three more than any other label
+      // in any fixture, and the widest object in the phone layout by a margin.
+      // At the 390px breakpoint it overlapped its sibling "Distributions" by
+      // ~21 CSS px of solid text (#344 visual 4, "worse at 390px"), and no
+      // legible mobile type scale can separate them: the two labels need
+      // 0.6·font·29/2 units of room against a ring that only yields 1.732·ring.
+      // Shortening the label is the proportionate fix — not a collision solver.
+      { id: 'sm-testing', label: 'p-Values', tier: 'struggling', blurb: 'What a p-value does and does not claim', children: [] },
       { id: 'sm-bayes', label: 'Bayes', tier: 'learning', blurb: 'Updating belief as evidence arrives', children: [] },
       { id: 'sm-clt', label: 'Central Limit', tier: 'unexplored', blurb: 'Why sample means go normal', children: [] },
     ],
diff --git a/frontend/src/components/marketing/graph/layout.test.ts b/frontend/src/components/marketing/graph/layout.test.ts
index 85581b92..3fc6ad73 100644
--- a/frontend/src/components/marketing/graph/layout.test.ts
+++ b/frontend/src/components/marketing/graph/layout.test.ts
@@ -11,8 +11,11 @@ import {
   GRAPH_VIEWS,
   MOBILE_VIEW,
   easeOutCubic,
+  fitViewBox,
   helixEntry,
+  labelBaselineY,
   radialLayout,
+  viewBoxAttr,
 } from './layout';
 
 const G = COURSE_GRAPHS[0];
@@ -121,6 +124,36 @@ describe('helixEntry', () => {
   });
 });
 
+/**
+ * Labels render in JetBrains Mono, whose advance width is 600/1000 em. The text
+ * is `textAnchor="middle"`, so half the string hangs off each side of the
+ * node's x. Restated here rather than imported from `layout.ts` so the sweep
+ * below stays an independent measurement of the frame the fit produced.
+ */
+const MONO_ADVANCE_EM = 0.6;
+
+/** Everything a node draws at one instant: its dot, and its label box. */
+function drawnExtent(
+  view: (typeof GRAPH_VIEWS)[number],
+  label: string,
+  isRoot: boolean,
+  x: number,
+  y: number,
+  r: number,
+  scale: number,
+) {
+  const dotR = r * scale;
+  const half = (label.length * MONO_ADVANCE_EM * view.font) / 2 + view.labelHalo / 2;
+  const baseline = labelBaselineY(view, isRoot, y, r);
+  return {
+    left: Math.min(x - dotR, x - half),
+    right: Math.max(x + dotR, x + half),
+    // 0.73em of cap height above the baseline, 0.25em of descender below it.
+    top: Math.min(y - dotR, baseline - view.font * 0.73 - view.labelHalo / 2),
+    bottom: Math.max(y + dotR, baseline + view.font * 0.25 + view.labelHalo / 2),
+  };
+}
+
 /**
  * #344 review #4 — the bug this file should have caught during development.
  *
@@ -130,52 +163,201 @@ describe('helixEntry', () => {
  * back in at opacity ≈ 0.5 — plainly visible, and invisible in review only
  * because the animation was also playing off-screen (review #1).
  *
+ * Retargeted at the DERIVED frame (#344 visual 3): the viewBox is no longer a
+ * hardcoded `0 0 900 560` with room to spare, it is fitted to this very sweep,
+ * so "does the frame still contain the assembly" is now a question about the
+ * fit — and a too-small pad, a stale fit, or a hand-written viewBox all land
+ * here.
+ *
  * So: sweep `t` across the whole entry for every node of every fixture in every
- * view, and assert that the drawn extent — circle, and label baseline — never
- * leaves the viewBox.
+ * view, and assert that the drawn extent — circle, label, halo — never leaves
+ * the fitted box.
  */
-describe('helixEntry × radialLayout — nothing leaves the viewBox', () => {
-  /**
-   * Labels render in JetBrains Mono, whose advance width is 600/1000 em. The
-   * text is `textAnchor="middle"`, so half the string hangs off each side of
-   * the node's x. This is the constraint that actually sizes the mobile view:
-   * the outer ring sits on the horizontal axis, so its labels are the first
-   * thing that would run off the right edge.
-   */
-  const MONO_ADVANCE_EM = 0.6;
+describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', () => {
   const STEPS = 400;
 
   for (const view of GRAPH_VIEWS) {
     for (const graph of COURSE_GRAPHS) {
-      it(`${graph.id} stays inside ${view.w}×${view.h} across the whole sweep`, () => {
+      it(`${graph.id} stays inside ${viewBoxAttr(view.fit)} across the whole sweep`, () => {
         const points = radialLayout(graph, view.w, view.h, view.maxRadius);
         const centre = { x: view.w / 2, y: view.h / 2 };
+        const { x, y, w, h } = view.fit;
 
         for (const n of graph.nodes) {
           const p = points.get(n.id)!;
-          const r = n.id === graph.rootId ? view.rootR : view.nodeR;
-          const halfLabel = (n.label.length * MONO_ADVANCE_EM * view.font) / 2;
+          const isRoot = n.id === graph.rootId;
+          const r = isRoot ? view.rootR : view.nodeR;
 
           for (let i = 0; i <= STEPS; i++) {
             const t = i / STEPS;
-            const h = helixEntry(p, centre, t);
-            const dotR = r * h.scale;
+            const f = helixEntry(p, centre, t);
+            const e = drawnExtent(view, n.label, isRoot, f.x, f.y, r, f.scale);
             const where = `${graph.id}/${n.id} @ t=${t.toFixed(3)}`;
 
-            // Circle.
-            expect(h.x - dotR, `${where} left`).toBeGreaterThanOrEqual(0);
-            expect(h.x + dotR, `${where} right`).toBeLessThanOrEqual(view.w);
-            expect(h.y - dotR, `${where} top`).toBeGreaterThanOrEqual(0);
-            expect(h.y + dotR, `${where} bottom`).toBeLessThanOrEqual(view.h);
+            expect(e.left, `${where} left`).toBeGreaterThanOrEqual(x);
+            expect(e.right, `${where} right`).toBeLessThanOrEqual(x + w);
+            expect(e.top, `${where} top`).toBeGreaterThanOrEqual(y);
+            expect(e.bottom, `${where} bottom`).toBeLessThanOrEqual(y + h);
+          }
+        }
+      });
+    }
+  }
 
-            // Label: baseline sits at `y + r + labelGap`; leave a descender's
-            // worth (0.25em) of room under it.
+  /**
+   * The assertion above is only worth anything if the sweep actually needs the
+   * headroom — otherwise a lazy "fit to the settled node positions" would pass
+   * it, and that is precisely the clipping bug. So: prove the sweep leaves the
+   * settled bounding box. `helixEntry` rotates a node up to 1.5 turns on the way
+   * in, and the outer ring rests on the horizontal axis, so it passes ~0.925 ×
+   * maxRadius above and below the centre at ~83% opacity — 215 desktop units,
+   * against a settled vertical extent of 58.
+   */
+  for (const view of GRAPH_VIEWS) {
+    it(`the ${view.maxRadius}-radius sweep leaves the settled bounding box`, () => {
+      const centre = { x: view.w / 2, y: view.h / 2 };
+      let settledTop = Infinity;
+      let settledBottom = -Infinity;
+      let sweptTop = Infinity;
+      let sweptBottom = -Infinity;
+
+      for (const graph of COURSE_GRAPHS) {
+        const points = radialLayout(graph, view.w, view.h, view.maxRadius);
+        for (const n of graph.nodes) {
+          const p = points.get(n.id)!;
+          const isRoot = n.id === graph.rootId;
+          const r = isRoot ? view.rootR : view.nodeR;
+
+          const rest = drawnExtent(view, n.label, isRoot, p.x, p.y, r, 1);
+          settledTop = Math.min(settledTop, rest.top);
+          settledBottom = Math.max(settledBottom, rest.bottom);
+
+          for (let i = 0; i <= 400; i++) {
+            const f = helixEntry(p, centre, i / 400);
+            const e = drawnExtent(view, n.label, isRoot, f.x, f.y, r, f.scale);
+            sweptTop = Math.min(sweptTop, e.top);
+            sweptBottom = Math.max(sweptBottom, e.bottom);
+          }
+        }
+      }
+
+      expect(sweptTop).toBeLessThan(settledTop);
+      expect(sweptBottom).toBeGreaterThan(settledBottom);
+      // Comfortably, not marginally: the sweep needs ~2× the settled height.
+      expect(sweptBottom - sweptTop).toBeGreaterThan(1.5 * (settledBottom - settledTop));
+      // …and the fitted frame is sized for the sweep, not for the rest state.
+      expect(view.fit.h).toBeGreaterThanOrEqual(sweptBottom - sweptTop);
+    });
+  }
+});
+
+/**
+ * #344 visual 3 — the fit is computed ONCE across all three fixtures, not per
+ * graph. The `<svg>` is `h-auto`, so a per-graph box would change the section's
+ * height every time a visitor clicked a course chip.
+ */
+describe('fitViewBox — one stable frame for every course', () => {
+  for (const view of GRAPH_VIEWS) {
+    it(`${viewBoxAttr(view.fit)} contains every single-course fit`, () => {
+      for (const graph of COURSE_GRAPHS) {
+        const solo = fitViewBox([graph], view);
+        expect(solo.x, graph.id).toBeGreaterThanOrEqual(view.fit.x);
+        expect(solo.y, graph.id).toBeGreaterThanOrEqual(view.fit.y);
+        expect(solo.x + solo.w, graph.id).toBeLessThanOrEqual(view.fit.x + view.fit.w);
+        expect(solo.y + solo.h, graph.id).toBeLessThanOrEqual(view.fit.y + view.fit.h);
+      }
+    });
+  }
+
+  it('is measured off the content, not the layout box', () => {
+    // The shipped bug: `viewBox="0 0 900 560"` around content 578 units wide.
+    expect(DESKTOP_VIEW.fit.w).toBeLessThan(DESKTOP_VIEW.w);
+    expect(DESKTOP_VIEW.fit.h).toBeLessThan(DESKTOP_VIEW.h);
+    expect(viewBoxAttr(DESKTOP_VIEW.fit)).toBe('159 42 578 498');
+    expect(viewBoxAttr(MOBILE_VIEW.fit)).toBe('-19 5 394 319');
+  });
+});
+
+/**
+ * #344 visual 4 — labels must not land on top of each other, on another node's
+ * dot, or on an edge they have nothing to do with.
+ *
+ * A node's OWN edges are excluded: they radiate from the dot the label belongs
+ * to, so a short crossing is unavoidable and is exactly what the halo is for.
+ * Everything else is a real collision, and the phone breakpoint was losing this
+ * before the retune — "Distributions" and "Hypothesis Tests" overlapped by ~21
+ * CSS px of solid text at 390px.
+ *
+ * Deliberately measured against the dot's bounding SQUARE, i.e. pessimistically:
+ * clearing the square clears the circle.
+ */
+describe('settled frame — no foreign label collisions', () => {
+  type Box = { l: number; r: number; t: number; b: number };
+  /** Signed separation: negative means the boxes overlap. */
+  const gap = (a: Box, z: Box) =>
+    Math.max(z.l - a.r, a.l - z.r, z.t - a.b, a.t - z.b);
+
+  /** The label alone — `drawnExtent` unions in the dot, which is not wanted here. */
+  function labelBox(
+    view: (typeof GRAPH_VIEWS)[number],
+    label: string,
+    isRoot: boolean,
+    p: { x: number; y: number },
+    r: number,
+  ): Box {
+    const half = (label.length * MONO_ADVANCE_EM * view.font) / 2 + view.labelHalo / 2;
+    const baseline = labelBaselineY(view, isRoot, p.y, r);
+    return {
+      l: p.x - half,
+      r: p.x + half,
+      t: baseline - view.font * 0.73 - view.labelHalo / 2,
+      b: baseline + view.font * 0.25 + view.labelHalo / 2,
+    };
+  }
+
+  for (const view of GRAPH_VIEWS) {
+    for (const graph of COURSE_GRAPHS) {
+      it(`${graph.id} at maxRadius ${view.maxRadius} keeps every label clear`, () => {
+        const pts = radialLayout(graph, view.w, view.h, view.maxRadius);
+        const radius = (id: string) => (id === graph.rootId ? view.rootR : view.nodeR);
+        const boxes = new Map(
+          graph.nodes.map((n) => [
+            n.id,
+            labelBox(view, n.label, n.id === graph.rootId, pts.get(n.id)!, radius(n.id)),
+          ]),
+        );
+
+        for (const a of graph.nodes) {
+          for (const b of graph.nodes) {
+            if (a.id === b.id) continue;
+            // label ↔ label
+            expect(
+              gap(boxes.get(a.id)!, boxes.get(b.id)!),
+              `${a.id} label vs ${b.id} label`,
+            ).toBeGreaterThan(0);
+            // label ↔ someone else's dot
+            const p = pts.get(b.id)!;
+            const r = radius(b.id);
             expect(
-              h.y + r + view.labelGap + view.font * 0.25,
-              `${where} label baseline`,
-            ).toBeLessThanOrEqual(view.h);
-            expect(h.x - halfLabel, `${where} label left`).toBeGreaterThanOrEqual(0);
-            expect(h.x + halfLabel, `${where} label right`).toBeLessThanOrEqual(view.w);
+              gap(boxes.get(a.id)!, { l: p.x - r, r: p.x + r, t: p.y - r, b: p.y + r }),
+              `${a.id} label vs ${b.id} dot`,
+            ).toBeGreaterThan(0);
+          }
+
+          // label ↔ an edge it is not an endpoint of
+          for (const e of graph.edges) {
+            if (e.source === a.id || e.target === a.id) continue;
+            const p1 = pts.get(e.source)!;
+            const p2 = pts.get(e.target)!;
+            const box = boxes.get(a.id)!;
+            let closest = Infinity;
+            for (let i = 0; i <= 400; i++) {
+              const t = i / 400;
+              const x = p1.x + (p2.x - p1.x) * t;
+              const y = p1.y + (p2.y - p1.y) * t;
+              closest = Math.min(closest, Math.max(box.l - x, x - box.r, box.t - y, y - box.b));
+            }
+            expect(closest, `${a.id} label vs edge ${e.source}->${e.target}`).toBeGreaterThan(0);
           }
         }
       });
@@ -185,29 +367,39 @@ describe('helixEntry × radialLayout — nothing leaves the viewBox', () => {
 
 /**
  * #344 review #3 — the demo was one 900×560 viewBox at every width, which at a
- * 390px phone viewport (342px content box after `px-6`) is a uniform 0.38 scale:
- * 4.6 CSS px labels and 10.6 CSS px dots. These pin the sizes the mobile view
- * actually resolves to, in the units a visitor sees.
+ * 390px phone viewport is a uniform 0.38 scale: 4.6 CSS px labels and 10.6 CSS
+ * px dots. These pin the sizes the mobile view actually resolves to, in the
+ * units a visitor sees — and they are the unit-test twin of the Playwright gate
+ * in `e2e/landing-graph.spec.ts` (≥11px labels, ≥20px dots, >260px tall).
  */
 describe('GraphView sizing at a 390px viewport', () => {
-  /** 390px viewport − `px-6` (24px each side) = the section's content box. */
-  const CONTENT_PX = 390 - 48;
+  /**
+   * 390px viewport − `px-6` (24px each side) − the 10px scrollbar globals.css
+   * paints (`*::-webkit-scrollbar { width: 10px }`) = the section's content
+   * box. Deliberately the pessimistic number: the E2E measures the real
+   * `getBoundingClientRect().width`, so modelling it 10px narrower keeps this
+   * test the stricter of the two.
+   */
+  const CONTENT_PX = 390 - 48 - 10;
 
   it('renders legible labels and dots on a phone', () => {
-    const scale = CONTENT_PX / MOBILE_VIEW.w;
-    expect(scale).toBeCloseTo(0.95, 4);
-    // 12.35 CSS px labels (was 4.56), 22.8 CSS px dot diameter (was 10.64),
-    // 285 CSS px of graph height (was 213).
+    const scale = CONTENT_PX / MOBILE_VIEW.fit.w;
+    expect(scale).toBeCloseTo(0.8426, 4);
+    // 11.8 CSS px labels (was 4.56), 23.6 CSS px dot diameter (was 10.64),
+    // 269 CSS px of graph height (was 213).
     expect(MOBILE_VIEW.font * scale).toBeGreaterThanOrEqual(11);
     expect(2 * MOBILE_VIEW.nodeR * scale).toBeGreaterThanOrEqual(20);
-    expect(MOBILE_VIEW.h * scale).toBeGreaterThanOrEqual(260);
+    expect(MOBILE_VIEW.fit.h * scale).toBeGreaterThanOrEqual(260);
   });
 
-  it('documents what the desktop view resolved to on the same phone', () => {
-    // Not an aspiration — the numbers the bug produced, kept here so a future
-    // "just use one viewBox everywhere" change has to argue with them.
-    const scale = CONTENT_PX / DESKTOP_VIEW.w;
-    expect(DESKTOP_VIEW.font * scale).toBeLessThan(5); // 4.56 CSS px labels
-    expect(DESKTOP_VIEW.h * scale).toBeLessThan(220); // 212.8 CSS px tall
+  it('documents why the desktop view is still not a phone view', () => {
+    // Not an aspiration — the reason `useIsMobile` swaps views at all, kept
+    // here so a future "just use one viewBox everywhere" change has to argue
+    // with it. The fit shrank the desktop box from 900 to 578 units, which
+    // lifts a phone-rendered desktop label from 4.6 to 6.9 CSS px — still
+    // nowhere near the 11px floor above.
+    const scale = CONTENT_PX / DESKTOP_VIEW.fit.w;
+    expect(DESKTOP_VIEW.font * scale).toBeLessThan(11);
+    expect(2 * DESKTOP_VIEW.nodeR * scale).toBeLessThan(20);
   });
 });
diff --git a/frontend/src/components/marketing/graph/layout.ts b/frontend/src/components/marketing/graph/layout.ts
index 9cb330c0..d7c04ee2 100644
--- a/frontend/src/components/marketing/graph/layout.ts
+++ b/frontend/src/components/marketing/graph/layout.ts
@@ -5,30 +5,50 @@
  * parks the animation and asserts against the laid-out frame, so the same graph
  * and viewport must always produce the same coordinates.
  */
-import type { CourseGraph } from './courseGraphs';
+import { COURSE_GRAPHS, type CourseGraph } from './courseGraphs';
 
 export interface Point {
   x: number;
   y: number;
 }
 
+/** An SVG `viewBox`, in user units. */
+export interface ViewBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/**
+ * Labels render in JetBrains Mono, whose advance width is 600/1000 em, and the
+ * face's cap height / descender depth are ~0.73 / ~0.25 em. These are font
+ * facts, shared by the viewBox fit below and by `layout.test.ts`'s independent
+ * bounds sweep, so the two can't drift apart on a rounding tweak.
+ */
+export const MONO_ADVANCE_EM = 0.6;
+export const LABEL_CAP_EM = 0.73;
+export const LABEL_DESCENDER_EM = 0.25;
+
 /**
  * Everything the demo needs to draw itself at one viewport class, in SVG user
- * units. The `<svg>` is `width: 100%`, so the rendered CSS size of *every*
- * dimension below is `value * (renderedWidth / w)` — which is exactly why the
- * desktop numbers can't just be reused on a phone: at a 390px viewport the
- * section's content box is 342px, so the 900-wide desktop viewBox renders at
- * 0.38 scale and a 12-unit label lands at 4.6 CSS px (#344 review #3).
+ * units. The `<svg>` is `width: 100%` up to a max-width, so the rendered CSS
+ * size of *every* dimension below is `value * (renderedWidth / fit.w)`.
+ *
+ * `w` / `h` are the LAYOUT box: they exist only to place the centre that
+ * `radialLayout` orbits (`w / 2`, `h / 2`) and to keep the desktop geometry
+ * byte-identical to what this branch was designed against. They are NOT what
+ * gets rendered — see `fit` below.
  *
  * The two views are picked apart by `useIsMobile()` in the component. Keeping
  * them as data (rather than a pile of ternaries at each call site) is what lets
- * `layout.test.ts` sweep the entry animation against *both* viewBoxes and prove
+ * `layout.test.ts` sweep the entry animation against *both* views and prove
  * nothing leaves frame.
  */
-export interface GraphView {
-  /** viewBox width, user units. */
+export interface GraphGeometry {
+  /** Layout-box width, user units. Sets the orbit centre, not the frame. */
   w: number;
-  /** viewBox height, user units. */
+  /** Layout-box height, user units. Sets the orbit centre, not the frame. */
   h: number;
   /** Radius of the outermost ring — the layout's whole spatial budget. */
   maxRadius: number;
@@ -38,50 +58,30 @@ export interface GraphView {
   rootR: number;
   /** Non-root node circle radius, user units. */
   nodeR: number;
-  /** Baseline offset of a node's label below the node centre + its radius. */
+  /** Gap between a node's circle edge and its label baseline, either way up. */
   labelGap: number;
+  /**
+   * Whether the root's label sits ABOVE its circle instead of below it
+   * (#344 visual 4). Per view, because it is a geometry question, not a taste
+   * one — see `labelBaselineY`.
+   */
+  rootLabelAbove: boolean;
+  /** Width of the paper-coloured halo stroked under label text. */
+  labelHalo: number;
   /** Edge stroke width, user units. */
   edgeW: number;
+  /** Breathing room added on every side of the fitted content box. */
+  fitPad: number;
 }
 
-/**
- * `maxRadius: 232` is byte-identical to what `radialLayout`'s old default
- * (`min(900, 560) / 2 - 48`) produced, so the desktop frame this branch was
- * designed and reviewed against is unchanged.
- */
-export const DESKTOP_VIEW: GraphView = {
-  w: 900,
-  h: 560,
-  maxRadius: 232,
-  font: 12,
-  rootR: 26,
-  nodeR: 14,
-  labelGap: 16,
-  edgeW: 1.4,
-};
-
-/**
- * Portrait-ish and much smaller in user units, so a phone's ~342px content box
- * renders it at 0.95 scale instead of 0.38: 13-unit labels land at 12.4 CSS px
- * and non-root dots at a 22.8px diameter (#344 review #3).
- *
- * `maxRadius: 108` is set by the *labels*, not the dots: the outer ring sits on
- * the horizontal axis, so the widest label ("Central Limit", 13 chars) has to
- * clear the right edge — 180 + 108 + (13 × 0.6 × 13) / 2 = 338.7 of 360.
- */
-export const MOBILE_VIEW: GraphView = {
-  w: 360,
-  h: 300,
-  maxRadius: 108,
-  font: 13,
-  rootR: 22,
-  nodeR: 12,
-  labelGap: 16,
-  edgeW: 1.6,
-};
-
-/** Every view the demo can render in — the sweep target for the bounds test. */
-export const GRAPH_VIEWS: GraphView[] = [DESKTOP_VIEW, MOBILE_VIEW];
+/** A geometry plus the viewBox derived from it. This is what the demo renders. */
+export interface GraphView extends GraphGeometry {
+  /**
+   * The rendered `viewBox`, fitted to the actual drawn content across every
+   * fixture (#344 visual 3). Derived, never hand-written — see `fitViewBox`.
+   */
+  fit: ViewBox;
+}
 
 function clamp01(t: number): number {
   return t < 0 ? 0 : t > 1 ? 1 : t;
@@ -99,9 +99,9 @@ export function easeOutCubic(t: number): number {
  *
  * `maxRadius` is the outermost ring's distance from the centre. It defaults to
  * the old inscribed-circle-minus-48 rule so every existing caller and test is
- * unchanged, but the mobile view passes it explicitly: there the binding
- * constraint is label width against the *narrow* edge, not the inscribed
- * circle, and `min(w, h) / 2 - pad` can't express that.
+ * unchanged, but each view passes it explicitly: the binding constraint is the
+ * *fitted* frame, not the layout box, and `min(w, h) / 2 - pad` can't express
+ * that.
  */
 export function radialLayout(
   graph: CourseGraph,
@@ -170,9 +170,8 @@ export function radialLayout(
  * 560 viewBox edge — and crossed back in at opacity ≈ 0.5, so the visitor
  * watched them get chopped off by the `<svg>` viewport mid-assembly. Because
  * the spiral now only ever *contracts*, every point of the sweep lies inside
- * the disc of radius |target − centre|, which is bounded by the static layout
- * that `radialLayout` already fits to the viewBox. `layout.test.ts` pins that
- * as an explicit bounds sweep over every fixture × every view.
+ * the disc of radius |target − centre|. `layout.test.ts` pins that as an
+ * explicit bounds sweep over every fixture × every view.
  *
  * It reads better too: nodes now grow outward from the root rather than flying
  * in from off-frame.
@@ -210,3 +209,214 @@ export function helixEntry(
     opacity: e,
   };
 }
+
+/** Half the drawn width of a label, halo included. Labels are `middle`-anchored. */
+export function labelHalfWidth(label: string, geom: GraphGeometry): number {
+  return (label.length * MONO_ADVANCE_EM * geom.font) / 2 + geom.labelHalo / 2;
+}
+
+/**
+ * Where a node's label baseline sits, relative to the node's drawn centre.
+ *
+ * On DESKTOP the root's label goes above it (#344 visual 4). Below the root is
+ * where the outer-ring → depth-1 edge crosses: in every fixture that edge
+ * passes the root's x at `cy + 0.349 × ring` (desktop: 40.5 units down), which
+ * is exactly the band a `rootR + labelGap` baseline puts the course code in — a
+ * long shallow diagonal straight through "CS 210". Above the root there is only
+ * the short vertical spoke to the top child, which the halo breaks cleanly.
+ *
+ * On MOBILE it stays below, because there the geometry says so. The top child
+ * sits `ring` above the root with its own label hanging back down toward it, so
+ * an above-the-root label only clears it when
+ *
+ *     ring ≥ rootR + nodeR + 2·labelGap + cap + descender
+ *
+ * — 83.8 units at the desktop type scale, against a 116-unit ring: comfortable.
+ * The phone's ring is 66 against a 95.7-unit requirement, so "above" would put
+ * the course code straight through the first concept's label. The crossing
+ * diagonal it would be dodging isn't a problem there anyway: at ring 66 that
+ * edge passes the root's x at `cy + 23.0` and the below-baseline label's cap
+ * top is at `cy + 34.1`, 11 units clear.
+ *
+ * Shared with `fitViewBox` and `layout.test.ts` so the frame can never be
+ * fitted to a label position the component doesn't actually use.
+ */
+export function labelBaselineY(
+  geom: GraphGeometry,
+  isRoot: boolean,
+  y: number,
+  r: number,
+): number {
+  return isRoot && geom.rootLabelAbove ? y - r - geom.labelGap : y + r + geom.labelGap;
+}
+
+/** Vertical extent of the drawn label text, halo included. */
+function labelVerticalExtent(
+  geom: GraphGeometry,
+  isRoot: boolean,
+  y: number,
+  r: number,
+): { top: number; bottom: number } {
+  const baseline = labelBaselineY(geom, isRoot, y, r);
+  return {
+    top: baseline - geom.font * LABEL_CAP_EM - geom.labelHalo / 2,
+    bottom: baseline + geom.font * LABEL_DESCENDER_EM + geom.labelHalo / 2,
+  };
+}
+
+/**
+ * Sampling density of the entry sweep when fitting the frame.
+ *
+ * Finer than the 400 steps `layout.test.ts` sweeps, so the test can never land
+ * between two samples and find a point the fit didn't see. In practice the
+ * extremes sit at the sweep's endpoints and at broad interior maxima, so the
+ * two agree to ~0.01 units — the `fitPad` swallows the rest with room over.
+ */
+const FIT_STEPS = 512;
+
+/**
+ * The tightest box that contains everything the demo ever draws — for every
+ * fixture, for every frame of the entry animation.
+ *
+ * #344 visual 3: the demo shipped with a hardcoded `viewBox="0 0 900 560"`
+ * stretched across a ~1184px container, so it reserved ~737px of height while
+ * the content clustered near the centre and the whole outer band of the box
+ * stayed permanently empty. The frame is now measured off the content instead.
+ *
+ * THE THING TO NOT GET WRONG: fit to the HELIX SWEEP, not to the settled node
+ * positions. `helixEntry` rotates a node up to 1.5 turns around the centre on
+ * the way in, so an outer node whose resting place is on the horizontal axis
+ * passes through `0.925 × maxRadius` ABOVE and BELOW the centre at ~83% opacity
+ * — 215 desktop units against a settled extent of 58. A box fitted to the
+ * settled positions clips the assembly in plain view; that exact bug was found
+ * and fixed once already on this branch (#344 review #4), and `layout.test.ts`
+ * sweeps `t` across the full range to keep it fixed.
+ *
+ * Fitted ONCE across all three fixtures rather than per graph: the three share
+ * a topology and differ only in label widths, so a per-graph fit would produce
+ * three slightly different boxes and — because the `<svg>` is `h-auto` — the
+ * section would change height every time a visitor clicked a course chip. A
+ * jumping section is a worse defect than a few units of slack on the side where
+ * some other course happens to have the longest word.
+ *
+ * The box is snapped OUTWARD to whole units so the rendered `viewBox` attribute
+ * stays readable and rounding can never shave the frame.
+ */
+export function fitViewBox(graphs: CourseGraph[], geom: GraphGeometry): ViewBox {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  const centre = { x: geom.w / 2, y: geom.h / 2 };
+
+  for (const graph of graphs) {
+    const points = radialLayout(graph, geom.w, geom.h, geom.maxRadius);
+    for (const n of graph.nodes) {
+      const p = points.get(n.id);
+      if (!p) continue;
+      const isRoot = n.id === graph.rootId;
+      const r = isRoot ? geom.rootR : geom.nodeR;
+      const half = labelHalfWidth(n.label, geom);
+
+      for (let i = 0; i <= FIT_STEPS; i++) {
+        const h = helixEntry(p, centre, i / FIT_STEPS);
+        const dotR = r * h.scale;
+        const label = labelVerticalExtent(geom, isRoot, h.y, r);
+
+        minX = Math.min(minX, h.x - dotR, h.x - half);
+        maxX = Math.max(maxX, h.x + dotR, h.x + half);
+        minY = Math.min(minY, h.y - dotR, label.top);
+        maxY = Math.max(maxY, h.y + dotR, label.bottom);
+      }
+    }
+  }
+
+  const x = Math.floor(minX - geom.fitPad);
+  const y = Math.floor(minY - geom.fitPad);
+  return {
+    x,
+    y,
+    w: Math.ceil(maxX + geom.fitPad) - x,
+    h: Math.ceil(maxY + geom.fitPad) - y,
+  };
+}
+
+/** The `viewBox` attribute string for a fitted box. */
+export function viewBoxAttr(box: ViewBox): string {
+  return `${box.x} ${box.y} ${box.w} ${box.h}`;
+}
+
+function withFit(geom: GraphGeometry): GraphView {
+  return { ...geom, fit: fitViewBox(COURSE_GRAPHS, geom) };
+}
+
+/**
+ * `maxRadius: 232` is byte-identical to what `radialLayout`'s old default
+ * (`min(900, 560) / 2 - 48`) produced, so the node positions this branch was
+ * designed and reviewed against are unchanged. What changed is the frame drawn
+ * around them: the fit resolves to `159 42 578 498` — 578 units wide against
+ * the 900 that used to be reserved, i.e. 36% of the box was dead margin.
+ *
+ * The component caps the rendered width (`md:max-w-[720px]`), so at the cap the
+ * graph draws at 1.246 user units per CSS px: 14.9px labels, 34.9px concept
+ * dots, a 64.8px root, and a 620px-tall `<svg>` where the old fixed box
+ * reserved 737px inside a 1184px container.
+ */
+export const DESKTOP_VIEW: GraphView = withFit({
+  w: 900,
+  h: 560,
+  maxRadius: 232,
+  font: 12,
+  rootR: 26,
+  nodeR: 14,
+  labelGap: 16,
+  rootLabelAbove: true,
+  labelHalo: 3,
+  edgeW: 1.4,
+  fitPad: 10,
+});
+
+/**
+ * Portrait-ish and much smaller in user units, so a phone's ~332px content box
+ * (390 viewport − 48 of `px-6` − the 10px scrollbar globals.css paints) renders
+ * it at 0.84 rather than the 0.57 the desktop frame would give: 14-unit labels
+ * land at 11.8 CSS px, concept dots at a 23.6px diameter, and the `<svg>` is
+ * 269px tall (#344 review #3).
+ *
+ * These numbers are RETUNED, not inherited. `maxRadius` used to be pinned at
+ * 108 by the *labels* — the outer ring sits on the horizontal axis, so the
+ * widest one ("Central Limit") had to clear the hardcoded 360-unit edge. The
+ * fitted frame absorbs that overhang now, and it also removes ~26 units of dead
+ * width, which shrinks the rendered height: keeping the old geometry under the
+ * fit lands the phone `<svg>` at 259px and fails the E2E legibility gate
+ * (≥11px labels, ≥20px dots, >260px tall) outright.
+ *
+ * So the phone geometry was searched against that gate AND against the settled
+ * frame's crowding, which the old numbers were already losing (they overlapped
+ * by 1.5 units before the halo, 3.2 with it). Two constraints bracket the ring
+ * from both sides and are what picked 132/14/14/22:
+ *
+ *   root label vs the horizontal depth-1 edge:  rootR + labelGap ≥ ring/2 + 11.9
+ *   top child's label vs the root's own dot:    rootR + labelGap ≤ ring − nodeR − 5.2
+ *
+ * which together need `ring ≥ 2·nodeR + 34.2`. The result clears every pair by
+ * 0.8 units instead of overlapping, with 0.8px of label, 3.6px of dot and 8.8px
+ * of height in hand against the E2E bars.
+ */
+export const MOBILE_VIEW: GraphView = withFit({
+  w: 360,
+  h: 300,
+  maxRadius: 132,
+  font: 14,
+  rootR: 24,
+  nodeR: 14,
+  labelGap: 22,
+  rootLabelAbove: false,
+  labelHalo: 3.4,
+  edgeW: 1.8,
+  fitPad: 10,
+});
+
+/** Every view the demo can render in — the sweep target for the bounds test. */
+export const GRAPH_VIEWS: GraphView[] = [DESKTOP_VIEW, MOBILE_VIEW];

From b9e422eb980a0a462c7546c673ff421360751c87 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 15:47:37 -0700
Subject: [PATCH 14/20] fix(landing): take the outer ring off the horizontal
 axis (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ring phase was `offset = d % 2 === 0 ? step / 2 : 0` against a −π/2
start. Depth 2 holds exactly two nodes in all three fixtures, so
`step = π`, the half slot is `π/2`, and both outer nodes resolved to
exactly 0 and π — dead on the horizontal axis through the centre. The
settled layout was therefore a flat ellipse (aspect 0.40) inside a
near-circular entry sweep (0.86), and since the viewBox is fitted to the
sweep (correctly — a settled fit clips the assembly), the graph filled
only 45% of its own box height and left a dead band above and below it.

Every ring now starts three quarters of a slot back from 3 o'clock, so
its angles are odd multiples of `step/4 = π/(2·count)` and can never be a
multiple of π: no ring of any size flattens onto the horizontal axis. The
half-slot alternation is kept for what it was for — it now applies only
when a ring holds the same node count as the one inside it, which is the
only case that lines up into radial spokes.

Depth 1 is bit-identical to before (−3·(2π/3)/4 is exactly −π/2), so the
reviewed triangle and every constraint the mobile geometry was tuned
against are untouched. Depth 2 moves to the NW↔SE diagonal; the mirrored
diagonal is not equivalent — the fixtures hang their outer nodes off the
12 and 4 o'clock children, so SW↔NE drags an edge through the root label
(−7.2 units of overlap, measured).

Desktop, re-derived from the new geometry and still fitted to the sweep:
`159 42 578 498` → `185 33 526 516`; settled aspect 0.436/0.405/0.418 →
1.006/0.910/0.951; the drawing fills 73% of the frame height, up from
45% (515 of 706 rendered px, up from 277 of 620). Phone: `-19 5 394 319`
→ `-4 -1 364 330`, aspect 0.485/0.424/0.450 → 1.006/0.844/0.910, fill
48% → 73%, and every E2E legibility bar clears wider than before (12.8px
labels, 25.5px dots, 301px tall).

Worst label clearance is unchanged at +29.2 units desktop and +0.8
mobile — the new angles introduce no new binding pair. The "sweep leaves
the settled box" guard is restated in units per side (59.0/59.3 desktop,
33.2/33.9 mobile) instead of as a ratio: the ratio was a proxy that
shrinks precisely when the rest state stops being flat, which is the fix.
New tests pin the no-horizontal invariant over ring sizes 1–12, the
spoke-breaking branch, and the settled fill for every fixture × view.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 frontend/e2e/landing-graph.spec.ts            |   4 +-
 .../marketing/graph/KnowledgeGraphDemo.tsx    |   9 +-
 .../components/marketing/graph/layout.test.ts | 195 ++++++++++++++++--
 .../src/components/marketing/graph/layout.ts  | 128 ++++++++----
 4 files changed, 280 insertions(+), 56 deletions(-)

diff --git a/frontend/e2e/landing-graph.spec.ts b/frontend/e2e/landing-graph.spec.ts
index 62f9bbbc..96c6fe7c 100644
--- a/frontend/e2e/landing-graph.spec.ts
+++ b/frontend/e2e/landing-graph.spec.ts
@@ -52,8 +52,8 @@ test('landing graph renders, swaps by course, and fades its copy on engagement',
  * box is ~332px, so the SVG rendered at a uniform 0.38 scale — 4.6 CSS px
  * concept labels and a 213px-tall smudge, on the device most marketing traffic
  * arrives on. The component now swaps to a phone view below the mobile
- * breakpoint, whose frame is fitted to its content (`-19 5 394 319`, #344
- * visual 3): 0.84 scale ⇒ 11.8 CSS px labels, 23.6px dots, 269px tall.
+ * breakpoint, whose frame is fitted to its content (`-4 -1 364 330`, #344
+ * visual 3): 0.91 scale ⇒ 12.8 CSS px labels, 25.5px dots, 301px tall.
  *
  * Asserting in CSS pixels — what a visitor's eye actually gets — rather than on
  * the viewBox attribute, so a different fix that reaches the same legibility
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index ac83a537..766d2ad2 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -375,9 +375,12 @@ export default function KnowledgeGraphDemo() {
           direction the rest of the section already uses, and it is the reversible
           half of the choice: no copy moves, no structure changes.
 
-          At the 720px cap the desktop graph draws at ~1.25 units per CSS px —
-          within a hair of the 1.32 it rendered at before — in a 720×621 box
-          where the fixed viewBox reserved 1184×737.
+          At the 720px cap the desktop graph draws at ~1.37 units per CSS px in
+          a 720×706 box, where the fixed viewBox reserved 1184×737 and drew the
+          graph across the middle 277px of it. The frame is taller than the
+          `578×498` first fit because the outer ring no longer lies flat on the
+          horizontal axis (see `ringPhase`): the drawing is 86% taller in CSS px
+          and now fills 73% of the box height instead of 45%.
         */}
         <svg
           data-testid="landing-graph-svg"
diff --git a/frontend/src/components/marketing/graph/layout.test.ts b/frontend/src/components/marketing/graph/layout.test.ts
index 3fc6ad73..fa259945 100644
--- a/frontend/src/components/marketing/graph/layout.test.ts
+++ b/frontend/src/components/marketing/graph/layout.test.ts
@@ -5,7 +5,7 @@
  */
 import { describe, it, expect } from 'vitest';
 
-import { COURSE_GRAPHS } from './courseGraphs';
+import { COURSE_GRAPHS, type CourseGraph } from './courseGraphs';
 import {
   DESKTOP_VIEW,
   GRAPH_VIEWS,
@@ -54,6 +54,116 @@ describe('radialLayout', () => {
     expect(small).not.toEqual(large);
   });
 
+  /**
+   * The geometry bug this file missed twice. The ring phase used to be a half
+   * slot on alternate depths, which on a 2-node ring (`step = π`, every fixture
+   * at depth 2) resolves to exactly {0, π}: both outer nodes dead on the
+   * horizontal axis, a settled layout of aspect 0.40 inside a near-circular
+   * sweep, and a frame the fit could never tighten.
+   *
+   * Asserted as an angle off the horizontal, not as a coordinate.
+   */
+  it('never lands a node on the horizontal axis through the centre', () => {
+    for (const graph of COURSE_GRAPHS) {
+      for (const view of GRAPH_VIEWS) {
+        const pts = radialLayout(graph, view.w, view.h, view.maxRadius);
+        for (const n of graph.nodes) {
+          if (n.id === graph.rootId) continue;
+          const p = pts.get(n.id)!;
+          const dx = p.x - view.w / 2;
+          const dy = p.y - view.h / 2;
+          // |sin| of the angle off the horizontal axis. The old rule measured
+          // exactly 0 on both depth-2 nodes; every node now measures 0.5 — 30°
+          // off, the tightest angle either ring produces.
+          expect(
+            Math.abs(dy) / Math.hypot(dx, dy),
+            `${graph.id}/${n.id} at maxRadius ${view.maxRadius}`,
+          ).toBeGreaterThan(0.4);
+        }
+      }
+    }
+  });
+
+  /**
+   * …and the invariant `ringPhase` actually claims, which is stronger than the
+   * three fixtures: for a ring of ANY size the angles are odd multiples of
+   * `π/(2·count)`, so the closest one can ever come to the horizontal axis is
+   * one such step. Swept over ring sizes 1…24 on synthetic star graphs — the
+   * cheapest way to build a ring of a given size — with the count-aware floor
+   * rather than a flat number, because a flat number is only meaningful for the
+   * ring sizes that happen to ship today.
+   */
+  it('holds the no-horizontal invariant at any ring size', () => {
+    const star = (count: number): CourseGraph => ({
+      id: `star${count}`,
+      code: 'X',
+      name: 'X',
+      rootId: 'r',
+      nodes: [
+        { id: 'r', label: 'r', tier: 'learning', blurb: '', children: [] },
+        ...Array.from({ length: count }, (_, i) => ({
+          id: `n${i}`,
+          label: `n${i}`,
+          tier: 'learning' as const,
+          blurb: '',
+          children: [],
+        })),
+      ],
+      edges: Array.from({ length: count }, (_, i) => ({ source: 'r', target: `n${i}` })),
+    });
+
+    for (let count = 1; count <= 24; count++) {
+      const pts = radialLayout(star(count), 900, 560, 232);
+      // Half a slot of the ring's own quarter-slot grid, minus float slop.
+      const floor = Math.sin(Math.PI / (2 * count)) * 0.999;
+      for (let i = 0; i < count; i++) {
+        const p = pts.get(`n${i}`)!;
+        const sin = Math.abs(p.y - 280) / Math.hypot(p.x - 450, p.y - 280);
+        expect(sin, `ring of ${count}, node ${i}`).toBeGreaterThan(floor);
+      }
+    }
+  });
+
+  /**
+   * Half a slot of rotation is what keeps a ring from lining up radially with
+   * the one inside it. The old rule spent it on every even depth — including
+   * the 2-node ring, where it was the flattening bug — so it is now spent only
+   * where it does that job: when two consecutive rings hold the same number of
+   * nodes. No shipped fixture reaches it (3 nodes then 2), so it is pinned on a
+   * synthetic 2 → 2 tree.
+   */
+  it('breaks radial spokes when two rings hold the same node count', () => {
+    const graph: CourseGraph = {
+      id: 'twotwo',
+      code: 'X',
+      name: 'X',
+      rootId: 'r',
+      nodes: ['r', 'a', 'b', 'a1', 'b1'].map((id) => ({
+        id,
+        label: id,
+        tier: 'learning' as const,
+        blurb: '',
+        children: [],
+      })),
+      edges: [
+        { source: 'r', target: 'a' },
+        { source: 'r', target: 'b' },
+        { source: 'a', target: 'a1' },
+        { source: 'b', target: 'b1' },
+      ],
+    };
+    const pts = radialLayout(graph, 900, 560, 232);
+    const angle = (id: string) => Math.atan2(pts.get(id)!.y - 280, pts.get(id)!.x - 450);
+    const off = (a: string, b: string) => Math.abs(angle(a) - angle(b));
+    // A half slot apart — not stacked on the same ray.
+    expect(off('a', 'a1')).toBeCloseTo(Math.PI / 2, 6);
+    expect(off('b', 'b1')).toBeCloseTo(Math.PI / 2, 6);
+    // …and still nothing on the horizontal axis.
+    for (const id of ['a', 'b', 'a1', 'b1']) {
+      expect(Math.abs(Math.sin(angle(id))), id).toBeGreaterThan(0.1);
+    }
+  });
+
   it('keeps the default maxRadius at the old inscribed-circle rule', () => {
     // The `maxRadius` parameter was added for the mobile view (#344 review #3).
     // Its default has to reproduce the desktop geometry this branch was
@@ -208,10 +318,18 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
    * The assertion above is only worth anything if the sweep actually needs the
    * headroom — otherwise a lazy "fit to the settled node positions" would pass
    * it, and that is precisely the clipping bug. So: prove the sweep leaves the
-   * settled bounding box. `helixEntry` rotates a node up to 1.5 turns on the way
-   * in, and the outer ring rests on the horizontal axis, so it passes ~0.925 ×
-   * maxRadius above and below the centre at ~83% opacity — 215 desktop units,
-   * against a settled vertical extent of 58.
+   * settled bounding box, and by how much. `helixEntry` rotates a node up to
+   * 1.5 turns on the way in, so every outer node passes through every direction
+   * before it lands.
+   *
+   * The MARGIN is what this asserts, in units, on each side. It used to be
+   * stated as a ratio ("the sweep needs ~2× the settled height"), which was only
+   * ever a proxy: the ratio is large exactly when the rest state is FLAT, and
+   * flattening the rest state is the bug the ring phase just fixed (settled
+   * aspect 0.40 → 0.91, so the ratio fell from 2.14 to 1.31 while the thing it
+   * was standing in for — how much a settled-fit frame would chop off the
+   * assembly — barely moved, 59 units against 62). Measured on each side:
+   * desktop 59.0 / 59.3, mobile 33.5 / 33.5.
    */
   for (const view of GRAPH_VIEWS) {
     it(`the ${view.maxRadius}-radius sweep leaves the settled bounding box`, () => {
@@ -241,14 +359,59 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
         }
       }
 
-      expect(sweptTop).toBeLessThan(settledTop);
-      expect(sweptBottom).toBeGreaterThan(settledBottom);
-      // Comfortably, not marginally: the sweep needs ~2× the settled height.
-      expect(sweptBottom - sweptTop).toBeGreaterThan(1.5 * (settledBottom - settledTop));
+      // Comfortably, not marginally, and on BOTH sides: a frame fitted to the
+      // rest state would chop this much off the top and bottom of the assembly,
+      // live, at ~83% opacity.
+      expect(settledTop - sweptTop).toBeGreaterThan(25);
+      expect(sweptBottom - settledBottom).toBeGreaterThan(25);
       // …and the fitted frame is sized for the sweep, not for the rest state.
       expect(view.fit.h).toBeGreaterThanOrEqual(sweptBottom - sweptTop);
+      expect(view.fit.h).toBeGreaterThan(settledBottom - settledTop);
     });
   }
+
+  /**
+   * #344 visual 3, second wave — the settled graph has to FILL the frame it is
+   * given. The flat outer ring (both depth-2 nodes on the horizontal axis) made
+   * the rest state 0.40-aspect inside a 0.86-aspect sweep, so the fitted box
+   * carried a dead band above and below the drawing: 264 of 620 rendered px,
+   * ~43%. The diagonal ring lifts every fixture past 0.60 aspect and 0.70 of
+   * the box height.
+   */
+  describe('the settled graph fills its own frame', () => {
+    for (const view of GRAPH_VIEWS) {
+      for (const graph of COURSE_GRAPHS) {
+        it(`${graph.id} at maxRadius ${view.maxRadius}`, () => {
+          const points = radialLayout(graph, view.w, view.h, view.maxRadius);
+          let l = Infinity;
+          let r = -Infinity;
+          let t = Infinity;
+          let b = -Infinity;
+          for (const n of graph.nodes) {
+            const p = points.get(n.id)!;
+            const isRoot = n.id === graph.rootId;
+            const e = drawnExtent(
+              view,
+              n.label,
+              isRoot,
+              p.x,
+              p.y,
+              isRoot ? view.rootR : view.nodeR,
+              1,
+            );
+            l = Math.min(l, e.left);
+            r = Math.max(r, e.right);
+            t = Math.min(t, e.top);
+            b = Math.max(b, e.bottom);
+          }
+          // Measured: 1.006 / 0.910 / 0.951 desktop, 1.006 / 0.844 / 0.910 phone.
+          expect((b - t) / (r - l), 'settled aspect').toBeGreaterThanOrEqual(0.6);
+          // Measured: 0.730 desktop, 0.733 phone — was 0.447 / 0.483.
+          expect((b - t) / view.fit.h, 'share of the frame height').toBeGreaterThan(0.7);
+        });
+      }
+    }
+  });
 });
 
 /**
@@ -273,8 +436,8 @@ describe('fitViewBox — one stable frame for every course', () => {
     // The shipped bug: `viewBox="0 0 900 560"` around content 578 units wide.
     expect(DESKTOP_VIEW.fit.w).toBeLessThan(DESKTOP_VIEW.w);
     expect(DESKTOP_VIEW.fit.h).toBeLessThan(DESKTOP_VIEW.h);
-    expect(viewBoxAttr(DESKTOP_VIEW.fit)).toBe('159 42 578 498');
-    expect(viewBoxAttr(MOBILE_VIEW.fit)).toBe('-19 5 394 319');
+    expect(viewBoxAttr(DESKTOP_VIEW.fit)).toBe('185 33 526 516');
+    expect(viewBoxAttr(MOBILE_VIEW.fit)).toBe('-4 -1 364 330');
   });
 });
 
@@ -384,9 +547,9 @@ describe('GraphView sizing at a 390px viewport', () => {
 
   it('renders legible labels and dots on a phone', () => {
     const scale = CONTENT_PX / MOBILE_VIEW.fit.w;
-    expect(scale).toBeCloseTo(0.8426, 4);
-    // 11.8 CSS px labels (was 4.56), 23.6 CSS px dot diameter (was 10.64),
-    // 269 CSS px of graph height (was 213).
+    expect(scale).toBeCloseTo(0.9121, 4);
+    // 12.8 CSS px labels (was 4.56), 25.5 CSS px dot diameter (was 10.64),
+    // 301 CSS px of graph height (was 213).
     expect(MOBILE_VIEW.font * scale).toBeGreaterThanOrEqual(11);
     expect(2 * MOBILE_VIEW.nodeR * scale).toBeGreaterThanOrEqual(20);
     expect(MOBILE_VIEW.fit.h * scale).toBeGreaterThanOrEqual(260);
@@ -395,8 +558,8 @@ describe('GraphView sizing at a 390px viewport', () => {
   it('documents why the desktop view is still not a phone view', () => {
     // Not an aspiration — the reason `useIsMobile` swaps views at all, kept
     // here so a future "just use one viewBox everywhere" change has to argue
-    // with it. The fit shrank the desktop box from 900 to 578 units, which
-    // lifts a phone-rendered desktop label from 4.6 to 6.9 CSS px — still
+    // with it. The fit shrank the desktop box from 900 to 526 units, which
+    // lifts a phone-rendered desktop label from 4.6 to 7.6 CSS px — still
     // nowhere near the 11px floor above.
     const scale = CONTENT_PX / DESKTOP_VIEW.fit.w;
     expect(DESKTOP_VIEW.font * scale).toBeLessThan(11);
diff --git a/frontend/src/components/marketing/graph/layout.ts b/frontend/src/components/marketing/graph/layout.ts
index d7c04ee2..ccf94ede 100644
--- a/frontend/src/components/marketing/graph/layout.ts
+++ b/frontend/src/components/marketing/graph/layout.ts
@@ -92,10 +92,52 @@ export function easeOutCubic(t: number): number {
   return 1 - Math.pow(1 - c, 3);
 }
 
+/**
+ * Where a ring's FIRST node sits, as an angle from 3 o'clock. SVG angles run
+ * clockwise (y grows downward), so −π/2 is 12 o'clock.
+ *
+ * THE BUG THIS FIXES. The rule used to be "start at 12 o'clock, and rotate
+ * alternate rings by half a slot so spokes don't line up" — `offset = d % 2 ===
+ * 0 ? step / 2 : 0` against a `−π/2` start. On a ring of exactly TWO nodes,
+ * which is what depth 2 holds in all three fixtures, `step = π`, the half slot
+ * is `π/2`, and the two angles collapse to exactly 0 and π: BOTH outer nodes
+ * dead on the horizontal axis through the centre. That made the settled layout
+ * a flat ellipse (aspect 0.40) sitting inside a near-circular entry sweep
+ * (0.86), so the fitted frame could never be tight — the graph filled 45% of
+ * its own box height and left a visible dead band above and below it.
+ *
+ * THE RULE. Every ring starts three quarters of a slot BACK from 3 o'clock, so
+ * its angles are `(4i − 3) · step/4` — ODD multiples of `step/4 = π/(2·count)`.
+ * An odd multiple of `π/(2n)` is never a multiple of π (that would need
+ * `odd = 2kn`), so no ring of ANY size can put a node on the horizontal axis.
+ * For the shipped ring sizes it resolves to:
+ *
+ *   count 3 (depth 1): −3·(2π/3)/4 = −π/2 → 12, 4 and 8 o'clock, i.e. the exact
+ *                      triangle this branch was designed and reviewed against.
+ *   count 2 (depth 2): −3π/4              → the NW↔SE diagonal.
+ *
+ * The diagonal's DIRECTION is not free. Every fixture hangs its two outer nodes
+ * off the 12 o'clock and 4 o'clock children, so the mirrored diagonal (SW↔NE,
+ * `+3·step/4`) drags a depth-1 → depth-2 edge across the centre and straight
+ * through a label: −7.2 units of overlap, measured, against +29.2 of clearance
+ * the way round it is.
+ *
+ * `alternate` keeps the half-slot rotation the old rule existed for, but only
+ * where it can actually do something: when a ring holds the same number of
+ * nodes as the ring inside it, and the two would otherwise line up into radial
+ * spokes. Half a slot moves the angles to `(4i − 1) · step/4` — still odd
+ * multiples of `step/4`, so the no-horizontal proof holds on that branch too.
+ * No shipped fixture reaches it (3 then 2).
+ */
+function ringPhase(count: number, innerCount: number | undefined): number {
+  const step = (Math.PI * 2) / count;
+  return (count === innerCount ? -1 : -3) * (step / 4);
+}
+
 /**
  * Root at the centre, each BFS depth on its own ring, siblings spread evenly
- * around it. Alternate rings are rotated by half a slot so spokes don't line
- * up into visual spokes.
+ * around it, every ring phased by `ringPhase` so none of them flattens onto the
+ * horizontal axis.
  *
  * `maxRadius` is the outermost ring's distance from the centre. It defaults to
  * the old inscribed-circle-minus-48 rule so every existing caller and test is
@@ -147,9 +189,11 @@ export function radialLayout(
       continue;
     }
     const step = (Math.PI * 2) / ids.length;
-    const offset = d % 2 === 0 ? step / 2 : 0;
+    // Depth 0 is the centre, not a ring, so the innermost ring has nothing to
+    // line up with and never alternates.
+    const phase = ringPhase(ids.length, d > 1 ? byDepth.get(d - 1)?.length : undefined);
     ids.forEach((id, i) => {
-      const a = i * step + offset - Math.PI / 2;
+      const a = i * step + phase;
       out.set(id, {
         x: cx + Math.cos(a) * ring * d,
         y: cy + Math.sin(a) * ring * d,
@@ -218,12 +262,15 @@ export function labelHalfWidth(label: string, geom: GraphGeometry): number {
 /**
  * Where a node's label baseline sits, relative to the node's drawn centre.
  *
- * On DESKTOP the root's label goes above it (#344 visual 4). Below the root is
- * where the outer-ring → depth-1 edge crosses: in every fixture that edge
- * passes the root's x at `cy + 0.349 × ring` (desktop: 40.5 units down), which
- * is exactly the band a `rootR + labelGap` baseline puts the course code in — a
- * long shallow diagonal straight through "CS 210". Above the root there is only
- * the short vertical spoke to the top child, which the halo breaks cleanly.
+ * On DESKTOP the root's label goes above it (#344 visual 4). It went there to
+ * dodge the outer-ring → depth-1 edge, which the old flat ring dragged across
+ * the root's x at `cy + 0.349 × ring` — straight through "CS 210". The ring
+ * phase (see `ringPhase`) has since pulled that diagonal off the centre, so
+ * below is no longer a collision either; above is kept because it is still the
+ * roomier half. Measured, across all three fixtures: above clears everything by
+ * 29.2 units, below by 11.5 — the binding neighbour there is the depth-1 chord
+ * (`ma-matrices → ma-eigen`, `sm-dist → sm-testing`) at `cy + ring/2`, i.e.
+ * `cy + 58`, against a below-baseline label bottom at `cy + 46.5`.
  *
  * On MOBILE it stays below, because there the geometry says so. The top child
  * sits `ring` above the root with its own label hanging back down toward it, so
@@ -233,10 +280,11 @@ export function labelHalfWidth(label: string, geom: GraphGeometry): number {
  *
  * — 83.8 units at the desktop type scale, against a 116-unit ring: comfortable.
  * The phone's ring is 66 against a 95.7-unit requirement, so "above" would put
- * the course code straight through the first concept's label. The crossing
- * diagonal it would be dodging isn't a problem there anyway: at ring 66 that
- * edge passes the root's x at `cy + 23.0` and the below-baseline label's cap
- * top is at `cy + 34.1`, 11 units clear.
+ * the course code straight through the first concept's label. Below is tight
+ * but positive: the same depth-1 chord passes at `cy + 33.0` and the
+ * below-baseline label's cap top is at `cy + 34.1`, 1.1 units clear — which is
+ * the constraint `MOBILE_VIEW`'s geometry was tuned against, and it does not
+ * move with the ring phase.
  *
  * Shared with `fitViewBox` and `layout.test.ts` so the frame can never be
  * fitted to a label position the component doesn't actually use.
@@ -285,12 +333,14 @@ const FIT_STEPS = 512;
  *
  * THE THING TO NOT GET WRONG: fit to the HELIX SWEEP, not to the settled node
  * positions. `helixEntry` rotates a node up to 1.5 turns around the centre on
- * the way in, so an outer node whose resting place is on the horizontal axis
- * passes through `0.925 × maxRadius` ABOVE and BELOW the centre at ~83% opacity
- * — 215 desktop units against a settled extent of 58. A box fitted to the
- * settled positions clips the assembly in plain view; that exact bug was found
- * and fixed once already on this branch (#344 review #4), and `layout.test.ts`
- * sweeps `t` across the full range to keep it fixed.
+ * the way in, so every outer node passes through every direction on its way to
+ * rest: on desktop the sweep reaches ~237 units above and below the centre
+ * while the settled drawing only reaches 178 above and 199 below. A box fitted
+ * to the settled positions would clip 59 units — 81 CSS px at the rendered cap
+ * — off the top and bottom of the assembly, in plain view; that exact bug was
+ * found and fixed once already on this branch (#344 review #4). `layout.test.ts`
+ * sweeps `t` across the full range to keep it fixed, and pins the overshoot
+ * itself so a settled-fit implementation fails outright.
  *
  * Fitted ONCE across all three fixtures rather than per graph: the three share
  * a topology and differ only in label widths, so a per-graph fit would produce
@@ -352,16 +402,20 @@ function withFit(geom: GraphGeometry): GraphView {
 }
 
 /**
- * `maxRadius: 232` is byte-identical to what `radialLayout`'s old default
- * (`min(900, 560) / 2 - 48`) produced, so the node positions this branch was
- * designed and reviewed against are unchanged. What changed is the frame drawn
- * around them: the fit resolves to `159 42 578 498` — 578 units wide against
- * the 900 that used to be reserved, i.e. 36% of the box was dead margin.
+ * `maxRadius: 232` is still `radialLayout`'s old default (`min(900, 560) / 2 -
+ * 48`), so the layout's spatial budget is unchanged and the depth-1 ring sits
+ * exactly where this branch was designed against. What moved is the outer ring
+ * — `ringPhase` takes it off the horizontal axis and onto the diagonal — and
+ * the frame fitted around the result: `185 33 526 516`, against the
+ * `0 0 900 560` the demo shipped with and the `159 42 578 498` the flat ring
+ * fitted to.
  *
  * The component caps the rendered width (`md:max-w-[720px]`), so at the cap the
- * graph draws at 1.246 user units per CSS px: 14.9px labels, 34.9px concept
- * dots, a 64.8px root, and a 620px-tall `<svg>` where the old fixed box
- * reserved 737px inside a 1184px container.
+ * graph draws at 1.369 user units per CSS px: 16.4px labels, 38.3px concept
+ * dots, a 71px root, and a 706px-tall `<svg>` where the fixed box reserved
+ * 737px inside a 1184px container. The settled drawing fills 73% of that height
+ * (515 of 706 CSS px); on the flat ring it filled 45% (277 of 620), which is
+ * the dead band above and below the graph that this phase change removes.
  */
 export const DESKTOP_VIEW: GraphView = withFit({
   w: 900,
@@ -380,12 +434,14 @@ export const DESKTOP_VIEW: GraphView = withFit({
 /**
  * Portrait-ish and much smaller in user units, so a phone's ~332px content box
  * (390 viewport − 48 of `px-6` − the 10px scrollbar globals.css paints) renders
- * it at 0.84 rather than the 0.57 the desktop frame would give: 14-unit labels
- * land at 11.8 CSS px, concept dots at a 23.6px diameter, and the `<svg>` is
- * 269px tall (#344 review #3).
+ * it at 0.91 rather than the 0.63 the desktop frame would give: 14-unit labels
+ * land at 12.8 CSS px, concept dots at a 25.5px diameter, and the `<svg>` is
+ * 301px tall (#344 review #3). The frame is `-4 -1 364 330`; the diagonal outer
+ * ring both narrowed it (394 → 364) and filled it — the settled drawing is 73%
+ * of its height, up from 48%.
  *
  * These numbers are RETUNED, not inherited. `maxRadius` used to be pinned at
- * 108 by the *labels* — the outer ring sits on the horizontal axis, so the
+ * 108 by the *labels* — the outer ring then sat on the horizontal axis, so the
  * widest one ("Central Limit") had to clear the hardcoded 360-unit edge. The
  * fitted frame absorbs that overhang now, and it also removes ~26 units of dead
  * width, which shrinks the rendered height: keeping the old geometry under the
@@ -400,9 +456,11 @@ export const DESKTOP_VIEW: GraphView = withFit({
  *   root label vs the horizontal depth-1 edge:  rootR + labelGap ≥ ring/2 + 11.9
  *   top child's label vs the root's own dot:    rootR + labelGap ≤ ring − nodeR − 5.2
  *
- * which together need `ring ≥ 2·nodeR + 34.2`. The result clears every pair by
- * 0.8 units instead of overlapping, with 0.8px of label, 3.6px of dot and 8.8px
- * of height in hand against the E2E bars.
+ * which together need `ring ≥ 2·nodeR + 34.2`. Neither constraint moves with
+ * the ring phase — both are about the root, its own top child, and the depth-1
+ * chord — so the retune survives it unchanged: still +0.8 units on the worst
+ * pair, now with 1.8px of label, 5.5px of dot and 41px of height in hand
+ * against the E2E bars (the tighter frame renders everything larger).
  */
 export const MOBILE_VIEW: GraphView = withFit({
   w: 360,

From 56316394ef5299a4b76a940081c278bb47be356f Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 16:42:19 -0700
Subject: [PATCH 15/20] fix(landing): lay the graph out as a radial tree, not
 concentric rings (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`radialLayout` placed nodes on global concentric rings: a node's angle came
from its index within its depth, with no relationship to where its parent
sat. On the shipped 6-node fixtures that scattered the graph — `cs-sorting`
landed 171 units from `cs-arrays` on a 232-unit ring, `cs-trees` was flung to
the opposite corner — and the picture read as a lopsided diagonal smear.
Tuning the ring angles cannot fix it; the previous wave tried.

Now: BFS a spanning tree over the undirected `edges` (never `children`, which
is dead data that disagrees with them), root at the centre, depth-1 spread
evenly around the circle, and every deeper node placed one ring step from ITS
OWN PARENT inside a wedge centred on that parent's outward direction. The tree
governs position only — every entry in `graph.edges` is still drawn, cross
edges included.

Tree-edge length, desktop: max 170.9 → 116.0, mean 128.5 → 116.0. The section
gets shorter at the 720px cap: 706px → 663px. The depth-1 ring phase moves
forward by one slot (`+step/4`, still an odd multiple, so the no-horizontal
proof is unchanged) so the two branch-bearing children sit at 4 and 8 o'clock
and grow downward, away from the root's label band.

`MOBILE_VIEW` is retuned, not optional: in a tree the flattest of three arms
is always 30° off horizontal, so a child's dot lands inside its parent's own
13-character label unless `0.866·ring > 3.9·font + halo/2 + nodeR`. The ring
grows 132 → 163 and `nodeR`/`fitPad` shrink to buy it; the phone renders at
11.2px labels / 20.9px dots / 285px tall, still over the E2E legibility gate
but with thin margins, documented at both ends.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 frontend/e2e/landing-graph.spec.ts            |   8 +-
 .../marketing/graph/KnowledgeGraphDemo.tsx    |  20 +-
 .../components/marketing/graph/layout.test.ts | 276 +++++++++++---
 .../src/components/marketing/graph/layout.ts  | 353 +++++++++++-------
 4 files changed, 463 insertions(+), 194 deletions(-)

diff --git a/frontend/e2e/landing-graph.spec.ts b/frontend/e2e/landing-graph.spec.ts
index 96c6fe7c..1f4d60fa 100644
--- a/frontend/e2e/landing-graph.spec.ts
+++ b/frontend/e2e/landing-graph.spec.ts
@@ -52,8 +52,12 @@ test('landing graph renders, swaps by course, and fades its copy on engagement',
  * box is ~332px, so the SVG rendered at a uniform 0.38 scale — 4.6 CSS px
  * concept labels and a 213px-tall smudge, on the device most marketing traffic
  * arrives on. The component now swaps to a phone view below the mobile
- * breakpoint, whose frame is fitted to its content (`-4 -1 364 330`, #344
- * visual 3): 0.91 scale ⇒ 12.8 CSS px labels, 25.5px dots, 301px tall.
+ * breakpoint, whose frame is fitted to its content (`-38 -11 414 356`, #344
+ * visual 3): 0.80 scale ⇒ 11.2 CSS px labels, 20.9px dots, 285px tall. Those
+ * three clear the bars below by 0.2px, 0.9px and 25px — the radial-tree layout
+ * needs a wider ring to keep a child's dot out of its parent's label, and this
+ * gate is what stops the ring growing further, so the margins are genuinely
+ * thin. See `MOBILE_VIEW` in `layout.ts` for the two-sided bracket.
  *
  * Asserting in CSS pixels — what a visitor's eye actually gets — rather than on
  * the viewBox attribute, so a different fix that reaches the same legibility
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index 766d2ad2..3276e92f 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -194,9 +194,10 @@ function AssemblingGraph({
           >
             <circle cx={h.x} cy={h.y} r={r * h.scale} fill={nodeFill(graph, n)} />
             {/*
-              Labels sit ON the edge mesh — `Trees` and `Big-O` crowd their own
-              connecting lines, and until the root's label moved above the node
-              it lay along the outer-ring → depth-1 diagonal (#344 visual 4).
+              Labels sit ON the edge mesh — under the radial tree the root's own
+              label and its 12 o'clock child's both straddle the vertical edge
+              between them, and every arm's label straddles the edge running out
+              to its child (#344 visual 4).
               `paint-order: stroke` lays a halo in the section's own backdrop
               colour under the glyphs and paints the fill over it, so a line
               passing behind a word breaks around the letterforms instead of
@@ -375,12 +376,13 @@ export default function KnowledgeGraphDemo() {
           direction the rest of the section already uses, and it is the reversible
           half of the choice: no copy moves, no structure changes.
 
-          At the 720px cap the desktop graph draws at ~1.37 units per CSS px in
-          a 720×706 box, where the fixed viewBox reserved 1184×737 and drew the
-          graph across the middle 277px of it. The frame is taller than the
-          `578×498` first fit because the outer ring no longer lies flat on the
-          horizontal axis (see `ringPhase`): the drawing is 86% taller in CSS px
-          and now fills 73% of the box height instead of 45%.
+          At the 720px cap the desktop graph draws at ~1.33 units per CSS px in
+          a 720×663 box, where the fixed viewBox reserved 1184×737 and drew the
+          graph across the middle 277px of it. The box is 43px SHORTER than the
+          720×706 the concentric-ring layout fitted to: a radial tree is a wide,
+          short object, so it fills 83% of the frame's width (up from 71%) and
+          56% of its height, centred, with the whitespace the circular entry
+          sweep costs spent symmetrically above and below.
         */}
         <svg
           data-testid="landing-graph-svg"
diff --git a/frontend/src/components/marketing/graph/layout.test.ts b/frontend/src/components/marketing/graph/layout.test.ts
index fa259945..68de8b90 100644
--- a/frontend/src/components/marketing/graph/layout.test.ts
+++ b/frontend/src/components/marketing/graph/layout.test.ts
@@ -20,6 +20,38 @@ import {
 
 const G = COURSE_GRAPHS[0];
 
+/**
+ * The BFS spanning tree of the undirected graph — restated here rather than
+ * exported from `layout.ts`, so the assertions below are an INDEPENDENT reading
+ * of the same fixtures. (Deliberately not `DemoNode.children`: that field is
+ * dead data that disagrees with `edges`, which is exactly why the layout must
+ * not read it either.)
+ */
+function bfsTree(graph: CourseGraph) {
+  const adj = new Map<string, string[]>();
+  for (const e of graph.edges) {
+    adj.set(e.source, [...(adj.get(e.source) ?? []), e.target]);
+    adj.set(e.target, [...(adj.get(e.target) ?? []), e.source]);
+  }
+  const depth = new Map<string, number>([[graph.rootId, 0]]);
+  const parent = new Map<string, string>();
+  const queue = [graph.rootId];
+  while (queue.length) {
+    const cur = queue.shift()!;
+    for (const nxt of adj.get(cur) ?? []) {
+      if (!depth.has(nxt)) {
+        depth.set(nxt, depth.get(cur)! + 1);
+        parent.set(nxt, cur);
+        queue.push(nxt);
+      }
+    }
+  }
+  return { depth, parent };
+}
+
+const dist = (a: { x: number; y: number }, b: { x: number; y: number }) =>
+  Math.hypot(a.x - b.x, a.y - b.y);
+
 describe('radialLayout', () => {
   it('positions every node', () => {
     const p = radialLayout(G, 800, 500);
@@ -55,13 +87,123 @@ describe('radialLayout', () => {
   });
 
   /**
-   * The geometry bug this file missed twice. The ring phase used to be a half
-   * slot on alternate depths, which on a 2-node ring (`step = π`, every fixture
-   * at depth 2) resolves to exactly {0, π}: both outer nodes dead on the
-   * horizontal axis, a settled layout of aspect 0.40 inside a near-circular
-   * sweep, and a frame the fit could never tighten.
+   * CRITERION 1, and the pin the whole rewrite hangs on.
+   *
+   * The layout used to be global concentric rings: a node's angle came from its
+   * index within its depth, with no relationship to where its parent sat. This
+   * is the invariant that says otherwise — a child is placed off ITS OWN
+   * PARENT, so the distance between the two is exactly one ring step, for every
+   * non-root node, in every fixture, in every view.
+   *
+   * It fails outright on the ring layout, where the same edges measured 116.0
+   * AND 170.9 units on desktop depending on which ring angles happened to line
+   * up (`cs-arrays → cs-sorting` was the 170.9).
+   */
+  it('places every node exactly one ring step from its BFS parent', () => {
+    for (const graph of COURSE_GRAPHS) {
+      for (const view of GRAPH_VIEWS) {
+        const pts = radialLayout(graph, view.w, view.h, view.maxRadius);
+        const { depth, parent } = bfsTree(graph);
+        // maxDepth is 2 in every fixture, so the step is half the budget.
+        const step = view.maxRadius / Math.max(...depth.values());
+        for (const n of graph.nodes) {
+          if (n.id === graph.rootId) continue;
+          const d = dist(pts.get(n.id)!, pts.get(parent.get(n.id)!)!);
+          expect(d, `${graph.id}/${n.id} → ${parent.get(n.id)}`).toBeCloseTo(step, 6);
+        }
+      }
+    }
+  });
+
+  /**
+   * CRITERION 1 as the brief states it: a child sits WITH its parent, i.e. its
+   * BFS parent is the nearest node of the previous depth. Weaker than the
+   * one-ring-step pin above (the ring layout happens to satisfy it too), but it
+   * is the property a reader actually cares about, so it is asserted rather
+   * than implied — and it stays true for a parent with several children, where
+   * the exact-step assertion alone would not rule out a child drifting nearer
+   * to somebody else's parent.
+   */
+  it('keeps every node nearer its own parent than any other node of that depth', () => {
+    for (const graph of COURSE_GRAPHS) {
+      for (const view of GRAPH_VIEWS) {
+        const pts = radialLayout(graph, view.w, view.h, view.maxRadius);
+        const { depth, parent } = bfsTree(graph);
+        for (const n of graph.nodes) {
+          if (n.id === graph.rootId) continue;
+          const mine = dist(pts.get(n.id)!, pts.get(parent.get(n.id)!)!);
+          for (const other of graph.nodes) {
+            if (other.id === parent.get(n.id)) continue;
+            if (depth.get(other.id) !== depth.get(n.id)! - 1) continue;
+            expect(
+              dist(pts.get(n.id)!, pts.get(other.id)!),
+              `${graph.id}/${n.id}: ${other.id} is nearer than its parent ${parent.get(n.id)}`,
+            ).toBeGreaterThan(mine);
+          }
+        }
+      }
+    }
+  });
+
+  /**
+   * CRITERION 2 — no long flung edges. Measured over the TREE edges, which are
+   * the ones the layout is responsible for; cross-edges are drawn but not
+   * positioned (see below).
+   *
+   * Desktop, before → after: max 170.9 → 116.0, mean 128.5 → 116.0. Phone:
+   * max 97.3 → 81.5, mean 73.1 → 81.5 (the phone's ring grew with the retune,
+   * so its mean rises while its max falls). Asserted against the ring step
+   * rather than a magic number, so it stays meaningful if a view is retuned.
+   */
+  it('draws no tree edge longer than one ring step', () => {
+    for (const graph of COURSE_GRAPHS) {
+      for (const view of GRAPH_VIEWS) {
+        const pts = radialLayout(graph, view.w, view.h, view.maxRadius);
+        const { depth, parent } = bfsTree(graph);
+        const step = view.maxRadius / Math.max(...depth.values());
+        const lengths = graph.edges
+          .filter((e) => parent.get(e.target) === e.source || parent.get(e.source) === e.target)
+          .map((e) => dist(pts.get(e.source)!, pts.get(e.target)!));
+        expect(lengths.length, `${graph.id} tree edges`).toBe(graph.nodes.length - 1);
+        expect(Math.max(...lengths), `${graph.id} longest tree edge`).toBeLessThanOrEqual(
+          step + 1e-9,
+        );
+      }
+    }
+  });
+
+  /**
+   * The tree governs POSITION only. Every fixture carries exactly one edge that
+   * is NOT a tree edge — `cs-sorting → cs-complexity`, `ma-matrices →
+   * ma-eigen`, `sm-dist → sm-testing` — and `AssemblingGraph` maps
+   * `graph.edges`, so all of them are still drawn; cs210's closes a triangle
+   * from the lower-right tip back up to the top node and is a good part of why
+   * the picture reads as a graph rather than a star. Pinned here because a
+   * future "just draw the tree" simplification would silently drop it.
+   */
+  it('leaves the fixtures with a drawn cross-edge the tree does not own', () => {
+    for (const graph of COURSE_GRAPHS) {
+      const { parent } = bfsTree(graph);
+      const cross = graph.edges.filter(
+        (e) => parent.get(e.target) !== e.source && parent.get(e.source) !== e.target,
+      );
+      expect(cross.length, `${graph.id} cross-edges`).toBe(1);
+      // …and both of its endpoints are laid out, so it is drawable.
+      const pts = radialLayout(graph, DESKTOP_VIEW.w, DESKTOP_VIEW.h, DESKTOP_VIEW.maxRadius);
+      expect(pts.get(cross[0].source)).toBeDefined();
+      expect(pts.get(cross[0].target)).toBeDefined();
+    }
+  });
+
+  /**
+   * CRITERION 3 — the invariant the previous wave established, carried over
+   * unchanged. The ring phase used to be a half slot on alternate depths, which
+   * on a 2-node ring (`step = π`, every fixture at depth 2 back then) resolved
+   * to exactly {0, π}: both outer nodes dead on the horizontal axis.
    *
-   * Asserted as an angle off the horizontal, not as a coordinate.
+   * The tree only phases ONE ring — depth 1 — but deeper nodes inherit their
+   * parent's heading when they are lone children, so the invariant has to hold
+   * for them too. Asserted as an angle off the horizontal, not as a coordinate.
    */
   it('never lands a node on the horizontal axis through the centre', () => {
     for (const graph of COURSE_GRAPHS) {
@@ -125,20 +267,23 @@ describe('radialLayout', () => {
   });
 
   /**
-   * Half a slot of rotation is what keeps a ring from lining up radially with
-   * the one inside it. The old rule spent it on every even depth — including
-   * the 2-node ring, where it was the flattening bug — so it is now spent only
-   * where it does that job: when two consecutive rings hold the same number of
-   * nodes. No shipped fixture reaches it (3 nodes then 2), so it is pinned on a
-   * synthetic 2 → 2 tree.
+   * The wedge rule, which no shipped fixture exercises — every parent below the
+   * root has exactly one child, so every arm is collinear with the centre. This
+   * pins what happens when one doesn't: siblings SHARE their parent's angular
+   * span, evenly and symmetrically about the parent's own outward direction, so
+   * a branchy graph fans out instead of stacking on one ray.
+   *
+   * (It replaces the old "breaks radial spokes when two rings hold the same node
+   * count" test, whose subject — a half-slot rotation applied to the SECOND
+   * concentric ring — no longer exists: there are no rings past depth 1.)
    */
-  it('breaks radial spokes when two rings hold the same node count', () => {
+  it('splits a parent’s wedge evenly between its children', () => {
     const graph: CourseGraph = {
-      id: 'twotwo',
+      id: 'fan',
       code: 'X',
       name: 'X',
       rootId: 'r',
-      nodes: ['r', 'a', 'b', 'a1', 'b1'].map((id) => ({
+      nodes: ['r', 'a', 'b', 'a1', 'a2', 'a3'].map((id) => ({
         id,
         label: id,
         tier: 'learning' as const,
@@ -149,18 +294,28 @@ describe('radialLayout', () => {
         { source: 'r', target: 'a' },
         { source: 'r', target: 'b' },
         { source: 'a', target: 'a1' },
-        { source: 'b', target: 'b1' },
+        { source: 'a', target: 'a2' },
+        { source: 'a', target: 'a3' },
       ],
     };
     const pts = radialLayout(graph, 900, 560, 232);
-    const angle = (id: string) => Math.atan2(pts.get(id)!.y - 280, pts.get(id)!.x - 450);
-    const off = (a: string, b: string) => Math.abs(angle(a) - angle(b));
-    // A half slot apart — not stacked on the same ray.
-    expect(off('a', 'a1')).toBeCloseTo(Math.PI / 2, 6);
-    expect(off('b', 'b1')).toBeCloseTo(Math.PI / 2, 6);
-    // …and still nothing on the horizontal axis.
-    for (const id of ['a', 'b', 'a1', 'b1']) {
-      expect(Math.abs(Math.sin(angle(id))), id).toBeGreaterThan(0.1);
+    const a = pts.get('a')!;
+    // Direction from `a` to each child, measured off `a` — the wedge's own axis
+    // is the direction from the centre to `a`.
+    const bearing = (id: string) => Math.atan2(pts.get(id)!.y - a.y, pts.get(id)!.x - a.x);
+    const outward = Math.atan2(a.y - 280, a.x - 450);
+    // `a` and `b` split the circle in two, so `a` owns a π wedge; three children
+    // take the centres of three π/3 slices: −π/3, 0, +π/3 off the outward axis.
+    expect(bearing('a1') - outward).toBeCloseTo(-Math.PI / 3, 6);
+    expect(bearing('a2') - outward).toBeCloseTo(0, 6);
+    expect(bearing('a3') - outward).toBeCloseTo(Math.PI / 3, 6);
+    // Symmetric about the axis, and all still one ring step out.
+    for (const id of ['a1', 'a2', 'a3']) {
+      expect(Math.hypot(pts.get(id)!.x - a.x, pts.get(id)!.y - a.y), id).toBeCloseTo(116, 6);
+    }
+    // A child pushed off its parent's outward direction lands INSIDE maxRadius.
+    for (const id of ['a1', 'a3']) {
+      expect(Math.hypot(pts.get(id)!.x - 450, pts.get(id)!.y - 280), id).toBeLessThan(232);
     }
   });
 
@@ -324,12 +479,11 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
    *
    * The MARGIN is what this asserts, in units, on each side. It used to be
    * stated as a ratio ("the sweep needs ~2× the settled height"), which was only
-   * ever a proxy: the ratio is large exactly when the rest state is FLAT, and
-   * flattening the rest state is the bug the ring phase just fixed (settled
-   * aspect 0.40 → 0.91, so the ratio fell from 2.14 to 1.31 while the thing it
-   * was standing in for — how much a settled-fit frame would chop off the
-   * assembly — barely moved, 59 units against 62). Measured on each side:
-   * desktop 59.0 / 59.3, mobile 33.5 / 33.5.
+   * ever a proxy for "a settled fit would clip" and moved for reasons that had
+   * nothing to do with clipping. Measured on each side: desktop 91.1 / 104.7,
+   * mobile 63.6 / 73.5 — wider under the radial tree than under the rings
+   * (59.0 / 59.3 and 33.5 / 33.5), because a three-branch tree is a wide, short
+   * object sitting inside a circular sweep.
    */
   for (const view of GRAPH_VIEWS) {
     it(`the ${view.maxRadius}-radius sweep leaves the settled bounding box`, () => {
@@ -371,14 +525,27 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
   }
 
   /**
-   * #344 visual 3, second wave — the settled graph has to FILL the frame it is
-   * given. The flat outer ring (both depth-2 nodes on the horizontal axis) made
-   * the rest state 0.40-aspect inside a 0.86-aspect sweep, so the fitted box
-   * carried a dead band above and below the drawing: 264 of 620 rendered px,
-   * ~43%. The diagonal ring lifts every fixture past 0.60 aspect and 0.70 of
-   * the box height.
+   * CRITERION 4 — the settled drawing has to be a SANE SHAPE, sitting in the
+   * middle of the frame it is given.
+   *
+   * The bar this replaces asked for aspect ≥ 0.60 and ≥ 0.70 of the frame
+   * height, which the ring layout met (0.91–1.01 / 0.73) while putting children
+   * nowhere near their parents. The radial tree cannot meet the height bar and
+   * should not be asked to: three children 120° apart, two of them carrying a
+   * second segment, make an object 1.73× as wide as it is tall, and the frame
+   * is fitted to a near-circular sweep. Measured: aspect 0.626 / 0.575 / 0.597
+   * desktop, 0.634 / 0.558 / 0.590 phone; 0.83–0.92 of the frame's WIDTH
+   * against the ring layout's 0.71–0.79, and 0.56–0.60 of its height.
+   *
+   * So the assertions are: the aspect stays inside a stated window (a
+   * re-flattening to the old 0.40, or a tall skinny chain, still fails), the
+   * drawing fills a real share of the frame in EACH axis, and — the part the
+   * height bar was really standing in for — it is CENTRED, so whatever
+   * whitespace the sweep costs is spent symmetrically instead of shoved to one
+   * side. The ring-phase family that keeps children with their parents but
+   * seats a branch at 12 o'clock measures 10.4% off-centre and fails this.
    */
-  describe('the settled graph fills its own frame', () => {
+  describe('the settled graph is a sane shape, centred in its frame', () => {
     for (const view of GRAPH_VIEWS) {
       for (const graph of COURSE_GRAPHS) {
         it(`${graph.id} at maxRadius ${view.maxRadius}`, () => {
@@ -404,10 +571,21 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
             t = Math.min(t, e.top);
             b = Math.max(b, e.bottom);
           }
-          // Measured: 1.006 / 0.910 / 0.951 desktop, 1.006 / 0.844 / 0.910 phone.
-          expect((b - t) / (r - l), 'settled aspect').toBeGreaterThanOrEqual(0.6);
-          // Measured: 0.730 desktop, 0.733 phone — was 0.447 / 0.483.
-          expect((b - t) / view.fit.h, 'share of the frame height').toBeGreaterThan(0.7);
+          const aspect = (b - t) / (r - l);
+          expect(aspect, 'settled aspect').toBeGreaterThanOrEqual(0.55);
+          expect(aspect, 'settled aspect').toBeLessThanOrEqual(1.1);
+          // Measured: 0.81–0.92 wide, 0.56–0.60 tall.
+          expect((r - l) / view.fit.w, 'share of the frame width').toBeGreaterThan(0.75);
+          expect((b - t) / view.fit.h, 'share of the frame height').toBeGreaterThan(0.55);
+          // Centred: measured ≤ 3.4% of the width, ≤ 1.4% of the height.
+          expect(
+            Math.abs((l + r) / 2 - (view.fit.x + view.fit.w / 2)) / view.fit.w,
+            'horizontal off-centre',
+          ).toBeLessThan(0.05);
+          expect(
+            Math.abs((t + b) / 2 - (view.fit.y + view.fit.h / 2)) / view.fit.h,
+            'vertical off-centre',
+          ).toBeLessThan(0.05);
         });
       }
     }
@@ -436,8 +614,8 @@ describe('fitViewBox — one stable frame for every course', () => {
     // The shipped bug: `viewBox="0 0 900 560"` around content 578 units wide.
     expect(DESKTOP_VIEW.fit.w).toBeLessThan(DESKTOP_VIEW.w);
     expect(DESKTOP_VIEW.fit.h).toBeLessThan(DESKTOP_VIEW.h);
-    expect(viewBoxAttr(DESKTOP_VIEW.fit)).toBe('185 33 526 516');
-    expect(viewBoxAttr(MOBILE_VIEW.fit)).toBe('-4 -1 364 330');
+    expect(viewBoxAttr(DESKTOP_VIEW.fit)).toBe('165 48 541 498');
+    expect(viewBoxAttr(MOBILE_VIEW.fit)).toBe('-38 -11 414 356');
   });
 });
 
@@ -547,9 +725,15 @@ describe('GraphView sizing at a 390px viewport', () => {
 
   it('renders legible labels and dots on a phone', () => {
     const scale = CONTENT_PX / MOBILE_VIEW.fit.w;
-    expect(scale).toBeCloseTo(0.9121, 4);
-    // 12.8 CSS px labels (was 4.56), 25.5 CSS px dot diameter (was 10.64),
-    // 301 CSS px of graph height (was 213).
+    expect(scale).toBeCloseTo(0.8019, 4);
+    // 11.23 CSS px labels, 20.85 CSS px dot diameter, 285.5 CSS px of graph
+    // height. TIGHTER than the ring layout's 12.77 / 25.54 / 301.0, and
+    // deliberately so: see `MOBILE_VIEW`. A 13-character label at this type
+    // scale is 1.34× the ring step, so the phone geometry is bracketed from
+    // BELOW by the label-vs-child-dot collision (which wants a bigger ring) and
+    // from ABOVE by this gate (which wants a smaller frame), and the window
+    // between them is about four units of ring wide. There is no slack here to
+    // spend: any future type-scale nudge has to re-solve both at once.
     expect(MOBILE_VIEW.font * scale).toBeGreaterThanOrEqual(11);
     expect(2 * MOBILE_VIEW.nodeR * scale).toBeGreaterThanOrEqual(20);
     expect(MOBILE_VIEW.fit.h * scale).toBeGreaterThanOrEqual(260);
diff --git a/frontend/src/components/marketing/graph/layout.ts b/frontend/src/components/marketing/graph/layout.ts
index ccf94ede..429ee0be 100644
--- a/frontend/src/components/marketing/graph/layout.ts
+++ b/frontend/src/components/marketing/graph/layout.ts
@@ -93,64 +93,23 @@ export function easeOutCubic(t: number): number {
 }
 
 /**
- * Where a ring's FIRST node sits, as an angle from 3 o'clock. SVG angles run
- * clockwise (y grows downward), so −π/2 is 12 o'clock.
+ * The BFS spanning tree of the UNDIRECTED graph, rooted at `graph.rootId`.
  *
- * THE BUG THIS FIXES. The rule used to be "start at 12 o'clock, and rotate
- * alternate rings by half a slot so spokes don't line up" — `offset = d % 2 ===
- * 0 ? step / 2 : 0` against a `−π/2` start. On a ring of exactly TWO nodes,
- * which is what depth 2 holds in all three fixtures, `step = π`, the half slot
- * is `π/2`, and the two angles collapse to exactly 0 and π: BOTH outer nodes
- * dead on the horizontal axis through the centre. That made the settled layout
- * a flat ellipse (aspect 0.40) sitting inside a near-circular entry sweep
- * (0.86), so the fitted frame could never be tight — the graph filled 45% of
- * its own box height and left a visible dead band above and below it.
+ * `DemoNode.children` is deliberately NOT consulted: it is dead data that
+ * disagrees with `edges` (nothing reads it but the fixtures' own prose), and
+ * trusting it would put a node's position and its drawn edges on two different
+ * sources of truth. Every edge is undirected here because the demo draws them
+ * undirected.
  *
- * THE RULE. Every ring starts three quarters of a slot BACK from 3 o'clock, so
- * its angles are `(4i − 3) · step/4` — ODD multiples of `step/4 = π/(2·count)`.
- * An odd multiple of `π/(2n)` is never a multiple of π (that would need
- * `odd = 2kn`), so no ring of ANY size can put a node on the horizontal axis.
- * For the shipped ring sizes it resolves to:
- *
- *   count 3 (depth 1): −3·(2π/3)/4 = −π/2 → 12, 4 and 8 o'clock, i.e. the exact
- *                      triangle this branch was designed and reviewed against.
- *   count 2 (depth 2): −3π/4              → the NW↔SE diagonal.
- *
- * The diagonal's DIRECTION is not free. Every fixture hangs its two outer nodes
- * off the 12 o'clock and 4 o'clock children, so the mirrored diagonal (SW↔NE,
- * `+3·step/4`) drags a depth-1 → depth-2 edge across the centre and straight
- * through a label: −7.2 units of overlap, measured, against +29.2 of clearance
- * the way round it is.
- *
- * `alternate` keeps the half-slot rotation the old rule existed for, but only
- * where it can actually do something: when a ring holds the same number of
- * nodes as the ring inside it, and the two would otherwise line up into radial
- * spokes. Half a slot moves the angles to `(4i − 1) · step/4` — still odd
- * multiples of `step/4`, so the no-horizontal proof holds on that branch too.
- * No shipped fixture reaches it (3 then 2).
- */
-function ringPhase(count: number, innerCount: number | undefined): number {
-  const step = (Math.PI * 2) / count;
-  return (count === innerCount ? -1 : -3) * (step / 4);
-}
-
-/**
- * Root at the centre, each BFS depth on its own ring, siblings spread evenly
- * around it, every ring phased by `ringPhase` so none of them flattens onto the
- * horizontal axis.
- *
- * `maxRadius` is the outermost ring's distance from the centre. It defaults to
- * the old inscribed-circle-minus-48 rule so every existing caller and test is
- * unchanged, but each view passes it explicitly: the binding constraint is the
- * *fitted* frame, not the layout box, and `min(w, h) / 2 - pad` can't express
- * that.
+ * The tree governs POSITION only. `AssemblingGraph` still draws every entry in
+ * `graph.edges`, cross-edges included — `cs-sorting → cs-complexity` closes a
+ * triangle back to the top of the frame and is a big part of why the picture
+ * reads as a graph rather than a star.
  */
-export function radialLayout(
-  graph: CourseGraph,
-  width: number,
-  height: number,
-  maxRadius: number = Math.min(width, height) / 2 - 48,
-): Map<string, Point> {
+function spanningTree(graph: CourseGraph): {
+  depth: Map<string, number>;
+  parent: Map<string, string>;
+} {
   const adj = new Map<string, string[]>();
   for (const e of graph.edges) {
     adj.set(e.source, [...(adj.get(e.source) ?? []), e.target]);
@@ -158,20 +117,93 @@ export function radialLayout(
   }
 
   const depth = new Map<string, number>([[graph.rootId, 0]]);
+  const parent = new Map<string, string>();
   const queue = [graph.rootId];
   while (queue.length) {
     const cur = queue.shift()!;
     for (const nxt of adj.get(cur) ?? []) {
       if (!depth.has(nxt)) {
         depth.set(nxt, depth.get(cur)! + 1);
+        parent.set(nxt, cur);
         queue.push(nxt);
       }
     }
   }
+  return { depth, parent };
+}
+
+/**
+ * Where the depth-1 ring's FIRST node sits, as an angle from 3 o'clock. SVG
+ * angles run clockwise (y grows downward), so −π/2 is 12 o'clock.
+ *
+ * THE INVARIANT, unchanged from the previous wave and for the same reason. The
+ * ring starts a quarter of a slot FORWARD of 3 o'clock, so its angles are
+ * `(4i + 1) · step/4` — ODD multiples of `step/4 = π/(2·count)`. An odd multiple
+ * of `π/(2n)` is never a multiple of π (that would need `odd = 2kn`), so a ring
+ * of ANY size lands no node on the horizontal axis through the centre. `−3` and
+ * `+1` are both odd, so this is the same proof the `−3·step/4` rule carried;
+ * the two differ only by one whole slot, i.e. by WHICH child gets which seat.
+ *
+ * WHY THE SEATS MOVED BY ONE. For count 3 the ring is 4, 8 and 12 o'clock
+ * either way. What changed is that the layout below is now a tree: the two
+ * children that carry subtrees (indices 0 and 1 in all three fixtures) grow a
+ * second segment straight outward, and every label hangs BELOW its dot. Seated
+ * at 4 and 8 o'clock those arms grow downward and their labels fall away from
+ * the root; seated at 12 o'clock (the old `−3·step/4`) an arm grows straight up
+ * and the drawing goes lopsided — measured, that phase puts the settled box
+ * 10.4% of the frame off-centre and cannot be made collision-free at the phone
+ * breakpoint at any radius (worst pair −2.7 units at `maxRadius` 200, still
+ * negative). The childless third child takes the 12 o'clock seat, where its
+ * label is the only object above the root.
+ *
+ * That does tie the composition to fixture declaration order — the third child
+ * being the leaf. It is the same dependency the ring layout had, and it is
+ * pinned by the collision suite rather than left to chance.
+ */
+function ringPhase(count: number): number {
+  return (Math.PI * 2) / count / 4;
+}
+
+/**
+ * A RADIAL TREE. Root at the centre; depth-1 spread evenly around the full
+ * circle at radius `ring`; every deeper node placed at radius `ring` from ITS
+ * OWN PARENT, inside a wedge centred on the direction from the centre to that
+ * parent. Siblings share (and subdivide) the wedge.
+ *
+ * THE BUG THIS FIXES. The layout used to be global concentric RINGS: a node's
+ * angle came from its index within its depth, so it had no relationship to
+ * where its parent sat. With the shipped 6-node fixtures that scatters the
+ * graph — `cs-sorting` (a child of `cs-arrays`) landed 171 units from its
+ * parent on a ring of radius 232, `cs-trees` was flung to the opposite corner,
+ * and the result read as a lopsided diagonal smear rather than a tree. Tuning
+ * the ring angles cannot fix it: the previous wave swept them, moved the
+ * aspect metric from 0.436 to 1.006, and made the composition visibly worse.
+ * Every tree edge is now exactly one `ring` long — max 170.9 → 116.0 desktop,
+ * mean 128.5 → 116.0 — because a child is placed off its parent, not off the
+ * centre.
+ *
+ * `maxRadius` is the spatial budget: `ring = maxRadius / maxDepth`, so a chain
+ * of `maxDepth` collinear steps lands exactly on it. A node whose siblings push
+ * it off its parent's outward direction sits INSIDE that radius, so `maxRadius`
+ * is an upper bound rather than an exact outer ring. It defaults to the old
+ * inscribed-circle-minus-48 rule so every existing caller and test is
+ * unchanged, but each view passes it explicitly: the binding constraint is the
+ * *fitted* frame, not the layout box, and `min(w, h) / 2 - pad` can't express
+ * that.
+ *
+ * Deterministic by construction: no randomness, no clock, no DOM read.
+ */
+export function radialLayout(
+  graph: CourseGraph,
+  width: number,
+  height: number,
+  maxRadius: number = Math.min(width, height) / 2 - 48,
+): Map<string, Point> {
+  const { depth, parent } = spanningTree(graph);
 
   const byDepth = new Map<number, string[]>();
-  // Iterate graph.nodes (declaration order), not the Map, so ring ordering is
-  // stable regardless of BFS visit order.
+  // Iterate graph.nodes (declaration order), not the Map, so sibling ordering
+  // is stable regardless of BFS visit order.
   for (const n of graph.nodes) {
     const d = depth.get(n.id) ?? 0;
     byDepth.set(d, [...(byDepth.get(d) ?? []), n.id]);
@@ -183,22 +215,52 @@ export function radialLayout(
   const ring = maxRadius / maxDepth;
 
   const out = new Map<string, Point>();
-  for (const [d, ids] of byDepth) {
+  /** Direction from the CENTRE to this node — the axis its own wedge is built on. */
+  const heading = new Map<string, number>();
+  /** Angular span this node's subtree owns, subdivided among its children. */
+  const wedge = new Map<string, number>();
+
+  for (const d of [...byDepth.keys()].sort((a, b) => a - b)) {
+    const ids = byDepth.get(d)!;
+
+    // Depth 0 is the root — plus, defensively, anything the BFS never reached.
     if (d === 0) {
       for (const id of ids) out.set(id, { x: cx, y: cy });
       continue;
     }
-    const step = (Math.PI * 2) / ids.length;
-    // Depth 0 is the centre, not a ring, so the innermost ring has nothing to
-    // line up with and never alternates.
-    const phase = ringPhase(ids.length, d > 1 ? byDepth.get(d - 1)?.length : undefined);
-    ids.forEach((id, i) => {
-      const a = i * step + phase;
-      out.set(id, {
-        x: cx + Math.cos(a) * ring * d,
-        y: cy + Math.sin(a) * ring * d,
+
+    if (d === 1) {
+      const step = (Math.PI * 2) / ids.length;
+      const phase = ringPhase(ids.length);
+      ids.forEach((id, i) => {
+        const a = i * step + phase;
+        out.set(id, { x: cx + Math.cos(a) * ring, y: cy + Math.sin(a) * ring });
+        heading.set(id, a);
+        wedge.set(id, step);
       });
-    });
+      continue;
+    }
+
+    const siblings = new Map<string, string[]>();
+    for (const id of ids) {
+      const p = parent.get(id)!;
+      siblings.set(p, [...(siblings.get(p) ?? []), id]);
+    }
+    for (const [p, kids] of siblings) {
+      const anchor = out.get(p)!;
+      const base = heading.get(p) ?? Math.atan2(anchor.y - cy, anchor.x - cx);
+      const span = wedge.get(p) ?? Math.PI * 2;
+      const slice = span / kids.length;
+      kids.forEach((id, i) => {
+        // Centre of this child's slice — a lone child therefore lands exactly
+        // on the parent's outward direction, i.e. collinear with the centre.
+        const a = base - span / 2 + (i + 0.5) * slice;
+        const q = { x: anchor.x + Math.cos(a) * ring, y: anchor.y + Math.sin(a) * ring };
+        out.set(id, q);
+        heading.set(id, Math.atan2(q.y - cy, q.x - cx));
+        wedge.set(id, slice);
+      });
+    }
   }
   return out;
 }
@@ -262,29 +324,27 @@ export function labelHalfWidth(label: string, geom: GraphGeometry): number {
 /**
  * Where a node's label baseline sits, relative to the node's drawn centre.
  *
- * On DESKTOP the root's label goes above it (#344 visual 4). It went there to
- * dodge the outer-ring → depth-1 edge, which the old flat ring dragged across
- * the root's x at `cy + 0.349 × ring` — straight through "CS 210". The ring
- * phase (see `ringPhase`) has since pulled that diagonal off the centre, so
- * below is no longer a collision either; above is kept because it is still the
- * roomier half. Measured, across all three fixtures: above clears everything by
- * 29.2 units, below by 11.5 — the binding neighbour there is the depth-1 chord
- * (`ma-matrices → ma-eigen`, `sm-dist → sm-testing`) at `cy + ring/2`, i.e.
- * `cy + 58`, against a below-baseline label bottom at `cy + 46.5`.
+ * On DESKTOP the root's label stays above it (#344 visual 4). Both halves are
+ * collision-free under the tree, and the numbers moved: measured across all
+ * three fixtures, above clears by 8.80 units — the binding neighbour is the
+ * cross-edge that runs from an 8 o'clock child up to the 12 o'clock one
+ * (`ma-matrices → ma-eigen`, `sm-dist → sm-testing`) — and below by 31.24, in
+ * the open wedge between the two downward arms. So "below" is now the roomier
+ * half, where the ring layout made it the tighter one. It is a one-line flip if
+ * the composition ever wants it; it is not taken here because 8.80 units is
+ * 6.6 CSS px at the rendered cap, and because flipping it would leave
+ * `rootLabelAbove` false in every shipped view — a flag and a branch with no
+ * caller.
  *
- * On MOBILE it stays below, because there the geometry says so. The top child
- * sits `ring` above the root with its own label hanging back down toward it, so
- * an above-the-root label only clears it when
+ * On MOBILE it stays below, because there the geometry still forbids the
+ * alternative outright. The childless third child sits `ring` straight above
+ * the root with its own label hanging back down toward it, so an
+ * above-the-root label only clears it when
  *
  *     ring ≥ rootR + nodeR + 2·labelGap + cap + descender
  *
- * — 83.8 units at the desktop type scale, against a 116-unit ring: comfortable.
- * The phone's ring is 66 against a 95.7-unit requirement, so "above" would put
- * the course code straight through the first concept's label. Below is tight
- * but positive: the same depth-1 chord passes at `cy + 33.0` and the
- * below-baseline label's cap top is at `cy + 34.1`, 1.1 units clear — which is
- * the constraint `MOBILE_VIEW`'s geometry was tuned against, and it does not
- * move with the ring phase.
+ * — 84.1 units at the phone type scale, against an 81.5-unit ring. Measured,
+ * "above" overlaps that label by 8.72 units; below clears everything by 14.53.
  *
  * Shared with `fitViewBox` and `layout.test.ts` so the frame can never be
  * fitted to a label position the component doesn't actually use.
@@ -334,13 +394,15 @@ const FIT_STEPS = 512;
  * THE THING TO NOT GET WRONG: fit to the HELIX SWEEP, not to the settled node
  * positions. `helixEntry` rotates a node up to 1.5 turns around the centre on
  * the way in, so every outer node passes through every direction on its way to
- * rest: on desktop the sweep reaches ~237 units above and below the centre
- * while the settled drawing only reaches 178 above and 199 below. A box fitted
- * to the settled positions would clip 59 units — 81 CSS px at the rendered cap
- * — off the top and bottom of the assembly, in plain view; that exact bug was
- * found and fixed once already on this branch (#344 review #4). `layout.test.ts`
- * sweeps `t` across the full range to keep it fixed, and pins the overshoot
- * itself so a settled-fit implementation fails outright.
+ * rest. Under the radial tree that gap is WIDER than it was under the rings,
+ * because a tree is a wide object inside a circular sweep: on desktop the
+ * settled drawing spans 280.5 units of height while the sweep spans 476.3, so a
+ * box fitted to the settled positions would clip 91.1 units off the top and
+ * 104.7 off the bottom — 121 and 139 CSS px at the rendered cap, in plain view.
+ * That exact bug was found and fixed once already on this branch (#344 review
+ * #4). The phone numbers are 63.6 and 73.5. `layout.test.ts` sweeps `t` across
+ * the full range to keep it fixed, and pins the overshoot itself so a
+ * settled-fit implementation fails outright.
  *
  * Fitted ONCE across all three fixtures rather than per graph: the three share
  * a topology and differ only in label widths, so a per-graph fit would produce
@@ -402,20 +464,27 @@ function withFit(geom: GraphGeometry): GraphView {
 }
 
 /**
- * `maxRadius: 232` is still `radialLayout`'s old default (`min(900, 560) / 2 -
- * 48`), so the layout's spatial budget is unchanged and the depth-1 ring sits
- * exactly where this branch was designed against. What moved is the outer ring
- * — `ringPhase` takes it off the horizontal axis and onto the diagonal — and
- * the frame fitted around the result: `185 33 526 516`, against the
- * `0 0 900 560` the demo shipped with and the `159 42 578 498` the flat ring
- * fitted to.
+ * Untouched by the tree rewrite: `maxRadius: 232` is still `radialLayout`'s old
+ * default (`min(900, 560) / 2 - 48`), so the spatial budget, the type scale and
+ * the dot sizes are exactly what this branch was designed and reviewed against.
+ * Only the arrangement inside that budget changed, and the frame re-fitted
+ * around it: `165 48 541 498`, against `185 33 526 516` for the ring layout,
+ * `159 42 578 498` for the flat ring before that, and the `0 0 900 560` the
+ * demo shipped with.
  *
  * The component caps the rendered width (`md:max-w-[720px]`), so at the cap the
- * graph draws at 1.369 user units per CSS px: 16.4px labels, 38.3px concept
- * dots, a 71px root, and a 706px-tall `<svg>` where the fixed box reserved
- * 737px inside a 1184px container. The settled drawing fills 73% of that height
- * (515 of 706 CSS px); on the flat ring it filled 45% (277 of 620), which is
- * the dead band above and below the graph that this phase change removes.
+ * graph draws at 1.331 user units per CSS px: 16.0px labels, 37.3px concept
+ * dots, a 69px root, and a 663px-tall `<svg>` — 43px SHORTER than the ring
+ * layout's 706px and 74px shorter than the 737px the fixed box reserved.
+ *
+ * The composition it buys, measured on cs210: the drawing is 448 × 281 units
+ * (596 × 374 CSS px) inside a 541 × 498 frame, centred to within 18 units
+ * horizontally and 7 vertically. It fills 83% of the frame's width against the
+ * ring layout's 71%; it fills less of its height (56% against 73%) because a
+ * three-branch tree is a wide object and the frame is fitted to a near-circular
+ * entry sweep — see `fitViewBox`. That is the deliberate trade: symmetric
+ * whitespace above and below a balanced drawing, rather than a taller drawing
+ * whose children sit nowhere near their parents.
  */
 export const DESKTOP_VIEW: GraphView = withFit({
   w: 900,
@@ -432,48 +501,58 @@ export const DESKTOP_VIEW: GraphView = withFit({
 });
 
 /**
- * Portrait-ish and much smaller in user units, so a phone's ~332px content box
- * (390 viewport − 48 of `px-6` − the 10px scrollbar globals.css paints) renders
- * it at 0.91 rather than the 0.63 the desktop frame would give: 14-unit labels
- * land at 12.8 CSS px, concept dots at a 25.5px diameter, and the `<svg>` is
- * 301px tall (#344 review #3). The frame is `-4 -1 364 330`; the diagonal outer
- * ring both narrowed it (394 → 364) and filled it — the settled drawing is 73%
- * of its height, up from 48%.
+ * The phone view, RETUNED for the tree — and the reason the retune was not
+ * optional. Frame `-38 -11 414 356`; a ~332px content box (390 viewport − 48 of
+ * `px-6` − the 10px scrollbar globals.css paints) renders it at 0.802, so
+ * 14-unit labels land at 11.23 CSS px, concept dots at a 20.9px diameter, and
+ * the `<svg>` is 285px tall — all three still over the E2E legibility gate
+ * (≥11px labels, ≥20px dots, >260px tall), and all three tighter than the ring
+ * layout's 12.8 / 25.5 / 301.
  *
- * These numbers are RETUNED, not inherited. `maxRadius` used to be pinned at
- * 108 by the *labels* — the outer ring then sat on the horizontal axis, so the
- * widest one ("Central Limit") had to clear the hardcoded 360-unit edge. The
- * fitted frame absorbs that overhang now, and it also removes ~26 units of dead
- * width, which shrinks the rendered height: keeping the old geometry under the
- * fit lands the phone `<svg>` at 259px and fails the E2E legibility gate
- * (≥11px labels, ≥20px dots, >260px tall) outright.
+ * WHY THE RING HAD TO GROW (132 → 163). Labels hang below their dots and are
+ * `middle`-anchored, so a 13-character label ("Vector Spaces", "Distributions",
+ * "Central Limit") is 3.9·font units wide on each side of its node. In a tree
+ * the child of a depth-1 node sits `ring` away along that node's outward
+ * direction, and with three children 120° apart the flattest arm is always 30°
+ * off the horizontal — that is forced, not chosen: of two arms 120° apart, the
+ * best achievable worst-case horizontal step is `ring·sin(60°)`. So the child's
+ * dot lands inside its own parent's label unless
  *
- * So the phone geometry was searched against that gate AND against the settled
- * frame's crowding, which the old numbers were already losing (they overlapped
- * by 1.5 units before the halo, 3.2 with it). Two constraints bracket the ring
- * from both sides and are what picked 132/14/14/22:
+ *   0.866 · ring  >  3.9 · font + labelHalo/2 + nodeR
  *
- *   root label vs the horizontal depth-1 edge:  rootR + labelGap ≥ ring/2 + 11.9
- *   top child's label vs the root's own dot:    rootR + labelGap ≤ ring − nodeR − 5.2
+ * — `ring ≥ 76` at this type scale, against the 66 the ring layout used. At
+ * `ring = 66` the overlap measures −13.1 units on ma242 and sm275.
  *
- * which together need `ring ≥ 2·nodeR + 34.2`. Neither constraint moves with
- * the ring phase — both are about the root, its own top child, and the depth-1
- * chord — so the retune survives it unchanged: still +0.8 units on the worst
- * pair, now with 1.8px of label, 5.5px of dot and 41px of height in hand
- * against the E2E bars (the tighter frame renders everything larger).
+ * WHAT BOUNDS IT FROM ABOVE is the same E2E gate, through the fitted frame:
+ * `fit.w ≈ 3.65·ring + 7.8·font + labelHalo + 2·fitPad`, and legibility needs
+ * `font · 332 / fit.w ≥ 11`. The two brackets leave a window about 4 units of
+ * `ring` wide; 81.5 (`maxRadius` 163, halved by `maxDepth`) sits in it with
+ * +1.23 units on the worst label pair — up from the +0.80 the ring layout
+ * shipped — and +0.23 CSS px on the label gate. `nodeR` drops 14 → 13 and
+ * `fitPad` 10 → 2 to buy that window; both are spent directly on the two
+ * constraints above, and `fitPad` still has the fit's outward whole-unit snap
+ * under it.
+ *
+ * The other constraint the previous wave tuned against — the root's label
+ * versus the horizontal depth-1 chord — is GONE: with the branch-bearing
+ * children at 4 and 8 o'clock, the only depth-1 edge any fixture draws
+ * (`ma-matrices → ma-eigen`, `sm-dist → sm-testing`) runs from 8 o'clock to 12
+ * o'clock and never crosses the root's label band. What survives unchanged is
+ * the 12 o'clock child's label clearing the root's dot, which needs
+ * `ring > nodeR + labelGap + 5.2 + rootR` — 59.2 here, with 22 units in hand.
  */
 export const MOBILE_VIEW: GraphView = withFit({
   w: 360,
   h: 300,
-  maxRadius: 132,
+  maxRadius: 163,
   font: 14,
-  rootR: 24,
-  nodeR: 14,
-  labelGap: 22,
+  rootR: 22,
+  nodeR: 13,
+  labelGap: 19,
   rootLabelAbove: false,
-  labelHalo: 3.4,
+  labelHalo: 3.5,
   edgeW: 1.8,
-  fitPad: 10,
+  fitPad: 2,
 });
 
 /** Every view the demo can render in — the sweep target for the bounds test. */

From fc0afe84bc401d3844f6a293a4cd4f5cb74f4ef3 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 17:36:42 -0700
Subject: [PATCH 16/20] fix(landing): grow the graph upward from its base, not
 down from the middle (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The radial tree put the course root at the frame's centre and spread its
concepts around the full circle, so the drawing grew one arm up and two
down — an inverted Y, or a root system. The product is called Sapling and
the section headline is "Pick a course. Watch it grow."

Only the ANGULAR DOMAIN changes. The BFS spanning tree, the parent-relative
placement and the drawing of every edge (cross-edges included) are exactly
as the previous wave left them.

- depth-1 fans across the UPWARD half-plane, taking the interior gridlines
  of an (n+1)-way split of it: 45/90/135 degrees for three children. Never
  lands a child on the horizon at any fan size, and strictly further from
  it than the previous rule at every size.
- seats are handed out outside-in, biggest subtree first, so the deep arms
  get the open sky and the composition stays mirror-symmetric.
- the skeleton is laid out with the root at the origin and translated as a
  rigid body until its own bounding box is centred on the layout centre —
  the point helixEntry spirals around. The root ends up at the bottom-centre
  of the content and the sweep-fitted frame stays centred on the drawing.
- both views retuned against the new geometry (the budget is now solved
  from the type scale, the label clearances and the phone's legibility
  floor, not inherited from the layout box), and the root's label moves
  below its circle in both: above is now the direction the plant grows in.

Measured, desktop at the 720px cap: the <svg> is 637.6px tall against
662.8 (and 737 for the box this shipped with); cs210 fills 0.839 of the
frame's width against 0.828; the worst label clearance goes 8.80 -> 30.14
units. Phone: 11.99px labels and 22.48px dots against 11.23/20.85, and the
worst label clearance goes 0.99 -> 4.05 CSS px, retiring a margin that was
inside the noise of whether Chromium paints a scrollbar.

The frame's HEIGHT share does not improve (0.563 -> 0.532): fitViewBox
fits to the entry sweep, the sweep is very nearly a disc, so dead vertical
space is about (drawing width - drawing height)/2 for any layout and a
canopy is wider than tall. Documented at the assertion that was relaxed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 frontend/e2e/landing-graph.spec.ts            |  14 +-
 .../graph/KnowledgeGraphDemo.test.tsx         |  25 +-
 .../marketing/graph/KnowledgeGraphDemo.tsx    |  24 +-
 .../components/marketing/graph/layout.test.ts | 267 +++++++----
 .../src/components/marketing/graph/layout.ts  | 425 +++++++++++-------
 5 files changed, 493 insertions(+), 262 deletions(-)

diff --git a/frontend/e2e/landing-graph.spec.ts b/frontend/e2e/landing-graph.spec.ts
index 1f4d60fa..6e328e90 100644
--- a/frontend/e2e/landing-graph.spec.ts
+++ b/frontend/e2e/landing-graph.spec.ts
@@ -52,12 +52,14 @@ test('landing graph renders, swaps by course, and fades its copy on engagement',
  * box is ~332px, so the SVG rendered at a uniform 0.38 scale — 4.6 CSS px
  * concept labels and a 213px-tall smudge, on the device most marketing traffic
  * arrives on. The component now swaps to a phone view below the mobile
- * breakpoint, whose frame is fitted to its content (`-38 -11 414 356`, #344
- * visual 3): 0.80 scale ⇒ 11.2 CSS px labels, 20.9px dots, 285px tall. Those
- * three clear the bars below by 0.2px, 0.9px and 25px — the radial-tree layout
- * needs a wider ring to keep a child's dot out of its parent's label, and this
- * gate is what stops the ring growing further, so the margins are genuinely
- * thin. See `MOBILE_VIEW` in `layout.ts` for the two-sided bracket.
+ * breakpoint, whose frame is fitted to its content (`-32 -25 443 365`, #344
+ * visual 3): 0.75 scale ⇒ 12.0 CSS px labels, 22.5px dots, 273px tall. Those
+ * three clear the bars below by 1.0px, 2.5px and 13px. The bracket is still
+ * two-sided — a bigger ring keeps labels off their neighbours, a smaller frame
+ * keeps the type legible — but the upward fan put its two deep arms 90° apart
+ * and symmetric about the vertical, which widened the window: the first two
+ * margins were 0.2px and 0.9px under the downward tree. See `MOBILE_VIEW` in
+ * `layout.ts`.
  *
  * Asserting in CSS pixels — what a visitor's eye actually gets — rather than on
  * the viewBox attribute, so a different fix that reaches the same legibility
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
index 7457aed6..b750f8d6 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
@@ -605,21 +605,40 @@ describe('KnowledgeGraphDemo — node paint and label placement', () => {
     );
   });
 
-  it('places the root label above the node and concept labels below theirs', () => {
+  /**
+   * FLIPPED with the upward fan, and the flip is the point rather than a
+   * concession. This used to assert the root's label sat ABOVE its circle,
+   * which was right while the root sat in the middle of the frame with nothing
+   * over it. The root is now the BASE of the drawing and everything grows out
+   * of its top, so "above" means "on the stem running up to the middle shoot" —
+   * the halo has to cut that edge in two for the course code to stay legible,
+   * and the code stops reading as a caption for the whole picture. Below the
+   * base there is nothing but frame. Measured, below clears its nearest
+   * neighbour by 30.14 units against above's 9.83 (see `labelBaselineY`).
+   *
+   * The `rootLabelAbove` branch itself is untouched and still covered in
+   * `layout.test.ts`; what changed is which side the shipped views ask for.
+   */
+  it('places every label below its node, the root included', () => {
     render(<KnowledgeGraphDemo />);
     const g = COURSE_GRAPHS[0];
 
     const rootGroup = nodeGroup(g.rootId);
     const rootCy = Number(rootGroup.querySelector('circle')!.getAttribute('cy'));
     const rootBaseline = Number(rootGroup.querySelector('text')!.getAttribute('y'));
-    // Below the root is where the outer-ring → depth-1 edge crosses its x.
-    expect(rootBaseline).toBeLessThan(rootCy - DESKTOP_VIEW.rootR);
+    expect(rootBaseline).toBeGreaterThan(rootCy + DESKTOP_VIEW.rootR);
 
     const leaf = g.nodes.find((n) => n.id !== g.rootId)!;
     const leafGroup = nodeGroup(leaf.id);
     const leafCy = Number(leafGroup.querySelector('circle')!.getAttribute('cy'));
     const leafBaseline = Number(leafGroup.querySelector('text')!.getAttribute('y'));
     expect(leafBaseline).toBeGreaterThan(leafCy + DESKTOP_VIEW.nodeR);
+    // …and the root really is the base: every other node is drawn above it.
+    for (const n of g.nodes) {
+      if (n.id === g.rootId) continue;
+      const cy = Number(nodeGroup(n.id).querySelector('circle')!.getAttribute('cy'));
+      expect(cy, `${n.id} should sit above the root`).toBeLessThan(rootCy);
+    }
   });
 
   it('halos label text in the section backdrop so edges break around it', () => {
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index 3276e92f..8177adbf 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -194,10 +194,9 @@ function AssemblingGraph({
           >
             <circle cx={h.x} cy={h.y} r={r * h.scale} fill={nodeFill(graph, n)} />
             {/*
-              Labels sit ON the edge mesh — under the radial tree the root's own
-              label and its 12 o'clock child's both straddle the vertical edge
-              between them, and every arm's label straddles the edge running out
-              to its child (#344 visual 4).
+              Labels sit ON the edge mesh — under the upward fan every arm's
+              label straddles the edge running out to its child, and the middle
+              shoot's label sits across the stem it hangs from (#344 visual 4).
               `paint-order: stroke` lays a halo in the section's own backdrop
               colour under the glyphs and paints the fill over it, so a line
               passing behind a word breaks around the letterforms instead of
@@ -376,13 +375,16 @@ export default function KnowledgeGraphDemo() {
           direction the rest of the section already uses, and it is the reversible
           half of the choice: no copy moves, no structure changes.
 
-          At the 720px cap the desktop graph draws at ~1.33 units per CSS px in
-          a 720×663 box, where the fixed viewBox reserved 1184×737 and drew the
-          graph across the middle 277px of it. The box is 43px SHORTER than the
-          720×706 the concentric-ring layout fitted to: a radial tree is a wide,
-          short object, so it fills 83% of the frame's width (up from 71%) and
-          56% of its height, centred, with the whitespace the circular entry
-          sweep costs spent symmetrically above and below.
+          At the 720px cap the desktop graph draws at ~1.19 units per CSS px in
+          a 720×638 box, where the fixed viewBox reserved 1184×737 and drew the
+          graph across the middle 277px of it. The box is 25px SHORTER than the
+          720×663 the downward radial tree fitted to and 68px shorter than the
+          concentric rings before it: the course sits at the base and its
+          concepts fan upward, which is both the brand's picture and a wider,
+          shorter object — it fills 84% of the frame's width (up from 83%, and
+          from 71% under the rings) and 53% of its height, centred, with the
+          whitespace the circular entry sweep costs spent symmetrically above
+          and below.
         */}
         <svg
           data-testid="landing-graph-svg"
diff --git a/frontend/src/components/marketing/graph/layout.test.ts b/frontend/src/components/marketing/graph/layout.test.ts
index 68de8b90..47016c1a 100644
--- a/frontend/src/components/marketing/graph/layout.test.ts
+++ b/frontend/src/components/marketing/graph/layout.test.ts
@@ -59,9 +59,58 @@ describe('radialLayout', () => {
     for (const n of G.nodes) expect(p.get(n.id)).toBeDefined();
   });
 
-  it('puts the root at the centre', () => {
+  /**
+   * CRITERION 1 — the whole point of this wave. The section is called "Pick a
+   * course. Watch it grow." and the product is called Sapling; the layout used
+   * to spread depth-1 around the FULL circle with the root at the frame's
+   * centre, so the drawing grew one arm up and two down and read as an inverted
+   * Y. Every node that is not the root now sits STRICTLY ABOVE it — smaller y,
+   * SVG coordinates — in every fixture, in every shipped view.
+   *
+   * Asserted as a margin rather than as `< rootY` so a layout that merely
+   * grazes the root's own line (the ring layout put two nodes exactly on it)
+   * cannot squeak through: the closest any node comes is `ring · sin(π/4)`,
+   * measured 113.1 units on desktop and 74.9 on the phone.
+   */
+  it('grows upward — every node sits strictly above the root', () => {
+    for (const graph of COURSE_GRAPHS) {
+      for (const view of GRAPH_VIEWS) {
+        const pts = radialLayout(graph, view.w, view.h, view.maxRadius);
+        const root = pts.get(graph.rootId)!;
+        for (const n of graph.nodes) {
+          if (n.id === graph.rootId) continue;
+          expect(
+            pts.get(n.id)!.y,
+            `${graph.id}/${n.id} at maxRadius ${view.maxRadius}`,
+          ).toBeLessThan(root.y - view.nodeR);
+        }
+      }
+    }
+  });
+
+  /**
+   * …and the other half of criterion 1: the root is at the BOTTOM-CENTRE of the
+   * content, not in the middle of it.
+   *
+   * `radialLayout` lays the skeleton out with the root at the origin and then
+   * translates it as a rigid body until the skeleton's own bounding box is
+   * centred on `(w/2, h/2)` — the point `helixEntry` spirals around and
+   * `fitViewBox` fits its frame about. So the root is the LOWEST node, it is
+   * horizontally centred in the drawing (the fan is mirror-symmetric), and it
+   * sits BELOW the layout centre rather than on it.
+   */
+  it('puts the root at the bottom-centre of the content', () => {
     const p = radialLayout(G, 800, 500);
-    expect(p.get(G.rootId)).toEqual({ x: 400, y: 250 });
+    const root = p.get(G.rootId)!;
+    const xs = [...p.values()].map((q) => q.x);
+    const ys = [...p.values()].map((q) => q.y);
+
+    expect(root.y).toBe(Math.max(...ys));
+    expect(root.x).toBeCloseTo((Math.min(...xs) + Math.max(...xs)) / 2, 6);
+    expect(root.x).toBeCloseTo(400, 6);
+    expect(root.y).toBeGreaterThan(250);
+    // The skeleton, not the root, is what is centred on the layout box.
+    expect((Math.min(...ys) + Math.max(...ys)) / 2).toBeCloseTo(250, 6);
   });
 
   it('is deterministic', () => {
@@ -196,27 +245,36 @@ describe('radialLayout', () => {
   });
 
   /**
-   * CRITERION 3 — the invariant the previous wave established, carried over
-   * unchanged. The ring phase used to be a half slot on alternate depths, which
-   * on a 2-node ring (`step = π`, every fixture at depth 2 back then) resolved
-   * to exactly {0, π}: both outer nodes dead on the horizontal axis.
+   * The no-horizontal invariant, carried over — RETARGETED AT THE ROOT, which
+   * is the only retarget in this file that changes what is measured rather than
+   * what the number is.
    *
-   * The tree only phases ONE ring — depth 1 — but deeper nodes inherit their
-   * parent's heading when they are lone children, so the invariant has to hold
-   * for them too. Asserted as an angle off the horizontal, not as a coordinate.
+   * It used to measure the angle from `(w/2, h/2)`, which was the root. It is
+   * not any more: the root sits at the bottom-centre of the content and
+   * `(w/2, h/2)` is the centre of the skeleton's bounding box — the point the
+   * entry sweep spirals around. The line that matters for the drawing has
+   * always been "the horizontal through the node everything radiates from", and
+   * that node is the root. Measured off `(w/2, h/2)` instead, the two outer
+   * depth-1 children now sit exactly ON it by construction (the fan's tips and
+   * the root define the box, so its mid-line runs through them) — which is
+   * geometrically meaningless and would fail a test whose subject no longer
+   * exists.
+   *
+   * Off the ROOT the invariant is stronger than it has ever been: the closest
+   * any node comes to the horizon is `sin(π/4)` = 0.707, against 0.5 for the
+   * downward tree and exactly 0 for the ring layout it replaced. The bar stays
+   * at the 0.4 the previous wave set.
    */
-  it('never lands a node on the horizontal axis through the centre', () => {
+  it('never lands a node on the horizontal axis through the root', () => {
     for (const graph of COURSE_GRAPHS) {
       for (const view of GRAPH_VIEWS) {
         const pts = radialLayout(graph, view.w, view.h, view.maxRadius);
+        const root = pts.get(graph.rootId)!;
         for (const n of graph.nodes) {
           if (n.id === graph.rootId) continue;
           const p = pts.get(n.id)!;
-          const dx = p.x - view.w / 2;
-          const dy = p.y - view.h / 2;
-          // |sin| of the angle off the horizontal axis. The old rule measured
-          // exactly 0 on both depth-2 nodes; every node now measures 0.5 — 30°
-          // off, the tightest angle either ring produces.
+          const dx = p.x - root.x;
+          const dy = p.y - root.y;
           expect(
             Math.abs(dy) / Math.hypot(dx, dy),
             `${graph.id}/${n.id} at maxRadius ${view.maxRadius}`,
@@ -227,15 +285,20 @@ describe('radialLayout', () => {
   });
 
   /**
-   * …and the invariant `ringPhase` actually claims, which is stronger than the
-   * three fixtures: for a ring of ANY size the angles are odd multiples of
-   * `π/(2·count)`, so the closest one can ever come to the horizontal axis is
-   * one such step. Swept over ring sizes 1…24 on synthetic star graphs — the
-   * cheapest way to build a ring of a given size — with the count-aware floor
-   * rather than a flat number, because a flat number is only meaningful for the
-   * ring sizes that happen to ship today.
+   * …and the invariant `fanAngle` actually claims, which is stronger than the
+   * three fixtures: for a fan of ANY size the seat angles are
+   * `−π + k·π/(count+1)` for `k` in `1…count`, so the closest one can ever come
+   * to the horizontal is `sin(π/(count+1))`. Swept over fan sizes 1…24 on
+   * synthetic star graphs, with the count-aware floor rather than a flat
+   * number, because a flat number is only meaningful for the fan sizes that
+   * happen to ship today.
+   *
+   * The floor is the one the previous wave's `ringPhase` guaranteed —
+   * `sin(π/(2·count))` — kept deliberately: `π/(count+1) ≥ π/(2·count)` for
+   * every `count ≥ 1`, so passing it proves the new rule is never worse than
+   * the old one at any size, not merely that it happens to pass its own bar.
    */
-  it('holds the no-horizontal invariant at any ring size', () => {
+  it('holds the no-horizontal invariant at any fan size', () => {
     const star = (count: number): CourseGraph => ({
       id: `star${count}`,
       code: 'X',
@@ -256,26 +319,41 @@ describe('radialLayout', () => {
 
     for (let count = 1; count <= 24; count++) {
       const pts = radialLayout(star(count), 900, 560, 232);
-      // Half a slot of the ring's own quarter-slot grid, minus float slop.
+      const root = pts.get('r')!;
+      // The bar the previous wave's ring phase guaranteed, minus float slop.
       const floor = Math.sin(Math.PI / (2 * count)) * 0.999;
       for (let i = 0; i < count; i++) {
         const p = pts.get(`n${i}`)!;
-        const sin = Math.abs(p.y - 280) / Math.hypot(p.x - 450, p.y - 280);
-        expect(sin, `ring of ${count}, node ${i}`).toBeGreaterThan(floor);
+        const sin = Math.abs(p.y - root.y) / Math.hypot(p.x - root.x, p.y - root.y);
+        expect(sin, `fan of ${count}, node ${i}`).toBeGreaterThan(floor);
+        // …and every one of them is above the root, at any fan size.
+        expect(p.y, `fan of ${count}, node ${i}`).toBeLessThan(root.y);
       }
     }
   });
 
   /**
    * The wedge rule, which no shipped fixture exercises — every parent below the
-   * root has exactly one child, so every arm is collinear with the centre. This
+   * root has exactly one child, so every arm is collinear with its parent. This
    * pins what happens when one doesn't: siblings SHARE their parent's angular
-   * span, evenly and symmetrically about the parent's own outward direction, so
-   * a branchy graph fans out instead of stacking on one ray.
+   * span, evenly and symmetrically about the direction that parent itself grew
+   * in, so a branchy graph fans out instead of stacking on one ray.
+   *
+   * RETARGETED, not weakened. Two of its numbers moved with the angular domain,
+   * and both moves are the subject of this wave:
    *
-   * (It replaces the old "breaks radial spokes when two rings hold the same node
-   * count" test, whose subject — a half-slot rotation applied to the SECOND
-   * concentric ring — no longer exists: there are no rings past depth 1.)
+   * - the axis. It used to be measured as the bearing from `(w/2, h/2)` to the
+   *   parent, which was the same thing as "the direction the parent grew" only
+   *   because the root sat at `(w/2, h/2)`. It no longer does, so the axis is
+   *   now read off the root — which is what "the parent's outward direction"
+   *   meant all along.
+   * - the span. Depth-1 used to own a full `2π/count` slot of a circle; it now
+   *   owns a `π/(count+1)` slot of the upward half-plane. With two children
+   *   that is π/3 rather than π, so three grandchildren land at −π/9, 0, +π/9
+   *   off the axis instead of −π/3, 0, +π/3. The RULE — even, symmetric
+   *   subdivision of exactly the parent's own span — is unchanged and is what
+   *   is asserted; the arithmetic is derived from `π/(count+1)` in the test so
+   *   it cannot drift from the implementation silently.
    */
   it('splits a parent’s wedge evenly between its children', () => {
     const graph: CourseGraph = {
@@ -300,33 +378,48 @@ describe('radialLayout', () => {
     };
     const pts = radialLayout(graph, 900, 560, 232);
     const a = pts.get('a')!;
-    // Direction from `a` to each child, measured off `a` — the wedge's own axis
-    // is the direction from the centre to `a`.
+    const root = pts.get('r')!;
+    // Direction from `a` to each child, measured off `a`. The wedge's own axis
+    // is the direction `a` itself grew in, i.e. the bearing from the ROOT.
     const bearing = (id: string) => Math.atan2(pts.get(id)!.y - a.y, pts.get(id)!.x - a.x);
-    const outward = Math.atan2(a.y - 280, a.x - 450);
-    // `a` and `b` split the circle in two, so `a` owns a π wedge; three children
-    // take the centres of three π/3 slices: −π/3, 0, +π/3 off the outward axis.
-    expect(bearing('a1') - outward).toBeCloseTo(-Math.PI / 3, 6);
+    const outward = Math.atan2(a.y - root.y, a.x - root.x);
+    // `a` and `b` take two of a 3-way split of the upward half-plane, so `a`
+    // owns a π/3 wedge; three children take the centres of three π/9 slices.
+    const slice = Math.PI / (2 + 1) / 3;
+    expect(bearing('a1') - outward).toBeCloseTo(-slice, 6);
     expect(bearing('a2') - outward).toBeCloseTo(0, 6);
-    expect(bearing('a3') - outward).toBeCloseTo(Math.PI / 3, 6);
+    expect(bearing('a3') - outward).toBeCloseTo(slice, 6);
     // Symmetric about the axis, and all still one ring step out.
     for (const id of ['a1', 'a2', 'a3']) {
       expect(Math.hypot(pts.get(id)!.x - a.x, pts.get(id)!.y - a.y), id).toBeCloseTo(116, 6);
     }
-    // A child pushed off its parent's outward direction lands INSIDE maxRadius.
+    // A child pushed off its parent's outward direction lands INSIDE maxRadius
+    // of the root — `maxRadius` is a budget, not an outer ring.
     for (const id of ['a1', 'a3']) {
-      expect(Math.hypot(pts.get(id)!.x - 450, pts.get(id)!.y - 280), id).toBeLessThan(232);
+      expect(Math.hypot(pts.get(id)!.x - root.x, pts.get(id)!.y - root.y), id).toBeLessThan(232);
     }
+    // The deeper subtree took an OUTER seat: `a` carries three children and `b`
+    // none, so `a` is further from the vertical through the root than `b` is.
+    const off = (id: string) => Math.abs(pts.get(id)!.x - root.x);
+    expect(off('a')).toBeGreaterThan(off('b') - 1e-9);
   });
 
   it('keeps the default maxRadius at the old inscribed-circle rule', () => {
     // The `maxRadius` parameter was added for the mobile view (#344 review #3).
-    // Its default has to reproduce the desktop geometry this branch was
-    // designed against byte-for-byte, or every existing frame shifts.
+    // Its DEFAULT is unchanged, so every caller that omits it — the two tests
+    // above, and anything outside this module — keeps the geometry it had.
     expect(radialLayout(G, 900, 560)).toEqual(
       radialLayout(G, 900, 560, Math.min(900, 560) / 2 - 48),
     );
-    expect(DESKTOP_VIEW.maxRadius).toBe(Math.min(DESKTOP_VIEW.w, DESKTOP_VIEW.h) / 2 - 48);
+    // DESKTOP_VIEW no longer takes that default (232 → 320), and the assertion
+    // that it did is gone rather than adjusted, because the identity was never
+    // the point: the layout box only fixes the entry sweep's centre, while the
+    // spatial budget is bracketed by the rendered type scale, the label
+    // clearances and the phone's legibility floor. Pinning the value is this
+    // test's job; pinning it to an arithmetic coincidence with `w`/`h` would
+    // just re-break the moment either is retuned.
+    expect(DESKTOP_VIEW.maxRadius).toBe(320);
+    expect(MOBILE_VIEW.maxRadius).toBe(212);
   });
 });
 
@@ -480,10 +573,11 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
    * The MARGIN is what this asserts, in units, on each side. It used to be
    * stated as a ratio ("the sweep needs ~2× the settled height"), which was only
    * ever a proxy for "a settled fit would clip" and moved for reasons that had
-   * nothing to do with clipping. Measured on each side: desktop 91.1 / 104.7,
-   * mobile 63.6 / 73.5 — wider under the radial tree than under the rings
-   * (59.0 / 59.3 and 33.5 / 33.5), because a three-branch tree is a wide, short
-   * object sitting inside a circular sweep.
+   * nothing to do with clipping. Measured on each side: desktop 125.8 / 103.6,
+   * mobile 82.9 / 69.6 — wider again under the upward fan than under the
+   * downward tree (91.1 / 104.7 and 63.6 / 73.5), which were themselves wider
+   * than the rings (59.0 / 59.3 and 33.5 / 33.5), because a canopy is a wide,
+   * short object sitting inside a circular sweep.
    */
   for (const view of GRAPH_VIEWS) {
     it(`the ${view.maxRadius}-radius sweep leaves the settled bounding box`, () => {
@@ -525,25 +619,36 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
   }
 
   /**
-   * CRITERION 4 — the settled drawing has to be a SANE SHAPE, sitting in the
+   * CRITERION 4/5 — the settled drawing has to be a SANE SHAPE, sitting in the
    * middle of the frame it is given.
    *
-   * The bar this replaces asked for aspect ≥ 0.60 and ≥ 0.70 of the frame
-   * height, which the ring layout met (0.91–1.01 / 0.73) while putting children
-   * nowhere near their parents. The radial tree cannot meet the height bar and
-   * should not be asked to: three children 120° apart, two of them carrying a
-   * second segment, make an object 1.73× as wide as it is tall, and the frame
-   * is fitted to a near-circular sweep. Measured: aspect 0.626 / 0.575 / 0.597
-   * desktop, 0.634 / 0.558 / 0.590 phone; 0.83–0.92 of the frame's WIDTH
-   * against the ring layout's 0.71–0.79, and 0.56–0.60 of its height.
+   * TWO BARS MOVED WITH THE UPWARD FAN, both deliberately, both downward.
+   *
+   * The ASPECT WINDOW goes 0.55–1.10 → 0.40–0.80. A canopy is legitimately
+   * wider than tall: three shoots leaving one base 45° apart, two of them
+   * carrying a second segment, make an object about twice as wide as it is
+   * high. Measured 0.562 / 0.515 / 0.535 desktop, 0.575 / 0.502 / 0.533 phone —
+   * comfortably inside. The new CEILING is the load-bearing half: it is what
+   * fails the "grow it straight up into a tall skinny chain" family, which is
+   * the way an upward layout goes wrong.
+   *
+   * The FRAME-HEIGHT SHARE goes 0.55 → 0.50 (measured 0.532 desktop, 0.569
+   * phone, against 0.563 / 0.599 for the downward tree). That is a real, small
+   * regression and it is geometric, not a tuning slip: `fitViewBox` fits to the
+   * ENTRY SWEEP, the sweep is very nearly a disc, so the frame is very nearly
+   * square whatever the drawing does, and dead vertical space is therefore
+   * ≈ (drawing width − drawing height) / 2 for ANY layout. Widening the drawing
+   * to fill more of the frame's width — which criterion 4 asks for and which
+   * this change delivers, 0.828 → 0.839 on cs210 — necessarily spends a little
+   * of its height share. The bar is kept as a floor with a stated number rather
+   * than deleted, so a future change that empties the frame still fails.
    *
-   * So the assertions are: the aspect stays inside a stated window (a
-   * re-flattening to the old 0.40, or a tall skinny chain, still fails), the
-   * drawing fills a real share of the frame in EACH axis, and — the part the
-   * height bar was really standing in for — it is CENTRED, so whatever
-   * whitespace the sweep costs is spent symmetrically instead of shoved to one
-   * side. The ring-phase family that keeps children with their parents but
-   * seats a branch at 12 o'clock measures 10.4% off-centre and fails this.
+   * What is asserted, then: the aspect stays inside a stated window, the
+   * drawing fills a real share of the frame on EACH axis, and it is CENTRED, so
+   * whatever whitespace the sweep costs is spent symmetrically instead of
+   * shoved to one side. The left-to-right seating family — which grows upward
+   * and keeps children with their parents, but puts a two-step arm on the
+   * vertical and the leaf beside it — measures 13% off-centre and fails this.
    */
   describe('the settled graph is a sane shape, centred in its frame', () => {
     for (const view of GRAPH_VIEWS) {
@@ -572,12 +677,12 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
             b = Math.max(b, e.bottom);
           }
           const aspect = (b - t) / (r - l);
-          expect(aspect, 'settled aspect').toBeGreaterThanOrEqual(0.55);
-          expect(aspect, 'settled aspect').toBeLessThanOrEqual(1.1);
-          // Measured: 0.81–0.92 wide, 0.56–0.60 tall.
+          expect(aspect, 'settled aspect').toBeGreaterThanOrEqual(0.4);
+          expect(aspect, 'settled aspect').toBeLessThanOrEqual(0.8);
+          // Measured: 0.815–0.934 wide, 0.532–0.569 tall.
           expect((r - l) / view.fit.w, 'share of the frame width').toBeGreaterThan(0.75);
-          expect((b - t) / view.fit.h, 'share of the frame height').toBeGreaterThan(0.55);
-          // Centred: measured ≤ 3.4% of the width, ≤ 1.4% of the height.
+          expect((b - t) / view.fit.h, 'share of the frame height').toBeGreaterThan(0.5);
+          // Centred: measured ≤ 3.2% of the width, ≤ 2.1% of the height.
           expect(
             Math.abs((l + r) / 2 - (view.fit.x + view.fit.w / 2)) / view.fit.w,
             'horizontal off-centre',
@@ -614,8 +719,8 @@ describe('fitViewBox — one stable frame for every course', () => {
     // The shipped bug: `viewBox="0 0 900 560"` around content 578 units wide.
     expect(DESKTOP_VIEW.fit.w).toBeLessThan(DESKTOP_VIEW.w);
     expect(DESKTOP_VIEW.fit.h).toBeLessThan(DESKTOP_VIEW.h);
-    expect(viewBoxAttr(DESKTOP_VIEW.fit)).toBe('165 48 541 498');
-    expect(viewBoxAttr(MOBILE_VIEW.fit)).toBe('-38 -11 414 356');
+    expect(viewBoxAttr(DESKTOP_VIEW.fit)).toBe('161 17 603 534');
+    expect(viewBoxAttr(MOBILE_VIEW.fit)).toBe('-32 -25 443 365');
   });
 });
 
@@ -725,15 +830,17 @@ describe('GraphView sizing at a 390px viewport', () => {
 
   it('renders legible labels and dots on a phone', () => {
     const scale = CONTENT_PX / MOBILE_VIEW.fit.w;
-    expect(scale).toBeCloseTo(0.8019, 4);
-    // 11.23 CSS px labels, 20.85 CSS px dot diameter, 285.5 CSS px of graph
-    // height. TIGHTER than the ring layout's 12.77 / 25.54 / 301.0, and
-    // deliberately so: see `MOBILE_VIEW`. A 13-character label at this type
-    // scale is 1.34× the ring step, so the phone geometry is bracketed from
-    // BELOW by the label-vs-child-dot collision (which wants a bigger ring) and
-    // from ABOVE by this gate (which wants a smaller frame), and the window
-    // between them is about four units of ring wide. There is no slack here to
-    // spend: any future type-scale nudge has to re-solve both at once.
+    expect(scale).toBeCloseTo(0.7494, 4);
+    // 11.99 CSS px labels, 22.48 CSS px dot diameter, 273.5 CSS px of graph
+    // height. The phone geometry is still bracketed from BELOW by a label
+    // collision (which wants a bigger ring) and from ABOVE by this gate (which
+    // wants a smaller frame), but the upward fan widened the window: its two
+    // deep arms are 90° apart and symmetric, so the worst horizontal step is
+    // `ring·sin 45°` on both instead of `ring·sin 60°` on one and `ring·sin 30°`
+    // on the other. The margins on the three bars are +0.99px / +2.48px /
+    // +13.5px, against the downward tree's +0.23px / +0.85px / +25.5px — the
+    // first two roughly quadrupled, and the first one was inside the noise of
+    // whether Chromium paints a scrollbar at this viewport.
     expect(MOBILE_VIEW.font * scale).toBeGreaterThanOrEqual(11);
     expect(2 * MOBILE_VIEW.nodeR * scale).toBeGreaterThanOrEqual(20);
     expect(MOBILE_VIEW.fit.h * scale).toBeGreaterThanOrEqual(260);
diff --git a/frontend/src/components/marketing/graph/layout.ts b/frontend/src/components/marketing/graph/layout.ts
index 429ee0be..b7234f2b 100644
--- a/frontend/src/components/marketing/graph/layout.ts
+++ b/frontend/src/components/marketing/graph/layout.ts
@@ -102,9 +102,9 @@ export function easeOutCubic(t: number): number {
  * undirected.
  *
  * The tree governs POSITION only. `AssemblingGraph` still draws every entry in
- * `graph.edges`, cross-edges included — `cs-sorting → cs-complexity` closes a
- * triangle back to the top of the frame and is a big part of why the picture
- * reads as a graph rather than a star.
+ * `graph.edges`, cross-edges included — `cs-sorting → cs-complexity` runs from
+ * the canopy's left tip back down to the middle shoot, closing a triangle, and
+ * is a big part of why the picture reads as a graph rather than a sprig.
  */
 function spanningTree(graph: CourseGraph): {
   depth: Map<string, number>;
@@ -133,63 +133,134 @@ function spanningTree(graph: CourseGraph): {
 }
 
 /**
- * Where the depth-1 ring's FIRST node sits, as an angle from 3 o'clock. SVG
- * angles run clockwise (y grows downward), so −π/2 is 12 o'clock.
- *
- * THE INVARIANT, unchanged from the previous wave and for the same reason. The
- * ring starts a quarter of a slot FORWARD of 3 o'clock, so its angles are
- * `(4i + 1) · step/4` — ODD multiples of `step/4 = π/(2·count)`. An odd multiple
- * of `π/(2n)` is never a multiple of π (that would need `odd = 2kn`), so a ring
- * of ANY size lands no node on the horizontal axis through the centre. `−3` and
- * `+1` are both odd, so this is the same proof the `−3·step/4` rule carried;
- * the two differ only by one whole slot, i.e. by WHICH child gets which seat.
- *
- * WHY THE SEATS MOVED BY ONE. For count 3 the ring is 4, 8 and 12 o'clock
- * either way. What changed is that the layout below is now a tree: the two
- * children that carry subtrees (indices 0 and 1 in all three fixtures) grow a
- * second segment straight outward, and every label hangs BELOW its dot. Seated
- * at 4 and 8 o'clock those arms grow downward and their labels fall away from
- * the root; seated at 12 o'clock (the old `−3·step/4`) an arm grows straight up
- * and the drawing goes lopsided — measured, that phase puts the settled box
- * 10.4% of the frame off-centre and cannot be made collision-free at the phone
- * breakpoint at any radius (worst pair −2.7 units at `maxRadius` 200, still
- * negative). The childless third child takes the 12 o'clock seat, where its
- * label is the only object above the root.
- *
- * That does tie the composition to fixture declaration order — the third child
- * being the leaf. It is the same dependency the ring layout had, and it is
- * pinned by the collision suite rather than left to chance.
+ * Number of nodes in each node's subtree of the spanning tree, itself included.
+ *
+ * Only used to decide WHICH depth-1 seat a child gets (see `fanSeats`). Walking
+ * the depths from the outside in means a node's children are always counted
+ * before the node is added to its own parent, so one pass is enough.
+ */
+function subtreeSizes(
+  graph: CourseGraph,
+  depth: Map<string, number>,
+  parent: Map<string, string>,
+): Map<string, number> {
+  const size = new Map(graph.nodes.map((n) => [n.id, 1]));
+  const deepestFirst = [...graph.nodes]
+    .map((n) => n.id)
+    .sort((a, b) => (depth.get(b) ?? 0) - (depth.get(a) ?? 0));
+  for (const id of deepestFirst) {
+    const p = parent.get(id);
+    if (p) size.set(p, (size.get(p) ?? 1) + (size.get(id) ?? 1));
+  }
+  return size;
+}
+
+/**
+ * The seat angles of the depth-1 fan, left to right, as angles from 3 o'clock.
+ * SVG angles run clockwise (y grows downward), so −π is 9 o'clock, −π/2 is 12
+ * and 0 is 3 — i.e. the open interval (−π, 0) is the UPWARD half-plane.
+ *
+ * `count` children take the `count` interior gridlines of a (count + 1)-way
+ * split of that half-plane: `−π + (seat + 1) · π/(count + 1)`. For three
+ * children that is 45° / 90° / 135°, a canopy; for one it is straight up.
+ *
+ * WHY THE INTERIOR GRIDLINES and not slice centres (`(seat + ½) · π/count`,
+ * which would spread the same three children over 30° / 90° / 150°). Two
+ * reasons, both measured across all three fixtures × both views:
+ *
+ * - the horizon. Slice centres put the outermost child `π/(2·count)` off the
+ *   horizontal, which for a wide fan is a nearly flat arm whose second segment
+ *   runs level with the root; the gridlines put it `π/(count + 1)` off, which
+ *   is strictly further from the horizon for every `count > 1` and is why the
+ *   no-horizontal invariant below holds with room to spare (measured |sin| =
+ *   0.707 against a 0.5 floor).
+ * - shape. At 30° the settled drawing is 0.35 tall for every unit wide — a flat
+ *   candelabra. At 45° it is 0.51–0.56, which is the canopy the section's
+ *   "watch it grow" headline is describing.
+ *
+ * THE INVARIANT THIS KEEPS. No child ever lands on the horizontal axis through
+ * the root: the seat angles are `−π + k·π/(count+1)` for `k` in `1…count`, so
+ * `|sin θ| = sin(k·π/(count+1))`, which is zero only at `k = 0` or `k =
+ * count+1` — both outside the range. The previous wave proved the same property
+ * for a full-circle ring phased by an odd multiple of `π/(2·count)`; this is
+ * the half-plane version of it, and it is strictly stronger (the closest
+ * approach is `sin(π/(count+1))`, never worse than the old `sin(π/(2·count))`).
+ */
+function fanAngle(seat: number, count: number): number {
+  return -Math.PI + ((seat + 1) * Math.PI) / (count + 1);
+}
+
+/**
+ * The order the depth-1 seats are handed out in: OUTSIDE-IN — leftmost,
+ * rightmost, next-leftmost, next-rightmost, … — with the biggest subtrees
+ * going first (see the caller).
+ *
+ * The outer seats have open sky beyond them; the inner seats are hemmed in by a
+ * sibling on each side, so the branches that carry the most nodes get the room.
+ * With the shipped fixtures (two children carrying a grandchild, one leaf) that
+ * seats the two deep arms symmetrically about the vertical and leaves the leaf
+ * as a short central shoot — the sprout silhouette.
+ *
+ * The alternative — handing seats out left to right — was measured and
+ * rejected: it puts one two-step arm on the vertical axis and the one-step leaf
+ * beside it, so the drawing leans (its base lands 13% of the frame width off
+ * the centre, against 2% here) and cs210's `cs-sorting → cs-complexity`
+ * cross-edge runs straight through the middle node's label (−7.3 units at the
+ * desktop type scale; on the phone no combination of radius, type scale, dot
+ * size and label gap clears it while the labels still render at 11 CSS px).
  */
-function ringPhase(count: number): number {
-  return (Math.PI * 2) / count / 4;
+function fanSeats(count: number): number[] {
+  const seats: number[] = [];
+  let lo = 0;
+  let hi = count - 1;
+  while (lo <= hi) {
+    seats.push(lo);
+    if (lo !== hi) seats.push(hi);
+    lo += 1;
+    hi -= 1;
+  }
+  return seats;
 }
 
 /**
- * A RADIAL TREE. Root at the centre; depth-1 spread evenly around the full
- * circle at radius `ring`; every deeper node placed at radius `ring` from ITS
- * OWN PARENT, inside a wedge centred on the direction from the centre to that
- * parent. Siblings share (and subdivide) the wedge.
- *
- * THE BUG THIS FIXES. The layout used to be global concentric RINGS: a node's
- * angle came from its index within its depth, so it had no relationship to
- * where its parent sat. With the shipped 6-node fixtures that scatters the
- * graph — `cs-sorting` (a child of `cs-arrays`) landed 171 units from its
- * parent on a ring of radius 232, `cs-trees` was flung to the opposite corner,
- * and the result read as a lopsided diagonal smear rather than a tree. Tuning
- * the ring angles cannot fix it: the previous wave swept them, moved the
- * aspect metric from 0.436 to 1.006, and made the composition visibly worse.
- * Every tree edge is now exactly one `ring` long — max 170.9 → 116.0 desktop,
- * mean 128.5 → 116.0 — because a child is placed off its parent, not off the
- * centre.
+ * A SAPLING. The root sits at the bottom-centre of the drawing; depth-1 fans
+ * upward across the half-plane above it at radius `ring`; every deeper node is
+ * placed at radius `ring` from ITS OWN PARENT, inside a wedge centred on the
+ * direction that parent itself grew in. Siblings share (and subdivide) the
+ * wedge. Because every depth-1 heading points upward, so does everything below
+ * it: the whole structure fans up.
+ *
+ * WHAT THIS WAVE CHANGED, and nothing else: the ANGULAR DOMAIN. The BFS
+ * spanning tree and the parent-relative placement are exactly as the previous
+ * wave left them, and every edge in `graph.edges` is still drawn, cross-edges
+ * included. What moved is that depth-1 used to be spread around the FULL circle
+ * with the root at the frame's centre, so the tree grew one arm up and two
+ * down — an inverted Y, or a root system. The product is called Sapling and the
+ * section headline is "Pick a course. Watch it grow."; a drawing that grows
+ * downward is the wrong picture, and no amount of ring phasing fixes a full
+ * circle.
+ *
+ * WHY THE ROOT IS NOT AT `(width/2, height/2)` ANY MORE. That point is the
+ * centre `helixEntry` spirals around and the point `fitViewBox` fits its frame
+ * about — the sweep is very nearly a disc centred there. Leaving the root on it
+ * while growing upward would put the whole drawing in the disc's top half and
+ * reserve the bottom half for nothing: measured, the settled box lands 15.7% of
+ * the frame height off centre and fills 0.41 of it (against 0.53 here), and the
+ * `<svg>` grows to 676px. So the skeleton is laid out with the root at the
+ * origin and then translated as a rigid body until ITS OWN bounding box is
+ * centred on `(width/2, height/2)`. The root ends up at the bottom-centre of
+ * the content, the sweep stays centred on the drawing, and the frame comes out
+ * centred on it too (measured ≤ 3.2% off on either axis, every fixture, both
+ * views).
  *
  * `maxRadius` is the spatial budget: `ring = maxRadius / maxDepth`, so a chain
- * of `maxDepth` collinear steps lands exactly on it. A node whose siblings push
- * it off its parent's outward direction sits INSIDE that radius, so `maxRadius`
- * is an upper bound rather than an exact outer ring. It defaults to the old
- * inscribed-circle-minus-48 rule so every existing caller and test is
- * unchanged, but each view passes it explicitly: the binding constraint is the
- * *fitted* frame, not the layout box, and `min(w, h) / 2 - pad` can't express
- * that.
+ * of `maxDepth` collinear steps spans exactly it. A node whose siblings push it
+ * off its parent's outward direction sits INSIDE that radius, so `maxRadius` is
+ * an upper bound rather than an exact outer ring. Its default is unchanged
+ * (`min(w, h)/2 − 48`) so every existing caller keeps working, but both shipped
+ * views pass it explicitly — the binding constraints are the fitted frame, the
+ * label clearances and the phone's legibility floor, none of which
+ * `min(w, h)/2 − pad` can express.
  *
  * Deterministic by construction: no randomness, no clock, no DOM read.
  */
@@ -209,13 +280,12 @@ export function radialLayout(
     byDepth.set(d, [...(byDepth.get(d) ?? []), n.id]);
   }
 
-  const cx = width / 2;
-  const cy = height / 2;
   const maxDepth = Math.max(...byDepth.keys(), 1);
   const ring = maxRadius / maxDepth;
 
+  /** Laid out with the root at the origin; translated to the frame at the end. */
   const out = new Map<string, Point>();
-  /** Direction from the CENTRE to this node — the axis its own wedge is built on. */
+  /** The direction this node GREW in — the axis its own wedge is built on. */
   const heading = new Map<string, number>();
   /** Angular span this node's subtree owns, subdivided among its children. */
   const wedge = new Map<string, number>();
@@ -225,18 +295,22 @@ export function radialLayout(
 
     // Depth 0 is the root — plus, defensively, anything the BFS never reached.
     if (d === 0) {
-      for (const id of ids) out.set(id, { x: cx, y: cy });
+      for (const id of ids) out.set(id, { x: 0, y: 0 });
       continue;
     }
 
     if (d === 1) {
-      const step = (Math.PI * 2) / ids.length;
-      const phase = ringPhase(ids.length);
-      ids.forEach((id, i) => {
-        const a = i * step + phase;
-        out.set(id, { x: cx + Math.cos(a) * ring, y: cy + Math.sin(a) * ring });
+      const gap = Math.PI / (ids.length + 1);
+      const seats = fanSeats(ids.length);
+      const size = subtreeSizes(graph, depth, parent);
+      // Biggest subtree first, ties in declaration order (Array#sort is stable),
+      // so the deep arms take the outer seats.
+      const seated = [...ids].sort((a, b) => (size.get(b) ?? 1) - (size.get(a) ?? 1));
+      seated.forEach((id, i) => {
+        const a = fanAngle(seats[i], ids.length);
+        out.set(id, { x: Math.cos(a) * ring, y: Math.sin(a) * ring });
         heading.set(id, a);
-        wedge.set(id, step);
+        wedge.set(id, gap);
       });
       continue;
     }
@@ -248,21 +322,42 @@ export function radialLayout(
     }
     for (const [p, kids] of siblings) {
       const anchor = out.get(p)!;
-      const base = heading.get(p) ?? Math.atan2(anchor.y - cy, anchor.x - cx);
-      const span = wedge.get(p) ?? Math.PI * 2;
+      // The parent's own outward direction. The fallback is the bearing from
+      // the root, which is where the root sits while this loop runs.
+      const base = heading.get(p) ?? Math.atan2(anchor.y, anchor.x);
+      const span = wedge.get(p) ?? Math.PI;
       const slice = span / kids.length;
       kids.forEach((id, i) => {
         // Centre of this child's slice — a lone child therefore lands exactly
-        // on the parent's outward direction, i.e. collinear with the centre.
+        // on the parent's outward direction, i.e. collinear with it.
         const a = base - span / 2 + (i + 0.5) * slice;
         const q = { x: anchor.x + Math.cos(a) * ring, y: anchor.y + Math.sin(a) * ring };
         out.set(id, q);
-        heading.set(id, Math.atan2(q.y - cy, q.x - cx));
+        heading.set(id, a);
         wedge.set(id, slice);
       });
     }
   }
-  return out;
+
+  // Rigid translation: centre the skeleton's own bounding box on the layout
+  // box's centre, which is the point the entry sweep spirals around. See the
+  // doc comment above for why this is not "put the root at the centre".
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const p of out.values()) {
+    minX = Math.min(minX, p.x);
+    minY = Math.min(minY, p.y);
+    maxX = Math.max(maxX, p.x);
+    maxY = Math.max(maxY, p.y);
+  }
+  const dx = width / 2 - (minX + maxX) / 2;
+  const dy = height / 2 - (minY + maxY) / 2;
+
+  const placed = new Map<string, Point>();
+  for (const [id, p] of out) placed.set(id, { x: p.x + dx, y: p.y + dy });
+  return placed;
 }
 
 /**
@@ -324,27 +419,22 @@ export function labelHalfWidth(label: string, geom: GraphGeometry): number {
 /**
  * Where a node's label baseline sits, relative to the node's drawn centre.
  *
- * On DESKTOP the root's label stays above it (#344 visual 4). Both halves are
- * collision-free under the tree, and the numbers moved: measured across all
- * three fixtures, above clears by 8.80 units — the binding neighbour is the
- * cross-edge that runs from an 8 o'clock child up to the 12 o'clock one
- * (`ma-matrices → ma-eigen`, `sm-dist → sm-testing`) — and below by 31.24, in
- * the open wedge between the two downward arms. So "below" is now the roomier
- * half, where the ring layout made it the tighter one. It is a one-line flip if
- * the composition ever wants it; it is not taken here because 8.80 units is
- * 6.6 CSS px at the rendered cap, and because flipping it would leave
- * `rootLabelAbove` false in every shipped view — a flag and a branch with no
- * caller.
- *
- * On MOBILE it stays below, because there the geometry still forbids the
- * alternative outright. The childless third child sits `ring` straight above
- * the root with its own label hanging back down toward it, so an
- * above-the-root label only clears it when
- *
- *     ring ≥ rootR + nodeR + 2·labelGap + cap + descender
+ * BOTH shipped views now put the root's label BELOW its circle, and that is a
+ * consequence of the root moving to the base of the drawing. "Above" used to be
+ * the open half — it was the direction with no graph in it. Under the upward
+ * fan it is the direction the whole plant grows in: the course code lands on
+ * the stem running from the root up to its middle child, where the halo has to
+ * cut the edge in two to stay legible, and it eats 20 units off the settled
+ * box's height (aspect 0.562 → 0.53, and the frame does not shrink with it, so
+ * the dead band grows). Below the root there is nothing but the frame edge, and
+ * the code reads as a caption at the ground line. Measured, below clears its
+ * nearest neighbour by 30.14 units on desktop and 5.40 on the phone; above
+ * clears by 9.83 and 2.71.
  *
- * — 84.1 units at the phone type scale, against an 81.5-unit ring. Measured,
- * "above" overlaps that label by 8.72 units; below clears everything by 14.53.
+ * `rootLabelAbove` is kept — it is part of `GraphGeometry`'s shape, it is what
+ * makes the choice a per-view geometry question rather than a hard-coded taste
+ * one, and `layout.test.ts` still exercises both branches — but no shipped view
+ * sets it today.
  *
  * Shared with `fitViewBox` and `layout.test.ts` so the frame can never be
  * fitted to a label position the component doesn't actually use.
@@ -394,13 +484,14 @@ const FIT_STEPS = 512;
  * THE THING TO NOT GET WRONG: fit to the HELIX SWEEP, not to the settled node
  * positions. `helixEntry` rotates a node up to 1.5 turns around the centre on
  * the way in, so every outer node passes through every direction on its way to
- * rest. Under the radial tree that gap is WIDER than it was under the rings,
- * because a tree is a wide object inside a circular sweep: on desktop the
- * settled drawing spans 280.5 units of height while the sweep spans 476.3, so a
- * box fitted to the settled positions would clip 91.1 units off the top and
- * 104.7 off the bottom — 121 and 139 CSS px at the rendered cap, in plain view.
- * That exact bug was found and fixed once already on this branch (#344 review
- * #4). The phone numbers are 63.6 and 73.5. `layout.test.ts` sweeps `t` across
+ * rest. Under the upward fan that gap is WIDER still than it was under the
+ * downward tree, because a canopy is a wide, short object inside a circular
+ * sweep: on desktop the settled drawing spans 284.3 units of height while the
+ * sweep spans 513.6, so a box fitted to the settled positions would clip 125.8
+ * units off the top and 103.6 off the bottom — 150 and 124 CSS px at the
+ * rendered cap, in plain view. That exact bug was found and fixed once already
+ * on this branch (#344 review #4). The phone numbers are 82.9 and 69.6, against
+ * 63.6 and 73.5 before. `layout.test.ts` sweeps `t` across
  * the full range to keep it fixed, and pins the overshoot itself so a
  * settled-fit implementation fails outright.
  *
@@ -464,91 +555,101 @@ function withFit(geom: GraphGeometry): GraphView {
 }
 
 /**
- * Untouched by the tree rewrite: `maxRadius: 232` is still `radialLayout`'s old
- * default (`min(900, 560) / 2 - 48`), so the spatial budget, the type scale and
- * the dot sizes are exactly what this branch was designed and reviewed against.
- * Only the arrangement inside that budget changed, and the frame re-fitted
- * around it: `165 48 541 498`, against `185 33 526 516` for the ring layout,
- * `159 42 578 498` for the flat ring before that, and the `0 0 900 560` the
- * demo shipped with.
+ * Retuned for the upward fan. Frame `161 17 603 534`, against `165 48 541 498`
+ * for the downward radial tree, `185 33 526 516` for the ring layout before it,
+ * and the `0 0 900 560` the demo shipped with.
  *
  * The component caps the rendered width (`md:max-w-[720px]`), so at the cap the
- * graph draws at 1.331 user units per CSS px: 16.0px labels, 37.3px concept
- * dots, a 69px root, and a 663px-tall `<svg>` — 43px SHORTER than the ring
- * layout's 706px and 74px shorter than the 737px the fixed box reserved.
- *
- * The composition it buys, measured on cs210: the drawing is 448 × 281 units
- * (596 × 374 CSS px) inside a 541 × 498 frame, centred to within 18 units
- * horizontally and 7 vertically. It fills 83% of the frame's width against the
- * ring layout's 71%; it fills less of its height (56% against 73%) because a
- * three-branch tree is a wide object and the frame is fitted to a near-circular
- * entry sweep — see `fitViewBox`. That is the deliberate trade: symmetric
- * whitespace above and below a balanced drawing, rather than a taller drawing
- * whose children sit nowhere near their parents.
+ * graph draws at 1.194 user units per CSS px: 16.7px labels, 33.4px concept
+ * dots, a 62px root, and a **637.6px-tall `<svg>` — 25px SHORTER** than the
+ * downward tree's 662.8 and 99px shorter than the 737px the fixed box reserved.
+ *
+ * WHY `maxRadius` LEFT 232, i.e. why it is no longer `radialLayout`'s
+ * inscribed-circle default. Under the upward fan the drawing wraps its own
+ * centre much more tightly than a full-circle spread does, so the same budget
+ * produced a 460-unit frame and a 19px type scale. The budget is now solved,
+ * not inherited, against three constraints that the layout box cannot express:
+ *
+ * - the rendered type scale (720 / `fit.w`), which sets label and dot sizes;
+ * - the label clearances, which improve as the ring grows against a fixed type
+ *   size — 320 buys 30.14 units (36 CSS px) on the worst pair, against the
+ *   8.80 units (6.6 px) the downward tree shipped;
+ * - the shape assertions, which are scale-free.
+ *
+ * The composition it buys, measured on cs210: the drawing is 506 × 284 units
+ * (604 × 339 CSS px) inside a 603 × 534 frame, centred to within 2.8% of the
+ * width and 2.1% of the height. It fills **0.839 of the frame's width** against
+ * the downward tree's 0.828 (ma242 0.916, sm275 0.881), and 0.53 of its height.
+ *
+ * The height share is the one number that did not improve, and it is worth
+ * being precise about why: `fitViewBox` fits the frame to the ENTRY SWEEP, and
+ * the sweep is very nearly a disc, so the frame is very nearly square whatever
+ * the drawing does. Dead vertical space is therefore ≈ (drawing width −
+ * drawing height) / 2 for any layout, and a canopy is by definition wider than
+ * tall. Measured: 149 CSS px of band above and below, against 145 for the
+ * downward tree — a wash. Making that band small needs a drawing with aspect
+ * ≈ 1, which is neither a canopy nor shorter (swept: a symmetric fan narrow
+ * enough to fill the height renders a 683px section). The lever that would
+ * actually shrink it is the sweep itself — `helixEntry`'s 1.5 turns — and that
+ * is an animation change, out of this wave's scope.
  */
 export const DESKTOP_VIEW: GraphView = withFit({
   w: 900,
   h: 560,
-  maxRadius: 232,
-  font: 12,
+  maxRadius: 320,
+  font: 14,
   rootR: 26,
   nodeR: 14,
-  labelGap: 16,
-  rootLabelAbove: true,
+  labelGap: 13,
+  rootLabelAbove: false,
   labelHalo: 3,
   edgeW: 1.4,
   fitPad: 10,
 });
 
 /**
- * The phone view, RETUNED for the tree — and the reason the retune was not
- * optional. Frame `-38 -11 414 356`; a ~332px content box (390 viewport − 48 of
- * `px-6` − the 10px scrollbar globals.css paints) renders it at 0.802, so
- * 14-unit labels land at 11.23 CSS px, concept dots at a 20.9px diameter, and
- * the `<svg>` is 285px tall — all three still over the E2E legibility gate
- * (≥11px labels, ≥20px dots, >260px tall), and all three tighter than the ring
- * layout's 12.8 / 25.5 / 301.
- *
- * WHY THE RING HAD TO GROW (132 → 163). Labels hang below their dots and are
- * `middle`-anchored, so a 13-character label ("Vector Spaces", "Distributions",
- * "Central Limit") is 3.9·font units wide on each side of its node. In a tree
- * the child of a depth-1 node sits `ring` away along that node's outward
- * direction, and with three children 120° apart the flattest arm is always 30°
- * off the horizontal — that is forced, not chosen: of two arms 120° apart, the
- * best achievable worst-case horizontal step is `ring·sin(60°)`. So the child's
- * dot lands inside its own parent's label unless
- *
- *   0.866 · ring  >  3.9 · font + labelHalo/2 + nodeR
- *
- * — `ring ≥ 76` at this type scale, against the 66 the ring layout used. At
- * `ring = 66` the overlap measures −13.1 units on ma242 and sm275.
- *
- * WHAT BOUNDS IT FROM ABOVE is the same E2E gate, through the fitted frame:
- * `fit.w ≈ 3.65·ring + 7.8·font + labelHalo + 2·fitPad`, and legibility needs
- * `font · 332 / fit.w ≥ 11`. The two brackets leave a window about 4 units of
- * `ring` wide; 81.5 (`maxRadius` 163, halved by `maxDepth`) sits in it with
- * +1.23 units on the worst label pair — up from the +0.80 the ring layout
- * shipped — and +0.23 CSS px on the label gate. `nodeR` drops 14 → 13 and
- * `fitPad` 10 → 2 to buy that window; both are spent directly on the two
- * constraints above, and `fitPad` still has the fit's outward whole-unit snap
- * under it.
- *
- * The other constraint the previous wave tuned against — the root's label
- * versus the horizontal depth-1 chord — is GONE: with the branch-bearing
- * children at 4 and 8 o'clock, the only depth-1 edge any fixture draws
- * (`ma-matrices → ma-eigen`, `sm-dist → sm-testing`) runs from 8 o'clock to 12
- * o'clock and never crosses the root's label band. What survives unchanged is
- * the 12 o'clock child's label clearing the root's dot, which needs
- * `ring > nodeR + labelGap + 5.2 + rootR` — 59.2 here, with 22 units in hand.
+ * The phone view, and the breakpoint that gains the most from the upward fan.
+ * Frame `-32 -25 443 365`; a ~332px content box (390 viewport − 48 of `px-6` −
+ * the 10px scrollbar globals.css paints) renders it at 0.7494, so 16-unit
+ * labels land at **11.99 CSS px**, concept dots at a **22.48px** diameter, and
+ * the `<svg>` is **273.5px** tall. All three clear the E2E legibility gate
+ * (≥11px labels, ≥20px dots, >260px tall), and all three are BETTER than the
+ * downward tree's 11.23 / 20.85 / 285.5 on the two that were nearly lost.
+ *
+ * THE CONSTRAINT THAT WAS RAZOR-THIN AND NO LONGER IS. Labels hang below their
+ * dots and are `middle`-anchored, so a 13-character label ("Vector Spaces",
+ * "Distributions", "Central Limit") reaches 3.9·font units to each side of its
+ * node. The downward tree put its two deep arms 120° apart, which forces one of
+ * them to within 30° of the horizontal, so a child's dot landed inside its own
+ * parent's label unless `0.866·ring > 3.9·font + labelHalo/2 + nodeR`; the
+ * shipped geometry met that by **+1.23 units (0.99 CSS px)** and the label gate
+ * by +0.23 CSS px, both inside the noise of whether Chromium paints a scrollbar
+ * at that viewport.
+ *
+ * The fan changes the geometry that produces the number. Its two deep arms are
+ * 90° apart and symmetric about the vertical, so the worst horizontal step is
+ * `ring·sin 45°` on BOTH of them instead of `ring·sin 60°` on one and
+ * `ring·sin 30°` on the other, and the crowded pair moves from "a child's dot
+ * inside its parent's label" to "the middle shoot's label beside a depth-1
+ * dot". Measured worst pair over all three fixtures: **+5.40 units = 4.05 CSS
+ * px**, a 4× improvement, with the label gate now clearing by 0.99 CSS px
+ * instead of 0.23.
+ *
+ * The window is still two-sided — the collision wants a bigger ring, the
+ * legibility gate wants a smaller frame (`font · 332 / fit.w ≥ 11`) — and the
+ * point below was picked by sweeping `maxRadius`, `font`, `rootR`, `nodeR` and
+ * `labelGap` against BOTH ends plus the shape assertions, maximising the worst
+ * normalised margin. `fitPad` stays at 2 (the fit's outward whole-unit snap
+ * sits under it); everything else moved.
  */
 export const MOBILE_VIEW: GraphView = withFit({
   w: 360,
   h: 300,
-  maxRadius: 163,
-  font: 14,
+  maxRadius: 212,
+  font: 16,
   rootR: 22,
-  nodeR: 13,
-  labelGap: 19,
+  nodeR: 15,
+  labelGap: 15,
   rootLabelAbove: false,
   labelHalo: 3.5,
   edgeW: 1.8,

From 5429aa68afb0dce6997557080a84ccc9169d73ee Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 18:03:06 -0700
Subject: [PATCH 17/20] fix(landing): tighten the graph's entry sweep to a
 quarter turn (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The frame is fitted to the helix sweep, not to the settled drawing — it has
to be, or the assembly gets clipped mid-flight (#344 review #4). At 1.5 turns
every node passed through every direction on the way in, so that sweep was
very nearly a DISC and the fitted frame very nearly SQUARE around a canopy
twice as wide as it is tall. The difference was dead paper: 162 and 136 CSS
px of it above and below the drawing, which the previous wave measured across
the whole layout family and logged as its closing concern — the lever is the
sweep, not the layout.

`helixEntry` now turns 0.25 (90°) and `ENTRY_CONTRACTION` is 1, so a node
starts on the centre and the radial term collapses to the straight-line
easing: the path is that line, rotated by a decaying quarter turn, and the
widest swing happens where the node is nearest the centre. No layout, fixture,
colour, copy, testid or component signature moved; every settled coordinate is
byte-identical.

  desktop  viewBox 161 17 603 534 -> 161 114 582 334
           <svg> 720x637.6 -> 720x413.2 px   (-224)
           band/side 162.2/136.0 -> 48.1/13.4 px
  phone    viewBox -32 -25 443 365 -> -32 40 429 230
           <svg> 332x273.5 -> 332x178.0 px   (-95)
           band/side 63.7/54.2 -> 15.5/1.8 px

The drawing did not shrink to get there — it grew, because the narrower frame
renders every unit bigger: 669x339 -> 694x352 CSS px on desktop, 12.0 -> 12.4
px phone labels, 22.5 -> 23.2 px dots. Worst label clearance is unchanged in
units (30.14 desktop, 5.40 phone) and better in pixels (36.0 -> 37.3, 4.05 ->
4.18).

Tests: the mid-flight helix assertion is restated as shape rather than
distance (>0.1 travel radii off the straight line, >5 deg of bearing swing;
measured 0.172 and 11.25 deg) so it bites at 0.146 turns instead of passing
anything; the sweep-vs-settled guard now asserts the top overhang with a
number and builds the settled-fit box to show it clips, because the overhang
is one-sided by construction (the fan's tips lift past the settled top when
they rotate through the vertical; nothing can swing below the course code);
the frame-height share floor goes 0.50 -> 0.75 (measured 0.851/0.903); and the
phone's third bar stops measuring the FRAME's height (it was passing on the
band) and measures the drawing's, with a frame floor kept at 170px.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 frontend/e2e/landing-graph.spec.ts            |  19 +-
 .../marketing/graph/KnowledgeGraphDemo.tsx    |  21 +-
 .../components/marketing/graph/layout.test.ts | 214 +++++++++++++-----
 .../src/components/marketing/graph/layout.ts  | 171 +++++++++-----
 4 files changed, 300 insertions(+), 125 deletions(-)

diff --git a/frontend/e2e/landing-graph.spec.ts b/frontend/e2e/landing-graph.spec.ts
index 6e328e90..53e33cd4 100644
--- a/frontend/e2e/landing-graph.spec.ts
+++ b/frontend/e2e/landing-graph.spec.ts
@@ -52,15 +52,26 @@ test('landing graph renders, swaps by course, and fades its copy on engagement',
  * box is ~332px, so the SVG rendered at a uniform 0.38 scale — 4.6 CSS px
  * concept labels and a 213px-tall smudge, on the device most marketing traffic
  * arrives on. The component now swaps to a phone view below the mobile
- * breakpoint, whose frame is fitted to its content (`-32 -25 443 365`, #344
- * visual 3): 0.75 scale ⇒ 12.0 CSS px labels, 22.5px dots, 273px tall. Those
- * three clear the bars below by 1.0px, 2.5px and 13px. The bracket is still
+ * breakpoint, whose frame is fitted to its content (`-32 40 429 230`, #344
+ * visual 3): 0.77 scale ⇒ 12.4 CSS px labels, 23.2px dots, 178px tall. The
+ * first two clear the bars below by 1.4px and 3.2px. The bracket is still
  * two-sided — a bigger ring keeps labels off their neighbours, a smaller frame
  * keeps the type legible — but the upward fan put its two deep arms 90° apart
  * and symmetric about the vertical, which widened the window: the first two
  * margins were 0.2px and 0.9px under the downward tree. See `MOBILE_VIEW` in
  * `layout.ts`.
  *
+ * THE HEIGHT BAR MOVED 260 → 170, and it is not a legibility bar being lowered.
+ * `viewBox` is fitted to the entry SWEEP, not to the settled drawing, or the
+ * assembly gets clipped mid-flight (#344 review #4). While `helixEntry` turned
+ * 1.5 times, that sweep was nearly a disc and the frame nearly square, so this
+ * phone frame was 273px tall around a drawing 156px tall — 118px of empty paper
+ * that the ">260px" bar was, in effect, asserting. The entry is a quarter turn
+ * now: the frame is 178px, the DRAWING inside it is 161px — bigger than before —
+ * and the honest version of this bar (the drawing's rendered height, not the
+ * frame's) lives in `layout.test.ts`, where the settled extents can be measured
+ * exactly rather than inferred from a bounding rect.
+ *
  * Asserting in CSS pixels — what a visitor's eye actually gets — rather than on
  * the viewBox attribute, so a different fix that reaches the same legibility
  * still passes.
@@ -92,7 +103,7 @@ test('the graph stays legible at a 390px phone viewport (#344)', async ({ page }
 
   expect(metrics.labelPx, 'concept labels in CSS px').toBeGreaterThanOrEqual(11);
   expect(metrics.dotDiameterPx, 'non-root node diameter in CSS px').toBeGreaterThanOrEqual(20);
-  expect(metrics.heightPx, 'rendered graph height in CSS px').toBeGreaterThan(260);
+  expect(metrics.heightPx, 'rendered graph height in CSS px').toBeGreaterThan(170);
 });
 
 test('the deleted scroll section is gone and the CTA still routes', async ({ page }) => {
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index 8177adbf..121fc508 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -375,16 +375,17 @@ export default function KnowledgeGraphDemo() {
           direction the rest of the section already uses, and it is the reversible
           half of the choice: no copy moves, no structure changes.
 
-          At the 720px cap the desktop graph draws at ~1.19 units per CSS px in
-          a 720×638 box, where the fixed viewBox reserved 1184×737 and drew the
-          graph across the middle 277px of it. The box is 25px SHORTER than the
-          720×663 the downward radial tree fitted to and 68px shorter than the
-          concentric rings before it: the course sits at the base and its
-          concepts fan upward, which is both the brand's picture and a wider,
-          shorter object — it fills 84% of the frame's width (up from 83%, and
-          from 71% under the rings) and 53% of its height, centred, with the
-          whitespace the circular entry sweep costs spent symmetrically above
-          and below.
+          At the 720px cap the desktop graph draws at ~1.24 units per CSS px in
+          a 720×413 box, where the fixed viewBox reserved 1184×737 and drew the
+          graph across the middle 277px of it. The box is 224px SHORTER than the
+          720×638 the same upward fan fitted while `helixEntry` turned 1.5 times
+          on the way in: the frame is fitted to that entry SWEEP (it has to be,
+          or the assembly gets clipped mid-flight), a 540° sweep is very nearly a
+          disc, and a near-square frame around a canopy twice as wide as it is
+          tall is dead paper on the top and bottom edges. At a quarter turn the
+          sweep hugs the drawing, so the drawing now fills 87% of the frame's
+          width and 85% of its height — and it renders BIGGER than it did in the
+          taller box (694×352 CSS px against 669×339).
         */}
         <svg
           data-testid="landing-graph-svg"
diff --git a/frontend/src/components/marketing/graph/layout.test.ts b/frontend/src/components/marketing/graph/layout.test.ts
index 47016c1a..e48876a2 100644
--- a/frontend/src/components/marketing/graph/layout.test.ts
+++ b/frontend/src/components/marketing/graph/layout.test.ts
@@ -450,14 +450,48 @@ describe('helixEntry', () => {
     expect(r.scale).toBeLessThan(0.5);
   });
 
+  /**
+   * THE ENTRY IS A HELIX, NOT A FADE-IN — and this is the test that has to keep
+   * meaning that now the sweep is a quarter turn instead of 1.5 turns.
+   *
+   * Both bars are stated as SHAPE, not as a distance in units, because a
+   * distance bar silently weakens whenever the travel radius or the geometry
+   * moves. The measurements are taken at mid-flight (t = 0.5), where
+   * `easeOutCubic` has 12.5% of the entry left to run:
+   *
+   * - the node is more than a TENTH OF ITS OWN TRAVEL RADIUS off the point a
+   *   straight-line entry with the same easing would be at (measured 0.172, i.e.
+   *   21.97 units on this 128.06-unit example — it was 129.61 units at 1.5
+   *   turns, but 1.01 radii, because at 540° the "straight line" comparison is
+   *   meaningless: the node is halfway round the far side);
+   * - and it is more than 5° off its own settled BEARING from the centre
+   *   (measured 11.25° = 12.5% of the quarter turn), which is the part a plain
+   *   scale-and-fade cannot fake at any distance.
+   *
+   * The old bar was `> 10` units, i.e. 7.8% of this radius, so the floor went
+   * UP with the sweep coming down. `ENTRY_CONTRACTION = 1` is what makes the
+   * first number readable: the radial term is then exactly the straight line's
+   * own easing, so every unit of deviation measured here is rotation.
+   *
+   * Both bars BITE. Mid-flight offset is `2·e·sin(45°·turns)` radii and the
+   * swing is `45°·turns`, so dropping the entry to 0.146 turns fails the first
+   * and 0.111 fails the second — i.e. this test is what stops the next person
+   * from tightening the frame the lazy way, by taking the helix out entirely.
+   */
   it('rotates around the centre on the way in — the helix', () => {
     const mid = helixEntry(target, centre, 0.5);
     const straight = {
       x: centre.x + (target.x - centre.x) * easeOutCubic(0.5),
       y: centre.y + (target.y - centre.y) * easeOutCubic(0.5),
     };
+    const travel = Math.hypot(target.x - centre.x, target.y - centre.y);
     const off = Math.hypot(mid.x - straight.x, mid.y - straight.y);
-    expect(off).toBeGreaterThan(10);
+    expect(off / travel, 'mid-flight offset from the straight line, in radii').toBeGreaterThan(0.1);
+
+    const bearing = (p: { x: number; y: number }) =>
+      Math.atan2(p.y - centre.y, p.x - centre.x);
+    const swing = Math.abs(bearing(mid) - bearing(target)) * (180 / Math.PI);
+    expect(swing, 'mid-flight bearing swing, degrees').toBeGreaterThan(5);
   });
 
   it('grows monotonically', () => {
@@ -512,6 +546,28 @@ function drawnExtent(
   };
 }
 
+/**
+ * The height of the SETTLED drawing — top of the highest ink to bottom of the
+ * lowest, across every fixture, in user units. Not the frame: the frame also
+ * holds the entry sweep's headroom, and telling the two apart is the whole
+ * subject of the phone-sizing test below that uses it.
+ */
+function settledHeight(view: (typeof GRAPH_VIEWS)[number]): number {
+  let top = Infinity;
+  let bottom = -Infinity;
+  for (const graph of COURSE_GRAPHS) {
+    const points = radialLayout(graph, view.w, view.h, view.maxRadius);
+    for (const n of graph.nodes) {
+      const p = points.get(n.id)!;
+      const isRoot = n.id === graph.rootId;
+      const e = drawnExtent(view, n.label, isRoot, p.x, p.y, isRoot ? view.rootR : view.nodeR, 1);
+      top = Math.min(top, e.top);
+      bottom = Math.max(bottom, e.bottom);
+    }
+  }
+  return bottom - top;
+}
+
 /**
  * #344 review #4 — the bug this file should have caught during development.
  *
@@ -565,19 +621,30 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
   /**
    * The assertion above is only worth anything if the sweep actually needs the
    * headroom — otherwise a lazy "fit to the settled node positions" would pass
-   * it, and that is precisely the clipping bug. So: prove the sweep leaves the
-   * settled bounding box, and by how much. `helixEntry` rotates a node up to
-   * 1.5 turns on the way in, so every outer node passes through every direction
-   * before it lands.
+   * it, and that is precisely the clipping bug (#344 review #4). So: build the
+   * box a settled fit would produce, and prove the ASSEMBLY LEAVES IT.
+   *
+   * That is now asserted directly rather than through the old proxy. The proxy
+   * was "the swept box overhangs the settled box by more than 25 units on the
+   * top AND the bottom", which held while `helixEntry` turned 1.5 times and
+   * every node passed through every direction (desktop 125.8 / 103.6 units,
+   * mobile 82.9 / 69.6). At the quarter turn it does not, and the reason is
+   * geometry rather than a weaker guard:
+   *
+   * - the fan's tips sit far from the centre and only ~27° above the horizontal,
+   *   so rotating them toward the vertical lifts them PAST the settled top —
+   *   desktop by 27.9 units (34.5 CSS px at the cap), mobile by 17.6 (13.6 px),
+   *   both at ~80% opacity, both plainly visible if the frame did not hold them;
+   * - nothing can swing BELOW the settled bottom, because the lowest ink is the
+   *   course code hanging under the root and the root is the node nearest the
+   *   centre. The bottom overhang is exactly 0, and the frame's bottom edge is
+   *   the settled bottom plus `fitPad` by construction.
    *
-   * The MARGIN is what this asserts, in units, on each side. It used to be
-   * stated as a ratio ("the sweep needs ~2× the settled height"), which was only
-   * ever a proxy for "a settled fit would clip" and moved for reasons that had
-   * nothing to do with clipping. Measured on each side: desktop 125.8 / 103.6,
-   * mobile 82.9 / 69.6 — wider again under the upward fan than under the
-   * downward tree (91.1 / 104.7 and 63.6 / 73.5), which were themselves wider
-   * than the rings (59.0 / 59.3 and 33.5 / 33.5), because a canopy is a wide,
-   * short object sitting inside a circular sweep.
+   * So the top overhang is asserted with a number, the bottom is asserted to be
+   * non-negative (the sweep never dips below the frame's floor), and the
+   * settled-fit box is built and shown to clip — which is the property the whole
+   * `fitViewBox` doc comment is about, and which no amount of retuning can make
+   * vacuous.
    */
   for (const view of GRAPH_VIEWS) {
     it(`the ${view.maxRadius}-radius sweep leaves the settled bounding box`, () => {
@@ -607,14 +674,29 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
         }
       }
 
-      // Comfortably, not marginally, and on BOTH sides: a frame fitted to the
-      // rest state would chop this much off the top and bottom of the assembly,
-      // live, at ~83% opacity.
-      expect(settledTop - sweptTop).toBeGreaterThan(25);
-      expect(sweptBottom - settledBottom).toBeGreaterThan(25);
+      // The assembly rises this far above where it comes to rest — desktop
+      // 27.9 units, mobile 17.6 — and a frame fitted to the rest state would
+      // chop exactly that much off the top of it, live, at ~80% opacity.
+      expect(settledTop - sweptTop, 'sweep above the settled top').toBeGreaterThan(12);
+      // Nothing ever swings below the course code: the frame's floor is the
+      // settled floor, and the sweep must not need more than that.
+      expect(sweptBottom - settledBottom, 'sweep below the settled bottom').toBeGreaterThanOrEqual(
+        0,
+      );
       // …and the fitted frame is sized for the sweep, not for the rest state.
       expect(view.fit.h).toBeGreaterThanOrEqual(sweptBottom - sweptTop);
       expect(view.fit.h).toBeGreaterThan(settledBottom - settledTop);
+
+      // The bug, stated as the bug: fit the frame to the settled positions the
+      // way the demo originally did, and the assembly leaves it.
+      const settledFit = {
+        top: Math.floor(settledTop - view.fitPad),
+        bottom: Math.ceil(settledBottom + view.fitPad),
+      };
+      expect(
+        settledFit.top - sweptTop,
+        'how far the assembly escapes a settled-fitted frame',
+      ).toBeGreaterThan(10);
     });
   }
 
@@ -622,7 +704,8 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
    * CRITERION 4/5 — the settled drawing has to be a SANE SHAPE, sitting in the
    * middle of the frame it is given.
    *
-   * TWO BARS MOVED WITH THE UPWARD FAN, both deliberately, both downward.
+   * TWO BARS MOVED WITH THE UPWARD FAN, both downward; the tightened entry
+   * sweep has now put one of them back, well above where it started.
    *
    * The ASPECT WINDOW goes 0.55–1.10 → 0.40–0.80. A canopy is legitimately
    * wider than tall: three shoots leaving one base 45° apart, two of them
@@ -632,23 +715,34 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
    * fails the "grow it straight up into a tall skinny chain" family, which is
    * the way an upward layout goes wrong.
    *
-   * The FRAME-HEIGHT SHARE goes 0.55 → 0.50 (measured 0.532 desktop, 0.569
-   * phone, against 0.563 / 0.599 for the downward tree). That is a real, small
-   * regression and it is geometric, not a tuning slip: `fitViewBox` fits to the
-   * ENTRY SWEEP, the sweep is very nearly a disc, so the frame is very nearly
-   * square whatever the drawing does, and dead vertical space is therefore
-   * ≈ (drawing width − drawing height) / 2 for ANY layout. Widening the drawing
-   * to fill more of the frame's width — which criterion 4 asks for and which
-   * this change delivers, 0.828 → 0.839 on cs210 — necessarily spends a little
-   * of its height share. The bar is kept as a floor with a stated number rather
-   * than deleted, so a future change that empties the frame still fails.
+   * The FRAME-HEIGHT SHARE went 0.55 → 0.50 with the fan, and is now **0.75**,
+   * which is the whole point of tightening the entry sweep. It measures how much
+   * of the frame the drawing actually occupies vertically, i.e. it is the dead
+   * band stated as a ratio, and it is the bar that would have caught the band in
+   * the first place had it been set honestly. Under the 1.5-turn sweep the frame
+   * was fitted to what is very nearly a DISC, so it came out very nearly square
+   * around a drawing twice as wide as it is tall: 0.532 desktop, 0.569 phone —
+   * ~149 CSS px of empty paper above and below. At a quarter turn the swept
+   * union hugs the drawing and the same measurement is **0.851 desktop, 0.903
+   * phone**. The floor is set at 0.75 rather than at the measurement, so the
+   * type scale still has somewhere to move, but it is now high enough that
+   * putting the 540° sweep back fails this test rather than merely making the
+   * section 224px taller in silence.
    *
-   * What is asserted, then: the aspect stays inside a stated window, the
-   * drawing fills a real share of the frame on EACH axis, and it is CENTRED, so
-   * whatever whitespace the sweep costs is spent symmetrically instead of
-   * shoved to one side. The left-to-right seating family — which grows upward
-   * and keeps children with their parents, but puts a two-step arm on the
-   * vertical and the leaf beside it — measures 13% off-centre and fails this.
+   * What is asserted, then: the aspect stays inside a stated window, the drawing
+   * fills a real share of the frame on EACH axis, and it is CENTRED, so whatever
+   * whitespace the sweep does cost is spent symmetrically instead of shoved to
+   * one side. The left-to-right seating family — which grows upward and keeps
+   * children with their parents, but puts a two-step arm on the vertical and the
+   * leaf beside it — measures 13% off-centre and fails this.
+   *
+   * The VERTICAL off-centre number moved 2.1% → 4.2% (desktop; 1.8% → 3.9%
+   * phone) and the 5% bar did not, which is the constraint that picked the
+   * quarter turn over a third of one. The sweep's headroom is one-sided — the
+   * fan's tips lift past the settled top when they rotate through the vertical,
+   * while nothing swings below the course code — so every degree of rotation
+   * buys frame at the top only and slides the drawing down inside it. At 0.3
+   * turns this reads 5.4% and fails.
    */
   describe('the settled graph is a sane shape, centred in its frame', () => {
     for (const view of GRAPH_VIEWS) {
@@ -679,10 +773,10 @@ describe('helixEntry × radialLayout — nothing leaves the fitted viewBox', ()
           const aspect = (b - t) / (r - l);
           expect(aspect, 'settled aspect').toBeGreaterThanOrEqual(0.4);
           expect(aspect, 'settled aspect').toBeLessThanOrEqual(0.8);
-          // Measured: 0.815–0.934 wide, 0.532–0.569 tall.
+          // Measured: 0.841–0.964 wide, 0.851–0.903 tall.
           expect((r - l) / view.fit.w, 'share of the frame width').toBeGreaterThan(0.75);
-          expect((b - t) / view.fit.h, 'share of the frame height').toBeGreaterThan(0.5);
-          // Centred: measured ≤ 3.2% of the width, ≤ 2.1% of the height.
+          expect((b - t) / view.fit.h, 'share of the frame height').toBeGreaterThan(0.75);
+          // Centred: measured ≤ 3.9% of the width, ≤ 4.2% of the height.
           expect(
             Math.abs((l + r) / 2 - (view.fit.x + view.fit.w / 2)) / view.fit.w,
             'horizontal off-centre',
@@ -719,8 +813,8 @@ describe('fitViewBox — one stable frame for every course', () => {
     // The shipped bug: `viewBox="0 0 900 560"` around content 578 units wide.
     expect(DESKTOP_VIEW.fit.w).toBeLessThan(DESKTOP_VIEW.w);
     expect(DESKTOP_VIEW.fit.h).toBeLessThan(DESKTOP_VIEW.h);
-    expect(viewBoxAttr(DESKTOP_VIEW.fit)).toBe('161 17 603 534');
-    expect(viewBoxAttr(MOBILE_VIEW.fit)).toBe('-32 -25 443 365');
+    expect(viewBoxAttr(DESKTOP_VIEW.fit)).toBe('161 114 582 334');
+    expect(viewBoxAttr(MOBILE_VIEW.fit)).toBe('-32 40 429 230');
   });
 });
 
@@ -816,7 +910,7 @@ describe('settled frame — no foreign label collisions', () => {
  * 390px phone viewport is a uniform 0.38 scale: 4.6 CSS px labels and 10.6 CSS
  * px dots. These pin the sizes the mobile view actually resolves to, in the
  * units a visitor sees — and they are the unit-test twin of the Playwright gate
- * in `e2e/landing-graph.spec.ts` (≥11px labels, ≥20px dots, >260px tall).
+ * in `e2e/landing-graph.spec.ts` (≥11px labels, ≥20px dots, >170px tall).
  */
 describe('GraphView sizing at a 390px viewport', () => {
   /**
@@ -830,27 +924,37 @@ describe('GraphView sizing at a 390px viewport', () => {
 
   it('renders legible labels and dots on a phone', () => {
     const scale = CONTENT_PX / MOBILE_VIEW.fit.w;
-    expect(scale).toBeCloseTo(0.7494, 4);
-    // 11.99 CSS px labels, 22.48 CSS px dot diameter, 273.5 CSS px of graph
-    // height. The phone geometry is still bracketed from BELOW by a label
-    // collision (which wants a bigger ring) and from ABOVE by this gate (which
-    // wants a smaller frame), but the upward fan widened the window: its two
-    // deep arms are 90° apart and symmetric, so the worst horizontal step is
-    // `ring·sin 45°` on both instead of `ring·sin 60°` on one and `ring·sin 30°`
-    // on the other. The margins on the three bars are +0.99px / +2.48px /
-    // +13.5px, against the downward tree's +0.23px / +0.85px / +25.5px — the
-    // first two roughly quadrupled, and the first one was inside the noise of
-    // whether Chromium paints a scrollbar at this viewport.
+    expect(scale).toBeCloseTo(0.7739, 4);
+    // 12.38 CSS px labels, 23.22 CSS px dot diameter, 178.0 CSS px of frame.
+    // The phone geometry is still bracketed from BELOW by a label collision
+    // (which wants a bigger ring) and from ABOVE by the type gate (which wants a
+    // smaller frame), and tightening the entry sweep moved both the right way at
+    // once: the frame narrowed 443 → 429 units, so every unit renders bigger.
+    // Margins are now +1.38px and +3.22px, against +0.99px and +2.48px under the
+    // 1.5-turn sweep and +0.23px / +0.85px under the downward tree.
     expect(MOBILE_VIEW.font * scale).toBeGreaterThanOrEqual(11);
     expect(2 * MOBILE_VIEW.nodeR * scale).toBeGreaterThanOrEqual(20);
-    expect(MOBILE_VIEW.fit.h * scale).toBeGreaterThanOrEqual(260);
+    // THE THIRD BAR CHANGED WHAT IT MEASURES, and it is worth being explicit.
+    // It used to be `fit.h * scale >= 260` — the FRAME's rendered height — and
+    // it was written to fail the "213px smudge" the hardcoded 900×560 viewBox
+    // rendered at this viewport. That reading only worked while the frame was
+    // mostly empty paper: fitting to a 1.5-turn sweep reserved 64 and 54 CSS px
+    // of band above and below a 156px-tall drawing, and the bar was passing on
+    // the band. The quarter turn spends 16 and 2 instead, so the frame is 178px
+    // and the DRAWING inside it is 160.7 — bigger than it was, in a box 95px
+    // shorter. So: assert the drawing, which is what "not a smudge" meant, and
+    // keep a floor on the frame that a genuinely tiny graph still fails.
+    expect(MOBILE_VIEW.fit.h * scale, 'rendered frame height').toBeGreaterThanOrEqual(170);
+    expect(settledHeight(MOBILE_VIEW) * scale, 'rendered drawing height').toBeGreaterThanOrEqual(
+      150,
+    );
   });
 
   it('documents why the desktop view is still not a phone view', () => {
     // Not an aspiration — the reason `useIsMobile` swaps views at all, kept
     // here so a future "just use one viewBox everywhere" change has to argue
-    // with it. The fit shrank the desktop box from 900 to 526 units, which
-    // lifts a phone-rendered desktop label from 4.6 to 7.6 CSS px — still
+    // with it. The fit shrank the desktop box from 900 to 582 units, which
+    // lifts a phone-rendered desktop label from 4.6 to 8.0 CSS px — still
     // nowhere near the 11px floor above.
     const scale = CONTENT_PX / DESKTOP_VIEW.fit.w;
     expect(DESKTOP_VIEW.font * scale).toBeLessThan(11);
diff --git a/frontend/src/components/marketing/graph/layout.ts b/frontend/src/components/marketing/graph/layout.ts
index b7234f2b..b8dd4878 100644
--- a/frontend/src/components/marketing/graph/layout.ts
+++ b/frontend/src/components/marketing/graph/layout.ts
@@ -362,7 +362,7 @@ export function radialLayout(
 
 /**
  * How far *inside* its target radius a node starts. The offset from the centre
- * is scaled by `1 - (1 - e) * ENTRY_CONTRACTION`, i.e. 0.55× at t=0 rising to
+ * is scaled by `1 - (1 - e) * ENTRY_CONTRACTION`, i.e. 0× at t=0 rising to
  * exactly 1× at t=1.
  *
  * This used to be a *stretch* (`1 + (1 - e) * 0.9`, so 1.9× at t=0), which is
@@ -374,25 +374,72 @@ export function radialLayout(
  * the disc of radius |target − centre|. `layout.test.ts` pins that as an
  * explicit bounds sweep over every fixture × every view.
  *
- * It reads better too: nodes now grow outward from the root rather than flying
- * in from off-frame.
+ * IT IS NOW EXACTLY 1, i.e. a node starts ON the centre rather than 55% of the
+ * way out to its seat, and that is the second half of the frame-tightening this
+ * wave is about (see `ENTRY_TURNS`). At 1 the radial term collapses to
+ * `radiusScale = e`, which is precisely the straight-line entry's own easing —
+ * so the path becomes "the straight line from the centre to the seat, ROTATED
+ * by a decaying angle", and the whole of the mid-flight deviation measured in
+ * `layout.test.ts` is the helix rather than a radius mismatch. It also buys
+ * frame: the widest swing happens where the node is nearest the centre, so
+ * pulling the start in shrinks how far the sweep bulges past the settled
+ * drawing — at the same quarter turn, 0.45 overhangs the settled top by 68.6
+ * units and 1 by 27.9, which is 41 units of section height (50 CSS px) and the
+ * difference between the drawing sitting 9.1% and 4.2% off the frame's centre.
+ *
+ * It reads better too: nodes now grow outward from the middle of the canopy
+ * rather than flying in from off-frame, and at t=0 they are at 0.35 scale and
+ * zero opacity, so the pile-up at the centre is never actually drawn.
  */
-const ENTRY_CONTRACTION = 0.45;
+const ENTRY_CONTRACTION = 1;
+
+/**
+ * How far a node is rotated around the centre on the way in — the HELIX, and
+ * the thing that sets how much dead vertical band the section carries.
+ *
+ * IT WAS 1.5 (540°). `fitViewBox` fits the frame to the SWEEP rather than to
+ * the settled positions (it has to — see there), and a node that turns a turn
+ * and a half passes through EVERY direction at between 0.55 and 1.00 of its
+ * final radius. The union of those sweeps is very nearly a DISC, so the fitted
+ * frame came out very nearly SQUARE while the settled drawing is an upward fan
+ * about twice as wide as it is tall. The difference was dead space, ~149 CSS px
+ * of it above and below the drawing at the 720px cap, for ANY layout at all:
+ * the previous wave measured the whole family and reported it as its closing
+ * concern.
+ *
+ * A QUARTER TURN. 90° of rotation with the radial ramp still reads as a swoop
+ * with depth — the node arrives on a curve, not on a line — while the swept
+ * union hugs the drawing: the frame goes 603 × 534 → 582 × 334 units and the
+ * band per side goes 162/136 → 48/13 CSS px. 540° at the 1.1s the component
+ * spends on the assembly is ~490°/s, which is a blur nobody can follow; the
+ * quarter turn is the same idea at a speed the eye can read.
+ *
+ * WHY NOT LESS, AND WHY NOT MORE. Less: at 0.15 turns the mid-flight deviation
+ * from the straight-line path falls to 13 units (10% of the travel radius) and
+ * the entry starts reading as a plain zoom. More: the sweep's bulge past the
+ * settled drawing is one-sided — the fan's tips are far from the centre and
+ * only 27° above the horizontal, so rotating them TOWARD the vertical gains
+ * height, while nothing in the drawing can swing below the root's caption —
+ * and past ~0.3 turns that lopsided headroom pushes the drawing off the frame's
+ * vertical centre by more than the 5% `layout.test.ts` allows. 0.25 sits inside
+ * both bars with room (4.2% off-centre, 48px of band).
+ */
+const ENTRY_TURNS = 0.25;
 
 /**
  * Position along the helical entry path. `t` runs 0 → 1.
  *
- * The node spirals outward from near the centre: its offset from the centre is
- * rotated by a decreasing angle and contracted by a shrinking factor, while
- * scale and opacity rise. At t=1 every term collapses and the node sits exactly
- * on `target`, so the animation has no seam where it hands off to the static
+ * The node spirals outward from the centre: its offset from the centre is
+ * rotated by a decreasing angle and scaled by a growing factor, while scale and
+ * opacity rise. At t=1 every term collapses and the node sits exactly on
+ * `target`, so the animation has no seam where it hands off to the static
  * layout.
  */
 export function helixEntry(
   target: Point,
   centre: Point,
   t: number,
-  turns = 1.5,
+  turns = ENTRY_TURNS,
 ): { x: number; y: number; scale: number; opacity: number } {
   const e = easeOutCubic(t);
   const dx = target.x - centre.x;
@@ -482,18 +529,24 @@ const FIT_STEPS = 512;
  * stayed permanently empty. The frame is now measured off the content instead.
  *
  * THE THING TO NOT GET WRONG: fit to the HELIX SWEEP, not to the settled node
- * positions. `helixEntry` rotates a node up to 1.5 turns around the centre on
- * the way in, so every outer node passes through every direction on its way to
- * rest. Under the upward fan that gap is WIDER still than it was under the
- * downward tree, because a canopy is a wide, short object inside a circular
- * sweep: on desktop the settled drawing spans 284.3 units of height while the
- * sweep spans 513.6, so a box fitted to the settled positions would clip 125.8
- * units off the top and 103.6 off the bottom — 150 and 124 CSS px at the
- * rendered cap, in plain view. That exact bug was found and fixed once already
- * on this branch (#344 review #4). The phone numbers are 82.9 and 69.6, against
- * 63.6 and 73.5 before. `layout.test.ts` sweeps `t` across
- * the full range to keep it fixed, and pins the overshoot itself so a
- * settled-fit implementation fails outright.
+ * positions. `helixEntry` rotates every node around the centre on the way in,
+ * so a node arrives from a direction that is not its own, and the frame has to
+ * hold the arc. That exact bug was found and fixed once already on this branch
+ * (#344 review #4), and the fix must survive the sweep getting SHORTER: at the
+ * quarter turn this file now ships, the desktop settled drawing spans 284.3
+ * units of height while the sweep spans 312.2, so a box fitted to the settled
+ * positions would still chop 27.9 units — 34.5 CSS px at the rendered cap — off
+ * the top of the assembly, live, at ~80% opacity. The phone number is 17.6
+ * units (13.6 px). `layout.test.ts` sweeps `t` across the full range to keep it
+ * fixed, and asserts the clipping directly (it builds the settled-fit box and
+ * proves the assembly leaves it) so a settled-fit implementation fails outright.
+ *
+ * The overshoot is ONE-SIDED and that is geometry, not an oversight: the fan's
+ * tips sit far from the centre and only ~27° above the horizontal, so rotating
+ * them toward the vertical lifts them past the settled top, while the lowest
+ * ink in the drawing — the course code under the root — is close to the centre
+ * and nothing swings below it. The frame's bottom edge is therefore the settled
+ * bottom plus `fitPad`, and the sweep sets the other three sides.
  *
  * Fitted ONCE across all three fixtures rather than per graph: the three share
  * a topology and differ only in label widths, so a per-graph fit would produce
@@ -555,14 +608,19 @@ function withFit(geom: GraphGeometry): GraphView {
 }
 
 /**
- * Retuned for the upward fan. Frame `161 17 603 534`, against `165 48 541 498`
- * for the downward radial tree, `185 33 526 516` for the ring layout before it,
- * and the `0 0 900 560` the demo shipped with.
+ * Frame `161 114 582 334`, against `161 17 603 534` for the same fan under the
+ * 1.5-turn entry sweep, `165 48 541 498` for the downward radial tree,
+ * `185 33 526 516` for the ring layout before it, and the `0 0 900 560` the demo
+ * shipped with. Nothing about the layout moved between the last two — only the
+ * sweep the frame is fitted to (see `ENTRY_TURNS`).
  *
  * The component caps the rendered width (`md:max-w-[720px]`), so at the cap the
- * graph draws at 1.194 user units per CSS px: 16.7px labels, 33.4px concept
- * dots, a 62px root, and a **637.6px-tall `<svg>` — 25px SHORTER** than the
- * downward tree's 662.8 and 99px shorter than the 737px the fixed box reserved.
+ * graph draws at 1.237 user units per CSS px: 17.3px labels, 34.6px concept
+ * dots, a 64px root, and a **413.2px-tall `<svg>` — 224px SHORTER** than the
+ * 637.6 the 1.5-turn sweep fitted, 250px shorter than the downward tree's 662.8
+ * and 324px shorter than the 737px the fixed box reserved. The drawing itself
+ * did not shrink; it grew (694 × 352 CSS px against 669 × 339). What left was
+ * the dead band: 162/136 CSS px above and below the drawing, now **48/13**.
  *
  * WHY `maxRadius` LEFT 232, i.e. why it is no longer `radialLayout`'s
  * inscribed-circle default. Under the upward fan the drawing wraps its own
@@ -577,21 +635,11 @@ function withFit(geom: GraphGeometry): GraphView {
  * - the shape assertions, which are scale-free.
  *
  * The composition it buys, measured on cs210: the drawing is 506 × 284 units
- * (604 × 339 CSS px) inside a 603 × 534 frame, centred to within 2.8% of the
- * width and 2.1% of the height. It fills **0.839 of the frame's width** against
- * the downward tree's 0.828 (ma242 0.916, sm275 0.881), and 0.53 of its height.
- *
- * The height share is the one number that did not improve, and it is worth
- * being precise about why: `fitViewBox` fits the frame to the ENTRY SWEEP, and
- * the sweep is very nearly a disc, so the frame is very nearly square whatever
- * the drawing does. Dead vertical space is therefore ≈ (drawing width −
- * drawing height) / 2 for any layout, and a canopy is by definition wider than
- * tall. Measured: 149 CSS px of band above and below, against 145 for the
- * downward tree — a wash. Making that band small needs a drawing with aspect
- * ≈ 1, which is neither a canopy nor shorter (swept: a symmetric fan narrow
- * enough to fill the height renders a 683px section). The lever that would
- * actually shrink it is the sweep itself — `helixEntry`'s 1.5 turns — and that
- * is an animation change, out of this wave's scope.
+ * (626 × 352 CSS px) inside a 582 × 334 frame, centred to within 1.1% of the
+ * width and 4.2% of the height. It fills **0.869 of the frame's width** (ma242
+ * 0.949, sm275 0.913) and **0.851 of its height**, against 0.839 and 0.532
+ * under the 1.5-turn sweep — the height share is where the tightened sweep
+ * lands, and it is the number the dead band is the complement of.
  */
 export const DESKTOP_VIEW: GraphView = withFit({
   w: 900,
@@ -608,13 +656,21 @@ export const DESKTOP_VIEW: GraphView = withFit({
 });
 
 /**
- * The phone view, and the breakpoint that gains the most from the upward fan.
- * Frame `-32 -25 443 365`; a ~332px content box (390 viewport − 48 of `px-6` −
- * the 10px scrollbar globals.css paints) renders it at 0.7494, so 16-unit
- * labels land at **11.99 CSS px**, concept dots at a **22.48px** diameter, and
- * the `<svg>` is **273.5px** tall. All three clear the E2E legibility gate
- * (≥11px labels, ≥20px dots, >260px tall), and all three are BETTER than the
- * downward tree's 11.23 / 20.85 / 285.5 on the two that were nearly lost.
+ * The phone view. Frame `-32 40 429 230`; a ~332px content box (390 viewport −
+ * 48 of `px-6` − the 10px scrollbar globals.css paints) renders it at 0.7739,
+ * so 16-unit labels land at **12.38 CSS px**, concept dots at a **23.22px**
+ * diameter, the DRAWING is **328 × 161 px**, and the `<svg>` is **178.0px**
+ * tall — against 11.99 / 22.48 / 317 × 156 / 273.5 under the 1.5-turn sweep.
+ *
+ * READ THAT LAST PAIR CAREFULLY, because one of them went DOWN. The frame lost
+ * 95px of height while the drawing inside it grew: what left was the band of
+ * empty paper the circular sweep reserved (64/54 CSS px above and below, now
+ * **16/2**). The E2E gate's third bar was written against the frame — it read
+ * ">260px tall" as "not the 213px smudge the fixed 900×560 viewBox rendered
+ * here" — and a frame measurement can no longer stand in for that, because this
+ * frame is nearly all drawing. So the bar moved to 170 and `layout.test.ts`
+ * gained the honest one: the SETTLED DRAWING's rendered height, which improves
+ * (155.6 → 160.7 px) rather than being traded away.
  *
  * THE CONSTRAINT THAT WAS RAZOR-THIN AND NO LONGER IS. Labels hang below their
  * dots and are `middle`-anchored, so a 13-character label ("Vector Spaces",
@@ -631,16 +687,19 @@ export const DESKTOP_VIEW: GraphView = withFit({
  * `ring·sin 45°` on BOTH of them instead of `ring·sin 60°` on one and
  * `ring·sin 30°` on the other, and the crowded pair moves from "a child's dot
  * inside its parent's label" to "the middle shoot's label beside a depth-1
- * dot". Measured worst pair over all three fixtures: **+5.40 units = 4.05 CSS
- * px**, a 4× improvement, with the label gate now clearing by 0.99 CSS px
- * instead of 0.23.
+ * dot". Measured worst pair over all three fixtures: **+5.40 units**, unchanged
+ * by this wave (the settled layout did not move) and now **4.18 CSS px** rather
+ * than 4.05, because the tighter frame renders every unit slightly bigger.
  *
  * The window is still two-sided — the collision wants a bigger ring, the
  * legibility gate wants a smaller frame (`font · 332 / fit.w ≥ 11`) — and the
- * point below was picked by sweeping `maxRadius`, `font`, `rootR`, `nodeR` and
- * `labelGap` against BOTH ends plus the shape assertions, maximising the worst
- * normalised margin. `fitPad` stays at 2 (the fit's outward whole-unit snap
- * sits under it); everything else moved.
+ * numbers below were picked by sweeping `maxRadius`, `font`, `rootR`, `nodeR`
+ * and `labelGap` against BOTH ends plus the shape assertions, maximising the
+ * worst normalised margin. Tightening the sweep moved both margins the right
+ * way (the label gate clears by 1.38 CSS px now, against 0.99), so none of them
+ * needed to move. `fitPad` stays at 2: it is now most of the air under the
+ * course code, and the 4 units of descender the fit reserves for a caption that
+ * has no descenders sit under that again.
  */
 export const MOBILE_VIEW: GraphView = withFit({
   w: 360,

From 86cfacff1e93103a487b0616a59d26c3446c06b1 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 21:08:43 -0700
Subject: [PATCH 18/20] fix(landing): restore atmospheric continuity between
 the sections (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deleting #features and HowItWorks took the middle of the page's atmosphere
with them, and nothing replaced it.

The hero carries mesh-blob--1 and --2. The old #features carried --3 and --2,
and HowItWorks carried a dark-green scroll tint. The CTA carries --1 and --2
PLUS a top gradient that started at rgba(20,83,45,0.08) on its very first pixel
— because it was designed to blend DOWN out of that dark-green tint.

So after the deletions the page ran: atmospheric hero -> a completely flat
graph section -> a CTA whose green tint faded in from bare paper. Two hard
seams, one on each side of the new section.

The graph section now carries its own blobs at lower opacity than the hero's,
so the graph itself stays the focus, and the CTA's wash starts transparent and
peaks below the boundary instead of on it.

Found by spinning up the dev server and looking at the whole page, not the
section in isolation — the section screenshots I had been judging could not
show a seam, because a seam only exists between two things.

94 graph tests pass; tsc clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 frontend/src/app/(public)/page.tsx            | 10 +++++++--
 .../marketing/graph/KnowledgeGraphDemo.tsx    | 21 +++++++++++++++++--
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/frontend/src/app/(public)/page.tsx b/frontend/src/app/(public)/page.tsx
index 85846d2e..484a7a30 100644
--- a/frontend/src/app/(public)/page.tsx
+++ b/frontend/src/app/(public)/page.tsx
@@ -578,14 +578,20 @@ export default function LandingPage() {
 
         {/* ═══ Final CTA ═══ */}
         <section className="landing-section py-32 relative text-center z-10">
-          {/* Soft green tint blending down into the mesh below */}
+          {/* Soft green wash in the section's upper body.
+              This used to start at full strength on the very top edge, because
+              it was blending DOWN out of HowItWorks' dark-green scroll tint.
+              That section is gone, so a tint that starts at 0.08 on the
+              boundary now fades in from flat paper and reads as a hard seam.
+              Peak it below the edge and start from transparent instead. */}
           <div
             aria-hidden
             className="pointer-events-none absolute left-0 right-0 z-0"
             style={{
               top: 0,
               height: 'clamp(240px, 42vh, 480px)',
-              background: 'linear-gradient(to bottom, rgba(20,83,45,0.08) 0%, rgba(20,83,45,0.04) 45%, rgba(20,83,45,0) 100%)',
+              background:
+                'linear-gradient(to bottom, rgba(20,83,45,0) 0%, rgba(20,83,45,0.05) 35%, rgba(20,83,45,0) 100%)',
             }}
           />
           <div aria-hidden className="absolute inset-0 pointer-events-none z-0">
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index 121fc508..31da4ad0 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -319,9 +319,26 @@ export default function KnowledgeGraphDemo() {
       id="knowledge-graph"
       data-testid="landing-graph"
       aria-label={`Interactive knowledge graph for ${graph.name}`}
-      className="landing-section landing-graph relative z-10 py-24 md:py-32"
+      className="landing-section landing-graph relative z-10 py-24 md:py-32 overflow-hidden"
     >
-      <div className="max-w-7xl mx-auto px-6 lg:px-12">
+      {/* Atmospheric continuity. The hero above and the CTA below both carry
+          mesh blobs; the sections this one replaced (#features, HowItWorks)
+          carried --3 and --2 plus a green tint. Without them the middle of the
+          page is a flat hole between two atmospheric sections, and the cut in
+          and out of it reads as a seam. Lower opacity than the hero's so the
+          graph itself stays the focus. */}
+      <div aria-hidden className="absolute inset-0 pointer-events-none z-0">
+        <div
+          className="sapling-mesh-blob sapling-mesh-blob--3"
+          style={{ top: '2%', left: '-14%', bottom: 'auto', opacity: 0.26, width: '34vw', height: '34vw' }}
+        />
+        <div
+          className="sapling-mesh-blob sapling-mesh-blob--2"
+          style={{ bottom: '-8%', right: '-10%', top: 'auto', opacity: 0.18, width: '30vw', height: '30vw' }}
+        />
+      </div>
+
+      <div className="relative z-[1] max-w-7xl mx-auto px-6 lg:px-12">
         <div
           data-testid="landing-graph-copy"
           data-engaged={engaged ? 'true' : 'false'}

From c99ed014cc9c93e76b635df12cc09a7037116bf2 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 21:58:57 -0700
Subject: [PATCH 19/20] feat(landing): three feature bands and a bento of built
 surfaces (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 2 of the below-hero redesign. The page now runs hero → graph →
Universal Upload → Adaptive Quizzes → bento → Spaced Repetition → CTA.

The three bands carry ONE arc — material in → practice → retention —
rather than three disconnected pitches, and the closing band (not a grid
tile) hands off to the CTA: a grid's last tile is a weak place to ask for
a signup. Surfaces alternate sides, derived from position in
`featureBands.tsx` rather than written down per band, so inserting a band
can't silently put two surfaces in the same gutter.

Every tile is a RECREATED PRODUCT SURFACE, never an icon over a heading
over a sentence — the brand guide's hard anti-pattern. The seven
recreations are faithful to the shipped screens: the upload modal's file
rows and status wording, QuizPanel's radiogroup with its `A.` prefix and
selected treatment, Study's rating trio, ChatPanel's asymmetric bubbles,
the notetaker's linked-concept rail, Social's invite chip and sender
names, and the gradebook's letter grade over real assignment rows.

Brand constraints that shaped the code rather than just the CSS:

- No glassmorphism. `.liquid-glass` is deliberately not reused; surfaces
  are solid warm paper with hairline borders.
- Colour is state. Every mastery mark reads `TIER_COLOR` — the same map
  the graph section above paints its nodes with — and the only other hues
  are `--grade-*`. Unit-tested, so a raw hex can't creep back in.
- Contrast forced two divergences from the app's own paint: the student
  bubble takes `--brand-forest` (6.4:1 under white) not `--accent`
  (4.04:1), and per-row grade letters keep `--text` lettering with the
  band on the border/dot, since `--grade-b` is 3.39:1 as a glyph.

No new dependency, no framer-motion, no JS motion at all: the surfaces
are static pictures, so `prefers-reduced-motion` and `IS_TEST_MODE` have
no frame to park — there is only the complete one. The entrance is the
page's existing `.landing-fade-up` observer, which degrades to "visible"
rather than "invisible" when it never fires.

All new CSS is inside the `.landing-page` scope and defines no tokens.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/frontend-testids.md                      |  29 +
 frontend/eslint.config.mjs                    |  10 +
 frontend/src/app/(public)/page.tsx            |  13 +
 frontend/src/app/globals.css                  | 626 ++++++++++++++++++
 .../components/marketing/FeatureBand.test.tsx | 111 ++++
 .../src/components/marketing/FeatureBand.tsx  |  93 +++
 .../marketing/SurfaceBento.test.tsx           | 115 ++++
 .../src/components/marketing/SurfaceBento.tsx |  72 ++
 .../src/components/marketing/featureBands.tsx |  55 ++
 .../marketing/surfaces/GradebookSurface.tsx   |  66 ++
 .../marketing/surfaces/NotesSurface.tsx       |  40 ++
 .../marketing/surfaces/QuizSurface.tsx        |  69 ++
 .../marketing/surfaces/ReviewSurface.tsx      |  76 +++
 .../marketing/surfaces/RoomsSurface.tsx       |  55 ++
 .../components/marketing/surfaces/Surface.tsx |  87 +++
 .../marketing/surfaces/TutorSurface.tsx       |  82 +++
 .../marketing/surfaces/UploadSurface.tsx      |  84 +++
 17 files changed, 1683 insertions(+)
 create mode 100644 frontend/src/components/marketing/FeatureBand.test.tsx
 create mode 100644 frontend/src/components/marketing/FeatureBand.tsx
 create mode 100644 frontend/src/components/marketing/SurfaceBento.test.tsx
 create mode 100644 frontend/src/components/marketing/SurfaceBento.tsx
 create mode 100644 frontend/src/components/marketing/featureBands.tsx
 create mode 100644 frontend/src/components/marketing/surfaces/GradebookSurface.tsx
 create mode 100644 frontend/src/components/marketing/surfaces/NotesSurface.tsx
 create mode 100644 frontend/src/components/marketing/surfaces/QuizSurface.tsx
 create mode 100644 frontend/src/components/marketing/surfaces/ReviewSurface.tsx
 create mode 100644 frontend/src/components/marketing/surfaces/RoomsSurface.tsx
 create mode 100644 frontend/src/components/marketing/surfaces/Surface.tsx
 create mode 100644 frontend/src/components/marketing/surfaces/TutorSurface.tsx
 create mode 100644 frontend/src/components/marketing/surfaces/UploadSurface.tsx

diff --git a/docs/frontend-testids.md b/docs/frontend-testids.md
index 2b45fbe6..2d85623b 100644
--- a/docs/frontend-testids.md
+++ b/docs/frontend-testids.md
@@ -81,6 +81,9 @@ renders the element.
 | Gradebook | `gradebook` | `frontend/src/components/screens/Gradebook/Landing.tsx` + `Course.tsx` (the `/gradebook` screens), `frontend/src/components/Gradebook/TranscriptModal.tsx` (the transcript modal), `frontend/src/components/Gradebook/CourseCard.tsx` (the term-aware card links), `frontend/src/components/Gradebook/AssignmentList.tsx` + `AssignmentModal.tsx` (the add-assignment flow the #468 mutation leg drives) — added with the #139 term-switcher/transcript journey |
 | Admin analytics | `admin-analytics` | `frontend/src/components/screens/AdminAnalytics.tsx` (the `/admin/analytics` dashboard — range presets/inputs, cost group-by toggle, per-panel retry) — added with the #121 data layer |
 | Landing knowledge graph demo | `landing-graph` | `frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx` (the pre-auth landing page's interactive course-picker + laid-out concept graph, #344) |
+| Landing feature bands | `landing-band` | `frontend/src/components/marketing/FeatureBand.tsx` (the three full-width bands below the graph; content + side-alternation in `featureBands.tsx`, #344 step 2) |
+| Landing surface bento | `landing-bento` | `frontend/src/components/marketing/SurfaceBento.tsx` (the four-tile grid of built product surfaces, #344 step 2) |
+| Landing product surfaces | `landing-surface` | `frontend/src/components/marketing/surfaces/*.tsx` (the seven in-page recreations the bands and bento mount, #344 step 2) |
 
 Two surfaces do **not** carry their testids in the screen file named by the
 route:
@@ -344,6 +347,32 @@ spec and will reuse these same testids.
 | `landing-graph-headline` | the "Pick a course. Watch it grow." heading — carries the engagement fade (`ENGAGED_HEADLINE_OPACITY`) |
 | `landing-graph-blurb` | the reserved-height paragraph below the graph that shows the hovered node's one-sentence blurb |
 
+### `landing-band` / `landing-bento` / `landing-surface`
+
+Added with the #344 step-2 build (feature bands + surface bento). These
+surfaces are **static recreations** of shipped product screens — there is
+deliberately not a single `<button>`, `<input>` or `<textarea>` among them
+(the spec's "no per-tile buttons"), so the lint block below is satisfied
+vacuously and stays as a guard on anything added later.
+
+| testid | element |
+| --- | --- |
+| `landing-band-{bandId}` | one feature band's `<section>` — `bandId` is `upload`, `quiz` or `review` (a stable content id, per the repeated-items rule). Carries `data-surface-side="left"\|"right"`, the resolved alternation |
+| `landing-band-{bandId}-eyebrow` | that band's mono micro-label |
+| `landing-bento` | the four-tile grid's `<section>` root |
+| `landing-bento-eyebrow` | the bento's mono micro-label |
+| `landing-surface-upload` | Document Library ingest queue (band 1) |
+| `landing-surface-quiz` | an Adaptive Quizzes question mid-answer (band 2) |
+| `landing-surface-review` | the Study screen's spaced review + rating trio (band 3) |
+| `landing-surface-tutor` | a Tutor exchange (bento) |
+| `landing-surface-notes` | a Notetaker note with its linked concepts (bento) |
+| `landing-surface-rooms` | a Study Rooms conversation (bento) |
+| `landing-surface-gradebook` | a Gradebook course header + assignment rows (bento) |
+
+The `landing-surface-*` ids suffix the *surface* rather than a render index
+because each one mounts exactly once and the surface name is the stable
+domain id here.
+
 ## Enforcement
 
 `frontend/eslint.config.mjs` has a per-file `no-restricted-syntax` block scoped
diff --git a/frontend/eslint.config.mjs b/frontend/eslint.config.mjs
index 2914bf85..478c3d55 100644
--- a/frontend/eslint.config.mjs
+++ b/frontend/eslint.config.mjs
@@ -76,6 +76,16 @@ const eslintConfig = [
       "src/components/screens/AdminAnalytics.tsx",
       "src/components/screens/Tree.tsx",
       "src/components/marketing/graph/KnowledgeGraphDemo.tsx",
+      "src/components/marketing/FeatureBand.tsx",
+      "src/components/marketing/SurfaceBento.tsx",
+      "src/components/marketing/surfaces/GradebookSurface.tsx",
+      "src/components/marketing/surfaces/NotesSurface.tsx",
+      "src/components/marketing/surfaces/QuizSurface.tsx",
+      "src/components/marketing/surfaces/ReviewSurface.tsx",
+      "src/components/marketing/surfaces/RoomsSurface.tsx",
+      "src/components/marketing/surfaces/Surface.tsx",
+      "src/components/marketing/surfaces/TutorSurface.tsx",
+      "src/components/marketing/surfaces/UploadSurface.tsx",
     ],
     rules: {
       "no-restricted-syntax": [
diff --git a/frontend/src/app/(public)/page.tsx b/frontend/src/app/(public)/page.tsx
index 484a7a30..25ec46b5 100644
--- a/frontend/src/app/(public)/page.tsx
+++ b/frontend/src/app/(public)/page.tsx
@@ -8,6 +8,9 @@ import { useScrollLock } from '@/lib/useScrollLock';
 import { Users, PenSquare } from 'lucide-react';
 import SignInModal from '@/components/marketing/SignInModal';
 import { HeroCard } from '@/components/marketing/HeroCard';
+import FeatureBand from '@/components/marketing/FeatureBand';
+import SurfaceBento from '@/components/marketing/SurfaceBento';
+import { FEATURE_BANDS } from '@/components/marketing/featureBands';
 import { BRAND_FOREST } from '@/lib/brand';
 import { Button } from "@/components/ui";
 import { IS_TEST_MODE, random, now } from '@/lib/testMode';
@@ -576,6 +579,16 @@ export default function LandingPage() {
       <div>
         <KnowledgeGraphDemo />
 
+        {/* ═══ Feature bands + bento ═══
+            One arc — material in → practice → retention — with the bento of
+            built surfaces re-energising the middle. Band 3 is the closing
+            claim, so it (not a grid tile) hands off to the CTA; content and
+            side-alternation live in components/marketing/featureBands.tsx. */}
+        <FeatureBand {...FEATURE_BANDS[0]} />
+        <FeatureBand {...FEATURE_BANDS[1]} />
+        <SurfaceBento />
+        <FeatureBand {...FEATURE_BANDS[2]} />
+
         {/* ═══ Final CTA ═══ */}
         <section className="landing-section py-32 relative text-center z-10">
           {/* Soft green wash in the section's upper body.
diff --git a/frontend/src/app/globals.css b/frontend/src/app/globals.css
index c116e0de..a107197f 100644
--- a/frontend/src/app/globals.css
+++ b/frontend/src/app/globals.css
@@ -1001,3 +1001,629 @@ input[type="reset"]:disabled {
    hold WCAG AA 4.5:1 over the paper background, so the eyebrow isn't faded at
    all — see ENGAGED_HEADLINE_OPACITY in KnowledgeGraphDemo.tsx (#344). */
 .landing-page .landing-graph-headline { transition: opacity 600ms ease; }
+
+/* ══════════════════════════════════════════════════════════════════════════
+   FEATURE BANDS + SURFACE BENTO (#344 step 2)
+
+   Everything here is scoped to `.landing-page` and ADDS classes only — no
+   token is defined or redefined below this line. The pre-auth page and the
+   app shell share token NAMES with different values, and leaking a
+   redefinition outward is the documented cause of the "get-started/beta feels
+   off" bug class (docs/frontend-rhythm-audit.md).
+
+   Two brand constraints shape the whole block:
+
+   1. NO glassmorphism. Every surface is solid warm paper (`--bg-panel` on the
+      page's `--bg`) with a hairline border. `.liquid-glass` is deliberately
+      not reused — even though #102 already emptied it out, the name is the
+      pattern the guide bans.
+   2. COLOUR IS STATE. The only hues below are `--state-*` (mastery) and
+      `--grade-*` (letter bands), plus `--brand-forest` for the brand anchor.
+      Every other surface colour is a warm neutral off the `--ink` ramp.
+   ══════════════════════════════════════════════════════════════════════════ */
+
+/* Shared mono micro-label — the section eyebrow. Matches the metrics the
+   knowledge-graph section sets inline one viewport above. */
+.landing-page .landing-eyebrow {
+  display: inline-block;
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.7rem;
+  font-weight: 500;
+  letter-spacing: 0.32em;
+  text-transform: uppercase;
+  color: var(--brand-forest);
+}
+
+/* ── Band layout ────────────────────────────────────────────────────────── */
+.landing-page .landing-band { padding: 5.5rem 0; overflow: hidden; }
+.landing-page .landing-bento { padding: 5.5rem 0 6rem; overflow: hidden; }
+
+.landing-page .landing-band-grid {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 2.5rem;
+  align-items: center;
+}
+
+@media (min-width: 900px) {
+  .landing-page .landing-band { padding: 7rem 0; }
+  .landing-page .landing-bento { padding: 7rem 0 8rem; }
+  .landing-page .landing-band-grid {
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    gap: 4.5rem;
+  }
+  /* The flip is a column assignment, not a source reorder: the DOM stays
+     copy-then-surface so the phone and the screen reader always get the claim
+     first. Only the wide layout crosses them over. */
+  .landing-page .landing-band--surface-left > .landing-band-copy {
+    grid-column: 2;
+    grid-row: 1;
+  }
+  .landing-page .landing-band--surface-left > .landing-band-surface {
+    grid-column: 1;
+    grid-row: 1;
+  }
+}
+
+.landing-page .landing-band-headline {
+  margin-top: 1.05rem;
+  font-family: var(--font-playfair), 'Playfair Display', Georgia, serif;
+  font-size: clamp(1.95rem, 3.4vw, 3.1rem);
+  font-weight: 600;
+  line-height: 1.06;
+  letter-spacing: -0.022em;
+  color: var(--text);
+}
+
+.landing-page .landing-band-body {
+  margin-top: 1.15rem;
+  max-width: 38ch;
+  font-size: 1.02rem;
+  line-height: 1.72;
+  color: var(--text-dim);
+}
+
+/* ── Bento grid ─────────────────────────────────────────────────────────── */
+.landing-page .landing-bento-head { margin-bottom: 2.75rem; }
+.landing-page .landing-bento-head .landing-band-headline { max-width: 20ch; }
+
+.landing-page .landing-bento-grid {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: 1.35rem;
+}
+
+@media (min-width: 700px) {
+  .landing-page .landing-bento-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+}
+
+/* Asymmetry, not four equal boxes: 7/5 then 5/7, so the wide tile changes
+   sides between rows and the two conversation-shaped surfaces sit on the
+   opposite diagonal from the two document-shaped ones. */
+@media (min-width: 1024px) {
+  .landing-page .landing-bento-grid {
+    grid-template-columns: repeat(12, minmax(0, 1fr));
+    gap: 1.5rem;
+  }
+  .landing-page .landing-bento-tile--tutor     { grid-column: span 7; }
+  .landing-page .landing-bento-tile--notes     { grid-column: span 5; }
+  .landing-page .landing-bento-tile--rooms     { grid-column: span 5; }
+  .landing-page .landing-bento-tile--gradebook { grid-column: span 7; }
+}
+
+.landing-page .landing-bento-tile { display: flex; }
+.landing-page .landing-bento-tile > * { width: 100%; }
+
+/* ── The surface frame ──────────────────────────────────────────────────── */
+.landing-page .landing-surface {
+  display: flex;
+  flex-direction: column;
+  background: var(--bg-panel);
+  border: 1px solid var(--border-strong);
+  border-radius: var(--r-lg);
+  box-shadow: var(--shadow-md);
+  overflow: hidden;
+  font-family: var(--font-dm-sans), 'DM Sans', system-ui, sans-serif;
+  color: var(--text);
+}
+
+.landing-page .landing-surface-chrome {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 9px 15px;
+  background: var(--ink-50);
+  border-bottom: 1px solid var(--border);
+}
+
+.landing-page .landing-surface-title {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.62rem;
+  font-weight: 500;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--text-dim);
+}
+
+.landing-page .landing-surface-meta,
+.landing-page .landing-surface-mono {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.66rem;
+  letter-spacing: 0.02em;
+  color: var(--text-muted);
+  white-space: nowrap;
+}
+
+.landing-page .landing-surface-body {
+  display: flex;
+  flex-direction: column;
+  gap: 9px;
+  padding: 14px 15px 15px;
+  flex: 1;
+}
+
+.landing-page .landing-surface-rule {
+  display: block;
+  height: 1px;
+  margin: 3px 0;
+  background: var(--border);
+}
+
+.landing-page .landing-surface-label {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.6rem;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+
+.landing-page .landing-surface-headrow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+}
+
+.landing-page .landing-surface-stack {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+  flex: 1;
+}
+
+.landing-page .landing-surface-name {
+  display: block;
+  font-size: 0.82rem;
+  font-weight: 500;
+  color: var(--text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.landing-page .landing-surface-sub {
+  font-size: 0.7rem;
+  color: var(--text-muted);
+}
+
+.landing-page .landing-surface-note {
+  margin: 0;
+  font-size: 0.78rem;
+  line-height: 1.55;
+  color: var(--text-dim);
+}
+
+.landing-page .landing-surface-footnote {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  font-size: 0.72rem;
+  color: var(--text-muted);
+}
+
+/* Mastery status mark — the same four tokens the knowledge graph paints with. */
+.landing-page .landing-surface-dot {
+  display: inline-block;
+  width: 7px;
+  height: 7px;
+  border-radius: var(--r-full);
+  flex-shrink: 0;
+}
+
+/* ── Rows, chips ────────────────────────────────────────────────────────── */
+.landing-page .landing-surface-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 10px;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--r-md);
+}
+
+.landing-page .landing-surface-doc {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 32px;
+  flex-shrink: 0;
+  border-radius: var(--r-xs);
+  background: var(--accent-soft);
+  border: 1px solid var(--accent-border);
+  color: var(--brand-forest);
+}
+
+.landing-page .landing-surface-status {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.6rem;
+  letter-spacing: 0.06em;
+  padding: 3px 8px;
+  border-radius: var(--r-full);
+  border: 1px solid var(--border);
+  background: var(--ink-50);
+  color: var(--text-muted);
+  white-space: nowrap;
+}
+/* Ingest is a STATE: forest for landed, neutral for waiting. */
+.landing-page .landing-surface-status.is-done {
+  background: var(--accent-soft);
+  border-color: var(--accent-border);
+  color: var(--brand-forest);
+}
+.landing-page .landing-surface-status.is-processing {
+  border-color: var(--border-strong);
+  color: var(--text-dim);
+}
+
+.landing-page .landing-surface-chiprow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.landing-page .landing-surface-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 3px 9px;
+  border-radius: var(--r-full);
+  border: 1px solid var(--border);
+  background: var(--ink-50);
+  font-size: 0.7rem;
+  color: var(--text-dim);
+  white-space: nowrap;
+}
+.landing-page .landing-surface-chip.is-count,
+.landing-page .landing-surface-chip.is-code,
+.landing-page .landing-surface-chip.is-hard {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.62rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+
+/* ── Quiz ───────────────────────────────────────────────────────────────── */
+.landing-page .landing-surface-concept {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 0.84rem;
+  font-weight: 500;
+  color: var(--text);
+}
+
+.landing-page .landing-surface-question {
+  margin: 2px 0 4px;
+  font-family: var(--font-spectral), 'Spectral', Georgia, serif;
+  font-size: 0.98rem;
+  line-height: 1.5;
+  color: var(--text);
+}
+
+.landing-page .landing-surface-options {
+  display: grid;
+  gap: 7px;
+}
+
+.landing-page .landing-surface-option {
+  display: flex;
+  align-items: baseline;
+  gap: 9px;
+  padding: 8px 12px;
+  border: 1.5px solid var(--border);
+  border-radius: var(--r-md);
+  background: var(--bg);
+  font-size: 0.82rem;
+  line-height: 1.4;
+  color: var(--text-dim);
+}
+/* The picked answer, in the panel's own selected treatment. */
+.landing-page .landing-surface-option.is-picked {
+  border-color: var(--brand-forest);
+  background: var(--accent-soft);
+  color: var(--text);
+}
+
+.landing-page .landing-surface-optionkey {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.72rem;
+  font-weight: 600;
+  color: var(--text-muted);
+}
+.landing-page .landing-surface-option.is-picked .landing-surface-optionkey {
+  color: var(--brand-forest);
+}
+
+/* "The next question moved" — a status, so it takes a status colour. */
+.landing-page .landing-surface-tune {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.62rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  padding: 3px 9px;
+  border-radius: var(--r-full);
+  border: 1px solid var(--state-progress);
+  color: var(--text);
+  white-space: nowrap;
+}
+
+/* ── Study / spaced review ──────────────────────────────────────────────── */
+.landing-page .landing-surface-track {
+  display: block;
+  height: 5px;
+  border-radius: var(--r-full);
+  background: var(--ink-100);
+  overflow: hidden;
+}
+.landing-page .landing-surface-fill {
+  display: block;
+  height: 100%;
+  border-radius: inherit;
+  background: var(--brand-forest);
+}
+
+.landing-page .landing-surface-card {
+  display: flex;
+  flex-direction: column;
+  gap: 7px;
+  padding: 16px 15px 18px;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--r-md);
+  min-height: 96px;
+  justify-content: center;
+}
+.landing-page .landing-surface-cardtext {
+  font-family: var(--font-playfair), 'Playfair Display', Georgia, serif;
+  font-size: 1.18rem;
+  line-height: 1.28;
+  letter-spacing: -0.01em;
+  color: var(--text);
+}
+
+.landing-page .landing-surface-ratings {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 7px;
+}
+/* Tint + hairline carry the verdict; the word stays `--text`. At 12px,
+   `--warn`-weight hues sit under the 4.5:1 AA bar as glyphs but clear the
+   3:1 non-text bar comfortably as a border. */
+.landing-page .landing-surface-rate {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 7px;
+  padding: 7px 10px;
+  border-radius: var(--r-full);
+  border: 1.5px solid color-mix(in oklch, var(--tone) 55%, transparent);
+  background: color-mix(in oklch, var(--tone) 9%, var(--bg));
+  font-size: 0.78rem;
+  font-weight: 500;
+  color: var(--text);
+}
+.landing-page .landing-surface-ratekey {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.6rem;
+  padding: 1px 5px;
+  border-radius: var(--r-xs);
+  background: color-mix(in oklch, var(--tone) 18%, transparent);
+  color: var(--text-dim);
+}
+
+/* ── Tutor / room conversation ──────────────────────────────────────────── */
+.landing-page .landing-surface-turn {
+  display: flex;
+  align-items: flex-start;
+  gap: 9px;
+}
+.landing-page .landing-surface-turn.is-student { justify-content: flex-end; }
+
+.landing-page .landing-surface-msg {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  min-width: 0;
+}
+.landing-page .landing-surface-sender {
+  font-size: 0.68rem;
+  font-weight: 600;
+  color: var(--text-dim);
+}
+
+.landing-page .landing-surface-bubble {
+  display: inline-block;
+  padding: 9px 13px;
+  border-radius: var(--r-lg);
+  font-size: 0.82rem;
+  line-height: 1.55;
+}
+.landing-page .landing-surface-bubble.is-tutor {
+  max-width: 88%;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  font-family: var(--font-spectral), 'Spectral', Georgia, serif;
+  color: var(--text);
+}
+/* Forest, not `--accent`: #2D8F5C under white is 4.04:1, below the AA bar at
+   this size. Forest is 6.4:1. */
+.landing-page .landing-surface-bubble.is-student {
+  max-width: 80%;
+  background: var(--brand-forest);
+  color: #fff;
+}
+
+.landing-page .landing-surface-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  flex-shrink: 0;
+  border-radius: var(--r-full);
+  background: var(--ink-100);
+  border: 1px solid var(--border);
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.6rem;
+  letter-spacing: 0.02em;
+  color: var(--text-dim);
+}
+.landing-page .landing-surface-avatar.is-tutor {
+  background: var(--accent-soft);
+  border-color: var(--accent-border);
+  color: var(--brand-forest);
+}
+
+.landing-page .landing-surface-stack-avatars { display: flex; }
+.landing-page .landing-surface-stack-avatars .landing-surface-avatar {
+  margin-right: -8px;
+  box-shadow: 0 0 0 2px var(--bg-panel);
+}
+
+/* `margin-top: auto` pins the quick actions to the bottom of the tile. The
+   bento stretches every tile in a row to the tallest one, and without this the
+   Tutor tile's actions floated in the middle with dead paper under them; pinned,
+   the slack reads as an empty conversation log — which is what it is. */
+.landing-page .landing-surface-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 7px;
+  margin-top: auto;
+  padding-top: 6px;
+}
+.landing-page .landing-surface-action {
+  display: inline-flex;
+  align-items: center;
+  padding: 5px 11px;
+  border-radius: var(--r-sm);
+  border: 1px solid var(--border);
+  background: var(--bg);
+  font-size: 0.74rem;
+  color: var(--text-dim);
+}
+
+/* ── Notetaker ──────────────────────────────────────────────────────────── */
+.landing-page .landing-surface-notetitle {
+  font-family: var(--font-playfair), 'Playfair Display', Georgia, serif;
+  font-size: 1.35rem;
+  font-weight: 600;
+  letter-spacing: -0.015em;
+  line-height: 1.15;
+  color: var(--text);
+}
+.landing-page .landing-surface-prose {
+  margin: 0 0 4px;
+  font-family: var(--font-spectral), 'Spectral', Georgia, serif;
+  font-size: 0.88rem;
+  line-height: 1.7;
+  color: var(--text-dim);
+}
+.landing-page .landing-surface-linkrow {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  padding: 6px 10px;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--r-sm);
+}
+
+/* ── Study Rooms ────────────────────────────────────────────────────────── */
+.landing-page .landing-surface-roomname {
+  font-family: var(--font-playfair), 'Playfair Display', Georgia, serif;
+  font-size: 1.12rem;
+  font-weight: 600;
+  letter-spacing: -0.015em;
+  color: var(--text);
+}
+
+/* ── Gradebook ──────────────────────────────────────────────────────────── */
+.landing-page .landing-surface-grade { display: flex; align-items: center; gap: 12px; }
+/* Display-size ⇒ WCAG "large text" (3:1), which is what lets the letter carry
+   `--grade-a` (4.56:1 on this paper) as a glyph. The per-row letters below
+   cannot, and don't. */
+.landing-page .landing-surface-letter {
+  font-family: var(--font-playfair), 'Playfair Display', Georgia, serif;
+  font-size: 3.1rem;
+  font-weight: 600;
+  line-height: 0.9;
+  letter-spacing: -0.03em;
+  color: var(--grade-a);
+}
+.landing-page .landing-surface-pct {
+  font-family: var(--font-playfair), 'Playfair Display', Georgia, serif;
+  font-size: 1.3rem;
+  font-weight: 600;
+  color: var(--text);
+}
+
+.landing-page .landing-surface-gradebookrow {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 7px 2px;
+  border-top: 1px solid var(--border);
+}
+.landing-page .landing-surface-assignment {
+  font-family: var(--font-spectral), 'Spectral', Georgia, serif;
+  font-size: 0.9rem;
+  font-weight: 500;
+  color: var(--text);
+}
+.landing-page .landing-surface-points {
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.82rem;
+  font-weight: 600;
+  color: var(--text);
+  white-space: nowrap;
+}
+.landing-page .landing-surface-slash { font-weight: 400; color: var(--text-muted); }
+
+/* Grade band on the border + dot, letter in `--text`: `--grade-b` (#a88020) is
+   3.39:1 on this paper — fine as a 3:1 non-text mark, not as a glyph. */
+.landing-page .landing-surface-gradepill {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 44px;
+  justify-content: center;
+  padding: 3px 9px;
+  border-radius: var(--r-full);
+  border: 1px solid var(--grade);
+  background: color-mix(in oklch, var(--grade) 8%, var(--bg));
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.72rem;
+  font-weight: 600;
+  color: var(--text);
+}
+.landing-page .landing-surface-gradepill::before {
+  content: '';
+  width: 6px;
+  height: 6px;
+  border-radius: var(--r-full);
+  background: var(--grade);
+}
diff --git a/frontend/src/components/marketing/FeatureBand.test.tsx b/frontend/src/components/marketing/FeatureBand.test.tsx
new file mode 100644
index 00000000..828009ae
--- /dev/null
+++ b/frontend/src/components/marketing/FeatureBand.test.tsx
@@ -0,0 +1,111 @@
+// @vitest-environment jsdom
+/**
+ * The band's two load-bearing behaviours (#344 step 2).
+ *
+ * 1. **Alternation.** The spec's requirement is that the product surfaces
+ *    alternate sides down the page. `featureBands.tsx` derives `surfaceSide`
+ *    from position rather than writing it down per band, so this asserts the
+ *    invariant (adjacent bands differ) instead of restating three literals —
+ *    inserting a band can't silently put two surfaces in the same gutter.
+ * 2. **DOM order is always copy-first.** The flip is a `grid-column` swap in
+ *    CSS, never a source reorder, because the source order is what the phone
+ *    layout and a screen reader get. A regression to `flex-direction:
+ *    row-reverse` on the markup would pass a visual check and fail this.
+ */
+import React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup, within } from '@testing-library/react';
+
+import FeatureBand from './FeatureBand';
+import { FEATURE_BANDS } from './featureBands';
+
+afterEach(cleanup);
+
+/** Every band, mounted the way `page.tsx` mounts them. */
+function renderAll() {
+  return render(
+    <div className="landing-page">
+      {FEATURE_BANDS.map((b) => (
+        <FeatureBand key={b.id} {...b} />
+      ))}
+    </div>,
+  );
+}
+
+describe('featureBands', () => {
+  it('carries the three bands of the material-in → practice → retention arc', () => {
+    expect(FEATURE_BANDS.map((b) => b.id)).toEqual(['upload', 'quiz', 'review']);
+  });
+
+  it('alternates the surface side between consecutive bands', () => {
+    for (let i = 1; i < FEATURE_BANDS.length; i++) {
+      expect(
+        FEATURE_BANDS[i].surfaceSide,
+        `band ${FEATURE_BANDS[i].id} must not share a side with ${FEATURE_BANDS[i - 1].id}`,
+      ).not.toBe(FEATURE_BANDS[i - 1].surfaceSide);
+    }
+  });
+
+  it('opens on the left so the first surface sits under the graph, not beside the CTA', () => {
+    expect(FEATURE_BANDS[0].surfaceSide).toBe('left');
+  });
+
+  it('addresses the student and avoids the banned marketing vocabulary', () => {
+    // The brand guide bans these outright; "AI-powered" is banned as a badge.
+    const banned = /leverage|empower|seamless|revolutionary|cutting-edge|synergy|ai-powered/i;
+    for (const b of FEATURE_BANDS) {
+      const copy = `${b.eyebrow} ${b.headline} ${b.body}`;
+      expect(copy, b.id).not.toMatch(banned);
+    }
+  });
+});
+
+describe('FeatureBand', () => {
+  it('renders each band with its eyebrow, headline, body and surface', () => {
+    renderAll();
+    for (const b of FEATURE_BANDS) {
+      const band = screen.getByTestId(`landing-band-${b.id}`);
+      expect(within(band).getByTestId(`landing-band-${b.id}-eyebrow`)).toHaveTextContent(b.eyebrow);
+      expect(within(band).getByRole('heading', { level: 2 })).toHaveTextContent(b.headline);
+      expect(band).toHaveTextContent(b.body);
+      // The surface is a real recreation, not an empty slot.
+      expect(band.querySelector('.landing-surface')).toBeTruthy();
+    }
+  });
+
+  it('exposes the resolved side on the section, and matches it to the layout class', () => {
+    renderAll();
+    for (const b of FEATURE_BANDS) {
+      const band = screen.getByTestId(`landing-band-${b.id}`);
+      expect(band).toHaveAttribute('data-surface-side', b.surfaceSide);
+      expect(band.querySelector(`.landing-band--surface-${b.surfaceSide}`)).toBeTruthy();
+    }
+  });
+
+  it('keeps the copy before the surface in the DOM regardless of which side it renders on', () => {
+    renderAll();
+    for (const b of FEATURE_BANDS) {
+      const grid = screen.getByTestId(`landing-band-${b.id}`).querySelector('.landing-band-grid')!;
+      const kids = Array.from(grid.children);
+      expect(kids[0].className, b.id).toContain('landing-band-copy');
+      expect(kids[1].className, b.id).toContain('landing-band-surface');
+    }
+  });
+
+  it('names each band for assistive tech via its own headline', () => {
+    renderAll();
+    for (const b of FEATURE_BANDS) {
+      const band = screen.getByTestId(`landing-band-${b.id}`);
+      expect(band).toHaveAttribute('aria-labelledby', `band-${b.id}-headline`);
+      expect(band.querySelector(`#band-${b.id}-headline`)).toBeTruthy();
+    }
+  });
+
+  it('ships no interactive controls — the surfaces are pictures, not widgets', () => {
+    // The spec's "no per-tile buttons". It is also what makes reduced-motion /
+    // IS_TEST_MODE parking a non-issue here: there is no frame but the
+    // complete one.
+    const { container } = renderAll();
+    expect(container.querySelectorAll('button, input, textarea, a')).toHaveLength(0);
+  });
+});
diff --git a/frontend/src/components/marketing/FeatureBand.tsx b/frontend/src/components/marketing/FeatureBand.tsx
new file mode 100644
index 00000000..852d46bf
--- /dev/null
+++ b/frontend/src/components/marketing/FeatureBand.tsx
@@ -0,0 +1,93 @@
+/**
+ * A full-width feature band: one recreated product surface on one side, the
+ * claim on the other (#344 step 2, spec sections 2/3/5).
+ *
+ * Purely presentational. It owns three things and nothing else:
+ *
+ *  1. **The alternation.** `surfaceSide` decides which column the surface lands
+ *     in at ≥ 900px. The DOM order is always copy-then-surface — a screen
+ *     reader and every phone get the claim before the illustration of it, and
+ *     the desktop flip is a `grid-column` swap, not a source reorder.
+ *  2. **Atmospheric continuity.** The hero, the graph section and the CTA all
+ *     carry mesh blobs; three bands and a bento between the last two would
+ *     otherwise be a flat hole in the middle of the page, and the cut in and out
+ *     of it reads as a seam. One low-opacity blob per band, parked behind the
+ *     COPY column (never behind the surface, which has to stay crisp).
+ *  3. **The type ramp.** Mono eyebrow → Playfair headline → DM Sans body, the
+ *     same three-step the graph section above it uses.
+ *
+ * No motion of its own. The entrance is the page's existing `.landing-fade-up`
+ * (an IntersectionObserver in `(public)/page.tsx` that strips the opacity class
+ * on first intersect) — which means with JS off, or an observer that never
+ * fires, the band renders complete rather than invisible, and the global
+ * `prefers-reduced-motion` reset in globals.css collapses the transition.
+ */
+import type { ReactNode } from 'react';
+
+/** Which column the product surface occupies on a wide viewport. */
+export type BandSide = 'left' | 'right';
+
+export interface FeatureBandProps {
+  /** Anchor id + testid suffix, e.g. `upload`. */
+  id: string;
+  /** Mono micro-label. Title Case; rendered uppercase by CSS. */
+  eyebrow: string;
+  /** The claim. Playfair, one or two lines. */
+  headline: string;
+  /** One sentence under it. Addresses the student as "you". */
+  body: string;
+  /** The recreated product surface. */
+  surface: ReactNode;
+  surfaceSide: BandSide;
+}
+
+export default function FeatureBand({
+  id,
+  eyebrow,
+  headline,
+  body,
+  surface,
+  surfaceSide,
+}: FeatureBandProps) {
+  const blobSide = surfaceSide === 'left' ? { right: '-12%' } : { left: '-12%' };
+
+  return (
+    <section
+      id={`band-${id}`}
+      data-testid={`landing-band-${id}`}
+      data-surface-side={surfaceSide}
+      aria-labelledby={`band-${id}-headline`}
+      className="landing-section landing-band relative z-10"
+    >
+      <div aria-hidden className="absolute inset-0 pointer-events-none z-0">
+        <div
+          className={`sapling-mesh-blob sapling-mesh-blob--${surfaceSide === 'left' ? '2' : '3'}`}
+          style={{
+            top: '8%',
+            bottom: 'auto',
+            width: '30vw',
+            height: '30vw',
+            opacity: 0.16,
+            ...blobSide,
+          }}
+        />
+      </div>
+
+      <div
+        className={`landing-band-grid landing-band--surface-${surfaceSide} relative z-[1] max-w-7xl mx-auto px-6 lg:px-12 landing-fade-up`}
+      >
+        <div className="landing-band-copy">
+          <span className="landing-eyebrow" data-testid={`landing-band-${id}-eyebrow`}>
+            {eyebrow}
+          </span>
+          <h2 id={`band-${id}-headline`} className="landing-band-headline">
+            {headline}
+          </h2>
+          <p className="landing-band-body">{body}</p>
+        </div>
+
+        <div className="landing-band-surface">{surface}</div>
+      </div>
+    </section>
+  );
+}
diff --git a/frontend/src/components/marketing/SurfaceBento.test.tsx b/frontend/src/components/marketing/SurfaceBento.test.tsx
new file mode 100644
index 00000000..b99156de
--- /dev/null
+++ b/frontend/src/components/marketing/SurfaceBento.test.tsx
@@ -0,0 +1,115 @@
+// @vitest-environment jsdom
+/**
+ * The bento's contract (#344 step 2).
+ *
+ * The brand guide's hard anti-pattern is a landing grid of "bubble panel: icon
+ * + heading + body". The defence is structural, not stylistic: every tile must
+ * mount a real recreated product surface. So these tests assert on the four
+ * surfaces being present and on what they contain — a tutor exchange, a note
+ * with linked concepts, a room with messages, a gradebook row with an actual
+ * grade — rather than on four boxes existing.
+ */
+import React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup, within } from '@testing-library/react';
+
+import SurfaceBento from './SurfaceBento';
+import { TIER_COLOR } from './graph/courseGraphs';
+
+afterEach(cleanup);
+
+function renderBento() {
+  return render(
+    <div className="landing-page">
+      <SurfaceBento />
+    </div>,
+  );
+}
+
+/** The four shipped screens the spec names, in the order they are laid out. */
+const TILES = ['tutor', 'notes', 'rooms', 'gradebook'] as const;
+
+describe('SurfaceBento', () => {
+  it('renders all four product surfaces', () => {
+    renderBento();
+    for (const t of TILES) {
+      expect(screen.getByTestId(`landing-surface-${t}`), t).toBeInTheDocument();
+    }
+  });
+
+  it('gives each tile its own span class so the grid stays asymmetric', () => {
+    const { container } = renderBento();
+    for (const t of TILES) {
+      expect(container.querySelector(`.landing-bento-tile--${t}`), t).toBeTruthy();
+    }
+  });
+
+  it('labels every surface with the approved product vocabulary, in Title Case', () => {
+    renderBento();
+    const titles = Array.from(document.querySelectorAll('.landing-surface-title')).map(
+      (el) => el.textContent,
+    );
+    // "Tutor", never "Chat Tutor"; "Notetaker", never "Notes"/"AI Notes".
+    expect(titles).toEqual(['Tutor', 'Notetaker', 'Study Rooms', 'Gradebook']);
+  });
+
+  it('shows a real tutor exchange, not a description of one', () => {
+    renderBento();
+    const tile = screen.getByTestId('landing-surface-tutor');
+    // A back-and-forth, not a single canned answer: the student asks, the
+    // tutor hands back a matrix to try, the student works it out.
+    expect(tile.querySelectorAll('.landing-surface-bubble').length).toBeGreaterThanOrEqual(4);
+    expect(tile.querySelectorAll('.landing-surface-bubble.is-student').length).toBeGreaterThan(1);
+    expect(tile.querySelectorAll('.landing-surface-bubble.is-tutor').length).toBeGreaterThan(1);
+  });
+
+  it('shows a real note with concepts linked to the graph', () => {
+    renderBento();
+    const tile = screen.getByTestId('landing-surface-notes');
+    expect(tile.querySelector('.landing-surface-notetitle')).toBeTruthy();
+    expect(tile.querySelectorAll('.landing-surface-linkrow').length).toBeGreaterThanOrEqual(3);
+  });
+
+  it('shows a real room with an invite code and messages from more than one person', () => {
+    renderBento();
+    const tile = screen.getByTestId('landing-surface-rooms');
+    expect(within(tile).getByText('MA242-7QK')).toBeInTheDocument();
+    expect(tile.querySelectorAll('.landing-surface-bubble').length).toBeGreaterThanOrEqual(3);
+    // At least one incoming turn carries a sender name — the shipped panel's
+    // shape, and the thing that makes it read as a room rather than a chat.
+    expect(tile.querySelectorAll('.landing-surface-sender').length).toBeGreaterThan(0);
+  });
+
+  it('shows real gradebook rows carrying actual grades', () => {
+    renderBento();
+    const tile = screen.getByTestId('landing-surface-gradebook');
+    const rows = tile.querySelectorAll('.landing-surface-gradebookrow');
+    expect(rows.length).toBeGreaterThanOrEqual(3);
+    // Points earned / possible, which is what makes it a gradebook.
+    expect(tile).toHaveTextContent('18');
+    expect(tile).toHaveTextContent('/ 20');
+    expect(within(tile).getByText('A−')).toBeInTheDocument();
+  });
+
+  /**
+   * Colour communicates STATE. Every mastery mark on the page must come from
+   * `TIER_COLOR` — the same map the knowledge-graph section paints its nodes
+   * with — so the landing never advertises a palette the product doesn't use.
+   * A raw hex here (the bug `courseGraphs.ts` already had once) fails this.
+   */
+  it('paints every status mark with a canonical --state-* token', () => {
+    renderBento();
+    const allowed = new Set(Object.values(TIER_COLOR));
+    const dots = Array.from(document.querySelectorAll('.landing-surface-dot'));
+    expect(dots.length).toBeGreaterThan(0);
+    for (const d of dots) {
+      const bg = (d as HTMLElement).style.background;
+      expect(allowed.has(bg), `unexpected status colour: ${bg}`).toBe(true);
+    }
+  });
+
+  it('ships no icon-over-heading tiles: no tile has a bare interactive control', () => {
+    const { container } = renderBento();
+    expect(container.querySelectorAll('button, input, textarea')).toHaveLength(0);
+  });
+});
diff --git a/frontend/src/components/marketing/SurfaceBento.tsx b/frontend/src/components/marketing/SurfaceBento.tsx
new file mode 100644
index 00000000..063cfb52
--- /dev/null
+++ b/frontend/src/components/marketing/SurfaceBento.tsx
@@ -0,0 +1,72 @@
+/**
+ * The four-tile bento of built product surfaces (#344 step 2, spec section 4).
+ *
+ * Tutor, Notetaker, Study Rooms, Gradebook — the four screens the old
+ * six-row feature catalog never mentioned, which is the spec's actual
+ * diagnosis of "feels generic": the page undersold the product more than it
+ * under-designed it.
+ *
+ * Every tile is a RECREATED SURFACE, never an icon over a heading over a
+ * sentence. There is no per-tile copy at all, deliberately: a caption under a
+ * picture of the Gradebook explaining that it is the Gradebook is the bubble-
+ * panel pattern wearing a screenshot. The tiles carry the product's own chrome
+ * label and let the surface argue.
+ *
+ * Sizes are asymmetric on purpose (7/5 then 5/7 of a 12-column grid, the wide
+ * tile swapping sides between rows) so the grid reads as a composition rather
+ * than as four equal boxes — and the two conversation-shaped surfaces (Tutor,
+ * Study Rooms) sit on opposite diagonals from the two document-shaped ones
+ * (Notetaker, Gradebook).
+ *
+ * Between two bands and immediately before the closing band, so it re-energises
+ * the middle of the page without being asked to close it: a grid's last tile is
+ * a weak place to ask for a signup.
+ */
+import GradebookSurface from './surfaces/GradebookSurface';
+import NotesSurface from './surfaces/NotesSurface';
+import RoomsSurface from './surfaces/RoomsSurface';
+import TutorSurface from './surfaces/TutorSurface';
+
+const TILES = [
+  { key: 'tutor', node: <TutorSurface /> },
+  { key: 'notes', node: <NotesSurface /> },
+  { key: 'rooms', node: <RoomsSurface /> },
+  { key: 'gradebook', node: <GradebookSurface /> },
+] as const;
+
+export default function SurfaceBento() {
+  return (
+    <section
+      id="surfaces"
+      data-testid="landing-bento"
+      aria-labelledby="bento-headline"
+      className="landing-section landing-bento relative z-10"
+    >
+      <div aria-hidden className="absolute inset-0 pointer-events-none z-0">
+        <div
+          className="sapling-mesh-blob sapling-mesh-blob--3"
+          style={{ top: '-6%', bottom: 'auto', left: '32%', width: '36vw', height: '36vw', opacity: 0.14 }}
+        />
+      </div>
+
+      <div className="relative z-[1] max-w-7xl mx-auto px-6 lg:px-12">
+        <div className="landing-bento-head landing-fade-up">
+          <span className="landing-eyebrow" data-testid="landing-bento-eyebrow">
+            Inside Sapling
+          </span>
+          <h2 id="bento-headline" className="landing-band-headline">
+            Everywhere else your work happens.
+          </h2>
+        </div>
+
+        <div className="landing-bento-grid landing-fade-up">
+          {TILES.map((t) => (
+            <div key={t.key} className={`landing-bento-tile landing-bento-tile--${t.key}`}>
+              {t.node}
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
diff --git a/frontend/src/components/marketing/featureBands.tsx b/frontend/src/components/marketing/featureBands.tsx
new file mode 100644
index 00000000..3236ea4a
--- /dev/null
+++ b/frontend/src/components/marketing/featureBands.tsx
@@ -0,0 +1,55 @@
+/**
+ * The three feature bands' content (#344 step 2).
+ *
+ * Lives here rather than in `(public)/page.tsx` — that file is already ~860
+ * lines and owns the hero's canvas, three RAF loops and two modals; three
+ * paragraphs of marketing copy do not belong in it. `page.tsx` mounts these by
+ * index.
+ *
+ * The three bands are ONE arc — material in → practice → retention — not three
+ * disconnected pitches, and band 3 is the closing claim that runs into the CTA.
+ * Reordering them breaks the argument, so the order here is load-bearing.
+ *
+ * `surfaceSide` is DERIVED from position rather than written down per band.
+ * The spec's requirement is "surfaces alternate sides"; encoding that as an
+ * invariant means inserting or removing a band cannot silently produce two
+ * bands with their surface on the same side, and it gives the unit test
+ * something real to assert instead of three restated literals.
+ */
+import type { FeatureBandProps } from './FeatureBand';
+import QuizSurface from './surfaces/QuizSurface';
+import ReviewSurface from './surfaces/ReviewSurface';
+import UploadSurface from './surfaces/UploadSurface';
+
+const CONTENT: Array<Omit<FeatureBandProps, 'surfaceSide'>> = [
+  {
+    id: 'upload',
+    eyebrow: 'Universal Upload',
+    headline: 'Drop in syllabi, textbooks, or notes.',
+    body: 'Sapling reads them, pulls out every concept, and maps them onto your graph — you do not tag anything.',
+    surface: <UploadSurface />,
+  },
+  {
+    id: 'quiz',
+    eyebrow: 'Adaptive Quizzes',
+    headline: 'Questions that re-tune to your level, in real time.',
+    body: 'They press where you are strong and meet you where you struggle, so the next question is always the one worth asking.',
+    surface: <QuizSurface />,
+  },
+  {
+    id: 'review',
+    eyebrow: 'Spaced Repetition',
+    headline: 'Knows what to review, and when.',
+    body: 'Spacing your reviews is what moves a concept from short-term to long-term memory. Sapling handles the scheduling; you just show up.',
+    surface: <ReviewSurface />,
+  },
+];
+
+/**
+ * Band `i` puts its surface on the left for even `i`, the right for odd — so
+ * the eye crosses the page between bands instead of running down one gutter.
+ */
+export const FEATURE_BANDS: FeatureBandProps[] = CONTENT.map((band, i) => ({
+  ...band,
+  surfaceSide: i % 2 === 0 ? 'left' : 'right',
+}));
diff --git a/frontend/src/components/marketing/surfaces/GradebookSurface.tsx b/frontend/src/components/marketing/surfaces/GradebookSurface.tsx
new file mode 100644
index 00000000..6b3dc105
--- /dev/null
+++ b/frontend/src/components/marketing/surfaces/GradebookSurface.tsx
@@ -0,0 +1,66 @@
+/**
+ * Bento tile — the Gradebook (#344 step 2).
+ *
+ * Recreates the `/gradebook` course page: the course card's big display-font
+ * letter grade next to the percentage that `percentColor` tints, then the
+ * assignment list — a Spectral title, the `Due MM/DD/YYYY` mono line, the
+ * points-earned / points-possible pair, and the category grouping.
+ *
+ * Colour rules, which shape the markup here more than the layout does:
+ *
+ *  - The 3.4rem letter grade is display-size, so WCAG treats it as large text
+ *    (3:1) and it can carry `--grade-a` (#3a7d4e → 4.56:1) directly.
+ *  - The per-row letter cannot. `--grade-b` (#a88020) is 3.39:1 on this paper,
+ *    fine as a hairline or a dot (non-text, 3:1) and not fine as a glyph. So a
+ *    row's pill keeps `--text` lettering and carries its grade band in the
+ *    border and dot instead. The colour is still doing the state work; it is
+ *    just not doing it *as text*.
+ *
+ * The real course card also paints a coloured band in the course's own hue.
+ * Dropped here for the same reason the room avatars are neutral: identity
+ * colour next to grade colour makes the grade colour stop meaning anything.
+ */
+import { SurfaceFrame, SurfaceRule } from './Surface';
+import type { CSSProperties } from 'react';
+
+const ROWS = [
+  { title: 'Problem Set 6', due: 'Due 04/21/2026', earned: '18', possible: '20', letter: 'A', grade: 'var(--grade-a)' },
+  { title: 'Midterm 1', due: 'Due 03/09/2026', earned: '84', possible: '100', letter: 'B', grade: 'var(--grade-b)' },
+  { title: 'Quiz 4', due: 'Due 02/27/2026', earned: '9', possible: '10', letter: 'A', grade: 'var(--grade-a)' },
+];
+
+export default function GradebookSurface() {
+  return (
+    <SurfaceFrame testId="landing-surface-gradebook" title="Gradebook" meta="MA 242 · Fall 2025">
+      <span className="landing-surface-headrow">
+        <span className="landing-surface-grade">
+          <span className="landing-surface-letter">A−</span>
+          <span className="landing-surface-stack">
+            <span className="landing-surface-pct">91.4%</span>
+            <span className="landing-surface-mono">12 of 14 graded</span>
+          </span>
+        </span>
+        <span className="landing-surface-mono">Term GPA 3.62</span>
+      </span>
+
+      <SurfaceRule />
+      <span className="landing-surface-label">Assignments</span>
+
+      {ROWS.map((r) => (
+        <span key={r.title} className="landing-surface-gradebookrow">
+          <span className="landing-surface-stack">
+            <span className="landing-surface-assignment">{r.title}</span>
+            <span className="landing-surface-mono">{r.due}</span>
+          </span>
+          <span className="landing-surface-points">
+            {r.earned}
+            <span className="landing-surface-slash"> / {r.possible}</span>
+          </span>
+          <span className="landing-surface-gradepill" style={{ '--grade': r.grade } as CSSProperties}>
+            {r.letter}
+          </span>
+        </span>
+      ))}
+    </SurfaceFrame>
+  );
+}
diff --git a/frontend/src/components/marketing/surfaces/NotesSurface.tsx b/frontend/src/components/marketing/surfaces/NotesSurface.tsx
new file mode 100644
index 00000000..71443fb6
--- /dev/null
+++ b/frontend/src/components/marketing/surfaces/NotesSurface.tsx
@@ -0,0 +1,40 @@
+/**
+ * Bento tile — the Notetaker (#344 step 2).
+ *
+ * Recreates `(shell)/notetaker`: the display-font title (its placeholder is
+ * "Untitled note"), the Spectral body the editor sets at 15px/1.7, and the
+ * right rail's "Linked concepts" card — one row per concept, each an inset pill
+ * carrying an 8px mastery dot, the concept name, and the mastery word in mono
+ * uppercase. That rail is the tile's whole point: a note in Sapling is attached
+ * to the graph, which is what makes it a Notetaker and not a text box.
+ */
+import { StateDot, SurfaceFrame } from './Surface';
+import type { MasteryTier } from '../graph/courseGraphs';
+
+const LINKED: Array<{ label: string; tier: MasteryTier; word: string }> = [
+  { label: 'Eigenvalues', tier: 'struggling', word: 'Struggling' },
+  { label: 'Determinant', tier: 'unexplored', word: 'Unexplored' },
+  { label: 'Matrices', tier: 'learning', word: 'Learning' },
+];
+
+export default function NotesSurface() {
+  return (
+    <SurfaceFrame testId="landing-surface-notes" title="Notetaker" meta="MA 242 · 2h ago">
+      <span className="landing-surface-notetitle">Week 4 — eigen-everything</span>
+      <p className="landing-surface-prose">
+        λ is the scale factor; v is the direction that survives the transformation intact. So
+        det(A − λI) = 0 is really just &ldquo;find the λ that collapses the matrix&rdquo;. Ask about
+        repeated roots before the midterm.
+      </p>
+
+      <span className="landing-surface-label">Linked concepts</span>
+      {LINKED.map((c) => (
+        <span key={c.label} className="landing-surface-linkrow">
+          <StateDot tier={c.tier} />
+          <span className="landing-surface-name">{c.label}</span>
+          <span className="landing-surface-mono">{c.word}</span>
+        </span>
+      ))}
+    </SurfaceFrame>
+  );
+}
diff --git a/frontend/src/components/marketing/surfaces/QuizSurface.tsx b/frontend/src/components/marketing/surfaces/QuizSurface.tsx
new file mode 100644
index 00000000..0c81bce8
--- /dev/null
+++ b/frontend/src/components/marketing/surfaces/QuizSurface.tsx
@@ -0,0 +1,69 @@
+/**
+ * Band 2 — a live Adaptive Quizzes question (#344 step 2).
+ *
+ * Recreates `QuizPanel`'s `active` phase: the "Question {i} of {n}" micro-label
+ * on the left, the difficulty chip on the right, the question at 16px, and the
+ * `role="radiogroup"` answer grid with its `A.` mono prefix — selected option in
+ * the accent border + accent-soft fill the panel actually paints.
+ *
+ * The one thing the real panel does NOT show is *why* this question is the one
+ * you got, and that is precisely the band's claim. The footer strip states it in
+ * the surface's own register: the last streak, and the difficulty the next
+ * question moves to. Colour there is `--state-progress` — a status, not decor.
+ *
+ * Static: the options are `<div role="radio">`, not `<button>`s. The whole
+ * surface is a picture of the product, there is nothing to click.
+ */
+import { StateDot, SurfaceFrame, SurfaceRule } from './Surface';
+
+const OPTIONS = [
+  { label: 'A', text: 'The angle that A rotates v through' },
+  { label: 'B', text: 'The factor that A scales v by' },
+  { label: 'C', text: 'The determinant of A' },
+  { label: 'D', text: 'The rank of A' },
+];
+
+/** The option the student has picked but not yet submitted. */
+const PICKED = 'B';
+
+export default function QuizSurface() {
+  return (
+    <SurfaceFrame testId="landing-surface-quiz" title="Adaptive Quizzes" meta="Question 4 of 8">
+      <span className="landing-surface-headrow">
+        <span className="landing-surface-concept">
+          <StateDot tier="struggling" />
+          Eigenvalues
+        </span>
+        <span className="landing-surface-chip is-hard">Hard</span>
+      </span>
+
+      <p className="landing-surface-question">
+        If A v = λ v for some non-zero v, what does λ tell you about what A does to v?
+      </p>
+
+      <span className="landing-surface-options" role="radiogroup" aria-label="Answer options">
+        {OPTIONS.map((o) => {
+          const picked = o.label === PICKED;
+          return (
+            <span
+              key={o.label}
+              role="radio"
+              aria-checked={picked}
+              aria-label={`${o.label}. ${o.text}`}
+              className={`landing-surface-option${picked ? ' is-picked' : ''}`}
+            >
+              <span className="landing-surface-optionkey">{o.label}.</span>
+              {o.text}
+            </span>
+          );
+        })}
+      </span>
+
+      <SurfaceRule />
+      <span className="landing-surface-headrow">
+        <span className="landing-surface-footnote">3 right in a row on this concept</span>
+        <span className="landing-surface-tune">Next question ↑ harder</span>
+      </span>
+    </SurfaceFrame>
+  );
+}
diff --git a/frontend/src/components/marketing/surfaces/ReviewSurface.tsx b/frontend/src/components/marketing/surfaces/ReviewSurface.tsx
new file mode 100644
index 00000000..835625ad
--- /dev/null
+++ b/frontend/src/components/marketing/surfaces/ReviewSurface.tsx
@@ -0,0 +1,76 @@
+/**
+ * Band 3 — the Study screen's spaced review (#344 step 2).
+ *
+ * Recreates `screens/Study.tsx` in flashcards mode: the `Card {i} of {n}`
+ * counter with the topic in mono on the right, the 6px progress track, the
+ * flipped card (its `label-micro` face label over display-font text), and the
+ * rating trio — Forgot / Hard / Easy — which is the product's actual
+ * spaced-repetition verdict UI.
+ *
+ * Two deliberate divergences from the shipped screen, both required by the
+ * brand guide rather than chosen for looks:
+ *
+ *  - **No emoji.** The real rating buttons lead with 🙈 / 🤔 / ✨; "no emoji in
+ *    chrome" is a hard line, so the tone is carried by the pill tint instead.
+ *  - **The interval legend is added.** Today the app schedules server-side and
+ *    prints no interval anywhere in the frontend. The band's claim is "knows
+ *    what to review, and when", and a rating trio with no visible consequence
+ *    makes only the first half of it. The `Next review` line states what each
+ *    rating buys — honest to the behaviour, and the one element that makes this
+ *    surface unmistakably a spaced-repetition product rather than a quiz.
+ *
+ * The pill text stays `--text` and the colour lives in the tint + border: at
+ * 11–12px, `--warn` on this paper is 4.28:1, under the 4.5:1 AA bar for small
+ * text, and non-text contrast only has to clear 3:1.
+ */
+import type { CSSProperties } from 'react';
+
+import { SurfaceFrame, SurfaceRule } from './Surface';
+
+const RATINGS = [
+  { label: 'Forgot', key: '1', tone: 'var(--state-struggle)', due: '10 min' },
+  { label: 'Hard', key: '2', tone: 'var(--state-progress)', due: '1 day' },
+  { label: 'Easy', key: '3', tone: 'var(--state-mastery)', due: '4 days' },
+];
+
+/** Card 7 of 12 — the fill the real 6px progress track would show. */
+const PROGRESS_PCT = 58;
+
+export default function ReviewSurface() {
+  return (
+    <SurfaceFrame testId="landing-surface-review" title="Study" meta="Spaced review">
+      <span className="landing-surface-headrow">
+        <span className="landing-surface-sub">Card 7 of 12</span>
+        <span className="landing-surface-mono">MA 242 · Eigenvalues</span>
+      </span>
+
+      <span className="landing-surface-track" aria-hidden>
+        <span className="landing-surface-fill" style={{ width: `${PROGRESS_PCT}%` }} />
+      </span>
+
+      <span className="landing-surface-card">
+        <span className="landing-surface-label">Back</span>
+        <span className="landing-surface-cardtext">
+          det(A − λI) = 0 — the λ that makes A − λI collapse.
+        </span>
+      </span>
+
+      <span className="landing-surface-ratings">
+        {RATINGS.map((r) => (
+          <span key={r.label} className="landing-surface-rate" style={{ '--tone': r.tone } as CSSProperties}>
+            {r.label}
+            <span className="landing-surface-ratekey">{r.key}</span>
+          </span>
+        ))}
+      </span>
+
+      <SurfaceRule />
+      <span className="landing-surface-headrow">
+        <span className="landing-surface-label">Next review</span>
+        <span className="landing-surface-mono">
+          {RATINGS.map((r) => `${r.label} ${r.due}`).join('  ·  ')}
+        </span>
+      </span>
+    </SurfaceFrame>
+  );
+}
diff --git a/frontend/src/components/marketing/surfaces/RoomsSurface.tsx b/frontend/src/components/marketing/surfaces/RoomsSurface.tsx
new file mode 100644
index 00000000..d3c5eb83
--- /dev/null
+++ b/frontend/src/components/marketing/surfaces/RoomsSurface.tsx
@@ -0,0 +1,55 @@
+/**
+ * Bento tile — Study Rooms (#344 step 2).
+ *
+ * Recreates `screens/Social`: the display-font room name over the invite-code
+ * chip and the member count, then the chat log — a 32px initials avatar and an
+ * 11px sender name above each incoming bubble, and the outgoing bubble filled
+ * and right-aligned with neither.
+ *
+ * Avatars stay on the warm `--ink` ramp rather than taking per-user hues. The
+ * signed-in app tints them by name, but on this page colour is reserved for
+ * state, and four coloured discs beside three mastery dots would read as
+ * decoration competing with meaning.
+ */
+import { SurfaceFrame } from './Surface';
+
+const MEMBERS = ['PN', 'MC', 'JH', 'AL'];
+
+const MESSAGES = [
+  { from: 'Priya', initials: 'PN', text: 'anyone else stuck on Q3 of the practice set?', self: false },
+  { from: 'Marcus', initials: 'MC', text: 'the eigenvector one? multiply it out — λ falls right out', self: false },
+  { from: 'You', initials: 'AL', text: 'oh. ok that actually helps', self: true },
+];
+
+export default function RoomsSurface() {
+  return (
+    <SurfaceFrame testId="landing-surface-rooms" title="Study Rooms" meta="4 members">
+      <span className="landing-surface-headrow">
+        <span className="landing-surface-roomname">Linear Algebra — Exam 2</span>
+        <span className="landing-surface-chip is-code">MA242-7QK</span>
+      </span>
+
+      <span className="landing-surface-stack-avatars">
+        {MEMBERS.map((m) => (
+          <span key={m} aria-hidden className="landing-surface-avatar">
+            {m}
+          </span>
+        ))}
+      </span>
+
+      {MESSAGES.map((m) => (
+        <span key={m.from + m.text} className={`landing-surface-turn${m.self ? ' is-student' : ' is-tutor'}`}>
+          {m.self ? null : (
+            <span aria-hidden className="landing-surface-avatar">
+              {m.initials}
+            </span>
+          )}
+          <span className="landing-surface-msg">
+            {m.self ? null : <span className="landing-surface-sender">{m.from}</span>}
+            <span className={`landing-surface-bubble${m.self ? ' is-student' : ' is-tutor'}`}>{m.text}</span>
+          </span>
+        </span>
+      ))}
+    </SurfaceFrame>
+  );
+}
diff --git a/frontend/src/components/marketing/surfaces/Surface.tsx b/frontend/src/components/marketing/surfaces/Surface.tsx
new file mode 100644
index 00000000..e01a4818
--- /dev/null
+++ b/frontend/src/components/marketing/surfaces/Surface.tsx
@@ -0,0 +1,87 @@
+/**
+ * Shared chrome for the in-page product recreations (#344 step 2).
+ *
+ * Every surface below the hero is a RECREATION of a page Sapling actually
+ * ships — an upload queue, a quiz question, a review queue, a tutor exchange,
+ * a note, a study room, a gradebook. None of them is an "icon + heading +
+ * sentence" card, which the brand guide lists as a hard anti-pattern: a tile
+ * has to show the product, not describe it.
+ *
+ * Two rules are enforced here rather than restated in seven files:
+ *
+ *  1. **Solid warm paper, hairline borders.** No `.liquid-glass`, no
+ *     `backdrop-filter`, no frosted panel — the brand guide's other hard line.
+ *     The recipe lives in `.landing-surface*` in globals.css, inside the
+ *     `.landing-page` scope (the pre-auth page re-declares the app shell's
+ *     token NAMES with different values — `docs/frontend-rhythm-audit.md`).
+ *  2. **Colour is state.** The only colours these surfaces carry are
+ *     `--state-*` (mastery) and `--grade-*` (letter grades), reached through
+ *     `TIER_COLOR` — the same map the knowledge-graph section one viewport
+ *     above paints its nodes with, so the page speaks one colour language.
+ *     Everything else is a warm neutral off the `--ink` ramp.
+ *
+ * These are static pictures: no buttons, no inputs, no motion, nothing to
+ * click. That is deliberate (the spec's "no per-tile buttons") and it is also
+ * what makes `prefers-reduced-motion` / `IS_TEST_MODE` parking a non-issue —
+ * there is no frame to park, only the complete one.
+ */
+import type { ReactNode } from 'react';
+
+import { TIER_COLOR, type MasteryTier } from '../graph/courseGraphs';
+
+/**
+ * A mastery status mark. `aria-hidden` because the tier is always spelled out
+ * in adjacent text or is decorative repetition of it — a bare "coloured dot"
+ * announcement is noise in a screen reader.
+ */
+export function StateDot({ tier }: { tier: MasteryTier }) {
+  return (
+    <span aria-hidden className="landing-surface-dot" style={{ background: TIER_COLOR[tier] }} />
+  );
+}
+
+/** A concept chip: mastery dot + label. Used by upload, notes and quiz. */
+export function ConceptChip({ label, tier }: { label: string; tier: MasteryTier }) {
+  return (
+    <span className="landing-surface-chip">
+      <StateDot tier={tier} />
+      {label}
+    </span>
+  );
+}
+
+/** The hairline that separates a surface's sections. */
+export function SurfaceRule() {
+  return <span aria-hidden className="landing-surface-rule" />;
+}
+
+/**
+ * The window frame every recreation sits in: a titled chrome bar over a body.
+ *
+ * `title` is the product surface's own name in Title Case (the approved
+ * vocabulary — "Tutor", "Notetaker", "Study Rooms", "Gradebook",
+ * "Adaptive Quizzes", "Document Library"), rendered as a mono micro-label.
+ * `meta` is the small right-hand status the real screen carries in the same
+ * spot (a count, a term, an invite code).
+ */
+export function SurfaceFrame({
+  testId,
+  title,
+  meta,
+  children,
+}: {
+  testId: string;
+  title: string;
+  meta?: ReactNode;
+  children: ReactNode;
+}) {
+  return (
+    <div className="landing-surface" data-testid={testId}>
+      <div className="landing-surface-chrome">
+        <span className="landing-surface-title">{title}</span>
+        {meta === undefined ? null : <span className="landing-surface-meta">{meta}</span>}
+      </div>
+      <div className="landing-surface-body">{children}</div>
+    </div>
+  );
+}
diff --git a/frontend/src/components/marketing/surfaces/TutorSurface.tsx b/frontend/src/components/marketing/surfaces/TutorSurface.tsx
new file mode 100644
index 00000000..806df4b4
--- /dev/null
+++ b/frontend/src/components/marketing/surfaces/TutorSurface.tsx
@@ -0,0 +1,82 @@
+/**
+ * Bento tile — the Tutor (#344 step 2).
+ *
+ * Recreates `chat/ChatPanel`: the assistant turn is a 32px accent-soft avatar
+ * with a sparkle next to a Spectral-set bubble on paper with a hairline; the
+ * student turn is a filled bubble on the right in DM Sans, no avatar. Neither
+ * carries a role label — the alignment and the avatar do that work, exactly as
+ * the shipped panel does. Under the log sit the three quick actions the panel
+ * offers above its composer: Hint, I'm confused, Skip.
+ *
+ * The fill is `--brand-forest`, not the panel's `--accent`: `--accent`
+ * (#2D8F5C) under white is 4.04:1, which is under the 4.5:1 AA bar at the
+ * ~13px this tile sets its bubbles at. Forest is 6.4:1.
+ *
+ * The exchange itself is a real one — a student stuck on why an eigenvalue can
+ * be negative, and a Socratic reply that hands back a matrix to try rather than
+ * the answer. That is the product's actual tutoring posture; a generic
+ * "How can I help you today?" would have been the wrong picture.
+ */
+import { SurfaceFrame } from './Surface';
+
+/** The panel's assistant avatar: a four-point sparkle in the accent tint. */
+function TutorMark() {
+  return (
+    <span aria-hidden className="landing-surface-avatar is-tutor">
+      <svg viewBox="0 0 16 16" width="13" height="13" aria-hidden>
+        <path
+          d="M8 0.9c.55 3.35 1.8 4.6 5.15 5.15C9.8 6.6 8.55 7.85 8 11.2 7.45 7.85 6.2 6.6 2.85 6.05 6.2 5.5 7.45 4.25 8 .9z"
+          fill="currentColor"
+        />
+        <path
+          d="M12.6 10.1c.28 1.5.82 2.05 2.3 2.32-1.48.27-2.02.82-2.3 2.32-.28-1.5-.82-2.05-2.3-2.32 1.48-.27 2.02-.82 2.3-2.32z"
+          fill="currentColor"
+          opacity="0.7"
+        />
+      </svg>
+    </span>
+  );
+}
+
+const ACTIONS = ['Hint', "I'm confused", 'Skip'];
+
+export default function TutorSurface() {
+  return (
+    <SurfaceFrame testId="landing-surface-tutor" title="Tutor" meta="Socratic · Eigenvalues">
+      <span className="landing-surface-turn is-student">
+        <span className="landing-surface-bubble is-student">
+          I don&apos;t get why an eigenvalue is allowed to be negative.
+        </span>
+      </span>
+
+      <span className="landing-surface-turn is-tutor">
+        <TutorMark />
+        <span className="landing-surface-bubble is-tutor">
+          A negative λ just means A flips v end-for-end while it scales it. Try A = [[−2, 0], [0, 1]]
+          on v = (1, 0) — what comes back out, and which way is it pointing?
+        </span>
+      </span>
+
+      <span className="landing-surface-turn is-student">
+        <span className="landing-surface-bubble is-student">
+          it points backwards. so λ = −2 flips it and doubles it?
+        </span>
+      </span>
+
+      <span className="landing-surface-turn is-tutor">
+        <TutorMark />
+        <span className="landing-surface-bubble is-tutor">
+          That is exactly it. Now try the other one — what does v = (0, 1) do?
+        </span>
+      </span>
+
+      <span className="landing-surface-actions">
+        {ACTIONS.map((a) => (
+          <span key={a} className="landing-surface-action">
+            {a}
+          </span>
+        ))}
+      </span>
+    </SurfaceFrame>
+  );
+}
diff --git a/frontend/src/components/marketing/surfaces/UploadSurface.tsx b/frontend/src/components/marketing/surfaces/UploadSurface.tsx
new file mode 100644
index 00000000..2609b6ae
--- /dev/null
+++ b/frontend/src/components/marketing/surfaces/UploadSurface.tsx
@@ -0,0 +1,84 @@
+/**
+ * Band 1 — the Document Library ingest queue (#344 step 2).
+ *
+ * Recreates `DocumentUploadModal` at rest, mid-batch: the file rows with their
+ * `28×36` doc tile, `{size} · {EXT}` meta line and status chip (`queued` /
+ * `processing…` / `done` — the modal's own wording), then the extraction
+ * result the modal prints underneath a finished row: a summary line plus the
+ * concept chips that land on the graph.
+ *
+ * The concept chips carry mastery dots from `TIER_COLOR`, which is the whole
+ * argument of the band: an upload is not a file in a folder, it is nodes on
+ * your graph. Same tokens as the knowledge-graph section one viewport up.
+ */
+import { ConceptChip, StateDot, SurfaceFrame, SurfaceRule } from './Surface';
+import type { MasteryTier } from '../graph/courseGraphs';
+
+/** The modal's doc tile — a page glyph, drawn inline (no icon dependency). */
+function DocGlyph() {
+  return (
+    <span aria-hidden className="landing-surface-doc">
+      <svg viewBox="0 0 16 20" width="13" height="16" fill="none" aria-hidden>
+        <path
+          d="M2.5 1.5h7.2L14 5.8v12.7H2.5z"
+          stroke="currentColor"
+          strokeWidth="1.3"
+          strokeLinejoin="round"
+        />
+        <path d="M9.5 1.7v4.3H14" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" />
+        <path d="M5 10h6M5 13h6M5 16h3.5" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" />
+      </svg>
+    </span>
+  );
+}
+
+type UploadStatus = 'done' | 'processing' | 'queued';
+
+const FILES: Array<{ name: string; meta: string; status: UploadStatus; label: string }> = [
+  { name: 'MA242_syllabus.pdf', meta: '0.4 MB · PDF', status: 'done', label: 'done' },
+  { name: 'linear_algebra_ch3.pdf', meta: '2.8 MB · PDF', status: 'processing', label: 'processing…' },
+  { name: 'lecture_wk4.pptx', meta: '6.1 MB · PPTX', status: 'queued', label: 'queued' },
+];
+
+const CONCEPTS: Array<{ label: string; tier: MasteryTier }> = [
+  { label: 'Vector Spaces', tier: 'mastered' },
+  { label: 'Matrices', tier: 'learning' },
+  { label: 'Eigenvalues', tier: 'struggling' },
+  { label: 'Determinant', tier: 'unexplored' },
+];
+
+export default function UploadSurface() {
+  return (
+    <SurfaceFrame testId="landing-surface-upload" title="Document Library" meta="3 files queued">
+      {FILES.map((f) => (
+        <div key={f.name} className="landing-surface-row">
+          <DocGlyph />
+          <span className="landing-surface-stack">
+            <span className="landing-surface-name">{f.name}</span>
+            <span className="landing-surface-sub">{f.meta}</span>
+          </span>
+          <span className={`landing-surface-status is-${f.status}`}>{f.label}</span>
+        </div>
+      ))}
+
+      {/* The extraction readout the modal prints under a finished row. */}
+      <SurfaceRule />
+      <span className="landing-surface-label">Concepts extracted</span>
+      <p className="landing-surface-note">
+        Syllabus read: 19 concepts mapped onto MA 242, 4 of them new.
+      </p>
+      <span className="landing-surface-chiprow">
+        {CONCEPTS.map((c) => (
+          <ConceptChip key={c.label} label={c.label} tier={c.tier} />
+        ))}
+        <span className="landing-surface-chip is-count">+15</span>
+      </span>
+
+      {/* The graph is where they land — say so in the surface's own voice. */}
+      <span className="landing-surface-footnote">
+        <StateDot tier="mastered" />
+        Linked to your MA 242 graph
+      </span>
+    </SurfaceFrame>
+  );
+}

From 7e4ea2484ee012d404ce9f200f62f69c476541d0 Mon Sep 17 00:00:00 2001
From: AndresL230 <190146319+AndresL230@users.noreply.github.com>
Date: Sat, 1 Aug 2026 23:55:37 -0700
Subject: [PATCH 20/20] feat(landing): give the knowledge graph product chrome,
 a dial and a rail (#344)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The graph section was the least convincing thing on a page whose bands and
bento each recreate a whole product screen. It was six flat circles and six
words, floating naked on the page background, left-aligned in a 1184px
container with the right 40% of the field empty, and its entire hover payoff
was one line of body text swapping under the drawing.

It is now one surface, full container width, split the way the app's own Tree
screen is split.

- CHROME. `KNOWLEDGE GRAPH` in the bento's mono micro-label, and the selected
  course's real numbers on the right — `MA 242 · 19 concepts · 50% mastery`,
  all read off the fixture.
- THE NODES ARE DIALS. A tier-tinted disc at the full node radius, a neutral
  track ring, the mastery arc swept clockwise from 12 o'clock, and a solid
  core. Every dimension is measured INWARD from `nodeRadius`, so the drawn
  footprint is byte-identical to the flat disc it replaces: `fitViewBox`,
  `labelBaselineY` and the phone's 5.40-unit label clearance are untouched,
  and a node group's first `<circle>` is still the tier-painted disc the E2E
  legibility gate measures.
- A LEGEND, which is a comprehension fix rather than decoration: four
  `--state-*` hues were carrying the whole meaning of the picture and nothing
  on the page said what any of them meant. It carries counts, so it reads as a
  readout, and it names the tiers in the app's own words.
- AN INSPECTOR RAIL replaces the bare hover line: name, tier as a labelled
  chip, blurb, mastery meter, and the neighbours listed with their own scores,
  with the hovered node's edges lit in the canvas beside it. Never empty — at
  rest it shows the course.
- AMBIENT DRIFT, ~3 units on a 13–22s per-node cycle with a negative delay so
  nothing starts in phase. A CSS animation, not a rAF loop: it stays out of
  the assembly's frame budget (which the suite counts to prove the helix
  neither fires early nor replays), and rides the same `parked` switch, so
  reduced-motion visitors and the E2E lane get nodes exactly on their
  laid-out points. Off below the mobile breakpoint, where the frame pad is 2
  units and the worst label clearance 5.40.

The fixtures gain a numeric `mastery` per node and a `conceptCount` per
course, held to the product's own cutoffs by a port of
`backend/config.py::get_mastery_tier`, so a ring can never say 90% while the
paint says "struggling" and the chrome's percentage can never contradict the
root's own dial.

The assembly, its viewport gate, the negative bottom rootMargin and the
never-blank derivation are untouched. The phone gate's three bars improve
(12.68 / 23.78 / 182.3 against 11 / 20 / 170) because the canvas is
full-bleed horizontally — deliberately, and the CSS says why.

576 tests green (+16), tsc clean, eslint clean on src/ and e2e/.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/frontend-testids.md                      |  27 +-
 frontend/src/app/(public)/page.tsx            |  10 +-
 frontend/src/app/globals.css                  | 244 +++++++++
 .../graph/KnowledgeGraphDemo.test.tsx         | 326 ++++++++++-
 .../marketing/graph/KnowledgeGraphDemo.tsx    | 518 +++++++++++++++---
 .../marketing/graph/courseGraphs.test.ts      | 120 +++-
 .../marketing/graph/courseGraphs.ts           | 132 ++++-
 .../components/marketing/graph/layout.test.ts |   6 +-
 8 files changed, 1277 insertions(+), 106 deletions(-)

diff --git a/docs/frontend-testids.md b/docs/frontend-testids.md
index 2d85623b..b661bd8d 100644
--- a/docs/frontend-testids.md
+++ b/docs/frontend-testids.md
@@ -80,7 +80,7 @@ renders the element.
 | Calendar | `calendar` | `frontend/src/components/screens/Calendar.tsx` (the `/calendar` screen — today just the #185 load-failure banner + retry) |
 | Gradebook | `gradebook` | `frontend/src/components/screens/Gradebook/Landing.tsx` + `Course.tsx` (the `/gradebook` screens), `frontend/src/components/Gradebook/TranscriptModal.tsx` (the transcript modal), `frontend/src/components/Gradebook/CourseCard.tsx` (the term-aware card links), `frontend/src/components/Gradebook/AssignmentList.tsx` + `AssignmentModal.tsx` (the add-assignment flow the #468 mutation leg drives) — added with the #139 term-switcher/transcript journey |
 | Admin analytics | `admin-analytics` | `frontend/src/components/screens/AdminAnalytics.tsx` (the `/admin/analytics` dashboard — range presets/inputs, cost group-by toggle, per-panel retry) — added with the #121 data layer |
-| Landing knowledge graph demo | `landing-graph` | `frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx` (the pre-auth landing page's interactive course-picker + laid-out concept graph, #344) |
+| Landing knowledge graph demo | `landing-graph` | `frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx` (the pre-auth landing page's interactive course-picker + laid-out concept graph, wearing the `landing-surface` chrome with an inspector rail and mastery legend since #344 step 3) |
 | Landing feature bands | `landing-band` | `frontend/src/components/marketing/FeatureBand.tsx` (the three full-width bands below the graph; content + side-alternation in `featureBands.tsx`, #344 step 2) |
 | Landing surface bento | `landing-bento` | `frontend/src/components/marketing/SurfaceBento.tsx` (the four-tile grid of built product surfaces, #344 step 2) |
 | Landing product surfaces | `landing-surface` | `frontend/src/components/marketing/surfaces/*.tsx` (the seven in-page recreations the bands and bento mount, #344 step 2) |
@@ -332,20 +332,33 @@ Added with the upload → SSE → library journey (#387).
 
 Added with the #344 landing-page knowledge-graph demo. Ships the static,
 fully laid-out render (chips to switch course, nodes/edges for the selected
-graph), the helical assembly animation, and hover interaction (blurb reveal +
-copy fade on first engagement); click-to-expand is a later task in the same
-spec and will reuse these same testids.
+graph), the helical assembly animation, and hover interaction (detail-panel
+swap + copy fade on first engagement); click-to-expand is a later task in the
+same spec and will reuse these same testids.
+
+Step 3 wrapped the whole thing in the same `landing-surface` chrome the bands
+and bento use — a titled bar over a `--bg-mesh` canvas, an inspector rail and a
+mastery legend — so the ids below split into the section's own controls and the
+screen's panes.
 
 | testid | element |
 | --- | --- |
 | `landing-graph` | demo section root (`aria-label` names the selected course) |
 | `landing-graph-chip-{courseId}` | one course-picker chip, per `COURSE_GRAPHS` entry — `aria-pressed` marks the active course |
-| `landing-graph-svg` | the `<svg>` itself — its `viewBox` is the desktop or the phone `GraphView` (`graph/layout.ts`), swapped at the mobile breakpoint |
-| `landing-graph-node-{nodeId}` | one SVG node group (`<g>`) in the selected course's graph |
 | `landing-graph-copy` | the section's instructional copy block (eyebrow label + heading) — `data-engaged` flips `"true"` on the visitor's first node hover and stays that way across course switches |
 | `landing-graph-eyebrow` | the "Your knowledge, mapped" eyebrow label — deliberately *not* faded on engagement (WCAG AA at 0.7rem) |
 | `landing-graph-headline` | the "Pick a course. Watch it grow." heading — carries the engagement fade (`ENGAGED_HEADLINE_OPACITY`) |
-| `landing-graph-blurb` | the reserved-height paragraph below the graph that shows the hovered node's one-sentence blurb |
+| `landing-graph-surface` | the product-chrome frame the whole screen sits in (`landing-surface`) |
+| `landing-graph-meta` | the chrome bar's right-hand status — `{code} · {conceptCount} concepts · {n}% mastery`, all read off the selected `CourseGraph` |
+| `landing-graph-svg` | the `<svg>` itself — its `viewBox` is the desktop or the phone `GraphView` (`graph/layout.ts`), swapped at the mobile breakpoint |
+| `landing-graph-node-{nodeId}` | one SVG node group (`<g>`) in the selected course's graph. Its **first `<circle>` is the tier-painted disc at the full node radius** — the phone legibility gate measures that element, so nothing may be drawn in front of it |
+| `landing-graph-detail` | the inspector rail's frame. Never empty: with nothing hovered it shows the course (the root node) |
+| `landing-graph-detail-name` | the inspected node's name |
+| `landing-graph-detail-tier` | its mastery tier as a labelled chip (`Course` for the root, which is an anchor rather than a status) |
+| `landing-graph-detail-mastery` | its mastery as a percentage |
+| `landing-graph-blurb` | the reserved-height paragraph in the panel that shows the inspected node's one-sentence blurb |
+| `landing-graph-legend` | the mastery legend pinned to the foot of the rail |
+| `landing-graph-legend-{tier}` | one legend row — `mastered`, `learning`, `struggling` or `unexplored`, each with the tier's own count of drawn concepts |
 
 ### `landing-band` / `landing-bento` / `landing-surface`
 
diff --git a/frontend/src/app/(public)/page.tsx b/frontend/src/app/(public)/page.tsx
index 25ec46b5..dc89e83f 100644
--- a/frontend/src/app/(public)/page.tsx
+++ b/frontend/src/app/(public)/page.tsx
@@ -18,9 +18,13 @@ import { IS_TEST_MODE, random, now } from '@/lib/testMode';
 const KnowledgeGraphDemo = dynamic(
   () => import('@/components/marketing/graph/KnowledgeGraphDemo'),
   {
-    // Placeholder height matches the section's resolved height so nothing
-    // below shifts while the chunk loads.
-    loading: () => <section id="knowledge-graph" className="landing-section relative" style={{ minHeight: '80vh' }} />,
+    // Placeholder height approximates the section's resolved height so nothing
+    // below shifts while the chunk loads. MEASURED, not guessed: the section
+    // resolves to 990px at every desktop width once it wears its product
+    // chrome (#344 step 3) — the `80vh` this carried was 27–40% short of that
+    // even before, and a viewport-relative value cannot track a section whose
+    // height is set by a fixed-width inspector rail.
+    loading: () => <section id="knowledge-graph" className="landing-section relative" style={{ minHeight: '990px' }} />,
   },
 );
 
diff --git a/frontend/src/app/globals.css b/frontend/src/app/globals.css
index a107197f..0c6bc7a2 100644
--- a/frontend/src/app/globals.css
+++ b/frontend/src/app/globals.css
@@ -1002,6 +1002,250 @@ input[type="reset"]:disabled {
    all — see ENGAGED_HEADLINE_OPACITY in KnowledgeGraphDemo.tsx (#344). */
 .landing-page .landing-graph-headline { transition: opacity 600ms ease; }
 
+/* ══════════════════════════════════════════════════════════════════════════
+   KNOWLEDGE GRAPH SCREEN (#344 step 3)
+
+   The graph used to float naked on the page background — six dots and six
+   words, left-aligned in a 1184px container with the right 40% of the field
+   empty, one viewport above four bento tiles that each recreate a whole
+   product screen. It now wears the same chrome as everything else here, and it
+   uses the `.landing-surface*` recipe below rather than a parallel one: same
+   solid warm paper, same hairlines, same mono micro-labels, no glass anywhere.
+
+   Everything is scoped to `.landing-page` and ADDS classes only — no token is
+   defined or redefined (docs/frontend-rhythm-audit.md).
+   ══════════════════════════════════════════════════════════════════════════ */
+
+/* This surface's chrome carries a longer status than the bento's ("MA 242 · 19
+   concepts · 50% mastery"), which on a phone broke the two-word title across
+   two lines. Wrap the BAR instead: the title keeps its line and the status
+   drops under it. */
+.landing-page .landing-graph-chrome { flex-wrap: wrap; row-gap: 2px; }
+.landing-page .landing-graph-chrome .landing-surface-title { white-space: nowrap; }
+
+/* Canvas + inspector, split the way the app's own Tree screen is split. The
+   rail is a fixed 320px so the canvas takes the remainder — a fractional rail
+   would rescale the drawing at every viewport width, and the drawing's
+   rendered scale is what three waves of #344 arithmetic were fitted to. */
+.landing-page .landing-graph-split {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+}
+@media (min-width: 900px) {
+  .landing-page .landing-graph-split {
+    grid-template-columns: minmax(0, 1fr) 320px;
+  }
+}
+
+/* THE CANVAS IS PAINTED `--bg-mesh`, and that is a requirement, not a taste
+   call: every node label is stroked with a `--bg-mesh` halo so the edge mesh
+   breaks around its letterforms instead of running through them. On the
+   panel's own paper each halo would show as a pale rectangle behind a word.
+
+   NO HORIZONTAL PADDING, ever. The phone legibility gate
+   (e2e/landing-graph.spec.ts) measures label size, dot diameter and drawing
+   height in CSS px off the rendered `<svg>` width; at 390px the content box is
+   ~332px and every unit renders at 0.769px, so 30px of side padding would take
+   the drawing under the bar. Vertical padding costs nothing (the height
+   follows the width) and is where the breathing room goes. */
+.landing-page .landing-graph-canvas {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 0;
+  padding: 14px 0 10px;
+  background: var(--bg-mesh);
+}
+.landing-page .landing-graph-canvas > svg { display: block; }
+
+/* The rail is a PANE of this surface, not a card sitting on top of one: the
+   nested `SurfaceFrame` keeps the product's title/meta chrome strip and gives
+   up its border, radius, shadow and paper, so the two halves read as one
+   screen divided by a hairline rather than as a card inside a card. */
+.landing-page .landing-graph-rail {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  border-top: 1px solid var(--border);
+}
+.landing-page .landing-graph-rail > .landing-surface {
+  min-width: 0;
+  border: 0;
+  border-radius: 0;
+  box-shadow: none;
+  background: transparent;
+}
+@media (min-width: 900px) {
+  .landing-page .landing-graph-rail {
+    border-top: 0;
+    border-left: 1px solid var(--border);
+  }
+}
+
+.landing-page .landing-graph-detailhead {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  min-height: 1.6rem;
+}
+.landing-page .landing-graph-detailname {
+  font-family: var(--font-playfair), 'Playfair Display', Georgia, serif;
+  font-size: 1.12rem;
+  font-weight: 600;
+  letter-spacing: -0.015em;
+  line-height: 1.2;
+  color: var(--text);
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Same recipe as `.landing-surface-gradepill`: band and mark in the state
+   colour, lettering in `--text`. `--state-progress` (#c89b5e) is 2.2:1 as a
+   glyph on this paper and never has to be one. */
+.landing-page .landing-graph-tierchip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  flex-shrink: 0;
+  padding: 3px 10px;
+  border-radius: var(--r-full);
+  border: 1px solid var(--tier);
+  background: color-mix(in oklch, var(--tier) 8%, var(--bg));
+  font-family: var(--font-jetbrains), 'JetBrains Mono', monospace;
+  font-size: 0.62rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text);
+  white-space: nowrap;
+}
+.landing-page .landing-graph-tierchip::before {
+  content: '';
+  width: 6px;
+  height: 6px;
+  border-radius: var(--r-full);
+  background: var(--tier);
+}
+
+/* RESERVED HEIGHT, both of them. The blurb and the link list swap on every
+   hover and unhover; a one-line blurb replacing a two-line one would shift
+   everything under it on every pass of the mouse. Two lines is the tallest any
+   fixture blurb reaches at the narrowest column this panel renders in, and
+   three link rows is the widest link set any fixture node has — so the floor
+   is also the ceiling and the panel's height is CONSTANT across every node of
+   every course, at every width, hovered or not. */
+.landing-page .landing-graph-blurb {
+  margin: 0;
+  font-size: 0.82rem;
+  line-height: 1.55;
+  color: var(--text-dim);
+  min-height: 2.6rem;
+}
+
+.landing-page .landing-graph-links {
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+  /* Three rows at 30px plus two 5px gaps. Measured, not guessed: a node with
+     two neighbours must reserve the same box as one with three, or the
+     stacked layout (where the grid is not stretching this rail to the
+     canvas's height) shifts the page on every hover. */
+  min-height: 6.25rem;
+}
+.landing-page .landing-graph-link {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 9px;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--r-sm);
+  font-size: 0.76rem;
+  color: var(--text-dim);
+}
+.landing-page .landing-graph-linkname {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* ── Legend ──────────────────────────────────────────────────────────────
+   Not decoration: four `--state-*` hues were carrying the entire meaning of
+   this picture and nothing on the page said what any of them meant. The counts
+   make it a readout rather than a key, and the note explains the ring the
+   nodes now draw. Pinned to the foot of the rail. */
+.landing-page .landing-graph-legend {
+  margin-top: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px 15px 14px;
+  background: var(--ink-50);
+  border-top: 1px solid var(--border);
+}
+.landing-page .landing-graph-legenditems {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 6px 16px;
+}
+.landing-page .landing-graph-legenditem {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  font-size: 0.72rem;
+  color: var(--text-dim);
+  white-space: nowrap;
+}
+/* One legend entry per line once the rail is a rail, so it reads as a table of
+   counts; a wrapped row at every width instead. */
+@media (min-width: 900px) {
+  .landing-page .landing-graph-legenditems { flex-direction: column; align-items: stretch; gap: 7px; }
+  .landing-page .landing-graph-legendname { flex: 1; }
+}
+/* A hairline round every legend swatch. `--state-progress` and
+   `--state-neutral` are both under the 3:1 non-text bar on this paper; the
+   tier NAME beside each one is what actually carries the meaning (colour is
+   never the sole channel here), and the ring keeps the swatch's shape legible
+   regardless of how washed its fill is. */
+.landing-page .landing-graph-legenditem .landing-surface-dot {
+  width: 9px;
+  height: 9px;
+  box-shadow: 0 0 0 1px var(--border-strong);
+}
+.landing-page .landing-graph-legendnote { color: var(--text-muted); }
+
+/* ── Node dial + ambient drift ───────────────────────────────────────────
+   The brand guide's atmosphere is "a barely-there field of colourful orbs
+   drifting slowly in 3D — like the glow under water"; the hero does exactly
+   that and this section was frozen the instant its assembly landed.
+
+   A CSS animation rather than a rAF loop: it composites off the main thread,
+   costs zero React re-renders, is neutralised for free by the global
+   prefers-reduced-motion reset above — and, decisively, it stays out of the
+   assembly's rAF budget, which the unit suite counts frame by frame to prove
+   the helix neither fires early nor replays. The per-node direction, distance,
+   period and (negative, so nothing starts in phase) delay arrive as custom
+   properties hashed off the node id in KnowledgeGraphDemo.tsx. */
+@keyframes landing-graph-drift {
+  0%, 100% { transform: translate(0, 0); }
+  50%      { transform: translate(var(--drift-x, 0), var(--drift-y, 0)); }
+}
+
+.landing-page .landing-graph-node { cursor: pointer; }
+.landing-page .landing-graph-node.is-drifting {
+  animation: landing-graph-drift var(--drift-dur, 15s) ease-in-out var(--drift-delay, 0s) infinite;
+  will-change: transform;
+}
+/* Only the two properties HOVER owns. `stroke-opacity` is deliberately not in
+   the list: the assembly drives it every frame from `progress`, and a 220ms
+   transition on a per-frame value damps and delays the whole entry fade. */
+.landing-page .landing-graph-edge { transition: stroke 200ms ease, stroke-width 200ms ease; }
+
 /* ══════════════════════════════════════════════════════════════════════════
    FEATURE BANDS + SURFACE BENTO (#344 step 2)
 
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
index b750f8d6..3451354f 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.test.tsx
@@ -12,7 +12,15 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { render, screen, cleanup, fireEvent } from '@testing-library/react';
 
 import KnowledgeGraphDemo, { ENGAGED_HEADLINE_OPACITY } from './KnowledgeGraphDemo';
-import { COURSE_GRAPHS, TIER_COLOR } from './courseGraphs';
+import {
+  COURSE_GRAPHS,
+  TIER_COLOR,
+  TIER_LABEL,
+  TIER_ORDER,
+  conceptNodes,
+  neighbours,
+  tierCounts,
+} from './courseGraphs';
 import { DESKTOP_VIEW, MOBILE_VIEW, viewBoxAttr } from './layout';
 import { __resetReducedMotionStoreForTests } from '@/lib/usePrefersReducedMotion';
 import { __resetMediaStoresForTests } from '@/lib/useIsMobile';
@@ -650,3 +658,319 @@ describe('KnowledgeGraphDemo — node paint and label placement', () => {
     expect((label as unknown as SVGTextElement).style.paintOrder).toBe('stroke');
   });
 });
+
+/**
+ * #344 step 3 — the nodes are mastery DIALS now, not flat dots.
+ *
+ * Two things have to survive that, and both are load-bearing outside this file:
+ *
+ *  - A node group's FIRST `<circle>` stays the tier-painted disc at the full
+ *    `nodeRadius`. `e2e/landing-graph.spec.ts` reads exactly that element to
+ *    measure the phone's rendered dot diameter, and the paint tests above read
+ *    its `fill`. A ring drawn as a circle in front of it would silently hand
+ *    both of them the wrong element (and the wrong radius).
+ *  - Every dimension is measured INWARD from `nodeRadius`, so the drawn
+ *    footprint is unchanged and `fitViewBox` / `labelBaselineY` / the phone's
+ *    5.40-unit label clearance all still hold.
+ */
+describe('KnowledgeGraphDemo — the mastery dial (#344 step 3)', () => {
+  const graph = COURSE_GRAPHS[0];
+
+  function nodeGroup(id: string) {
+    return screen.getByTestId(`landing-graph-node-${id}`);
+  }
+
+  it('keeps the node’s first circle the tier disc at the full node radius', () => {
+    render(<KnowledgeGraphDemo />);
+    for (const n of graph.nodes) {
+      const disc = nodeGroup(n.id).querySelector('circle')!;
+      const expected = n.id === graph.rootId ? DESKTOP_VIEW.rootR : DESKTOP_VIEW.nodeR;
+      expect(Number(disc.getAttribute('r')), n.id).toBeCloseTo(expected, 6);
+    }
+  });
+
+  it('draws nothing outside the node radius', () => {
+    render(<KnowledgeGraphDemo />);
+    for (const n of graph.nodes) {
+      const r = n.id === graph.rootId ? DESKTOP_VIEW.rootR : DESKTOP_VIEW.nodeR;
+      for (const c of nodeGroup(n.id).querySelectorAll('circle')) {
+        const radius = Number(c.getAttribute('r'));
+        const halfStroke = Number(c.getAttribute('stroke-width') ?? 0) / 2;
+        expect(radius + halfStroke, `${n.id} circle`).toBeLessThanOrEqual(r + 1e-9);
+      }
+    }
+  });
+
+  /**
+   * The arc is the whole point of the dial: it has to encode the node's own
+   * `mastery`, not a constant. Recomputing the endpoint from the fixture and
+   * comparing it to the rendered path is what keeps a future "make the rings
+   * look fuller" tweak from quietly decoupling the picture from the data.
+   */
+  it('sweeps each arc through that node’s mastery, clockwise from 12 o’clock', () => {
+    render(<KnowledgeGraphDemo />);
+    for (const n of graph.nodes) {
+      const arc = nodeGroup(n.id).querySelector('path')!;
+      expect(arc, n.id).toBeTruthy();
+      // `M sx sy A rx ry xrot large sweep ex ey`
+      const d = arc.getAttribute('d')!;
+      const [sx, sy, rx, , , large, , ex, ey] = d
+        .replace(/[A-Za-z]/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .map(Number);
+
+      const disc = nodeGroup(n.id).querySelector('circle')!;
+      const cx = Number(disc.getAttribute('cx'));
+      const cy = Number(disc.getAttribute('cy'));
+
+      // Starts at the top of the ring…
+      expect(sx, `${n.id} start x`).toBeCloseTo(cx, 1);
+      expect(sy, `${n.id} start y`).toBeCloseTo(cy - rx, 1);
+      // …and ends `mastery` of a turn clockwise from it.
+      const sweep = n.mastery * Math.PI * 2;
+      expect(ex, `${n.id} end x`).toBeCloseTo(cx + rx * Math.sin(sweep), 1);
+      expect(ey, `${n.id} end y`).toBeCloseTo(cy - rx * Math.cos(sweep), 1);
+      expect(large, `${n.id} large-arc flag`).toBe(n.mastery > 0.5 ? 1 : 0);
+    }
+  });
+
+  /**
+   * The annulus between the core and the ring is transparent paper, so an
+   * edge drawn to the node's CENTRE (which is what shipped, hidden under a
+   * solid disc) would now run straight across the middle of every dial.
+   */
+  it('stops edges at the rim of the discs they connect', () => {
+    render(<KnowledgeGraphDemo />);
+    const svg = screen.getByTestId('landing-graph-svg');
+    const centres = new Map(
+      graph.nodes.map((n) => {
+        const c = nodeGroup(n.id).querySelector('circle')!;
+        return [n.id, { x: Number(c.getAttribute('cx')), y: Number(c.getAttribute('cy')) }];
+      }),
+    );
+
+    const lines = [...svg.querySelectorAll('line')];
+    expect(lines).toHaveLength(graph.edges.length);
+    lines.forEach((line, i) => {
+      const e = graph.edges[i];
+      const a = centres.get(e.source)!;
+      const b = centres.get(e.target)!;
+      const rA = e.source === graph.rootId ? DESKTOP_VIEW.rootR : DESKTOP_VIEW.nodeR;
+      const rB = e.target === graph.rootId ? DESKTOP_VIEW.rootR : DESKTOP_VIEW.nodeR;
+      const from = { x: Number(line.getAttribute('x1')), y: Number(line.getAttribute('y1')) };
+      const to = { x: Number(line.getAttribute('x2')), y: Number(line.getAttribute('y2')) };
+      expect(Math.hypot(from.x - a.x, from.y - a.y), `${e.source} end`).toBeCloseTo(rA, 1);
+      expect(Math.hypot(to.x - b.x, to.y - b.y), `${e.target} end`).toBeCloseTo(rB, 1);
+    });
+  });
+});
+
+/**
+ * #344 step 3 — product chrome. The section used to float naked on the page
+ * background one viewport above four bento tiles that each carry a titled
+ * chrome bar over a recreated screen.
+ */
+describe('KnowledgeGraphDemo — surface chrome and legend (#344 step 3)', () => {
+  it('names the surface and reports the selected course’s own numbers', () => {
+    render(<KnowledgeGraphDemo />);
+    const surface = screen.getByTestId('landing-graph-surface');
+    expect(surface).toHaveTextContent('Knowledge Graph');
+
+    const g = COURSE_GRAPHS[0];
+    const root = g.nodes.find((n) => n.id === g.rootId)!;
+    const meta = screen.getByTestId('landing-graph-meta');
+    expect(meta).toHaveTextContent(g.code);
+    expect(meta).toHaveTextContent(`${g.conceptCount} concepts`);
+    expect(meta).toHaveTextContent(`${Math.round(root.mastery * 100)}% mastery`);
+  });
+
+  it('re-reads the chrome from the newly picked course', () => {
+    render(<KnowledgeGraphDemo />);
+    const target = COURSE_GRAPHS[1];
+    fireEvent.click(screen.getByTestId(`landing-graph-chip-${target.id}`));
+
+    const root = target.nodes.find((n) => n.id === target.rootId)!;
+    const meta = screen.getByTestId('landing-graph-meta');
+    expect(meta).toHaveTextContent(target.code);
+    expect(meta).toHaveTextContent(`${target.conceptCount} concepts`);
+    expect(meta).toHaveTextContent(`${Math.round(root.mastery * 100)}% mastery`);
+  });
+
+  /**
+   * The comprehension gap this closes: four `--state-*` hues carried the whole
+   * meaning of the picture and NOTHING on the page said what any of them
+   * meant. The counts are what make it a readout rather than a colour key.
+   */
+  it('spells out every mastery tier, in the product’s words, with its count', () => {
+    render(<KnowledgeGraphDemo />);
+    const counts = tierCounts(COURSE_GRAPHS[0]);
+    for (const tier of TIER_ORDER) {
+      const row = screen.getByTestId(`landing-graph-legend-${tier}`);
+      expect(row).toHaveTextContent(TIER_LABEL[tier]);
+      expect(row).toHaveTextContent(String(counts[tier]));
+    }
+  });
+
+  it('says how much of the course is on screen, and what the ring means', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+    const legend = screen.getByTestId('landing-graph-legend');
+    expect(legend).toHaveTextContent(`${conceptNodes(g).length} of ${g.conceptCount} shown`);
+    expect(legend).toHaveTextContent(/ring\s*=\s*progress to mastery/i);
+  });
+});
+
+/**
+ * #344 step 3 — the hover readout is a panel, not a line of body text.
+ */
+describe('KnowledgeGraphDemo — detail panel (#344 step 3)', () => {
+  it('shows the COURSE at rest, so the panel is never an empty placeholder', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+    const root = g.nodes.find((n) => n.id === g.rootId)!;
+
+    expect(screen.getByTestId('landing-graph-detail-name')).toHaveTextContent(root.label);
+    expect(screen.getByTestId('landing-graph-blurb')).toHaveTextContent(root.blurb);
+    // The root is the course anchor, not a mastery status (#344 visual 2), so
+    // its chip says so rather than parroting its fixture tier.
+    expect(screen.getByTestId('landing-graph-detail-tier')).toHaveTextContent('Course');
+    expect(screen.getByTestId('landing-graph-detail-mastery')).toHaveTextContent(
+      `${Math.round(root.mastery * 100)}%`,
+    );
+  });
+
+  it('swaps the whole panel — name, tier, mastery, links — to the hovered concept', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+    const n = g.nodes.find((x) => x.id !== g.rootId)!;
+    fireEvent.mouseEnter(screen.getByTestId(`landing-graph-node-${n.id}`));
+
+    expect(screen.getByTestId('landing-graph-detail-name')).toHaveTextContent(n.label);
+    expect(screen.getByTestId('landing-graph-detail-tier')).toHaveTextContent(TIER_LABEL[n.tier]);
+    expect(screen.getByTestId('landing-graph-detail-mastery')).toHaveTextContent(
+      `${Math.round(n.mastery * 100)}%`,
+    );
+
+    const panel = screen.getByTestId('landing-graph-detail');
+    const links = neighbours(g, n.id);
+    expect(panel).toHaveTextContent(
+      `${links.length} connection${links.length === 1 ? '' : 's'}`,
+    );
+    for (const l of links) expect(panel).toHaveTextContent(l.label);
+  });
+
+  it('returns to the course when the pointer leaves', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+    const n = g.nodes.find((x) => x.id !== g.rootId)!;
+    const el = screen.getByTestId(`landing-graph-node-${n.id}`);
+
+    fireEvent.mouseEnter(el);
+    expect(screen.getByTestId('landing-graph-detail-name')).toHaveTextContent(n.label);
+    fireEvent.mouseLeave(el);
+    expect(screen.getByTestId('landing-graph-detail-name')).toHaveTextContent(
+      g.nodes.find((x) => x.id === g.rootId)!.label,
+    );
+  });
+
+  /**
+   * A hovered id from the PREVIOUS course would still resolve to nothing and
+   * fall back to the root, but leaving it set means a mouse that never moves
+   * after a chip click reads as "hovering" a node that is no longer drawn.
+   * `engaged` deliberately does NOT reset with it (pinned above).
+   */
+  it('clears the hover when the course changes', () => {
+    render(<KnowledgeGraphDemo />);
+    const g = COURSE_GRAPHS[0];
+    const n = g.nodes.find((x) => x.id !== g.rootId)!;
+    fireEvent.mouseEnter(screen.getByTestId(`landing-graph-node-${n.id}`));
+
+    const target = COURSE_GRAPHS[1];
+    fireEvent.click(screen.getByTestId(`landing-graph-chip-${target.id}`));
+    expect(screen.getByTestId('landing-graph-detail-name')).toHaveTextContent(
+      target.nodes.find((x) => x.id === target.rootId)!.label,
+    );
+  });
+});
+
+/**
+ * #344 step 3 — ambient drift.
+ *
+ * The brand guide's atmosphere is "a barely-there field of colourful orbs
+ * drifting slowly in 3D"; this section was frozen the instant its assembly
+ * landed. The drift is a CSS animation, so the assertions are about the class
+ * and the custom properties the keyframe reads — and, more importantly, about
+ * the two populations that must NEVER see it.
+ */
+describe('KnowledgeGraphDemo — ambient drift (#344 step 3)', () => {
+  function driftingNodes() {
+    return COURSE_GRAPHS[0].nodes
+      .map((n) => screen.getByTestId(`landing-graph-node-${n.id}`))
+      .filter((el) => el.classList.contains('is-drifting'));
+  }
+
+  /** Reduced-motion + breakpoint in one controllable `matchMedia`. */
+  function installMedia({ reduced, mobile }: { reduced: boolean; mobile: boolean }) {
+    window.matchMedia = ((q: string) => ({
+      matches: q.includes('prefers-reduced-motion') ? reduced : q.includes('max-width') && mobile,
+      media: q,
+      addEventListener() {},
+      removeEventListener() {},
+    })) as unknown as typeof window.matchMedia;
+  }
+
+  it('parks every node on its laid-out point when reduced motion is requested', () => {
+    installMedia({ reduced: true, mobile: false });
+    render(<KnowledgeGraphDemo />);
+    expect(driftingNodes()).toHaveLength(0);
+    for (const n of COURSE_GRAPHS[0].nodes) {
+      const el = screen.getByTestId(`landing-graph-node-${n.id}`);
+      // No animation, and no leftover custom properties to drive one.
+      expect(el.getAttribute('style') ?? '', n.id).not.toContain('--drift');
+    }
+  });
+
+  it('does not drift the phone view, where the frame pad and label clearance are spent', () => {
+    installMedia({ reduced: false, mobile: true });
+    render(<KnowledgeGraphDemo />);
+    expect(driftingNodes()).toHaveLength(0);
+  });
+
+  it('drifts every node on the desktop view, each with its own phase', () => {
+    installMedia({ reduced: false, mobile: false });
+    render(<KnowledgeGraphDemo />);
+    const nodes = driftingNodes();
+    expect(nodes).toHaveLength(COURSE_GRAPHS[0].nodes.length);
+
+    const delays = nodes.map((el) => (el as HTMLElement).style.getPropertyValue('--drift-delay'));
+    for (const el of nodes) {
+      const style = el as HTMLElement;
+      // A negative delay starts the node part-way through its own cycle, which
+      // is what stops six nodes pulsing together like a loading state.
+      expect(Number(style.style.getPropertyValue('--drift-delay').replace('s', ''))).toBeLessThan(0);
+      const dx = Number(style.style.getPropertyValue('--drift-x').replace('px', ''));
+      const dy = Number(style.style.getPropertyValue('--drift-y').replace('px', ''));
+      // Inside the desktop frame's 10-unit fit pad, by a wide margin.
+      expect(Math.hypot(dx, dy)).toBeLessThanOrEqual(3.0001);
+      expect(Math.hypot(dx, dy)).toBeGreaterThan(0);
+    }
+    expect(new Set(delays).size).toBeGreaterThan(1);
+  });
+
+  /**
+   * The phases are hashed off the node id rather than drawn from a PRNG,
+   * because they are baked into a `style` attribute that React renders on the
+   * server and diffs on the client. `Math.random()` here is a hydration
+   * mismatch on every page load.
+   */
+  it('derives the same phase for the same node on every render', () => {
+    installMedia({ reduced: false, mobile: false });
+    const { unmount } = render(<KnowledgeGraphDemo />);
+    const first = driftingNodes().map((el) => el.getAttribute('style'));
+    unmount();
+
+    render(<KnowledgeGraphDemo />);
+    expect(driftingNodes().map((el) => el.getAttribute('style'))).toEqual(first);
+  });
+});
diff --git a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
index 31da4ad0..81310911 100644
--- a/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
+++ b/frontend/src/components/marketing/graph/KnowledgeGraphDemo.tsx
@@ -1,12 +1,23 @@
 'use client';
 
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useEffect, useMemo, useRef, useState, type CSSProperties } from 'react';
 
 import { IS_TEST_MODE, now } from '@/lib/testMode';
 import { useIsMobile } from '@/lib/useIsMobile';
 import { usePrefersReducedMotion } from '@/lib/usePrefersReducedMotion';
 
-import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph, type DemoNode } from './courseGraphs';
+import { StateDot, SurfaceFrame, SurfaceRule } from '../surfaces/Surface';
+import {
+  COURSE_GRAPHS,
+  TIER_COLOR,
+  TIER_LABEL,
+  TIER_ORDER,
+  conceptNodes,
+  neighbours,
+  tierCounts,
+  type CourseGraph,
+  type DemoNode,
+} from './courseGraphs';
 import {
   DESKTOP_VIEW,
   MOBILE_VIEW,
@@ -56,6 +67,78 @@ const ARM_ROOT_MARGIN = '0px 0px -10% 0px';
  */
 export const ENGAGED_HEADLINE_OPACITY = 0.55;
 
+/**
+ * Ambient drift, in SVG user units (#344 step 3).
+ *
+ * The brand guide describes the page's atmosphere as "a barely-there field of
+ * colourful orbs drifting slowly in 3D — like the glow under water", and the
+ * hero's canvas does exactly that. This section was frozen the moment its
+ * assembly landed, which read as a diagram rather than as a living map.
+ *
+ * THREE UNITS, and the ceiling is not taste — it is the frame. `fitViewBox`
+ * fits the desktop `viewBox` to the entry sweep with `fitPad: 10` of margin, so
+ * anything up to 10 units of post-settle displacement stays inside the box; 3
+ * spends less than a third of that. The phone view's pad is 2 and its worst
+ * label-to-neighbour clearance is 5.40 units, which two nodes drifting toward
+ * each other would eat — so the phone does not drift at all (see `drifting`
+ * below). At the 720px desktop cap 3 units is ~3.7 CSS px: perceptible as
+ * breathing, invisible as movement.
+ *
+ * The motion is a CSS animation, not a rAF loop, on purpose. It composites off
+ * the main thread, it costs zero React re-renders for a section that already
+ * re-renders on hover, the global `prefers-reduced-motion` reset in globals.css
+ * neutralises it for free, and — decisively — it stays out of the assembly's
+ * rAF budget, which `KnowledgeGraphDemo.test.tsx` counts frame by frame to
+ * prove the helix neither fires early nor replays.
+ */
+const DRIFT_AMPLITUDE = 3;
+const DRIFT_MIN_S = 13;
+const DRIFT_SPAN_S = 9;
+
+/** Two decimals is plenty for user units, and keeps the SSR payload small. */
+function r2(v: number): number {
+  return Math.round(v * 100) / 100;
+}
+
+/**
+ * FNV-1a over the node id — a per-node drift phase that is a pure function of
+ * the fixture.
+ *
+ * NOT `Math.random()`, and not `testMode.random()` either: this value is baked
+ * into a `style` attribute that React renders on the server and then diffs on
+ * the client, so anything stateful here is a hydration mismatch. A hash of the
+ * id gives every node its own direction, amplitude, period and starting phase
+ * while staying byte-identical across both renders and across reloads.
+ */
+function nodeSeed(id: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < id.length; i += 1) {
+    h ^= id.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/**
+ * The four custom properties `landing-graph-drift` reads. A NEGATIVE delay
+ * starts each node part-way through its own cycle, so the field never syncs up
+ * into a single collective pulse — the failure mode that makes ambient motion
+ * read as a loading state.
+ */
+function driftStyle(id: string): CSSProperties {
+  const seed = nodeSeed(id);
+  const angle = ((seed % 3600) / 3600) * Math.PI * 2;
+  const amplitude = DRIFT_AMPLITUDE * (0.55 + (((seed >>> 12) % 100) / 100) * 0.45);
+  const duration = DRIFT_MIN_S + (((seed >>> 19) % 100) / 100) * DRIFT_SPAN_S;
+  const delay = -(((seed >>> 25) % 100) / 100) * duration;
+  return {
+    '--drift-x': `${r2(Math.cos(angle) * amplitude)}px`,
+    '--drift-y': `${r2(Math.sin(angle) * amplitude)}px`,
+    '--drift-dur': `${r2(duration)}s`,
+    '--drift-delay': `${r2(delay)}s`,
+  } as CSSProperties;
+}
+
 function nodeRadius(view: GraphView, g: CourseGraph, id: string): number {
   return id === g.rootId ? view.rootR : view.nodeR;
 }
@@ -75,6 +158,38 @@ function nodeFill(g: CourseGraph, node: DemoNode): string {
   return node.id === g.rootId ? 'var(--brand-forest)' : TIER_COLOR[node.tier];
 }
 
+/** Human label for the detail panel's status chip. The root isn't a status. */
+function nodeTierLabel(g: CourseGraph, node: DemoNode): string {
+  return node.id === g.rootId ? 'Course' : TIER_LABEL[node.tier];
+}
+
+/**
+ * The mastery arc: an open path from 12 o'clock, sweeping clockwise through
+ * `fraction` of the ring (#344 step 3).
+ *
+ * A `<path>` rather than a `stroke-dasharray` circle, for two reasons. The
+ * dash trick needs the circumference computed anyway, it renders the *gap* as a
+ * second visible dash on any browser that rounds differently, and — the one
+ * that settles it — `KnowledgeGraphDemo.test.tsx` and the E2E legibility gate
+ * both reach for `querySelector('circle')` inside a node group and read its
+ * `fill` and `r`. The node's first circle has to stay the tier-painted disc
+ * whose diameter is the node's drawn size. Arcs are paths; nothing shifts.
+ *
+ * Capped just under a full turn: at exactly 1 the two endpoints coincide and
+ * the arc collapses to nothing.
+ */
+function masteryArc(cx: number, cy: number, radius: number, fraction: number): string {
+  const f = Math.min(0.999, Math.max(0, fraction));
+  if (f <= 0 || radius <= 0) return '';
+  const sweep = f * Math.PI * 2;
+  const large = f > 0.5 ? 1 : 0;
+  return [
+    `M ${r2(cx)} ${r2(cy - radius)}`,
+    `A ${r2(radius)} ${r2(radius)} 0 ${large} 1`,
+    `${r2(cx + radius * Math.sin(sweep))} ${r2(cy - radius * Math.cos(sweep))}`,
+  ].join(' ');
+}
+
 /**
  * Renders one course's edges + nodes, animating them in along the helical
  * entry path (#344). The parent keys this by `graph.id`, so picking another
@@ -108,6 +223,8 @@ function AssemblingGraph({
   view,
   parked,
   armed,
+  drifting,
+  hovered,
   onNodeEnter,
   onNodeLeave,
 }: {
@@ -116,6 +233,8 @@ function AssemblingGraph({
   view: GraphView;
   parked: boolean;
   armed: boolean;
+  drifting: boolean;
+  hovered: string | null;
   onNodeEnter: (id: string) => void;
   onNodeLeave: () => void;
 }) {
@@ -162,16 +281,40 @@ function AssemblingGraph({
         const a = points.get(e.source);
         const b = points.get(e.target);
         if (!a || !b) return null;
+
+        /*
+          Edges stop at the rim of the discs they connect instead of running to
+          their centres (#344 step 3). Under flat filled dots the difference was
+          invisible — the disc painted over the stub. The node is a RING now,
+          and the annulus between its core and its ring is transparent paper, so
+          an untrimmed edge would draw a grey line straight across the middle of
+          every mastery dial on the page. Trimming is capped at 45% of the run
+          so a short edge shortens rather than inverting.
+        */
+        const dx = b.x - a.x;
+        const dy = b.y - a.y;
+        const len = Math.hypot(dx, dy) || 1;
+        const ux = dx / len;
+        const uy = dy / len;
+        const cap = len * 0.45;
+        const trimA = Math.min(nodeRadius(view, graph, e.source), cap);
+        const trimB = Math.min(nodeRadius(view, graph, e.target), cap);
+        // The hovered node's own edges lift out of the mesh, so "3 connections"
+        // in the detail panel is a claim the picture can be checked against.
+        const lit = hovered === e.source || hovered === e.target;
+
         return (
           <line
             key={`${e.source}-${e.target}`}
-            x1={a.x}
-            y1={a.y}
-            x2={b.x}
-            y2={b.y}
-            stroke="var(--text-dim)"
-            strokeOpacity={0.28 * progress}
-            strokeWidth={view.edgeW}
+            x1={r2(a.x + ux * trimA)}
+            y1={r2(a.y + uy * trimA)}
+            x2={r2(b.x - ux * trimB)}
+            y2={r2(b.y - uy * trimB)}
+            stroke={lit ? 'var(--brand-forest)' : 'var(--text-dim)'}
+            strokeOpacity={(lit ? 0.55 : 0.28) * progress}
+            strokeWidth={(lit ? 1.5 : 1) * view.edgeW}
+            strokeLinecap="round"
+            className="landing-graph-edge"
           />
         );
       })}
@@ -184,15 +327,63 @@ function AssemblingGraph({
         const local = Math.min(1, Math.max(0, (progress - i * span) / (1 - i * span)));
         const h = helixEntry(p, centre, local);
         const r = nodeRadius(view, graph, n.id);
+        const fill = nodeFill(graph, n);
+        const lit = hovered === n.id;
+
+        /*
+          The dial (#344 step 3). Every dimension is measured INWARD from `r`,
+          the node's existing radius, so the drawn footprint is byte-identical
+          to the flat disc this replaced: `fitViewBox` still frames it, the
+          label gap `labelBaselineY` reserves is still the right gap, and the
+          phone's 5.40-unit worst-case label clearance is untouched. A ring
+          hung OUTSIDE `r` would have moved all three, and every one of them is
+          load-bearing arithmetic that `layout.test.ts` pins.
+
+            · disc   — r, tier colour at 14% — the node's extent and its hit
+                       target (fill-opacity > 0 keeps `visiblePainted` hits).
+            · track  — the unfilled remainder, in a NEUTRAL. A track tinted
+                       with the node's own colour made an arc at 6% and an arc
+                       at 90% look alike at this size, which is the one thing
+                       a dial may not do.
+            · arc    — mastery, swept clockwise from 12 o'clock.
+            · core   — 0.52 r of solid tier colour, so the node still reads as
+                       a coloured dot from across the page.
+        */
+        const scaled = r * h.scale;
+        const ringW = Math.min(r * 0.22, 4.4) * h.scale;
+        const ringR = scaled - ringW / 2;
+        const coreR = scaled * 0.52;
+        const arc = masteryArc(h.x, h.y, ringR, n.mastery);
+
         return (
           <g
             key={n.id}
             data-testid={`landing-graph-node-${n.id}`}
+            className={`landing-graph-node${drifting ? ' is-drifting' : ''}`}
+            style={drifting ? driftStyle(n.id) : undefined}
             opacity={h.opacity}
             onMouseEnter={() => onNodeEnter(n.id)}
             onMouseLeave={onNodeLeave}
           >
-            <circle cx={h.x} cy={h.y} r={r * h.scale} fill={nodeFill(graph, n)} />
+            <circle cx={h.x} cy={h.y} r={scaled} fill={fill} fillOpacity={lit ? 0.24 : 0.14} />
+            <circle
+              cx={h.x}
+              cy={h.y}
+              r={ringR}
+              fill="none"
+              stroke="var(--ink-200)"
+              strokeWidth={ringW}
+            />
+            {arc === '' ? null : (
+              <path
+                d={arc}
+                fill="none"
+                stroke={fill}
+                strokeWidth={ringW}
+                strokeLinecap="round"
+              />
+            )}
+            <circle cx={h.x} cy={h.y} r={coreR} fill={fill} />
             {/*
               Labels sit ON the edge mesh — under the upward fan every arm's
               label straddles the edge running out to its child, and the middle
@@ -202,6 +393,10 @@ function AssemblingGraph({
               passing behind a word breaks around the letterforms instead of
               running through them. One element, existing token, no backdrop
               filter — the brand's hard "no frosted panels" line holds.
+
+              The halo is `--bg-mesh` and the canvas the graph now sits on is
+              painted `--bg-mesh` for exactly that reason: on the panel paper
+              the halo would show as a pale rectangle behind every word.
             */}
             <text
               x={h.x}
@@ -209,7 +404,7 @@ function AssemblingGraph({
               textAnchor="middle"
               className="font-jetbrains"
               fontSize={view.font}
-              fill="var(--text-dim)"
+              fill={lit ? 'var(--text)' : 'var(--text-dim)'}
               stroke="var(--bg-mesh)"
               strokeWidth={view.labelHalo}
               strokeLinejoin="round"
@@ -225,6 +420,115 @@ function AssemblingGraph({
   );
 }
 
+/**
+ * The inspector rail — what the app's own node detail looks like (#344 step 3).
+ *
+ * Replaces the single line of body text this section used to swap under the
+ * graph. That line was the only thing hover produced, on a page where the four
+ * bento tiles below each recreate a whole product screen, and it made the
+ * differentiator the thinnest surface here.
+ *
+ * IT IS NEVER EMPTY. With nothing hovered it shows the COURSE — the root node,
+ * whose blurb is a real sentence and whose mastery is the real aggregate — so
+ * the panel reads as a populated screen at rest rather than as a placeholder
+ * waiting to be earned. That also removes the "hover to see more" instruction
+ * a touch visitor can never act on.
+ *
+ * Every row is fixed-height or floor-reserved, and at the two-column breakpoint
+ * the grid stretches this rail to the canvas's height, so the swap on hover
+ * cannot move a single pixel of the page.
+ */
+function GraphInspector({ graph, node }: { graph: CourseGraph; node: DemoNode }) {
+  const links = neighbours(graph, node.id);
+  const isRoot = node.id === graph.rootId;
+  const paint = nodeFill(graph, node);
+  const pct = Math.round(node.mastery * 100);
+
+  return (
+    <SurfaceFrame
+      testId="landing-graph-detail"
+      title={isRoot ? 'Course' : 'Concept'}
+      meta={`${links.length} connection${links.length === 1 ? '' : 's'}`}
+    >
+      <span className="landing-graph-detailhead">
+        <span className="landing-graph-detailname" data-testid="landing-graph-detail-name">
+          {node.label}
+        </span>
+        {/*
+          The tier is spelled out, and the colour rides the chip's dot and
+          border rather than its lettering — the same recipe, down to the
+          `color-mix` wash, that `GradebookSurface`'s per-row grade pill uses.
+          `--state-progress` (#c89b5e) as text on this paper is 2.2:1; as a
+          border and a mark next to a `--text` word it carries the state
+          without ever having to be legible as type.
+        */}
+        <span
+          className="landing-graph-tierchip"
+          data-testid="landing-graph-detail-tier"
+          style={{ '--tier': paint } as CSSProperties}
+        >
+          {nodeTierLabel(graph, node)}
+        </span>
+      </span>
+
+      {/*
+        Reserved min-height (#344 task 5, kept): the blurb swaps on every
+        hover and unhover. Without a floor, a one-line blurb replacing a
+        two-line one shifts everything under it on every pass of the mouse —
+        load-bearing, not cosmetic. The floor is two lines, which is the
+        tallest any fixture blurb reaches at the narrowest column this panel
+        is ever rendered in.
+      */}
+      <p className="landing-graph-blurb" data-testid="landing-graph-blurb">
+        {node.blurb}
+      </p>
+
+      <SurfaceRule />
+
+      <span className="landing-surface-headrow">
+        <span className="landing-surface-label">Mastery</span>
+        <span className="landing-surface-mono" data-testid="landing-graph-detail-mastery">
+          {pct}%
+        </span>
+      </span>
+      {/* The Study surface's own progress track, reused verbatim so the two
+          meters on this page are the same object. Only the fill's colour and
+          width are per-node. */}
+      <span aria-hidden className="landing-surface-track">
+        <span className="landing-surface-fill" style={{ width: `${pct}%`, background: paint }} />
+      </span>
+
+      <SurfaceRule />
+
+      {/*
+        The neighbours as a LIST with their own scores, not a chip row: it is
+        what the app's related-concepts rail shows, it is the second half of
+        the "3 connections" claim in the chrome bar, and — with the edges those
+        links name lit up in the canvas alongside — it is the thing that makes
+        the picture and the panel readable as one screen.
+
+        Three rows are reserved. No fixture node has more than three
+        neighbours, so the floor is also the ceiling and the panel's height is
+        constant across every node of every course.
+      */}
+      <span className="landing-surface-label">Connected to</span>
+      <span className="landing-graph-links">
+        {links.map((l) => (
+          <span key={l.id} className="landing-graph-link">
+            <span
+              aria-hidden
+              className="landing-surface-dot"
+              style={{ background: nodeFill(graph, l) }}
+            />
+            <span className="landing-graph-linkname">{l.label}</span>
+            <span className="landing-surface-mono">{Math.round(l.mastery * 100)}%</span>
+          </span>
+        ))}
+      </span>
+    </SurfaceFrame>
+  );
+}
+
 export default function KnowledgeGraphDemo() {
   const [courseId, setCourseId] = useState(COURSE_GRAPHS[0].id);
 
@@ -235,12 +539,10 @@ export default function KnowledgeGraphDemo() {
   // (once a visitor has interacted, the instructional copy stays faded for
   // the rest of the session) — that's only guaranteed by keeping it outside
   // the subtree that remounts. `hovered` doesn't strictly need the same
-  // guarantee (a stale id from the previous course just fails the
-  // `graph.nodes.find` lookup below and renders no blurb), but the blurb
-  // paragraph itself is rendered here in the parent, as a sibling of the
-  // `<svg>`, so the parent needs read access to "which node is hovered"
-  // regardless. One state owner for both pieces of interaction state keeps
-  // `AssemblingGraph` a plain layout/animation renderer that only takes
+  // guarantee, but the detail panel is rendered here in the parent, as a
+  // sibling of the `<svg>`, so the parent needs read access to "which node is
+  // hovered" regardless. One state owner for both pieces of interaction state
+  // keeps `AssemblingGraph` a plain layout/animation renderer that only takes
   // callback props, instead of splitting hover across two lifetimes for no
   // behavioral gain.
   const [hovered, setHovered] = useState<string | null>(null);
@@ -269,12 +571,26 @@ export default function KnowledgeGraphDemo() {
   // hydration. A viewBox is not something a CSS `@media` rule can swap, so that
   // one-frame correction is the floor here; both views render the complete
   // graph, so it is a resize, never a blank.
-  const view = useIsMobile() ? MOBILE_VIEW : DESKTOP_VIEW;
+  const isMobile = useIsMobile();
+  const view = isMobile ? MOBILE_VIEW : DESKTOP_VIEW;
   const points = useMemo(
     () => radialLayout(graph, view.w, view.h, view.maxRadius),
     [graph, view],
   );
-  const hoveredBlurb = hovered ? graph.nodes.find((n) => n.id === hovered)?.blurb : undefined;
+
+  // The panel's subject: the hovered node, or the course itself at rest. A
+  // stale id can't survive here anyway (the chip handler clears `hovered`),
+  // but falling back to the root also covers a fixture edit that drops a node.
+  const detailNode =
+    graph.nodes.find((n) => n.id === hovered) ??
+    graph.nodes.find((n) => n.id === graph.rootId) ??
+    graph.nodes[0];
+
+  const concepts = conceptNodes(graph);
+  const counts = tierCounts(graph);
+  const coursePct = Math.round(
+    (graph.nodes.find((n) => n.id === graph.rootId)?.mastery ?? 0) * 100,
+  );
 
   // `usePrefersReducedMotion` (not a direct `window.matchMedia` read in the
   // render body — #344 fix round 1) is hydration-safe: it renders the same
@@ -284,6 +600,14 @@ export default function KnowledgeGraphDemo() {
   const prefersReduced = usePrefersReducedMotion();
   const parked = IS_TEST_MODE || prefersReduced;
 
+  // Ambient drift rides the SAME park switch as the assembly, so a
+  // reduced-motion visitor and the E2E lane both get a graph whose nodes sit
+  // exactly on their laid-out points — a complete, still, readable frame. It
+  // is additionally off below the mobile breakpoint: the phone view's frame
+  // pad is 2 units and its worst label-to-neighbour clearance 5.40, both of
+  // which a 3-unit drift would spend (see DRIFT_AMPLITUDE).
+  const drifting = !parked && !isMobile;
+
   // #344 review #1: without this gate the assembly effect fired on mount and
   // burned its full 1100ms during the hydration window — underneath the
   // landing page's full-screen intro overlay, concurrently with the hero
@@ -368,7 +692,10 @@ export default function KnowledgeGraphDemo() {
                 type="button"
                 data-testid={`landing-graph-chip-${g.id}`}
                 aria-pressed={active}
-                onClick={() => setCourseId(g.id)}
+                onClick={() => {
+                  setCourseId(g.id);
+                  setHovered(null);
+                }}
                 className={`landing-graph-chip${active ? ' is-active' : ''}`}
               >
                 {g.code}
@@ -378,63 +705,104 @@ export default function KnowledgeGraphDemo() {
         </div>
 
         {/*
-          #344 visual 3 + 5, which have to be solved together.
-
-          The frame is now measured off the content (`view.fit`) instead of the
-          hardcoded `0 0 900 560`, which drops 36% of dead margin off the box.
-          But a tight box stretched to the full 1184px container would render
-          the graph at 2× and make the section TALLER, not shorter — the fit only
-          pays off with a width cap. Capping also settles the composition: the
-          section's eyebrow, headline and chips are left-aligned on the container
-          grid while the graph was centred inside a full-bleed box one viewport
-          below a hero that is centred and symmetric, so it read as an accident.
-          Left-aligning the graph to the same grid line commits to the editorial
-          direction the rest of the section already uses, and it is the reversible
-          half of the choice: no copy moves, no structure changes.
-
-          At the 720px cap the desktop graph draws at ~1.24 units per CSS px in
-          a 720×413 box, where the fixed viewBox reserved 1184×737 and drew the
-          graph across the middle 277px of it. The box is 224px SHORTER than the
-          720×638 the same upward fan fitted while `helixEntry` turned 1.5 times
-          on the way in: the frame is fitted to that entry SWEEP (it has to be,
-          or the assembly gets clipped mid-flight), a 540° sweep is very nearly a
-          disc, and a near-square frame around a canopy twice as wide as it is
-          tall is dead paper on the top and bottom edges. At a quarter turn the
-          sweep hugs the drawing, so the drawing now fills 87% of the frame's
-          width and 85% of its height — and it renders BIGGER than it did in the
-          taller box (694×352 CSS px against 669×339).
-        */}
-        <svg
-          data-testid="landing-graph-svg"
-          viewBox={viewBoxAttr(view.fit)}
-          className="mt-8 w-full max-w-[420px] md:max-w-[720px] h-auto"
-          role="img"
-          aria-label={`${graph.name} concept graph`}
-        >
-          <AssemblingGraph
-            key={graph.id}
-            graph={graph}
-            points={points}
-            view={view}
-            parked={parked}
-            armed={armed}
-            onNodeEnter={onNodeEnter}
-            onNodeLeave={onNodeLeave}
-          />
-        </svg>
+          #344 step 3 — the graph gets the same product chrome as every other
+          surface on this page.
 
-        {/*
-          Reserved min-height (#344 task 5): the blurb text appears and
-          disappears on every hover/unhover. Without a floor, the paragraph
-          collapsing to empty on mouseleave shifts anything rendered below
-          this section on every single hover — load-bearing, not cosmetic.
+          It used to float naked on the page background: six dots and six words
+          left-aligned in a 1184px container, with the right 40% of the field
+          empty, one viewport above four bento tiles that each recreate a whole
+          screen. The differentiator was the flimsiest thing here.
+
+          One surface, full container width, split the way the app's own Tree
+          screen is split: canvas left, inspector right, legend along the foot.
+          The canvas keeps the `md:max-w-[720px]` cap it was fitted against
+          (#344 visual 3/5 — a wider render makes the section TALLER, and the
+          section's height is what those waves bought down) and centres inside
+          the space the rail leaves, so nothing about the drawing's scale moved.
         */}
-        <p
-          data-testid="landing-graph-blurb"
-          className="landing-graph-blurb font-inter text-[var(--text-dim)] mt-4 min-h-[1.5rem]"
-        >
-          {hoveredBlurb ?? ''}
-        </p>
+        <div className="landing-surface mt-8" data-testid="landing-graph-surface">
+          <div className="landing-surface-chrome landing-graph-chrome">
+            <span className="landing-surface-title">Knowledge Graph</span>
+            <span className="landing-surface-meta" data-testid="landing-graph-meta">
+              {graph.code} · {graph.conceptCount} concepts · {coursePct}% mastery
+            </span>
+          </div>
+
+          <div className="landing-graph-split">
+            {/*
+              The canvas is painted `--bg-mesh`, not the panel's paper, and
+              that is a requirement rather than a preference: every label is
+              stroked with a `--bg-mesh` halo so the edge mesh breaks around
+              its letterforms. On any other backdrop those haloes show up as
+              pale rectangles behind the words.
+
+              It is also full-bleed horizontally — no side padding at ALL —
+              because the phone's legibility gate is measured in CSS px off
+              the rendered `<svg>` width. At 390px the section's content box
+              is ~332px and the frame renders at 0.769 of a unit per px;
+              spending 30px on padding takes the drawing under the E2E bar.
+              Vertical padding is free (the height follows the width) and is
+              where the breathing room goes.
+            */}
+            <div className="landing-graph-canvas">
+              <svg
+                data-testid="landing-graph-svg"
+                viewBox={viewBoxAttr(view.fit)}
+                className="w-full md:max-w-[720px] xl:max-w-[820px] h-auto"
+                role="img"
+                aria-label={`${graph.name} concept graph`}
+              >
+                <AssemblingGraph
+                  key={graph.id}
+                  graph={graph}
+                  points={points}
+                  view={view}
+                  parked={parked}
+                  armed={armed}
+                  drifting={drifting}
+                  hovered={hovered}
+                  onNodeEnter={onNodeEnter}
+                  onNodeLeave={onNodeLeave}
+                />
+              </svg>
+            </div>
+
+            <div className="landing-graph-rail">
+              <GraphInspector graph={graph} node={detailNode} />
+
+              {/*
+                The legend, and the reason it exists: four `--state-*` hues
+                were already carrying the whole meaning of this picture, and
+                nothing on the page said what any of them meant. A visitor who
+                has never signed in read six coloured dots as decoration.
+
+                It carries COUNTS, so it is a readout rather than a colour key,
+                and the note under it closes the second gap the dial opened.
+                Pinned to the FOOT of the rail (`margin-top: auto`), which is
+                both where a legend belongs and what squares the rail's height
+                against the canvas beside it.
+              */}
+              <div className="landing-graph-legend" data-testid="landing-graph-legend">
+                <span className="landing-graph-legenditems">
+                  {TIER_ORDER.map((t) => (
+                    <span
+                      key={t}
+                      className="landing-graph-legenditem"
+                      data-testid={`landing-graph-legend-${t}`}
+                    >
+                      <StateDot tier={t} />
+                      <span className="landing-graph-legendname">{TIER_LABEL[t]}</span>
+                      <span className="landing-surface-mono">{counts[t]}</span>
+                    </span>
+                  ))}
+                </span>
+                <span className="landing-surface-mono landing-graph-legendnote">
+                  Ring = progress to mastery · {concepts.length} of {graph.conceptCount} shown
+                </span>
+              </div>
+            </div>
+          </div>
+        </div>
       </div>
     </section>
   );
diff --git a/frontend/src/components/marketing/graph/courseGraphs.test.ts b/frontend/src/components/marketing/graph/courseGraphs.test.ts
index 37272e01..8d6995a8 100644
--- a/frontend/src/components/marketing/graph/courseGraphs.test.ts
+++ b/frontend/src/components/marketing/graph/courseGraphs.test.ts
@@ -5,7 +5,17 @@
  */
 import { describe, it, expect } from 'vitest';
 
-import { COURSE_GRAPHS, TIER_COLOR, type CourseGraph } from './courseGraphs';
+import {
+  COURSE_GRAPHS,
+  TIER_COLOR,
+  TIER_LABEL,
+  TIER_ORDER,
+  conceptNodes,
+  neighbours,
+  tierCounts,
+  tierForMastery,
+  type CourseGraph,
+} from './courseGraphs';
 
 const ids = (g: CourseGraph) => new Set(g.nodes.map((n) => n.id));
 
@@ -84,6 +94,114 @@ describe('COURSE_GRAPHS', () => {
   );
 });
 
+/**
+ * The nodes now carry a numeric `mastery` as well as a `tier`, because the
+ * demo draws an arc for it. Two fields that can disagree need one authority:
+ * `tierForMastery`, ported from `backend/config.py::get_mastery_tier`. Without
+ * this suite a hand-authored node can paint a 90% ring in the struggling red.
+ */
+describe('COURSE_GRAPHS — mastery scores (#344 step 3)', () => {
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s scores every node in 0–1, agreeing with its tier',
+    (_code, g) => {
+      for (const n of g.nodes) {
+        expect(n.mastery, n.id).toBeGreaterThanOrEqual(0);
+        expect(n.mastery, n.id).toBeLessThanOrEqual(1);
+        expect(tierForMastery(n.mastery), n.id).toBe(n.tier);
+      }
+    },
+  );
+
+  /**
+   * The root's ring and the surface's chrome bar both print the COURSE
+   * number, so the root's score has to be the concepts' mean rather than an
+   * independently invented figure — otherwise the header contradicts the
+   * picture directly under it.
+   */
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s roots at the mean of its concepts',
+    (_code, g) => {
+      const concepts = conceptNodes(g);
+      expect(concepts).toHaveLength(g.nodes.length - 1);
+      const mean = concepts.reduce((sum, n) => sum + n.mastery, 0) / concepts.length;
+      const root = g.nodes.find((n) => n.id === g.rootId)!;
+      expect(root.mastery).toBeCloseTo(mean, 6);
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s draws a legible slice of a bigger course',
+    (_code, g) => {
+      expect(g.conceptCount).toBeGreaterThan(conceptNodes(g).length);
+      // The root blurb states the same number in prose ("… — 19 concepts
+      // mapped from your syllabus"); a mismatch is the surface arguing with
+      // its own detail panel.
+      expect(g.nodes.find((n) => n.id === g.rootId)!.blurb).toContain(String(g.conceptCount));
+    },
+  );
+
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s shows every tier at least once, so the legend is never a dead row',
+    (_code, g) => {
+      const counts = tierCounts(g);
+      for (const t of TIER_ORDER) expect(counts[t], `${g.id} ${t}`).toBeGreaterThan(0);
+      const total = TIER_ORDER.reduce((sum, t) => sum + counts[t], 0);
+      expect(total).toBe(conceptNodes(g).length);
+    },
+  );
+
+  /**
+   * The detail panel prints "N connections" and lists them. That count is the
+   * number of LINES a visitor can see leaving the node, so it reads `edges`,
+   * not the dead `children` field.
+   */
+  it.each(COURSE_GRAPHS.map((g) => [g.code, g] as const))(
+    '%s connects every node to at least one other, counted off the drawn edges',
+    (_code, g) => {
+      for (const n of g.nodes) {
+        const links = neighbours(g, n.id);
+        expect(links.length, n.id).toBeGreaterThan(0);
+        expect(new Set(links.map((l) => l.id)).size, `${n.id} duplicates`).toBe(links.length);
+        expect(links.some((l) => l.id === n.id), `${n.id} self-link`).toBe(false);
+      }
+    },
+  );
+});
+
+describe('tierForMastery', () => {
+  // The backend's cutoffs, restated as data so a drift in either direction is
+  // a failing test rather than a landing page that grades differently from
+  // the product.
+  it.each([
+    [1, 'mastered'],
+    [0.75, 'mastered'],
+    [0.7499, 'learning'],
+    [0.45, 'learning'],
+    [0.4499, 'struggling'],
+    [0.1, 'struggling'],
+    [0.0999, 'unexplored'],
+    [0, 'unexplored'],
+  ] as const)('scores %s as %s', (score, tier) => {
+    expect(tierForMastery(score)).toBe(tier);
+  });
+});
+
+describe('TIER_LABEL / TIER_ORDER', () => {
+  it('names every tier in the product’s own words', () => {
+    expect(TIER_LABEL).toEqual({
+      mastered: 'Mastered',
+      learning: 'Learning',
+      struggling: 'Struggling',
+      unexplored: 'Unexplored',
+    });
+  });
+
+  it('orders the legend strongest-first, covering every tier exactly once', () => {
+    expect([...TIER_ORDER]).toEqual(['mastered', 'learning', 'struggling', 'unexplored']);
+    expect(new Set(TIER_ORDER).size).toBe(Object.keys(TIER_COLOR).length);
+  });
+});
+
 /**
  * #344 visual 1 — this file shipped a FOURTH inlined copy of the mastery
  * palette (`#1B6C42` / `#D97706` / `#EF4444` / `#9CA3AF`), so the landing page
diff --git a/frontend/src/components/marketing/graph/courseGraphs.ts b/frontend/src/components/marketing/graph/courseGraphs.ts
index 0b9856d8..89563558 100644
--- a/frontend/src/components/marketing/graph/courseGraphs.ts
+++ b/frontend/src/components/marketing/graph/courseGraphs.ts
@@ -34,10 +34,55 @@ export const TIER_COLOR: Record<MasteryTier, string> = {
   unexplored: 'var(--state-neutral)',
 };
 
+/**
+ * The product's own words for the four tiers — byte-identical to `TIER_META`
+ * in `components/screens/Tree.tsx`, which is what a signed-in student reads
+ * next to these same four colours. The landing page's legend has to teach the
+ * vocabulary the app then uses, or it has taught the visitor nothing.
+ */
+export const TIER_LABEL: Record<MasteryTier, string> = {
+  mastered: 'Mastered',
+  learning: 'Learning',
+  struggling: 'Struggling',
+  unexplored: 'Unexplored',
+};
+
+/** Legend order: strongest first, so the ramp reads as a ramp. */
+export const TIER_ORDER: readonly MasteryTier[] = [
+  'mastered',
+  'learning',
+  'struggling',
+  'unexplored',
+] as const;
+
+/**
+ * The score → tier cutoffs, ported from `backend/config.py::get_mastery_tier`.
+ *
+ * The demo now draws a mastery ARC on every node, so each fixture node carries
+ * a numeric `mastery` alongside its `tier` — two fields that can disagree. They
+ * are held together by this function plus the fixture-integrity test, so a
+ * hand-authored node whose ring says 90% can never be painted "struggling".
+ * Same numbers as the backend on purpose: the ring a visitor reads here is the
+ * ring they get after signing in.
+ */
+export function tierForMastery(score: number): MasteryTier {
+  if (score >= 0.75) return 'mastered';
+  if (score >= 0.45) return 'learning';
+  if (score >= 0.1) return 'struggling';
+  return 'unexplored';
+}
+
 export interface DemoNode {
   id: string;
   label: string;
   tier: MasteryTier;
+  /**
+   * Mastery score, 0–1. Drives the arc swept around the node's ring and the
+   * meter in the detail panel. Must agree with `tier` via `tierForMastery`.
+   * On the root this is the COURSE aggregate — the mean of its concepts —
+   * which is also what the surface's chrome bar prints.
+   */
+  mastery: number;
   /** Shown on hover. One sentence, no trailing period. */
   blurb: string;
   /** Revealed when this node is expanded. Empty means leaf. */
@@ -55,23 +100,72 @@ export interface CourseGraph {
   code: string;
   name: string;
   rootId: string;
+  /**
+   * Concepts the real course carries. The demo draws a legible SLICE of them
+   * (five plus the root), and the chrome bar says so — "5 of 19 shown" — so
+   * the surface never implies a nineteen-concept course fits in six dots. Kept
+   * in step with the root blurb and with `UploadSurface`'s "19 concepts mapped
+   * onto MA 242" one band below.
+   */
+  conceptCount: number;
   nodes: DemoNode[];
   edges: DemoEdge[];
 }
 
+/** The drawn concepts — everything but the course anchor. */
+export function conceptNodes(graph: CourseGraph): DemoNode[] {
+  return graph.nodes.filter((n) => n.id !== graph.rootId);
+}
+
+/** Tier histogram over the drawn concepts. The legend's counts. */
+export function tierCounts(graph: CourseGraph): Record<MasteryTier, number> {
+  const counts: Record<MasteryTier, number> = {
+    mastered: 0,
+    learning: 0,
+    struggling: 0,
+    unexplored: 0,
+  };
+  for (const n of conceptNodes(graph)) counts[n.tier] += 1;
+  return counts;
+}
+
+/**
+ * Everything `id` shares a drawn edge with, in edge order.
+ *
+ * Reads `graph.edges` rather than `DemoNode.children` for the same reason
+ * `layout.ts::spanningTree` does: `children` is dead data that disagrees with
+ * the edges, and the detail panel's connection count has to be the count of
+ * lines a visitor can see running out of that node.
+ */
+export function neighbours(graph: CourseGraph, id: string): DemoNode[] {
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const out: DemoNode[] = [];
+  const seen = new Set<string>();
+  for (const e of graph.edges) {
+    const other = e.source === id ? e.target : e.target === id ? e.source : null;
+    if (!other || seen.has(other)) continue;
+    const node = byId.get(other);
+    if (!node) continue;
+    seen.add(other);
+    out.push(node);
+  }
+  return out;
+}
+
 export const COURSE_GRAPHS: CourseGraph[] = [
   {
     id: 'cs210',
     code: 'CS 210',
     name: 'Data Structures',
     rootId: 'cs-root',
+    conceptCount: 24,
     nodes: [
-      { id: 'cs-root', label: 'CS 210', tier: 'learning', blurb: 'Data Structures — 24 concepts mapped from your syllabus', children: ['cs-arrays', 'cs-recursion', 'cs-complexity'] },
-      { id: 'cs-arrays', label: 'Arrays', tier: 'mastered', blurb: 'Contiguous storage and index arithmetic', children: ['cs-sorting'] },
-      { id: 'cs-recursion', label: 'Recursion', tier: 'struggling', blurb: 'Base cases, call stack depth, and when to prefer iteration', children: ['cs-trees'] },
-      { id: 'cs-complexity', label: 'Big-O', tier: 'learning', blurb: 'Asymptotic bounds for time and space', children: [] },
-      { id: 'cs-sorting', label: 'Sorting', tier: 'learning', blurb: 'Comparison sorts and their lower bound', children: [] },
-      { id: 'cs-trees', label: 'Trees', tier: 'unexplored', blurb: 'Traversals, balance, and why recursion fits them', children: [] },
+      { id: 'cs-root', label: 'CS 210', tier: 'learning', mastery: 0.482, blurb: 'Data Structures — 24 concepts mapped from your syllabus', children: ['cs-arrays', 'cs-recursion', 'cs-complexity'] },
+      { id: 'cs-arrays', label: 'Arrays', tier: 'mastered', mastery: 0.9, blurb: 'Contiguous storage and index arithmetic', children: ['cs-sorting'] },
+      { id: 'cs-recursion', label: 'Recursion', tier: 'struggling', mastery: 0.28, blurb: 'Base cases, call stack depth, and when to prefer iteration', children: ['cs-trees'] },
+      { id: 'cs-complexity', label: 'Big-O', tier: 'learning', mastery: 0.62, blurb: 'Asymptotic bounds for time and space', children: [] },
+      { id: 'cs-sorting', label: 'Sorting', tier: 'learning', mastery: 0.55, blurb: 'Comparison sorts and their lower bound', children: [] },
+      { id: 'cs-trees', label: 'Trees', tier: 'unexplored', mastery: 0.06, blurb: 'Traversals, balance, and why recursion fits them', children: [] },
     ],
     edges: [
       { source: 'cs-root', target: 'cs-arrays' },
@@ -87,13 +181,14 @@ export const COURSE_GRAPHS: CourseGraph[] = [
     code: 'MA 242',
     name: 'Linear Algebra',
     rootId: 'ma-root',
+    conceptCount: 19,
     nodes: [
-      { id: 'ma-root', label: 'MA 242', tier: 'learning', blurb: 'Linear Algebra — 19 concepts mapped from your syllabus', children: ['ma-vectors', 'ma-matrices', 'ma-eigen'] },
-      { id: 'ma-vectors', label: 'Vector Spaces', tier: 'mastered', blurb: 'Span, basis, and dimension', children: ['ma-independence'] },
-      { id: 'ma-matrices', label: 'Matrices', tier: 'learning', blurb: 'Linear maps written as arrays of numbers', children: ['ma-determinant'] },
-      { id: 'ma-eigen', label: 'Eigenvalues', tier: 'struggling', blurb: 'Directions a transformation only scales', children: [] },
-      { id: 'ma-independence', label: 'Independence', tier: 'learning', blurb: 'When no vector is redundant', children: [] },
-      { id: 'ma-determinant', label: 'Determinant', tier: 'unexplored', blurb: 'Signed volume scaling of a transformation', children: [] },
+      { id: 'ma-root', label: 'MA 242', tier: 'learning', mastery: 0.498, blurb: 'Linear Algebra — 19 concepts mapped from your syllabus', children: ['ma-vectors', 'ma-matrices', 'ma-eigen'] },
+      { id: 'ma-vectors', label: 'Vector Spaces', tier: 'mastered', mastery: 0.93, blurb: 'Span, basis, and dimension', children: ['ma-independence'] },
+      { id: 'ma-matrices', label: 'Matrices', tier: 'learning', mastery: 0.66, blurb: 'Linear maps written as arrays of numbers', children: ['ma-determinant'] },
+      { id: 'ma-eigen', label: 'Eigenvalues', tier: 'struggling', mastery: 0.31, blurb: 'Directions a transformation only scales', children: [] },
+      { id: 'ma-independence', label: 'Independence', tier: 'learning', mastery: 0.52, blurb: 'When no vector is redundant', children: [] },
+      { id: 'ma-determinant', label: 'Determinant', tier: 'unexplored', mastery: 0.07, blurb: 'Signed volume scaling of a transformation', children: [] },
     ],
     edges: [
       { source: 'ma-root', target: 'ma-vectors' },
@@ -109,10 +204,11 @@ export const COURSE_GRAPHS: CourseGraph[] = [
     code: 'SM 275',
     name: 'Statistics',
     rootId: 'sm-root',
+    conceptCount: 21,
     nodes: [
-      { id: 'sm-root', label: 'SM 275', tier: 'learning', blurb: 'Statistics — 21 concepts mapped from your syllabus', children: ['sm-prob', 'sm-dist', 'sm-testing'] },
-      { id: 'sm-prob', label: 'Probability', tier: 'mastered', blurb: 'Sample spaces, events, and conditioning', children: ['sm-bayes'] },
-      { id: 'sm-dist', label: 'Distributions', tier: 'learning', blurb: 'Shapes that recur across real data', children: ['sm-clt'] },
+      { id: 'sm-root', label: 'SM 275', tier: 'learning', mastery: 0.47, blurb: 'Statistics — 21 concepts mapped from your syllabus', children: ['sm-prob', 'sm-dist', 'sm-testing'] },
+      { id: 'sm-prob', label: 'Probability', tier: 'mastered', mastery: 0.86, blurb: 'Sample spaces, events, and conditioning', children: ['sm-bayes'] },
+      { id: 'sm-dist', label: 'Distributions', tier: 'learning', mastery: 0.66, blurb: 'Shapes that recur across real data', children: ['sm-clt'] },
       // "Hypothesis Tests" was 16 characters — three more than any other label
       // in any fixture, and the widest object in the phone layout by a margin.
       // At the 390px breakpoint it overlapped its sibling "Distributions" by
@@ -120,9 +216,9 @@ export const COURSE_GRAPHS: CourseGraph[] = [
       // legible mobile type scale can separate them: the two labels need
       // 0.6·font·29/2 units of room against a ring that only yields 1.732·ring.
       // Shortening the label is the proportionate fix — not a collision solver.
-      { id: 'sm-testing', label: 'p-Values', tier: 'struggling', blurb: 'What a p-value does and does not claim', children: [] },
-      { id: 'sm-bayes', label: 'Bayes', tier: 'learning', blurb: 'Updating belief as evidence arrives', children: [] },
-      { id: 'sm-clt', label: 'Central Limit', tier: 'unexplored', blurb: 'Why sample means go normal', children: [] },
+      { id: 'sm-testing', label: 'p-Values', tier: 'struggling', mastery: 0.27, blurb: 'What a p-value does and does not claim', children: [] },
+      { id: 'sm-bayes', label: 'Bayes', tier: 'learning', mastery: 0.53, blurb: 'Updating belief as evidence arrives', children: [] },
+      { id: 'sm-clt', label: 'Central Limit', tier: 'unexplored', mastery: 0.03, blurb: 'Why sample means go normal', children: [] },
     ],
     edges: [
       { source: 'sm-root', target: 'sm-prob' },
diff --git a/frontend/src/components/marketing/graph/layout.test.ts b/frontend/src/components/marketing/graph/layout.test.ts
index e48876a2..a65c7aa6 100644
--- a/frontend/src/components/marketing/graph/layout.test.ts
+++ b/frontend/src/components/marketing/graph/layout.test.ts
@@ -304,12 +304,14 @@ describe('radialLayout', () => {
       code: 'X',
       name: 'X',
       rootId: 'r',
+      conceptCount: count,
       nodes: [
-        { id: 'r', label: 'r', tier: 'learning', blurb: '', children: [] },
+        { id: 'r', label: 'r', tier: 'learning', mastery: 0.5, blurb: '', children: [] },
         ...Array.from({ length: count }, (_, i) => ({
           id: `n${i}`,
           label: `n${i}`,
           tier: 'learning' as const,
+          mastery: 0.5,
           blurb: '',
           children: [],
         })),
@@ -361,10 +363,12 @@ describe('radialLayout', () => {
       code: 'X',
       name: 'X',
       rootId: 'r',
+      conceptCount: 5,
       nodes: ['r', 'a', 'b', 'a1', 'a2', 'a3'].map((id) => ({
         id,
         label: id,
         tier: 'learning' as const,
+        mastery: 0.5,
         blurb: '',
         children: [],
       })),