virtualmatter 0.6.0 → 0.6.2

package/README.md

@@ -38,9 +38,11 @@ npx virtualmatter pull https://make.virtualmatter.ai/edit/my-world-<framing-id>
 ```
 
 While `sync` runs, saving a Lua script in your editor deploys it - scripts
-hot-reload in the engine. If someone edits the same file in the live session,
-your copy stays put and the remote version lands next to it as
-`<name>.remote-conflict` for you to merge.
+hot-reload in the engine. Sync never overwrites work you have not synced: if
+a file changed both here and in the live session (while sync ran, or while it
+was stopped), your copy stays put and the remote version lands next to it as
+`<name>.remote-conflict`. Merge, save, and it pushes. Edits made while sync
+was stopped go out when it starts again.
 
 `make`, `pull` and `sync` print the world's editor link ending in `?chat=closed`.
 Open it in any browser to watch changes land live - no install needed.
@@ -56,10 +58,12 @@ Poke at the running engine from another terminal:
 
 ```bash
 npx virtualmatter run-lua --code "return Server.GetInfo()"
+npx virtualmatter run-lua --target client --code "return Client:GetID()"   # UI, input, camera
 npx virtualmatter errors
 npx virtualmatter screenshot -o shot.png                  # default overview
 npx virtualmatter screenshot --target "Player" -o p.png   # frame one object
 npx virtualmatter screenshot --at 0,30,40 --rot 0,-35,0    # exact camera
