@jgengine/core 0.9.0 → 0.11.0

package/dist/runtime/worldProjection.d.ts

@@ -0,0 +1,47 @@
+import type { SceneEntity } from "../scene/entityStore.js";
+import type { SnapshotViewer } from "./worldSnapshot.js";
+/**
+ * Host-side interest/privacy policy — how the authoritative world projects to each viewer over the
+ * wire. Unset (the default) means every client receives the whole world, exactly as before. Enabling a
+ * field changes only what each client *sees*, never how the host simulates: the game plays identically.
+ * The core replication modules read this to attach a {@link SnapshotModule.project} without the engine
+ * growing a per-feature branch.
+ */
+export interface ReplicationPolicy {
+    /**
+     * Replicate each player's private per-user state (inventory) only to that player — other viewers
+     * receive none of it. Off by default so existing games keep broadcasting every player's state.
+     */
+    privatePerUser?: boolean;
+    /**
+     * Area-of-interest radius in world units: an entity replicates to a viewer only when within this
+     * distance of the viewer's own entity (the entity whose `id` equals the viewer's `userId`). A viewer
+     * always receives its own entity. Omit for no distance culling — every entity to every viewer.
+     */
+    aoiRadius?: number;
+}
+/** True when at least one field of the policy would change the wire payload. A no-op policy needs no projection.
+ * @internal host projection plumbing — games set ReplicationPolicy; the runtime applies it.
+ */
+export declare function policyProjectsViewers(policy: ReplicationPolicy | undefined): boolean;
+/**
+ * Cull an entity list to a viewer's area of interest: keep the viewer's own entity plus every entity
+ * within `radius` of it. When the viewer has no locatable entity the full list is returned (fail-open —
+ * a spectator or not-yet-spawned player still sees the world rather than an empty one).
+ * @internal host projection plumbing
+ */
+export declare function projectEntitiesForViewer(entities: readonly SceneEntity[], viewer: SnapshotViewer, radius: number): readonly SceneEntity[];
+/** The set of entity ids a viewer can see under an area-of-interest radius — the visibility set entity-keyed modules cull against.
+ * @internal host projection plumbing
+ */
+export declare function visibleEntityIds(entities: readonly SceneEntity[], viewer: SnapshotViewer, radius: number): Set<string>;
+/** Keep only the entries of an entity-id-keyed record whose id is in `visible` — the projection for entity stats under area-of-interest.
+ * @internal host projection plumbing
+ */
+export declare function projectByVisibleIds<T>(byId: Record<string, T>, visible: Set<string>): Record<string, T>;
+/**
+ * Narrow a `userId → state` record to only the viewer's own entry — the projection for private
+ * per-user state (inventory, wallets) so one client never receives another player's private data.
+ * @internal host projection plumbing
+ */
+export declare function projectPerUserForViewer<T>(byUser: Record<string, T>, viewer: SnapshotViewer): Record<string, T>;

package/dist/runtime/worldProjection.js

