From db951f3feadffc682a92b288d335a2f1604c0f81 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 11:26:00 +0000 Subject: [PATCH] Add a tour for the curious as a sixth learning path Ten watchable pages for readers with no computer science background (sorting, searching, mazes, recursion gone wrong, a peek at attention), first on the home page. Paths may now have 8 to 25 steps. Each card's progress bar is named after its path, so screen readers can tell them apart now that one page can count toward two paths. The cards sit three to a row. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015Hhm4fvca2gU9R3a9ohe4W --- BRIEFING.md | 9 ++-- CHANGES.md | 4 ++ src/paths/PathCards.svelte | 9 ++-- src/paths/PathMeter.svelte | 8 +++- src/paths/data/tour.ts | 92 ++++++++++++++++++++++++++++++++++++++ src/paths/paths.test.ts | 10 +++-- src/paths/paths.ts | 3 +- tests/e2e/paths.spec.ts | 8 +++- 8 files changed, 128 insertions(+), 15 deletions(-) create mode 100644 src/paths/data/tour.ts diff --git a/BRIEFING.md b/BRIEFING.md index 424a0640..359f099f 100644 --- a/BRIEFING.md +++ b/BRIEFING.md @@ -44,10 +44,11 @@ the browser, exported as files, and embedded in Canvas. save examples on the server, sync preferences and hear about new pages. Signing in is never required; signed out, the site works as before and sends nothing. `PLAN.md` section 18. -- **Learning paths (2026-11-15, defaults taken, awaiting Yusuf):** five curated routes for kinds - of learner, each a page at `/path//` (`src/paths/`), with stages of 15 to 20 steps. A step is - one page, done when the page is finished (every lesson read, every check right), so progress - comes from what the site already stores and syncs. Free order with a highlighted next step. +- **Learning paths (2026-11-15, confirmed by Yusuf):** six curated routes for kinds of learner (a + short tour for the curious, then five courses), each a page at `/path//` (`src/paths/`) with + stages of 10 to 20 steps. A step is one page, done when the page is finished (every lesson read, + every check right), so progress comes from what the site already stores and syncs; practice + scores do not count. Free order with a highlighted next step. ## Non-goals (v1) diff --git a/CHANGES.md b/CHANGES.md index e21313f8..d8b52bc5 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -571,3 +571,7 @@ 2026-11-15 [decision] Learning paths: 5 curated routes (data structures, algorithms, interviews, LLMs, theory of computation), 15 to 20 pages each; recommended answers taken after 15 min without a reply, open to reversal 2026-11-15 [code] Learning paths (src/paths): /path// pages (prerendered, in sitemap and offline list), cards on the home page, a step bar on pages opened with #path=; step done = page finished + +2026-11-15 [decision] Yusuf: add a curious-beginner tour as a sixth path; practice scores do not count toward a step; path copy reviewed and accepted + +2026-11-15 [code] Path "A tour for the curious" (/path/tour/, 10 steps, first on the home page); paths may be 8 to 25 steps; each card's progress bar is named after its path; cards three a row diff --git a/src/paths/PathCards.svelte b/src/paths/PathCards.svelte index 39179b3a..b8067ab7 100644 --- a/src/paths/PathCards.svelte +++ b/src/paths/PathCards.svelte @@ -19,7 +19,7 @@ {path.blurb} {#if state.started} - + {:else}

{state.total} steps

{/if} @@ -44,8 +44,11 @@ ul { display: grid; - /* Five paths fit on one row of a wide screen. */ - grid-template-columns: repeat(auto-fill, minmax(min(100%, 200px), 1fr)); + /* Three paths a row on a wide screen (six paths, two even rows). */ + grid-template-columns: repeat( + auto-fill, + minmax(min(100%, max(240px, calc((100% - 20px) / 3))), 1fr) + ); gap: 10px; list-style: none; margin: 8px 0 0; diff --git a/src/paths/PathMeter.svelte b/src/paths/PathMeter.svelte index 74fa1967..1a6dfd04 100644 --- a/src/paths/PathMeter.svelte +++ b/src/paths/PathMeter.svelte @@ -2,7 +2,11 @@ import type { PathProgress } from './paths'; /** A path's progress: a bar, the percent, and the count of steps done. */ - let { state, compact = false }: { state: PathProgress; compact?: boolean } = $props(); + let { + state, + compact = false, + label = 'Path progress', + }: { state: PathProgress; compact?: boolean; label?: string } = $props();
@@ -13,7 +17,7 @@ aria-valuemax="100" aria-valuenow={state.percent} aria-valuetext="{state.percent}% complete, {state.finished} of {state.total} steps done" - aria-label="Path progress" + aria-label={label} >
diff --git a/src/paths/data/tour.ts b/src/paths/data/tour.ts new file mode 100644 index 00000000..8c005db4 --- /dev/null +++ b/src/paths/data/tour.ts @@ -0,0 +1,92 @@ +import type { PathDef } from '../paths'; + +const path: PathDef = { + id: 'tour', + title: 'A tour for the curious', + audience: 'Curious, no computer science needed', + blurb: 'Ten of the most watchable pages: sorting, searching, mazes, and a peek inside an LLM.', + intro: + 'No course, no exam, no prerequisites. These are ten pages worth watching even if you ' + + 'have never written a line of code. Press play on the suggested example and watch what ' + + 'happens; the narration says what each step does. Read the lessons and answer the checks ' + + 'if you want the step marked done. Or just watch. Nobody is grading this.', + stages: [ + { + title: 'Putting things in order', + steps: [ + { + viz: 'bubble-sort', + example: 'largest-last', + note: 'The simplest way to sort: swap neighbours that are out of order until nothing moves.', + }, + { + viz: 'merge-sort', + example: 'top-down', + note: 'A much faster way: split the list in half, sort each half, then zip them together.', + }, + ], + }, + { + title: 'Finding things fast', + steps: [ + { + viz: 'binary-search', + example: 'found', + note: 'Guess the middle, throw away half, repeat. Ten values take at most four guesses.', + }, + { + viz: 'bst', + example: 'balanced-order', + note: 'A tree where smaller goes left and larger goes right. Insert order decides how tall it gets.', + }, + ], + }, + { + title: 'Mazes and routes', + steps: [ + { + viz: 'grid-bfs', + example: 'maze', + note: 'Spread out from the start one ring at a time, and the first time you reach the exit is the shortest way.', + }, + { + viz: 'a-star', + example: 'manhattan', + note: 'The same search with a sense of direction. It heads for the goal and skips most of the grid.', + }, + ], + }, + { + title: 'When computers do too much', + steps: [ + { + viz: 'fibonacci-calls', + example: 'explosion', + note: 'A simple recipe that asks the same question 67 times to get one number.', + }, + { + viz: 'n-queens', + example: 'four-first', + note: 'Place queens so none attack each other. Watch it hit dead ends and back up.', + }, + { + viz: 'big-o-lab', + example: 'quadratic-wall', + note: 'Why programmers worry about this: a millisecond against 17 minutes on the same input.', + }, + ], + }, + { + title: 'A peek inside an LLM', + steps: [ + { + viz: 'self-attention', + example: 'cat-sat', + note: 'How a language model links "sat" to "cat": each word scores how much every other word matters.', + }, + ], + }, + ], +}; + +export default path; diff --git a/src/paths/paths.test.ts b/src/paths/paths.test.ts index f6f7c613..21eeff82 100644 --- a/src/paths/paths.test.ts +++ b/src/paths/paths.test.ts @@ -27,16 +27,18 @@ describe('learning paths', () => { expect(path.stages.every((s) => s.steps.length > 0)).toBe(true); }); - it('steps on live pages, each page once, in 12 to 25 steps', () => { + it('steps on live pages, each page once, in 8 to 25 steps', () => { for (const s of steps) expect(byId.has(s.viz), s.viz).toBe(true); expect(new Set(steps.map((s) => s.viz)).size).toBe(steps.length); - expect(steps.length).toBeGreaterThanOrEqual(12); + expect(steps.length).toBeGreaterThanOrEqual(8); expect(steps.length).toBeLessThanOrEqual(25); }); it('states its own number of steps, if it states one', () => { - for (const [, n] of path.blurb.matchAll(/\b(\d+) (?:pages|steps|small pictures)\b/g)) - expect(Number(n)).toBe(steps.length); + for (const [, n] of path.blurb.matchAll( + /\b(\d+|Ten) (?:of the most watchable )?(?:pages|steps|small pictures)\b/g, + )) + expect(n === 'Ten' ? 10 : Number(n)).toBe(steps.length); }); it('suggests examples the pages have', () => { diff --git a/src/paths/paths.ts b/src/paths/paths.ts index 8a5e3520..bc9515bb 100644 --- a/src/paths/paths.ts +++ b/src/paths/paths.ts @@ -5,6 +5,7 @@ import computation from './data/computation'; import dataStructures from './data/data-structures'; import interviews from './data/interviews'; import llms from './data/llms'; +import tour from './data/tour'; /** * Learning paths: a short, ordered route through the site for one kind of learner (a first data @@ -41,7 +42,7 @@ export interface PathDef { } /** Every path, in the order the home page shows them. */ -export const paths: PathDef[] = [dataStructures, algorithms, interviews, llms, computation]; +export const paths: PathDef[] = [tour, dataStructures, algorithms, interviews, llms, computation]; export const findPath = (id: string): PathDef | undefined => paths.find((p) => p.id === id); diff --git a/tests/e2e/paths.spec.ts b/tests/e2e/paths.spec.ts index b431149d..eb4488db 100644 --- a/tests/e2e/paths.spec.ts +++ b/tests/e2e/paths.spec.ts @@ -65,8 +65,14 @@ test('a path shows the share of steps finished and the next step', async ({ page // The home page card shows it too. await page.goto('/'); await expect( - page.getByRole('region', { name: 'Learning paths' }).getByRole('progressbar'), + page + .getByRole('region', { name: 'Learning paths' }) + .getByRole('progressbar', { name: 'A first data structures course: progress' }), ).toHaveAttribute('aria-valuenow', '21'); + // big-o-lab is a step of the tour too: 1 of its 10. + await expect( + page.getByRole('progressbar', { name: 'A tour for the curious: progress' }), + ).toHaveAttribute('aria-valuenow', '10'); // No horizontal scroll, on any viewport. await page.goto('/path/data-structures/');