@jgengine/shell 0.18.1 → 0.21.0

package/dist/inputSink.js

@@ -5,56 +5,91 @@ import { INPUT_COMMAND } from "@jgengine/core/runtime/hostedGameRunner";
 export function noopInputSink() {
     return { send() { } };
 }
-const remoteInputSources = new Map();
-function remoteInputSourceFor(serverId) {
-    let source = remoteInputSources.get(serverId);
+const remoteInputSources = new WeakMap();
+let lastInputSeq = 0;
+function remoteInputSourceFor(backend, serverId) {
+    let sources = remoteInputSources.get(backend.transport);
+    if (sources === undefined) {
+        sources = new Map();
+        remoteInputSources.set(backend.transport, sources);
+    }
+    let source = sources.get(serverId);
     if (source === undefined) {
-        source = { pending: null, inFlight: false };
-        remoteInputSources.set(serverId, source);
+        source = { pending: null, inFlight: null, latest: null, presses: new Map() };
+        sources.set(serverId, source);
     }
     return source;
 }
+// Use the browser time origin so a full reload stays ahead of the previous client.
+// The local high-water mark also preserves release ordering if its clock regresses.
 function monotonicInputSeq() {
-    return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+    const now = typeof performance !== "undefined" ? performance.timeOrigin + performance.now() : Date.now();
+    return lastInputSeq = Math.max(now, lastInputSeq + 0.001);
 }
 function pumpRemoteInput(backend, serverId, source) {
-    if (source.inFlight)
+    if (source.inFlight !== null)
         return;
     const frame = source.pending;
     if (frame === null) {
-        remoteInputSources.delete(serverId);
+        if (source.presses.size === 0)
+            remoteInputSources.get(backend.transport)?.delete(serverId);
         return;
     }
     source.pending = null;
-    source.inFlight = true;
+    const owner = {};
+    source.inFlight = owner;
+    const presses = [...source.presses.values()].map(press => ({ ...press }));
     const seq = monotonicInputSeq();
+    // Live clients and the joined host have independent simulation clocks. The host
+    // stamps receipt on its next tick; explicit ticks remain supported by replay.
+    const { tick: _clientTick, presses: _framePresses, ...intent } = frame;
     void backend.transport
-        .runCommand({ serverId, command: INPUT_COMMAND, input: { ...frame, seq } })
+        .runCommand({ serverId, command: INPUT_COMMAND, input: { ...intent, ...(presses.length > 0 ? { presses } : {}), seq } })
         .then((result) => {
-        if (!result.ok) {
+        if (result.ok)
+            for (const press of presses)
+                source.presses.delete(press.seq);
+        if (!result.ok)
             console.warn(`[jgengine:input] frame seq=${seq} to server "${serverId}" rejected: ${result.reason}`);
-        }
     })
         .catch((error) => {
         console.warn(`[jgengine:input] frame seq=${seq} to server "${serverId}" failed to send`, error);
     })
         .finally(() => {
-        source.inFlight = false;
+        // An urgent discrete intent supersedes this flight. Its old completion must not
+        // release the replacement's ACK gate or replay the superseded pending frame.
+        if (source.inFlight !== owner)
+            return;
+        source.inFlight = null;
         pumpRemoteInput(backend, serverId, source);
     });
 }
-/**
- * Sends each frame's input to the authoritative host over the transport, reusing the `runCommand` path via
- * {@link INPUT_COMMAND}. Sends are sequenced one-in-flight-at-a-time per `serverId` and stamped with a monotonic
- * seq: a frame sent while one is already in flight replaces the pending frame rather than racing it, so the
- * latest intent always wins and a stale frame can never resolve after (and overwrite) a newer one.
+/** Coalesces continuous frames. Discrete release/reset intents bypass a pending ACK;
+ * the host's monotonic sequence admission rejects any older input arriving afterwards.
  * @internal
  */
 export function remoteInputSink(backend, serverId) {
     return {
-        send(frame) {
-            const source = remoteInputSourceFor(serverId);
-            source.pending = frame;
+        send(frame, options) {
+            const source = remoteInputSourceFor(backend, serverId);
+            if (options?.reset)
+                source.presses.clear();
+            for (const press of frame.presses ?? [])
+                source.presses.set(press.seq, { ...press });
+            // A reset must overtake an identical neutral release that still carries an
+            // unacknowledged press. Intent equality alone does not describe that flight.
+            if (!options?.reset && source.latest !== null && inputFramesEqual(source.latest, frame) && source.presses.size === 0)
+                return;
+            const snapshot = {
+                ...frame, held: [...frame.held],
+                ...(frame.presses === undefined ? {} : { presses: frame.presses.map(press => ({ ...press })) }),
+                pointer: frame.pointer === null ? null : { ...frame.pointer },
+                ...(frame.analog === undefined ? {} : { analog: frame.analog === null ? null : { ...frame.analog } }),
+            };
+            source.latest = snapshot;
+            source.pending = snapshot;
+            if (options?.urgent)
+                source.inFlight = null;
             pumpRemoteInput(backend, serverId, source);
         },
     };
@@ -72,6 +107,10 @@ export function resolveInputSink(opts) {
  * @internal
  */
 export function inputFramesEqual(a, b) {
+    const ap = a.presses ?? [];
+    const bp = b.presses ?? [];
+    if (ap.length !== bp.length || ap.some((press, index) => press.seq !== bp[index].seq || press.action !== bp[index].action))
+        return false;
     if (a.held.length !== b.held.length)
         return false;
     for (let i = 0; i < a.held.length; i++)

package/dist/lazyShell3dPresentation.d.ts

@@ -0,0 +1,9 @@
+import { type ComponentProps } from "react";
+import type { Shell3dPresentation } from "./Shell3dPresentation.js";
+type Presentation = typeof Shell3dPresentation;
+type Props = ComponentProps<Presentation> & {
+    onPresentationReveal?: () => void;
+};
+/** Loads the normal 3D implementation only for a 3D presentation. @internal */
+export declare function LazyShell3dPresentation({ onPresentationReveal, ...props }: Props): import("react").JSX.Element;
+export {};

package/dist/lazyShell3dPresentation.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { lazy, Suspense, useLayoutEffect, useState } from "react";
+import { suspendPlayControls } from "@jgengine/core/game/controlGate";
+import { markPresentationCodeLoadFailure } from "./presentationRecovery.js";
+let loadedPresentation;
+function getPresentation() {
+    return loadedPresentation ??= lazy(() => import("./Shell3dPresentation.js").then((module) => ({ default: module.Shell3dPresentation }), (error) => {
+        throw markPresentationCodeLoadFailure(error);
+    }));
+}
+function LoadingPresentation({ ctx }) {
+    useLayoutEffect(() => suspendPlayControls(ctx), [ctx]);
+    return (_jsx("div", { role: "status", "aria-live": "polite", "data-shell-code-loading": true, style: { display: "grid", placeItems: "center", width: "100%", height: "100%", minHeight: 160, background: "#0f172a", color: "#e2e8f0", fontFamily: "ui-sans-serif, system-ui, sans-serif" }, children: "Loading game view\u2026" }));
+}
+function PresentationReveal({ onReveal }) {
+    // React repeats layout effects when a suspended tree becomes visible again.
+    useLayoutEffect(() => { onReveal?.(); });
+    return null;
+}
+/** Loads the normal 3D implementation only for a 3D presentation. @internal */
+export function LazyShell3dPresentation({ onPresentationReveal, ...props }) {
+    const [Presentation] = useState(getPresentation);
+    return (_jsxs(Suspense, { fallback: _jsx(LoadingPresentation, { ctx: props.ctx }), children: [_jsx(Presentation, { ...props }), _jsx(PresentationReveal, { onReveal: onPresentationReveal })] }));
+}

package/dist/materialOverride.d.ts

@@ -4,6 +4,8 @@ export interface MaterialOverrideOptions {
     clone?: boolean;
     /** Loaded PBR textures matching `ModelMaterialOverride.maps`' roles, applied onto each standard or physical material alongside the tint override. The caller (a React component, via `useTexture`) owns loading; this function never fetches a URL. */
     textures?: MaterialOverrideTextures;
+    /** Records material replacements for the caller's resource owner. */
+    ownMaterial?: (material: THREE.Material) => void;
 }
 /** Loaded PBR textures for `applyMaterialOverride`'s `textures` option — matches `ModelMaterialMaps`' roles. */
 export interface MaterialOverrideTextures {
@@ -14,6 +16,46 @@ export interface MaterialOverrideTextures {
     metalness?: THREE.Texture;
     emissive?: THREE.Texture;
     height?: THREE.Texture;
+    alpha?: THREE.Texture;
+    sheenColor?: THREE.Texture;
+    sheenRoughness?: THREE.Texture;
+    anisotropy?: THREE.Texture;
+    clearcoat?: THREE.Texture;
+    clearcoatRoughness?: THREE.Texture;
+    clearcoatNormal?: THREE.Texture;
+    specularIntensity?: THREE.Texture;
+    specularColor?: THREE.Texture;
+    transmission?: THREE.Texture;
+    thickness?: THREE.Texture;
+    iridescence?: THREE.Texture;
+    iridescenceThickness?: THREE.Texture;
 }
+/** Physical texture roles mapped to the pinned Three renderer's native properties. @internal */
+export declare const MATERIAL_TEXTURE_PROPERTIES: {
+    readonly color: "map";
+    readonly normal: "normalMap";
+    readonly roughness: "roughnessMap";
+    readonly ao: "aoMap";
+    readonly metalness: "metalnessMap";
+    readonly emissive: "emissiveMap";
+    readonly height: "displacementMap";
+    readonly alpha: "alphaMap";
+    readonly sheenColor: "sheenColorMap";
+    readonly sheenRoughness: "sheenRoughnessMap";
+    readonly anisotropy: "anisotropyMap";
+    readonly clearcoat: "clearcoatMap";
+    readonly clearcoatRoughness: "clearcoatRoughnessMap";
+    readonly clearcoatNormal: "clearcoatNormalMap";
+    readonly specularIntensity: "specularIntensityMap";
+    readonly specularColor: "specularColorMap";
+    readonly transmission: "transmissionMap";
+    readonly thickness: "thicknessMap";
+    readonly iridescence: "iridescenceMap";
+    readonly iridescenceThickness: "iridescenceThicknessMap";
+};
+/** Whether authored settings require a physical shader; ordinary PBR stays standard. @internal */
+export declare function requiresPhysicalMaterial(override: ModelMaterialOverride, textures?: MaterialOverrideTextures): boolean;
 /** @internal */
 export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride, options?: MaterialOverrideOptions): void;
+/** Apply the shared override contract to one material. @internal */
+export declare function applyMaterialOverrideToMaterial(material: THREE.Material, override: ModelMaterialOverride, clone: boolean, textures: MaterialOverrideTextures | undefined): THREE.Material;

package/dist/materialOverride.js

@@ -1,50 +1,106 @@
 import * as THREE from "three";
+/** Physical texture roles mapped to the pinned Three renderer's native properties. @internal */
+export const MATERIAL_TEXTURE_PROPERTIES = {
+    color: "map", normal: "normalMap", roughness: "roughnessMap", ao: "aoMap", metalness: "metalnessMap", emissive: "emissiveMap", height: "displacementMap", alpha: "alphaMap",
+    sheenColor: "sheenColorMap", sheenRoughness: "sheenRoughnessMap", anisotropy: "anisotropyMap", clearcoat: "clearcoatMap", clearcoatRoughness: "clearcoatRoughnessMap", clearcoatNormal: "clearcoatNormalMap", specularIntensity: "specularIntensityMap", specularColor: "specularColorMap", transmission: "transmissionMap", thickness: "thicknessMap", iridescence: "iridescenceMap", iridescenceThickness: "iridescenceThicknessMap",
+};
+const physicalNumbers = ["sheen", "sheenRoughness", "anisotropy", "anisotropyRotation", "clearcoat", "clearcoatRoughness", "ior", "specularIntensity", "transmission", "thickness", "attenuationDistance", "iridescence", "iridescenceIOR"];
+const physicalColors = ["sheenColor", "specularColor", "attenuationColor"];
+/** Whether authored settings require a physical shader; ordinary PBR stays standard. @internal */
+export function requiresPhysicalMaterial(override, textures) {
+    return [...physicalNumbers, ...physicalColors, "iridescenceThicknessRange"].some(key => override[key] !== undefined) || Object.keys(textures ?? {}).some(key => ["sheenColor", "sheenRoughness", "anisotropy", "clearcoat", "clearcoatRoughness", "clearcoatNormal", "specularIntensity", "specularColor", "transmission", "thickness", "iridescence", "iridescenceThickness"].includes(key));
+}
 /** @internal */
 export function applyMaterialOverride(root, override, options) {
     const clone = options?.clone !== false;
     const textures = options?.textures;
+    const applied = new Map();
+    const apply = (material) => {
+        const cached = applied.get(material);
+        if (cached !== undefined)
+            return cached;
+        const target = applyMaterialOverrideToMaterial(material, override, clone, textures);
+        applied.set(material, target);
+        if (target !== material)
+            options?.ownMaterial?.(target);
+        return target;
+    };
     root.traverse((node) => {
         const mesh = node;
         if (!mesh.isMesh)
             return;
-        mesh.material = Array.isArray(mesh.material)
-            ? mesh.material.map((material) => overrideOne(material, override, clone, textures))
-            : overrideOne(mesh.material, override, clone, textures);
+        mesh.material = Array.isArray(mesh.material) ? mesh.material.map(apply) : apply(mesh.material);
     });
 }
-function overrideOne(material, override, clone, textures) {
+/** Apply the shared override contract to one material. @internal */
+export function applyMaterialOverrideToMaterial(material, override, clone, textures) {
     if (!isStandardOrPhysicalMaterial(material))
         return material;
-    const target = clone ? material.clone() : material;
-    if (override.color !== undefined)
-        target.color.set(override.color);
-    if (override.metalness !== undefined)
-        target.metalness = override.metalness;
-    if (override.roughness !== undefined)
-        target.roughness = override.roughness;
-    if (override.emissive !== undefined)
-        target.emissive.set(override.emissive);
-    if (override.emissiveIntensity !== undefined)
-        target.emissiveIntensity = override.emissiveIntensity;
-    if (textures?.color !== undefined)
-        target.map = textures.color;
-    if (textures?.normal !== undefined)
-        target.normalMap = textures.normal;
-    if (textures?.roughness !== undefined)
-        target.roughnessMap = textures.roughness;
-    if (textures?.ao !== undefined)
-        target.aoMap = textures.ao;
-    if (textures?.metalness !== undefined)
-        target.metalnessMap = textures.metalness;
-    if (textures?.emissive !== undefined)
-        target.emissiveMap = textures.emissive;
-    if (textures?.height !== undefined)
-        target.displacementMap = textures.height;
-    if (textures !== undefined)
-        target.needsUpdate = true;
-    if (override.rim !== undefined)
-        applyRimLight(target, override.rim);
-    return target;
+    const promote = requiresPhysicalMaterial(override, textures) && !material.isMeshPhysicalMaterial;
+    const target = promote ? new THREE.MeshPhysicalMaterial() : clone ? material.clone() : material;
+    try {
+        if (promote)
+            THREE.MeshStandardMaterial.prototype.copy.call(target, material);
+        if (clone || promote) {
+            target.onBeforeCompile = material.onBeforeCompile;
+            target.customProgramCacheKey = material.customProgramCacheKey;
+        }
+        if (override.color !== undefined)
+            target.color.set(override.color);
+        if (override.metalness !== undefined)
+            target.metalness = override.metalness;
+        if (override.roughness !== undefined)
+            target.roughness = override.roughness;
+        if (override.emissive !== undefined)
+            target.emissive.set(override.emissive);
+        if (override.emissiveIntensity !== undefined)
+            target.emissiveIntensity = override.emissiveIntensity;
+        if (override.normalScale !== undefined)
+            target.normalScale.set(...override.normalScale);
+        const physical = target;
+        for (const key of physicalNumbers)
+            if (override[key] !== undefined)
+                physical[key] = override[key];
+        for (const key of physicalColors)
+            if (override[key] !== undefined)
+                physical[key].set(override[key]);
+        if (override.iridescenceThicknessRange !== undefined)
+            physical.iridescenceThicknessRange = [...override.iridescenceThicknessRange];
+        if (override.alphaMode !== undefined) {
+            target.transparent = override.alphaMode === "blend";
+            target.alphaTest = override.alphaMode === "mask" ? override.alphaCutoff ?? 0.5 : 0;
+            target.depthWrite = override.alphaMode !== "blend";
+        }
+        else if (override.alphaCutoff !== undefined)
+            target.alphaTest = override.alphaCutoff;
+        if (override.opacity !== undefined)
+            target.opacity = override.opacity;
+        if (override.doubleSided !== undefined)
+            target.side = override.doubleSided ? THREE.DoubleSide : THREE.FrontSide;
+        for (const [role, texture] of Object.entries(textures ?? {})) {
+            const property = MATERIAL_TEXTURE_PROPERTIES[role];
+            if (property !== undefined)
+                target[property] = texture;
+        }
+        if (textures !== undefined)
+            target.needsUpdate = true;
+        if (override.rim !== undefined)
+            applyRimLight(target, override.rim);
+        if (override.alphaMode !== undefined || override.doubleSided !== undefined)
+            target.needsUpdate = true;
+        return target;
+    }
+    catch (error) {
+        if (target !== material) {
+            try {
+                target.dispose();
+            }
+            finally {
+                throw error;
+            }
+        }
+        throw error;
+    }
 }
 function isStandardOrPhysicalMaterial(material) {
     return material.isMeshStandardMaterial === true;
@@ -60,7 +116,10 @@ function applyRimLight(target, rim) {
     const power = rim.power ?? 2.5;
     if (strength <= 0)
         return;
-    target.onBeforeCompile = (shader) => {
+    const previousCompile = target.onBeforeCompile;
+    const previousKey = target.customProgramCacheKey();
+    target.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(target, shader, renderer);
         shader.uniforms.uJgRimColor = { value: color };
         shader.uniforms.uJgRimStrength = { value: strength };
         shader.uniforms.uJgRimPower = { value: power };
@@ -74,6 +133,6 @@ outgoingLight += uJgRimColor * jgRim * uJgRimStrength;
 #include <opaque_fragment>`);
     };
     // Two materials differing only in rim tuning must not share a compiled program.
-    target.customProgramCacheKey = () => `jgengine-rim-${rim.color ?? "#ffffff"}-${strength}-${power}`;
+    target.customProgramCacheKey = () => `${previousKey}|jgengine-rim-${rim.color ?? "#ffffff"}-${strength}-${power}`;
     target.needsUpdate = true;
 }

package/dist/multiplayer.d.ts

@@ -1,5 +1,8 @@
 import type { GameDefinition } from "@jgengine/core/game/defineGame";
 import type { MultiplayerSession } from "@jgengine/core/runtime/transport";
+import { type HostedWorldStore } from "@jgengine/core/runtime/hostedWorldSession";
+import type { PlayableGame } from "./registry.js";
+import { type PeerHost, type PeerHostOptions, type PeerGuest, type PeerGuestOptions, type PeerSignaling } from "@jgengine/ws/peer";
 export type ShellMultiplayer = MultiplayerSession;
 export declare const DEFAULT_FEED_ACTIONS: string[];
 export declare function randomPlayerId(): string;
@@ -12,12 +15,39 @@ export type ResolveShellMultiplayerArgs = {
     feedActions?: string[];
 };
 export declare function resolveShellMultiplayer(args: ResolveShellMultiplayerArgs): ShellMultiplayer | null;
-export declare function resolvePeerShellMultiplayer(args: {
+/** Alternate peer factories for hosts that provide their own WebRTC implementation or transport pipe. */
+export interface PeerShellFactories {
+    host(options: PeerHostOptions): PeerHost;
+    guest(options: PeerGuestOptions): PeerGuest;
+}
+/** Peer bootstrap options; passing a playable hosts its authoritative GameContext world. */
+export interface ResolvePeerShellMultiplayerArgs {
     gameId: string;
     role: "host" | "join";
     room?: string;
     userId?: string;
     feedActions?: string[];
-}): Promise<ShellMultiplayer & {
-    close: () => void;
+    /** Requires an adapter with `authority: "server"`; joiners mount the same playable. */
+    playable?: PlayableGame;
+    /** Maximum active players in the authoritative world, including the host player. */
+    slotsPerServer?: number;
+    /** Authoritative tick interval in milliseconds; defaults to 1000 / 30. */
+    tickMs?: number;
+    /** Minimum automatic save interval; joins, commands and close still save immediately. Defaults to 1000 ms. */
+    saveIntervalMs?: number;
+    /** Persistence for the authoritative host world; defaults to an in-memory store. */
+    store?: HostedWorldStore;
+    /** Signaling ownership transfers to the returned session, which closes it on teardown. */
+    signaling?: PeerSignaling;
+    peers?: PeerShellFactories;
+    /** Inject host scheduling; the returned cancellation is called before transport teardown. */
+    scheduleTicks?: (tick: () => void, intervalMs: number) => () => void;
+}
+/**
+ * Opens a peer session. With `playable`, one host runs the game loop and guests mirror its shared world.
+ * Await `close()` to finish authoritative persistence. Same-origin rooms use BroadcastChannel signaling.
+ * @capability multiplayer-p2p bootstrap a playable authoritative world for browser peer co-op
+ */
+export declare function resolvePeerShellMultiplayer(args: ResolvePeerShellMultiplayerArgs): Promise<ShellMultiplayer & {
+    close: () => Promise<void>;
 }>;

package/dist/multiplayer.js

@@ -1,4 +1,6 @@
 import { adapterOf, isServerAuthoritative } from "@jgengine/core/runtime/adapter";
+import { createHostedWorldSession, createHostedWorldSessionAsync } from "@jgengine/core/runtime/hostedWorldSession";
+import { createWorldGameHost } from "@jgengine/ws/worldHost";
 import { createWsBackend } from "@jgengine/ws/createWsBackend";
 import { announcePeerHost, broadcastChannelSignaling, createPeerGuest, createPeerHost, joinPeerSession, } from "@jgengine/ws/peer";
 export const DEFAULT_FEED_ACTIONS = ["entity.died"];
@@ -47,35 +49,116 @@ export function resolveShellMultiplayer(args) {
         `so the game shipped single-player. Wire up the ${adapter.kind} transport or switch to ws()/lan().`);
     return null;
 }
+/**
+ * Opens a peer session. With `playable`, one host runs the game loop and guests mirror its shared world.
+ * Await `close()` to finish authoritative persistence. Same-origin rooms use BroadcastChannel signaling.
+ * @capability multiplayer-p2p bootstrap a playable authoritative world for browser peer co-op
+ */
 export async function resolvePeerShellMultiplayer(args) {
+    if (args.playable !== undefined && !isServerAuthoritative(args.playable.game.multiplayer)) {
+        throw new Error("playable peer worlds require authority: server");
+    }
+    const tickMs = args.tickMs ?? 1000 / 30;
+    if (!Number.isFinite(tickMs) || tickMs <= 0 || tickMs > 1000)
+        throw new Error("tickMs must be greater than zero and at most 1000");
+    const saveIntervalMs = args.saveIntervalMs ?? 1000;
+    if (!Number.isFinite(saveIntervalMs) || saveIntervalMs < 0)
+        throw new Error("saveIntervalMs must be nonnegative and finite");
     const userId = args.userId ?? randomPlayerId();
     const feedActions = args.feedActions ?? DEFAULT_FEED_ACTIONS;
-    const signaling = broadcastChannelSignaling(args.room ?? `jg-p2p-${args.gameId}`);
+    const signaling = args.signaling ?? broadcastChannelSignaling(args.room ?? `jg-p2p-${args.gameId}`);
+    const peers = args.peers ?? { host: createPeerHost, guest: createPeerGuest };
     if (args.role === "host") {
-        const peerHost = createPeerHost({ userId });
-        const stopAnnouncing = announcePeerHost(peerHost, signaling);
+        let closed = false;
+        let activeSession = null;
+        let host;
+        let cancelTicks = () => { };
+        let stopAnnouncing = () => { };
+        let peerHost;
+        let closing = null;
+        try {
+            if (args.playable !== undefined) {
+                const playable = args.playable;
+                let loading = null;
+                host = createWorldGameHost({
+                    slotsPerServer: args.slotsPerServer,
+                    session({ gameId, serverId }) {
+                        if (closed || gameId !== args.gameId || serverId !== args.gameId)
+                            return null;
+                        if (loading === null) {
+                            const attempt = args.store === undefined
+                                ? Promise.resolve(createHostedWorldSession({ definition: playable.game, content: playable.content, host: { userId, isNew: true }, saveIntervalMs }))
+                                : createHostedWorldSessionAsync({ definition: playable.game, content: playable.content, host: { userId, isNew: true }, store: args.store, saveIntervalMs });
+                            loading = attempt;
+                            void attempt.catch(() => { if (loading === attempt)
+                                loading = null; });
+                        }
+                        return loading.then(session => { activeSession = session; return session; });
+                    },
+                });
+            }
+            peerHost = peers.host({ userId, ...(host === undefined ? {} : { host }) });
+            stopAnnouncing = announcePeerHost(peerHost, signaling);
+            if (host !== undefined) {
+                const worldHost = host;
+                const tick = () => { if (!closed && activeSession !== null && activeSession.members().length > 0)
+                    worldHost.tick(tickMs / 1000); };
+                cancelTicks = args.scheduleTicks?.(tick, tickMs) ?? (() => {
+                    const timer = setInterval(tick, tickMs);
+                    return () => clearInterval(timer);
+                })();
+            }
+            const resolvedPeerHost = peerHost;
+            return {
+                gameId: args.gameId, userId, backend: resolvedPeerHost.backend, feedActions,
+                close() {
+                    if (closing !== null)
+                        return closing;
+                    closed = true;
+                    cancelTicks();
+                    stopAnnouncing();
+                    signaling.close();
+                    resolvedPeerHost.close();
+                    closing = resolvedPeerHost.router.drain().then(async () => {
+                        if (host !== undefined)
+                            await host.stop();
+                    });
+                    return closing;
+                },
+            };
+        }
+        catch (error) {
+            closed = true;
+            cancelTicks();
+            stopAnnouncing();
+            signaling.close();
+            peerHost?.close();
+            await peerHost?.router.drain();
+            if (host !== undefined)
+                await host.stop();
+            throw error;
+        }
+    }
+    let guest;
+    try {
+        guest = peers.guest({ userId });
+        const backend = await joinPeerSession(guest, signaling);
+        const resolvedGuest = guest;
+        let closed = false;
         return {
-            gameId: args.gameId,
-            userId,
-            backend: peerHost.backend,
-            feedActions,
-            close: () => {
-                stopAnnouncing();
+            gameId: args.gameId, userId, backend, feedActions,
+            async close() {
+                if (closed)
+                    return;
+                closed = true;
                 signaling.close();
-                peerHost.close();
+                resolvedGuest.close();
             },
         };
     }
-    const guest = createPeerGuest({ userId });
-    const backend = await joinPeerSession(guest, signaling);
-    return {
-        gameId: args.gameId,
-        userId,
-        backend,
-        feedActions,
-        close: () => {
-            signaling.close();
-            guest.close();
-        },
-    };
+    catch (error) {
+        signaling.close();
+        guest?.close();
+        throw error;
+    }
 }

package/dist/pointer/pointerService.d.ts

@@ -2,6 +2,8 @@ import * as THREE from "three";
 import type { PointerHit, PointerVec3 } from "@jgengine/core/input/pointer";
 export declare const POINTER_ENTITY_KEY = "jgEntityId";
 export declare const POINTER_OBJECT_KEY = "jgObjectId";
+/** Object-store identities indexed by the current compacted GPU instance slot. @internal */
+export declare const POINTER_OBJECT_INSTANCES_KEY = "jgObjectInstances";
 export type PointerHitFilter = (object: THREE.Object3D) => boolean;
 interface PointerDeps {
     camera: THREE.Camera;

package/dist/pointer/pointerService.js

@@ -1,6 +1,8 @@
 import * as THREE from "three";
 export const POINTER_ENTITY_KEY = "jgEntityId";
 export const POINTER_OBJECT_KEY = "jgObjectId";
+/** Object-store identities indexed by the current compacted GPU instance slot. @internal */
+export const POINTER_OBJECT_INSTANCES_KEY = "jgObjectInstances";
 function tagOf(object, key) {
     let cursor = object;
     while (cursor !== null) {
@@ -24,6 +26,8 @@ export function createPointerService() {
     const centerNdc = new THREE.Vector2(0, 0);
     const scratch = new THREE.Vector3();
     const normalMatrix = new THREE.Matrix3();
+    const instanceMatrix = new THREE.Matrix4();
+    const hitMatrix = new THREE.Matrix4();
     const groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
     let deps = null;
     let cursorPresent = false;
@@ -45,7 +49,12 @@ export function createPointerService() {
             const point = [hit.point.x, hit.point.y, hit.point.z];
             let normal = [0, 1, 0];
             if (hit.face !== null && hit.face !== undefined) {
-                normalMatrix.getNormalMatrix(hit.object.matrixWorld);
+                hitMatrix.copy(hit.object.matrixWorld);
+                if (mesh.isInstancedMesh && hit.instanceId !== undefined) {
+                    mesh.getMatrixAt(hit.instanceId, instanceMatrix);
+                    hitMatrix.multiply(instanceMatrix);
+                }
+                normalMatrix.getNormalMatrix(hitMatrix);
                 scratch.copy(hit.face.normal).applyMatrix3(normalMatrix).normalize();
                 normal = [scratch.x, scratch.y, scratch.z];
             }
@@ -54,7 +63,8 @@ export function createPointerService() {
                 point,
                 normal,
                 entity: tagOf(hit.object, POINTER_ENTITY_KEY),
-                object: tagOf(hit.object, POINTER_OBJECT_KEY),
+                object: hit.instanceId === undefined ? tagOf(hit.object, POINTER_OBJECT_KEY) :
+                    hit.object.userData[POINTER_OBJECT_INSTANCES_KEY]?.[hit.instanceId] ?? tagOf(hit.object, POINTER_OBJECT_KEY),
                 ...(uv !== undefined ? { uv } : {}),
                 material: standardMaterialSample(mesh.material),
                 ...(hit.instanceId !== undefined ? { instanceId: hit.instanceId } : {}),

package/dist/postfx/PostProcessing.d.ts

@@ -1,9 +1,18 @@
+import { EffectComposer, type ShaderPass } from "three-stdlib";
 import type { PostProcessingConfig } from "@jgengine/core/render/postProcessing";
 import type { GraphicsQuality } from "@jgengine/core/settings/settingsModel";
+interface BuiltGraph {
+    composer: EffectComposer;
+    grade: ShaderPass | null;
+}
+/** Release each pass and the composer's owned targets. @internal */
+export declare function disposeGraph(built: BuiltGraph): void;
+/** Resize the composer and its passes at the renderer's pixel ratio. @internal */
+export declare function syncSize(built: BuiltGraph, width: number, height: number, pixelRatio: number): void;
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
- * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Grade. Rendered only
+ * post chain: RenderPass → GTAO → UnrealBloom → SMAA → OutputPass → Stylize → Grade. Rendered only
  * when `PlayableGame.postProcessing` is set, so games without it draw unchanged.
  *
  * `stages` (resolved from the player's graphics profile) controls expensive passes
@@ -20,3 +29,4 @@ export declare function PostProcessing({ config, quality, stages }: {
         smaa: boolean;
     };
 }): null;
+export {};