@bitmagic/cli 0.1.52-dev.0 → 0.1.52-dev.2

package/dist/assets/file-kind.js

@@ -0,0 +1,180 @@
+/**
+ * What `bitmagic assets add <file>` makes of a filename, decided BEFORE anything is read, uploaded
+ * or written — so a file this lane cannot take costs nothing and leaves world.json untouched.
+ *
+ * The table mirrors the Creator's Assets-tab upload (`creator/src/vue/composables/useAssetsEditor.ts`
+ * `handleFileUpload` + `assetsUploadTypes.ts` `detectAssetType`) where the CLI can do the same
+ * thing, and refuses — by name, with where to go instead — where it cannot:
+ *
+ *  - `.gltf` is refused rather than accepted-and-broken: the engine voxelizes ONE fetched URL, and
+ *    a `.gltf` is a JSON index whose buffers and textures live in files beside it.
+ *  - `.vox`/`.qb` (MagicaVoxel/Qubicle import), `.fbx` (animation import), `.spz`/`.ply`/`.sog`
+ *    (splat transcode) and `.mp4` (video faststart) each need a conversion the Creator runs through
+ *    game-play-agent, which a CLI project cannot reach.
+ *
+ * Audio and raster images are uploaded AS THEY ARE. The Creator transcodes them to `.opus`/`.webp`
+ * for size; the engine decodes mp3/ogg/m4a through Web Audio and draws png/jpg like any browser,
+ * so the difference is bytes, not whether it works. `audioTranscodeNote` says so once.
+ */
+import * as path from 'path';
+import { CliError } from '../errors.js';
+const CREATOR_ONLY = {
+    vox: 'MagicaVoxel import',
+    qb: 'Qubicle import',
+    fbx: 'FBX animation import',
+    spz: 'Gaussian-splat transcode',
+    ply: 'Gaussian-splat transcode',
+    sog: 'Gaussian-splat transcode',
+    mp4: 'video',
+};
+const IMAGE_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+};
+const AUDIO_TYPES = {
+    opus: 'audio/ogg',
+    ogg: 'audio/ogg',
+    m4a: 'audio/mp4',
+    mp3: 'audio/mpeg',
+};
+/** Every extension `classifyAssetFile` accepts, for help text and the README. */
+export const ACCEPTED_EXTENSIONS = ['glb', 'vxl', 'png', 'jpg', 'jpeg', 'webp', 'opus', 'ogg', 'm4a', 'mp3', 'json'];
+export function fileExtension(filename) {
+    return path.extname(filename).slice(1).toLowerCase();
+}
+export function classifyAssetFile(filename, options) {
+    const extension = fileExtension(filename);
+    const base = path.basename(filename);
+    if (options.keepGlb && extension !== 'glb') {
+        throw new CliError(`--keep-glb only applies to a .glb file, and ${base} is not one. world.json is unchanged.`);
+    }
+    if (extension === 'glb') {
+        return options.keepGlb
+            ? { kind: 'glb-keep', assetType: 'glb', contentType: 'model/gltf-binary', extension }
+            : { kind: 'glb-voxelize', assetType: 'vxl', contentType: 'model/gltf-binary', extension };
+    }
+    if (extension === 'vxl') {
+        // The same content type the engine uploads its own bakes under (VoxelMessageHandlers.ts).
+        // api-server marks it compressible, so the PUT gzips.
+        return { kind: 'vxl', assetType: 'vxl', contentType: 'application/octet-stream', extension };
+    }
+    const imageType = IMAGE_TYPES[extension];
+    if (imageType !== undefined) {
+        return { kind: 'image', assetType: 'image', contentType: imageType, extension };
+    }
+    const audioType = AUDIO_TYPES[extension];
+    if (audioType !== undefined) {
+        return { kind: 'audio', assetType: 'audio', contentType: audioType, extension };
+    }
+    if (extension === 'json') {
+        return { kind: 'json', assetType: 'json', contentType: 'application/json', extension };
+    }
+    if (extension === 'gltf') {
+        throw new CliError(`${base} is a .gltf, which keeps its buffers and textures in files beside it — the game loads a `
+            + 'single URL. Export it as a self-contained .glb and add that instead. world.json is unchanged.');
+    }
+    const creatorOnly = CREATOR_ONLY[extension];
+    if (creatorOnly !== undefined) {
+        throw new CliError(`.${extension} (${creatorOnly}) needs a conversion this CLI does not run. `
+            + 'Upload it through the Creator\'s Assets tab instead. world.json is unchanged.');
+    }
+    throw new CliError(`Cannot add ${base}: this CLI takes ${ACCEPTED_EXTENSIONS.map((e) => `.${e}`).join(', ')}. `
+        + 'world.json is unchanged.');
+}
+/**
+ * The asset's name when `--name` is not given: the file's basename without its extension, which
+ * is what the Creator pre-fills its name prompt with.
+ */
+export function defaultAssetName(filename) {
+    return path.basename(filename).replace(/\.[^/.]+$/, '');
+}
+/**
+ * Characters that survive a path check but break the URL the object is served from, or the storage
+ * key itself. api-server builds `publicUrl` by concatenating the key onto the portal origin with no
+ * percent-encoding, so a `#` truncates the URL at a fragment and a `?` at a query — the asset then
+ * 404s at game load, long after a successful-looking upload. GCS rejects CR/LF in object names
+ * outright. Refused up front rather than escaped, so the name in world.json is the name on disk.
+ */
+// eslint-disable-next-line no-control-regex -- control characters are exactly what this rejects
+const URL_UNSAFE = /[#?%\u0000-\u001f\u007f]/;
+/** GCS caps an object key at 1024 bytes; the engine prefixes and suffixes the name inside one. */
+const MAX_NAME_LENGTH = 128;
+function describeUnsafe(value) {
+    const bad = URL_UNSAFE.exec(value)?.[0] ?? '';
+    const code = bad.charCodeAt(0);
+    return code < 0x20 || code === 0x7f ? `a control character (0x${code.toString(16)})` : `"${bad}"`;
+}
+/**
+ * A name the engine can build a filename from. `CREATE_ASSET_FROM_GLB_URL` uploads its bake as
+ * `<gameId>-<name>-<timestamp>.vxl`, and api-server refuses a filename carrying a separator or
+ * `..` — so a name that would trip that fails HERE, before the file has been uploaded and the
+ * browser launched, instead of as an opaque "Failed to upload VXL file" minutes later.
+ *
+ * The length cap and the URL-unsafe set are part of the same job: both produce a failure that only
+ * appears after the upload (or after a ten-minute bake), which is precisely what this is for.
+ */
+export function validateAssetName(name) {
+    const trimmed = name.trim();
+    if (trimmed === '')
+        throw new CliError('The asset name cannot be empty. world.json is unchanged.');
+    if (/[/\\]/.test(trimmed) || trimmed.includes('..')) {
+        throw new CliError(`The asset name ${JSON.stringify(name)} cannot contain a path separator or "..". world.json is unchanged.`);
+    }
+    if (URL_UNSAFE.test(trimmed)) {
+        throw new CliError(`The asset name ${JSON.stringify(name)} cannot contain ${describeUnsafe(trimmed)} — it ends up in `
+            + 'the uploaded file\'s URL. world.json is unchanged.');
+    }
+    if (trimmed.length > MAX_NAME_LENGTH) {
+        throw new CliError(`The asset name is ${trimmed.length} characters; keep it under ${MAX_NAME_LENGTH}. world.json is unchanged.`);
+    }
+    return trimmed;
+}
+/**
+ * The upload filename: a bare basename, which is all api-server accepts.
+ *
+ * Mirrors `sanitizeUploadFilename` in full — separators AND `..`, as three independent checks.
+ * `path.basename` strips `/` on POSIX but leaves `\`, so a legal `my\model.glb` used to pass here
+ * and then eat a network round-trip to be refused by the server with a message naming nothing the
+ * creator could act on. The URL-unsafe and length checks are here for the same reason as on the
+ * name above.
+ */
+export function uploadFilename(filePath) {
+    const base = path.basename(filePath);
+    if (base.includes('/') || base.includes('\\')) {
+        throw new CliError(`Rename ${JSON.stringify(base)} first: an upload filename cannot contain a path separator. `
+            + 'world.json is unchanged.');
+    }
+    if (base.includes('..')) {
+        throw new CliError(`Rename ${base} first: an upload filename cannot contain "..". world.json is unchanged.`);
+    }
+    if (URL_UNSAFE.test(base)) {
+        throw new CliError(`Rename ${JSON.stringify(base)} first: a filename cannot contain ${describeUnsafe(base)} — it ends up `
+            + 'in the uploaded file\'s URL. world.json is unchanged.');
+    }
+    if (base.length > MAX_NAME_LENGTH) {
+        throw new CliError(`Rename ${JSON.stringify(base)} first: keep the filename under ${MAX_NAME_LENGTH} characters. `
+            + 'world.json is unchanged.');
+    }
+    return base;
+}
+/**
+ * `asset_<timestamp>_<random>` — byte-compatible with the engine's `ObjectIdService.generateId`
+ * and with what api-server mints for the generators (`cli-assets.ts`), so an id minted here is
+ * indistinguishable from one minted anywhere else in the system.
+ */
+export function mintAssetId(now = Date.now, random = Math.random) {
+    return `asset_${now()}_${random().toString(36).substring(2, 8)}`;
+}
+/**
+ * Said once per audio upload that the Creator would have transcoded. The engine plays the file
+ * as-is; this is about download size, and it names the exact command rather than a vague "consider".
+ */
+export function audioTranscodeNote(extension) {
+    if (extension === 'opus')
+        return null;
+    return `Uploaded as .${extension}. The game plays it as-is; for a smaller download convert it first: `
+        + `ffmpeg -i in.${extension} -c:a libopus -b:a 96k out.opus`;
+}
+//# sourceMappingURL=file-kind.js.map

package/dist/assets/file-kind.js.map

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

package/dist/assets/list.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `bitmagic assets list` — the project's `assets[]`, as the dev view's assets panel sees it
+ * (`editor/server.ts` `GET /api/assets` reads the same array and nothing else).
+ */
+import { type JsonObject } from '../project/world-json.js';
+export interface AssetRow {
+    id: string;
+    name: string;
+    type: string;
+    size?: number;
+    /** Placed instances in `environmentObjects[]`. */
+    placed: number;
+    /**
+     * Every reference anywhere in world.json — placed instances plus levels, maps, doors, key items,
+     * village rosters.
+     *
+     * Reported alongside {@link placed} rather than folded into it because the two answer different
+     * questions, and counting only placed instances was actively misleading: a level asset showed
+     * `0`, an agent read that as "safe to delete", and `assets remove` then refused — or, with
+     * `--force`, removed the asset while leaving the level pointing at nothing.
+     */
+    references: number;
+}
+export declare function summarizeAssets(world: JsonObject): AssetRow[];
+export declare function formatSize(bytes: number | undefined): string;
+/** Fixed-width columns, no dependency, readable in a terminal and greppable by an agent. */
+export declare function formatAssetTable(rows: AssetRow[]): string;

package/dist/assets/list.js

@@ -0,0 +1,50 @@
+/**
+ * `bitmagic assets list` — the project's `assets[]`, as the dev view's assets panel sees it
+ * (`editor/server.ts` `GET /api/assets` reads the same array and nothing else).
+ */
+import { isJsonObject } from '../project/world-json.js';
+import { findAssetReferences } from './remove.js';
+export function summarizeAssets(world) {
+    const assets = Array.isArray(world.assets) ? world.assets : [];
+    return assets.filter(isJsonObject).map((asset) => {
+        const id = typeof asset.id === 'string' ? asset.id : '';
+        // The SAME scan `assets remove` refuses on, so the two commands cannot disagree about what
+        // counts as a reference.
+        const found = id === '' ? [] : findAssetReferences(world, id);
+        return {
+            id,
+            name: typeof asset.name === 'string' ? asset.name : '',
+            type: typeof asset.type === 'string' ? asset.type : '',
+            ...(typeof asset.size === 'number' ? { size: asset.size } : {}),
+            placed: found.filter((ref) => ref.placed).length,
+            references: found.length,
+        };
+    });
+}
+export function formatSize(bytes) {
+    if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
+        return '';
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/** Fixed-width columns, no dependency, readable in a terminal and greppable by an agent. */
+export function formatAssetTable(rows) {
+    if (rows.length === 0)
+        return 'No assets in world.json yet. `bitmagic assets add <file>` adds one.';
+    const header = { id: 'ID', name: 'NAME', type: 'TYPE', size: 'SIZE', placed: 'PLACED', references: 'REFS' };
+    const cells = rows.map((row) => ({
+        id: row.id, name: row.name, type: row.type, size: formatSize(row.size),
+        placed: String(row.placed), references: String(row.references),
+    }));
+    const width = (key) => Math.max(header[key].length, ...cells.map((cell) => cell[key].length));
+    const w = {
+        id: width('id'), name: width('name'), type: width('type'), size: width('size'), placed: width('placed'),
+    };
+    const line = (cell) => `${cell.id.padEnd(w.id)}  ${cell.name.padEnd(w.name)}  ${cell.type.padEnd(w.type)}  `
+        + `${cell.size.padStart(w.size)}  ${cell.placed.padStart(w.placed)}  ${cell.references}`;
+    return [line(header), ...cells.map(line)].join('\n');
+}
+//# sourceMappingURL=list.js.map

package/dist/assets/list.js.map

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

package/dist/assets/remove.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What `bitmagic assets remove <id>` does to world.json, decided before anything is written.
+ *
+ * Removal is world.json only. The uploaded bytes stay in storage — that is what the Creator's
+ * Remove and game-play-agent's `/api/remove-asset` do too (there is no delete endpoint on either
+ * server, and every upload is immutable-cached), so a published game that still points at the file
+ * keeps working.
+ *
+ * The one thing this does that the Creator's button does not: it looks for what still POINTS at
+ * the asset first. world.json references an asset by id under a handful of keys — placed objects'
+ * `assetId`, a level's `vwldAssetId`, a map's `mapAssetId`, doors, key items, towers — and a
+ * removed asset that any of them still names is a load error the creator finds later, in the
+ * browser, with nothing connecting it back to this command. So the scan is a generic walk for
+ * those keys rather than a list of known containers: a container added to the schema tomorrow is
+ * still caught. What it cannot see is game CODE (`engine.playSound(assetId)`), and the refusal
+ * says so.
+ *
+ * `--force` removes the asset and every placed instance in `environmentObjects[]` in the same
+ * atomic write, and reports the rest as warnings.
+ */
+import type { WorldJsonModification } from '@bitmagic/world-forger/pipeline/index.js';
+import { type JsonObject } from '../project/world-json.js';
+export interface AssetReference {
+    /** JSON-pointer-ish path to the referencing value, e.g. `environmentObjects[3].assetId`. */
+    path: string;
+    /**
+     * True when this is a placed instance in root `environmentObjects[]` — the one kind of reference
+     * `--force` can clean up by removing it alongside the asset.
+     *
+     * Recorded during the walk rather than recovered by re-parsing {@link path}: the path is a
+     * human-readable rendering, and deriving structure back out of it silently returns "no placed
+     * instances" the moment that rendering changes.
+     */
+    placed: boolean;
+}
+export interface RemovalPlan {
+    asset: JsonObject;
+    modifications: WorldJsonModification[];
+    /** Placed instances in `environmentObjects[]` — removed with the asset under `--force`. */
+    placedInstances: number;
+    /** References elsewhere in the document, which `--force` leaves in place and reports. */
+    otherReferences: AssetReference[];
+}
+/**
+ * Every place in the document where one of the reference keys holds `assetId`. The asset's own
+ * `assets[]` entry is skipped — its `id` is not a reference key, but a vehicle asset's own
+ * `vehicleFitment` might one day carry one, so the whole `assets[]` subtree is excluded outright.
+ */
+export declare function findAssetReferences(world: JsonObject, assetId: string): AssetReference[];
+export declare function planAssetRemoval(world: JsonObject, assetId: string, force: boolean): RemovalPlan;

package/dist/assets/remove.js

@@ -0,0 +1,91 @@
+import { CliError } from '../errors.js';
+import { isJsonObject } from '../project/world-json.js';
+/**
+ * Whether a key holds an asset id. Matched by SHAPE rather than by an enumerated list, because an
+ * enumerated list is exactly what went wrong: `buildingAssetIds` (required on every village
+ * hotspot) was missing, so removing a village's building asset reported zero references and left
+ * the world throwing `references unknown assetId(s)` at load.
+ *
+ * The shape covers `assetId` and every `<thing>AssetId` / `<thing>AssetIds` in the GameData types
+ * (`vwldAssetId`, `mapAssetId`, `characterAssetId`, `buildingAssetIds`, `audioAssetIds`, …), so a
+ * container OR a key added to the schema tomorrow is caught without editing this file.
+ */
+function isReferenceKey(key) {
+    return key === 'assetId' || /^[A-Za-z]\w*AssetIds?$/.test(key);
+}
+/**
+ * Does this value name the asset? Plural keys hold an ARRAY of ids, which a bare `===` could never
+ * match — the second half of the same bug.
+ */
+function namesAsset(value, assetId) {
+    if (typeof value === 'string')
+        return value === assetId;
+    return Array.isArray(value) && value.some((item) => item === assetId);
+}
+/** Root array of placed instances — the only references `--force` removes rather than reports. */
+const PLACED_OBJECTS_KEY = 'environmentObjects';
+/**
+ * Every place in the document where one of the reference keys holds `assetId`. The asset's own
+ * `assets[]` entry is skipped — its `id` is not a reference key, but a vehicle asset's own
+ * `vehicleFitment` might one day carry one, so the whole `assets[]` subtree is excluded outright.
+ */
+export function findAssetReferences(world, assetId) {
+    const found = [];
+    const walk = (value, path, inPlacedObjects) => {
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => walk(item, `${path}[${index}]`, inPlacedObjects));
+            return;
+        }
+        if (!isJsonObject(value))
+            return;
+        for (const [key, child] of Object.entries(value)) {
+            const childPath = path === '' ? key : `${path}.${key}`;
+            if (path === '' && key === 'assets')
+                continue;
+            if (isReferenceKey(key) && namesAsset(child, assetId)) {
+                found.push({ path: childPath, placed: inPlacedObjects && key === 'assetId' });
+                continue;
+            }
+            walk(child, childPath, inPlacedObjects || (path === '' && key === PLACED_OBJECTS_KEY));
+        }
+    };
+    walk(world, '', false);
+    return found;
+}
+export function planAssetRemoval(world, assetId, force) {
+    const assets = Array.isArray(world.assets) ? world.assets : [];
+    const asset = assets.find((item) => isJsonObject(item) && item.id === assetId);
+    if (asset === undefined) {
+        throw new CliError(`No asset with id "${assetId}" in this project's world.json. `
+            + '`bitmagic assets list` shows the ids. world.json is unchanged.');
+    }
+    const references = findAssetReferences(world, assetId);
+    const placed = references.filter((ref) => ref.placed);
+    const others = references.filter((ref) => !ref.placed);
+    if (references.length > 0 && !force) {
+        const name = typeof asset.name === 'string' ? asset.name : assetId;
+        const lines = references.slice(0, 8).map((ref) => `  - ${ref.path}`);
+        if (references.length > 8)
+            lines.push(`  - …and ${references.length - 8} more`);
+        throw new CliError(`"${name}" is still referenced ${references.length === 1 ? 'once' : `${references.length} times`} in world.json:\n`
+            + `${lines.join('\n')}\n`
+            + 'Removing it would leave those pointing at nothing. Re-run with --force to remove the asset '
+            + `and its ${placed.length} placed instance${placed.length === 1 ? '' : 's'} together`
+            + (others.length > 0 ? ' (the other references stay and are reported)' : '')
+            + '. Game code that names the id (playSound, spawnFromAsset, …) is not checked. world.json is unchanged.');
+    }
+    const modifications = [{
+            type: 'removeRoot',
+            path: ['assets'],
+            predicate: (item) => isJsonObject(item) && item.id === assetId,
+        }];
+    if (placed.length > 0) {
+        modifications.push({
+            type: 'removeRoot',
+            path: ['environmentObjects'],
+            predicate: (item) => isJsonObject(item) && item.assetId === assetId,
+        });
+    }
+    return { asset, modifications, placedInstances: placed.length, otherReferences: others };
+}
+//# sourceMappingURL=remove.js.map

