diff --git a/.claude/skills/add-feature-demo/SKILL.md b/.claude/skills/add-feature-demo/SKILL.md
index 344e9e623..4b21b8396 100644
--- a/.claude/skills/add-feature-demo/SKILL.md
+++ b/.claude/skills/add-feature-demo/SKILL.md
@@ -6,8 +6,8 @@ description: Use this skill when adding a new feature to the engine.
 # Add a Demo
 
 `documentation-site/src/pages/demos/<name>/` holds interactive, in-browser
-demos of engine features, each rendered through
-`documentation-site/src/components/Demo.tsx`. Read `AGENTS.md`'s
+demos of engine features, each rendered through `DemoPage`
+(`documentation-site/src/components/demo-page/`). Read `AGENTS.md`'s
 "Documentation Site Demos" section first for the `file:..`/`dist` gotcha
 that governs how demos are verified — it applies to every demo, new or
 existing.
@@ -57,8 +57,8 @@ Follow the existing file split, every demo uses the same shape:
   `_create-boundaries.ts` from `_spawn-shapes.ts`, not into one monolithic
   file — each file also becomes its own tab in the demo's code viewer (see
   step 3).
-- `index.tsx` — the page itself, a thin wrapper around `<Demo>` (see step
-  3).
+- `index.tsx` — the page itself, a thin wrapper around `<DemoPage>` (see
+  step 3).
 
 Demo-only components/systems (input handling for interaction, camera
 follow, reset-on-key, etc.) still follow the engine's own component/system
@@ -71,59 +71,93 @@ instead of `/src` because they're not part of the public API.
 import React, { JSX } from 'react';
 import { create<PascalName>Game } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
-import someOtherCode from '!!raw-loader!./_some-other-file';
+import thingSystemCode from '!!raw-loader!./_thing.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function <PascalName>(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: '<Human Title> Demo',
-        description: 'A demo showcasing <what it shows>.',
-      }}
-      header="<Human Title>"
-      blurb="<1-3 sentences: what the demo shows, what the engine feature
-        does, and how to interact with it (click/drag/keys) if applicable.>"
+    <DemoPage
+      slug="<kebab-case-name>"
       createGame={create<PascalName>Game}
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'some-other-file.ts', content: someOtherCode },
+      controls={[
+        { inputs: ['←', 'A'], action: 'Move left' },
+        { inputs: [{ device: 'mouse', label: 'Click' }], action: 'Select' },
+      ]}
+      highlights={[
+        {
+          text: '<One short sentence on what the engine does here.>',
+          file: 'thing.system.ts',
+        },
+      ]}
+      docLinks={[{ label: '<Guide>', to: '/docs/docs/<module>/<page>' }]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary: '<One sentence on what the file does.>',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: '<Feature>',
+          files: [
+            {
+              name: 'thing.system.ts',
+              summary: '<One sentence.>',
+              content: thingSystemCode,
+            },
+          ],
+        },
       ]}
     />
   );
 }
 ```
 
-Each `codeFiles` entry drives one tab in the demo's live code viewer, so
-list every demo-source file the reader would need to fully understand the
-scene, in the order that makes it easiest to follow (usually `game.ts`
-first, since it's the entry point). Import each via `!!raw-loader!` exactly
-like `gameCode` — this is what pulls the raw source text in at build time,
-not the compiled/imported binding.
-
-If the demo needs live interaction controls beyond canvas input (a slider,
-a toggle button), pass a React node via `interactions` — see
-`space-shooter/index.tsx` and `_BloomControls.tsx` for the pattern of a
-small controls component alongside the demo files.
-
-## 4. Wire it into the navbar
-
-Add an entry to the `Demos` dropdown in
-`documentation-site/docusaurus.config.ts` (currently around line 114),
-alphabetical-ish grouping isn't strictly enforced but new entries are
-generally added near thematically similar ones (physics demos are grouped
-together, etc.):
-
-```typescript
-{
-  to: 'demos/<kebab-case-name>',
-  label: '<Human Label>',
-},
-```
-
-This is the only place demos are registered/linked — there's no separate
-index page or sidebar to update.
+The page's title and one-line summary come from the demo's entry in
+`documentation-site/src/data/demos.ts` (step 4), so the catalogue card and
+the page always agree. Write the rest for a reader who has never seen the
+feature:
+
+- `controls`: one row per action, with alternative inputs in the same
+  row. Check each binding against the demo's input code. Leave it out for
+  a demo you only watch.
+- `highlights`: 3-5 "How it works" points, one short sentence each, each
+  linked to the file that implements it. Clicking the link opens that file
+  in the code explorer.
+- `docLinks`: the guides under `documentation-site/docs/docs` that cover
+  the feature (`/docs/docs/<path>`, a folder's `index.md` is
+  `/docs/docs/<folder>`).
+- `fileGroups`: every demo-source file a reader needs, grouped by purpose,
+  with `create-game.ts` alone under "Start here". Name each after its
+  source file without the leading underscore, and keep the
+  `.component.ts`/`.system.ts` suffixes: the explorer's type icons and
+  filter come from them. Import each via `!!raw-loader!` exactly like
+  `gameCode`, which pulls in the raw source text at build time.
+- **Never list React or other framework code** (`.tsx`/`.jsx`) in
+  `fileGroups`. The explorer shows engine code a reader can reuse in their
+  own game; a settings panel that only exists to drive this site's page
+  isn't that. `DemoPage` throws if a `.tsx`/`.jsx` file is listed.
+
+If the demo needs something else beside the game, such as live settings (a
+slider, a toggle) or a legend for colors in the scene, pass it as `panels`,
+wrapped in `DemoPanel` (with `DemoLegend` for a legend). Build live
+settings from `DemoSettings`, `DemoSlider`, `DemoToggle`, `DemoChoice` and
+`DemoTextField`. Keep the game-side logic the panel changes in a plain
+`.ts` file (shown in the explorer) and the React panel itself out of the
+explorer. See `text/index.tsx` and `easing-functions/index.tsx`.
+
+## 4. Add it to the demo catalogue
+
+Add an entry to `documentation-site/src/data/demos.ts` with the demo's
+`slug` (its directory name), `title`, a one-sentence `description` (what
+you see or do, and which feature it shows; it's the page's summary too) and
+the category slugs it belongs to. See AGENTS.md's "Demo Catalogue and
+Categories" section.
 
 ## 5. Verify
 
@@ -138,23 +172,14 @@ verification checklist:
    already-built, unchanged API).
 2. From `documentation-site/`: `npm run typecheck`, then `npm run build`
    (`docusaurus build`) — this is what actually catches a broken import
-   against the published package surface or an MDX/broken-link error from
-   the navbar entry.
+   against the published package surface or a broken `docLinks` entry.
 3. `npm run start` in `documentation-site/` (or reuse a running dev
    server), open `demos/<kebab-case-name>` in a browser with a full page
    reload (fast refresh doesn't guarantee a clean re-init), and confirm it
-   renders and behaves correctly — click through any interactions the
-   `blurb` describes.
-4. **Also click the entry from the actual "Demos" navbar dropdown** - don't
-   only visit the URL directly. Adding the array entry in step 4 above is
-   necessary but not sufficient: the dropdown has grown to ~30 entries and
-   its `.dropdown__menu` is capped to the viewport height with internal
-   scrolling (`documentation-site/src/css/custom.css`) specifically so
-   every entry stays reachable regardless of list length - confirm your new
-   entry actually scrolls into view and is clickable in a real browser,
-   since a syntactically-correct array entry can still end up unreachable
-   if that CSS ever regresses or a future redesign changes the dropdown
-   markup.
+   renders and behaves correctly — try every control the page lists and
+   open each highlight's file link.
+4. Open the demo from its card on `/demos` too, to check the catalogue
+   entry.
 
 If this was prompted by a `/src` change (not a brand-new demo for existing
 functionality), also re-run the full root-level `CLAUDE.md` verification
diff --git a/.cspell/project-words.txt b/.cspell/project-words.txt
index 05e559eab..7538c4616 100644
--- a/.cspell/project-words.txt
+++ b/.cspell/project-words.txt
@@ -394,3 +394,13 @@ Zoltan
 rrggbb
 rrggbbaa
 zstandard
+sublist
+orbitron
+mcinerney
+inerney
+rasmus
+andersson
+oxanium
+overcrafted
+squaremeapixel
+manu
diff --git a/AGENTS.md b/AGENTS.md
index c852ea38b..cd12289ad 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -673,7 +673,14 @@ e2e/playwright-report` opens the HTML report, which links each test's
 
 `documentation-site/src/pages/demos/<name>/` holds interactive, in-browser
 demos of engine features (`physics`, `ecs`, `particles`, `rendering`, ...),
-each rendered through `documentation-site/src/components/Demo.tsx`.
+each rendered through `DemoPage` (`documentation-site/src/components/demo-page/`):
+the running game with its controls and a short "How it works" list beside
+it, and a code explorer for the demo's source below. Its title and summary
+come from the demo's entry in `documentation-site/src/data/demos.ts`. The
+`add-feature-demo` skill shows how to write a page. The code explorer only
+shows engine code a reader can reuse: never list React or other framework
+code (`.tsx`/`.jsx`) in it, such as a settings panel that only drives the
+site's page.
 
 **Critical gotcha**: these demos import the engine as a published package
 (e.g. `import { addRigidBodyComponent } from '@forge-game-engine/forge/physics'`),
@@ -721,8 +728,9 @@ wrapper around the shared `CategoryDemosPage` component.
 The catalogue's data lives separately from the demo pages themselves:
 
 - `documentation-site/src/data/demo-categories.ts` - the fixed list of
-  categories (slug, title, description, card image under
-  `static/img/demos/categories/`).
+  categories (slug, title, description, and the line icon its card shows,
+  from `src/components/ModuleIcon.tsx`, the same set the homepage's feature
+  grid uses).
 - `documentation-site/src/data/demos.ts` - one entry per demo (slug, title,
   short description, and the category slugs it belongs to). A demo can
   belong to more than one category - e.g. the car demo is tagged both
@@ -731,8 +739,8 @@ The catalogue's data lives separately from the demo pages themselves:
 
 **When adding a new demo**, also add an entry to `demos.ts` with the
 category slugs it belongs to (adding a new category itself means adding to
-`demo-categories.ts` and a matching SVG under
-`static/img/demos/categories/`, plus a new
+`demo-categories.ts` with a `ModuleIcon` name, drawing a new icon in
+`ModuleIcon.tsx` in the same style if none fits, plus a new
 `src/pages/demos/category/<slug>/index.tsx` wrapper). A demo that combines
 many engine features into a complete mini-game (like the space shooter,
 brick breaker and car demos) belongs in the `games` category regardless of
diff --git a/documentation-site/docs/credits.md b/documentation-site/docs/credits.md
index 3d29e30be..176e0dd8d 100644
--- a/documentation-site/docs/credits.md
+++ b/documentation-site/docs/credits.md
@@ -2,24 +2,82 @@
 title: Credits and attributions
 ---
 
-## Icons
+Forge's demos, documentation and website use art, audio and fonts made by
+the people below. Thank you to all of them.
+
+## Sprites and textures
 
-Scroll down icons created by [Smashicons](https://www.flaticon.com/free-icons/scroll-down) from [Flaticon](https://www.flaticon.com/)
+- [Kenney](https://kenney.nl), all licensed
+  [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/):
+  - [UI Pack](https://kenney.nl/assets/ui-pack): the buttons, sliders, text
+    inputs and panels in the UI demos.
+  - [Fantasy UI Borders](https://kenney.nl/assets/fantasy-ui-borders): the
+    frames in the nine-slice and masks demos.
+  - [Particle Pack](https://kenney.nl/assets/particle-pack): the particle
+    textures in the particles demo.
+  - [Pattern Pack](https://kenney.nl/assets/pattern-pack): the backgrounds in
+    the physics demos.
+  - [Pirate Pack](https://kenney.nl/assets/pirate-pack): the sprites in the
+    pirate battle demo.
+  - [Puzzle Pack 2](https://kenney.nl/assets/puzzle-pack-2): the sprites in
+    the brick breaker demo.
+  - [Rolling Ball Assets](https://kenney.nl/assets/rolling-ball-assets): the
+    balls and blocks in the physics demos.
+  - [Simple Space](https://kenney.nl/assets/simple-space): ships, meteors and
+    stars in the space demos.
+- [Screaming Brain Studios](https://screamingbrainstudios.com/dl-seamless-space-backgrounds/):
+  the nebula space background.
+- [Wenrexa](https://opengameart.org/content/assets-free-laser-bullets-pack-2020):
+  the laser bullets in the space shooter demo.
+- [Squaremeapixel](https://squaremeapixel.itch.io/space-pack): the
+  spaceships and asteroids in the space shooter demo.
+- [CodeManu](https://codemanu.itch.io/vfx-free-pack): the explosion
+  animation in the space shooter demo.
+- [Overcrafted](https://overcrafted.itch.io/free-paid-vehicle-car-sprites-):
+  the car body and wheels in the car demo.
+- [Deep-Fold's Pixel Planet Generator](https://deep-fold.itch.io/pixel-planet-generator):
+  the pixel-art planet in the rendering demos and blog.
+- [OboroPixel](https://oboropixel.itch.io/characters-animations-asset-pack):
+  the soldier sprite sheets in the sprite animation docs.
 
-## Sprites
+## Music and sound effects
 
-- Some assets used in the demos and documentation have been provided by [Screaming Brain Studios - OpenGameArt.org](https://opengameart.org/content/seamless-space-backgrounds)
-- Some assets used in the demos and documentation have been provided by [Wenrexa - OpenGameArt.org](https://opengameart.org/content/assets-free-laser-bullets-pack-2020)
-- Some assets used in the demos and documentation have been provided by [OboroPixel - itch.io](https://oboropixel.itch.io/characters-animations-asset-pack)
+- Music by
+  [GerardDEP](https://pixabay.com/users/gerarddep-48160304/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=363808)
+  from
+  [Pixabay](https://pixabay.com/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=363808).
+- Sound effects by
+  [LoLa Joy](https://pixabay.com/users/u_xg7ssi08yr-48039129/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=381976)
+  from
+  [Pixabay](https://pixabay.com/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=381976).
 
 ## Fonts
 
-- The engine's shipped default font atlas, and the text rendering demo's
-  font, both use [Liberation Sans](https://github.com/liberationfonts)
-  (Copyright (c) 2012 Red Hat, Inc. with Reserved Font Name Liberation),
-  licensed under the [SIL Open Font License, Version 1.1](https://scripts.sil.org/OFL).
+All licensed under the
+[SIL Open Font License, Version 1.1](https://openfontlicense.org):
+
+- [Liberation Sans](https://github.com/liberationfonts) (Copyright (c) 2012
+  Red Hat, Inc. with Reserved Font Name Liberation): the engine's default
+  font atlas, used by the text demo.
+- [Orbitron](https://github.com/theleagueof/orbitron) by Matt McInerney:
+  the website's headings.
+- [Inter](https://github.com/rsms/inter) by Rasmus Andersson: the website's
+  body text.
+- [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) by JetBrains:
+  the website's code.
+
+## Icons
+
+- [Font Awesome Free](https://fontawesome.com) icons, licensed
+  [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+## Galactic Journey
 
-## Music
+The gameplay video on the home page is from
+[Galactic Journey](https://galactic-journey-6517e.web.app), a game made with
+Forge. Besides the art credited above, it uses:
 
-- Some music used in the demos and documentation have been provided by [GerardDEP](https://pixabay.com/users/gerarddep-48160304/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=363808) from [Pixabay](https://pixabay.com//?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=363808)
-- Some sound effects used in the demos and documentation have been provided by [LoLa Joy](https://pixabay.com/users/u_xg7ssi08yr-48039129/?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=381976) from [Pixabay](https://pixabay.com//?utm_source=link-attribution&utm_medium=referral&utm_campaign=music&utm_content=381976)
+- The sci-fi UI kit by [Wenrexa](https://wenrexa.itch.io).
+- [Oxanium](https://github.com/sevmeyer/oxanium) (Copyright 2019 The Oxanium
+  Project Authors), licensed under the
+  [SIL Open Font License, Version 1.1](https://openfontlicense.org).
diff --git a/documentation-site/docusaurus.config.ts b/documentation-site/docusaurus.config.ts
index 36876486f..9d9740c3a 100644
--- a/documentation-site/docusaurus.config.ts
+++ b/documentation-site/docusaurus.config.ts
@@ -56,7 +56,16 @@ const config: Config = {
           onUntruncatedBlogPosts: 'warn',
         },
         theme: {
-          customCss: './src/css/custom.css',
+          // Self-hosted fonts: Orbitron for headings, Inter for body text and
+          // JetBrains Mono for code and small eyebrow labels.
+          customCss: [
+            require.resolve('@fontsource/orbitron/600.css'),
+            require.resolve('@fontsource/orbitron/700.css'),
+            require.resolve('@fontsource-variable/inter/index.css'),
+            require.resolve('@fontsource/jetbrains-mono/400.css'),
+            require.resolve('@fontsource/jetbrains-mono/500.css'),
+            './src/css/custom.css',
+          ],
         },
       } satisfies Preset.Options,
     ],
@@ -95,6 +104,7 @@ const config: Config = {
     // Replace with your project's social card
     image: 'img/forge-social-card.jpg',
     colorMode: {
+      defaultMode: 'dark',
       respectPrefersColorScheme: true,
     },
     navbar: {
diff --git a/documentation-site/package-lock.json b/documentation-site/package-lock.json
index c5ee2dc0a..82e96e23e 100644
--- a/documentation-site/package-lock.json
+++ b/documentation-site/package-lock.json
@@ -12,6 +12,9 @@
         "@docusaurus/faster": "^3.10.2",
         "@docusaurus/preset-classic": "^3.10.1",
         "@docusaurus/theme-mermaid": "^3.10.1",
+        "@fontsource-variable/inter": "^5.3.0",
+        "@fontsource/jetbrains-mono": "^5.3.0",
+        "@fontsource/orbitron": "^5.3.0",
         "@forge-game-engine/forge": "file:..",
         "@mdx-js/react": "^3.1.1",
         "clsx": "^2.0.0",
@@ -36,7 +39,7 @@
     },
     "..": {
       "name": "@forge-game-engine/forge",
-      "version": "0.25.8",
+      "version": "0.26.1",
       "license": "MIT",
       "dependencies": {
         "@types/imurmurhash": "^0.1.4",
@@ -4288,6 +4291,33 @@
         "tslib": "^2.4.0"
       }
     },
+    "node_modules/@fontsource-variable/inter": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/inter/-/inter-5.3.0.tgz",
+      "integrity": "sha512-OupL48va4JNofb97w6NYeF9S7W/kHNKM0Er8Dem5nqi4jeOLrVJDoE8tZEpnMJmtkvNbB1EIPPwHcdkF6b1oUA==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource/jetbrains-mono": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource/jetbrains-mono/-/jetbrains-mono-5.3.0.tgz",
+      "integrity": "sha512-fqDfB5I9f1p1TV486aUgB9t8zP84P0O1FtQR5Ol9vjwPy+S+EIGlVYm1cvj2W5shcZMTg2nZFdVMoH5wFu8a1A==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource/orbitron": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@fontsource/orbitron/-/orbitron-5.3.0.tgz",
+      "integrity": "sha512-+BhPsbUAo/AF7sRcf+TEexm+EWWkgTiR9Zwb7AhYIPkc5oplfvw0C45Oc2xlKPhwVEmxG8hHuA6/Ansbl+Bc6w==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
     "node_modules/@forge-game-engine/forge": {
       "resolved": "..",
       "link": true
diff --git a/documentation-site/package.json b/documentation-site/package.json
index eecf2b174..d25284e00 100644
--- a/documentation-site/package.json
+++ b/documentation-site/package.json
@@ -22,6 +22,9 @@
     "@docusaurus/faster": "^3.10.2",
     "@docusaurus/preset-classic": "^3.10.1",
     "@docusaurus/theme-mermaid": "^3.10.1",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource/jetbrains-mono": "^5.3.0",
+    "@fontsource/orbitron": "^5.3.0",
     "@forge-game-engine/forge": "file:..",
     "@mdx-js/react": "^3.1.1",
     "clsx": "^2.0.0",
diff --git a/documentation-site/src/components/CategoryDemosPage.tsx b/documentation-site/src/components/CategoryDemosPage.tsx
index 28eedce5c..3990c67c9 100644
--- a/documentation-site/src/components/CategoryDemosPage.tsx
+++ b/documentation-site/src/components/CategoryDemosPage.tsx
@@ -34,8 +34,9 @@ export const CategoryDemosPage: FC<CategoryDemosPageProps> = ({
         <Link to="/demos" className={styles.back}>
           ← All categories
         </Link>
+        <p className="eyebrow">Demos</p>
         <h1>{category.title}</h1>
-        <p>{category.description}</p>
+        <p className={styles.intro}>{category.description}</p>
         <div className={styles.demoGrid}>
           {categoryDemos.map((demo) => (
             <DemoCard
diff --git a/documentation-site/src/components/Demo.tsx b/documentation-site/src/components/Demo.tsx
deleted file mode 100644
index 304264526..000000000
--- a/documentation-site/src/components/Demo.tsx
+++ /dev/null
@@ -1,95 +0,0 @@
-import React, { FC, ReactNode, useRef } from 'react';
-import Layout from '@theme/Layout';
-import Link from '@docusaurus/Link';
-import { useLocation } from '@docusaurus/router';
-import clsx from 'clsx';
-import { CreateDemoGame, useGame } from '@site/src/hooks/useGame';
-import { useFullscreen } from '@site/src/hooks/useFullscreen';
-import { demoCategories } from '@site/src/data/demo-categories';
-import styles from './_Demo.module.css';
-import { CodeSelector } from './_CodeSelector';
-
-interface CodeFile {
-  name: string;
-  content: string;
-}
-
-interface DemoProps {
-  metaData: {
-    title: string;
-    description: string;
-  };
-  interactions?: ReactNode;
-  header: string;
-  blurb: string;
-  createGame: CreateDemoGame;
-  codeFiles: CodeFile[];
-}
-
-export const Demo: FC<DemoProps> = ({
-  metaData,
-  blurb,
-  interactions,
-  header,
-  createGame,
-  codeFiles,
-}) => {
-  const demoBoxRef = useRef<HTMLDivElement>(null);
-  const { isFullscreen, toggleFullscreen } = useFullscreen(demoBoxRef);
-
-  // `Game` keeps its render context sized to its container itself (via a
-  // `ResizeObserver`), so entering/exiting fullscreen resizes the running
-  // game in place instead of needing a restart.
-  useGame(createGame);
-
-  // The category page a demo was navigated from is threaded through as a
-  // `from` query param (see `DemoCard`), so the back button returns to the
-  // specific category the user was browsing rather than always the full
-  // demo catalogue.
-  const location = useLocation();
-  const fromCategory = demoCategories.find(
-    (category) =>
-      category.slug === new URLSearchParams(location.search).get('from'),
-  );
-  const backLink = fromCategory
-    ? {
-        to: `/demos/category/${fromCategory.slug}`,
-        label: `← Back to ${fromCategory.title}`,
-      }
-    : { to: '/demos', label: '← All demos' };
-
-  return (
-    <Layout
-      title={metaData.title}
-      description={metaData.description}
-      wrapperClassName={styles.wrapper}
-    >
-      <div className={styles.container}>
-        <Link to={backLink.to} className={styles.back}>
-          {backLink.label}
-        </Link>
-        <h1>{header}</h1>
-        {interactions}
-        <div className={styles.demoContainer}>
-          <div id="demo-game" ref={demoBoxRef} className={styles.demoBox}>
-            <button
-              type="button"
-              className={styles.fullscreenButton}
-              onClick={toggleFullscreen}
-              aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
-            >
-              <i
-                className={clsx(
-                  'fa-solid',
-                  isFullscreen ? 'fa-compress' : 'fa-expand',
-                )}
-              ></i>
-            </button>
-          </div>
-          <CodeSelector codeFiles={codeFiles} />
-        </div>
-        <p>{blurb}</p>
-      </div>
-    </Layout>
-  );
-};
diff --git a/documentation-site/src/components/DemoCategoryCard.tsx b/documentation-site/src/components/DemoCategoryCard.tsx
index d30c04d35..87ddaaf6b 100644
--- a/documentation-site/src/components/DemoCategoryCard.tsx
+++ b/documentation-site/src/components/DemoCategoryCard.tsx
@@ -1,7 +1,8 @@
 import React, { FC } from 'react';
 import Link from '@docusaurus/Link';
-import useBaseUrl from '@docusaurus/useBaseUrl';
 import { DemoCategory } from '@site/src/data/demo-categories';
+import { demos } from '@site/src/data/demos';
+import { ModuleIcon } from './ModuleIcon';
 import styles from './_DemoCategoryCard.module.css';
 
 interface DemoCategoryCardProps {
@@ -9,15 +10,22 @@ interface DemoCategoryCardProps {
 }
 
 export const DemoCategoryCard: FC<DemoCategoryCardProps> = ({ category }) => {
-  const imageUrl = useBaseUrl(category.image);
+  const demoCount = demos.filter((demo) =>
+    demo.categories.includes(category.slug),
+  ).length;
 
   return (
     <Link to={`/demos/category/${category.slug}`} className={styles.card}>
-      <img src={imageUrl} alt="" className={styles.image} />
-      <div className={styles.body}>
-        <h3 className={styles.title}>{category.title}</h3>
-        <p className={styles.description}>{category.description}</p>
+      <div className={styles.top}>
+        <span className={styles.iconTile}>
+          <ModuleIcon name={category.icon} className={styles.icon} />
+        </span>
+        <span className={styles.count}>
+          {demoCount} {demoCount === 1 ? 'demo' : 'demos'}
+        </span>
       </div>
+      <h3 className={styles.title}>{category.title}</h3>
+      <p className={styles.description}>{category.description}</p>
     </Link>
   );
 };
diff --git a/documentation-site/src/components/ModuleIcon.tsx b/documentation-site/src/components/ModuleIcon.tsx
new file mode 100644
index 000000000..3ec7f54d4
--- /dev/null
+++ b/documentation-site/src/components/ModuleIcon.tsx
@@ -0,0 +1,159 @@
+import React, { FC, ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './_ModuleIcon.module.css';
+
+/**
+ * Line icons for the engine's modules, used on the homepage and the demo
+ * categories: teal strokes (`currentColor`) with
+ * one amber accent each, drawn on a 24x24 grid.
+ */
+const icons = {
+  ecs: (
+    <>
+      <rect x="3" y="3" width="7" height="7" rx="1.5" />
+      <rect
+        x="14"
+        y="3"
+        width="7"
+        height="7"
+        rx="1.5"
+        className={styles.accent}
+      />
+      <rect x="3" y="14" width="7" height="7" rx="1.5" />
+      <rect x="14" y="14" width="7" height="7" rx="1.5" />
+    </>
+  ),
+  rendering: (
+    <>
+      <path d="M12 3 21 20H3Z" />
+      <path d="M12 3v17M7.6 12h8.8" />
+    </>
+  ),
+  postProcessing: (
+    <>
+      <circle cx="12" cy="12" r="3.5" className={styles.accent} />
+      <path d="M12 2.5v2.5M12 19v2.5M2.5 12H5M19 12h2.5M5.3 5.3l1.8 1.8M16.9 16.9l1.8 1.8M5.3 18.7l1.8-1.8M16.9 7.1l1.8-1.8" />
+    </>
+  ),
+  physics: (
+    <>
+      <circle cx="15" cy="10" r="4.5" />
+      <path d="M3 7h5M3 10h5M3 13h5M3 20h18" />
+    </>
+  ),
+  ui: (
+    <>
+      <rect x="3" y="4" width="18" height="16" rx="2" />
+      <path d="M3 9h18M7 15h10" />
+      <circle cx="12" cy="15" r="2" className={styles.accent} />
+    </>
+  ),
+  text: <path d="M5 20 12 4l7 16M8 14h8" />,
+  input: (
+    <>
+      <rect x="2" y="7" width="20" height="11" rx="5.5" />
+      <path d="M7 10.5v4M5 12.5h4" />
+      <circle cx="16" cy="11" r="1.3" className={styles.accent} />
+      <circle cx="18.2" cy="14" r="1.3" className={styles.accent} />
+    </>
+  ),
+  audio: (
+    <>
+      <path d="M4 9h4l5-4v14l-5-4H4Z" />
+      <path d="M16.5 9a4 4 0 0 1 0 6M19 6.5a8 8 0 0 1 0 11" />
+    </>
+  ),
+  animations: (
+    <>
+      <rect x="3" y="5" width="18" height="14" rx="2" />
+      <path d="M9 5v14M15 5v14" />
+      <circle cx="6" cy="14" r="1.4" className={styles.accent} />
+      <circle cx="12" cy="11" r="1.4" className={styles.accent} />
+      <circle cx="18" cy="9" r="1.4" className={styles.accent} />
+    </>
+  ),
+  particles: (
+    <>
+      <circle cx="12" cy="12" r="2.6" className={styles.accent} />
+      <circle cx="5" cy="7" r="1.5" />
+      <circle cx="12" cy="4" r="1.5" />
+      <circle cx="19" cy="7" r="1.5" />
+      <circle cx="5" cy="17" r="1.5" />
+      <circle cx="12" cy="20" r="1.5" />
+      <circle cx="19" cy="17" r="1.5" />
+    </>
+  ),
+  transforms: (
+    <>
+      <circle cx="12" cy="5" r="2.2" className={styles.accent} />
+      <circle cx="6" cy="19" r="2.2" />
+      <circle cx="18" cy="19" r="2.2" />
+      <path d="M11 7 7 17M13 7l4 10" />
+    </>
+  ),
+  assetLoading: <path d="M12 4v11M7 10l5 5 5-5M4 17v3h16v-3" />,
+  states: (
+    <>
+      <circle cx="5" cy="12" r="2.8" />
+      <circle cx="12" cy="12" r="2.8" className={styles.accent} />
+      <circle cx="19" cy="12" r="2.8" />
+    </>
+  ),
+  events: <path d="M13 2 4 14h7l-1 8 10-13h-7Z" />,
+  timers: (
+    <>
+      <circle cx="12" cy="13" r="8" />
+      <path d="M12 13V9M10 2h4M18 6l1.5-1.5" />
+      <circle cx="12" cy="13" r="1.3" className={styles.accent} />
+    </>
+  ),
+  gameLoop: <path d="M20 12a8 8 0 1 1-2.3-5.6M20 4v4h-4" />,
+  stateMachines: (
+    <>
+      <circle cx="6" cy="6" r="2.8" />
+      <circle cx="18" cy="6" r="2.8" />
+      <circle cx="18" cy="18" r="2.8" className={styles.accent} />
+      <path d="M8.8 6h6.4M18 8.8v6.4M8 8l8 8" />
+    </>
+  ),
+  lifetimes: (
+    <>
+      <path d="M7 3h10M7 21h10M8 3c0 6 8 6 8 9s-8 3-8 9M16 3c0 6-8 6-8 9s8 3 8 9" />
+      <path d="M10 19h4l-2-2.5Z" className={styles.accent} />
+    </>
+  ),
+  storage: (
+    <>
+      <ellipse cx="12" cy="6" rx="7" ry="3" className={styles.accent} />
+      <path d="M5 6v12c0 1.7 3.1 3 7 3s7-1.3 7-3V6M5 12c0 1.7 3.1 3 7 3s7-1.3 7-3" />
+    </>
+  ),
+  math: (
+    <>
+      <path d="M4 3v17h17M7 16c3-9 6 2 11-9" />
+      <circle cx="18" cy="7" r="1.5" className={styles.accent} />
+    </>
+  ),
+} satisfies Record<string, ReactNode>;
+
+export type ModuleIconName = keyof typeof icons;
+
+interface ModuleIconProps {
+  name: ModuleIconName;
+  className?: string;
+}
+
+export const ModuleIcon: FC<ModuleIconProps> = ({ name, className }) => (
+  <svg
+    className={clsx(styles.icon, className)}
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.6"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    {icons[name]}
+  </svg>
+);
diff --git a/documentation-site/src/components/_CategoryDemosPage.module.css b/documentation-site/src/components/_CategoryDemosPage.module.css
index 14b22ae37..44a1b8351 100644
--- a/documentation-site/src/components/_CategoryDemosPage.module.css
+++ b/documentation-site/src/components/_CategoryDemosPage.module.css
@@ -1,5 +1,14 @@
 .container {
-  margin: 50px;
+  width: 100%;
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 2.5rem 1.5rem 4rem;
+}
+
+.intro {
+  max-width: 48rem;
+  color: var(--text-muted-color);
+  font-size: 1.15rem;
 }
 
 .back {
diff --git a/documentation-site/src/components/_CodeSelector.module.css b/documentation-site/src/components/_CodeSelector.module.css
deleted file mode 100644
index f40783976..000000000
--- a/documentation-site/src/components/_CodeSelector.module.css
+++ /dev/null
@@ -1,116 +0,0 @@
-.container {
-  height: 600px;
-  margin-left: 20px;
-  width: 40%;
-  min-width: 600px;
-  display: flex;
-  flex-direction: column;
-  color: var(--text-color);
-}
-
-.fileNameToolbar {
-  display: flex;
-  background-color: var(--card-background-color);
-  flex-direction: row;
-  align-items: center;
-}
-
-.fileTypeIcon {
-  margin-left: 20px;
-}
-
-.fileNameToolbar button {
-  margin: 5px;
-  background-color: rgb(50, 50, 50);
-  border-radius: 5px;
-  margin-left: auto;
-  border: none;
-  text-align: center;
-  padding: 10px;
-  border-bottom: 2px solid transparent;
-  cursor: pointer;
-  margin-right: 5px;
-  text-wrap: nowrap;
-}
-
-.fileNameToolbar .folder {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  color: white;
-}
-
-.fileNameToolbar .folder:hover {
-  background-color: var(--card-highlight-color);
-  cursor: pointer;
-}
-
-.fileNameToolbar .fileName {
-  font-weight: 500;
-  margin-left: 20px;
-}
-
-.fileNameToolbar button:hover {
-  background-color: var(--card-highlight-color);
-}
-
-.fileNameToolbar button.selected {
-  background-color: var(--card-highlight-color);
-  border-bottom: 2px solid var(--ifm-color-primary);
-  font-weight: bold;
-}
-
-.codeBlock {
-  margin: 0;
-  overflow-y: auto;
-  border-radius: 0;
-}
-
-.codeSelector {
-  display: flex;
-  background-color: var(--card-background-color);
-  flex-direction: column;
-  height: 100%;
-  overflow-y: auto;
-}
-
-.codeSelector button {
-  width: 100%;
-  padding: 10px 0;
-  text-align: left;
-  background-color: var(--card-background-color);
-  border: none;
-  cursor: pointer;
-}
-
-.codeSelector button span {
-  margin-left: 50px;
-}
-
-.codeSelector button:hover {
-  background-color: var(--card-highlight-color);
-}
-
-.codeSelector i {
-  margin-left: 20px;
-  margin-right: 10px;
-}
-
-.fileTypeGroup {
-  border-top: 1px solid rgb(80, 80, 80);
-  padding-top: 10px;
-}
-
-.fileIcon {
-  margin-left: 20px;
-  margin-right: 10px;
-}
-
-.fileButtonName {
-  margin-left: 50px;
-}
-
-.selectedFile {
-  background-color: var(--card-highlight-color);
-  font-weight: bold;
-}
diff --git a/documentation-site/src/components/_CodeSelector.tsx b/documentation-site/src/components/_CodeSelector.tsx
deleted file mode 100644
index f8c23e386..000000000
--- a/documentation-site/src/components/_CodeSelector.tsx
+++ /dev/null
@@ -1,60 +0,0 @@
-/* eslint-disable @typescript-eslint/naming-convention */
-import { FC, useState } from 'react';
-import CodeBlock from '@theme/CodeBlock';
-import { cleanCodeSnippet } from '../utils/clean-code-snippet';
-import styles from './_CodeSelector.module.css';
-import { CodeFile, CodeSelectorProps } from './_CodeSelector.types';
-import { fileTypeIconLookup, getFileTypeIcon } from './_CodeSelector.utils';
-import { FileToolbar } from './_FileToolbar';
-import { FileSelectorDropdown } from './_FileSelectorDropdown';
-
-export type { CodeFile, CodeSelectorProps };
-
-export const CodeSelector: FC<CodeSelectorProps> = ({
-  codeFiles,
-  selectedFileName,
-}) => {
-  const [selectedFile, setSelectedFile] = useState<CodeFile>(
-    codeFiles.find((file) => file.name === selectedFileName) || codeFiles[0],
-  );
-
-  const [selectingFile, setSelectingFile] = useState<boolean>(false);
-
-  const fileType = getFileTypeIcon(selectedFile.name);
-  const fileTypeIcon = fileTypeIconLookup[fileType];
-
-  const handleSelectFile = (file: CodeFile): void => {
-    setSelectedFile(file);
-    setSelectingFile(false);
-  };
-
-  const toggleSelector = (): void => {
-    setSelectingFile(!selectingFile);
-  };
-
-  return (
-    <div className={styles.container}>
-      <FileToolbar
-        fileName={selectedFile.name}
-        fileTypeIcon={fileTypeIcon}
-        onToggleSelector={toggleSelector}
-        numberOfFiles={codeFiles.length}
-      />
-      {selectingFile ? (
-        <FileSelectorDropdown
-          codeFiles={codeFiles}
-          selectedFileName={selectedFile.name}
-          onSelectFile={handleSelectFile}
-        />
-      ) : (
-        <CodeBlock
-          language="typescript"
-          className={styles.codeBlock}
-          showLineNumbers
-        >
-          {cleanCodeSnippet(selectedFile.content)}
-        </CodeBlock>
-      )}
-    </div>
-  );
-};
diff --git a/documentation-site/src/components/_CodeSelector.types.ts b/documentation-site/src/components/_CodeSelector.types.ts
deleted file mode 100644
index 03607667c..000000000
--- a/documentation-site/src/components/_CodeSelector.types.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-export interface CodeFile {
-  name: string;
-  content: string;
-}
-
-export interface CodeSelectorProps {
-  codeFiles: CodeFile[];
-  selectedFileName?: string;
-}
diff --git a/documentation-site/src/components/_CodeSelector.utils.ts b/documentation-site/src/components/_CodeSelector.utils.ts
deleted file mode 100644
index 2cb5e856b..000000000
--- a/documentation-site/src/components/_CodeSelector.utils.ts
+++ /dev/null
@@ -1,61 +0,0 @@
-/* eslint-disable @typescript-eslint/naming-convention */
-import { CodeFile } from './_CodeSelector.types';
-
-export type FileType = 'Game' | 'Components' | 'Systems' | 'Shaders' | 'Others';
-
-export const fileTypeIconLookup: Record<FileType, string> = {
-  Game: 'fa-earth-africa',
-  Components: 'fa-cube',
-  Systems: 'fa-gears',
-  Shaders: 'fa-palette',
-  Others: 'fa-code',
-};
-
-export const FILE_TYPES: readonly FileType[] = [
-  'Game',
-  'Components',
-  'Systems',
-  'Shaders',
-  'Others',
-];
-
-export const getFileTypeIcon = (fileName: string): FileType => {
-  if (fileName.includes('.component')) {
-    return 'Components';
-  }
-
-  if (fileName.includes('.system')) {
-    return 'Systems';
-  }
-
-  if (fileName.includes('game')) {
-    return 'Game';
-  }
-
-  if (fileName.includes('.shader')) {
-    return 'Shaders';
-  }
-
-  return 'Others';
-};
-
-export const groupByFileType = (
-  codeFiles: CodeFile[],
-): Record<FileType, CodeFile[]> => {
-  const record = {
-    Game: [],
-    Components: [],
-    Systems: [],
-    Shaders: [],
-    Others: [],
-  } as Record<FileType, CodeFile[]>;
-
-  const groups = codeFiles.reduce((acc, file) => {
-    const fileType = getFileTypeIcon(file.name);
-    acc[fileType].push(file);
-
-    return acc;
-  }, record);
-
-  return groups;
-};
diff --git a/documentation-site/src/components/_Demo.module.css b/documentation-site/src/components/_Demo.module.css
deleted file mode 100644
index 6dc437047..000000000
--- a/documentation-site/src/components/_Demo.module.css
+++ /dev/null
@@ -1,60 +0,0 @@
-.demoContainer {
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  flex-direction: row;
-  margin-top: 8px;
-}
-
-.demoBox {
-  position: relative;
-  height: 600px;
-  width: 60%;
-  background-color: black;
-}
-
-.demoBox canvas {
-  position: absolute;
-}
-
-.demoBox:fullscreen,
-.demoBox:-webkit-full-screen {
-  width: 100%;
-  height: 100%;
-}
-
-.fullscreenButton {
-  position: absolute;
-  top: 10px;
-  right: 10px;
-  z-index: 1;
-  background-color: rgb(50, 50, 50);
-  border: none;
-  border-radius: 5px;
-  color: white;
-  padding: 8px 10px;
-  cursor: pointer;
-}
-
-.fullscreenButton:hover {
-  background-color: var(--card-highlight-color);
-}
-
-.demoContainer h1 {
-  width: 100%;
-  text-align: center;
-  margin-bottom: 20px;
-}
-
-.container {
-  margin: 50px;
-}
-
-.back {
-  display: inline-block;
-  margin-bottom: 1rem;
-}
-
-.wrapper {
-  justify-content: start;
-}
diff --git a/documentation-site/src/components/_DemoCard.module.css b/documentation-site/src/components/_DemoCard.module.css
index a70ddea3a..62efff041 100644
--- a/documentation-site/src/components/_DemoCard.module.css
+++ b/documentation-site/src/components/_DemoCard.module.css
@@ -2,6 +2,7 @@
   display: flex;
   flex-direction: column;
   padding: 1.25rem;
+  border: 1px solid var(--card-border-color);
   border-radius: 12px;
   background-color: var(--card-background-color);
   color: var(--text-color);
@@ -12,19 +13,22 @@
 }
 
 .card:hover {
-  transform: translateY(-4px);
-  box-shadow: 0 8px 20px rgba(0, 0, 0, 0.15);
+  transform: translateY(-3px);
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
   color: var(--text-color);
   text-decoration: none;
 }
 
 .title {
   margin: 0 0 0.4rem;
+  font-size: 1.2rem;
 }
 
 .description {
   margin: 0 0 0.75rem;
-  opacity: 0.85;
+  color: var(--text-muted-color);
+  font-size: 0.93rem;
   flex-grow: 1;
 }
 
@@ -35,8 +39,12 @@
 }
 
 .tag {
-  font-size: 0.75rem;
-  padding: 0.2rem 0.6rem;
+  padding: 0.15rem 0.55rem;
+  border: 1px solid var(--card-border-color);
   border-radius: 999px;
-  background-color: var(--card-highlight-color);
+  color: var(--ifm-color-primary);
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.7rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
 }
diff --git a/documentation-site/src/components/_DemoCategoryCard.module.css b/documentation-site/src/components/_DemoCategoryCard.module.css
index b0e4fd821..d1fbf3358 100644
--- a/documentation-site/src/components/_DemoCategoryCard.module.css
+++ b/documentation-site/src/components/_DemoCategoryCard.module.css
@@ -1,39 +1,70 @@
 .card {
   display: flex;
   flex-direction: column;
-  overflow: hidden;
+  padding: 1.25rem;
+  border: 1px solid var(--card-border-color);
   border-radius: 12px;
   background-color: var(--card-background-color);
   color: var(--text-color);
   text-decoration: none;
   transition:
     transform 0.15s ease,
+    border-color 0.15s ease,
     box-shadow 0.15s ease;
 }
 
 .card:hover {
-  transform: translateY(-4px);
-  box-shadow: 0 8px 20px rgba(0, 0, 0, 0.15);
+  transform: translateY(-3px);
+  border-color: var(--ifm-color-primary);
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
   color: var(--text-color);
   text-decoration: none;
 }
 
-.image {
-  width: 100%;
-  aspect-ratio: 16 / 9;
-  object-fit: cover;
-  display: block;
+.top {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  margin-bottom: 1.25rem;
+}
+
+/* The icon sits on a faint teal tile, so it reads as a badge. */
+.iconTile {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 3.5rem;
+  height: 3.5rem;
+  border: 1px solid rgba(79, 196, 196, 0.25);
+  border-radius: 10px;
+  background-color: rgba(79, 196, 196, 0.08);
 }
 
-.body {
-  padding: 1rem 1.25rem 1.25rem;
+.icon {
+  width: 2rem;
+  height: 2rem;
+}
+
+.count {
+  color: var(--text-muted-color);
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.72rem;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
 }
 
 .title {
   margin: 0 0 0.4rem;
+  font-size: 1.2rem;
+  transition: color 0.15s;
+}
+
+.card:hover .title {
+  color: var(--ifm-color-primary);
 }
 
 .description {
   margin: 0;
-  opacity: 0.85;
+  color: var(--text-muted-color);
+  font-size: 0.93rem;
 }
diff --git a/documentation-site/src/components/_DemoSearch.module.css b/documentation-site/src/components/_DemoSearch.module.css
index 1574bb979..e7a28d1fa 100644
--- a/documentation-site/src/components/_DemoSearch.module.css
+++ b/documentation-site/src/components/_DemoSearch.module.css
@@ -5,7 +5,7 @@
   padding: 0.6rem 1rem;
   margin: 1.5rem 0;
   font-size: 1rem;
-  border: 2px solid var(--card-highlight-color);
+  border: 1px solid var(--card-border-color);
   border-radius: 8px;
   background-color: var(--card-background-color);
   color: var(--text-color);
diff --git a/documentation-site/src/components/_FileSelectorDropdown.tsx b/documentation-site/src/components/_FileSelectorDropdown.tsx
deleted file mode 100644
index 058c0f536..000000000
--- a/documentation-site/src/components/_FileSelectorDropdown.tsx
+++ /dev/null
@@ -1,47 +0,0 @@
-import { FC } from 'react';
-import styles from './_CodeSelector.module.css';
-import { CodeFile } from './_CodeSelector.types';
-import {
-  FILE_TYPES,
-  fileTypeIconLookup,
-  groupByFileType,
-} from './_CodeSelector.utils';
-import { FileTypeGroup } from './_FileTypeGroup';
-
-interface FileSelectorDropdownProps {
-  codeFiles: CodeFile[];
-  selectedFileName: string;
-  onSelectFile: (file: CodeFile) => void;
-}
-
-export const FileSelectorDropdown: FC<FileSelectorDropdownProps> = ({
-  codeFiles,
-  selectedFileName,
-  onSelectFile,
-}) => {
-  const groupedFiles = groupByFileType(codeFiles);
-
-  return (
-    <div className={styles.codeSelector}>
-      {FILE_TYPES.map((type) => {
-        const typeIcon = fileTypeIconLookup[type];
-        const files = groupedFiles[type];
-
-        if (files.length === 0) {
-          return null;
-        }
-
-        return (
-          <FileTypeGroup
-            key={type}
-            type={type}
-            typeIcon={typeIcon}
-            files={files}
-            selectedFileName={selectedFileName}
-            onSelectFile={onSelectFile}
-          />
-        );
-      })}
-    </div>
-  );
-};
diff --git a/documentation-site/src/components/_FileToolbar.tsx b/documentation-site/src/components/_FileToolbar.tsx
deleted file mode 100644
index c0e2885e6..000000000
--- a/documentation-site/src/components/_FileToolbar.tsx
+++ /dev/null
@@ -1,28 +0,0 @@
-import { FC } from 'react';
-import clsx from 'clsx';
-import styles from './_CodeSelector.module.css';
-
-interface FileToolbarProps {
-  fileName: string;
-  fileTypeIcon: string;
-  onToggleSelector: () => void;
-  numberOfFiles: number;
-}
-
-export const FileToolbar: FC<FileToolbarProps> = ({
-  fileName,
-  fileTypeIcon,
-  onToggleSelector,
-  numberOfFiles,
-}) => {
-  return (
-    <div className={styles.fileNameToolbar}>
-      <i className={clsx('fa-solid', fileTypeIcon, styles.fileTypeIcon)}></i>
-      <span className={styles.fileName}>{fileName}</span>
-      <button onClick={onToggleSelector}>
-        {numberOfFiles} file(s){' '}
-        <i className={clsx('fa-solid fa-folder', styles.folder)}></i>
-      </button>
-    </div>
-  );
-};
diff --git a/documentation-site/src/components/_FileTypeGroup.tsx b/documentation-site/src/components/_FileTypeGroup.tsx
deleted file mode 100644
index ca24b24e2..000000000
--- a/documentation-site/src/components/_FileTypeGroup.tsx
+++ /dev/null
@@ -1,44 +0,0 @@
-import { FC } from 'react';
-import clsx from 'clsx';
-import styles from './_CodeSelector.module.css';
-import { CodeFile } from './_CodeSelector.types';
-
-interface FileTypeGroupProps {
-  type: string;
-  typeIcon: string;
-  files: CodeFile[];
-  selectedFileName: string;
-  onSelectFile: (file: CodeFile) => void;
-}
-
-export const FileTypeGroup: FC<FileTypeGroupProps> = ({
-  type,
-  typeIcon,
-  files,
-  selectedFileName,
-  onSelectFile,
-}) => {
-  if (files.length === 0) {
-    return null;
-  }
-
-  return (
-    <div className={styles.fileTypeGroup}>
-      <i className={clsx('fa-solid', typeIcon, styles.fileIcon)}></i>
-      {type}
-      {files.map((file) => {
-        const isSelected = file.name === selectedFileName;
-
-        return (
-          <button
-            key={file.name}
-            className={clsx(isSelected ? styles.selectedFile : undefined)}
-            onClick={() => onSelectFile(file)}
-          >
-            <span className={styles.fileButtonName}>{file.name}</span>
-          </button>
-        );
-      })}
-    </div>
-  );
-};
diff --git a/documentation-site/src/components/_InteractionInstruction.module.css b/documentation-site/src/components/_InteractionInstruction.module.css
deleted file mode 100644
index 1674323ee..000000000
--- a/documentation-site/src/components/_InteractionInstruction.module.css
+++ /dev/null
@@ -1,18 +0,0 @@
-.container {
-  display: inline-flex;
-  align-items: center;
-  padding: 8px;
-  gap: 8px;
-  max-width: 400px;
-  min-width: 200px;
-  margin-right: 10px;
-  vertical-align: top;
-
-  background-color: var(--card-background-color);
-}
-
-.container p {
-  display: inline-block;
-  max-width: 80%;
-  margin: 0;
-}
diff --git a/documentation-site/src/components/_InteractionInstruction.tsx b/documentation-site/src/components/_InteractionInstruction.tsx
deleted file mode 100644
index f8b79c214..000000000
--- a/documentation-site/src/components/_InteractionInstruction.tsx
+++ /dev/null
@@ -1,19 +0,0 @@
-import React, { FC, ReactNode } from 'react';
-import styles from './_InteractionInstruction.module.css';
-
-interface KeyboardKeyProps {
-  displayElement: ReactNode;
-  text: string;
-}
-
-export const InteractionInstruction: FC<KeyboardKeyProps> = ({
-  displayElement,
-  text,
-}) => {
-  return (
-    <div className={styles.container}>
-      {displayElement}
-      <p>{text}</p>
-    </div>
-  );
-};
diff --git a/documentation-site/src/components/_KeyboardKey.module.css b/documentation-site/src/components/_KeyboardKey.module.css
deleted file mode 100644
index 0544a2f71..000000000
--- a/documentation-site/src/components/_KeyboardKey.module.css
+++ /dev/null
@@ -1,23 +0,0 @@
-.keyBox {
-  border-radius: 3px;
-  border-left: 5px solid #d1d16c;
-  border-right: 5px solid #d1d16c;
-  border-bottom: 5px solid #a0a053;
-  width: 35px;
-  display: inline-block;
-  align-self: baseline;
-}
-
-.keyTop {
-  padding-top: 5px;
-  width: 25px;
-  height: 30px;
-  background-color: #ffff87;
-  font-weight: bold;
-  font-size: 1em;
-  color: black;
-  font-family:
-    'Lucida Sans', 'Lucida Sans Regular', 'Lucida Grande',
-    'Lucida Sans Unicode', Geneva, Verdana, sans-serif;
-  text-align: center;
-}
diff --git a/documentation-site/src/components/_KeyboardKey.tsx b/documentation-site/src/components/_KeyboardKey.tsx
deleted file mode 100644
index a59236418..000000000
--- a/documentation-site/src/components/_KeyboardKey.tsx
+++ /dev/null
@@ -1,14 +0,0 @@
-import React, { FC } from 'react';
-import styles from './_KeyboardKey.module.css';
-
-interface KeyboardKeyProps {
-  keyCode: string;
-}
-
-export const KeyboardKey: FC<KeyboardKeyProps> = ({ keyCode }) => {
-  return (
-    <div className={styles.keyBox}>
-      <div className={styles.keyTop}>{keyCode}</div>
-    </div>
-  );
-};
diff --git a/documentation-site/src/components/_ModuleIcon.module.css b/documentation-site/src/components/_ModuleIcon.module.css
new file mode 100644
index 000000000..37d25c178
--- /dev/null
+++ b/documentation-site/src/components/_ModuleIcon.module.css
@@ -0,0 +1,11 @@
+.icon {
+  flex-shrink: 0;
+  width: 2.5rem;
+  height: 2.5rem;
+  color: var(--ifm-color-primary);
+}
+
+.accent {
+  fill: var(--forge-amber);
+  stroke: var(--forge-amber);
+}
diff --git a/documentation-site/src/components/_ScrollWheel.tsx b/documentation-site/src/components/_ScrollWheel.tsx
deleted file mode 100644
index 8772ba1b2..000000000
--- a/documentation-site/src/components/_ScrollWheel.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-import React, { FC } from 'react';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-
-export const ScrollWheel: FC = () => {
-  const { siteConfig } = useDocusaurusContext();
-
-  return (
-    <img
-      src={`${siteConfig.baseUrl}/img/scroll.png`}
-      alt="scroll icon"
-      style={{
-        width: 35,
-        height: 35,
-      }}
-    />
-  );
-};
diff --git a/documentation-site/src/components/demo-page/CodeExplorer.module.css b/documentation-site/src/components/demo-page/CodeExplorer.module.css
new file mode 100644
index 000000000..696889ed5
--- /dev/null
+++ b/documentation-site/src/components/demo-page/CodeExplorer.module.css
@@ -0,0 +1,231 @@
+.explorer {
+  display: grid;
+  grid-template-columns: 300px minmax(0, 1fr);
+  height: 640px;
+  overflow: hidden;
+  border-radius: 8px;
+  border: 1px solid var(--ifm-color-emphasis-300);
+}
+
+.fileBrowser {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  border-right: 1px solid var(--ifm-color-emphasis-300);
+  background-color: var(--ifm-background-surface-color);
+}
+
+.fileFilters {
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+  padding: 0.75rem;
+  border-bottom: 1px solid var(--ifm-color-emphasis-300);
+}
+
+.fileSearch {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.35rem 0.6rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 6px;
+  background-color: var(--ifm-background-color);
+  color: var(--ifm-color-emphasis-600);
+}
+
+.fileSearch:focus-within {
+  border-color: var(--ifm-color-primary);
+}
+
+.fileSearch input {
+  flex: 1;
+  min-width: 0;
+  border: none;
+  outline: none;
+  background: none;
+  color: var(--ifm-font-color-base);
+  font-size: 0.9rem;
+}
+
+.typeFilter {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+}
+
+.typeFilterButton {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  padding: 0.15rem 0.55rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 999px;
+  background: none;
+  color: var(--ifm-font-color-base);
+  font-size: 0.78rem;
+  cursor: pointer;
+}
+
+.typeFilterButton .fileIcon {
+  width: auto;
+}
+
+.typeFilterButton:hover {
+  background-color: var(--ifm-color-emphasis-200);
+}
+
+.typeFilterButtonSelected,
+.typeFilterButtonSelected:hover {
+  border-color: var(--ifm-color-primary);
+  background-color: var(--ifm-color-emphasis-200);
+  font-weight: bold;
+}
+
+.typeFilterCount {
+  color: var(--ifm-color-emphasis-600);
+  font-weight: normal;
+}
+
+.fileTree {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 0.75rem 0;
+}
+
+.noFiles {
+  margin: 0;
+  padding: 0 1rem;
+  font-size: 0.9rem;
+  color: var(--ifm-color-emphasis-600);
+}
+
+.fileGroup + .fileGroup {
+  margin-top: 0.75rem;
+}
+
+.fileGroupTitle {
+  padding: 0 1rem 0.25rem;
+  font-size: 0.72rem;
+  font-weight: bold;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--ifm-color-emphasis-600);
+}
+
+.fileTree ul {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.fileButton {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  padding: 0.3rem 1rem;
+  border: none;
+  border-left: 3px solid transparent;
+  background: none;
+  color: var(--ifm-font-color-base);
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.82rem;
+  text-align: left;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.fileName {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.fileButton:hover {
+  background-color: var(--ifm-color-emphasis-200);
+}
+
+.fileButtonSelected,
+.fileButtonSelected:hover {
+  border-left-color: var(--ifm-color-primary);
+  background-color: var(--ifm-color-emphasis-200);
+  font-weight: bold;
+}
+
+.fileIcon {
+  flex-shrink: 0;
+  width: 1rem;
+  text-align: center;
+}
+
+i.fileIcon {
+  color: var(--ifm-color-emphasis-700);
+}
+
+.fileTypeLabel {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.8rem;
+}
+
+.fileTypeLabel .fileIcon {
+  width: auto;
+}
+
+.filePaneTitle {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.filePane {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.filePaneHeader {
+  display: flex;
+  flex-direction: column;
+  gap: 0.1rem;
+  padding: 0.6rem 1rem;
+  border-bottom: 1px solid var(--ifm-color-emphasis-300);
+  background-color: var(--ifm-background-surface-color);
+}
+
+.filePaneName {
+  font-family: var(--ifm-font-family-monospace);
+  font-weight: bold;
+}
+
+.filePaneSummary {
+  font-size: 0.88rem;
+  color: var(--ifm-color-emphasis-700);
+}
+
+.codeBlock {
+  flex: 1;
+  min-height: 0;
+  margin: 0;
+  overflow-y: auto;
+  border-radius: 0;
+  box-shadow: none;
+}
+
+@media (max-width: 996px) {
+  .explorer {
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-rows: auto minmax(0, 1fr);
+    height: 80vh;
+  }
+
+  .fileBrowser {
+    max-height: 40vh;
+    border-right: none;
+    border-bottom: 1px solid var(--ifm-color-emphasis-300);
+  }
+}
diff --git a/documentation-site/src/components/demo-page/CodeExplorer.tsx b/documentation-site/src/components/demo-page/CodeExplorer.tsx
new file mode 100644
index 000000000..f0afa474e
--- /dev/null
+++ b/documentation-site/src/components/demo-page/CodeExplorer.tsx
@@ -0,0 +1,177 @@
+import React, { FC, useState } from 'react';
+import CodeBlock from '@theme/CodeBlock';
+import clsx from 'clsx';
+import { cleanCodeSnippet } from '@site/src/utils/clean-code-snippet';
+import styles from './CodeExplorer.module.css';
+import {
+  DemoFileType,
+  demoFileTypeOrder,
+  demoFileTypes,
+  getDemoFileType,
+} from './file-types';
+import { DemoFile, DemoFileGroup } from './types';
+
+// Below this many files the whole list fits on screen, so search and
+// filters would only add clutter.
+const minFilesForFilters = 6;
+
+interface CodeExplorerProps {
+  fileGroups: DemoFileGroup[];
+  selectedFile: DemoFile;
+  onSelectFile: (fileName: string) => void;
+}
+
+const FileTypeIcon: FC<{ type: DemoFileType }> = ({ type }) => (
+  <i
+    className={clsx('fa-solid', demoFileTypes[type].icon, styles.fileIcon)}
+    aria-hidden="true"
+  ></i>
+);
+
+/**
+ * Browses a demo's source files: a grouped file list with search and a
+ * type filter, and the selected file's code.
+ */
+export const CodeExplorer: FC<CodeExplorerProps> = ({
+  fileGroups,
+  selectedFile,
+  onSelectFile,
+}) => {
+  const [query, setQuery] = useState('');
+  const [typeFilter, setTypeFilter] = useState<DemoFileType | 'all'>('all');
+
+  const allFiles = fileGroups.flatMap((group) => group.files);
+  const typesPresent = demoFileTypeOrder.filter((type) =>
+    allFiles.some((file) => getDemoFileType(file.name) === type),
+  );
+  const normalizedQuery = query.trim().toLowerCase();
+
+  const matches = (file: DemoFile): boolean =>
+    (typeFilter === 'all' || getDemoFileType(file.name) === typeFilter) &&
+    file.name.toLowerCase().includes(normalizedQuery);
+
+  const visibleGroups = fileGroups
+    .map((group) => ({ ...group, files: group.files.filter(matches) }))
+    .filter((group) => group.files.length > 0);
+
+  const selectedType = getDemoFileType(selectedFile.name);
+  const showFilters = allFiles.length >= minFilesForFilters;
+
+  const filterOptions: { value: DemoFileType | 'all'; label: string }[] = [
+    { value: 'all', label: 'All' },
+    ...typesPresent.map((type) => ({
+      value: type,
+      label: demoFileTypes[type].pluralLabel,
+    })),
+  ];
+
+  return (
+    <div className={styles.explorer}>
+      <div className={styles.fileBrowser}>
+        {showFilters && (
+          <div className={styles.fileFilters}>
+            <div className={styles.fileSearch}>
+              <i
+                className="fa-solid fa-magnifying-glass"
+                aria-hidden="true"
+              ></i>
+              <input
+                type="search"
+                placeholder="Search files"
+                aria-label="Search files by name"
+                value={query}
+                onChange={(event) => setQuery(event.target.value)}
+              />
+            </div>
+            <div
+              className={styles.typeFilter}
+              role="group"
+              aria-label="Filter files by type"
+            >
+              {filterOptions.map(({ value, label }) => {
+                const count =
+                  value === 'all'
+                    ? allFiles.length
+                    : allFiles.filter(
+                        (file) => getDemoFileType(file.name) === value,
+                      ).length;
+
+                return (
+                  <button
+                    key={value}
+                    type="button"
+                    className={clsx(
+                      styles.typeFilterButton,
+                      typeFilter === value && styles.typeFilterButtonSelected,
+                    )}
+                    aria-pressed={typeFilter === value}
+                    onClick={() => setTypeFilter(value)}
+                  >
+                    {value !== 'all' && <FileTypeIcon type={value} />}
+                    {label}
+                    <span className={styles.typeFilterCount}>{count}</span>
+                  </button>
+                );
+              })}
+            </div>
+          </div>
+        )}
+
+        <nav className={styles.fileTree} aria-label="Source files">
+          {visibleGroups.length === 0 && (
+            <p className={styles.noFiles}>No files match.</p>
+          )}
+          {visibleGroups.map((group) => (
+            <div key={group.title} className={styles.fileGroup}>
+              <div className={styles.fileGroupTitle}>{group.title}</div>
+              <ul>
+                {group.files.map((file) => {
+                  const isSelected = file.name === selectedFile.name;
+                  const type = getDemoFileType(file.name);
+
+                  return (
+                    <li key={file.name}>
+                      <button
+                        type="button"
+                        className={clsx(
+                          styles.fileButton,
+                          isSelected && styles.fileButtonSelected,
+                        )}
+                        aria-current={isSelected ? 'true' : undefined}
+                        title={`${file.name} (${demoFileTypes[type].label})`}
+                        onClick={() => onSelectFile(file.name)}
+                      >
+                        <FileTypeIcon type={type} />
+                        <span className={styles.fileName}>{file.name}</span>
+                      </button>
+                    </li>
+                  );
+                })}
+              </ul>
+            </div>
+          ))}
+        </nav>
+      </div>
+
+      <div className={styles.filePane}>
+        <div className={styles.filePaneHeader}>
+          <div className={styles.filePaneTitle}>
+            <span className={styles.filePaneName}>{selectedFile.name}</span>
+            <span className={styles.fileTypeLabel}>
+              <FileTypeIcon type={selectedType} />
+              {demoFileTypes[selectedType].label}
+            </span>
+          </div>
+          <span className={styles.filePaneSummary}>{selectedFile.summary}</span>
+        </div>
+        <CodeBlock
+          language="typescript"
+          className={styles.codeBlock}
+          showLineNumbers
+        >
+          {cleanCodeSnippet(selectedFile.content)}
+        </CodeBlock>
+      </div>
+    </div>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/DemoControls.module.css b/documentation-site/src/components/demo-page/DemoControls.module.css
new file mode 100644
index 000000000..6abcb467d
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoControls.module.css
@@ -0,0 +1,59 @@
+.controls {
+  display: grid;
+  /* The keys column fits its widest row, up to about half the panel. */
+  grid-template-columns: fit-content(55%) minmax(0, 1fr);
+  gap: 0.6rem 1rem;
+  align-items: center;
+  margin: 0;
+}
+
+.control {
+  display: contents;
+}
+
+.controlKeys {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.35rem;
+  margin: 0;
+  font-weight: normal;
+}
+
+.controlOr {
+  font-size: 0.75rem;
+  color: var(--ifm-color-emphasis-600);
+}
+
+.key {
+  min-width: 2rem;
+  padding: 0.2rem 0.45rem;
+  border: 1px solid var(--ifm-color-emphasis-400);
+  border-bottom-width: 3px;
+  border-radius: 6px;
+  background-color: var(--ifm-color-emphasis-100);
+  color: var(--ifm-font-color-base);
+  font-family: var(--ifm-font-family-base);
+  font-size: 0.95rem;
+  font-weight: bold;
+  line-height: 1.4;
+  text-align: center;
+  white-space: nowrap;
+  box-shadow: none;
+}
+
+.controlAction {
+  margin: 0;
+  font-weight: 600;
+}
+
+.controlDetail {
+  display: block;
+  font-size: 0.8rem;
+  font-weight: normal;
+  color: var(--ifm-color-emphasis-700);
+}
+
+.inputIcon {
+  margin-right: 0.3rem;
+}
diff --git a/documentation-site/src/components/demo-page/DemoControls.tsx b/documentation-site/src/components/demo-page/DemoControls.tsx
new file mode 100644
index 000000000..86094e5cd
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoControls.tsx
@@ -0,0 +1,83 @@
+import React, { FC, Fragment } from 'react';
+import clsx from 'clsx';
+import styles from './DemoControls.module.css';
+import { DemoControl, DemoInput } from './types';
+
+const deviceIcons = {
+  mouse: 'fa-computer-mouse',
+  gamepad: 'fa-gamepad',
+  touch: 'fa-hand-pointer',
+};
+
+const inputKey = (input: DemoInput): string =>
+  typeof input === 'string' ? input : `${input.device}:${input.label}`;
+
+// Keys shown as their symbol rather than their name, so every key cap stays
+// one short character wide. The name is still read out by screen readers.
+const keySymbols: Record<string, string> = {
+  Enter: '⏎',
+  Space: '␣',
+};
+
+const InputCap: FC<{ input: DemoInput }> = ({ input }) => {
+  if (typeof input === 'string') {
+    const symbol = keySymbols[input];
+
+    if (symbol) {
+      return (
+        <kbd className={styles.key} title={input} aria-label={input}>
+          {symbol}
+        </kbd>
+      );
+    }
+
+    return <kbd className={styles.key}>{input}</kbd>;
+  }
+
+  return (
+    <kbd className={styles.key}>
+      <i
+        className={clsx(
+          'fa-solid',
+          deviceIcons[input.device],
+          styles.inputIcon,
+        )}
+        aria-hidden="true"
+      ></i>
+      {input.label}
+    </kbd>
+  );
+};
+
+interface DemoControlsProps {
+  controls: DemoControl[];
+}
+
+/**
+ * Lists a demo's controls: the inputs on the left, what they do on the
+ * right.
+ */
+export const DemoControls: FC<DemoControlsProps> = ({ controls }) => {
+  return (
+    <dl className={styles.controls}>
+      {controls.map((control) => (
+        <div key={control.action} className={styles.control}>
+          <dt className={styles.controlKeys}>
+            {control.inputs.map((input, index) => (
+              <Fragment key={inputKey(input)}>
+                {index > 0 && <span className={styles.controlOr}>or</span>}
+                <InputCap input={input} />
+              </Fragment>
+            ))}
+          </dt>
+          <dd className={styles.controlAction}>
+            {control.action}
+            {control.detail && (
+              <span className={styles.controlDetail}>{control.detail}</span>
+            )}
+          </dd>
+        </div>
+      ))}
+    </dl>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/DemoGame.module.css b/documentation-site/src/components/demo-page/DemoGame.module.css
new file mode 100644
index 000000000..c0fa5fcbf
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoGame.module.css
@@ -0,0 +1,56 @@
+.game {
+  position: relative;
+  align-self: stretch;
+  /* At least 16:9, and taller when the sidebar beside it is (up to 3:2,
+   * see DemoPage.module.css), so the two columns end level. */
+  aspect-ratio: 16 / 9;
+  width: 100%;
+  overflow: hidden;
+  border-radius: 8px;
+  background-color: black;
+  box-shadow: 0 0 0 1px var(--ifm-color-emphasis-300);
+}
+
+.game:focus {
+  outline: none;
+}
+
+.game:focus-visible {
+  box-shadow: 0 0 0 3px var(--ifm-color-primary);
+}
+
+.game canvas {
+  position: absolute;
+}
+
+.game:fullscreen {
+  width: 100%;
+  height: 100%;
+  border-radius: 0;
+  aspect-ratio: auto;
+}
+
+.focusHint {
+  position: absolute;
+  left: 50%;
+  bottom: 16px;
+  z-index: 1;
+  transform: translateX(-50%);
+  padding: 6px 14px;
+  border-radius: 999px;
+  background-color: rgba(11, 19, 43, 0.75);
+  color: white;
+  font-size: 0.9rem;
+  pointer-events: none;
+  transition: opacity 0.2s;
+}
+
+.focusHintHidden {
+  opacity: 0;
+}
+
+@media (max-width: 1200px) {
+  .game {
+    align-self: auto;
+  }
+}
diff --git a/documentation-site/src/components/demo-page/DemoGame.tsx b/documentation-site/src/components/demo-page/DemoGame.tsx
new file mode 100644
index 000000000..7bd2ea4ab
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoGame.tsx
@@ -0,0 +1,54 @@
+import React, { FC, useEffect, useRef, useState } from 'react';
+import clsx from 'clsx';
+import { CreateDemoGame, useGame } from '@site/src/hooks/useGame';
+import { useFullscreen } from '@site/src/hooks/useFullscreen';
+import { usePreventPageScrollKeys } from '@site/src/hooks/usePreventPageScrollKeys';
+import { FullscreenButton } from './FullscreenButton';
+import styles from './DemoGame.module.css';
+
+interface DemoGameProps {
+  title: string;
+  createGame: CreateDemoGame;
+}
+
+/**
+ * Runs a demo's game in a focusable, fullscreen-able box. Every demo's
+ * `createGame` renders into the `demo-game` element this creates.
+ */
+export const DemoGame: FC<DemoGameProps> = ({ title, createGame }) => {
+  const gameRef = useRef<HTMLDivElement>(null);
+  const { isFullscreen, toggleFullscreen } = useFullscreen(gameRef);
+  const [hasFocus, setHasFocus] = useState(false);
+
+  useGame(createGame);
+  usePreventPageScrollKeys(gameRef);
+
+  // Focus the game straight away, so the controls work without a click and
+  // the arrow keys drive the game instead of scrolling the page.
+  useEffect(() => {
+    gameRef.current?.focus({ preventScroll: true });
+  }, []);
+
+  return (
+    <div
+      id="demo-game"
+      ref={gameRef}
+      className={styles.game}
+      tabIndex={0}
+      aria-label={`${title} game`}
+      onFocus={() => setHasFocus(true)}
+      onBlur={() => setHasFocus(false)}
+    >
+      <FullscreenButton
+        isFullscreen={isFullscreen}
+        onToggle={toggleFullscreen}
+      />
+      <div
+        className={clsx(styles.focusHint, hasFocus && styles.focusHintHidden)}
+        aria-hidden="true"
+      >
+        <i className="fa-solid fa-hand-pointer"></i> Click to play
+      </div>
+    </div>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/DemoHeader.module.css b/documentation-site/src/components/demo-page/DemoHeader.module.css
new file mode 100644
index 000000000..a1dfaac2d
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoHeader.module.css
@@ -0,0 +1,32 @@
+.back {
+  display: inline-block;
+  margin-bottom: 0.75rem;
+  font-size: 0.9rem;
+}
+
+.header {
+  margin-bottom: 1.25rem;
+}
+
+.title {
+  margin-bottom: 0.25rem;
+}
+
+.summary {
+  max-width: 70ch;
+  margin: 0;
+  font-size: 1.1rem;
+  color: var(--ifm-color-emphasis-700);
+}
+
+.docLinks {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem 0.75rem;
+  margin-top: 0.5rem;
+  font-size: 0.95rem;
+}
+
+.docLinks span {
+  color: var(--ifm-color-emphasis-700);
+}
diff --git a/documentation-site/src/components/demo-page/DemoHeader.tsx b/documentation-site/src/components/demo-page/DemoHeader.tsx
new file mode 100644
index 000000000..a96dcd825
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoHeader.tsx
@@ -0,0 +1,46 @@
+import React, { FC } from 'react';
+import Link from '@docusaurus/Link';
+import { useDemoBackLink } from '@site/src/hooks/useDemoBackLink';
+import styles from './DemoHeader.module.css';
+import { DemoDocLink } from './types';
+
+interface DemoHeaderProps {
+  title: string;
+  summary: string;
+  docLinks: DemoDocLink[];
+}
+
+/**
+ * A demo page's back link, title, one-line summary and links to the docs.
+ */
+export const DemoHeader: FC<DemoHeaderProps> = ({
+  title,
+  summary,
+  docLinks,
+}) => {
+  const backLink = useDemoBackLink();
+
+  return (
+    <>
+      <Link to={backLink.to} className={styles.back}>
+        {backLink.label}
+      </Link>
+      <header className={styles.header}>
+        <h1 className={styles.title}>{title}</h1>
+        <p className={styles.summary}>{summary}</p>
+        {docLinks.length > 0 && (
+          <nav className={styles.docLinks} aria-label="Related docs">
+            <span>
+              <i className="fa-solid fa-book" aria-hidden="true"></i> Docs:
+            </span>
+            {docLinks.map((docLink) => (
+              <Link key={docLink.to} to={docLink.to}>
+                {docLink.label}
+              </Link>
+            ))}
+          </nav>
+        )}
+      </header>
+    </>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/DemoHighlights.module.css b/documentation-site/src/components/demo-page/DemoHighlights.module.css
new file mode 100644
index 000000000..a92dd557a
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoHighlights.module.css
@@ -0,0 +1,28 @@
+.highlights {
+  display: flex;
+  flex-direction: column;
+  gap: 0.45rem;
+  margin: 0;
+  padding-left: 1.1rem;
+  font-size: 0.9rem;
+  line-height: 1.5;
+}
+
+.fileLink {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3rem;
+  margin-left: 0.4rem;
+  padding: 0 0.4rem;
+  border: none;
+  border-radius: 4px;
+  background-color: var(--ifm-color-emphasis-200);
+  color: var(--ifm-link-color);
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.78rem;
+  cursor: pointer;
+}
+
+.fileLink:hover {
+  background-color: var(--ifm-color-emphasis-300);
+}
diff --git a/documentation-site/src/components/demo-page/DemoHighlights.tsx b/documentation-site/src/components/demo-page/DemoHighlights.tsx
new file mode 100644
index 000000000..4e20f361c
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoHighlights.tsx
@@ -0,0 +1,36 @@
+import React, { FC } from 'react';
+import styles from './DemoHighlights.module.css';
+import { DemoHighlight } from './types';
+
+interface DemoHighlightsProps {
+  highlights: DemoHighlight[];
+  onOpenFile: (fileName: string) => void;
+}
+
+/**
+ * The "How it works" list: a few short points, each with a link that opens
+ * the file implementing it in the code explorer.
+ */
+export const DemoHighlights: FC<DemoHighlightsProps> = ({
+  highlights,
+  onOpenFile,
+}) => {
+  return (
+    <ul className={styles.highlights}>
+      {highlights.map(({ text, file }, index) => (
+        <li key={index}>
+          {text}
+          {file && (
+            <button
+              type="button"
+              className={styles.fileLink}
+              onClick={() => onOpenFile(file)}
+            >
+              <i className="fa-solid fa-code" aria-hidden="true"></i> {file}
+            </button>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/DemoLegend.module.css b/documentation-site/src/components/demo-page/DemoLegend.module.css
new file mode 100644
index 000000000..704b3b993
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoLegend.module.css
@@ -0,0 +1,23 @@
+.legend {
+  display: flex;
+  flex-direction: column;
+  gap: 0.45rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  font-size: 0.9rem;
+}
+
+.item {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+}
+
+.marker {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.25rem;
+}
diff --git a/documentation-site/src/components/demo-page/DemoLegend.tsx b/documentation-site/src/components/demo-page/DemoLegend.tsx
new file mode 100644
index 000000000..ce48f3e0a
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoLegend.tsx
@@ -0,0 +1,24 @@
+import React, { FC } from 'react';
+import styles from './DemoLegend.module.css';
+import { DemoLegendItem } from './types';
+
+interface DemoLegendProps {
+  items: DemoLegendItem[];
+}
+
+/**
+ * A key to what the markers in a demo's scene mean, such as the color of
+ * each row. Put it in a {@link DemoPanel}.
+ */
+export const DemoLegend: FC<DemoLegendProps> = ({ items }) => {
+  return (
+    <ul className={styles.legend}>
+      {items.map((item) => (
+        <li key={item.label} className={styles.item}>
+          <span className={styles.marker}>{item.marker}</span>
+          {item.label}
+        </li>
+      ))}
+    </ul>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/DemoPage.module.css b/documentation-site/src/components/demo-page/DemoPage.module.css
new file mode 100644
index 000000000..cd68bd6ce
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoPage.module.css
@@ -0,0 +1,61 @@
+.page {
+  width: 100%;
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 1.5rem 1.5rem 3rem;
+}
+
+.stage {
+  --sidebar-width: 380px;
+  --stage-gap: 1.25rem;
+
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) var(--sidebar-width);
+  gap: var(--stage-gap);
+  container-type: inline-size;
+}
+
+/* The game grows to end level with the sidebar, but never past a 3:2
+ * shape: a taller canvas would show less of the world's width. Past that,
+ * the sidebar scrolls instead. */
+.sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  max-height: calc((100cqw - var(--sidebar-width) - var(--stage-gap)) / 1.5);
+  overflow-y: auto;
+}
+
+.source {
+  margin-top: 2.5rem;
+  scroll-margin-top: calc(var(--ifm-navbar-height) + 1rem);
+}
+
+.sourceTitle {
+  margin-bottom: 0.75rem;
+}
+
+@media (max-width: 1200px) {
+  .stage {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .sidebar {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    max-height: none;
+    overflow-y: visible;
+  }
+}
+
+@media (max-width: 996px) {
+  .page {
+    padding: 1rem 1rem 2rem;
+  }
+}
+
+/* The last panel fills any height left beside the game, so the sidebar
+ * ends level with it. */
+.sidebar > :last-child {
+  flex: 1;
+}
diff --git a/documentation-site/src/components/demo-page/DemoPage.tsx b/documentation-site/src/components/demo-page/DemoPage.tsx
new file mode 100644
index 000000000..7ee70226e
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoPage.tsx
@@ -0,0 +1,130 @@
+import React, { FC, ReactNode, useRef, useState } from 'react';
+import Layout from '@theme/Layout';
+import { CreateDemoGame } from '@site/src/hooks/useGame';
+import { demos } from '@site/src/data/demos';
+import styles from './DemoPage.module.css';
+import { CodeExplorer } from './CodeExplorer';
+import { DemoControls } from './DemoControls';
+import { DemoGame } from './DemoGame';
+import { DemoHeader } from './DemoHeader';
+import { DemoHighlights } from './DemoHighlights';
+import { DemoPanel } from './DemoPanel';
+import {
+  DemoControl,
+  DemoDocLink,
+  DemoFile,
+  DemoFileGroup,
+  DemoHighlight,
+} from './types';
+
+interface DemoPageProps {
+  /** The demo's entry in `src/data/demos.ts`, which holds its title and summary. */
+  slug: string;
+  createGame: CreateDemoGame;
+  /** Leave out for a demo you only watch. */
+  controls?: DemoControl[];
+  /**
+   * Extra sidebar content shown after the controls, such as live settings
+   * or a legend. Wrap each in a `DemoPanel`.
+   */
+  panels?: ReactNode;
+  /** The few ideas a reader should take away, each linked to its code. */
+  highlights: DemoHighlight[];
+  docLinks?: DemoDocLink[];
+  /** The first group's first file is the one shown when the page opens. */
+  fileGroups: DemoFileGroup[];
+}
+
+const findFile = (fileGroups: DemoFileGroup[], name: string): DemoFile => {
+  for (const group of fileGroups) {
+    const file = group.files.find((candidate) => candidate.name === name);
+
+    if (file) {
+      return file;
+    }
+  }
+
+  throw new Error(`The demo has no source file named "${name}".`);
+};
+
+/**
+ * A demo page: the running game with its controls and a short explanation
+ * beside it, and a code explorer for the demo's source below.
+ */
+export const DemoPage: FC<DemoPageProps> = ({
+  slug,
+  createGame,
+  controls = [],
+  panels,
+  highlights,
+  docLinks = [],
+  fileGroups,
+}) => {
+  const explorerRef = useRef<HTMLElement>(null);
+  const [selectedFileName, setSelectedFileName] = useState(
+    fileGroups[0].files[0].name,
+  );
+  const demo = demos.find((candidate) => candidate.slug === slug);
+
+  if (!demo) {
+    throw new Error(`No demo with slug "${slug}" in src/data/demos.ts.`);
+  }
+
+  // The explorer shows code a reader can use in their own game. React
+  // components that only drive this site's settings panels aren't that.
+  for (const file of fileGroups.flatMap((group) => group.files)) {
+    if (/\.[jt]sx$/.test(file.name)) {
+      throw new Error(
+        `"${file.name}" is page code, not engine code, so the code explorer doesn't show it.`,
+      );
+    }
+  }
+
+  for (const highlight of highlights) {
+    if (highlight.file) {
+      findFile(fileGroups, highlight.file);
+    }
+  }
+
+  const openFile = (fileName: string): void => {
+    setSelectedFileName(fileName);
+    explorerRef.current?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+  };
+
+  return (
+    <Layout title={`${demo.title} Demo`} description={demo.description}>
+      <main className={styles.page}>
+        <DemoHeader
+          title={demo.title}
+          summary={demo.description}
+          docLinks={docLinks}
+        />
+
+        <div className={styles.stage}>
+          <DemoGame title={demo.title} createGame={createGame} />
+
+          <aside className={styles.sidebar}>
+            {controls.length > 0 && (
+              <DemoPanel title="Controls" icon="fa-keyboard">
+                <DemoControls controls={controls} />
+              </DemoPanel>
+            )}
+            {panels}
+            <DemoPanel title="How it works" icon="fa-lightbulb">
+              <DemoHighlights highlights={highlights} onOpenFile={openFile} />
+            </DemoPanel>
+          </aside>
+        </div>
+
+        <section ref={explorerRef} className={styles.source}>
+          <h2 className={styles.sourceTitle}>Source code</h2>
+          <CodeExplorer
+            fileGroups={fileGroups}
+            selectedFile={findFile(fileGroups, selectedFileName)}
+            onSelectFile={setSelectedFileName}
+          />
+        </section>
+      </main>
+    </Layout>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/DemoPanel.module.css b/documentation-site/src/components/demo-page/DemoPanel.module.css
new file mode 100644
index 000000000..348e1b254
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoPanel.module.css
@@ -0,0 +1,17 @@
+.panel {
+  padding: 0.9rem 1.1rem;
+  border-radius: 8px;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  background-color: var(--ifm-background-surface-color);
+}
+
+.panelTitle {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.6rem;
+  font-size: 0.8rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--ifm-color-emphasis-700);
+}
diff --git a/documentation-site/src/components/demo-page/DemoPanel.tsx b/documentation-site/src/components/demo-page/DemoPanel.tsx
new file mode 100644
index 000000000..9870efdbc
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoPanel.tsx
@@ -0,0 +1,25 @@
+import React, { FC, ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './DemoPanel.module.css';
+
+interface DemoPanelProps {
+  title: string;
+  /** A Font Awesome solid icon name, such as `'fa-keyboard'`. */
+  icon: string;
+  children: ReactNode;
+}
+
+/**
+ * A titled card in a demo page's sidebar. Use it for anything a demo shows
+ * beside its game, such as live settings or a legend.
+ */
+export const DemoPanel: FC<DemoPanelProps> = ({ title, icon, children }) => {
+  return (
+    <section className={styles.panel}>
+      <h2 className={styles.panelTitle}>
+        <i className={clsx('fa-solid', icon)} aria-hidden="true"></i> {title}
+      </h2>
+      {children}
+    </section>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/DemoSettings.module.css b/documentation-site/src/components/demo-page/DemoSettings.module.css
new file mode 100644
index 000000000..02f48a7d1
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoSettings.module.css
@@ -0,0 +1,158 @@
+.settings {
+  display: flex;
+  flex-direction: column;
+  gap: 0.85rem;
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.3rem;
+  min-width: 0;
+}
+
+.fieldHeader {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.5rem;
+  font-size: 0.85rem;
+  font-weight: 600;
+}
+
+.fieldValue {
+  color: var(--ifm-color-emphasis-700);
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.8rem;
+  font-weight: normal;
+}
+
+.slider {
+  width: 100%;
+  margin: 0;
+  accent-color: var(--ifm-color-primary);
+}
+
+.textInput {
+  width: 100%;
+  padding: 0.4rem 0.55rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 6px;
+  background-color: var(--ifm-background-color);
+  color: var(--ifm-font-color-base);
+  font: inherit;
+  font-size: 0.88rem;
+  resize: vertical;
+}
+
+.textInput:focus {
+  border-color: var(--ifm-color-primary);
+  outline: none;
+}
+
+.choice {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.3rem;
+}
+
+.choiceButton {
+  flex: 1 0 auto;
+  padding: 0.25rem 0.55rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 6px;
+  background: none;
+  color: var(--ifm-font-color-base);
+  font-size: 0.8rem;
+  cursor: pointer;
+}
+
+.choiceButton:hover {
+  background-color: var(--ifm-color-emphasis-200);
+}
+
+.choiceButtonSelected,
+.choiceButtonSelected:hover {
+  border-color: var(--ifm-color-primary);
+  background-color: var(--ifm-color-primary);
+  color: var(--ifm-background-color);
+  font-weight: 600;
+}
+
+.toggle {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.toggleRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  font-size: 0.85rem;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.toggleInput {
+  position: relative;
+  flex-shrink: 0;
+  width: 2.2rem;
+  height: 1.2rem;
+  margin: 0;
+  border-radius: 999px;
+  background-color: var(--ifm-color-emphasis-400);
+  appearance: none;
+  cursor: pointer;
+  transition: background-color 0.15s;
+}
+
+.toggleInput::after {
+  position: absolute;
+  top: 0.15rem;
+  left: 0.15rem;
+  width: 0.9rem;
+  height: 0.9rem;
+  border-radius: 50%;
+  background-color: white;
+  content: '';
+  transition: transform 0.15s;
+}
+
+.toggleInput:checked {
+  background-color: var(--ifm-color-primary);
+}
+
+.toggleInput:checked::after {
+  transform: translateX(1rem);
+}
+
+.toggleInput:focus-visible {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: 2px;
+}
+
+.toggleChildren {
+  display: flex;
+  flex-direction: column;
+  gap: 0.85rem;
+  padding-left: 0.75rem;
+  border-left: 2px solid var(--ifm-color-emphasis-300);
+}
+
+.section {
+  display: flex;
+  flex-direction: column;
+  gap: 0.85rem;
+  padding-top: 0.85rem;
+  border-top: 1px solid var(--ifm-color-emphasis-200);
+}
+
+.sectionTitle {
+  margin: 0;
+  font-size: 0.72rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--ifm-color-emphasis-600);
+}
diff --git a/documentation-site/src/components/demo-page/DemoSettings.tsx b/documentation-site/src/components/demo-page/DemoSettings.tsx
new file mode 100644
index 000000000..8c2da267d
--- /dev/null
+++ b/documentation-site/src/components/demo-page/DemoSettings.tsx
@@ -0,0 +1,202 @@
+import React, { ReactNode, useId } from 'react';
+import clsx from 'clsx';
+import styles from './DemoSettings.module.css';
+
+/**
+ * Stacks a demo's live settings (sliders, toggles, choices) in a
+ * `DemoPanel`, with even spacing.
+ */
+export const DemoSettings = ({
+  children,
+}: {
+  children: ReactNode;
+}): ReactNode => <div className={styles.settings}>{children}</div>;
+
+/**
+ * A titled group of settings, separated from the ones above it.
+ */
+export const DemoSettingsSection = ({
+  title,
+  children,
+}: {
+  title: string;
+  children: ReactNode;
+}): ReactNode => (
+  <section className={styles.section}>
+    <h3 className={styles.sectionTitle}>{title}</h3>
+    {children}
+  </section>
+);
+
+interface DemoSliderProps {
+  label: string;
+  value: number;
+  min: number;
+  max: number;
+  step?: number;
+  /** Formats the value shown beside the label. Shows it as is by default. */
+  format?: (value: number) => string;
+  onChange: (value: number) => void;
+}
+
+/**
+ * A labeled range slider that shows its current value.
+ */
+export const DemoSlider = ({
+  label,
+  value,
+  min,
+  max,
+  step = 1,
+  format = String,
+  onChange,
+}: DemoSliderProps): ReactNode => {
+  const id = useId();
+
+  return (
+    <div className={styles.field}>
+      <label htmlFor={id} className={styles.fieldHeader}>
+        {label}
+        <span className={styles.fieldValue}>{format(value)}</span>
+      </label>
+      <input
+        id={id}
+        className={styles.slider}
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        onChange={(event) => onChange(Number(event.target.value))}
+      />
+    </div>
+  );
+};
+
+interface DemoTextFieldProps {
+  label: string;
+  value: string;
+  /** More than one row makes it a multi-line text area. */
+  rows?: number;
+  onChange: (value: string) => void;
+}
+
+/**
+ * A labeled text box, single- or multi-line.
+ */
+export const DemoTextField = ({
+  label,
+  value,
+  rows = 1,
+  onChange,
+}: DemoTextFieldProps): ReactNode => {
+  const id = useId();
+
+  return (
+    <div className={styles.field}>
+      <label htmlFor={id} className={styles.fieldHeader}>
+        {label}
+      </label>
+      {rows > 1 ? (
+        <textarea
+          id={id}
+          className={styles.textInput}
+          rows={rows}
+          value={value}
+          onChange={(event) => onChange(event.target.value)}
+        />
+      ) : (
+        <input
+          id={id}
+          className={styles.textInput}
+          type="text"
+          value={value}
+          onChange={(event) => onChange(event.target.value)}
+        />
+      )}
+    </div>
+  );
+};
+
+interface DemoChoiceProps<T extends string> {
+  label: string;
+  value: T;
+  options: readonly { value: T; label: string }[];
+  onChange: (value: T) => void;
+}
+
+/**
+ * A row of buttons for picking one of a few options.
+ */
+export const DemoChoice = <T extends string>({
+  label,
+  value,
+  options,
+  onChange,
+}: DemoChoiceProps<T>): ReactNode => {
+  const id = useId();
+
+  return (
+    <div className={styles.field}>
+      <span id={id} className={styles.fieldHeader}>
+        {label}
+      </span>
+      <div className={styles.choice} role="radiogroup" aria-labelledby={id}>
+        {options.map((option) => (
+          <button
+            key={option.value}
+            type="button"
+            role="radio"
+            aria-checked={option.value === value}
+            className={clsx(
+              styles.choiceButton,
+              option.value === value && styles.choiceButtonSelected,
+            )}
+            onClick={() => onChange(option.value)}
+          >
+            {option.label}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+interface DemoToggleProps {
+  label: string;
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  /** Settings that only apply while the toggle is on, shown below it then. */
+  children?: ReactNode;
+}
+
+/**
+ * A labeled on/off switch. Its `children` only show while it's on.
+ */
+export const DemoToggle = ({
+  label,
+  checked,
+  onChange,
+  children,
+}: DemoToggleProps): ReactNode => {
+  const id = useId();
+
+  return (
+    <div className={styles.toggle}>
+      <label htmlFor={id} className={styles.toggleRow}>
+        {label}
+        <input
+          id={id}
+          className={styles.toggleInput}
+          type="checkbox"
+          role="switch"
+          checked={checked}
+          onChange={(event) => onChange(event.target.checked)}
+        />
+      </label>
+      {checked && children && (
+        <div className={styles.toggleChildren}>{children}</div>
+      )}
+    </div>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/FullscreenButton.module.css b/documentation-site/src/components/demo-page/FullscreenButton.module.css
new file mode 100644
index 000000000..5ca761c70
--- /dev/null
+++ b/documentation-site/src/components/demo-page/FullscreenButton.module.css
@@ -0,0 +1,17 @@
+.fullscreenButton {
+  position: absolute;
+  top: 10px;
+  right: 10px;
+  z-index: 1;
+  background-color: rgba(11, 19, 43, 0.75);
+  border: 1px solid rgba(207, 214, 234, 0.2);
+  border-radius: 6px;
+  color: white;
+  padding: 8px 10px;
+  cursor: pointer;
+}
+
+.fullscreenButton:hover {
+  border-color: var(--forge-amber);
+  color: var(--forge-amber);
+}
diff --git a/documentation-site/src/components/demo-page/FullscreenButton.tsx b/documentation-site/src/components/demo-page/FullscreenButton.tsx
new file mode 100644
index 000000000..ac0931fcf
--- /dev/null
+++ b/documentation-site/src/components/demo-page/FullscreenButton.tsx
@@ -0,0 +1,27 @@
+import React, { FC } from 'react';
+import clsx from 'clsx';
+import styles from './FullscreenButton.module.css';
+
+interface FullscreenButtonProps {
+  isFullscreen: boolean;
+  onToggle: () => void;
+}
+
+export const FullscreenButton: FC<FullscreenButtonProps> = ({
+  isFullscreen,
+  onToggle,
+}) => {
+  return (
+    <button
+      type="button"
+      className={styles.fullscreenButton}
+      onClick={onToggle}
+      aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
+      title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}
+    >
+      <i
+        className={clsx('fa-solid', isFullscreen ? 'fa-compress' : 'fa-expand')}
+      ></i>
+    </button>
+  );
+};
diff --git a/documentation-site/src/components/demo-page/file-types.ts b/documentation-site/src/components/demo-page/file-types.ts
new file mode 100644
index 000000000..1d6c80d09
--- /dev/null
+++ b/documentation-site/src/components/demo-page/file-types.ts
@@ -0,0 +1,43 @@
+/**
+ * What kind of code a demo source file holds, worked out from its name:
+ * `*.component.ts` and `*.system.ts` are ECS components and systems,
+ * `*.shader.*` and `*.glsl` are shaders, and everything else sets up the
+ * game.
+ */
+export type DemoFileType = 'component' | 'system' | 'shader' | 'setup';
+
+interface DemoFileTypeInfo {
+  label: string;
+  pluralLabel: string;
+  icon: string;
+}
+
+export const demoFileTypes: Record<DemoFileType, DemoFileTypeInfo> = {
+  setup: { label: 'Setup', pluralLabel: 'Setup', icon: 'fa-wrench' },
+  component: { label: 'Component', pluralLabel: 'Components', icon: 'fa-cube' },
+  system: { label: 'System', pluralLabel: 'Systems', icon: 'fa-gears' },
+  shader: { label: 'Shader', pluralLabel: 'Shaders', icon: 'fa-palette' },
+};
+
+export const demoFileTypeOrder: readonly DemoFileType[] = [
+  'setup',
+  'component',
+  'system',
+  'shader',
+];
+
+export const getDemoFileType = (fileName: string): DemoFileType => {
+  if (fileName.includes('.component.')) {
+    return 'component';
+  }
+
+  if (fileName.includes('.system.')) {
+    return 'system';
+  }
+
+  if (fileName.includes('.shader.') || fileName.endsWith('.glsl')) {
+    return 'shader';
+  }
+
+  return 'setup';
+};
diff --git a/documentation-site/src/components/demo-page/index.ts b/documentation-site/src/components/demo-page/index.ts
new file mode 100644
index 000000000..b9d5a89a3
--- /dev/null
+++ b/documentation-site/src/components/demo-page/index.ts
@@ -0,0 +1,12 @@
+export * from './CodeExplorer';
+export * from './DemoControls';
+export * from './DemoGame';
+export * from './DemoHeader';
+export * from './DemoHighlights';
+export * from './DemoLegend';
+export * from './DemoPage';
+export * from './DemoPanel';
+export * from './DemoSettings';
+export * from './FullscreenButton';
+export * from './file-types';
+export * from './types';
diff --git a/documentation-site/src/components/demo-page/types.ts b/documentation-site/src/components/demo-page/types.ts
new file mode 100644
index 000000000..63e7f9825
--- /dev/null
+++ b/documentation-site/src/components/demo-page/types.ts
@@ -0,0 +1,65 @@
+import { ReactNode } from 'react';
+
+/**
+ * One input that triggers a control: a key's label (`'→'`, `'D'`,
+ * `'Space'`), or a mouse or gamepad input described in a few words.
+ */
+export type DemoInput =
+  string | { device: 'mouse' | 'gamepad' | 'touch'; label: string };
+
+/**
+ * One action the player can take, and the inputs that trigger it.
+ * Alternatives in `inputs` are shown joined by "or".
+ */
+export interface DemoControl {
+  inputs: DemoInput[];
+  action: string;
+  /** A short note on what the action does in special situations. */
+  detail?: string;
+}
+
+/**
+ * A source file shown in the code explorer: engine code a reader can reuse
+ * in their own game. Never a React (`.tsx`) file that only drives the
+ * site's page.
+ */
+export interface DemoFile {
+  name: string;
+  /** One sentence on what the file does, shown above its code. */
+  summary: string;
+  content: string;
+}
+
+/**
+ * Files listed together under one heading in the code explorer.
+ */
+export interface DemoFileGroup {
+  title: string;
+  files: DemoFile[];
+}
+
+/**
+ * One point in a demo's "How it works" list, optionally linked to the file
+ * that implements it.
+ */
+export interface DemoHighlight {
+  text: ReactNode;
+  file?: string;
+}
+
+/**
+ * A link to the documentation for a feature the demo uses.
+ */
+export interface DemoDocLink {
+  label: string;
+  to: string;
+}
+
+/**
+ * One entry in a {@link DemoLegend}: a marker (a color swatch, a number)
+ * and what it stands for.
+ */
+export interface DemoLegendItem {
+  marker: ReactNode;
+  label: string;
+}
diff --git a/documentation-site/src/components/home/Home.module.css b/documentation-site/src/components/home/Home.module.css
new file mode 100644
index 000000000..c823f5b8e
--- /dev/null
+++ b/documentation-site/src/components/home/Home.module.css
@@ -0,0 +1,245 @@
+/* Hero */
+
+.hero {
+  overflow: hidden;
+  padding: 6rem 1.5rem 5rem;
+  color: var(--forge-periwinkle);
+  background: var(--forge-navy);
+}
+
+.heroInner {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1.15fr);
+  gap: 3.5rem;
+  align-items: center;
+  /* The same column as the sections below. */
+  max-width: calc(1200px - 3rem);
+  margin: 0 auto;
+}
+
+/* The gameplay video, framed like a screen. */
+.heroMedia {
+  margin: 0;
+}
+
+.heroScreen {
+  overflow: hidden;
+  aspect-ratio: 16 / 9;
+  border: 1px solid rgba(207, 214, 234, 0.18);
+  border-radius: 12px;
+  background: #000000;
+  box-shadow:
+    0 0 0 1px rgba(79, 196, 196, 0.15),
+    0 24px 60px rgba(0, 0, 0, 0.45),
+    0 0 80px rgba(79, 196, 196, 0.12);
+}
+
+.heroCaption {
+  margin-top: 0.75rem;
+  color: #9aa4c4;
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.78rem;
+  letter-spacing: 0.05em;
+  text-align: right;
+}
+
+.heroVideo {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.heroTitle {
+  margin: 0 0 1rem;
+  color: #ffffff;
+  font-size: clamp(3rem, 8vw, 5.5rem);
+  line-height: 1;
+}
+
+.heroIntro {
+  max-width: 40rem;
+  margin: 0 0 2rem;
+  color: #c3cbe0;
+  font-size: clamp(1.1rem, 2vw, 1.35rem);
+  line-height: 1.5;
+}
+
+.heroActions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+  margin-bottom: 2rem;
+}
+
+.heroSecondary {
+  border-color: rgba(207, 214, 234, 0.3);
+  color: #e6eaf5;
+}
+
+.install {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.75rem;
+  max-width: 100%;
+  padding: 0.35rem 0.35rem 0.35rem 1rem;
+  border: 1px solid rgba(207, 214, 234, 0.18);
+  border-radius: 8px;
+  background: rgba(11, 19, 43, 0.6);
+}
+
+.installCommand {
+  overflow-x: auto;
+  padding: 0;
+  border: none;
+  background: none;
+  color: #e6eaf5;
+  font-size: 0.9rem;
+  white-space: nowrap;
+}
+
+.copyButton {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.35rem 0.65rem;
+  border: 1px solid rgba(207, 214, 234, 0.18);
+  border-radius: 6px;
+  background: transparent;
+  color: #c3cbe0;
+  font-size: 0.8rem;
+  cursor: pointer;
+  transition:
+    color 0.15s,
+    border-color 0.15s;
+}
+
+.copyButton:hover {
+  border-color: var(--forge-amber);
+  color: var(--forge-amber);
+}
+
+.copyButtonCopied,
+.copyButtonCopied:hover {
+  border-color: #4fc4c4;
+  color: #4fc4c4;
+}
+
+.installPrompt {
+  color: var(--forge-amber);
+}
+
+/* Sections */
+
+.section {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 5rem 1.5rem;
+}
+
+.sectionTitle {
+  margin: 0 0 1rem;
+  font-size: clamp(2.2rem, 5vw, 3.25rem);
+  line-height: 1.1;
+}
+
+.sectionIntro {
+  max-width: 48rem;
+  margin: 0 0 3rem;
+  color: var(--text-muted-color);
+  font-size: clamp(1.05rem, 1.8vw, 1.3rem);
+  line-height: 1.5;
+}
+
+.sectionFooter {
+  margin-top: 2rem;
+  font-weight: 600;
+}
+
+/* Modules */
+
+.moduleGrid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 0.5rem 1.5rem;
+}
+
+.module {
+  display: flex;
+  gap: 1rem;
+  margin: 0 -0.75rem;
+  padding: 0.9rem 0.75rem;
+  border-radius: 10px;
+  color: inherit;
+  text-decoration: none;
+  transition: background-color 0.15s;
+}
+
+.module:hover {
+  background-color: var(--card-background-color);
+  color: inherit;
+  text-decoration: none;
+}
+
+.module:hover .moduleTitle {
+  color: var(--ifm-color-primary);
+}
+
+.moduleTitle {
+  margin: 0 0 0.2rem;
+  font-size: 1.2rem;
+  transition: color 0.15s;
+}
+
+.moduleDescription {
+  margin: 0;
+  color: var(--text-muted-color);
+  font-size: 0.95rem;
+  line-height: 1.45;
+}
+
+/* Demos */
+
+.demoGrid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 1.25rem;
+}
+
+@media (max-width: 996px) {
+  .heroInner {
+    grid-template-columns: minmax(0, 1fr);
+    gap: 2.5rem;
+  }
+}
+
+@media (max-width: 1100px) {
+  .moduleGrid,
+  .demoGrid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 600px) {
+  .hero {
+    padding: 4rem 1rem 3.5rem;
+  }
+
+  .installCommand {
+    font-size: 0.78rem;
+  }
+
+  .copyLabel {
+    display: none;
+  }
+
+  .section {
+    padding: 3.5rem 1rem;
+  }
+
+  .moduleGrid,
+  .demoGrid {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
diff --git a/documentation-site/src/components/home/InstallCommand.tsx b/documentation-site/src/components/home/InstallCommand.tsx
new file mode 100644
index 000000000..259d58a7c
--- /dev/null
+++ b/documentation-site/src/components/home/InstallCommand.tsx
@@ -0,0 +1,54 @@
+import React, { FC, useEffect, useState } from 'react';
+import clsx from 'clsx';
+import styles from './Home.module.css';
+
+const command = 'npm install @forge-game-engine/forge';
+const copiedFeedbackMilliseconds = 2000;
+
+/**
+ * The npm install command, with a button that copies it.
+ */
+export const InstallCommand: FC = () => {
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => {
+    if (!copied) {
+      return undefined;
+    }
+
+    const timeout = setTimeout(
+      () => setCopied(false),
+      copiedFeedbackMilliseconds,
+    );
+
+    return () => clearTimeout(timeout);
+  }, [copied]);
+
+  const copy = (): void => {
+    navigator.clipboard.writeText(command).then(
+      () => setCopied(true),
+      (error: unknown) => console.error('Failed to copy the command:', error),
+    );
+  };
+
+  return (
+    <div className={styles.install}>
+      <code className={styles.installCommand}>
+        <span className={styles.installPrompt}>$</span> {command}
+      </code>
+      <button
+        type="button"
+        className={clsx(styles.copyButton, copied && styles.copyButtonCopied)}
+        onClick={copy}
+        aria-label={copied ? 'Copied' : 'Copy the install command'}
+        title={copied ? 'Copied' : 'Copy'}
+      >
+        <i
+          className={clsx('fa-solid', copied ? 'fa-check' : 'fa-copy')}
+          aria-hidden="true"
+        ></i>
+        <span className={styles.copyLabel}>{copied ? 'Copied' : 'Copy'}</span>
+      </button>
+    </div>
+  );
+};
diff --git a/documentation-site/src/css/custom.css b/documentation-site/src/css/custom.css
index 742e06500..d9fce3195 100644
--- a/documentation-site/src/css/custom.css
+++ b/documentation-site/src/css/custom.css
@@ -1,56 +1,94 @@
 /**
- * Any CSS included here will be global. The classic template
- * bundles Infima by default. Infima is a CSS framework designed to
- * work well for content-centric websites.
+ * Global styles for the docs site. Infima (Docusaurus's CSS framework)
+ * reads the --ifm-* variables below, so most of the look is set here.
  */
 
 /*
- * Brand palette: https://coolors.co/0b132b-1c2541-cfd6ea-4e878c-ffbc42
- * #0b132b (navy), #1c2541 (dark blue), #cfd6ea (periwinkle), #4e878c (teal),
- * #ffbc42 (amber). Shade ramps below are the teal hue lightened/darkened
- * to keep AA contrast against each mode's background.
+ * Brand palette: navy (#0b132b), dark blue (#1c2541), periwinkle (#cfd6ea),
+ * teal and amber (#ffbc42). Dark mode is the brand's home: a deep navy
+ * background with a bright teal for links and icons and amber for accents.
+ * Light mode keeps the same hues, with a darker teal so links stay readable
+ * on white.
  */
 :root {
-  --ifm-color-primary: #4e878c;
-  --ifm-color-primary-dark: #3f6e72;
-  --ifm-color-primary-darker: #315458;
-  --ifm-color-primary-darkest: #1b2f30;
-  --ifm-color-primary-light: #5e9fa5;
-  --ifm-color-primary-lighter: #78afb4;
-  --ifm-color-primary-lightest: #9fc6ca;
-  /* The base teal only clears ~4:1 against a white background, so links
-   * (normal-weight body text) use the darker shade for AA contrast. */
+  --forge-navy: #0b132b;
+  --forge-navy-light: #1c2541;
+  --forge-periwinkle: #cfd6ea;
+  --forge-amber: #ffbc42;
+  --forge-amber-dark: #ffa605;
+
+  --ifm-font-family-base:
+    'Inter Variable', 'Inter', system-ui, -apple-system, 'Segoe UI', sans-serif;
+  --ifm-heading-font-family:
+    'Orbitron', 'Inter Variable', system-ui, -apple-system, sans-serif;
+  --ifm-font-family-monospace:
+    'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
+  --ifm-heading-font-weight: 700;
+  --ifm-code-font-size: 90%;
+  --ifm-global-radius: 8px;
+  --ifm-navbar-height: 4rem;
+
+  --ifm-color-primary: #2f7f86;
+  --ifm-color-primary-dark: #2a7279;
+  --ifm-color-primary-darker: #286c72;
+  --ifm-color-primary-darkest: #21595e;
+  --ifm-color-primary-light: #348c93;
+  --ifm-color-primary-lighter: #36929a;
+  --ifm-color-primary-lightest: #3da5ae;
   --ifm-link-color: var(--ifm-color-primary-dark);
-  --text-color: #1c2541;
-  --ifm-code-font-size: 95%;
+
+  --ifm-background-color: #f5f7fc;
+  --ifm-background-surface-color: #ffffff;
+  --ifm-font-color-base: #1c2541;
+  --ifm-heading-color: #0b132b;
+  --ifm-color-emphasis-700: #4a5578;
+  --ifm-toc-border-color: #dde2ef;
+  --ifm-hr-border-color: #dde2ef;
+
   --docusaurus-highlighted-code-line-bg: rgba(11, 19, 43, 0.08);
-  /* The hero is a fixed navy gradient in both themes (see .hero--primary),
-   * so one light text color covers both. */
-  --hero-font-color: #cfd6ea;
-  --card-highlight-color: #ffbc42;
-  --card-background-color: #cfd6ea;
-  --ifm-footer-background-color: #0b132b;
-  --ifm-footer-color: #cfd6ea;
-  --ifm-footer-link-color: #9fc6ca;
-  --ifm-footer-link-hover-color: #ffbc42;
+
+  /* Shared by the site's own components (cards, search, demo pages). */
+  --text-color: var(--ifm-font-color-base);
+  --text-muted-color: #5a6587;
+  --card-background-color: var(--ifm-background-surface-color);
+  --card-border-color: #dde2ef;
+  --card-highlight-color: var(--forge-amber);
+  --hero-font-color: var(--forge-periwinkle);
+
+  --ifm-footer-background-color: var(--forge-navy);
+  --ifm-footer-color: #9aa4c4;
+  --ifm-footer-link-color: #c3cbe0;
+  --ifm-footer-link-hover-color: var(--forge-amber);
   --ifm-footer-title-color: #ffffff;
 }
 
-/* For readability concerns, you should choose a lighter palette in dark mode. */
 [data-theme='dark'] {
-  --ifm-color-primary: #85b7bb;
-  --ifm-color-primary-dark: #6ba7ac;
-  --ifm-color-primary-darker: #559499;
-  --ifm-color-primary-darkest: #3f6e72;
-  --ifm-color-primary-light: #9fc6ca;
-  --ifm-color-primary-lighter: #b9d6d8;
-  --ifm-color-primary-lightest: #d4e5e7;
-  --text-color: #cfd6ea;
+  --ifm-color-primary: #4fc4c4;
+  --ifm-color-primary-dark: #3dbcbc;
+  --ifm-color-primary-darker: #39b1b1;
+  --ifm-color-primary-darkest: #2f9292;
+  --ifm-color-primary-light: #66cbcb;
+  --ifm-color-primary-lighter: #72cfcf;
+  --ifm-color-primary-lightest: #94dbdb;
+  --ifm-link-color: var(--ifm-color-primary);
+
+  --ifm-background-color: #0b132b;
+  --ifm-background-surface-color: #111b38;
+  --ifm-font-color-base: #c3cbe0;
+  --ifm-heading-color: #f2f4fa;
+  --ifm-color-emphasis-700: #9aa4c4;
+  --ifm-toc-border-color: rgba(207, 214, 234, 0.12);
+  --ifm-hr-border-color: rgba(207, 214, 234, 0.12);
+  --ifm-navbar-background-color: rgba(11, 19, 43, 0.85);
+  --ifm-code-background: rgba(207, 214, 234, 0.08);
+
   --docusaurus-highlighted-code-line-bg: rgba(255, 255, 255, 0.08);
-  /* Amber-on-light-text fails contrast, so dark mode's highlight uses the
-   * darker teal shade instead, which stays readable with light body text. */
-  --card-highlight-color: #315458;
-  --card-background-color: #1c2541;
+
+  --text-muted-color: #8f9abb;
+  --card-border-color: rgba(207, 214, 234, 0.12);
+  /* Amber text on amber fails contrast, so dark cards highlight with a
+   * deep teal instead. */
+  --card-highlight-color: #1d4247;
 }
 
 .main-wrapper {
@@ -58,39 +96,129 @@
   justify-content: center;
 }
 
-/* The hero CTA uses the amber accent (with dark navy text) so it pops
- * against the navy hero rather than blending into it. */
+h1,
+h2,
+h3 {
+  letter-spacing: 0.01em;
+}
+
+/* A small, letter-spaced monospace label above a heading. */
+.eyebrow {
+  margin-bottom: 0.5rem;
+  color: var(--ifm-color-emphasis-700);
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.8rem;
+  font-weight: 500;
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+}
+
+/* Navbar: translucent navy with a blur in both themes, so the white logo
+ * and the brand bar look the same in light mode. */
+.navbar {
+  --ifm-navbar-background-color: rgba(11, 19, 43, 0.92);
+  --ifm-navbar-link-color: #c3cbe0;
+  --ifm-navbar-link-hover-color: #ffffff;
+  --ifm-navbar-link-active-color: #4fc4c4;
+  --ifm-menu-color: #c3cbe0;
+
+  border-bottom: 1px solid rgba(207, 214, 234, 0.12);
+  box-shadow: none;
+  backdrop-filter: blur(12px);
+}
+
+.navbar__title {
+  color: #ffffff;
+}
+
+.navbar .clean-btn,
+.navbar__toggle {
+  color: #c3cbe0;
+}
+
+.navbar .navbar__title {
+  font-family: var(--ifm-heading-font-family);
+  font-size: 1.3rem;
+  font-weight: 700;
+  letter-spacing: 0.02em;
+}
+
+.navbar__link {
+  font-weight: 500;
+}
+
+/* Buttons: amber call to action, outlined secondary. */
+.button {
+  font-family: var(--ifm-heading-font-family);
+  font-weight: 600;
+  letter-spacing: 0.03em;
+}
+
 .button--primary {
-  background: #ffbc42;
-  color: #1c2541;
   border: none;
+  background: var(--forge-amber);
+  color: var(--forge-navy);
 }
 
 .button--primary:hover {
-  background: #ffa605;
-  color: #1c2541;
-  box-shadow: 0 0 20px rgba(255, 188, 66, 0.6);
+  background: var(--forge-amber-dark);
+  color: var(--forge-navy);
+  box-shadow: 0 0 24px rgba(255, 188, 66, 0.45);
 }
 
 .button--secondary {
+  border: 1px solid var(--card-border-color);
   background: transparent;
-  color: var(--hero-font-color);
-  border: 1px solid rgba(207, 214, 234, 0.4);
+  color: var(--ifm-font-color-base);
   transition: none;
 }
 
 .button--secondary:hover {
-  background: #cfd6ea;
-  color: #1c2541;
-  border: 1px solid #cfd6ea;
+  border-color: var(--ifm-color-primary);
+  background: transparent;
+  color: var(--ifm-color-primary);
+}
+
+/* Code blocks and inline code. */
+.theme-code-block {
+  border: 1px solid var(--card-border-color);
+  box-shadow: none;
+}
+
+code {
+  border: none;
+}
+
+/* Docs sidebar and table of contents. */
+.menu__link {
+  font-size: 0.92rem;
+}
+
+.menu__link--active:not(.menu__link--sublist) {
+  font-weight: 600;
+}
+
+.theme-doc-sidebar-container {
+  border-right-color: var(--card-border-color) !important;
+}
+
+/* Admonitions read as cards, not loud colored boxes. */
+.theme-admonition {
+  border: 1px solid var(--card-border-color);
+  border-left-width: 4px;
+  box-shadow: none;
+}
+
+.footer {
+  border-top: 1px solid var(--card-border-color);
 }
 
-/* A fixed navy gradient (not the interactive teal primary) so the hero
- * reads as a bold brand statement in both themes, with teal and amber
- * reserved as accents on top of it. */
-.hero--primary {
-  background: linear-gradient(160deg, #0b132b 0%, #1c2541 100%);
-  color: var(--hero-font-color);
+.footer__title {
+  font-family: var(--ifm-font-family-monospace);
+  font-size: 0.8rem;
+  font-weight: 500;
+  letter-spacing: 0.15em;
+  text-transform: uppercase;
 }
 
 .code-block-removed-line {
diff --git a/documentation-site/src/data/demo-categories.ts b/documentation-site/src/data/demo-categories.ts
index 11a8351c8..a5476969b 100644
--- a/documentation-site/src/data/demo-categories.ts
+++ b/documentation-site/src/data/demo-categories.ts
@@ -1,10 +1,13 @@
+import type { ModuleIconName } from '@site/src/components/ModuleIcon';
+
 /**
  * A category demos can be sorted into on the `/demos` page. A demo can
  * belong to more than one category (see `Demo.categories` in `./demos.ts`).
  */
 export interface DemoCategory {
   description: string;
-  image: string;
+  /** The line icon the category's card shows, shared with the homepage. */
+  icon: ModuleIconName;
   slug: string;
   title: string;
 }
@@ -13,46 +16,43 @@ export const demoCategories: DemoCategory[] = [
   {
     slug: 'rendering',
     title: 'Rendering',
-    description: 'Sprites, shaders, text and other WebGL2 rendering features.',
-    image: '/img/demos/categories/rendering.svg',
+    description: 'Sprites, shaders, text and post-processing.',
+    icon: 'rendering',
   },
   {
     slug: 'physics',
     title: 'Physics',
-    description: 'Rigid bodies, joints, motors and collision resolution.',
-    image: '/img/demos/categories/physics.svg',
+    description: 'Rigid bodies, joints, motors and collisions.',
+    icon: 'physics',
   },
   {
     slug: 'ui',
     title: 'UI',
-    description:
-      'The retained-mode UI module: layout, anchoring, buttons, sliders and more.',
-    image: '/img/demos/categories/ui.svg',
+    description: 'Layout, anchoring, buttons, sliders and more.',
+    icon: 'ui',
   },
   {
     slug: 'particles',
     title: 'Particles',
-    description:
-      'The particle system, for effects like fountains, bursts and trails.',
-    image: '/img/demos/categories/particles.svg',
+    description: 'Emitters, bursts and spawn shapes.',
+    icon: 'particles',
   },
   {
     slug: 'animations',
     title: 'Animations',
-    description: 'Easing and other animation utilities.',
-    image: '/img/demos/categories/animations.svg',
+    description: 'Easing and property animations.',
+    icon: 'animations',
   },
   {
     slug: 'ecs',
     title: 'ECS',
-    description: 'The core Entity-Component-System architecture.',
-    image: '/img/demos/categories/ecs.svg',
+    description: 'Worlds, entities, components and systems.',
+    icon: 'ecs',
   },
   {
     slug: 'games',
     title: 'Games',
-    description:
-      'Complete, composite demos that combine many engine features at once.',
-    image: '/img/demos/categories/games.svg',
+    description: 'Complete games that combine many engine features.',
+    icon: 'input',
   },
 ];
diff --git a/documentation-site/src/data/demos.ts b/documentation-site/src/data/demos.ts
index ebdd6f0d6..a8bb4a679 100644
--- a/documentation-site/src/data/demos.ts
+++ b/documentation-site/src/data/demos.ts
@@ -16,21 +16,21 @@ export const demos: Demo[] = [
     slug: 'space-shooter',
     title: 'Space Shooter',
     description:
-      'A complete space shooter with player movement, shooting, enemy spawning and collisions.',
+      'Fly a ship through an asteroid field and shoot it apart, with bloom, a blurred background, sprite-sheet explosions and audio buses.',
     categories: ['games'],
   },
   {
     slug: 'brick-breaker',
     title: 'Brick Breaker',
     description:
-      'A paddle-and-ball brick breaker built entirely from native rigid bodies.',
+      'Break a wall of bricks with a ball and paddle that are native rigid bodies, so every bounce comes from the physics engine.',
     categories: ['games'],
   },
   {
     slug: 'car',
     title: 'Car',
     description:
-      'A drivable car built from rigid bodies, joints, springs and motors.',
+      'Drive a car with working suspension over procedurally generated hills, built from rigid bodies, joints, springs and motors.',
     categories: ['physics', 'games'],
   },
   {
@@ -44,7 +44,7 @@ export const demos: Demo[] = [
     slug: 'ecs',
     title: 'ECS',
     description:
-      'A minimal walkthrough of creating a world, entity, component and system.',
+      'A star circling the screen, built from a world, an entity, its components and one system.',
     categories: ['ecs'],
   },
   {
@@ -65,42 +65,42 @@ export const demos: Demo[] = [
     slug: 'sensors',
     title: 'Sensors and Contacts',
     description:
-      'Trigger zones that detect bodies passing through without blocking them.',
+      'Falling balls pass through sensor zones that tint them on contact, while solid ramps bounce them.',
     categories: ['physics'],
   },
   {
     slug: 'raycasting',
     title: 'Raycasting',
     description:
-      'Casts a ray from a fixed point toward the cursor against static colliders.',
+      'Move the mouse to cast a ray toward the cursor and see where it first hits a collider.',
     categories: ['physics'],
   },
   {
     slug: 'rolling-ball',
     title: 'Rolling Ball',
     description:
-      'A ball rolls over procedurally generated terrain using TerrainCollider and friction.',
+      'Roll and jump a ball over curved terrain, driven by a motor and ground friction.',
     categories: ['physics'],
   },
   {
     slug: 'prismatic-joint',
     title: 'Prismatic Joint (Slider)',
     description:
-      'PrismaticJoint driving a piston, an elevator and an inclined slider.',
+      'A piston, an elevator and an inclined slider, each held to a single sliding axis by a prismatic joint.',
     categories: ['physics'],
   },
   {
     slug: 'revolute-joint',
     title: 'Revolute Joint (Hinge)',
     description:
-      'RevoluteJoint driving a hinged door, a free pendulum and a spinning wheel.',
+      'A limited door hinge, a free pendulum and a spinning wheel, each pinned at one point by a revolute joint.',
     categories: ['physics'],
   },
   {
     slug: 'torque',
     title: 'Torque and Motors',
     description:
-      'Spinning a flywheel by applying torque directly versus an AngularVelocityMotorEcsComponent.',
+      'Hold Space to spin one flywheel by applying torque, while a motor holds the other at a steady speed.',
     categories: ['physics'],
   },
   {
@@ -155,14 +155,14 @@ export const demos: Demo[] = [
     slug: 'nine-slice',
     title: 'Nine-Slice Sprites',
     description:
-      'Compares a stretched sprite to nine-sliced panels that keep crisp corners at any size.',
+      'Compares a stretched sprite to a nine-sliced one that keeps crisp corners at any size.',
     categories: ['rendering'],
   },
   {
     slug: 'context-loss',
     title: 'Context Loss',
     description:
-      'Losing and restoring the WebGL context without reloading the page.',
+      'Click to lose the WebGL context, and watch the engine rebuild its GPU resources when it comes back.',
     categories: ['rendering'],
   },
   {
@@ -176,28 +176,28 @@ export const demos: Demo[] = [
     slug: 'texture-filtering',
     title: 'Texture Filtering',
     description:
-      'Nearest-neighbor versus linear texture filtering side by side.',
+      'The same pixel-art texture drawn with nearest-neighbor filtering (crisp pixels) and linear filtering (smooth blur).',
     categories: ['rendering'],
   },
   {
     slug: 'text',
     title: 'Text Rendering',
     description:
-      'MSDF text rendering: alignment, line height, live reflow, rich text tags and outline/shadow effects.',
+      'Type your own text and change its size, wrapping, alignment, line height, outline and glow while it redraws live.',
     categories: ['rendering'],
   },
   {
     slug: 'ui-anchors',
     title: 'UI Anchors',
     description:
-      'An interactive playground for every UiAnchor preset and its position/size behavior.',
+      'Panels pinned to corners and edges of the canvas, plus one panel whose anchor, position and size you can change live.',
     categories: ['ui'],
   },
   {
     slug: 'ui-nested-resize',
     title: 'UI Nested Resize',
     description:
-      'A moving, resizing window with four levels of nested anchored children.',
+      'A window that moves and resizes on its own while its nested title bar, controls and corner tag follow through their anchors.',
     categories: ['ui'],
   },
   {
@@ -211,7 +211,7 @@ export const demos: Demo[] = [
     slug: 'ui-button',
     title: 'UI Buttons',
     description:
-      'Buttons with hover, click and keyboard/gamepad focus navigation.',
+      'Three buttons you can click, or move focus between with the keyboard, showing hover, press and focus states.',
     categories: ['ui'],
   },
   {
@@ -239,7 +239,7 @@ export const demos: Demo[] = [
     slug: 'ui-slider',
     title: 'UI Slider',
     description:
-      'A draggable slider whose whole track acts as the drag surface.',
+      "Drag a slider's handle, or click anywhere on its track, to set a value shown live in a label.",
     categories: ['ui'],
   },
   {
@@ -267,14 +267,14 @@ export const demos: Demo[] = [
     slug: 'layout-groups',
     title: 'UI Layout Groups',
     description:
-      'Vertical, horizontal and grid layout groups that arrange UI automatically.',
+      'Four panels arranged by vertical, horizontal and grid layout groups, with no hand-placed positions or sizes.',
     categories: ['ui'],
   },
   {
     slug: 'ui-canvas-group',
     title: 'UI Canvas Group',
     description:
-      'A CanvasGroup fades and disables an entire nested UI subtree at once.',
+      'One canvas group fades and disables a whole nested modal, including a button inside it, with a single toggle.',
     categories: ['ui'],
   },
   {
diff --git a/documentation-site/src/hooks/useDemoBackLink.ts b/documentation-site/src/hooks/useDemoBackLink.ts
new file mode 100644
index 000000000..0617142f3
--- /dev/null
+++ b/documentation-site/src/hooks/useDemoBackLink.ts
@@ -0,0 +1,29 @@
+import { useLocation } from '@docusaurus/router';
+import { demoCategories } from '@site/src/data/demo-categories';
+
+interface DemoBackLink {
+  to: string;
+  label: string;
+}
+
+/**
+ * Where a demo page's back link goes. The category page a demo was opened
+ * from is passed as a `from` query param (see `DemoCard`), so the link
+ * returns to that category instead of the full demo catalogue.
+ */
+export const useDemoBackLink = (): DemoBackLink => {
+  const location = useLocation();
+  const fromCategory = demoCategories.find(
+    (category) =>
+      category.slug === new URLSearchParams(location.search).get('from'),
+  );
+
+  if (fromCategory) {
+    return {
+      to: `/demos/category/${fromCategory.slug}`,
+      label: `← Back to ${fromCategory.title}`,
+    };
+  }
+
+  return { to: '/demos', label: '← All demos' };
+};
diff --git a/documentation-site/src/hooks/usePreventPageScrollKeys.ts b/documentation-site/src/hooks/usePreventPageScrollKeys.ts
new file mode 100644
index 000000000..388b93c73
--- /dev/null
+++ b/documentation-site/src/hooks/usePreventPageScrollKeys.ts
@@ -0,0 +1,41 @@
+import { RefObject, useEffect } from 'react';
+
+const pageScrollKeys = new Set([
+  'ArrowUp',
+  'ArrowDown',
+  'ArrowLeft',
+  'ArrowRight',
+  ' ',
+  'PageUp',
+  'PageDown',
+]);
+
+/**
+ * Stops the keys that scroll the page from scrolling it while `elementRef`
+ * has focus, so playing a demo with the arrow keys or space doesn't move
+ * the page. The engine's keyboard input listens on the whole page, so the
+ * game still receives the keys.
+ */
+export const usePreventPageScrollKeys = (
+  elementRef: RefObject<HTMLElement | null>,
+): void => {
+  useEffect(() => {
+    const element = elementRef.current;
+
+    if (!element) {
+      return undefined;
+    }
+
+    const handleKeyDown = (event: KeyboardEvent): void => {
+      if (pageScrollKeys.has(event.key)) {
+        event.preventDefault();
+      }
+    };
+
+    element.addEventListener('keydown', handleKeyDown);
+
+    return () => {
+      element.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [elementRef]);
+};
diff --git a/documentation-site/src/pages/demos/_index.module.css b/documentation-site/src/pages/demos/_index.module.css
index 6c0f4c315..47d2afd7a 100644
--- a/documentation-site/src/pages/demos/_index.module.css
+++ b/documentation-site/src/pages/demos/_index.module.css
@@ -1,5 +1,14 @@
 .container {
-  margin: 50px;
+  width: 100%;
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 2.5rem 1.5rem 4rem;
+}
+
+.intro {
+  max-width: 48rem;
+  color: var(--text-muted-color);
+  font-size: 1.15rem;
 }
 
 .categoryGrid,
diff --git a/documentation-site/src/pages/demos/brick-breaker/index.tsx b/documentation-site/src/pages/demos/brick-breaker/index.tsx
index 583e369a1..2bf5dd004 100644
--- a/documentation-site/src/pages/demos/brick-breaker/index.tsx
+++ b/documentation-site/src/pages/demos/brick-breaker/index.tsx
@@ -17,102 +17,177 @@ import brickComponentCode from '!!raw-loader!./_brick.component';
 import brickSystemCode from '!!raw-loader!./_brick.system';
 import brickShaderCode from '!!raw-loader!./_brick.shader';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function BrickBreaker(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Brick Breaker Demo',
-        description: 'A demo showcasing a simple brick breaker game.',
-      }}
-      header="Brick Breaker"
-      blurb="This demo showcases a brick breaker game built using the Forge Game Engine. A paddle, ball and grid of bricks are all native rigid bodies, so the ball bounces off the walls, paddle and bricks using the engine's built-in collision detection and resolution rather than any custom bounce logic. Break all the bricks and a fresh grid spawns in to keep the game going."
+    <DemoPage
+      slug="brick-breaker"
       createGame={createBrickBreakerGame}
-      codeFiles={[
+      controls={[
+        { inputs: ['←', 'A'], action: 'Move left' },
+        { inputs: ['→', 'D'], action: 'Move right' },
         {
-          name: 'game.ts',
-          content: gameCode,
-        },
-        {
-          name: 'create-background.ts',
-          content: createBackgroundCode,
-        },
-        {
-          name: 'background.component.ts',
-          content: backgroundComponentCode,
-        },
-        {
-          name: 'background.system.ts',
-          content: backgroundSystemCode,
-        },
-        {
-          name: 'background.shader.ts',
-          content: backgroundShaderCode,
-        },
-        {
-          name: 'ball.component.ts',
-          content: ballComponentCode,
-        },
-        {
-          name: 'ball.system.ts',
-          content: ballSystemCode,
-        },
-        {
-          name: 'create-ball.ts',
-          content: createBallCode,
-        },
-        {
-          name: 'create-boundaries.ts',
-          content: createBoundariesCode,
+          inputs: [
+            { device: 'gamepad', label: 'Left stick' },
+            { device: 'gamepad', label: 'D-pad' },
+          ],
+          action: 'Move',
         },
+      ]}
+      highlights={[
         {
-          name: 'create-bricks.ts',
-          content: createBricksCode,
+          text: "The ball, paddle, walls and bricks are all physics bodies, so every bounce comes from the engine's collision resolution, not custom bounce code.",
+          file: 'create-ball.ts',
         },
         {
-          name: 'brick.component.ts',
-          content: brickComponentCode,
+          text: "The ball's contacts list which bricks it touched this tick, and the ball system removes them.",
+          file: 'ball.system.ts',
         },
         {
-          name: 'brick.system.ts',
-          content: brickSystemCode,
+          text: 'When the last brick breaks, a fresh grid spawns so the game keeps going.',
+          file: 'create-bricks.ts',
         },
         {
-          name: 'brick.shader.ts',
-          content: brickShaderCode,
+          text: 'Each brick is drawn with a custom fragment shader that adds a gloss and a moving sheen.',
+          file: 'brick.shader.ts',
         },
         {
-          name: 'create-paddle.ts',
-          content: createPaddleCode,
+          text: 'The animated backdrop is a shader on its own camera and render layer, so it always draws behind the game.',
+          file: 'create-background.ts',
         },
+      ]}
+      docLinks={[
+        { label: 'Rigid bodies', to: '/docs/docs/physics/rigid-bodies' },
+        { label: 'Collisions', to: '/docs/docs/physics/collisions' },
         {
-          name: 'paddle.component.ts',
-          content: paddleComponentCode,
+          label: 'Material uniforms',
+          to: '/docs/docs/rendering/material-uniforms',
         },
-        {
-          name: 'paddle.system.ts',
-          content: paddleSystemCode,
+        { label: 'Input actions', to: '/docs/docs/input/actions' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the cameras, inputs and scene, and registers every system in order.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Play area',
+          files: [
+            {
+              name: 'create-boundaries.ts',
+              summary:
+                'Builds the top and side walls and returns the play area they bound.',
+              content: createBoundariesCode,
+            },
+          ],
+        },
+        {
+          title: 'Paddle',
+          files: [
+            {
+              name: 'create-paddle.ts',
+              summary:
+                'Creates the paddle sprite and collider near the bottom of the play area.',
+              content: createPaddleCode,
+            },
+            {
+              name: 'paddle.component.ts',
+              summary: "The paddle's speed and how far it can move each way.",
+              content: paddleComponentCode,
+            },
+            {
+              name: 'paddle.system.ts',
+              summary:
+                'Moves the paddle with the input axis, clamped to the walls.',
+              content: paddleSystemCode,
+            },
+          ],
+        },
+        {
+          title: 'Ball',
+          files: [
+            {
+              name: 'create-ball.ts',
+              summary:
+                'Creates the ball as a bouncy rigid body and launches it at the bricks.',
+              content: createBallCode,
+            },
+            {
+              name: 'ball.component.ts',
+              summary: "The ball's launch speed and start position.",
+              content: ballComponentCode,
+            },
+            {
+              name: 'ball.system.ts',
+              summary:
+                'Breaks bricks the ball touches and relaunches it after a miss.',
+              content: ballSystemCode,
+            },
+          ],
+        },
+        {
+          title: 'Bricks',
+          files: [
+            {
+              name: 'create-bricks.ts',
+              summary:
+                'Lays out the brick grid and respawns it once every brick is gone.',
+              content: createBricksCode,
+            },
+            {
+              name: 'brick.component.ts',
+              summary: 'A tag that marks an entity as a brick.',
+              content: brickComponentCode,
+            },
+            {
+              name: 'brick.system.ts',
+              summary: "Feeds the current time to every brick's shader.",
+              content: brickSystemCode,
+            },
+            {
+              name: 'brick.shader.ts',
+              summary:
+                'A fragment shader that adds a gloss and a sweeping sheen to bricks.',
+              content: brickShaderCode,
+            },
+          ],
+        },
+        {
+          title: 'Background',
+          files: [
+            {
+              name: 'create-background.ts',
+              summary:
+                'Creates a full-screen sprite drawn with the background shader.',
+              content: createBackgroundCode,
+            },
+            {
+              name: 'background.component.ts',
+              summary: 'A tag that marks the background entity.',
+              content: backgroundComponentCode,
+            },
+            {
+              name: 'background.system.ts',
+              summary: "Feeds the current time to the background's shader.",
+              content: backgroundSystemCode,
+            },
+            {
+              name: 'background.shader.ts',
+              summary:
+                'A slowly drifting blue-to-black gradient with a soft vignette.',
+              content: backgroundShaderCode,
+            },
+          ],
         },
       ]}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="A" />}
-            text="Left"
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="D" />}
-            text="Right"
-          />
-          <InteractionInstruction
-            displayElement={<span>🎮</span>}
-            text="Move with left stick or D-pad"
-          />
-        </>
-      }
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/car/_air-control.component.ts b/documentation-site/src/pages/demos/car/_air-control.component.ts
index b323fa748..0d9d05f06 100644
--- a/documentation-site/src/pages/demos/car/_air-control.component.ts
+++ b/documentation-site/src/pages/demos/car/_air-control.component.ts
@@ -3,26 +3,9 @@ import { Axis1dAction } from '@forge-game-engine/forge/input';
 import { GroundContactEcsComponent } from './_ground-contact.component';
 
 /**
- * Marks the chassis for mid-air pitch control:
- * `createAirControlEcsSystem` drives the chassis's angular velocity
- * towards a target proportional to `throttleInput` (the same
- * targetVelocity/maxTorque approach `AngularVelocityMotorEcsComponent` uses
- * for the wheels) whenever both `frontWheelGroundContact` and
- * `rearWheelGroundContact` report their wheel touching no ground - gas
- * pitches the nose up and back, brake pitches it down and forward, the same
- * "tilt in the air" control the genre is named for. Driving towards a
- * target angular *velocity*, rather than just applying a constant torque,
- * gives the player direct, bounded control of the rotation rate: releasing
- * the input targets zero rotation and actively cancels existing spin
- * (within `maxTorque`) instead of only bleeding off via the chassis's own
- * angular drag, so a bad rotation can be caught and corrected mid-air
- * rather than fought against.
- *
- * `frontWheelGroundContact`/`rearWheelGroundContact` are each the same
- * `GroundContactEcsComponent` object attached to that wheel's own entity
- * (see `createWheel`) - held here by direct reference rather than joined
- * via an ECS query, since this component lives on the chassis's entity, not
- * either wheel's.
+ * Mid-air pitch control. While both wheels are off the ground, the chassis
+ * spins towards `throttleInput * maxAngularSpeed`: gas tilts the nose up,
+ * brake tilts it down, and letting go stops the spin.
  */
 export interface AirControlEcsComponent {
   chassisEntity: number;
diff --git a/documentation-site/src/pages/demos/car/_air-control.system.ts b/documentation-site/src/pages/demos/car/_air-control.system.ts
index d361f4ec3..6b6f39461 100644
--- a/documentation-site/src/pages/demos/car/_air-control.system.ts
+++ b/documentation-site/src/pages/demos/car/_air-control.system.ts
@@ -9,21 +9,9 @@ import { AirControlEcsComponent, airControlId } from './_air-control.component';
 import { isGrounded } from './_ground-contact.component';
 
 /**
- * While a matched entity's `AirControlEcsComponent.frontWheelGroundContact`
- * and `rearWheelGroundContact` both report their wheel touching no ground,
- * drives the chassis's angular velocity towards
- * `throttleInput.value * maxAngularSpeed`, spending no more than `maxTorque`
- * to do so - the same targetVelocity/maxTorque approach
- * `createAngularVelocityMotorEcsSystem` uses for the wheels, applied
- * directly here (rather than via `AngularVelocityMotorEcsComponent`) so it
- * only ever acts while airborne; wired onto the wheels' motors instead, a
- * target of `0` at neutral throttle would fight the chassis's ground-level
- * suspension lean too. Does nothing while grounded, leaving the chassis
- * entirely to the suspension and `ChassisStabilizerEcsComponent`.
- *
- * Must run after `createGroundContactEcsSystem` in the same tick (so it
- * sees this tick's grounded state) and before whatever system integrates
- * velocity into position (`createEulerIntegrationEcsSystem`).
+ * While both wheels are airborne, applies the torque that moves the
+ * chassis's spin towards the throttle's target speed, capped at `maxTorque`.
+ * Does nothing on the ground.
  * @param time - The time instance used to scale torque by the tick's delta
  * time.
  */
diff --git a/documentation-site/src/pages/demos/car/_camera-follow.component.ts b/documentation-site/src/pages/demos/car/_camera-follow.component.ts
index a5710812f..4512806ab 100644
--- a/documentation-site/src/pages/demos/car/_camera-follow.component.ts
+++ b/documentation-site/src/pages/demos/car/_camera-follow.component.ts
@@ -2,39 +2,22 @@ import { createComponentId, EcsWorld } from '@forge-game-engine/forge/ecs';
 import { Vec2, Vector2 } from '@forge-game-engine/forge/math';
 
 /**
- * Smoothly moves this entity's `PositionEcsComponent` towards `targetEntity`'s
- * current position (plus `offset`), via `smoothDampVector2`.
- * `createCameraFollowEcsSystem` applies this every tick; demo-only, since
- * the engine's `CameraEcsComponent` only supports input-driven pan/zoom, not
- * following an arbitrary entity. Used here to keep the car on screen as it
- * drives across a course much wider than the canvas.
+ * Smoothly moves this entity (the camera) towards `targetEntity`, so the
+ * car stays on screen on a course much wider than the canvas.
  */
 export interface CameraFollowEcsComponent {
   targetEntity: number;
 
-  /**
-   * A fixed world-space offset added to `target.position`, e.g. to frame
-   * more of the track ahead of the car than behind it.
-   */
+  /** Added to the target's position, to show more of the road ahead. */
   offset: Vector2;
 
-  /**
-   * The approximate time, in seconds, `smoothDampVector2` takes to catch up
-   * to `target`. Smaller values follow more tightly.
-   */
+  /** Roughly how long, in seconds, the camera takes to catch up. */
   smoothTime: number;
 
-  /**
-   * The maximum speed, in world units/s, the camera may move at while
-   * catching up, so a sudden large jump in `target.position` (a reset, a
-   * hard landing) doesn't whip the camera across the screen.
-   */
+  /** The camera's top speed, in world units per second. */
   maxSpeed: number;
 
-  /**
-   * `smoothDampVector2`'s running velocity state, carried from tick to
-   * tick. Starts at zero.
-   */
+  /** The camera's current velocity, carried between ticks. */
   velocity: Vector2;
 }
 
diff --git a/documentation-site/src/pages/demos/car/_camera-follow.system.ts b/documentation-site/src/pages/demos/car/_camera-follow.system.ts
index 23427f0d5..a16bab012 100644
--- a/documentation-site/src/pages/demos/car/_camera-follow.system.ts
+++ b/documentation-site/src/pages/demos/car/_camera-follow.system.ts
@@ -11,14 +11,8 @@ import {
 } from './_camera-follow.component';
 
 /**
- * Smoothly moves each matched entity's `PositionEcsComponent` towards its
- * `CameraFollowEcsComponent.targetEntity` position every tick, via
- * `smoothDampVector2`. Reads the target's `local` position (it has no
- * parent, so that's its current position whenever this runs) and writes the
- * camera's `local` position, which `createTransformEcsSystem` turns into the
- * `world` position the render system reads.
- * @param time - The time instance used to advance `smoothDampVector2` by
- * the tick's delta time.
+ * Moves each following camera towards its target with `smoothDampVector2`.
+ * @param time - The time instance used to advance the smoothing.
  */
 export const createCameraFollowEcsSystem = (
   time: Time,
diff --git a/documentation-site/src/pages/demos/car/_car-reset.component.ts b/documentation-site/src/pages/demos/car/_car-reset.component.ts
index 34132fdac..30e3ad7e2 100644
--- a/documentation-site/src/pages/demos/car/_car-reset.component.ts
+++ b/documentation-site/src/pages/demos/car/_car-reset.component.ts
@@ -12,10 +12,8 @@ export interface CarResetBody {
 }
 
 /**
- * Teleports every one of `bodies` back to its recorded spawn position,
- * angle, and zero velocity whenever `restartInput` fires, undoing however
- * far the car has driven, flipped, or tumbled down a hill.
- * `createCarResetEcsSystem` applies this every tick.
+ * Moves every body in `bodies` back to its spawn point when
+ * `restartInput` fires.
  */
 export interface CarResetEcsComponent {
   restartInput: TriggerAction;
diff --git a/documentation-site/src/pages/demos/car/_car-reset.system.ts b/documentation-site/src/pages/demos/car/_car-reset.system.ts
index ea2bfad21..f61a4c445 100644
--- a/documentation-site/src/pages/demos/car/_car-reset.system.ts
+++ b/documentation-site/src/pages/demos/car/_car-reset.system.ts
@@ -5,11 +5,8 @@ import { Vec2 } from '@forge-game-engine/forge/math';
 import { CarResetEcsComponent, carResetId } from './_car-reset.component';
 
 /**
- * Teleports every body in each matched entity's `CarResetEcsComponent.bodies`
- * back to its recorded spawn transform, with zero velocity, on the tick
- * `restartInput` fires. Writes each body's `local` pose, so it must run
- * before `createTransformEcsSystem`, so a restart applied this tick is
- * reflected in this same tick's physics step and render.
+ * Moves the car's bodies back to their spawn transforms, at rest, on the
+ * tick the restart input fires.
  */
 export const createCarResetEcsSystem = (): EcsSystem<
   [CarResetEcsComponent]
diff --git a/documentation-site/src/pages/demos/car/_chassis-stabilizer.component.ts b/documentation-site/src/pages/demos/car/_chassis-stabilizer.component.ts
index 7d992da0b..a9c6da114 100644
--- a/documentation-site/src/pages/demos/car/_chassis-stabilizer.component.ts
+++ b/documentation-site/src/pages/demos/car/_chassis-stabilizer.component.ts
@@ -2,30 +2,10 @@ import { createComponentId, EcsWorld } from '@forge-game-engine/forge/ecs';
 import { GroundContactEcsComponent } from './_ground-contact.component';
 
 /**
- * Applies a restoring torque pulling the chassis's rotation back towards
- * zero (`-angle * levelingStiffness`) and resisting its `angularVelocity`
- * (`-angularVelocity * levelingDamping`), via `applyTorque`.
- * `createChassisStabilizerEcsSystem` applies this only while
- * `frontWheelGroundContact` or `rearWheelGroundContact` reports its wheel
- * touching the ground - never while airborne, so it doesn't fight
- * `AirControlEcsComponent`'s deliberate tilt input.
- *
- * `frontWheelGroundContact`/`rearWheelGroundContact` are each the same
- * `GroundContactEcsComponent` object attached to that wheel's own entity
- * (see `createWheel`) - held here by direct reference rather than joined
- * via an ECS query, since this component lives on its own control entity,
- * not either wheel's (or the chassis's own).
- *
- * A real car's suspension keeps the chassis roughly level through its
- * control-arm geometry, not just spring force; the chassis here hangs from
- * only two independently-solved `LinearSpring`/`LinearDamper` pairs (see
- * `createCar`), which has no equivalent geometric constraint and lets small
- * disturbances (an uneven landing, a bump straddling two ground segments)
- * accumulate into a persistent tilt over time rather than settling back to
- * level. This is deliberately much weaker than the pitch torque a hard
- * acceleration or brake produces, so the car still visibly leans under
- * throttle - it only pulls the chassis back level once nothing else is
- * actively tipping it.
+ * Gently pulls the chassis back to level while a wheel is on the ground.
+ * Two independent springs alone let small bumps add up into a lasting
+ * tilt. It's much weaker than the lean from accelerating or braking, so
+ * the car still leans.
  */
 export interface ChassisStabilizerEcsComponent {
   chassisEntity: number;
diff --git a/documentation-site/src/pages/demos/car/_chassis-stabilizer.system.ts b/documentation-site/src/pages/demos/car/_chassis-stabilizer.system.ts
index c83d06a7a..0c4715e7f 100644
--- a/documentation-site/src/pages/demos/car/_chassis-stabilizer.system.ts
+++ b/documentation-site/src/pages/demos/car/_chassis-stabilizer.system.ts
@@ -8,15 +8,8 @@ import {
 import { isGrounded } from './_ground-contact.component';
 
 /**
- * While a matched entity's `ChassisStabilizerEcsComponent.frontWheelGroundContact`
- * or `rearWheelGroundContact` reports its wheel touching the ground, applies
- * the restoring torque to the chassis every tick, via `applyTorque`. Does
- * nothing while both wheels are airborne, leaving the chassis entirely to
- * `AirControlEcsComponent`'s deliberate tilt input.
- *
- * Must run after `createGroundContactEcsSystem` in the same tick (so it
- * sees this tick's grounded state) and before whatever system integrates
- * velocity into position (`createEulerIntegrationEcsSystem`).
+ * Applies a spring-like torque towards level while either wheel is on the
+ * ground. Does nothing in the air, where air control takes over.
  * @param time - The time instance used to scale the torque by the tick's
  * delta time.
  */
diff --git a/documentation-site/src/pages/demos/car/_create-car.ts b/documentation-site/src/pages/demos/car/_create-car.ts
index 491201025..892ba3627 100644
--- a/documentation-site/src/pages/demos/car/_create-car.ts
+++ b/documentation-site/src/pages/demos/car/_create-car.ts
@@ -36,208 +36,54 @@ import { addWheelDriveComponent } from './_wheel-drive.component';
 
 const gravity = { x: 0, y: -600 };
 
+// The chassis is the heaviest body in the car, so it has enough rotational
+// inertia to absorb the wheels' drive torque instead of flipping forward.
 const chassisWidth = 450;
 const chassisHeight = 150;
-
-// With the wheel/upright mass this rig needs for stable joints (see
-// `uprightDensity` below), a chassis this light ends up the *lightest*
-// individual body in the car - `chassisWidth * chassisHeight *
-// chassisDensity` is only ~23,600 against ~15,700 per wheel and ~16,100 per
-// upright, i.e. under a third of the car's total mass, when in a real car
-// the body (chassis + engine) dwarfs the wheels. A chassis that light has
-// little rotational inertia to resist the torque the drive wheels'
-// ground-friction reaction transmits back through the suspension anchors
-// (see `createWheelMount`'s comment on that coupling) - accelerating hard,
-// especially uphill, could tip it into an uncontrolled forward pitch
-// (front digging in, the opposite of the intended throttle-lean) that then
-// only compounded once it went airborne. Raising `chassisDensity` so the
-// chassis is comfortably the heaviest single body (now ~56% of total mass)
-// gives it enough of its own rotational inertia to absorb that reaction
-// smoothly instead of snapping into it - confirmed empirically (accelerate
-// from a stop, sustain it uphill, brake hard) that this removes the
-// unwanted forward pitch while still leaving the deliberately weaker
-// stoppie-under-hard-braking-at-speed rotation clearly intact, and barely
-// changes resting suspension sag.
 const chassisDensity = 0.5;
 
 const wheelRadius = 100;
 const wheelDensity = 0.2;
-
-// Slightly below the wheel-ground friction a bare tire/asphalt pairing
-// would use (`1`, still the historical default here) - the peak transient
-// slip right as full throttle is first requested (before the wheel's spin
-// catches up to the car's speed) briefly demands close to this much
-// friction force at the contact patch, and with `chassisDensity` this low
-// used to translate a chunk of that force into unwanted chassis rotation
-// via the tilted suspension anchors. A little less peak grip there,
-// combined with the heavier chassis above, was enough (empirically) to
-// keep that transient from reaching the chassis at all, without making the
-// car noticeably harder to accelerate or climb with once rolling.
 const wheelFriction = 1;
 
-// The wheel doesn't mount to the chassis directly. A single linear spring
-// only constrains a wheel's *distance* from its anchor, leaving it free to
-// swing around that anchor like a pendulum - and a plain revolute joint or
-// prismatic joint wired straight to the wheel isn't right either: a
-// revolute joint would pin the wheel rigidly in place (no suspension travel
-// at all), and a prismatic joint locks the two bodies' *relative rotation*
-// (it captures a referenceAngle and holds it), which would lock the
-// wheel's spin to the chassis and make driving impossible.
-//
-// Instead each wheel gets a small intermediate "upright" body (a real car's
-// wheel hub/knuckle) invisible and non-colliding (no
-// `ColliderEcsComponent`), connected two different ways:
-//  - A prismatic joint pins the upright to the chassis, free to slide only
-//    along `suspensionAxis` (in the chassis's local space) - this is the
-//    suspension's travel, and it's fine that the joint locks the upright's
-//    rotation to the chassis's, since the upright itself never needs to
-//    spin.
-//  - A revolute joint pins the wheel's position to the upright (coincident
-//    centers) while leaving rotation completely free, so the wheel can
-//    still spin for driving.
-// A linear spring/damper pair along the same axis, between the chassis and
-// the upright, then provides the suspension's actual force. Unlike a
-// spring alone, both joints are hard, warm-started constraints (solved
-// every tick, the same as collision contacts) with no lateral give of
-// their own - so the wheel only ever moves along `suspensionAxis` relative
-// to the chassis, no swinging.
-// A tiny, near-massless upright (relative to the wheel and chassis it sits
-// between) makes both joint solvers badly ill-conditioned: resolving a
-// wheel-ground collision impulse through a light body sandwiched between
-// two much heavier ones (the wheel at one joint, the chassis at the other)
-// blows up within a couple of iterations. Keeping the upright's mass close
-// to the wheel's (`wheelRadius * wheelRadius * Math.PI * wheelDensity`,
-// currently ~15,700) keeps both joints' effective mass ratios reasonable -
-// `uprightDensity` has to scale with `wheelRadius`/`wheelDensity` to hold
-// that, since the upright's own radius stays small and unnoticeable.
+// Each wheel hangs from a small, invisible "upright" (a wheel hub). Its mass
+// is kept close to the wheel's: a near-massless body between two heavy ones
+// makes the joint solvers unstable.
 const uprightRadius = 8;
 const uprightDensity = 80;
 
-// Anchors are in the chassis's local space: roughly at the bottom corners,
-// inset a bit so the wheels sit under the body rather than past its edges.
+// Suspension anchors, in the chassis's local space.
 const frontAnchor = { x: chassisWidth / 2 - 115, y: -chassisHeight / 2 };
 const rearAnchor = { x: -(chassisWidth / 2 - 115), y: -chassisHeight / 2 };
 
-// Each wheel is constrained (via its mount's prismatic joint - see
-// `createWheelMount`) to slide only along this axis relative to its
-// anchor, so tilting it away from straight-up/down carries the wheel
-// itself further out from the chassis than its anchor: the line connecting
-// each anchor to its wheel splays outward into a trapezoid rather than a
-// rectangle, like a monster truck's lifted suspension. This also means an
-// impact that's perpendicular to the chassis (hitting a wall or ledge
-// face-on) now has a component along the suspension axis for the spring to
-// absorb, instead of landing entirely on the joint's hard, unsprung
-// constraint.
+// The suspension axes splay outwards like a monster truck's, so a head-on
+// impact is partly absorbed by the spring instead of the rigid joint.
 const frontSuspensionAxis = Vec2.rotate(Vec2.up, degreesToRadians(35));
 const rearSuspensionAxis = Vec2.rotate(Vec2.up, degreesToRadians(-35));
 
-// How far below each anchor a wheel starts, on top of the anchor's own
-// offset. Since `addLinearSpringComponent` defaults `restLength` to the
-// anchors' distance at attach time, this becomes the suspension's rest
-// length, and starting the wheel slightly higher than that (see
-// `wheelSpawnDrop` in `createCar`) lets the car visibly settle onto its
-// suspension as soon as the demo starts, the same way the Linear Spring and
-// Damper demo's wheels do. Kept just large enough that the wheels tuck in
-// close under the chassis (rather than dangling below it with an
-// unrealistic gap) while still leaving several times the equilibrium sag
-// of margin, so the wheel never has to cross (or come numerically close
-// to) the chassis anchor itself, where `createLinearSpringEcsSystem`'s
-// direction normalization becomes unstable as the anchor-to-wheel distance
-// approaches zero.
+// How far below its anchor a wheel starts. This becomes the springs' rest
+// length.
 const wheelDropHeight = 25;
 
-// Chosen so the car's weight compresses each suspension by a small fraction
-// of `wheelDropHeight` at rest (leaving visible, but bounded, suspension
-// travel) rather than anywhere close to all the way to the chassis anchor.
-// Kept well below the stiffness a spring-only mount would want: the
-// prismatic/revolute joint pair already hard-constrains everything but
-// the vertical travel every tick, so a stiffer spring on top of
-// that mostly ends up fighting the joints instead of damping out - a wheel
-// slamming into the ground can end up launching the whole car into the air
-// instead of just compressing the suspension.
-//
-// Being stable *at rest* isn't enough to verify this against: with
-// `frontSuspensionAxis`/`rearSuspensionAxis` tilted rather than vertical,
-// each wheel's ground-friction reaction force has a component along that
-// wheel's own axis, so accelerating or braking couples horizontal force
-// into each suspension corner's loading, not just vertical weight. The two
-// corners have no shared geometry (no anti-roll bar, no rigid axle) tying
-// their loading together, only independent springs - so under hard
-// driving torque this coupling is enough for one corner to unload faster
-// than the other can compensate, letting that wheel lift off entirely and
-// the chassis pitch hard, without player input, while still grounded. Raising
-// stiffness to shrink the *resting* sag (as this was previously tuned to
-// do) only pushes that dynamic imbalance further out of the range this
-// rig's independent-spring, no-shared-axle suspension can absorb - the
-// resting sag it leaves is a real trade-off, not a leftover to tune away.
-// Verify empirically against *driving* stability (accelerate from a stop,
-// sustain it, brake hard), not just resting stability, before changing
-// this.
+// Soft enough that the joints, not the spring, hold the wheel in line. A
+// stiffer spring fights the joints and can launch the car on hard landings.
 const suspensionStiffness = 1_000_000;
 const suspensionDamping = 165_000;
 
-// An engine is meant to feel overpowered enough to punch
-// through bumps and keep climbing rather than stalling on them.
-// `motorMaxTorque` is scaled up to match the car's current total mass:
-// raising `uprightDensity` to fix the wheel-mount mass ratio (see its
-// comment above) added a lot of mass that wasn't here when this was last
-// tuned - each upright went from ~1,200 to ~16,000, roughly a 50% increase
-// in the whole car's mass - and without a matching torque increase the
-// drivetrain no longer had enough force to meaningfully accelerate it.
-// Confirmed empirically that the car was still torque-limited (not just
-// grip-limited) at that scaled-up value - doubling it again visibly sped up
-// both the wheels' own spin-up and the chassis's acceleration, rather than
-// just wasting the extra torque as more wheel spin, so it was raised
-// further. Tested up to 3x this value too: that made launches snappier
-// still, but also made hard braking's chassis dive noticeably harder
-// (pushing back towards the exaggerated flip a previous fix addressed) for
-// only a marginal further gain in sustained speed - this is the point
-// past which more torque stops being "more power" and starts being "less
-// control."
-//
-// Raising `chassisDensity` (see its comment above, fixing an unwanted
-// forward-pitch-under-throttle bug) added roughly another 66% to the car's
-// total mass on top of that - scaled up again by the same ratio to keep
-// the previously-tuned acceleration feel rather than let the extra weight
-// quietly turn "overpowered" back into "sluggish."
-//
-// `maxWheelSpeed` is deliberately far higher than the car could ever
-// actually roll at - `WheelDriveEcsComponent.maxSlipAngularSpeed` is what
-// actually keeps a wheel grounded in reality (see its comment), by
-// clamping the target this produces to a bounded slip band around the
-// wheel's *current* rolling speed. That clamp is what matters; this is
-// just "go as fast as grip allows", not a speed the wheel is meant to
-// reach unassisted.
+// More torque than the tires can use, so grip (friction) is what limits
+// acceleration. `maxWheelSpeed` means "as fast as grip allows";
+// `maxSlipAngularSpeed` stops an airborne wheel from spinning up uselessly.
 const motorMaxTorque = 25_500_000_000;
 const maxWheelSpeed = 350;
-
-// How far past a wheel's current rolling speed its target is allowed to
-// stray (see `WheelDriveEcsComponent.maxSlipAngularSpeed`) - generous
-// enough for a deliberate wheel spin launch from a stop, bounded enough that
-// a wheel briefly unloaded by the chassis's throttle-lean can't run away to
-// `maxWheelSpeed` and waste torque spinning uselessly fast instead of
-// quickly regaining grip once it lands.
 const maxSlipAngularSpeed = 6;
 
-// See `ChassisStabilizerEcsComponent` for why this exists. Strong enough to
-// pull the chassis back to (roughly) level within a second or two of
-// nothing else disturbing it, but still far weaker than the pitch torque a
-// hard acceleration or brake produces, so the car still visibly leans under
-// throttle.
+// Pulls the chassis back to level on the ground, but far weaker than the
+// lean from accelerating or braking.
 const chassisLevelingStiffness = 300_000_000;
 const chassisLevelingDamping = 40_000_000;
 
-// The chassis's target angular speed at full throttle while airborne, and
-// the torque budget `AirControlEcsComponent` spends chasing it - the
-// classic "tilt in mid-air" control, gas pitching the nose
-// up and back, brake pitching it down and forward. Targeting a speed
-// (rather than just applying a constant torque) gives the player direct,
-// bounded control: releasing the input targets zero rotation and actively
-// cancels existing spin instead of coasting on whatever momentum was built
-// up. `airControlMaxTorque` is high enough (matching the chassis's
-// `chassisDensity`-driven moment of inertia) to reach `airControlMaxAngularSpeed`
-// within a few tenths of a second, so input reads as immediate rather than
-// a slow wind-up.
+// Mid-air pitch control: the chassis's target spin speed at full throttle,
+// and the torque spent reaching it.
 const airControlMaxAngularSpeed = 3.5;
 const airControlMaxTorque = 8_000_000_000;
 
@@ -247,13 +93,8 @@ interface CarSprites {
 }
 
 /**
- * A driven wheel's entity id alongside the `GroundContactEcsComponent`
- * tracking its own grounded state - `createWheel` attaches the latter
- * directly to the wheel's entity (so `WheelDriveEcsSystem` can query it
- * jointly), and returns it too so `createCar` can hand the same object by
- * reference to `AirControlEcsComponent`/`ChassisStabilizerEcsComponent`,
- * which live on the chassis's control entity and need to read both wheels'
- * grounded state.
+ * A wheel's entity and its ground contact, which the chassis's stabilizer
+ * and air control read to know whether the car is airborne.
  */
 interface Wheel {
   entity: number;
@@ -299,6 +140,9 @@ async function loadCarSprites(
   };
 }
 
+/**
+ * Creates a motor-driven wheel that tracks what it's touching.
+ */
 function createWheel(
   world: EcsWorld,
   sprite: SpriteEcsComponent,
@@ -348,21 +192,16 @@ function createWheel(
 }
 
 /**
- * Mounts `wheelEntity` to `chassisEntity` at `chassisAnchor` through an
- * intermediate "upright" body (see the module doc comment above for why:
- * a prismatic joint constrains the upright to slide only along
- * `suspensionAxis` relative to the chassis, a revolute joint pins the wheel
- * to that upright with its rotation left free, and a linear spring/
- * damper pair along the same axis supplies the suspension force).
- * @param world - The ECS world to add the mount's entities to.
- * @param chassisEntity - The chassis the wheel mounts to.
- * @param wheelEntity - The wheel being mounted.
- * @param chassisAnchor - Where on the chassis (in its local space) the
- * upright's prismatic joint and the spring/damper attach.
- * @param uprightPosition - The upright's initial world-space position,
- * directly below `chassisAnchor` by the suspension's rest length.
- * @returns The upright's entity id, so it can be included alongside the
- * chassis and wheel in `CarResetEcsComponent.bodies`.
+ * Mounts a wheel to the chassis through an invisible upright:
+ * - a prismatic joint lets the upright slide only along `suspensionAxis`,
+ * - a revolute joint pins the wheel to the upright but leaves it free to
+ *   spin,
+ * - a spring and damper along the same axis are the suspension.
+ *
+ * Joining the wheel to the chassis directly doesn't work: a revolute joint
+ * alone has no suspension travel, and a prismatic joint alone would stop
+ * the wheel from spinning.
+ * @returns The upright's entity, so the car reset can move it too.
  */
 function createWheelMount(
   world: EcsWorld,
@@ -423,24 +262,16 @@ function createWheelMount(
 }
 
 /**
- * Builds a car: a chassis with two wheels mounted
- * beneath it (see `createWheelMount`), each driven by an
- * `AngularVelocityMotorEcsComponent` whose target speed tracks
- * `throttleInput`. The mount constrains a wheel to only slide vertically
- * relative to the chassis - it's the linear spring/damper providing
- * that mount's force (not a rigid frame) that lets the chassis pitch under
- * acceleration and braking, the same "leaning" feel the genre is named for
- * - a light `ChassisStabilizerEcsComponent` only pulls it back level once
- * nothing else is actively tipping it.
+ * Builds the car: a chassis with two motor-driven wheels on spring
+ * suspension, plus the components that keep it level, steer it in mid-air
+ * and reset it.
  * @param world - The ECS world to add the car's entities to.
  * @param renderContext - The render context used to load sprites.
- * @param renderLayer - The render layer the car should be drawn on.
- * @param groundPosition - A point on the ground the car should spawn above.
- * @param throttleInput - Drives both wheels' motors: positive accelerates
- * forward, negative reverses/brakes.
- * @param restartInput - Teleports the car back to its spawn transform when
- * triggered (see `createCarResetEcsSystem`).
- * @returns The chassis's entity id, for the camera to follow.
+ * @param renderLayer - The render layer the car is drawn on.
+ * @param groundPosition - A point on the ground to spawn the car above.
+ * @param throttleInput - Positive drives forward, negative brakes/reverses.
+ * @param restartInput - Moves the car back to its spawn point.
+ * @returns The chassis's entity, for the camera to follow.
  */
 export async function createCar(
   world: EcsWorld,
@@ -452,12 +283,9 @@ export async function createCar(
 ): Promise<number> {
   const sprites = await loadCarSprites(renderContext, renderLayer);
 
-  // Spawn the chassis slightly above its resting ride height so the car
-  // visibly settles onto its suspension as the demo starts, without
-  // starting so high that the initial impact injects a lot of energy into
-  // the springs.
+  // Spawn slightly above ride height so the car visibly settles onto its
+  // suspension.
   const wheelSpawnDrop = wheelDropHeight - 8;
-  // clone: groundPosition is a caller-owned parameter, must not mutate it.
   const chassisPosition = Vec2.add(Vec2.clone(groundPosition), {
     x: 0,
     y: wheelRadius + wheelDropHeight + chassisHeight / 2 + 100,
@@ -484,23 +312,13 @@ export async function createCar(
     restitution: 0.1,
   });
   addRigidBodyComponent(world, chassisEntity, {
-    // Each wheel mount's prismatic joint hard-constrains it against
-    // swinging (see the module doc comment above), so this isn't
-    // compensating for that the way it originally was - it's just a
-    // small amount of drag so any pitch imparted while settling onto the
-    // suspension (or while landing after a jump) damps out over time
-    // instead of persisting indefinitely.
+    // A little drag so pitch from landings dies out over time.
     angularDrag: 0.5,
   });
   addGravityComponent(world, chassisEntity, { amount: gravity });
 
-  // Offset along the same tilted axis each wheel's mount constrains it to
-  // (see `frontSuspensionAxis`/`rearSuspensionAxis`), not straight down, so
-  // the wheel spawns already on its prismatic joint's constraint line
-  // instead of being yanked sideways onto it over the first few frames.
-  // clone: chassisPosition is reused below for the rear wheel too, and
-  // frontSuspensionAxis/rearSuspensionAxis are shared with the joint's
-  // `axis` below - none of these may be mutated in place.
+  // Each wheel spawns on its tilted suspension axis, so the joint doesn't
+  // yank it sideways in the first frames.
   const frontWheelPosition = Vec2.add(
     Vec2.add(
       Vec2.add(Vec2.clone(chassisPosition), frontAnchor),
@@ -516,6 +334,7 @@ export async function createCar(
     { x: 0, y: -wheelRadius },
   );
 
+  // Rear-wheel biased: the front wheel gets half the torque.
   const frontWheel = createWheel(
     world,
     sprites.wheel,
@@ -550,14 +369,8 @@ export async function createCar(
     rearSuspensionAxis,
   );
 
-  // Both live on this one entity so they're easy to find alongside each
-  // other, though neither is queried jointly with the other - each just
-  // holds direct references to `frontWheel.groundContact`/
-  // `rearWheel.groundContact` (see `AirControlEcsComponent`/
-  // `ChassisStabilizerEcsComponent`'s doc comments for why: those
-  // components live on their own control entity, not either wheel's, so an
-  // ECS query can't join them the way `WheelDriveEcsSystem` joins a wheel
-  // with its own `GroundContactEcsComponent`).
+  // Both need to know whether either wheel is on the ground, so they hold
+  // the wheels' ground-contact components directly.
   const chassisControlEntity = world.createEntity();
 
   addChassisStabilizerComponent(world, chassisControlEntity, {
diff --git a/documentation-site/src/pages/demos/car/_create-game.ts b/documentation-site/src/pages/demos/car/_create-game.ts
index 2fbcc0a88..fbc597515 100644
--- a/documentation-site/src/pages/demos/car/_create-game.ts
+++ b/documentation-site/src/pages/demos/car/_create-game.ts
@@ -43,9 +43,7 @@ const renderLayers = {
 export const createCarGame = async (): Promise<Game> => {
   const { game, world, renderContext, time } = createGame('demo-game');
 
-  // `isStatic: true` since this camera's position is driven by
-  // `createCameraFollowEcsSystem` rather than `createCameraEcsSystem`'s
-  // input-driven pan/zoom.
+  // Static: the camera-follow system moves this camera, not pan/zoom input.
   const cameraEntity = createCamera(world, {
     isStatic: true,
     zoom: 0.5,
@@ -80,53 +78,23 @@ export const createCarGame = async (): Promise<Game> => {
   const collisionManifolds: CollisionManifold[] = [];
   const contactConstraints: ContactConstraint[] = [];
 
-  // Each wheel mount chains two joints through its upright (chassis <->
-  // upright via the prismatic joint, upright <-> wheel via the revolute
-  // joint), and both mounts share the chassis body - the single-iteration
-  // default is enough for an isolated joint, but this shared-body chain
-  // needs several more per tick to stay stable at this rig's mass/torque
-  // scale (confirmed empirically: with the default of 1, the chassis
-  // tumbles and the car flies apart within the first second).
+  // Each wheel hangs from two chained joints that share the chassis, which
+  // needs more solver iterations than the default to stay stable.
   const jointIterations = { iterations: 8 };
 
-  // `createCollisionResolutionEcsSystem`'s default `maxBiasSpeed` (3 units/
-  // second) is tuned for Box2D's own meters-scale default (its
-  // `contactPushMaxSpeed` is `3.0 * b2_lengthUnitsPerMeter`) - this course's
-  // world units are pixel-scale instead (`gravity` above is -600, roughly
-  // 60x real-world `g`, and `wheelRadius` alone is 100 units), so a wheel
-  // that lands hard after catching air off a hill can end up tens of units
-  // deep in the terrain, and 3 units/second of correction then takes many
-  // seconds to dig it back out - long enough to read as the wheel being
-  // stuck clipped into the ground rather than momentarily compressed into
-  // it. Scaling the cap up by roughly the same ~60-100x
-  // this course's units are bigger than Box2D's assumed meters (confirmed
-  // empirically: 300 clears a hard landing within a fraction of a second,
-  // matching how quickly the suspension itself settles, without changing
-  // resting behavior on flat ground - the cap only matters once penetration
-  // is already large) restores the "quickly digs itself back out" feel
-  // `maxBiasSpeed` is meant to provide at this course's actual scale.
+  // The default correction speed is tuned for metre-scale worlds. This
+  // world is pixel-scale, so a wheel that lands hard would take seconds to
+  // dig itself out of the ground.
   const collisionResolutionOptions = { maxBiasSpeed: 300 };
 
-  // `createCarResetEcsSystem` may teleport every body back to its spawn
-  // transform, so it runs first, followed by `createTransformEcsSystem`,
-  // which turns every entity's `local` pose into the `world` pose that the
-  // physics and render systems read. `createGroundContactEcsSystem` recomputes
-  // each wheel's grounded state from the wheel's contacts (filled by
-  // narrow-phase, just before it), and
-  // `createWheelDriveEcsSystem` (sets each wheel's motor target from
-  // `throttleInput`, but only requests full speed while that wheel's own
-  // ground contact says it's grounded) / `createChassisStabilizerEcsSystem`
-  // / `createAirControlEcsSystem` must run after it in this same list, so
-  // they see this tick's grounded state rather than last tick's. The
-  // suspension's spring/damper forces run before collision resolution (like
-  // gravity), and the prismatic/revolute joints that hard-constrain each
-  // wheel mount run after it, so they get the "last word" on velocity each
-  // tick. `createContinuousCollisionEcsSystem` runs right after
-  // `createEulerIntegrationEcsSystem`, so it can stop a wheel that this
-  // tick's integration would sink deep into the terrain at the surface
-  // instead. `createCameraFollowEcsSystem` writes the camera's `local` position
-  // after `createTransformEcsSystem` has run, so its smoothed camera
-  // position is rendered from the next tick on.
+  // System order matters:
+  // 1. Reset, then transforms, so a restart shows up this tick.
+  // 2. Ground contact after narrow phase (which fills contacts), and before
+  //    the systems that read it (wheel drive, stabilizer, air control).
+  // 3. Springs and dampers before collision resolution; joints after it, so
+  //    they get the last word on velocity.
+  // 4. Continuous collision right after integration, so a fast wheel stops
+  //    at the ground instead of sinking into it.
   world.addSystem(createCarResetEcsSystem());
   world.addSystem(createTransformEcsSystem());
   world.addSystem(createGravityEcsSystem(time));
diff --git a/documentation-site/src/pages/demos/car/_create-terrain.ts b/documentation-site/src/pages/demos/car/_create-terrain.ts
index 50a414d20..9931e9f25 100644
--- a/documentation-site/src/pages/demos/car/_create-terrain.ts
+++ b/documentation-site/src/pages/demos/car/_create-terrain.ts
@@ -17,69 +17,30 @@ import {
 } from '@forge-game-engine/forge/rendering';
 import { getAssetUrl } from '@site/src/utils/get-asset-url';
 
-// How far apart (in world x) consecutive sampled height points are. Small
-// enough, relative to the wheel radius (see `wheelRadius` in
-// `_create-car.ts`), that a wheel spans more than one of the collider's
-// surface edges at once - deliberately exercising the multi-edge case the
-// old column-based terrain (each column its own `PolygonCollider` entity)
-// couldn't, since `TerrainCollider` resolves a body against every stretch
-// of its surface chain the body actually reaches (see
-// `detectCircleTerrainCollision`/`detectPolygonTerrainCollision`), rather
-// than against one column at a time.
+// Horizontal distance between sampled height points. Smaller than a wheel,
+// so a wheel often touches several surface edges at once.
 const pointSpacing = 60;
 
-// How far the solid slab extends below the lowest sampled point. A single
-// flat bottom edge for the whole course, so this only needs to cover the
-// tallest hill's height *above* the flat launch pad, not the pad's own
-// height (see `TerrainCollider`'s docs: `depth` is measured from the
-// lowest point across the whole collider).
+// How far the solid ground extends below the lowest point.
 const terrainDepth = 500;
 
-// `block_square.png` is a 64x64 rounded, bolted panel; tiled at its native
-// size it reads as a plated floor rather than smearing across the whole
-// course.
 const groundTextureUrl = getAssetUrl('img/physics/block_square.png');
 
-/**
- * How far the flat launch pad the car spawns on extends before the terrain
- * starts climbing, in world units.
- */
+// Length of the flat launch pad the car spawns on.
 const flatStartLength = 400;
 
-/**
- * Total horizontal distance the generated course covers, including the
- * flat launch pad.
- */
 const courseLength = 20000;
 
-/**
- * How far before the flat launch pad the sampled terrain starts, so the car
- * always has solid ground under it even while braking/reversing near the
- * spawn point.
- */
+// Ground behind the spawn point, so the car can reverse off the pad.
 const runoffLength = 500;
 
-/**
- * How far past `flatStartLength` the hills take to ramp up to full
- * amplitude. Without this, `rollingHills`/`climb`/`noise` would switch on
- * abruptly at `flatStartLength`, and since their slope there is nonzero,
- * that would make the very first sampled point a sharp kink (a car arriving
- * at speed would feel a sudden bump rather than easing onto a slope).
- * Smoothstep ramps `rollingHills`/`climb`/`noise` in with a slope of zero at
- * `flatStartLength`, so the ground eases out of the flat pad instead of
- * kinking.
- */
+// Distance over which the hills fade in, so the pad eases into the first
+// slope instead of ending in a kink.
 const hillRampLength = 400;
 
 /**
- * Computes the ground height at `x`: flat for `flatStartLength`, then a mix
- * of two sine waves at different frequencies (rolling hills), a slow upward
- * trend (so the course is a net "climb" rather than just undulating), and
- * small per-point noise so it doesn't read as perfectly periodic - all
- * ramped in smoothly over `hillRampLength` so the transition out of the
- * flat pad has no sudden change in slope.
- * @param x - The world-space x coordinate to sample.
- * @param random - The seeded random source used for per-point noise.
+ * The ground height at `x`: flat for the launch pad, then two sine waves
+ * (rolling hills), a slow climb and a little noise.
  */
 function heightAt(x: number, random: Random): number {
   if (x <= flatStartLength) {
@@ -101,10 +62,7 @@ function heightAt(x: number, random: Random): number {
 }
 
 /**
- * Samples `heightAt` left to right across the whole course, as the
- * terrain's surface points in world coordinates (the terrain entity sits at
- * the origin, unrotated, and its solid slab extends below the points).
- * @param random - The seeded random source used for per-point noise.
+ * Samples `heightAt` across the course, left to right.
  */
 function buildSurfacePoints(random: Random): Vector2[] {
   const points: Vector2[] = [];
@@ -138,17 +96,10 @@ function toCurvePoints(points: readonly Vector2[]): TerrainCurvePoint[] {
 }
 
 /**
- * Builds the course's terrain: a single, continuous `TerrainCollider`
- * following a procedurally generated height profile, starting with a flat
- * launch pad and climbing into gently rolling hills, plus a matching mesh
- * (see `createTerrainMesh`) built from the exact same points, so what's
- * drawn always matches what's touched. The mesh is attached to the terrain
- * entity via `addTerrainMeshComponent`, so `createTerrainRenderEcsSystem`
- * draws it automatically - the caller doesn't need to wire it up itself.
- * @param world - The ECS world to add the terrain entity to.
- * @param renderContext - The render context used to load the ground texture and build the mesh.
- * @param random - The seeded random source used to vary the terrain.
- * @returns A point on the flat launch pad, suitable for spawning the car above.
+ * Builds the course: one `TerrainCollider` for physics and a terrain mesh
+ * for rendering, both from the same points so what you see is what the car
+ * touches.
+ * @returns A point on the launch pad to spawn the car above.
  */
 export async function createTerrain(
   world: EcsWorld,
diff --git a/documentation-site/src/pages/demos/car/_ground-contact.component.ts b/documentation-site/src/pages/demos/car/_ground-contact.component.ts
index 4509b95ca..bf1daa2f1 100644
--- a/documentation-site/src/pages/demos/car/_ground-contact.component.ts
+++ b/documentation-site/src/pages/demos/car/_ground-contact.component.ts
@@ -1,17 +1,8 @@
 import { createComponentId, EcsWorld } from '@forge-game-engine/forge/ecs';
 
 /**
- * Tracks how many static (ground) bodies this entity is currently touching,
- * recomputed every tick by `createGroundContactEcsSystem` from the entity's
- * `ContactsEcsComponent`. A count rather than a boolean so it generalizes to
- * any number of static bodies a wheel might simultaneously touch.
- *
- * Attached directly to the wheel's own entity, so anything else on that
- * same entity (e.g. `WheelDriveEcsComponent`) can query for it jointly.
- * `AirControlEcsComponent`/`ChassisStabilizerEcsComponent` live on a
- * different entity (the chassis) but need to know about *both* wheels, so
- * they instead hold direct references to each wheel's
- * `GroundContactEcsComponent` object.
+ * How many static (ground) bodies this wheel is touching. Updated every
+ * tick by `createGroundContactEcsSystem`.
  */
 export interface GroundContactEcsComponent {
   groundContacts: number;
@@ -21,9 +12,7 @@ export const groundContactId =
   createComponentId<GroundContactEcsComponent>('groundContact');
 
 /**
- * Returns whether `groundContact` currently reports its entity touching no
- * ground.
- * @param groundContact - The ground-contact state to check.
+ * Returns whether the entity is touching the ground.
  */
 export function isGrounded(groundContact: GroundContactEcsComponent): boolean {
   return groundContact.groundContacts > 0;
@@ -31,12 +20,7 @@ export function isGrounded(groundContact: GroundContactEcsComponent): boolean {
 
 /**
  * Attaches a {@link GroundContactEcsComponent} to `entity`.
- * @param world - The ECS world `entity` belongs to.
- * @param entity - The entity to attach the component to.
- * @returns The attached component, so it can be handed to other components
- * that need to read this entity's grounded state (see the class doc
- * comment). `groundContacts` starts at `0`, since it's system-managed
- * state, not configuration.
+ * @returns The component, so the chassis's components can read it too.
  */
 export function addGroundContactComponent(
   world: EcsWorld,
diff --git a/documentation-site/src/pages/demos/car/_ground-contact.system.ts b/documentation-site/src/pages/demos/car/_ground-contact.system.ts
index 7eec3cf18..4ab1289a5 100644
--- a/documentation-site/src/pages/demos/car/_ground-contact.system.ts
+++ b/documentation-site/src/pages/demos/car/_ground-contact.system.ts
@@ -10,13 +10,8 @@ import {
 } from './_ground-contact.component';
 
 /**
- * Recomputes each matched entity's `GroundContactEcsComponent.groundContacts`
- * from its `ContactsEcsComponent`, counting how many of the entities it's
- * touching are static (no `RigidBodyEcsComponent`) bodies. Must run after
- * `createNarrowPhaseEcsSystem`, which fills the contacts, and before any
- * system that reads a `GroundContactEcsComponent` this same tick
- * (`createWheelDriveEcsSystem`, `createChassisStabilizerEcsSystem`,
- * `createAirControlEcsSystem`).
+ * Counts how many static bodies each wheel is touching, from the contacts
+ * the narrow phase found this tick.
  */
 export const createGroundContactEcsSystem = (): EcsSystem<
   [GroundContactEcsComponent, ContactsEcsComponent]
diff --git a/documentation-site/src/pages/demos/car/_wheel-drive.component.ts b/documentation-site/src/pages/demos/car/_wheel-drive.component.ts
index 2498f867d..656087139 100644
--- a/documentation-site/src/pages/demos/car/_wheel-drive.component.ts
+++ b/documentation-site/src/pages/demos/car/_wheel-drive.component.ts
@@ -2,64 +2,31 @@ import { createComponentId, EcsWorld } from '@forge-game-engine/forge/ecs';
 import { Axis1dAction } from '@forge-game-engine/forge/input';
 
 /**
- * Marks an entity as a driven wheel: `createWheelDriveEcsSystem` queries for
- * this alongside the entity's `AngularVelocityMotorEcsComponent` and
- * `GroundContactEcsComponent`, and sets the motor's `targetVelocity` and
- * `maxTorque` from `throttleInput` every tick. There's no engine-provided
- * "steer this motor from an input action" component, since what an axis
- * should drive (a wheel, a turret, a slider) is always game-specific - this
- * component plays that role for the demo.
+ * Drives a wheel's motor from the throttle input.
  */
 export interface WheelDriveEcsComponent {
   throttleInput: Axis1dAction;
 
-  /**
-   * The chassis this wheel belongs to, used to compute the wheel's rolling
-   * angular speed (`-chassisVelocity.x / wheelRadius`) that
-   * `targetVelocity` is clamped around via `maxSlipAngularSpeed` while the
-   * wheel is airborne.
-   */
+  /** The chassis, whose speed tells how fast the wheel should roll. */
   chassisEntity: number;
 
-  /**
-   * This wheel's radius, used for the same rolling-speed conversion as
-   * `chassisBody`.
-   */
   wheelRadius: number;
 
   /**
-   * The wheel's angular speed, in rad/s, at full throttle
-   * (`throttleInput.value` of `1` or `-1`) while grounded. The engine's own
-   * Coulomb friction model (see `resolveCollision`) is what actually caps
-   * how much of this the wheel can turn into real acceleration without
-   * slipping - this is deliberately far higher than the car could ever
-   * really roll at, an "as fast as grip allows" request rather than a speed
-   * the wheel is expected to reach unassisted.
+   * Wheel spin at full throttle, in rad/s. Deliberately unreachable: ground
+   * friction decides how much of it turns into speed.
    */
   maxWheelSpeed: number;
 
   /**
-   * How far past the wheel's current rolling speed `targetVelocity` is
-   * allowed to stray *while airborne*, in rad/s. A grounded wheel's slip is
-   * already correctly limited by ground friction, the same way a real
-   * tire's is - but an airborne wheel has no friction at all, nothing but
-   * its own rotational inertia to resist the motor, so left unclamped it
-   * would accelerate towards `maxWheelSpeed` almost instantly regardless of
-   * whether that speed is at all useful, and be spinning far faster than
-   * the car is actually moving by the time it lands. This bounds that
-   * runaway without limiting how hard a *grounded* wheel can actually
-   * accelerate the car.
+   * In the air, how far the wheel may spin past its rolling speed, in
+   * rad/s. Without it, an airborne wheel spins up uselessly fast.
    */
   maxSlipAngularSpeed: number;
 
   /**
-   * The motor's torque budget, in N·m, while `throttleInput` is nonzero.
-   * `createWheelDriveEcsSystem` drops the motor's actual `maxTorque` to `0`
-   * whenever `throttleInput.value` is exactly `0` instead of driving
-   * `targetVelocity` to `0` at this full budget - the latter would brake the
-   * wheel to a dead stop the instant the player lets go of the controls
-   * (effectively an always-on parking brake), rather than letting it
-   * freewheel and coast downhill under gravity the way an idling car does.
+   * Motor torque while the throttle is held. With no throttle the motor
+   * lets go, so the car coasts instead of parking.
    */
   maxTorque: number;
 }
diff --git a/documentation-site/src/pages/demos/car/_wheel-drive.system.ts b/documentation-site/src/pages/demos/car/_wheel-drive.system.ts
index 2676b241b..323bb9efb 100644
--- a/documentation-site/src/pages/demos/car/_wheel-drive.system.ts
+++ b/documentation-site/src/pages/demos/car/_wheel-drive.system.ts
@@ -13,42 +13,13 @@ import {
 import { WheelDriveEcsComponent, wheelDriveId } from './_wheel-drive.component';
 
 /**
- * Sets each matched entity's `AngularVelocityMotorEcsComponent.targetVelocity`
- * and `maxTorque` from its `WheelDriveEcsComponent.throttleInput` every tick,
- * so `createAngularVelocityMotorEcsSystem` (registered afterwards) drives the
- * wheel towards it.
+ * Sets each wheel motor's target speed and torque from the throttle.
  *
- * The sign is flipped: with this engine's Y-up convention, a wheel rolling
- * without slipping to the right (positive world-space x velocity `V`) spins
- * with angular velocity `-V / radius` (positive angular velocity is
- * counter-clockwise, and the bottom contact point of a wheel moving right
- * traces backwards, i.e. clockwise). So driving the car forward (positive
- * throttle, positive x) needs a *negative* target angular velocity.
- *
- * While the wheel's `GroundContactEcsComponent` reports it touching the
- * ground, the throttle-desired target is used directly - the engine's own
- * friction model (see `createCollisionResolutionEcsSystem`) is what
- * correctly limits how much of that becomes real acceleration versus slip,
- * the same way it would for a real tire. Only while airborne is the target
- * clamped to within `maxSlipAngularSpeed` of the wheel's current rolling
- * speed - see `WheelDriveEcsComponent.maxSlipAngularSpeed` for why an
- * unclamped target would let an airborne wheel run away regardless of
- * `maxWheelSpeed`.
- *
- * `maxTorque` is dropped to `0` whenever `throttleInput.value` is exactly
- * `0`, rather than leaving it at `wheelDrive.maxTorque` and letting
- * `targetVelocity` fall to `0` - at `wheelDrive.maxTorque` (large enough to
- * punch through bumps), driving `targetVelocity` to `0` would brake the
- * wheel to a dead stop the instant the player releases the controls, acting
- * as a permanent parking brake and preventing the car from coasting downhill
- * under gravity. Dropping the torque budget to `0` instead leaves the motor
- * with nothing to push with, so the wheel spins freely at whatever rate
- * rolling contact and gravity give it.
- *
- * Must run after `createGroundContactEcsSystem` in the same tick (so it sees
- * this tick's grounded state) and before `createAngularVelocityMotorEcsSystem`,
- * which itself must run before whatever system integrates velocity into
- * position (`createEulerIntegrationEcsSystem`).
+ * - The sign is flipped: in a Y-up world a wheel rolling right spins
+ *   clockwise, which is a negative angle.
+ * - On the ground the target is used as is; friction limits the grip.
+ * - In the air the target stays close to the wheel's rolling speed.
+ * - With no throttle the torque drops to zero, so the car coasts.
  */
 export const createWheelDriveEcsSystem = (): EcsSystem<
   [
diff --git a/documentation-site/src/pages/demos/car/index.tsx b/documentation-site/src/pages/demos/car/index.tsx
index d48a0e921..a5c84ab2a 100644
--- a/documentation-site/src/pages/demos/car/index.tsx
+++ b/documentation-site/src/pages/demos/car/index.tsx
@@ -17,109 +17,164 @@ import airControlSystemCode from '!!raw-loader!./_air-control.system';
 import groundContactComponentCode from '!!raw-loader!./_ground-contact.component';
 import groundContactSystemCode from '!!raw-loader!./_ground-contact.system';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function Car(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Car Demo',
-        description:
-          'A demo showing how to set up a car with the physics engine: a chassis with two spring-suspended, motor-driven wheels climbing a procedurally generated hill.',
-      }}
-      header="Car"
-      blurb="This demo composes several of the physics engine's existing primitives into a drivable car: the chassis, both wheels, and a small invisible 'upright' body per wheel (a wheel hub/knuckle) are all independent entities with their own RigidBodyEcsComponent, and each wheel is driven by an AngularVelocityMotorEcsComponent (see the Torque and Motors demo). A demo-only GroundContactEcsComponent/system pair, attached to each wheel's own entity, tracks how many static bodies that wheel is touching, recomputed every tick from the wheel's ContactsEcsComponent. While a wheel is grounded, its motor's target speed tracks the throttle input directly, and the engine's own Coulomb friction model - not an artificial clamp - is what correctly limits how much of that becomes real acceleration versus slip, the same way it would for a real tire. Only while a wheel is airborne does WheelDriveEcsSystem clamp its target to a bounded slip band around its current rolling speed (derived from the chassis's own velocity every tick): airborne, a wheel has nothing but its own rotational inertia to resist the motor, so left unclamped it would accelerate towards an arbitrary top speed almost instantly and land spinning far faster than the car is actually moving, burning torque on wheel spin instead of quickly regaining grip. Each wheel mounts to the chassis through its upright: a PrismaticJoint (see the Prismatic Joint demo) constrains the upright to slide only vertically relative to the chassis, a RevoluteJoint (see the Revolute Joint demo) pins the wheel's position to that upright while leaving its rotation completely free to spin, and a LinearSpring/LinearDamper pair (see the Linear Spring and Damper demo) along that same axis supplies the suspension's force. Wiring either joint straight to the wheel wouldn't work - a RevoluteJoint would pin it rigidly in place with no suspension travel, and a PrismaticJoint locks relative rotation, which would lock the wheel's spin to the chassis - so the upright exists specifically to give the wheel a rotation-free attachment point. Unlike a spring-only mount, both joints are hard, iteratively-solved constraints with no lateral give, so the wheel only ever travels along that one axis, no swinging or sideways slop. Because the mount's *force* still comes from a soft spring rather than a rigid frame, accelerating and braking visibly pitches the chassis backward and forward, the 'leaning' feel the genre is named for; a light demo-only ChassisStabilizerEcsComponent nudges the chassis back level once nothing else is actively tipping it, without fighting a deliberate acceleration or brake lean. Each wheel mount's PrismaticJoint axis is also tilted outward rather than straight up/down, so the line from each chassis anchor to its wheel splays into a trapezoid instead of a rectangle, like a monster truck's lifted suspension - besides the visual, this gives an impact that's perpendicular to the chassis (hitting a ledge face-on) a component along the suspension axis for the spring to absorb, rather than landing entirely on the joint's hard, unsprung constraint. The terrain is a single static TerrainCollider following a procedurally generated height profile (see the Terrain guide), and a demo-only camera-follow system (the engine's built-in camera only supports input-driven pan/zoom) keeps the car in view as it drives across a course much wider than the canvas. ChassisStabilizerEcsComponent and AirControlEcsComponent, which both live on the chassis rather than either wheel, hold direct references to both wheels' GroundContactEcsComponent objects to check grounded state - ChassisStabilizerEcsSystem stays out of the way entirely while both wheels are airborne, and in that same situation AirControlEcsSystem instead drives the chassis's angular velocity towards a target proportional to the throttle input (the same targetVelocity/maxTorque approach AngularVelocityMotorEcsComponent uses for the wheels) - gas targets a nose-up-and-back spin, brake targets nose-down-and-forward, and releasing the input targets zero rotation, actively cancelling existing spin rather than just coasting on momentum, the classic mid-air control for lining up a landing. Letting go of the throttle on the ground also drops the driven wheel's motor torque budget to zero rather than braking it to a stop, so the car coasts and freewheels downhill under gravity instead of being held by an invisible parking brake. The hills get steep further along the course - if the car flips or gets stuck, press R to restart."
+    <DemoPage
+      slug="car"
       createGame={createCarGame}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="→" />}
-            text="Accelerate"
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="D" />}
-            text="Accelerate"
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="←" />}
-            text="Brake / Reverse"
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="A" />}
-            text="Brake / Reverse"
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="R" />}
-            text="Restart"
-          />
-        </>
-      }
-      codeFiles={[
+      controls={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          inputs: ['→', 'D'],
+          action: 'Accelerate',
+          detail: 'In the air: tilt back',
         },
         {
-          name: 'create-car.ts',
-          content: createCarCode,
-        },
-        {
-          name: 'create-terrain.ts',
-          content: createTerrainCode,
-        },
-        {
-          name: 'create-inputs.ts',
-          content: createInputsCode,
-        },
-        {
-          name: 'wheel-drive.component.ts',
-          content: wheelDriveComponentCode,
-        },
-        {
-          name: 'wheel-drive.system.ts',
-          content: wheelDriveSystemCode,
-        },
-        {
-          name: 'camera-follow.component.ts',
-          content: cameraFollowComponentCode,
-        },
-        {
-          name: 'camera-follow.system.ts',
-          content: cameraFollowSystemCode,
-        },
-        {
-          name: 'car-reset.component.ts',
-          content: carResetComponentCode,
-        },
-        {
-          name: 'car-reset.system.ts',
-          content: carResetSystemCode,
+          inputs: ['←', 'A'],
+          action: 'Brake / reverse',
+          detail: 'In the air: tilt forward',
         },
+        { inputs: ['R'], action: 'Restart' },
+      ]}
+      highlights={[
         {
-          name: 'chassis-stabilizer.component.ts',
-          content: chassisStabilizerComponentCode,
+          text: 'The chassis and both wheels are separate rigid bodies.',
+          file: 'create-car.ts',
         },
         {
-          name: 'chassis-stabilizer.system.ts',
-          content: chassisStabilizerSystemCode,
+          text: 'Each wheel hangs from a hidden hub: a prismatic joint for suspension travel, a revolute joint so it can spin, and a spring and damper for the bounce.',
+          file: 'create-car.ts',
         },
         {
-          name: 'air-control.component.ts',
-          content: airControlComponentCode,
+          text: 'A motor spins each wheel, and friction with the ground decides how much of that becomes speed.',
+          file: 'wheel-drive.system.ts',
         },
         {
-          name: 'air-control.system.ts',
-          content: airControlSystemCode,
+          text: 'With both wheels off the ground, the throttle tilts the car so you can line up a landing.',
+          file: 'air-control.system.ts',
         },
         {
-          name: 'ground-contact.component.ts',
-          content: groundContactComponentCode,
+          text: 'The hills are a single terrain collider, drawn with a mesh built from the same points.',
+          file: 'create-terrain.ts',
         },
-        {
-          name: 'ground-contact.system.ts',
-          content: groundContactSystemCode,
+      ]}
+      docLinks={[
+        { label: 'Rigid bodies', to: '/docs/docs/physics/rigid-bodies' },
+        { label: 'Joints', to: '/docs/docs/physics/joints' },
+        { label: 'Forces', to: '/docs/docs/physics/forces' },
+        { label: 'Terrain', to: '/docs/docs/physics/terrain' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the camera, terrain and car, and registers every system in the order they run.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-car.ts',
+              summary:
+                'Builds the chassis, wheels and suspension, and the tuning values that make it drive well.',
+              content: createCarCode,
+            },
+            {
+              name: 'create-terrain.ts',
+              summary:
+                'Generates the hills, their collider and the mesh that draws them.',
+              content: createTerrainCode,
+            },
+            {
+              name: 'create-inputs.ts',
+              summary: 'Binds the arrow keys, A/D and R to game actions.',
+              content: createInputsCode,
+            },
+          ],
+        },
+        {
+          title: 'Driving',
+          files: [
+            {
+              name: 'ground-contact.component.ts',
+              summary: 'Stores how many ground bodies a wheel is touching.',
+              content: groundContactComponentCode,
+            },
+            {
+              name: 'ground-contact.system.ts',
+              summary: "Counts each wheel's ground contacts every tick.",
+              content: groundContactSystemCode,
+            },
+            {
+              name: 'wheel-drive.component.ts',
+              summary:
+                "Settings for driving a wheel's motor from the throttle.",
+              content: wheelDriveComponentCode,
+            },
+            {
+              name: 'wheel-drive.system.ts',
+              summary:
+                "Sets each wheel motor's speed and torque from the throttle.",
+              content: wheelDriveSystemCode,
+            },
+          ],
+        },
+        {
+          title: 'Balance',
+          files: [
+            {
+              name: 'chassis-stabilizer.component.ts',
+              summary: 'Settings for pulling the chassis back to level.',
+              content: chassisStabilizerComponentCode,
+            },
+            {
+              name: 'chassis-stabilizer.system.ts',
+              summary: 'Levels the chassis while a wheel is on the ground.',
+              content: chassisStabilizerSystemCode,
+            },
+            {
+              name: 'air-control.component.ts',
+              summary: 'Settings for tilting the car in mid-air.',
+              content: airControlComponentCode,
+            },
+            {
+              name: 'air-control.system.ts',
+              summary: 'Tilts the car with the throttle while it is airborne.',
+              content: airControlSystemCode,
+            },
+          ],
+        },
+        {
+          title: 'Camera and reset',
+          files: [
+            {
+              name: 'camera-follow.component.ts',
+              summary: 'Settings for a camera that follows an entity.',
+              content: cameraFollowComponentCode,
+            },
+            {
+              name: 'camera-follow.system.ts',
+              summary: 'Moves the camera smoothly after the car.',
+              content: cameraFollowSystemCode,
+            },
+            {
+              name: 'car-reset.component.ts',
+              summary: "Each body's spawn point, for restarting.",
+              content: carResetComponentCode,
+            },
+            {
+              name: 'car-reset.system.ts',
+              summary: 'Puts the car back at the start when R is pressed.',
+              content: carResetSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/context-loss/index.tsx b/documentation-site/src/pages/demos/context-loss/index.tsx
index aec62a3ae..a1be9a075 100644
--- a/documentation-site/src/pages/demos/context-loss/index.tsx
+++ b/documentation-site/src/pages/demos/context-loss/index.tsx
@@ -5,35 +5,75 @@ import createPlanetCode from '!!raw-loader!./_create-planet';
 import loseContextOnClickCode from '!!raw-loader!./_lose-context-on-click';
 import spinSystemCode from '!!raw-loader!./_spin.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function ContextLoss(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Context Loss',
-        description:
-          'A demo showing the engine surviving a lost WebGL context.',
-      }}
-      header="Context Loss"
-      blurb="Click the planet to make the browser take the WebGL context away, the way a GPU reset would. Nothing is drawn while it's gone, but the game keeps running: when the context comes back a moment later, the engine rebuilds its textures, programs and buffers, and the planet has kept spinning. It comes back at a lower pixel ratio, chosen in the onContextLost listener."
+    <DemoPage
+      slug="context-loss"
       createGame={createContextLossGame}
-      codeFiles={[
+      controls={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          inputs: [{ device: 'mouse', label: 'Click the planet' }],
+          action: 'Lose the WebGL context',
+          detail: 'It comes back after 1.5 seconds',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'A click makes the browser take the WebGL context away, the way a GPU reset would, and gives it back a moment later.',
+          file: 'lose-context-on-click.ts',
+        },
+        {
+          text: 'Nothing is drawn while the context is gone, but the game keeps running, so the planet has kept spinning when it returns.',
+          file: 'spin.system.ts',
         },
         {
-          name: 'lose-context-on-click.ts',
-          content: loseContextOnClickCode,
+          text: 'On restore, the engine rebuilds its textures, programs and buffers from data it kept, like the image the planet texture was loaded from.',
+          file: 'create-planet.ts',
         },
         {
-          name: 'create-planet.ts',
-          content: createPlanetCode,
+          text: 'The onContextLost listener lowers the maximum pixel ratio, so the game comes back at a lower resolution.',
+          file: 'lose-context-on-click.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Context loss', to: '/docs/docs/rendering/context-loss' },
+        { label: 'Textures', to: '/docs/docs/rendering/textures' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Creates the camera and planet, sets up the click handler and registers the systems.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'spin.system.ts',
-          content: spinSystemCode,
+          title: 'Scene',
+          files: [
+            {
+              name: 'lose-context-on-click.ts',
+              summary:
+                'Loses and restores the context on click, and lowers the pixel ratio when it is lost.',
+              content: loseContextOnClickCode,
+            },
+            {
+              name: 'create-planet.ts',
+              summary: 'Creates the spinning planet sprite.',
+              content: createPlanetCode,
+            },
+            {
+              name: 'spin.system.ts',
+              summary:
+                'A spin component and the system that turns entities at a steady rate.',
+              content: spinSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/easing-functions/index.tsx b/documentation-site/src/pages/demos/easing-functions/index.tsx
index 3c70b3ede..47eecd559 100644
--- a/documentation-site/src/pages/demos/easing-functions/index.tsx
+++ b/documentation-site/src/pages/demos/easing-functions/index.tsx
@@ -5,59 +5,100 @@ import createEasingRowsCode from '!!raw-loader!./_create-easing-rows';
 import easingRowComponentCode from '!!raw-loader!./_easing-row.component';
 import easingRowSystemCode from '!!raw-loader!./_easing-row.system';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
+import {
+  DemoLegend,
+  DemoPage,
+  DemoPanel,
+} from '@site/src/components/demo-page';
 import { easingRowConfigs } from './_create-easing-rows';
 
 export default function EasingFunctions(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Easing Functions',
-        description:
-          'A demo showcasing all of the easing functions in the animations module.',
-      }}
-      header="Easing Functions"
-      blurb="Each lane sweeps a ball back and forth using one of the easing functions from the animations module, so their curves can be compared side by side. Watch how easeInBack, easeInOutBack and easeInOutElastic momentarily overshoot the lane before settling."
+    <DemoPage
+      slug="easing-functions"
       createGame={createEasingFunctionsGame}
-      codeFiles={[
+      panels={
+        <DemoPanel title="Legend" icon="fa-list">
+          <DemoLegend
+            items={easingRowConfigs.map(({ name, color }) => ({
+              marker: (
+                <span
+                  style={{
+                    width: 16,
+                    height: 16,
+                    borderRadius: '50%',
+                    backgroundColor: color.toRGBAString(),
+                  }}
+                />
+              ),
+              label: name,
+            }))}
+          />
+        </DemoPanel>
+      }
+      highlights={[
+        {
+          text: 'Each lane sweeps a ball back and forth with a different easing function, so the curves can be compared side by side.',
+          file: 'create-easing-rows.ts',
+        },
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'A system turns time into a 0 to 1 ping-pong phase, eases it, and moves the ball between the lane ends by that amount.',
+          file: 'easing-row.system.ts',
         },
         {
-          name: 'create-easing-rows.ts',
-          content: createEasingRowsCode,
+          text: 'easeInBack, easeInOutBack and easeInOutElastic return values outside 0 to 1, so their balls briefly overshoot the lane.',
+          file: 'create-easing-rows.ts',
         },
+      ]}
+      docLinks={[
         {
-          name: 'easing-row.component.ts',
-          content: easingRowComponentCode,
+          label: 'Property animations',
+          to: '/docs/docs/animations/property-animations',
         },
         {
-          name: 'easing-row.system.ts',
-          content: easingRowSystemCode,
+          label: 'Interpolation and smoothing',
+          to: '/docs/docs/math/interpolation-and-smoothing',
+        },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary: 'Builds the easing lanes and registers the systems.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-easing-rows.ts',
+              summary:
+                'Lists the easing functions and builds a lane and ball for each.',
+              content: createEasingRowsCode,
+            },
+          ],
+        },
+        {
+          title: 'Easing',
+          files: [
+            {
+              name: 'easing-row.component.ts',
+              summary: "A ball's easing function and the range it sweeps.",
+              content: easingRowComponentCode,
+            },
+            {
+              name: 'easing-row.system.ts',
+              summary:
+                'Moves each ball along its lane using its easing function.',
+              content: easingRowSystemCode,
+            },
+          ],
         },
       ]}
-      interactions={
-        <>
-          {easingRowConfigs.map(({ name, color }) => (
-            <InteractionInstruction
-              key={name}
-              displayElement={
-                <div
-                  style={{
-                    width: 16,
-                    height: 16,
-                    borderRadius: '50%',
-                    backgroundColor: color.toRGBAString(),
-                  }}
-                />
-              }
-              text={name}
-            />
-          ))}
-        </>
-      }
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/ecs/index.tsx b/documentation-site/src/pages/demos/ecs/index.tsx
index fff52ebde..53e8cafa3 100644
--- a/documentation-site/src/pages/demos/ecs/index.tsx
+++ b/documentation-site/src/pages/demos/ecs/index.tsx
@@ -5,34 +5,69 @@ import createEntityCode from '!!raw-loader!./_create-entity';
 import createSpriteCode from '!!raw-loader!./_create-sprite';
 import createSystemCode from '!!raw-loader!./_demo.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
-export default function Rendering(): JSX.Element {
+export default function Ecs(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Entity Component System',
-        description: 'A demo showcasing a full space shooter game.',
-      }}
-      header="Entity Component System"
-      blurb="This demo shows how to create a simple ECS world, entity, component and system."
+    <DemoPage
+      slug="ecs"
       createGame={createEcsGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'createGame gives you a world, and systems are added to it in the order they should run each frame.',
+          file: 'create-game.ts',
         },
         {
-          name: 'create-entity.ts',
-          content: createEntityCode,
+          text: 'An entity is just a number: the star is built by adding sprite, position and rotation components to it.',
+          file: 'create-entity.ts',
         },
         {
-          name: 'create-sprite.ts',
-          content: createSpriteCode,
+          text: 'The demo system queries every entity with a position and rotation, and moves the star in a circle while it spins.',
+          file: 'demo.system.ts',
         },
         {
-          name: 'demo.system.ts',
-          content: createSystemCode,
+          text: 'Systems write the local pose, and the transform system turns it into the world pose the renderer draws.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'ECS', to: '/docs/docs/ecs' },
+        { label: 'Entities', to: '/docs/docs/ecs/entity' },
+        { label: 'Components', to: '/docs/docs/ecs/component' },
+        { label: 'Systems', to: '/docs/docs/ecs/system' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Creates the world and camera, adds the star and registers the systems.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Entity and system',
+          files: [
+            {
+              name: 'create-sprite.ts',
+              summary: 'Loads the star image as a sprite.',
+              content: createSpriteCode,
+            },
+            {
+              name: 'create-entity.ts',
+              summary:
+                'Creates an entity and adds sprite, position and rotation components.',
+              content: createEntityCode,
+            },
+            {
+              name: 'demo.system.ts',
+              summary: 'Moves every matching entity in a circle and spins it.',
+              content: createSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/erosion-burn/index.tsx b/documentation-site/src/pages/demos/erosion-burn/index.tsx
index 32eac1b0e..281c0930e 100644
--- a/documentation-site/src/pages/demos/erosion-burn/index.tsx
+++ b/documentation-site/src/pages/demos/erosion-burn/index.tsx
@@ -6,39 +6,77 @@ import erosionComponentCode from '!!raw-loader!./_erosion.component';
 import erosionSystemCode from '!!raw-loader!./_erosion.system';
 import erosionShaderCode from '!!raw-loader!./_erosion.shader';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function ErosionBurn(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Erosion Burn Demo',
-        description:
-          "A demo showcasing an alpha erosion burn shader eating away a sprite's edges.",
-      }}
-      header="Erosion Burn"
-      blurb="This demo shows a custom fragment shader that erodes a sprite's alpha using a Perlin noise texture, while a gradient texture colors the leading edge bright yellow, orange and white to sell the look of it smouldering away. The shader reuses the engine's default sprite vertex shader and just swaps in a custom fragment shader with extra textures and uniforms, the same pattern used for the bricks in the Brick Breaker demo, here extended to take multiple textures on one material."
+    <DemoPage
+      slug="erosion-burn"
       createGame={createErosionBurnGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'A custom fragment shader hides every pixel whose Perlin noise value is below the burn line.',
+          file: 'erosion.shader.ts',
         },
         {
-          name: 'create-sprite.ts',
-          content: createSpriteCode,
+          text: 'Just ahead of the burn line, a gradient texture tints the edge yellow, orange and white so it looks like it smoulders.',
+          file: 'erosion.shader.ts',
         },
         {
-          name: 'erosion.component.ts',
-          content: erosionComponentCode,
+          text: "The material keeps the engine's default sprite vertex shader and adds two extra textures and two uniforms.",
+          file: 'create-sprite.ts',
         },
         {
-          name: 'erosion.system.ts',
-          content: erosionSystemCode,
+          text: 'A system moves the burn line back and forth each frame by setting a material uniform.',
+          file: 'erosion.system.ts',
+        },
+      ]}
+      docLinks={[
+        {
+          label: 'Custom sprite shaders',
+          to: '/docs/docs/rendering/sprites',
+        },
+        { label: 'Materials', to: '/docs/docs/rendering/material-uniforms' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Places the burning sprite, tags it and registers the systems.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'erosion.shader.ts',
-          content: erosionShaderCode,
+          title: 'The burn effect',
+          files: [
+            {
+              name: 'erosion.shader.ts',
+              summary:
+                'The fragment shader that erodes alpha with noise and colors the edge.',
+              content: erosionShaderCode,
+            },
+            {
+              name: 'create-sprite.ts',
+              summary:
+                'Loads the textures and builds a sprite material with the erosion shader.',
+              content: createSpriteCode,
+            },
+            {
+              name: 'erosion.component.ts',
+              summary: 'A tag marking the sprites the erosion system animates.',
+              content: erosionComponentCode,
+            },
+            {
+              name: 'erosion.system.ts',
+              summary:
+                'Moves the burn line in and out by updating a shader uniform.',
+              content: erosionSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/game-states/index.tsx b/documentation-site/src/pages/demos/game-states/index.tsx
index 8c1ee02e5..8d916b2f7 100644
--- a/documentation-site/src/pages/demos/game-states/index.tsx
+++ b/documentation-site/src/pages/demos/game-states/index.tsx
@@ -4,56 +4,124 @@ import gameCode from '!!raw-loader!./_create-game';
 import demoStateCode from '!!raw-loader!./_demo-state';
 import screensCode from '!!raw-loader!./_screens';
 import stateInputSystemCode from '!!raw-loader!./_state-input.system';
+import starComponentCode from '!!raw-loader!./_star.component';
 import starSystemCode from '!!raw-loader!./_star.system';
+import playerComponentCode from '!!raw-loader!./_player.component';
 import playerSystemCode from '!!raw-loader!./_player.system';
 import hudSystemCode from '!!raw-loader!./_hud.system';
 import createLabelCode from '!!raw-loader!./_create-label';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function GameStates(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Game States Demo',
-        description:
-          'A demo showcasing game states, run conditions and state-scoped entities.',
-      }}
-      header="Game States"
-      blurb="A menu, a round and a game-over screen, switched with a GameState. Each state's setup runs once when it's entered, gameplay systems only run while playing, and state-scoped entities are removed on the transitions that end them: the menu's text when it's left, and a round's stars and basket when the next round or the menu starts, so they stay behind the game-over screen. No system checks the state or cleans up after a round."
+    <DemoPage
+      slug="game-states"
       createGame={createGameStatesGame}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="Space" />}
-            text="Play, or play again."
-          />
-          <InteractionInstruction
-            displayElement={
-              <>
-                <KeyboardKey keyCode="←" />
-                <KeyboardKey keyCode="→" />
-              </>
-            }
-            text="Move the basket."
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="Esc" />}
-            text="Back to the menu from the game-over screen."
-          />
-        </>
-      }
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'demo-state.ts', content: demoStateCode },
-        { name: 'screens.ts', content: screensCode },
-        { name: 'state-input.system.ts', content: stateInputSystemCode },
-        { name: 'star.system.ts', content: starSystemCode },
-        { name: 'player.system.ts', content: playerSystemCode },
-        { name: 'hud.system.ts', content: hudSystemCode },
-        { name: 'create-label.ts', content: createLabelCode },
+      controls={[
+        { inputs: ['Space'], action: 'Play', detail: 'Also plays again' },
+        { inputs: ['←', 'A'], action: 'Move left' },
+        { inputs: ['→', 'D'], action: 'Move right' },
+        {
+          inputs: ['Esc'],
+          action: 'Back to the menu',
+          detail: 'From the game-over screen',
+        },
+      ]}
+      highlights={[
+        {
+          text: "Each state's setup system runs once, in the state's enter group, when that state is entered.",
+          file: 'create-game.ts',
+        },
+        {
+          text: 'Gameplay systems use an inState run condition, so they only run while playing and none of them checks the state.',
+          file: 'create-game.ts',
+        },
+        {
+          text: "State-scoped entities remove themselves: the menu text when the menu is left, and a round's stars and basket when the next round or the menu starts.",
+          file: 'screens.ts',
+        },
+        {
+          text: 'Because the round is only cleaned up later, its stars and basket stay visible behind the game-over screen.',
+          file: 'star.system.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Game states', to: '/docs/docs/states' },
+        { label: 'Systems', to: '/docs/docs/ecs/system' },
+        { label: 'Rendering text', to: '/docs/docs/text/rendering-text' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Creates the game state and registers each system with its run condition.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'States and screens',
+          files: [
+            {
+              name: 'demo-state.ts',
+              summary:
+                'The three state names and the round score the systems share.',
+              content: demoStateCode,
+            },
+            {
+              name: 'screens.ts',
+              summary:
+                'Enter systems that build the menu, a round and the game-over screen.',
+              content: screensCode,
+            },
+            {
+              name: 'state-input.system.ts',
+              summary:
+                'Switches state when Space or Escape is pressed on the menu or game-over screen.',
+              content: stateInputSystemCode,
+            },
+            {
+              name: 'create-label.ts',
+              summary: 'Creates a centered line of text.',
+              content: createLabelCode,
+            },
+          ],
+        },
+        {
+          title: 'Playing a round',
+          files: [
+            {
+              name: 'player.component.ts',
+              summary: "The basket's speed, width and how far it can move.",
+              content: playerComponentCode,
+            },
+            {
+              name: 'player.system.ts',
+              summary: 'Moves the basket left and right with the input.',
+              content: playerSystemCode,
+            },
+            {
+              name: 'star.component.ts',
+              summary: "A falling star's speed.",
+              content: starComponentCode,
+            },
+            {
+              name: 'star.system.ts',
+              summary:
+                'Spawns falling stars, scores catches and ends the round after three misses.',
+              content: starSystemCode,
+            },
+            {
+              name: 'hud.system.ts',
+              summary: "Writes the round's score into the score text.",
+              content: hudSystemCode,
+            },
+          ],
+        },
       ]}
     />
   );
diff --git a/documentation-site/src/pages/demos/index.tsx b/documentation-site/src/pages/demos/index.tsx
index 3516873a8..824e999e9 100644
--- a/documentation-site/src/pages/demos/index.tsx
+++ b/documentation-site/src/pages/demos/index.tsx
@@ -27,8 +27,12 @@ export default function Demos(): JSX.Element {
       description="Interactive demos of the Forge Game Engine's features, sorted by category."
     >
       <div className={styles.container}>
+        <p className="eyebrow">See it running</p>
         <h1>Demos</h1>
-        <p>Browse interactive demos by category, or search for one by title.</p>
+        <p className={styles.intro}>
+          Try each feature live, with the code that runs it right beside it.
+          Browse by category, or search by title.
+        </p>
         <DemoSearch value={query} onChange={setQuery} />
         {trimmedQuery.length === 0 ? (
           <div className={styles.categoryGrid}>
diff --git a/documentation-site/src/pages/demos/layout-groups/index.tsx b/documentation-site/src/pages/demos/layout-groups/index.tsx
index f8d96d3f0..b56e40c16 100644
--- a/documentation-site/src/pages/demos/layout-groups/index.tsx
+++ b/documentation-site/src/pages/demos/layout-groups/index.tsx
@@ -6,25 +6,86 @@ import toolbarCode from '!!raw-loader!./_create-toolbar';
 import inventoryGridCode from '!!raw-loader!./_create-inventory-grid';
 import optionsFormCode from '!!raw-loader!./_create-options-form';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function LayoutGroups(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Layout Groups',
-        description:
-          'A demo showcasing horizontal, vertical, and grid layout groups (including content-sized grid columns) plus content size fitting, from the ui module.',
-      }}
-      header="Layout Groups"
-      blurb="Four panels, each arranged automatically instead of by hand. 'Menu' stacks three buttons with a VerticalLayoutGroupEcsComponent, and shrink-wraps its own size to fit them via a ContentSizeFitterEcsComponent - resize a button and the panel follows. 'Toolbar' spaces a row of icons evenly with a HorizontalLayoutGroupEcsComponent. 'Inventory' places eight cells into a fixed 4-column grid with a GridLayoutGroupEcsComponent. 'Options' uses that same component with columnWidthMode: 'content' instead - the label column sizes itself to whichever of 'Music'/'Fullscreen' is widest, so both rows' controls line up on the same left edge. None of the arranged children set their own anchoredPosition or size - createUiLayoutGroupEcsSystem computes all of it, every frame."
+    <DemoPage
+      slug="layout-groups"
       createGame={createLayoutGroupsGame}
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'create-menu.ts', content: menuCode },
-        { name: 'create-toolbar.ts', content: toolbarCode },
-        { name: 'create-inventory-grid.ts', content: inventoryGridCode },
-        { name: 'create-options-form.ts', content: optionsFormCode },
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: 'Use a button, slider or toggle',
+        },
+        { inputs: ['↑↓←→'], action: 'Move focus' },
+        { inputs: ['Enter', 'Space'], action: 'Press the focused element' },
+      ]}
+      highlights={[
+        {
+          text: "'Menu' stacks its buttons with a vertical layout group, and a content size fitter shrink-wraps the panel around them.",
+          file: 'create-menu.ts',
+        },
+        {
+          text: "'Toolbar' spaces and sizes a row of icons evenly with a horizontal layout group.",
+          file: 'create-toolbar.ts',
+        },
+        {
+          text: "'Inventory' places eight cells in a fixed four-column grid, where cellSize alone decides each cell's size.",
+          file: 'create-inventory-grid.ts',
+        },
+        {
+          text: "'Options' sizes its label column to the widest label with columnWidthMode 'content', so the controls line up.",
+          file: 'create-options-form.ts',
+        },
+        {
+          text: 'No arranged child sets its own position or size; the layout group system computes them every frame.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Layout groups', to: '/docs/docs/ui/layout-groups' },
+        { label: 'Anchors and layout', to: '/docs/docs/ui/anchors-and-layout' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the canvas and input, and builds the four panels.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Panels',
+          files: [
+            {
+              name: 'create-menu.ts',
+              summary:
+                'A vertical stack of buttons in a panel that fits its content.',
+              content: menuCode,
+            },
+            {
+              name: 'create-toolbar.ts',
+              summary: 'A horizontal row of evenly spaced icons.',
+              content: toolbarCode,
+            },
+            {
+              name: 'create-inventory-grid.ts',
+              summary: 'Eight fixed-size cells in a four-column grid.',
+              content: inventoryGridCode,
+            },
+            {
+              name: 'create-options-form.ts',
+              summary:
+                'A label and control form whose label column sizes to its content.',
+              content: optionsFormCode,
+            },
+          ],
+        },
       ]}
     />
   );
diff --git a/documentation-site/src/pages/demos/linear-spring-damper/index.tsx b/documentation-site/src/pages/demos/linear-spring-damper/index.tsx
index b5dfca373..320d1a0df 100644
--- a/documentation-site/src/pages/demos/linear-spring-damper/index.tsx
+++ b/documentation-site/src/pages/demos/linear-spring-damper/index.tsx
@@ -7,43 +7,98 @@ import resetSystemCode from '!!raw-loader!./_reset.system';
 import springLineComponentCode from '!!raw-loader!./_spring-line.component';
 import springLineSystemCode from '!!raw-loader!./_spring-line.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function LinearSpringDamper(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Linear Spring and Damper Demo',
-        description:
-          "A demo showcasing the physics engine's LinearSpring and LinearDamper: position- and velocity-based forces connecting two bodies, used to model vehicle suspension.",
-      }}
-      header="Linear Spring and Damper (Suspension)"
-      blurb="Both columns hang a wheel below a fixed mount (the attachment point on the vehicle frame) with a LinearSpring, released with an upward velocity to simulate just having hit a bump (the bump kicks the wheel up towards the mount, then the spring pulls it back down), then every few seconds teleported back to that same starting position and velocity to replay the same bump (see reset.component.ts and reset.system.ts; a repeated impulse instead would risk pumping unbounded energy into the undamped column over a long-running demo). The left wheel has only a spring: once disturbed, it keeps oscillating until the next reset, with nothing to dissipate its energy. The right wheel pairs the same spring with a LinearDamper, which resists the compression/extension speed and settles the wheel back to rest well before the next reset, the same role a shock absorber plays alongside a suspension spring. The connecting line's length visualizes each spring's current stretch."
+    <DemoPage
+      slug="linear-spring-damper"
       createGame={createLinearSpringDamperGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'Each wheel hangs below a fixed mount on a linear spring, like a suspension on a vehicle frame.',
+          file: 'create-suspensions.ts',
         },
         {
-          name: 'create-suspensions.ts',
-          content: createSuspensionsCode,
+          text: 'The left wheel has only a spring, so nothing removes its energy and it keeps bouncing.',
+          file: 'create-suspensions.ts',
         },
         {
-          name: 'reset.component.ts',
-          content: resetComponentCode,
+          text: 'The right wheel adds a linear damper, which resists the speed of the bounce and settles it quickly, like a shock absorber.',
+          file: 'create-suspensions.ts',
         },
         {
-          name: 'reset.system.ts',
-          content: resetSystemCode,
+          text: 'Every few seconds both wheels are put back with the same upward velocity, replaying an identical bump.',
+          file: 'reset.system.ts',
         },
         {
-          name: 'spring-line.component.ts',
-          content: springLineComponentCode,
+          text: "The bar between mount and wheel stretches each tick to show the spring's current length.",
+          file: 'spring-line.system.ts',
+        },
+      ]}
+      docLinks={[
+        {
+          label: 'Forces',
+          to: '/docs/docs/physics/forces',
+        },
+        { label: 'Bodies and shapes', to: '/docs/docs/physics/rigid-bodies' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the camera and suspensions, and registers every system in the order they run.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-suspensions.ts',
+              summary:
+                'Builds the two mounts and wheels, connected by a spring with or without a damper.',
+              content: createSuspensionsCode,
+            },
+          ],
+        },
+        {
+          title: 'Replaying the bump',
+          files: [
+            {
+              name: 'reset.component.ts',
+              summary:
+                'The position and velocity a wheel returns to, and how often.',
+              content: resetComponentCode,
+            },
+            {
+              name: 'reset.system.ts',
+              summary:
+                'Teleports each wheel back to its start on a fixed interval.',
+              content: resetSystemCode,
+            },
+          ],
         },
         {
-          name: 'spring-line.system.ts',
-          content: springLineSystemCode,
+          title: 'Drawing the spring',
+          files: [
+            {
+              name: 'spring-line.component.ts',
+              summary:
+                'Links a line sprite to a fixed anchor and a moving body.',
+              content: springLineComponentCode,
+            },
+            {
+              name: 'spring-line.system.ts',
+              summary:
+                'Stretches each line sprite between its anchor and the body every tick.',
+              content: springLineSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/masks/index.tsx b/documentation-site/src/pages/demos/masks/index.tsx
index 946c6ccf5..9dcd7f5be 100644
--- a/documentation-site/src/pages/demos/masks/index.tsx
+++ b/documentation-site/src/pages/demos/masks/index.tsx
@@ -7,26 +7,91 @@ import maskPulseSystemCode from '!!raw-loader!./_mask-pulse.system';
 import scrollComponentCode from '!!raw-loader!./_scroll.component';
 import scrollSystemCode from '!!raw-loader!./_scroll.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function Masks(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Masks Demo',
-        description:
-          'A demo showcasing MaskEcsComponent: clipping a scrolling list to a rect, and revealing a bar and an arc gauge with linear and radial masks.',
-      }}
-      header="Masks"
-      blurb="A MaskEcsComponent clips the sprites and text of its entity and its descendants. Left: a list scrolls through a rect mask. Top right: a nine-slice bar stays full size while a linear mask reveals it, so its rounded ends never squash. Bottom right: a radial mask over three quarters of a turn fills an arc gauge."
+    <DemoPage
+      slug="masks"
       createGame={createMasksGame}
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'create-masked-content.ts', content: maskedContentCode },
-        { name: 'mask-pulse.component.ts', content: maskPulseComponentCode },
-        { name: 'mask-pulse.system.ts', content: maskPulseSystemCode },
-        { name: 'scroll.component.ts', content: scrollComponentCode },
-        { name: 'scroll.system.ts', content: scrollSystemCode },
+      highlights={[
+        {
+          text: 'A mask clips the sprites and text of its entity and all of its descendants.',
+          file: 'create-masked-content.ts',
+        },
+        {
+          text: 'On the left, a list taller than its viewport scrolls through a rect mask and is clipped to it.',
+          file: 'scroll.system.ts',
+        },
+        {
+          text: 'Top right, a linear mask reveals a full-size nine-slice bar, so its rounded ends never squash.',
+          file: 'create-masked-content.ts',
+        },
+        {
+          text: 'Bottom right, a radial mask over three quarters of a turn fills an arc gauge.',
+          file: 'create-masked-content.ts',
+        },
+        {
+          text: "A small system animates the fills by writing each mask's amount.",
+          file: 'mask-pulse.system.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Masks', to: '/docs/docs/rendering/masks' },
+        {
+          label: 'Nine-slice sprites',
+          to: '/docs/docs/rendering/nine-slice-sprites',
+        },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary: 'Builds the masked scenes and registers the systems.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-masked-content.ts',
+              summary:
+                'Creates the scrolling list, the linear fill bar and the radial gauge.',
+              content: maskedContentCode,
+            },
+          ],
+        },
+        {
+          title: 'Animation',
+          files: [
+            {
+              name: 'scroll.component.ts',
+              summary:
+                'Settings for scrolling an entity upward and wrapping it.',
+              content: scrollComponentCode,
+            },
+            {
+              name: 'scroll.system.ts',
+              summary: 'Scrolls the list upward and wraps it back around.',
+              content: scrollSystemCode,
+            },
+            {
+              name: 'mask-pulse.component.ts',
+              summary: 'How fast a linear or radial mask fills and empties.',
+              content: maskPulseComponentCode,
+            },
+            {
+              name: 'mask-pulse.system.ts',
+              summary:
+                "Sweeps each pulsing mask's amount between 0 and 1 and back.",
+              content: maskPulseSystemCode,
+            },
+          ],
+        },
       ]}
     />
   );
diff --git a/documentation-site/src/pages/demos/moving-platform/index.tsx b/documentation-site/src/pages/demos/moving-platform/index.tsx
index e8e713291..ff433035c 100644
--- a/documentation-site/src/pages/demos/moving-platform/index.tsx
+++ b/documentation-site/src/pages/demos/moving-platform/index.tsx
@@ -7,32 +7,91 @@ import platformMoverComponentCode from '!!raw-loader!./_platform-mover.component
 import platformMoverSystemCode from '!!raw-loader!./_platform-mover.system';
 import spawnCratesCode from '!!raw-loader!./_spawn-crates';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function MovingPlatform(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Moving Platform Demo',
-        description:
-          "A demo showcasing RigidBodyEcsComponent's kinematic body type: a platform driven directly by game code that carries and pushes dynamic crates without being affected by gravity or collisions itself.",
-      }}
-      header="Moving Platform"
-      blurb="The platform is a kinematic body (type: 'kinematic'): a small demo-only system (see platform-mover.component.ts and platform-mover.system.ts) sets its velocity directly and reverses it at either end, and createEulerIntegrationEcsSystem moves it every tick from that velocity, exactly like a dynamic body. But unlike a dynamic body, gravity and collisions never change the platform's own velocity - only the crates react, getting carried along and pushed as the platform sweeps under them. Click anywhere to drop another crate."
+    <DemoPage
+      slug="moving-platform"
       createGame={createMovingPlatformGame}
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'create-platform.ts', content: createPlatformCode },
+      controls={[
         {
-          name: 'platform-mover.component.ts',
-          content: platformMoverComponentCode,
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: 'Drop a crate',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'The platform is a kinematic body: game code sets its velocity, and gravity and collisions never change it.',
+          file: 'create-platform.ts',
+        },
+        {
+          text: 'A small demo system reverses the velocity at each end; euler integration moves it like any other body.',
+          file: 'platform-mover.system.ts',
+        },
+        {
+          text: 'The crates are dynamic bodies, so they ride along on the platform and get pushed as it sweeps under them.',
+          file: 'spawn-crates.ts',
+        },
+        {
+          text: 'A click converts the cursor to world space and drops a new crate there.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Bodies and shapes', to: '/docs/docs/physics/rigid-bodies' },
+        { label: 'Collisions', to: '/docs/docs/physics/collisions' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the scene and starting crates, registers the systems and handles clicks.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'The platform',
+          files: [
+            {
+              name: 'create-platform.ts',
+              summary:
+                'Creates the kinematic platform with its collider and starting velocity.',
+              content: createPlatformCode,
+            },
+            {
+              name: 'platform-mover.component.ts',
+              summary: 'The bounds and speed of a back-and-forth platform.',
+              content: platformMoverComponentCode,
+            },
+            {
+              name: 'platform-mover.system.ts',
+              summary:
+                "Reverses the platform's velocity when it reaches either bound.",
+              content: platformMoverSystemCode,
+            },
+          ],
         },
         {
-          name: 'platform-mover.system.ts',
-          content: platformMoverSystemCode,
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'spawn-crates.ts',
+              summary: 'Loads the crate sprite and spawns dynamic crates.',
+              content: spawnCratesCode,
+            },
+            {
+              name: 'create-boundaries.ts',
+              summary:
+                'Adds a static floor and walls that catch crates falling off the platform.',
+              content: createBoundariesCode,
+            },
+          ],
         },
-        { name: 'spawn-crates.ts', content: spawnCratesCode },
-        { name: 'create-boundaries.ts', content: createBoundariesCode },
       ]}
     />
   );
diff --git a/documentation-site/src/pages/demos/newtons-cradle/index.tsx b/documentation-site/src/pages/demos/newtons-cradle/index.tsx
index 32b9d8680..6194818bb 100644
--- a/documentation-site/src/pages/demos/newtons-cradle/index.tsx
+++ b/documentation-site/src/pages/demos/newtons-cradle/index.tsx
@@ -2,28 +2,81 @@ import React, { JSX } from 'react';
 import { createNewtonsCradleGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 import createCradleCode from '!!raw-loader!./_create-cradle';
+import armComponentCode from '!!raw-loader!./_arm.component';
+import armSystemCode from '!!raw-loader!./_arm.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function NewtonsCradle(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: "Newton's Cradle Demo",
-        description:
-          "A demo showcasing the physics engine's RevoluteJoint and collision resolution together: five balls hinged to a shared frame, transferring momentum through each other exactly like the executive desk toy.",
-      }}
-      header="Newton's Cradle"
-      blurb="Five balls are each hinged to their own pivot on a shared frame by a RevoluteJoint, spaced so neighboring balls just touch at rest, exactly like the desk toy. The joints only keep each ball swinging about its own pivot, they play no part in transferring momentum between balls, that comes entirely from the engine's ordinary collision resolution between the balls themselves. The leftmost ball starts pulled back and is released exactly once, when the scene is built, swings in, and the impact carries down the row to pop the rightmost ball out. From there it's left alone, so it settles the same way a real cradle does after a single push."
+    <DemoPage
+      slug="newtons-cradle"
       createGame={createNewtonsCradleGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'Each of the five balls hangs from its own pivot on a revolute joint, which only keeps it swinging in an arc.',
+          file: 'create-cradle.ts',
         },
         {
-          name: 'create-cradle.ts',
-          content: createCradleCode,
+          text: 'Momentum passes down the row through ordinary collision resolution between the balls, helped by a high restitution.',
+          file: 'create-cradle.ts',
+        },
+        {
+          text: 'A tiny gap between resting balls makes each impact a separate event, so only the last ball pops out.',
+          file: 'create-cradle.ts',
+        },
+        {
+          text: 'The leftmost ball is released once when the scene is built, then the cradle settles on its own.',
+          file: 'create-cradle.ts',
+        },
+        {
+          text: 'Joints are invisible, so a demo system stretches and turns a sprite between each pivot and ball every tick.',
+          file: 'arm.system.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Joints', to: '/docs/docs/physics/joints' },
+        { label: 'Collisions', to: '/docs/docs/physics/collisions' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the camera and cradle, and registers every system in the order they run.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-cradle.ts',
+              summary:
+                'Builds the frame and five hinged balls, with the first one pulled back.',
+              content: createCradleCode,
+            },
+          ],
+        },
+        {
+          title: 'Drawing the arms',
+          files: [
+            {
+              name: 'arm.component.ts',
+              summary:
+                'Links an arm sprite to a fixed pivot and a swinging body.',
+              content: armComponentCode,
+            },
+            {
+              name: 'arm.system.ts',
+              summary:
+                'Positions, rotates and stretches each arm between its pivot and ball.',
+              content: armSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/nine-slice/index.tsx b/documentation-site/src/pages/demos/nine-slice/index.tsx
index 0783ef7df..5a93515c4 100644
--- a/documentation-site/src/pages/demos/nine-slice/index.tsx
+++ b/documentation-site/src/pages/demos/nine-slice/index.tsx
@@ -5,64 +5,75 @@ import createPanelsCode from '!!raw-loader!./_create-panels';
 import panelComponentCode from '!!raw-loader!./_panel.component';
 import panelSystemCode from '!!raw-loader!./_panel.system';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-  fontWeight: 700,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function NineSlice(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Nine-Slice Sprites',
-        description:
-          'A demo comparing a naively-stretched sprite against nine-sliced sprites with stretch and tile edge/center modes.',
-      }}
-      header="Nine-Slice Sprites"
-      blurb="The same 96x96 panel artwork (a flat white fill with a thin inset frame line and cross-shaped corner notches, from Kenney's Fantasy UI Borders pack) drives all three panels, which all breathe between the same minimum and maximum size together. The left panel is a plain, unsliced sprite: as it grows, its corner notches and frame line stretch right along with it, smearing out of shape. The middle and right panels are nine-sliced with 'stretch' and 'tile' edge/center modes respectively: both keep their corner notches a crisp, fixed size no matter how large the panel gets. Because this artwork's edges and center are a flat, untextured fill rather than a repeating pattern, 'stretch' and 'tile' render identically here - the difference between those two modes only becomes visible with source art that has repeating detail (a brick or wood-grain edge, for example) for tiling to preserve."
+    <DemoPage
+      slug="nine-slice"
       createGame={createNineSliceGame}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={<div style={badgeStyle}>1</div>}
-            text="Naive stretch (no slicing)"
-          />
-          <InteractionInstruction
-            displayElement={<div style={badgeStyle}>2</div>}
-            text="Nine-slice: stretch"
-          />
-          <InteractionInstruction
-            displayElement={<div style={badgeStyle}>3</div>}
-            text="Nine-slice: tile (looks identical to #2 with this flat-fill artwork)"
-          />
-        </>
-      }
-      codeFiles={[
+      highlights={[
+        {
+          text: "Both panels use the same 96x96 frame artwork from Kenney's Fantasy UI Borders pack.",
+          file: 'create-panels.ts',
+        },
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'The top panel is a plain sprite: it stretches as a single quad, so its corner notches and frame line smear as it grows.',
+          file: 'create-panels.ts',
         },
         {
-          name: 'create-panels.ts',
-          content: createPanelsCode,
+          text: 'The bottom panel is nine-sliced: its corners keep a fixed size and only its edges and center stretch.',
+          file: 'create-panels.ts',
+        },
+        {
+          text: 'A system grows and shrinks both panels together while turning them, so only the slicing differs.',
+          file: 'panel.system.ts',
+        },
+      ]}
+      docLinks={[
+        {
+          label: 'Nine-slice sprites',
+          to: '/docs/docs/rendering/nine-slice-sprites',
+        },
+        { label: 'Sprites', to: '/docs/docs/rendering/sprites' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary: 'Creates the panels and registers the systems.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'panel.component.ts',
-          content: panelComponentCode,
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-panels.ts',
+              summary:
+                'Builds a plain and a nine-sliced sprite from the same panel texture.',
+              content: createPanelsCode,
+            },
+          ],
         },
         {
-          name: 'panel.system.ts',
-          content: panelSystemCode,
+          title: 'Animation',
+          files: [
+            {
+              name: 'panel.component.ts',
+              summary: 'The smallest and largest size a panel grows between.',
+              content: panelComponentCode,
+            },
+            {
+              name: 'panel.system.ts',
+              summary:
+                "Animates each panel's width on a sine wave and slowly rotates it.",
+              content: panelSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/particles/index.tsx b/documentation-site/src/pages/demos/particles/index.tsx
index c036bc4c3..8250e6b7f 100644
--- a/documentation-site/src/pages/demos/particles/index.tsx
+++ b/documentation-site/src/pages/demos/particles/index.tsx
@@ -4,31 +4,72 @@ import gameCode from '!!raw-loader!./_create-game';
 import createCursorEffectsCode from '!!raw-loader!./_create-cursor-effects';
 import createEmberFountainCode from '!!raw-loader!./_create-ember-fountain';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function Particles(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Particles Demo',
-        description:
-          "A demo showcasing Forge's particle system using Kenney's particle pack.",
-      }}
-      header="Particles"
-      blurb="This demo showcases the particle system using Kenney's particle pack. A fountain of embers at the bottom streams upward on its own at a steady emissionRate, slowing with drag as it rises and fading out. Click anywhere to burst a ring of sparks that fly outward from the cursor, slow down and fall under gravity, and hold and drag the mouse to trail smoke that rises, grows and fades. The spark and smoke emitters live on the same entity as two named emitters, the same pattern used for running several independent effects, like an attack and a footstep, off one entity, and every effect spawns around its entity's position."
+    <DemoPage
+      slug="particles"
       createGame={createParticlesGame}
-      codeFiles={[
+      controls={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: 'Burst sparks',
         },
         {
-          name: 'create-cursor-effects.ts',
-          content: createCursorEffectsCode,
+          inputs: [{ device: 'mouse', label: 'Hold and drag' }],
+          action: 'Trail smoke',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'The ember fountain runs forever on a steady emissionRate, with drag slowing the embers as they rise and fade.',
+          file: 'create-ember-fountain.ts',
+        },
+        {
+          text: 'A click fires one burst of sparks outward from a ring, and gravity pulls them down as they fade.',
+          file: 'create-cursor-effects.ts',
+        },
+        {
+          text: 'The spark and smoke emitters are two named emitters on one entity, a pattern for running several effects from one object.',
+          file: 'create-cursor-effects.ts',
+        },
+        {
+          text: "Emitters spawn around their entity's world position, so moving the cursor entity moves the effects.",
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Particles', to: '/docs/docs/particles' },
+        { label: 'Configuring emitters', to: '/docs/docs/particles/emitters' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Creates both effects, registers the particle systems and wires up mouse input.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'create-ember-fountain.ts',
-          content: createEmberFountainCode,
+          title: 'Effects',
+          files: [
+            {
+              name: 'create-ember-fountain.ts',
+              summary: 'An emitter that streams embers upward on its own.',
+              content: createEmberFountainCode,
+            },
+            {
+              name: 'create-cursor-effects.ts',
+              summary:
+                'One entity with spark and smoke emitters, driven by the mouse.',
+              content: createCursorEffectsCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/persistent-state/index.tsx b/documentation-site/src/pages/demos/persistent-state/index.tsx
index 057995876..20d0f8c09 100644
--- a/documentation-site/src/pages/demos/persistent-state/index.tsx
+++ b/documentation-site/src/pages/demos/persistent-state/index.tsx
@@ -5,46 +5,93 @@ import settingsCode from '!!raw-loader!./_settings';
 import spinnerComponentCode from '!!raw-loader!./_spinner.component';
 import spinnerSystemCode from '!!raw-loader!./_spinner.system';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function PersistentState(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Persistent State Demo',
-        description:
-          'A demo showcasing createPersistentState from the storage module: settings that survive a reload.',
-      }}
-      header="Persistent State"
-      blurb="The size and spin settings are a persistent state stored in localStorage. They're loaded before the game is created, written into the square's component, and stored on every change, so they survive a reload and a later visit. Reset makes them the defaults again and removes the stored entry."
+    <DemoPage
+      slug="persistent-state"
       createGame={createPersistentStateGame}
-      interactions={
-        <InteractionInstruction
-          displayElement={
-            <div style={badgeStyle}>
-              <i className="fa-solid fa-computer-mouse" />
-            </div>
-          }
-          text="Change the settings, then reload the page."
-        />
-      }
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'settings.ts', content: settingsCode },
-        { name: 'spinner.component.ts', content: spinnerComponentCode },
-        { name: 'spinner.system.ts', content: spinnerSystemCode },
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Drag the slider' }],
+          action: 'Change the size',
+        },
+        {
+          inputs: [{ device: 'mouse', label: 'Click the toggle' }],
+          action: 'Turn spinning on or off',
+        },
+        {
+          inputs: [{ device: 'mouse', label: 'Click Reset' }],
+          action: 'Restore the defaults',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'The size and spin settings are a persistent state kept in localStorage, so change them and reload the page to see them kept.',
+          file: 'settings.ts',
+        },
+        {
+          text: 'The settings are loaded before the game is created, and a stored value that fails validation falls back to its default.',
+          file: 'settings.ts',
+        },
+        {
+          text: "Every change goes through settings.set, which stores it and copies the new values into the square's component.",
+          file: 'create-game.ts',
+        },
+        {
+          text: 'Reset restores the defaults and removes the stored entry.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'If storage is unavailable, the settings fall back to memory and last for this visit only.',
+          file: 'settings.ts',
+        },
+      ]}
+      docLinks={[
+        {
+          label: 'Persistent state',
+          to: '/docs/docs/storage/persistent-state',
+        },
+        {
+          label: 'Storage backends',
+          to: '/docs/docs/storage/storage-backends',
+        },
+        { label: 'UI controls', to: '/docs/docs/ui/controls' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Loads the settings, builds the square and settings panel, and wires changes to storage.',
+              content: gameCode,
+            },
+            {
+              name: 'settings.ts',
+              summary:
+                'Creates the persistent settings record, with validation and a memory fallback.',
+              content: settingsCode,
+            },
+          ],
+        },
+        {
+          title: 'Spinner',
+          files: [
+            {
+              name: 'spinner.component.ts',
+              summary: "The square's size, spin setting and spin speed.",
+              content: spinnerComponentCode,
+            },
+            {
+              name: 'spinner.system.ts',
+              summary: 'Scales the square and turns it while spin is on.',
+              content: spinnerSystemCode,
+            },
+          ],
+        },
       ]}
     />
   );
diff --git a/documentation-site/src/pages/demos/physics/index.tsx b/documentation-site/src/pages/demos/physics/index.tsx
index 95d39c704..e586d368c 100644
--- a/documentation-site/src/pages/demos/physics/index.tsx
+++ b/documentation-site/src/pages/demos/physics/index.tsx
@@ -4,30 +4,71 @@ import gameCode from '!!raw-loader!./_create-game';
 import createBoundariesCode from '!!raw-loader!./_create-boundaries';
 import spawnShapesCode from '!!raw-loader!./_spawn-shapes';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function Physics(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Physics Demo',
-        description: 'A demo showcasing the physics engine.',
-      }}
-      header="Physics"
-      blurb="This demo showcases the engine's built-in 2D physics: rigid bodies, gravity, collision detection and resolution. A pile of circles and squares falls into a walled area, bouncing and colliding with the floor, walls and each other until they settle. Click anywhere on the canvas to trigger an explosion that blasts nearby shapes away from the click point."
+    <DemoPage
+      slug="physics"
       createGame={createPhysicsGame}
-      codeFiles={[
+      controls={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: 'Trigger an explosion',
         },
+      ]}
+      highlights={[
+        {
+          text: 'Three hundred circles, squares, triangles and planks are dynamic rigid bodies that fall under gravity and pile up.',
+          file: 'spawn-shapes.ts',
+        },
+        {
+          text: 'The floor and walls have colliders but no rigid body, so they are static and never move.',
+          file: 'create-boundaries.ts',
+        },
+        {
+          text: 'Broad phase, narrow phase and collision resolution run each tick to find touching shapes and push them apart.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'A click converts the cursor to world space and applies an explosive force that blasts nearby shapes away.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Physics', to: '/docs/docs/physics' },
+        { label: 'Bodies and shapes', to: '/docs/docs/physics/rigid-bodies' },
+        { label: 'Collisions', to: '/docs/docs/physics/collisions' },
+        { label: 'Forces', to: '/docs/docs/physics/forces' },
+      ]}
+      fileGroups={[
         {
-          name: 'create-boundaries.ts',
-          content: createBoundariesCode,
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the camera and scene, registers the physics systems and handles clicks.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'spawn-shapes.ts',
-          content: spawnShapesCode,
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-boundaries.ts',
+              summary:
+                'Adds the static floor and side walls that hold the pile.',
+              content: createBoundariesCode,
+            },
+            {
+              name: 'spawn-shapes.ts',
+              summary:
+                'Spawns hundreds of random shapes, pairing each sprite with a matching collider.',
+              content: spawnShapesCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/prismatic-joint/index.tsx b/documentation-site/src/pages/demos/prismatic-joint/index.tsx
index 7a9bbef2d..ad47a59b6 100644
--- a/documentation-site/src/pages/demos/prismatic-joint/index.tsx
+++ b/documentation-site/src/pages/demos/prismatic-joint/index.tsx
@@ -5,35 +5,74 @@ import createSlidersCode from '!!raw-loader!./_create-sliders';
 import pumpComponentCode from '!!raw-loader!./_pump.component';
 import pumpSystemCode from '!!raw-loader!./_pump.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function PrismaticJoint(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Prismatic Joint (Slider) Demo',
-        description:
-          "A demo showcasing the physics engine's PrismaticJoint: a constraint that locks two bodies to a single sliding axis.",
-      }}
-      header="Prismatic Joint (Slider)"
-      blurb="This demo showcases PrismaticJoint in three different setups. On the left, a piston pumps back and forth along a level rail between two limits. In the middle, an elevator platform is pumped upward and falls back down under gravity to its lower limit. On the right, a ball is pumped back up a diagonal incline and rolls back down it under gravity. In every case the joint keeps the slider locked to its rail: no rotation, no drifting sideways off the line, only limited to translate along the axis. PrismaticJoint has no built-in motor, so each slider is driven by a small demo-only system that periodically applies an impulse (see pump.component.ts and pump.system.ts)."
+    <DemoPage
+      slug="prismatic-joint"
       createGame={createPrismaticJointGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'Each slider is joined to a static anchor by a prismatic joint, so it can only move along one axis, never rotate or drift sideways.',
+          file: 'create-sliders.ts',
         },
         {
-          name: 'create-sliders.ts',
-          content: createSlidersCode,
+          text: 'Joint limits stop each slider at the ends of its dotted rail: a level piston, a vertical elevator and a diagonal incline.',
+          file: 'create-sliders.ts',
         },
         {
-          name: 'pump.component.ts',
-          content: pumpComponentCode,
+          text: 'Prismatic joints have no motor, so a small demo system applies an impulse every few seconds; gravity brings the elevator and ball back.',
+          file: 'pump.system.ts',
         },
         {
-          name: 'pump.system.ts',
-          content: pumpSystemCode,
+          text: 'The joint solver runs after collision resolution, so the rail constraint has the last word on velocity each tick.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Joints', to: '/docs/docs/physics/joints' },
+        { label: 'Forces', to: '/docs/docs/physics/forces' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the camera and sliders, and registers every system in the order they run.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-sliders.ts',
+              summary:
+                'Builds the piston, elevator and incline: anchors, rails, sliders and their joints.',
+              content: createSlidersCode,
+            },
+          ],
+        },
+        {
+          title: 'Pumping',
+          files: [
+            {
+              name: 'pump.component.ts',
+              summary:
+                'Settings for periodically nudging a slider along its rail.',
+              content: pumpComponentCode,
+            },
+            {
+              name: 'pump.system.ts',
+              summary:
+                'Applies each pump impulse on its interval, flipping direction for the piston.',
+              content: pumpSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/raycasting/_ray-visual.ts b/documentation-site/src/pages/demos/raycasting/_ray-visual.ts
index ff30484df..fd00f6057 100644
--- a/documentation-site/src/pages/demos/raycasting/_ray-visual.ts
+++ b/documentation-site/src/pages/demos/raycasting/_ray-visual.ts
@@ -56,7 +56,7 @@ export async function createRayVisual(
   const { textureCache } = renderContext;
 
   const markerTexture = await textureCache.getOrLoad(
-    getAssetUrl('img/blue-circle.png'),
+    getAssetUrl('img/White_Circle.png'),
   );
 
   const lineSprite = {
diff --git a/documentation-site/src/pages/demos/raycasting/index.tsx b/documentation-site/src/pages/demos/raycasting/index.tsx
index 21905a547..ecba2bf7d 100644
--- a/documentation-site/src/pages/demos/raycasting/index.tsx
+++ b/documentation-site/src/pages/demos/raycasting/index.tsx
@@ -4,30 +4,69 @@ import gameCode from '!!raw-loader!./_create-game';
 import createTargetsCode from '!!raw-loader!./_create-targets';
 import rayVisualCode from '!!raw-loader!./_ray-visual';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function Raycasting(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Raycasting Demo',
-        description: "A demo showcasing the physics engine's raycast function.",
-      }}
-      header="Raycasting"
-      blurb="This demo showcases the physics engine's `raycast` function. A ray is cast from the fixed point on the left edge toward your mouse cursor every time it moves, against a handful of static circle and square colliders. Where the ray hits something, a marker appears at the exact intersection point and the ray turns red; otherwise it just extends toward the cursor."
+    <DemoPage
+      slug="raycasting"
       createGame={createRaycastingGame}
-      codeFiles={[
+      controls={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          inputs: [{ device: 'mouse', label: 'Move' }],
+          action: 'Aim the ray',
         },
+      ]}
+      highlights={[
+        {
+          text: 'Each mouse move casts a ray from a fixed point on the left toward the cursor with the raycast function.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The closest hit is first in the results; a marker shows its exact point and the ray turns red.',
+          file: 'ray-visual.ts',
+        },
+        {
+          text: 'The targets are plain static colliders with no rigid body, which is all a raycast needs.',
+          file: 'create-targets.ts',
+        },
+        {
+          text: 'The broad phase still runs every tick, because raycast reads the bounding boxes it keeps up to date.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Raycasting', to: '/docs/docs/physics/raycasting' },
+        { label: 'Bodies and shapes', to: '/docs/docs/physics/rigid-bodies' },
+      ]}
+      fileGroups={[
         {
-          name: 'create-targets.ts',
-          content: createTargetsCode,
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the scene and casts a ray toward the cursor on every mouse move.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'ray-visual.ts',
-          content: rayVisualCode,
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-targets.ts',
+              summary:
+                'Places the static circle and square colliders the ray hits.',
+              content: createTargetsCode,
+            },
+            {
+              name: 'ray-visual.ts',
+              summary:
+                'Draws the ray as a stretched sprite and shows a marker at the hit point.',
+              content: rayVisualCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/revolute-joint/index.tsx b/documentation-site/src/pages/demos/revolute-joint/index.tsx
index 990a92853..99722b2fc 100644
--- a/documentation-site/src/pages/demos/revolute-joint/index.tsx
+++ b/documentation-site/src/pages/demos/revolute-joint/index.tsx
@@ -5,35 +5,74 @@ import createHingesCode from '!!raw-loader!./_create-hinges';
 import pushComponentCode from '!!raw-loader!./_push.component';
 import pushSystemCode from '!!raw-loader!./_push.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function RevoluteJoint(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Revolute Joint (Hinge) Demo',
-        description:
-          "A demo showcasing the physics engine's RevoluteJoint: a constraint that pins two bodies together at a point, locking translation but leaving rotation free.",
-      }}
-      header="Revolute Joint (Hinge)"
-      blurb="This demo showcases RevoluteJoint in three different setups. On the left, a door is hinged to a wall mount, its swing limited to 90 degrees between closed and open; gravity swings it shut and a periodic push swings it back open. In the middle, a pendulum is hinged by an arm to a fixed pivot and, with no limit and no push at all, simply swings back and forth under gravity, rotation is completely free. On the right, a wheel is hinged directly to its hub and, having been given a single initial spin, keeps rotating indefinitely: unlike RevoluteJoint's translation lock, nothing resists rotation unless a limit is enabled. RevoluteJoint has no built-in motor, so the door's swing is driven by a small demo-only system that periodically applies an off-center impulse (see push.component.ts and push.system.ts)."
+    <DemoPage
+      slug="revolute-joint"
       createGame={createRevoluteJointGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'A revolute joint pins two bodies together at a point: translation is locked, but rotation stays free.',
+          file: 'create-hinges.ts',
         },
         {
-          name: 'create-hinges.ts',
-          content: createHingesCode,
+          text: "The door's joint is limited to a 90 degree swing; gravity closes it and a periodic push opens it again.",
+          file: 'create-hinges.ts',
         },
         {
-          name: 'push.component.ts',
-          content: pushComponentCode,
+          text: 'The pendulum has no limit and no push, and the wheel was spun once, so it keeps turning with nothing to resist it.',
+          file: 'create-hinges.ts',
         },
         {
-          name: 'push.system.ts',
-          content: pushSystemCode,
+          text: 'Revolute joints have no motor, so the door is pushed by an impulse applied near its far edge.',
+          file: 'push.system.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Joints', to: '/docs/docs/physics/joints' },
+        { label: 'Forces', to: '/docs/docs/physics/forces' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the camera and hinges, and registers every system in the order they run.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-hinges.ts',
+              summary:
+                'Builds the door, pendulum and wheel, each hinged to a fixed pivot.',
+              content: createHingesCode,
+            },
+          ],
+        },
+        {
+          title: 'Pushing the door',
+          files: [
+            {
+              name: 'push.component.ts',
+              summary:
+                'Settings for an impulse applied at a point on a body every so often.',
+              content: pushComponentCode,
+            },
+            {
+              name: 'push.system.ts',
+              summary:
+                'Applies each push at its contact point, rotated to follow the body.',
+              content: pushSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/rolling-ball/index.tsx b/documentation-site/src/pages/demos/rolling-ball/index.tsx
index 343dd50cf..4f022dcaf 100644
--- a/documentation-site/src/pages/demos/rolling-ball/index.tsx
+++ b/documentation-site/src/pages/demos/rolling-ball/index.tsx
@@ -8,65 +8,99 @@ import rollSystemCode from '!!raw-loader!./_roll.system';
 import jumpSystemCode from '!!raw-loader!./_jump.system';
 import cameraFollowSystemCode from '!!raw-loader!./_camera-follow.system';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function RollingBall(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Rolling Ball Demo',
-        description:
-          'A demo showcasing TerrainCollider with a smooth, textured, curve-generated course and a player-controlled ball that rolls via friction from an AngularVelocityMotorEcsComponent.',
-      }}
-      header="Rolling Ball"
-      blurb="A standalone showcase of TerrainCollider: a long course whose smooth silhouette comes from a Catmull-Rom curve through sparse, randomly-placed control points, triangulated into a single mesh and textured with a tileable grass-like border blending into a tileable dirt-like fill. TerrainCollider's own collision points are sampled from that exact same curve, so what's drawn always matches what the ball touches. Roll input drives the ball's AngularVelocityMotorEcsComponent, and friction against the terrain - ordinary collision resolution, nothing special-cased - turns that spin into rolling motion up and down the hills. A small camera-follow system keeps the ball in view as it travels, and a jump impulse fires while grounded (the ball's ContactsEcsComponent lists the terrain entity)."
+    <DemoPage
+      slug="rolling-ball"
       createGame={createRollingBallGame}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="A" />}
-            text="Roll left"
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="D" />}
-            text="Roll right"
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="␣" />}
-            text="Jump"
-          />
-        </>
-      }
-      codeFiles={[
+      controls={[
+        { inputs: ['←', 'A'], action: 'Roll left' },
+        { inputs: ['→', 'D'], action: 'Roll right' },
+        { inputs: ['Space'], action: 'Jump', detail: 'Only on the ground' },
+      ]}
+      highlights={[
+        {
+          text: 'The hills are a smooth curve through a few random control points, used for both the TerrainCollider and the drawn mesh, so what you see is what the ball touches.',
+          file: 'create-terrain.ts',
+        },
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'The terrain mesh tiles a grass border near the surface that blends into a dirt fill below.',
+          file: 'create-terrain.ts',
         },
         {
-          name: 'create-terrain.ts',
-          content: createTerrainCode,
+          text: "Rolling sets the target speed of the ball's angular velocity motor, and ordinary friction with the ground turns that spin into movement.",
+          file: 'roll.system.ts',
         },
         {
-          name: 'create-player.ts',
-          content: createPlayerCode,
+          text: 'The ball can jump only while its contacts list the terrain, and it respawns if it falls off the end.',
+          file: 'jump.system.ts',
         },
         {
-          name: 'create-inputs.ts',
-          content: createInputsCode,
+          text: 'The camera eases after the ball with exponential smoothing.',
+          file: 'camera-follow.system.ts',
         },
+      ]}
+      docLinks={[
+        { label: 'Terrain', to: '/docs/docs/physics/terrain' },
+        { label: 'Forces', to: '/docs/docs/physics/forces' },
+        { label: 'Collisions', to: '/docs/docs/physics/collisions' },
+      ]}
+      fileGroups={[
         {
-          name: 'roll.system.ts',
-          content: rollSystemCode,
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Builds the terrain, ball and camera, and registers every system in order.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'jump.system.ts',
-          content: jumpSystemCode,
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-terrain.ts',
+              summary:
+                'Generates the curved hills, their collider and the textured mesh that draws them.',
+              content: createTerrainCode,
+            },
+            {
+              name: 'create-player.ts',
+              summary:
+                'Creates the ball as a rigid body with gravity, friction and a spin motor.',
+              content: createPlayerCode,
+            },
+            {
+              name: 'create-inputs.ts',
+              summary: 'Binds A/D, the arrow keys and Space to roll and jump.',
+              content: createInputsCode,
+            },
+          ],
         },
         {
-          name: 'camera-follow.system.ts',
-          content: cameraFollowSystemCode,
+          title: 'Systems',
+          files: [
+            {
+              name: 'roll.system.ts',
+              summary: "Sets the ball motor's target spin from the roll input.",
+              content: rollSystemCode,
+            },
+            {
+              name: 'jump.system.ts',
+              summary:
+                'Jumps while touching the terrain and respawns the ball if it falls.',
+              content: jumpSystemCode,
+            },
+            {
+              name: 'camera-follow.system.ts',
+              summary: 'Eases the camera towards the ball every tick.',
+              content: cameraFollowSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/sensors/index.tsx b/documentation-site/src/pages/demos/sensors/index.tsx
index 537b58705..ffbbdcc65 100644
--- a/documentation-site/src/pages/demos/sensors/index.tsx
+++ b/documentation-site/src/pages/demos/sensors/index.tsx
@@ -7,29 +7,87 @@ import triggerZoneComponentCode from '!!raw-loader!./_trigger-zone.component';
 import triggerZoneSystemCode from '!!raw-loader!./_trigger-zone.system';
 import drainSystemCode from '!!raw-loader!./_drain.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function Sensors(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Sensors and Contacts Demo',
-        description:
-          'A demo showcasing sensor colliders and per-entity contacts.',
-      }}
-      header="Sensors and Contacts"
-      blurb="Balls fall through a world of solid and sensor colliders. The grey walls and ramps are ordinary colliders that balls bounce off. The two colored bands are sensors: the narrow phase detects balls overlapping them but never resolves those overlaps, so balls fall straight through. Each band has a ContactsEcsComponent, and a small system reads it every tick, tinting a ball when it starts touching the band, resetting it when the contact ends, and brightening the band while anything is inside. A sensor drain below the bottom edge removes every ball it starts touching. The zones and the drain use a collision mask that only accepts balls, so they never report the walls they touch."
+    <DemoPage
+      slug="sensors"
       createGame={createSensorsGame}
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'create-scene.ts', content: createSceneCode },
+      highlights={[
         {
-          name: 'trigger-zone.component.ts',
-          content: triggerZoneComponentCode,
+          text: 'The grey walls and ramps are ordinary colliders, so the falling balls bounce off them.',
+          file: 'create-scene.ts',
+        },
+        {
+          text: 'The colored bands are sensors: the narrow phase detects overlaps but never resolves them, so balls fall straight through.',
+          file: 'create-scene.ts',
+        },
+        {
+          text: 'Each band reads its contacts every tick, tinting a ball when it enters, resetting it when it leaves, and brightening while occupied.',
+          file: 'trigger-zone.system.ts',
+        },
+        {
+          text: 'A sensor drain below the bottom edge removes every ball that starts touching it.',
+          file: 'drain.system.ts',
+        },
+        {
+          text: 'The bands and drain use a collision mask that only accepts balls, so they never report the walls they touch.',
+          file: 'create-scene.ts',
+        },
+      ]}
+      docLinks={[{ label: 'Collisions', to: '/docs/docs/physics/collisions' }]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the camera and scene, and registers every system in the order they run.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-scene.ts',
+              summary:
+                'Creates the solid walls and ramps, the two sensor bands and the drain.',
+              content: createSceneCode,
+            },
+            {
+              name: 'ball-spawner.system.ts',
+              summary:
+                'Drops a new ball from above the scene every fifth of a second.',
+              content: ballSpawnerSystemCode,
+            },
+          ],
+        },
+        {
+          title: 'Sensors',
+          files: [
+            {
+              name: 'trigger-zone.component.ts',
+              summary: 'The tint a sensor band gives balls inside it.',
+              content: triggerZoneComponentCode,
+            },
+            {
+              name: 'trigger-zone.system.ts',
+              summary:
+                "Reads each band's contacts to tint balls and brighten the band.",
+              content: triggerZoneSystemCode,
+            },
+            {
+              name: 'drain.system.ts',
+              summary:
+                'Removes every ball that starts touching the drain sensor.',
+              content: drainSystemCode,
+            },
+          ],
         },
-        { name: 'trigger-zone.system.ts', content: triggerZoneSystemCode },
-        { name: 'drain.system.ts', content: drainSystemCode },
-        { name: 'ball-spawner.system.ts', content: ballSpawnerSystemCode },
       ]}
     />
   );
diff --git a/documentation-site/src/pages/demos/space-shooter/_BloomControls.module.css b/documentation-site/src/pages/demos/space-shooter/_BloomControls.module.css
index 0d4e02e8c..1cf07f114 100644
--- a/documentation-site/src/pages/demos/space-shooter/_BloomControls.module.css
+++ b/documentation-site/src/pages/demos/space-shooter/_BloomControls.module.css
@@ -1,20 +1,13 @@
 .container {
   display: flex;
-  flex-wrap: wrap;
-  gap: 16px;
-  align-items: center;
-  padding: 8px 12px;
-  margin-right: 10px;
-  vertical-align: top;
-
-  background-color: var(--card-background-color);
+  flex-direction: column;
+  gap: 10px;
 }
 
 .control {
   display: flex;
   flex-direction: column;
   gap: 2px;
-  min-width: 140px;
 }
 
 .control label {
diff --git a/documentation-site/src/pages/demos/space-shooter/_GaussianBlurControls.module.css b/documentation-site/src/pages/demos/space-shooter/_GaussianBlurControls.module.css
index 0d4e02e8c..1cf07f114 100644
--- a/documentation-site/src/pages/demos/space-shooter/_GaussianBlurControls.module.css
+++ b/documentation-site/src/pages/demos/space-shooter/_GaussianBlurControls.module.css
@@ -1,20 +1,13 @@
 .container {
   display: flex;
-  flex-wrap: wrap;
-  gap: 16px;
-  align-items: center;
-  padding: 8px 12px;
-  margin-right: 10px;
-  vertical-align: top;
-
-  background-color: var(--card-background-color);
+  flex-direction: column;
+  gap: 10px;
 }
 
 .control {
   display: flex;
   flex-direction: column;
   gap: 2px;
-  min-width: 140px;
 }
 
 .control label {
diff --git a/documentation-site/src/pages/demos/space-shooter/index.tsx b/documentation-site/src/pages/demos/space-shooter/index.tsx
index 96f9d51f0..ff555a1b9 100644
--- a/documentation-site/src/pages/demos/space-shooter/index.tsx
+++ b/documentation-site/src/pages/demos/space-shooter/index.tsx
@@ -39,12 +39,10 @@ import collisionCategoriesCode from '!!raw-loader!./_collision-categories';
 import gameOverComponentCode from '!!raw-loader!./_game-over.component';
 import gameOverSystemCode from '!!raw-loader!./_game-over.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage, DemoPanel } from '@site/src/components/demo-page';
 import type { CreateDemoGame } from '@site/src/hooks/useGame';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
 
-export default function Rendering(): JSX.Element {
+export default function SpaceShooter(): JSX.Element {
   const bloomRef = useRef<BloomEcsComponent | null>(null);
   const [threshold, setThreshold] = useState(bloomDefaults.threshold);
   const [passes, setPasses] = useState(bloomDefaults.passes);
@@ -166,171 +164,269 @@ export default function Rendering(): JSX.Element {
   };
 
   return (
-    <Demo
-      metaData={{
-        title: 'Space Shooter Demo',
-        description: 'A demo showcasing a full space shooter game.',
-      }}
-      header="Space Shooter"
-      blurb="This demo showcases a complete space shooter game built using the Forge Game Engine. It features player-controlled movement, shooting mechanics, enemy spawning, and collision detection. The game demonstrates how to leverage the engine's capabilities to create an engaging and interactive experience. Players can navigate their spaceship, avoid obstacles, and shoot down enemies while enjoying smooth rendering and responsive controls."
+    <DemoPage
+      slug="space-shooter"
       createGame={createGame}
-      codeFiles={[
+      controls={[
+        { inputs: ['WASD', '↑↓←→'], action: 'Move' },
         {
-          name: 'game.ts',
-          content: gameCode,
+          inputs: ['Space', { device: 'mouse', label: 'Left button' }],
+          action: 'Shoot',
+          detail: 'Hold to keep firing',
         },
         {
-          name: 'asteroid-spawner.component.ts',
-          content: asteroidSpawnerComponentCode,
-        },
-        {
-          name: 'asteroid-spawner.system.ts',
-          content: asteroidSpawnerSystemCode,
-        },
-        {
-          name: 'asteroid.component.ts',
-          content: asteroidComponentCode,
-        },
-        {
-          name: 'asteroid.system.ts',
-          content: asteroidSystemCode,
-        },
-        {
-          name: 'background.component.ts',
-          content: backgroundComponentCode,
-        },
-        {
-          name: 'background.shader.ts',
-          content: backgroundShaderCode,
-        },
-        {
-          name: 'background.system.ts',
-          content: backgroundSystemCode,
-        },
-        {
-          name: 'bullet.component.ts',
-          content: bulletComponentCode,
-        },
-        {
-          name: 'bullet.system.ts',
-          content: bulletSystemCode,
-        },
-        {
-          name: 'camera-shake.component.ts',
-          content: cameraShakeComponentCode,
-        },
-        {
-          name: 'camera-shake.system.ts',
-          content: cameraShakeSystemCode,
-        },
-        {
-          name: 'collision-categories.ts',
-          content: collisionCategoriesCode,
-        },
-        {
-          name: 'collision.system.ts',
-          content: collisionSystemCode,
+          inputs: ['R'],
+          action: 'Restart',
+          detail: 'After the ship is destroyed',
         },
+      ]}
+      panels={
+        <>
+          <DemoPanel title="Bloom" icon="fa-sliders">
+            <BloomControls
+              enabled={bloomEnabled}
+              threshold={threshold}
+              passes={passes}
+              intensity={intensity}
+              onEnabledChange={handleBloomEnabledChange}
+              onThresholdChange={handleThresholdChange}
+              onPassesChange={handlePassesChange}
+              onIntensityChange={handleIntensityChange}
+            />
+          </DemoPanel>
+          <DemoPanel title="Background blur" icon="fa-sliders">
+            <GaussianBlurControls
+              enabled={blurEnabled}
+              passes={blurPasses}
+              intensity={blurIntensity}
+              onEnabledChange={handleBlurEnabledChange}
+              onPassesChange={handleBlurPassesChange}
+              onIntensityChange={handleBlurIntensityChange}
+            />
+          </DemoPanel>
+          <DemoPanel title="Audio" icon="fa-volume-high">
+            <AudioControls
+              musicVolume={musicVolume}
+              sfxVolume={sfxVolume}
+              muted={muted}
+              onMusicVolumeChange={handleMusicVolumeChange}
+              onSfxVolumeChange={handleSfxVolumeChange}
+              onMutedChange={handleMutedChange}
+            />
+          </DemoPanel>
+        </>
+      }
+      highlights={[
         {
-          name: 'create-asteroids.ts',
-          content: createAsteroidsCode,
+          text: 'Bullets carry an emissive map and the foreground renders in HDR, so bloom makes only the bullets glow.',
+          file: 'create-player.ts',
         },
         {
-          name: 'create-background.ts',
-          content: createBackgroundMaterialCode,
+          text: 'The background and foreground render to separate targets, so the blur softens the nebula while the ship stays sharp.',
+          file: 'create-game.ts',
         },
         {
-          name: 'create-explosions.ts',
-          content: createExplosionsCode,
+          text: 'Collision categories make asteroids test only against bullets and the ship, and their contacts decide what explodes.',
+          file: 'collision.system.ts',
         },
         {
-          name: 'create-inputs.ts',
-          content: createInputsCode,
+          text: 'Explosions are sprite-sheet animations that remove themselves when their lifetime ends, and they shake the camera.',
+          file: 'create-explosions.ts',
         },
         {
-          name: 'create-music.ts',
-          content: createMusicCode,
+          text: 'Music and sound effects play on separate mixer buses, which is what the audio sliders control.',
+          file: 'create-music.ts',
         },
+      ]}
+      docLinks={[
+        { label: 'Bloom', to: '/docs/docs/rendering/bloom' },
+        { label: 'Gaussian blur', to: '/docs/docs/rendering/gaussian-blur' },
+        { label: 'Collisions', to: '/docs/docs/physics/collisions' },
+        { label: 'Mixer and buses', to: '/docs/docs/audio/mixer-and-buses' },
+      ]}
+      fileGroups={[
         {
-          name: 'create-player.ts',
-          content: createPlayerCode,
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up audio, render targets, cameras and post-processing, and registers every system.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'game-over.component.ts',
-          content: gameOverComponentCode,
+          title: 'Player',
+          files: [
+            {
+              name: 'create-inputs.ts',
+              summary:
+                'Binds WASD, the arrow keys, Space, the mouse and R to game actions.',
+              content: createInputsCode,
+            },
+            {
+              name: 'create-player.ts',
+              summary:
+                'Loads the ship and glowing bullet sprites and spawns the ship.',
+              content: createPlayerCode,
+            },
+            {
+              name: 'player.component.ts',
+              summary: "The ship's speed and the bounds it can move within.",
+              content: playerComponentCode,
+            },
+            {
+              name: 'movement.system.ts',
+              summary: 'Moves the ship with the input, clamped to the screen.',
+              content: movementSystemCode,
+            },
+          ],
         },
         {
-          name: 'game-over.system.ts',
-          content: gameOverSystemCode,
+          title: 'Shooting',
+          files: [
+            {
+              name: 'gun.component.ts',
+              summary: 'The fire rate and bullet sprite for a gun.',
+              content: gunComponentCode,
+            },
+            {
+              name: 'gun.system.ts',
+              summary:
+                'Fires a pair of bullets and a laser sound while shoot is held.',
+              content: gunSystemCode,
+            },
+            {
+              name: 'bullet.component.ts',
+              summary: "A bullet's speed.",
+              content: bulletComponentCode,
+            },
+            {
+              name: 'bullet.system.ts',
+              summary: 'Moves bullets up the screen.',
+              content: bulletSystemCode,
+            },
+          ],
         },
         {
-          name: 'gun.component.ts',
-          content: gunComponentCode,
+          title: 'Asteroids',
+          files: [
+            {
+              name: 'create-asteroids.ts',
+              summary:
+                'Loads the asteroid sprites and creates the spawner above the screen.',
+              content: createAsteroidsCode,
+            },
+            {
+              name: 'asteroid-spawner.component.ts',
+              summary:
+                'Spawn rate, area, speeds and sprites for new asteroids.',
+              content: asteroidSpawnerComponentCode,
+            },
+            {
+              name: 'asteroid-spawner.system.ts',
+              summary:
+                'Spawns asteroids with a random sprite, position and speed.',
+              content: asteroidSpawnerSystemCode,
+            },
+            {
+              name: 'asteroid.component.ts',
+              summary: "An asteroid's fall and spin speed.",
+              content: asteroidComponentCode,
+            },
+            {
+              name: 'asteroid.system.ts',
+              summary:
+                'Moves and spins asteroids, and removes them once off screen.',
+              content: asteroidSystemCode,
+            },
+          ],
         },
         {
-          name: 'gun.system.ts',
-          content: gunSystemCode,
+          title: 'Collisions and game over',
+          files: [
+            {
+              name: 'collision-categories.ts',
+              summary:
+                'Collision category bits for asteroids, bullets and the ship.',
+              content: collisionCategoriesCode,
+            },
+            {
+              name: 'collision.system.ts',
+              summary:
+                'Explodes asteroids hit by bullets, and destroys the ship on contact.',
+              content: collisionSystemCode,
+            },
+            {
+              name: 'game-over.component.ts',
+              summary: 'Whether the game is over, and the restart message.',
+              content: gameOverComponentCode,
+            },
+            {
+              name: 'game-over.system.ts',
+              summary:
+                'Shows the restart message and resets the round when R is pressed.',
+              content: gameOverSystemCode,
+            },
+          ],
         },
         {
-          name: 'movement.system.ts',
-          content: movementSystemCode,
+          title: 'Effects and audio',
+          files: [
+            {
+              name: 'create-explosions.ts',
+              summary:
+                'Builds the explosion animation and spawns explosions with sound and shake.',
+              content: createExplosionsCode,
+            },
+            {
+              name: 'camera-shake.component.ts',
+              summary:
+                'The strength, duration and current offset of a camera shake.',
+              content: cameraShakeComponentCode,
+            },
+            {
+              name: 'camera-shake.system.ts',
+              summary: 'Jolts the camera with fading random offsets.',
+              content: cameraShakeSystemCode,
+            },
+            {
+              name: 'create-music.ts',
+              summary: 'Plays the looping background music on the music bus.',
+              content: createMusicCode,
+            },
+          ],
         },
         {
-          name: 'player.component.ts',
-          content: playerComponentCode,
+          title: 'Background',
+          files: [
+            {
+              name: 'create-background.ts',
+              summary:
+                'Creates a full-screen sprite drawn with the nebula shader.',
+              content: createBackgroundMaterialCode,
+            },
+            {
+              name: 'background.component.ts',
+              summary: 'A tag that marks the background entity.',
+              content: backgroundComponentCode,
+            },
+            {
+              name: 'background.system.ts',
+              summary:
+                'Updates the shader time and resizes the background with the canvas.',
+              content: backgroundSystemCode,
+            },
+            {
+              name: 'background.shader.ts',
+              summary:
+                'Draws twinkling, scrolling star layers over a scrolling nebula texture.',
+              content: backgroundShaderCode,
+            },
+          ],
         },
       ]}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="A" />}
-            text="Left"
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="D" />}
-            text="Right"
-          />
-
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="␣" />}
-            text="Shoot"
-          />
-
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="R" />}
-            text="Restart (after death)"
-          />
-
-          <BloomControls
-            enabled={bloomEnabled}
-            threshold={threshold}
-            passes={passes}
-            intensity={intensity}
-            onEnabledChange={handleBloomEnabledChange}
-            onThresholdChange={handleThresholdChange}
-            onPassesChange={handlePassesChange}
-            onIntensityChange={handleIntensityChange}
-          />
-
-          <GaussianBlurControls
-            enabled={blurEnabled}
-            passes={blurPasses}
-            intensity={blurIntensity}
-            onEnabledChange={handleBlurEnabledChange}
-            onPassesChange={handleBlurPassesChange}
-            onIntensityChange={handleBlurIntensityChange}
-          />
-
-          <AudioControls
-            musicVolume={musicVolume}
-            sfxVolume={sfxVolume}
-            muted={muted}
-            onMusicVolumeChange={handleMusicVolumeChange}
-            onSfxVolumeChange={handleSfxVolumeChange}
-            onMutedChange={handleMutedChange}
-          />
-        </>
-      }
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/stress-test/index.tsx b/documentation-site/src/pages/demos/stress-test/index.tsx
index 301072467..fc381400e 100644
--- a/documentation-site/src/pages/demos/stress-test/index.tsx
+++ b/documentation-site/src/pages/demos/stress-test/index.tsx
@@ -6,39 +6,80 @@ import spriteSpawnerComponentCode from '!!raw-loader!./_sprite-spawner.component
 import spriteSpawnerSystemCode from '!!raw-loader!./_sprite-spawner.system';
 import fpsMonitorSystemCode from '!!raw-loader!./_fps-monitor.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function StressTest(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Stress Test Demo',
-        description:
-          'A demo that stress tests the rendering pipeline by spawning sprites until the frame rate drops.',
-      }}
-      header="Stress Test"
-      blurb="This demo spawns batches of sprites at a regular interval, growing the sprite count over time. Open the browser console to see how many sprites had been spawned when the frame rate first dropped below 100, 60 and 30 FPS. Spawning stops once the frame rate drops below 30."
+    <DemoPage
+      slug="stress-test"
       createGame={createStressTestGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'Every tenth of a second, a spawner adds 100 more sprites at random positions.',
+          file: 'sprite-spawner.system.ts',
         },
         {
-          name: 'create-sprite-spawner.ts',
-          content: createSpriteSpawnerCode,
+          text: 'All the sprites share one texture, so the renderer can batch them into instanced draws.',
+          file: 'create-sprite-spawner.ts',
         },
         {
-          name: 'sprite-spawner.component.ts',
-          content: spriteSpawnerComponentCode,
+          text: 'Open the browser console to see the sprite count when the frame rate first drops below 100, 60 and 30 FPS.',
+          file: 'fps-monitor.system.ts',
         },
         {
-          name: 'sprite-spawner.system.ts',
-          content: spriteSpawnerSystemCode,
+          text: 'Spawning stops once the frame rate falls below 30 FPS.',
+          file: 'fps-monitor.system.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Sprites', to: '/docs/docs/rendering/sprites' },
+        { label: 'Time', to: '/docs/docs/common/time' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Creates the spawner and registers the spawn, render and FPS systems.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Spawning sprites',
+          files: [
+            {
+              name: 'create-sprite-spawner.ts',
+              summary:
+                'Loads the star sprite and creates the spawner across the camera view.',
+              content: createSpriteSpawnerCode,
+            },
+            {
+              name: 'sprite-spawner.component.ts',
+              summary:
+                'The batch size, timing, bounds and count of the spawner.',
+              content: spriteSpawnerComponentCode,
+            },
+            {
+              name: 'sprite-spawner.system.ts',
+              summary:
+                'Spawns a batch of sprites at random positions on a fixed interval.',
+              content: spriteSpawnerSystemCode,
+            },
+          ],
         },
         {
-          name: 'fps-monitor.system.ts',
-          content: fpsMonitorSystemCode,
+          title: 'Measuring',
+          files: [
+            {
+              name: 'fps-monitor.system.ts',
+              summary:
+                'Logs the sprite count at each FPS threshold and stops the spawner.',
+              content: fpsMonitorSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/text/_PlaygroundControls.module.css b/documentation-site/src/pages/demos/text/_PlaygroundControls.module.css
deleted file mode 100644
index fd6983192..000000000
--- a/documentation-site/src/pages/demos/text/_PlaygroundControls.module.css
+++ /dev/null
@@ -1,54 +0,0 @@
-.container {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 16px;
-  align-items: center;
-  padding: 8px 12px;
-  margin-right: 10px;
-  vertical-align: top;
-
-  background-color: var(--card-background-color);
-}
-
-.control {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-  min-width: 140px;
-}
-
-.textControl {
-  min-width: 260px;
-  flex-grow: 1;
-}
-
-.effectGroup {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 16px;
-  align-items: center;
-  padding-left: 12px;
-  border-left: 1px solid var(--ifm-color-emphasis-300);
-}
-
-.control label {
-  display: flex;
-  justify-content: space-between;
-  gap: 8px;
-  font-size: 0.85rem;
-}
-
-.control input[type='range'],
-.control input[type='checkbox'] {
-  accent-color: var(--ifm-color-primary);
-}
-
-.control input[type='text'],
-.control select {
-  font: inherit;
-  padding: 4px 6px;
-  border: 1px solid var(--ifm-color-emphasis-300);
-  border-radius: 4px;
-  background-color: var(--ifm-background-color);
-  color: var(--ifm-font-color-base);
-}
diff --git a/documentation-site/src/pages/demos/text/_PlaygroundControls.tsx b/documentation-site/src/pages/demos/text/_PlaygroundControls.tsx
index 3fb9411d7..fa230d2ea 100644
--- a/documentation-site/src/pages/demos/text/_PlaygroundControls.tsx
+++ b/documentation-site/src/pages/demos/text/_PlaygroundControls.tsx
@@ -1,274 +1,154 @@
-import React, { ChangeEvent, FC } from 'react';
-import { PlaygroundHorizontalAlign } from './_create-playground';
-import styles from './_PlaygroundControls.module.css';
+import React, { FC } from 'react';
+import {
+  DemoChoice,
+  DemoSettings,
+  DemoSettingsSection,
+  DemoSlider,
+  DemoTextField,
+  DemoToggle,
+} from '@site/src/components/demo-page';
+import {
+  TextHorizontalAlign,
+  TextVerticalAlign,
+} from '@forge-game-engine/forge/text';
+import {
+  playgroundMaxWrapWidth,
+  PlaygroundSettings,
+} from './_create-playground';
+
+const horizontalAlignOptions: { value: TextHorizontalAlign; label: string }[] =
+  [
+    { value: 'left', label: 'Left' },
+    { value: 'center', label: 'Center' },
+    { value: 'right', label: 'Right' },
+    { value: 'justify', label: 'Justify' },
+  ];
+
+const verticalAlignOptions: { value: TextVerticalAlign; label: string }[] = [
+  { value: 'top', label: 'Top' },
+  { value: 'capline', label: 'Capline' },
+  { value: 'middle', label: 'Middle' },
+  { value: 'baseline', label: 'Baseline' },
+  { value: 'bottom', label: 'Bottom' },
+];
+
+const oneDecimal = (value: number): string => value.toFixed(1);
 
 interface PlaygroundControlsProps {
-  text: string;
-  size: number;
-  minSize: number;
-  maxSize: number;
-  horizontalAlign: PlaygroundHorizontalAlign;
-  wrapEnabled: boolean;
-
-  outlineEnabled: boolean;
-  outlineWidth: number;
-  minOutlineWidth: number;
-  maxOutlineWidth: number;
-
-  glowEnabled: boolean;
-  glowOffsetX: number;
-  glowOffsetY: number;
-  minGlowOffset: number;
-  maxGlowOffset: number;
-  glowSoftness: number;
-  minGlowSoftness: number;
-  maxGlowSoftness: number;
-
-  onTextChange: (value: string) => void;
-  onSizeChange: (value: number) => void;
-  onHorizontalAlignChange: (value: PlaygroundHorizontalAlign) => void;
-  onWrapEnabledChange: (value: boolean) => void;
-
-  onOutlineEnabledChange: (value: boolean) => void;
-  onOutlineWidthChange: (value: number) => void;
-
-  onGlowEnabledChange: (value: boolean) => void;
-  onGlowOffsetXChange: (value: number) => void;
-  onGlowOffsetYChange: (value: number) => void;
-  onGlowSoftnessChange: (value: number) => void;
+  settings: PlaygroundSettings;
+  onChange: (change: Partial<PlaygroundSettings>) => void;
 }
 
 /**
- * Live controls for the text demo's "Try it yourself" playground: a text
- * input, a size slider, an alignment select (only meaningful while wrapping
- * is on - `TextEcsComponent.horizontalAlign` is otherwise ignored, see
- * `text-component.ts`), a wrap toggle, and outline/glow controls (enabled
- * toggle plus width/offset/softness - color is fixed, not user-controllable;
- * an `<input type="color">` control was tried here and dropped for being
- * noticeably slow to interact with). Every change writes straight into the
- * running playground's `TextEcsComponent` (see `index.tsx`'s handlers and
- * `_create-playground.ts`), the same way the space-shooter demo's bloom/blur
- * controls retune their components live.
+ * The settings beside the text demo's canvas. Each change is written into
+ * the running text straight away.
  */
 export const PlaygroundControls: FC<PlaygroundControlsProps> = ({
-  text,
-  size,
-  minSize,
-  maxSize,
-  horizontalAlign,
-  wrapEnabled,
-  outlineEnabled,
-  outlineWidth,
-  minOutlineWidth,
-  maxOutlineWidth,
-  glowEnabled,
-  glowOffsetX,
-  glowOffsetY,
-  minGlowOffset,
-  maxGlowOffset,
-  glowSoftness,
-  minGlowSoftness,
-  maxGlowSoftness,
-  onTextChange,
-  onSizeChange,
-  onHorizontalAlignChange,
-  onWrapEnabledChange,
-  onOutlineEnabledChange,
-  onOutlineWidthChange,
-  onGlowEnabledChange,
-  onGlowOffsetXChange,
-  onGlowOffsetYChange,
-  onGlowSoftnessChange,
+  settings,
+  onChange,
 }) => {
-  const handleTextChange = (event: ChangeEvent<HTMLInputElement>) => {
-    onTextChange(event.target.value);
-  };
-
-  const handleSizeChange = (event: ChangeEvent<HTMLInputElement>) => {
-    onSizeChange(Number(event.target.value));
-  };
-
-  const handleHorizontalAlignChange = (
-    event: ChangeEvent<HTMLSelectElement>,
-  ) => {
-    onHorizontalAlignChange(event.target.value as PlaygroundHorizontalAlign);
-  };
-
-  const handleWrapEnabledChange = (event: ChangeEvent<HTMLInputElement>) => {
-    onWrapEnabledChange(event.target.checked);
-  };
-
-  const handleOutlineEnabledChange = (event: ChangeEvent<HTMLInputElement>) => {
-    onOutlineEnabledChange(event.target.checked);
-  };
-
-  const handleOutlineWidthChange = (event: ChangeEvent<HTMLInputElement>) => {
-    onOutlineWidthChange(Number(event.target.value));
-  };
-
-  const handleGlowEnabledChange = (event: ChangeEvent<HTMLInputElement>) => {
-    onGlowEnabledChange(event.target.checked);
-  };
-
-  const handleGlowOffsetXChange = (event: ChangeEvent<HTMLInputElement>) => {
-    onGlowOffsetXChange(Number(event.target.value));
-  };
-
-  const handleGlowOffsetYChange = (event: ChangeEvent<HTMLInputElement>) => {
-    onGlowOffsetYChange(Number(event.target.value));
-  };
-
-  const handleGlowSoftnessChange = (event: ChangeEvent<HTMLInputElement>) => {
-    onGlowSoftnessChange(Number(event.target.value));
-  };
-
   return (
-    <div className={styles.container}>
-      <div className={`${styles.control} ${styles.textControl}`}>
-        <label htmlFor="playground-text">
-          <span>Text</span>
-        </label>
-        <input
-          id="playground-text"
-          type="text"
-          value={text}
-          onChange={handleTextChange}
+    <DemoSettings>
+      <DemoTextField
+        label="Text"
+        rows={3}
+        value={settings.text}
+        onChange={(text) => onChange({ text })}
+      />
+      <DemoToggle
+        label="Rich text tags (<b>, <color>)"
+        checked={settings.richText}
+        onChange={(richText) => onChange({ richText })}
+      />
+
+      <DemoSettingsSection title="Layout">
+        <DemoSlider
+          label="Size"
+          value={settings.size}
+          min={12}
+          max={64}
+          onChange={(size) => onChange({ size })}
         />
-      </div>
-      <div className={styles.control}>
-        <label htmlFor="playground-size">
-          <span>Size</span>
-          <span>{size}</span>
-        </label>
-        <input
-          id="playground-size"
-          type="range"
-          min={minSize}
-          max={maxSize}
-          step={1}
-          value={size}
-          onChange={handleSizeChange}
+        <DemoSlider
+          label="Wrap width"
+          value={settings.wrapWidth}
+          min={120}
+          max={playgroundMaxWrapWidth}
+          onChange={(wrapWidth) => onChange({ wrapWidth })}
         />
-      </div>
-      <div className={styles.control}>
-        <label htmlFor="playground-align">
-          <span>Align</span>
-        </label>
-        <select
-          id="playground-align"
-          value={horizontalAlign}
-          disabled={!wrapEnabled}
-          onChange={handleHorizontalAlignChange}
-        >
-          <option value="left">Left</option>
-          <option value="center">Center</option>
-          <option value="right">Right</option>
-          <option value="justify">Justify</option>
-        </select>
-      </div>
-      <div className={styles.control}>
-        <label htmlFor="playground-wrap">
-          <span>Wrap</span>
-        </label>
-        <input
-          id="playground-wrap"
-          type="checkbox"
-          checked={wrapEnabled}
-          onChange={handleWrapEnabledChange}
+        <DemoSlider
+          label="Line height"
+          value={settings.lineHeight}
+          min={0.6}
+          max={2}
+          step={0.1}
+          format={oneDecimal}
+          onChange={(lineHeight) => onChange({ lineHeight })}
+        />
+        <DemoChoice
+          label="Horizontal align"
+          value={settings.horizontalAlign}
+          options={horizontalAlignOptions}
+          onChange={(horizontalAlign) => onChange({ horizontalAlign })}
+        />
+        <DemoChoice
+          label="Vertical align (to the orange line)"
+          value={settings.verticalAlign}
+          options={verticalAlignOptions}
+          onChange={(verticalAlign) => onChange({ verticalAlign })}
         />
-      </div>
+      </DemoSettingsSection>
 
-      <div className={styles.effectGroup}>
-        <div className={styles.control}>
-          <label htmlFor="playground-outline">
-            <span>Outline</span>
-          </label>
-          <input
-            id="playground-outline"
-            type="checkbox"
-            checked={outlineEnabled}
-            onChange={handleOutlineEnabledChange}
-          />
-        </div>
-        <div className={styles.control}>
-          <label htmlFor="playground-outline-width">
-            <span>Width</span>
-            <span>{outlineWidth.toFixed(1)}</span>
-          </label>
-          <input
-            id="playground-outline-width"
-            type="range"
-            min={minOutlineWidth}
-            max={maxOutlineWidth}
+      <DemoSettingsSection title="Effects">
+        <DemoToggle
+          label="Outline"
+          checked={settings.outline}
+          onChange={(outline) => onChange({ outline })}
+        >
+          <DemoSlider
+            label="Width"
+            value={settings.outlineWidth}
+            min={0.1}
+            max={4}
             step={0.1}
-            value={outlineWidth}
-            disabled={!outlineEnabled}
-            onChange={handleOutlineWidthChange}
+            format={oneDecimal}
+            onChange={(outlineWidth) => onChange({ outlineWidth })}
           />
-        </div>
-      </div>
-
-      <div className={styles.effectGroup}>
-        <div className={styles.control}>
-          <label htmlFor="playground-glow">
-            <span>Glow</span>
-          </label>
-          <input
-            id="playground-glow"
-            type="checkbox"
-            checked={glowEnabled}
-            onChange={handleGlowEnabledChange}
-          />
-        </div>
-        <div className={styles.control}>
-          <label htmlFor="playground-glow-offset-x">
-            <span>Offset X</span>
-            <span>{glowOffsetX.toFixed(1)}</span>
-          </label>
-          <input
-            id="playground-glow-offset-x"
-            type="range"
-            min={minGlowOffset}
-            max={maxGlowOffset}
+        </DemoToggle>
+        <DemoToggle
+          label="Glow"
+          checked={settings.glow}
+          onChange={(glow) => onChange({ glow })}
+        >
+          <DemoSlider
+            label="Offset X"
+            value={settings.glowOffsetX}
+            min={-3}
+            max={3}
             step={0.1}
-            value={glowOffsetX}
-            disabled={!glowEnabled}
-            onChange={handleGlowOffsetXChange}
+            format={oneDecimal}
+            onChange={(glowOffsetX) => onChange({ glowOffsetX })}
           />
-        </div>
-        <div className={styles.control}>
-          <label htmlFor="playground-glow-offset-y">
-            <span>Offset Y</span>
-            <span>{glowOffsetY.toFixed(1)}</span>
-          </label>
-          <input
-            id="playground-glow-offset-y"
-            type="range"
-            min={minGlowOffset}
-            max={maxGlowOffset}
+          <DemoSlider
+            label="Offset Y"
+            value={settings.glowOffsetY}
+            min={-3}
+            max={3}
             step={0.1}
-            value={glowOffsetY}
-            disabled={!glowEnabled}
-            onChange={handleGlowOffsetYChange}
+            format={oneDecimal}
+            onChange={(glowOffsetY) => onChange({ glowOffsetY })}
           />
-        </div>
-        <div className={styles.control}>
-          <label htmlFor="playground-glow-softness">
-            <span>Softness</span>
-            <span>{glowSoftness.toFixed(1)}</span>
-          </label>
-          <input
-            id="playground-glow-softness"
-            type="range"
-            min={minGlowSoftness}
-            max={maxGlowSoftness}
+          <DemoSlider
+            label="Softness"
+            value={settings.glowSoftness}
+            min={0}
+            max={4}
             step={0.1}
-            value={glowSoftness}
-            disabled={!glowEnabled}
-            onChange={handleGlowSoftnessChange}
+            format={oneDecimal}
+            onChange={(glowSoftness) => onChange({ glowSoftness })}
           />
-        </div>
-      </div>
-    </div>
+        </DemoToggle>
+      </DemoSettingsSection>
+    </DemoSettings>
   );
 };
diff --git a/documentation-site/src/pages/demos/text/_create-effects-examples.ts b/documentation-site/src/pages/demos/text/_create-effects-examples.ts
deleted file mode 100644
index 067710af4..000000000
--- a/documentation-site/src/pages/demos/text/_create-effects-examples.ts
+++ /dev/null
@@ -1,161 +0,0 @@
-import { addPositionComponent } from '@forge-game-engine/forge/common';
-import { EcsWorld } from '@forge-game-engine/forge/ecs';
-import { Vector2 } from '@forge-game-engine/forge/math';
-import { Color, SpriteEcsComponent } from '@forge-game-engine/forge/rendering';
-import {
-  addTextComponent,
-  FontAtlas,
-  shapeText,
-} from '@forge-game-engine/forge/text';
-import { createGuideBox } from './_create-guide-box';
-
-// A short, ordinary phrase - deliberately not pushed toward this atlas's
-// worst-case glyphs (acute-corner caps, tight counters) or toward the edge
-// of the documented safe outline/shadow range. See
-// `documentation-site/docs/docs/text/text-effects.md`'s "Choosing a safe
-// range" section for why this demo stays conservative rather than
-// showcasing the effect's absolute maximum.
-const sampleText = 'Forge Engine';
-const bodySize = 22;
-const captionSize = 13;
-const captionColor = new Color(0.55, 0.6, 0.72, 1);
-const bodyColor = new Color(0.85, 0.87, 0.92, 1);
-const captionGap = 14;
-const columnGap = 18;
-
-// Both `outlineWidth` and `shadowSoftness`/`shadowOffset` are bounded only
-// by the atlas's own encoded budget (see text-effects.md's "Choosing a
-// safe range") - each renders at the same, uniform strength on every
-// glyph regardless of how tightly its neighbors are kerned, including "rg"
-// in "Forge", this atlas's tightest same-word pair. That budget is
-// smallest at small on-screen sizes, so caption text only ever has a
-// little of it to spend - these values deliberately stay conservative
-// rather than pushing toward it. See the hero example below for what a
-// bigger, bolder effect looks like once the text itself is rendered large
-// enough to afford more.
-const outlineWidth = 1;
-const shadowSoftness = 1.2;
-const shadowOffset: Vector2 = { x: 0.8, y: -0.8 };
-
-interface EffectsColumn {
-  label: string;
-  outlineColor: Color;
-  outlineWidth: number;
-  shadowColor: Color;
-  shadowOffset: Vector2;
-  shadowSoftness: number;
-}
-
-const transparent = Color.transparent;
-
-const columns: EffectsColumn[] = [
-  {
-    label: 'base (no effect)',
-    outlineColor: Color.black,
-    outlineWidth: 0,
-    shadowColor: transparent,
-    shadowOffset: { x: 0, y: 0 },
-    shadowSoftness: 0,
-  },
-  {
-    label: 'outline',
-    // A saturated, high-contrast color (not a realistic near-black outline)
-    // so the effect actually reads clearly at demo scale - the "safe"
-    // outlineWidth budget documented in text-effects.md is about *size*,
-    // not color, so this doesn't misrepresent it.
-    outlineColor: new Color(1, 0.55, 0.15, 1),
-    outlineWidth,
-    shadowColor: transparent,
-    shadowOffset: { x: 0, y: 0 },
-    shadowSoftness: 0,
-  },
-  {
-    label: 'soft shadow / glow',
-    outlineColor: Color.black,
-    outlineWidth: 0,
-    shadowColor: new Color(0.15, 0.65, 1, 0.95),
-    shadowOffset,
-    shadowSoftness,
-  },
-];
-
-/**
- * Builds a 3-column showcase of `TextEcsComponent`'s outline/soft-shadow
- * effects: unmodified text, an outlined column, and a soft-shadow/glow
- * column, all using the same conservative, documented-safe effect values
- * (see the module-level comments above) rather than this atlas's absolute
- * maximum.
- * @param world - The ECS world to add label entities to.
- * @param fontAtlas - The font atlas every label draws from.
- * @param whiteSprite - A plain white sprite template for the guide boxes.
- * @param guideLayer - The draw-order layer for guide boxes (drawn behind text).
- * @param contentLayer - The draw-order layer for captions/body text.
- * @param topLeft - This section's top-left corner, in world units.
- * @param usableWidth - The total width available to lay the 3 columns out in.
- * @returns The y coordinate immediately below the section's content, for
- * stacking the next section beneath it.
- */
-export function createEffectsExamples(
-  world: EcsWorld,
-  fontAtlas: FontAtlas,
-  whiteSprite: SpriteEcsComponent,
-  guideLayer: number,
-  contentLayer: number,
-  topLeft: Vector2,
-  usableWidth: number,
-): number {
-  const columnWidth =
-    (usableWidth - columnGap * (columns.length - 1)) / columns.length;
-  const boxTop = topLeft.y - captionGap;
-
-  // Sized from shapeText's own computed bounds (matching every other
-  // section in this demo), not guessed - `maxWidth: columnWidth` also
-  // guarantees the sample text can never visually overflow into the next
-  // column, whatever its wrapped height ends up being.
-  const { bounds } = shapeText(sampleText, fontAtlas.data, {
-    size: bodySize,
-    maxWidth: columnWidth,
-  });
-
-  columns.forEach((column, index) => {
-    const x = topLeft.x + index * (columnWidth + columnGap);
-
-    const captionEntity = world.createEntity();
-    addPositionComponent(world, captionEntity, {
-      local: { x, y: topLeft.y },
-    });
-    addTextComponent(world, captionEntity, {
-      text: column.label,
-      fontAtlas,
-      size: captionSize,
-      color: captionColor,
-      layer: contentLayer,
-    });
-
-    createGuideBox(
-      world,
-      whiteSprite,
-      { x, y: boxTop },
-      { x: columnWidth, y: bounds.height },
-      guideLayer,
-    );
-
-    const textEntity = world.createEntity();
-    addPositionComponent(world, textEntity, { local: { x, y: boxTop } });
-    addTextComponent(world, textEntity, {
-      text: sampleText,
-      fontAtlas,
-      size: bodySize,
-      maxWidth: columnWidth,
-      color: bodyColor,
-      layer: contentLayer,
-      outlineColor: column.outlineColor,
-      outlineWidth: column.outlineWidth,
-      shadowColor: column.shadowColor,
-      shadowOffset: column.shadowOffset,
-      shadowSoftness: column.shadowSoftness,
-    });
-  });
-
-  return boxTop - bounds.height;
-}
diff --git a/documentation-site/src/pages/demos/text/_create-effects-hero-example.ts b/documentation-site/src/pages/demos/text/_create-effects-hero-example.ts
deleted file mode 100644
index 05fb6c2f7..000000000
--- a/documentation-site/src/pages/demos/text/_create-effects-hero-example.ts
+++ /dev/null
@@ -1,102 +0,0 @@
-import { addPositionComponent } from '@forge-game-engine/forge/common';
-import { EcsWorld } from '@forge-game-engine/forge/ecs';
-import { Vector2 } from '@forge-game-engine/forge/math';
-import { Color, SpriteEcsComponent } from '@forge-game-engine/forge/rendering';
-import {
-  addTextComponent,
-  FontAtlas,
-  shapeText,
-} from '@forge-game-engine/forge/text';
-import { createGuideBox } from './_create-guide-box';
-
-// The safe outline/shadow budget is a fixed *fraction* of a glyph's
-// on-screen size - the atlas's own encoded distanceRange for `outlineWidth`,
-// and additionally, for a multi-letter word, its tightest same-word letter
-// gap for `shadowSoftness`/`shadowOffset` (see text-effects.md's "Choosing
-// a safe range") - so a large, clearly-visible effect needs correspondingly
-// large on-screen text, the same way a thick CSS text-stroke needs a large
-// font-size to read as anything but a smudge. This hero example renders one
-// big word specifically to prove that scaling relationship: at this size,
-// `outlineWidth`/`shadowSoftness` can go well beyond the small-caption
-// showcase above and still render at full, uncapped strength.
-const heroText = 'FORGE';
-const heroSize = 80;
-const captionSize = 13;
-const captionColor = new Color(0.55, 0.6, 0.72, 1);
-const bodyColor = new Color(0.85, 0.87, 0.92, 1);
-const captionGap = 14;
-
-const heroOutlineColor = new Color(1, 0.55, 0.15, 1);
-const heroOutlineWidth = 6;
-const heroShadowColor = new Color(0.15, 0.65, 1, 0.85);
-const heroShadowOffset: Vector2 = { x: 3, y: -3 };
-const heroShadowSoftness = 7;
-
-/**
- * Builds a single large "hero" word with both an outline and a soft
- * shadow/glow applied together, at a big enough on-screen size for
- * `outlineWidth`/`shadowSoftness` to read as genuinely large and soft,
- * proving the effect's size scales with the requested values (not silently
- * capped to a sliver) once there's enough room in the shaders' safe-distance
- * budgets (`msdf-effects.frag`) to actually use them.
- * @param world - The ECS world to add label entities to.
- * @param fontAtlas - The font atlas every label draws from.
- * @param whiteSprite - A plain white sprite template for the guide box.
- * @param guideLayer - The draw-order layer for the guide box (drawn behind text).
- * @param contentLayer - The draw-order layer for the caption/body text.
- * @param topLeft - This section's top-left corner, in world units.
- * @param usableWidth - The total width available to lay the example out in.
- * @returns The y coordinate immediately below the section's content.
- */
-export function createEffectsHeroExample(
-  world: EcsWorld,
-  fontAtlas: FontAtlas,
-  whiteSprite: SpriteEcsComponent,
-  guideLayer: number,
-  contentLayer: number,
-  topLeft: Vector2,
-  usableWidth: number,
-): number {
-  const boxTop = topLeft.y - captionGap;
-
-  const captionEntity = world.createEntity();
-  addPositionComponent(world, captionEntity, {
-    local: { x: topLeft.x, y: topLeft.y },
-  });
-  addTextComponent(world, captionEntity, {
-    text: `outline + soft shadow / glow together, at a larger size (outlineWidth: ${heroOutlineWidth}, shadowSoftness: ${heroShadowSoftness})`,
-    fontAtlas,
-    size: captionSize,
-    color: captionColor,
-    layer: contentLayer,
-  });
-
-  const { bounds } = shapeText(heroText, fontAtlas.data, { size: heroSize });
-
-  createGuideBox(
-    world,
-    whiteSprite,
-    { x: topLeft.x, y: boxTop },
-    { x: usableWidth, y: bounds.height },
-    guideLayer,
-  );
-
-  const textEntity = world.createEntity();
-  addPositionComponent(world, textEntity, {
-    local: { x: topLeft.x, y: boxTop },
-  });
-  addTextComponent(world, textEntity, {
-    text: heroText,
-    fontAtlas,
-    size: heroSize,
-    color: bodyColor,
-    layer: contentLayer,
-    outlineColor: heroOutlineColor,
-    outlineWidth: heroOutlineWidth,
-    shadowColor: heroShadowColor,
-    shadowOffset: heroShadowOffset,
-    shadowSoftness: heroShadowSoftness,
-  });
-
-  return boxTop - bounds.height;
-}
diff --git a/documentation-site/src/pages/demos/text/_create-game.ts b/documentation-site/src/pages/demos/text/_create-game.ts
index 0993fbf8a..8e577a37e 100644
--- a/documentation-site/src/pages/demos/text/_create-game.ts
+++ b/documentation-site/src/pages/demos/text/_create-game.ts
@@ -2,10 +2,8 @@ import { createTransformEcsSystem } from '@forge-game-engine/forge/common';
 import defaultFontImageUrl from '@forge-game-engine/forge/fonts/default/default.png';
 import {
   createCamera,
-  createCameraEcsSystem,
   createImageSprite,
   createRenderEcsSystem,
-  getCameraView,
 } from '@forge-game-engine/forge/rendering';
 import {
   createTextShapingEcsSystem,
@@ -13,61 +11,28 @@ import {
 } from '@forge-game-engine/forge/text';
 import { createGame, Game } from '@forge-game-engine/forge/utilities';
 import { DEMO_VERTICAL_WORLD_UNITS } from '@site/src/utils/demo-camera';
-import { createEffectsExamples } from './_create-effects-examples';
-import { createEffectsHeroExample } from './_create-effects-hero-example';
-import { createHorizontalAlignmentExamples } from './_create-horizontal-alignment-examples';
-import { createLineHeightExamples } from './_create-line-height-examples';
-import { createLiveMaxWidthExample } from './_create-live-max-width-example';
-import { createRichTextExample } from './_create-rich-text-example';
-import { createVerticalAlignmentExamples } from './_create-vertical-alignment-examples';
-import { createLiveMaxWidthEcsSystem } from './_live-max-width.system';
 import { createPlayground, Playground } from './_create-playground';
 
-const renderLayers = {
-  foreground: 1 << 0,
-};
-
-// Draw-order (not culling) layers: guide boxes/lines are drawn first so the
-// text painted at `content` always ends up on top of them, regardless of
-// how their world positions happen to compare.
-const drawOrder = {
-  guide: 0,
-  content: 1,
-};
-
-const margin = 24;
-const sectionGap = 16;
-
 /**
- * Builds the text rendering demo: a showcase of every `horizontalAlign` and
- * `verticalAlign` value, a comparison of a few `lineHeight` multipliers, a
- * paragraph whose `maxWidth` oscillates every frame to show
- * `createTextShapingEcsSystem` reflowing text live, rich text tags, an
- * interactive
- * playground, and an outline/soft-shadow showcase, all drawn from one
- * shared `FontAtlas`: the engine's default font, imported through the
- * package's `fonts/default` exports so webpack serves both files.
- * @param onPlaygroundReady - Called once the playground's live
- * `TextEcsComponent` exists, so `index.tsx`'s controls can mutate it
- * directly (mirroring how other demos hand a live component back to React,
- * e.g. the space-shooter demo's `onBloomReady`).
+ * Builds the text demo: one block of text drawn with the engine's default
+ * font, which the page's controls change while the game runs.
+ * @param onPlaygroundReady - Called with the playground once it exists, so
+ * the page's controls can update it.
  * @returns The created game.
  */
 export const createTextGame = async (
   onPlaygroundReady: (playground: Playground) => void,
 ): Promise<Game> => {
-  const { game, world, renderContext, time } = createGame('demo-game');
+  const { game, world, renderContext } = createGame('demo-game');
 
-  const camera = createCamera(world, {
+  createCamera(world, {
     isStatic: true,
-    cullingMask: renderLayers.foreground,
     verticalWorldUnits: DEMO_VERTICAL_WORLD_UNITS,
   });
 
-  const fontAtlasCache = new FontAtlasCache(renderContext);
-  const fontAtlas = await fontAtlasCache.getOrLoad({
-    // Importing the JSON would give its parsed contents, so `new URL` asks
-    // webpack for its URL instead.
+  // The engine ships a default font. Importing its JSON would give the
+  // parsed contents, so `new URL` asks webpack for the file's URL instead.
+  const fontAtlas = await new FontAtlasCache(renderContext).getOrLoad({
     metricsUrl: new URL(
       '@forge-game-engine/forge/fonts/default/default.json',
       import.meta.url,
@@ -75,114 +40,14 @@ export const createTextGame = async (
     imageUrl: defaultFontImageUrl,
   });
 
-  const whiteSprite = {
-    ...createImageSprite(renderContext.whiteTexture, { pixelsPerUnit: 1 }),
-    category: renderLayers.foreground,
-  };
-
-  const { x: width, y: height } = getCameraView(
-    world,
-    camera,
-    renderContext,
-  ).size;
-  const usableWidth = width - margin * 2;
-  const left = -usableWidth / 2;
-  let y = height / 2 - margin;
-
-  y = createHorizontalAlignmentExamples(
-    world,
-    fontAtlas,
-    whiteSprite,
-    drawOrder.guide,
-    drawOrder.content,
-    { x: left, y },
-    usableWidth,
-  );
-  y -= sectionGap;
-
-  y = createVerticalAlignmentExamples(
-    world,
-    fontAtlas,
-    whiteSprite,
-    drawOrder.guide,
-    drawOrder.content,
-    { x: left, y },
-    usableWidth,
-  );
-  y -= sectionGap;
-
-  y = createLineHeightExamples(
-    world,
-    fontAtlas,
-    whiteSprite,
-    drawOrder.guide,
-    drawOrder.content,
-    { x: left, y },
-    usableWidth,
-  );
-  y -= sectionGap;
-
-  y = createLiveMaxWidthExample(
-    world,
-    fontAtlas,
-    whiteSprite,
-    drawOrder.guide,
-    drawOrder.content,
-    { x: left, y },
-    usableWidth,
-  );
-  y -= sectionGap;
+  const whiteSprite = createImageSprite(renderContext.whiteTexture, {
+    pixelsPerUnit: 1,
+  });
 
-  y = createRichTextExample(
-    world,
-    fontAtlas,
-    whiteSprite,
-    drawOrder.guide,
-    drawOrder.content,
-    { x: left, y },
-    usableWidth,
-  );
-  y -= sectionGap;
+  const playground = createPlayground(world, fontAtlas, whiteSprite);
 
-  const playground = createPlayground(
-    world,
-    fontAtlas,
-    whiteSprite,
-    drawOrder.guide,
-    drawOrder.content,
-    { x: left, y },
-    usableWidth,
-  );
   onPlaygroundReady(playground);
-  y = playground.bottom;
-  y -= sectionGap;
-
-  y = createEffectsExamples(
-    world,
-    fontAtlas,
-    whiteSprite,
-    drawOrder.guide,
-    drawOrder.content,
-    { x: left, y },
-    usableWidth,
-  );
-  y -= sectionGap;
-
-  createEffectsHeroExample(
-    world,
-    fontAtlas,
-    whiteSprite,
-    drawOrder.guide,
-    drawOrder.content,
-    { x: left, y },
-    usableWidth,
-  );
 
-  world.addSystem(createCameraEcsSystem(time));
-  world.addSystem(createLiveMaxWidthEcsSystem(time));
-  // After every system that writes `position.local` (the live max-width
-  // example moves its guide box each frame), so rendering sees this
-  // frame's world positions.
   world.addSystem(createTransformEcsSystem());
   world.addSystem(createTextShapingEcsSystem());
   world.addSystem(createRenderEcsSystem(renderContext));
diff --git a/documentation-site/src/pages/demos/text/_create-guide-box.ts b/documentation-site/src/pages/demos/text/_create-guide-box.ts
deleted file mode 100644
index c1df15fd1..000000000
--- a/documentation-site/src/pages/demos/text/_create-guide-box.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import {
-  addPositionComponent,
-  PositionEcsComponent,
-} from '@forge-game-engine/forge/common';
-import { EcsWorld } from '@forge-game-engine/forge/ecs';
-import { Vector2 } from '@forge-game-engine/forge/math';
-import {
-  addSpriteComponent,
-  Color,
-  SpriteEcsComponent,
-} from '@forge-game-engine/forge/rendering';
-
-// A fully opaque, dark tint rather than a translucent one: a dark,
-// canvas-distinct color is what reads as a faint "panel" against the
-// demo's black background, without relying on partial transparency.
-export const guideBoxColor = new Color(0.16, 0.17, 0.21, 1);
-
-/**
- * Creates a translucent rectangle, top-left anchored at `topLeft`, sized to
- * `size`: a visual guide showing the `maxWidth`/height column a nearby
- * `TextEcsComponent` is laid out against. Top-left anchoring (rather than
- * the sprite's own center pivot) matches how a `TextEcsComponent`'s own
- * bounds are anchored to its entity position (see `shapeText`'s
- * `verticalAlign: 'top'` default), so a box built from the same `topLeft`
- * a label uses frames that label's block exactly.
- * @param world - The ECS world to add the guide box entity to.
- * @param spriteTemplate - A plain white sprite (from `createImageSprite`)
- * to tint and resize into the box.
- * @param topLeft - The box's top-left corner, in world units.
- * @param size - The box's width/height, in world units.
- * @param layer - The render layer to draw the box on (behind the text it frames).
- * @returns The guide box's `SpriteEcsComponent` and `PositionEcsComponent`,
- * so a caller can resize/reposition it later (see `_live-max-width.system.ts`).
- */
-export function createGuideBox(
-  world: EcsWorld,
-  spriteTemplate: SpriteEcsComponent,
-  topLeft: Vector2,
-  size: Vector2,
-  layer: number,
-): { sprite: SpriteEcsComponent; position: PositionEcsComponent } {
-  const entity = world.createEntity();
-
-  const position = addPositionComponent(world, entity, {
-    local: { x: topLeft.x + size.x / 2, y: topLeft.y - size.y / 2 },
-  });
-
-  const sprite = addSpriteComponent(world, entity, {
-    ...spriteTemplate,
-    width: size.x,
-    height: size.y,
-    tintColor: guideBoxColor,
-    layer,
-  });
-
-  return { sprite, position };
-}
diff --git a/documentation-site/src/pages/demos/text/_create-horizontal-alignment-examples.ts b/documentation-site/src/pages/demos/text/_create-horizontal-alignment-examples.ts
deleted file mode 100644
index 94edf10f4..000000000
--- a/documentation-site/src/pages/demos/text/_create-horizontal-alignment-examples.ts
+++ /dev/null
@@ -1,113 +0,0 @@
-import { addPositionComponent } from '@forge-game-engine/forge/common';
-import { EcsWorld } from '@forge-game-engine/forge/ecs';
-import { Vector2 } from '@forge-game-engine/forge/math';
-import { Color, SpriteEcsComponent } from '@forge-game-engine/forge/rendering';
-import {
-  addTextComponent,
-  FontAtlas,
-  shapeText,
-} from '@forge-game-engine/forge/text';
-import { createGuideBox } from './_create-guide-box';
-
-// Long enough to wrap onto 3 lines with a noticeably short last line -
-// that's what makes left vs. center vs. right vs. justify visibly differ;
-// a two-line wrap where both lines are nearly the same width doesn't.
-const sampleText =
-  'Pack my box with five dozen liquor jugs and a case of vintage wine.';
-const bodySize = 15;
-const bodyLineHeight = 1.15;
-const captionSize = 13;
-const captionColor = new Color(0.55, 0.6, 0.72, 1);
-const bodyColor = new Color(0.85, 0.87, 0.92, 1);
-const captionGap = 20;
-const columnGap = 18;
-
-const columns: {
-  label: string;
-  horizontalAlign: 'left' | 'center' | 'right' | 'justify';
-}[] = [
-  { label: 'left (default)', horizontalAlign: 'left' },
-  { label: 'center', horizontalAlign: 'center' },
-  { label: 'right', horizontalAlign: 'right' },
-  { label: 'justify', horizontalAlign: 'justify' },
-];
-
-/**
- * Builds a 4-column showcase of every `horizontalAlign` value
- * (`left`/`center`/`right`/`justify`), all wrapping the same sentence at the
- * same `maxWidth` so alignment is the only thing that varies between
- * columns. Each column gets a guide box (see `createGuideBox`) framing the
- * shared `maxWidth`/computed-height column the text is aligned within.
- * @param world - The ECS world to add label entities to.
- * @param fontAtlas - The font atlas every label draws from.
- * @param whiteSprite - A plain white sprite template for the guide boxes.
- * @param guideLayer - The draw-order layer for guide boxes (drawn behind text).
- * @param contentLayer - The draw-order layer for captions/body text.
- * @param topLeft - This section's top-left corner, in world units.
- * @param usableWidth - The total width available to lay the 4 columns out in.
- * @returns The y coordinate immediately below the section's content, for
- * stacking the next section beneath it.
- */
-export function createHorizontalAlignmentExamples(
-  world: EcsWorld,
-  fontAtlas: FontAtlas,
-  whiteSprite: SpriteEcsComponent,
-  guideLayer: number,
-  contentLayer: number,
-  topLeft: Vector2,
-  usableWidth: number,
-): number {
-  const columnWidth =
-    (usableWidth - columnGap * (columns.length - 1)) / columns.length;
-  const boxTop = topLeft.y - captionGap;
-
-  let sectionBottom = boxTop;
-
-  columns.forEach((column, index) => {
-    const x = topLeft.x + index * (columnWidth + columnGap);
-
-    const captionEntity = world.createEntity();
-    addPositionComponent(world, captionEntity, {
-      local: { x, y: topLeft.y },
-    });
-    addTextComponent(world, captionEntity, {
-      text: column.label,
-      fontAtlas,
-      size: captionSize,
-      color: captionColor,
-      layer: contentLayer,
-    });
-
-    const { bounds } = shapeText(sampleText, fontAtlas.data, {
-      size: bodySize,
-      lineHeight: bodyLineHeight,
-      horizontalAlign: column.horizontalAlign,
-      maxWidth: columnWidth,
-    });
-
-    createGuideBox(
-      world,
-      whiteSprite,
-      { x, y: boxTop },
-      { x: columnWidth, y: bounds.height },
-      guideLayer,
-    );
-
-    const textEntity = world.createEntity();
-    addPositionComponent(world, textEntity, { local: { x, y: boxTop } });
-    addTextComponent(world, textEntity, {
-      text: sampleText,
-      fontAtlas,
-      size: bodySize,
-      lineHeight: bodyLineHeight,
-      horizontalAlign: column.horizontalAlign,
-      maxWidth: columnWidth,
-      color: bodyColor,
-      layer: contentLayer,
-    });
-
-    sectionBottom = Math.min(sectionBottom, boxTop - bounds.height);
-  });
-
-  return sectionBottom;
-}
diff --git a/documentation-site/src/pages/demos/text/_create-line-height-examples.ts b/documentation-site/src/pages/demos/text/_create-line-height-examples.ts
deleted file mode 100644
index 5d6db1ea0..000000000
--- a/documentation-site/src/pages/demos/text/_create-line-height-examples.ts
+++ /dev/null
@@ -1,102 +0,0 @@
-import { addPositionComponent } from '@forge-game-engine/forge/common';
-import { EcsWorld } from '@forge-game-engine/forge/ecs';
-import { Vector2 } from '@forge-game-engine/forge/math';
-import { Color, SpriteEcsComponent } from '@forge-game-engine/forge/rendering';
-import {
-  addTextComponent,
-  FontAtlas,
-  shapeText,
-} from '@forge-game-engine/forge/text';
-import { createGuideBox } from './_create-guide-box';
-
-const sampleText = 'The quick brown fox jumps over the lazy dog.';
-const bodySize = 15;
-const captionSize = 13;
-const captionColor = new Color(0.55, 0.6, 0.72, 1);
-const bodyColor = new Color(0.85, 0.87, 0.92, 1);
-const captionGap = 20;
-const columnGap = 18;
-
-const columns: { label: string; lineHeight: number }[] = [
-  { label: 'lineHeight: 0.8', lineHeight: 0.8 },
-  { label: 'lineHeight: 1 (default)', lineHeight: 1 },
-  { label: 'lineHeight: 1.8', lineHeight: 1.8 },
-];
-
-/**
- * Builds a 3-column showcase of the `lineHeight` multiplier: the same
- * wrapped paragraph is laid out at a few different multipliers side by
- * side, each with a guide box sized to that column's own computed
- * `bounds.height` - so the boxes themselves visibly grow with `lineHeight`,
- * not just the gaps between lines.
- * @param world - The ECS world to add label entities to.
- * @param fontAtlas - The font atlas every label draws from.
- * @param whiteSprite - A plain white sprite template for the guide boxes.
- * @param guideLayer - The draw-order layer for guide boxes (drawn behind text).
- * @param contentLayer - The draw-order layer for captions/body text.
- * @param topLeft - This section's top-left corner, in world units.
- * @param usableWidth - The total width available to lay the 3 columns out in.
- * @returns The y coordinate immediately below the section's content, for
- * stacking the next section beneath it.
- */
-export function createLineHeightExamples(
-  world: EcsWorld,
-  fontAtlas: FontAtlas,
-  whiteSprite: SpriteEcsComponent,
-  guideLayer: number,
-  contentLayer: number,
-  topLeft: Vector2,
-  usableWidth: number,
-): number {
-  const columnWidth =
-    (usableWidth - columnGap * (columns.length - 1)) / columns.length;
-  const boxTop = topLeft.y - captionGap;
-
-  let sectionBottom = boxTop;
-
-  columns.forEach((column, index) => {
-    const x = topLeft.x + index * (columnWidth + columnGap);
-
-    const captionEntity = world.createEntity();
-    addPositionComponent(world, captionEntity, {
-      local: { x, y: topLeft.y },
-    });
-    addTextComponent(world, captionEntity, {
-      text: column.label,
-      fontAtlas,
-      size: captionSize,
-      color: captionColor,
-      layer: contentLayer,
-    });
-
-    const { bounds } = shapeText(sampleText, fontAtlas.data, {
-      size: bodySize,
-      lineHeight: column.lineHeight,
-      maxWidth: columnWidth,
-    });
-
-    createGuideBox(
-      world,
-      whiteSprite,
-      { x, y: boxTop },
-      { x: columnWidth, y: bounds.height },
-      guideLayer,
-    );
-
-    const textEntity = world.createEntity();
-    addPositionComponent(world, textEntity, { local: { x, y: boxTop } });
-    addTextComponent(world, textEntity, {
-      text: sampleText,
-      fontAtlas,
-      size: bodySize,
-      lineHeight: column.lineHeight,
-      maxWidth: columnWidth,
-      color: bodyColor,
-      layer: contentLayer,
-    });
-
-    sectionBottom = Math.min(sectionBottom, boxTop - bounds.height);
-  });
-
-  return sectionBottom;
-}
diff --git a/documentation-site/src/pages/demos/text/_create-live-max-width-example.ts b/documentation-site/src/pages/demos/text/_create-live-max-width-example.ts
deleted file mode 100644
index b4b0e4eeb..000000000
--- a/documentation-site/src/pages/demos/text/_create-live-max-width-example.ts
+++ /dev/null
@@ -1,109 +0,0 @@
-import { addPositionComponent } from '@forge-game-engine/forge/common';
-import { EcsWorld } from '@forge-game-engine/forge/ecs';
-import { Vector2 } from '@forge-game-engine/forge/math';
-import { Color, SpriteEcsComponent } from '@forge-game-engine/forge/rendering';
-import {
-  addTextComponent,
-  FontAtlas,
-  shapeText,
-} from '@forge-game-engine/forge/text';
-import { createGuideBox } from './_create-guide-box';
-import { liveMaxWidthId } from './_live-max-width.component';
-
-const sampleText =
-  "This paragraph's maxWidth oscillates every frame - watch the words jump between lines as the column narrows and widens.";
-const bodySize = 15;
-const bodyLineHeight = 1.2;
-const captionSize = 13;
-const captionColor = new Color(0.55, 0.6, 0.72, 1);
-const bodyColor = new Color(0.85, 0.87, 0.92, 1);
-const captionGap = 22;
-const periodSeconds = 4;
-const minWidthFraction = 0.35;
-
-/**
- * Builds the live `maxWidth` showcase: a single paragraph whose
- * `TextEcsComponent.maxWidth` `createLiveMaxWidthEcsSystem` oscillates every
- * frame between `minWidthFraction * usableWidth` and `usableWidth`, with a
- * guide box that tracks the current width and a caption that reports it -
- * this is what makes the reflow driven by `createTextShapingEcsSystem`'s
- * dirty tracking visible in real time, rather than only at a single
- * `maxWidth` value.
- * @param world - The ECS world to add the label entities to.
- * @param fontAtlas - The font atlas the label draws from.
- * @param whiteSprite - A plain white sprite template for the guide box.
- * @param guideLayer - The draw-order layer for the guide box (drawn behind text).
- * @param contentLayer - The draw-order layer for the caption/body text.
- * @param topLeft - This section's top-left corner, in world units.
- * @param usableWidth - The widest the paragraph's column ever gets, in world units.
- * @returns The y coordinate immediately below the section's content.
- */
-export function createLiveMaxWidthExample(
-  world: EcsWorld,
-  fontAtlas: FontAtlas,
-  whiteSprite: SpriteEcsComponent,
-  guideLayer: number,
-  contentLayer: number,
-  topLeft: Vector2,
-  usableWidth: number,
-): number {
-  const minWidth = usableWidth * minWidthFraction;
-  const boxTop = topLeft.y - captionGap;
-
-  const captionEntity = world.createEntity();
-  addPositionComponent(world, captionEntity, {
-    local: { x: topLeft.x, y: topLeft.y },
-  });
-  const liveCaption = addTextComponent(world, captionEntity, {
-    text: `maxWidth: ${Math.round(usableWidth)} world units (live)`,
-    fontAtlas,
-    size: captionSize,
-    color: captionColor,
-    layer: contentLayer,
-  });
-
-  // Sized for the tallest wrap this text ever produces - at `minWidth`, the
-  // narrowest the oscillation gets - so the guide box never needs to
-  // resize itself; only the paragraph beneath it does.
-  const { bounds: tallestBounds } = shapeText(sampleText, fontAtlas.data, {
-    size: bodySize,
-    lineHeight: bodyLineHeight,
-    maxWidth: minWidth,
-  });
-
-  const { sprite: guideBoxSprite, position: guideBoxPosition } = createGuideBox(
-    world,
-    whiteSprite,
-    { x: topLeft.x, y: boxTop },
-    { x: usableWidth, y: tallestBounds.height },
-    guideLayer,
-  );
-
-  const textEntity = world.createEntity();
-  addPositionComponent(world, textEntity, {
-    local: { x: topLeft.x, y: boxTop },
-  });
-  addTextComponent(world, textEntity, {
-    text: sampleText,
-    fontAtlas,
-    size: bodySize,
-    lineHeight: bodyLineHeight,
-    horizontalAlign: 'justify',
-    maxWidth: usableWidth,
-    color: bodyColor,
-    layer: contentLayer,
-  });
-
-  world.addComponent(textEntity, liveMaxWidthId, {
-    minWidth,
-    maxWidth: usableWidth,
-    periodSeconds,
-    elapsedSeconds: 0,
-    guideBoxLeftX: topLeft.x,
-    guideBoxSprite,
-    guideBoxPosition,
-    captionText: liveCaption,
-  });
-
-  return boxTop - tallestBounds.height;
-}
diff --git a/documentation-site/src/pages/demos/text/_create-playground.ts b/documentation-site/src/pages/demos/text/_create-playground.ts
index d9561caa5..1f9e1fac1 100644
--- a/documentation-site/src/pages/demos/text/_create-playground.ts
+++ b/documentation-site/src/pages/demos/text/_create-playground.ts
@@ -1,196 +1,160 @@
-import { addPositionComponent } from '@forge-game-engine/forge/common';
+import {
+  addPositionComponent,
+  PositionEcsComponent,
+} from '@forge-game-engine/forge/common';
 import { EcsWorld } from '@forge-game-engine/forge/ecs';
-import { Vector2 } from '@forge-game-engine/forge/math';
-import { Color, SpriteEcsComponent } from '@forge-game-engine/forge/rendering';
+import {
+  addSpriteComponent,
+  Color,
+  SpriteEcsComponent,
+} from '@forge-game-engine/forge/rendering';
 import {
   addTextComponent,
   FontAtlas,
   TextEcsComponent,
+  TextHorizontalAlign,
+  TextVerticalAlign,
 } from '@forge-game-engine/forge/text';
-import { createGuideBox } from './_create-guide-box';
-
-export type PlaygroundHorizontalAlign = TextEcsComponent['horizontalAlign'];
 
-// The same conservative, documented-safe effect values used by
-// `_create-effects-examples.ts` - see `text-effects.md`'s "Choosing a safe
-// range" section for why the playground doesn't default to an atlas's
-// absolute maximum. Fixed rather than user-controllable: an `<input
-// type="color">` control was tried here and dropped for being noticeably
-// slow to interact with, so only width/offset/softness are adjustable.
-const outlineColor = new Color(1, 0.55, 0.15, 1);
-const glowColor = new Color(0.15, 0.65, 1, 1);
-
-/** The values the playground's controls start at (see `_PlaygroundControls.tsx`). */
-export const playgroundDefaults = {
-  text: "Type your own text here! This is the engine's shipped default font atlas (Liberation Sans, SIL OFL 1.1) - zero font setup required. Try <b>bold</b> and <color=#ff7a3d>color</color> tags.",
-  size: 24,
-  minSize: 12,
-  maxSize: 56,
-  horizontalAlign: 'left' as PlaygroundHorizontalAlign,
-  wrapEnabled: true,
+/**
+ * Everything the playground's controls can change.
+ */
+export interface PlaygroundSettings {
+  text: string;
+  size: number;
+  wrapWidth: number;
+  lineHeight: number;
+  horizontalAlign: TextHorizontalAlign;
+  verticalAlign: TextVerticalAlign;
+  richText: boolean;
+  outline: boolean;
+  outlineWidth: number;
+  glow: boolean;
+  glowOffsetX: number;
+  glowOffsetY: number;
+  glowSoftness: number;
+}
 
-  outlineEnabled: false,
+export const defaultPlaygroundSettings: PlaygroundSettings = {
+  text: 'Forge draws text from a <b>signed distance field</b> font, so it stays <color=#ffbc42>sharp</color> at any size. Type here and drag the sliders to watch it reflow.',
+  size: 32,
+  wrapWidth: 560,
+  lineHeight: 1,
+  horizontalAlign: 'left',
+  verticalAlign: 'top',
+  richText: true,
+  outline: false,
   outlineWidth: 1.2,
-  minOutlineWidth: 0.1,
-  maxOutlineWidth: 4,
-
-  glowEnabled: false,
-  glowAlpha: 0.95,
+  glow: false,
   glowOffsetX: 0.8,
   glowOffsetY: -0.8,
-  minGlowOffset: -3,
-  maxGlowOffset: 3,
   glowSoftness: 1.4,
-  minGlowSoftness: 0,
-  maxGlowSoftness: 4,
 };
 
-const captionColor = new Color(0.55, 0.6, 0.72, 1);
-const bodyColor = new Color(0.9, 0.92, 0.96, 1);
-const captionGap = 22;
-const boxHeight = 220;
-
-export interface Playground {
-  /** The live `TextEcsComponent` the controls mutate directly. */
-  textComponent: TextEcsComponent;
-
-  /** The `maxWidth` to restore when the "Wrap" toggle is turned back on. */
-  wrapWidth: number;
-
-  /** The y coordinate immediately below this section's content. */
-  bottom: number;
-}
-
-/**
- * Sets `textComponent.maxWidth` from the "Wrap" toggle: `wrapWidth` when
- * enabled, `undefined` (never wrap) when disabled.
- * @param textComponent - The playground's live text component.
- * @param wrapWidth - The width to wrap at when `enabled`.
- * @param enabled - Whether wrapping is turned on.
- */
-export function setPlaygroundWrap(
-  textComponent: TextEcsComponent,
-  wrapWidth: number,
-  enabled: boolean,
-): void {
-  textComponent.maxWidth = enabled ? wrapWidth : undefined;
-}
+const columnColor = new Color(0.16, 0.17, 0.21, 1);
+const anchorColor = new Color(0.95, 0.55, 0.25, 1);
+const textColor = new Color(0.92, 0.94, 0.97, 1);
+const outlineColor = new Color(1, 0.45, 0.15, 1);
+const glowColor = new Color(0.15, 0.65, 1, 0.95);
+const anchorThickness = 2;
 
-/**
- * Sets `textComponent`'s outline fields from the outline controls.
- * `outlineWidth` of `0` (when `enabled` is `false`) draws no outline, the
- * same "width is its own off switch" semantics
- * `TextEcsComponent.outlineWidth` itself documents.
- * @param textComponent - The playground's live text component.
- * @param enabled - Whether the outline is turned on.
- * @param width - The outline width, in screen-pixel-range units.
- */
-export function setPlaygroundOutline(
-  textComponent: TextEcsComponent,
-  enabled: boolean,
-  width: number,
-): void {
-  textComponent.outlineColor = outlineColor;
-  textComponent.outlineWidth = enabled ? width : 0;
-}
+// The demo's canvas is always at least 3:2, so its view is at least 900
+// world units wide; this leaves a margin either side.
+export const playgroundMaxWrapWidth = 800;
+// Tall enough to cover the view at any canvas size.
+const columnHeight = 2000;
 
 /**
- * Sets `textComponent`'s soft-shadow/glow fields from the glow controls.
- * A transparent `shadowColor` (when `enabled` is `false`) draws no glow,
- * the same "alpha is its own off switch" semantics
- * `TextEcsComponent.shadowColor` itself documents.
- * @param textComponent - The playground's live text component.
- * @param enabled - Whether the glow is turned on.
- * @param offset - The glow's offset from the glyph, in screen-pixel-range units.
- * @param softness - How far the glow fades out, in screen-pixel-range units.
+ * The playground's live entities, which `applyPlaygroundSettings` updates.
  */
-export function setPlaygroundGlow(
-  textComponent: TextEcsComponent,
-  enabled: boolean,
-  offset: Vector2,
-  softness: number,
-): void {
-  textComponent.shadowColor = new Color(
-    glowColor.r,
-    glowColor.g,
-    glowColor.b,
-    enabled ? playgroundDefaults.glowAlpha : 0,
-  );
-  textComponent.shadowOffset = offset;
-  textComponent.shadowSoftness = softness;
+export interface Playground {
+  text: TextEcsComponent;
+  textPosition: PositionEcsComponent;
+  column: SpriteEcsComponent;
+  anchorLine: SpriteEcsComponent;
 }
 
 /**
- * Builds the interactive playground: a live-typed `TextEcsComponent` whose
- * text, size, alignment, wrapping, outline, and glow are all driven by
- * `_PlaygroundControls.tsx` mutating the returned `textComponent` directly -
- * `createTextShapingEcsSystem`'s own dirty tracking (see
- * `text-shaping-system.ts`) picks up each change on its own, no extra
- * plumbing needed.
- * @param world - The ECS world to add the label entities to.
- * @param fontAtlas - The font atlas the label draws from.
- * @param whiteSprite - A plain white sprite template for the guide box.
- * @param guideLayer - The draw-order layer for the guide box (drawn behind text).
- * @param contentLayer - The draw-order layer for the caption/body text.
- * @param topLeft - This section's top-left corner, in world units.
- * @param usableWidth - The wrap width used while "Wrap" is enabled.
- * @returns The playground's live text component, its wrap width, and the y
- * coordinate immediately below the section's content.
+ * Builds the playground: one block of text, a dark column showing its wrap
+ * width, and an orange line through the point the text is anchored to.
+ * The text is centered on the canvas and anchored at its middle, so every
+ * `verticalAlign` value moves the text relative to the line.
+ * @param world - The ECS world to add the entities to.
+ * @param fontAtlas - The font the text is drawn with.
+ * @param whiteSprite - A plain white sprite to tint into the column and line.
+ * @returns The live entities, for `applyPlaygroundSettings`.
  */
 export function createPlayground(
   world: EcsWorld,
   fontAtlas: FontAtlas,
   whiteSprite: SpriteEcsComponent,
-  guideLayer: number,
-  contentLayer: number,
-  topLeft: Vector2,
-  usableWidth: number,
 ): Playground {
-  const captionEntity = world.createEntity();
-  addPositionComponent(world, captionEntity, {
-    local: { x: topLeft.x, y: topLeft.y },
+  const columnEntity = world.createEntity();
+  addPositionComponent(world, columnEntity);
+  const column = addSpriteComponent(world, columnEntity, {
+    ...whiteSprite,
+    height: columnHeight,
+    tintColor: columnColor,
+    layer: 0,
   });
-  addTextComponent(world, captionEntity, {
-    text: 'Try it yourself',
-    fontAtlas,
-    size: 13,
-    color: captionColor,
-    layer: contentLayer,
-  });
-
-  const boxTop = topLeft.y - captionGap;
 
-  createGuideBox(
-    world,
-    whiteSprite,
-    { x: topLeft.x, y: boxTop },
-    { x: usableWidth, y: boxHeight },
-    guideLayer,
-  );
+  const anchorEntity = world.createEntity();
+  addPositionComponent(world, anchorEntity);
+  const anchorLine = addSpriteComponent(world, anchorEntity, {
+    ...whiteSprite,
+    height: anchorThickness,
+    tintColor: anchorColor,
+    layer: 1,
+  });
 
   const textEntity = world.createEntity();
-  addPositionComponent(world, textEntity, {
-    local: { x: topLeft.x, y: boxTop },
-  });
-  const textComponent = addTextComponent(world, textEntity, {
-    text: playgroundDefaults.text,
+  const textPosition = addPositionComponent(world, textEntity);
+  const text = addTextComponent(world, textEntity, {
+    text: defaultPlaygroundSettings.text,
+    size: defaultPlaygroundSettings.size,
     fontAtlas,
-    size: playgroundDefaults.size,
-    horizontalAlign: playgroundDefaults.horizontalAlign,
-    maxWidth: usableWidth,
-    color: bodyColor,
+    color: textColor,
     outlineColor,
-    shadowOffset: {
-      x: playgroundDefaults.glowOffsetX,
-      y: playgroundDefaults.glowOffsetY,
-    },
-    shadowSoftness: playgroundDefaults.glowSoftness,
-    layer: contentLayer,
+    layer: 2,
   });
 
-  return {
-    textComponent,
-    wrapWidth: usableWidth,
-    bottom: boxTop - boxHeight,
-  };
+  const playground = { text, textPosition, column, anchorLine };
+
+  applyPlaygroundSettings(playground, defaultPlaygroundSettings);
+
+  return playground;
+}
+
+/**
+ * Writes `settings` into the playground's text and resizes its guides to
+ * match. The text shaping system reshapes the text on its next update.
+ * @param playground - The playground to update.
+ * @param settings - The values to show.
+ */
+export function applyPlaygroundSettings(
+  playground: Playground,
+  settings: PlaygroundSettings,
+): void {
+  const { text, textPosition, column, anchorLine } = playground;
+  const wrapWidth = Math.min(settings.wrapWidth, playgroundMaxWrapWidth);
+
+  // The text's x is the left edge of its wrap width, so centering the
+  // column on the canvas means starting the text half a column to the left.
+  textPosition.local = { x: -wrapWidth / 2, y: 0 };
+  column.width = wrapWidth;
+  anchorLine.width = wrapWidth;
+
+  text.text = settings.text;
+  text.size = settings.size;
+  text.maxWidth = wrapWidth;
+  text.lineHeight = settings.lineHeight;
+  text.horizontalAlign = settings.horizontalAlign;
+  text.verticalAlign = settings.verticalAlign;
+  text.richText = settings.richText;
+
+  // A zero outline width and a transparent shadow draw nothing.
+  text.outlineWidth = settings.outline ? settings.outlineWidth : 0;
+  text.shadowColor = settings.glow ? glowColor : Color.transparent;
+  text.shadowOffset = { x: settings.glowOffsetX, y: settings.glowOffsetY };
+  text.shadowSoftness = settings.glowSoftness;
 }
diff --git a/documentation-site/src/pages/demos/text/_create-rich-text-example.ts b/documentation-site/src/pages/demos/text/_create-rich-text-example.ts
deleted file mode 100644
index 31ebd02e2..000000000
--- a/documentation-site/src/pages/demos/text/_create-rich-text-example.ts
+++ /dev/null
@@ -1,107 +0,0 @@
-import { addPositionComponent } from '@forge-game-engine/forge/common';
-import { EcsWorld } from '@forge-game-engine/forge/ecs';
-import { Vector2 } from '@forge-game-engine/forge/math';
-import { Color, SpriteEcsComponent } from '@forge-game-engine/forge/rendering';
-import {
-  addTextComponent,
-  FontAtlas,
-  shapeText,
-} from '@forge-game-engine/forge/text';
-import { createGuideBox } from './_create-guide-box';
-
-const paragraph =
-  "Rich text tags style part of a string: <b>bold</b> words, <color=#ff7a3d>colored</color> words, and <b><color=#5cc8ff>both at once</color></b>. Tags are stripped before shaping, so this paragraph <color=#9be564>wraps and kerns exactly as it would without them</color>. Markup that isn't a tag stays literal: HP < 50%.";
-const outlinedText = '<b>Bold</b> and regular, outlined';
-const bodySize = 16;
-const outlinedSize = 24;
-const captionSize = 13;
-const captionColor = new Color(0.55, 0.6, 0.72, 1);
-const bodyColor = new Color(0.9, 0.92, 0.96, 1);
-const outlineColor = new Color(1, 0.55, 0.15, 1);
-const captionGap = 14;
-const rowGap = 12;
-
-/**
- * Builds the rich text section: a wrapped paragraph mixing `<b>` and
- * `<color>` tags, and a bold word next to a regular one with an outline, to
- * show the outline following the thickened bold ink.
- * @param world - The ECS world to add label entities to.
- * @param fontAtlas - The font atlas every label draws from.
- * @param whiteSprite - A plain white sprite template for the guide box.
- * @param guideLayer - The draw-order layer for the guide box (drawn behind text).
- * @param contentLayer - The draw-order layer for the caption/body text.
- * @param topLeft - This section's top-left corner, in world units.
- * @param usableWidth - The total width available to lay the example out in.
- * @returns The y coordinate immediately below the section's content.
- */
-export function createRichTextExample(
-  world: EcsWorld,
-  fontAtlas: FontAtlas,
-  whiteSprite: SpriteEcsComponent,
-  guideLayer: number,
-  contentLayer: number,
-  topLeft: Vector2,
-  usableWidth: number,
-): number {
-  const captionEntity = world.createEntity();
-  addPositionComponent(world, captionEntity, {
-    local: { x: topLeft.x, y: topLeft.y },
-  });
-  addTextComponent(world, captionEntity, {
-    text: 'rich text tags: b and color=#rrggbb',
-    fontAtlas,
-    size: captionSize,
-    color: captionColor,
-    layer: contentLayer,
-  });
-
-  // `shapeText` parses tags too, so the guide box is sized from exactly the
-  // text that's drawn.
-  const { bounds: paragraphBounds } = shapeText(paragraph, fontAtlas.data, {
-    size: bodySize,
-    maxWidth: usableWidth,
-  });
-  const { bounds: outlinedBounds } = shapeText(outlinedText, fontAtlas.data, {
-    size: outlinedSize,
-  });
-
-  const paragraphTop = topLeft.y - captionGap;
-  const outlinedTop = paragraphTop - paragraphBounds.height - rowGap;
-
-  createGuideBox(
-    world,
-    whiteSprite,
-    { x: topLeft.x, y: paragraphTop },
-    { x: usableWidth, y: paragraphBounds.height },
-    guideLayer,
-  );
-
-  const paragraphEntity = world.createEntity();
-  addPositionComponent(world, paragraphEntity, {
-    local: { x: topLeft.x, y: paragraphTop },
-  });
-  addTextComponent(world, paragraphEntity, {
-    text: paragraph,
-    fontAtlas,
-    size: bodySize,
-    color: bodyColor,
-    maxWidth: usableWidth,
-    layer: contentLayer,
-  });
-
-  const outlinedEntity = world.createEntity();
-  addPositionComponent(world, outlinedEntity, {
-    local: { x: topLeft.x, y: outlinedTop },
-  });
-  addTextComponent(world, outlinedEntity, {
-    text: outlinedText,
-    fontAtlas,
-    size: outlinedSize,
-    color: bodyColor,
-    outlineColor,
-    outlineWidth: 1.5,
-    layer: contentLayer,
-  });
-
-  return outlinedTop - outlinedBounds.height;
-}
diff --git a/documentation-site/src/pages/demos/text/_create-vertical-alignment-examples.ts b/documentation-site/src/pages/demos/text/_create-vertical-alignment-examples.ts
deleted file mode 100644
index ac5acea9d..000000000
--- a/documentation-site/src/pages/demos/text/_create-vertical-alignment-examples.ts
+++ /dev/null
@@ -1,127 +0,0 @@
-import { addPositionComponent } from '@forge-game-engine/forge/common';
-import { EcsWorld } from '@forge-game-engine/forge/ecs';
-import { Vector2 } from '@forge-game-engine/forge/math';
-import {
-  addSpriteComponent,
-  Color,
-  SpriteEcsComponent,
-} from '@forge-game-engine/forge/rendering';
-import {
-  addTextComponent,
-  FontAtlas,
-  shapeText,
-} from '@forge-game-engine/forge/text';
-
-const sampleText = 'Anchored to the line below.';
-const bodySize = 15;
-const bodyLineHeight = 1.15;
-const captionSize = 13;
-const captionColor = new Color(0.55, 0.6, 0.72, 1);
-const bodyColor = new Color(0.85, 0.87, 0.92, 1);
-const anchorLineColor = new Color(0.95, 0.55, 0.25, 1);
-const anchorLineThickness = 2;
-const captionGap = 20;
-const columnGap = 18;
-
-const columns: {
-  label: string;
-  verticalAlign: 'top' | 'middle' | 'bottom' | 'baseline' | 'capline';
-}[] = [
-  { label: 'top (default)', verticalAlign: 'top' },
-  { label: 'middle', verticalAlign: 'middle' },
-  { label: 'bottom', verticalAlign: 'bottom' },
-  { label: 'baseline', verticalAlign: 'baseline' },
-  { label: 'capline', verticalAlign: 'capline' },
-];
-
-/**
- * Builds a 5-column showcase of every `verticalAlign` value (`top`/
- * `middle`/`bottom`/`baseline`/`capline`): each column draws the same short
- * block of text against a shared, highlighted anchor line at the same
- * entity position, so the difference between them is exactly what moves
- * relative to that line - `top` hangs below it, `bottom` sits above it,
- * `middle` centers the band from the first line's cap height to the last
- * line's baseline on it, `baseline` puts the first line's baseline
- * directly on it, and `capline` hangs below it like `top` but from the
- * shorter cap height instead of the ascender.
- * @param world - The ECS world to add label entities to.
- * @param fontAtlas - The font atlas every label draws from.
- * @param whiteSprite - A plain white sprite template for the anchor lines.
- * @param guideLayer - The draw-order layer for the anchor lines (drawn behind text).
- * @param contentLayer - The draw-order layer for captions/body text.
- * @param topLeft - This section's top-left corner, in world units.
- * @param usableWidth - The total width available to lay the 5 columns out in.
- * @returns The y coordinate immediately below the section's content, for
- * stacking the next section beneath it.
- */
-export function createVerticalAlignmentExamples(
-  world: EcsWorld,
-  fontAtlas: FontAtlas,
-  whiteSprite: SpriteEcsComponent,
-  guideLayer: number,
-  contentLayer: number,
-  topLeft: Vector2,
-  usableWidth: number,
-): number {
-  const columnWidth =
-    (usableWidth - columnGap * (columns.length - 1)) / columns.length;
-
-  const { bounds } = shapeText(sampleText, fontAtlas.data, {
-    size: bodySize,
-    lineHeight: bodyLineHeight,
-    horizontalAlign: 'center',
-    maxWidth: columnWidth,
-  });
-
-  // A `bottom`-aligned column needs `bounds.height` of headroom above the
-  // anchor line, and a `top`-aligned one needs the same below it, so the
-  // anchor line sits exactly one block-height beneath the captions.
-  const anchorY = topLeft.y - captionGap - bounds.height;
-
-  columns.forEach((column, index) => {
-    const columnLeft = topLeft.x + index * (columnWidth + columnGap);
-    const columnCenter = columnLeft + columnWidth / 2;
-
-    const captionEntity = world.createEntity();
-    addPositionComponent(world, captionEntity, {
-      local: { x: columnLeft, y: topLeft.y },
-    });
-    addTextComponent(world, captionEntity, {
-      text: column.label,
-      fontAtlas,
-      size: captionSize,
-      color: captionColor,
-      layer: contentLayer,
-    });
-
-    const lineEntity = world.createEntity();
-    addPositionComponent(world, lineEntity, {
-      local: { x: columnCenter, y: anchorY },
-    });
-    addSpriteComponent(world, lineEntity, {
-      ...whiteSprite,
-      width: columnWidth,
-      height: anchorLineThickness,
-      tintColor: anchorLineColor,
-      layer: guideLayer,
-    });
-
-    const textEntity = world.createEntity();
-    addPositionComponent(world, textEntity, {
-      local: { x: columnLeft, y: anchorY },
-    });
-    addTextComponent(world, textEntity, {
-      text: sampleText,
-      fontAtlas,
-      size: bodySize,
-      lineHeight: bodyLineHeight,
-      horizontalAlign: 'center',
-      verticalAlign: column.verticalAlign,
-      maxWidth: columnWidth,
-      color: bodyColor,
-      layer: contentLayer,
-    });
-  });
-
-  return anchorY - bounds.height;
-}
diff --git a/documentation-site/src/pages/demos/text/_live-max-width.component.ts b/documentation-site/src/pages/demos/text/_live-max-width.component.ts
deleted file mode 100644
index 278b99932..000000000
--- a/documentation-site/src/pages/demos/text/_live-max-width.component.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import { PositionEcsComponent } from '@forge-game-engine/forge/common';
-import { createComponentId } from '@forge-game-engine/forge/ecs';
-import { SpriteEcsComponent } from '@forge-game-engine/forge/rendering';
-import { TextEcsComponent } from '@forge-game-engine/forge/text';
-
-/**
- * Demo-only component driving the live `maxWidth` example: tracks the
- * oscillation's range/timing so `createLiveMaxWidthEcsSystem` can sweep the
- * entity's own `TextEcsComponent.maxWidth` back and forth every frame,
- * while keeping a guide box and a caption label in sync with the current
- * value.
- */
-export interface LiveMaxWidthEcsComponent {
-  minWidth: number;
-  maxWidth: number;
-  periodSeconds: number;
-  elapsedSeconds: number;
-
-  /** The guide box's fixed left edge; only its width/center-x change as `maxWidth` oscillates. */
-  guideBoxLeftX: number;
-  guideBoxSprite: SpriteEcsComponent;
-  guideBoxPosition: PositionEcsComponent;
-
-  /** A label rewritten each tick to show the current `maxWidth` value. */
-  captionText: TextEcsComponent;
-}
-
-export const liveMaxWidthId =
-  createComponentId<LiveMaxWidthEcsComponent>('liveMaxWidth');
diff --git a/documentation-site/src/pages/demos/text/_live-max-width.system.ts b/documentation-site/src/pages/demos/text/_live-max-width.system.ts
deleted file mode 100644
index 6eb2b36bf..000000000
--- a/documentation-site/src/pages/demos/text/_live-max-width.system.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { Time } from '@forge-game-engine/forge/common';
-import { EcsSystem } from '@forge-game-engine/forge/ecs';
-import { TextEcsComponent, textId } from '@forge-game-engine/forge/text';
-import {
-  LiveMaxWidthEcsComponent,
-  liveMaxWidthId,
-} from './_live-max-width.component';
-
-/**
- * Sweeps every `LiveMaxWidthEcsComponent` entity's own `TextEcsComponent.maxWidth`
- * back and forth (a sine wave between `minWidth` and `maxWidth`) every
- * frame, and keeps its guide box and caption label in sync - this is what
- * demonstrates `createTextShapingEcsSystem` reflowing text live: watch the
- * words jump between lines as the column narrows and widens.
- * @param time - The time instance used to derive elapsed seconds.
- * @returns The live `maxWidth` ECS system.
- */
-export const createLiveMaxWidthEcsSystem = (
-  time: Time,
-): EcsSystem<[LiveMaxWidthEcsComponent, TextEcsComponent]> => ({
-  query: [liveMaxWidthId, textId],
-  update: (_world, { components: [liveMaxWidths, texts] }) => {
-    for (let i = 0; i < liveMaxWidths.length; i++) {
-      const live = liveMaxWidths[i];
-      const textComponent = texts[i];
-
-      live.elapsedSeconds += time.deltaTimeInSeconds;
-
-      const angle = (live.elapsedSeconds / live.periodSeconds) * Math.PI * 2;
-      const midpoint = (live.minWidth + live.maxWidth) / 2;
-      const amplitude = (live.maxWidth - live.minWidth) / 2;
-      const currentMaxWidth = midpoint + amplitude * Math.sin(angle);
-
-      textComponent.maxWidth = currentMaxWidth;
-      live.guideBoxSprite.width = currentMaxWidth;
-      live.guideBoxPosition.local.x = live.guideBoxLeftX + currentMaxWidth / 2;
-      live.captionText.text = `maxWidth: ${Math.round(currentMaxWidth)} world units (live)`;
-    }
-  },
-});
diff --git a/documentation-site/src/pages/demos/text/index.tsx b/documentation-site/src/pages/demos/text/index.tsx
index f59442b4e..6101067d2 100644
--- a/documentation-site/src/pages/demos/text/index.tsx
+++ b/documentation-site/src/pages/demos/text/index.tsx
@@ -1,57 +1,20 @@
 import React, { JSX, useCallback, useRef, useState } from 'react';
 import { createTextGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
-import createGuideBoxCode from '!!raw-loader!./_create-guide-box';
-import createHorizontalAlignmentExamplesCode from '!!raw-loader!./_create-horizontal-alignment-examples';
-import createVerticalAlignmentExamplesCode from '!!raw-loader!./_create-vertical-alignment-examples';
-import createLineHeightExamplesCode from '!!raw-loader!./_create-line-height-examples';
-import createLiveMaxWidthExampleCode from '!!raw-loader!./_create-live-max-width-example';
-import liveMaxWidthComponentCode from '!!raw-loader!./_live-max-width.component';
-import liveMaxWidthSystemCode from '!!raw-loader!./_live-max-width.system';
-import createEffectsExamplesCode from '!!raw-loader!./_create-effects-examples';
 import createPlaygroundCode from '!!raw-loader!./_create-playground';
-import playgroundControlsCode from '!!raw-loader!./_PlaygroundControls';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage, DemoPanel } from '@site/src/components/demo-page';
 import {
+  applyPlaygroundSettings,
+  defaultPlaygroundSettings,
   Playground,
-  playgroundDefaults,
-  PlaygroundHorizontalAlign,
-  setPlaygroundGlow,
-  setPlaygroundOutline,
-  setPlaygroundWrap,
+  PlaygroundSettings,
 } from './_create-playground';
 import { PlaygroundControls } from './_PlaygroundControls';
 
 export default function Text(): JSX.Element {
   const playgroundRef = useRef<Playground | null>(null);
-  const [text, setText] = useState(playgroundDefaults.text);
-  const [size, setSize] = useState(playgroundDefaults.size);
-  const [horizontalAlign, setHorizontalAlign] =
-    useState<PlaygroundHorizontalAlign>(playgroundDefaults.horizontalAlign);
-  const [wrapEnabled, setWrapEnabled] = useState(
-    playgroundDefaults.wrapEnabled,
-  );
-
-  const [outlineEnabled, setOutlineEnabled] = useState(
-    playgroundDefaults.outlineEnabled,
-  );
-  const [outlineWidth, setOutlineWidth] = useState(
-    playgroundDefaults.outlineWidth,
-  );
-
-  const [glowEnabled, setGlowEnabled] = useState(
-    playgroundDefaults.glowEnabled,
-  );
-  const [glowOffsetX, setGlowOffsetX] = useState(
-    playgroundDefaults.glowOffsetX,
-  );
-  const [glowOffsetY, setGlowOffsetY] = useState(
-    playgroundDefaults.glowOffsetY,
-  );
-  const [glowSoftness, setGlowSoftness] = useState(
-    playgroundDefaults.glowSoftness,
-  );
+  const [settings, setSettings] = useState(defaultPlaygroundSettings);
 
   const createGame = useCallback(
     () =>
@@ -61,177 +24,73 @@ export default function Text(): JSX.Element {
     [],
   );
 
-  const handleTextChange = (value: string) => {
-    setText(value);
-
-    if (playgroundRef.current) {
-      playgroundRef.current.textComponent.text = value;
-    }
-  };
-
-  const handleSizeChange = (value: number) => {
-    setSize(value);
+  const handleChange = (change: Partial<PlaygroundSettings>): void => {
+    const next = { ...settings, ...change };
 
-    if (playgroundRef.current) {
-      playgroundRef.current.textComponent.size = value;
-    }
-  };
-
-  const handleHorizontalAlignChange = (value: PlaygroundHorizontalAlign) => {
-    setHorizontalAlign(value);
+    setSettings(next);
 
     if (playgroundRef.current) {
-      playgroundRef.current.textComponent.horizontalAlign = value;
+      applyPlaygroundSettings(playgroundRef.current, next);
     }
   };
 
-  const handleWrapEnabledChange = (value: boolean) => {
-    setWrapEnabled(value);
-
-    if (playgroundRef.current) {
-      setPlaygroundWrap(
-        playgroundRef.current.textComponent,
-        playgroundRef.current.wrapWidth,
-        value,
-      );
-    }
-  };
-
-  const applyOutline = (enabled: boolean, width: number) => {
-    if (playgroundRef.current) {
-      setPlaygroundOutline(playgroundRef.current.textComponent, enabled, width);
-    }
-  };
-
-  const handleOutlineEnabledChange = (value: boolean) => {
-    setOutlineEnabled(value);
-    applyOutline(value, outlineWidth);
-  };
-
-  const handleOutlineWidthChange = (value: number) => {
-    setOutlineWidth(value);
-    applyOutline(outlineEnabled, value);
-  };
-
-  const applyGlow = (
-    enabled: boolean,
-    offsetX: number,
-    offsetY: number,
-    softness: number,
-  ) => {
-    if (playgroundRef.current) {
-      setPlaygroundGlow(
-        playgroundRef.current.textComponent,
-        enabled,
-        { x: offsetX, y: offsetY },
-        softness,
-      );
-    }
-  };
-
-  const handleGlowEnabledChange = (value: boolean) => {
-    setGlowEnabled(value);
-    applyGlow(value, glowOffsetX, glowOffsetY, glowSoftness);
-  };
-
-  const handleGlowOffsetXChange = (value: number) => {
-    setGlowOffsetX(value);
-    applyGlow(glowEnabled, value, glowOffsetY, glowSoftness);
-  };
-
-  const handleGlowOffsetYChange = (value: number) => {
-    setGlowOffsetY(value);
-    applyGlow(glowEnabled, glowOffsetX, value, glowSoftness);
-  };
-
-  const handleGlowSoftnessChange = (value: number) => {
-    setGlowSoftness(value);
-    applyGlow(glowEnabled, glowOffsetX, glowOffsetY, value);
-  };
-
   return (
-    <Demo
-      metaData={{
-        title: 'Text Rendering Demo',
-        description:
-          'A demo showcasing MSDF text rendering, multi-line layout, alignment, live reflow, rich text tags, an interactive playground, and outline/soft-shadow effects with addTextComponent and createTextShapingEcsSystem.',
-      }}
-      header="Text Rendering"
-      blurb="A showcase of MSDF text rendering using the engine's shipped default font atlas (Liberation Sans, SIL OFL 1.1 - zero font setup required): every horizontalAlign value (left/center/right/justify) wrapping the same sentence, every verticalAlign value (top/middle/bottom/baseline/capline) positioned against a shared anchor line, with middle centering the cap-height-to-baseline band, a few lineHeight multipliers compared side by side, a paragraph whose maxWidth oscillates every frame (driving createTextShapingEcsSystem to reflow it live), a paragraph styled with <b> and <color> rich text tags, an interactive playground you can type into using the controls above, and - at the bottom - outline/soft-shadow effects at a conservative, documented-safe size (see the Text Effects guide for why). Every guide box/line is sized from shapeText's own computed bounds, not guessed."
+    <DemoPage
+      slug="text"
       createGame={createGame}
-      interactions={
-        <PlaygroundControls
-          text={text}
-          size={size}
-          minSize={playgroundDefaults.minSize}
-          maxSize={playgroundDefaults.maxSize}
-          horizontalAlign={horizontalAlign}
-          wrapEnabled={wrapEnabled}
-          outlineEnabled={outlineEnabled}
-          outlineWidth={outlineWidth}
-          minOutlineWidth={playgroundDefaults.minOutlineWidth}
-          maxOutlineWidth={playgroundDefaults.maxOutlineWidth}
-          glowEnabled={glowEnabled}
-          glowOffsetX={glowOffsetX}
-          glowOffsetY={glowOffsetY}
-          minGlowOffset={playgroundDefaults.minGlowOffset}
-          maxGlowOffset={playgroundDefaults.maxGlowOffset}
-          glowSoftness={glowSoftness}
-          minGlowSoftness={playgroundDefaults.minGlowSoftness}
-          maxGlowSoftness={playgroundDefaults.maxGlowSoftness}
-          onTextChange={handleTextChange}
-          onSizeChange={handleSizeChange}
-          onHorizontalAlignChange={handleHorizontalAlignChange}
-          onWrapEnabledChange={handleWrapEnabledChange}
-          onOutlineEnabledChange={handleOutlineEnabledChange}
-          onOutlineWidthChange={handleOutlineWidthChange}
-          onGlowEnabledChange={handleGlowEnabledChange}
-          onGlowOffsetXChange={handleGlowOffsetXChange}
-          onGlowOffsetYChange={handleGlowOffsetYChange}
-          onGlowSoftnessChange={handleGlowSoftnessChange}
-        />
+      panels={
+        <DemoPanel title="Playground" icon="fa-sliders">
+          <PlaygroundControls settings={settings} onChange={handleChange} />
+        </DemoPanel>
       }
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        {
-          name: 'create-guide-box.ts',
-          content: createGuideBoxCode,
-        },
+      highlights={[
         {
-          name: 'create-horizontal-alignment-examples.ts',
-          content: createHorizontalAlignmentExamplesCode,
+          text: "The text uses the engine's built-in font, a signed distance field atlas that stays sharp at any size.",
+          file: 'create-game.ts',
         },
         {
-          name: 'create-vertical-alignment-examples.ts',
-          content: createVerticalAlignmentExamplesCode,
+          text: 'Every setting is a field on one text component. The text shaping system reshapes the text whenever a field changes.',
+          file: 'create-playground.ts',
         },
         {
-          name: 'create-line-height-examples.ts',
-          content: createLineHeightExamplesCode,
+          text: 'The dark column is the wrap width. Lines break at the word that would cross it, and horizontal align places each line inside it.',
+          file: 'create-playground.ts',
         },
         {
-          name: 'create-live-max-width-example.ts',
-          content: createLiveMaxWidthExampleCode,
-        },
-        {
-          name: 'live-max-width.component.ts',
-          content: liveMaxWidthComponentCode,
-        },
-        {
-          name: 'live-max-width.system.ts',
-          content: liveMaxWidthSystemCode,
+          text: "The orange line is the text's position. Vertical align picks which part of the text sits on it.",
+          file: 'create-playground.ts',
         },
+      ]}
+      docLinks={[
+        { label: 'Rendering text', to: '/docs/docs/text/rendering-text' },
+        { label: 'Text effects', to: '/docs/docs/text/text-effects' },
         {
-          name: 'create-playground.ts',
-          content: createPlaygroundCode,
+          label: 'Loading a font atlas',
+          to: '/docs/docs/text/loading-a-font-atlas',
         },
+      ]}
+      fileGroups={[
         {
-          name: 'PlaygroundControls.tsx',
-          content: playgroundControlsCode,
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Loads the default font, creates the playground and registers the systems.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'create-effects-examples.ts',
-          content: createEffectsExamplesCode,
+          title: 'Playground',
+          files: [
+            {
+              name: 'create-playground.ts',
+              summary:
+                'Creates the text and its guides, and applies the settings to them.',
+              content: createPlaygroundCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/texture-filtering/index.tsx b/documentation-site/src/pages/demos/texture-filtering/index.tsx
index 957579fad..c5958a4b0 100644
--- a/documentation-site/src/pages/demos/texture-filtering/index.tsx
+++ b/documentation-site/src/pages/demos/texture-filtering/index.tsx
@@ -4,30 +4,54 @@ import gameCode from '!!raw-loader!./_create-game';
 import createEntityCode from '!!raw-loader!./_create-entity';
 import createSpriteCode from '!!raw-loader!./_create-sprite';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
-export default function Rendering(): JSX.Element {
+export default function TextureFiltering(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Texture Filtering',
-        description: 'A demo showcasing how texture filtering works.',
-      }}
-      header="Texture Filtering"
-      blurb="This demo shows how texture filtering works. On the left, the planet is using nearest neighbor filtering (pixelated) and on the planet on the right is using linear filtering."
+    <DemoPage
+      slug="texture-filtering"
       createGame={createTextureFilteringGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'Both planets load the same small pixel-art image and scale it up 4.5 times.',
+          file: 'create-entity.ts',
         },
         {
-          name: 'create-entity.ts',
-          content: createEntityCode,
+          text: "The left planet's texture uses 'nearest' filtering, which keeps hard, blocky pixels.",
+          file: 'create-sprite.ts',
         },
         {
-          name: 'create-sprite.ts',
-          content: createSpriteCode,
+          text: "The right planet's texture uses 'linear' filtering, which blends neighboring pixels into a smooth, blurry image.",
+          file: 'create-sprite.ts',
+        },
+      ]}
+      docLinks={[{ label: 'Textures', to: '/docs/docs/rendering/textures' }]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary: 'Creates a pixelated and a smooth planet side by side.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-sprite.ts',
+              summary:
+                "Loads the planet texture with 'nearest' or 'linear' filtering.",
+              content: createSpriteCode,
+            },
+            {
+              name: 'create-entity.ts',
+              summary: 'Places a planet sprite, scaled up and rotated.',
+              content: createEntityCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/torque/index.tsx b/documentation-site/src/pages/demos/torque/index.tsx
index 6b2efde96..26cc043eb 100644
--- a/documentation-site/src/pages/demos/torque/index.tsx
+++ b/documentation-site/src/pages/demos/torque/index.tsx
@@ -7,51 +7,91 @@ import thrusterSystemCode from '!!raw-loader!./_thruster.system';
 import gustComponentCode from '!!raw-loader!./_gust.component';
 import gustSystemCode from '!!raw-loader!./_gust.system';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function Torque(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Torque and Motors Demo',
-        description:
-          "A demo showcasing RigidBody.applyTorque and the physics engine's AngularVelocityMotorEcsComponent, for spinning a body with torque.",
-      }}
-      header="Torque and Motors"
-      blurb="This demo showcases the two ways to spin a RigidBody with torque. On the left, a flywheel carries a demo-specific ThrusterEcsComponent: while Space is held, createThrusterEcsSystem calls RigidBody.applyTorque on it directly every tick, spinning it up, and releasing lets a small angularDrag on the body gradually spin it back down, since nothing drives it once the torque stops. There's no engine-provided component for this one-shot/manual case, a game is expected to write a small system like this itself. On the right, a flywheel carries an AngularVelocityMotorEcsComponent, a built-in engine component that holds a steady target angular velocity on its own, no input needed, with no angularDrag of its own; a demo-only gust periodically knocks its speed off course, and the motor spends its limited maxTorque budget correcting back towards the target every tick afterwards."
+    <DemoPage
+      slug="torque"
       createGame={createTorqueGame}
-      interactions={
-        <InteractionInstruction
-          displayElement={<KeyboardKey keyCode="␣" />}
-          text="Hold to thrust"
-        />
-      }
-      codeFiles={[
+      controls={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          inputs: ['Space'],
+          action: 'Spin the left flywheel',
+          detail: 'Hold to keep applying torque',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'While Space is held, a small game system calls applyTorque on the left flywheel every tick.',
+          file: 'thruster.system.ts',
         },
         {
-          name: 'create-flywheels.ts',
-          content: createFlywheelsCode,
+          text: 'Let go and angular drag on the left flywheel slowly spins it back down, since nothing drives it anymore.',
+          file: 'create-flywheels.ts',
         },
         {
-          name: 'thruster.component.ts',
-          content: thrusterComponentCode,
+          text: "The right flywheel has the engine's AngularVelocityMotorEcsComponent, which holds a target spin speed with no input at all.",
+          file: 'create-flywheels.ts',
         },
         {
-          name: 'thruster.system.ts',
-          content: thrusterSystemCode,
+          text: 'Every few seconds a gust knocks the right flywheel off speed, and the motor uses its limited maxTorque to recover.',
+          file: 'gust.system.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Forces', to: '/docs/docs/physics/forces' },
+        { label: 'Rigid bodies', to: '/docs/docs/physics/rigid-bodies' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Binds Space, creates both flywheels and registers the systems in order.',
+              content: gameCode,
+            },
+            {
+              name: 'create-flywheels.ts',
+              summary:
+                'Builds the thruster flywheel and the motor-driven flywheel.',
+              content: createFlywheelsCode,
+            },
+          ],
         },
         {
-          name: 'gust.component.ts',
-          content: gustComponentCode,
+          title: 'Thruster',
+          files: [
+            {
+              name: 'thruster.component.ts',
+              summary: 'The input and torque for a player-driven thruster.',
+              content: thrusterComponentCode,
+            },
+            {
+              name: 'thruster.system.ts',
+              summary:
+                'Applies torque to the flywheel while the input is held.',
+              content: thrusterSystemCode,
+            },
+          ],
         },
         {
-          name: 'gust.system.ts',
-          content: gustSystemCode,
+          title: 'Gust',
+          files: [
+            {
+              name: 'gust.component.ts',
+              summary: 'How hard and how often a gust knocks a flywheel.',
+              content: gustComponentCode,
+            },
+            {
+              name: 'gust.system.ts',
+              summary:
+                "Periodically changes the flywheel's spin, alternating direction.",
+              content: gustSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/ui-anchors/index.tsx b/documentation-site/src/pages/demos/ui-anchors/index.tsx
index dce53b345..bdd2f30b1 100644
--- a/documentation-site/src/pages/demos/ui-anchors/index.tsx
+++ b/documentation-site/src/pages/demos/ui-anchors/index.tsx
@@ -2,10 +2,8 @@ import React, { JSX, useCallback, useRef, useState } from 'react';
 import { createAnchorsGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 import createAnchorPlaygroundCode from '!!raw-loader!./_create-anchor-playground';
-import playgroundControlsCode from '!!raw-loader!./_PlaygroundControls';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
+import { DemoPage, DemoPanel } from '@site/src/components/demo-page';
 import {
   AnchorPlayground,
   anchorPlaygroundDefaults,
@@ -17,17 +15,6 @@ import {
 } from './_create-anchor-playground';
 import { PlaygroundControls } from './_PlaygroundControls';
 
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
-
 export default function UiAnchors(): JSX.Element {
   const playgroundRef = useRef<AnchorPlayground | null>(null);
   const [presetName, setPresetName] = useState<AnchorPlaygroundPresetName>(
@@ -113,17 +100,11 @@ export default function UiAnchors(): JSX.Element {
   const { isStretchX, isStretchY } = getAnchorStretchAxes(presetName);
 
   return (
-    <Demo
-      metaData={{
-        title: 'UI Anchors',
-        description:
-          'A demo showcasing RectTransformEcsComponent anchors and pivots from the ui module: corner-pinned, edge-stretched, and centered panels, plus a live-controllable anchor playground.',
-      }}
-      header="UI Anchors"
-      blurb="Four corner-pinned reference panels (topLeft, topRight, bottomLeft, bottomRight) and a full-width top bar (stretchTop), plus one orange playground panel you can drive yourself with the controls above: pick any UiAnchor preset, then drag its position and size/margin sliders to see exactly how each axis's anchor, pivot, anchoredPosition, and size (or margin, for a stretched axis) interact. Every panel's RectTransformEcsComponent resolves fresh every frame from the canvas's current aspect ratio, so toggling fullscreen keeps each one exactly where its own anchor says it should be, at any window shape - no manual reflow code required."
+    <DemoPage
+      slug="ui-anchors"
       createGame={createGame}
-      interactions={
-        <>
+      panels={
+        <DemoPanel title="Playground" icon="fa-sliders">
           <PlaygroundControls
             presetName={presetName}
             anchoredPositionX={anchoredPositionX}
@@ -142,25 +123,53 @@ export default function UiAnchors(): JSX.Element {
             onSizeOrMarginXChange={handleSizeOrMarginXChange}
             onSizeOrMarginYChange={handleSizeOrMarginYChange}
           />
-          <InteractionInstruction
-            displayElement={
-              <div style={badgeStyle}>
-                <i className="fa-solid fa-expand" />
-              </div>
-            }
-            text="Toggle fullscreen to see the orange playground panel (and every reference panel) hold its anchor at a different aspect ratio."
-          />
-        </>
+        </DemoPanel>
       }
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
+      highlights={[
+        {
+          text: 'Each panel has an anchor that pins it to a corner or stretches it along an edge of the canvas.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The orange panel takes its anchor, position and size straight from the playground controls, written into its live rect transform.',
+          file: 'create-anchor-playground.ts',
+        },
+        {
+          text: 'On a point axis the slider sets a fixed size; on a stretched axis it sets a margin from the anchored span.',
+          file: 'create-anchor-playground.ts',
+        },
+        {
+          text: 'Layout is resolved every frame, so in fullscreen every panel still sits where its anchor says, at any aspect ratio.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Anchors and layout', to: '/docs/docs/ui/anchors-and-layout' },
+        { label: 'Responsive UI', to: '/docs/docs/ui/responsive-ui' },
+        { label: 'Creating a canvas', to: '/docs/docs/ui/creating-a-canvas' },
+      ]}
+      fileGroups={[
         {
-          name: 'create-anchor-playground.ts',
-          content: createAnchorPlaygroundCode,
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Builds the canvas, the five reference panels and the orange playground panel.',
+              content: gameCode,
+            },
+          ],
         },
         {
-          name: 'PlaygroundControls.tsx',
-          content: playgroundControlsCode,
+          title: 'Playground',
+          files: [
+            {
+              name: 'create-anchor-playground.ts',
+              summary:
+                "The anchor presets and functions that write the controls into the panel's rect transform.",
+              content: createAnchorPlaygroundCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/ui-button/index.tsx b/documentation-site/src/pages/demos/ui-button/index.tsx
index abf8a40ea..7dc62c855 100644
--- a/documentation-site/src/pages/demos/ui-button/index.tsx
+++ b/documentation-site/src/pages/demos/ui-button/index.tsx
@@ -2,58 +2,59 @@ import React, { JSX } from 'react';
 import { createButtonGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiButton(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Buttons',
-        description:
-          'A demo showcasing createButton and keyboard/gamepad focus navigation from the ui module: click, hover, and arrow-key/Enter navigation between three buttons.',
-      }}
-      header="UI Buttons"
-      blurb="Three buttons (createButton), each hoverable, clickable, and keyboard/gamepad-focus-navigable. Click one, or use the arrow keys to move focus between them and Enter/Space to activate the focused one - either path raises the same onInvoke, updating the status text above. Hovering a button also focuses it, so the highlight follows the mouse the same way it follows the keyboard, and each button's color eases between normal/hover/pressed tints via createUiTransitionEcsSystem."
+    <DemoPage
+      slug="ui-button"
       createGame={createButtonGame}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={
-              <div style={badgeStyle}>
-                <i className="fa-solid fa-computer-mouse" />
-              </div>
-            }
-            text="Click a button."
-          />
-          <InteractionInstruction
-            displayElement={
-              <>
-                <KeyboardKey keyCode="↑" />
-                <KeyboardKey keyCode="↓" />
-              </>
-            }
-            text="Move focus between buttons."
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="⏎" />}
-            text="Activate the focused button."
-          />
-        </>
-      }
-      codeFiles={[{ name: 'game.ts', content: gameCode }]}
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: 'Press a button',
+        },
+        { inputs: ['↑↓'], action: 'Move focus' },
+        { inputs: ['Enter', 'Space'], action: 'Press the focused button' },
+      ]}
+      highlights={[
+        {
+          text: 'Each button comes from one createButton call: a sliced panel sprite, a label and an interactable component.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'A click and Enter or Space on the focused button raise the same onInvoke event, which updates the status text.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The canvas takes a navigate and a submit input action, so the arrow keys move focus between buttons.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'Hovering a button focuses it too, and its color eases between normal, hover and pressed tints.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        {
+          label: 'Buttons and interaction',
+          to: '/docs/docs/ui/buttons-and-interaction',
+        },
+        { label: 'Creating a canvas', to: '/docs/docs/ui/creating-a-canvas' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Wires mouse and keyboard input, then builds three buttons and a status label.',
+              content: gameCode,
+            },
+          ],
+        },
+      ]}
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/ui-canvas-group/index.tsx b/documentation-site/src/pages/demos/ui-canvas-group/index.tsx
index 5b63f3409..43985099f 100644
--- a/documentation-site/src/pages/demos/ui-canvas-group/index.tsx
+++ b/documentation-site/src/pages/demos/ui-canvas-group/index.tsx
@@ -2,42 +2,62 @@ import React, { JSX } from 'react';
 import { createCanvasGroupGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiCanvasGroup(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Canvas Group',
-        description:
-          'A demo showcasing CanvasGroupEcsComponent fading and disabling a whole nested UI subtree at once.',
-      }}
-      header="UI Canvas Group"
-      blurb="A single CanvasGroupEcsComponent lives on the outer modal panel. Toggling 'Disable modal' fades and disables everything under it in one write - the nested card, its label, its long description, and its 'Confirm' button (a real createButton) - two and three levels down in the tree. createUiCanvasGroupEcsSystem walks the whole subtree, not just direct children, so alpha/interactable/blocksRaycasts propagate arbitrarily deep: 'Confirm' becomes genuinely unable to be clicked while disabled, not just dimmed. The toggle itself lives outside the group, so it stays fully opaque and clickable the whole time."
+    <DemoPage
+      slug="ui-canvas-group"
       createGame={createCanvasGroupGame}
-      interactions={
-        <InteractionInstruction
-          displayElement={
-            <div style={badgeStyle}>
-              <i className="fa-solid fa-computer-mouse" />
-            </div>
-          }
-          text="Click 'Disable modal' to fade the whole card."
-        />
-      }
-      codeFiles={[{ name: 'game.ts', content: gameCode }]}
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: "Toggle 'Disable modal'",
+        },
+        {
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: 'Press Confirm',
+          detail: 'Does nothing while the modal is disabled',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'One canvas group sits on the modal panel, and the toggle changes only that component.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The fade and disable reach every descendant: the nested card, its labels and the Confirm button two or three levels down.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'While disabled, Confirm really ignores clicks, because the group turns off interactable and blocksRaycasts, not just alpha.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The toggle lives outside the group, so it stays opaque and clickable the whole time.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        {
+          label: 'Hiding, fading and tooltips',
+          to: '/docs/docs/ui/canvas-groups-and-tooltips',
+        },
+        { label: 'Controls', to: '/docs/docs/ui/controls' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Builds the modal with its canvas group, the nested card and the toggle that disables it.',
+              content: gameCode,
+            },
+          ],
+        },
+      ]}
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/ui-dropdown/index.tsx b/documentation-site/src/pages/demos/ui-dropdown/index.tsx
index 501cbd892..f78ecc5bf 100644
--- a/documentation-site/src/pages/demos/ui-dropdown/index.tsx
+++ b/documentation-site/src/pages/demos/ui-dropdown/index.tsx
@@ -2,42 +2,60 @@ import React, { JSX } from 'react';
 import { createDropdownGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiDropdown(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Dropdown',
-        description:
-          'A demo showcasing createDropdown from the ui module: a header button showing the selected option, plus a click-to-open list of option rows.',
-      }}
-      header="UI Dropdown"
-      blurb="createDropdown builds a header (an ordinary createButton showing the currently-selected option) with a UiDropdownEcsComponent, plus one option-row button per entry - stacked below the header and hidden until it's clicked open. A chevron on the header's right edge flips between v (closed) and ^ (open) as the list toggles. Selecting an option updates the header's label, raises onValueChanged, and closes the list. Clicking outside the open list doesn't close it - only clicking the header again or selecting an option does."
+    <DemoPage
+      slug="ui-dropdown"
       createGame={createDropdownGame}
-      interactions={
-        <InteractionInstruction
-          displayElement={
-            <div style={badgeStyle}>
-              <i className="fa-solid fa-computer-mouse" />
-            </div>
-          }
-          text="Click the dropdown to open it, then pick an option."
-        />
-      }
-      codeFiles={[{ name: 'game.ts', content: gameCode }]}
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Click the header' }],
+          action: 'Open or close the list',
+        },
+        {
+          inputs: [{ device: 'mouse', label: 'Click an option' }],
+          action: 'Select it',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'One createDropdown call builds a header button showing the selected option, plus one hidden button per option below it.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'Clicking the header shows or hides the list, and the chevron on its right edge flips to match.',
+          file: 'create-game.ts',
+        },
+        {
+          text: "Picking an option updates the header's label, raises onValueChanged and closes the list.",
+          file: 'create-game.ts',
+        },
+        {
+          text: 'Clicking outside the open list leaves it open; only the header or an option closes it.',
+        },
+      ]}
+      docLinks={[
+        { label: 'Controls', to: '/docs/docs/ui/controls' },
+        {
+          label: 'Buttons and interaction',
+          to: '/docs/docs/ui/buttons-and-interaction',
+        },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up mouse input and a UI canvas, then creates a four-option dropdown.',
+              content: gameCode,
+            },
+          ],
+        },
+      ]}
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/ui-main-menu/index.tsx b/documentation-site/src/pages/demos/ui-main-menu/index.tsx
index ce3a45bca..0a606be9b 100644
--- a/documentation-site/src/pages/demos/ui-main-menu/index.tsx
+++ b/documentation-site/src/pages/demos/ui-main-menu/index.tsx
@@ -6,63 +6,92 @@ import missionBriefCode from '!!raw-loader!./_create-mission-brief';
 import flagshipPanelCode from '!!raw-loader!./_create-flagship-panel';
 import paletteCode from '!!raw-loader!./_palette';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiMainMenu(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Main Menu',
-        description:
-          'A full main-menu screen built from the ui module - hand-composed numbered menu rows, a vertical layout group with content size fitting, a progress bar, and a button - reproducing a flat sci-fi reference design.',
-      }}
-      header="UI Main Menu"
-      blurb="A complete main-menu screen, built entirely from the ui module against a flat sci-fi reference design. The left nav panel (createMainMenu) stacks six hand-composed rows - a button only supports one centered label, but a row needs a left border accent, a dim index, and a bright title - with a VerticalLayoutGroupEcsComponent inside a ContentSizeFitterEcsComponent container; each row's own tint is fully transparent until it's hovered or focused (UiColorTransitionEcsComponent), so the first row reads as solid blue at rest simply because it starts focused. Beside it, createMissionBrief lays out a decorative backdrop circle (drawn first, so later siblings composite on top of it), a title, and a wrapped blurb, and createFlagshipPanel adds a bordered ship-render placeholder, a createProgressBar fleet-strength meter, and a createButton Deploy call to action. Click a row, or use the arrow keys to move focus (the first row starts focused, matching the reference) and Enter/Space to invoke - either path updates the status line above the menu, and Deploy updates it too."
+    <DemoPage
+      slug="ui-main-menu"
       createGame={createUiMainMenuGame}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={
-              <div style={badgeStyle}>
-                <i className="fa-solid fa-computer-mouse" />
-              </div>
-            }
-            text="Click a menu row or the Deploy button."
-          />
-          <InteractionInstruction
-            displayElement={
-              <>
-                <KeyboardKey keyCode="↑" />
-                <KeyboardKey keyCode="↓" />
-              </>
-            }
-            text="Move focus between menu rows."
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="⏎" />}
-            text="Invoke the focused row or button."
-          />
-        </>
-      }
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'create-main-menu.ts', content: mainMenuCode },
-        { name: 'create-mission-brief.ts', content: missionBriefCode },
-        { name: 'create-flagship-panel.ts', content: flagshipPanelCode },
-        { name: 'palette.ts', content: paletteCode },
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: 'Choose a menu row or Deploy',
+        },
+        { inputs: ['↑↓'], action: 'Move focus' },
+        { inputs: ['Enter', 'Space'], action: 'Choose the focused item' },
+      ]}
+      highlights={[
+        {
+          text: 'Each menu row is a panel given the same interactable and color transition components a button uses, so it can hold an accent, an index and a title.',
+          file: 'create-main-menu.ts',
+        },
+        {
+          text: 'A vertical layout group inside a content size fitter stacks the six rows, so no row needs layout math.',
+          file: 'create-main-menu.ts',
+        },
+        {
+          text: 'Rows are transparent until hovered or focused; the first row starts focused, which is why it shows blue at rest.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The ship readout combines a progress bar for fleet strength with a Deploy button.',
+          file: 'create-flagship-panel.ts',
+        },
+        {
+          text: 'The canvas uses the fitReferenceResolution scale mode, so the edge-to-edge layout never crops at any window shape.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Layout groups', to: '/docs/docs/ui/layout-groups' },
+        {
+          label: 'Buttons and interaction',
+          to: '/docs/docs/ui/buttons-and-interaction',
+        },
+        { label: 'Responsive UI', to: '/docs/docs/ui/responsive-ui' },
+        { label: 'Controls', to: '/docs/docs/ui/controls' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up input and the canvas, then builds the menu, brief and ship readout.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the screen',
+          files: [
+            {
+              name: 'create-main-menu.ts',
+              summary:
+                'Builds the left nav panel with its title, six numbered rows and footer.',
+              content: mainMenuCode,
+            },
+            {
+              name: 'create-mission-brief.ts',
+              summary:
+                'Lays out the backdrop circle, mission title and wrapped blurb.',
+              content: missionBriefCode,
+            },
+            {
+              name: 'create-flagship-panel.ts',
+              summary:
+                'Builds the ship placeholder, fleet strength meter and Deploy button.',
+              content: flagshipPanelCode,
+            },
+            {
+              name: 'palette.ts',
+              summary: 'The shared colors every element on the screen uses.',
+              content: paletteCode,
+            },
+          ],
+        },
       ]}
     />
   );
diff --git a/documentation-site/src/pages/demos/ui-nested-resize/index.tsx b/documentation-site/src/pages/demos/ui-nested-resize/index.tsx
index 9abc74d5f..5bde9e055 100644
--- a/documentation-site/src/pages/demos/ui-nested-resize/index.tsx
+++ b/documentation-site/src/pages/demos/ui-nested-resize/index.tsx
@@ -1,31 +1,115 @@
 import React, { JSX } from 'react';
 import { createNestedResizeGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
+import createWindowFrameCode from '!!raw-loader!./_create-window-frame';
+import createTitleBarCode from '!!raw-loader!./_create-title-bar';
+import createOptionsContentCode from '!!raw-loader!./_create-options-content';
+import createCornerDecorationsCode from '!!raw-loader!./_create-corner-decorations';
+import loadDemoSpritesCode from '!!raw-loader!./_load-demo-sprites';
 import liveMotionComponentCode from '!!raw-loader!./_live-motion.component';
 import liveMotionSystemCode from '!!raw-loader!./_live-motion.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiNestedResize(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Nested Resize',
-        description:
-          'A demo showcasing nested RectTransformEcsComponent anchors reacting live to a parent panel that resizes and moves every frame - stretch anchors resize through multiple levels of nesting, point anchors reposition without resizing.',
-      }}
-      header="UI Nested Resize"
-      blurb="A basic options menu window whose size and position both oscillate every frame (no user input - plain sine waves on four independent axes, see live-motion.system.ts), with four levels of nesting reacting to it: a stretchAll content panel that fills and resizes with it wherever it currently is - hosting a Music slider, a Fullscreen toggle, and a Back button - a stretchTop title bar nested a level deeper still that stretches its width along with its content parent, and a middleRight close button nested a level deeper again that keeps a constant size while sliding along the title bar's moving right edge - a point anchor still resolves correctly this many levels down. A corner accent and a version tag, both parented directly to the window, round it out, keeping a constant size while sliding to stay pinned to their corner. Nothing here reacts to the resize/move directly except the window's own component - every child's behavior falls straight out of the anchor it was given to createUiLayoutEcsSystem, at any depth of nesting."
+    <DemoPage
+      slug="ui-nested-resize"
       createGame={createNestedResizeGame}
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
+      controls={[
         {
-          name: 'live-motion.component.ts',
-          content: liveMotionComponentCode,
+          inputs: [{ device: 'mouse', label: 'Drag or click' }],
+          action: 'Use the slider, toggle and Back button',
+          detail: 'They keep working while the window moves',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'Only the window itself is animated: four sine waves move and resize it every frame, and nothing else reacts to that in code.',
+          file: 'live-motion.system.ts',
+        },
+        {
+          text: 'A stretchAll content panel fills the window, so it resizes on both axes and follows it wherever it goes.',
+          file: 'create-window-frame.ts',
+        },
+        {
+          text: 'A stretchTop title bar one level deeper follows only the width, and its middleRight close button slides along its edge at a fixed size.',
+          file: 'create-title-bar.ts',
+        },
+        {
+          text: 'The version tag is anchored to a corner of the window, so it keeps its size and stays pinned as the edges move.',
+          file: 'create-corner-decorations.ts',
+        },
+        {
+          text: 'The motion system runs before the layout system, so each frame lays out from the size it just wrote.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Anchors and layout', to: '/docs/docs/ui/anchors-and-layout' },
+        { label: 'Controls', to: '/docs/docs/ui/controls' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the canvas, builds the options window and registers the motion system.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the window',
+          files: [
+            {
+              name: 'create-window-frame.ts',
+              summary:
+                'Creates the moving window panel and the stretchAll content panel inside it.',
+              content: createWindowFrameCode,
+            },
+            {
+              name: 'create-title-bar.ts',
+              summary:
+                'Creates the stretchTop title bar and its middleRight close button.',
+              content: createTitleBarCode,
+            },
+            {
+              name: 'create-options-content.ts',
+              summary:
+                'Creates the Music slider, Fullscreen toggle and Back button.',
+              content: createOptionsContentCode,
+            },
+            {
+              name: 'create-corner-decorations.ts',
+              summary: "Creates the version tag pinned to the window's corner.",
+              content: createCornerDecorationsCode,
+            },
+            {
+              name: 'load-demo-sprites.ts',
+              summary: 'Loads every sprite the window and its controls use.',
+              content: loadDemoSpritesCode,
+            },
+          ],
         },
         {
-          name: 'live-motion.system.ts',
-          content: liveMotionSystemCode,
+          title: 'Live motion',
+          files: [
+            {
+              name: 'live-motion.component.ts',
+              summary:
+                'The range and period of each axis the window moves and resizes on.',
+              content: liveMotionComponentCode,
+            },
+            {
+              name: 'live-motion.system.ts',
+              summary:
+                "Writes the window's size and position from a sine wave every frame.",
+              content: liveMotionSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/ui-progress-bar/index.tsx b/documentation-site/src/pages/demos/ui-progress-bar/index.tsx
index 753332682..7b7776fec 100644
--- a/documentation-site/src/pages/demos/ui-progress-bar/index.tsx
+++ b/documentation-site/src/pages/demos/ui-progress-bar/index.tsx
@@ -4,23 +4,61 @@ import gameCode from '!!raw-loader!./_create-game';
 import pulseComponentCode from '!!raw-loader!./_pulse.component';
 import pulseSystemCode from '!!raw-loader!./_pulse.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiProgressBar(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Progress Bar',
-        description:
-          'A demo showcasing createProgressBar from the ui module: read-only linear and radial fill indicators driven purely by value.',
-      }}
-      header="UI Progress Bar"
-      blurb="createProgressBar builds a read-only fill indicator - no UiInteractableEcsComponent, since a progress bar reports state rather than accepting input. Its fill keeps its full size and a mask reveals the part the value covers: a linear mask for the health bar, a radial one (fillShape) for the cooldown ring. This demo's own _pulse.system.ts (not part of the ui module) oscillates both values on a timer to show them moving without needing any player interaction; createUiProgressBarEcsSystem picks up those writes the same frame they're made, unlike a slider, which has no such guarantee."
+    <DemoPage
+      slug="ui-progress-bar"
       createGame={createProgressBarGame}
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'pulse.component.ts', content: pulseComponentCode },
-        { name: 'pulse.system.ts', content: pulseSystemCode },
+      highlights={[
+        {
+          text: 'A progress bar only shows a value, so it has no interactable component and takes no input.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The fill keeps its full size and a mask reveals the part the value covers.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The health bar uses a linear mask; the cooldown ring sets fillShape to a radial one that sweeps clockwise from the top.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'A demo-only pulse system writes both values every frame, and the bars show each write in the same frame.',
+          file: 'pulse.system.ts',
+        },
+      ]}
+      docLinks={[{ label: 'Controls', to: '/docs/docs/ui/controls' }]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Creates a linear health bar and a radial cooldown ring, each with a pulse.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Pulse',
+          files: [
+            {
+              name: 'pulse.component.ts',
+              summary:
+                'The range and speed a progress bar value oscillates at.',
+              content: pulseComponentCode,
+            },
+            {
+              name: 'pulse.system.ts',
+              summary:
+                "Moves each pulsing progress bar's value back and forth over time.",
+              content: pulseSystemCode,
+            },
+          ],
+        },
       ]}
     />
   );
diff --git a/documentation-site/src/pages/demos/ui-scroll-view/index.tsx b/documentation-site/src/pages/demos/ui-scroll-view/index.tsx
index 2e09daf4e..823745c99 100644
--- a/documentation-site/src/pages/demos/ui-scroll-view/index.tsx
+++ b/documentation-site/src/pages/demos/ui-scroll-view/index.tsx
@@ -2,58 +2,66 @@ import React, { JSX } from 'react';
 import { createScrollViewGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiScrollView(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Scroll View',
-        description:
-          'A demo showcasing createScrollView from the ui module: a clipped, scrolling list dragged with the pointer, turned with the mouse wheel, moved with a scrollbar and followed by keyboard focus, with inertia and elastic edges.',
-      }}
-      header="UI Scroll View"
-      blurb="createScrollView clips a list of 30 buttons to its viewport with a mask. Drag the list - on a button or between them - and it follows the pointer, coasts after a quick release and springs back when pulled past an end. A drag that starts on a button scrolls instead of clicking it. The mouse wheel and the scrollbar scroll it too, and moving focus with the arrow keys scrolls the focused button into view."
+    <DemoPage
+      slug="ui-scroll-view"
       createGame={createScrollViewGame}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={
-              <div style={badgeStyle}>
-                <i className="fa-solid fa-computer-mouse" />
-              </div>
-            }
-            text="Drag the list or its scrollbar, turn the wheel, or click a level."
-          />
-          <InteractionInstruction
-            displayElement={
-              <>
-                <KeyboardKey keyCode="↑" />
-                <KeyboardKey keyCode="↓" />
-              </>
-            }
-            text="Move focus through the list; it scrolls to follow."
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="⏎" />}
-            text="Pick the focused level."
-          />
-        </>
-      }
-      codeFiles={[{ name: 'game.ts', content: gameCode }]}
+      controls={[
+        {
+          inputs: [
+            { device: 'mouse', label: 'Drag' },
+            { device: 'mouse', label: 'Wheel' },
+            { device: 'mouse', label: 'Drag scrollbar' },
+          ],
+          action: 'Scroll the list',
+        },
+        { inputs: ['↑↓'], action: 'Move focus' },
+        {
+          inputs: [{ device: 'mouse', label: 'Click' }, 'Enter', 'Space'],
+          action: 'Pick a level',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'createScrollView clips a list of 30 buttons to its viewport with a mask, and lays them out in a column.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'Dragging the list follows the pointer, coasts after a quick release and springs back when pulled past an end.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'A drag that starts on a button scrolls the list instead of clicking the button.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'Moving focus with the arrow keys scrolls the focused button into view.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Scroll views', to: '/docs/docs/ui/scroll-views' },
+        {
+          label: 'Buttons and interaction',
+          to: '/docs/docs/ui/buttons-and-interaction',
+        },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Builds the scroll view, its scrollbar and 30 level buttons, and wires mouse and keyboard input.',
+              content: gameCode,
+            },
+          ],
+        },
+      ]}
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/ui-slider/index.tsx b/documentation-site/src/pages/demos/ui-slider/index.tsx
index ad8063ca6..801aad389 100644
--- a/documentation-site/src/pages/demos/ui-slider/index.tsx
+++ b/documentation-site/src/pages/demos/ui-slider/index.tsx
@@ -2,42 +2,57 @@ import React, { JSX } from 'react';
 import { createSliderGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiSlider(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Slider',
-        description:
-          'A demo showcasing createSlider from the ui module: a click-and-drag track with a handle and fill, driving a live value label.',
-      }}
-      header="UI Slider"
-      blurb="createSlider builds a track with a draggable handle and a fill sprite that tracks the current value. The whole track is the drag surface - clicking anywhere on it, not just the handle, jumps the handle there - and dragging keeps tracking even if the pointer strays outside the track's vertical bounds. The value label updates live via onValueChanged."
+    <DemoPage
+      slug="ui-slider"
       createGame={createSliderGame}
-      interactions={
-        <InteractionInstruction
-          displayElement={
-            <div style={badgeStyle}>
-              <i className="fa-solid fa-computer-mouse" />
-            </div>
-          }
-          text="Drag the handle, or click anywhere on the track."
-        />
-      }
-      codeFiles={[{ name: 'game.ts', content: gameCode }]}
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Drag the handle' }],
+          action: 'Change the value',
+        },
+        {
+          inputs: [{ device: 'mouse', label: 'Click the track' }],
+          action: 'Jump to a value',
+        },
+      ]}
+      highlights={[
+        {
+          text: 'createSlider builds a track, a draggable handle and a fill sprite that grows with the value.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The whole track is the drag surface, so clicking anywhere on it moves the handle there.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'A drag keeps tracking even when the pointer strays above or below the track.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The value label updates live from the onValueChanged event, and wholeNumbers rounds the value to integers.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Sliders', to: '/docs/docs/ui/controls#sliders' },
+        { label: 'Creating a canvas', to: '/docs/docs/ui/creating-a-canvas' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary: 'Builds the slider and a value label that follows it.',
+              content: gameCode,
+            },
+          ],
+        },
+      ]}
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/ui-stress-test/index.tsx b/documentation-site/src/pages/demos/ui-stress-test/index.tsx
index 928d5d84c..dcd7b8254 100644
--- a/documentation-site/src/pages/demos/ui-stress-test/index.tsx
+++ b/documentation-site/src/pages/demos/ui-stress-test/index.tsx
@@ -5,35 +5,69 @@ import spawnerComponentCode from '!!raw-loader!./_stress-test-spawner.component'
 import spawnerSystemCode from '!!raw-loader!./_stress-test-spawner.system';
 import fpsMonitorSystemCode from '!!raw-loader!./_fps-monitor.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiStressTest(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Stress Test Demo',
-        description:
-          'A demo that stress tests the UI layout system by spawning grid-arranged UI panels until the frame rate drops.',
-      }}
-      header="UI Stress Test"
-      blurb="This demo spawns batches of small UI panels into a grid layout group at a regular interval, growing the on-screen UI element count over time. Open the browser console to see how many panels had been spawned when the frame rate first dropped below 100, 60, and 30 FPS. Spawning stops once the frame rate drops below 30. createUiLayoutEcsSystem/createUiLayoutGroupEcsSystem resolve every element fresh every frame with no dirty tracking (DL-12) - this demo is that design's own stress test."
+    <DemoPage
+      slug="ui-stress-test"
       createGame={createUiStressTestGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: 'A spawner adds 50 small panels to a grid layout group every tenth of a second.',
+          file: 'stress-test-spawner.system.ts',
         },
         {
-          name: 'stress-test-spawner.component.ts',
-          content: spawnerComponentCode,
+          text: 'The UI layout systems recompute every element every frame, with no dirty tracking, so layouts can never go stale.',
+          file: 'create-game.ts',
         },
         {
-          name: 'stress-test-spawner.system.ts',
-          content: spawnerSystemCode,
+          text: 'Open the browser console to see how many panels were on screen when the frame rate dropped below 100, 60 and 30 FPS.',
+          file: 'fps-monitor.system.ts',
         },
         {
-          name: 'fps-monitor.system.ts',
-          content: fpsMonitorSystemCode,
+          text: 'Spawning stops once the frame rate falls below 30 FPS.',
+          file: 'fps-monitor.system.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Layout groups', to: '/docs/docs/ui/layout-groups' },
+        { label: 'Systems', to: '/docs/docs/ecs/system' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Builds the full-screen grid, the spawner and the counter label, and registers the systems.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Spawning and measuring',
+          files: [
+            {
+              name: 'stress-test-spawner.component.ts',
+              summary:
+                'Holds the grid container, batch settings and how many panels were spawned.',
+              content: spawnerComponentCode,
+            },
+            {
+              name: 'stress-test-spawner.system.ts',
+              summary:
+                'Adds a batch of tinted panels to the grid at a fixed interval.',
+              content: spawnerSystemCode,
+            },
+            {
+              name: 'fps-monitor.system.ts',
+              summary:
+                'Logs the panel count at each FPS threshold and stops the spawner at the last.',
+              content: fpsMonitorSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/demos/ui-text-input/index.tsx b/documentation-site/src/pages/demos/ui-text-input/index.tsx
index 95cdf0596..e978e2855 100644
--- a/documentation-site/src/pages/demos/ui-text-input/index.tsx
+++ b/documentation-site/src/pages/demos/ui-text-input/index.tsx
@@ -2,53 +2,64 @@ import React, { JSX } from 'react';
 import { createTextInputGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-import { KeyboardKey } from '@site/src/components/_KeyboardKey';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiTextInput(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Text Input',
-        description:
-          'A demo showcasing createTextInput from the ui module: a name entry form with two text fields, character filters, and submit/cancel events.',
-      }}
-      header="UI Text Input"
-      blurb="A name entry form built from two text fields (createTextInput) and a button. Click or tap a field to type into it; Enter submits the field and Escape cancels it. The pilot name can't start with a space and the badge number keeps only upper-cased letters and digits. Keys typed into a field don't move UI focus or press the focused button."
+    <DemoPage
+      slug="ui-text-input"
       createGame={createTextInputGame}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={
-              <div style={badgeStyle}>
-                <i className="fa-solid fa-computer-mouse" />
-              </div>
-            }
-            text="Click a field to type into it."
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="⏎" />}
-            text="Submit the field you're typing in."
-          />
-          <InteractionInstruction
-            displayElement={<KeyboardKey keyCode="Esc" />}
-            text="Cancel typing."
-          />
-        </>
-      }
-      codeFiles={[{ name: 'game.ts', content: gameCode }]}
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Click a field' }],
+          action: 'Start typing',
+        },
+        { inputs: ['↑↓←→'], action: 'Move focus' },
+        {
+          inputs: ['Enter'],
+          action: 'Submit',
+          detail: 'Outside a field: press the focused field or button',
+        },
+        { inputs: ['Esc'], action: 'Cancel typing' },
+      ]}
+      highlights={[
+        {
+          text: 'createTextInput builds each field, with a placeholder, a caret and a maximum length.',
+          file: 'create-game.ts',
+        },
+        {
+          text: "Filters shape what's typed: the pilot name can't start with a space, and the badge keeps only upper-cased letters and digits.",
+          file: 'create-game.ts',
+        },
+        {
+          text: "Enter fires the field's onSubmit event and Escape fires onCancel, which update the status line.",
+          file: 'create-game.ts',
+        },
+        {
+          text: "Keys typed into a field don't reach the UI's bindings, so they never move focus or press the focused button.",
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Text input', to: '/docs/docs/ui/text-input' },
+        {
+          label: 'Buttons and interaction',
+          to: '/docs/docs/ui/buttons-and-interaction',
+        },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Builds the two filtered text fields, the log-in button and the status line.',
+              content: gameCode,
+            },
+          ],
+        },
+      ]}
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/ui-toggle/index.tsx b/documentation-site/src/pages/demos/ui-toggle/index.tsx
index c5adece94..477c60417 100644
--- a/documentation-site/src/pages/demos/ui-toggle/index.tsx
+++ b/documentation-site/src/pages/demos/ui-toggle/index.tsx
@@ -2,42 +2,53 @@ import React, { JSX } from 'react';
 import { createToggleGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiToggle(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI Toggles',
-        description:
-          'A demo showcasing checkboxes and radio groups from the ui module: createToggle, UiToggleGroupEcsComponent.',
-      }}
-      header="UI Toggles"
-      blurb="The 'Mute' toggle (createToggle, no group) flips freely, checkbox-style. The three 'Difficulty' toggles share a UiToggleGroupEcsComponent (addUiToggleGroupComponent), making them a radio group - clicking one turns the others off, since a group always has exactly one selection by default (allowSwitchOff: false). Both are the same createToggle/UiToggleEcsComponent underneath; a shared group is the only thing that turns a set of checkboxes into radio buttons."
+    <DemoPage
+      slug="ui-toggle"
       createGame={createToggleGame}
-      interactions={
-        <InteractionInstruction
-          displayElement={
-            <div style={badgeStyle}>
-              <i className="fa-solid fa-computer-mouse" />
-            </div>
-          }
-          text="Click a toggle."
-        />
-      }
-      codeFiles={[{ name: 'game.ts', content: gameCode }]}
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: 'Flip a toggle',
+        },
+      ]}
+      highlights={[
+        {
+          text: "The 'Mute' toggle has no group, so it flips on and off freely, like a checkbox.",
+          file: 'create-game.ts',
+        },
+        {
+          text: "The three 'Difficulty' toggles share a toggle group, which turns them into radio buttons.",
+          file: 'create-game.ts',
+        },
+        {
+          text: 'A group keeps exactly one toggle on by default, so turning one on turns the others off.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Toggles', to: '/docs/docs/ui/controls#toggles' },
+        {
+          label: 'Grouping toggles',
+          to: '/docs/docs/ui/controls#grouping-toggles',
+        },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Builds a lone checkbox toggle and a three-way radio group with captions.',
+              content: gameCode,
+            },
+          ],
+        },
+      ]}
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/ui-world-space-canvas/index.tsx b/documentation-site/src/pages/demos/ui-world-space-canvas/index.tsx
index af41f0b8d..e4ef9c2a4 100644
--- a/documentation-site/src/pages/demos/ui-world-space-canvas/index.tsx
+++ b/documentation-site/src/pages/demos/ui-world-space-canvas/index.tsx
@@ -2,20 +2,51 @@ import React, { JSX } from 'react';
 import { createWorldSpaceCanvasGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function UiWorldSpaceCanvas(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'UI World-Space Canvas',
-        description:
-          'A demo showcasing renderMode: worldSpace - a diegetic health bar placed above its target, either parented to it or kept upright with anchoredPosition.',
-      }}
-      header="UI World-Space Canvas"
-      blurb="Two identical spinning 'enemies', each with a diegetic health-bar canvas (renderMode: 'worldSpace'). The left enemy's health bar is attached the ordinary way, with world.setParent - it inherits the enemy's full world transform and visibly spins and swings around as the enemy rotates, exactly like any other parented entity. The right enemy's has no parent and is placed above it with its anchoredPosition instead, so it stays upright regardless of which way the enemy is facing - the behavior a health bar almost always wants. For a moving target, a system of your own writes anchoredPosition from the target's position every frame."
+    <DemoPage
+      slug="ui-world-space-canvas"
       createGame={createWorldSpaceCanvasGame}
-      codeFiles={[{ name: 'game.ts', content: gameCode }]}
+      highlights={[
+        {
+          text: "Each health bar is a UI canvas with renderMode 'worldSpace', drawn by the same camera as the enemies.",
+          file: 'create-game.ts',
+        },
+        {
+          text: "The left bar is attached with world.setParent, so it inherits the enemy's rotation and spins with it.",
+          file: 'create-game.ts',
+        },
+        {
+          text: 'The right bar has no parent and sits above its enemy through anchoredPosition, so it stays upright.',
+          file: 'create-game.ts',
+        },
+        {
+          text: 'To follow a moving target, a system of your own writes anchoredPosition from its position every frame.',
+          file: 'create-game.ts',
+        },
+      ]}
+      docLinks={[
+        {
+          label: 'Creating a world-space canvas',
+          to: '/docs/docs/ui/creating-a-canvas#creating-a-world-space-canvas',
+        },
+        { label: 'Transforms', to: '/docs/docs/common/transforms' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Builds two spinning enemies, each with a world-space health bar attached a different way.',
+              content: gameCode,
+            },
+          ],
+        },
+      ]}
     />
   );
 }
diff --git a/documentation-site/src/pages/demos/visibility/index.tsx b/documentation-site/src/pages/demos/visibility/index.tsx
index d92621a32..a38a548ca 100644
--- a/documentation-site/src/pages/demos/visibility/index.tsx
+++ b/documentation-site/src/pages/demos/visibility/index.tsx
@@ -4,55 +4,76 @@ import gameCode from '!!raw-loader!./_create-game';
 import menuCode from '!!raw-loader!./_create-menu';
 import beaconCode from '!!raw-loader!./_create-beacon';
 
-import { Demo } from '@site/src/components/Demo';
-import { InteractionInstruction } from '@site/src/components/_InteractionInstruction';
-
-const badgeStyle: React.CSSProperties = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  width: 20,
-  height: 20,
-  borderRadius: '50%',
-  backgroundColor: 'var(--ifm-color-emphasis-300)',
-  fontSize: 12,
-};
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function Visibility(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Visibility',
-        description:
-          'A demo showcasing VisibilityEcsComponent hiding an entity and everything parented under it, in the world and in UI.',
-      }}
-      header="Visibility"
-      blurb="Each toggle sets one VisibilityEcsComponent. Hiding 'Load game' takes it out of the menu's vertical layout group, so the buttons below move up and the panel shrinks. Hiding the menu hides the panel, its title and every button, which can no longer be hovered, clicked or focused. Fading the menu sets a canvas group's alpha instead: the menu stays laid out, drawn and clickable. Hiding the beacon hides its lamp and stops its spark emitter, while sparks already in the air fade out."
+    <DemoPage
+      slug="visibility"
       createGame={createVisibilityGame}
-      interactions={
-        <>
-          <InteractionInstruction
-            displayElement={
-              <div style={badgeStyle}>
-                <i className="fa-solid fa-computer-mouse" />
-              </div>
-            }
-            text="Click the toggles to hide and show parts of the scene."
-          />
-          <InteractionInstruction
-            displayElement={
-              <div style={badgeStyle}>
-                <i className="fa-solid fa-keyboard" />
-              </div>
-            }
-            text="Arrow keys move focus; hiding the focused button clears focus."
-          />
-        </>
-      }
-      codeFiles={[
-        { name: 'game.ts', content: gameCode },
-        { name: 'menu.ts', content: menuCode },
-        { name: 'beacon.ts', content: beaconCode },
+      controls={[
+        {
+          inputs: [{ device: 'mouse', label: 'Click' }],
+          action: 'Show, hide or fade',
+          detail: 'Click a checkbox in the top-left corner',
+        },
+        { inputs: ['↑↓←→'], action: 'Move focus' },
+        { inputs: ['Enter', 'Space'], action: 'Tick the focused checkbox' },
+      ]}
+      highlights={[
+        {
+          text: "Hiding 'Load game' takes it out of the menu's layout group, so the buttons below move up and the panel shrinks.",
+          file: 'create-menu.ts',
+        },
+        {
+          text: 'Hiding the menu hides the panel and everything under it. Its buttons can no longer be hovered, clicked or focused, and a hidden button loses focus.',
+          file: 'create-menu.ts',
+        },
+        {
+          text: "Fading the menu sets a canvas group's alpha instead, so it stays laid out, drawn and clickable.",
+          file: 'create-menu.ts',
+        },
+        {
+          text: 'Hiding the beacon hides its lamp and stops its spark emitter, while sparks already in the air fade out.',
+          file: 'create-beacon.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Visibility', to: '/docs/docs/rendering/visibility' },
+        {
+          label: 'Hiding, fading and tooltips',
+          to: '/docs/docs/ui/canvas-groups-and-tooltips',
+        },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Builds the menu, the beacon and the toggles that hide and fade them.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-menu.ts',
+              summary:
+                'A fitted button menu with a visibility component and a canvas group.',
+              content: menuCode,
+            },
+            {
+              name: 'create-beacon.ts',
+              summary:
+                'A beacon with a child lamp and a spark emitter, hidden as one.',
+              content: beaconCode,
+            },
+          ],
+        },
       ]}
     />
   );
diff --git a/documentation-site/src/pages/demos/wrecking-ball/index.tsx b/documentation-site/src/pages/demos/wrecking-ball/index.tsx
index 7653f24e3..c688a322f 100644
--- a/documentation-site/src/pages/demos/wrecking-ball/index.tsx
+++ b/documentation-site/src/pages/demos/wrecking-ball/index.tsx
@@ -2,28 +2,76 @@ import React, { JSX } from 'react';
 import { createWreckingBallGame } from './_create-game';
 import gameCode from '!!raw-loader!./_create-game';
 import createWreckingBallCode from '!!raw-loader!./_create-wrecking-ball';
+import armComponentCode from '!!raw-loader!./_arm.component';
+import armSystemCode from '!!raw-loader!./_arm.system';
 
-import { Demo } from '@site/src/components/Demo';
+import { DemoPage } from '@site/src/components/demo-page';
 
 export default function WreckingBall(): JSX.Element {
   return (
-    <Demo
-      metaData={{
-        title: 'Wrecking Ball Demo',
-        description:
-          "A demo showcasing the physics engine's RevoluteJoint and collision resolution together: a ball hinged to a crane, swung into a wall of bricks.",
-      }}
-      header="Wrecking Ball"
-      blurb="A ball is hinged to a crane by a long arm, pulled back to one side, and released exactly once, when the scene is built, swinging into a wall of bricks. The joint only keeps the ball swinging about the crane's pivot; knocking the wall down comes entirely from the engine's ordinary collision resolution between the ball and the bricks, the same combination of joint and collisions used in the Newton's Cradle demo. After the first swing it's left alone rather than re-launched, so it settles the way a real wrecking ball would after a single push."
+    <DemoPage
+      slug="wrecking-ball"
       createGame={createWreckingBallGame}
-      codeFiles={[
+      highlights={[
         {
-          name: 'game.ts',
-          content: gameCode,
+          text: "A heavy ball hangs from the crane's pivot on a revolute joint, which keeps it swinging in an arc.",
+          file: 'create-wrecking-ball.ts',
         },
         {
-          name: 'create-wrecking-ball.ts',
-          content: createWreckingBallCode,
+          text: 'Knocking the wall down is ordinary collision resolution between the ball and the light, dynamic bricks.',
+          file: 'create-wrecking-ball.ts',
+        },
+        {
+          text: 'The ball is pulled back and released once when the scene is built, then left to settle.',
+          file: 'create-wrecking-ball.ts',
+        },
+        {
+          text: 'Joints are invisible, so a demo system stretches and turns a sprite between the pivot and ball every tick.',
+          file: 'arm.system.ts',
+        },
+      ]}
+      docLinks={[
+        { label: 'Joints', to: '/docs/docs/physics/joints' },
+        { label: 'Collisions', to: '/docs/docs/physics/collisions' },
+      ]}
+      fileGroups={[
+        {
+          title: 'Start here',
+          files: [
+            {
+              name: 'create-game.ts',
+              summary:
+                'Sets up the camera and scene, and registers every system in the order they run.',
+              content: gameCode,
+            },
+          ],
+        },
+        {
+          title: 'Building the scene',
+          files: [
+            {
+              name: 'create-wrecking-ball.ts',
+              summary: 'Builds the pivot, hinged ball, floor and brick wall.',
+              content: createWreckingBallCode,
+            },
+          ],
+        },
+        {
+          title: 'Drawing the arm',
+          files: [
+            {
+              name: 'arm.component.ts',
+              summary:
+                'Links an arm sprite to a fixed pivot and a swinging body.',
+              content: armComponentCode,
+            },
+            {
+              name: 'arm.system.ts',
+              summary:
+                'Positions, rotates and stretches the arm between the pivot and ball.',
+              content: armSystemCode,
+            },
+          ],
         },
       ]}
     />
diff --git a/documentation-site/src/pages/index.module.css b/documentation-site/src/pages/index.module.css
deleted file mode 100644
index 7f77cc85d..000000000
--- a/documentation-site/src/pages/index.module.css
+++ /dev/null
@@ -1,50 +0,0 @@
-/**
- * CSS files with the .module.css suffix will be treated as CSS modules
- * and scoped locally.
- */
-
-.heroBanner {
-  padding: 4rem 0;
-  text-align: center;
-  position: relative;
-  z-index: 0;
-  overflow: hidden;
-  height: 100%;
-  flex-grow: 1;
-}
-
-@media screen and (max-width: 996px) {
-  .heroBanner {
-    padding: 2rem;
-  }
-}
-
-.heroVideo {
-  position: absolute;
-  top: 0;
-  left: 0;
-  width: 100%;
-  height: 100%;
-  object-fit: cover;
-  filter: blur(10px);
-  transform: scale(1.1);
-  z-index: -1;
-}
-
-.heroVideoOverlay {
-  position: absolute;
-  top: 0;
-  left: 0;
-  width: 100%;
-  height: 100%;
-  background: rgba(0, 0, 0, 0.5);
-  z-index: -1;
-}
-
-.buttons {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  flex-direction: column;
-  gap: 1rem;
-}
diff --git a/documentation-site/src/pages/index.tsx b/documentation-site/src/pages/index.tsx
index b71f49156..e6030e299 100644
--- a/documentation-site/src/pages/index.tsx
+++ b/documentation-site/src/pages/index.tsx
@@ -1,61 +1,274 @@
 import type { ReactNode } from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useBaseUrl from '@docusaurus/useBaseUrl';
 import Layout from '@theme/Layout';
-import Heading from '@theme/Heading';
+import { DemoCard } from '@site/src/components/DemoCard';
+import { ModuleIcon, ModuleIconName } from '@site/src/components/ModuleIcon';
+import styles from '@site/src/components/home/Home.module.css';
+import { InstallCommand } from '@site/src/components/home/InstallCommand';
+import { demos } from '@site/src/data/demos';
 
-import styles from './index.module.css';
+interface EngineModule {
+  title: string;
+  description: string;
+  icon: ModuleIconName;
+  to: string;
+}
+
+const engineModules: EngineModule[] = [
+  {
+    title: 'ECS',
+    description: 'Entities, components and systems',
+    icon: 'ecs',
+    to: '/docs/docs/ecs',
+  },
+  {
+    title: 'Rendering',
+    description: 'WebGL2 sprites, cameras and nine-slice',
+    icon: 'rendering',
+    to: '/docs/docs/rendering',
+  },
+  {
+    title: 'Post-processing',
+    description: 'Bloom, blur and HDR',
+    icon: 'postProcessing',
+    to: '/docs/docs/rendering/bloom',
+  },
+  {
+    title: 'Physics',
+    description: 'Rigid bodies, joints and raycasts',
+    icon: 'physics',
+    to: '/docs/docs/physics',
+  },
+  {
+    title: 'UI',
+    description: 'Anchored layout, menus and controls',
+    icon: 'ui',
+    to: '/docs/docs/ui',
+  },
+  {
+    title: 'Text',
+    description: 'Sharp MSDF text at any size',
+    icon: 'text',
+    to: '/docs/docs/text',
+  },
+  {
+    title: 'Input',
+    description: 'Keyboard, mouse and gamepad',
+    icon: 'input',
+    to: '/docs/docs/input',
+  },
+  {
+    title: 'Audio',
+    description: 'Sounds and music through mixer buses',
+    icon: 'audio',
+    to: '/docs/docs/audio',
+  },
+  {
+    title: 'Animations',
+    description: 'Sprite sheets and easing',
+    icon: 'animations',
+    to: '/docs/docs/animations',
+  },
+  {
+    title: 'Particles',
+    description: 'Emitters, bursts and spawn shapes',
+    icon: 'particles',
+    to: '/docs/docs/particles',
+  },
+  {
+    title: 'Transforms',
+    description: 'Parent and child hierarchies',
+    icon: 'transforms',
+    to: '/docs/docs/common/transforms',
+  },
+  {
+    title: 'Asset loading',
+    description: 'Cached images and font atlases',
+    icon: 'assetLoading',
+    to: '/docs/docs/asset-loading',
+  },
+  {
+    title: 'Game states',
+    description: 'Menus, rounds and the switches between them',
+    icon: 'states',
+    to: '/docs/docs/states',
+  },
+  {
+    title: 'State machines',
+    description: 'States and the transitions between them',
+    icon: 'stateMachines',
+    to: '/docs/api/classes/FiniteStateMachine',
+  },
+  {
+    title: 'Events',
+    description: 'Decoupled game events',
+    icon: 'events',
+    to: '/docs/docs/events',
+  },
+  {
+    title: 'Timers',
+    description: 'Delayed and repeating callbacks',
+    icon: 'timers',
+    to: '/docs/docs/timer',
+  },
+  {
+    title: 'Lifetimes',
+    description: 'Entity expiry and removal',
+    icon: 'lifetimes',
+    to: '/docs/docs/lifecycle',
+  },
+  {
+    title: 'Storage',
+    description: 'Persistent state and storage backends',
+    icon: 'storage',
+    to: '/docs/docs/storage',
+  },
+  {
+    title: 'Math',
+    description: 'Vectors, matrices and seeded random',
+    icon: 'math',
+    to: '/docs/docs/math',
+  },
+  {
+    title: 'Game loop',
+    description: 'Frame timing and resizing',
+    icon: 'gameLoop',
+    to: '/docs/docs/ecs/game',
+  },
+];
+
+const featuredDemoSlugs = ['car', 'space-shooter', 'text', 'physics'];
+
+// Gameplay of Galactic Journey, a game built with Forge, as WebM (VP9) and
+// MP4 (H.264): each browser plays the first format it supports.
+const heroVideoPaths = {
+  webm: '/videos/galactic-journey.webm',
+  mp4: '/videos/galactic-journey.mp4',
+};
+const galacticJourneyUrl = 'https://galactic-journey-6517e.web.app';
 
-function HomepageHeader() {
-  const { siteConfig } = useDocusaurusContext();
+const Hero = (): ReactNode => {
+  const webmUrl = useBaseUrl(heroVideoPaths.webm);
+  const mp4Url = useBaseUrl(heroVideoPaths.mp4);
 
   return (
-    <header className={clsx('hero hero--primary', styles.heroBanner)}>
-      <video
-        className={styles.heroVideo}
-        src={`${siteConfig.baseUrl}videos/Hero.mp4`}
-        autoPlay
-        loop
-        muted
-        playsInline
-      />
-      <div className={styles.heroVideoOverlay} />
-      <div className="container">
-        <img
-          src={`${siteConfig.baseUrl}/img/Logo_Transparent.png`}
-          alt="Site Logo"
-          style={{ display: 'block', margin: '0 auto 1rem', maxWidth: 160 }}
-        />
-        <Heading as="h1" className="hero__title">
-          {siteConfig.title}
-        </Heading>
-        <p className="hero__subtitle">{siteConfig.tagline}</p>
-        <div className={styles.buttons}>
-          <Link className="button button--primary button--lg" to="/docs/intro">
-            Get Started!
-          </Link>
-          <Link
-            className="button button--secondary button--lg"
-            to="/docs/category/documentation"
-          >
-            Documentation
-          </Link>
+    <header className={styles.hero}>
+      <div className={styles.heroInner}>
+        <div className={styles.heroText}>
+          <h1 className={styles.heroTitle}>Forge</h1>
+          <p className={styles.heroIntro}>
+            Build 2D games for the web in TypeScript. Built on an ECS core,
+            rendered with WebGL2.
+          </p>
+          <div className={styles.heroActions}>
+            <Link
+              className="button button--primary button--lg"
+              to="/docs/intro"
+            >
+              Get started
+            </Link>
+            <Link
+              className={clsx(
+                'button button--secondary button--lg',
+                styles.heroSecondary,
+              )}
+              to="/demos"
+            >
+              Browse demos
+            </Link>
+          </div>
+          <InstallCommand />
         </div>
+        <figure className={styles.heroMedia}>
+          <div className={styles.heroScreen}>
+            <video
+              className={styles.heroVideo}
+              autoPlay
+              loop
+              muted
+              playsInline
+              aria-label="Gameplay of Galactic Journey, a game made with Forge"
+            >
+              <source src={webmUrl} type="video/webm" />
+              <source src={mp4Url} type="video/mp4" />
+            </video>
+          </div>
+          <figcaption className={styles.heroCaption}>
+            Galactic Journey, made with Forge ·{' '}
+            <Link to={galacticJourneyUrl}>Play it</Link>
+          </figcaption>
+        </figure>
       </div>
     </header>
   );
-}
+};
 
-export default function Home(): ReactNode {
-  const { siteConfig } = useDocusaurusContext();
+const Modules = (): ReactNode => (
+  <section className={styles.section}>
+    <h2 className={styles.sectionTitle}>Everything you need</h2>
+    <p className={styles.sectionIntro}>To build a great 2D game.</p>
+    <div className={styles.moduleGrid}>
+      {engineModules.map((engineModule) => (
+        <Link
+          key={engineModule.title}
+          to={engineModule.to}
+          className={styles.module}
+        >
+          <ModuleIcon name={engineModule.icon} />
+          <div>
+            <h3 className={styles.moduleTitle}>{engineModule.title}</h3>
+            <p className={styles.moduleDescription}>
+              {engineModule.description}
+            </p>
+          </div>
+        </Link>
+      ))}
+    </div>
+  </section>
+);
+
+const FeaturedDemos = (): ReactNode => {
+  const featured = featuredDemoSlugs.map((slug) => {
+    const demo = demos.find((candidate) => candidate.slug === slug);
 
+    if (!demo) {
+      throw new Error(`No demo with slug "${slug}" in src/data/demos.ts.`);
+    }
+
+    return demo;
+  });
+
+  return (
+    <section className={styles.section}>
+      <h2 className={styles.sectionTitle}>Demos</h2>
+      <p className={styles.sectionIntro}>
+        Try features and games live in your browser.
+      </p>
+      <div className={styles.demoGrid}>
+        {featured.map((demo) => (
+          <DemoCard key={demo.slug} demo={demo} />
+        ))}
+      </div>
+      <p className={styles.sectionFooter}>
+        <Link to="/demos">All demos →</Link>
+      </p>
+    </section>
+  );
+};
+
+export default function Home(): ReactNode {
   return (
     <Layout
-      title={siteConfig.title}
-      description="Forge is a browser-based, code only game engine. It has everything you would expect from an engine, including rendering, audio, input, animations, ECS, etc."
+      title="Browser game engine"
+      description="Forge is a TypeScript game engine for the browser: built on an ECS core and rendered with WebGL2."
     >
-      <HomepageHeader />
+      <Hero />
+      <main>
+        <Modules />
+        <FeaturedDemos />
+      </main>
     </Layout>
   );
 }
diff --git a/documentation-site/static/img/blue-circle.png b/documentation-site/static/img/blue-circle.png
deleted file mode 100644
index b77661d92..000000000
Binary files a/documentation-site/static/img/blue-circle.png and /dev/null differ
diff --git a/documentation-site/static/img/demos/categories/animations.svg b/documentation-site/static/img/demos/categories/animations.svg
deleted file mode 100644
index f8ff505ce..000000000
--- a/documentation-site/static/img/demos/categories/animations.svg
+++ /dev/null
@@ -1,7 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 270" role="img" aria-hidden="true">
-  <rect width="480" height="270" rx="24" fill="#fce7f3" />
-  <line x1="110" y1="200" x2="110" y2="70" stroke="#f9a8d4" stroke-width="4" />
-  <line x1="110" y1="200" x2="370" y2="200" stroke="#f9a8d4" stroke-width="4" />
-  <path d="M110 200 C 180 200, 180 70, 240 70 S 300 200, 370 90" fill="none" stroke="#db2777" stroke-width="7" stroke-linecap="round" />
-  <circle cx="290" cy="130" r="10" fill="#db2777" />
-</svg>
diff --git a/documentation-site/static/img/demos/categories/ecs.svg b/documentation-site/static/img/demos/categories/ecs.svg
deleted file mode 100644
index fa2db5c2f..000000000
--- a/documentation-site/static/img/demos/categories/ecs.svg
+++ /dev/null
@@ -1,9 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 270" role="img" aria-hidden="true">
-  <rect width="480" height="270" rx="24" fill="#ccfbf1" />
-  <line x1="240" y1="90" x2="160" y2="180" stroke="#0d9488" stroke-width="5" />
-  <line x1="240" y1="90" x2="320" y2="180" stroke="#0d9488" stroke-width="5" />
-  <line x1="160" y1="180" x2="320" y2="180" stroke="#0d9488" stroke-width="5" />
-  <circle cx="240" cy="90" r="26" fill="#0d9488" />
-  <circle cx="160" cy="180" r="20" fill="#2dd4bf" />
-  <circle cx="320" cy="180" r="20" fill="#2dd4bf" />
-</svg>
diff --git a/documentation-site/static/img/demos/categories/games.svg b/documentation-site/static/img/demos/categories/games.svg
deleted file mode 100644
index 6b4fc03f8..000000000
--- a/documentation-site/static/img/demos/categories/games.svg
+++ /dev/null
@@ -1,8 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 270" role="img" aria-hidden="true">
-  <rect width="480" height="270" rx="24" fill="#fee2e2" />
-  <rect x="120" y="105" width="240" height="90" rx="45" fill="#dc2626" />
-  <rect x="165" y="135" width="40" height="12" rx="4" fill="#fecaca" />
-  <rect x="179" y="121" width="12" height="40" rx="4" fill="#fecaca" />
-  <circle cx="320" cy="135" r="11" fill="#fecaca" />
-  <circle cx="300" cy="160" r="11" fill="#fecaca" />
-</svg>
diff --git a/documentation-site/static/img/demos/categories/particles.svg b/documentation-site/static/img/demos/categories/particles.svg
deleted file mode 100644
index cb9e823fb..000000000
--- a/documentation-site/static/img/demos/categories/particles.svg
+++ /dev/null
@@ -1,14 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 270" role="img" aria-hidden="true">
-  <rect width="480" height="270" rx="24" fill="#ffedd5" />
-  <circle cx="240" cy="150" r="10" fill="#ea580c" />
-  <circle cx="240" cy="90" r="8" fill="#fb923c" />
-  <circle cx="185" cy="115" r="7" fill="#fb923c" />
-  <circle cx="295" cy="115" r="7" fill="#fb923c" />
-  <circle cx="170" cy="165" r="6" fill="#fdba74" />
-  <circle cx="310" cy="165" r="6" fill="#fdba74" />
-  <circle cx="200" cy="195" r="5" fill="#fdba74" />
-  <circle cx="280" cy="195" r="5" fill="#fdba74" />
-  <circle cx="240" cy="205" r="9" fill="#ea580c" />
-  <circle cx="150" cy="90" r="4" fill="#fed7aa" />
-  <circle cx="330" cy="90" r="4" fill="#fed7aa" />
-</svg>
diff --git a/documentation-site/static/img/demos/categories/physics.svg b/documentation-site/static/img/demos/categories/physics.svg
deleted file mode 100644
index 55ab90dd4..000000000
--- a/documentation-site/static/img/demos/categories/physics.svg
+++ /dev/null
@@ -1,8 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 270" role="img" aria-hidden="true">
-  <rect width="480" height="270" rx="24" fill="#dbeafe" />
-  <line x1="80" y1="210" x2="400" y2="210" stroke="#1d4ed8" stroke-width="6" stroke-linecap="round" />
-  <path d="M110 130 Q170 40 230 130" fill="none" stroke="#93c5fd" stroke-width="4" stroke-dasharray="8 8" />
-  <circle cx="110" cy="150" r="26" fill="#2563eb" />
-  <circle cx="230" cy="150" r="26" fill="#2563eb" />
-  <rect x="300" y="160" width="70" height="50" rx="8" fill="#1d4ed8" transform="rotate(8 335 185)" />
-</svg>
diff --git a/documentation-site/static/img/demos/categories/rendering.svg b/documentation-site/static/img/demos/categories/rendering.svg
deleted file mode 100644
index 2a99ca292..000000000
--- a/documentation-site/static/img/demos/categories/rendering.svg
+++ /dev/null
@@ -1,9 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 270" role="img" aria-hidden="true">
-  <rect width="480" height="270" rx="24" fill="#ede9fe" />
-  <rect x="120" y="60" width="240" height="140" rx="10" fill="#ffffff" stroke="#7c3aed" stroke-width="6" />
-  <rect x="138" y="78" width="204" height="104" fill="#c4b5fd" />
-  <circle cx="200" cy="120" r="16" fill="#fbbf24" />
-  <path d="M138 182 L200 130 L240 160 L280 110 L342 182 Z" fill="#7c3aed" />
-  <rect x="200" y="200" width="80" height="14" rx="4" fill="#7c3aed" />
-  <rect x="220" y="214" width="40" height="10" rx="4" fill="#7c3aed" />
-</svg>
diff --git a/documentation-site/static/img/demos/categories/ui.svg b/documentation-site/static/img/demos/categories/ui.svg
deleted file mode 100644
index fd949124e..000000000
--- a/documentation-site/static/img/demos/categories/ui.svg
+++ /dev/null
@@ -1,10 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 270" role="img" aria-hidden="true">
-  <rect width="480" height="270" rx="24" fill="#dcfce7" />
-  <rect x="110" y="55" width="260" height="160" rx="12" fill="#ffffff" stroke="#16a34a" stroke-width="6" />
-  <rect x="130" y="80" width="90" height="28" rx="14" fill="#16a34a" />
-  <circle cx="330" cy="94" r="14" fill="#ffffff" stroke="#16a34a" stroke-width="6" />
-  <rect x="300" y="88" width="60" height="12" rx="6" fill="#bbf7d0" />
-  <rect x="130" y="130" width="200" height="10" rx="5" fill="#bbf7d0" />
-  <circle cx="230" cy="135" r="12" fill="#16a34a" />
-  <rect x="130" y="160" width="90" height="30" rx="6" fill="#16a34a" />
-</svg>
diff --git a/documentation-site/static/img/scroll.png b/documentation-site/static/img/scroll.png
deleted file mode 100644
index 55ee9f521..000000000
Binary files a/documentation-site/static/img/scroll.png and /dev/null differ
diff --git a/documentation-site/static/videos/Hero.mp4 b/documentation-site/static/videos/Hero.mp4
deleted file mode 100644
index 4496ea26a..000000000
Binary files a/documentation-site/static/videos/Hero.mp4 and /dev/null differ
diff --git a/documentation-site/static/videos/galactic-journey.mp4 b/documentation-site/static/videos/galactic-journey.mp4
new file mode 100644
index 000000000..a7304d15d
Binary files /dev/null and b/documentation-site/static/videos/galactic-journey.mp4 differ
diff --git a/documentation-site/static/videos/galactic-journey.webm b/documentation-site/static/videos/galactic-journey.webm
new file mode 100644
index 000000000..524462143
Binary files /dev/null and b/documentation-site/static/videos/galactic-journey.webm differ