@jgengine/core 0.10.0 → 0.11.0

package/dist/runtime/worldReplication.d.ts

@@ -9,6 +9,13 @@ import type { WorldSnapshot } from "./worldSnapshot.js";
  */
 export interface WorldDiff {
     revision: number;
+    /**
+     * The revision this diff was computed against — `sinceRevision` echoed back. A {@link WorldMirror} only applies
+     * a diff whose `baseRevision` matches its own current revision exactly; a mismatch means frames were skipped and
+     * the mirror must resync from a fresh baseline instead of silently drifting. Absent on a diff built by an older
+     * producer — treated as legacy and always applied, matching pre-revision-checking behavior.
+     */
+    baseRevision?: number;
     entities: readonly SceneEntity[];
     removedEntities: readonly string[];
     stats: Record<string, StatValueMap>;
@@ -17,15 +24,27 @@ export interface WorldDiff {
     removedStore: readonly string[];
     /** Changed whole-module snapshots keyed by module name — everything a client can't reconstruct from deltas. */
     modules: WorldSnapshot;
+    /** Module keys present in a prior baseline that no longer exist — a client drops them wholesale on apply. */
+    removedModules: readonly string[];
+}
+/**
+ * Optional acceleration for {@link createWorldReplicator}: a monotone world-dirty counter (aggregated from
+ * each {@link SnapshotModule.version}). When it hasn't advanced since the last commit nothing mutated, so the
+ * replicator skips re-reading and re-serializing the whole world — the change-detection short-circuit item #28
+ * asks for. Omit it (or pass a snapshot-only source) to keep the original full-re-serialize-per-commit behavior.
+ */
+export interface WorldReplicatorOptions {
+    worldVersion?: () => number;
 }
 /**
  * Turns successive full {@link WorldSnapshot}s into per-client {@link WorldDiff}s. Each `commit()` re-reads the
  * world, stamps every item that changed with the new revision, and remembers removals; `diff(sinceRevision)`
  * then replays exactly the items stamped after that revision. Everything the tracker holds is JSON — the same
  * shape that rides the wire — so a diff is inherently serializable. Change-detection is a full re-serialize per
- * commit; dirty-hint acceleration is a later optimization behind the same seam.
- */
-export declare function createWorldReplicator(takeSnapshot: () => WorldSnapshot): {
+ * commit unless {@link WorldReplicatorOptions.worldVersion} lets an unchanged tick short-circuit before it.
+  * @internal
+  */
+export declare function createWorldReplicator(takeSnapshot: () => WorldSnapshot, options?: WorldReplicatorOptions): {
     commit: () => number;
     diff: (sinceRevision: number) => WorldDiff;
     revision: () => number;
@@ -35,12 +54,16 @@ export type WorldReplicator = ReturnType<typeof createWorldReplicator>;
 /**
  * Diff two full {@link WorldSnapshot}s directly, stamping the result at `revision` — the stateless counterpart of
  * {@link createWorldReplicator} for hosts that persist snapshots rather than keep a live tracker (Convex reconstructs
- * per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`.
- */
-export declare function diffSnapshots(prev: WorldSnapshot, next: WorldSnapshot, revision: number): WorldDiff;
+ * per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`. `baseRevision`, when the
+ * caller knows the revision `prev` was stamped at, lets a {@link WorldMirror} verify continuity the same way a
+ * `createWorldReplicator` diff does; omitted, the diff is legacy/always-apply.
+  * @internal
+  */
+export declare function diffSnapshots(prev: WorldSnapshot, next: WorldSnapshot, revision: number, baseRevision?: number): WorldDiff;
 /**
  * Fold a {@link WorldDiff} onto a prior {@link WorldSnapshot} baseline, returning the next full snapshot — the
  * client-side inverse of {@link createWorldReplicator}. Pure data in, pure data out: upserts changed entities,
  * stats and store keys, drops the removed ones, and replaces changed module snapshots wholesale.
- */
+  * @internal
+  */
 export declare function applyWorldDiff(baseline: WorldSnapshot, diff: WorldDiff): WorldSnapshot;

package/dist/runtime/worldReplication.js

@@ -4,9 +4,12 @@ const CORE_KEYS = new Set(["entities", "stats", "store"]);
  * world, stamps every item that changed with the new revision, and remembers removals; `diff(sinceRevision)`
  * then replays exactly the items stamped after that revision. Everything the tracker holds is JSON — the same
  * shape that rides the wire — so a diff is inherently serializable. Change-detection is a full re-serialize per
- * commit; dirty-hint acceleration is a later optimization behind the same seam.
- */
-export function createWorldReplicator(takeSnapshot) {
+ * commit unless {@link WorldReplicatorOptions.worldVersion} lets an unchanged tick short-circuit before it.
+  * @internal
+  */
+export function createWorldReplicator(takeSnapshot, options = {}) {
+    const worldVersion = options.worldVersion;
+    let committedVersion;
     let revision = 0;
     const entities = new Map();
     const removedEntities = new Map();
@@ -15,6 +18,7 @@ export function createWorldReplicator(takeSnapshot) {
     const store = new Map();
     const removedStore = new Map();
     const modules = new Map();
+    const removedModules = new Map();
     function diffMap(live, tracked, removed, nextRevision) {
         let changed = false;
         for (const [key, json] of live) {
@@ -35,6 +39,12 @@ export function createWorldReplicator(takeSnapshot) {
         return changed;
     }
     function commit() {
+        if (worldVersion !== undefined) {
+            const current = worldVersion();
+            if (committedVersion !== undefined && current === committedVersion)
+                return revision;
+            committedVersion = current;
+        }
         const snapshot = takeSnapshot();
         const nextRevision = revision + 1;
         const liveEntities = new Map();
@@ -58,7 +68,7 @@ export function createWorldReplicator(takeSnapshot) {
         let changed = diffMap(liveEntities, entities, removedEntities, nextRevision);
         changed = diffMap(liveStats, stats, removedStats, nextRevision) || changed;
         changed = diffMap(liveStore, store, removedStore, nextRevision) || changed;
-        changed = diffMap(liveModules, modules, new Map(), nextRevision) || changed;
+        changed = diffMap(liveModules, modules, removedModules, nextRevision) || changed;
         if (changed)
             revision = nextRevision;
         return revision;
@@ -86,6 +96,7 @@ export function createWorldReplicator(takeSnapshot) {
         }
         return {
             revision,
+            baseRevision: sinceRevision,
             entities: changedEntities,
             removedEntities: keysAfter(removedEntities, sinceRevision),
             stats: changedStats,
@@ -93,6 +104,7 @@ export function createWorldReplicator(takeSnapshot) {
             store: changedStore,
             removedStore: keysAfter(removedStore, sinceRevision),
             modules: changedModules,
+            removedModules: keysAfter(removedModules, sinceRevision),
         };
     }
     return { commit, diff, revision: () => revision };
@@ -108,9 +120,12 @@ function keysAfter(map, sinceRevision) {
 /**
  * Diff two full {@link WorldSnapshot}s directly, stamping the result at `revision` — the stateless counterpart of
  * {@link createWorldReplicator} for hosts that persist snapshots rather than keep a live tracker (Convex reconstructs
- * per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`.
- */
-export function diffSnapshots(prev, next, revision) {
+ * per invocation). `applyWorldDiff(prev, diffSnapshots(prev, next, r))` reproduces `next`. `baseRevision`, when the
+ * caller knows the revision `prev` was stamped at, lets a {@link WorldMirror} verify continuity the same way a
+ * `createWorldReplicator` diff does; omitted, the diff is legacy/always-apply.
+  * @internal
+  */
+export function diffSnapshots(prev, next, revision, baseRevision) {
     const prevEntities = new Map();
     for (const entity of (prev["entities"] ?? [])) {
         prevEntities.set(entity.id, JSON.stringify(entity));
@@ -143,20 +158,35 @@ export function diffSnapshots(prev, next, revision) {
     }
     const removedStore = [...prevStore.keys()].filter((key) => !nextStore.has(key));
     const modules = {};
+    const nextModuleKeys = new Set();
     for (const [key, value] of Object.entries(next)) {
         if (CORE_KEYS.has(key))
             continue;
+        nextModuleKeys.add(key);
         const json = JSON.stringify(value ?? null);
         if (JSON.stringify(prev[key] ?? null) !== json)
             modules[key] = JSON.parse(json);
     }
-    return { revision, entities, removedEntities, stats, removedStats, store, removedStore, modules };
+    const removedModules = Object.keys(prev).filter((key) => !CORE_KEYS.has(key) && !nextModuleKeys.has(key));
+    return {
+        revision,
+        ...(baseRevision === undefined ? {} : { baseRevision }),
+        entities,
+        removedEntities,
+        stats,
+        removedStats,
+        store,
+        removedStore,
+        modules,
+        removedModules,
+    };
 }
 /**
  * Fold a {@link WorldDiff} onto a prior {@link WorldSnapshot} baseline, returning the next full snapshot — the
  * client-side inverse of {@link createWorldReplicator}. Pure data in, pure data out: upserts changed entities,
  * stats and store keys, drops the removed ones, and replaces changed module snapshots wholesale.
- */
+  * @internal
+  */
 export function applyWorldDiff(baseline, diff) {
     const next = { ...baseline };
     const entityById = new Map();
@@ -181,5 +211,7 @@ export function applyWorldDiff(baseline, diff) {
     next["store"] = Array.from(storeByKey.entries());
     for (const [key, value] of Object.entries(diff.modules))
         next[key] = value;
+    for (const key of diff.removedModules)
+        delete next[key];
     return next;
 }

package/dist/runtime/worldSnapshot.d.ts

@@ -1,17 +1,44 @@
+/** Who a host→client snapshot is being projected for — the identity a {@link SnapshotModule.project} filters against. */
+export interface SnapshotViewer {
+    readonly userId: string;
+}
 /**
  * The replication seam for host-authoritative shared worlds: the opt-in feature manifest *is* the
  * replication schema. Each live subsystem a game opts into registers a {@link SnapshotModule} keyed
  * by name; the host serializes exactly the registered set into a {@link WorldSnapshot} and a client
  * hydrates the same keys back. Adding a replicated subsystem is a registration, never a new branch.
+ *
+ * Two optional members carry per-viewer projection and change detection *through the same contract*,
+ * so a feature opts into either without the engine growing a per-feature branch:
+ * - {@link project} narrows this module's snapshot to what one viewer may see (private state, area of
+ *   interest). Absent → the module is world-public and every client receives it verbatim (the default).
+ * - {@link version} is a monotone counter the host reads to skip re-serializing an unchanged module.
  */
 export interface SnapshotModule<T = unknown> {
     readonly key: string;
     snapshot(): T;
     hydrate(data: T): void;
+    /**
+     * Narrow this module's full snapshot to what `viewer` is allowed to see — return the same shape
+     * carrying only the visible subset (drop other players' private state, cull entities outside the
+     * viewer's area of interest). `world` is the whole unprojected baseline, so a module can cross-
+     * reference another (e.g. drop stats for entities the viewer can't see). Absent → world-public: the
+     * full value is sent to every viewer.
+     */
+    project?(data: T, viewer: SnapshotViewer, world: WorldSnapshot): T;
+    /** Monotone change counter; unchanged between host commits means this module didn't mutate and need not re-serialize. */
+    version?(): number;
 }
 /** Full world baseline keyed by {@link SnapshotModule.key} — one entry per opted-in subsystem. */
 export type WorldSnapshot = Record<string, unknown>;
-/** Serialize every registered module into one keyed baseline — the host→client full-world send. */
-export declare function composeWorldSnapshot(modules: readonly SnapshotModule[]): WorldSnapshot;
-/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched. */
+/**
+ * Serialize every registered module into one keyed baseline — the host→client full-world send. When a
+ * `viewer` is supplied, each module that implements {@link SnapshotModule.project} narrows its value to
+ * what that viewer may see; modules without a projector are sent verbatim.
+ * @internal
+ */
+export declare function composeWorldSnapshot(modules: readonly SnapshotModule[], viewer?: SnapshotViewer): WorldSnapshot;
+/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched.
+ * @internal
+ */
 export declare function applyWorldSnapshot(modules: readonly SnapshotModule[], snapshot: WorldSnapshot): void;

package/dist/runtime/worldSnapshot.js

@@ -1,11 +1,26 @@
-/** Serialize every registered module into one keyed baseline — the host→client full-world send. */
-export function composeWorldSnapshot(modules) {
-    const snapshot = {};
+/**
+ * Serialize every registered module into one keyed baseline — the host→client full-world send. When a
+ * `viewer` is supplied, each module that implements {@link SnapshotModule.project} narrows its value to
+ * what that viewer may see; modules without a projector are sent verbatim.
+ * @internal
+ */
+export function composeWorldSnapshot(modules, viewer) {
+    const raw = {};
     for (const module of modules)
-        snapshot[module.key] = module.snapshot();
+        raw[module.key] = module.snapshot();
+    if (viewer === undefined)
+        return raw;
+    const snapshot = {};
+    for (const module of modules) {
+        const value = raw[module.key];
+        snapshot[module.key] =
+            module.project !== undefined ? module.project(value, viewer, raw) : value;
+    }
     return snapshot;
 }
-/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched. */
+/** Hydrate every registered module whose key is present in `snapshot`; keys absent from it are left untouched.
+ * @internal
+ */
 export function applyWorldSnapshot(modules, snapshot) {
     for (const module of modules) {
         if (Object.prototype.hasOwnProperty.call(snapshot, module.key)) {

package/dist/scene/assetCatalog.d.ts

@@ -1,3 +1,4 @@
+import type { AssetSpace } from "./assetSpace.js";
 /** Measured horizontal footprint, footprint center, and lowest Y of a model in model space. */
 export interface ModelDims {
     footprint: {
@@ -14,7 +15,27 @@ export interface ModelAssetRef {
     url: string;
     /** Measured at asset reindex: horizontal footprint, footprint center, and lowest Y in model space (pre-scale). Lets the shell auto-center and ground-snap corner-pivot kit models. */
     dims?: ModelDims;
+    /** Authored asset-space metadata — canonical facing (degrees), source-unit scale, footprint, anchor, bounds, and rotation policy. The upstream owner of placement corrections; see {@link "scene/assetSpace".AssetSpace}. */
+    space?: AssetSpace;
 }
+/**
+ * A catalog entry backed by a registered {@link registerAssetGenerator} instead of a GLB URL — a
+ * slider-driven parametric prop (bookcase, building). `defaults` seeds a fresh placement's params.
+ * Placed instances persist `{ assetId, params, seed }` in the scene and re-resolve at runtime.
+ */
+export interface GeneratorAssetRef {
+    kind: "generator";
+    /** Id of the registered generator this asset resolves through. */
+    generatorId: string;
+    /** Default params stamped onto a fresh placement's meta. */
+    defaults?: Record<string, unknown>;
+    /** Authored asset-space metadata — canonical facing (degrees), footprint, anchor, bounds, and rotation policy; see {@link "scene/assetSpace".AssetSpace}. */
+    space?: AssetSpace;
+}
+/** A catalog entry: a static GLB model, or a parametric generator. */
+export type AssetRef = ModelAssetRef | GeneratorAssetRef;
+/** True when a catalog entry is a parametric generator rather than a static GLB. @internal */
+export declare function isGeneratorAsset(ref: AssetRef): ref is GeneratorAssetRef;
 export interface AssetCatalog<TMeta extends ModelAssetRef = ModelAssetRef> {
     register(id: string, asset: TMeta): void;
     resolve(id: string): TMeta | null;

package/dist/scene/assetCatalog.js

@@ -1,3 +1,7 @@
+/** True when a catalog entry is a parametric generator rather than a static GLB. @internal */
+export function isGeneratorAsset(ref) {
+    return ref.kind === "generator";
+}
 export function createAssetCatalog() {
     const assets = new Map();
     return {

package/dist/scene/assetDiagnostics.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pure, zero-dependency classification of a model-asset fetch before it reaches
+ * a GLTF parser. Runtime loaders hand the raw response (status, content type,
+ * and the first bytes) to {@link classifyAssetResponse} so a missing or
+ * mis-served file surfaces as an actionable diagnostic naming the broken asset
+ * contract, instead of the opaque "Unexpected token < in JSON" parse error a
+ * dev-server HTML fallback otherwise produces. No `fetch`, DOM, or three.js
+ * dependency lives here — callers supply the already-read bytes.
+ */
+/**
+ * How a model-asset fetch resolved. `ok` means the bytes are a parseable GLB or
+ * glTF-JSON; every other kind is a distinct failure a loader should report
+ * rather than parse: `missing` (HTTP error / no bytes), `html` (a dev-server
+ * fallback page served in place of the file), `corrupt` (bytes present but not a
+ * recognizable model), `unsupported` (a recognizable but non-model format).
+ */
+export type AssetLoadKind = "ok" | "missing" | "html" | "corrupt" | "unsupported";
+/** The signature read from a response's leading bytes, independent of HTTP metadata. @internal */
+export type AssetByteSignature = "glb" | "gltf-json" | "html" | "png" | "jpeg" | "zip" | "unknown" | "empty";
+/**
+ * A probe of a model-asset fetch: the URL, an optional logical asset id for the
+ * diagnostic, and whatever the caller managed to read. Any field may be absent
+ * (e.g. a network error yields no `status` or `bytes`); the classifier degrades
+ * gracefully.
+ */
+export interface AssetResponseProbe {
+    url: string;
+    /** Logical catalog id / alias behind the URL, surfaced in the diagnostic message when known. */
+    logicalId?: string;
+    /** HTTP status code; `0` or `>= 400` is treated as missing. Omit when the fetch never completed. */
+    status?: number;
+    statusText?: string;
+    /** `Content-Type` response header, lower-cased or not — matched case-insensitively. */
+    contentType?: string;
+    /** The leading bytes of the body (a few hundred is plenty); their signature decides GLB vs HTML vs corrupt. */
+    bytes?: Uint8Array;
+}
+/** The verdict for one model-asset fetch: its {@link AssetLoadKind} plus a ready-to-log message. */
+export interface AssetLoadDiagnosis {
+    kind: AssetLoadKind;
+    /** True only for `kind: "ok"` — safe to hand the bytes to a GLTF parser. */
+    ok: boolean;
+    url: string;
+    logicalId?: string;
+    byteSignature: AssetByteSignature;
+    /** Human-readable, actionable one-liner naming the asset, the URL, and the likely fix. */
+    message: string;
+}
+/** GLB little-endian magic — the ASCII "glTF" at byte 0 of a binary glTF container. @internal */
+export declare const GLB_MAGIC_ASCII = "glTF";
+/**
+ * Classify the leading bytes of a response body by their format signature, with
+ * no HTTP context. Recognizes GLB (`glTF` magic), glTF-JSON (a leading `{`), an
+ * HTML fallback page (`<!doctype`, `<html`, or a bare `<`), and a few common
+ * non-model binaries (PNG, JPEG, ZIP) so they can be reported as unsupported
+ * rather than corrupt.
+ */
+export declare function readByteSignature(bytes: Uint8Array): AssetByteSignature;
+/**
+ * Turn a {@link AssetResponseProbe} into an {@link AssetLoadDiagnosis}. HTTP
+ * status is checked first (a `>= 400` or `0` status is `missing`), then the
+ * `Content-Type` and byte signature decide between an HTML fallback, a
+ * parseable model (`ok`), an unsupported-but-recognizable format, and otherwise
+ * corrupt bytes. The returned `message` always names the asset and URL and, for
+ * failures, points at the likely fix (provision the pack, check the serving path).
+ *
+ * @capability asset-load-diagnostics classify a model fetch (missing / HTML fallback / corrupt / unsupported) before parsing
+ */
+export declare function classifyAssetResponse(probe: AssetResponseProbe): AssetLoadDiagnosis;

package/dist/scene/assetDiagnostics.js

@@ -0,0 +1,110 @@
+/**
+ * Pure, zero-dependency classification of a model-asset fetch before it reaches
+ * a GLTF parser. Runtime loaders hand the raw response (status, content type,
+ * and the first bytes) to {@link classifyAssetResponse} so a missing or
+ * mis-served file surfaces as an actionable diagnostic naming the broken asset
+ * contract, instead of the opaque "Unexpected token < in JSON" parse error a
+ * dev-server HTML fallback otherwise produces. No `fetch`, DOM, or three.js
+ * dependency lives here — callers supply the already-read bytes.
+ */
+/** GLB little-endian magic — the ASCII "glTF" at byte 0 of a binary glTF container. @internal */
+export const GLB_MAGIC_ASCII = "glTF";
+function startsWithAscii(bytes, ascii) {
+    if (bytes.length < ascii.length)
+        return false;
+    for (let i = 0; i < ascii.length; i += 1) {
+        if (bytes[i] !== ascii.charCodeAt(i))
+            return false;
+    }
+    return true;
+}
+/** Skip a UTF-8 BOM and leading ASCII whitespace, returning the index of the first meaningful byte. */
+function firstNonBlank(bytes) {
+    let i = 0;
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
+        i = 3;
+    while (i < bytes.length) {
+        const b = bytes[i];
+        // space, tab, CR, LF
+        if (b === 0x20 || b === 0x09 || b === 0x0d || b === 0x0a)
+            i += 1;
+        else
+            break;
+    }
+    return i;
+}
+/**
+ * Classify the leading bytes of a response body by their format signature, with
+ * no HTTP context. Recognizes GLB (`glTF` magic), glTF-JSON (a leading `{`), an
+ * HTML fallback page (`<!doctype`, `<html`, or a bare `<`), and a few common
+ * non-model binaries (PNG, JPEG, ZIP) so they can be reported as unsupported
+ * rather than corrupt.
+ */
+export function readByteSignature(bytes) {
+    if (bytes.length === 0)
+        return "empty";
+    if (startsWithAscii(bytes, GLB_MAGIC_ASCII))
+        return "glb";
+    if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+        return "png";
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "jpeg";
+    if (bytes.length >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b && bytes[2] === 0x03 && bytes[3] === 0x04) {
+        return "zip";
+    }
+    const start = firstNonBlank(bytes);
+    const head = bytes[start];
+    if (head === undefined)
+        return "empty";
+    // '<' — an HTML document served where a model was expected.
+    if (head === 0x3c)
+        return "html";
+    // '{' — glTF-JSON (the non-binary .gltf form) is a parseable model.
+    if (head === 0x7b)
+        return "gltf-json";
+    return "unknown";
+}
+function describe(logicalId, url) {
+    return logicalId === undefined ? `"${url}"` : `"${logicalId}" (${url})`;
+}
+/**
+ * Turn a {@link AssetResponseProbe} into an {@link AssetLoadDiagnosis}. HTTP
+ * status is checked first (a `>= 400` or `0` status is `missing`), then the
+ * `Content-Type` and byte signature decide between an HTML fallback, a
+ * parseable model (`ok`), an unsupported-but-recognizable format, and otherwise
+ * corrupt bytes. The returned `message` always names the asset and URL and, for
+ * failures, points at the likely fix (provision the pack, check the serving path).
+ *
+ * @capability asset-load-diagnostics classify a model fetch (missing / HTML fallback / corrupt / unsupported) before parsing
+ */
+export function classifyAssetResponse(probe) {
+    const { url, logicalId, status, statusText, contentType, bytes } = probe;
+    const signature = bytes === undefined ? "empty" : readByteSignature(bytes);
+    const who = describe(logicalId, url);
+    const finish = (kind, message) => ({
+        kind,
+        ok: kind === "ok",
+        url,
+        ...(logicalId === undefined ? {} : { logicalId }),
+        byteSignature: signature,
+        message,
+    });
+    if (status !== undefined && (status === 0 || status >= 400)) {
+        const suffix = statusText === undefined || statusText.length === 0 ? "" : ` ${statusText}`;
+        return finish("missing", `Asset ${who} did not load: HTTP ${status}${suffix}. The file is not being served — provision the pack (e.g. \`assets pull <source>\`) or check the model path.`);
+    }
+    const htmlContentType = contentType !== undefined && contentType.toLowerCase().includes("text/html");
+    if (signature === "html" || (htmlContentType && signature !== "glb" && signature !== "gltf-json")) {
+        return finish("html", `Asset ${who} resolved to an HTML page, not a model — the dev server returned its fallback document because the file is missing. Provision the pack (\`assets pull <source>\`) so the bytes exist under the served path.`);
+    }
+    if (signature === "glb" || signature === "gltf-json")
+        return finish("ok", `Asset ${who} loaded (${signature}).`);
+    if (signature === "png" || signature === "jpeg" || signature === "zip") {
+        return finish("unsupported", `Asset ${who} is a ${signature} file, not a GLB/glTF model — the reference points at the wrong file or the wrong loader is being used.`);
+    }
+    if (signature === "empty") {
+        return finish("corrupt", `Asset ${who} returned an empty body — the file exists but has no bytes. Re-provision the pack or remove the reference.`);
+    }
+    return finish("corrupt", `Asset ${who} is not a recognizable GLB/glTF model (leading bytes do not match any known signature). The file is likely truncated or corrupt — re-provision the pack.`);
+}

package/dist/scene/assetGenerator.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The generator-asset seam: register a parametric asset generator (`generate(params, seed) → parts`)
+ * so a slider-driven prop (a bookcase with width/shelves/book-density, a building with floors/bays)
+ * lives in the catalog alongside static GLBs. A placed instance stores only `{ assetId, params, seed }`
+ * — the geometry is re-resolved at runtime, never baked. Schema drives the inspector via #809. The
+ * generic seam is engine; concrete generators (building, bookcase) are adopters registered from
+ * game/example code — the building generator is the one engine adopter, as a proof it composes.
+ *
+ * @capability asset-generator seeded parametric geometry registered as a placeable asset
+ */
+import { type ParamSchema, type ParsedParams } from "./sceneKinds.js";
+/** One generated primitive part — a box/panel placed in the asset's local space. */
+export interface GeneratedPart {
+    id: string;
+    /** Optional semantic tag (shelf, board, book, wall, window …) for materials/inspection. */
+    kind?: string;
+    /** Local-space center. */
+    position: readonly [number, number, number];
+    /** Full box dimensions (w, h, d) in meters. */
+    size: readonly [number, number, number];
+    rotationY?: number;
+    /** Hex color; the renderer falls back to a neutral material when absent. */
+    color?: string;
+}
+/** A resolved generator asset: its parts plus the overall local-space bounds (min/max corners). */
+export interface GeneratedAsset {
+    parts: GeneratedPart[];
+    bounds: {
+        min: readonly [number, number, number];
+        max: readonly [number, number, number];
+    };
+    /**
+     * The declared local-space direction the asset's "front" faces (a bookcase's open/book face, a
+     * building's entrance) — so a camera rig or placement tool can orient it without hand-tuned
+     * `rotationY`. Omit to use the convention default, +Z (`DEFAULT_FORWARD` in `./facing`); every
+     * generator should build its front toward +Z unless it declares otherwise.
+     */
+    forward?: readonly [number, number, number];
+}
+/** A registered asset generator — schema drives the inspector; `generate` is a pure seeded function. */
+export interface AssetGeneratorDefinition {
+    id: string;
+    label: string;
+    schema: ParamSchema;
+    /** Deterministic geometry from validated params + a seed string. Same inputs → same parts. */
+    generate: (params: ParsedParams, seed: string) => GeneratedAsset;
+}
+/** Register a parametric asset generator. Idempotent per id (last wins); call at module load. */
+export declare function registerAssetGenerator(definition: AssetGeneratorDefinition): void;
+/** The registered generator for an id, or undefined. @internal */
+export declare function getAssetGenerator(id: string): AssetGeneratorDefinition | undefined;
+/** Every registered generator, in registration order. @internal */
+export declare function listAssetGenerators(): AssetGeneratorDefinition[];
+/**
+ * Compute bounds from parts (each part is an axis-aligned box at its center) — a helper generators
+ * return so callers can frame/ground the asset without re-deriving it.
+ */
+export declare function partsBounds(parts: readonly GeneratedPart[]): GeneratedAsset["bounds"];
+/**
+ * Re-resolve a placed generator instance from its stored `meta` (`{ assetId, seed, ...params }`): look
+ * up the generator, parse its params off `meta` against the schema, and generate. Returns null when
+ * `assetId` names no registered generator. This is what a runtime renderer calls per placed instance.
+ * @internal
+ */
+export declare function resolveGeneratorAsset(meta: Record<string, unknown> | undefined): GeneratedAsset | null;

package/dist/scene/assetGenerator.js

@@ -0,0 +1,64 @@
+/**
+ * The generator-asset seam: register a parametric asset generator (`generate(params, seed) → parts`)
+ * so a slider-driven prop (a bookcase with width/shelves/book-density, a building with floors/bays)
+ * lives in the catalog alongside static GLBs. A placed instance stores only `{ assetId, params, seed }`
+ * — the geometry is re-resolved at runtime, never baked. Schema drives the inspector via #809. The
+ * generic seam is engine; concrete generators (building, bookcase) are adopters registered from
+ * game/example code — the building generator is the one engine adopter, as a proof it composes.
+ *
+ * @capability asset-generator seeded parametric geometry registered as a placeable asset
+ */
+import { parseParams } from "./sceneKinds.js";
+const generators = new Map();
+/** Register a parametric asset generator. Idempotent per id (last wins); call at module load. */
+export function registerAssetGenerator(definition) {
+    generators.set(definition.id, definition);
+}
+/** The registered generator for an id, or undefined. @internal */
+export function getAssetGenerator(id) {
+    return generators.get(id);
+}
+/** Every registered generator, in registration order. @internal */
+export function listAssetGenerators() {
+    return [...generators.values()];
+}
+/**
+ * Compute bounds from parts (each part is an axis-aligned box at its center) — a helper generators
+ * return so callers can frame/ground the asset without re-deriving it.
+ */
+export function partsBounds(parts) {
+    if (parts.length === 0)
+        return { min: [0, 0, 0], max: [0, 0, 0] };
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (const part of parts) {
+        minX = Math.min(minX, part.position[0] - part.size[0] / 2);
+        minY = Math.min(minY, part.position[1] - part.size[1] / 2);
+        minZ = Math.min(minZ, part.position[2] - part.size[2] / 2);
+        maxX = Math.max(maxX, part.position[0] + part.size[0] / 2);
+        maxY = Math.max(maxY, part.position[1] + part.size[1] / 2);
+        maxZ = Math.max(maxZ, part.position[2] + part.size[2] / 2);
+    }
+    return { min: [minX, minY, minZ], max: [maxX, maxY, maxZ] };
+}
+/**
+ * Re-resolve a placed generator instance from its stored `meta` (`{ assetId, seed, ...params }`): look
+ * up the generator, parse its params off `meta` against the schema, and generate. Returns null when
+ * `assetId` names no registered generator. This is what a runtime renderer calls per placed instance.
+ * @internal
+ */
+export function resolveGeneratorAsset(meta) {
+    const assetId = typeof meta?.["assetId"] === "string" ? meta["assetId"] : undefined;
+    if (assetId === undefined)
+        return null;
+    const generator = generators.get(assetId);
+    if (generator === undefined)
+        return null;
+    const seed = typeof meta?.["seed"] === "string" ? meta["seed"] : assetId;
+    const params = parseParams(generator.schema, meta);
+    return generator.generate(params, seed);
+}