package/dist/assets/remove.js.map

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

package/dist/assets/vxl-summary.d.ts

@@ -0,0 +1,23 @@
+export interface VxlSummary {
+    version: number;
+    minVoxelSize: number;
+    boundingBox: {
+        minX: number;
+        minY: number;
+        minZ: number;
+        maxX: number;
+        maxY: number;
+        maxZ: number;
+    };
+    fragmentCount: number;
+    /** Absent when the fragment table could not be walked to its end. */
+    voxelCount?: number;
+}
+/** True when the first four bytes are the VXL3 magic — cheap, no copy, no decompression. */
+export declare function isVxl3(bytes: Uint8Array): boolean;
+/**
+ * Read a VXL3 file's header. Returns `null` for anything that is not a well-formed VXL3 — a legacy
+ * JSON `.vxl`, a truncated file, an unknown compression id — so the caller can name the problem
+ * instead of writing an asset entry the engine would then fail to load.
+ */
+export declare function summarizeVxl(bytes: Uint8Array): VxlSummary | null;

package/dist/assets/vxl-summary.js

@@ -0,0 +1,103 @@
+/**
+ * The metadata a `.vxl` file carries in its own header, read here so `bitmagic assets add x.vxl`
+ * can record `boundingBox` / `voxelSize` / `voxelCount` the way the Creator's upload does — the
+ * Creator gets them from game-play-agent's `/api/analyze-asset` (`AssetsController.parseVxlV3Summary`),
+ * which a CLI project cannot reach, and this is the same read of the same bytes.
+ *
+ * Only what the fixed 48-byte body header states outright is trusted unconditionally: bounds,
+ * LOD-0 voxel size and fragment count. `voxelCount` is the sum of the LOD-0 fragments' leaf counts,
+ * found by walking the fragment table (its stride is `16 + leafCount × (7 + paletteIdxBytes)` for
+ * every version through v8 — the columnar and emissive/slot additions changed what is INSIDE a
+ * fragment and what follows the table, not its size). Should a future version change that, the
+ * walk runs off the end and the count is simply omitted rather than reported wrong.
+ *
+ * Layout reference: game/src/engine/VxlV3Format.ts (the wire-format doc comment at its top).
+ */
+import * as zlib from 'zlib';
+/** "VXL3" little-endian, as `VxlV3Format.ts` writes it. */
+const VXL3_MAGIC = 0x33_4c_58_56;
+const WRAPPER_BYTES = 5;
+const BODY_HEADER_BYTES = 48;
+/**
+ * The versions the engine's own decoder accepts (`VxlV3Format.ts`: 3 no-LOD, 4 LOD trailer,
+ * 5 columnar, 6 emissive, 7 slots, 8 per-LOD material columns, 9 block types).
+ *
+ * Checked rather than merely recorded: this header parse only reads the fixed 48-byte prologue,
+ * which a FUTURE version could keep byte-compatible while changing what follows. Accepting such a
+ * file would write an `assets[]` entry the vendored engine then throws on at load — the exact
+ * outcome returning `null` exists to prevent.
+ */
+const MIN_SUPPORTED_VERSION = 3;
+const MAX_SUPPORTED_VERSION = 9;
+/** True when the first four bytes are the VXL3 magic — cheap, no copy, no decompression. */
+export function isVxl3(bytes) {
+    if (bytes.byteLength < 4)
+        return false;
+    return new DataView(bytes.buffer, bytes.byteOffset, 4).getUint32(0, true) === VXL3_MAGIC;
+}
+/**
+ * Read a VXL3 file's header. Returns `null` for anything that is not a well-formed VXL3 — a legacy
+ * JSON `.vxl`, a truncated file, an unknown compression id — so the caller can name the problem
+ * instead of writing an asset entry the engine would then fail to load.
+ */
+export function summarizeVxl(bytes) {
+    // Only the WRAPPER is guaranteed to be on disk at full size — the body header's 48 bytes are
+    // measured after decompression below. A gzipped body compresses well under 48 bytes for a
+    // near-empty asset, and gating on the raw length here rejected such files as malformed.
+    if (!isVxl3(bytes) || bytes.byteLength < WRAPPER_BYTES)
+        return null;
+    const compressionId = bytes[4];
+    const payload = bytes.subarray(WRAPPER_BYTES);
+    let body;
+    if (compressionId === 1) {
+        try {
+            body = new Uint8Array(zlib.gunzipSync(payload));
+        }
+        catch {
+            return null;
+        }
+    }
+    else if (compressionId === 0) {
+        body = payload;
+    }
+    else {
+        return null;
+    }
+    if (body.byteLength < BODY_HEADER_BYTES)
+        return null;
+    const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+    const version = view.getUint32(0, true);
+    if (version < MIN_SUPPORTED_VERSION || version > MAX_SUPPORTED_VERSION)
+        return null;
+    const minVoxelSize = view.getFloat32(4, true);
+    const boundingBox = {
+        minX: view.getFloat32(16, true),
+        minY: view.getFloat32(20, true),
+        minZ: view.getFloat32(24, true),
+        maxX: view.getFloat32(28, true),
+        maxY: view.getFloat32(32, true),
+        maxZ: view.getFloat32(36, true),
+    };
+    const paletteIdxBytes = body[41];
+    if (paletteIdxBytes !== 1 && paletteIdxBytes !== 2)
+        return null;
+    const paletteCount = view.getUint16(42, true);
+    const fragmentCount = view.getUint16(44, true);
+    const summary = { version, minVoxelSize, boundingBox, fragmentCount };
+    // Best-effort leaf total. Every fragment header is 16 bytes (leafCount + aabb) followed by
+    // leafCount records of 7 + paletteIdxBytes bytes, however those bytes are arranged inside.
+    const leafBytes = 7 + paletteIdxBytes;
+    let cursor = BODY_HEADER_BYTES + paletteCount * 2;
+    let voxelCount = 0;
+    for (let f = 0; f < fragmentCount; f++) {
+        if (cursor + 16 > body.byteLength)
+            return summary;
+        const leafCount = view.getUint32(cursor, true);
+        voxelCount += leafCount;
+        cursor += 16 + leafCount * leafBytes;
+        if (cursor > body.byteLength)
+            return summary;
+    }
+    return { ...summary, voxelCount };
+}
+//# sourceMappingURL=vxl-summary.js.map

