virtualmatter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atomontage Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# virtualmatter
+
+The command line for building with Virtual Matter - and the MCP server that
+gives coding agents direct hands on a live session: montage files, Lua
+execution, engine errors, and screenshots.
+
+No install needed:
+
+```bash
+npx virtualmatter --help
+```
+
+(`vm` works as a shorthand alias when installed.)
+
+Requires Node 20 or newer. No native modules.
+
+## Quickstart
+
+```bash
+# 1. Sign in (device code - approve it in your browser)
+npx virtualmatter login
+
+# 2. Pull a world you can edit. Paste the /edit link from your browser.
+npx virtualmatter pull https://make.virtualmatter.ai/edit/<framing-id> my-world
+cd my-world
+
+# 3. Start the hot loop: local edits push instantly, remote edits pull back.
+npx virtualmatter sync
+```
+
+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.
+
+Poke at the running engine from another terminal:
+
+```bash
+npx virtualmatter run-lua --code "return Server.GetInfo()"
+npx virtualmatter errors
+npx virtualmatter screenshot -o shot.png
+```
+
+## Hook up a coding agent (MCP)
+
+Register the MCP server with Claude Code in one line, from a pulled folder:
+
+```bash
+claude mcp add virtualmatter -- npx -y virtualmatter mcp
+```
+
+Or point it at a framing directly, no pulled folder needed:
+
+```bash
+claude mcp add virtualmatter -- npx -y virtualmatter mcp --framing <framing-id>
+```
+
+The server exposes `list_files`, `read_file`, `write_file`, `run_lua`,
+`get_engine_errors`, `capture_screenshot`, and `world_info`. Writes handle
+etag concurrency internally, and written Lua hot-reloads in the engine - so
+for an agent, writing a script is deploying it.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `login` / `logout` / `whoami` | Device-code sign-in against the Virtual Matter identity server; tokens live in `~/.config/virtualmatter/credentials.json` (mode 0600) and refresh automatically. |
+| `pull <url-or-framing-id> [dir]` | Resolve (cold-starting if needed) the framing's session and download its file tree, plus an `AGENTS.md` briefing for agents. |
+| `sync [dir]` | Watch + two-way sync with the live session. Ctrl-C to stop. |
+| `run-lua [dir] --code "<lua>" [--target server\|client]` | Execute Lua in the running engine. |
+| `errors [dir]` | Recent engine errors. |
+| `screenshot [dir] [-o out.png]` | Capture the engine's current view. |
+| `client` | Print the native client download link for your OS. |
+| `mcp [dir] [--framing <id>]` | Run the stdio MCP server. |
+
+`pull` understands `/edit/<id>`, `/play/<id>`, and `/m/<id>` links from any
+Virtual Matter host, or a bare framing id. Project-level links (`/g/...`,
+`/play/p/...`) point at a whole project - open the project and copy the
+`/edit` link for the framing you want.
+
+## Good to know
+
+- **Device sign-in is rolling out.** If `login` reports that device sign-in
+  is not enabled yet for this environment, the server-side toggle has not
+  reached your environment - it is coming.
+- `VIRTUALMATTER_API_BASE` overrides the platform API base (default
+  `https://make.virtualmatter.ai`) for dev/staging environments.
+- Sync skips `Uploads/`, `Screenshots/`, `Agent Logs/`, dotfiles, and its own
+  bookkeeping (`.virtualmatter.json`).
+- `pull` may cold-start a session for the framing; the first one can take a
+  minute.

package/dist/api.js

