@bitmagic/cli 0.1.59-dev.2 → 0.1.59-dev.4

package/README.md

@@ -204,6 +204,7 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic generate <skybox\|background\|block-type\|sound\|image\|character\|animation\|model\|prop\|vehicle> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. `model` mints a **new** 3D object from a prompt, `prop` upgrades an existing placeholder **in place** (both produce voxels directly; `--mesh` takes the older mesh path), `vehicle` adds a new drivable one, `animation` takes a parameter spec rather than a prompt, `block-type` registers a custom voxel block — see below. `skybox` and `background` write the **same** field: pick one. |
 | `bitmagic assets add <file> [--name <n>] [--asset-id <id>] [--keep-glb] [--voxel-size <m>] [--max-voxel-size <m>] [--height <m>] [--hollow\|--solid] [--force]` | Upload **your own** file — `.glb`, `.vxl`, `.png/.jpg/.webp`, `.opus/.ogg/.m4a/.mp3`, `.json` — into the game's assets and write its entry into `src/work/world.json`. A `.glb` is voxelized in a headless browser (Chrome + a free port in 3000–3199, like `prop`) unless `--keep-glb`. Free — no sparks. See **Adding your own assets** below. |
 | `bitmagic assets list` | The assets in `world.json`: id, name, type, size, placed instances, and total references. Local, no network. |
+| `bitmagic assets materials <assetId> [--set <file.json>] [--auto] [--clear]` | Show what an asset's voxels look like, or say what they are **made of** — so a sword's steel blade shines and its leather grip does not. With no flag it prints the asset's colour groups; `--set` applies your verdicts; `--auto` lets a model decide (what `generate prop` and `generate model` already do on their own); `--clear` removes them. Free — no sparks, nothing generated. See **Voxel materials** below. |
 | `bitmagic assets remove <assetId> [--force]` | Remove an asset from `world.json` (the uploaded file stays in storage). Refuses while anything in `world.json` still references it; `--force` removes the asset and its placed instances together. |
 | `bitmagic cover [--prompt "..."] [--force] [--no-start-screen]` | Generate the game's cover art from `GAME-DESIGN.md`: sets the start screen, saves `.bitmagic/cover.webp`, becomes the publish thumbnail. Costs sparks. |
 | `bitmagic reference <make\|accept\|show\|clear> ...` | Make a concept image of the game's world, iterate until it is right, and `accept` one — the accepted image becomes the default style reference for `generate skybox\|background\|block-type\|image`, `cover` and `forge`. Only `make` costs sparks (priced like an image). See **Reference image** below. |
@@ -774,6 +775,104 @@ whose vendored engine predates voxel masters takes the mesh path regardless, and
 If the bake fails after the source exists, the error prints the exact command to retry the browser
 step **without paying again** — `--master-url …` for voxels, `--glb-url …` for a mesh.
 
