@bitmagic/cli 0.1.1 → 0.1.3

package/dist/forge/upload-proxy.js

@@ -0,0 +1,134 @@
+/**
+ * A tiny loopback HTTP server that lets the ENGINE reach api-server's signed-upload endpoint.
+ *
+ * The engine uploads its own `.vxl`/`.vwld` bytes — hundreds of megabytes, so they never cross the
+ * message channel — by asking for a presigned PUT first. `StorageUploadUtil.ts` does that with a
+ * hardcoded path and no credentials:
+ *
+ *     fetch(`${getAgentUrl()}/api/generate-upload-url`, {
+ *         headers: { 'Content-Type': 'application/json' },   // no Authorization
+ *
+ * Neither half of that reaches api-server. The path it calls is game-play-agent's
+ * (`mastra/routes.ts`); api-server serves `POST /api/cli/v1/uploads/signed-url`. And every route
+ * under `/api/cli/v1/*` is Auth0 + Admin gated, while a browser page has no token — so pointing
+ * `agentUrl` straight at api-server answers 401 to every upload, which is exactly what the first
+ * end-to-end forge did: 14 archetypes dropped and the level bake failed after voxelizing all 392
+ * chunks.
+ *
+ * So the CLI bridges it instead of the engine changing. That direction is deliberate:
+ *
+ *  - **The engine cannot be the fix.** Published games carry frozen template code compiled against
+ *    the current engine (see the engine-API rule in AGENTS.md), and `StorageUploadUtil` is shared
+ *    by every lane. Teaching it to send a bearer token is a breaking change to all of them to serve
+ *    one.
+ *  - **The token must not enter the page.** It stays in this process. The forge browser runs with
+ *    `--disable-web-security`, so a token in page scope is worth strictly less than one outside it.
+ *
+ * Bound to 127.0.0.1 for the same reason: this server holds a creator's access token and answers
+ * with write credentials into Bitmagic's bucket. It must not be reachable off the machine.
+ *
+ * `gameId` is FORCED from the CLI's own project context rather than taken from the request body.
+ * api-server checks ownership regardless (`assertOwnsGame`, and the key is pinned to
+ * `worlds/v3/<gameId>/`), so this is defence in depth — but it is cheap, and it means a page that
+ * somehow holds the wrong id cannot even ask for the wrong namespace.
+ */
+import * as http from 'http';
+import { CliError } from '../errors.js';
+/** The path the ENGINE calls. Not api-server's — that is what this proxy translates. */
+export const ENGINE_UPLOAD_PATH = '/api/generate-upload-url';
+/** The api-server route it forwards to. */
+export const API_SERVER_UPLOAD_PATH = '/api/cli/v1/uploads/signed-url';
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.on('data', (chunk) => { body += String(chunk); });
+        req.on('end', () => resolve(body));
+        req.on('error', reject);
+    });
+}
+/**
+ * CORS is answered explicitly rather than relying on `--disable-web-security`. The flag is there
+ * for the presigned PUT to GCS, not as this proxy's security model, and a request the browser
+ * refuses to make is indistinguishable from a server that is down.
+ */
+function writeCors(res) {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+}
+export async function startUploadProxy(options) {
+    const log = options.log ?? (() => { });
+    const doFetch = options.fetchImpl ?? fetch;
+    const apiBase = options.apiUrl.replace(/\/$/, '');
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            writeCors(res);
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204).end();
+                return;
+            }
+            if (req.method !== 'POST' || req.url !== ENGINE_UPLOAD_PATH) {
+                // Named rather than silent: an engine that starts calling a different path should show up
+                // as this line in the forge log, not as a mute upload failure.
+                log(`[upload-proxy] ignoring ${req.method ?? '?'} ${req.url ?? '?'}`);
+                res.writeHead(404, { 'Content-Type': 'application/json' })
+                    .end(JSON.stringify({ error: 'Not found' }));
+                return;
+            }
+            let parsed = {};
+            try {
+                const raw = await readBody(req);
+                if (raw)
+                    parsed = JSON.parse(raw);
+            }
+            catch {
+                res.writeHead(400, { 'Content-Type': 'application/json' })
+                    .end(JSON.stringify({ error: 'Request body must be JSON' }));
+                return;
+            }
+            try {
+                const upstream = await doFetch(`${apiBase}${API_SERVER_UPLOAD_PATH}`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${options.token}`,
+                    },
+                    // `noCache` is dropped: api-server pins its own immutable cacheControl. gameId is ours,
+                    // not the page's — see the header.
+                    body: JSON.stringify({
+                        gameId: options.gameId,
+                        filename: parsed.filename,
+                        contentType: parsed.contentType,
+                    }),
+                });
+                const text = await upstream.text();
+                if (!upstream.ok) {
+                    log(`[upload-proxy] api-server refused ${String(parsed.filename ?? '?')}: ${upstream.status} ${text.slice(0, 200)}`);
+                }
+                res.writeHead(upstream.status, { 'Content-Type': 'application/json' }).end(text);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                log(`[upload-proxy] could not reach api-server: ${message}`);
+                res.writeHead(502, { 'Content-Type': 'application/json' })
+                    .end(JSON.stringify({ error: `Could not reach api-server: ${message}` }));
+            }
+        })();
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (address === null || typeof address === 'string') {
+        server.close();
+        throw new CliError('The upload proxy could not bind a local port, so the level cannot be baked.');
+    }
+    const url = `http://127.0.0.1:${address.port}`;
+    log(`Upload proxy on ${url} → ${apiBase}${API_SERVER_UPLOAD_PATH}`);
+    return {
+        url,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+//# sourceMappingURL=upload-proxy.js.map

package/dist/forge/upload-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-proxy.js","sourceRoot":"","sources":["../../src/forge/upload-proxy.ts"],"names":[],"mappings":"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"}

package/dist/generate/stream.d.ts

@@ -1,15 +1,6 @@
 import type { WorldPatch } from '@bitmagic/asset-core';
 import type { Environment } from '../config/environments.js';
-export interface SseEvent {
-    event: string;
-    data: unknown;
-}
-/**
- * Pure, synchronous parse of a full set of chunks — cheap and exhaustive to test. Production
- * streaming uses the same underlying buffer (`createSseFrameBuffer`) one network read at a time,
- * via `requestGeneration`, so this function is not itself on that path.
- */
-export declare function parseSseChunks(chunks: string[]): SseEvent[];
+export { parseSseChunks, type SseEvent } from '../http/sse.js';
 export interface GenerationOutcome {
     success: boolean;
     message: string;

package/dist/generate/stream.js

@@ -1,66 +1,9 @@
 import { CliError } from '../errors.js';
-/**
- * The unit of `event:`/`data:` lines terminated by a blank line, per the SSE wire format
- * `api-server/src/cli/cli-assets.ts` writes. Splits on `\n`, joining multiple `data:` lines (the
- * spec allows more than one) with `\n` before parsing as JSON. A leading `:` line (the server's
- * `: keepalive` comment) carries no `data:`, so it naturally produces no event.
- */
-function parseFrame(frame) {
-    let eventName = 'message';
-    const dataLines = [];
-    for (const line of frame.split('\n')) {
-        if (line.startsWith('event:')) {
-            eventName = line.slice('event:'.length).trim();
-        }
-        else if (line.startsWith('data:')) {
-            dataLines.push(line.slice('data:'.length).trim());
-        }
-        // Any other line (including a `:`-prefixed comment, or blank) carries no event data.
-    }
-    if (dataLines.length === 0)
-        return null;
-    return { event: eventName, data: JSON.parse(dataLines.join('\n')) };
-}
-/**
- * Incremental frame buffer: SSE frames arrive in arbitrary chunks over the wire — one frame can
- * span two reads, and two frames can arrive in one — so this accumulates bytes and only emits
- * events once a full `\n\n`-delimited frame is available. The trailing, not-yet-delimited
- * remainder stays in `buffer` for the next push. Shared by both `parseSseChunks` (fed the whole
- * chunk array at once) and `requestGeneration` (fed one chunk per network read), so the two
- * cannot drift apart.
- */
-function createSseFrameBuffer() {
-    let buffer = '';
-    return {
-        push(chunk) {
-            buffer += chunk;
-            const frames = buffer.split('\n\n');
-            // The last element is either '' (buffer ended exactly on a delimiter) or an incomplete
-            // trailing frame — either way it is not yet a complete frame, so keep it buffered.
-            buffer = frames.pop() ?? '';
-            const events = [];
-            for (const frame of frames) {
-                const event = parseFrame(frame);
-                if (event)
-                    events.push(event);
-            }
-            return events;
-        },
-    };
-}
-/**
- * Pure, synchronous parse of a full set of chunks — cheap and exhaustive to test. Production
- * streaming uses the same underlying buffer (`createSseFrameBuffer`) one network read at a time,
- * via `requestGeneration`, so this function is not itself on that path.
- */
-export function parseSseChunks(chunks) {
-    const frameBuffer = createSseFrameBuffer();
-    const events = [];
-    for (const chunk of chunks) {
-        events.push(...frameBuffer.push(chunk));
-    }
-    return events;
-}
+import { createSseFrameBuffer } from '../http/sse.js';
+// The frame buffer and its parser moved to ../http/sse.ts when `bitmagic forge` gained a second
+// consumer of the identical wire format. Re-exported from here so this module's own callers and
+// tests are unaffected by that move.
+export { parseSseChunks } from '../http/sse.js';
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }

package/dist/generate/stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/generate/stream.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/generate/stream.ts"],"names":[],"mappings":"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"}

package/dist/http/sse.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The SSE wire format the CLI-lane endpoints speak (`api-server/src/cli/cli-assets.ts`,
+ * `cli-forge.ts`): `event:` / `data:` lines terminated by a blank line, with `: keepalive`
+ * comment lines interleaved.
+ *
+ * Extracted from `generate/stream.ts` — which still re-exports `parseSseChunks` so its own
+ * tests and callers are unchanged — because `forge/stream.ts` consumes the identical format
+ * from a different endpoint. Two copies of a frame buffer that must agree byte-for-byte with
+ * one server is exactly the kind of thing that drifts silently: a fix to one (a multi-line
+ * `data:`, a chunk boundary mid-frame) would not reach the other, and the symptom would be a
+ * dropped terminal frame on one command only.
+ */
+export interface SseEvent {
+    event: string;
+    data: unknown;
+}
+/**
+ * Incremental frame buffer: SSE frames arrive in arbitrary chunks over the wire — one frame can
+ * span two reads, and two frames can arrive in one — so this accumulates bytes and only emits
+ * events once a full `\n\n`-delimited frame is available. The trailing, not-yet-delimited
+ * remainder stays in `buffer` for the next push.
+ */
+export declare function createSseFrameBuffer(): {
+    push: (chunk: string) => SseEvent[];
+};
+/**
+ * Pure, synchronous parse of a full set of chunks — cheap and exhaustive to test. Production
+ * streaming uses the same underlying buffer one network read at a time, so this function is not
+ * itself on that path.
+ */
+export declare function parseSseChunks(chunks: string[]): SseEvent[];
+/**
+ * Read an SSE response body to completion, handing every parsed event to `onEvent`. Stops early
+ * — and returns `true` — the moment `onEvent` reports the terminal frame arrived, so a server
+ * that holds the connection open after its result does not stall the command.
+ *
+ * Returns `false` when the stream ended with no terminal frame: a truncated connection, which
+ * every caller must report as "not a confirmed failure" rather than as a clean empty result.
+ */
+export declare function consumeSseStream(body: ReadableStream<Uint8Array>, onEvent: (event: SseEvent) => boolean): Promise<boolean>;

package/dist/http/sse.js

@@ -0,0 +1,98 @@
+/**
+ * The SSE wire format the CLI-lane endpoints speak (`api-server/src/cli/cli-assets.ts`,
+ * `cli-forge.ts`): `event:` / `data:` lines terminated by a blank line, with `: keepalive`
+ * comment lines interleaved.
+ *
+ * Extracted from `generate/stream.ts` — which still re-exports `parseSseChunks` so its own
+ * tests and callers are unchanged — because `forge/stream.ts` consumes the identical format
+ * from a different endpoint. Two copies of a frame buffer that must agree byte-for-byte with
+ * one server is exactly the kind of thing that drifts silently: a fix to one (a multi-line
+ * `data:`, a chunk boundary mid-frame) would not reach the other, and the symptom would be a
+ * dropped terminal frame on one command only.
+ */
+/**
+ * One `\n\n`-delimited frame. Joins multiple `data:` lines (the spec allows more than one)
+ * with `\n` before parsing as JSON. A leading `:` line (the server's `: keepalive` comment)
+ * carries no `data:`, so it naturally produces no event.
+ */
+function parseFrame(frame) {
+    let eventName = 'message';
+    const dataLines = [];
+    for (const line of frame.split('\n')) {
+        if (line.startsWith('event:')) {
+            eventName = line.slice('event:'.length).trim();
+        }
+        else if (line.startsWith('data:')) {
+            dataLines.push(line.slice('data:'.length).trim());
+        }
+        // Any other line (including a `:`-prefixed comment, or blank) carries no event data.
+    }
+    if (dataLines.length === 0)
+        return null;
+    return { event: eventName, data: JSON.parse(dataLines.join('\n')) };
+}
+/**
+ * Incremental frame buffer: SSE frames arrive in arbitrary chunks over the wire — one frame can
+ * span two reads, and two frames can arrive in one — so this accumulates bytes and only emits
+ * events once a full `\n\n`-delimited frame is available. The trailing, not-yet-delimited
+ * remainder stays in `buffer` for the next push.
+ */
+export function createSseFrameBuffer() {
+    let buffer = '';
+    return {
+        push(chunk) {
+            buffer += chunk;
+            const frames = buffer.split('\n\n');
+            // The last element is either '' (buffer ended exactly on a delimiter) or an incomplete
+            // trailing frame — either way it is not yet a complete frame, so keep it buffered.
+            buffer = frames.pop() ?? '';
+            const events = [];
+            for (const frame of frames) {
+                const event = parseFrame(frame);
+                if (event)
+                    events.push(event);
+            }
+            return events;
+        },
+    };
+}
+/**
+ * Pure, synchronous parse of a full set of chunks — cheap and exhaustive to test. Production
+ * streaming uses the same underlying buffer one network read at a time, so this function is not
+ * itself on that path.
+ */
+export function parseSseChunks(chunks) {
+    const frameBuffer = createSseFrameBuffer();
+    const events = [];
+    for (const chunk of chunks) {
+        events.push(...frameBuffer.push(chunk));
+    }
+    return events;
+}
+/**
+ * Read an SSE response body to completion, handing every parsed event to `onEvent`. Stops early
+ * — and returns `true` — the moment `onEvent` reports the terminal frame arrived, so a server
+ * that holds the connection open after its result does not stall the command.
+ *
+ * Returns `false` when the stream ended with no terminal frame: a truncated connection, which
+ * every caller must report as "not a confirmed failure" rather than as a clean empty result.
+ */
+export async function consumeSseStream(body, onEvent) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const frameBuffer = createSseFrameBuffer();
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            return false;
+        // `{ stream: true }` retains any trailing partial multi-byte UTF-8 sequence inside the
+        // decoder itself, so a character split across two network chunks decodes correctly once its
+        // remaining bytes arrive in the next read, instead of emitting U+FFFD.
+        const text = decoder.decode(value, { stream: true });
+        for (const event of frameBuffer.push(text)) {
+            if (onEvent(event))
+                return true;
+        }
+    }
+}
+//# sourceMappingURL=sse.js.map

package/dist/http/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/http/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH;;;;GAIG;AACH,SAAS,UAAU,CAAC,KAAa;IAC/B,IAAI,SAAS,GAAG,SAAS,CAAC;IAC1B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACjD,CAAC;aAAM,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,qFAAqF;IACvF,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAY,EAAE,CAAC;AACjF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,OAAO;QACL,IAAI,CAAC,KAAa;YAChB,MAAM,IAAI,KAAK,CAAC;YAChB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACpC,uFAAuF;YACvF,mFAAmF;YACnF,MAAM,GAAG,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAe,EAAE,CAAC;YAC9B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;gBAChC,IAAI,KAAK;oBAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAChC,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAgB;IAC7C,MAAM,WAAW,GAAG,oBAAoB,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAgC,EAChC,OAAqC;IAErC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,MAAM,WAAW,GAAG,oBAAoB,EAAE,CAAC;IAE3C,SAAS,CAAC;QACR,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,IAAI;YAAE,OAAO,KAAK,CAAC;QAEvB,uFAAuF;QACvF,4FAA4F;QAC5F,uEAAuE;QACvE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,IAAI,OAAO,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;QAClC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/local-port.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The port window the platform's bucket CORS policy allowlists as an origin.
+ *
+ * A scaffolded project fetches its forged level (`.vwld`) and its GLBs from the portal CDN, so a
+ * project served on localhost is making CROSS-ORIGIN requests for them. The bucket answers with
+ * `Access-Control-Allow-Origin` only for the origins named in its CORS config — the portal and
+ * creator hosts, plus `http://localhost:3000`–`3199` (roleverse-infra,
+ * the portal-cdn terragrunt config per environment). `bitmagic dev` sits inside that window at
+ * 3010; anything that asks the OS for an ephemeral port (`listen(0)` → 49xxx+) falls outside it.
+ *
+ * The failure is quiet and easy to misread. The fetch is blocked, `WorldGenerator` falls back to
+ * an empty voxel world, the level's terrain simply is not there, and the symptom is a player
+ * falling through the floor forever — which reads as a broken forge, not a blocked request. The
+ * forge's own browser hides it too, because it runs with `--disable-web-security` for the presigned
+ * PUTs, so uploads and reads both succeed there while a normal browser fails.
+ */
+export declare const CORS_ALLOWED_PORT_MIN = 3000;
+export declare const CORS_ALLOWED_PORT_MAX = 3199;
+/**
+ * A free port the CDN will serve assets to, or `null` when the whole window is taken.
+ *
+ * Returning `null` rather than silently falling back to an ephemeral port is deliberate: the
+ * caller can then say what the consequence is, instead of the run proceeding to a level with no
+ * terrain and no explanation.
+ *
+ * The scan starts at a pseudo-random offset so two concurrent runs do not both take 3000 and race;
+ * `tryListen` closing before the caller binds leaves a window either way, which is why callers
+ * must handle a bind failure rather than trusting this.
+ */
+export declare function reserveCorsAllowedPort(): Promise<number | null>;

package/dist/local-port.js

@@ -0,0 +1,53 @@
+import * as net from 'net';
+/**
+ * The port window the platform's bucket CORS policy allowlists as an origin.
+ *
+ * A scaffolded project fetches its forged level (`.vwld`) and its GLBs from the portal CDN, so a
+ * project served on localhost is making CROSS-ORIGIN requests for them. The bucket answers with
+ * `Access-Control-Allow-Origin` only for the origins named in its CORS config — the portal and
+ * creator hosts, plus `http://localhost:3000`–`3199` (roleverse-infra,
+ * the portal-cdn terragrunt config per environment). `bitmagic dev` sits inside that window at
+ * 3010; anything that asks the OS for an ephemeral port (`listen(0)` → 49xxx+) falls outside it.
+ *
+ * The failure is quiet and easy to misread. The fetch is blocked, `WorldGenerator` falls back to
+ * an empty voxel world, the level's terrain simply is not there, and the symptom is a player
+ * falling through the floor forever — which reads as a broken forge, not a blocked request. The
+ * forge's own browser hides it too, because it runs with `--disable-web-security` for the presigned
+ * PUTs, so uploads and reads both succeed there while a normal browser fails.
+ */
+export const CORS_ALLOWED_PORT_MIN = 3000;
+export const CORS_ALLOWED_PORT_MAX = 3199;
+function tryListen(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(null));
+        server.listen(port, '127.0.0.1', () => {
+            const address = server.address();
+            const bound = address !== null && typeof address !== 'string' ? address.port : null;
+            server.close(() => resolve(bound));
+        });
+    });
+}
+/**
+ * A free port the CDN will serve assets to, or `null` when the whole window is taken.
+ *
+ * Returning `null` rather than silently falling back to an ephemeral port is deliberate: the
+ * caller can then say what the consequence is, instead of the run proceeding to a level with no
+ * terrain and no explanation.
+ *
+ * The scan starts at a pseudo-random offset so two concurrent runs do not both take 3000 and race;
+ * `tryListen` closing before the caller binds leaves a window either way, which is why callers
+ * must handle a bind failure rather than trusting this.
+ */
+export async function reserveCorsAllowedPort() {
+    const span = CORS_ALLOWED_PORT_MAX - CORS_ALLOWED_PORT_MIN + 1;
+    const start = Math.floor(Math.random() * span);
+    for (let i = 0; i < span; i += 1) {
+        const port = CORS_ALLOWED_PORT_MIN + ((start + i) % span);
+        const bound = await tryListen(port);
+        if (bound !== null)
+            return bound;
+    }
+    return null;
+}
+//# sourceMappingURL=local-port.js.map

