create-three-flatland 0.0.0

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

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+import { approach, SPRITE_SCALE, targetScale, toPointerNdc } 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('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)
+  })
+})
+
+describe('toPointerNdc', () => {
+  const rect = { left: 0, top: 0, width: 800, height: 600 }
+
+  it('maps the centre to the origin', () => {
+    expect(toPointerNdc(400, 300, rect)).toEqual({ x: 0, y: 0 })
+  })
+
+  it('flips the Y axis — client Y grows down, NDC Y grows up', () => {
+    expect(toPointerNdc(0, 0, rect)).toEqual({ x: -1, y: 1 })
+    expect(toPointerNdc(800, 600, rect)).toEqual({ x: 1, y: -1 })
+  })
+
+  it('accounts for a canvas that is not at the page origin', () => {
+    expect(toPointerNdc(140, 90, { left: 40, top: 40, width: 200, height: 100 })).toEqual({ x: 0, y: 0 })
+  })
+
+  it('returns the origin instead of NaN for a zero-size rect', () => {
+    // A canvas queried before layout reports 0×0. Dividing by that would hand
+    // the raycaster NaN, which silently disables every hit test.
+    const ndc = toPointerNdc(10, 10, { left: 0, top: 0, width: 0, height: 0 })
+    expect(Number.isNaN(ndc.x)).toBe(false)
+    expect(Number.isNaN(ndc.y)).toBe(false)
+    expect(ndc).toEqual({ x: 0, y: 0 })
+  })
+})

package/templates/three/src/interaction.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure scene logic, lifted out of the render loop.
+ *
+ * The animation and pointer maths live here rather than inline in `main.ts` for
+ * one reason: a function that takes numbers and returns numbers can be tested
+ * without a GPU, a canvas, or a browser. `src/interaction.test.ts` is the whole
+ * payoff — and it is the pattern to keep reaching for as this project grows.
+ * Anything that 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
+
+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
+}
+
+/**
+ * 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
+}
+
+/** The subset of DOMRect this module needs — so tests don't have to build one. */
+export interface ViewportRect {
+  left: number
+  top: number
+  width: number
+  height: number
+}
+
+/**
+ * Client (CSS pixel) coordinates → normalized device coordinates for `Raycaster`.
+ *
+ * Two things are easy to get wrong here. The Y axis flips: NDC is +1 at the TOP
+ * of the viewport while client Y grows downward. And a canvas queried before
+ * layout reports a zero-size rect, which would divide by zero and hand the
+ * raycaster NaN — silently killing every hit test rather than failing loudly.
+ */
+export function toPointerNdc(clientX: number, clientY: number, rect: ViewportRect): { x: number; y: number } {
+  if (rect.width === 0 || rect.height === 0) return { x: 0, y: 0 }
+  return {
+    x: ((clientX - rect.left) / rect.width) * 2 - 1,
+    y: -((clientY - rect.top) / rect.height) * 2 + 1,
+  }
+}

package/templates/three/src/main.ts

