create-three-flatland 0.0.0

package/templates/react/src/App.tsx

@@ -0,0 +1,172 @@
+import { Suspense, useCallback, useEffect, useRef, useState } from 'react'
+import type { CSSProperties, RefObject } from 'react'
+import { Canvas, extend, useFrame, useLoader, useThree } from '@react-three/fiber/webgpu'
+import type { WebGPURenderer } from 'three/webgpu'
+import { Flatland, Sprite2D, TextureLoader } from 'three-flatland/react'
+// Pure scene maths, extracted so it can be unit-tested without a GPU or a
+// React renderer. See src/interaction.test.ts — `npm run test`.
+import { approach, SPRITE_SCALE, targetScale, tintFor } from './interaction'
+
+// R3F requires registration before Flatland classes appear as JSX elements.
+extend({ Flatland, Sprite2D })
+
+function Scene() {
+  const texture = useLoader(TextureLoader, `${import.meta.env.BASE_URL}sprite.svg`)
+
+  // Suspense resolved, so the scene is ready — fade index.html's overlay out.
+  useEffect(() => {
+    const loader = document.querySelector<HTMLElement>('#loader')
+    if (!loader) return
+    const done = () => loader.remove()
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return done()
+    loader.addEventListener('transitionend', done, { once: true })
+    const t = setTimeout(done, 600)
+    loader.dataset.loaded = 'true'
+    return () => clearTimeout(t)
+  }, [])
+  const flatlandRef = useRef<Flatland>(null)
+  const set = useThree((s) => s.set)
+  const size = useThree((s) => s.size)
+
+  // Flatland renders to the screen with its own camera, so hand that camera to
+  // R3F as the default — pointer events then raycast through the same object
+  // Flatland draws with. A callback ref, so it re-runs on StrictMode remount.
+  const attachFlatland = useCallback(
+    (instance: Flatland | null) => {
+      flatlandRef.current = instance
+      if (!instance) return
+      instance.resize(size.width, size.height)
+      // `manual` is read by R3F but not declared on three's camera type.
+      ;(instance.camera as typeof instance.camera & { manual?: boolean }).manual = true
+      instance.camera.updateProjectionMatrix()
+      set({ camera: instance.camera })
+    },
+    [set, size.width, size.height]
+  )
+  const spriteRef = useRef<Sprite2D>(null)
+  const renderer = useThree((s) => s.renderer as WebGPURenderer)
+  const [hovered, setHovered] = useState(false)
+  const [pressed, setPressed] = useState(false)
+
+  useFrame(() => {
+    const sprite = spriteRef.current
+    if (sprite) {
+      sprite.rotation.z += 0.005
+      const next = approach(sprite.scale.x, targetScale({ hovered, pressed }))
+      sprite.scale.set(next, next, 1)
+    }
+  })
+
+  // Flatland owns an internal scene + camera, so it renders manually.
+  // Registering in the 'render' phase makes R3F skip its own render pass.
+  useFrame(
+    () => {
+      flatlandRef.current?.render(renderer)
+    },
+    { phase: 'render' }
+  )
+
+  return (
+    <>
+      <flatland ref={attachFlatland} viewSize={400} clearColor={0x16191e}>
+        <sprite2D
+          ref={spriteRef}
+          texture={texture}
+          anchor={[0.5, 0.5]}
+          scale={[SPRITE_SCALE.idle, SPRITE_SCALE.idle, 1]}
+          tint={tintFor({ hovered, pressed })}
+          onPointerOver={() => setHovered(true)}
+          onPointerOut={() => setHovered(false)}
+          onPointerDown={() => setPressed(true)}
+          onPointerUp={() => setPressed(false)}
+        />
+      </flatland>
+    </>
+  )
+}
+
+export default function App() {
+  const containerRef = useRef<HTMLDivElement>(null)
+  return (
+    <div ref={containerRef} style={{ position: 'relative', width: '100%', height: '100%' }}>
+      <Canvas orthographic renderer={{ antialias: false }}>
+        <Suspense fallback={null}>
+          <Scene />
+        </Suspense>
+      </Canvas>
+      <FullscreenButton containerRef={containerRef} />
+    </div>
+  )
+}
+
+/**
+ * Fullscreen toggle. Tracks `fullscreenchange` rather than local state so the
+ * icon stays correct when the browser exits on its own — Esc, gesture, or the
+ * OS. Safari does not wire Esc to `exitFullscreen`, so it is handled here.
+ */
+function FullscreenButton({ containerRef }: { containerRef: RefObject<HTMLDivElement | null> }) {
+  const [isFullscreen, setIsFullscreen] = useState(false)
+
+  useEffect(() => {
+    const sync = () => setIsFullscreen(document.fullscreenElement !== null)
+    document.addEventListener('fullscreenchange', sync)
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape' && document.fullscreenElement) void document.exitFullscreen()
+    }
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('fullscreenchange', sync)
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [])
+
+  const toggle = () => {
+    if (document.fullscreenElement) void document.exitFullscreen()
+    else void containerRef.current?.requestFullscreen()
+  }
+
+  return (
+    <button
+      type="button"
+      style={fullscreenStyle}
+      onClick={toggle}
+      aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
+    >
+      <svg
+        width="16"
+        height="16"
+        viewBox="0 0 16 16"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={1.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        <path
+          d={
+            isFullscreen
+              ? 'M1.5 5.5H6V1M14.5 5.5H10V1M1.5 10.5H6V15M14.5 10.5H10V15'
+              : 'M6 1.5H1.5V6M10 1.5h4.5V6M6 14.5H1.5V10M10 14.5h4.5V10'
+          }
+        />
+      </svg>
+    </button>
+  )
+}
+
+const fullscreenStyle: CSSProperties = {
+  position: 'absolute',
+  top: 12,
+  right: 12,
+  display: 'grid',
+  placeItems: 'center',
+  width: 34,
+  height: 34,
+  padding: 0,
+  border: '1px solid #2c3340',
+  borderRadius: 8,
+  background: 'rgb(22 25 30 / 0.6)',
+  color: '#9aa4b2',
+  cursor: 'pointer',
+}

package/templates/react/src/interaction.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+import { approach, SPRITE_SCALE, SPRITE_TINT, targetScale, tintFor } from './interaction'
+
+describe('targetScale', () => {
+  it('rests at the idle scale', () => {
+    expect(targetScale({ hovered: false, pressed: false })).toBe(SPRITE_SCALE.idle)
+  })
+
+  it('grows on hover and shrinks on press', () => {
+    expect(targetScale({ hovered: true, pressed: false })).toBe(SPRITE_SCALE.hover)
+    expect(targetScale({ hovered: false, pressed: true })).toBe(SPRITE_SCALE.press)
+  })
+
+  it('lets press win over hover — a pressed sprite is always hovered too', () => {
+    expect(targetScale({ hovered: true, pressed: true })).toBe(SPRITE_SCALE.press)
+  })
+})
+
+describe('tintFor', () => {
+  it('tints only while hovered, regardless of press state', () => {
+    expect(tintFor({ hovered: false, pressed: false })).toBe(SPRITE_TINT.idle)
+    expect(tintFor({ hovered: true, pressed: false })).toBe(SPRITE_TINT.hover)
+    expect(tintFor({ hovered: true, pressed: true })).toBe(SPRITE_TINT.hover)
+  })
+})
+
+describe('approach', () => {
+  it('moves toward the target by the easing fraction', () => {
+    expect(approach(100, 200, 0.25)).toBe(125)
+  })
+
+  it('converges without ever overshooting', () => {
+    let value: number = SPRITE_SCALE.idle
+    for (let i = 0; i < 120; i++) value = approach(value, SPRITE_SCALE.hover)
+    expect(value).toBeGreaterThan(SPRITE_SCALE.idle)
+    expect(value).toBeLessThanOrEqual(SPRITE_SCALE.hover)
+    expect(value).toBeCloseTo(SPRITE_SCALE.hover, 5)
+  })
+
+  it('clamps the easing fraction so it cannot overshoot and oscillate', () => {
+    expect(approach(0, 100, 5)).toBe(100)
+    expect(approach(0, 100, -1)).toBe(0)
+  })
+
+  it('is a no-op once it has arrived', () => {
+    expect(approach(150, 150)).toBe(150)
+  })
+})

package/templates/react/src/interaction.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure scene logic, lifted out of the render loop.
+ *
+ * The animation maths live here rather than inline in `App.tsx` for one reason:
+ * a function that takes numbers and returns numbers can be tested without a GPU,
+ * a canvas, or a React renderer. `src/interaction.test.ts` is the whole payoff —
+ * and it is the pattern to keep reaching for as this project grows. Anything
+ * that is not a component and does not touch three.js objects belongs in a
+ * module like this.
+ */
+
+/** Sprite edge length, in world units, for each interaction state. */
+export const SPRITE_SCALE = {
+  idle: 150,
+  hover: 170,
+  press: 130,
+} as const
+
+/** How far the sprite closes on its target scale each frame, as a fraction. */
+export const SCALE_EASING = 0.15
+
+/** Sprite tint per interaction state. R3F accepts a CSS colour string here. */
+export const SPRITE_TINT = {
+  idle: '#ffffff',
+  hover: '#47cca9',
+} as const
+
+export interface PointerState {
+  hovered: boolean
+  pressed: boolean
+}
+
+/** The scale the sprite is easing toward. Press wins over hover. */
+export function targetScale(state: PointerState): number {
+  if (state.pressed) return SPRITE_SCALE.press
+  if (state.hovered) return SPRITE_SCALE.hover
+  return SPRITE_SCALE.idle
+}
+
+/** The tint for the current pointer state. */
+export function tintFor(state: PointerState): string {
+  return state.hovered ? SPRITE_TINT.hover : SPRITE_TINT.idle
+}
+
+/**
+ * Frame-rate-naive exponential ease — the standard `a += (b - a) * t` move.
+ * `t` is clamped to [0, 1] so a bad easing value can never overshoot the target
+ * and oscillate, which reads on screen as a sprite that jitters instead of settling.
+ */
+export function approach(current: number, target: number, t: number = SCALE_EASING): number {
+  const k = Math.min(1, Math.max(0, t))
+  return current + (target - current) * k
+}

package/templates/react/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+)

