Test suite, difficulty filter, and playback focus fix

.claude/skills/audit-architecture/SKILL.md

@@ -15,10 +15,13 @@ When the user asks to audit, review, or check architecture compliance, code stru
 Run each check and report findings:
 
 ### 1. Component Size Limits
+
 Search `src/components/` for `.tsx` files over 300 lines. Flag each with line count and suggestion to extract sub-components or data files.
 
 ### 2. Folder-Based Topic Structure
+
 For each folder in `src/components/visualizations/*/`, verify these files exist:
+
 - `index.tsx`
 - `types.ts`
 - `helpers.ts`
@@ -27,26 +30,37 @@ For each folder in `src/components/visualizations/*/`, verify these files exist:
 Report any missing files.
 
 ### 3. `"use client"` Directive
+
 Check all visualization components in `src/components/visualizations/` for the `"use client"` directive on line 1. Flag any missing.
 
 ### 4. Named Exports
+
 Check visualization components use named exports (not `export default`). Search for `export default` in visualization files and flag.
 
 ### 5. Import Alias Usage
+
 Search for deep relative imports (e.g., `../../../`) in `src/components/`. These should use the `@/` alias. Flag violations.
 
 ### 6. Const-Form Components
-Search for `export function` declarations in `src/components/visualizations/` that should be `const`-form arrow functions. Note: the existing codebase uses `export function` for main visualization components, so only flag new patterns that deviate from the established convention.
+
+Search for `export function` or `function X(` component declarations in `src/components/` and `src/hooks/`. Every component and hook uses const arrow form; only Next.js `page.tsx` and `layout.tsx` under `src/app/` use `export default function`.
 
 ### 7. Panel Title Constants
+
 Search visualization files for hardcoded strings `"Source Code"` or `"Console Output"` that should use `VISUALIZATION_PANEL_TITLES` from `uiCopy.ts`. Flag violations.
 
 ### 8. ExampleSelector Registration
-For topics using `ExampleSelector`, verify their ID appears in `SELECTOR_TOOLBAR_TOPIC_IDS` in `VisualizationPageShell.tsx`. Cross-reference by searching for `ExampleSelector` imports in visualization files.
+
+For topics with no example picker (`useStepPlayback` called directly, no `ExamplePicker`), verify the registry entry sets `toolbar: "simple"`. For topics that hand-roll a toolbar (`ToolbarPortal`, `TransportControls`, or `VISUALIZATION_EMPTY_STATES.stepDescription` imported in a topic `index.tsx`), flag them: topics must use `VisualizationToolbar`, `SourceCodePanel`, and `useExampleTopic`.
+
+### 9. Category Branching
+
+Search `src/components/` and `src/lib/` for `=== "javascript"` or `=== "react"`. Components must read `CATEGORIES[topic.category]` from `src/lib/categories.ts` instead. Flag violations.
 
 ## Output Format
 
 Report as a numbered list:
+
 ```
 1. PASS: Component size limits (all under 300 lines)
 2. FAIL: Missing types.ts in src/components/visualizations/closures/

.claude/skills/audit-release/SKILL.md

@@ -13,29 +13,37 @@ When the user asks to verify, check, or validate before release, deploy, or merg
 ## Checks
 
 ### 1. Lint
+
 Run `npm run lint`. Report any errors or warnings.
 
 ### 2. Build
+
 Run `npm run build`. Report any build failures. Capture and display the generated routes list from build output.
 
 ### 3. Route Page Coverage
-For every topic in `src/lib/topics.ts`, verify a route page file exists at `src/app/<category>/<id>/page.tsx`. Flag missing route pages.
+
+Run `npm run typecheck`. The `VISUALIZATIONS`, theory, keyword, and description registries are typed by `TopicId`, so a topic missing from any of them fails here. Also confirm each topic id has a folder under `src/components/visualizations/`.
 
 ### 4. ExampleSelector Registration
-Search visualization files for `ExampleSelector` imports. For each topic using it, verify the topic ID is in `SELECTOR_TOOLBAR_TOPIC_IDS` in `src/components/layout/VisualizationPageShell.tsx`. Flag missing registrations.
+
+For topics whose `index.tsx` does not use `ExamplePicker`, verify the registry entry sets `toolbar: "simple"` so the loading skeleton matches.
 
 ### 5. Theory Registration
-For every theory content file in `src/content/theory/javascript/` and `src/content/theory/react/`, verify it is imported and registered in `src/content/theory/index.ts`. Flag unregistered files.
+
+For every theory content file in `src/content/theory/<category>/` (every folder), verify it is imported and registered in `src/content/theory/index.ts`. Flag unregistered files.
 
 ### 6. Console.log Audit
+
 Search for `console.log` statements in `src/` (excluding `src/content/` and `ConsoleOutput` rendering). Flag any found in production code.
 
 ### 7. Topic-Keyword Cross-Check
+
 Verify every topic in `src/lib/topics.ts` has a `TOPIC_KEYWORDS` entry in `src/lib/metadata.ts`.
 
 ## Output Format
 
 Report as a numbered pass/fail list with actionable items:
+
 ```
 1. PASS: Lint (0 errors, 0 warnings)
 2. PASS: Build (17 routes generated)

