@jgengine/shell 0.19.0 → 0.21.0

package/dist/world/staticObjectBatches.js

@@ -0,0 +1,163 @@
+import * as THREE from "three";
+import { POINTER_OBJECT_INSTANCES_KEY } from "../pointer/pointerService.js";
+/** The same compatibility gate is used when live placements change after grouping. @internal */
+export function canBatchStaticObject(candidate) {
+    const { object, model, catalog } = candidate;
+    return candidate.authored && !candidate.custom && candidate.style === undefined &&
+        isCompatibleStaticObject(object, model, catalog);
+}
+/** Checks a live placement without constructing a grouping candidate. @internal */
+export function isCompatibleStaticObject(object, model, catalog) {
+    const animation = object.animation ?? model?.animation;
+    return model !== undefined &&
+        object.visual === undefined && object.state === undefined && object.slots === undefined &&
+        catalog?.proximityPrompt === undefined && (catalog?.verbs?.length ?? 0) === 0 &&
+        (catalog?.breakable === undefined || catalog.breakable === false) && catalog?.slotInventory === undefined &&
+        (animation === undefined || animation === "auto" || animation === "none") && model.ik === undefined &&
+        (model.scale ?? 1) >= 0 && (model.parts?.length ?? 0) === 0 && (model.attachments?.length ?? 0) === 0 &&
+        model.partMotion === undefined && model.material?.maps === undefined && (model.materialAssignments?.length ?? 0) === 0 &&
+        (model.hiddenNodes === undefined || (Array.isArray(model.hiddenNodes) && model.hiddenNodes.length === 0));
+}
+/** Stable exclusion snapshot; only compatibility transitions allocate. @internal */
+export function incompatibleStaticObjectIds(batch, get, catalog, previous, fallbackObjects) {
+    const compatible = (object) => object.catalogId === batch.objects[0].catalogId &&
+        isCompatibleStaticObject(object, batch.model, catalog(object.instanceId));
+    let count = 0;
+    let changed = false;
+    for (const object of batch.objects) {
+        const live = get(object.instanceId);
+        if (live !== null && !compatible(live)) {
+            changed ||= previous[count] !== live.instanceId;
+            const before = fallbackObjects?.get(live.instanceId);
+            if (before !== undefined)
+                changed ||= before.catalogId !== live.catalogId || before.animation !== live.animation ||
+                    before.visual !== live.visual || before.state !== live.state || before.slots !== live.slots;
+            fallbackObjects?.set(live.instanceId, live);
+            count++;
+        }
+    }
+    if (fallbackObjects !== undefined)
+        for (const id of fallbackObjects.keys()) {
+            const live = get(id);
+            if (live === null || compatible(live))
+                fallbackObjects.delete(id);
+        }
+    if (!changed && count === previous.length)
+        return previous;
+    return batch.objects.flatMap((object) => {
+        const live = get(object.instanceId);
+        return live !== null && !compatible(live) ? [live.instanceId] : [];
+    });
+}
+/** Groups compatible authored props above eight placements per spatial cell. @internal */
+export function groupStaticObjects(candidates, chunkSize = 24, previous) {
+    const groups = new Map();
+    const singles = [];
+    for (const candidate of candidates) {
+        const { object, model } = candidate;
+        if (model === undefined || !canBatchStaticObject(candidate)) {
+            singles.push(candidate);
+            continue;
+        }
+        const key = JSON.stringify([object.catalogId, Math.floor(object.position[0] / chunkSize), Math.floor(object.position[2] / chunkSize), model]);
+        let group = groups.get(key);
+        if (group === undefined) {
+            group = { batch: { key, model, objects: [] }, candidates: [] };
+            groups.set(key, group);
+        }
+        group.batch.objects.push(object);
+        group.candidates.push(candidate);
+    }
+    const batches = [];
+    for (const { batch, candidates: members } of groups.values()) {
+        if (batch.objects.length > 8) {
+            const cached = previous?.get(batch.key);
+            batches.push(cached !== undefined && cached.objects.length === batch.objects.length &&
+                cached.objects.every((object, index) => object.instanceId === batch.objects[index].instanceId) ? cached : batch);
+        }
+        else
+            singles.push(...members);
+    }
+    return { batches, singles };
+}
+/** Rejects loaded scenes whose behavior cannot be represented by static instanced draws. @internal */
+export function canInstanceStaticScene(scene, clips) {
+    if (clips.length > 0)
+        return false;
+    scene.updateMatrixWorld(true);
+    if (!scene.matrix.equals(new THREE.Matrix4()))
+        return false;
+    let supported = true;
+    scene.traverse((node) => {
+        if (node.layers.mask !== 1 || node.renderOrder !== 0 || node.matrix.determinant() < 0)
+            supported = false;
+        const mesh = node;
+        if (!mesh.isMesh) {
+            if (!node.isGroup && node.type !== "Object3D" && node.type !== "Scene")
+                supported = false;
+            return;
+        }
+        if (mesh.isSkinnedMesh || mesh.isInstancedMesh ||
+            mesh.morphTargetInfluences !== undefined || mesh.onBeforeRender !== THREE.Object3D.prototype.onBeforeRender ||
+            mesh.onAfterRender !== THREE.Object3D.prototype.onAfterRender)
+            supported = false;
+        const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        if (materials.some((material) => material.transparent || material.isShaderMaterial))
+            supported = false;
+        const elements = mesh.matrixWorld.elements;
+        for (let a = 0; a < 3; a++)
+            for (let b = a + 1; b < 3; b++) {
+                const dot = elements[a * 4] * elements[b * 4] + elements[a * 4 + 1] * elements[b * 4 + 1] + elements[a * 4 + 2] * elements[b * 4 + 2];
+                const lengthA = Math.hypot(elements[a * 4], elements[a * 4 + 1], elements[a * 4 + 2]);
+                const lengthB = Math.hypot(elements[b * 4], elements[b * 4 + 1], elements[b * 4 + 2]);
+                // Three's instanced normal transform assumes orthogonal matrix columns.
+                if (Math.abs(dot) > 1e-5 * lengthA * lengthB)
+                    supported = false;
+            }
+    });
+    return supported;
+}
+/** Compact visible placements and update picking identities without allocating per instance. @internal */
+export function syncStaticObjectSource(mesh, source, objects, get, visible, scratch) {
+    const ids = (mesh.userData[POINTER_OBJECT_INSTANCES_KEY] ??= []);
+    const poses = (mesh.userData["jgStaticObjectPoses"] ??= []);
+    if (mesh.userData["jgStaticObjectSource"] !== source) {
+        poses.length = 0;
+        mesh.userData["jgStaticObjectSource"] = source;
+    }
+    let count = 0;
+    let changed = false;
+    const composed = scratch.matrixWorld;
+    for (const object of objects) {
+        const live = get(object.instanceId);
+        if (live === null || !visible(live.instanceId))
+            continue;
+        if (poses[count] === live) {
+            ids[count++] = live.instanceId;
+            continue;
+        }
+        scratch.position.fromArray(live.position);
+        scratch.rotation.set(0, live.rotationY, 0);
+        scratch.updateMatrix();
+        composed.multiplyMatrices(scratch.matrix, source.localMatrix);
+        const offset = count * 16;
+        for (let axis = 0; axis < 16; axis += 1) {
+            if (mesh.instanceMatrix.array[offset + axis] !== Math.fround(composed.elements[axis])) {
+                changed = true;
+                break;
+            }
+        }
+        mesh.setMatrixAt(count, composed);
+        poses[count] = live;
+        ids[count++] = live.instanceId;
+    }
+    ids.length = count;
+    poses.length = count;
+    changed ||= mesh.count !== count;
+    mesh.count = count;
+    mesh.visible = count > 0;
+    if (changed) {
+        mesh.instanceMatrix.needsUpdate = true;
+        mesh.computeBoundingSphere();
+    }
+}