@@ -0,0 +1,138 @@
+import { WebGPURenderer } from 'three/webgpu'
+import { Color, Raycaster, Vector2 } from 'three'
+import { Flatland, Sprite2D, TextureLoader } from 'three-flatland'
+// Pure scene maths, extracted so it can be unit-tested without a GPU.
+// See src/interaction.test.ts — `npm run test`.
+import { approach, SPRITE_SCALE, targetScale, toPointerNdc } from './interaction'
+
+/* HMR teardown state — without this, every dev save stacks another
+ * renderer + animation loop. Dev-only: `import.meta.hot` is undefined in prod. */
+let rafId = 0
+let activeRenderer: WebGPURenderer | null = null
+let activeFlatland: Flatland | null = null
+/* Every listener registered this run, so HMR can remove them all. Anonymous
+ * callbacks can't be removed, so each dev save would otherwise stack another
+ * closure over an already-disposed renderer and call setSize on it. */
+const listeners: Array<() => void> = []
+
+function on<T extends EventTarget>(target: T, type: string, handler: EventListener): void {
+  target.addEventListener(type, handler)
+  listeners.push(() => target.removeEventListener(type, handler))
+}
+
+/** Fade the loading overlay out, then remove it. Instant under reduced motion. */
+function dismissLoader(): void {
+  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 })
+  // Fallback: if the transition never fires (tab hidden, reduced-motion race).
+  setTimeout(done, 600)
+  loader.dataset.loaded = 'true'
+}
+
+async function main() {
+  const container = document.querySelector<HTMLDivElement>('#app')!
+
+  // Flatland is the front door: it owns the orthographic camera,
+  // sprite batching, resize, and disposal.
+  const flatland = new Flatland({ viewSize: 400, clearColor: 0x16191e })
+
+  // Always WebGPURenderer — it selects the backend itself (WebGPU where
+  // supported, WebGL2 fallback where not). Never construct WebGLRenderer.
+  const renderer = new WebGPURenderer({ antialias: false })
+  activeRenderer = renderer
+  activeFlatland = flatland
+  container.appendChild(renderer.domElement)
+
+  await renderer.init()
+  const texture = await TextureLoader.load(`${import.meta.env.BASE_URL}sprite.svg`)
+
+  // Renderer + texture ready — fade the loading overlay out, then drop it.
+  dismissLoader()
+
+  const sprite = new Sprite2D({ texture, anchor: [0.5, 0.5] })
+  sprite.scale.set(SPRITE_SCALE.idle, SPRITE_SCALE.idle, 1)
+  flatland.add(sprite)
+
+  // Pointer interactivity — a standard three.js Raycaster. Sprite2D
+  // implements raycast() (see hitTestMode for radius/bounds/alpha/none).
+  const raycaster = new Raycaster()
+  const pointer = new Vector2()
+  let hovered = false
+  let pressed = false
+
+  on(renderer.domElement, 'pointermove', ((event: PointerEvent) => {
+    const ndc = toPointerNdc(event.clientX, event.clientY, renderer.domElement.getBoundingClientRect())
+    pointer.set(ndc.x, ndc.y)
+    raycaster.setFromCamera(pointer, flatland.camera)
+    hovered = raycaster.intersectObject(sprite).length > 0
+  }) as EventListener)
+  on(renderer.domElement, 'pointerdown', () => {
+    pressed = hovered
+  })
+  on(window, 'pointerup', () => {
+    pressed = false
+  })
+
+  // Fullscreen. `data-fullscreen` drives the icon swap from CSS, and it is set
+  // from `fullscreenchange` rather than on click so it stays correct when the
+  // browser exits on its own. Safari does not wire Esc to exitFullscreen.
+  const fullscreenBtn = document.querySelector('#fullscreen')
+  if (fullscreenBtn) {
+    const syncFullscreen = () => {
+      const active = document.fullscreenElement !== null
+      fullscreenBtn.setAttribute('data-fullscreen', String(active))
+      fullscreenBtn.setAttribute('aria-label', active ? 'Exit fullscreen' : 'Enter fullscreen')
+    }
+    on(fullscreenBtn, 'click', () => {
+      if (document.fullscreenElement) void document.exitFullscreen()
+      else void container.requestFullscreen()
+    })
+    on(document, 'fullscreenchange', syncFullscreen)
+    on(document, 'keydown', ((event: KeyboardEvent) => {
+      if (event.key === 'Escape' && document.fullscreenElement) void document.exitFullscreen()
+    }) as EventListener)
+    syncFullscreen()
+  }
+
+  const resize = () => {
+    flatland.resize(container.clientWidth, container.clientHeight)
+    renderer.setSize(container.clientWidth, container.clientHeight)
+  }
+  on(window, 'resize', resize)
+  resize()
+
+  const idleTint = new Color(0xffffff)
+  const hoverTint = new Color(0x47cca9)
+
+  function animate() {
+    rafId = requestAnimationFrame(animate)
+    sprite.rotation.z += 0.005
+    const next = approach(sprite.scale.x, targetScale({ hovered, pressed }))
+    sprite.scale.set(next, next, 1)
+    sprite.tint.lerp(hovered ? hoverTint : idleTint, 0.15)
+    flatland.render(renderer)
+  }
+  animate()
+}
+
+void main()
+
+if (import.meta.hot) {
+  import.meta.hot.dispose(() => {
+    if (rafId) {
+      cancelAnimationFrame(rafId)
+      rafId = 0
+    }
+    for (const off of listeners.splice(0)) off()
+    activeFlatland?.dispose()
+    activeFlatland = null
+    if (activeRenderer) {
+      activeRenderer.dispose?.()
+      activeRenderer.domElement.remove()
+      activeRenderer = null
+    }
+  })
+}

package/templates/three/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "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,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "e2e", "vite.config.ts", "playwright.config.ts"]
+}

package/templates/three/vite.config.ts

@@ -0,0 +1,4 @@
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+})

package/templates/three/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'] },
+})