.claude/skills/audit-seo/SKILL.md

@@ -15,35 +15,45 @@ When the user asks to audit, check, or verify SEO compliance, metadata, or topic
 Run each check and report findings:
 
 ### 1. TOPIC_KEYWORDS Coverage
+
 Read `src/lib/topics.ts` to get all topic IDs. Read `src/lib/metadata.ts` and verify every topic ID has an entry in `TOPIC_KEYWORDS`. Flag missing topics.
 
 ### 2. docsUrl Validation
+
 Verify every topic in `src/lib/topics.ts` has a non-empty `docsUrl` field. Flag any empty or missing values.
 
 ### 3. Theory Registration
+
 Read `src/content/theory/index.ts`. For each theory file imported, verify:
+
 - The corresponding `.ts` file exists at the expected path
 - The topic ID exists in `src/lib/topics.ts`
-Flag orphaned theory files or unregistered topics.
+  Flag orphaned theory files or unregistered topics.
 
 ### 4. TOPIC_THEORY_DESCRIPTIONS Coverage
+
 For every topic registered in `src/content/theory/index.ts`, verify it has a corresponding entry in `TOPIC_THEORY_DESCRIPTIONS` in `src/lib/metadata.ts`. Flag missing descriptions.
 
 ### 5. relatedTopicIds Validation
+
 For each theory content file, check that:
+
 - `relatedTopicIds` is not an empty array
 - Each ID in `relatedTopicIds` exists in `src/lib/topics.ts`
-Flag empty arrays and invalid IDs.
+  Flag empty arrays and invalid IDs.
 
 ### 6. Sitemap and Robots
-Verify `src/app/sitemap.ts` and `src/app/robots.ts` exist.
+
+Verify `src/app/sitemap.ts` and `src/app/robots.ts` exist, and that every category in `src/lib/categories.ts` has a route page at `src/app/<id>/page.tsx`.
 
 ### 7. Route Page Coverage
-For every topic in `src/lib/topics.ts`, verify a route page file exists at `src/app/<category>/<id>/page.tsx`. Flag missing route pages.
+
+Routes are generated from `src/lib/topics.ts` by `src/app/[category]/[topic]/page.tsx`, so every registered topic has a page. Verify `generateStaticParams` still maps over `topics` and that `sitemap.ts` lists every topic route.
 
 ## Output Format
 
 Report as a pass/fail table:
