From 676fc2989cf601e98a4ef7d8da27818998ecd243 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 09:26:03 +0000 Subject: [PATCH] Add five learning paths with their own pages and progress Curated routes for five kinds of learner (a first data structures course, an algorithms course, coding interview prep, how LLMs work, theory of computation), 15 to 20 pages each in named stages. - /path// pages, prerendered with their own title and description, in the sitemap and the offline list - cards on the home page with the percent of steps done - a step bar on a page opened from a path (#path=): step n of N, progress, the step's note, previous and next - a step opens on a suggested curated example; it is done when the page is finished, so progress comes from what the site already stores Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015Hhm4fvca2gU9R3a9ohe4W --- BRIEFING.md | 5 + CHANGES.md | 4 + scripts/prerender.mjs | 47 +++++--- src/paths/PathBar.svelte | 102 ++++++++++++++++ src/paths/PathCards.svelte | 91 ++++++++++++++ src/paths/PathMeter.svelte | 54 +++++++++ src/paths/PathPage.svelte | 193 ++++++++++++++++++++++++++++++ src/paths/data/algorithms.ts | 143 ++++++++++++++++++++++ src/paths/data/computation.ts | 113 +++++++++++++++++ src/paths/data/data-structures.ts | 137 +++++++++++++++++++++ src/paths/data/interviews.ts | 144 ++++++++++++++++++++++ src/paths/data/llms.ts | 128 ++++++++++++++++++++ src/paths/paths.test.ts | 139 +++++++++++++++++++++ src/paths/paths.ts | 95 +++++++++++++++ src/ui/App.svelte | 4 + src/ui/Catalog.svelte | 2 + src/ui/VizPage.svelte | 16 ++- src/ui/route.ts | 14 ++- tests/e2e/paths.spec.ts | 94 +++++++++++++++ 19 files changed, 1507 insertions(+), 18 deletions(-) create mode 100644 src/paths/PathBar.svelte create mode 100644 src/paths/PathCards.svelte create mode 100644 src/paths/PathMeter.svelte create mode 100644 src/paths/PathPage.svelte create mode 100644 src/paths/data/algorithms.ts create mode 100644 src/paths/data/computation.ts create mode 100644 src/paths/data/data-structures.ts create mode 100644 src/paths/data/interviews.ts create mode 100644 src/paths/data/llms.ts create mode 100644 src/paths/paths.test.ts create mode 100644 src/paths/paths.ts create mode 100644 tests/e2e/paths.spec.ts diff --git a/BRIEFING.md b/BRIEFING.md index eb3c8335..424a0640 100644 --- a/BRIEFING.md +++ b/BRIEFING.md @@ -44,6 +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. + ## Non-goals (v1) - LTI grade passback diff --git a/CHANGES.md b/CHANGES.md index e8e01c90..e21313f8 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -567,3 +567,7 @@ 2026-11-15 [doc] HANDOFF.md rewritten as the closing handoff of this session, with a to-do list (shared-code suggestions, two page fixes, CI time); PR to main, merged by fast-forward once CI passes, on Yusuf's "create pr, merge" 2026-11-15 [note] Deployed 08:18 UTC on Yusuf's "create pr, merge": main fb02fc9..17bd730 by fast-forward, which merged PR #2 (footer credit, closing handoff). CI 243 green. Bundle index-Dwyn5AT1.js matches; 276 addresses 200 with the footer and mark once; the footer reads "Created by Yusuf Pisan" with the link; no account requests. Session ready to archive + +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 diff --git a/scripts/prerender.mjs b/scripts/prerender.mjs index 57cefdc0..16c8dbf2 100644 --- a/scripts/prerender.mjs +++ b/scripts/prerender.mjs @@ -40,23 +40,39 @@ try { if (!template.includes('
')) throw new Error('Unexpected dist/index.html'); fs.writeFileSync(path.join(dist, 'index.html'), template); - for (const def of vizzes) { - const title = `${def.title} · ${SITE_NAME}`; - const url = `${SITE_URL}/${def.id}/`; + // A page of the app at // with its own title, description, preview tags and canonical URL. + const writePage = (dir, name, blurb, needs) => { + const title = `${name} · ${SITE_NAME}`; + const url = `${SITE_URL}/${dir}/`; let html = template.replace(/[^<]*<\/title>/, `<title>${esc(title)}`); - html = setMeta(html, 'name', 'description', def.blurb); + html = setMeta(html, 'name', 'description', blurb); html = setMeta(html, 'property', 'og:title', title); - html = setMeta(html, 'property', 'og:description', def.blurb); + html = setMeta(html, 'property', 'og:description', blurb); html = setMeta(html, 'property', 'og:url', url); html = html.replace('', ` \n `); html = html.replace( '
', - `
\n `, + `
\n `, ); - fs.mkdirSync(path.join(dist, def.id), { recursive: true }); - fs.writeFileSync(path.join(dist, def.id, 'index.html'), html); + fs.mkdirSync(path.join(dist, dir), { recursive: true }); + fs.writeFileSync(path.join(dist, dir, 'index.html'), html); + }; + for (const def of vizzes) + writePage(def.id, def.title, def.blurb, 'This interactive visualization'); + + // Learning paths (src/paths): /path//. A step on a page that is not live fails the build. + const { paths, pathSteps } = await server.ssrLoadModule('/src/paths/paths.ts'); + const liveIds = new Set(vizzes.map((d) => d.id)); + for (const p of paths) { + const missing = pathSteps(p).filter((s) => !liveIds.has(s.viz)); + if (missing.length) + throw new Error( + `src/paths: path "${p.id}" has steps on pages not live: ${missing.map((s) => s.viz)}`, + ); + writePage(`path/${p.id}`, p.title, p.blurb, 'This learning path'); } + const pathDirs = paths.map((p) => `path/${p.id}`); // Catalog thumbnails: the steps of one example per page, stripped to bare shapes. // previews.json holds the still pictures; previews/.json the frames, fetched on first play. @@ -70,7 +86,11 @@ try { } fs.writeFileSync(path.join(dist, 'previews.json'), JSON.stringify(posters)); - const urls = [`${SITE_URL}/`, ...vizzes.map((d) => `${SITE_URL}/${d.id}/`)]; + const urls = [ + `${SITE_URL}/`, + ...pathDirs.map((d) => `${SITE_URL}/${d}/`), + ...vizzes.map((d) => `${SITE_URL}/${d.id}/`), + ]; fs.writeFileSync( path.join(dist, 'sitemap.xml'), `\n\n` + @@ -82,7 +102,7 @@ try { `User-agent: *\nAllow: /\nSitemap: ${SITE_URL}/sitemap.xml\n`, ); console.log( - `prerendered ${vizzes.length} visualization pages, ${Object.keys(previews).length} previews`, + `prerendered ${vizzes.length} visualization pages, ${pathDirs.length} paths, ${Object.keys(previews).length} previews`, ); // The releases (src/releases.ts), for the platform's email about new pages: each page with its @@ -120,10 +140,7 @@ try { .readdirSync(dist, { recursive: true }) .map((f) => String(f).split(path.sep).join('/')) .filter((f) => fs.statSync(path.join(dist, f)).isFile()); - const entries = offlineList( - files, - vizzes.map((d) => d.id), - ); + const entries = offlineList(files, [...vizzes.map((d) => d.id), ...pathDirs]); const read = (f) => fs.readFileSync(path.join(dist, f)); const shell = shellList(entries, read('index.html').toString('utf8')); const worker = fs.readFileSync(path.resolve('src/pwa/sw.js'), 'utf8'); diff --git a/src/paths/PathBar.svelte b/src/paths/PathBar.svelte new file mode 100644 index 00000000..5f92f51a --- /dev/null +++ b/src/paths/PathBar.svelte @@ -0,0 +1,102 @@ + + + + + diff --git a/src/paths/PathCards.svelte b/src/paths/PathCards.svelte new file mode 100644 index 00000000..39179b3a --- /dev/null +++ b/src/paths/PathCards.svelte @@ -0,0 +1,91 @@ + + +
+

Learning paths

+

Not sure where to start? Pick a path and follow it one page at a time.

+ +
+ + diff --git a/src/paths/PathMeter.svelte b/src/paths/PathMeter.svelte new file mode 100644 index 00000000..74fa1967 --- /dev/null +++ b/src/paths/PathMeter.svelte @@ -0,0 +1,54 @@ + + +
+
+ +
+

+ {state.percent}% + · {state.finished} of {state.total} steps done +

+
+ + diff --git a/src/paths/PathPage.svelte b/src/paths/PathPage.svelte new file mode 100644 index 00000000..1aaab175 --- /dev/null +++ b/src/paths/PathPage.svelte @@ -0,0 +1,193 @@ + + +{#if !path || !state} +
+

Not here yet

+

There is no learning path called "{id}" on this site.

+

See all visualizations

+
+{:else} +
+

← All visualizations

+
+

{path.audience}

+

{path.title}

+

{path.intro}

+
+ +
+ + {#if state.next} + + {state.finished || state.started ? 'Continue' : 'Start'}: step {state.next.n}, + {vizTitle(state.next.step.viz)} + + {:else} +

All {state.total} steps done.

+ {/if} +
+ + {#each path.stages as stage, si (stage.title)} +
+

{stage.title}

+
    + {#each stage.steps as step (step.viz)} + {@const s = state.steps.find((x) => x.step === step)!} +
  1. + +
    + {vizTitle(step.viz)} +

    {step.note}

    +

    + {#if s.summary.finished} + Done + {:else if s.summary.started} + {summaryText(s.summary)} + {:else} + Not started + {/if} +

    +
    + {#if s.summary.started}{/if} +
  2. + {/each} +
+
+ {/each} +
+{/if} + + diff --git a/src/paths/data/algorithms.ts b/src/paths/data/algorithms.ts new file mode 100644 index 00000000..d260d2a5 --- /dev/null +++ b/src/paths/data/algorithms.ts @@ -0,0 +1,143 @@ +import type { PathDef } from '../paths'; + +const path: PathDef = { + id: 'algorithms', + title: 'An algorithms course', + audience: 'Students in a first algorithms course', + blurb: 'Sorting, divide and conquer, greedy, dynamic programming and graphs in 20 pages.', + intro: + 'An algorithms course is mostly a handful of ideas used over and over: split the problem, ' + + 'make the obvious choice, remember what you already worked out. Each step is one page. ' + + 'Play the suggested example, read the lessons, and answer the checks; the step is done when ' + + 'every lesson is read and every check is right. If a data structure on the way is new to ' + + 'you, the data structures path has it.', + stages: [ + { + title: 'Counting the cost', + steps: [ + { + viz: 'loop-counting', + example: 'triangle', + note: 'Count the steps of a loop inside a loop. The triangle is where n²/2 comes from.', + }, + { + viz: 'master-theorem', + example: 'merge-sort', + note: 'T(n) = 2T(n/2) + n, drawn as a tree. You will see this recurrence all term.', + }, + ], + }, + { + title: 'Sorting and searching', + steps: [ + { + viz: 'binary-search', + example: 'lower-bound', + note: 'Halve the range each time. The off-by-one mistakes live in the variants, so start with lower bound.', + }, + { + viz: 'insertion-sort', + example: 'nearly-sorted', + note: 'O(n²) in the worst case and close to O(n) on nearly sorted input. Both matter.', + }, + { + viz: 'merge-sort', + example: 'top-down', + note: 'Split in half, sort each half, merge. O(n log n) every time, at the cost of extra space.', + }, + { + viz: 'quick-sort', + example: 'sorted-worst', + note: 'Usually the fastest in practice. Here is the input that makes a bad pivot rule O(n²).', + }, + { + viz: 'counting-sort', + example: 'stable', + note: 'No comparisons, so the n log n lower bound does not apply. It needs small keys.', + }, + ], + }, + { + title: 'Divide and conquer, and greedy', + steps: [ + { + viz: 'quickselect', + example: 'median', + note: 'Quicksort that only follows one side: the median in O(n) on average.', + }, + { + viz: 'karatsuba', + example: 'three-products', + note: 'Three multiplications instead of four, and the running time drops below n².', + }, + { + viz: 'activity-selection', + example: 'shortest-fails', + note: 'Greedy works when you pick the right rule. Shortest first is the wrong one.', + }, + { + viz: 'huffman', + example: 'abracadabra', + note: 'Merge the two rarest symbols, again and again. The result is an optimal prefix code.', + }, + ], + }, + { + title: 'Dynamic programming', + steps: [ + { + viz: 'fibonacci-calls', + example: 'explosion', + note: 'The same calls over and over. This is the problem dynamic programming solves.', + }, + { + viz: 'dp-change', + example: 'greedy-fails', + note: 'Greedy change-making fails for some coin sets. The table does not.', + }, + { + viz: 'dp-lcs', + example: 'row-by-row', + note: 'A two-dimensional table filled row by row, then walked backwards for the answer.', + }, + { + viz: 'dp-knapsack', + example: 'greedy-fails', + note: 'Take it or leave it, for every item and every capacity.', + }, + ], + }, + { + title: 'Graph algorithms', + steps: [ + { + viz: 'topo-indegree', + example: 'paths-dag', + note: 'Order tasks so every arrow points forward, by removing vertices with nothing coming in.', + }, + { + viz: 'dijkstra', + example: 'negative-edge', + note: 'Shortest paths, closest first. It assumes no negative edges, and this example shows why.', + }, + { + viz: 'bellman-ford', + example: 'negative-cycle', + note: 'Slower, but it handles negative edges and tells you when a negative cycle exists.', + }, + { + viz: 'kruskal', + example: 'lightest-first', + note: 'Minimum spanning tree: take the lightest edge that does not make a cycle.', + }, + { + viz: 'max-flow', + example: 'take-flow-back', + note: 'Push flow along paths, and push it back when a better route turns up.', + }, + ], + }, + ], +}; + +export default path; diff --git a/src/paths/data/computation.ts b/src/paths/data/computation.ts new file mode 100644 index 00000000..efd6aac7 --- /dev/null +++ b/src/paths/data/computation.ts @@ -0,0 +1,113 @@ +import type { PathDef } from '../paths'; + +const path: PathDef = { + id: 'computation', + title: 'Theory of computation', + audience: 'Students in automata, formal languages or computability', + blurb: 'Finite automata to the halting problem in 15 pages.', + intro: + 'Three machines, each more powerful than the last, and the question of what none of them ' + + 'can do. Each step is one page. Run the machine on the suggested input, read the lessons, ' + + 'and answer the checks; the step is done when every lesson is read and every check is ' + + 'right. The constructions (NFA to DFA, grammar to normal form) are easier to follow when ' + + 'you step through them than when you read them.', + stages: [ + { + title: 'Finite automata', + steps: [ + { + viz: 'dfa', + example: 'div-by-3', + note: 'One state at a time, one move per symbol. This one checks divisibility by 3.', + }, + { + viz: 'nfa', + example: 'third-from-end', + note: 'Several states at once. Easier to design, and no more powerful.', + }, + { + viz: 'nfa-to-dfa', + example: 'third-from-end', + note: 'The subset construction, and why the DFA can need many more states.', + }, + { + viz: 'dfa-minimization', + example: 'table-filling', + note: 'Merge the states that no input can tell apart.', + }, + { + viz: 'regex-to-nfa', + example: 'ends-in-abb', + note: 'Regular expressions and finite automata describe the same languages. Here is one direction.', + }, + ], + }, + { + title: 'What finite automata cannot do', + steps: [ + { + viz: 'pumping-lemma', + example: 'winning-string', + note: 'The pumping lemma as a game against an opponent. Choosing the string is most of the proof.', + }, + { + viz: 'myhill-nerode', + example: 'anbn-classes', + note: 'Count the words a machine must keep apart. Infinitely many means not regular.', + }, + ], + }, + { + title: 'Grammars and pushdown automata', + steps: [ + { + viz: 'cfg-derivation', + example: 'two-trees', + note: 'Rules that rewrite symbols. Two parse trees for one string means the grammar is ambiguous.', + }, + { + viz: 'pda', + example: 'a-n-b-n', + note: 'A finite automaton with a stack, enough for aⁿbⁿ.', + }, + { + viz: 'cfg-to-cnf', + example: 'every-stage', + note: 'Chomsky normal form, one stage at a time. Needed for the next step.', + }, + { + viz: 'cyk', + example: 'anbn', + note: 'Is this string in the language? A table over substrings answers it in O(n³).', + }, + ], + }, + { + title: 'Turing machines and their limits', + steps: [ + { + viz: 'turing-machine', + example: 'zeros-ones', + note: 'A tape, a head and a few rules. As far as we know, this is everything a computer can do.', + }, + { + viz: 'multitape-tm', + example: 'palindrome', + note: 'More tapes are faster but no more powerful.', + }, + { + viz: 'halting-problem', + example: 'whole-argument', + note: 'No program can decide whether every program halts. The proof is a diagonal.', + }, + { + viz: 'chomsky-hierarchy', + example: 'whole-map', + note: 'Everything in this path on one map. Where does each language you met belong?', + }, + ], + }, + ], +}; + +export default path; diff --git a/src/paths/data/data-structures.ts b/src/paths/data/data-structures.ts new file mode 100644 index 00000000..f1c6dbcf --- /dev/null +++ b/src/paths/data/data-structures.ts @@ -0,0 +1,137 @@ +import type { PathDef } from '../paths'; + +const path: PathDef = { + id: 'data-structures', + title: 'A first data structures course', + audience: 'Students taking (or retaking) data structures', + blurb: 'Arrays to graphs in 19 pages, in the order most courses teach them.', + intro: + 'This is roughly the order a first data structures course follows. Each step is ' + + 'one page. Play the suggested example, read the lessons, and answer the checks; the step ' + + 'is done when every lesson is read and every check is right. Skip around if you like. ' + + 'The path keeps track either way.', + stages: [ + { + title: 'Before the structures', + steps: [ + { + viz: 'memory-model', + example: 'reassign-vs-mutate', + note: 'Every structure here is values and references. Get this wrong and linked lists will hurt.', + }, + { + viz: 'big-o-lab', + example: 'quadratic-wall', + note: 'Why we care about O(n) against O(n²): at a million items, a millisecond against 17 minutes.', + }, + ], + }, + { + title: 'Lines of things', + steps: [ + { + viz: 'dynamic-array', + example: 'amortized', + note: 'The array that grows. Doubling makes append cheap on average, even though some appends copy everything.', + }, + { + viz: 'stack-array', + example: 'lifo', + note: 'Last in, first out, with an array and one integer.', + }, + { + viz: 'queue-array', + example: 'wraparound', + note: 'First in, first out. The trick is letting the front wrap around the end.', + }, + { + viz: 'linked-list', + example: 'head-order', + note: 'Nodes and next pointers. Insert at the head is O(1); finding anything is O(n).', + }, + { + viz: 'doubly-linked-list', + example: 'four-updates', + note: 'A pointer back as well. Count the four pointers that change on every insert.', + }, + ], + }, + { + title: 'Trees', + steps: [ + { + viz: 'binary-tree', + example: 'four-orders', + note: 'Preorder, inorder, postorder and level order on the same tree.', + }, + { + viz: 'bst', + example: 'delete-two-children', + note: 'Smaller to the left, larger to the right. Delete is the hard case, so start there.', + }, + { + viz: 'avl', + example: 'sorted-input', + note: 'Sorted input turns a plain BST into a list. Rotations keep this one short.', + }, + ], + }, + { + title: 'Heaps and hashing', + steps: [ + { + viz: 'binary-heap', + example: 'build-bottom-up', + note: 'A tree stored in an array. Building it bottom-up is O(n), which surprises most people.', + }, + { + viz: 'hash-chaining', + example: 'collisions', + note: 'Two keys, one bucket. Chaining keeps a list in each one.', + }, + { + viz: 'hash-open', + example: 'primary-clustering', + note: 'No lists: probe for the next free slot, and watch the clusters grow.', + }, + { + viz: 'hash-rehash', + example: 'doubling', + note: 'Past a load factor the table grows and every key moves. Watch what a power-of-2 size does to these keys.', + }, + ], + }, + { + title: 'Graphs', + steps: [ + { + viz: 'graph-representations', + example: 'sparse', + note: 'Adjacency matrix or adjacency list. Most graphs you meet are sparse, so mostly lists.', + }, + { + viz: 'bfs', + example: 'layers', + note: 'A queue visits the graph one layer at a time, so it finds fewest-edge paths.', + }, + { + viz: 'dfs', + example: 'stack-order', + note: 'Swap the queue for a stack (or recursion) and you go deep first.', + }, + { + viz: 'dijkstra', + example: 'closest-first', + note: 'BFS with weights: a priority queue picks the closest vertex next.', + }, + { + viz: 'disjoint-sets', + example: 'compression', + note: 'Union and find, nearly O(1) each. You will need it for Kruskal.', + }, + ], + }, + ], +}; + +export default path; diff --git a/src/paths/data/interviews.ts b/src/paths/data/interviews.ts new file mode 100644 index 00000000..aacae5d7 --- /dev/null +++ b/src/paths/data/interviews.ts @@ -0,0 +1,144 @@ +import type { PathDef } from '../paths'; + +const path: PathDef = { + id: 'interviews', + title: 'Coding interview prep', + audience: 'Anyone preparing for technical interviews', + blurb: 'The patterns behind most interview problems, in 19 pages, starting with a map.', + intro: + 'Most interview problems are a few patterns in disguise. The trick is spotting which one, ' + + 'so the path starts with a map of problem cues and the pattern each one points to. Each ' + + 'step after that is one pattern. Play the suggested example, read the lessons, and answer ' + + 'the checks; the step is done when every lesson is read and every check is right. Then try ' + + 'the practice questions, since that is closest to the real thing. If you have two weeks, ' + + 'do a stage every two or three days.', + stages: [ + { + title: 'Start with the map', + steps: [ + { + viz: 'pattern-map', + example: 'whole-map', + note: 'Problem cues on one side, patterns on the other. Come back to it after each stage.', + }, + ], + }, + { + title: 'Arrays and strings', + steps: [ + { + viz: 'two-pointers', + example: 'find-pair', + note: 'A sorted array and two indices walking towards each other: O(n) instead of O(n²).', + }, + { + viz: 'sliding-window', + example: 'grow-and-shrink', + note: 'Grow the window on the right, shrink it on the left. Each index moves at most n times.', + }, + { + viz: 'prefix-sum-hashmap', + example: 'count-with-negatives', + note: 'Subarrays that sum to k, with negative numbers. A sliding window cannot do this one.', + }, + { + viz: 'frequency-counting', + example: 'count-signatures', + note: 'Count letters in a hash map. Anagrams, first unique character and friends.', + }, + { + viz: 'monotonic-stack', + example: 'next-greater', + note: 'Next greater element in one pass. Each value is pushed and popped once.', + }, + ], + }, + { + title: 'Lists, intervals and heaps', + steps: [ + { + viz: 'fast-slow-pointers', + example: 'odd-middle', + note: 'One pointer moves twice as fast. The middle of a list without counting it first.', + }, + { + viz: 'merge-intervals', + example: 'sort-then-merge', + note: 'Sort by start, then one pass. Most interval problems start this way.', + }, + { + viz: 'top-k', + example: 'best-three', + note: 'Keep a heap of size k: O(n log k), and it works on a stream.', + }, + { + viz: 'k-way-merge', + example: 'three-lists', + note: 'A heap holds the head of every list, so the smallest is always on top.', + }, + ], + }, + { + title: 'Search and backtracking', + steps: [ + { + viz: 'binary-search-answer', + example: 'ship-in-three-days', + note: 'Binary search over the answer, not the array. Look for "smallest value that works".', + }, + { + viz: 'state-space-bfs', + example: 'three-wheels', + note: 'Fewest moves means BFS. The vertices are states of the puzzle, not cells of a grid.', + }, + { + viz: 'combination-sum', + example: 'sort-and-prune', + note: 'Try a choice, recurse, undo it. Sorting first lets you stop early.', + }, + ], + }, + { + title: 'Dynamic programming', + steps: [ + { + viz: 'dp-grid-paths', + example: 'count-with-walls', + note: 'Each cell from the cell above and the cell to its left. The gentlest DP there is.', + }, + { + viz: 'dp-lis', + example: 'patience', + note: 'Longest increasing subsequence in O(n log n), with piles of cards.', + }, + { + viz: 'dp-state-machine', + example: 'cooldown-sell-early', + note: 'Buy and sell problems: a few states per day and the moves between them.', + }, + ], + }, + { + title: 'Design a data structure', + steps: [ + { + viz: 'lru-cache', + example: 'hit-moves-to-front', + note: 'A hash map and a doubly linked list, for O(1) get and put. Asked everywhere.', + }, + { + viz: 'min-stack', + example: 'mins-on-the-side', + note: 'The minimum in O(1): keep a second stack of minimums.', + }, + { + viz: 'rate-limiter', + example: 'bucket-refills', + note: 'A system design favourite. Compare a token bucket with a fixed window.', + }, + ], + }, + ], +}; + +export default path; diff --git a/src/paths/data/llms.ts b/src/paths/data/llms.ts new file mode 100644 index 00000000..36a72ace --- /dev/null +++ b/src/paths/data/llms.ts @@ -0,0 +1,128 @@ +import type { PathDef } from '../paths'; + +const path: PathDef = { + id: 'llms', + title: 'How LLMs work', + audience: 'Programmers curious about what is inside an LLM', + blurb: 'From text to tokens to attention to the next word, in 17 small pictures.', + intro: + 'A large language model is a lot of arithmetic, but the ideas fit on a handful of pages. ' + + 'Every page here runs a tiny model you can step through: a few words, a few dimensions, ' + + 'numbers small enough to check by hand. Each step is one page. Play the suggested example, ' + + 'read the lessons, and answer the checks; the step is done when every lesson is read and ' + + 'every check is right. No calculus needed until the training stage, and not much then.', + stages: [ + { + title: 'Text into numbers', + steps: [ + { + viz: 'bpe-tokenizer', + example: 'toy-corpus', + note: 'Models do not see words. Merge the most common pair of symbols, again and again, and you get tokens.', + }, + { + viz: 'embeddings', + example: 'kitten-cosine', + note: 'Each token becomes a list of numbers. Similar meanings end up pointing the same way.', + }, + { + viz: 'word2vec', + example: 'one-pass', + note: 'Where those numbers come from: nudge words that appear together closer.', + }, + ], + }, + { + title: 'Predicting the next token', + steps: [ + { + viz: 'ngram-lm', + example: 'count-bigrams', + note: 'The simplest language model: count which word follows which.', + }, + { + viz: 'sampling', + example: 'hot', + note: 'The model gives probabilities; temperature, top-k and top-p decide which word you get.', + }, + { + viz: 'beam-search', + example: 'greedy-misses', + note: 'Taking the likeliest word each time can miss the likeliest sentence.', + }, + ], + }, + { + title: 'Inside the transformer', + steps: [ + { + viz: 'self-attention', + example: 'cat-sat', + note: 'Each word looks at the others and decides which ones matter. This is the core idea.', + }, + { + viz: 'multi-head-attention', + example: 'two-heads', + note: 'Several attention patterns side by side, each free to look for something different.', + }, + { + viz: 'positional-encoding', + example: 'rope-turns', + note: 'Attention ignores word order on its own. This is how order gets back in.', + }, + { + viz: 'transformer-block', + example: 'first-word', + note: 'Attention, a small network, and the residual stream, stacked into one block.', + }, + ], + }, + { + title: 'Training', + steps: [ + { + viz: 'backpropagation', + example: 'chain', + note: 'The chain rule, one node at a time: how much each weight is to blame.', + }, + { + viz: 'gradient-descent', + example: 'converge', + note: 'Step downhill, and watch what the step size does. Then try momentum and Adam.', + }, + { + viz: 'lora', + example: 'rank-two-reaches', + note: 'Fine-tuning by training two thin matrices instead of the whole weight matrix.', + }, + ], + }, + { + title: 'Serving and retrieval', + steps: [ + { + viz: 'kv-cache', + example: 'one-by-one', + note: 'Why generating the hundredth token does not redo the first ninety-nine.', + }, + { + viz: 'speculative-decoding', + example: 'one-round', + note: 'A small model guesses ahead and the big one checks several guesses at once.', + }, + { + viz: 'bm25', + example: 'cat-mat', + note: 'Retrieval before vectors: an inverted index and a score for word matches.', + }, + { + viz: 'hnsw', + example: 'greedy-misses', + note: 'Nearest neighbours among millions of embeddings by walking a graph, and where a greedy walk gets stuck.', + }, + ], + }, + ], +}; + +export default path; diff --git a/src/paths/paths.test.ts b/src/paths/paths.test.ts new file mode 100644 index 00000000..f6f7c613 --- /dev/null +++ b/src/paths/paths.test.ts @@ -0,0 +1,139 @@ +import { describe, expect, it } from 'vitest'; +import { emptyProgress, type Progress } from '../progress/progress'; +import { parseLocation, vizHref } from '../ui/route'; +import { vizzes } from '../viz/all'; +import { findPath, pathProgress, paths, pathSteps, stepOf, vizTitle, type PathDef } from './paths'; + +const byId = new Map(vizzes.map((d) => [d.id, d])); + +describe('learning paths', () => { + it('have unique ids that are safe in an address', () => { + const ids = paths.map((p) => p.id); + expect(new Set(ids).size).toBe(ids.length); + for (const id of ids) expect(id).toMatch(/^[a-z0-9]+(-[a-z0-9]+)*$/); + }); + + for (const path of paths) { + describe(path.id, () => { + const steps = pathSteps(path); + + it('has text everywhere, without em dashes or placeholders', () => { + const texts = [path.title, path.audience, path.blurb, path.intro]; + texts.push(...path.stages.map((s) => s.title), ...steps.map((s) => s.note)); + for (const t of texts) { + expect(t.trim().length).toBeGreaterThan(2); + expect(t).not.toMatch(/—|\bTODO\b|\bTBD\b|undefined/); + } + expect(path.stages.every((s) => s.steps.length > 0)).toBe(true); + }); + + it('steps on live pages, each page once, in 12 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).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); + }); + + it('suggests examples the pages have', () => { + for (const s of steps.filter((x) => x.example)) { + const ids = byId.get(s.viz)!.examples.map((e) => e.id); + expect(ids, `${s.viz}: ${s.example}`).toContain(s.example); + } + }); + + it('names every step by its catalog title', () => { + for (const s of steps) expect(vizTitle(s.viz)).not.toBe(s.viz); + }); + }); + } +}); + +describe('pathProgress', () => { + const path: PathDef = { + id: 'test', + title: 'Test', + audience: 'Tests', + blurb: 'A path for tests.', + intro: 'A path for tests.', + stages: [ + { title: 'One', steps: [{ viz: 'a', note: 'a' }] }, + { + title: 'Two', + steps: [ + { viz: 'b', note: 'b' }, + { viz: 'c', note: 'c' }, + ], + }, + ], + }; + const at = '2026-11-15T00:00:00.000Z'; + const finished = (lessons: string[]) => ({ + lessons: Object.fromEntries(lessons.map((l) => [l, { done: true, at }])), + checks: {}, + practice: {}, + outline: { lessons, checks: [], at }, + }); + + it('starts at zero with the first step next', () => { + const s = pathProgress(emptyProgress(), path); + expect(s).toMatchObject({ total: 3, finished: 0, started: 0, percent: 0 }); + expect(s.next?.n).toBe(1); + }); + + it('counts finished pages, rounds down, and points at the first one not finished', () => { + const p: Progress = { + ...emptyProgress(), + pages: { + a: finished(['x', 'y']), + c: finished(['z']), + b: { ...finished(['x', 'y']), lessons: { x: { done: true, at } } }, + }, + }; + const s = pathProgress(p, path); + expect(s).toMatchObject({ finished: 2, started: 3, percent: 66 }); + expect(s.next?.step.viz).toBe('b'); + expect(s.next?.n).toBe(2); + }); + + it('reaches 100 with nothing next', () => { + const p: Progress = { + ...emptyProgress(), + pages: { a: finished(['x']), b: finished(['x']), c: finished(['x']) }, + }; + expect(pathProgress(p, path)).toMatchObject({ percent: 100, next: undefined }); + }); + + it('finds a step by page', () => { + expect(stepOf(path, 'c')).toMatchObject({ n: 3, step: { viz: 'c' } }); + expect(stepOf(path, 'nope')).toBeUndefined(); + }); +}); + +describe('path addresses', () => { + it('parses /path// as a path page', () => { + expect(parseLocation('/path/data-structures/', '')).toEqual({ + kind: 'path', + id: 'data-structures', + key: '/path/data-structures/', + }); + }); + + it('carries the path on a visualization page, but not inside a lesson list', () => { + expect(vizHref('bst', { path: 'data-structures' })).toBe('/bst/#path=data-structures'); + expect(vizHref('bst', { path: 'data-structures', list: 'L', item: 2 })).toBe( + '/bst/#list=L&item=2', + ); + const r = parseLocation('/bst/', '#path=data-structures'); + expect(r.kind === 'viz' && r.path).toBe('data-structures'); + }); + + it('knows each path by id', () => { + for (const p of paths) expect(findPath(p.id)).toBe(p); + expect(findPath('nope')).toBeUndefined(); + }); +}); diff --git a/src/paths/paths.ts b/src/paths/paths.ts new file mode 100644 index 00000000..8a5e3520 --- /dev/null +++ b/src/paths/paths.ts @@ -0,0 +1,95 @@ +import { pageSummary, type PageSummary, type Progress } from '../progress/progress'; +import { families } from '../viz/catalog'; +import algorithms from './data/algorithms'; +import computation from './data/computation'; +import dataStructures from './data/data-structures'; +import interviews from './data/interviews'; +import llms from './data/llms'; + +/** + * Learning paths: a short, ordered route through the site for one kind of learner (a first data + * structures course, interview preparation, how LLMs work, ...). Each path has its own page, + * /path//, written by scripts/prerender.mjs. A step is one visualization page, done when the + * page is finished (every lesson read and every check answered right, `pageSummary`), so a path's + * progress comes from the progress the site already keeps and syncs; nothing new is stored. + */ +export interface PathStep { + /** The visualization's id, as in src/viz/catalog.ts. */ + viz: string; + /** One line: why this page comes here, and what to look for. */ + note: string; + /** A curated example of that page to open first (its `id` in examples/*.json). */ + example?: string; +} + +export interface PathStage { + title: string; + steps: PathStep[]; +} + +export interface PathDef { + /** The address is /path//. */ + id: string; + title: string; + /** Who it is for, in a few words, for the card on the home page. */ + audience: string; + /** One sentence for the card and the page's description. */ + blurb: string; + /** A paragraph or two at the top of the path's page. */ + intro: string; + stages: PathStage[]; +} + +/** Every path, in the order the home page shows them. */ +export const paths: PathDef[] = [dataStructures, algorithms, interviews, llms, computation]; + +export const findPath = (id: string): PathDef | undefined => paths.find((p) => p.id === id); + +export const pathSteps = (path: PathDef): PathStep[] => path.stages.flatMap((s) => s.steps); + +/** A page's title as the catalog shows it. */ +export const vizTitle = (viz: string): string => + families.flatMap((f) => f.items).find((i) => i.id === viz)?.title ?? viz; + +/** The step of a path on page `viz`, and its number (1 for the first). */ +export function stepOf(path: PathDef, viz: string): { n: number; step: PathStep } | undefined { + const i = pathSteps(path).findIndex((s) => s.viz === viz); + return i < 0 ? undefined : { n: i + 1, step: pathSteps(path)[i]! }; +} + +export const pathHref = (id: string): string => `/path/${id}/`; + +export interface StepStatus { + step: PathStep; + /** 1 for the first step of the path. */ + n: number; + summary: PageSummary; +} + +export interface PathProgress { + steps: StepStatus[]; + total: number; + finished: number; + started: number; + /** Whole percent of steps finished, rounded down so 100 means every step. */ + percent: number; + /** The first step not finished yet, or undefined once every step is. */ + next: StepStatus | undefined; +} + +export function pathProgress(p: Progress, path: PathDef): PathProgress { + const steps = pathSteps(path).map((step, i) => ({ + step, + n: i + 1, + summary: pageSummary(p, step.viz), + })); + const finished = steps.filter((s) => s.summary.finished).length; + return { + steps, + total: steps.length, + finished, + started: steps.filter((s) => s.summary.started).length, + percent: steps.length ? Math.floor((100 * finished) / steps.length) : 0, + next: steps.find((s) => !s.summary.finished), + }; +} diff --git a/src/ui/App.svelte b/src/ui/App.svelte index 4edbabd5..e701fdf4 100644 --- a/src/ui/App.svelte +++ b/src/ui/App.svelte @@ -6,6 +6,7 @@ import type { AnyVizDef, SavedExample } from '../engine/types'; import { REPO_URL, SITE_NAME } from '../site'; import ListsRoute from '../lists/ListsRoute.svelte'; + import PathPage from '../paths/PathPage.svelte'; import { loadViz } from '../viz/registry'; import AccountMenu from './AccountMenu.svelte'; import AppStatus from './AppStatus.svelte'; @@ -175,6 +176,8 @@ {:else if route.kind === 'lists' || route.kind === 'list'} {#key route.key}{/key} + {:else if route.kind === 'path'} + {#key route.key}{/key} {:else if route.kind === 'viz'} {#if unavailable} @@ -207,6 +210,7 @@ practiceCount={route.practiceCount} list={route.list} item={route.item} + path={route.path} /> {/key} {:else if viz === null} diff --git a/src/ui/Catalog.svelte b/src/ui/Catalog.svelte index 63e51e78..657c7314 100644 --- a/src/ui/Catalog.svelte +++ b/src/ui/Catalog.svelte @@ -5,6 +5,7 @@ import { pageSummary } from '../progress/progress'; import { families, isLive, pathways, type Pathway } from '../viz/catalog'; import NewSince from './NewSince.svelte'; + import PathCards from '../paths/PathCards.svelte'; import PreviewThumb from './PreviewThumb.svelte'; import ProgressMark from './ProgressMark.svelte'; import ProgressOverview from './ProgressOverview.svelte'; @@ -76,6 +77,7 @@ +