package/dist/world/worldBarSamples.d.ts

@@ -1,7 +1,8 @@
-import type { SceneEntity } from "@jgengine/core/scene/entityStore";
-import type { CatalogEntityRole } from "@jgengine/core/runtime/gameContext";
-import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { SceneEntity, EntityPosition } from "@jgengine/core/scene/entityStore";
+import type { CatalogEntityRole, GameContext } from "@jgengine/core/runtime/gameContext";
 export interface WorldBarSample {
+    /** Live anchor id used by retained samples; omitted for caller-painted screen samples. */
+    entityId?: string;
     x: number;
     y: number;
     percent: number;
@@ -16,49 +17,52 @@ export interface Projectable {
     y: number;
     z: number;
 }
-/**
- * True when world geometry stands between the player's eye and `target`. World bars and nameplates
- * are DOM/canvas overlays projected to screen space, so nothing in the depth buffer can hide them —
- * without this test an enemy's health bar reads straight through the building it is standing behind.
- * @internal
- */
-export declare function worldBarOccluded(ctx: GameContext, from: readonly [number, number, number], target: readonly [number, number, number], eyeHeight: number): boolean;
-/**
- * Projects every non-local, role/distance-filtered entity carrying `statId` into `into` as a
- * `WorldBarSample`. Pure data step behind `WorldHealthBars` — call it directly to paint the bars
- * with your own renderer.
- * @internal
- */
-export declare function collectWorldBarSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: {
-    matrixWorldInverse: unknown;
+/** Render camera matrices; world translation supplies the overlay's viewpoint. */
+export interface WorldOverlayCamera {
+    matrixWorld: {
+        elements: ArrayLike<number>;
+    };
+    matrixWorldInverse: {
+        elements: ArrayLike<number>;
+    };
     projectionMatrix: unknown;
-}, viewport: {
+}
+/** Sampling policy shared by health bars and nameplates. */
+export interface WorldOverlaySampleOptions {
+    /** Maximum sampled overlays and visibility rays per refresh. Default 64; unchecked entities stay hidden. */
+    maxSamples?: number;
+    /** Match a renderer's visibility or membership policy. */
+    isVisible?: (id: string) => boolean;
+    /** Authored display name; return null to omit the nameplate. */
+    resolveName?: (entity: SceneEntity) => string | null;
+}
+/** True when blocking scene geometry lies between the render camera and overlay anchor. @internal */
+export declare function worldBarOccluded(ctx: GameContext, from: EntityPosition, target: EntityPosition): boolean;
+/** Project nearby live non-local entities carrying `statId`; occlusion defaults on. @internal */
+export declare function collectWorldBarSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: WorldOverlayCamera, viewport: {
     width: number;
     height: number;
-}, into: WorldBarSample[], project: Projectable, maxDistance?: number, occlude?: boolean): number;
-/** One entity's projected nameplate: screen `x`/`y`, display `name`, health `percent` (or `null` when statless), and world `distance` from the player. */
+}, into: WorldBarSample[], project: Projectable, maxDistance?: number, occlude?: boolean, options?: WorldOverlaySampleOptions): number;
+/** Reproject retained bar anchors without a nearby query or visibility ray. @internal */
+export declare function refreshWorldBarSamples(ctx: GameContext, height: number, camera: WorldOverlayCamera, viewport: {
+    width: number;
+    height: number;
+}, samples: WorldBarSample[], project: Projectable, maxDistance?: number, options?: WorldOverlaySampleOptions): void;
+/** Projected nameplate with optional health and distance from the render camera. */
 export interface NameplateSample {
     id: string;
     name: string;
     x: number;
     y: number;
-    /** Health-stat fraction 0..1, or `null` when the entity carries no `statId` stat (name-only nameplate). */
+    /** Health-stat fraction 0..1, or null for a statless entity. */
     percent: number | null;
     distance: number;
 }
