feat(ux): worked numerical examples + math foundations in HelpModal

Raschka-style: every help modal now carries (1) the schematic tensor-
flow SVG, (2) a concrete numerical worked example with small matrices
showing real values in cells coloured by a diverging heatmap, and (3)
a list of math-foundation links to 3Blue1Brown / distill.pub /
Raschka / Alammar / EleutherAI / Maarten Grootendorst, each with a
one-sentence gloss + a one-sentence key insight.

New diagrams primitives in TensorDiagram.tsx:
  • MatrixGrid — N×M cells, per-cell heatmap colour, shape badge,
    role-coded left rail (q amber / k cyan / v violet / attn blue
    / out green / gate yellow / hidden grey / mask muted).
  • heatmapColor — diverging pink → mid → role-tinted ramp.
  • MathLink — chip-shaped link with gloss text.
  • CellRole + role tint table for canonical Raschka/3B1B/Distill
    palette on a dark #0e1014 background.

New data modules:
  • worked_examples.ts — 6 concrete examples (attention, mlp, moe,
    rmsnorm, softmax, dot_product) with full Q/K/V/scores/probs/y
    tensors. RMSNorm example proves ‖y‖_RMS=1 numerically.
  • math_foundations.ts — 14 canonical concepts (vector_norm,
    rms_norm, dot_product, matmul, softmax, attention, RoPE,
    residual stream, layernorm, gradient descent, backprop,
    selective SSM, MoE, LoRA) — each verified to 200 OK.
  • TOPIC_FOUNDATIONS + TOPIC_WORKED_EXAMPLES — registry mapping
    HelpIcon topic strings to the relevant examples/foundations.

New auto-rendering component: WorkedExampleDiagram lays out a
WorkedExample's tensors in column-major step order, drawing arrows
with operation labels between them. Handles 1-D / 2-D / 3-D tensors
(3-D shows head 0 with a chip; head stacks would blow the modal
width).

HelpModal: three sections rendered when applicable:
  1. "Tensor flow" — schematic SVG diagram (existing).
  2. "Worked example" — concrete numerical matrices (new).
  3. "Math foundations" — links + glosses (new).

Two background research agents informed the work: Exa+Brave+Perplexity
deep-research on (a) the visual idiom across Raschka / 3Blue1Brown /
Distill / Jay Alammar (palette, matrix-rendering style, dimensions,
notation conventions), and (b) canonical "explained-for-humans" links
per concept. URLs all HEAD-verified 200.

Fix: pre-existing TS error in App.tsx where `snap.spec.dim_env` was
used but the wireSpecRef snapshot exposes `dimEnv` (not nested under
spec). Switched to `snap.dimEnv` so inspect.histogram's brick-context
path compiles.

Tests: 11 new vitest (worked-example registry shape + RMSNorm=1
assertion + dot-product=11 cell render + HelpModal three-section
integration + per-topic coverage). One existing TensorDiagrams test
loosened from getByTestId('tensor-diagram') to
getAllByTestId(...).length ≥ 1 because both schematic + worked-example
now render the test-id at the same time. Regression: 522/522 vitest.

Author: apstenku123

vbgui/src/App.tsx

