@homie-rocks/studio 0.46.6 → 0.48.0

package/CHANGELOG.md

@@ -17,9 +17,91 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.48.0] - 2026-10-13
+
+**Plugin 0.48.0** · Baked physics worlds for server rules and local prediction.
+
+Rules games can sweep capsules through a baked GLB with the same deterministic physics on the server and in local prediction.
+
+### Added
+
+- Rules games can opt into deterministic Rapier collision through
+  `@homie-rocks/physics`: build-time GLB baking, asynchronous initialization before
+  ticking, synchronous metered capsule sweeps, casts, rays, overlaps and solver
+  steps, and complete physics snapshots saved with the room. Browser movement
+  replays against the same baked world. Games without physics retain their
+  existing behavior and budget costs.
+- `ctx.substeps(body, hz, callback)` lets a game choose its own integration rate
+  within a room tick. Server and browser share the callback and budget; the view
+  draws its recorded intermediate poses. The build checks authoritative body
+  fields separately from these temporary drawing traces.
+- Release tests compare 220 complete guarded-room hashes across Node, Chrome and
+  workerd for eight capsules at 300 Hz on a 1,754-triangle level, restore mid-fall,
+  and settle two predictions exactly with 150 ms each way and seeded packet loss.
+  The calibration and real two-Chrome-player Octree trial are recorded in
+  `docs/physics-048-calibration.md` and `docs/receipts/`.
+- Physics 0.1.2 adds a stateless capsule cast for applications that own integration
+  and replay; it uses the package's existing character contact handling.
+
+### Fixed
+
+- Predictor callbacks that inspect the room no longer reenter snapshot replay.
+- Provider discovery recognizes existing Homie fal and ElevenLabs key files,
+  including the legacy workspace location, without copying or exposing keys.
+
+### Upgrade notes
+
+- Physics is opt-in. Install `@homie-rocks/physics` 0.1.2 and name the
+  game's static GLB with `map.physics.level`; see the Physics section of the
+  rules guide. The complete solver save can exceed browser-host checkpoint caps,
+  so the real-mesh example uses server hosting.
+
+## [0.47.0] - 2026-10-13
+
+**Plugin 0.47.0** · Wrapped worlds and generated collision maps.
+
+Games can wrap across map edges and replace seeded tile levels during play, with the same collision geometry in server rules and prediction.
+
+### Added
+
+- Maps may opt into wrapping independently on x, y and z with `wrap: {x:true}`;
+  periods come from bounds. Bodies, sweeps, rays, overlaps, support, near/box queries,
+  area events, ranged effects, spatial delivery, rewind and view interpolation use
+  periodic geometry. Crossing an edge wraps rather than clamps. Sweeps/rays retain
+  their supplied direction and pay for each periodic image they visit.
+- Room handlers can call `world.map.replace(data)`. A replacement is validated,
+  indexed and activated atomically at the next tick, preserving bounds and wrapping.
+  Compact current/pending revisions are saved and sent once per collision revision;
+  local prediction replays the same compiled map by activation tick.
+- Maps accept row-major `tiles` with width, height, size, optional origin and solid
+  height. Nonzero cells compile to indexed horizontal runs. Rules and movement can
+  query `map.tile(x,y)`; views read `room.map.tiles`.
+- Named multi-source cardinal `tiles.flows` bake during map compilation. Rules and
+  movement use constant-work `map.distance(name,x,y)` and `map.flow(name,x,y)`.
+  The standalone rules runtime ships the nav package's new `Flow.js` baker, checked
+  against its source in the release gate. Generation, copying, indexing and baking
+  are charged to the rules handler; ordinary static-map budget charges are unchanged.
+- Seeded virtual-time release cases cover two-view seam crossing in 2D/3D and
+  generated-map collision, mid-round regeneration and restore, including 300 ms
+  delay and 12% loss. Geometry and navigation tests cover periodic casts,
+  multi-period movement, atomic failure and independently checked shortest paths.
+  Eight-player generation/restore replays also match every save and snapshot
+  across Node, Chrome and workerd for 240 seeded ticks.
+
+### Fixed
+
+- Handlers reached synchronously by `world.dispatch` now report their coverage to
+  the build checker, including failures, without opening a second handler budget.
+- The rewrite guide specifies named helper re-exports (`export *` is refused), and
+  the rules guide explains that mandatory spawn fields precede deferred `arrive`.
+
+This release covers wrapped worlds and generated levels. Arbitrary triangle-mesh
+collision, the measured Rapier-versus-kernel decision, first-class integration
+substeps, and the assisted rewrite command remain follow-up work.
+
 ## [0.46.6] - 2026-10-11
 
-**Plugin 0.46.6** · Big rooms: what one room carries, measured.
+**Plugin 0.46.6** · Big rooms: what one room carries, measured. · [release-2026-10-11-studio-0.46.6](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-11-studio-0.46.6)
 
 What one room object carries on Cloudflare, measured in six trials and stated: with a light game at 20 ticks a second, 300 players with margin, 600 at the edge, 800 to 1,000 only by luck.
 

package/guides/game/REWRITE.md

@@ -17,7 +17,8 @@ Read RULES.md before starting.
    An old file named rules.ts may already export pure helpers that tests import.
    Preserve that public test API and every existing test file byte-for-byte,
    including imports. Re-export the old helpers from rules.ts if extracted into
-   another module; do not redirect tests to that module. Record test-file hashes
+   another module with named exports (`export { helper } from './helper'`);
+   `export *` is refused. Do not redirect tests to that module. Record test-file hashes
    before editing and compare them at the end. The filename alone does not
    mean it is a rules-plus-view game. If tests now load toolkit TypeScript under
    Node, use a narrowly scoped TypeScript loader and keep the normal test command

package/guides/game/RULES.md

@@ -404,6 +404,46 @@ map.spots, and `world.sweep/support/overlaps` (also on map). Sweeps test static
 `20 + 4S` plus copying, writes body.pos, and returns an optional hit.
 Movement may write pos, vel, heading, grounded and declared motion; never return
 an updated body. Normalize diagonals and respect maxSpeed. Collision movement needs a sweep; setting velocity alone does not move a body.
+
+### Integrating at the game's own rate
+
+Opt in from `move` with `ctx.substeps(body, hz, step)`. For a 20 Hz room,
+300 Hz runs fifteen integrations inside each tick; 60 Hz runs three. The rate
+must be a positive integer multiple of the room rate. Existing movement is
+unchanged unless it calls this method.
+
+```ts
+export const move = defineMove({
+  runner(body, input, ctx) {
+    ctx.substeps(body, 300, step => {
+      if (step.first && input.jump && body.grounded)
+        body.vel = { ...body.vel, z: 8 };
+      body.vel = { ...body.vel, z: body.vel.z - 30 * step.dt };
+      ctx.map.sweep(body, ctx.math.scale(body.vel, step.dt));
+    });
+  }
+});
+```
+
+The callback receives `dt` (seconds), zero-based `index`, `count`, `first`
+and end-of-step `fraction`. Use `step.dt` for integration; `ctx.dt` remains
+the full tick. A pulse belongs to the tick: consume it on `step.first` when
+it should act once. Held inputs retain their existing tick-mean semantics;
+this API does not recover the timestamp of changes within a tick. A game
+that already reconstructs held transitions can keep that policy in the
+callback. It does not change Stormbreak's existing integration.
+
+One body may be integrated once per move. The call charges 8 units plus
+64 per pose (the initial pose and each completed substep), before allocating
+the trace. Guarded callback operations and collision queries charge the
+same movement-handler budget as usual. There is no separate quota or
+implicit rate cap.
+
+The browser predicts the identical callback and draws between the recorded
+substep poses, including a path that leaves and returns to the same tick
+endpoint. The trace is temporary drawing data: it adds no wire fields or
+save fields. The final body and declared motion fields are saved as before.
+This helper does not add triangle collision or a physics world.
 Put freezes, boost expiry and knockback in declared motion. Initialize a late arrival
 in on.arrive too: onRoom.roundStart already happened before it joined.
 
@@ -1078,6 +1118,15 @@ leaves: take the marker down quietly. `ctx.ray/rays/rayAll` query what the
 player sees (`ctx.viewTick`); `ctx.preview` says the run is between ticks. A
 predictor runs often: keep it cheap, and keep per-entity state in `me`.
 
+`ctx.each(kind, fn)` reads frozen entities from the authoritative snapshot this
+prediction started from. Use it for pickups and other snapshot-based decisions;
+it excludes provisional ghosts. Reading `room.each`, `room.get`, `room.me` or
+ray queries inside a predictor cannot advance the clock or start a nested
+preview. Other room entities retain their normal drawn poses; `room.me` reads
+the authoritative own entity during the callback. Use the callback's `me` for
+the predicted own state. Snapshot reconciliation also prevents clock pumping
+through event listeners until replay finishes.
+
 To guess a shot the server will judge with rewind, ask for what the server
 will use (0.46.5). `ctx.judgedTick(aimTick)` is the tick it will pose the others
 at: the `aimTick` the input carries, held to how far back this seat may look
@@ -1178,3 +1227,161 @@ still snap to authority. Opt in only after measuring stop/reversal and delayed
 collision behavior for the game's mover.
 
 For multi-cast movement or scratch trajectory checks, `ctx.world.sweep(body, delta, {ground:false})` (also captured-scene `sweep`) moves and returns the same collision but leaves `body.grounded` unchanged. Use it only when your mover computes support explicitly. Omitting the option retains the existing support query and grounding behavior. This avoids paying for identical support checks after horizontal and upward probes.
+
+
+## Wrapped worlds and generated levels (0.47.0)
+
+Declare wrapping in the map, independently per axis. The period is the bounds'
+extent; an omitted axis keeps its existing bounded behaviour:
+
+```json
+{"bounds":{"min":[0,0,0],"max":[25,25,10]},"wrap":{"x":true}}
+```
+
+Bodies and hit positions use canonical coordinates in `[min,max)`. Sweeps and rays
+follow the supplied displacement through periodic copies of the geometry; they can
+cross more than one period and pay for each visited image. Near/box queries, area
+events, effect ranges, spatial delivery, rewind and drawing interpolation use the
+short way around. Exactly half a period chooses the negative direction. A renderer
+can read `room.map.wrap.x` (the pair `[min,max]`) to draw copies at the viewport's
+edges. The server does not duplicate entities. In a maze with one tunnel, keep
+solid border cells on every other row; wrapping itself is per axis, not per row.
+
+For a generated maze, replace the room's current map in `room.start` or a room
+handler. Build its data using the rules' seeded random source, then publish once:
+
+```ts
+world.map.replace({
+  bounds: { min: [0, 0], max: [25, 25] },
+  wrap: { x: true },
+  tiles: { width: 25, height: 25, size: 1, data: cells,
+    flows: { exit: [312] } },
+  spots: { start: [[12.5, 19.5]] },
+});
+```
+
+`replace` preserves the original bounds and wrapping. It validates, bakes cardinal
+navigation fields and compiles the spatial index before publishing anything. A
+failed bake leaves the previous revision intact. The last successful replacement
+in a tick becomes current at the next tick; all bodies use the same revision.
+The compact map data and activation tick travel with collision revisions and saves,
+including both current and pending maps. Prediction replays against that tick's
+compiled geometry. Late knowledge is corrected by the normal reconciliation path.
+
+Tiles are row-major integers: zero is open, nonzero is solid. `at` defaults to
+`[0,0,0]`, `size` and `solidHeight` to 1. Horizontal runs become indexed boxes,
+including in 3D. On a wrapped axis the grid must span the full map. Authored boxes,
+round shapes, terrain and spots can be included in the same replacement. The view
+reads `room.map.tiles`; rules and movement read `world.map.tile(x,y)` and
+`ctx.map.tile(x,y)`. Cell coordinates are integers, not metres. Outside an unwrapped
+grid is solid. A custom tile mover may read these cells instead of using sweeps.
+
+`flows` names lists of open destination cell indices. `map.distance(name,x,y)` gives
+cardinal hops to the nearest destination, or -1 when unreachable/unknown;
+`map.flow(name,x,y)` gives the next unit direction, zero at a destination, or
+undefined when unreachable/unknown. Each lookup is constant work (4 or 8 budget
+units). Baking uses `@homie-rocks/nav`'s shared cardinal flow implementation;
+left/up/right/down resolves ties, including tunnels. Change destinations by
+publishing new flow declarations with the map. This is a bake, not an unmetered
+path search: budget for every field and regenerate only when its goals change.
+
+Room replacement charges copying, grid scanning, index construction and each flow
+bake to the calling handler. Snapshots charge for the compact data. Existing static
+maps need no replacement and retain their previous budget charges. A few thousand
+cells regenerated a few times a round belong in one map revision; live collider
+entities remain suitable for independently moving doors, cover and platforms.
+
+`spawn` exposes a new entity before its deferred `on.arrive` handler. Pass every
+field that must be valid immediately in the spawn data; use `arrive` for subsequent
+work, not for mandatory initialization.
+
+## Physics
+
+Use the opt-in `@homie-rocks/physics` bridge when the level is an arbitrary triangle
+mesh: caves, ramps, stairs and the static environment of a game such as Octree
+Arena. Keep `ctx.map` for the kernel's boxes, circles, capsules and height tiles.
+Install `@homie-rocks/physics` 0.1.2 in the studio. A game that does not
+ask for physics loads no physics engine and pays no physics units.
+
+In `map/main.json`, name a static GLB relative to the game directory:
+
+```json
+{
+  "bounds": { "min": [-100, -100, -100], "max": [100, 100, 100] },
+  "physics": { "level": "assets/level.glb" }
+}
+```
+
+The build bakes the default scene's node transforms and triangles into the
+physics package's indexed mesh format. It converts glTF Y-up to rules Z-up
+(`x, -z, y`), preserves reflected winding, and ships the baked mesh with the
+server rules and the browser movement bundle. Skins, animations and morph targets
+need a separate static collision GLB. The server never loads or parses a GLB.
+
+The smallest moving capsule uses the same guarded movement on both sides:
+
+```ts
+// src/move.ts
+import { defineMove } from '@homie-rocks/studio/rules';
+export const move = defineMove({ runner(body, input, ctx) {
+  ctx.substeps(body, 300, step => {
+    if (step.first && input.jump && body.grounded)
+      body.vel = { x: body.vel.x, y: body.vel.y, z: 10 };
+    body.vel = { x: input.ax * 5, y: 0, z: body.vel.z - 30 * step.dt };
+    ctx.physics.sweep(body, ctx.math.scale(body.vel, step.dt), .35, 1.35);
+  });
+} });
+
+// src/rules.ts
+import { defineRules, f } from '@homie-rocks/studio/rules';
+import { move } from './move';
+export default defineRules({
+  contract: 2, space: { dims: 3 }, move,
+  entities: { runner: {
+    player: true,
+    input: { ax: f.held(), jump: f.press() },
+    body: { shape: 'capsule', radius: .35, height: 1.35, maxSpeed: 30 }
+  } },
+  room: { bots: { keep: 0 }, join() {
+    return { kind: 'runner', at: { x: 0, y: 0, z: 8 } };
+  } }
+});
+```
+
+Use `"room": {"host":"server","offline":false}` in `game.json`. Physics
+initialization is awaited once per isolate before any room can tick; calls inside
+a handler are synchronous. `sweep(body, delta, radius, height)` sweeps and slides
+an upright capsule whose `body.pos` is its centre and whose height includes its
+caps. It writes position, velocity and grounded state. `ctx.physics.cast`,
+`ray`, and `overlap` expose the package's convex shape cast, raycast and overlap
+queries; query shapes are boxes, spheres or capsules. Room/entity handlers have
+these operations at `world.physics` and can call `world.physics.step(seconds)`
+to advance the collision world's solver clock. Movement owns capsule integration;
+its queries do not create persistent physics bodies or advance another player's
+world. This bridge exposes the baked collision world, not rigid-body ownership or
+predicted dynamic-body interactions.
+
+Every operation is charged before its engine work. On a 1,754-triangle level:
+
+| Operation | Budget units |
+| --- | ---: |
+| Capsule/convex cast | 768 |
+| Ray | 640 |
+| Overlap | 640 |
+| Solver step | 8 + 2,400 per 1/300 second |
+| Capsule sweep and slide | 64 + 768 per cast, at most four casts |
+
+Mesh-query and solver charges scale by `ceil(triangles / 1754)`, at least one.
+Substeps retain their usual pose and guarded callback charges. There is no new
+room budget, player cap or rate quota. The reproducible calibration is
+`scripts/calibrate-rules-physics.mjs`; its receipt compares physics on the real
+mesh with kernel operations on a box, since the kernel has no arbitrary-mesh
+or solver-step equivalent.
+
+A room save includes the package's complete binary world snapshot as JSON bytes,
+including solver state and its time remainder. The capsule's position, velocity,
+grounded flag and declared motion are saved by rules as usual. Browser prediction
+creates the same baked world and replays pending guarded movement against it;
+substep drawing traces remain temporary. Physics worlds are disposed when their
+host or view closes. A full solver save can exceed browser-host checkpoint caps;
+the build measures this, and server-hosted rooms retain the full save.