package/dist/assets/vxl-summary.js.map

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

package/dist/browser-gl.d.ts

@@ -43,13 +43,10 @@ export type RendererChoice = 'webgpu' | 'webgl';
 /**
  * Chrome flags for the GL backend, given the environment and platform.
  *
- * Software GL is used when `CI=true` (GitHub-hosted runners have no GPU, and asking ANGLE for a
- * Vulkan device there just wastes the startup) or when `BITMAGIC_BROWSER_SOFTWARE_GL=true`, the
- * escape hatch for a machine whose driver makes the GPU path worse than the software one.
- *
- * Everywhere else the real GPU is requested. The Vulkan flags are Linux-only because they are only
- * a fix there: macOS headless already reaches the GPU through ANGLE's Metal backend, and asking it
- * for Vulkan would take that away.
+ * Software GL is forced wherever `usesSoftwareGl` holds. Everywhere else the real GPU is
+ * requested. The Vulkan flags are Linux-only because they are only a fix there: macOS headless
+ * already reaches the GPU through ANGLE's Metal backend, and asking it for Vulkan would take that
+ * away.
  */
 export declare function browserGlArgs(env: Record<string, string | undefined>, platform?: Platform): string[];
 /**
@@ -61,12 +58,53 @@ export declare function browserGlArgs(env: Record<string, string | undefined>, p
  * verify exists to catch.
  */
 export declare function browserRendererArgs(env: Record<string, string | undefined>, renderer: RendererChoice, platform?: Platform): string[];