+
 ```
 | Check                          | Status | Details |
 |-------------------------------|--------|---------|

.claude/skills/create-js-topic/SKILL.md

@@ -1,61 +1,62 @@
 ---
-description: Create a new JavaScript visualization topic, scaffold all required files, register in topic and theory registries, and verify the build passes.
+description: Create a new visualization topic in any category (JavaScript, Frameworks, Backend, AI), scaffold all required files, register in topic and theory registries, and verify the build passes.
 ---
 
-# Create JS Topic
+# Create Topic
 
-Scaffold a new JavaScript visualization topic end-to-end. This skill handles the full multi-file workflow from topic registration to build verification.
+Scaffold a new visualization topic end-to-end for any non-React category (for React use `create-react-topic`). This skill handles the full multi-file workflow from topic registration to build verification.
 
 ## When to Use
 
-When the user asks to create, add, or build a new JavaScript topic or visualization.
+When the user asks to create, add, or build a new topic or visualization in the javascript, frameworks, backend, or ai category.
 
 ## Workflow
 
 1. **Gather inputs** from the user:
+   - Category (`javascript`, `frameworks`, `backend`, or `ai`; see `src/lib/categories.ts`)
    - Topic ID (kebab-case, e.g., `async-await`)
    - Title (display name, e.g., "Async/Await")
    - Difficulty (`beginner`, `intermediate`, or `advanced`)
    - `docsUrl` (MDN or authoritative reference URL)
    - Description (1-2 sentences for SEO and landing page cards)
    - Whether it uses ExampleSelector (multiple sub-examples)
-   - Whether it should be folder-based (recommended for complex topics)
 
-2. **Register the topic** in `src/lib/topics.ts`. Add to the `topics` array following the existing order convention.
+2. **Register the topic** in `src/lib/topics.ts`. Add to `TOPIC_DEFINITIONS` following the existing order convention. The route is derived; set `toolbar: "simple"` only if the topic has no example picker. Once registered, `npm run typecheck` reports every registry that still lacks an entry.
 
 3. **Add SEO keywords** in `src/lib/metadata.ts` under `TOPIC_KEYWORDS`. Add 4-7 relevant search terms.
 
-4. **Create the route page** at `src/app/javascript/<id>/page.tsx`. Follow the exact pattern from existing pages (see `src/app/javascript/generators/page.tsx` for reference).
+4. **Register the component** in `VISUALIZATIONS` in `src/components/visualizations/registry.tsx` (one `dynamic()` entry keyed by topic id). Routing is generated from the registry.
 
-5. **Scaffold the visualization component:**
-   - **Single-file:** `src/components/visualizations/<TopicName>.tsx`
-   - **Folder-based:** `src/components/visualizations/<topic-id>/` with `index.tsx`, `types.ts`, `helpers.ts`, `data.ts`, `components/`
+5. **Scaffold the visualization folder** at `src/components/visualizations/<topic-id>/` with `index.tsx`, `types.ts`, `helpers.ts`, `data.ts`, `components/`.
    - Read `docs/topic-authoring.md` for the full skeleton template.
-   - Read `docs/component-reference.md` for component APIs and hooks.
+   - Read `docs/component-reference.md` for component APIs and hooks, including PipelineDiagram, TokenChips, HeatmapGrid, MetricBars, and MessageFlow for backend and AI topics.
+   - Use `useExampleTopic(EXAMPLES)` with 2 or 3 examples, `VisualizationToolbar` with an `ExamplePicker` in `leading`, and `SourceCodePanel` for the code.
 
-6. **If using ExampleSelector:** Add topic ID to `SELECTOR_TOOLBAR_TOPIC_IDS` in `src/components/layout/VisualizationPageShell.tsx`.
+6. **Extend the shared types:** the step interface extends `BaseStep`, the example interface extends `SourceExample<Step>` (both from `src/types/visualization.ts`).
 
-7. **Create theory content** at `src/content/theory/javascript/<id>.ts`. Read `docs/theory-authoring.md` for field-by-field guidance and tone requirements.
+7. **Create theory content** at `src/content/theory/<category>/<id>.ts`. Read `docs/theory-authoring.md` for field-by-field guidance and tone requirements.
 
 8. **Register theory** in `src/content/theory/index.ts`. Import and add to `THEORY_CONTENT_BY_TOPIC_ID`.
 
 9. **Add theory description** in `src/lib/metadata.ts` under `TOPIC_THEORY_DESCRIPTIONS`.
 
-10. **Verify:** Run `npm run build`. Fix any errors.
+10. **Add inbound links:** add the new ID to `relatedTopicIds` of 2 or more existing theory files (keep each list at 3 to 5).
+
+11. **Verify:** Run `npm run audit:steps -- <id>` and fix anything it flags, then `npm run verify` (lint, typecheck, format, step audit, build).
 
 ## Key Files
 
 - `src/lib/topics.ts` -- topic registry
 - `src/lib/metadata.ts` -- keywords and theory descriptions
-- `src/app/javascript/<id>/page.tsx` -- route page (new)
+- `src/components/visualizations/registry.tsx` -- component registry
 - `src/components/visualizations/` -- visualization component (new)
-- `src/content/theory/javascript/<id>.ts` -- theory content (new)
+- `src/content/theory/<category>/<id>.ts` -- theory content (new)
 - `src/content/theory/index.ts` -- theory registry
-- `src/components/layout/VisualizationPageShell.tsx` -- SELECTOR_TOOLBAR_TOPIC_IDS
 
 ## Documentation
 
-- `docs/topic-authoring.md` -- full JS topic workflow and checklist
+- `docs/topic-authoring.md` -- full topic workflow and checklist
+- `docs/categories.md` -- category registry
 - `docs/component-reference.md` -- component APIs, hooks, animations
 - `docs/theory-authoring.md` -- theory content requirements
 
@@ -64,7 +65,7 @@ When the user asks to create, add, or build a new JavaScript topic or visualizat
 - No em dashes or AI-sounding language in content
 - No emojis in step descriptions or UI text
 - Use `VISUALIZATION_PANEL_TITLES` and `VISUALIZATION_EMPTY_STATES` from `uiCopy.ts`
-- Wrap `setActiveExampleId` in `handleExampleChange` callback
+- Use `useExampleTopic` + `VisualizationToolbar` + `ExamplePicker`; never hand-roll the toolbar or step pill
 - Theory `relatedTopicIds` must have 3-5 valid IDs (never empty)
-- Code line fading guard: `isDone && !isActive`
+- Source code renders through `SourceCodePanel`
 - Components use `"use client"` directive and named exports

.claude/skills/create-react-topic/SKILL.md

@@ -22,43 +22,44 @@ When the user asks to create, add, or build a new React topic or visualization.
 
 2. **Read the reference implementation** at `src/components/visualizations/reconciliation/` -- read all files (`types.ts`, `helpers.ts`, `data.ts`, `index.tsx`, `components/DiffPanel.tsx`) to understand the exact pattern.
 
-3. **Register the topic** in `src/lib/topics.ts` with `category: "react"` and `route: "/react/<id>"`.
+3. **Register the topic** in `src/lib/topics.ts` with `category: "react"`. The route is derived; do not add one. Once registered, `npm run typecheck` reports every registry that still lacks an entry.
 
 4. **Add SEO keywords** in `src/lib/metadata.ts` under `TOPIC_KEYWORDS`.
 
-5. **Create the route page** at `src/app/react/<id>/page.tsx`. Follow the pattern from `src/app/react/reconciliation/page.tsx`.
+5. **Register the component** in `VISUALIZATIONS` in `src/components/visualizations/registry.tsx` (one `dynamic()` entry keyed by topic id). Routing is generated from the registry.
 
 6. **Scaffold the folder structure:**
+
    ```
    src/components/visualizations/<topic-id>/
      types.ts       # Step, Example, Kind types
      helpers.ts     # kindBadgeClass, kindLabel using shared factories
      data.ts        # EXAMPLES array with step data