+## Voxel materials
+
+A generated voxel asset carries colours and nothing else, so every voxel shades identically: a
+sword's steel blade responds to light exactly like its leather grip, and both read as flat paint.
+Material classes fix that by saying what each colour is **made of**.
+
+**You usually do not have to do anything.** `bitmagic generate prop` and `bitmagic generate model`
+classify the asset right after the bake: a light model reads the same colour table shown below
+together with the asset's prompt, and its verdicts are written into the `.vxl` before the command
+returns (`Materials: metal, leather` in the output; `materials.classifier: "ai"` on the asset's
+`world.json` entry). Pass `--no-materials` to skip it. A classification that cannot run — no model
+credential, an engine too old to write classes — is a note, never a failed generation; the asset is
+baked and matte, and `bitmagic assets materials <id> --auto` retries it later.
+
+When the automatic answer is wrong, or for an asset added from a file (which records no prompt, so
+nothing is classified automatically), `bitmagic assets materials` is two steps, and the CLI does not
+guess at the middle one — **you do**, because you are the one who knows what the asset is meant to
+be.
+
+```bash
+bitmagic assets materials sword-01              # what does this asset look like?
+bitmagic assets materials sword-01 --set m.json # here is what those colours are
+bitmagic assets materials sword-01 --auto       # or let the model decide again
+```
+
+The first command prints the asset's colour groups:
+
+```
+"Longsword"  signature 4f2a91cd (version 1)
+
+20 voxels, 5 palette entries, bbox 1x20x1 voxels
+
+id   colour   share  height(min-max)  extent(x,y,z)  radial  shape       parts
+g0   #dddddd   70.0%        0.33-0.98 0.00,0.65,0.00    0.00  thin-long   1
+g1   #998866   20.0%        0.03-0.18 0.00,0.15,0.00    0.00  blob        1
+g2   #eecc66   10.0%        0.23-0.28 0.00,0.05,0.00    0.00  blob        1
+```
+
+Read with the asset's own prompt — printed underneath — that is enough to name the materials: g0 is
+the steel blade (most of the model, upper two thirds, long and thin), g1 the leather grip at the
+bottom, g2 a brass pommel between them. `share` is the fraction of the asset, `height` where it
+sits from floor to top, `extent` its size along each axis relative to the whole, `radial` how far
+from the centre axis, and `parts` how many separate pieces the colour forms — a colour scattered
+across the whole model in many parts is dithering, not a material.
+
+Then write the verdicts:
+
+```json
+{
+  "signatureVersion": 1,
+  "signatureHash": "4f2a91cd",
+  "verdicts": [
+    { "id": "g0", "class": "metal",   "confidence": 0.95 },
+    { "id": "g1", "class": "leather", "confidence": 0.9 },
+    { "id": "g2", "class": "gold",    "confidence": 0.6 }
+  ]
+}
+```
+
+The `signatureHash` binds the answer to the asset it describes: re-bake or re-voxelize the asset
+and the hash changes, so a stale set of verdicts is refused rather than applied to geometry it
+never saw.
+
+**Classes:** `matte` (the default — no special shading), `metal`, `gold`, `chrome`, `gem`, `glass`,
+`wood`, `stone`, `cloth`, `fur`, `leather`, `plastic`, `paint`. The first five reflect the sky; the
+rest get a highlight from the scene's own lights, which keeps their colours exactly as they are.
+`fur` is the odd one out — it reflects nothing, but picks up a soft halo towards its silhouette the
+way a pelt or plush does. Use it for exactly that: a teddy bear, an animal, a fur trim. Anything
+merely soft is `cloth`.
+
+**Rules worth following:**
+
+- `matte` is the right answer for most groups, and costs nothing. Leave a group out entirely rather
+  than inventing a material for it.
+- The asset's prompt is the strongest evidence there is — it names the materials, and your job is
+  only to decide which colour group is which.
+- A material the prompt does **not** name needs strong evidence from the geometry. A precious
+  material (`gold`, `gem`, `glass`) claimed over more than a quarter of the asset is refused
+  outright unless the prompt says so: a wooden crate is never 40% gem, and a wrongly shiny surface
+  is what a player notices.
+- Use a low confidence rather than guessing. Below 0.45 a verdict is dropped, which is a better
+  outcome than a surface that shines when it should not.
+- An asset that records no prompt or description has nothing saying what it is. Prefer leaving it
+  alone.
+
+**Budget.** Four materials per asset. Each one is an extra draw call on every placed instance, so
+over budget the smallest is folded into a related class (`gold` into `metal`, `gem` into `glass`)
+rather than dropped — every fold is reported. Very small groups are dropped too, except for the
+precious classes, where a fraction of a per cent is exactly the point.
+
+Materials are written into the `.vxl` under the **same asset id**, so every placed instance changes
+with it. `--clear` puts an asset back to the plain look. A re-bake (`bitmagic assets revoxelize`)
+produces a fresh `.vxl` whose palette the old verdicts no longer describe, so it classifies again
+on its own — `--no-materials` there leaves the re-baked asset plain. Nothing here generates anything or costs
+sparks; what it costs is the headless browser bake, since only the engine can read and write a
+`.vxl`. An asset whose base voxels glow (from the older per-colour glow that materials replaced) is
+refused rather than having that glow silently traded for a shine.
+
 ## Drivable vehicles
 
 `bitmagic generate vehicle` designs a vehicle and registers it as a **new** asset — unlike