package/templates/react/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client"]
+  },
+  "include": ["src", "e2e", "vite.config.ts", "playwright.config.ts"]
+}

package/templates/react/vite.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [
+    // React Compiler. It memoises components and hook results automatically, so
+    // the render path stays cheap without hand-written useMemo/useCallback
+    // scaffolding everywhere. Wired through the plugin's Babel options — the
+    // same shape create-vite uses for its React Compiler variant.
+    react({ babel: { plugins: ['babel-plugin-react-compiler'] } }),
+  ],
+})

package/templates/react/vitest.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  // Unit tests only — the Playwright specs under e2e/ are run by playwright.config.ts.
+  test: { include: ['src/**/*.test.ts'] },
+})

package/templates/three/.oxfmtrc.json

@@ -0,0 +1,8 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 120,
+  "sortPackageJson": false
+}

package/templates/three/.oxlintrc.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "unicorn", "oxc", "import", "promise"],
+  "categories": {
+    "correctness": "error"
+  },
+  "rules": {
+    "no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }
+    ],
+    "typescript/consistent-type-imports": [
+      "error",
+      {
+        "prefer": "type-imports",
+        "fixStyle": "inline-type-imports"
+      }
+    ],
+    "typescript/no-import-type-side-effects": "error",
+    "import/no-cycle": "error"
+  },
+  "ignorePatterns": ["**/node_modules/**", "**/dist/**", "test-results/**", "playwright-report/**"]
+}