+npx virtualmatter screenshot --client 4 -o ui.png          # what client 4 sees, UI included
                                           # --rot is yaw,pitch,roll
 ```
 
@@ -117,9 +121,9 @@ deploying it.
 | `pull [target] [dir]` | Mirror a world's file tree. `target` is any link to the world (or your website) or a framing id, and always resolves to the world's editor; omitted, it uses this folder's world or your only one. |
 | `sync [dir]` | Watch + two-way sync with the live session. Ctrl-C to stop. |
 | `open [target]` (`client`) | Optional: open a world in the native desktop client, downloading and signing it in on first use. `--install-only`, `--print` (just the download URL), `--force`. |
-| `run-lua [dir] --code "<lua>" [--target server\|client]` | Execute Lua in the running engine. |
+| `run-lua [dir] --code "<lua>" [--target server\|client] [--client <id>]` | Execute Lua in the running engine. A client run uses the only connected client unless `--client` names one (list them with `--code "return Server:GetClients()"`). |
 | `errors [dir]` | Recent engine errors. |
-| `screenshot [dir] [-o out.png]` | Capture the engine's current view. |
+| `screenshot [dir] [-o out.png] [--client <id>]` | Capture the engine's view; `--client` captures through a connected client, UI included. |
 | `mcp [dir] [--framing <id>]` | Run the stdio MCP server. |
 | `login` / `logout` / `whoami` | Device-code sign-in; every other command signs you in automatically when needed. Tokens live in `~/.config/virtualmatter/credentials.json` (mode 0600) and refresh automatically. |
 
@@ -131,7 +135,9 @@ deploying it.
   an error, for scripts that must never block on a browser.
 - The native client is unpacked under `~/.config/virtualmatter/client/<build>`
   (override with `VIRTUALMATTER_CLIENT_DIR`); each engine build gets its own
-  folder, so a newer build never overwrites the one you are running.
+  folder, so a newer build never overwrites the one you are running. Once a
+  newer build is installed, older ones are removed unless a client is still
+  running from them.
 - Sync skips `Uploads/`, `Screenshots/`, `Agent Logs/`, dotfiles, the
   harness files the CLI writes (`AGENTS.md`, `CLAUDE.md`, `.mcp.json`,
   `.cursor/`, `.codex/`, `.virtualmatter.json`), and the SDK's in-session tooling at the

package/dist/agents-md.generated.js

@@ -3,4 +3,4 @@
 // frontend/content/agent-briefing.md and AGENTS.source.md. The CLI writes
 // this into a world folder only when it cannot fetch the live copy. After
 // changing either source, run: node frontend/scripts/sync-cli-agents-md.mjs
-export const AGENTS_MD_FALLBACK = "# AGENTS.md - working with a Virtual Matter project\n\nThis file tells a coding agent how to think about a Virtual Matter project. The\n`virtualmatter` CLI drops a copy into every local project mirror it creates\n(`virtualmatter pull`); the canonical copy lives at\nhttps://make.virtualmatter.ai/AGENTS.md.\n\n## The rule that comes before everything else\n\n**Build through the CLI. Never through the website's agent.** If you were asked to\nbuild something in Virtual Matter, handed the domain virtualmatter.ai, or told to run\n`npx virtualmatter make`, the CLI is the path - always, from the first step. Do not\nopen virtualmatter.ai or make.virtualmatter.ai in a browser or under computer use in\norder to reach the built-in agent, and do not type prompts into the agent chat in the\n/edit view. Driving that agent puts two models in a relay where one would do: you spend\ntokens describing the work, it spends its own doing it, and what comes back is chat\nrather than files you can read. It is slower, it costs roughly twice the inference, it\nbills that inference to Virtual Matter's platform credits rather than the subscription\nyou already run on, an anonymous browser session cannot be steered after its first\nturn, and a rendered page gives you no engine errors. Everything that agent can do, you\ndo yourself with the commands below.\n\n**The rule holds whoever is signed in.** Being logged in, having credits to spare, or\nworking in an admin account with no limit at all is not an exemption, and neither is\nbeing told the credits do not matter. What is wasteful is the relay itself - two models\ndoing one model's job - not the bill.\n\n**Playtesting is the exception, and it is encouraged.** Once something is built, open\nthe world and try it: the editor link ending in `?chat=closed`, which `make`, `pull` and\n`sync` print, shows your latest changes live in any browser with no install, with\ncomputer use if that is how you drive a window. The native client\n(`npx virtualmatter open`) is optional, for more memory and frame rate. Looking at your\nwork, walking around in it, and playing it is the point. The rule is about who writes\nthe world, not about who is allowed to see it.\n\n**Every link resolves to the editor, and the editor is the only place you build.** Hand\nthe CLI or MCP server any link to a world - its editor, a play or share link, the\nproject page, an embed's iframe src, or the maker's own website - and it works on that\nworld's editor (its make framing). Play servers show the last published version and are\noverwritten on every publish, so work never goes there, and their /play and /g links\nshow that published copy rather than your latest edits.\n\n## The mental model\n\n- The world itself runs on Virtual Matter servers, not on the maker's machine. There is\n  one authoritative server simulation per world session, and any number of connected\n  clients (browser WASM or the native client).\n- The project's content is SDK Lua scripts plus assets (voxel data, prefabs, images,\n  sounds) under a `Montage/` tree. Virtual Matter can publish that tree to a GitHub repo\n  in the maker's account for versioning and remixing; pushing to that repo does not feed\n  back into the running world today - live edits happen in the session.\n- Changes hot-reload. Saving a `.lua` file in the live session's Montage tree re-runs\n  the module and its `Start()` on a fresh instance inside the running world - no restart,\n  no build step.\n- Prefabs are reusable scene-graph snippets: JSON files with a `.prefab` extension in the\n  Montage folder, instantiated at runtime via `Server:InsertPrefab(asset)`.\n- There is no local runtime - the world cannot run on the maker's machine. The\n  `virtualmatter` CLI (npm) is how you reach it from a local harness, and it needs no\n  setup: the first command that needs an account signs you in with a device code.\n  `npx virtualmatter make \"My world\"` makes a world and mirrors its Montage tree\n  into `./my-world`; `npx virtualmatter pull <any Virtual Matter link>` mirrors an\n  existing one (/edit, /play, /g, /p, /projects links all work, with or without a\n  readable slug); `npx virtualmatter list` shows your worlds; `npx virtualmatter sync`\n  live-pushes saves into the running session (which hot-reloads them);\n  `npx virtualmatter run-lua` / `errors` / `screenshot` drive the engine;\n  `npx virtualmatter open` optionally opens the world in the native desktop client,\n  downloaded and signed in on first use; and `npx virtualmatter mcp` serves\n  all of it over MCP. A mirrored folder carries `.mcp.json` and `.cursor/mcp.json`\n  (so Claude Code and Cursor register the MCP server on their own), this file, and a\n  `CLAUDE.md` that imports it. Folders from virtualmatter 0.5.0 on also carry\n  `.codex/config.toml`, which Codex loads once you trust the folder; with an older\n  CLI, or if Codex does not list the server, register it once with\n  `codex mcp add virtualmatter -- npx -y virtualmatter mcp`. In Claude Code outside a\n  mirrored folder, use `claude mcp add virtualmatter -- npx -y virtualmatter mcp`. The\n  server works before a world\n  is selected (`list_projects`, `create_project`, `select_project`), then exposes\n  `list_files`, `read_file`, `write_file`, `run_lua`, `get_engine_errors`,\n  `capture_screenshot`, `open_native_client`, and `world_info`.\n- Work through the CLI, not the website - see the rule above. Prompting the built-in\n  agent to do your building is the one thing to avoid; opening the world to play it is\n  not.\n- Seeing your work: `virtualmatter screenshot` shoots a default overview of the world\n  origin, `--target <object>` frames one object by name or id, and `--at x,y,z --rot\n  yaw,pitch,roll` places the camera exactly. Y is up and -Z is forward, and the\n  rotation really is yaw first: yaw 0 faces -Z, pitch -90 looks straight down, pitch 0\n  is the horizon. The MCP `capture_screenshot`\n  tool takes the same arguments. Verify a change with a screenshot plus `errors` rather\n  than assuming a write worked.\n- The mirrored folder's AGENTS.md is this guide followed by the engine SDK's own agent guide\n  (the AGENTS.md that lives in every Montage tree and inside the desktop client's\n  Data/Sdk/Montage/). The engine guide assumes an in-session agent driving the engine\n  through `atomo`; the merged file maps each `atomo` step to the CLI or MCP equivalent, and\n  the `Skills/*.md` references it points at are in the folder. The SDK's own tooling\n  (`atomo`, `vm_auth.py`, the agent-log hooks) is not mirrored: it only works inside a\n  session. Sandboxed agents need network access for every CLI command.\n\n## Reference\n\nThe same facts as terse lists, for quick lookup.\n\n### Project model\n- A project (\"montage\") is one voxel world hosted with Virtual Matter.\n- A project has framings: \"make\" framings (editing sessions) and \"play\"\n  framings (public play sessions). A framing is a running session slot\n  on a voxel host.\n- Project content = SDK Lua scripts + assets under a Montage/ tree.\n  Edits made in the live session hot-reload into the running world.\n  The tree can be published to a maker-owned GitHub repo.\n\n### URL shapes (make.virtualmatter.ai)\n- /new                 builder for people: create a world from a prompt\n                       (also at https://virtualmatter.ai/); coding agents\n                       use npx virtualmatter make instead\n- /edit/<framing-id>   maker session: live world + agent chat. The chat is\n                       for people; a coding agent builds with the CLI and\n                       never prompts it\n                       (also /edit/<slug>-<framing-id>; the CLI accepts both)\n- /play/<framing-id>   play session for a specific framing\n- /g/<id>              share URL resolver: 302s to a live session\n\n### APIs (unauthenticated)\n- GET https://make.virtualmatter.ai/api/v1/public/native-clients\n  JSON: { iteration, clients: [{ platform, kind, url, filename,\n  file_size, branch, commit, match }] } - per-platform native client\n  installers (kind \"download\") or store links (kind \"store\", iOS).\n\n### CLI + MCP (npm package \"virtualmatter\", Node >= 20)\n- npx virtualmatter make \"<name>\"     make a world, mirror it into ./<slug>\n- npx virtualmatter pull <link>       mirror an existing world (any link shape)\n- npx virtualmatter list              your worlds with framing ids + URLs\n- npx virtualmatter sync              live-push saves into the running world\n- npx virtualmatter open              optional: open it in the native client\n- npx virtualmatter mcp               stdio MCP server (list_projects,\n  create_project, select_project, list_files, read_file, write_file,\n  run_lua, get_engine_errors, capture_screenshot, open_native_client,\n  world_info)\n- Sign-in happens on first use (device code); no separate login step.\n- These commands are the whole build path. Never prompt the built-in\n  agent on the site to do the work; a browser or the native client is\n  for playtesting what you built.\n- Any link to a world (editor, play or share link, project page, embed,\n  or the maker's own website) resolves to its editor, the only place\n  the CLI and MCP server work. Play servers show the last published\n  version and are overwritten on publish.\n- Watch changes land live at the editor link ending in ?chat=closed,\n  in any browser, no install. The native client is optional.\n- A mirrored folder carries .mcp.json, .cursor/mcp.json, AGENTS.md and\n  CLAUDE.md, so Claude Code and Cursor register the server on their own.\n- Codex: folders from 0.5.0 on carry .codex/config.toml, loaded once the\n  folder is trusted; otherwise register the server once:\n  codex mcp add virtualmatter -- npx -y virtualmatter mcp\n\n## SDK Lua cheat sheet\n\nThe scripting language is Lua 5.4, sandboxed: `os`, `io`, `require`, `package`,\n`dofile`, `loadfile`, `loadstring` are nil. `math`, `string`, `table`, `coroutine`\nremain. No `os.time` - use `Time.time` (sim time), `Time.frame`, or\n`AE:GetDebugTime()` (wall clock).\n\n### Script shape\n\nEvery persistent behavior is a `.lua` file in the Montage tree returning a `self` table:\n\n```lua\nlocal self = {}\nfunction self:Start() end\nfunction self:Update(deltaTime) end\nreturn self\n```\n\nAttach to an object with `obj:AddScript(\"My Folder/Example.lua\", sync)` - the path is\nrelative to the Montage root; `sync = true` replicates the script to clients.\n`obj:FindScript(\"Example\")` returns the live instance.\n\n### Server / client split\n\nThe same script runs on the server and (when synced) on every client. Branch with\n`self.onServer` / `self.onClient`:\n\n```lua\nfunction self:Update(dt)\n    if self.onClient then return end  -- voxel edits are server-only\n    -- authoritative logic here\nend\n```\n\nNothing replicates automatically: set `syncToClients = true` on the script or\nVoxelData component, and use `util:makeNetworkedTable(self, { hp = 100 })` for\nproperties that should sync (server writes, clients read, deltas only).\n`obj.pos` / `obj.rot` do not auto-sync - replicate them yourself.\n\n### RPC\n\n```lua\nself:RPC(\"serverDoSomething\", pos, dir)   -- on a client: goes to the server\nfunction self:serverDoSomething(pos, dir, clientID)  -- clientID auto-appended\n    assert(self.onServer)\nend\n```\n\nOn the server, `self:RPC(...)` fans out to all clients. Reliable, FIFO per direction.\nRequires `self.component.syncToClients = true`.\n\n### Scene and objects (server)\n\n```lua\nlocal ob = Scene:CreateObject(\"Name\")\nob.save = true\nob:AddScript(\"Path/Script.lua\")\nScene:GetObjectByName(\"Name\")\nScene:CloneObject(ob)                 -- prefer over rebuilding\nob.active = false                     -- prefer over destroy\nob:AddTag(\"Enemy\"); FindObjectsWithTag(\"Enemy\")  -- tags are runtime-only state\n```\n\n### Voxel editing (server only, async)\n\n```lua\nVox:Add(Sphere(pos, 2)):Color(1, 0, 0):Run()\nVox:Add(Box(Vec3(0, -1, 0), Vec3(20, 2, 20))):ForceStatic():Run()\n```\n\nShapes: `Box(center, fullSize)`, `Sphere(center, r)`, `Capsule(p1, p2, r)`,\n`Cylinder(p1, p2, r1[, r2])`. `Run()` is async - chain `:OnFinished(fn)` before\n`:Run()` to read post-commit state. Big edits stall the frame for every client;\nkeep in-game edits small and infrequent.\n\n### Input (event-driven, client input reaches the server)\n\n```lua\nself.component.syncToClients = true\nevents.keyDown.addListener(self, function(key, from) self.keys[key] = true end)\nevents.keyUp.addListener(self, function(key, from) self.keys[key] = false end)\n```\n\nPlayer-driven movement must be client-predicted - never gate the player's own\nfeedback on the server round-trip.\n\n### Physics\n\n```lua\nlocal rb = obj:AddComponent(\"RigidBody\")\nrb:AddImpulse(Vec3(0, 50, 0), obj.pos)\nrb.velocity; rb.mass; rb.gravityScale\n```\n\n### Time and diagnostics\n\n```lua\nTime.dt; Time.time; Time.frame; Time.timeScale\nAE:GetLogValue(\"Raycasts\")        -- engine counters, e.g. raycasts this frame\nAE:GetAssets()                    -- list all assets (APIs take Assets, not paths)\n```\n\n### UI (client-side HUD)\n\nBuild screen UI with the MUI builder: `UI:AddPanel|AddButton|AddLabel|AddSlider|...`\nchained with `:Set{...}`; flexbox-like row-wrap layout.\n\n## Conventions\n\n- Coordinates: Y is up, -Z is forward, X is right.\n- Script files are named in capital case with spaces (`Character Controller.lua`).\n- Check whether a script is already attached before adding it - duplicates run twice.\n- The server is for authority (world edits, spawns, state); clients are for feel\n  (prediction, FX, UI).\n\n## Embed or build a world for an existing website\n\nFor a shared project link, fetch `/api/v1/public/embed?target=<encoded-link>`\nand follow `/embed-guide.md`. Use the returned canonical player URL, not the\nmaker's external website URL. Keep the existing website and its design.\n\nFor account discovery or prompt-based creation, connect the hosted MCP at\n`https://make.virtualmatter.ai/api/v1/mcp` using OAuth. Users can sign up in\nthe connection flow. Tools: `list_projects`, `get_embed`, `create_project`\n(with a prompt and stable request_id), `get_build_status`. VM's agent builds\nusing VM credits. Review and share the private world before embedding.\nThe local CLI exposes `embed`, `build --prompt --request-id`, and `build-status`.\n\n## Local conversation history\n\nAfter pulling a project, run `virtualmatter agent-logs setup` once to enable\nfuture chat history capture for local harnesses. It adds Codex, Claude Code,\nCursor, and (when installed) Hermes hooks without replacing existing hooks.\nKeep `virtualmatter sync` or `virtualmatter agent-logs watch` running for retry\nand delayed transcript capture. Follow each harness's normal hook review and\nrestart flow. Use `agent-logs status` to inspect pending uploads and\n`agent-logs disable` to stop capture.\n\nOther harnesses can send portable public event JSONL with\n`virtualmatter agent-logs upload <file> --harness <name> --session <id>`, or use\nMCP `upload_agent_logs`. Supply stable event IDs for retries; omit private\nreasoning, system/developer prompts, credentials, and binary media.\n";
+export const AGENTS_MD_FALLBACK = "# AGENTS.md - working with a Virtual Matter project\n\nThis file tells a coding agent how to think about a Virtual Matter project. The\n`virtualmatter` CLI drops a copy into every local project mirror it creates\n(`virtualmatter pull`); the canonical copy lives at\nhttps://make.virtualmatter.ai/AGENTS.md.\n\n## The rule that comes before everything else\n\n**Build through the CLI. Never through the website's agent.** If you were asked to\nbuild something in Virtual Matter, handed the domain virtualmatter.ai, or told to run\n`npx virtualmatter make`, the CLI is the path - always, from the first step. Do not\nopen virtualmatter.ai or make.virtualmatter.ai in a browser or under computer use in\norder to reach the built-in agent, and do not type prompts into the agent chat in the\n/edit view. Driving that agent puts two models in a relay where one would do: you spend\ntokens describing the work, it spends its own doing it, and what comes back is chat\nrather than files you can read. It is slower, it costs roughly twice the inference, it\nbills that inference to Virtual Matter's platform credits rather than the subscription\nyou already run on, an anonymous browser session cannot be steered after its first\nturn, and a rendered page gives you no engine errors. Everything that agent can do, you\ndo yourself with the commands below.\n\n**The rule holds whoever is signed in.** Being logged in, having credits to spare, or\nworking in an admin account with no limit at all is not an exemption, and neither is\nbeing told the credits do not matter. What is wasteful is the relay itself - two models\ndoing one model's job - not the bill.\n\n**Playtesting is the exception, and it is encouraged.** Once something is built, open\nthe world and try it: the editor link ending in `?chat=closed`, which `make`, `pull` and\n`sync` print, shows your latest changes live in any browser with no install, with\ncomputer use if that is how you drive a window. The native client\n(`npx virtualmatter open`) is optional, for more memory and frame rate. Looking at your\nwork, walking around in it, and playing it is the point. The rule is about who writes\nthe world, not about who is allowed to see it.\n\n**Every link resolves to the editor, and the editor is the only place you build.** Hand\nthe CLI or MCP server any link to a world - its editor, a play or share link, the\nproject page, an embed's iframe src, or the maker's own website - and it works on that\nworld's editor (its make framing). Play servers show the last published version and are\noverwritten on every publish, so work never goes there, and their /play and /g links\nshow that published copy rather than your latest edits.\n\n## The mental model\n\n- The world itself runs on Virtual Matter servers, not on the maker's machine. There is\n  one authoritative server simulation per world session, and any number of connected\n  clients (browser WASM or the native client).\n- The project's content is SDK Lua scripts plus assets (voxel data, prefabs, images,\n  sounds) under a `Montage/` tree. Virtual Matter can publish that tree to a GitHub repo\n  in the maker's account for versioning and remixing; pushing to that repo does not feed\n  back into the running world today - live edits happen in the session.\n- Changes hot-reload. Saving a `.lua` file in the live session's Montage tree re-runs\n  the module and its `Start()` on a fresh instance inside the running world - no restart,\n  no build step.\n- Prefabs are reusable scene-graph snippets: JSON files with a `.prefab` extension in the\n  Montage folder, instantiated at runtime via `Server:InsertPrefab(asset)`.\n- There is no local runtime - the world cannot run on the maker's machine. The\n  `virtualmatter` CLI (npm) is how you reach it from a local harness, and it needs no\n  setup: the first command that needs an account signs you in with a device code.\n  `npx virtualmatter make \"My world\"` makes a world and mirrors its Montage tree\n  into `./my-world`; `npx virtualmatter pull <any Virtual Matter link>` mirrors an\n  existing one (/edit, /play, /g, /p, /projects links all work, with or without a\n  readable slug); `npx virtualmatter list` shows your worlds; `npx virtualmatter sync`\n  live-pushes saves into the running session (which hot-reloads them);\n  `npx virtualmatter run-lua` / `errors` / `screenshot` drive the engine;\n  `npx virtualmatter open` optionally opens the world in the native desktop client,\n  downloaded and signed in on first use; and `npx virtualmatter mcp` serves\n  all of it over MCP. A mirrored folder carries `.mcp.json` and `.cursor/mcp.json`\n  (so Claude Code and Cursor register the MCP server on their own), this file, and a\n  `CLAUDE.md` that imports it. Folders from virtualmatter 0.5.0 on also carry\n  `.codex/config.toml`, which Codex loads once you trust the folder; with an older\n  CLI, or if Codex does not list the server, register it once with\n  `codex mcp add virtualmatter -- npx -y virtualmatter mcp`. In Claude Code outside a\n  mirrored folder, use `claude mcp add virtualmatter -- npx -y virtualmatter mcp`. The\n  server works before a world\n  is selected (`list_projects`, `create_project`, `select_project`), then exposes\n  `list_files`, `read_file`, `write_file`, `run_lua`, `get_engine_errors`,\n  `capture_screenshot`, `open_native_client`, and `world_info`.\n- Work through the CLI, not the website - see the rule above. Prompting the built-in\n  agent to do your building is the one thing to avoid; opening the world to play it is\n  not.\n- Seeing your work: `virtualmatter screenshot` shoots a default overview of the world\n  origin, `--target <object>` frames one object by name or id, and `--at x,y,z --rot\n  yaw,pitch,roll` places the camera exactly. Y is up and -Z is forward, and the\n  rotation really is yaw first: yaw 0 faces -Z, pitch -90 looks straight down, pitch 0\n  is the horizon. The MCP `capture_screenshot`\n  tool takes the same arguments. Verify a change with a screenshot plus `errors` rather\n  than assuming a write worked.\n- The mirrored folder's AGENTS.md is this guide followed by the engine SDK's own agent guide\n  (the AGENTS.md that lives in every Montage tree and inside the desktop client's\n  Data/Sdk/Montage/). The engine guide assumes an in-session agent driving the engine\n  through `atomo`; the merged file maps each `atomo` step to the CLI or MCP equivalent, and\n  the `Skills/*.md` references it points at are in the folder. The SDK's own tooling\n  (`atomo`, `vm_auth.py`, the agent-log hooks) is not mirrored: it only works inside a\n  session. Sandboxed agents need network access for every CLI command.\n\n## Reference\n\nThe same facts as terse lists, for quick lookup.\n\n### Project model\n- A project (\"montage\") is one voxel world hosted with Virtual Matter.\n- A project has framings: \"make\" framings (editing sessions) and \"play\"\n  framings (public play sessions). A framing is a running session slot\n  on a voxel host.\n- Project content = SDK Lua scripts + assets under a Montage/ tree.\n  Edits made in the live session hot-reload into the running world.\n  The tree can be published to a maker-owned GitHub repo.\n\n### URL shapes (make.virtualmatter.ai)\n- /new                 builder for people: create a world from a prompt\n                       (also at https://virtualmatter.ai/); coding agents\n                       use npx virtualmatter make instead\n- /edit/<framing-id>   maker session: live world + agent chat. The chat is\n                       for people; a coding agent builds with the CLI and\n                       never prompts it\n                       (also /edit/<slug>-<framing-id>; the CLI accepts both)\n- /play/<framing-id>   play session for a specific framing\n- /g/<id>              share URL resolver: 302s to a live session\n\n### APIs (unauthenticated)\n- GET https://make.virtualmatter.ai/api/v1/public/native-clients\n  JSON: { iteration, clients: [{ platform, kind, variant, url, filename,\n  file_size, branch, commit, match }] } - per-platform native client\n  installers (kind \"download\") or store links (kind \"store\", iOS).\n  Windows and Linux list two downloads each: variant \"installer\" /\n  \"flatpak\" for people, and \"portable\" / \"tarball\", the file tree the\n  CLI installs.\n\n### CLI + MCP (npm package \"virtualmatter\", Node >= 20)\n- npx virtualmatter make \"<name>\"     make a world, mirror it into ./<slug>\n- npx virtualmatter pull <link>       mirror an existing world (any link shape)\n- npx virtualmatter list              your worlds with framing ids + URLs\n- npx virtualmatter sync              live-push saves into the running world\n- npx virtualmatter open              optional: open it in the native client\n- npx virtualmatter mcp               stdio MCP server (list_projects,\n  create_project, select_project, list_files, read_file, write_file,\n  run_lua, get_engine_errors, capture_screenshot, open_native_client,\n  world_info)\n- Sign-in happens on first use (device code); no separate login step.\n- These commands are the whole build path. Never prompt the built-in\n  agent on the site to do the work; a browser or the native client is\n  for playtesting what you built.\n- Any link to a world (editor, play or share link, project page, embed,\n  or the maker's own website) resolves to its editor, the only place\n  the CLI and MCP server work. Play servers show the last published\n  version and are overwritten on publish.\n- Watch changes land live at the editor link ending in ?chat=closed,\n  in any browser, no install. The native client is optional.\n- A mirrored folder carries .mcp.json, .cursor/mcp.json, AGENTS.md and\n  CLAUDE.md, so Claude Code and Cursor register the server on their own.\n- Codex: folders from 0.5.0 on carry .codex/config.toml, loaded once the\n  folder is trusted; otherwise register the server once:\n  codex mcp add virtualmatter -- npx -y virtualmatter mcp\n\n## SDK Lua cheat sheet\n\nThe scripting language is Lua 5.4, sandboxed: `os`, `io`, `require`, `package`,\n`dofile`, `loadfile`, `loadstring` are nil. `math`, `string`, `table`, `coroutine`\nremain. No `os.time` - use `Time.time` (sim time), `Time.frame`, or\n`AE:GetDebugTime()` (wall clock).\n\n### Script shape\n\nEvery persistent behavior is a `.lua` file in the Montage tree returning a `self` table:\n\n```lua\nlocal self = {}\nfunction self:Start() end\nfunction self:Update(deltaTime) end\nreturn self\n```\n\nAttach to an object with `obj:AddScript(\"My Folder/Example.lua\", sync)` - the path is\nrelative to the Montage root; `sync = true` replicates the script to clients.\n`obj:FindScript(\"Example\")` returns the live instance.\n\n### Server / client split\n\nThe same script runs on the server and (when synced) on every client. Branch with\n`self.onServer` / `self.onClient`:\n\n```lua\nfunction self:Update(dt)\n    if self.onClient then return end  -- voxel edits are server-only\n    -- authoritative logic here\nend\n```\n\nNothing replicates automatically: set `syncToClients = true` on the script or\nVoxelData component, and use `util:makeNetworkedTable(self, { hp = 100 })` for\nproperties that should sync (server writes, clients read, deltas only).\n`obj.pos` / `obj.rot` do not auto-sync - replicate them yourself.\n\n### RPC\n\n```lua\nself:RPC(\"serverDoSomething\", pos, dir)   -- on a client: goes to the server\nfunction self:serverDoSomething(pos, dir, clientID)  -- clientID auto-appended\n    assert(self.onServer)\nend\n```\n\nOn the server, `self:RPC(...)` fans out to all clients. Reliable, FIFO per direction.\nRequires `self.component.syncToClients = true`.\n\n### Scene and objects (server)\n\n```lua\nlocal ob = Scene:CreateObject(\"Name\")\nob.save = true\nob:AddScript(\"Path/Script.lua\")\nScene:GetObjectByName(\"Name\")\nScene:CloneObject(ob)                 -- prefer over rebuilding\nob.active = false                     -- prefer over destroy\nob:AddTag(\"Enemy\"); FindObjectsWithTag(\"Enemy\")  -- tags are runtime-only state\n```\n\n### Voxel editing (server only, async)\n\n```lua\nVox:Add(Sphere(pos, 2)):Color(1, 0, 0):Run()\nVox:Add(Box(Vec3(0, -1, 0), Vec3(20, 2, 20))):ForceStatic():Run()\n```\n\nShapes: `Box(center, fullSize)`, `Sphere(center, r)`, `Capsule(p1, p2, r)`,\n`Cylinder(p1, p2, r1[, r2])`. `Run()` is async - chain `:OnFinished(fn)` before\n`:Run()` to read post-commit state. Big edits stall the frame for every client;\nkeep in-game edits small and infrequent.\n\n### Input (event-driven, client input reaches the server)\n\n```lua\nself.component.syncToClients = true\nevents.keyDown.addListener(self, function(key, from) self.keys[key] = true end)\nevents.keyUp.addListener(self, function(key, from) self.keys[key] = false end)\n```\n\nPlayer-driven movement must be client-predicted - never gate the player's own\nfeedback on the server round-trip.\n\n### Physics\n\n```lua\nlocal rb = obj:AddComponent(\"RigidBody\")\nrb:AddImpulse(Vec3(0, 50, 0), obj.pos)\nrb.velocity; rb.mass; rb.gravityScale\n```\n\n### Time and diagnostics\n\n```lua\nTime.dt; Time.time; Time.frame; Time.timeScale\nAE:GetLogValue(\"Raycasts\")        -- engine counters, e.g. raycasts this frame\nAE:GetAssets()                    -- list all assets (APIs take Assets, not paths)\n```\n\n### UI (client-side HUD)\n\nBuild screen UI with the MUI builder: `UI:AddPanel|AddButton|AddLabel|AddSlider|...`\nchained with `:Set{...}`; flexbox-like row-wrap layout.\n\n## Conventions\n\n- Coordinates: Y is up, -Z is forward, X is right.\n- Script files are named in capital case with spaces (`Character Controller.lua`).\n- Check whether a script is already attached before adding it - duplicates run twice.\n- The server is for authority (world edits, spawns, state); clients are for feel\n  (prediction, FX, UI).\n\n## Embed or build a world for an existing website\n\nFor a shared project link, fetch `/api/v1/public/embed?target=<encoded-link>`\nand follow `/embed-guide.md`. Use the returned canonical player URL, not the\nmaker's external website URL. Keep the existing website and its design.\n\nFor account discovery or prompt-based creation, connect the hosted MCP at\n`https://make.virtualmatter.ai/api/v1/mcp` using OAuth. Users can sign up in\nthe connection flow. Tools: `list_projects`, `get_embed`, `create_project`\n(with a prompt and stable request_id), `get_build_status`. VM's agent builds\nusing VM credits. Review and share the private world before embedding.\nThe local CLI exposes `embed`, `build --prompt --request-id`, and `build-status`.\n\n## Local conversation history\n\nCapturing this harness's conversation into the world's Agent Logs is the maker's\ndecision, not yours. Do not run `virtualmatter agent-logs setup`, and do not upload\nlogs with `agent-logs upload` or MCP `upload_agent_logs`, unless the maker asks for it\nin their own words. `virtualmatter agent-logs status` shows whether capture is on;\n`virtualmatter agent-logs disable` turns it off.\n";