package/dist/assets/materials.d.ts

@@ -0,0 +1,165 @@
+import type { Environment } from '../config/environments.js';
+import { withVoxelizeSession } from '../forge/voxelize-session.js';
+import type { ProjectContext } from '../project/context.js';
+/**
+ * Whether this project's vendored engine can answer these messages at all.
+ *
+ * A capability PROBE, not a version compare, exactly as `engineSupportsVxlMaster`
+ * does and for the reason its own doc gives: an engine with no handler never
+ * replies, so the request would stall for the full ten-minute bake timeout and
+ * then report a timeout, with nothing pointing at the real cause.
+ */
+export declare function engineSupportsMaterialClasses(projectRoot: string): boolean;
+/** One colour group of an asset, as the engine described it. */
+export interface MaterialGroup {
+    id: string;
+    hex: string;
+    share: number;
+    shape: string;
+}
+/** What the engine reports about an asset's materials. */
+export interface MaterialSignatureReply {
+    version: number;
+    hash: string;
+    voxelCount: number;
+    paletteSize: number;
+    groups: MaterialGroup[];
+    existingSlots: string[];
+}
+/** A single group's verdict, as written into a `--set` file. */
+export interface MaterialVerdictInput {
+    id: string;
+    class: string;
+    confidence: number;
+}
+export interface MaterialsBaseOptions {
+    context: ProjectContext;
+    environment: Environment;
+    token: string;
+    assetId: string;
+    log: (message: string) => void;
+    fetchImpl?: typeof globalThis.fetch;
+    /** Injected in tests so the lane runs without Chrome. */
+    session?: typeof withVoxelizeSession;
+}
+export interface ReadMaterialsResult {
+    assetId: string;
+    assetName: string;
+    signature: MaterialSignatureReply;
+    /** The engine's own rendering of the signature — printed verbatim. */
+    table: string;
+    /** The asset's generation prompt or description, when it records one. */
+    promptText?: string;
+}
+/**
+ * The asset to work on, refused before the browser starts if it cannot be.
+ *
+ * Only a `vxl` asset has voxels to classify. A GLB kept as a mesh, an image, a
+ * sound: none of them have a palette, and saying so up front costs nothing while
+ * a browser launch costs seconds.
+ */
+export declare function findVoxelAsset(world: Record<string, unknown>, assetId: string): {
+    asset: Record<string, unknown>;
+    url: string;
+    name: string;
+};
+/**
+ * The text this asset was generated from, if it records any.
+ *
+ * The single most valuable signal a classifier has — it names the materials
+ * outright — and also what the plausibility guard checks a precious-material
+ * claim against. Absent for an asset added from a file, which is exactly the case
+ * where classifying on colour alone would be guessing.
+ */
+export declare function assetPromptText(asset: Record<string, unknown>): string | undefined;
+/**
+ * Ask the engine what the asset is made of.
+ *
+ * Reads only — no upload, no world.json write, nothing spent. Safe to run as often
+ * as you like, which matters because it is the step an agent runs first.
+ */
+export declare function readAssetMaterials(options: MaterialsBaseOptions): Promise<ReadMaterialsResult>;
+export interface SetMaterialsOptions extends MaterialsBaseOptions {
+    /** The verdicts to apply, and the signature hash they were computed against. */
+    signatureVersion: number;
+    signatureHash: string;
+    verdicts: MaterialVerdictInput[];
+}
+export interface ClearMaterialsOptions extends MaterialsBaseOptions {
+    clear: true;
+}
+export interface SetMaterialsResult {
+    assetId: string;
+    assetName: string;
+    /** The material classes now on the asset. Empty after a --clear. */
+    slots: string[];
+    /** Classes that lost a share floor, the slot budget, or the plausibility guard. */
+    dropped: Array<{
+        class: string;
+        reason: string;
+        share: number;
+    }>;
+    /** Fraction of the asset left with the default look. */
+    baseShare: number;
+    /** True when nothing changed, so no upload and no world.json write happened. */
+    unchanged: boolean;
+    assetUrl?: string;
+    instanceCount: number;
+}
+/**
+ * Apply an assignment — or strip every class with `--clear` — and record the
+ * result in world.json.
+ *
+ * The engine hands back BYTES rather than uploading, the same split
+ * `REVOXELIZE_FROM_VXL_MASTER` uses: in a pro project the CLI owns world.json,
+ * and two writers on one asset thrash the reload watcher.
+ */
+export declare function setAssetMaterials(options: SetMaterialsOptions | ClearMaterialsOptions): Promise<SetMaterialsResult>;
+/** What api-server answers `POST /api/cli/v1/assets/materials/classify` with. */
+export interface ClassifyReply {
+    signatureHash?: unknown;
+    verdicts?: unknown;
+    model?: unknown;
+}
+/** The model step, injectable so the lane is testable without api-server. */
+export type ClassifyMaterials = (request: {
+    gameId: string;
+    assetName: string;
+    table: string;
+    signatureHash: string;
+    promptText?: string;
+}) => Promise<ClassifyReply>;
+export interface ClassifyMaterialsOptions extends MaterialsBaseOptions {
+    /** Test seam; the default posts to api-server. */
+    classify?: ClassifyMaterials;
+}
+export interface ClassifyMaterialsResult extends SetMaterialsResult {
+    /** The model that answered, for provenance. Absent when no verdicts came back. */
+    model?: string;
+}
+/**
+ * Read, classify and apply in ONE browser session: what `generate prop|model` run
+ * on the asset they just baked, and what `assets materials --auto` runs on demand.
+ *
+ * The middle step is api-server's light model rather than the creator's coding
+ * agent — the same prompt that agent would be shown, answered without a round
+ * trip through it, so a generated sword shines before anyone has looked at it.
+ * `assets materials --set` still overrides whatever this decided.
+ *
+ * An empty verdict list skips the APPLY entirely: the engine would leave the
+ * file byte-identical anyway, and not asking is one fewer thing to time out.
+ */
+export declare function classifyAssetMaterials(options: ClassifyMaterialsOptions): Promise<ClassifyMaterialsResult>;
+/**
+ * The tail of `generate prop|model` and `assets revoxelize`: classify the asset
+ * just baked, and say what happened.
+ *
+ * **Never throws.** The asset is baked, uploaded and in world.json by the time
+ * this runs, and a generation is paid for; a classification that fails —
+ * api-server without a model credential, a browser that would not come up a
+ * second time, a vendored engine too old to write classes — costs a note, never
+ * the asset. `bitmagic assets materials <id> --auto` re-runs it on demand.
+ */
+export declare function classifyAssetMaterialsQuietly(options: ClassifyMaterialsOptions): Promise<{
+    slots: string[];
+} | null>;