package/dist/local-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-port.js","sourceRoot":"","sources":["../src/local-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAE3B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAE1C,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE;YACpC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACpF,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAC1C,MAAM,IAAI,GAAG,qBAAqB,GAAG,qBAAqB,GAAG,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,qBAAqB,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;IACnC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/scaffold/project-files.js

@@ -8,20 +8,60 @@ const DEPENDENCIES = {
     i18next: '^24.2.3',
     'i18next-browser-languagedetector': '^8.0.4',
     jszip: '^3.10.1',
-    three: '^0.183.0',
+    three: '^0.185.1',
 };
 const DEV_DEPENDENCIES = {
     '@types/node': '^24.10.0',
-    '@types/three': '^0.183.0',
+    '@types/three': '^0.185.4',
     // engine/types/ammo.d.ts opens with a triple-slash reference to this package's ambient types.
     'ammojs-typed': '^1.0.6',
+    // Declares `navigator.gpu`, which the engine reads to choose its renderer backend. Named in
+    // tsconfig's `types` too — see the note there for why installing it is not enough.
+    '@webgpu/types': '^0.1.69',
     typescript: '^5.9.2',
     vite: '^7.3.1',
 };
+/**
+ * The three.js release every `three*` import map entry below resolves to. Written once because
+ * the entries repeat it eight times, including four times inside the `three` shim, and a bump
+ * that updates some copies but not others splits the engine across two module instances — the
+ * exact failure the comments below describe.
+ */
+const THREE_VERSION = '0.185.1';
+/**
+ * `three` resolves to a shim, not straight to the webgpu build. r185's three.webgpu.js exports
+ * neither `UniformsUtils` (which every classic postprocessing pass imports from `three`) nor
+ * `ShaderLib`/`UniformsLib` (`lines/LineMaterial.js`), so the vendored engine — which imports
+ * those passes statically in GameEngine.ts — fails to load with "The requested module 'three'
+ * does not provide an export named 'UniformsUtils'". The shim re-exports the webgpu build from
+ * the SAME URL as the `three/webgpu` entry, so it stays ONE module instance, and adds the
+ * missing names from three's own src. Absolute URLs only: a data: module has no base URL and so
+ * cannot resolve bare or relative specifiers. Keep in step with game/index.html.
+ */
+const THREE_SHIM = [
+    'data:text/javascript,',
+    `export*from'https://esm.sh/three@${THREE_VERSION}/webgpu';`,
+    `export{UniformsUtils}from'https://esm.sh/three@${THREE_VERSION}/src/renderers/shaders/UniformsUtils.js';`,
+    `export{ShaderLib}from'https://esm.sh/three@${THREE_VERSION}/src/renderers/shaders/ShaderLib.js';`,
+    `export{UniformsLib}from'https://esm.sh/three@${THREE_VERSION}/src/renderers/shaders/UniformsLib.js'`,
+].join('');
 /** Resolved in the browser from a CDN, not from node_modules — see the design's import-map note. */
 const CDN_IMPORTS = {
-    three: 'https://esm.sh/three@0.182.0',
-    'three/': 'https://esm.sh/three@0.182.0/',
+    // `three` and `three/webgpu` are ONE module instance (see THREE_SHIM). Pointed at separate
+    // builds (core + webgpu) they are two, and r185's LightsNode then fails to recognise lights
+    // built by the other instance — the scene renders unlit. Keep in step with game/index.html.
+    three: THREE_SHIM,
+    'three/webgpu': `https://esm.sh/three@${THREE_VERSION}/webgpu`,
+    'three/tsl': `https://esm.sh/three@${THREE_VERSION}/tsl`,
+    // The addon entries use esm.sh's `*` build, which keeps `three` a BARE specifier so addons
+    // resolve back through this map. Plain esm.sh inlines its own copy of three, which shares no
+    // module with the webgpu build: GLTFLoader then hands back Meshes from a second Mesh class and
+    // the engine's `instanceof THREE.Mesh` scans find nothing. Same one-instance rule as above.
+    // The classic WebGL addons are not excepted — the shim, not a pinned inlined-three build, is
+    // what gives them the UniformsUtils / ShaderLib / UniformsLib they import from bare `three`.
+    'three/addons/': `https://esm.sh/*three@${THREE_VERSION}/addons/`,
+    'three/examples/jsm/': `https://esm.sh/*three@${THREE_VERSION}/examples/jsm/`,
+    'three/': `https://esm.sh/three@${THREE_VERSION}/`,
     '@dimforge/rapier3d-compat': 'https://esm.sh/@dimforge/rapier3d-compat@0.19.3',
     '@dimforge/rapier2d-compat': 'https://esm.sh/@dimforge/rapier2d-compat@0.19.3',
     i18next: 'https://esm.sh/i18next@24.2.3',
@@ -72,7 +112,14 @@ export function renderTsconfig() {
             noImplicitAny: true,
             resolveJsonModule: true,
             sourceMap: true,
-            types: [],
+            // `types: []` opts out of auto-including every @types package — deliberate, because the
+            // vendored engine ships its own and a stray global would shadow them. The consequence is
+            // that a package whose whole job is a GLOBAL augmentation has to be named here or it is
+            // invisible: `@webgpu/types` declares `navigator.gpu`, which the engine reads to pick its
+            // renderer backend (`engine/GameEngine.ts`). Without it a scaffolded project fails to
+            // type-check with "Property 'gpu' does not exist on type 'Navigator'" — the engine's own
+            // package.json carries the dependency, so nothing catches this in the monorepo.
+            types: ['@webgpu/types'],
             typeRoots: ['engine/types', 'node_modules/@types', 'node_modules/ammojs-typed/ammo/ambient'],
         },
         include: ['src/**/*', 'engine/**/*'],
@@ -245,10 +292,43 @@ Four things worth knowing before you use these:
 4. **A running \`bitmagic dev\` will not show the new asset until the browser reloads.** The
    command reminds you.
 
-**Not available from the CLI yet:** 3D models, voxel assets and block types. Those require a
-browser to voxelize and upload, which this toolchain does not yet run. Do not try to work around
-it by hand-editing \`world.json\` to point at a model you have not generated — the asset will not
-exist and the game will fail to load it.
+**Not available as \`generate\` subcommands:** individual 3D models, voxel assets and block types.
+Those need a browser to voxelize and upload. Do not work around it by hand-editing
+\`world.json\` to point at a model you have not generated — the asset will not exist and the game
+will fail to load it.
+
+## Forging a whole level
+
+\`\`\`
+bitmagic forge --prompt "a ruined desert temple with a central courtyard"
+\`\`\`
+
+This designs a scene, builds its geometry, bakes it to voxels and writes the finished level —
+terrain, props, spawn points — into \`src/work/world.json\`. Add \`--city\`, \`--dungeon\`,
+\`--platformer\` or \`--freeform\` (at most one) for a different kind of place; omit them all for
+natural terrain.
+
+Five things worth knowing:
+
+1. **It is slow and it is expensive.** A forge runs for many minutes — the level bake alone can
+   take twenty — and costs considerably more than any single \`generate\`. Run it once,
+   deliberately. Progress is printed throughout, the bake included.
+2. **It needs Google Chrome installed.** The bake runs in a real headless browser, because
+   voxelizing is the engine's own code. The command builds and serves the project itself, so you
+   do not need \`bitmagic dev\` running and it will not collide with one that is.
+3. **It rewrites large parts of \`world.json\`** (assets, environmentObjects, the level registry,
+   spawn points), so re-read the file afterwards if you were editing it. The command prints which
+   paths it changed. It also drops a \`forged-heightfield.json\` beside it, which later placements
+   use to sit objects on the new terrain.
+4. **Every failure says whether \`world.json\` changed** — and it only ever changes on the final
+   step, all at once. A failure before that leaves the project exactly as it was.
+5. **Resume rather than re-run.** The command prints a job id. If it fails after the design
+   succeeded, \`bitmagic forge --resume <jobId>\` skips the steps already paid for. The failure
+   message says when resuming is worth it, and when the failure is deterministic and you should
+   change the prompt instead.
+
+Afterwards run \`bitmagic dev\` and actually walk the level — one that loads is not necessarily
+one you can move through.
 `;
 }
 export function renderGenerateSkill() {