Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions BRIEFING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<id>/` (`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/<id>/` (`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)

Expand Down
4 changes: 4 additions & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<id>/ pages (prerendered, in sitemap and offline list), cards on the home page, a step bar on pages opened with #path=<id>; 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
9 changes: 6 additions & 3 deletions src/paths/PathCards.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
<span class="blurb">{path.blurb}</span>
</a>
{#if state.started}
<PathMeter {state} compact />
<PathMeter {state} compact label="{path.title}: progress" />
{:else}
<p class="muted steps">{state.total} steps</p>
{/if}
Expand All @@ -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;
Expand Down
8 changes: 6 additions & 2 deletions src/paths/PathMeter.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -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();
</script>

<div class="meter" class:compact>
Expand All @@ -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}
>
<span class="fill" style:width="{state.percent}%"></span>
</div>
Expand Down
92 changes: 92 additions & 0 deletions src/paths/data/tour.ts
Original file line number Diff line number Diff line change
@@ -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;
10 changes: 6 additions & 4 deletions src/paths/paths.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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', () => {
Expand Down
3 changes: 2 additions & 1 deletion src/paths/paths.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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);

Expand Down
8 changes: 7 additions & 1 deletion tests/e2e/paths.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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/');
Expand Down
Loading