package/dist/client.js

@@ -5,7 +5,8 @@
  *
  * Builds are unpacked under <configDir>/client/<dir_uid>/ so re-running
  * `open` is instant, and a newer build lands next to the old one instead
- * of over it. Archives are removed after extraction.
+ * of over it. Archives are removed after extraction, and once a new build
+ * is in place the older ones are removed unless a client is running from them.
  */
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -21,9 +22,23 @@ export function detectPlatform(p = process.platform) {
         return "windows";
     return "linux";
 }
-/** The build the catalog offers for a platform, or null when there is none. */
+/**
+ * The build the CLI can install for a platform, or null when there is none.
+ *
+ * Linux and Windows list two downloads each: the one for people (the Flatpak,
+ * the installer) and a plain file tree (the tarball, the portable zip). The
+ * CLI unpacks and runs a file tree, which a Flatpak bundle or a Setup.exe is
+ * not, so it always takes the file tree - by `variant`, and by file name for a
+ * platform that predates the field.
+ */
 export function pickBuild(clients, platform) {
-    return clients.find((c) => c.platform.toLowerCase() === platform && c.kind === "download") ?? null;
+    return (clients.find((c) => c.platform.toLowerCase() === platform && c.kind === "download" && !isHumanOnlyDownload(c)) ?? null);
+}
+function isHumanOnlyDownload(client) {
+    if (client.variant === "flatpak" || client.variant === "installer")
+        return true;
+    const name = (client.filename ?? client.url).toLowerCase();
+    return name.endsWith(".flatpak") || name.endsWith(".exe") || name.endsWith(".msi");
 }
 /** A stable per-build install directory name derived from the download path. */
 export function buildKey(client) {
@@ -116,10 +131,86 @@ async function download(url, dest, onProgress, fetchFn = fetch) {
     }
     fs.renameSync(tmp, dest);
 }