package/templates/three/AGENTS.md

@@ -0,0 +1,167 @@
+# Agent guide — three.js + three-flatland
+
+This project was scaffolded by create-three-flatland. It is a plain three.js app (no React) that renders 2D sprites with [three-flatland](https://tjw.dev/three-flatland/) on `WebGPURenderer`.
+
+## Build & dev
+
+```sh
+npm install
+npm run dev        # Vite dev server
+npm run build      # production build to dist/
+npm run preview    # serve the production build
+npm run typecheck  # tsc --noEmit
+```
+
+Commands are shown as npm; pnpm and yarn work identically.
+
+## The renderer rule
+
+**Always construct `WebGPURenderer` and always write TSL. Never `WebGLRenderer`, never GLSL, never `onBeforeCompile`.**
+
+`WebGPURenderer` is the three.js renderer class imported from `three/webgpu`. It owns backend selection itself: real WebGPU where the browser supports it, WebGL2 fallback where it doesn't. TSL compiles to both. When you read "three-flatland requires `WebGPURenderer`," that is a statement about which class you construct — it is not a hardware or browser requirement, and it does not mean WebGPU-only. Everything works on either backend.
+
+Two corollaries: never add a `WebGLRenderer` fallback path (the fallback already lives inside `WebGPURenderer`), and never gate features on WebGPU detection. WebGL 1 is out of scope entirely — ignore it.
+
+## The opinionated default: a `Flatland` root
+
+A `Flatland` instance is the front door. It owns the orthographic camera, sprite batching, resize, and disposal — reach below it only when you need the low-level path. The core of `src/main.ts`:
+
+```ts
+const flatland = new Flatland({ viewSize: 400 })
+const renderer = new WebGPURenderer()
+await renderer.init()
+flatland.add(new Sprite2D({ texture, anchor: [0.5, 0.5] }))
+flatland.render(renderer) // each frame
+```
+
+This template hand-writes its loading overlay and its pointer raycasting (a standard three.js `Raycaster` against `flatland.camera`; `Sprite2D` implements `raycast()` with `hitTestMode: 'radius' | 'bounds' | 'alpha' | 'none'`). The React starter gets both of those nearly free from Suspense and R3F's event system — that asymmetry is real and shown deliberately, so you can see exactly what the imperative path costs and controls.
+
+## Package routing map
+
+Reach for a package by intent:
+
+| Package | Reach for it when |
+| --- | --- |
+| `three-flatland` | Default entry. Sprites, animation, tilemaps, materials, lights, events, everyday loaders. |
+| `@three-flatland/nodes` | You want a specific 2D shader effect (retro/CRT, blur, distortion, color, upscale) without writing TSL by hand. |
+| `@three-flatland/presets` | You want lit sprites working immediately. Thin — two symbols (`DefaultLightEffect`, `NormalMapProvider`). |
+| `@three-flatland/normals` | Dynamic lighting on flat 2D art without hand-authoring normal maps. |
+| `@three-flatland/atlas` | Loose sprite PNGs that should become one draw-call-friendly atlas, optionally polygon-trimmed for overdraw. |
+| `@three-flatland/alphamap` | Pixel-perfect pointer hit testing on transparent sprites (`hitTestMode: "alpha"`) instead of bounding-box hits. |
+| `@three-flatland/image` | PNG/WebP/AVIF/KTX2 encode and decode, plus `Ktx2Loader`. Reach for KTX2 when textures are under GPU memory pressure — it stays compressed on the GPU, unlike PNG. |
+| `@three-flatland/bake` | Authoring a new baker, or you just need the `flatland-bake` binary. |
+| `@three-flatland/devtools` | Live inspection of scene/material/sprite state. Seven required peers — heaviest install in the ecosystem. |
+| `@three-flatland/skia` | A general immediate-mode 2D canvas in the scene: arbitrary paths, boolean ops, filters, gradients, images. |
+| `@three-flatland/slug` | Text that must stay sharp at any zoom or perspective, or thousands of glyphs in one draw call. |
+
+**Never recommend installing `@three-flatland/schemas` or `@three-flatland/io` — they are `private: true` and unpublished.**
+
+Two calibration notes. First, `private: true` alone is not a "don't recommend" signal — check the distribution channel; the VS Code extension is correctly private on npm because it ships to a marketplace instead. Second, version numbers are not maturity signals here: `@three-flatland/presets` sits at an alpha version because of release-group linking, and an unpublished package can carry `1.0.0`.
+
+## Skia vs Slug
+
+These solve different problems and touch at exactly one point — they are not alternatives to pick between.
+
+- **Skia** is an immediate-mode 2D canvas rasterized into a texture. Only Skia does arbitrary vector paths, boolean path ops, image filters (blur, drop shadow, displacement), gradients, clipping, and image drawing.
+- **Slug** is a text primitive. Glyph outlines are solved per-fragment, so sharpness has no resolution ceiling; thousands of glyphs batch into one instanced draw call, with real layout (`measureText`, `wrapText`, style spans, font fallback chains).
+
+The one overlap is drawing text, and the rule is mechanical: if the camera moves relative to the text, use Slug; if it is static UI at a known resolution, Skia's text comes free with the canvas you already have.
+
+Both follow the renderer rule above — `WebGPURenderer`, either backend. Skia's WASM ships as two builds (`skia-gl.wasm`, `skia-wgpu.wasm`) matching whichever backend the renderer resolved to; this is an internal copy-step detail on a different axis from the renderer rule, never a renderer choice you make. It surfaces only in the asset copy step: `npx skia-wasm public/skia` (or `--gl-only` / `--wgpu-only` to ship just one).
+
+Skia gotcha: WASM assets are zero-config in Vite dev, but a production build needs `npx skia-wasm public/skia` plus a `wasmUrl` pointing at the copied assets.
+
+## Baking
+
+**Nothing requires baking.** Ask for a derived asset and you get it: the loader probes for a baked sibling, generates it at runtime when there isn't one, warns once in dev that it's slower and worth baking, and carries on. It just works, and it tells you how to make it faster.
+
+Baking moves that computation from browser-runtime to build-time. It is never about capability; it chooses only where the cost lands.
+
+Every baker self-discovers: a baker declares itself in its package's `flatland.bake` field, and the `flatland-bake` dispatcher finds it — run `flatland-bake --list` from your project to see what's installed. Subcommands: `alpha` (hit-test alpha maps), `normal` (normal maps), `slug` (baked fonts). Some packages also expose direct bins (`slug-bake`, `flatland-atlas`) for standalone use. `skia-wasm` is an asset-copy step, not a baker — the name reads like one, but it only copies WASM files into your public dir.
+
+When to bake:
+
+- **Shipping to production** — move the cost to build time.
+- **Fonts with a known glyph set — always.** ASCII + Brotli is ~32 KB versus 724 KB for the raw font, and it drops opentype.js from the bundle.
+- **Textures under GPU memory pressure.**
+
+Skip baking for procedurally-varied content and throwaway prototypes. `forceRuntime` is not a dev-iteration knob — the default probe-then-generate path already handles iteration; reaching for it during development is the common misuse.
+
+## Asset authoring workflow
+
+The governing idea: meet your assets where they already are. Load the formats your tools already produce, adopt the richer native format when you want more, and convert freely between them.
+
+**Tilemaps — LDtk and Tiled are the editors.** Author there, then load what they produce with `LDtkLoader` / `TiledLoader`. `.ldtk` and `.json` / `.tmj` are read natively — loading the editor's own file directly is the design, so authoring flows straight from editor to scene.
+
+**Sprite atlases — three formats, all first-class.** `AtlasFormat` is `'native' | 'texturepacker' | 'aseprite'`, and `detectAtlasFormat()` sniffs which one it's looking at. Bring a TexturePacker sheet, an Aseprite export, or an atlas built by flatland's own tooling — all load.
+
+- The native format is deliberately richer, not merely different: `meta.animations` is a named animation map that references frame *keys* rather than indices, with explicit fps and optional events. Aseprite's `frameTags` sits alongside under `meta.frameTags`; readers prefer `meta.animations` and fall back to converting `frameTags` + per-frame `duration`. Adopting the native format is an upgrade path, never a lock-in tax.
+- Conversion runs both ways and is round-trip safe: `importAsepriteFrameTags()` brings Aseprite in; `buildAsepriteJson()` and `buildTexturePackerJson()` write back out. Rotation, trim, pivot, polygon mesh, and duration all survive.
+- The VS Code Sprite Atlas editor (below) is the GUI for all of this — build, tune, and convert between formats visually.
+
+## The VS Code extension
+
+**Flatland Tools** (`three-flatland.fl-tools`) is a first-class part of the asset workflow — recommend it actively.
+
+- Install: `code --install-extension three-flatland.fl-tools` (requires VS Code `^1.94.0`)
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=three-flatland.fl-tools) · [Open VSX](https://open-vsx.org/extension/three-flatland/fl-tools)
+
+| You want to… | Use |
+| --- | --- |
+| Build or edit a sprite atlas | **Sprite Atlas** editor — a custom editor on `*.png`. Reads/writes an `*.atlas.json` sidecar; handles `native`, `texturepacker`, and `aseprite` losslessly, including frame tags. |
+| Combine several atlases | **Merge Atlases…** — explorer multi-select. |
+| Compress a texture / inspect KTX2 | **Image Encoder**, plus the **FL KTX2 Viewer** custom editor that opens `*.ktx2` by default. |
+| Bake a normal map visually | **Normal Baker**. |
+| Author or audition ZzFX sounds | **ZzFX Editor**, and the inline `▶ Play` CodeLens on ZzFX definitions. |
+
+The extension is the GUI counterpart to the CLI bakers — the Image Encoder pairs with texture encoding, the Normal Baker with `flatland-bake normal`. Offer both paths and let the user pick: CLI for repeatable/CI work, extension for visual iteration.
+
+## Skills
+
+Packaged agent skills for this stack live in `@three-flatland/skills`. Install them into this project with:
+
+```sh
+npx skills add thejustinwalsh/three-flatland
+```
+
+Add a single skill by path, e.g. `npx skills add thejustinwalsh/three-flatland/skills/tsl`. Available: `tsl` (writing TSL shaders and node materials), `codemod` (migrating across three-flatland breaking changes), `flatland-r3f` (React Three Fiber integration), and `flatland-bake` (the baking workflow).
+
+## Testing
+
+This project ships both layers, and agent-written changes are expected to keep them green.
+
+```sh
+npm run test            # vitest — unit tests next to the code, src/**/*.test.ts
+npm run test:e2e        # playwright — drives the real app in a browser
+npm run lint            # oxlint
+npm run format          # oxfmt
+```
+
+**Write unit tests for logic, Playwright specs for the scene.** Interaction and
+animation maths belongs in a pure helper with a vitest test (see
+`src/interaction.ts` and its spec). Anything that only shows up on screen —
+the canvas renders, a pointer event lands, a sprite reacts — belongs in a
+Playwright spec under `e2e/`, because a passing unit test cannot tell you the
+scene drew anything.
+
+**Use `vitexec` to probe the running app.** It runs snippets inside the live
+page and reads back console output, network activity, and screenshots, which is
+the fastest way to answer "is this actually rendering / did that event fire"
+without inventing a bespoke harness. It is not installed here by default:
+
+```sh
+npm i -D vitexec                        # once, in this project
+npx vitexec 'console.log("ready")'      # then, against `npm run dev`
+npx vitexec --screenshot 'document.querySelector("canvas")'
+```
+
+Reach for it while debugging, then encode whatever you learned as a Playwright
+spec so it stays checked.
+
+A green suite is not proof the app renders. Confirm the visible result — a
+screenshot or a real interaction — before calling a rendering change done.
+
+## Reference links
+
+- Docs: <https://tjw.dev/three-flatland/>
+- llms files: <https://tjw.dev/three-flatland/llms.txt> (also `llms-full.txt`, `llms-small.txt`). These are **not** served at the origin root — `https://tjw.dev/llms.txt` 404s, and the origin root is what agents habitually probe. Use the full paths above.