@homie-rocks/studio 0.44.0 → 0.44.1

package/CHANGELOG.md

@@ -17,6 +17,28 @@ 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.44.1] - 2026-10-10
+
+**Plugin 0.44.1**
+
+Predicted movement meets the live world, and local builds keep dev running.
+
+### Added
+
+- Rules movement sweeps, support and overlap queries include declared live colliders: rectangular cover, doors and platforms, with tick-stamped geometry in prediction and room restores.
+- The npm package ships generated, version-matched game authoring and rewrite guides. Studio guidance and check/build output point to them and report older plugin copies with an update step.
+
+### Fixed
+
+- Spatial delivery retains live collision revisions in keyframes and compact updates, even when a collider lies outside the player’s visual interest radius.
+- Rebuilding while dev is running preserves immutable Worker module graphs and atomically switches the entry, so a reload cannot lose its imported chunks.
+- Customer offers omit the studio refund window when no window is set.
+
+### Upgrade notes
+
+- Declare non-player entity colliders with `collider: true` or `{size, enabled}` field names. Movement uses `ctx.world.sweep/support/overlaps`; existing `ctx.map.sweep` includes declared colliders too. Games without colliders keep their existing snapshot shape.
+- Read `node_modules/@homie-rocks/studio/guides/game/` after upgrading. Older plugin sessions need an update and a new session; the installed guides are usable immediately.
+
 ## [0.44.0] - 2026-10-10
 
 **Plugin 0.44.0** · [#83](https://github.com/homie-rocks/homie/pull/83)

package/README.md

@@ -41,7 +41,8 @@ asks (`game new <id> --from gem-rush`, or `--from ember-vale` for a hero who las
 New games are rules plus view: `src/rules.ts` declares state and server decisions,
 `src/move.ts` supplies shared movement and local prediction, and `src/view.ts` draws
 and sends input through `openRoom`. All five starters declare `room.host: server`.
-Follow the game skill and `RULES.md`; `build` checks rules, movement and view types
+Read the installed [game skill](guides/game/SKILL.md), [rules guide](guides/game/RULES.md)
+and [rewrite guide](guides/game/REWRITE.md), generated from the matching plugin release; `build` checks rules, movement and view types
 and refuses a game with neither rules nor a browser-hosted netplay contract.
 The same rules support browser hosting for offline, local and private play.
 Existing browser-hosted games remain supported; rewriting one is an explicit task.

package/bin/homie-studio.mjs

@@ -901,6 +901,10 @@ async function main() {
   // The starter library and the optimiser work anywhere; the rest of style and assets inside a studio (lib/art-cli.mjs).
   if (cmd === 'assets' && ['find', 'optimise', 'optimize'].includes(sub)) return assetsCommand(null, sub, positional, flags, { log });
   const root = requireStudio();
+  // Keep guidance visible to AI callers using --json as well as human output.
+  if (['build', 'check', 'upgrade'].includes(cmd)) {
+    for (const line of (await import('../lib/authoring-guides.mjs')).authoringWords()) process.stderr.write(`${line}\n`);
+  }
   if (cmd === 'function') return (await import('../lib/functions-cli.mjs')).functionCommand(root, sub, positional, flags, { log });
   if (cmd === 'tool') return (await import('../lib/tools-cli.mjs')).toolCommand(root, sub, positional, flags, { log });
   // A trailer is the plugin's video skill; this hands the words after the id over to it (lib/trailer.mjs).

package/guides/game/REWRITE.md

@@ -0,0 +1,78 @@
+# Rewrite a browser-hosted game as rules plus view
+
+Use this path when the owner asks to move an old game's rules onto the server.
+There is no automatic converter. An ordinary edit is not permission to rewrite;
+old games continue to work as they are. Read RULES.md before starting.
+
+1. Read this game's codex, manifest, entry, host loop, input, packing/checkpoint
+   code, bots, saves and tests. Record what players must keep: controls, timings,
+   movement curve, camera, art, sound, collisions, scoring, rounds and joining.
+   Play a baseline on computer and phone and capture the same short actions and
+   screenshots you will repeat later. Keep a commit or separate copy to compare.
+   Do not change other games, shared studio configuration or their tests to make
+   this game pass. Install the studio's pinned dependencies; upgrade the toolkit
+   only when needed for the requested rewrite, preserving unrelated dependencies.
+   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
+   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
+   working. Do not count a special test invocation while `npm test` is broken.
+2. Keep the renderer, assets, camera, UI and audio as the view. Make an inventory
+   of every value that can change play. Put each on the entity that owns it with
+   declared fields; put room-wide facts in shared. Replace packed rows with named
+   fields, numeric IDs with opaque refs, and remembered module state with fields.
+3. Extract the existing movement curve into defineMove. Keep its units and timing
+   by converting to metres and seconds at one boundary. Use ctx.math and the
+   compiled map; encode knockback, cooldowns and freezes in motion. The view must
+   draw room.me/room.each, not integrate a second body. The same movement now runs
+   on the server and predicts on the player's screen. Preserve feel by measuring
+   acceleration, jump apex, duration, stop distance and knock distance against baseline.
+4. Move hits, pickups, spawns, scores and victory into rules. An entity writes only
+   itself; requests to other entities become declared events. The receiver validates
+   the request and changes itself, then sends a result. Shared writes and round ends
+   belong to room handlers. Replace clocks and random calls with world ticks/math/RNG.
+   Replace direct model calls with declared asks and a deterministic floor. Bots
+   produce inputs in think. Companions use guide/view/floor and vocabulary goals.
+5. Write map/main.json from the existing collision geometry. Use it for the view
+   too; keep purely decorative art out of collisions. In 3D z is up in rules, feet
+   locate a body, and Three.js maps x,y,z to x,z,y. Preserve spawn locations and
+   arrival/reset behavior, including arrivals during the results break.
+6. Replace view-side networking with openRoom<typeof rules>(). Send input and
+   declared commands, listen for declared effects, retain chat/watch/prefs through
+   room.net. Remove the old host loop, Roster, packing, snapshots and checkpoint
+   callbacks from this game's entry. Keep cloud character saves and their key/schema;
+   they remain separate from automatic room saves and are not verified currency.
+   Set manifest entry to src/view.ts, index.html to the relative ./assets/main.js
+   module script, and room.host to server.
+   Retain the game's ID and public URLs. Do not change to browser hosting to pass.
+   In a studio made before server rules, compare site/src/worker.mjs with the
+   installed toolkit's Worker template: it must import the generated
+   ./rules/index.mjs registry and call hostRules(rules). Add that small hookup
+   while retaining the studio's existing routes and configuration. Confirm both
+   browsers report hosted=server and role=replica; a successful build alone cannot
+   prove an older custom Worker registered the rules.
+7. Build early and after each coherent extraction. Read every diagnostic and repair
+   its source using RULES.md's message guide; never edit the toolkit/guard or remove
+   tests to escape a restriction. Type errors often name a capability moved to the
+   wrong half. A save/checker internal failure must be reported as such.
+8. Repeat the baseline in two real browsers with 150 ms delay: same controls, art,
+   camera, first minute, win/loss and next round; both browsers must be replicas of
+   the server. Check late join, reload, reconnect and a player leaving. Run check,
+   this game's existing tests and the studio's other tests unchanged. Compare files
+   outside this game against baseline and explain any necessary shared-file change.
+   Report observed differences and limits rather than claiming equivalence from a build.
+
+Do the engineering yourself. Tell the owner what changed for their game, what was
+preserved and how you checked it. Never promise larger rooms, private per-seat
+state, perfect latency or automatic conversion.
+
+For buildable/destructible worlds, declare non-player entities with `collider: true`
+or `collider: {size: 'size', enabled: 'solid'}` (declared vec3 and bit fields).
+Move uses `ctx.world.sweep/support/overlaps`; `ctx.map` exposes these same queries
+for existing movement code. Keep build/damage/door logic in entity handlers.
+Never copy collision lists into player motion or implement a second replay loop.
+Test visible prediction at 300 ms with loss, rejoin and saved-room restore.
+The installed toolkit's `guides/game/` is the version-matched source for this guide.