@@ -0,0 +1,52 @@
+/** True when at least one field of the policy would change the wire payload. A no-op policy needs no projection.
+ * @internal host projection plumbing — games set ReplicationPolicy; the runtime applies it.
+ */
+export function policyProjectsViewers(policy) {
+    if (policy === undefined)
+        return false;
+    return policy.privatePerUser === true || policy.aoiRadius !== undefined;
+}
+function distanceSquared(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    const dz = a[2] - b[2];
+    return dx * dx + dy * dy + dz * dz;
+}
+/**
+ * Cull an entity list to a viewer's area of interest: keep the viewer's own entity plus every entity
+ * within `radius` of it. When the viewer has no locatable entity the full list is returned (fail-open —
+ * a spectator or not-yet-spawned player still sees the world rather than an empty one).
+ * @internal host projection plumbing
+ */
+export function projectEntitiesForViewer(entities, viewer, radius) {
+    const self = entities.find((entity) => entity.id === viewer.userId);
+    if (self === undefined)
+        return entities;
+    const radiusSquared = radius * radius;
+    return entities.filter((entity) => entity.id === viewer.userId || distanceSquared(entity.position, self.position) <= radiusSquared);
+}
+/** The set of entity ids a viewer can see under an area-of-interest radius — the visibility set entity-keyed modules cull against.
+ * @internal host projection plumbing
+ */
+export function visibleEntityIds(entities, viewer, radius) {
+    return new Set(projectEntitiesForViewer(entities, viewer, radius).map((entity) => entity.id));
+}
+/** Keep only the entries of an entity-id-keyed record whose id is in `visible` — the projection for entity stats under area-of-interest.
+ * @internal host projection plumbing
+ */
+export function projectByVisibleIds(byId, visible) {
+    const out = {};
+    for (const [id, value] of Object.entries(byId))
+        if (visible.has(id))
+            out[id] = value;
+    return out;
+}
+/**
+ * Narrow a `userId → state` record to only the viewer's own entry — the projection for private
+ * per-user state (inventory, wallets) so one client never receives another player's private data.
+ * @internal host projection plumbing
+ */
+export function projectPerUserForViewer(byUser, viewer) {
+    const own = byUser[viewer.userId];
+    return own === undefined ? {} : { [viewer.userId]: own };
+}

package/dist/runtime/worldReplication.d.ts

@@ -0,0 +1,69 @@
+import type { SceneEntity } from "../scene/entityStore.js";
+import type { StatValueMap } from "../scene/entityStats.js";
+import type { WorldSnapshot } from "./worldSnapshot.js";
+/**
+ * A revision-stamped delta over a {@link WorldSnapshot}. The host sends one per tick to each client, carrying
+ * only what changed since that client's last acknowledged revision — entity/stat/store deltas plus whole
+ * snapshots of any other opted-in module (feed, leaderboard, chat, …) that changed. Fold it onto a prior
+ * baseline with {@link applyWorldDiff}.
+ */
+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>;
+    removedStats: readonly string[];
+    store: readonly (readonly [string, unknown])[];
+    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 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;
+};
+/** The stateful diff tracker returned by {@link createWorldReplicator}: `commit()`, `diff(sinceRevision)`, `revision()`. */
+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`. `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

