From a7fa1bd8fdec26ba920077900e636b5add5a02b4 Mon Sep 17 00:00:00 2001
From: "Yifeng \"Evan\" Wang" <7312949+doodlewind@users.noreply.github.com>
Date: Sun, 23 Aug 2026 08:43:08 +0800
Subject: [PATCH] docs: restate PocketJS as a portable application runtime

One positioning sentence now carries the project everywhere it is defined:
"PocketJS is a portable application runtime that turns modern component code
into native pixels across radically different hardware." It replaces the
UI-runtime-minus-the-browser framing in the landing hero, the homepage and
site-wide meta descriptions, the docs overview and architecture intros, and the
npm package description. The landing headline becomes "UI runtime for every
kind of computer"; the pinned hero copy in tests/site-stage.test.ts follows.

The README keeps the chapter order it gained in #325 but drops the landing
voice: section names are now plain technical headings (Programming model,
Rendering and execution, Performance, Native modules, Hardware support,
Applications, Getting started, Ahead-of-time compilation, Repository layout,
Building and testing, Documentation), prose is third person, and the frameworks,
styling, animation and target-admission material sits under subsections. Adds a
Contents list and a Documentation index; keeps every measurement, receipt link
and attribution.

Verified: `bun run test` (11/11 stages), `bun run site:build`, and a headless
Chrome measurement of the three-line headline (widest line 445 px against 651 px
of plate at 1600w, no overflow at 1600/1280/820/390 px).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                            | 304 +++++++++++++++------------
 package.json                         |   2 +-
 site/build.ts                        |   2 +-
 site/content/docs/architecture.md    |   7 +-
 site/content/docs/getting-started.md |   7 +-
 site/content/docs/overview.md        |  13 +-
 site/home.html                       |   9 +-
 site/templates.ts                    |   4 +-
 tests/site-stage.test.ts             |   6 +-
 9 files changed, 200 insertions(+), 154 deletions(-)