@@ -0,0 +1,60 @@
+/** Platform API client: authorized fetch, whoami, session resolution, native clients. */
+import { getAccessToken } from "./auth.js";
+import { apiBase } from "./config.js";
+export async function authorizedFetch(url, init = {}, fetchFn = fetch) {
+    const token = await getAccessToken(fetchFn);
+    const headers = new Headers(init.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    return fetchFn(url, { ...init, headers });
+}
+export async function whoami(fetchFn = fetch) {
+    const res = await authorizedFetch(`${apiBase()}/api/v1/me`, {}, fetchFn);
+    if (!res.ok)
+        throw new Error(`GET /api/v1/me failed: HTTP ${res.status}`);
+    return (await res.json());
+}
+/**
+ * Resolve (and if needed cold-spawn) the session serving a framing.
+ * POST /api/v1/framings/{id}/session returns 200 with the session, or
+ * 202 {status:"spawning", retry_after_ms} - poll until 200 or timeout.
+ */
+export async function resolveSession(framingId, opts = {}) {
+    const fetchFn = opts.fetchFn ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? Date.now;
+    const deadline = now() + (opts.timeoutMs ?? 120_000);
+    for (;;) {
+        const res = await authorizedFetch(`${apiBase()}/api/v1/framings/${encodeURIComponent(framingId)}/session`, { method: "POST" }, fetchFn);
+        if (res.status === 200) {
+            return (await res.json());
+        }
+        if (res.status === 202) {
+            const body = (await res.json());
+            const wait = Math.max(500, body.retry_after_ms ?? 2000);
+            if (now() + wait > deadline) {
+                throw new Error("The session is still spawning after ~120s. Try again in a minute - cold starts can take a while.");
+            }
+            await sleep(wait);
+            continue;
+        }
+        if (res.status === 401 || res.status === 403) {
+            throw new Error(`Not authorized for framing ${framingId} (HTTP ${res.status}).`);
+        }
+        if (res.status === 404) {
+            throw new Error(`Framing ${framingId} was not found.`);
+        }
+        throw new Error(`Session lookup failed: HTTP ${res.status}`);
+    }
+}
+/** Session base URL where the file/engine API lives. */
+export function sessionBaseUrl(session) {
+    const host = session.voxel_host.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+    return `https://${host}/s/${session.session_id}`;
+}
+export async function fetchNativeClients(fetchFn = fetch) {
+    const res = await fetchFn(`${apiBase()}/api/v1/public/native-clients`);
+    if (!res.ok)
+        throw new Error(`GET /api/v1/public/native-clients failed: HTTP ${res.status}`);
+    const body = (await res.json());
+    return body.clients ?? [];
+}

package/dist/auth.js

@@ -0,0 +1,179 @@
+/**
+ * OAuth 2.0 Device Authorization Grant (RFC 8628) against Keycloak,
+ * plus token storage and refresh.
+ *
+ * Tokens live in ~/.config/virtualmatter/credentials.json, chmod 0600.
+ * The access token is refreshed via the token endpoint when it is within
+ * 30 seconds of expiry.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { OAUTH_CLIENT_ID, configDir, credentialsPath, oidcDiscoveryUrl } from "./config.js";
+export class DeviceFlowDisabledError extends Error {
+    constructor() {
+        super("Device sign-in is not enabled yet for this environment. Ask an operator to enable the OAuth 2.0 Device Authorization Grant on the Keycloak client, then run `virtualmatter login` again.");
+        this.name = "DeviceFlowDisabledError";
+    }
+}
+export class NotLoggedInError extends Error {
+    constructor() {
+        super("Not signed in. Run `virtualmatter login` first.");
+        this.name = "NotLoggedInError";
+    }
+}
+const REFRESH_SKEW_MS = 30_000;
+/** Refresh margin exported for tests. */
+export { REFRESH_SKEW_MS };
+async function fetchDiscovery(fetchFn) {
+    const res = await fetchFn(oidcDiscoveryUrl());
+    if (!res.ok) {
+        throw new Error(`OIDC discovery failed: HTTP ${res.status}`);
+    }
+    const doc = (await res.json());
+    if (!doc.device_authorization_endpoint || !doc.token_endpoint) {
+        throw new Error("OIDC discovery document is missing device_authorization_endpoint or token_endpoint");
+    }
+    return {
+        device_authorization_endpoint: doc.device_authorization_endpoint,
+        token_endpoint: doc.token_endpoint,
+    };
+}
+function form(params) {
+    return {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(params).toString(),
+    };
+}
+/** Start the device flow: returns the codes to show the user, plus the token endpoint. */
+export async function startDeviceFlow(fetchFn = fetch) {
+    const disco = await fetchDiscovery(fetchFn);
+    const res = await fetchFn(disco.device_authorization_endpoint, form({ client_id: OAUTH_CLIENT_ID, scope: "openid" }));
+    if (!res.ok) {
+        let body = {};
+        try {
+            body = (await res.json());
+        }
+        catch {
+            /* non-JSON error body */
+        }
+        if (body.error === "unauthorized_client") {
+            throw new DeviceFlowDisabledError();
+        }
+        throw new Error(`Device authorization failed: HTTP ${res.status}${body.error ? ` (${body.error}: ${body.error_description ?? ""})` : ""}`);
+    }
+    const auth = (await res.json());
+    return { auth, tokenEndpoint: disco.token_endpoint };
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Poll the token endpoint per RFC 8628 until the user approves, the code
+ * expires, or the server rejects. Respects `interval` and `slow_down`.
+ */
+export async function pollForToken(tokenEndpoint, auth, opts = {}) {
+    const fetchFn = opts.fetchFn ?? fetch;
+    const sleep = opts.sleep ?? defaultSleep;
+    const now = opts.now ?? Date.now;
+    let intervalMs = Math.max(1, auth.interval ?? 5) * 1000;
+    const deadline = now() + auth.expires_in * 1000;
+    for (;;) {
+        if (now() > deadline) {
+            throw new Error("Device sign-in timed out before the code was approved. Run `virtualmatter login` again.");
+        }
+        await sleep(intervalMs);
+        const res = await fetchFn(tokenEndpoint, form({
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+            device_code: auth.device_code,
+            client_id: OAUTH_CLIENT_ID,
+        }));
+        if (res.ok) {
+            const tok = (await res.json());
+            return {
+                access_token: tok.access_token,
+                refresh_token: tok.refresh_token,
+                expires_at: now() + tok.expires_in * 1000,
+                token_endpoint: tokenEndpoint,
+            };
+        }
+        let body = {};
+        try {
+            body = (await res.json());
+        }
+        catch {
+            /* keep polling on transient non-JSON errors */
+        }
+        switch (body.error) {
+            case "authorization_pending":
+                continue;
+            case "slow_down":
+                intervalMs += 5000;
+                continue;
+            case "expired_token":
+                throw new Error("The sign-in code expired before it was approved. Run `virtualmatter login` again.");
+            case "access_denied":
+                throw new Error("Sign-in was denied.");
+            case "unauthorized_client":
+                throw new DeviceFlowDisabledError();
+            default:
+                throw new Error(`Token request failed: HTTP ${res.status}${body.error ? ` (${body.error}: ${body.error_description ?? ""})` : ""}`);
+        }
+    }
+}
+export function saveCredentials(creds) {
+    const dir = configDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = credentialsPath();
+    const tmp = path.join(dir, `.credentials.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    fs.chmodSync(file, 0o600);
+}
+export function loadCredentials() {
+    try {
+        const raw = fs.readFileSync(credentialsPath(), "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function clearCredentials() {
+    try {
+        fs.unlinkSync(credentialsPath());
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Return a valid access token, refreshing it when within 30s of expiry.
+ * Throws NotLoggedInError when no usable credentials exist.
+ */
+export async function getAccessToken(fetchFn = fetch, now = Date.now) {
+    const creds = loadCredentials();
+    if (!creds)
+        throw new NotLoggedInError();
+    if (now() < creds.expires_at - REFRESH_SKEW_MS) {
+        return creds.access_token;
+    }
+    if (!creds.refresh_token)
+        throw new NotLoggedInError();
+    const res = await fetchFn(creds.token_endpoint, form({
+        grant_type: "refresh_token",
+        refresh_token: creds.refresh_token,
+        client_id: OAUTH_CLIENT_ID,
+    }));
+    if (!res.ok) {
+        throw new NotLoggedInError();
+    }
+    const tok = (await res.json());
+    const next = {
+        access_token: tok.access_token,
+        refresh_token: tok.refresh_token ?? creds.refresh_token,
+        expires_at: now() + tok.expires_in * 1000,
+        token_endpoint: creds.token_endpoint,
+    };
+    saveCredentials(next);
+    return next.access_token;
+}

package/dist/browser.js

@@ -0,0 +1,19 @@
+/** Best-effort "open this URL in a browser" with no dependencies. */
+import { spawn } from "node:child_process";
+export function openInBrowser(url) {
+    try {
+        const [cmd, args] = process.platform === "darwin"
+            ? ["open", [url]]
+            : process.platform === "win32"
+                ? ["cmd", ["/c", "start", "", url]]
+                : ["xdg-open", [url]];
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => {
+            /* best-effort: the URL is printed anyway */
+        });
+        child.unref();
+    }
+    catch {
+        /* best-effort */
+    }
+}

package/dist/config.js

@@ -0,0 +1,22 @@
+import os from "node:os";
+import path from "node:path";
+/** Platform API base. Overridable so dev/staging environments work. */
+export function apiBase() {
+    const raw = process.env.VIRTUALMATTER_API_BASE ?? "https://make.virtualmatter.ai";
+    return raw.replace(/\/+$/, "");
+}
+/** Keycloak realm OIDC discovery document URL. */
+export function oidcDiscoveryUrl() {
+    return (process.env.VIRTUALMATTER_OIDC_DISCOVERY ??
+        "https://auth.atomontage.app/auth/realms/Atomontage/.well-known/openid-configuration");
+}
+export const OAUTH_CLIENT_ID = "virtualmatter-platform";
+/** Directory where credentials live: ~/.config/virtualmatter */
+export function configDir() {
+    return (process.env.VIRTUALMATTER_CONFIG_DIR ?? path.join(os.homedir(), ".config", "virtualmatter"));
+}
+export function credentialsPath() {
+    return path.join(configDir(), "credentials.json");
+}
+/** Name of the per-directory sync state file. */
+export const STATE_FILE = ".virtualmatter.json";

package/dist/files.js

@@ -0,0 +1,115 @@
+/**
+ * Client for the session file + engine API served at
+ * https://<voxel_host>/s/<session_id>/api/montage/<framing_id>/...
+ */
+import { authorizedFetch } from "./api.js";
+export class ConflictError extends Error {
+    filePath;
+    constructor(filePath) {
+        super(`Conflict (412) writing ${filePath}: the remote copy changed.`);
+        this.filePath = filePath;
+        this.name = "ConflictError";
+    }
+}
+function encodePath(p) {
+    return p.split("/").map(encodeURIComponent).join("/");
+}
+/**
+ * The server's ETag HEADERS are RFC-9110-quoted (`"abc..."`, possibly
+ * weak `W/"abc..."`) while its listing JSON and write responses carry
+ * bare sha256 hex. Everything we store and compare must be the bare
+ * form - storing the quoted header verbatim made every listing
+ * comparison miss and sent sync into an eternal re-pull loop (caught
+ * live on the first end-to-end run, 2026-08-28).
+ */
+export function normalizeEtag(v) {
+    if (v === null)
+        return null;
+    let s = v.trim();
+    if (s.startsWith("W/"))
+        s = s.slice(2).trim();
+    if (s.length >= 2 && s.startsWith('"') && s.endsWith('"'))
+        s = s.slice(1, -1);
+    return s;
+}
+export class FilesClient {
+    sessionBase;
+    framingId;
+    fetchFn;
+    constructor(sessionBase, framingId, fetchFn = fetch) {
+        this.sessionBase = sessionBase;
+        this.framingId = framingId;
+        this.fetchFn = fetchFn;
+    }
+    get apiRoot() {
+        return `${this.sessionBase}/api/montage/${encodeURIComponent(this.framingId)}`;
+    }
+    async list() {
+        const res = await authorizedFetch(`${this.apiRoot}/files`, {}, this.fetchFn);
+        if (!res.ok)
+            throw new Error(`Listing files failed: HTTP ${res.status}`);
+        // Server envelope: {files: [...], truncated: bool} (session-agent
+        // files API). Truncation only trips past 20k files; surface it so a
+        // giant world doesn't silently half-sync.
+        const body = (await res.json());
+        if (body.truncated) {
+            console.error("Warning: the server truncated the file listing (very large world) - sync may be incomplete.");
+        }
+        return body.files;
+    }
+    async get(filePath) {
+        const res = await authorizedFetch(`${this.apiRoot}/files/content/${encodePath(filePath)}`, {}, this.fetchFn);
+        if (!res.ok)
+            throw new Error(`Downloading ${filePath} failed: HTTP ${res.status}`);
+        const bytes = Buffer.from(await res.arrayBuffer());
+        return { bytes, etag: normalizeEtag(res.headers.get("ETag")) };
+    }
+    async put(filePath, body, opts) {
+        const headers = { "Content-Type": "application/octet-stream" };
+        if (opts.createOnly)
+            headers["If-None-Match"] = "*";
+        else if (opts.etag)
+            headers["If-Match"] = opts.etag;
+        const res = await authorizedFetch(`${this.apiRoot}/files/content/${encodePath(filePath)}`, { method: "PUT", headers, body: new Uint8Array(body) }, this.fetchFn);
+        if (res.status === 412)
+            throw new ConflictError(filePath);
+        if (!res.ok)
+            throw new Error(`Uploading ${filePath} failed: HTTP ${res.status}`);
+        const parsed = (await res.json());
+        return parsed.etag;
+    }
+    async delete(filePath, etag) {
+        const res = await authorizedFetch(`${this.apiRoot}/files/content/${encodePath(filePath)}`, { method: "DELETE", headers: { "If-Match": etag } }, this.fetchFn);
+        if (res.status === 412)
+            throw new ConflictError(filePath);
+        if (!res.ok && res.status !== 404) {
+            throw new Error(`Deleting ${filePath} failed: HTTP ${res.status}`);
+        }
+    }
+    async runLua(code, target) {
+        const res = await authorizedFetch(`${this.apiRoot}/engine/run-lua`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ code, target }),
+        }, this.fetchFn);
+        if (!res.ok)
+            throw new Error(`run-lua failed: HTTP ${res.status}`);
+        // Server envelope: {output: <text>} - the engine bridge's text
+        // (result/print/error sections) passed through verbatim.
+        const body = (await res.json());
+        return body.output;
+    }
+    async engineErrors() {
+        const res = await authorizedFetch(`${this.apiRoot}/engine/errors`, {}, this.fetchFn);
+        if (!res.ok)
+            throw new Error(`Fetching engine errors failed: HTTP ${res.status}`);
+        const body = (await res.json());
+        return body.output;
+    }
+    async screenshot() {
+        const res = await authorizedFetch(`${this.apiRoot}/engine/screenshot`, { method: "POST" }, this.fetchFn);
+        if (!res.ok)
+            throw new Error(`Screenshot failed: HTTP ${res.status}`);
+        return Buffer.from(await res.arrayBuffer());
+    }
+}

package/dist/ignore.js

@@ -0,0 +1,23 @@
+/** Shared path-exclusion rules for pull + sync. */
+import { STATE_FILE } from "./config.js";
+/** Server-side folders never synced. */
+const EXCLUDED_DIRS = ["Uploads", "Screenshots", "Agent Logs"];
+export function isIgnoredPath(relPath) {
+    const norm = relPath.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (norm.length === 0)
+        return true;
+    const segments = norm.split("/");
+    const first = segments[0];
+    if (EXCLUDED_DIRS.includes(first))
+        return true;
+    // Dotfiles anywhere in the path (covers .virtualmatter.json, .git, .DS_Store).
+    if (segments.some((s) => s.startsWith(".")))
+        return true;
+    if (norm === STATE_FILE)
+        return true;
+    if (norm === "AGENTS.md")
+        return true;
+    if (norm.endsWith(".remote-conflict"))
+        return true;
+    return false;
+}

package/dist/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/** virtualmatter - the CLI coding agents (and humans) install to build with Virtual Matter. */
+import fs from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { resolveSession, sessionBaseUrl, fetchNativeClients, whoami } from "./api.js";
+import { clearCredentials, loadCredentials, pollForToken, saveCredentials, startDeviceFlow, } from "./auth.js";
+import { openInBrowser } from "./browser.js";
+import { FilesClient } from "./files.js";
+import { runMcpServer, resolveFramingId } from "./mcp.js";
+import { pullCommand } from "./pull.js";
+import { requireState } from "./state.js";
+import { SyncEngine, runSyncLoop } from "./sync.js";
+import { parseTarget, PROJECT_URL_HELP } from "./urls.js";
+const program = new Command();
+program
+    .name("virtualmatter")
+    .description("Build with Virtual Matter from your terminal: sync montage files, run Lua, capture screenshots, and expose it all to coding agents over MCP.")
+    .version("0.1.0");
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+async function run(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+}
+/** Resolve a session-scoped FilesClient from a synced dir's state file. */
+async function clientForDir(dir) {
+    const state = requireState(dir);
+    const session = await resolveSession(state.framing_id);
+    return { client: new FilesClient(sessionBaseUrl(session), state.framing_id), framingId: state.framing_id };
+}
+program
+    .command("login")
+    .description("Sign in with Virtual Matter using a device code")
+    .action(() => run(async () => {
+    const { auth, tokenEndpoint } = await startDeviceFlow();
+    const url = auth.verification_uri_complete ?? auth.verification_uri;
+    console.log(`Open ${url}`);
+    console.log(`and enter the code: ${auth.user_code}`);
+    openInBrowser(url);
+    const creds = await pollForToken(tokenEndpoint, auth);
+    saveCredentials(creds);
+    const me = await whoami();
+    console.log(`Signed in as ${me.username ?? me.email ?? me.id}.`);
+}));
+program
+    .command("logout")
+    .description("Forget the stored credentials")
+    .action(() => {
+    const removed = clearCredentials();
+    console.log(removed ? "Signed out." : "No stored credentials.");
+});
+program
+    .command("whoami")
+    .description("Show who is signed in")
+    .action(() => run(async () => {
+    if (!loadCredentials())
+        fail("Not signed in. Run `virtualmatter login` first.");
+    const me = await whoami();
+    console.log(JSON.stringify(me, null, 2));
+}));
+program
+    .command("pull")
+    .description("Download a framing's file tree into a local folder")
+    .argument("<target>", "an /edit, /play, or /m URL - or a bare framing id")
+    .argument("[dir]", "destination folder (default: ./<framing-id>)")
+    .action((target, dir) => run(async () => {
+    const parsed = parseTarget(target);
+    if (parsed.kind === "project")
+        fail(PROJECT_URL_HELP);
+    if (parsed.kind === "invalid")
+        fail(parsed.reason);
+    const dest = path.resolve(dir ?? parsed.framingId);
+    const result = await pullCommand(parsed.framingId, dest);
+    console.log(`Pulled ${result.fileCount} files into ${dest}.`);
+    console.log(`Next: cd ${path.relative(process.cwd(), dest) || "."} && virtualmatter sync`);
+}));
+program
+    .command("sync")
+    .description("Two-way sync: watch the folder, push local edits, pull remote changes")
+    .argument("[dir]", "a folder previously created by `virtualmatter pull`", ".")
+    .action((dir) => run(async () => {
+    const abs = path.resolve(dir);
+    const state = requireState(abs);
+    const session = await resolveSession(state.framing_id);
+    const client = new FilesClient(sessionBaseUrl(session), state.framing_id);
+    const engine = new SyncEngine(client, abs, state);
+    console.log(`Syncing ${abs} with framing ${state.framing_id}. Ctrl-C to stop.`);
+    await runSyncLoop(engine, abs);
+}));
+program
+    .command("run-lua")
+    .description("Execute Lua in the running engine")
+    .argument("[dir]", "a synced folder", ".")
+    .requiredOption("--code <lua>", "Lua source to execute")
+    .option("--target <target>", "server or client", "server")
+    .action((dir, opts) => run(async () => {
+    if (opts.target !== "server" && opts.target !== "client") {
+        fail("--target must be server or client");
+    }
+    const { client } = await clientForDir(path.resolve(dir));
+    const result = await client.runLua(opts.code, opts.target);
+    console.log(JSON.stringify({ result }, null, 2));
+}));
+program
+    .command("errors")
+    .description("Show recent engine errors")
+    .argument("[dir]", "a synced folder", ".")
+    .action((dir) => run(async () => {
+    const { client } = await clientForDir(path.resolve(dir));
+    console.log(JSON.stringify(await client.engineErrors(), null, 2));
+}));
+program
+    .command("screenshot")
+    .description("Capture a PNG of the engine's current view")
+    .argument("[dir]", "a synced folder", ".")
+    .option("-o, --out <file>", "output file", "screenshot.png")
+    .action((dir, opts) => run(async () => {
+    const { client } = await clientForDir(path.resolve(dir));
+    const png = await client.screenshot();
+    fs.writeFileSync(opts.out, png);
+    console.log(`Wrote ${opts.out} (${png.length} bytes).`);
+}));
+program
+    .command("client")
+    .description("Print the native client download URL for this OS")
+    .action(() => run(async () => {
+    const clients = await fetchNativeClients();
+    const platform = process.platform === "darwin" ? "macos" : process.platform === "win32" ? "windows" : "linux";
+    const matches = clients.filter((c) => c.platform.toLowerCase().includes(platform));
+    if (matches.length === 0) {
+        console.log(`No native client published for ${platform} yet. All available:`);
+        for (const c of clients)
+            console.log(`  ${c.platform}${c.kind ? ` (${c.kind})` : ""}: ${c.url}`);
+        return;
+    }
+    for (const c of matches)
+        console.log(`${c.platform}${c.kind ? ` (${c.kind})` : ""}: ${c.url}`);
+}));
+program
+    .command("mcp")
+    .description("Run the stdio MCP server for coding agents")
+    .argument("[dir]", "a synced folder whose state file names the framing", ".")
+    .option("--framing <id>", "framing id (overrides the state file)")
+    .action((dir, opts) => run(async () => {
+    const abs = path.resolve(dir);
+    // Validate early so misconfiguration fails loudly at registration time.
+    resolveFramingId(abs, opts.framing);
+    await runMcpServer(abs, opts.framing);
+}));
+program.parseAsync(process.argv).catch((err) => {
+    fail(err instanceof Error ? err.message : String(err));
+});

package/dist/mcp.js

@@ -0,0 +1,147 @@
+/**
+ * `virtualmatter mcp` - a stdio MCP server that gives a coding agent direct
+ * hands on a live Virtual Matter session: montage files, Lua execution,
+ * engine errors, and screenshots.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { resolveSession, sessionBaseUrl } from "./api.js";
+import { apiBase } from "./config.js";
+import { ConflictError, FilesClient } from "./files.js";
+import { loadState } from "./state.js";
+export function resolveFramingId(dir, framingFlag) {
+    if (framingFlag)
+        return framingFlag;
+    const state = loadState(dir);
+    if (state)
+        return state.framing_id;
+    throw new Error(`No .virtualmatter.json in ${dir} and no --framing flag. Run \`virtualmatter pull\` there first, or pass --framing <id>.`);
+}
+function makeContext(framingId) {
+    let session = null;
+    let client = null;
+    const getSession = async () => {
+        if (!session)
+            session = await resolveSession(framingId);
+        return session;
+    };
+    return {
+        framingId,
+        getSession,
+        async getClient() {
+            if (!client)
+                client = new FilesClient(sessionBaseUrl(await getSession()), framingId);
+            return client;
+        },
+    };
+}
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+/**
+ * write_file etag handling: look up the current etag from a listing, PUT with
+ * If-Match (or If-None-Match: * for a new file), and on 412 retry ONCE with a
+ * fresh etag - the agent supplied the full desired content, so last-write-wins
+ * on retry is the intended semantics.
+ */
+export async function writeWithRetry(client, filePath, body) {
+    const findEtag = async () => {
+        const listing = await client.list();
+        return listing.find((f) => f.path === filePath)?.etag;
+    };
+    let etag = await findEtag();
+    try {
+        return await client.put(filePath, body, etag ? { etag } : { createOnly: true });
+    }
+    catch (err) {
+        if (!(err instanceof ConflictError))
+            throw err;
+        etag = await findEtag();
+        return await client.put(filePath, body, etag ? { etag } : { createOnly: true });
+    }
+}
+export async function runMcpServer(dir, framingFlag) {
+    const framingId = resolveFramingId(dir, framingFlag);
+    const ctx = makeContext(framingId);
+    const server = new McpServer({ name: "virtualmatter", version: "0.1.0" });
+    server.registerTool("list_files", {
+        description: "List every file in the live Virtual Matter session's Montage tree. Returns path, size, mtime_ms, and etag per file. Call this before reading or writing to learn what exists. Lua scripts under this tree hot-reload in the engine when written.",
+        inputSchema: {},
+    }, async () => {
+        const client = await ctx.getClient();
+        return textResult(JSON.stringify(await client.list(), null, 2));
+    });
+    server.registerTool("read_file", {
+        description: "Read one file from the live session's Montage tree. Pass the exact relative path from list_files (e.g. \"Scripts/main.lua\"). Returns the file content as text.",
+        inputSchema: { path: z.string().describe("Relative file path inside the montage tree") },
+    }, async ({ path: filePath }) => {
+        const client = await ctx.getClient();
+        const { bytes } = await client.get(filePath);
+        return textResult(bytes.toString("utf8"));
+    });
+    server.registerTool("write_file", {
+        description: "Write (create or overwrite) one file in the live session's Montage tree with the full desired content. Concurrency is handled internally with etags - if someone else changed the file since you read it, the write retries once against the latest version and your content wins. Lua scripts hot-reload in the engine on write, so writing a script IS deploying it.",
+        inputSchema: {
+            path: z.string().describe("Relative file path inside the montage tree"),
+            content: z.string().describe("Full new file content (UTF-8 text)"),
+        },
+    }, async ({ path: filePath, content }) => {
+        const client = await ctx.getClient();
+        const etag = await writeWithRetry(client, filePath, Buffer.from(content, "utf8"));
+        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.",
+        inputSchema: {
+            code: z.string().describe("Lua source to execute"),
+            target: z
+                .enum(["server", "client"])
+                .optional()
+                .describe("Which Lua state to run in (default: server)"),
+        },
+    }, async ({ code, target }) => {
+        const client = await ctx.getClient();
+        const result = await client.runLua(code, target ?? "server");
+        return textResult(JSON.stringify({ result }, null, 2));
+    });
+    server.registerTool("get_engine_errors", {
+        description: "Fetch recent Lua/engine errors from the running session. Check this after writing a script or running Lua - a hot-reload that failed shows up here, not in the write result.",
+        inputSchema: {},
+    }, async () => {
+        const client = await ctx.getClient();
+        return textResult(JSON.stringify(await client.engineErrors(), null, 2));
+    });
+    server.registerTool("capture_screenshot", {
+        description: "Capture a PNG screenshot of the engine's current view and return it as an image. Use it to visually verify what a change actually looks like in the world.",
+        inputSchema: {},
+    }, async () => {
+        const client = await ctx.getClient();
+        const png = await client.screenshot();
+        return {
+            content: [
+                { type: "image", data: png.toString("base64"), mimeType: "image/png" },
+            ],
+        };
+    });
+    server.registerTool("world_info", {
+        description: "Return the framing id plus the URLs for this session: the editor and play links a human can open, and the session API base this server talks to.",
+        inputSchema: {},
+    }, async () => {
+        const session = await ctx.getSession();
+        return textResult(JSON.stringify({
+            framing_id: ctx.framingId,
+            edit_url: `${apiBase()}/edit/${ctx.framingId}`,
+            play_url: `${apiBase()}/play/${ctx.framingId}`,
+            session_api_base: sessionBaseUrl(session),
+            voxel_host: session.voxel_host,
+            session_id: session.session_id,
+        }, null, 2));
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Keep the process alive until the transport closes.
+    await new Promise((resolve) => {
+        transport.onclose = () => resolve();
+    });
+}

package/dist/pull.js

@@ -0,0 +1,62 @@
+/** `virtualmatter pull`: download a framing's file tree and seed the state file. */
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSession, sessionBaseUrl } from "./api.js";
+import { apiBase } from "./config.js";
+import { FilesClient } from "./files.js";
+import { isIgnoredPath } from "./ignore.js";
+import { saveState } from "./state.js";
+const AGENTS_MD_STUB = `# Working with Virtual Matter
+
+This folder is a live mirror of a Virtual Matter framing's Montage files.
+
+- \`virtualmatter sync\` keeps it in sync with the running session.
+- \`virtualmatter run-lua --code "..."\` executes Lua in the engine.
+- \`virtualmatter errors\` shows recent engine errors.
+- \`virtualmatter screenshot -o shot.png\` captures the current view.
+- Lua scripts under this tree hot-reload in the engine when saved.
+
+Do not edit \`.virtualmatter.json\` - it is sync bookkeeping.
+`;
+export async function fetchAgentsMd(fetchFn = fetch) {
+    try {
+        const res = await fetchFn(`${apiBase()}/AGENTS.md`);
+        if (res.ok) {
+            const text = await res.text();
+            if (text.trim().length > 0 && !text.trimStart().startsWith("<"))
+                return text;
+        }
+    }
+    catch {
+        /* fall through to the stub */
+    }
+    return AGENTS_MD_STUB;
+}
+export async function pullTree(client, dir, framingId) {
+    fs.mkdirSync(dir, { recursive: true });
+    const remote = await client.list();
+    const state = { framing_id: framingId, etags: {} };
+    let count = 0;
+    for (const file of remote) {
+        if (isIgnoredPath(file.path))
+            continue;
+        const { bytes, etag } = await client.get(file.path);
+        const absPath = path.join(dir, file.path);
+        fs.mkdirSync(path.dirname(absPath), { recursive: true });
+        fs.writeFileSync(absPath, bytes);
+        state.etags[file.path] = etag ?? file.etag;
+        count++;
+    }
+    saveState(dir, state);
+    return { dir, framingId, fileCount: count };
+}
+export async function pullCommand(framingId, dir) {
+    console.log(`Resolving session for framing ${framingId} (this can cold-start one) ...`);
+    const session = await resolveSession(framingId);
+    const client = new FilesClient(sessionBaseUrl(session), framingId);
+    console.log(`Session ready at ${sessionBaseUrl(session)}. Downloading files ...`);
+    const result = await pullTree(client, dir, framingId);
+    const agentsMd = await fetchAgentsMd();
+    fs.writeFileSync(path.join(dir, "AGENTS.md"), agentsMd);
+    return result;
+}

package/dist/state.js

@@ -0,0 +1,32 @@
+/** The .virtualmatter.json state file: framing id + per-file etag bookkeeping. */
+import fs from "node:fs";
+import path from "node:path";
+import { STATE_FILE } from "./config.js";
+export function statePath(dir) {
+    return path.join(dir, STATE_FILE);
+}
+export function loadState(dir) {
+    try {
+        const raw = fs.readFileSync(statePath(dir), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.framing_id !== "string")
+            return null;
+        return { framing_id: parsed.framing_id, etags: parsed.etags ?? {} };
+    }
+    catch {
+        return null;
+    }
+}
+export function saveState(dir, state) {
+    const tmp = statePath(dir) + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n");
+    fs.renameSync(tmp, statePath(dir));
+}
+/** Load the state file or exit with guidance. */
+export function requireState(dir) {
+    const state = loadState(dir);
+    if (!state) {
+        throw new Error(`No ${STATE_FILE} found in ${dir}. Run \`virtualmatter pull <url-or-framing-id> ${dir}\` first, or pass --framing <id>.`);
+    }
+    return state;
+}

package/dist/sync.js

@@ -0,0 +1,251 @@
+/**
+ * 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.
+ */
+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";
+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 class SyncEngine {
+    client;
+    dir;
+    log;
+    now;
+    state;
+    /** relPath -> timestamp of a write WE made (pull), so the watcher skips it. */
+    selfWrites = new Map();
+    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;
+    }
+    get framingId() {
+        return this.state.framing_id;
+    }
+    abs(relPath) {
+        return path.join(this.dir, relPath);
+    }
+    persist() {
+        saveState(this.dir, this.state);
+    }
+    recordSelfWrite(relPath) {
+        this.selfWrites.set(relPath, this.now());
+    }
+    isSelfWrite(relPath) {
+        const t = this.selfWrites.get(relPath);
+        if (t === undefined)
+            return false;
+        if (this.now() - t > SELF_WRITE_GRACE_MS) {
+            this.selfWrites.delete(relPath);
+            return false;
+        }
+        return true;
+    }
+    async pullFile(relPath, etag) {
+        const { bytes, etag: gotEtag } = await this.client.get(relPath);
+        const absPath = this.abs(relPath);
+        fs.mkdirSync(path.dirname(absPath), { recursive: true });
+        this.recordSelfWrite(relPath);
+        fs.writeFileSync(absPath, bytes);
+        this.state.etags[relPath] = gotEtag ?? etag;
+        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.
+     */
+    async initialSync() {
+        const remote = await this.client.list();
+        let pulled = 0;
+        let pushed = 0;
+        const remotePaths = new Set();
+        for (const file of remote) {
+            if (isIgnoredPath(file.path))
+                continue;
+            remotePaths.add(file.path);
+            const known = this.state.etags[file.path];
+            const localExists = fs.existsSync(this.abs(file.path));
+            if (known !== file.etag || !localExists) {
+                await this.pullFile(file.path, file.etag);
+                pulled++;
+            }
+        }
+        // Local files the remote has never seen get created remotely.
+        for (const relPath of this.walkLocal()) {
+            if (remotePaths.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++;
+        }
+        return { pulled, pushed };
+    }
+    *walkLocal(rel = "") {
+        const absDir = path.join(this.dir, rel);
+        let entries;
+        try {
+            entries = fs.readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+            if (isIgnoredPath(relPath))
+                continue;
+            if (entry.isDirectory())
+                yield* this.walkLocal(relPath);
+            else if (entry.isFile())
+                yield relPath;
+        }
+    }
+    async pushFile(relPath, opts) {
+        const body = fs.readFileSync(this.abs(relPath));
+        const known = this.state.etags[relPath];
+        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;
+            this.persist();
+            this.log.info(`pushed ${relPath}`);
+        }
+        catch (err) {
+            if (err instanceof ConflictError) {
+                await this.handleConflict(relPath);
+                return;
+            }
+            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, "/");
+        if (isIgnoredPath(norm))
+            return;
+        if (this.isSelfWrite(norm))
+            return;
+        if (!fs.existsSync(this.abs(norm)))
+            return;
+        try {
+            await this.pushFile(norm);
+        }
+        catch (err) {
+            this.log.warn(`push of ${norm} failed: ${String(err)}`);
+        }
+    }
+    /** Watcher callback for a local delete. */
+    async handleLocalDelete(relPath) {
+        const norm = relPath.replace(/\\/g, "/");
+        if (isIgnoredPath(norm))
+            return;
+        if (this.isSelfWrite(norm))
+            return;
+        const known = this.state.etags[norm];
+        if (known === undefined)
+            return;
+        try {
+            await this.client.delete(norm, known);
+            delete this.state.etags[norm];
+            this.persist();
+            this.log.info(`deleted ${norm} remotely`);
+        }
+        catch (err) {
+            if (err instanceof ConflictError) {
+                await this.handleConflict(norm);
+                return;
+            }
+            this.log.warn(`remote delete of ${norm} failed: ${String(err)}`);
+        }
+    }
+    /**
+     * 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.
+     */
+    async pollOnce() {
+        const remote = await this.client.list();
+        const pulled = [];
+        for (const file of remote) {
+            if (isIgnoredPath(file.path))
+                continue;
+            if (this.state.etags[file.path] === file.etag && fs.existsSync(this.abs(file.path)))
+                continue;
+            await this.pullFile(file.path, file.etag);
+            pulled.push(file.path);
+            this.log.info(`pulled ${file.path}`);
+        }
+        return pulled;
+    }
+}
+/** 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 watcher = chokidar.watch(dir, {
+        ignoreInitial: true,
+        ignored: (p) => {
+            const rel = path.relative(dir, p).replace(/\\/g, "/");
+            return rel.length > 0 && isIgnoredPath(rel);
+        },
+    });
+    let queue = Promise.resolve();
+    const enqueue = (fn) => {
+        queue = queue.then(fn).catch((err) => console.warn(String(err)));
+    };
+    watcher.on("add", (p) => enqueue(() => engine.handleLocalChange(path.relative(dir, p))));
+    watcher.on("change", (p) => enqueue(() => engine.handleLocalChange(path.relative(dir, p))));
+    watcher.on("unlink", (p) => enqueue(() => engine.handleLocalDelete(path.relative(dir, p))));
+    const interval = setInterval(() => {
+        enqueue(async () => {
+            try {
+                await engine.pollOnce();
+            }
+            catch (err) {
+                console.warn(`remote poll failed: ${String(err)}`);
+            }
+        });
+    }, 3000);
+    await new Promise((resolve) => {
+        const stop = async () => {
+            clearInterval(interval);
+            await watcher.close();
+            console.log("\nsync stopped.");
+            resolve();
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+}
+export { loadState };

package/dist/urls.js

@@ -0,0 +1,62 @@
+/**
+ * Parse the URL shapes a user may paste and extract a framing id.
+ *
+ * Framing-shaped (id resolves locally):
+ *   /edit/<framingId>   /play/<framingId>   /m/<framingId>
+ * Project-shaped (v1 does not resolve these):
+ *   /g/<montageId>      /play/p/<montageId>
+ * Accepted on any virtualmatter.ai / virtualmatter.dev host, and a bare
+ * framing id (UUID) is accepted as-is.
+ */
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+function isVirtualmatterHost(host) {
+    const h = host.toLowerCase();
+    return (h === "virtualmatter.ai" ||
+        h.endsWith(".virtualmatter.ai") ||
+        h === "virtualmatter.dev" ||
+        h.endsWith(".virtualmatter.dev") ||
+        h === "localhost" ||
+        h === "127.0.0.1");
+}
+// Framing ids are nanoids (URL-safe alphabet, typically 21 chars),
+// case-SENSITIVE - never lowercase them. 15-32 keeps obvious typos and
+// full URLs out while accepting every id shape the platform mints.
+const NANOID_RE = /^[A-Za-z0-9_-]{15,32}$/;
+export function parseTarget(input) {
+    const trimmed = input.trim();
+    if (UUID_RE.test(trimmed)) {
+        return { kind: "framing", framingId: trimmed.toLowerCase() };
+    }
+    if (NANOID_RE.test(trimmed) && !trimmed.includes(".")) {
+        return { kind: "framing", framingId: trimmed };
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        return { kind: "invalid", reason: `Not a framing id or URL: ${trimmed}` };
+    }
+    if (!isVirtualmatterHost(url.hostname)) {
+        return { kind: "invalid", reason: `Not a Virtual Matter host: ${url.hostname}` };
+    }
+    const parts = url.pathname.split("/").filter((p) => p.length > 0);
+    // Project-level shapes first: /g/<montageId> and /play/p/<montageId>
+    if (parts.length >= 2 && parts[0] === "g" && parts[1]) {
+        return { kind: "project", montageId: parts[1] };
+    }
+    if (parts.length >= 3 && parts[0] === "play" && parts[1] === "p" && parts[2]) {
+        return { kind: "project", montageId: parts[2] };
+    }
+    // Framing shapes: /edit/<id>, /play/<id>, /m/<id>
+    if (parts.length >= 2 && parts[1] && ["edit", "play", "m"].includes(parts[0])) {
+        const id = parts[1];
+        if (UUID_RE.test(id)) {
+            return { kind: "framing", framingId: id.toLowerCase() };
+        }
+        return { kind: "framing", framingId: id };
+    }
+    return { kind: "invalid", reason: `Unrecognized Virtual Matter URL path: ${url.pathname}` };
+}
+/** Human guidance for project-shaped URLs (v1 keeps it simple). */
+export const PROJECT_URL_HELP = "That link points at a whole project, not a single framing. Open the project in your browser and copy the /edit/<id> link for the framing you want, then try again.";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "virtualmatter",
+  "version": "0.1.0",
+  "description": "CLI + MCP server for building with Virtual Matter - sync montage files, run Lua, capture screenshots, and wire coding agents into a live session.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "virtualmatter": "./dist/index.js",
+    "vm": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "chokidar": "^4.0.3",
+    "commander": "^14.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "homepage": "https://make.virtualmatter.ai/developers",
+  "keywords": [
+    "voxel",
+    "game-development",
+    "mcp",
+    "ai-agents",
+    "virtualmatter",
+    "atomontage"
+  ]
+}