@@ -0,0 +1,217 @@
+const CORE_KEYS = new Set(["entities", "stats", "store"]);
+/**
+ * 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 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();
+    const stats = new Map();
+    const removedStats = new Map();
+    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) {
+            const prev = tracked.get(key);
+            if (prev === undefined || prev.json !== json) {
+                tracked.set(key, { json, revision: nextRevision });
+                removed.delete(key);
+                changed = true;
+            }
+        }
+        for (const key of tracked.keys()) {
+            if (!live.has(key)) {
+                tracked.delete(key);
+                removed.set(key, nextRevision);
+                changed = true;
+            }
+        }
+        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();
+        for (const entity of (snapshot["entities"] ?? [])) {
+            liveEntities.set(entity.id, JSON.stringify(entity));
+        }
+        const liveStats = new Map();
+        for (const [id, value] of Object.entries((snapshot["stats"] ?? {}))) {
+            liveStats.set(id, JSON.stringify(value));
+        }
+        const liveStore = new Map();
+        for (const [key, value] of (snapshot["store"] ?? [])) {
+            liveStore.set(key, JSON.stringify(value ?? null));
+        }
+        const liveModules = new Map();
+        for (const [key, value] of Object.entries(snapshot)) {
+            if (CORE_KEYS.has(key))
+                continue;
+            liveModules.set(key, JSON.stringify(value ?? null));
+        }
+        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, removedModules, nextRevision) || changed;
+        if (changed)
+            revision = nextRevision;
+        return revision;
+    }
+    function diff(sinceRevision) {
+        const changedEntities = [];
+        for (const [, tracked] of entities) {
+            if (tracked.revision > sinceRevision)
+                changedEntities.push(JSON.parse(tracked.json));
+        }
+        const changedStats = {};
+        for (const [id, tracked] of stats) {
+            if (tracked.revision > sinceRevision)
+                changedStats[id] = JSON.parse(tracked.json);
+        }
+        const changedStore = [];
+        for (const [key, tracked] of store) {
+            if (tracked.revision > sinceRevision)
+                changedStore.push([key, JSON.parse(tracked.json)]);
+        }
+        const changedModules = {};
+        for (const [key, tracked] of modules) {
+            if (tracked.revision > sinceRevision)
+                changedModules[key] = JSON.parse(tracked.json);
+        }
+        return {
+            revision,
+            baseRevision: sinceRevision,
+            entities: changedEntities,
+            removedEntities: keysAfter(removedEntities, sinceRevision),
+            stats: changedStats,
+            removedStats: keysAfter(removedStats, sinceRevision),
+            store: changedStore,
+            removedStore: keysAfter(removedStore, sinceRevision),
+            modules: changedModules,
+            removedModules: keysAfter(removedModules, sinceRevision),
+        };
+    }
+    return { commit, diff, revision: () => revision };
+}
+function keysAfter(map, sinceRevision) {
+    const out = [];
+    for (const [key, revision] of map) {
+        if (revision > sinceRevision)
+            out.push(key);
+    }
+    return out;
+}
+/**
+ * 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`. `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));
+    }
+    const entities = [];
+    const nextEntityIds = new Set();
+    for (const entity of (next["entities"] ?? [])) {
+        nextEntityIds.add(entity.id);
+        const json = JSON.stringify(entity);
+        if (prevEntities.get(entity.id) !== json)
+            entities.push(JSON.parse(json));
+    }
+    const removedEntities = [...prevEntities.keys()].filter((id) => !nextEntityIds.has(id));
+    const prevStats = (prev["stats"] ?? {});
+    const nextStats = (next["stats"] ?? {});
+    const stats = {};
+    for (const [id, value] of Object.entries(nextStats)) {
+        const json = JSON.stringify(value);
+        if (JSON.stringify(prevStats[id]) !== json)
+            stats[id] = JSON.parse(json);
+    }
+    const removedStats = Object.keys(prevStats).filter((id) => !(id in nextStats));
+    const prevStore = new Map((prev["store"] ?? []));
+    const nextStore = new Map((next["store"] ?? []));
+    const store = [];
+    for (const [key, value] of nextStore) {
+        const json = JSON.stringify(value ?? null);
+        if (JSON.stringify(prevStore.get(key) ?? null) !== json)
+            store.push([key, JSON.parse(json)]);
+    }
+    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);
+    }
+    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();
+    for (const entity of (baseline["entities"] ?? []))
+        entityById.set(entity.id, entity);
+    for (const entity of diff.entities)
+        entityById.set(entity.id, entity);
+    for (const id of diff.removedEntities)
+        entityById.delete(id);
+    next["entities"] = Array.from(entityById.values());
+    const statsById = { ...(baseline["stats"] ?? {}) };
+    for (const [id, value] of Object.entries(diff.stats))
+        statsById[id] = value;
+    for (const id of diff.removedStats)
+        delete statsById[id];
+    next["stats"] = statsById;
+    const storeByKey = new Map((baseline["store"] ?? []));
+    for (const [key, value] of diff.store)
+        storeByKey.set(key, value);
+    for (const key of diff.removedStore)
+        storeByKey.delete(key);
+    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

@@ -0,0 +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. 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

@@ -0,0 +1,30 @@
+/**
+ * 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)
+        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.
+ * @internal
+ */
+export function applyWorldSnapshot(modules, snapshot) {
+    for (const module of modules) {
+        if (Object.prototype.hasOwnProperty.call(snapshot, module.key)) {
+            module.hydrate(snapshot[module.key]);
+        }
+    }
+}

package/dist/scene/assetCatalog.d.ts

@@ -1,3 +1,5 @@
+import type { AssetSpace } from "./assetSpace.js";
+/** Measured horizontal footprint, footprint center, and lowest Y of a model in model space. */
 export interface ModelDims {
     footprint: {
         w: number;
@@ -13,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;