Skip to content

docs: restate PocketJS as a portable application runtime - #328

Merged
doodlewind merged 1 commit into
mainfrom
docs/portable-application-runtime
Aug 23, 2026
Merged

docs: restate PocketJS as a portable application runtime#328
doodlewind merged 1 commit into
mainfrom
docs/portable-application-runtime

Conversation

@doodlewind

Copy link
Copy Markdown
Collaborator

Positioning

One sentence now defines the project everywhere it is stated:

PocketJS is a portable application runtime that turns modern component code into native pixels across radically different hardware.

Surface Before After
Landing headline (site/home.html) "A very ambitious UI runtime." "UI runtime for every kind of computer"
Landing hero paragraph "a UI runtime that keeps JSX, Tailwind and reactive state, then removes every layer below them…" the positioning sentence, then the same removal + QuickJS-on-Rust mechanism
Homepage meta description (site/build.ts) same UI-runtime framing positioning sentence + mechanism
Site-wide meta + JSON-LD (SITE_DESC) "A compact JavaScript runtime for building UI, games, 3D experiences and AI-native applications…" positioning sentence + one native tree, no DOM/CSS engine/WebView
Site footer blurb (SITE_FOOTER_DESC) "compact JavaScript runtime for UI, games, 3D and AI-native software" portable application runtime, native pixels, compact native core
docs/overview intro "lets you build … interfaces for Sony PSP and PS Vita hardware" positioning sentence, then the same compile/render mechanism, targets given as examples
docs/architecture intro "a JSX UI stack that runs apps on real Sony PSP and PS Vita hardware" positioning sentence, same one-principle line kept
docs/getting-started scope line "PSP and PS Vita packages" "PSP, PS Vita, and the other registered targets"
npm description "High-performance JSX UI outside the browser…" positioning sentence + Rust core, build-time Tailwind, 8 MB budget

tests/site-stage.test.ts pins the hero copy, so both assertions were updated with it.

README register

Same chapter order as #325, without the landing voice:

  • 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.
  • Subsections carry the detail (### Frameworks, ### Styling, ### Animation, ### Target admission, ### From component to pixel, ### The frame contract, ### On a Sony PSP, ### On a desktop).
  • Third-person prose: "Write components as you already do" → "Three frameworks compile to the same native tree"; "What it asks of the machine" → "Performance"; "Not a roadmap" → "Every entry below has booted the runtime on the real machine".
  • Adds a Contents list and a Documentation index table; every measurement, receipt link, image and the yui540 attribution are unchanged.

Verification

  • bun run test — 11/11 stages green, 443 tests. (One earlier run had a single non-reproducing unit-stage failure, the known flake on this machine; the clean run is the one reported.)
  • bun run site:build — homepage, 18 docs pages, 19 blog posts; built output carries the new descriptions.
  • Headless Chrome measurement of the new three-line headline (VT323 loaded, not the fallback): widest line 445 px against 651 px of plate interior at 1600w, fits: true and zero horizontal overflow at 1600 / 1280 / 820 / 390 px. A two-line break would have been 636 px against 651 px, so the three-line break is deliberate.
  • README relative paths (28) and every pocketjs.dev docs/blog slug re-checked; TOC anchors match the headings.

Docs and site copy only; no runtime code paths touched.

🤖 Generated with Claude Code

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>
@doodlewind
doodlewind marked this pull request as ready for review August 23, 2026 00:45
@doodlewind
doodlewind merged commit 4771071 into main Aug 23, 2026
1 check passed
@doodlewind
doodlewind deleted the docs/portable-application-runtime branch August 23, 2026 00:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant