@homie-rocks/studio 0.47.0 → 0.48.1

package/CHANGELOG.md

@@ -17,6 +17,97 @@ 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.1] - 2026-10-13
+
+**Plugin 0.48.1** · Input history under loss.
+
+Rules views recover missing input and acknowledge late movement scheduling.
+
+### Changed
+
+- Snapshots that precede a predicted input's application receipt retain the live
+  movement prediction within the replay window; explicit placements still apply.
+- Prediction clock steering is limited to 0.5% instead of 5%; it slews without
+  repeatedly rebasing stamped input when the jitter estimate changes.
+- Rules input frames repeat a bounded history sized from measured latency and
+  jitter and missing application receipts, with input sequence numbers and sub-tick control changes. Snapshot
+  control rows report application ticks, including pulses. Retransmissions no
+  longer distort latency steering. A newer tick acknowledgement cannot stop
+  retries for an earlier missing input; only its own receipt does.
+- Late movement replays up to one second of body history against historical
+  geometry, fenced by authoritative body writes and placements. Outside that
+  history an entry applies next tick. Entries with press handlers also apply
+  next tick, so historical replay cannot duplicate world actions. New views use application receipts instead
+  of negative held-input compensation; old wire entries retain their behaviour.
+- Small visual corrections use `room.predict.blendMs` and expire within one
+  second (or an explicitly longer blend), including while stationary; `idleHold` no longer holds them indefinitely. Placement counters
+  still distinguish respawns from prediction corrections. Vertical travel cannot
+  erase a horizontal correction fast enough to reverse the held direction.
+  Remaining offsets drain over the final 250 ms rather than snapping at expiry.
+
+### Added
+
+- `room.input(sample, {at})` timestamps a control inside the current predicted
+  tick. `player.pulses: 'hold'` queues actions while control is taken;
+  `'drop'` remains the default.
+- Seeded virtual-time coverage of 40/80/150/300 ms each way and 0.5/1/2/5% loss,
+  dropped inputs and ordered stall/burst delivery, in small rooms and through Gates.
+- A seeded baked-physics-world regression at 80 ms each way and 2% loss checks
+  zero drawn warps, application receipts, 300 Hz substeps, predictor room reads
+  and exact settling for two moving bodies.
+
+### Fixed
+
+- Multiple pulse calls within one predicted tick queue instead of overwriting
+  one another. Their application ticks are distinct from the movement entry.
+- Placements preserve the established prediction-clock phase, and the snapshot
+  body is advanced to its predicted tick instead of relabelling an old pose.
+  Projection is bounded to the server's one-second input window, and its controls
+  are stamped for that same path. Queued held state from an earlier placement
+  cannot later change the respawned body; discrete presses received before the
+  browser learns of the placement still belong to the player.
+- A fresh control after a browser stall is recorded after resetting the stale
+  prediction clock, preventing a short press from moving by the stalled backlog.
+
+## [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.

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
@@ -1172,10 +1221,8 @@ occupied terrain nodes out of the graph, and choose reachable endpoints.
 `@homie-rocks/nav` is the richer mesh/crowd API for applications that own that
 runtime; rules graphs avoid importing mutable navigation state into handlers.
 
-`room.predict.idleHold: true` holds small visual reconciliation offsets while
-input and body are stationary. Movement resumes smoothing. Large invalid poses
-still snap to authority. Opt in only after measuring stop/reversal and delayed
-collision behavior for the game's mover.
+Small reconciliation offsets expire even while stationary; see “Input during loss
+and stalls” below for the visual correction settings.
 
 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.
 