-/**
- * Projects every non-local, role/distance-filtered entity into `into` as a
- * `NameplateSample`. Pure data step powering `WorldNameplates` — swap in your
- * own renderer by calling this directly instead of the component.
- * @internal
- */
-export declare function collectNameplateSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: {
-    matrixWorldInverse: unknown;
-    projectionMatrix: unknown;
-}, viewport: {
+/** Project nearby live non-local nameplates; occlusion defaults on. @internal */
+export declare function collectNameplateSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: WorldOverlayCamera, viewport: {
     width: number;
     height: number;
-}, into: NameplateSample[], project: Projectable, maxDistance?: number, occlude?: boolean): number;
+}, into: NameplateSample[], project: Projectable, maxDistance?: number, occlude?: boolean, options?: WorldOverlaySampleOptions): number;
 /** @internal */
 export declare function paintWorldBarSamples(canvas: {
     width: number;

package/dist/world/worldBarSamples.js

@@ -1,98 +1,140 @@
 import { worldHealthBarAllowsRole } from "@jgengine/core/game/playableGame";
-/**
- * True when world geometry stands between the player's eye and `target`. World bars and nameplates
- * are DOM/canvas overlays projected to screen space, so nothing in the depth buffer can hide them —
- * without this test an enemy's health bar reads straight through the building it is standing behind.
- * @internal
- */
-export function worldBarOccluded(ctx, from, target, eyeHeight) {
-    const origin = [from[0], from[1] + eyeHeight, from[2]];
-    const dx = target[0] - origin[0];
-    const dy = target[1] + eyeHeight - origin[1];
-    const dz = target[2] - origin[2];
+/** True when blocking scene geometry lies between the render camera and overlay anchor. @internal */
+export function worldBarOccluded(ctx, from, target) {
+    const dx = target[0] - from[0];
+    const dy = target[1] - from[1];
+    const dz = target[2] - from[2];
     const length = Math.hypot(dx, dy, dz);
     if (length < 0.001)
         return false;
-    const hit = ctx.scene.object.raycast({
-        origin,
+    return ctx.scene.raycast({
+        origin: from,
         direction: [dx / length, dy / length, dz / length],
-        // Stop short of the entity so its own collider never counts as its own occluder.
-        maxDistance: length - 0.5,
-    });
-    return hit !== null;
+        maxDistance: length - 0.001,
+        filter: { entities: false },
+        accept: (hit) => hit.blocks,
+    }) !== null;
 }
-/**
- * Projects every non-local, role/distance-filtered entity carrying `statId` into `into` as a
- * `WorldBarSample`. Pure data step behind `WorldHealthBars` — call it directly to paint the bars
- * with your own renderer.
- * @internal
- */
-export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 60, occlude = false) {
+function cameraOrigin(camera) {
+    const matrix = camera.matrixWorld.elements;
+    return [matrix[12], matrix[13], matrix[14]];
+}
+function projectAnchor(entity, height, camera, project) {
+    const anchor = [entity.position[0], entity.position[1] + height, entity.position[2]];
+    const inverse = camera.matrixWorldInverse.elements;
+    const cameraZ = inverse[2] * anchor[0] + inverse[6] * anchor[1] + inverse[10] * anchor[2] + inverse[14];
+    if (!Number.isFinite(cameraZ) || cameraZ >= 0)
+        return null;
+    project.set(...anchor).project(camera);
+    if (!Number.isFinite(project.x) || !Number.isFinite(project.y) || !Number.isFinite(project.z))
+        return null;
+    if (Math.abs(project.x) > 1 || Math.abs(project.y) > 1 || Math.abs(project.z) > 1)
+        return null;
+    return anchor;
+}
+function healthFraction(stat) {
+    const range = stat.max - stat.min;
+    return range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
+}
+function eligibleEntity(ctx, id, options) {
+    if (id === ctx.player.userId || id === ctx.player.possession.active(ctx.player.userId) || options.isVisible?.(id) === false)
+        return null;
+    const entity = ctx.scene.entity.get(id);
+    if (entity === null || entity.hidden === true)
+        return null;
+    const health = ctx.scene.entity.stats.get(id, "health");
+    if (health !== null && health.current <= health.min)
+        return null;
+    return entity;
+}
+function sampleLimit(options) {
+    return Math.max(0, Math.min(256, Math.floor(options.maxSamples ?? 64) || 0));
+}
+/** Project nearby live non-local entities carrying `statId`; occlusion defaults on. @internal */
+export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 60, occlude = true, options = {}) {
     into.length = 0;
-    const playerId = ctx.player.userId;
-    const player = ctx.scene.entity.get(playerId);
-    for (const entity of ctx.scene.entity.list()) {
-        if (entity.id === playerId)
+    const origin = cameraOrigin(camera);
+    const limit = sampleLimit(options);
+    if (limit === 0 || !Number.isFinite(maxDistance) || maxDistance <= 0)
+        return 0;
+    let checked = 0;
+    for (const id of ctx.scene.entity.inRadius(origin, maxDistance)) {
+        const entity = eligibleEntity(ctx, id, options);
+        if (entity === null || !worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
             continue;
-        if (!worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
+        const stat = ctx.scene.entity.stats.get(id, statId);
+        if (stat === null)
             continue;
-        if (player !== null &&
-            Math.hypot(entity.position[0] - player.position[0], entity.position[2] - player.position[2]) >
-                maxDistance) {
+        const anchor = projectAnchor(entity, height, camera, project);
+        if (anchor === null)
             continue;
-        }
-        if (occlude && player !== null && worldBarOccluded(ctx, player.position, entity.position, 1.5))
+        if (checked++ >= limit)
+            break;
+        if (occlude && worldBarOccluded(ctx, origin, anchor))
             continue;
-        const stat = ctx.scene.entity.stats.get(entity.id, statId);
-        if (stat === null)
+        into.push({
+            entityId: id,
+            x: (project.x * 0.5 + 0.5) * viewport.width,
+            y: (-project.y * 0.5 + 0.5) * viewport.height,
+            percent: healthFraction(stat),
+        });
+    }
+    return into.length;
+}
+/** Reproject retained bar anchors without a nearby query or visibility ray. @internal */
+export function refreshWorldBarSamples(ctx, height, camera, viewport, samples, project, maxDistance = 60, options = {}) {
+    const origin = cameraOrigin(camera);
+    let kept = 0;
+    for (const sample of samples) {
+        if (sample.entityId === undefined)
+            continue;
+        const entity = eligibleEntity(ctx, sample.entityId, options);
+        if (entity === null || Math.hypot(entity.position[0] - origin[0], entity.position[1] - origin[1], entity.position[2] - origin[2]) > maxDistance)
             continue;
-        const range = stat.max - stat.min;
-        const percent = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
-        project.set(entity.position[0], entity.position[1] + height, entity.position[2]);
-        project.project(camera);
-        if (project.z < -1 || project.z > 1)
+        if (projectAnchor(entity, height, camera, project) === null)
             continue;
-        const x = (project.x * 0.5 + 0.5) * viewport.width;
-        const y = (-project.y * 0.5 + 0.5) * viewport.height;
-        into.push({ x, y, percent });
+        sample.x = (project.x * 0.5 + 0.5) * viewport.width;
+        sample.y = (-project.y * 0.5 + 0.5) * viewport.height;
+        samples[kept++] = sample;
     }
-    return into.length;
+    samples.length = kept;
+}
+function defaultDisplayName(entity) {
+    const name = entity.name.trim();
+    // Entity names also key catalogs; machine identifiers need an explicit display-name resolver.
+    return name === entity.id || /^[a-z0-9_-]+$/.test(name) || /[_:/]/.test(name) ? null : name || null;
 }
-/**
- * Projects every non-local, role/distance-filtered entity into `into` as a
- * `NameplateSample`. Pure data step powering `WorldNameplates` — swap in your
- * own renderer by calling this directly instead of the component.
- * @internal
- */
-export function collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 40, occlude = false) {
+/** Project nearby live non-local nameplates; occlusion defaults on. @internal */
+export function collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 40, occlude = true, options = {}) {
     into.length = 0;
-    const playerId = ctx.player.userId;
-    const player = ctx.scene.entity.get(playerId);
-    for (const entity of ctx.scene.entity.list()) {
-        if (entity.id === playerId)
+    const origin = cameraOrigin(camera);
+    const limit = sampleLimit(options);
+    if (limit === 0 || !Number.isFinite(maxDistance) || maxDistance <= 0)
+        return 0;
+    let checked = 0;
+    for (const id of ctx.scene.entity.inRadius(origin, maxDistance)) {
+        const entity = eligibleEntity(ctx, id, options);
+        if (entity === null || !worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
             continue;
-        if (!worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
+        const name = (options.resolveName ?? defaultDisplayName)(entity)?.trim();
+        if (!name)
             continue;
-        const distance = player === null
-            ? 0
-            : Math.hypot(entity.position[0] - player.position[0], entity.position[2] - player.position[2]);
-        if (player !== null && distance > maxDistance)
+        const anchor = projectAnchor(entity, height, camera, project);
+        if (anchor === null)
             continue;
-        if (occlude && player !== null && worldBarOccluded(ctx, player.position, entity.position, 1.5))
-            continue;
-        const stat = ctx.scene.entity.stats.get(entity.id, statId);
-        let percent = null;
-        if (stat !== null) {
-            const range = stat.max - stat.min;
-            percent = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
-        }
-        project.set(entity.position[0], entity.position[1] + height, entity.position[2]);
-        project.project(camera);
-        if (project.z < -1 || project.z > 1)
+        if (checked++ >= limit)
+            break;
+        if (occlude && worldBarOccluded(ctx, origin, anchor))
             continue;
-        const x = (project.x * 0.5 + 0.5) * viewport.width;
-        const y = (-project.y * 0.5 + 0.5) * viewport.height;
-        into.push({ id: entity.id, name: entity.name, x, y, percent, distance });
+        const stat = ctx.scene.entity.stats.get(id, statId);
+        into.push({
+            id,
+            name,
+            x: (project.x * 0.5 + 0.5) * viewport.width,
+            y: (-project.y * 0.5 + 0.5) * viewport.height,
+            percent: stat === null ? null : healthFraction(stat),
+            distance: Math.hypot(entity.position[0] - origin[0], entity.position[1] - origin[1], entity.position[2] - origin[2]),
+        });
     }
     return into.length;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.19.0",
-    "@jgengine/react": "^0.19.0",
-    "@jgengine/ws": "^0.19.0"
+    "@jgengine/core": "^0.21.0",
+    "@jgengine/react": "^0.21.0",
+    "@jgengine/ws": "^0.21.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/ce-handoff/SKILL.md

@@ -25,7 +25,7 @@ Create one immutable handoff at the destination the user requested, or use the m
 ### Build the handoff
 
 1. Distill the current objective and the user's latest intent. If a focus was supplied, make it the `resume_focus`.
-2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md` / `CLAUDE.md`, `workflow`, domain skills).
+2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md`, `workflow`, domain skills).
 3. Point to plans, issues, commits, diffs, documentation, and relevant files instead of reproducing their contents. Prefer repository-relative paths (`docs/plans/…`, `packages/…`, `Games/…`).
 4. Redact secrets, credentials, tokens, and unrelated personal information. Preserve operational paths only when the next agent needs them.
 5. Write or publish with existing tools. If the user named another path, folder, format, or publication destination, honor it. Do not also create a managed-store copy unless asked.

package/skills/jgengine/SKILL.md

@@ -9,6 +9,22 @@ This skill decides what to load; it is not an engine manual. Package map, comman
 
 A created project installs only `jgengine`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
 
+Created projects pin their scaffolding CLI as a local devDependency, separately from SDK versions. Run `npx jgengine doctor` after SDK upgrades to check CLI compatibility. Skill installation preserves newer or differing unversioned copies; update the project CLI first, and use `skills -p --force` only when replacement is intended. Each packaged skill install records its CLI and SDK versions in `.jgengine-version.json`.
+
+## Framework-first decisions
+
+For every requested interaction, feature, fix or visual change, follow the boundary in
+[AGENTS.md](../../../AGENTS.md): discover the installed
+capability, adopt it, or improve its shared owner before adding reusable game-local code.
+Games keep unique rules, content, assets and presentation. Custom markup is not a reason
+to copy focus handling, input tracking, storage or model lifecycle.
+
+Check installed versions before recreating an upstream fix. A published upgrade may
+replace a workaround; a beta merge does not update consumers. In the games workspace,
+the root catalog owns SDK versions. After adoption, remove superseded local machinery
+and verify the actual game. Outside these repositories, report missing SDK contracts
+upstream rather than treating a local engine implementation as the finished solution.
+
 ## 1. Establish the target
 
 For greenfield builds, write `src/art-direction.md` before any code.
@@ -26,6 +42,10 @@ Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player
 
 For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
 
+`doctor` and `upgrade` resolve Bun `catalog:` and `catalog:<name>` declarations from the nearest workspace's `workspaces.catalog` or `workspaces.catalogs`, and follow hoisted SDK installs. Missing or malformed catalog entries fail diagnostics. `upgrade` is read-only by default. For catalog-owned versions, run `upgrade --plan --to <published-version>` at the workspace root or in a game, review the whole root catalog plan and migrations, then run `upgrade --apply --to <published-version>`. Apply preserves per-game `catalog:` declarations, unrelated text, CLI/github versions, and a held editor override; it verifies published SDK targets and refuses files changed while planning. Apply changes declarations only: run `bun install` at the root, then `jgengine doctor --workspace --json` once there to check installed SDK identities across declared workspace owners. Rebuild, migrate, and verify game behavior afterward. `--json` includes exact before/after text; an apply prints its plan before writing and reports write status on stderr. A report without installed packages labels its resolved pins as a declared baseline.
+
+When a linked consumer renders differently despite matching root SDK versions, `doctor` checks direct consumers and SDK dependency/peer paths, including private copies with the same version. Review the reported importer and real paths, align the shared catalog and linked-consumer declarations, then reinstall at the root and rerun `doctor --workspace`; a root install may leave private linked-package installs intact. Restart running games after reinstall. Workspace mode checks installed identities only, reports coverage, and refuses unsupported patterns, escaped symlinks or exhausted traversal budgets. The default project audit stays scoped; neither mode covers custom bundler aliases or indirect non-SDK chains.
+
 ## 2. Select domains
 
 Load only rows the target needs. Do not preload every domain.
@@ -49,12 +69,12 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 Within each selected domain:
 
 0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); in the monorepo, `grep -i "<intent>" .claude/skills/*/capabilities.md` does the same. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); agents can use `--json --limit 5` for ranked imports and recipes with total, partial-match, and truncation fields. In the monorepo, `rg -i "<intent>" .claude/skills/*/capabilities.md` does the same search. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
 2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 3. Open the linked reference only for a deeper recipe or trap.
 4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
 
-If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter and a reviewed consumer cleanup; coordinate a differently composed second consumer when applicable. Recipes wire SDK APIs, not copied implementations. If editor-owned content cannot be expressed, file the editor gap first; track any fallback and its removal path.
 
 ## 4. Build and finish