# Constitution

The ground rules for this knowledgebase. When a decision isn't covered here, pick
the option that keeps the material simple, honest, and hands-on, then add a line
here if it is likely to come up again.

## 1. Purpose

We build interactive learning material for data structures and algorithms.
Learners should come away able to *run the algorithm in their head*, not just
recognise it. Reading is the warm-up; doing is the point.

## 2. Every topic has three parts

1. **Brief** — the minimum theory needed to follow along: what the structure is,
   which rules it keeps, and the vocabulary used later. Aim for a five-minute
   read. Link out for depth rather than growing the brief.
2. **Walkthrough** — a curated example played step by step, with narration that
   explains *why* each step happens. The learner controls the pace (forward,
   back, auto-play) and can feed in their own inputs.
3. **Practice** — the same algorithm on randomised input. At each real decision
   point the algorithm makes, the learner picks from several options:
   - A right answer lets the animation continue.
   - A wrong answer is never just "wrong": say why the chosen option doesn't
     apply *to these specific nodes*, then explain the correct one.

## 3. Pedagogy

- **Ask about decisions, not trivia.** Questions sit where the algorithm itself
  branches (which case? which rotation? where does it go?).
- **Explanations come from the actual state.** Narration and feedback are
  generated from the data structure at that moment and name real values. No
  hand-written text that can drift out of sync with the code.
- **Randomise inputs, stabilise vocabulary.** Practice data must differ between
  plays so answers can't be memorised. Options that form a taxonomy (e.g. the
  fix-up cases) keep a fixed order so the taxonomy itself is learned; spatial
  options (e.g. positions in a tree) are shuffled.
- **Don't leak the answer.** While a question is open, nothing on screen
  (highlights, colours, labels, narration, the order of a list) may reveal it.
- **Don't let guessing pay.** Check how often each option position, and each
  answer to a yes/no question, is correct across many random runs. If one
  dominates, shuffle the options or ask a better question (e.g. "what is the new
  distance?" instead of "update or keep?").
- **One right answer.** Where the algorithm itself allows several valid choices (which neighbour
  first, how to break a tie), fix a stated convention, such as alphabetical order, so each question
  has exactly one answer, and say so in the brief.
- **No forced questions.** Don't ask when the state leaves only one possibility (the key must be in
  this leaf; after one matched character the answer is always 0). Narrate it instead.
- **Ask before the reveal.** If playing the step would show the answer (a search walking the trie,
  nodes being pruned), ask first and animate after.
- **Rounds of sensible length.** If random inputs make the number of questions swing widely, generate
  practice inputs whose round stays within a set range.
- **Same words everywhere.** Brief, walkthrough and practice use identical names
  for roles and cases (e.g. N, P, U, G).

## 4. Technology

- Plain HTML, CSS and JavaScript. No frameworks, no build step, no runtime
  dependencies, no network requests.
- Every page works when opened straight from disk (`file://`). That means
  classic `<script>` tags, not ES modules.
- Target current evergreen browsers. Use modern JS freely within that.
- Node's built-in test runner (`node --test`) is the only tooling, used for
  engine tests. It is not needed to view the material.

## 5. Architecture

Each topic separates three layers:

| Layer | Knows about | Must not |
| --- | --- | --- |
| **Engine** (`<topic>.js`) | The algorithm. Produces a *trace*: a list of steps, each with a state snapshot, narration, and an optional decision (prompt, options, correct answer, explanations). | Touch the DOM. |
| **View** (`shared/tree-view.js`, `array-view.js`, `graph-view.js`, `table-view.js`, `forest-view.js`, `grid-view.js`, `btree-view.js`, `trie-view.js`) | Drawing and animating snapshots. Reusable across topics. | Know about any particular algorithm. |
| **Lesson** (`shared/lesson.js`) | Tabs, walkthrough player, practice loop, scoring. Plays any engine's traces. | Re-implement algorithm logic or write explanations. |
| **App** (`app.js`) | Per-topic wiring: brief figures and the `Lesson.init` configuration. | Duplicate what the shared layers already do. |

The engine is the single source of truth. Walkthrough and practice play the
same traces; they only differ in whether the decision is shown or asked.

Engines export via `module.exports` when available and a global otherwise, so the
same file runs in the browser and in Node tests. Logic that several engines need
(e.g. BST search paths, rotations, the placement question) lives in DOM-free
shared modules such as `shared/bst.js`, loaded the same way.

When a second topic needs something the first one built inline, move it into
`shared/` rather than copying it. A topic may also build directly on another
topic's engine when the material does (heapsort extends the binary heap engine).

Engines keep keys distinct, so views can follow each value as it moves.

## 6. Visual & interaction language

- Shared design tokens live in `shared/base.css`; topics don't invent colours.
- Animation shows *transformation* (a node moving, a colour changing), typically
  300–700 ms. Honour `prefers-reduced-motion`.
- Support light and dark themes.
- Everything is keyboard-operable: number keys pick options, `Enter` continues,
  arrow keys step the walkthrough.
- Colour is never the only signal: narration names colours in words and is
  announced via `aria-live`.

## 7. Layout

```
index.html                 landing page listing topics
shared/                    base.css (tokens), lesson.css/.js (page player),
                           tree-view.js, array-view.js, graph-view.js, table-view.js,
                           forest-view.js, grid-view.js, btree-view.js,
                           trie-view.js (views),
                           bst.js, graph.js (engine helpers)
topics/<slug>/index.html   the topic page (brief, walkthrough, practice)
topics/<slug>/<slug>.js    the engine (DOM-free)
topics/<slug>/app.js       page wiring
tests/<slug>.test.js       engine tests
```

## 8. Definition of done for a topic

- Engine tests pass (`node --test`), including invariant checks over many
  random inputs and checks that each decision's correct answer matches what the
  engine actually did.
- Brief, walkthrough and practice all work from `file://` with no console errors.
- Every decision has a specific explanation for every wrong option.
- Factual claims in the brief about its own figures are checked by a test.
- Linked from `index.html`, in the track and position where it fits the learning path.