meshpad 0.0.0 → 0.1.0

package/README.md

@@ -1,7 +1,222 @@
-# meshpad
+# Meshpad
 
-Upcoming project. This initial package does not provide functionality yet.
+Build mobile-first 3D game prototypes in one TypeScript file. Meshpad includes TypeScript, Three.js, Vite, a portrait game shell, a HUD, level navigation, win/fail screens, and headless PNG rendering.
+
+Requires Node.js 22.12 or newer and a WebGL 2 browser.
+
+```sh
+npx meshpad init my-game
+cd my-game
+npm install
+npm run dev
+```
+
+The HUD keeps a dropdown-style level chooser on the left, an optional hearts/time/moves counter at the true center, and restart on the right in one row. Rounded buttons, simple SVG icons, Baloo 2, and a purple/cream/yellow palette give it a casual game feel. Win popups offer next level or replay. Fail popups offer retry, plus play on for hearts, time, and moves modes. Baloo 2 loads from Google Fonts, with rounded system fonts as a fallback.
+
+The generated project has one dependency, `meshpad`, and one implementation file, `game.ts`. No HTML, CSS, Vite config, or separate TypeScript or Three.js install is required. `package.json`, `tsconfig.json`, `.gitignore`, and `vercel.json` are provided. The starter is a three-level tap-the-cube game with a countdown.
+
+For an empty directory:
+
+```sh
+npx meshpad init
+npm install
+```
+
+If a `package.json` already exists, install `meshpad`, add `game.ts`, and run `npx meshpad dev`. Initialization refuses to overwrite existing files.
+
+```ts
+import { createGame, THREE } from 'meshpad';
+
+createGame({
+  title: 'My game',
+  levels: [{
+    name: 'Hello, world',
+    setup({ scene, win, fail }) {
+      const cube = new THREE.Mesh(
+        new THREE.BoxGeometry(),
+        new THREE.MeshStandardMaterial({ color: '#f9c203' }),
+      );
+      scene.add(cube);
+      return {
+        update(dt, elapsed) {
+          cube.rotation.y += dt;
+          if (elapsed >= 10) fail();
+        },
+        pointer({ type, hits }) {
+          if (type === 'pointerdown' && hits([cube]).length) win();
+        },
+      };
+    },
+  }],
+});
+```
+
+`THREE` is the included Three.js namespace. Named imports are also available from `meshpad/three`. Three.js's add-on barrel is available through `meshpad/addons`, with the same exports and no extra dependency:
+
+```ts
+import { BufferGeometryUtils, OrbitControls, GLTFLoader } from 'meshpad/addons';
+const geometry = BufferGeometryUtils.mergeVertices(new THREE.BoxGeometry());
+```
+
+### TypeScript projects
+
+Game entries must be `.ts` files; JavaScript and declaration-only entries are rejected. `game.ts` is the default for dev, build, rendering, and type checking. Custom entries such as `src/main.ts` also work. Builds and renders check types before starting, and development checks types at startup and after edits, displaying errors in the terminal and browser.
+
+```sh
+npx meshpad typecheck
+# or in generated projects:
+npm run typecheck
+```
+
+The generated `tsconfig.json` extends `meshpad/tsconfig`, which provides strict checking, DOM types, bundler module resolution, and no JavaScript emission. Editors use the same preset. With no project config, the CLI uses these defaults. Checks cover the project's TypeScript files and the entry's imports; type errors stop production builds. Meshpad bundles the compiler, so projects keep a single dependency. For separate setup helpers, import `type LevelContext` and `type LevelHooks` from `meshpad`.
+
+### Game API
+
+`createGame({ levels, title?, root?, initialLevel?, failure?, background?, maxPixelRatio?, maxWidth?, renderer?, onError? })` returns a game. Level indexes in JavaScript start at **0**. The CLI's `--level` starts at **1**.
+
+Each level is `{ name?, difficulty?, failure?, setup(context) }`. `difficulty` accepts `normal` (the default), `hard`, `very-hard`, or `ultra-hard`. The full-screen, scrollable level chooser shows each level’s number, optional name, and difficulty badge, with an X button to close it. Initial setup starts in a microtask, after the entry module's synchronous code has run, so it can use classes and constants declared below `createGame()`. Setup may be asynchronous. Context provides:
+
+| Value | Purpose |
+| --- | --- |
+| `scene`, `camera`, `renderer` | Fresh scene, perspective camera, and shared renderer. Default lighting is included. |
+| `level`, `index` | Current level and index. |
+| `width`, `height` | Current stage dimensions in CSS pixels. |
+| `win()`, `fail()` | Finish the level and display a result popup. `fail()` always fails immediately. Repeated results are ignored. |
+| `mistake()`, `move()` | Lose one heart or spend one move in the matching mode. Returns `false` in other modes, outside active play, or from an old level. |
+| `failure` | Read-only resource snapshot: `type`, `initial`, `remaining`, and `playOnAmount`. |
+| `signal` | Aborted on level exit. Use for fetches and event listeners. |
+
+Setup can return the following optional hooks and settings:
+
+| Hook or setting | Purpose |
+| --- | --- |
+| `update(dt, elapsed)` | Advance gameplay; time values are seconds. |
+| `pointer(event)` | Handle input with `type`, `originalEvent`, normalized `point`, `raycaster`, and recursive `hits(objects?)`. The canvas captures pointers for dragging and forwards cancellation. |
+| `resize(width, height)` | Update layout or a custom camera using stage dimensions in CSS pixels. |
+| `beforeRender()` | Run a shadow map or other pre-pass immediately before every draw, including resize, paused frames, and `step(0)`. Restore any renderer state changed by the pass. |
+| `debug()` | Return JSON-serializable game state for `game.debug()` and headless JSON. Keep this hook free of side effects; inspection may call it repeatedly. |
+| `camera` | Supply a Three.js camera, including an orthographic camera. Meshpad leaves its projection alone. |
+| `autoResizeCamera` | Set `false` to preserve the default camera's custom projection, or `true` to update a supplied perspective camera's aspect automatically. |
+| `onPlayOn()` | Optional recovery hook after the resource is restored. The scene, elapsed time, and level signal are preserved. Hook errors show retry. |
+| `dispose()` | Release non-scene resources. |
+
+For example, return `{ camera: myOrthographicCamera, resize(width, height) { /* update its frustum */ }, debug: () => ({ moves, grabbed }) }`. The default perspective camera remains available in setup's context; `game.camera` exposes the active camera after setup.
+
+The game exposes `ready`, `loadLevel(index)`, `restart()`, `next()`, `previous()`, `win()`, `fail()`, `mistake()`, `move()`, `playOn()`, `pause()`, `resume()`, `step(seconds)`, `debug()`, and `dispose()`, plus `scene`, `camera`, `renderer`, and read-only `state`. Await `game.ready` before interacting programmatically; `scene` and `camera` are initially undefined. `debug()` returns `null` without a debug hook. Loading returns a promise and resolves `false` if a newer load supersedes it. An explicit load or disposal before initial setup supersedes the deferred load as well. Navigation stops at the first/last level. `state.status` is `loading`, `playing`, `paused`, `won`, `failed`, `error`, or `disposed`.
+
+Each level owns its scene: Meshpad disposes geometry, materials, textures, skeletons, and shadows on exit. Avoid sharing these resources across levels. Use `dispose()` for controls, timers, audio, or render targets. Use `signal` for listeners (`element.addEventListener('click', handler, { signal })`) and async work; check `signal.aborted` after awaiting work that cannot be cancelled. Old level callbacks cannot alter the active level. Setup failures reject the load promise and show a retry screen; runtime hook failures show the same screen and call `onError`.
+
+### Failure modes
+
+Try all four HUDs with `node bin/meshpad.js dev examples/failure-modes/game.ts` in this repository. Tap the cube to progress; in this demo, missed taps trigger mistakes or consume moves.
+
+Set `failure` on the game, or override it on an individual level. Omitting it preserves the existing direct fail/retry behavior.
+
+| Mode | Configuration | Failure trigger | Play on |
+| --- | --- | --- | --- |
+| Default | `{ type: 'default' }` | `fail()` | Unavailable; retry only |
+| Hearts | `{ type: 'hearts', hearts: 3 }` | Each `mistake()` loses one heart; zero fails | Refill all hearts |
+| Time | `{ type: 'time', seconds: 90, playOnSeconds: 20 }` | Countdown reaches zero | Add 20 seconds, configurable |
+| Moves | `{ type: 'moves', moves: 25, playOnMoves: 10 }` | Each `move()` spends one move; zero fails | Add 10 moves, configurable |
+
+Hearts default to 3 and support 3, 4, or 5. Time and moves require a positive starting value. Move counts and bonuses must be positive safe integers; seconds and time bonuses must be positive finite numbers. Invalid settings throw before a renderer is created.
+
+```ts
+createGame({
+  failure: { type: 'hearts', hearts: 4 },
+  levels: [
+    { setup({ mistake }) { /* Call mistake() for each incorrect action. */ } },
+    { difficulty: 'hard', failure: { type: 'time', seconds: 60, playOnSeconds: 30 }, setup() {} },
+    { failure: { type: 'moves', moves: 15 }, setup({ move, win }) {
+      // After applying an accepted move: if solved, win(); otherwise, move().
+      // Checking the win first lets the final available move complete the level.
+    } },
+    { failure: { type: 'default' }, setup({ fail }) { /* Direct fail/retry. */ } },
+  ],
+});
+```
+
+The timer is automatic and displays remaining seconds rounded up as `MM:SS`. It advances with simulation time, including `step()`, and pauses while gameplay is paused, the level list is open, or the tab is hidden. Hearts show filled and empty heart icons; moves show a box labeled **Moves** above the count. Every variant keeps the level index and the same navigation controls. The dropdown-style level label opens a scrollable list of level rows with difficulty badges and allows selecting any level; closing it restores the prior pause state. Programmatic `next()` and `previous()` remain available.
+
+`game.state.failure` and `context.failure` expose immutable snapshots. Resource fields are `null` in default mode. On failure, **Play on** restores hearts or adds the configured time/moves without rerunning setup, resetting elapsed time, or replacing the board. **Retry** and the HUD restart button start the level fresh. Play on can be used after each failure and returns `false` unless the current level has failed in a resource mode. Win and error screens never offer play on.
+
+### Mobile defaults
+
+The stage fills the available height and stays portrait, centered on wider screens. The default maximum width is 540px and pixel ratio is capped at 2. Included styles handle dynamic viewport height, safe-area insets, fixed positioning, overscroll, text selection, tap highlights, and touch gestures. Viewport resizing follows `visualViewport`, orientation, and page restoration. Rendering sleeps in hidden tabs, clamps frame deltas after interruptions, and resumes after WebGL context restoration. `pause()` remains in effect across tab changes.
+
+The generated HTML includes mobile viewport and standalone-web-app metadata. The default camera updates its aspect automatically; custom cameras own their projection and can use `resize` to update it. Styles apply a full-page game layout; pass `root` to mount in a specific element with its own dimensions.
+
+### Commands
+
+```sh
+meshpad dev [game.ts] --host 0.0.0.0 --port 5173
+meshpad build [game.ts] --out-dir dist
+meshpad typecheck [game.ts]
+meshpad preview --port 4173
+meshpad --help
+```
+
+Put static assets in `public/` and load them using paths such as `/models/piece.glb`. Imported assets and `new URL('./asset.png', import.meta.url)` work through Vite. Builds target Safari 15+ and Chrome 96+ with WebGL 2. Development on a phone uses your computer's LAN address and `--host 0.0.0.0`.
+
+### Headless rendering
+
+Install the bundled Playwright Chromium browser once:
+
+```sh
+npx meshpad browsers
+# Linux CI machines can also install system dependencies:
+npx meshpad browsers --with-deps
+
+npx meshpad render game.ts --output renders/level.png \
+  --width 390 --height 844 --level 1 --time 1.5
+```
+
+The renderer starts a local Vite server, loads the actual game in headless Chromium with software WebGL, waits for setup, advances simulation in fixed substeps, and saves a PNG plus adjacent JSON containing `state`, `debug`, DPR, and draw statistics. Animation starts at time zero; `--time` advances game hooks up to 60 seconds. Keep randomness seeded and animations in `update` for reproducible captures. Browser timers, external services, and asynchronously loaded assets outside setup are not deterministic; await required assets in setup. `--timeout` bounds setup (default 30000ms). `--json` also prints the result to stdout for other tools.
+
+`--scene-only` omits the HUD. `--dpr 2` doubles PNG dimensions and drawing-buffer resolution without changing the layout; capture DPR ranges from 0.25 to 4 and overrides the game's pixel-ratio cap. The output captures the portrait stage within the requested viewport; on a wide viewport the PNG is narrower than the viewport. Rendering needs Chromium locally or in CI; deployed games are static and need no server or browser installation.
+
+### Scripted play
+
+`play` uses the same headless runner as `render`, with browser pointer input projected from world positions. Write `steps.json` as an array:
+
+```json
+[
+  { "type": "pointerdown", "world": [-1, 0, 0] },
+  { "type": "state", "label": "grabbed" },
+  { "type": "pointermove", "world": [1, 0, 0] },
+  { "type": "advance", "seconds": 0.5 },
+  { "type": "screenshot", "output": "renders/dragging.png" },
+  { "type": "pointerup" },
+  { "type": "state", "label": "released" }
+]
+```
+
+```sh
+meshpad play game.ts --level 2 --script steps.json --dpr 2 \
+  --output renders/final.png
+```
+
+`play` requires `--script`; `render --script steps.json` also works. Both accept the same capture options and always save a final PNG and adjacent JSON. `play` prints the full result JSON, including labeled state and screenshot `snapshots`, so tests can assert on `debug` and `state.status`.
+
+Pointer steps use a single left mouse pointer. `world` is `[x, y, z]`, projected through the active camera; `pointerup` may omit it to release at the current position. Down/up with a world position first moves the pointer there, emitting normal browser move events. World positions target the canvas within the portrait stage, and HUD controls can intercept input as they do during manual play. Use `--scene-only` to hide the HUD for unobstructed input. A move is instantaneous; combine moves and `advance` steps for a timed drag. Each advance accepts 0–60 seconds and runs fixed substeps; gameplay stops advancing on win, failure, or pause.
+
+Screenshot paths inside the script are relative to the script file; CLI `--output` is relative to the working directory. Each screenshot gets adjacent JSON. The whole script is validated before launch, and runtime errors identify the failing step. Captures with a failing setup, frame hook, or non-serializable debug snapshot exit with a nonzero status.
+
+### Deploy
+
+```sh
+npm run build
+```
+
+Deploy the generated project to Vercel using the included `vercel.json`, which sets `npm run build` and `dist`. The output is a static site and can also be hosted anywhere that serves `dist/`. The toolkit repository itself builds its hello-world example with the same commands.
+
+### Development
 
 ```sh
-npm install meshpad
+npm install
+npm run typecheck
+npm test
+npm run test:browser  # requires meshpad browsers first
+npm run dev
+npm run render -- --time 1
 ```