package/guides/game/SKILL.md

@@ -6,6 +6,11 @@ metadata:
   providers: cloudflare github ollama
 ---
 
+For a game with its own fixed integration rate, use the opt-in
+`ctx.substeps(body, hz, step)` facility in `RULES.md` (Integrating at the game's
+own rate). Its callbacks share the tick budget and its recorded poses drive
+local drawing. Keep the game's input-transition policy explicit.
+
 Read the installed toolkit's `node_modules/@homie-rocks/studio/guides/game/{RULES,REWRITE}.md`
 before authoring: these match its runtime even when this plugin is older. Toolkit
 check/build report stale installed plugin copies and the update step. For solid slopes and terrain, use heightTiles with `base` and the source
@@ -75,6 +80,12 @@ Cloudflare or physical-phone capacity guarantees.
 
 ## Write and change rules plus view
 
+For wrapping worlds or generated levels, use the map's opt-in `wrap` and room-scoped
+`world.map.replace` APIs described in RULES.md's **Wrapped worlds and generated levels**.
+Prefer one indexed map revision for a generated maze; keep independently moving
+doors and platforms as live colliders. Generation and navigation baking spend the
+room handler's budget.
+
 **Read [RULES.md](RULES.md) before writing code.** All five starters use this contract.
 Work in few, large edits: read each source file once, decide its changes, then
 make every change it needs in ONE file_edit with an edits list. Build after each
@@ -445,3 +456,16 @@ nothing is cut off or runs off the side. Fix what you see; build again.
 A whole landing of the studio's own (`site/pages/<id>/index.html`) replaces the generated one: only when
 the person asks for a hand-made page, and start from the generated one's HTML so Play, the TV road and
 "Made with Homie" stay.
