feat: kmeans viz, new media via LFS, classification layout fix

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -5,3 +5,4 @@ out
 *.log
 .env*
 .vercel
+*.tsbuildinfo

components/viz/ClassificationDemo.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { motion } from "framer-motion";
+import { useEffect, useState } from "react";
+import { COLORS } from "./common";
+import { useReducedMotion } from "@/lib/hooks/useReducedMotion";
+
+type Sample = {
+  src: string;
+  alt: string;
+  // First entry is the predicted label (highest confidence). Probabilities
+  // must sum to (approximately) 1.
+  probs: { label: string; p: number }[];
+};
+
+const SAMPLES: Sample[] = [
+  {
+    src: "/team/01.jpg",
+    alt: "team member 1",
+    probs: [
+      { label: "que mulher maravilhosa (UAU)", p: 0.94 },
+      { label: "readstone", p: 0.030 },
+      { label: "modelo de comercial de shampoo", p: 0.012 },
+      { label: "sereia", p: 0.011 },
+      { label: "engenheira da computação", p: 0.007 },
+    ],
+  },
+  {
+    src: "/team/02.jpg",
+    alt: "team member 2",
+    probs: [
+      { label: "frutinha++", p: 0.91 },
+      { label: "morango maduro", p: 0.040 },
+      { label: "compota artesanal", p: 0.025 },
+      { label: "smoothie de açaí", p: 0.015 },
+      { label: "fruta exótica", p: 0.010 },
+    ],
+  },
+  {
+    src: "/team/03.jpg",
+    alt: "team member 3",
+    probs: [
+      { label: "homens extremamente atraentes", p: 0.96 },
+      { label: "testosterona", p: 0.018 },
+      { label: "hardware", p: 0.012 },
+      { label: "modelos", p: 0.006 },
+      { label: "gambiarra", p: 0.004 },
+    ],
+  },
+  {
+    src: "/team/04.jpg",
+    alt: "team member 4",
+    probs: [
+      { label: "Jorge", p: 0.97 },
+      { label: "homem em flagrante", p: 0.015 },
+      { label: "professor disfarçado", p: 0.008 },
+      { label: "George Clooney brasileiro", p: 0.005 },
+      { label: "vendedor de seguros", p: 0.002 },
+    ],
+  },
+  {
+    src: "/team/05.jpg",
+    alt: "team member 5",
+    probs: [
+      { label: "boiadeira", p: 0.62 },
+      { label: "princesa da roça", p: 0.31 },
+      { label: "agro pop", p: 0.040 },
+      { label: "festa junina", p: 0.020 },
+      { label: "cowgirl", p: 0.010 },
+    ],
+  },
+];
+
+export function ClassificationDemo({
+  intervalMs = 5500,
+  maxImageHeight = 360,
+}: {
+  intervalMs?: number;
+  maxImageHeight?: number;
+}) {
+  const [idx, setIdx] = useState(0);
+  const [paused, setPaused] = useState(false);
+  const reduce = useReducedMotion();
+
+  useEffect(() => {
+    if (paused || reduce) return;
+    const id = setInterval(
+      () => setIdx((i) => (i + 1) % SAMPLES.length),
+      intervalMs,
+    );
+    return () => clearInterval(id);
+  }, [paused, reduce, intervalMs]);
+
+  const sample = SAMPLES[idx];
+
+  return (
+    <figure className="mx-auto flex w-full max-w-[920px] flex-col items-center">
+      <div className="w-full overflow-hidden rounded-md border border-stroke bg-surface">
+        <div className="grid grid-cols-5 items-center gap-5 p-5">
+          {/* Image — left 2 cols, fixed max-height to keep portrait and
+              landscape photos at the same vertical footprint. */}
+          <div className="col-span-2 flex items-center justify-center">
+            <motion.img
+              key={sample.src}
+              src={sample.src}
+              alt={sample.alt}
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              transition={{ duration: 0.4 }}
+              className="rounded-md border border-stroke object-contain"
+              style={{ maxHeight: maxImageHeight, maxWidth: "100%" }}
+            />
+          </div>
+
+          {/* Probability list — right 3 cols, auto-sized */}
+          <div className="col-span-3 flex flex-col gap-2.5">
+            <div className="mb-1 font-mono text-[11px] uppercase tracking-[0.14em] text-muted">
+              predicted distribution
+            </div>
+            {sample.probs.map((row, i) => {
+              const isTop = i === 0;
+              const pct = row.p * 100;
+              return (
+                <div key={`${idx}-${i}`} className="space-y-1">
+                  <div className="flex items-baseline justify-between gap-3">
+                    <span
+                      className={
+                        "truncate text-[13px] " +
+                        (isTop ? "text-ink" : "text-muted")
+                      }
+                    >
+                      {row.label}
+                    </span>
+                    <span className="font-mono text-[11px] tabular-nums text-ink">
+                      {pct < 10 ? pct.toFixed(1) : pct.toFixed(0)}%
+                    </span>
+                  </div>
+                  <div className="h-1.5 w-full overflow-hidden rounded-full bg-stroke">
+                    <motion.div
+                      key={`${idx}-${i}-bar`}
+                      initial={{ width: 0 }}
+                      animate={{ width: `${pct}%` }}
+                      transition={{
+                        duration: 0.7,
+                        delay: 0.15 + i * 0.05,
+                        ease: [0.22, 0.61, 0.36, 1],
+                      }}
+                      className="h-full"
+                      style={{
+                        background: isTop ? COLORS.accent : COLORS.honey,
+                      }}
+                    />
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+
+      <figcaption className="mt-3 text-center font-mono text-[11px] uppercase tracking-[0.12em] text-muted">
+        softmax over a class vocabulary — argmax wins
+      </figcaption>
+
+      {/* Thumbnail strip + pause */}
+      <div className="mt-3 flex items-center gap-3">
+        <div className="flex gap-1.5">
+          {SAMPLES.map((_, i) => (
+            <button
+              key={i}
+              type="button"
+              aria-label={`Sample ${i + 1}`}
+              onClick={() => setIdx(i)}
+              data-active={i === idx}
+              className="h-1.5 w-1.5 rounded-full bg-stroke transition-all hover:bg-muted data-[active=true]:w-6 data-[active=true]:bg-ink"
+            />
+          ))}
+        </div>
+        <button
+          type="button"
+          onClick={() => setPaused((p) => !p)}
+          className="rounded-md border border-stroke bg-surface px-3 py-1.5 font-mono text-[11px] uppercase tracking-[0.12em] text-muted transition hover:border-ink hover:text-ink"
+        >
+          {paused ? "play" : "pause"}
+        </button>
+      </div>
+    </figure>
+  );
+}

components/viz/KMeans.tsx

@@ -1,9 +1,18 @@
 "use client";
 
-import { useMemo, useState } from "react";
+import { motion } from "framer-motion";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { COLORS, VizFrame } from "./common";
+import { useReducedMotion } from "@/lib/hooks/useReducedMotion";
 
-function rng(seed = 7) {
+type Pt = { x: number; y: number };
+
+const X_MIN = 0.5;
+const X_MAX = 9.5;
+const Y_MIN = 0.5;
+const Y_MAX = 7.5;
+
+function rng(seed: number) {
   let s = seed;
   return () => {
     s = (s * 1664525 + 1013904223) % 4294967296;
@@ -11,132 +20,289 @@ function rng(seed = 7) {
   };
 }
 
-function gen(K = 3, perCluster = 25) {
+// Well-separated cluster centres — pick K from a fixed pool placed at the
+// corners and middles of the plot area so the groups stay visually distinct.
+const CENTRE_POOL: Pt[] = [
+  { x: 1.8, y: 1.6 },
+  { x: 8.2, y: 1.6 },
+  { x: 8.4, y: 6.3 },
+  { x: 1.6, y: 6.2 },
+  { x: 5.0, y: 4.0 },
+];
+
+function genPoints(K: number, perCluster: number) {
   const r = rng(11);
-  const centers = Array.from({ length: K }, () => [r() * 8 + 1, r() * 6 + 1] as [number, number]);
-  const pts: { x: number; y: number; trueK: number }[] = [];
-  centers.forEach((c, k) => {
+  const centres = CENTRE_POOL.slice(0, K);
+  const pts: Pt[] = [];
+  centres.forEach((c) => {
     for (let i = 0; i < perCluster; i++) {
       pts.push({
-        x: c[0] + (r() - 0.5) * 1.4,
-        y: c[1] + (r() - 0.5) * 1.4,
-        trueK: k,
+        x: c.x + (r() - 0.5) * 1.6,
+        y: c.y + (r() - 0.5) * 1.6,
       });
     }
   });
-  return { points: pts, centers };
+  return pts;
+}
+
+// Random initial centroids spread across the *full* plot — not just where the
+// data lives — so the first few iterations clearly show centroids moving.
+function genInitial(K: number, seed: number): Pt[] {
+  const r = rng(seed);
+  return Array.from({ length: K }, () => ({
+    x: X_MIN + r() * (X_MAX - X_MIN),
+    y: Y_MIN + r() * (Y_MAX - Y_MIN),
+  }));
 }
 
-function step(
-  points: { x: number; y: number }[],
-  centroids: [number, number][],
-) {
-  const assign = points.map((p) =>
-    centroids.reduce((best, c, k) => {
-      const d = (p.x - c[0]) ** 2 + (p.y - c[1]) ** 2;
-      return d < best.d ? { d, k } : best;
-    }, { d: Infinity, k: 0 }).k,
+function assignStep(points: Pt[], centroids: Pt[]): number[] {
+  return points.map((p) =>
+    centroids.reduce(
+      (best, c, k) => {
+        const d = (p.x - c.x) ** 2 + (p.y - c.y) ** 2;
+        return d < best.d ? { d, k } : best;
+      },
+      { d: Infinity, k: 0 },
+    ).k,
   );
-  const next: [number, number][] = centroids.map((_, k) => {
+}
+
+function updateStep(points: Pt[], assign: number[], K: number, prev: Pt[]): Pt[] {
+  return Array.from({ length: K }, (_, k) => {
     const cls = points.filter((_, i) => assign[i] === k);
-    if (!cls.length) return centroids[k];
-    const mx = cls.reduce((a, p) => a + p.x, 0) / cls.length;
-    const my = cls.reduce((a, p) => a + p.y, 0) / cls.length;
-    return [mx, my];
+    if (!cls.length) return prev[k];
+    return {
+      x: cls.reduce((a, p) => a + p.x, 0) / cls.length,
+      y: cls.reduce((a, p) => a + p.y, 0) / cls.length,
+    };
   });
-  return { assign, next };
 }
 
-const PALETTE = [COLORS.accent, COLORS.honey, COLORS.green, COLORS.red];
+function inertia(points: Pt[], assign: number[], centroids: Pt[]): number {
+  return points.reduce((acc, p, i) => {
+    const c = centroids[assign[i]];
+    return acc + (p.x - c.x) ** 2 + (p.y - c.y) ** 2;
+  }, 0);
+}
+
+const PALETTE = [COLORS.accent, COLORS.honey, COLORS.green, COLORS.red, "#7E57C2"];
+
+type Phase = "assign" | "update";
 
 export function KMeans({
   width = 720,
-  height = 460,
-  K = 3,
+  height = 500,
+  K = 4,
 }: {
   width?: number;
   height?: number;
   K?: number;
 }) {
   const padX = 50;
-  const padY = 40;
-  const { points } = useMemo(() => gen(K, 25), [K]);
-  const initial: [number, number][] = useMemo(() => {
-    const r = rng(99);
-    return Array.from({ length: K }, () => [r() * 8 + 1, r() * 6 + 1] as [number, number]);
-  }, [K]);
-  const [centroids, setCentroids] = useState<[number, number][]>(initial);
-  const [iter, setIter] = useState(0);
-
-  const sx = (x: number) => padX + (x / 10) * (width - padX * 2);
-  const sy = (y: number) => height - padY - (y / 8) * (height - padY * 2);
+  const padY = 50;
+  const points = useMemo(() => genPoints(K, 28), [K]);
+  // Bumped on every Reset; drives a fresh random centroid initialisation.
+  const [seedTick, setSeedTick] = useState(0);
+  const initial = useMemo(
+    () => genInitial(K, 1 + seedTick * 7919),
+    [K, seedTick],
+  );
 
-  const { assign } = step(points, centroids);
+  const [centroids, setCentroids] = useState<Pt[]>(initial);
+  const [iter, setIter] = useState(0);
+  const [phase, setPhase] = useState<Phase>("assign");
+  const [playing, setPlaying] = useState(false);
+  const reduce = useReducedMotion();
 
-  const advance = () => {
-    const { next } = step(points, centroids);
-    setCentroids(next);
-    setIter((i) => i + 1);
-  };
-  const reset = () => {
+  // Whenever the seed bumps, reset state to the new initial centroids.
+  useEffect(() => {
     setCentroids(initial);
     setIter(0);
-  };
+    setPhase("assign");
+    setPlaying(false);
+  }, [initial]);
+
+  const sx = useCallback(
+    (x: number) => padX + (x / 10) * (width - padX * 2),
+    [width],
+  );
+  const sy = useCallback(
+    (y: number) => height - padY - (y / 8) * (height - padY * 2),
+    [height],
+  );
+
+  const assign = useMemo(
+    () => assignStep(points, centroids),
+    [points, centroids],
+  );
+  const J = useMemo(
+    () => inertia(points, assign, centroids),
+    [points, assign, centroids],
+  );
+
+  // Run the next half-step. assign → update → next iter.
+  const advance = useCallback(() => {
+    if (phase === "assign") {
+      setPhase("update");
+    } else {
+      const next = updateStep(points, assign, K, centroids);
+      const moved = next.some(
+        (c, k) =>
+          Math.abs(c.x - centroids[k].x) > 1e-4 ||
+          Math.abs(c.y - centroids[k].y) > 1e-4,
+      );
+      setCentroids(next);
+      setIter((i) => i + 1);
+      setPhase("assign");
+      if (!moved) setPlaying(false);
+    }
+  }, [phase, points, assign, K, centroids]);
+
+  const advanceRef = useRef(advance);
+  advanceRef.current = advance;
+
+  useEffect(() => {
+    if (!playing || reduce) return;
+    const id = setInterval(() => advanceRef.current(), 900);
+    return () => clearInterval(id);
+  }, [playing, reduce]);
+
+  // Reset draws a *new* random initial centroid placement each time.
+  const reset = () => setSeedTick((t) => t + 1);
+
+  // For the assign phase, draw a thin line from each point to its winning
+  // centroid. This is the "compute distance, pick the smallest" step made
+  // visible.
+  const showLinks = phase === "assign";
 
   return (
     <div className="flex w-full max-w-full flex-col items-center">
-      <VizFrame width={width} height={height}>
+      <VizFrame
+        width={width}
+        height={height}
+        caption={
+          phase === "assign"
+            ? "step 1 — assign each point to the nearest centroid"
+            : "step 2 — move each centroid to the mean of its cluster"
+        }
+      >
         <svg viewBox={`0 0 ${width} ${height}`} className="h-full w-full">
+          {/* Faint outline at the initial centroid spot — anchors the eye. */}
+          {initial.map((c, k) => (
+            <circle
+              key={`init-${k}`}
+              cx={sx(c.x)}
+              cy={sy(c.y)}
+              r={10}
+              fill="none"
+              stroke={PALETTE[k % PALETTE.length]}
+              strokeOpacity={0.35}
+              strokeDasharray="3 3"
+              strokeWidth={1}
+            />
+          ))}
+
+          {showLinks
+            ? points.map((p, i) => {
+                const c = centroids[assign[i]];
+                return (
+                  <line
+                    key={`l-${i}`}
+                    x1={sx(p.x)}
+                    y1={sy(p.y)}
+                    x2={sx(c.x)}
+                    y2={sy(c.y)}
+                    stroke={PALETTE[assign[i] % PALETTE.length]}
+                    strokeOpacity={0.18}
+                    strokeWidth={1}
+                  />
+                );
+              })
+            : null}
+
           {points.map((p, i) => (
             <circle
-              key={i}
+              key={`p-${i}`}
               cx={sx(p.x)}
               cy={sy(p.y)}
               r={3}
               fill={PALETTE[assign[i] % PALETTE.length]}
-              fillOpacity={0.6}
+              fillOpacity={0.85}
             />
           ))}
+
           {centroids.map((c, k) => (
-            <g key={k}>
-              <circle
-                cx={sx(c[0])}
-                cy={sy(c[1])}
-                r={9}
+            <motion.g
+              key={`c-${k}`}
+              animate={{ cx: sx(c.x), cy: sy(c.y) }}
+              transition={{ duration: 0.5, ease: [0.22, 0.61, 0.36, 1] }}
+            >
+              <motion.circle
+                animate={{ cx: sx(c.x), cy: sy(c.y) }}
+                transition={{ duration: 0.5, ease: [0.22, 0.61, 0.36, 1] }}
+                r={10}
                 fill={PALETTE[k % PALETTE.length]}
                 stroke={COLORS.ink}
                 strokeWidth={1.5}
               />
-              <text
-                x={sx(c[0])}
-                y={sy(c[1]) + 4}
+              <motion.text
+                animate={{ x: sx(c.x), y: sy(c.y) + 4 }}
+                transition={{ duration: 0.5, ease: [0.22, 0.61, 0.36, 1] }}
                 textAnchor="middle"
                 fontSize={11}
                 fill={COLORS.surface}
                 fontFamily="JetBrains Mono, monospace"
               >
-                {k + 1}
-              </text>
-            </g>
+                μ{k + 1}
+              </motion.text>
+            </motion.g>
           ))}
+
+          {/* Step badge top-left of plot area */}
+          <g transform={`translate(${padX}, ${padY - 22})`}>
+            <text
+              fontSize={11}
+              fontFamily="JetBrains Mono, monospace"
+              fill={phase === "assign" ? COLORS.accent : COLORS.honey}
+              style={{ textTransform: "uppercase", letterSpacing: "0.16em" }}
+            >
+              {phase === "assign"
+                ? `iter ${iter} · assignment`
+                : `iter ${iter} · update`}
+            </text>
+          </g>
         </svg>
       </VizFrame>
-      <div className="mt-4 flex items-center gap-3 font-mono text-[11px] uppercase tracking-[0.12em] text-muted">
-        <button
-          type="button"
-          onClick={advance}
-          className="rounded-md border border-stroke bg-surface px-3 py-1.5 transition hover:border-ink hover:text-ink"
-        >
-          Step
-        </button>
-        <button
-          type="button"
-          onClick={reset}
-          className="rounded-md border border-stroke bg-surface px-3 py-1.5 transition hover:border-ink hover:text-ink"
-        >
-          Reset
-        </button>
-        <span>iter = {String(iter).padStart(2, "0")}</span>
+
+      <div className="mt-4 flex w-full max-w-[640px] flex-wrap items-center justify-between gap-3 font-mono text-[11px] uppercase tracking-[0.12em]">
+        <div className="flex items-center gap-2">
+          <button
+            type="button"
+            onClick={advance}
+            className="rounded-md border border-stroke bg-surface px-3 py-1.5 text-muted transition hover:border-ink hover:text-ink"
+          >
+            Step
+          </button>
+          <button
+            type="button"
+            onClick={() => setPlaying((p) => !p)}
+            className="rounded-md border border-stroke bg-surface px-3 py-1.5 text-muted transition hover:border-ink hover:text-ink"
+          >
+            {playing ? "Pause" : "Play"}
+          </button>
+          <button
+            type="button"
+            onClick={reset}
+            className="rounded-md border border-stroke bg-surface px-3 py-1.5 text-muted transition hover:border-ink hover:text-ink"
+          >
+            Reset
+          </button>
+        </div>
+        <div className="text-muted">
+          iter <span className="text-ink">{String(iter).padStart(2, "0")}</span>{" "}
+          · J ={" "}
+          <span className="text-ink">{J.toFixed(2)}</span>
+        </div>
       </div>
     </div>
   );

components/viz/VideoDemo.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { useState } from "react";
+import { COLORS, VizFrame } from "./common";
+
+export type VideoClip = {
+  src: string;
+  label: string;
+};
+
+export function VideoDemo({
+  clips,
+  caption,
+  width = 880,
+  height = 500,
+}: {
+  clips: VideoClip[];
+  caption?: string;
+  width?: number;
+  height?: number;
+}) {
+  const [idx, setIdx] = useState(0);
+  const clip = clips[idx];
+
+  return (
+    <div className="flex w-full max-w-full flex-col items-center">
+      <VizFrame width={width} height={height} caption={caption}>
+        <div className="flex h-full w-full items-center justify-center bg-bone p-3">
+          <video
+            key={clip.src}
+            src={clip.src}
+            autoPlay
+            muted
+            loop
+            playsInline
+            controls
+            className="max-h-full max-w-full rounded-md border border-stroke bg-black"
+          />
+        </div>
+      </VizFrame>
+
+      {clips.length > 1 ? (
+        <div className="mt-4 flex flex-wrap items-center gap-2 font-mono text-[11px] uppercase tracking-[0.12em]">
+          {clips.map((c, i) => (
+            <button
+              key={c.src}
+              type="button"
+              onClick={() => setIdx(i)}
+              data-active={i === idx}
+              className="rounded-md border border-stroke bg-surface px-3 py-1.5 text-muted transition hover:border-ink hover:text-ink data-[active=true]:border-ink data-[active=true]:text-ink"
+              style={i === idx ? { color: COLORS.ink } : undefined}
+            >
+              {c.label}
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

content/slides/ch04-classical-ml.tsx

@@ -167,22 +167,107 @@ export const ch04: Chapter = {
     },
     {
       id: "ch04-07",
-      title: "k-means clustering",
+      title: "k-means — the algorithm",
       eyebrow: "Unsupervised baseline",
-      layout: "split",
+      layout: "prose",
       content: (
         <div className="space-y-4">
           <p>
-            Initialise <M>k</M> centroids, alternate assignment and update.
-            Centroids converge to local minima of the within-cluster sum of
-            squares:
+            Given <M>N</M> points <M>{"\\{x_i\\} \\subset \\mathbb{R}^d"}</M>{" "}
+            and a chosen number of clusters <M>K</M>, find an assignment{" "}
+            <M>{"r_{ik} \\in \\{0, 1\\}"}</M> and centroids{" "}
+            <M>{"\\mu_k \\in \\mathbb{R}^d"}</M> that minimise the{" "}
+            <em>within-cluster sum of squares</em> (also called inertia):
           </p>
-          <MBlock>{"\\sum_{k} \\sum_{x \\in C_k} \\|x - \\mu_k\\|^2"}</MBlock>
+          <MBlock>
+            {"J = \\sum_{i=1}^{N}\\sum_{k=1}^{K} r_{ik}\\,\\|x_i - \\mu_k\\|^2"}
+          </MBlock>
+          <p>
+            Joint minimisation over <M>r</M> and{" "}
+            <M>{"\\mu"}</M> is NP-hard. Lloyd&apos;s algorithm (1957) is the
+            workhorse heuristic — alternate two closed-form steps until
+            nothing changes:
+          </p>
+          <div className="space-y-3 rounded-md border border-stroke bg-surface px-5 py-4 text-[14px]">
+            <div>
+              <div className="mb-1 font-mono text-[11px] uppercase tracking-[0.12em] text-accent">
+                step 1 · assignment
+              </div>
+              <p className="mb-2">
+                Fix the centroids. Send each point to the closest one.
+              </p>
+              <MBlock>
+                {"r_{ik} = \\begin{cases} 1 & k = \\arg\\min_j \\|x_i - \\mu_j\\|^2 \\\\ 0 & \\text{otherwise} \\end{cases}"}
+              </MBlock>
+            </div>
+            <div>
+              <div className="mb-1 font-mono text-[11px] uppercase tracking-[0.12em] text-honey">
+                step 2 · update
+              </div>
+              <p className="mb-2">
+                Fix the assignment. Move each centroid to the mean of its
+                points (this is the value that minimises <M>J</M> for fixed{" "}
+                <M>r</M>):
+              </p>
+              <MBlock>
+                {"\\mu_k = \\frac{\\sum_i r_{ik}\\,x_i}{\\sum_i r_{ik}}"}
+              </MBlock>
+            </div>
+          </div>
           <p className="text-muted">
-            Sensitive to initialisation; we typically run several seeds and
-            keep the best. <strong>k-means++</strong> picks initial centroids
-            more carefully and almost always converges faster.
+            Both steps strictly decrease <M>J</M> (or leave it unchanged), so
+            the algorithm <em>always converges</em> — typically in fewer than
+            20 iterations. Cost per iteration:{" "}
+            <M>{"O(N \\cdot K \\cdot d)"}</M>.
+          </p>
+        </div>
+      ),
+    },
+    {
+      id: "ch04-07b",
+      title: "k-means in action",
+      eyebrow: "Watch J fall",
+      layout: "split",
+      content: (
+        <div className="space-y-4">
+          <p>
+            <span className="font-mono text-[12px] text-accent">Step</span>{" "}
+            advances one half-iteration at a time, alternating between the
+            two phases. <span className="font-mono text-[12px] text-accent">Play</span>{" "}
+            runs to convergence. <span className="font-mono text-[12px]">J</span>{" "}
+            is the inertia; watch it monotonically decrease.
           </p>
+          <ul className="space-y-2 text-[14px] text-ink/85">
+            <li>
+              · Thin lines in the assignment phase show each point pulled to
+              its nearest centroid (the <M>{"\\arg\\min"}</M>).
+            </li>
+            <li>
+              · In the update phase, the centroids translate to the cluster
+              mean — usually the largest <M>J</M> drop happens here.
+            </li>
+            <li>
+              · The animation stops automatically when no centroid moves.
+            </li>
+          </ul>
+          <Callout label="Gotchas" tone="warm">
+            <ul className="space-y-1">
+              <li>
+                · <strong>Initialisation matters.</strong> Plain k-means is
+                sensitive to the starting centroids;{" "}
+                <strong>k-means++</strong> seeds them apart on purpose and
+                almost always converges to a better minimum.
+              </li>
+              <li>
+                · <strong>You must pick K.</strong> Use the elbow method on{" "}
+                <M>J(K)</M> or the silhouette score.
+              </li>
+              <li>
+                · <strong>Assumes spherical, equal-size clusters.</strong>{" "}
+                For arbitrary shapes use DBSCAN or a Gaussian mixture model.
+              </li>
+            </ul>
+          </Callout>
         </div>
       ),
       viz: <KMeans />,

content/slides/ch05-deep-learning.tsx

@@ -9,8 +9,18 @@ import { RegularizationViz } from "@/components/viz/RegularizationViz";
 import { Callout } from "@/components/ui/Callout";
 import { M, MBlock } from "@/components/math/Math";
 
-// Replace with your own playground URL.
-const PLAYGROUND_URL = "https://playground.tensorflow.org/";
+const PLAYGROUNDS = [
+  {
+    name: "Neural Network Playground",
+    url: "https://playground.tensorflow.org/",
+    note: "TensorFlow · the original interactive playground",
+  },
+  {
+    name: "Samuel's NN Playground",
+    url: "https://samuellimabraz.github.io/#nn-playground",
+    note: "custom build · same idea, our notation",
+  },
+];
 
 export const ch05: Chapter = {
   id: "ch05",
@@ -131,30 +141,31 @@ export const ch05: Chapter = {
             interact is to build a tiny network in a browser and watch it
             train.
           </p>
-          <a
-            href={PLAYGROUND_URL}
-            target="_blank"
-            rel="noreferrer"
-            className="inline-flex items-center gap-3 rounded-md border border-ink/40 bg-surface px-5 py-3 transition hover:border-ink hover:bg-bone"
-          >
-            <span className="font-mono text-[11px] uppercase tracking-[0.16em] text-muted">
-              Open
-            </span>
-            <span className="font-serif text-lg text-ink">
-              Neural Network Playground
-            </span>
-            <span className="font-mono text-[11px] text-muted">↗</span>
-          </a>
+          <div className="flex flex-col gap-3">
+            {PLAYGROUNDS.map((p) => (
+              <a
+                key={p.url}
+                href={p.url}
+                target="_blank"
+                rel="noreferrer"
+                className="inline-flex items-center gap-3 rounded-md border border-ink/40 bg-surface px-5 py-3 transition hover:border-ink hover:bg-bone"
+              >
+                <span className="font-mono text-[11px] uppercase tracking-[0.16em] text-muted">
+                  Open
+                </span>
+                <span className="font-serif text-lg text-ink">{p.name}</span>
+                <span className="ml-auto font-mono text-[11px] text-muted">
+                  {p.note}
+                </span>
+                <span className="font-mono text-[11px] text-muted">↗</span>
+              </a>
+            ))}
+          </div>
           <p className="text-muted">
             Things to look for: how the spiral dataset needs ≥ 2 hidden layers;
             how ReLU vs sigmoid affects convergence; how a too-large learning
             rate explodes; how regularisation smooths the boundary.
           </p>
-          <p className="font-mono text-[11px] uppercase tracking-[0.12em] text-muted">
-            <span className="text-honey">tip</span> · the playground URL is a
-            constant in <code className="font-mono normal-case">ch05-deep-learning.tsx</code>; replace it with
-            your own demo.
-          </p>
         </div>
       ),
     },

content/slides/ch07-cv-tasks.tsx

@@ -1,6 +1,8 @@
 import type { Chapter } from "@/components/slide/types";
 import { MaskOverlay } from "@/components/viz/Scene";
 import { BboxFormats } from "@/components/viz/BboxFormats";
+import { ClassificationDemo } from "@/components/viz/ClassificationDemo";
+import { VideoDemo } from "@/components/viz/VideoDemo";
 import { Callout } from "@/components/ui/Callout";
 import { M, MBlock } from "@/components/math/Math";
 
@@ -19,17 +21,24 @@ export const ch07: Chapter = {
       content: (
         <div className="space-y-4">
           <p>
-            A single label per image. Output is a probability distribution over
-            classes through softmax:
+            One label per image. Output is a probability distribution over a
+            fixed vocabulary, produced by softmax over the network logits:
           </p>
           <MBlock>{"\\hat p_k = \\frac{e^{z_k}}{\\sum_j e^{z_j}}"}</MBlock>
-          <p className="text-muted">
-            Loss is cross-entropy. Top-1 and top-5 accuracy are the standard metrics.
-            ImageNet was the long-standing benchmark.
+          <p>
+            The prediction is <M>{"\\arg\\max_k \\hat p_k"}</M>; loss is
+            categorical cross-entropy. Top-1 and top-5 accuracy are the
+            standard metrics. ImageNet (1000 classes) was the long-standing
+            benchmark.
           </p>
+          <Callout label="Watch">
+            Bars on the right are the full distribution, not just the winner.
+            Image 5 is the same person as image 1 — see how the model splits
+            its mass between two classes when the appearance changes.
+          </Callout>
         </div>
       ),
-      viz: <MaskOverlay mode="classification" />,
+      viz: <ClassificationDemo />,
     },
     {
       id: "ch07-01",
@@ -39,16 +48,26 @@ export const ch07: Chapter = {
       content: (
         <div className="space-y-4">
           <p>
-            Predict a set of bounding boxes plus a class label per box. Each prediction
-            carries a confidence score.
+            Predict a variable-length list of (box, class, confidence). The
+            output structure is what makes detection harder than classification
+            — a single image can contain zero or many objects.
           </p>
-          <p className="text-muted">
-            Most Black Bee perception lives here: gates, posts, drones. Chapter 8 is
-            entirely about this task.
+          <p>
+            Most Black Bee perception lives here: gates, posts, drones. The
+            video on the right is one of our trained YOLO models running on a
+            real flight log. Chapter 8 unpacks the architecture.
           </p>
         </div>
       ),
-      viz: <MaskOverlay mode="detection" />,
+      viz: (
+        <VideoDemo
+          caption="real Black Bee mission · YOLO detection on flight footage"
+          clips={[
+            { src: "/team/det-1.mp4", label: "clip 1" },
+            { src: "/team/det-2.mp4", label: "clip 2" },
+          ]}
+        />
+      ),
     },
     {
       id: "ch07-02",
@@ -58,22 +77,27 @@ export const ch07: Chapter = {
       content: (
         <div className="space-y-4">
           <p>
-            Three conventions you will see daily, all describing the same rectangle:
+            Three conventions you will see daily, all describing the same
+            rectangle:
           </p>
           <ul className="space-y-2 text-[14px] text-ink/85">
             <li>
-              <strong>xyxy</strong> · top-left and bottom-right corners. COCO, supervision.
+              <strong>xyxy</strong> · top-left and bottom-right corners. COCO,
+              supervision.
             </li>
             <li>
-              <strong>xywh</strong> · centre with width and height. Internal to many models.
+              <strong>xywh</strong> · centre with width and height. Internal
+              to many models.
             </li>
             <li>
-              <strong>normalized</strong> · everything divided by image size. YOLO labels.
+              <strong>normalized</strong> · everything divided by image size.
+              YOLO labels.
             </li>
           </ul>
           <Callout label="In Nectar">
-            <code className="font-mono text-[12px]">FormatConverter</code> in the SDK
-            handles COCO ↔ YOLO conversion automatically. Chapter 11 returns to it.
+            <code className="font-mono text-[12px]">FormatConverter</code> in
+            the SDK handles COCO ↔ YOLO conversion automatically. Chapter 11
+            returns to it.
           </Callout>
         </div>
       ),
@@ -87,14 +111,28 @@ export const ch07: Chapter = {
       content: (
         <div className="space-y-4">
           <p>
-            Every pixel gets a class label. Output is an image with the same spatial
-            size as the input but with channels equal to the number of classes.
+            Every pixel gets a class label. The output has the same spatial
+            size as the input, with one channel per class:
+          </p>
+          <MBlock>
+            {"\\hat Y \\in \\mathbb{R}^{H \\times W \\times C}, \\quad \\hat y_{ij} = \\arg\\max_c \\hat Y_{ijc}"}
+          </MBlock>
+          <p>
+            All pixels of the same class share one mask — &quot;all gate
+            pixels&quot;, not &quot;this gate vs that gate&quot;. Loss is
+            per-pixel cross-entropy, often combined with Dice loss to handle
+            class imbalance.
           </p>
-          <MBlock>{"\\hat Y \\in \\mathbb{R}^{H \\times W \\times C}, \\quad \\hat y_{ij} = \\arg\\max_c \\hat Y_{ijc}"}</MBlock>
           <p className="text-muted">
-            All pixels of the same class share one mask — &quot;all gate pixels&quot;,
-            not &quot;this gate vs. that gate&quot;.
+            Typical use cases: free-space mapping for autonomous driving, lane
+            segmentation, terrain classification from aerial imagery.
+            Architectures: U-Net, DeepLab, SegFormer, Mask2Former.
           </p>
+          <Callout>
+            We do not use this on Black Bee yet — most of our targets are
+            countable objects, where instance segmentation or detection fits
+            better.
+          </Callout>
         </div>
       ),
       viz: <MaskOverlay mode="semantic" />,
@@ -107,17 +145,31 @@ export const ch07: Chapter = {
       content: (
         <div className="space-y-4">
           <p>
-            Detection + per-pixel mask, separate per object. Mask R-CNN added a small
-            mask head on top of Faster R-CNN; YOLO-seg and DETR-seg do similarly.
+            Detection plus a per-pixel mask, separate for each object. Mask
+            R-CNN added a small mask head on top of Faster R-CNN; YOLO-seg and
+            DETR-seg do similarly.
+          </p>
+          <p>
+            The video on the right is one of our segmentation models on a real
+            flight; each instance gets its own coloured mask, which lets us
+            count, sort, or pick objects individually.
           </p>
           <p className="text-muted">
             The Nectar SDK supports this through{" "}
-            <code className="font-mono text-[12px]">Segmentor</code> with the same
-            three frameworks (YOLO, DETR, RF-DETR). See chapter 11.
+            <code className="font-mono text-[12px]">Segmentor</code> with the
+            same three frameworks (YOLO, DETR, RF-DETR). See chapter 11.
           </p>
         </div>
       ),
-      viz: <MaskOverlay mode="instance" />,
+      viz: (
+        <VideoDemo
+          caption="real Black Bee mission · instance segmentation on flight footage"
+          clips={[
+            { src: "/team/seg-2.mp4", label: "clip 1" },
+            { src: "/team/seg-1.mp4", label: "clip 2" },
+          ]}
+        />
+      ),
     },
     {
       id: "ch07-05",
@@ -127,12 +179,13 @@ export const ch07: Chapter = {
       content: (
         <div className="space-y-4">
           <p>
-            Predict a small set of named points per object — corners of a gate, joints
-            of a body. Either as a heatmap per keypoint, or as a regressed coordinate.
+            Predict a small set of named points per object — corners of a
+            gate, joints of a body. Either as a heatmap per keypoint, or as a
+            regressed coordinate.
           </p>
           <p className="text-muted">
-            Useful when downstream geometry (pose estimation, alignment) needs precise
-            anchors.
+            Useful when downstream geometry (pose estimation, alignment) needs
+            precise anchors.
           </p>
         </div>
       ),
@@ -146,16 +199,16 @@ export const ch07: Chapter = {
       content: (
         <div className="space-y-4">
           <p>
-            Per-pixel distance in metres. Stereo, time-of-flight, or learned monocular
-            depth from a single RGB image.
+            Per-pixel distance in metres. Stereo, time-of-flight, or learned
+            monocular depth from a single RGB image.
           </p>
           <p>
-            Black Bee uses this directly: the RealSense and OAK-D drivers in the
-            Nectar vision module return depth alongside colour.
+            Black Bee uses this directly: the RealSense and OAK-D drivers in
+            the Nectar vision module return depth alongside colour.
           </p>
           <Callout label="Tip" tone="warm">
-            Monocular depth is up to a scale factor. Useful for ordering objects, less
-            useful for absolute distances without calibration.
+            Monocular depth is up to a scale factor. Useful for ordering
+            objects, less useful for absolute distances without calibration.
           </Callout>
         </div>
       ),

public/team/det-1.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d06d26c358f209b881c5fe426b62bd9f6a17d3b22aa00259caeff109c78fa8ca
+size 3008225

public/team/det-2.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:87d841d138b67d4e49a0ba18bae57c76985b4af95f2885faba0a37a81aa42b8a
+size 3549299

public/team/seg-1.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3603d67b1a2660df5284649d937073fb8227d7bd9cd95eb0ab5b812c83f4b788
+size 18444491

public/team/seg-2.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:34e1a8f2c0ecb4b03c041e530b4caec53470ab3a4a2534574bbd1a8c01b498e7
+size 5527552