package/addons.d.ts

@@ -0,0 +1 @@
+export * from 'three/addons';

package/bin/meshpad.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { buildProject, initProject, manifest, previewProject, startDev } from '../src/tooling.js';
+import { checkProject } from '../src/typecheck.js';
+
+const help = `Meshpad · single-file 3D game prototypes
+
+Usage:
+  meshpad init [directory]          Create a TypeScript hello-world project
+  meshpad dev [game.ts]             Start Vite with live type checking
+  meshpad build [game.ts]           Type check and build into dist/
+  meshpad typecheck [game.ts]       Check project types without building
+  meshpad preview                  Serve a production build locally
+  meshpad browsers [--with-deps]    Install Chromium for rendering
+  meshpad render [game.ts]          Type check and render to PNG + JSON
+  meshpad play [game.ts] --script <steps.json>
+                                   Run scripted input; print capture JSON
+
+Options:
+  --host <host>                    Dev/preview host (default: 127.0.0.1)
+  --port <number>                  Dev/preview port
+  --out-dir <path>                 Build/preview output directory
+  --output, -o <path.png>           Render output (default: renders/game.png)
+  --width <pixels>                 Render viewport width (default: 390)
+  --height <pixels>                Render viewport height (default: 844)
+  --dpr <number>                   Capture pixel ratio, 0.25–4 (default: 1)
+  --script <steps.json>            Pointer, advance, screenshot, and state steps
+  --json                          Print render result as JSON (play default)
+  --level <number>                 Render level, starting at 1
+  --time <seconds>                 Advance simulation before capture (0–60)
+  --timeout <milliseconds>         Render setup timeout (default: 30000)
+  --scene-only                    Capture without the HUD
+  --help, -h                      Show help
+  --version, -v                   Show version
+`;
+
+try {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+      host: { type: 'string' }, port: { type: 'string' }, 'out-dir': { type: 'string' },
+      output: { type: 'string', short: 'o' }, width: { type: 'string' }, height: { type: 'string' },
+      level: { type: 'string' }, time: { type: 'string' }, timeout: { type: 'string' },
+      dpr: { type: 'string' }, script: { type: 'string' }, json: { type: 'boolean' },
+      'scene-only': { type: 'boolean' }, 'with-deps': { type: 'boolean' },
+    },
+  });
+  const [command = 'dev', entry, ...extra] = positionals;
+  if (values.version) console.log(manifest.version);
+  else if (values.help) console.log(help);
+  else {
+    if (extra.length || (entry && ['preview', 'browsers'].includes(command))) throw new Error('Too many arguments. Run "meshpad --help".');
+    const options = { host: values.host, outDir: values['out-dir'] };
+    if (values.port != null) {
+      options.port = Number(values.port);
+      if (!Number.isInteger(options.port) || options.port < 0 || options.port > 65535) throw new Error('port must be an integer from 0 to 65535.');
+    }
+    switch (command) {
+      case 'init': {
+        const directory = await initProject(entry);
+        console.log(`Created ${directory}\n\nNext: cd ${JSON.stringify(directory)}\n      npm install\n      npm run dev`);
+        break;
+      }
+      case 'dev': {
+        const server = await startDev(entry, options);
+        server.printUrls();
+        break;
+      }
+      case 'build': await buildProject(entry, options); break;
+      case 'typecheck': {
+        await checkProject(entry);
+        console.log('TypeScript check passed.');
+        break;
+      }
+      case 'preview': {
+        const server = await previewProject(options);
+        server.printUrls();
+        break;
+      }
+      case 'browsers': {
+        const require = createRequire(import.meta.url);
+        const cli = join(dirname(require.resolve('playwright/package.json')), 'cli.js');
+        const child = spawn(process.execPath, [cli, 'install', 'chromium', ...(values['with-deps'] ? ['--with-deps'] : [])], { stdio: 'inherit' });
+        process.exitCode = await new Promise((resolve, reject) => { child.on('error', reject); child.on('exit', (code) => resolve(code ?? 1)); });
+        break;
+      }
+      case 'render': case 'play': {
+        if (command === 'play' && !values.script) throw new Error('play requires --script <steps.json>.');
+        const { captureGame } = await import('../src/capture.js');
+        const renderOptions = { output: values.output, sceneOnly: values['scene-only'], script: values.script };
+        for (const name of ['width', 'height', 'level', 'time', 'timeout', 'dpr']) if (values[name] != null) renderOptions[name] = Number(values[name]);
+        const result = await captureGame(entry, renderOptions);
+        if (command === 'play' || values.json) console.log(JSON.stringify(result, null, 2));
+        else console.log(`Rendered level ${result.level} → ${result.output}\n${result.three.calls} draw calls · ${result.three.triangles} triangles`);
+        break;
+      }
+      default: throw new Error(`Unknown command: ${command}. Run "meshpad --help".`);
+    }
+  }
+} catch (error) {
+  console.error(`meshpad: ${error.message}`);
+  process.exitCode = 1;
+}