@@ -1245,3 +1292,141 @@ 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.
+
+## Input during loss and stalls (0.48.1)
+
+Rules views resend recent input automatically: a 4–64 tick history follows the
+measured round trip, jitter and missing application receipts (loss or recovery
+delay). Each tick entry carries a sequence number; each
+control change carries a field index, sequence and fraction of the predicted tick.
+Duplicates neither execute again nor count as fresh latency measurements. Both
+missing application frames and ordered TCP stalls are covered.
+
+The server retains up to one second of movement history and replays late movement
+against the geometry of those ticks. It never repeats commands or effects. An
+external body/motion write or placement fences that history. Beyond a fence or
+the retained history, input applies on the next tick instead. Entries carrying
+press handlers also apply next tick: world actions are never rerun as movement. Snapshot control
+rows report the application tick and the view uses it for replay. Within the
+replay window a snapshot still missing a predicted input does not replace live
+movement; an explicit placement always does. Legacy wire
+entries retain their old compensation; current views do not receive negative
+held values to repay late releases.
+
+Held controls integrate their duration, sampled controls coalesce to the latest
+value per tick, presses coalesce per field per tick, and valued pulses execute
+in order, one per tick. More sampled input never buys extra simulation steps.
+The clock resets before a fresh control after a long browser stall, so the press
+cannot inherit ten seconds of elapsed time. The prediction clock slews by at
+most 0.5%, preserving the cadence for fixed-step renderers.
+
+`room.input(sample, {at: event.timeStamp})` accepts the event's monotonic time
+(same origin as `performance.now()`), clamped to this predicted tick and now.
+Omit it to use the call time. A player can declare
+`player: {control: 'canMove', pulses: 'hold'}` to keep pulses during a knock or
+stun and deliver them when control returns. The default `'drop'` preserves the
+previous behaviour. The game's action handler still decides its cooldown.
+
+Residual drawing corrections use `room.predict.blendMs` (100 ms by default),
+slowed on each moving axis to avoid reversing movement (jumping cannot spend
+horizontal correction faster), with a one-second maximum
+(or the explicitly longer blendMs). Any remainder drains over the final 250 ms
+rather than disappearing on the deadline. `snapM` selects the large-error threshold;
+placements still snap. A placement keeps the established clock phase and
+projects the new body from the snapshot tick to the own tick; it never labels an
+old pose as a future one. Projection is bounded to one second and sends the
+controls it used. Queued held state from an earlier placement cannot later
+change the new body. Newly received discrete presses still belong to the player
+when the browser has not yet learned of that placement. `idleHold` no longer keeps a stopped body displaced
+indefinitely. These drawing settings never alter server truth.

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
@@ -451,3 +456,25 @@ 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.
+
+### Input under loss
+
+Rules games inherit redundant sequenced input, late movement replay and applied-tick
+receipts. Do not add a game-side resend loop or interpret negative held values as
+late-release repayment. Use `f.held()` for duration, sampled fields for latest
+state and `f.pulse()` for ordered actions. Choose `player.pulses: 'hold'` when a
+knock should buffer an action; the default drops it. See RULES.md, “Input during
+loss and stalls”, for timestamps, replay boundaries and visual correction settings.

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

@@ -20,6 +20,7 @@ import { boundPosition } from '../rules/topology.mjs';
  * 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';
@@ -356,6 +357,7 @@ function play(c, companions, allow) {
       const r = kind.body.radius, height = kind.body.height || 2 * r, bounds = c.map.bounds;
       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;
@@ -390,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);
 }

package/lib/rules-guard.mjs

@@ -69,9 +69,10 @@ export const HOOK_NAMES = ['valueOf', 'toString', 'toJSON'];
 export const WORLD_METHODS = ['ticks', 'random', 'route', 'label', 'send', 'dispatch', 'sendRoom', 'announce', 'sendArea', 'after', 'emit', 'spawn', 'despawn', 'place', 'near', 'inBox', 'ray', 'rayAll', 'rays', 'sweep', 'ask', 'goalDone', 'finish', 'end', 'restart', 'spot', 'spots', 'replace', 'tile', 'distance', 'flow'];
 export const MATH_METHODS = ['sin', 'cos', 'tan', 'atan', 'atan2', 'asin', 'acos', 'exp', 'log', 'pow', 'hypot', 'rad', 'deg', 'clamp', 'lerp', 'vec', 'add', 'sub', 'scale', 'dot', 'cross', 'len', 'dist', 'norm', 'clampLen', 'lerpVec', 'dir', 'angle'];
 const VALUE_METHODS = new Set([...ARRAY_METHODS, ...STRING_METHODS, ...MAPSET_METHODS]);
-export const MOVE_METHODS = ['support', 'overlaps'];
-const NEW_METHODS = new Set(['route','label','dispatch','rayAll','rays','restart','replace','tile','distance','flow']);
-const CALLABLE = new Set([...VALUE_METHODS, ...WORLD_METHODS, ...MOVE_METHODS, ...MATH_METHODS]);
+export const MOVE_METHODS = ['substeps', 'support', 'overlaps'];
+export const PHYSICS_METHODS = ['step', 'cast', 'overlap'];
+const NEW_METHODS = new Set(['step','cast','overlap','substeps','route','label','dispatch','rayAll','rays','restart','replace','tile','distance','flow']);
+const CALLABLE = new Set([...VALUE_METHODS, ...WORLD_METHODS, ...MOVE_METHODS, ...PHYSICS_METHODS, ...MATH_METHODS]);
 const refusedName = (k) => REFUSED_NAMES.includes(k) || k.startsWith('toLocale');
 /** Operators that turn each operand into a number or a text. (`+` is handled beside them; `==` and `!=` are refused.) */
 const CONVERTING = new Set(['-', '*', '/', '%', '&', '|', '^', '<<', '>>', '>>>', '<', '>', '<=', '>=']);

package/lib/rules-types.mjs

@@ -119,7 +119,7 @@ export type Room<R = never> = Omit<BaseRoom<R>, 'me' | 'each' | 'get' | 'on' | '
  each<K extends keyof Entities>(kind: K, fn: (entity: Entities[K]) => void): void;
  get(id: string): Entity | null;
  on<K extends keyof Effects>(name: K, fn: (event: Effects[K]) => void): () => void;
- input(sample: ${input}): void;
+ input(sample: ${input}, options?: {at?: number}): void;
  command<K extends keyof Commands>(name: K, ...data: {} extends Commands[K] ? [data?: Commands[K]] : [data: Commands[K]]): void;
 };
 export declare function openRoom<R = never>(options?: OpenRoomOptions): Room<R>;