-     index.tsx      # Main component with ExampleSelector + ComponentTreeDiagram
+     index.tsx      # useExampleTopic + VisualizationToolbar + ExamplePicker + ComponentTreeDiagram
      components/    # Sub-components as needed
    ```
+
    - Read `docs/react-topic-authoring.md` for React-specific patterns
    - Read `docs/component-reference.md` for ComponentTreeDiagram API
 
-7. **Add to SELECTOR_TOOLBAR_TOPIC_IDS** in `src/components/layout/VisualizationPageShell.tsx`.
+7. **Set `toolbar: "simple"`** in the topic entry only if the topic has no example picker (React topics normally do, so skip this).
 
 8. **Create theory content** at `src/content/theory/react/<id>.ts`. Read `docs/theory-authoring.md` for requirements.
 
 9. **Register theory** in `src/content/theory/index.ts`.
 
 10. **Add theory description** in `src/lib/metadata.ts` under `TOPIC_THEORY_DESCRIPTIONS`.
 
-11. **Verify:** Run `npm run build`. Fix any errors.
+11. **Verify:** Run `npm run audit:steps -- <id>` and fix anything it flags, then `npm run verify`.
 
 ## Key Files
 
 - `src/lib/topics.ts` -- topic registry
 - `src/lib/metadata.ts` -- keywords and theory descriptions
-- `src/app/react/<id>/page.tsx` -- route page (new)
+- `src/components/visualizations/registry.tsx` -- component registry
 - `src/components/visualizations/<topic-id>/` -- visualization folder (new)
 - `src/content/theory/react/<id>.ts` -- theory content (new)
 - `src/content/theory/index.ts` -- theory registry
-- `src/components/layout/VisualizationPageShell.tsx` -- SELECTOR_TOOLBAR_TOPIC_IDS
 - `src/components/visualizations/reconciliation/` -- reference implementation
 
 ## Documentation
@@ -71,7 +72,7 @@ When the user asks to create, add, or build a new React topic or visualization.
 ## NeonPanel Tone Conventions
 
 | Panel          | Tone     |
-|----------------|----------|
+| -------------- | -------- |
 | Source Code    | `amber`  |
 | Previous Tree  | `cyan`   |
 | New Tree       | `green`  |
@@ -83,5 +84,5 @@ When the user asks to create, add, or build a new React topic or visualization.
 - Use `ComponentTreeDiagram` for tree visualizations (auto-scales, no horizontal scroll)
 - No em dashes or AI-sounding language in content
 - No emojis in step descriptions or UI text
-- Use `handleExampleChange` callback wrapper
+- Use `useExampleTopic` + `VisualizationToolbar` + `ExamplePicker`; never hand-roll the toolbar or step pill
 - Theory `relatedTopicIds` must have 3-5 valid IDs (never empty)