package/index.d.ts

@@ -0,0 +1,133 @@
+/// <reference types="vite/client" />
+import type * as Three from 'three';
+export * as THREE from 'three';
+
+export interface GamePointer {
+  type: 'pointerdown' | 'pointermove' | 'pointerup' | 'pointercancel';
+  originalEvent: PointerEvent;
+  /** Normalized device coordinates, from -1 to 1. */
+  point: Three.Vector2;
+  raycaster: Three.Raycaster;
+  hits(objects?: Three.Object3D[]): Three.Intersection[];
+}
+
+export interface LevelHooks {
+  /** Runs after play on restores the resource, without setting up the level again. */
+  onPlayOn?(): void;
+  /** Replace the default camera. Custom cameras own their projection by default. */
+  camera?: Three.Camera;
+  /** Automatically update a perspective camera's aspect on resize. */
+  autoResizeCamera?: boolean;
+  /** Seconds since the last frame and since this level started. */
+  update?(dt: number, elapsed: number): void;
+  /** Runs immediately before every draw, including resize and step(0). */
+  beforeRender?(): void;
+  /** Return JSON-serializable state for inspection and headless captures. */
+  debug?(): unknown;
+  pointer?(event: GamePointer): void;
+  /** Use to update an orthographic camera or custom layout. */
+  resize?(width: number, height: number): void;
+  /** Dispose controls, audio, timers, or other non-scene resources. */
+  dispose?(): void;
+}
+
+export interface LevelContext {
+  scene: Three.Scene;
+  camera: Three.PerspectiveCamera;
+  renderer: Three.WebGLRenderer;
+  level: Level;
+  /** Zero-based level index. */
+  index: number;
+  /** Aborted on level exit, setup failure, or game disposal. */
+  signal: AbortSignal;
+  readonly width: number;
+  readonly height: number;
+  readonly failure: Readonly<FailureState>;
+  win(): boolean;
+  /** Fail immediately, regardless of the configured mode. */
+  fail(): boolean;
+  /** Lose one heart. Ignored outside hearts mode or active play. */
+  mistake(): boolean;
+  /** Spend one move. Check for a win before spending the final move. */
+  move(): boolean;
+}
+
+export type FailureMode =
+  | { type: 'default' }
+  | { type: 'hearts'; hearts?: 3 | 4 | 5 }
+  | { type: 'time'; seconds: number; playOnSeconds?: number }
+  | { type: 'moves'; moves: number; playOnMoves?: number };
+
+export interface FailureState {
+  readonly type: FailureMode['type'];
+  /** Null in default mode; seconds may be fractional. */
+  readonly remaining: number | null;
+  readonly initial: number | null;
+  readonly playOnAmount: number | null;
+}
+
+export type LevelDifficulty = 'normal' | 'hard' | 'very-hard' | 'ultra-hard';
+
+export interface Level {
+  name?: string;
+  /** Displayed in the level chooser. Defaults to normal. */
+  difficulty?: LevelDifficulty;
+  /** Overrides the game's failure mode for this level. */
+  failure?: FailureMode;
+  setup(context: LevelContext): LevelHooks | void | Promise<LevelHooks | void>;
+}
+
+export interface GameOptions {
+  levels: Level[];
+  /** Defaults to { type: 'default' }, with retry and no play on. */
+  failure?: FailureMode;
+  title?: string;
+  /** Element or selector. Defaults to document.body. */
+  root?: HTMLElement | string;
+  /** Zero-based index. Defaults to 0. */
+  initialLevel?: number;
+  background?: Three.ColorRepresentation;
+  /** Defaults to 2. */
+  maxPixelRatio?: number;
+  /** Portrait stage width cap in CSS pixels. Defaults to 540. */
+  maxWidth?: number;
+  renderer?: Three.WebGLRendererParameters;
+  onError?(error: Error): void;
+}
+
+export interface GameState {
+  readonly status: 'loading' | 'playing' | 'paused' | 'won' | 'failed' | 'error' | 'disposed';
+  readonly index: number;
+  readonly elapsed: number;
+  readonly error: Error | null;
+  readonly failure: Readonly<FailureState>;
+}
+
+export interface Game {
+  readonly renderer: Three.WebGLRenderer;
+  readonly scene: Three.Scene | undefined;
+  readonly camera: Three.Camera | undefined;
+  readonly state: GameState;
+  /** Initial setup starts in a microtask. Rejects on setup failure. */
+  ready: Promise<boolean>;
+  /** Current level's debug snapshot, or null when no debug hook is available. */
+  debug(): unknown;
+  /** Resolves false if superseded by another load or disposal. */
+  loadLevel(index: number): Promise<boolean>;
+  restart(): Promise<boolean>;
+  next(): Promise<boolean>;
+  previous(): Promise<boolean>;
+  win(): boolean;
+  fail(): boolean;
+  mistake(): boolean;
+  move(): boolean;
+  /** Continue a failed non-default level, preserving its scene and elapsed time. */
+  playOn(): boolean;
+  pause(): void;
+  resume(): void;
+  /** Advance up to 60 seconds in fixed substeps, then draw. */
+  step(seconds?: number): void;
+  dispose(): void;
+}
+
+export function createGame(options: GameOptions): Game;