@@ -1953,7 +1953,7 @@ export function App(): JSX.Element {
                       const params = (node.data as {
                         params?: Record<string, unknown> })
                         ?.params ?? {};
-                      const dim_env = snap.spec.dim_env;
+                      const dim_env = snap.dimEnv;
                       const minimal_spec = {
                         graph: {
                           nodes: [

vbgui/src/components/HelpIcon.tsx

@@ -4,7 +4,11 @@
 
 import { useState } from "react";
 import { createPortal } from "react-dom";
-import { TENSOR_DIAGRAMS } from "./diagrams";
+import {
+  TENSOR_DIAGRAMS, TOPIC_WORKED_EXAMPLES, WORKED_EXAMPLES,
+  TOPIC_FOUNDATIONS, MATH_FOUNDATIONS,
+  WorkedExampleDiagram, MathLink,
+} from "./diagrams";
 import { T } from "@/theme";
 
 export interface HelpTopic {
@@ -1051,6 +1055,41 @@ export function HelpModal({ topic, onClose }: HelpModalProps): JSX.Element {
                   </Section>
                 ) : null;
               })()}
+              {(() => {
+                const exKey = TOPIC_WORKED_EXAMPLES[topic];
+                const ex = exKey ? WORKED_EXAMPLES[exKey] : null;
+                return ex ? (
+                  <Section label="Worked example"
+                            testid="help-modal-worked-example">
+                    <WorkedExampleDiagram example={ex} />
+                  </Section>
+                ) : null;
+              })()}
+              {(() => {
+                const keys = TOPIC_FOUNDATIONS[topic] ?? [];
+                if (keys.length === 0) return null;
+                return (
+                  <Section label="Math foundations"
+                            testid="help-modal-math-foundations">
+                    {keys.map((k) => {
+                      const m = MATH_FOUNDATIONS[k];
+                      if (!m) return null;
+                      return (
+                        <div key={k} style={{ marginBottom: 4 }}>
+                          <MathLink topic={k}
+                                     gloss={m.gloss}
+                                     url={m.urls[0]?.url ?? "#"} />
+                          <div style={{ color: "#94a3b8",
+                                         fontSize: 11,
+                                         padding: "2px 12px 6px" }}>
+                            <em>{m.key_insight}</em>
+                          </div>
+                        </div>
+                      );
+                    })}
+                  </Section>
+                );
+              })()}
               <Section label="Why" testid="help-modal-why">
                 {entry.why}
               </Section>

vbgui/src/components/diagrams/TensorDiagram.tsx

@@ -21,19 +21,75 @@ import { type ReactNode } from "react";
 
 
 export const DIAG_THEME = {
-  bg:        "rgba(15, 23, 42, 0.6)",
-  border:    "rgba(255, 255, 255, 0.05)",
+  bg:        "#0e1014",   // Raschka/3B1B-style deep neutral
+  bgPanel:   "rgba(20, 23, 28, 0.85)",
+  border:    "rgba(255, 255, 255, 0.06)",
   tensorBg:  "#1e293b",
   tensorFg:  "#22d3ee",
   opBg:      "#312e81",
   opFg:      "#818cf8",
-  arrow:     "#94a3b8",
-  residual:  "#facc15",
-  text:      "#f1f5f9",
-  textMuted: "#94a3b8",
+  arrow:     "#9aa0a6",
+  residual:  "#f5b841",
+  text:      "#e8e8e8",
+  textMuted: "#9aa0a6",
+  // Role-coded hues per the unified Raschka + 3B1B + Distill style:
+  roleQ:     "#f5b841",  // amber — query
+  roleK:     "#4ec9b0",  // cyan  — key
+  roleV:     "#b48ead",  // violet — value
+  roleAttn:  "#5aa9e6",  // blue — attention
+  roleAttnL: "#d96c8e",  // pink low end of attn heatmap
+  roleOut:   "#7bc47f",  // green — output
+  masked:    "#3a3f47",
 } as const;
 
 
+export type CellRole = "q" | "k" | "v" | "attn" | "out" | "gate"
+                       | "hidden" | "raw" | "mask";
+
+const ROLE_TINT: Record<CellRole, string> = {
+  q:      DIAG_THEME.roleQ,
+  k:      DIAG_THEME.roleK,
+  v:      DIAG_THEME.roleV,
+  attn:   DIAG_THEME.roleAttn,
+  out:    DIAG_THEME.roleOut,
+  gate:   "#fbbf24",
+  hidden: "#94a3b8",
+  raw:    "#64748b",
+  mask:   DIAG_THEME.masked,
+};
+
+
+/** Map a float (clipped to [-clip, +clip]) to a hex colour:
+ *  blue (high) → muted (zero) → pink (low). Used by MatrixGrid for
+ *  per-cell heatmap rendering. */
+export function heatmapColor(
+  value: number, clip: number = 2.0, role: CellRole = "raw",
+): string {
+  const v = Math.max(-clip, Math.min(clip, value));
+  const t = (v + clip) / (2 * clip);     // [0,1]
+  // Diverging palette: pink (0) → grey (0.5) → blue/role (1).
+  const lo = { r: 0xd9, g: 0x6c, b: 0x8e };
+  const mid = { r: 0x24, g: 0x29, b: 0x33 };
+  const hiHex = ROLE_TINT[role] === ROLE_TINT.raw
+    ? "#5aa9e6" : ROLE_TINT[role];
+  const hi = {
+    r: parseInt(hiHex.slice(1, 3), 16),
+    g: parseInt(hiHex.slice(3, 5), 16),
+    b: parseInt(hiHex.slice(5, 7), 16),
+  };
+  const lerp = (a: number, b: number, k: number): number =>
+    Math.round(a + (b - a) * k);
+  const c = t < 0.5
+    ? { r: lerp(lo.r, mid.r, t * 2),
+        g: lerp(lo.g, mid.g, t * 2),
+        b: lerp(lo.b, mid.b, t * 2) }
+    : { r: lerp(mid.r, hi.r, (t - 0.5) * 2),
+        g: lerp(mid.g, hi.g, (t - 0.5) * 2),
+        b: lerp(mid.b, hi.b, (t - 0.5) * 2) };
+  return `rgb(${c.r}, ${c.g}, ${c.b})`;
+}
+
+
 export interface DiagramProps {
   width?: number;
   height?: number;
@@ -227,6 +283,141 @@ export function Residual({
 }
 
 
+/* ===========================================================
+   MatrixGrid + RoleTensor + dataflow worked-example primitives
+   =========================================================== */
+
+
+export interface MatrixGridProps {
+  /** Top-left x in SVG user-space. */
+  x: number;
+  y: number;
+  /** 2-D numeric values (rows × cols). 1-D arrays are treated as
+   *  a single row. */
+  values: number[][] | number[];
+  /** Label rendered above the grid. */
+  label?: string;
+  /** Bold colour-coded role used for the highlight rail + shape
+   *  badge tint. */
+  role?: CellRole;
+  /** Optional shape suffix rendered top-right (e.g. "[4,4]"). When
+   *  omitted, computed from `values`. */
+  shape?: string;
+  /** Cell side length in user-space units. */
+  cell?: number;
+  /** Clip range for the heatmap colour ramp. Cells > +clip / < -clip
+   *  saturate to the role hue / pink. */
+  clip?: number;
+  /** Pre-rounded display floats — when omitted, uses values directly. */
+  display?: (string | number)[][] | (string | number)[];
+  testid?: string;
+}
+
+
+export function MatrixGrid({
+  x, y, values, label, role = "raw", shape, cell = 26, clip = 2,
+  display, testid,
+}: MatrixGridProps): JSX.Element {
+  const rows: number[][] = Array.isArray(values[0])
+    ? (values as number[][])
+    : ([values] as number[][]);
+  const dispRows: (string | number)[][] = display
+    ? (Array.isArray((display as never[])[0])
+        ? (display as (string | number)[][])
+        : ([display] as (string | number)[][]))
+    : rows.map((r) => r.map((v) => v.toFixed(2)));
+  const nRows = rows.length;
+  const nCols = rows[0]?.length ?? 0;
+  const totalW = nCols * cell;
+  const totalH = nRows * cell;
+  const shapeText = shape ??
+    (nRows === 1 ? `[${nCols}]` : `[${nRows},${nCols}]`);
+  const tint = ROLE_TINT[role];
+
+  return (
+    <g data-testid={testid ?? (label ? `matrix-${label}` : "matrix-grid")}>
+      {label && (
+        <text x={x} y={y - 6}
+              fill={tint}
+              fontSize={11} fontWeight={700}
+              fontFamily="system-ui, sans-serif">
+          {label}
+        </text>
+      )}
+      <text x={x + totalW} y={y - 6}
+            textAnchor="end"
+            fill={DIAG_THEME.textMuted}
+            fontSize={9}
+            fontFamily="ui-monospace, monospace">
+        {shapeText}
+      </text>
+      {/* role highlight rail along the left edge */}
+      <rect x={x - 3} y={y} width={3} height={totalH}
+             fill={tint} opacity={0.85} rx={1} />
+      {rows.map((row, ri) =>
+        row.map((v, ci) => {
+          const cx = x + ci * cell;
+          const cy = y + ri * cell;
+          const fill = role === "mask" ? DIAG_THEME.masked
+                                       : heatmapColor(v, clip, role);
+          return (
+            <g key={`${ri}-${ci}`}>
+              <rect x={cx} y={cy} width={cell} height={cell}
+                     fill={fill}
+                     stroke="rgba(255,255,255,0.06)" strokeWidth={0.6} />
+              <text x={cx + cell / 2} y={cy + cell / 2 + 3}
+                    textAnchor="middle"
+                    fill={DIAG_THEME.text}
+                    fontSize={Math.max(8, cell * 0.32)}
+                    fontFamily="ui-monospace, monospace">
+                {String(dispRows[ri]?.[ci] ?? v)}
+              </text>
+            </g>
+          );
+        })
+      )}
+    </g>
+  );
+}
+
+
+export interface MathLinkProps {
+  /** Topic key — used to render the gloss text inline. */
+  topic: string;
+  gloss: string;
+  url: string;
+  testid?: string;
+}
+
+/** A reference chip showing a math-foundation link with a short gloss.
+ *  Rendered inside <Section label="Math foundations"> as a list. */
+export function MathLink({
+  topic, gloss, url, testid,
+}: MathLinkProps): JSX.Element {
+  return (
+    <a href={url} target="_blank" rel="noopener noreferrer"
+       data-testid={testid ?? `math-link-${topic}`}
+       style={{
+         display: "block",
+         padding: "6px 10px",
+         margin: "4px 0",
+         background: "rgba(74, 174, 224, 0.08)",
+         border: "1px solid rgba(74, 174, 224, 0.25)",
+         borderRadius: 6,
+         color: DIAG_THEME.text,
+         textDecoration: "none",
+         fontSize: 12,
+         fontFamily: "system-ui, sans-serif",
+       }}>
+      <strong style={{ color: DIAG_THEME.roleK, marginRight: 6 }}>
+        {topic.replace(/_/g, " ")}
+      </strong>
+      <span style={{ color: DIAG_THEME.textMuted }}>— {gloss}</span>
+    </a>
+  );
+}
+
+
 /** A logical group/box around a sub-region of the diagram (e.g.
  *  multi-head attention). Renders a faint outlined rectangle with a
  *  small caption in the top-left corner. */