+/**
+ * The path of `lsregister`, the tool that edits macOS's database of known apps.
+ * Not on any PATH - it lives inside the LaunchServices framework.
+ */
+const LSREGISTER = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
+/**
+ * Take this cached client OUT of macOS's app database.
+ *
+ * The cache holds a real .app bundle, and macOS registers every bundle it
+ * sees. Every copy carries the same bundle id, and the "which app opens
+ * virtualmatter:// links" preference is stored per bundle ID, not per path -
+ * so macOS picks among the copies by its own rules, and a cached build from
+ * last week can win over the one in /Applications. That is not hypothetical:
+ * a world link opened a nine-day-old cached client, which then refused to
+ * connect to its own world because the client predated a compatibility fix on
+ * that same release branch.
+ *
+ * The CLI launches this copy by path, so it never needs to be registered.
+ * Unregistering it leaves the user's installed app as the only candidate.
+ * Best-effort by design: this is tidiness, not correctness, and any failure
+ * (another OS, a future layout, a locked database) must not break a launch.
+ */
+export function dropFromLaunchServices(appPath, platform = detectPlatform(), runner = spawnSync) {
+    if (platform !== "macos" || !appPath.endsWith(".app"))
+        return;
+    try {
+        runner(LSREGISTER, ["-u", appPath], { stdio: "ignore" });
+    }
+    catch {
+        /* tidiness only */
+    }
+}
+function run(cmd, args) {
+    const res = spawnSync(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+    if (res.error)
+        throw new Error(`Could not run ${cmd}: ${res.error.message}`);
+    if (res.status !== 0) {
+        throw new Error(`${cmd} failed (${res.status}): ${res.stderr?.toString().trim()}`);
+    }
+}
+/**
+ * A macOS disk image: mount it read-only out of sight, copy every top-level
+ * .app out with ditto (which keeps the bundle's symlinks and signature), and
+ * always detach. The image's other entries - the /Applications shortcut, the
+ * window background - are for people dragging the app across by hand.
+ */
+function extractDmg(archive, dest) {
+    const mount = fs.mkdtempSync(path.join(path.dirname(dest), ".mount-"));
+    try {
+        run("hdiutil", ["attach", archive, "-readonly", "-nobrowse", "-noautoopen", "-noverify", "-mountpoint", mount]);
+        try {
+            const apps = fs.readdirSync(mount).filter((n) => n.endsWith(".app"));
+            if (apps.length === 0)
+                throw new Error(`${path.basename(archive)} holds no .app bundle.`);
+            for (const app of apps)
+                run("ditto", [path.join(mount, app), path.join(dest, app)]);
+        }
+        finally {
+            const res = spawnSync("hdiutil", ["detach", mount, "-quiet"], { stdio: "ignore" });
+            if (res.status !== 0)
+                spawnSync("hdiutil", ["detach", mount, "-force", "-quiet"], { stdio: "ignore" });
+        }
+    }
+    finally {
+        try {
+            fs.rmdirSync(mount);
+        }
+        catch {
+            /* still attached: removing it would reach into the image */
+        }
+    }
+}
 /** Unpack with the OS's own tools: ditto keeps bundle symlinks + bits on macOS; bsdtar handles zip + tgz elsewhere. */
 export function extractArchive(archive, dest, platform) {
-    fs.mkdirSync(dest, { recursive: true });
     const lower = archive.toLowerCase();
+    if (platform === "macos" && lower.endsWith(".dmg")) {
+        fs.mkdirSync(dest, { recursive: true });
+        extractDmg(archive, dest);
+        return;
+    }
     let cmd;
     let args;
     if (platform === "macos" && lower.endsWith(".zip")) {
@@ -137,12 +228,65 @@ export function extractArchive(archive, dest, platform) {
     else {
         throw new Error(`Don't know how to unpack ${path.basename(archive)}.`);
     }
-    const res = spawnSync(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
-    if (res.error)
-        throw new Error(`Could not run ${cmd}: ${res.error.message}`);
-    if (res.status !== 0) {
-        throw new Error(`${cmd} failed (${res.status}): ${res.stderr?.toString().trim()}`);
+    fs.mkdirSync(dest, { recursive: true });
+    run(cmd, args);
+}
+const ARCHIVE_RE = /\.(zip|tgz|tar\.gz|tar\.xz|tar\.bz2|tar|dmg)(\.part)?$/i;
+/** A partial download younger than this may belong to another `open` still running. */
+const PART_GRACE_MS = 60 * 60 * 1000;
+/** Whether a running process was started from inside `dir`. */
+function runningFrom(dir) {
+    if (process.platform === "win32")
+        return false; // Windows refuses to delete a running build, which is the same answer
+    const res = spawnSync("ps", ["-axo", "command="], { encoding: "utf8" });
+    if (res.status !== 0)
+        return true; // unknown: keep it
+    return res.stdout.split("\n").some((line) => line.includes(dir + path.sep));
+}
+/**
+ * Remove what earlier installs left in the install root: other builds, empty
+ * folders and archives from a download or unpack that never finished. Only
+ * touches what this module creates - a folder carrying the install marker,
+ * an empty folder, an archive - so a shared VIRTUALMATTER_CLIENT_DIR keeps
+ * anything else. A build a client is still running from is kept. Returns the
+ * paths removed.
+ */
+export function pruneOtherBuilds(keepDir, root = path.dirname(keepDir)) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
     }
+    catch {
+        return [];
+    }
+    const removed = [];
+    for (const e of entries) {
+        const full = path.join(root, e.name);
+        if (path.resolve(full) === path.resolve(keepDir))
+            continue;
+        try {
+            if (e.isDirectory()) {
+                const ours = fs.existsSync(path.join(full, MARKER)) || fs.readdirSync(full).length === 0;
+                if (!ours || runningFrom(full))
+                    continue;
+            }
+            else if (e.isFile()) {
+                if (!ARCHIVE_RE.test(e.name))
+                    continue;
+                if (e.name.endsWith(".part") && Date.now() - fs.statSync(full).mtimeMs < PART_GRACE_MS)
+                    continue;
+            }
+            else {
+                continue;
+            }
+            fs.rmSync(full, { recursive: true, force: true });
+            removed.push(full);
+        }
+        catch {
+            /* in use or not ours to delete: leave it */
+        }
+    }
+    return removed;
 }
 function formatMb(bytes) {
     return `${(bytes / 1048576).toFixed(0)} MB`;
@@ -177,11 +321,21 @@ export async function ensureClientInstalled(opts = {}) {
     }, fetchFn);
     log(`Unpacking into ${dir} ...`);
     fs.rmSync(dir, { recursive: true, force: true });
-    extractArchive(archive, dir, platform);
-    fs.rmSync(archive, { force: true });
-    const entrypoint = findEntrypoint(dir, platform);
-    if (!entrypoint)
-        throw new Error(`Unpacked ${build.filename ?? "the build"} but found nothing to launch in ${dir}.`);
+    let entrypoint;
+    try {
+        extractArchive(archive, dir, platform);
+        entrypoint = findEntrypoint(dir, platform);
+        if (!entrypoint)
+            throw new Error(`Unpacked ${build.filename ?? "the build"} but found nothing to launch in ${dir}.`);
+    }
+    catch (err) {
+        // Leave nothing half-installed behind: the next run downloads afresh either way.
+        fs.rmSync(dir, { recursive: true, force: true });
+        throw err;
+    }
+    finally {
+        fs.rmSync(archive, { force: true });
+    }
     if (platform !== "windows") {
         // Archives produced on Windows CI can lose the executable bit.
         for (const p of [entrypoint, path.join(dir, "Client"), path.join(dir, "crashpad_handler")]) {
@@ -195,7 +349,12 @@ export async function ensureClientInstalled(opts = {}) {
         }
     }
     const installed = { platform, dir, entrypoint, build };
+    // Keep the cache out of the OS's app database (see dropFromLaunchServices).
+    dropFromLaunchServices(entrypoint, platform);
     fs.writeFileSync(path.join(dir, MARKER), JSON.stringify(installed, null, 2) + "\n");
+    const pruned = pruneOtherBuilds(dir);
+    if (pruned.length)
+        log(`Removed ${pruned.length === 1 ? "an older build" : `${pruned.length} older builds and leftovers`}: ${pruned.map((p) => path.basename(p)).join(", ")}`);
     return installed;
 }
 function apiBaseFor(_build) {
@@ -225,6 +384,9 @@ export function launchClient(installed, montageUrl) {
         console.error(`Could not launch the client: ${err.message}`);
     });
     child.unref();
+    // Launching re-registers the bundle, so drop it again: the installed app in
+    // /Applications should stay the one that opens world links.
+    dropFromLaunchServices(installed.entrypoint, installed.platform);
 }
 // ---------------------------------------------------------------- sign-in hand-over
 /**

package/dist/files.js

@@ -112,11 +112,14 @@ export class FilesClient {
             throw new Error(`Deleting ${filePath} failed: HTTP ${res.status}`);
         }
     }
-    async runLua(code, target) {
+    async runLua(code, target, clientId) {
+        const payload = { code, target };
+        if (target === "client" && clientId !== undefined)
+            payload.client_id = clientId;
         const res = await authorizedFetch(`${this.apiRoot}/engine/run-lua`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ code, target }),
+            body: JSON.stringify(payload),
         }, this.fetchFn);
         if (!res.ok)
             throw new Error(await engineErrorMessage(res, "run-lua"));
@@ -151,6 +154,8 @@ export class FilesClient {
                 camera_rot_z: rz,
             });
         }
+        if (opts.clientId !== undefined)
+            body.client_id = opts.clientId;
         const res = await authorizedFetch(`${this.apiRoot}/engine/screenshot`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },

package/dist/index.js

@@ -300,12 +300,17 @@ program
     .argument("[dir]", "a synced folder", ".")
     .requiredOption("--code <lua>", "Lua source to execute")
     .option("--target <target>", "server or client", "server")
+    .option("--client <id>", "client id for --target client (default: the only connected client; list them with --code 'return Server:GetClients()')")
     .action((dir, opts) => run(async () => {
     if (opts.target !== "server" && opts.target !== "client") {
         fail("--target must be server or client");
     }
+    const clientId = opts.client === undefined ? undefined : clientIdFlag(opts.client);
+    if (clientId !== undefined && opts.target !== "client") {
+        fail("--client needs --target client");
+    }
     const { client } = await clientForDir(path.resolve(dir));
-    const result = await client.runLua(opts.code, opts.target);
+    const result = await client.runLua(opts.code, opts.target, clientId);
     console.log(JSON.stringify({ result }, null, 2));
 }));
 program
@@ -316,6 +321,13 @@ program
     const { client } = await clientForDir(path.resolve(dir));
     console.log(JSON.stringify(await client.engineErrors(), null, 2));
 }));
+/** Parse a --client flag: a positive integer client id. */
+function clientIdFlag(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1)
+        fail(`--client takes a client id (a positive integer), got "${value}"`);
+    return n;
+}
 /** Parse an "x,y,z" flag into a numeric triple. */
 function triple(value, flag) {
     const parts = value.split(",").map((p) => Number(p.trim()));
@@ -333,6 +345,7 @@ program
     .option("--rot <yaw,pitch,roll>", "camera rotation in degrees, yaw first (default: 0,-45,0)")
     .option("--target <id-or-name>", "frame this object instead of using a camera pose")
     .option("--distance <meters>", "framing distance for --target (default: from the object's bounds)")
+    .option("--client <id>", "capture through this connected client, UI included; with no --at/--rot/--target it is exactly what that client sees")
     .action((dir, opts) => run(async () => {
     const { client } = await clientForDir(path.resolve(dir));
     const png = await client.screenshot({
@@ -340,6 +353,7 @@ program
         rot: opts.rot ? triple(opts.rot, "--rot") : undefined,
         target: opts.target,
         distance: opts.distance === undefined ? undefined : Number(opts.distance),
+        clientId: opts.client === undefined ? undefined : clientIdFlag(opts.client),
     });
     fs.writeFileSync(opts.out, png);
     console.log(`Wrote ${opts.out} (${png.length} bytes).`);

package/dist/mcp.js

@@ -249,17 +249,23 @@ export async function runMcpServer(dir, framingFlag) {
         return textResult(JSON.stringify({ ok: true, path: filePath, etag }));
     });
     server.registerTool("run_lua", {
-        description: "Execute a Lua snippet in the running Virtual Matter engine and return its result. target \"server\" (default) runs in the server-side Lua state where game logic lives; \"client\" runs in the connected client. Use this to inspect live state, call engine APIs, or nudge the scene without editing files.",
+        description: "Execute a Lua snippet in the running Virtual Matter engine and return its result. target \"server\" (default) runs in the server-side Lua state where game logic lives; \"client\" runs in a connected client (someone must have the world open) - that is where UI, input and the camera live. With several clients connected, pass client_id; list them with target server and code 'return Server:GetClients()'. Use this to inspect live state, call engine APIs, or nudge the scene without editing files.",
         inputSchema: {
             code: z.string().describe("Lua source to execute"),
             target: z
                 .enum(["server", "client"])
                 .optional()
                 .describe("Which Lua state to run in (default: server)"),
+            client_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("For target client: which connected client (default: the only one connected)"),
         },
-    }, async ({ code, target }) => {
+    }, async ({ code, target, client_id }) => {
         const client = await ctx.getClient();
-        const result = await client.runLua(code, target ?? "server");
+        const result = await client.runLua(code, target ?? "server", client_id);
         return textResult(JSON.stringify({ result }, null, 2));
     });
     server.registerTool("get_engine_errors", {
@@ -286,13 +292,20 @@ export async function runMcpServer(dir, framingFlag) {
                 .length(3)
                 .optional()
                 .describe("Camera rotation in degrees as [yaw, pitch, roll] - that order. Yaw 0 faces -Z; pitch -90 looks straight down, 0 is the horizon. Default [0, -45, 0] looks down at the origin."),
+            client_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Capture through this connected client, UI (HUD, menus) included - a server capture never shows UI. With no target/at/rot it is exactly what that client sees."),
         },
-    }, async ({ target, at, rot }) => {
+    }, async ({ target, at, rot, client_id }) => {
         const client = await ctx.getClient();
         const png = await client.screenshot({
             target,
             at: at,
             rot: rot,
+            clientId: client_id,
         });
         return {
             content: [

package/dist/pull.js

@@ -5,7 +5,7 @@ import { resolveEditSession, sessionBaseUrl } from "./api.js";
 import { composeAgentsMd, fetchAgentsMd, writeAgentFiles } from "./agentfiles.js";
 import { FilesClient } from "./files.js";
 import { isIgnoredPath } from "./ignore.js";
-import { saveState } from "./state.js";
+import { recordLocal, saveState } from "./state.js";
 export { fetchAgentsMd } from "./agentfiles.js";
 export { AGENTS_MD_FALLBACK } from "./agents-md.generated.js";
 /** Download workers per pull. The tree is ~1000 small files; sequential
@@ -50,7 +50,7 @@ export async function fetchEngineAgentsMd(client) {
 export async function pullTree(client, dir, framingId) {
     fs.mkdirSync(dir, { recursive: true });
     const remote = (await client.list()).filter((f) => !isIgnoredPath(f.path));
-    const state = { framing_id: framingId, etags: {} };
+    const state = { framing_id: framingId, etags: {}, local: {} };
     const progress = makeProgress(remote.length);
     let next = 0;
     const worker = async () => {
@@ -64,6 +64,8 @@ export async function pullTree(client, dir, framingId) {
             fs.mkdirSync(path.dirname(absPath), { recursive: true });
             fs.writeFileSync(absPath, bytes);
             state.etags[file.path] = etag ?? file.etag;
+            // what the disk holds now, so the first sync can tell local edits apart
+            recordLocal(state, dir, file.path, bytes);
             progress.tick(file.path);
         }
     };

package/dist/state.js

@@ -1,4 +1,5 @@
-/** The .virtualmatter.json state file: framing id + per-file etag bookkeeping. */
+/** The .virtualmatter.json state file: framing id + per-file sync bookkeeping. */
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { STATE_FILE } from "./config.js";
@@ -11,7 +12,7 @@ export function loadState(dir) {
         const parsed = JSON.parse(raw);
         if (typeof parsed.framing_id !== "string")
             return null;
-        return { framing_id: parsed.framing_id, etags: parsed.etags ?? {} };
+        return { framing_id: parsed.framing_id, etags: parsed.etags ?? {}, local: parsed.local ?? {} };
     }
     catch {
         return null;
@@ -30,3 +31,56 @@ export function requireState(dir) {
     }
     return state;
 }
+export function sha256Hex(bytes) {
+    return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Record a file whose content hash is already known to match its last sync,
+ * from a stat alone. How a state file from before `local` records existed
+ * gets upgraded as files are first checked, so the next check is stat-only.
+ */
+export function adoptLocal(state, dir, relPath, hash) {
+    const st = fs.statSync(path.join(dir, relPath));
+    state.local ??= {};
+    state.local[relPath] = { hash, size: st.size, mtime_ms: st.mtimeMs };
+}
+/** Record `bytes` (just written to or read from `relPath`) as the synced local copy. */
+export function recordLocal(state, dir, relPath, bytes) {
+    const st = fs.statSync(path.join(dir, relPath));
+    state.local ??= {};
+    state.local[relPath] = { hash: sha256Hex(bytes), size: st.size, mtime_ms: st.mtimeMs };
+}
+/**
+ * The current content hash of a local file, or null if it does not exist.
+ * Reuses the recorded hash when size and mtime are unchanged, so a start
+ * over a big world does not re-read every voxel file.
+ */
+export function localHash(state, dir, relPath) {
+    const abs = path.join(dir, relPath);
+    let st;
+    try {
+        st = fs.statSync(abs);
+    }
+    catch {
+        return null;
+    }
+    if (!st.isFile())
+        return null;
+    const rec = state.local?.[relPath];
+    if (rec && rec.size === st.size && rec.mtime_ms === st.mtimeMs)
+        return rec.hash;
+    return sha256Hex(fs.readFileSync(abs));
+}
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/**
+ * The content hash of `relPath` as of its last sync, or undefined when
+ * unknown. Falls back to the etag for state files written before `local`
+ * existed - the session API's etags ARE the sha256 of the content.
+ */
+export function syncedHash(state, relPath) {
+    const rec = state.local?.[relPath];
+    if (rec)
+        return rec.hash;
+    const etag = state.etags[relPath];
+    return etag !== undefined && SHA256_HEX.test(etag) ? etag : undefined;
+}

package/dist/sync.js

@@ -1,21 +1,29 @@
 import { startLogSync } from "./agent-logs.js";
 /**
- * The sync hot loop: initial pull of remote changes, watch the local tree
- * and push edits with stored etags, poll the remote listing and pull files
- * whose etag changed remotely. Conflicts (412) never kill the loop - the
- * remote version lands next to yours as <name>.remote-conflict.
+ * The sync hot loop: reconcile both sides at start, watch the local tree and
+ * push edits with stored etags, poll the remote listing and pull files whose
+ * etag changed remotely.
+ *
+ * NEVER OVERWRITE UNSYNCED WORK. Every decision compares each side against
+ * what it looked like at the last sync - the server's etag, and the local
+ * record (content hash) in the state file - so a side that moved while the
+ * other did not is copied across, and a file BOTH sides changed is a
+ * conflict: the local file stays exactly as it is, the remote version lands
+ * next to it as <name>.remote-conflict, and nothing is pushed until you save.
+ * Conflicts never kill the loop.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { ConflictError } from "./files.js";
 import { isIgnoredPath } from "./ignore.js";
-import { loadState, saveState } from "./state.js";
+import { loadState, adoptLocal, localHash, recordLocal, saveState, sha256Hex, syncedHash, } from "./state.js";
 const consoleLogger = {
     info: (m) => console.log(m),
     warn: (m) => console.warn(m),
 };
 /** How long after our own local write of a pulled file we ignore watcher events for it. */
 const SELF_WRITE_GRACE_MS = 2000;
+export const CONFLICT_SUFFIX = ".remote-conflict";
 export class SyncEngine {
     client;
     dir;
@@ -24,12 +32,15 @@ export class SyncEngine {
     state;
     /** relPath -> timestamp of a write WE made (pull), so the watcher skips it. */
     selfWrites = new Map();
+    /** State changed without being written yet (see flush). */
+    dirty = false;
     constructor(client, dir, state, opts = {}) {
         this.client = client;
         this.dir = dir;
         this.log = opts.logger ?? consoleLogger;
         this.now = opts.now ?? Date.now;
         this.state = state;
+        this.state.local ??= {};
     }
     get framingId() {
         return this.state.framing_id;
@@ -53,6 +64,43 @@ export class SyncEngine {
         }
         return true;
     }
+    /**
+     * Has the local copy changed since its last sync? `true` also when the
+     * base is unknown but the file exists - "maybe" must be treated as "yes",
+     * or an unknown base is exactly how local work gets pulled over.
+     */
+    localChanged(relPath) {
+        const now = localHash(this.state, this.dir, relPath);
+        if (now === null)
+            return false;
+        const base = syncedHash(this.state, relPath);
+        if (base !== undefined && now === base) {
+            const rec = this.state.local?.[relPath];
+            if (!rec || rec.hash !== now) {
+                // Unchanged, but only known so by reading it (no record yet, or
+                // the mtime moved with the content the same). Record it so the
+                // next check is a stat - the backstop scan runs every few seconds.
+                adoptLocal(this.state, this.dir, relPath, now);
+                this.dirty = true;
+            }
+            else {
+                const st = fs.statSync(this.abs(relPath));
+                if (st.mtimeMs !== rec.mtime_ms || st.size !== rec.size) {
+                    adoptLocal(this.state, this.dir, relPath, now);
+                    this.dirty = true;
+                }
+            }
+            return false;
+        }
+        return true;
+    }
+    /** Record changes made while checking files (adopted records) - batched, one write per pass. */
+    flush() {
+        if (!this.dirty)
+            return;
+        this.dirty = false;
+        this.persist();
+    }
     async pullFile(relPath, etag) {
         const { bytes, etag: gotEtag } = await this.client.get(relPath);
         const absPath = this.abs(relPath);
@@ -60,39 +108,129 @@ export class SyncEngine {
         this.recordSelfWrite(relPath);
         fs.writeFileSync(absPath, bytes);
         this.state.etags[relPath] = gotEtag ?? etag;
+        recordLocal(this.state, this.dir, relPath, bytes);
         this.persist();
     }
     /**
-     * Initial reconcile: pull every remote file that is new or whose etag
-     * changed since the last sync, and push local files the remote has never
-     * seen. Returns counts for logging/tests.
+     * Both sides changed: keep the local file untouched, put the remote copy
+     * beside it, and point the stored etag at the remote version so that the
+     * next deliberate save of the local file is what wins. The local record is
+     * left alone, so the file still reads as locally changed.
+     */
+    async writeConflict(relPath, remoteEtag) {
+        try {
+            const { bytes, etag } = await this.client.get(relPath);
+            const conflictPath = this.abs(relPath) + CONFLICT_SUFFIX;
+            fs.mkdirSync(path.dirname(conflictPath), { recursive: true });
+            fs.writeFileSync(conflictPath, bytes);
+            const e = etag ?? remoteEtag;
+            if (e)
+                this.state.etags[relPath] = e;
+            this.persist();
+            this.log.warn(`conflict on ${relPath}: it changed both here and in the world. Your file is untouched; ` +
+                `the world's version is saved as ${relPath}${CONFLICT_SUFFIX} - merge, save, and it will push.`);
+        }
+        catch (err) {
+            this.log.warn(`conflict on ${relPath}, and fetching the remote version failed: ${String(err)}`);
+        }
+    }
+    /**
+     * A conflict the user has not resolved yet: the sidecar is still there and
+     * the local file has not been saved since it was written. Such a file is
+     * never pushed automatically - only a save does that.
+     */
+    unresolvedConflict(relPath) {
+        try {
+            const side = fs.statSync(this.abs(relPath) + CONFLICT_SUFFIX);
+            const mine = fs.statSync(this.abs(relPath));
+            return side.mtimeMs >= mine.mtimeMs;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Initial reconcile, per file, against the last sync:
+     *
+     *   local unchanged, remote changed   -> pull
+     *   local changed,   remote unchanged -> push
+     *   both changed (or both new, and different) -> conflict (local kept)
+     *   local only, never synced          -> push (create)
+     *   remote only                       -> pull
+     *
+     * A file deleted locally while sync was off is pulled back rather than
+     * deleted remotely: a start never destroys anything on either side.
      */
     async initialSync() {
         const remote = await this.client.list();
         let pulled = 0;
         let pushed = 0;
-        const remotePaths = new Set();
+        let conflicts = 0;
+        const remoteByPath = new Map();
         for (const file of remote) {
             if (isIgnoredPath(file.path))
                 continue;
-            remotePaths.add(file.path);
+            remoteByPath.set(file.path, file);
             const known = this.state.etags[file.path];
-            const localExists = fs.existsSync(this.abs(file.path));
-            if (known !== file.etag || !localExists) {
+            const current = localHash(this.state, this.dir, file.path);
+            if (current === null) {
+                await this.pullFile(file.path, file.etag);
+                pulled++;
+                continue;
+            }
+            if (current === file.etag) {
+                // same content on both sides (etags are content hashes): just
+                // bring the bookkeeping up to date
+                const rec = this.state.local?.[file.path];
+                if (known !== file.etag || !rec || rec.hash !== current) {
+                    this.state.etags[file.path] = file.etag;
+                    adoptLocal(this.state, this.dir, file.path, current);
+                    this.dirty = true;
+                }
+                continue;
+            }
+            const remoteChanged = known !== file.etag;
+            const localChanged = this.localChanged(file.path);
+            if (!localChanged && remoteChanged) {
                 await this.pullFile(file.path, file.etag);
+                this.log.info(`pulled ${file.path}`);
                 pulled++;
             }
+            else if (localChanged && !remoteChanged) {
+                if (this.unresolvedConflict(file.path)) {
+                    this.log.warn(`${file.path} still has an unresolved ${file.path}${CONFLICT_SUFFIX} - not pushing it. ` +
+                        `Merge, save the file (or delete the ${CONFLICT_SUFFIX} file), and it will push.`);
+                    continue;
+                }
+                if (await this.pushFile(file.path))
+                    pushed++;
+            }
+            else if (localChanged && remoteChanged) {
+                await this.writeConflict(file.path, file.etag);
+                conflicts++;
+            }
         }
-        // Local files the remote has never seen get created remotely.
         for (const relPath of this.walkLocal()) {
-            if (remotePaths.has(relPath))
+            if (remoteByPath.has(relPath))
                 continue;
-            if (this.state.etags[relPath] !== undefined)
-                continue; // was remote once; treat as remote delete, leave local alone
-            await this.pushFile(relPath, { createOnly: true });
-            pushed++;
+            if (this.state.etags[relPath] === undefined) {
+                // never synced: new here, create it remotely
+                if (await this.pushFile(relPath, { createOnly: true }))
+                    pushed++;
+                continue;
+            }
+            // Synced once, gone remotely. Untouched here: leave it (a remote
+            // delete is not ours to undo). Edited here since: that is work, so it
+            // is re-created rather than stranded.
+            if (this.localChanged(relPath)) {
+                this.log.warn(`${relPath} was deleted in the world but edited here - re-creating it.`);
+                delete this.state.etags[relPath];
+                if (await this.pushFile(relPath, { createOnly: true }))
+                    pushed++;
+            }
         }
-        return { pulled, pushed };
+        this.flush();
+        return { pulled, pushed, conflicts };
     }
     *walkLocal(rel = "") {
         const absDir = path.join(this.dir, rel);
@@ -113,42 +251,31 @@ export class SyncEngine {
                 yield relPath;
         }
     }
+    /** Push the local file. Returns false when there was nothing to send or it became a conflict. */
     async pushFile(relPath, opts) {
         const body = fs.readFileSync(this.abs(relPath));
         const known = this.state.etags[relPath];
+        // unchanged since the last sync: nothing to send (a touch, or the
+        // watcher and the local scan both reporting the same save)
+        if (known !== undefined && syncedHash(this.state, relPath) === sha256Hex(body))
+            return false;
         const createOnly = opts?.createOnly ?? known === undefined;
         try {
             const etag = await this.client.put(relPath, body, createOnly ? { createOnly: true } : { etag: known });
             this.state.etags[relPath] = etag;
+            recordLocal(this.state, this.dir, relPath, body);
             this.persist();
             this.log.info(`pushed ${relPath}`);
+            return true;
         }
         catch (err) {
             if (err instanceof ConflictError) {
-                await this.handleConflict(relPath);
-                return;
+                await this.writeConflict(relPath);
+                return false;
             }
             throw err;
         }
     }
-    /** 412: fetch the remote version to <name>.remote-conflict, keep the loop alive. */
-    async handleConflict(relPath) {
-        try {
-            const { bytes, etag } = await this.client.get(relPath);
-            const conflictPath = this.abs(relPath) + ".remote-conflict";
-            fs.mkdirSync(path.dirname(conflictPath), { recursive: true });
-            fs.writeFileSync(conflictPath, bytes);
-            if (etag)
-                this.state.etags[relPath] = etag;
-            // Deliberately NOT overwriting the local file - the user resolves.
-            this.persist();
-            this.log.warn(`conflict on ${relPath}: the remote copy changed while you edited it. ` +
-                `Remote version saved as ${relPath}.remote-conflict - merge, save, and it will push.`);
-        }
-        catch (err) {
-            this.log.warn(`conflict on ${relPath}, and fetching the remote version failed: ${String(err)}`);
-        }
-    }
     /** Watcher callback for a local add/change. */
     async handleLocalChange(relPath) {
         const norm = relPath.replace(/\\/g, "/");
@@ -178,12 +305,13 @@ export class SyncEngine {
         try {
             await this.client.delete(norm, known);
             delete this.state.etags[norm];
+            delete this.state.local?.[norm];
             this.persist();
             this.log.info(`deleted ${norm} remotely`);
         }
         catch (err) {
             if (err instanceof ConflictError) {
-                await this.handleConflict(norm);
+                await this.writeConflict(norm);
                 return;
             }
             this.log.warn(`remote delete of ${norm} failed: ${String(err)}`);
@@ -192,7 +320,8 @@ export class SyncEngine {
     /**
      * One remote poll tick: pull files whose remote etag differs from our
      * bookkeeping. Files we just pushed match by etag, so they are skipped
-     * naturally. Returns the pulled paths.
+     * naturally. A file with local changes that have not gone out yet is a
+     * conflict, never a pull. Returns the pulled paths.
      */
     async pollOnce() {
         const remote = await this.client.list();
@@ -200,23 +329,81 @@ export class SyncEngine {
         for (const file of remote) {
             if (isIgnoredPath(file.path))
                 continue;
-            if (this.state.etags[file.path] === file.etag && fs.existsSync(this.abs(file.path)))
+            const exists = fs.existsSync(this.abs(file.path));
+            if (this.state.etags[file.path] === file.etag && exists)
+                continue;
+            if (!exists && this.state.etags[file.path] === file.etag) {
+                // Deleted here, unchanged in the world since the last sync: a delete
+                // the watcher has not delivered yet, not a file to restore. Pulling it
+                // back also marked it as our own write, so the late unlink event was
+                // then ignored and the file came back for good.
+                await this.handleLocalDelete(file.path);
                 continue;
+            }
+            if (exists) {
+                const current = localHash(this.state, this.dir, file.path);
+                if (current === file.etag) {
+                    this.state.etags[file.path] = file.etag;
+                    adoptLocal(this.state, this.dir, file.path, current);
+                    this.persist();
+                    continue;
+                }
+                if (this.localChanged(file.path)) {
+                    // writeConflict points the etag at this remote version, so the
+                    // check at the top of the loop keeps it from firing again
+                    await this.writeConflict(file.path, file.etag);
+                    continue;
+                }
+            }
             await this.pullFile(file.path, file.etag);
             pulled.push(file.path);
             this.log.info(`pulled ${file.path}`);
         }
         return pulled;
     }
+    /**
+     * Backstop for the watcher: push every local file that changed since its
+     * last sync, and create new ones. File-system events get lost (editors
+     * that write in place, network drives, a burst while the queue is busy);
+     * a stat walk every few seconds cannot miss a save. Unchanged files cost a
+     * stat and no read. Returns the pushed paths.
+     */
+    async scanLocal() {
+        const pushed = [];
+        for (const relPath of this.walkLocal()) {
+            if (this.isSelfWrite(relPath))
+                continue;
+            const known = this.state.etags[relPath];
+            if (known !== undefined && !this.localChanged(relPath))
+                continue;
+            if (known !== undefined && this.unresolvedConflict(relPath))
+                continue;
+            try {
+                if (await this.pushFile(relPath))
+                    pushed.push(relPath);
+            }
+            catch (err) {
+                this.log.warn(`push of ${relPath} failed: ${String(err)}`);
+            }
+        }
+        this.flush();
+        return pushed;
+    }
 }
 /** Run the full watch loop until SIGINT. Not unit-tested directly; the decisions above are. */
 export async function runSyncLoop(engine, dir) {
     const { default: chokidar } = await import("chokidar");
-    const { pulled, pushed } = await engine.initialSync();
-    console.log(`initial sync: ${pulled} pulled, ${pushed} pushed. Watching ${dir} ...`);
+    const { pulled, pushed, conflicts } = await engine.initialSync();
+    console.log(`initial sync: ${pulled} pulled, ${pushed} pushed` +
+        (conflicts ? `, ${conflicts} conflict${conflicts === 1 ? "" : "s"} (see above)` : "") +
+        `. Watching ${dir} ...`);
     const stopLogs = startLogSync(dir);
     const watcher = chokidar.watch(dir, {
         ignoreInitial: true,
+        // Wait for a write to settle before reading it. Without this an editor
+        // that rewrites a file in place fired "change" mid-write and the sync
+        // pushed a truncated file.
+        awaitWriteFinish: { stabilityThreshold: 250, pollInterval: 50 },
         ignored: (p) => {
             const rel = path.relative(dir, p).replace(/\\/g, "/");
             return rel.length > 0 && isIgnoredPath(rel);
@@ -231,6 +418,12 @@ export async function runSyncLoop(engine, dir) {
     watcher.on("unlink", (p) => enqueue(() => engine.handleLocalDelete(path.relative(dir, p))));
     const interval = setInterval(() => {
         enqueue(async () => {
+            try {
+                await engine.scanLocal();
+            }
+            catch (err) {
+                console.warn(`local scan failed: ${String(err)}`);
+            }
             try {
                 await engine.pollOnce();
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virtualmatter",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "CLI + MCP server for building with Virtual Matter - list and create worlds, sync their files, run Lua, capture screenshots, open the native client, and wire coding agents into a live session.",
   "license": "MIT",
   "type": "module",