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 @@ +