Add four topics, fix lint and link graph, prepare for open source

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,46 @@
+name: Bug report
+description: Something in a visualization or page does not work as expected
+labels: [bug]
+body:
+  - type: input
+    id: topic
+    attributes:
+      label: Topic
+      description: Which topic, and which step if it is step-specific.
+      placeholder: Event Loop, step 4
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: What happened instead
+      description: A screen recording is worth more than a paragraph here.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Open /javascript/event-loop
+        2. Select the async/await example
+        3. Press play
+    validations:
+      required: true
+
+  - type: input
+    id: browser
+    attributes:
+      label: Browser and OS
+      placeholder: Firefox 141, macOS 15
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or idea
+    url: https://github.com/tornike14/visualizejs/discussions
+    about: Ask about the project or float an idea before opening an issue.
+  - name: Security vulnerability
+    url: https://github.com/tornike14/visualizejs/security/advisories/new
+    about: Report privately. Please do not open a public issue.

.github/ISSUE_TEMPLATE/content_correction.yml

@@ -0,0 +1,33 @@
+name: Content correction
+description: A theory page or step description states something inaccurate
+labels: [content, correction]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Technical accuracy matters more here than any feature. Thanks for taking
+        the time to report this.
+
+  - type: input
+    id: location
+    attributes:
+      label: Where
+      description: Page URL, and the section or step number.
+      placeholder: /react/hooks/theory, "Common Mistakes" section
+    validations:
+      required: true
+
+  - type: textarea
+    id: claim
+    attributes:
+      label: What it currently says
+    validations:
+      required: true
+
+  - type: textarea
+    id: correction
+    attributes:
+      label: What it should say, and why
+      description: A link to the spec, MDN, or the React docs settles it fastest.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/topic_request.yml

@@ -0,0 +1,47 @@
+name: Topic request
+description: Propose a new JavaScript or React concept to visualize
+labels: [topic request]
+body:
+  - type: input
+    id: concept
+    attributes:
+      label: Concept
+      placeholder: Web Workers
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      options:
+        - JavaScript
+        - React
+    validations:
+      required: true
+
+  - type: textarea
+    id: visual
+    attributes:
+      label: What would the visualization show
+      description: >
+        The concepts that work well here have moving parts worth watching:
+        state that changes over time, a structure being traversed, or an
+        ordering that surprises people. Describe the panels and what changes
+        between steps.
+    validations:
+      required: true
+
+  - type: textarea
+    id: misconception
+    attributes:
+      label: What do people usually get wrong about it
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: contributing
+    attributes:
+      label: Would you like to build it?
+      options:
+        - label: I would like to work on this myself

.github/pull_request_template.md

@@ -0,0 +1,34 @@
+## What changed
+
+<!-- Describe the change and why it is needed. Link the issue if there is one. -->
+
+## Type
+
+- [ ] Bug fix
+- [ ] Content correction
+- [ ] New topic
+- [ ] Improvement to an existing visualization
+- [ ] Docs or tooling
+
+## Verification
+
+- [ ] `npm run lint` passes
+- [ ] `npm run build` passes
+- [ ] `npm run check:registries` passes
+
+## For a new topic
+
+Confirm each registry was updated, or delete this section.
+
+- [ ] `src/lib/topics.ts`
+- [ ] Route at `src/app/<category>/<topic-id>/page.tsx`
+- [ ] Visualization at `src/components/visualizations/<topic-id>/`
+- [ ] Theory content at `src/content/theory/<category>/<topic-id>.ts`
+- [ ] `THEORY_CONTENT_BY_TOPIC_ID` in `src/content/theory/index.ts`
+- [ ] `TOPIC_KEYWORDS` and `TOPIC_THEORY_DESCRIPTIONS` in `src/lib/metadata.ts`
+- [ ] `SELECTOR_TOOLBAR_TOPIC_IDS` if the topic uses `ExampleSelector`
+- [ ] Added to the `relatedTopicIds` of 2 or more existing theory files
+
+## Screenshots
+
+<!-- Visualization changes are much easier to review with a screenshot or recording. -->

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Lint and build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+
+  registry-check:
+    name: Registry integrity
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Verify every topic is fully registered
+        run: node scripts/check-registries.mjs

.gitignore

@@ -24,6 +24,10 @@
 .DS_Store
 *.pem
 
+# claude code local state
+.claude/settings.local.json
+.claude/worktrees/
+
 # debug
 npm-debug.log*
 yarn-debug.log*

CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## The Short Version
+
+Be respectful. This project exists to help people learn, and learners ask basic questions. Treat every question as a reasonable one.
+
+## Expected Behavior
+
+- Give feedback on the code and the content, not the person who wrote it.
+- Assume the other person is acting in good faith.
+- Accept that maintainers may decline a contribution, and explain your reasoning when you decline someone else's.
+- Correct technical inaccuracies directly and without condescension. Getting the internals right is the point of this project, so corrections are welcome and expected.
+
+## Unacceptable Behavior
+
+- Harassment, insults, or personal attacks.
+- Discriminatory language or imagery of any kind.
+- Publishing other people's private information without permission.
+- Sustained disruption of discussions or reviews.
+
+## Scope
+
+This applies in issues, pull requests, discussions, and any other space where someone is representing the project.
+
+## Reporting
+
+Report a problem through GitHub's [private vulnerability reporting](https://github.com/tornike14/visualizejs/security/advisories/new) or by contacting the maintainer directly through their GitHub profile. Reports stay confidential.
+
+Maintainers will review and respond. Outcomes range from a warning to a permanent ban from the project's spaces, depending on severity.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing to VisualizeJS
+
+Thanks for wanting to help. This project explains JavaScript and React internals through animations, so contributions range from fixing a typo in a theory page to building a whole new topic.
+
+## Ways to Contribute
+
+- **Report a bug.** Open an issue with the topic, the step number, and what you expected.
+- **Correct the content.** If a theory page states something inaccurate, that matters more than any feature. Cite a spec or the React docs where you can.
+- **Improve an existing visualization.** Clearer steps, better labels, missing edge cases.
+- **Add a topic.** The largest kind of contribution. Read the section below before starting.
+
+For anything beyond a small fix, open an issue first so we can agree on the approach before you spend time on it.
+
+## Setup
+
+```bash
+npm install
+npm run dev
+```
+
+Node 20 or newer. Before opening a pull request:
+
+```bash
+npm run lint
+npm run build
+```
+
+Both must pass. CI runs the same two commands.
+
+## Project Conventions
+
+These are enforced in review. Most exist because inconsistency between 28 topics is more expensive than it looks.
+
+**Content**
+
+- No em dashes anywhere in user-facing text.
+- No emojis in step descriptions or UI text.
+- Write plainly. Avoid marketing language and filler such as "powerful", "seamless", or "it's worth noting".
+- Explain the mechanism. "React marks the fiber for work" beats "React handles it efficiently".
+
+**Code**
+
+- React components use const form (`const Component = () =>`), not function declarations.
+- Visualization components need the `"use client"` directive and named exports.
+- Component files target 200 lines, hard limit 300. Split into `components/` when you exceed it. Data files (`data.ts`) are exempt since they hold content.
+- Import panel titles and empty states from `src/lib/visualization/uiCopy.ts`. Never hardcode them.
+- Wrap `setActiveExampleId` in a `handleExampleChange` callback rather than passing the setter to `onSelect` directly.
+- Code line fading uses the guard `isDone && !isActive`. Never fade an active line.
+
+**Structure**
+
+Topics use a folder under `src/components/visualizations/<topic-id>/`:
+
+```
+index.tsx        Main component, wires playback and layout
+types.ts         Topic-specific types
+data.ts          Examples and step definitions
+helpers.ts       Pure functions used by the panels
+components/      Panel components
+```
+
+Reconciliation is the reference implementation for React topics. Event Loop is the reference for sandbox mode.
+
+## Adding a Topic
+
+A topic is not finished when the visualization renders. It is registered in several places, and missing one produces a page that half works. Work through all of these.
+
+**1. Topic registry** in [`src/lib/topics.ts`](src/lib/topics.ts)
+
+Add an entry with `id`, `title`, `category`, `route`, `description`, `difficulty`, and `docsUrl`. The `id` is the slug used everywhere else, so pick it carefully.
+
+**2. Route** at `src/app/<category>/<topic-id>/page.tsx`
+
+Copy an existing page. It resolves the topic with `getTopicOrThrow`, lazy-loads the visualization with `next/dynamic`, wraps it in `ErrorBoundary` and `VisualizationPageShell`, and exports `createTopicMetadata(topic)`.
+
+**3. Visualization** at `src/components/visualizations/<topic-id>/`
+
+Use `useStepPlayback` from `src/hooks/useStepPlayback.ts` for transport controls. Read [`docs/topic-authoring.md`](docs/topic-authoring.md), or [`docs/react-topic-authoring.md`](docs/react-topic-authoring.md) for React topics.
+
+**4. Theory content** at `src/content/theory/<category>/<topic-id>.ts`
+
+Implements `TopicTheoryContent`: `summary`, `whatItIs`, `howItWorks`, `commonMistakes`, `interviewQuestions`, and `relatedTopicIds`. See [`docs/theory-authoring.md`](docs/theory-authoring.md).
+
+`relatedTopicIds` must hold 3 to 5 valid topic IDs and must not include the topic's own ID.
+
+**5. Theory registry** in [`src/content/theory/index.ts`](src/content/theory/index.ts)
+
+Add the import and the entry in `THEORY_CONTENT_BY_TOPIC_ID`. `VisualizationPageShell` reads this map to render the theory sections beneath the visualization, so a topic missing here renders without any theory.
+
+**6. SEO metadata** in [`src/lib/metadata.ts`](src/lib/metadata.ts)
+
+Add entries to both `TOPIC_KEYWORDS` (4 to 8 search phrases) and `TOPIC_THEORY_DESCRIPTIONS` (one or two sentences, under 160 characters).
+
+**7. Toolbar registry** in [`src/components/layout/VisualizationPageShell.tsx`](src/components/layout/VisualizationPageShell.tsx)
+
+If your topic uses `ExampleSelector`, add its ID to `SELECTOR_TOOLBAR_TOPIC_IDS`. Skipping this makes the loading skeleton the wrong shape.
+
+**8. Inbound links**
+
+Add your topic ID to the `relatedTopicIds` of 2 or more existing theory files. A topic nothing links to is a dead end for readers and for search engines. Keep each list within the 3 to 5 range when you do this, swapping out a weaker link if needed.
+
+### Before You Open the PR
+
+```bash
+npm run lint
+npm run build
+```
+
+Then check that `/your-route` renders with the theory sections below the visualization, the sitemap at `/sitemap.xml` includes the route, and the related topic links at the bottom of the page resolve.
+
+## Pull Requests
+
+- Branch from `develop`, not `main`.
+- One topic or one fix per pull request.
+- Describe what changed and why. Screenshots or a screen recording help a lot for visualization changes.
+- Say which registries you touched when adding a topic.
+
+## Reporting Bugs
+
+Include the topic, the browser, the step where it goes wrong, and what you expected instead. A screen recording is worth more than a paragraph of description.
+
+## Questions
+
+Open a [discussion](https://github.com/tornike14/visualizejs/discussions) or an issue. Asking before building saves everyone time.