feat: render inline schematics and surface deep lessons

Add a declarative schematic engine (src/ui/schematic.ts) that turns a small
JSON spec into a self-contained SVG via a schematic fence in renderMarkdown.
It gives diagrams (e.g. view-vs-copy on a shared buffer) a home in lessons,
matching the memory-canvas palette.

Surface the per-topic deep lesson: the level lesson modal now shows the full
per-level lesson (objective, lesson, what this teaches, field notes) and a
Deep-lesson button; the levels modal gets a per-series deep-lesson entry point.

Write the numpy series deep lesson (ELI5 to ELI-PHD) with an embedded
view-vs-copy schematic as the worked exemplar.

Author: alisadeghiaghili

src/levels/index.ts

@@ -50,3 +50,10 @@ export function getLevel(id: string): Level | null {
 export function levelIndex(id: string): number {
   return allLevels().findIndex((l) => l.id === id);
 }
+
+/**
+ * The series a level belongs to (for its deep lesson), or null.
+ */
+export function sequenceForLevel(id: string): Sequence | null {
+  return sequences.find((s) => s.levels.some((l) => l.id === id)) ?? null;
+}

src/levels/numpy.ts

@@ -4,11 +4,107 @@
 
 import { preds } from '../engine/checks';
 import type { Sequence } from '../engine/types';
+import { schematicBlock, type SchematicSpec } from '../ui/schematic';
+
+/**
+ * The one picture the whole series is built on: a window over a buffer, where
+ * a slice is a second window over the SAME buffer (dashed) and a copy owns its
+ * own separate buffer.
+ */
+const VIEW_VS_COPY: SchematicSpec = {
+  id: 'numpy-view-vs-copy',
+  title: 'A window over a buffer — view vs copy',
+  nodes: [
+    { id: 'a', label: 'a', sub: 'ndarray · own' },
+    { id: 'v', label: 'v = a[:2]', sub: 'ndarray · view' },
+    { id: 'c', label: 'b = a.copy()', sub: 'ndarray · own' },
+    { id: 'bufA', label: 'buffer A', sub: 'float64[3]', type: 'buffer' },
+    { id: 'bufB', label: 'buffer B', sub: 'float64[2]', type: 'buffer' },
+  ],
+  edges: [
+    { from: 'a', to: 'bufA', label: 'owns' },
+    { from: 'v', to: 'bufA', label: 'same buffer', dashed: true },
+    { from: 'c', to: 'bufB', label: 'owns (new)' },
+  ],
+  legend: [
+    { color: 'amber', label: 'points at / owns' },
+    { color: 'coral', label: 'shares the buffer' },
+  ],
+};
 
 export const series: Sequence[] = [
   {
     id: 'numpy',
     title: 'NumPy: Buffers & Views',
+    deepLesson: `## ELI5
+
+A numpy array is like a **frame** you slide over a row of beads. The beads (the
+numbers) sit in one long, unbroken row — that row is the **buffer**. The frame
+is the **array**: it just says "start here, show this many beads." When you take
+a slice, you don't copy any beads; you make a *smaller frame* over the **same**
+row. When you copy, you pour the beads into a brand-new row.
+
+${schematicBlock(VIEW_VS_COPY)}
+
+## ELI10
+
+Two objects, always. \`np.array([1, 2, 3])\` allocates a **buffer** (a flat,
+contiguous run of raw numbers) and an **ndarray** — a *window* (an offset plus a
+length) that says which part of that buffer to show. The name \`a\` points at the
+window; the window points at the buffer.
+
+- \`a.copy()\` reads \`a\`'s buffer and mints a **second** buffer with the same
+  numbers. Two windows, two buffers — edits to one are invisible to the other.
+- \`a[:2]\` makes a **view**: a second window over the *same* buffer. No data
+  moves; only the offset and length change.
+- Because a view shares its buffer, \`v[0] = 9\` writes into the shared run, and
+  \`a\` sees the change. A copy, never.
+
+## ELI15
+
+The mental model that matters in real code: **a slice is a view, not a copy.**
+This is the single most common numpy foot-gun.
+
+- A slice \`a[i:j]\` is O(1) — it allocates a new window, moves no data, and
+  shares the buffer. The result's \`base\` attribute points back at the original.
+- Any operation that *builds new data* (an element-wise op like \`a + 1\`, a
+  fancy index, \`a.copy()\`) allocates a **fresh** buffer.
+- So the question to always ask: *does this expression share my data, or make
+  new data?* Chaining views is free; chaining real operations is where you pay
+  memory.
+
+## ELI20
+
+The memory mechanics, precisely.
+
+- A buffer is one contiguous \`float64\` run. An ndarray stores \`{buffer,
+  offset, shape, dtype, view}\`. Two ndarrays are "the same data" iff they
+  point at the same buffer box (that is exactly what the RAM view's shared
+  window strip shows).
+- Element-wise ops are vectorized: \`a + 1\` reads \`a\`'s window and writes a
+  new buffer. Chained expressions allocate an intermediate buffer per step —
+  the cost to watch in a hot loop.
+- \`a.sum()\` is a reduction over the window: one pass, a scalar out, no new
+  buffer.
+- Watch the RAM tab while you do this: addresses are monotonic, the buffer row
+  shows its raw byte cells, and each view paints its \`[offset..offset+shape)\`
+  window as a strip aligned to those cells.
+
+## ELI-PHD
+
+Where this model pays off and where it breaks.
+
+- **Strides & broadcast**: real ndarrays carry a stride, so a non-contiguous
+  slice is still a view (a window with a non-1 stride). This visualizer keeps a
+  flat 1-D window to stay honest about the buffer, and says so in the lessons.
+- **\`base\` / \`.copy()\` contract**: in production, \`arr.base\` is the canonical
+  "does this view own its data" check; \`copy(arr)\` and \`arr.copy()\` are the
+  escape hatch. A view outliving its buffer is the classic memory-safety trap.
+- **Performance**: prefer in-place ops and views when you don't need the
+  independence, and \`np.ascontiguousarray\` before a call that wants
+  contiguity. The identity picture — shared vs owned buffer — is the whole
+  decision: copy only when you must own the data.
+`,
     levels: [
       {
         id: 'np-make-array',

src/style.css

@@ -1184,6 +1184,35 @@ button.ghost,
   border-color: color-mix(in srgb, var(--ok) 40%, var(--line));
 }
 
+.series-deep {
+  margin-top: 10px;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-family: var(--mono);
+  font-size: 11px;
+  color: var(--teal);
+  background: color-mix(in srgb, var(--teal) 10%, var(--panel-2));
+  border: 1px solid color-mix(in srgb, var(--teal) 40%, var(--line));
+  border-radius: 8px;
+  padding: 5px 10px;
+  cursor: pointer;
+  transition: border-color 160ms var(--ease), background 160ms var(--ease);
+}
+
+.series-deep:hover {
+  border-color: var(--teal);
+  background: color-mix(in srgb, var(--teal) 20%, var(--panel-2));
+}
+
+/* —— Inline schematics (deep-lesson diagrams) —— */
+.modal-body .schematic {
+  background: var(--panel);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  padding: 8px;
+}
+
 .level-row .id {
   font-family: var(--mono);
   color: var(--haze);

src/ui/app.ts

@@ -7,9 +7,9 @@
 
 import { createSession, type Session, referenceEdges, liveObjectIds } from '../engine/session';
 import { checkGoal } from '../engine/checks';
-import type { GoalSpec, Level, MemoryState, Snapshot } from '../engine/types';
+import type { GoalSpec, Level, MemoryState, Sequence, Snapshot } from '../engine/types';
 import { splitPythonStatements } from '../engine/steps';
-import { allLevels, getLevel, levelIndex, sequences } from '../levels/index';
+import { allLevels, getLevel, levelIndex, sequenceForLevel, sequences } from '../levels/index';
 import { renderMemory, renderRam } from './memory';
 import { BoardView } from './board';
 import { TerminalView } from './terminal';
@@ -695,7 +695,10 @@ export class App {
             </button>`;
           })
           .join('');
-        return `<div class="series-block"><h3>${escapeHtml(s.title)}</h3><div class="level-list">${rows}</div></div>`;
+        const deepBtn = s.deepLesson
+          ? `<button type="button" class="series-deep" data-deep="${escapeHtml(s.id)}" title="Read the full ${escapeHtml(s.title)} lesson (ELI5→ELI-PHD)">▤ deep lesson</button>`
+          : '';
+        return `<div class="series-block"><h3>${escapeHtml(s.title)}</h3><div class="level-list">${rows}</div>${deepBtn}</div>`;
       })
       .join('');
 
@@ -720,18 +723,57 @@ export class App {
         if (id) this.enterLevel(id, { openLesson: true });
       });
     });
+    modal.el.querySelectorAll<HTMLButtonElement>('[data-deep]').forEach((btn) => {
+      btn.addEventListener('click', () => {
+        const seq = sequences.find((s) => s.id === btn.dataset.deep);
+        modal.close();
+        if (seq) this.openDeepLesson(seq);
+      });
+    });
   }
 
   private openLesson(): void {
     if (!this.level) {
       this.openWelcome();
       return;
     }
-    const lesson =
-      this.level.brief + '\n\n' + (this.level.hint ? `**Hint:** ${this.level.hint}` : '');
+    const level = this.level;
+    const seq = sequenceForLevel(level.id);
+    const parts: string[] = [];
+    parts.push(`### ${level.name}`);
+    parts.push(level.brief);
+    if (level.lesson) {
+      parts.push('');
+      parts.push(level.lesson);
+    }
+    if (level.learning?.length) {
+      parts.push('', '### What this teaches');
+      for (const b of level.learning) parts.push(`- ${b}`);
+    }
+    if (level.fieldNotes?.length) {
+      parts.push('', '### In production');
+      for (const n of level.fieldNotes) parts.push(`- ${n}`);
+    }
+    if (level.hint) {
+      parts.push('', `**Hint:** ${level.hint}`);
+    }
+    const actions: ModalSpec['actions'] = [];
+    if (seq?.deepLesson) {
+      actions.push({ label: 'Deep lesson', className: 'ghost', onClick: () => this.openDeepLesson(seq) });
+    }
+    actions.push({ label: 'Close', className: 'primary', onClick: () => this.terminal.focus() });
+    showModal({
+      title: level.name,
+      bodyHtml: renderMarkdown(parts.join('\n')),
+      actions,
+      onDismiss: () => this.terminal.focus(),
+    });
+  }
+
+  private openDeepLesson(seq: Sequence): void {
     showModal({
-      title: `${this.level.name}`,
-      bodyHtml: renderMarkdown(lesson),
+      title: `${seq.title} — deep lesson`,
+      bodyHtml: renderMarkdown(seq.deepLesson ?? ''),
       actions: [{ label: 'Close', className: 'primary', onClick: () => this.terminal.focus() }],
       onDismiss: () => this.terminal.focus(),
     });

src/ui/dialog.ts

@@ -2,6 +2,8 @@
  * HTML escaping, minimal markdown, and modal dialogs (ported from learn-r).
  */
 
+import { parseSchematic, renderSchematic } from './schematic';
+
 export function escapeHtml(s: string): string {
   return s
     .replaceAll('&', '&')
@@ -134,15 +136,33 @@ function renderProse(text: string): string {
   return out.join('');
 }
 
+/**
+ * Parse + render a ```schematic block, or fall back to showing the raw source
+ * if the spec is malformed (a broken diagram should read as data, not vanish).
+ */
+function renderSchematicSafe(json: string): string {
+  try {
+    return renderSchematic(parseSchematic(json));
+  } catch {
+    return `<pre class="md-code" data-lang="schematic"><code>${escapeHtml(json)}</code></pre>`;
+  }
+}
+
 export function renderMarkdown(md: string): string {
   const blocks = md.split(/```/);
   let html = '';
   blocks.forEach((block, i) => {
     if (i % 2 === 1) {
       const firstNewline = block.indexOf('\n');
       const lang = firstNewline >= 0 ? block.slice(0, firstNewline).trim() : '';
-      const code = firstNewline >= 0 ? block.slice(firstNewline + 1) : block;
-      html += `<pre class="md-code"${lang ? ` data-lang="${escapeHtml(lang)}"` : ''}><code>${escapeHtml(code.trimEnd())}</code></pre>`;
+      const code = (firstNewline >= 0 ? block.slice(firstNewline + 1) : block).trimEnd();
+      if (lang === 'schematic') {
+        // A diagram: render the JSON spec to an inline SVG. On any parse error
+        // fall back to showing the raw source so a broken spec degrades visibly.
+        html += renderSchematicSafe(code);
+      } else {
+        html += `<pre class="md-code"${lang ? ` data-lang="${escapeHtml(lang)}"` : ''}><code>${escapeHtml(code)}</code></pre>`;
+      }
     } else {
       const sections = block.split(/(^#{1,3}\s+.*$)/m);
       for (const sec of sections) {