+
+## Physics
+
+For movement against a static GLB's triangles, use the opt-in physics bridge in
+[RULES.md](RULES.md#physics). Install `@homie-rocks/physics` 0.1.2, set
+`map/main.json`'s `physics.level` to the game's GLB, and call
+`ctx.physics.sweep(body, delta, radius, height)` inside the game's movement.
+`ctx.substeps(body, 300, step => { ... })` shares its existing handler budget and
+predicts the same baked world in the browser. The full example, cost table and
+save contract are in that section. Prefer kernel collision for its primitive
+maps; use physics for arbitrary static triangle levels. Initialization is awaited
+before the first room tick, calls in handlers are synchronous, and the complete
+physics snapshot is saved with the room. No opt-in means no physics load or cost.

package/lib/doctor.mjs

@@ -1,3 +1,4 @@
+import { providerKey } from './provider-key.mjs';
 /**
  * `homie-studio setup status` (also `homie-studio doctor`): what this computer and this person's accounts have for
  * a studio, as one checklist, before anything is made. For each thing: green, missing, or "do this now", what it
@@ -231,16 +232,17 @@ export async function setupStatus({
         const s = await exec(cliBin, ['auth', 'status', '--format', 'json'], { timeout: 10_000 });
         try { signedIn = Boolean(JSON.parse(s.stdout)?.schemes?.some((x) => x.logged_in)); } catch { signedIn = false; }
       }
-      return { cli: v.code === 0, signedIn, key: Boolean(env.ELEVENLABS_API_KEY), projects: root ? projectsElevenLabs(root) : false };
+      const credential = providerKey('elevenlabs', env);
+      return { cli: v.code === 0, signedIn, key: Boolean(credential.key), source: credential.source, projects: root ? projectsElevenLabs(root) : false };
     })(),
     (async () => {
-      const key = String(env.FAL_KEY ?? '').trim();
+      const { key, source } = providerKey('fal', env);
       if (!key) return { key: false };
       const base = String(env.FAL_API_URL || 'https://api.fal.ai').replace(/\/+$/, '');
       try {
         const res = await fetchFn(`${base}/v1/models/pricing?endpoint_id=fal-ai/flux/dev`, { headers: { Authorization: `Key ${key}` }, signal: AbortSignal.timeout(6000) });
-        return { key: true, valid: res.ok ? true : res.status === 401 || res.status === 403 ? false : null };
-      } catch { return { key: true, valid: null }; }
+        return { key: true, source, valid: res.ok ? true : res.status === 401 || res.status === 403 ? false : null };
+      } catch { return { key: true, source, valid: null }; }
     })(),
   ]);
 
@@ -386,7 +388,7 @@ export async function setupStatus({
   // ElevenLabs.
   rows.push({
     id: 'elevenlabs', label: 'ElevenLabs', need: 'optional', state: eleven.signedIn || eleven.key || eleven.projects ? 'ok' : 'optional',
-    detail: eleven.signedIn ? 'the elevenlabs CLI is signed in' : eleven.key ? 'ELEVENLABS_API_KEY is set' : eleven.projects ? 'through Stripe Projects (its key, in the studio\'s git-ignored .env; never shown)' : eleven.cli ? 'the elevenlabs CLI is here, not signed in' : 'not connected',
+    detail: eleven.signedIn ? 'the elevenlabs CLI is signed in' : eleven.key ? `key from ${eleven.source}` : eleven.projects ? 'through Stripe Projects (its key, in the studio\'s git-ignored .env; never shown)' : eleven.cli ? 'the elevenlabs CLI is here, not signed in' : 'not connected',
     unlocks: 'songs and game scores (the music skill), billed to your own ElevenLabs plan; every render is quoted first',
     fix: eleven.signedIn || eleven.key || eleven.projects ? null : eleven.cli
       ? { who: 'ai', run: 'elevenlabs auth login', say: 'ElevenLabs opens in your browser; sign in once. No key is pasted anywhere.' }
@@ -396,7 +398,7 @@ export async function setupStatus({
   // fal.
   rows.push({
     id: 'fal', label: 'fal', need: 'optional', state: fal.key ? (fal.valid === false ? 'act' : 'ok') : 'optional',
-    detail: !fal.key ? 'no FAL_KEY in this environment' : fal.valid === true ? 'FAL_KEY is set and fal accepts it' : fal.valid === false ? 'fal refused the FAL_KEY that is set (wrong or revoked)' : 'FAL_KEY is set (fal did not answer just now)',
+    detail: !fal.key ? 'no fal key in the environment or Homie key files' : `key from ${fal.source}; ${fal.valid === true ? 'fal accepts it' : fal.valid === false ? 'fal refused it (wrong or revoked)' : 'fal did not answer just now'}`,
     unlocks: 'painted art and backdrops (the art skill) and generated video clips (the video skill), on your own fal account under a budget; covers from a real frame and captured trailers are free',
     fix: fal.key && fal.valid !== false ? null : { who: 'ai', say: 'Use local art and captured footage. Paid fal scripts need an already connected account; never ask the person to find or set a key. Offer the provider browser connection only when generated media is requested.', open: 'https://fal.ai/dashboard' },
   });

package/lib/mcp-tools.mjs

@@ -1,3 +1,4 @@
+import { providerKey } from './provider-key.mjs';
 /**
  * THE LOCAL MCP SERVER'S TOOLS (`homie-studio mcp`, lib/mcp.mjs): the studio toolkit as MCP tools, so the Claude
  * desktop app (through the Homie extension), Claude Code or any MCP client builds games in the SAME chat that shows
@@ -1497,7 +1498,7 @@ export function toolDefs(ctx, avail = {}) {
 
 /** What the media tools need, cheaply (no network): ffmpeg on the PATH, ElevenLabs' CLI or key. */
 export function availability(env = process.env) {
-  return { node: true, ffmpeg: Boolean(which(process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg')), elevenlabs: Boolean(env.ELEVENLABS_API_KEY || which(process.platform === 'win32' ? 'elevenlabs.exe' : 'elevenlabs')) };
+  return { node: true, ffmpeg: Boolean(which(process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg')), elevenlabs: Boolean(providerKey('elevenlabs', env).key || which(process.platform === 'win32' ? 'elevenlabs.exe' : 'elevenlabs')) };
 }
 
 /** The codex page small enough to hand a card (a tool result over ~150,000 characters is not shown). */

package/lib/physics-mesh.mjs

@@ -0,0 +1,40 @@
+import { NodeIO } from '@gltf-transform/core';
+import { Matrix4, Vector3 } from 'three';
+
+/** Build-time only: bake the default GLB scene, including every node transform.
+ * Rules use Z-up; glTF is Y-up. (x,y,z) -> (x,-z,y) preserves handedness.
+ * Animated, skinned and morphing geometry needs an explicitly authored static collider.
+ */
+export async function bakePhysicsMesh(path) {
+  const document = await new NodeIO().read(path);
+  const root = document.getRoot();
+  const scene = root.getDefaultScene() ?? root.listScenes()[0];
+  if (!scene || root.listAnimations().length) throw new Error('physics mesh: needs a static default scene');
+  const vertices = [], indices = [];
+  scene.traverse(node => {
+    if (node.getSkin()) throw new Error('physics mesh: skinned nodes need a static collider');
+    const matrix = new Matrix4().fromArray(node.getWorldMatrix());
+    const mirrored = matrix.determinant() < 0;
+    for (const primitive of node.getMesh()?.listPrimitives() ?? []) {
+      if (primitive.getMode() !== 4 || primitive.listTargets().length) throw new Error('physics mesh: only static triangles are supported');
+      const positions = primitive.getAttribute('POSITION'), index = primitive.getIndices();
+      if (!positions || positions.getElementSize() !== 3) throw new Error('physics mesh: missing xyz positions');
+      const base = vertices.length / 3;
+      for (let i = 0; i < positions.getCount(); i++) {
+        const p = new Vector3().fromArray(positions.getElement(i, [])).applyMatrix4(matrix);
+        if (![p.x,p.y,p.z].every(Number.isFinite)) throw new Error('physics mesh: nonfinite vertex');
+        vertices.push(Math.fround(p.x), Math.fround(-p.z), Math.fround(p.y));
+      }
+      const count = index?.getCount() ?? positions.getCount();
+      if (count % 3) throw new Error('physics mesh: incomplete triangle');
+      for (let i = 0; i < count; i += 3) {
+        const triangle = [0,1,2].map(j => index ? index.getScalar(i+j) : i+j);
+        if (!triangle.every(n => Number.isSafeInteger(n) && n >= 0 && n < positions.getCount())) throw new Error('physics mesh: index out of range');
+        if (mirrored) [triangle[1],triangle[2]] = [triangle[2],triangle[1]];
+        indices.push(...triangle.map(n => base+n));
+      }
+    }
+  });
+  if (!indices.length) throw new Error('physics mesh: no triangles');
+  return { vertices, indices };
+}

package/lib/provider-key.mjs

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Read only; callers must expose source, never key. No environment mutation. */
+export function providerKey(provider, env = process.env) {
+  const variable = { fal: 'FAL_KEY', elevenlabs: 'ELEVENLABS_API_KEY' }[provider];
+  if (!variable) throw new TypeError('unknown media provider');
+  const value = String(env[variable] ?? '').trim();
+  if (value) return { key: value, source: variable };
+  // An explicitly supplied environment is also an isolated home in tests/tools.
+  const home = env.HOME || env.USERPROFILE || (env === process.env ? homedir() : null);
+  if (home) for (const relative of [`keys/${provider}-key`, `workspace/${provider}-key`]) {
+    const path = join(home, '.homie', relative);
+    try {
+      const key = readFileSync(path, 'utf8').trim();
+      if (key && !/[\r\n]/.test(key)) return { key, source: `~/.homie/${relative}` };
+    } catch { /* Missing or unreadable files are not credentials. */ }
+  }
+  return { key: null, source: null };
+}

package/lib/rules-build.mjs

@@ -23,8 +23,8 @@ import { seatsOf } from '../worker/seats.mjs';
  */
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { join, resolve, relative, isAbsolute } from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import { GUARD_MODULE, RULES_MODULE, guardRules, guardedPlugin, problemLine } from './rules-guard.mjs';
 import { capOf, RULES_FRAMES, rulesRates } from '../worker/limits.mjs';
 import { PACKAGE_ROOT, isRulesGame, rulesIndex } from './studio.mjs';
@@ -66,15 +66,15 @@ function readMap(g) {
  * `W` (guard.ts, the wall), `P` (pack.ts) and `M` (math.ts). They are one instance together, apart from any other
  * copy of the runtime in this process, so the guard's budget counter is theirs alone.
  */
-export async function loadRules(esbuild, root, id, code, { bundleOnly = false } = {}) {
+export async function loadRules(esbuild, root, id, code, { bundleOnly = false, physics = false } = {}) {
   const dir = join(root, '.studio', 'rules');
   mkdirSync(dir, { recursive: true });
   const gen = join(dir, `${id}-${process.pid}-${++loads}.linked.mjs`);
   writeFileSync(gen, code);
   const lib = (name) => JSON.stringify(join(PACKAGE_ROOT, 'rules', name));
-  const entry = `import def from ${JSON.stringify(gen)};\nimport * as R from ${lib('rules.ts')};\nimport * as H from ${lib('host.ts')};\nimport * as C from ${lib('core.ts')};\nimport * as W from ${lib('guard.ts')};\nimport * as P from ${lib('pack.ts')};\nimport * as M from ${lib('math.ts')};\nexport { def, R, H, C, W, P, M };\n`;
+  const entry = `import def from ${JSON.stringify(gen)};\nimport * as R from ${lib('rules.ts')};\nimport * as H from ${lib('host.ts')};\nimport * as C from ${lib('core.ts')};\nimport * as W from ${lib('guard.ts')};\nimport * as P from ${lib('pack.ts')};\nimport * as M from ${lib('math.ts')};\nexport { def, R, H, C, W, P, M };\n${physics ? `export { initializePhysics } from ${lib('physics-engine.ts')};` : ''}`;
   try {
-  const res = await esbuild.build({ stdin: { contents: entry, resolveDir: root, loader: 'js' }, bundle: true, format: bundleOnly ? 'cjs' : 'esm', target: 'es2022', platform: 'neutral', write: false, logLevel: 'silent', plugins: [rulesModulesPlugin()] });
+  const res = await esbuild.build({ stdin: { contents: entry, resolveDir: root, loader: 'js' }, bundle: true, format: bundleOnly ? 'cjs' : 'esm', target: 'es2022', platform: 'neutral', ...(physics ? {mainFields: ['module','main']} : {}), write: false, logLevel: 'silent', plugins: [rulesModulesPlugin()] });
   const text = res.outputFiles[0].text;
   if (bundleOnly) { rmSync(gen, { force: true }); return text; }
   const out = join(dir, `${id}.check-${createHash('sha256').update(text).digest('hex').slice(0, 12)}-${process.pid}-${(loads += 1)}.mjs`);
@@ -146,8 +146,15 @@ export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck
   if (!guarded.ok) throw new Error(`${g.kind === 'app' ? 'apps' : 'games'}/${g.id}: its rules were refused.\n${guarded.problems.slice(0, 20).map((p) => `  ${problemLine(p)}`).join('\n')}${guarded.problems.length > 20 ? `\n  … and ${guarded.problems.length - 20} more` : ''}`);
   const tune = readJson(join(g.dir, 'tunables.json')) ?? {};
   const map = readMap(g);
+  if (map.physics !== undefined) {
+    const { bakePhysicsMesh } = await import('./physics-mesh.mjs');
+    if (!map.physics || typeof map.physics.level !== 'string') throw new Error('map.physics.level must name the game’s static GLB');
+    const path = resolve(g.dir, map.physics.level), rel = relative(g.dir, path);
+    if (rel.startsWith('..') || isAbsolute(rel)) throw new Error('physics level must be inside the game');
+    map.physics = await bakePhysicsMesh(path);
+  }
   const seats = seatsOf(g);
-  const bundle = await loadRules(esbuild, root, g.id, guarded.code, { bundleOnly: true });
+  const bundle = await loadRules(esbuild, root, g.id, guarded.code, { bundleOnly: true, physics: Boolean(map.physics) });
   const data = { id: g.id, tune, map, room: g.room, seats, vocab: readJson(join(g.dir, 'agents.json')), sites: guarded.sites };
   // The declarations first, for the type check: a wrong program is named by the compiler before anything is played.
   await typecheckRules(root, g, await runRulesWorker(bundle, data, { declarationsOnly: true }), tune, { log });
@@ -158,7 +165,8 @@ export async function prepareRules(esbuild, root, g, { log = () => {}, longCheck
   const trial = RULES_CAPACITY_TRIAL;
   log(`info: rules runtime reference trial: ${trial.game}, ${trial.seats} players at ${trial.tickHz} Hz for ${trial.minutes} minutes on ${trial.host} (${trial.platform}). Cloudflare capacity and billing are unmeasured.`);
   if (settings.tickHz > trial.tickHz) log(`info: ${g.kind === 'app' ? 'apps' : 'games'}/${g.id} asks for ${settings.tickHz} Hz, above the completed local reference trial's ${trial.tickHz} Hz. This game's generated check does not establish live room capacity.`);
-  const { def, R, H } = await loadRules(esbuild, root, g.id, guarded.code);
+  const { def, R, H, initializePhysics } = await loadRules(esbuild, root, g.id, guarded.code, {physics: Boolean(map.physics)});
+  if (initializePhysics) await initializePhysics(readFileSync(new URL(import.meta.resolve('@homie-rocks/physics/vendor/rapier.wasm'))));
   const compiled = R.compileRules(def, { tune, map: R.compileMap(map, map.name), settings, seats });
   const stats = smokeRun(H, compiled, g.id, { timer: () => 0, vocab: data.vocab });
   const snapshotCap = capOf('snap', seats); const checkpointCap = capOf('ckpt', seats);
@@ -207,8 +215,8 @@ export function viewPlugin(g, rules, entry, { lab = false } = {}) {
         if (a.path === 'homie:rules') return { contents: rules.code, resolveDir: g.dir, loader: 'js' };
         if (a.path === 'homie:host') return { contents: `import def from 'homie:rules';\nimport { browserHost } from ${JSON.stringify(join(PACKAGE_ROOT, 'rules', 'browser.ts'))};\nexport const makeHost = browserHost(def, ${JSON.stringify({ id: g.id, build: rules.build, tune: rules.tune, map: rules.map, settings: rules.settings, seats: rules.seats, vocab: game.vocab })});\n`, resolveDir: g.dir, loader: 'js' };
         return (a.path === 'homie:view'
-        ? { contents: `import 'homie:game';\nimport ${JSON.stringify(entry)};\n`, resolveDir: g.dir, loader: 'js' }
-        : { contents: `${existsSync(move) ? `import { move } from ${JSON.stringify(move)};` : 'const move = {};'}\nimport { setGame${game.vocab ? ', setAgentFactory' : ''} } from '${RULES_MODULE}/view';\n${game.vocab ? `import { useAgents } from ${JSON.stringify(join(PACKAGE_ROOT, 'agents/agents.ts'))}; setAgentFactory(useAgents);` : ''}\n${factory}\nsetGame(${JSON.stringify(game)}, move, loadHost);\n`, resolveDir: g.dir, loader: 'js' });
+        ? { contents: `import 'homie:game';\n${rules.map.physics ? `await import(${JSON.stringify(entry)});` : `import ${JSON.stringify(entry)};`}\n`, resolveDir: g.dir, loader: 'js' }
+        : { contents: `${existsSync(move) ? `import { move } from ${JSON.stringify(move)};` : 'const move = {};'}\nimport { setGame${game.vocab ? ', setAgentFactory' : ''} } from '${RULES_MODULE}/view';\n${game.vocab ? `import { useAgents } from ${JSON.stringify(join(PACKAGE_ROOT, 'agents/agents.ts'))}; setAgentFactory(useAgents);` : ''}\n${factory}\n${rules.map.physics ? `import {initializePhysics} from ${JSON.stringify(join(PACKAGE_ROOT, 'rules', 'physics-engine.ts'))}; import bytes from ${JSON.stringify(fileURLToPath(new URL('./dist/vendor/bytes.js', import.meta.resolve('@homie-rocks/physics/package.json'))))}; await initializePhysics(Uint8Array.from(atob(bytes), c => c.charCodeAt(0)));` : ''}\nsetGame(${JSON.stringify(game)}, move, loadHost);\n`, resolveDir: g.dir, loader: 'js' });
       });
       rulesModulesPlugin().setup(b);
       guarded.setup(b);
@@ -228,7 +236,7 @@ export function writeRules(root, built, ids) {
   mkdirSync(dir, { recursive: true });
   for (const r of built.filter((r) => r.settings.host === 'server')) {
     writeFileSync(join(dir, `${r.id}.mjs`), `${HEADER}// The rules of games/${r.id}, checked and guarded (build ${r.build}).\n${r.code}`);
-    writeFileSync(join(dir, `${r.id}.data.mjs`), `${HEADER}export default ${JSON.stringify({ tune: r.tune, map: r.map, settings: r.settings, seats: r.seats, build: r.build, stateHash: r.stateHash }, null, 2)};\n`);
+    writeFileSync(join(dir, `${r.id}.data.mjs`), `${HEADER}${r.map.physics ? `import {initializePhysics} from '@homie-rocks/studio/rules/physics-engine';\nimport wasm from '@homie-rocks/physics/vendor/rapier.wasm';\n` : ''}export default ${r.map.physics ? '{initialize: () => initializePhysics(wasm), ...' : ''}${JSON.stringify({ tune: r.tune, map: r.map, settings: r.settings, seats: r.seats, build: r.build, stateHash: r.stateHash }, null, 2)}${r.map.physics ? '}' : ''};\n`);
   }
   const have = ids.filter((id) => existsSync(join(dir, `${id}.mjs`)) && existsSync(join(dir, `${id}.data.mjs`)));
   for (const name of readdirSync(dir)) {

package/lib/rules-check-worker.mjs

@@ -1,3 +1,4 @@
+import { boundPosition } from '../rules/topology.mjs';
 /**
  * The generated play of a rules game, in a worker thread of its own (rules-check.mjs starts it).
  *
@@ -19,6 +20,7 @@
  * units used by the room and by the browsers' `move`, bytes of save rebuilt), never by a clock, so the same source gives
  * the same verdict and the same lines on every computer.
  */
+import { readFileSync } from 'node:fs';
 import { parentPort, workerData } from 'node:worker_threads';
 import { compileFunction } from 'node:vm';
 import { checkDecide } from '../worker/brain.mjs';
@@ -353,8 +355,9 @@ function play(c, companions, allow) {
         error => { fault ??= `${siteOf(name, 'move')} ${name}.move: prediction failed: ${error.message}.${when()}`; });
       units += result.used;
       const r = kind.body.radius, height = kind.body.height || 2 * r, bounds = c.map.bounds;
-      result.pos = L.P.vec3({ x: Math.max(bounds.min.x + r, Math.min(bounds.max.x - r, result.pos.x)), y: Math.max(bounds.min.y + r, Math.min(bounds.max.y - r, result.pos.y)), z: c.dims === 3 ? Math.max(bounds.min.z, Math.min(bounds.max.z - height, result.pos.z)) : 0 }, c.dims);
+      result.pos = L.P.vec3(boundPosition(result.pos,geometry??c.map,r,height,c.dims),c.dims);
       delete result.used;
+      delete result.steps; // Drawing traces are not authoritative body fields.
       if (JSON.stringify(result) !== JSON.stringify(after)) fault ??= `${siteOf(name, 'move')} ${name}.move: prediction and the server produced different bodies from the same input.${when()}`;
     }
     if (A.core.stats.tickUnits > peak) peak = A.core.stats.tickUnits;
@@ -389,6 +392,7 @@ try {
     let at = null; try { const g = linked.exports.W.G; if (g.line) at = `${g.file}:${g.line}`; } catch { /* the guard itself did not load */ }
     throw new Error(`${at ?? here()}: ${diagnostic(String(error?.message ?? error))}`);
   }
+  if (L.initializePhysics) await L.initializePhysics(readFileSync(new URL(import.meta.resolve('@homie-rocks/physics/vendor/rapier.wasm'))));
   const { c, problems } = compile();
   const result = { vocab: data.vocab, schema: L.R.schemaOf(c), publicTune: c.publicTune, settings: c.settings, problems, rounds: c.rounds, stateHash: stateHash(c),
     declarations: { events: c.events, asks: Object.fromEntries(Object.entries(c.asks).map(([n, a]) => [n, { state: a.stateFields, questions: a.questions }])), view: L.def.shapes?.view ?? {} } };

package/lib/rules-check.mjs

@@ -67,5 +67,5 @@ export function runRulesWorker(bundle, data, { declarationsOnly = false, allowan
 export async function checkRules(esbuild, root, id, code, data, options = {}) {
   // Imported here, not at the top: the worker imports this file for `stateHash`, and has no use for the build's tools.
   const { loadRules } = await import('./rules-build.mjs');
-  return runRulesWorker(await loadRules(esbuild, root, id, code, { bundleOnly: true }), { id, ...data }, options);
+  return runRulesWorker(await loadRules(esbuild, root, id, code, { bundleOnly: true, physics: Boolean(data.map?.physics) }), { id, ...data }, options);
 }