package/index.js

@@ -1,3 +1,3 @@
-"use strict";
-
-module.exports = {};
+export { createGame } from './src/game.js';
+export * as THREE from 'three';
+import './src/styles.css';

package/package.json

@@ -1,16 +1,74 @@
 {
   "name": "meshpad",
-  "version": "0.0.0",
-  "description": "Meshpad — upcoming project.",
+  "version": "0.1.0",
+  "description": "A single-file toolkit for mobile-first Three.js game prototypes.",
+  "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./three": {
+      "types": "./three.d.ts",
+      "import": "./src/three.js"
+    },
+    "./addons": {
+      "types": "./addons.d.ts",
+      "import": "./src/addons.js"
+    },
+    "./package.json": "./package.json",
+    "./tsconfig": "./tsconfig.json"
+  },
+  "bin": {
+    "meshpad": "./bin/meshpad.js"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "node bin/meshpad.js dev examples/hello-world/game.ts",
+    "build": "node bin/meshpad.js build examples/hello-world/game.ts",
+    "preview": "node bin/meshpad.js preview",
+    "render": "node bin/meshpad.js render examples/hello-world/game.ts",
+    "typecheck": "node bin/meshpad.js typecheck examples/hello-world/game.ts",
+    "test": "node --test test/*.test.js",
+    "test:browser": "node --test test/browser/*.test.js"
+  },
+  "dependencies": {
+    "@types/three": "^0.185.0",
+    "playwright": "^1.64.1",
+    "three": "^0.187.0",
+    "vite": "^8.3.6",
+    "typescript": "~6.0.3"
+  },
+  "sideEffects": [
+    "./index.js",
+    "**/*.css"
+  ],
   "files": [
-    "index.js"
+    "index.js",
+    "index.d.ts",
+    "three.d.ts",
+    "addons.d.ts",
+    "tsconfig.json",
+    "src",
+    "bin",
+    "templates"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/havaliza/meshpad.git"
   },
-  "keywords": [],
+  "keywords": [
+    "three",
+    "vite",
+    "game",
+    "prototype",
+    "mobile",
+    "3d"
+  ],
   "author": "",
   "license": "ISC"
 }

package/src/addons.js

@@ -0,0 +1 @@
+export * from 'three/addons';