diff --git a/README.md b/README.md
index 24673b71..a9958898 100644
--- a/README.md
+++ b/README.md
@@ -13,22 +13,36 @@
 [Pocket Lab](https://pocketlab.build) ·
 [Pocket Museum](https://museum.pocketlab.build/)
 
-## Keeps JSX, Tailwind and reactive state. Removes every layer below them.
-
-PocketJS is a UI runtime with **no DOM, no CSS engine and no WebView**. An app
-is a QuickJS guest on a Rust core that performs flexbox layout and draws every
-pixel itself, in **one thread inside one process**. The frameworks, the class
-strings and the reactive state stay the ones you already use; everything under
-them is replaced.
+PocketJS is a portable application runtime that turns modern component code into
+native pixels across radically different hardware. Solid, Vue Vapor and Octane
+components compile to one native tree, and a QuickJS guest drives a Rust core
+that performs flexbox layout and draws every pixel **in one thread inside one
+process**. There is **no DOM, no CSS engine and no WebView**.
 
 <a href="https://pocketjs.dev">
   <img src="./site/assets/pocketjs-demo-wall.jpg" alt="A wall of PocketJS software: music, deep-zoom graphics, messaging, a digital character, galleries, DevTools, dashboards, media, and a café app, alongside OpenStrike, Pocket Voxel and Pocket Figma on PSP, including Motion Lab studies credited to yui540" />
 </a>
 
-## Write components as you already do
+## Contents
+
+- [Programming model](#programming-model)
+- [Rendering and execution](#rendering-and-execution)
+- [Performance](#performance)
+- [Native modules](#native-modules)
+- [Hardware support](#hardware-support)
+- [Applications](#applications)
+- [Getting started](#getting-started)
+- [Ahead-of-time compilation](#ahead-of-time-compilation)
+- [Repository layout](#repository-layout)
+- [Building and testing](#building-and-testing)
+- [Documentation](#documentation)
+
+## Programming model
+
+### Frameworks
 
 Three frameworks compile to the same native tree and run on the same QuickJS
-guest, so the framework you pick changes your code and nothing below it.
+guest. The choice changes application code and nothing below it.
 
 | Framework | State and lifecycle | Source forms |
 | --- | --- | --- |
@@ -36,7 +50,7 @@ guest, so the framework you pick changes your code and nothing below it.
 | **Vue Vapor** | `vue` | JSX and `<script setup>` single-file components |
 | **Octane** | `octane` | Compiled hooks and JSX, with no virtual DOM |
 
-Framework primitives come directly from `solid-js`, `vue`, or `octane`.
+Framework primitives are imported directly from `solid-js`, `vue`, or `octane`.
 PocketJS owns the runtime, host components, lifecycle wiring, input, animation,
 assets, and the native boundary.
 
@@ -68,11 +82,44 @@ function Counter() {
 mount(() => <Counter />);
 ```
 
-Class literals compile into a baked style table at build time. There is no
-runtime CSS parser, cascade, or specificity resolution, and no reflow: the core
-lays out the tree and emits a draw list that the target backend submits through
-GE, GXM, Metal, wgpu, software rasterization, e-ink updates, or another declared
-host.
+### Styling
+
+Class literals are compiled into a baked style table at build time. The runtime
+resolves a class attribute by lookup, so there is no CSS parser, cascade,
+specificity resolution, or reflow on the device. The accepted vocabulary is a
+fixed Tailwind subset, enumerated in
+[Tailwind utilities](https://pocketjs.dev/docs/tailwind/).
+
+### Animation
+
+Keyframe timelines and spring curves are baked into the same style table and
+advanced by the Rust core on its own clock, so a screen can animate **with no
+per-frame JavaScript**. Motion Lab runs the yui540 studies in WebAssembly on
+[pocketjs.dev](https://pocketjs.dev) and on the handheld they were written for.
+
+| Baked keyframe timelines · (yui540) | 3D motion pipeline · (yui540) |
+| --- | --- |
+| ![Motion studies by yui540: menu, d-pad, share, hover, reload and keypad animations](./assets/screenshots/motions-53.gif) | ![3D motion studies by yui540: door, cubes, page flips and room transition](./assets/screenshots/motions-3d.gif) |
+
+### Target admission
+
+One bundle serves machines of different densities. An application declares its
+viewport and required APIs in `pocket.json`, and a target profile must satisfy
+that declaration before compilation and packaging proceed. Run from the
+application directory:
+
+```sh
+pocket check --target psp     # ok  480x272 · text.glyphs.baked · input.buttons
+pocket check --target vita    # ok  same bundle, density 2, no component edited
+```
+
+## Rendering and execution
+
+### From component to pixel
+
+The guest emits tree mutations; the core owns layout, the style table, and the
+draw list; a per-target backend submits that draw list through GE, GXM, Metal,
+wgpu, software rasterization, e-ink updates, or another declared host.
 
 ```text
 PocketJS · 1 thread, 1 process
@@ -102,55 +149,67 @@ Browser or WebView · 4 threads, 2 processes
   → pixels
 ```
 
-One bundle serves machines of different densities. The manifest declares what
-the app needs, and the target is checked against it before a build proceeds —
-from the app directory, against its `pocket.json`:
+### The frame contract
 
-```sh
-pocket check --target psp     # ok  480x272 · text.glyphs.baked · input.buttons
-pocket check --target vita    # ok  same bundle, density 2, no component edited
-```
+Time is the frame counter. One `frame(buttons)` call is a transaction that
+nothing outside it can interrupt, and nothing waits on a wall clock, so tests
+run as fast as the CPU allows without changing the timing they measure: a
+journey that takes six seconds in front of a user is a few dozen frames in CI.
 
-See [Frameworks](https://pocketjs.dev/docs/frameworks/),
-[Architecture](https://pocketjs.dev/docs/architecture/) and
-[Styling](https://pocketjs.dev/docs/styling/).
+```text
+state n+1 = F(state n, input n)
+pixels n  = G(state n)
+```
 
-## Animation is compiled
+- **Effects land on frame boundaries.** A network reply that arrives partway
+  through frame +3 is queued, not applied. It is delivered at the start of
+  frame +4, in FIFO order, before any application hook runs. There are no
+  microtask races and no mid-frame callbacks, and `after()` replaces
+  `setTimeout` with a deadline measured in frames.
+- **An async task lands on the same frame every run.** Driven by
+  `requestAnimationFrame` against a wall clock, one awaited confirmation lands
+  on **22 different frames** across 60 runs, and its timing assertion passes
+  **9 times out of 60**. On the frame clock it lands on **frame 144 in every
+  run**, 60 out of 60.
+- **History is a data structure.** Tapes replay byte-for-byte, a session
+  subsampled to 2 Hz is byte-identical to its 60 Hz counterpart, and forking a
+  tape at frame 9 to splice in a different press produces a counterfactual
+  world in **22 ms**.
+- **Chaos mode verifies the floor**, injecting real sleeps, allocation churn and
+  forced GC between frames without moving the trace by one bit.
 
-Keyframe timelines and spring curves are baked into the style table at build
-time and advanced by the Rust core on its own clock, so a screen can **animate
-with no per-frame JavaScript at all**. Motion Lab runs the yui540 studies in
-WebAssembly on [pocketjs.dev](https://pocketjs.dev), and on the handheld they
-were written for.
+See also: [The runtime that can't flake](https://pocketjs.dev/blog/ui-runtime-that-cant-flake/) ·
+[Time-travel DevTools](https://pocketjs.dev/blog/time-travel-devtools/) ·
+[Determinism](./docs/DETERMINISM.md)
 
-| Baked keyframe timelines · (yui540) | 3D motion pipeline · (yui540) |
-| --- | --- |
-| ![Motion studies by yui540: menu, d-pad, share, hover, reload and keypad animations](./assets/screenshots/motions-53.gif) | ![3D motion studies by yui540: door, cubes, page flips and room transition](./assets/screenshots/motions-3d.gif) |
+## Performance
 
-## What it asks of the machine
+With no browser engine in the pipeline, the cost of a screen stays close to what
+the hardware can do. A complete application drawing an animated interface
+**occupies 8 MB on a single 333 MHz core**: a quarter of the PSP's 32 MB, one
+part in 1536 of a 12 GB iPhone 17 Pro Max, on a core clocked 13 times slower
+than an A19 Pro performance core at 4.26 GHz.
 
-With no browser engine in the middle, the cost of a screen is close to what the
-bare metal can do. A whole PocketJS app drawing a smooth interface **lives in
-8 MB on a single 333 MHz core** — a quarter of the PSP's 32 MB, one part in 1536
-of a 12 GB iPhone 17 Pro Max, on a core clocked 13 times slower than an A19 Pro
-performance core at 4.26 GHz.
+### On a Sony PSP
 
-Benchmarked on a Sony PSP — one MIPS core at 333 MHz, 32 MB of RAM, 2004
-hardware, against the 16.67 ms budget for 60 fps:
+One MIPS core at 333 MHz, 32 MB of RAM, measured against the 16.67 ms budget for
+60 fps:
 
 | Measurement | Result |
 | --- | --- |
 | OpenStrike frame budget | **2.2 ms** of JavaScript, 8.4 ms of total CPU work, worst observed frame 9.7 ms |
-| Hero demo, why not just ship a virtual DOM | Solid 15.15 ms · Vue Vapor 16.74 ms · **Vue with a virtual DOM 90.75 ms** |
+| Hero demo, cost of a virtual DOM | Solid 15.15 ms · Vue Vapor 16.74 ms · **Vue with a virtual DOM 90.75 ms** |
 | Hero demo, the three shipped frameworks | Solid 3.66 ms · Vue Vapor 3.61 ms · Octane 6.53 ms |
 
-Seven samples per app. The two hero-demo rows come from separate runs and the
-toolchain got faster in between, so read each on its own terms rather than
-across them.
+Seven samples per application. The two hero-demo rows come from separate runs
+with different toolchain versions, so each row is comparable internally but not
+against the other.
 
-The same markdown editor, shelled three ways on an Apple M3 Max
-([full report](./docs/bench/gpui-vs-tauri-electron-2026-08-18.md), reproduce
-with `bun tools/bench-desktop.ts`):
+### On a desktop
+
+The same markdown editor shelled three ways on an Apple M3 Max
+([full report](./docs/bench/gpui-vs-tauri-electron-2026-08-18.md), reproduced by
+`bun tools/bench-desktop.ts`):
 
 | | pocket | Tauri v2 | Electron |
 | --- | --- | --- | --- |
@@ -159,60 +218,27 @@ with `bun tools/bench-desktop.ts`):
 | Idle resident memory | **83 MB** | 193 MB | 382 MB |
 | On disk | 10 MB | 9 MB | 242 MB |
 
-Left alone with a document open, the pocket build redraws **about twice a
+With a document open and no input, the pocket build redraws **about twice a
 second**: the caret blinking, and nothing else. The report also records where
-the pocket build loses, and why — the storm CPU ramps with document length,
-because the note re-wraps the whole document through the QuickJS interpreter on
-every keystroke.
+the pocket build loses. Its storm CPU rises with document length, because the
+editor re-wraps the whole document through the QuickJS interpreter on every
+keystroke.
 
-Further reading: [Shipping OpenStrike](https://pocketjs.dev/blog/shipping-openstrike/) ·
+See also: [Shipping OpenStrike](https://pocketjs.dev/blog/shipping-openstrike/) ·
 [Pocket Character](https://pocketjs.dev/blog/pocket-character/) ·
 [Twice the pixels, zero forks](https://pocketjs.dev/blog/pocketjs-on-ps-vita/) ·
 [The first iPhone](https://pocketjs.dev/blog/pocketjs-on-the-first-iphone/)
 
-## The frame contract
-
-Time is the frame counter. One `frame(buttons)` call is a transaction nothing
-outside it can interrupt, and nothing waits on a wall clock, so tests run as
-fast as the CPU allows without changing the timing they measure: a journey that
-takes six seconds in front of a user is a few dozen frames in CI.
-
-```text
-state n+1 = F(state n, input n)
-pixels n  = G(state n)
-```
-
-- **Effects land on frame boundaries.** A network reply that arrives partway
-  through frame +3 is queued, not applied. It is delivered at the start of
-  frame +4, in FIFO order, before any app hook runs. No microtask races, no
-  mid-frame callbacks, and `after()` replaces `setTimeout` with a deadline
-  measured in frames.
-- **The same async task lands on the same frame.** Driven by
-  `requestAnimationFrame` against a wall clock, one awaited confirmation lands
-  on **22 different frames** across 60 runs and its timing assertion passes
-  **9 times out of 60**. On the frame clock it lands on **frame 144 in every
-  run**, 60 out of 60.
-- **History is a data structure.** Tapes replay byte-for-byte, a session
-  subsampled to 2 Hz is byte-identical to its 60 Hz counterpart, and forking a
-  tape at frame 9 to splice in a different press produces a counterfactual
-  world in **22 ms**.
-- **Chaos mode proves the floor holds**, injecting real sleeps, allocation
-  churn and forced GC between frames without moving the trace by one bit.
+## Native modules
 
-Further reading: [The runtime that can't flake](https://pocketjs.dev/blog/ui-runtime-that-cant-flake/) ·
-[Time-travel DevTools](https://pocketjs.dev/blog/time-travel-devtools/) ·
-[Determinism](./docs/DETERMINISM.md)
-
-## Beyond 2D UI: mount what the content needs
-
-PocketJS is an application runtime with a game engine's architecture, so a game
-and an app are built the same way. Cores are **independent native modules,
-loaded the way a kernel loads drivers**: an app takes the ones its content needs
-and the rest never enters the build. Adding one widens what the program is
-allowed to ask for; it never changes how the program is written.
+The runtime has a game engine's architecture, so a game and an application are
+built the same way. Cores are **independent native modules, loaded the way a
+kernel loads drivers**: an application takes the ones its content needs, and the
+rest never enters the build. Mounting a module widens what the program may ask
+for; it does not change how the program is written.
 
 ```text
-guest program · your JavaScript, one frame at a time
+guest program · JavaScript, one frame at a time
   ui       tree, layout, draw, input, focus
   net      poll batches
   audio    pcm mixer
@@ -220,17 +246,16 @@ guest program · your JavaScript, one frame at a time
   voxel    chunks, meshing
 ```
 
-Further reading: [Core concepts](https://pocketjs.dev/docs/concepts/) ·
+See also: [Core concepts](https://pocketjs.dev/docs/concepts/) ·
 [The runtime family](./docs/RUNTIMES.md) ·
 [Pocket3D](./engine/pocket3d/README.md)
 
-## Compatibility: run on the metal, not emulated
+## Hardware support
 
-Not a roadmap. Every entry below has booted the runtime on the real machine, and
-what changes between them is one native submission layer, never the
-application. Keeping the hardware bootable is its own work, so we started
-[Pocket Museum](https://museum.pocketlab.build/) to repair these machines and
-keep them running.
+Every entry below has booted the runtime on the real machine. What changes
+between them is one native submission layer, never the application. Keeping the
+hardware bootable is its own work, tracked in
+[Pocket Museum](https://museum.pocketlab.build/).
 
 | Operating system | Native submission layer | Receipt |
 | --- | --- | --- |
@@ -249,29 +274,29 @@ keep them running.
 | ESP-IDF | RGB565 and PPA | [#160](https://github.com/pocket-stack/pocketjs/pull/160) |
 | The browser | WebAssembly core | [Playground](https://pocketjs.dev/playground/) |
 
-Devices it has booted on: **Sony PSP** (2004) · **PS Vita** (2011) ·
-**iPhone** (2007) · **iPhone 4S** (2011) · **iPod touch 6** (2015) ·
-**Nokia E7** (2011) · **Meizu M8** (2009) · **BlackBerry Classic** (2014) ·
-**PocketBook reader** (e-ink) · **ESP32-P4 devkit** (microcontroller) ·
+Devices verified so far: **Sony PSP** (2004), **PS Vita** (2011),
+**iPhone** (2007), **iPhone 4S** (2011), **iPod touch 6** (2015),
+**Nokia E7** (2011), **Meizu M8** (2009), **BlackBerry Classic** (2014),
+**PocketBook reader** (e-ink), **ESP32-P4 devkit** (microcontroller), and
 **Mac** (Apple silicon).
 
-The authoritative host and target inventory lives in
-[`contracts/spec/platforms.ts`](./contracts/spec/platforms.ts); an entry there
+The authoritative host and target inventory is
+[`contracts/spec/platforms.ts`](./contracts/spec/platforms.ts); each entry
 records what has been verified and how. See
 [Platform contracts](https://pocketjs.dev/docs/platform-contracts/) and the
 [Native contract](https://pocketjs.dev/docs/native-contract/).
 
-## Shipped on the runtime
+## Applications
 
-| Project | What it carries |
+| Project | Scope |
 | --- | --- |
 | [**OpenStrike**](https://pocketjs.dev/blog/shipping-openstrike/) | A Counter-Strike-shaped shooter on 2004 hardware: BSP maps, bots, and a HUD written in Solid JSX, at 60 fps with 2.2 ms of JavaScript per frame |
 | [**Pocket Voxel**](https://pocketjs.dev/blog/pocket-voxel/) | A creature-RPG town rebuilt as a walking voxel diorama. Game state lives in the JS guest; logic runs at 60 Hz while presentation holds a locked 30 fps beat |
-| [**Pocket Figma**](https://pocketjs.dev/blog/pocket-figma/) | A real 14,430-node design file, cooked into streamed tile pyramids and panned with the analog nub at 60 fps on a handheld with 32 MB of RAM |
-| [**Pocket Character**](https://pocketjs.dev/blog/pocket-character/) | A rigged VRM companion in a transparent always-on-top window, rendering skinned 3D at 60 fps in one process and 118 MB, against 8 processes and 2184 MB for the Electron build of the same idea |
-| [**Pocket YouTube**](https://pocketjs.dev/blog/pocket-youtube/) | Search, thumbnails, playback and seeking on a console that predates streaming, where the network is a USB cable and a Mac companion does the fetching |
+| [**Pocket Figma**](https://pocketjs.dev/blog/pocket-figma/) | A 14,430-node design file, cooked into streamed tile pyramids and panned with the analog nub at 60 fps on a handheld with 32 MB of RAM |
+| [**Pocket Character**](https://pocketjs.dev/blog/pocket-character/) | A rigged VRM companion in a transparent always-on-top window, rendering skinned 3D at 60 fps in one process and 118 MB, against 8 processes and 2184 MB for an Electron build of the same idea |
+| [**Pocket YouTube**](https://pocketjs.dev/blog/pocket-youtube/) | Search, thumbnails, playback and seeking on a console that predates streaming, where the network is a USB cable and a Mac companion performs the fetching |
 | [**Pocket DevTools**](https://pocketjs.dev/blog/time-travel-devtools/) | Time-travel debugging over a USB cable at 2 bytes per frame. The inspector highlight is emitted by the core into the draw list, so it renders on the device, on every backend |
-| [**Pocket Launcher**](./docs/LAUNCHER.md) | Whole-app lifecycle, target admission, frozen shots, and guest switching on PSP and Vita |
+| [**Pocket Launcher**](./docs/LAUNCHER.md) | Whole-application lifecycle, target admission, frozen shots, and guest switching on PSP and Vita |
 | [**Pocket Pi**](https://github.com/pocket-stack/pocket-pi) | A coding agent running inside the QuickJS guest environment, with no Node underneath |
 
 <p align="center">
@@ -280,11 +305,11 @@ records what has been verified and how. See
 
 <p align="center"><em>Pocket Voxel, captured on a PSP-2000: the flat Game Boy world standing up as geometry. <a href="https://pocketjs.dev/blog/pocket-voxel/">The making-of story</a>.</em></p>
 
-## Try it
+## Getting started
 
-The fastest zero-install path is the online
-[Playground](https://pocketjs.dev/playground/). Local browser development needs
-[Bun](https://bun.sh/) and [Rust via rustup](https://rustup.rs/):
+The zero-install path is the online
+[Playground](https://pocketjs.dev/playground/). Local browser development
+requires [Bun](https://bun.sh/) and [Rust via rustup](https://rustup.rs/):
 
 ```sh
 git clone https://github.com/pocket-stack/pocketjs
@@ -305,18 +330,19 @@ pocket check --target psp --manifest apps/my-app/pocket.json
 pocket build --target psp --manifest apps/my-app/pocket.json -- --release
 ```
 
-Vita packaging additionally needs VitaSDK and the pinned Rust toolchain
+Vita packaging additionally requires VitaSDK and the pinned Rust toolchain
 documented in [`hosts/vita/README.md`](./hosts/vita/README.md). Guest builds can
 be packaged as inspectable, target-thinnable
-[`.pocket` files](./docs/PLATFORM.md) instead of ad hoc port directories.
+[`.pocket` files](./docs/PLATFORM.md) instead of per-port directories.
 
-## Machines without a JavaScript engine
+## Ahead-of-time compilation
 
-Where even QuickJS is too much, [Pocket Vapor](./vapor/README.md) compiles a
-strict Vue Vapor subset ahead of time into target-native C: `.gba`, `.gb`,
-`.nes`, ESP32 firmware, and Playdate `.pdx` artifacts, with no JS engine, GC, or
-allocator on the device. It is a separate compiler with its own target and board
-contracts, not a low-memory mode for arbitrary PocketJS apps.
+For machines that cannot host a JavaScript engine at all,
+[Pocket Vapor](./vapor/README.md) compiles a strict Vue Vapor subset ahead of
+time into target-native C: `.gba`, `.gb`, `.nes`, ESP32 firmware, and Playdate
+`.pdx` artifacts, with no JS engine, GC, or allocator on the device. It is a
+separate compiler with its own target and board contracts, not a low-memory mode
+for arbitrary PocketJS applications.
 
 ```sh
 bun run vapor:dev             # run the component against the real Vue oracle in a browser
@@ -327,7 +353,7 @@ bun vapor/compiler/cli.ts vapor/examples/todo/todo.tsx --target gb
 Compiler-derived demands are checked against a target or board profile before
 lowering; see [`vapor/DESIGN.md`](./vapor/DESIGN.md).
 
-## Repository map
+## Repository layout
 
 | Path | Responsibility |
 | --- | --- |
@@ -341,7 +367,9 @@ lowering; see [`vapor/DESIGN.md`](./vapor/DESIGN.md).
 | [`tests/`](./tests/) | Contract, compiler, simulation, emulator, package, and golden verification |
 | [`docs/`](./docs/) | Platform, runtime, determinism, DevTools, backend, and benchmark records |
 
-Common repository checks (emulator journeys require their external toolchains):
+## Building and testing
+
+Emulator journeys require their external toolchains:
 
 ```sh
 bun run test                  # contracts, compiler, packages, sims, and host suites
@@ -351,19 +379,31 @@ bun run e2e:vita              # Vita3K native-density journey
 bun run site:build            # docs, playground, Stage, and landing build
 ```
 
-## Who builds this
+## Documentation
+
+| Topic | Reference |
+| --- | --- |
+| First application | [Getting started](https://pocketjs.dev/docs/getting-started/) |
+| Frameworks, components, styling | [Frameworks](https://pocketjs.dev/docs/frameworks/) · [Components](https://pocketjs.dev/docs/components/) · [Styling](https://pocketjs.dev/docs/styling/) |
+| Runtime internals | [Architecture](https://pocketjs.dev/docs/architecture/) · [Core concepts](https://pocketjs.dev/docs/concepts/) · [Native contract](https://pocketjs.dev/docs/native-contract/) |
+| Targets and packaging | [Platform contracts](https://pocketjs.dev/docs/platform-contracts/) · [The `.pocket` platform](./docs/PLATFORM.md) |
+| Debugging and verification | [DevTools](./docs/DEVTOOLS.md) · [Determinism](./docs/DETERMINISM.md) |
+| Runtimes beyond 2D UI | [The runtime family](./docs/RUNTIMES.md) · [Pocket3D](./engine/pocket3d/README.md) |
+| Complete examples | [`apps/`](./apps/) · [Blog](https://pocketjs.dev/blog/) |
+
+## Project
 
 [Pocket Lab](https://pocketlab.build) is an independent, non-VC-backed
 organization built on this runtime, so that the joy of creating belongs to
 everyone. Development is funded by
 [sponsors](https://github.com/sponsors/doodlewind).
 
-## Motion Lab attribution
+## Attribution
 
 The original motion studies are by [yui540](https://yui540.com/). PocketJS
-accepts yui540's two stated conditions for continued use: Motion Lab carries
-the requested `(yui540)` on-screen credit, and any other yui540 animation
-requires separate permission before it is ported. The accepted scope and
+accepts yui540's two stated conditions for continued use: Motion Lab carries the
+requested `(yui540)` on-screen credit, and any other yui540 animation requires
+separate permission before it is ported. The accepted scope and
 capture-maintenance rules are recorded in
 [`apps/motions/ATTRIBUTION.md`](./apps/motions/ATTRIBUTION.md).
 
diff --git a/package.json b/package.json
index 4077a332..e10deee0 100644
--- a/package.json
+++ b/package.json
@@ -189,7 +189,7 @@
     "./octane/net": "./framework/src/net-api.ts",
     "./octane/renderer": "./framework/src/renderer-octane.ts"
   },
-  "description": "High-performance JSX UI outside the browser, with native rendering, standard Vue Vapor and Solid support, a Tailwind design system, and 60 FPS animation under an 8 MB memory budget.",
+  "description": "A portable application runtime that turns modern component code into native pixels across radically different hardware: Solid, Vue Vapor and Octane over a native Rust core, with build-time Tailwind styling and 60 FPS animation under an 8 MB memory budget.",
   "scripts": {
     "bootstrap": "bun tools/bootstrap.ts",
     "pocket": "bun tools/pocket.ts",
diff --git a/site/build.ts b/site/build.ts
index 1902f6d0..b91a97ac 100644
--- a/site/build.ts
+++ b/site/build.ts
@@ -668,7 +668,7 @@ async function main() {
 // styles. Display faces come from Google Fonts; the fallback stacks keep the
 // page readable when that request fails.
 const HOME_DESC =
-  "PocketJS is a UI runtime that keeps JSX, Tailwind and reactive state, then removes every layer below them: no DOM, no CSS engine, no WebView. A QuickJS guest on a Rust core that lays out and draws every pixel itself.";
+  "PocketJS is a portable application runtime that turns modern component code into native pixels across radically different hardware. JSX, Tailwind and reactive state stay; no DOM, no CSS engine, no WebView, just a QuickJS guest on a Rust core that lays out and draws every pixel itself.";
 const escapeHtml = (s: string) =>
   s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 
diff --git a/site/content/docs/architecture.md b/site/content/docs/architecture.md
index 51cddd1a..ef15b291 100644
--- a/site/content/docs/architecture.md
+++ b/site/content/docs/architecture.md
@@ -1,8 +1,9 @@
 # Architecture
 
-PocketJS is a JSX UI stack that runs apps on real Sony PSP and PS Vita hardware,
-in PPSSPP and Vita3K, in desktop/browser hosts, and under headless Bun. It gets
-there with one principle:
+PocketJS is a portable application runtime that turns modern component code
+into native pixels across radically different hardware: real Sony PSP and PS
+Vita units, PPSSPP and Vita3K, desktop and browser hosts, and headless Bun. It
+gets there with one principle:
 **one Rust core, framework-specific JS adapters, one layout engine everywhere.**
 
 The JavaScript side can be Solid, Vue Vapor, or Octane. Solid uses its
diff --git a/site/content/docs/getting-started.md b/site/content/docs/getting-started.md
index cba16fea..4445ae74 100644
--- a/site/content/docs/getting-started.md
+++ b/site/content/docs/getting-started.md
@@ -2,9 +2,10 @@
 
 This is the fastest path from an empty checkout to JSX running on screen. You'll
 write a component, mount it, build it, and see it in the browser dev host — the
-same source and `pocket.json` can also be compiled into target-specific PSP and
-PS Vita packages. The logical 480×272 UI stays portable while each target owns
-its native renderer, raster density, and HostOps ABI.
+same source and `pocket.json` can also be compiled into target-specific packages
+for PSP, PS Vita, and the other registered targets. The logical 480×272 UI stays
+portable while each target owns its native renderer, raster density, and HostOps
+ABI.
 
 If you only want to *try* PocketJS, skip the toolchain entirely and open the
 online [Playground](/playground/): it runs the Rust core as WebAssembly in your
diff --git a/site/content/docs/overview.md b/site/content/docs/overview.md
index 4914fe27..42cfdcfc 100644
--- a/site/content/docs/overview.md
+++ b/site/content/docs/overview.md
@@ -1,11 +1,12 @@
 # Overview
 
-PocketJS lets you build **Solid**, **Vue Vapor**, or **Octane** interfaces for
-Sony PSP and
-PS Vita hardware. It compiles class strings and font glyphs at build time, then
-renders real flexbox, sub-pixel text and native animation through a compact
-`no_std` Rust core. One application manifest resolves into target-specific PSP
-and Vita artifacts; browser, desktop, PPSSPP/Vita3K, and headless hosts exercise
+PocketJS is a portable application runtime that turns modern component code
+into native pixels across radically different hardware. You write **Solid**,
+**Vue Vapor**, or **Octane** components; the runtime compiles class strings and
+font glyphs at build time, then renders flexbox layout, sub-pixel text and
+native animation through a compact `no_std` Rust core. One application manifest
+resolves into target-specific artifacts, from Sony PSP and PS Vita packages to
+desktop and e-reader hosts; browser, PPSSPP/Vita3K, and headless hosts exercise
 the same logical UI and HostOps semantics.
 
 If you know Solid, Vue, or React, you already know most of PocketJS. The
diff --git a/site/home.html b/site/home.html
index 7c5aa83f..a93358f7 100644
--- a/site/home.html
+++ b/site/home.html
@@ -50,12 +50,13 @@
   <div class="wrap hero-in">
     <div class="col">
       <div class="plate">
-        <h1><span class="metal lit">A very ambitious<br>UI runtime.</span></h1>
+        <h1><span class="metal lit">UI runtime for<br>every kind of<br>computer</span></h1>
         <span class="rail"></span>
       </div>
-      <p class="sub">PocketJS is a UI runtime that keeps JSX, Tailwind and reactive state, then
-        <strong>removes every layer below them</strong>: no DOM, no CSS engine, no WebView. What is left is a
-        QuickJS guest on a Rust core that lays out and draws every pixel itself.</p>
+      <p class="sub">PocketJS is a portable application runtime that turns modern component code into
+        <strong>native pixels across radically different hardware</strong>. JSX, Tailwind and reactive state
+        stay; every layer below them is gone: no DOM, no CSS engine, no WebView, just a QuickJS guest on a Rust
+        core that lays out and draws every pixel itself.</p>
       <div class="ctas">
         <a class="btn btn--pri" href="#ecosystem">See use cases</a>
         <a class="btn btn--sec" href="https://github.com/pocket-stack/pocketjs">Star on GitHub</a>
diff --git a/site/templates.ts b/site/templates.ts
index 8a97d6df..38bef8c5 100644
--- a/site/templates.ts
+++ b/site/templates.ts
@@ -9,10 +9,10 @@ const X_URL = "https://x.com/pocket_js";
 export const SITE_URL = "https://pocketjs.dev";
 export const SITE_TITLE = "PocketJS · JavaScript UI runtime";
 export const SITE_DESC =
-  "A compact JavaScript runtime for building UI, games, 3D experiences and AI-native applications across radically different devices. A tiny JavaScript guest where it fits; the framework compiled away where it doesn't.";
+  "PocketJS is a portable application runtime that turns modern component code into native pixels across radically different hardware. Solid, Vue Vapor and Octane components compile to one native tree that a Rust core lays out and draws, with no DOM, CSS engine or WebView underneath.";
 // Shared by the standalone homepage and every page rendered through renderPage().
 export const SITE_FOOTER_DESC =
-  "A compact JavaScript runtime for UI, games, 3D and AI-native software, carried to radically different devices by a tiny native core.";
+  "A portable application runtime that turns modern component code into native pixels, carried to radically different hardware by a compact native core.";
 export const SITE_FOOTER_DESC_SLOT = "{{SITE_FOOTER_DESC}}";
 export const OG_IMAGE_URL = `${SITE_URL}/og-image.png`;
 
diff --git a/tests/site-stage.test.ts b/tests/site-stage.test.ts
index 5d43e2cb..f442810e 100644
--- a/tests/site-stage.test.ts
+++ b/tests/site-stage.test.ts
@@ -83,8 +83,10 @@ test("homepage ships the four-chapter landing", () => {
   expect(home).toContain('class="hero-bg"');
   expect(home).toContain("/assets/pocketjs-demo-wall.mp4");
   expect(home).toContain("/assets/pocketjs-demo-wall.jpg");
-  expect(home).toContain("A very ambitious");
-  expect(home).toContain("PocketJS is a UI runtime that keeps JSX, Tailwind and reactive state");
+  expect(home).toContain("UI runtime for<br>every kind of<br>computer");
+  expect(home).toContain(
+    "PocketJS is a portable application runtime that turns modern component code into",
+  );
   for (const file of ["site/home.html", "site/bake-demo-wall.ts", "site/content/blog/pocket-figma.md"]) {
     expect(readFileSync(ROOT + file, "utf8")).not.toContain("figma-psp-cover-zoom");
   }