+/**
+ * How to launch Chrome for a renderer: headless or headed, and with which args.
+ *
+ * Headed exists for exactly one case — **WebGPU on Linux**, where headless Chrome cannot produce
+ * a real-GPU frame that a screenshot can see, in either compositing mode (measured on Chrome 151
+ * against an NVIDIA GPU with the Vulkan ICD installed):
+ *
+ *  - With `--disable-gpu-compositing` (the WebGL fix above), WebGPU reports `enabled_readback`,
+ *    Dawn reaches the native adapter and the game renders — but the presented frames never reach
+ *    the compositor OR the canvas: `page.screenshot()` and an in-page `drawImage(canvas)` both
+ *    come back black. Verify's black-frame detection then fails a healthy game.
+ *  - Without it, GPU compositing comes up and WebGPU reports `enabled` — but Dawn's adapter
+ *    request dies in the GPU process (`A valid external Instance reference no longer exists`),
+ *    `requestAdapter()` resolves null, and the game silently runs its WebGL2 fallback, which the
+ *    renderer probe rightly fails.
+ *
+ * Headed Chrome has neither problem: GPU compositing initialises against the display, Dawn gets
+ * the native adapter, and screenshots carry the real frame. So when webgpu is requested on Linux
+ * and a display exists, the plan is headed — with the window parked far off-screen so nothing
+ * flashes over the creator's desktop, and `--disable-backgrounding-occluded-windows` so Chrome
+ * does not throttle rendering in a window nobody can see. `--disable-gpu-compositing` is dropped
+ * in this mode: compositing is the point, and keeping the flag puts the run back in the black
+ * readback mode above.
+ *
+ * Everywhere else — webgl, macOS, CI, software GL, or a Linux box with no display (ssh, systemd,
+ * detached agents) — the plan is headless with the exact args `browserRendererArgs` always chose.
+ */
+export interface BrowserLaunchPlan {
+    headless: boolean;
+    args: string[];
+}
+export declare function browserLaunchPlan(env: Record<string, string | undefined>, renderer: RendererChoice, platform?: Platform): BrowserLaunchPlan;
+/**
+ * The plan for the automatic software-GL re-run: `browserLaunchPlan` as if
+ * `BITMAGIC_BROWSER_SOFTWARE_GL=true` had been set.
+ *
+ * Both verify paths (one-shot and `--watch`) relaunch through this after `shouldRetrySoftwareGl`
+ * says the machine's GPU stack is the likely culprit, so neither has to know which env var forces
+ * the fallback.
+ */
+export declare function softwareGlLaunchPlan(env: Record<string, string | undefined>, renderer: RendererChoice, platform?: Platform): BrowserLaunchPlan;
 /**
  * Whether a failed run is worth one automatic re-run on software GL.
  *
  * A lost WebGL context is a property of the machine's GPU/driver/compositor stack, not of the
  * game (see the file header) — the software path sidesteps that stack entirely. Pointless when
- * software GL was already in effect, which is what the env checks establish.
+ * software GL was already in effect, which is what `usesSoftwareGl` establishes.
  */
 export declare function shouldRetrySoftwareGl(observations: {
     webglContextLost: boolean;