package/dist/assets/materials.js

@@ -0,0 +1,395 @@
+/**
+ * Read and set what an asset's voxels are MADE OF.
+ *
+ * A voxel asset's colours say nothing about its materials, so a generated sword's
+ * steel blade shades exactly like its leather grip. `bitmagic assets materials`
+ * closes that gap in two steps, and the split is the whole design:
+ *
+ *   bitmagic assets materials <id>            → print what the asset looks like
+ *   bitmagic assets materials <id> --set f    → say what those colours are
+ *
+ * Nothing here classifies anything, and the CLI deliberately does not try. A pro
+ * project has no language model of its own — `buildCliForgeDeps` hands the forge a
+ * `model` that throws on purpose, because the scene design runs on api-server —
+ * but it does have one sitting right there: the creator's own coding agent, which
+ * already knows what it asked for, has the world.json and the game's art
+ * direction in context, and costs the project nothing. So the CLI's job is to
+ * print a readable description and accept an answer back.
+ *
+ * That makes this lane's classifier better informed than a server-side one, not
+ * worse: it is the same agent that wrote the prompt.
+ *
+ * Writes under the SAME asset id, so every placed instance changes with it — the
+ * upgrade-in-place contract `generate prop` and `assets revoxelize` both make.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { CliError } from '../errors.js';
+import { VOXELIZE_TIMEOUT_MS, withVoxelizeSession } from '../forge/voxelize-session.js';
+import { applyModificationsToWorld } from '../forge/apply-modifications.js';
+import { projectWorldJsonPath } from '../forge/run-pipeline.js';
+import { apiPost } from '../http/client.js';
+import { uploadProjectFile } from '../http/signed-upload.js';
+import { isJsonObject, readWorldJson } from '../project/world-json.js';
+import { summarizeVxl } from './vxl-summary.js';
+/**
+ * Whether this project's vendored engine can answer these messages at all.
+ *
+ * A capability PROBE, not a version compare, exactly as `engineSupportsVxlMaster`
+ * does and for the reason its own doc gives: an engine with no handler never
+ * replies, so the request would stall for the full ten-minute bake timeout and
+ * then report a timeout, with nothing pointing at the real cause.
+ */
+export function engineSupportsMaterialClasses(projectRoot) {
+    return fs.existsSync(path.join(projectRoot, 'engine', 'engine', 'template', 'VxlMaterialAssetHandler.ts'));
+}
+/**
+ * The asset to work on, refused before the browser starts if it cannot be.
+ *
+ * Only a `vxl` asset has voxels to classify. A GLB kept as a mesh, an image, a
+ * sound: none of them have a palette, and saying so up front costs nothing while
+ * a browser launch costs seconds.
+ */
+export function findVoxelAsset(world, assetId) {
+    const assets = Array.isArray(world.assets) ? world.assets : [];
+    const asset = assets.find((item) => isJsonObject(item) && item.id === assetId);
+    if (!isJsonObject(asset)) {
+        throw new CliError(`No asset with id "${assetId}" in this project's world.json. `
+            + 'Run `bitmagic assets list` to see the ids.');
+    }
+    const name = typeof asset.name === 'string' ? asset.name : assetId;
+    const url = asset.url;
+    if (asset.type !== 'vxl' || typeof url !== 'string' || url === '') {
+        throw new CliError(`"${name}" is not a voxel asset, so it has no voxels to give materials to. `
+            + 'Material classes apply to `vxl` assets — those produced by `bitmagic generate prop`, '
+            + '`generate model`, or `assets add <file.glb>` without `--keep-glb`.');
+    }
+    return { asset, url, name };
+}
+/**
+ * The text this asset was generated from, if it records any.
+ *
+ * The single most valuable signal a classifier has — it names the materials
+ * outright — and also what the plausibility guard checks a precious-material
+ * claim against. Absent for an asset added from a file, which is exactly the case
+ * where classifying on colour alone would be guessing.
+ */
+export function assetPromptText(asset) {
+    const production = asset.production;
+    if (isJsonObject(production) && typeof production.prompt === 'string' && production.prompt !== '') {
+        return production.prompt;
+    }
+    if (typeof asset.description === 'string' && asset.description !== '')
+        return asset.description;
+    return undefined;
+}
+/** Placed instances pointing at this asset — the blast radius, reported not assumed. */
+function countInstances(world, assetId) {
+    const objects = Array.isArray(world.environmentObjects) ? world.environmentObjects : [];
+    return objects.filter((item) => isJsonObject(item) && item.assetId === assetId).length;
+}
+function assertEngineSupport(context) {
+    if (engineSupportsMaterialClasses(context.root))
+        return;
+    throw new CliError('This project\'s vendored engine does not know about voxel material classes. '
+        + 'Run `bitmagic upgrade` to get a newer engine, then try again. world.json is unchanged.');
+}
+/**
+ * Ask the engine what the asset is made of.
+ *
+ * Reads only — no upload, no world.json write, nothing spent. Safe to run as often
+ * as you like, which matters because it is the step an agent runs first.
+ */
+export async function readAssetMaterials(options) {
+    const { context, environment, token, assetId, log } = options;
+    assertEngineSupport(context);
+    const world = readWorldJson(projectWorldJsonPath(context.root));
+    const { asset, url, name } = findVoxelAsset(world, assetId);
+    const runSession = options.session ?? withVoxelizeSession;
+    const read = await runSession({
+        context, environment, token, log, subject: `"${name}"`,
+        retryHint: 'Nothing was written — this only reads the asset, so it is safe to retry.',
+    }, (session) => readSignatureInSession(session, { assetId, name, url, log }));
+    const promptText = assetPromptText(asset);
+    return {
+        assetId,
+        assetName: name,
+        ...read,
+        ...(promptText === undefined ? {} : { promptText }),
+    };
+}
+/** The one READ message, inside a session someone else opened. */
+async function readSignatureInSession({ host, port }, target) {
+    const { assetId, name, url, log } = target;
+    log(`Reading "${name}"'s colours…`);
+    const result = await host.transport.sendAndWait({
+        type: 'READ_VXL_MATERIAL_SIGNATURE',
+        requestId: `materials-read-${assetId}-${port}`,
+        vxlUrl: url,
+    }, 'READ_VXL_MATERIAL_SIGNATURE_RESULT', VOXELIZE_TIMEOUT_MS, { maxRetries: 1 });
+    if (!result)
+        throw new CliError(`Reading "${name}" timed out.`);
+    if (result.success === false) {
+        const reason = typeof result.error === 'string' ? result.error : 'unknown error';
+        throw new CliError(`Reading "${name}" failed: ${reason}`);
+    }
+    const signature = result.signature;
+    if (!signature || typeof signature.hash !== 'string') {
+        throw new CliError(`The engine returned no material signature for "${name}".`);
+    }
+    return { signature, table: typeof result.table === 'string' ? result.table : '' };
+}
+/**
+ * Apply an assignment — or strip every class with `--clear` — and record the
+ * result in world.json.
+ *
+ * The engine hands back BYTES rather than uploading, the same split
+ * `REVOXELIZE_FROM_VXL_MASTER` uses: in a pro project the CLI owns world.json,
+ * and two writers on one asset thrash the reload watcher.
+ */
+export async function setAssetMaterials(options) {
+    const { context, environment, token, assetId, log } = options;
+    assertEngineSupport(context);
+    const worldPath = projectWorldJsonPath(context.root);
+    const world = readWorldJson(worldPath);
+    const { asset, url, name } = findVoxelAsset(world, assetId);
+    const clearing = 'clear' in options;
+    const promptText = assetPromptText(asset);
+    const runSession = options.session ?? withVoxelizeSession;
+    const retryHint = `Nothing was written — "${name}" is unchanged, so this is safe to retry.`;
+    const reply = await runSession({
+        context, environment, token, log, subject: `"${name}"`, retryHint,
+    }, (session) => applyInSession(session, {
+        assetId, name, url, log, retryHint,
+        ...(promptText === undefined ? {} : { promptText }),
+        ...(clearing ? { clear: true } : {
+            assignment: {
+                signatureVersion: options.signatureVersion,
+                signatureHash: options.signatureHash,
+                verdicts: options.verdicts,
+                // 'agent' because in this lane the classifier IS the creator's own coding
+                // agent; nothing here decided anything.
+                classifier: 'agent',
+            },
+        }),
+    }));
+    return recordApplied({
+        options, world, worldPath, asset, assetId, name, retryHint, reply,
+        classifier: clearing ? 'manual' : 'agent',
+    });
+}
+/** The one APPLY message, inside a session someone else opened. */
+async function applyInSession({ host, port }, target) {
+    const { assetId, name, url, log, retryHint } = target;
+    log(target.clear
+        ? `Removing "${name}"'s material classes…`
+        : `Setting "${name}"'s materials…`);
+    const result = await host.transport.sendAndWait({
+        type: 'APPLY_VXL_MATERIALS',
+        requestId: `materials-set-${assetId}-${port}`,
+        assetId,
+        assetName: name,
+        vxlUrl: url,
+        // The CLI uploads, so the engine returns bytes (see the doc above).
+        upload: false,
+        ...(target.clear ? { clear: true } : { assignment: target.assignment }),
+        ...(target.promptText === undefined ? {} : { promptText: target.promptText }),
+    }, 'APPLY_VXL_MATERIALS_RESULT', VOXELIZE_TIMEOUT_MS, { maxRetries: 1 });
+    if (!result)
+        throw new CliError(`Setting "${name}"'s materials timed out. ${retryHint}`);
+    if (result.success === false) {
+        const reason = typeof result.error === 'string' ? result.error : 'unknown error';
+        throw new CliError(`Setting "${name}"'s materials failed: ${reason}. ${retryHint}`);
+    }
+    return result;
+}
+/**
+ * After the engine answered: upload the bytes and record the result in world.json,
+ * or do neither when the file was left alone.
+ */
+async function recordApplied(input) {
+    const { options, world, worldPath, asset, assetId, name, retryHint, reply } = input;
+    const { context, environment, token } = options;
+    const slots = Array.isArray(reply.slots) ? reply.slots.filter((s) => typeof s === 'string') : [];
+    const dropped = Array.isArray(reply.dropped) ? reply.dropped : [];
+    const baseShare = typeof reply.baseShare === 'number' ? reply.baseShare : 1;
+    const instanceCount = countInstances(world, assetId);
+    if (reply.unchanged === true) {
+        // Byte-identical output: no upload, no url churn, no world.json write. "Nothing
+        // was classified" has to be indistinguishable from "this never ran".
+        return {
+            assetId, assetName: name, slots, dropped, baseShare,
+            unchanged: true, instanceCount,
+        };
+    }
+    const raw = reply.vxlBytes;
+    if (!(raw instanceof Uint8Array) && !Array.isArray(raw)) {
+        throw new CliError(`The engine returned no voxels for "${name}". ${retryHint}`);
+    }
+    const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+    // Read the header BEFORE uploading, as the re-bake path does: bytes that are not
+    // a readable `.vxl` must never reach storage under a name the engine will later
+    // try to load. This also catches the one failure this command could plausibly
+    // introduce — a version the project's own vxl-summary does not accept.
+    const summary = summarizeVxl(bytes);
+    if (summary === null) {
+        throw new CliError(`The engine returned bytes that are not a readable .vxl for "${name}". ${retryHint}`);
+    }
+    const upload = await uploadProjectFile(environment, token, {
+        gameId: context.metadata.gameId,
+        filename: `${context.metadata.gameId}-${name}-materials-${Date.now()}.vxl`,
+        contentType: 'application/octet-stream',
+        bytes,
+    }, { fetch: options.fetchImpl ?? globalThis.fetch });
+    // MERGED over the existing record, never substituted for it. An asset accumulates
+    // authored state this command knows nothing about — `fitBox`, `collision`,
+    // `light`, `voxelizeSettings` — and a fresh record would discard all of it. Only
+    // the file and its size change: geometry, bounds and voxel size are untouched by
+    // a material class, so re-asserting them here could only introduce a disagreement.
+    const modification = {
+        type: 'upsertRoot',
+        path: ['assets'],
+        predicate: (item) => isJsonObject(item) && item.id === assetId,
+        value: {
+            ...asset,
+            url: upload.url,
+            size: bytes.byteLength,
+            // Provenance only — the classes themselves live in the `.vxl`. `--clear`
+            // records the absence rather than deleting the field, so "this was
+            // deliberately put back to plain" stays distinguishable from "never
+            // classified".
+            materials: {
+                classifier: input.classifier,
+                slots,
+                at: new Date().toISOString(),
+                ...(input.model === undefined ? {} : { model: input.model }),
+            },
+        },
+    };
+    applyModificationsToWorld(worldPath, [modification], { subject: 'The asset\'s materials' });
+    return {
+        assetId,
+        assetName: name,
+        slots,
+        dropped,
+        baseShare,
+        unchanged: false,
+        assetUrl: upload.url,
+        instanceCount,
+    };
+}
+/**
+ * Read, classify and apply in ONE browser session: what `generate prop|model` run
+ * on the asset they just baked, and what `assets materials --auto` runs on demand.
+ *
+ * The middle step is api-server's light model rather than the creator's coding
+ * agent — the same prompt that agent would be shown, answered without a round
+ * trip through it, so a generated sword shines before anyone has looked at it.
+ * `assets materials --set` still overrides whatever this decided.
+ *
+ * An empty verdict list skips the APPLY entirely: the engine would leave the
+ * file byte-identical anyway, and not asking is one fewer thing to time out.
+ */
+export async function classifyAssetMaterials(options) {
+    const { context, environment, token, assetId, log } = options;
+    assertEngineSupport(context);
+    const worldPath = projectWorldJsonPath(context.root);
+    const world = readWorldJson(worldPath);
+    const { asset, url, name } = findVoxelAsset(world, assetId);
+    const promptText = assetPromptText(asset);
+    const retryHint = `Nothing was written — "${name}" is unchanged, so this is safe to retry.`;
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const classify = options.classify ?? ((request) => apiPost(environment, '/api/cli/v1/assets/materials/classify', token, request, { fetch: fetchImpl }));
+    const runSession = options.session ?? withVoxelizeSession;
+    const outcome = await runSession({
+        context, environment, token, log, subject: `"${name}"`, retryHint,
+    }, async (session) => {
+        const { signature, table } = await readSignatureInSession(session, { assetId, name, url, log });
+        log(`Deciding what "${name}" is made of…`);
+        const answer = await classify({
+            gameId: context.metadata.gameId,
+            assetName: name,
+            table,
+            signatureHash: signature.hash,
+            ...(promptText === undefined ? {} : { promptText }),
+        });
+        const verdicts = parseVerdictList(answer.verdicts);
+        const model = typeof answer.model === 'string' ? answer.model : undefined;
+        if (verdicts.length === 0)
+            return { reply: null, model };
+        const reply = await applyInSession(session, {
+            assetId, name, url, log, retryHint,
+            ...(promptText === undefined ? {} : { promptText }),
+            assignment: {
+                signatureVersion: signature.version,
+                signatureHash: signature.hash,
+                verdicts,
+                classifier: 'ai',
+                ...(model === undefined ? {} : { model }),
+            },
+        });
+        return { reply, model };
+    });
+    if (outcome.reply === null) {
+        return {
+            assetId, assetName: name, slots: [], dropped: [], baseShare: 1,
+            unchanged: true, instanceCount: countInstances(world, assetId),
+            ...(outcome.model === undefined ? {} : { model: outcome.model }),
+        };
+    }
+    const recorded = await recordApplied({
+        options, world, worldPath, asset, assetId, name, retryHint, reply: outcome.reply,
+        classifier: 'ai',
+        ...(outcome.model === undefined ? {} : { model: outcome.model }),
+    });
+    return { ...recorded, ...(outcome.model === undefined ? {} : { model: outcome.model }) };
+}
+/**
+ * The tail of `generate prop|model` and `assets revoxelize`: classify the asset
+ * just baked, and say what happened.
+ *
+ * **Never throws.** The asset is baked, uploaded and in world.json by the time
+ * this runs, and a generation is paid for; a classification that fails —
+ * api-server without a model credential, a browser that would not come up a
+ * second time, a vendored engine too old to write classes — costs a note, never
+ * the asset. `bitmagic assets materials <id> --auto` re-runs it on demand.
+ */
+export async function classifyAssetMaterialsQuietly(options) {
+    const { context, assetId, log } = options;
+    if (!engineSupportsMaterialClasses(context.root))
+        return null;
+    try {
+        const result = await classifyAssetMaterials(options);
+        if (result.unchanged) {
+            log(`Materials: nothing on "${result.assetName}" needs special shading.`);
+        }
+        else {
+            log(`Materials: ${result.slots.join(', ')} — `
+                + `${Math.round(result.baseShare * 100)}% of "${result.assetName}" keeps the default look.`);
+        }
+        return { slots: result.slots };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`note: could not decide what the asset is made of (${message}). `
+            + `It is baked and in world.json; \`bitmagic assets materials ${assetId} --auto\` retries.`);
+        return null;
+    }
+}
+/** api-server's verdict list, with anything malformed dropped rather than refused. */
+function parseVerdictList(value) {
+    if (!Array.isArray(value))
+        return [];
+    const verdicts = [];
+    for (const item of value) {
+        if (!isJsonObject(item))
+            continue;
+        const { id, confidence } = item;
+        const className = item.class;
+        if (typeof id !== 'string' || typeof className !== 'string' || typeof confidence !== 'number')
+            continue;
+        verdicts.push({ id, class: className, confidence });
+    }
+    return verdicts;
+}
+//# sourceMappingURL=materials.js.map