@jgengine/shell 0.10.0 → 0.12.0

package/README.md

@@ -13,7 +13,7 @@ const games: GameRegistry = {
 <GamePlayerShell playable={await games["my-game"]()} />;
 ```
 
-Peer deps: `react`, `three`, `@react-three/fiber`, `@react-three/drei`, `three-stdlib`. The shell's HUD classes are Tailwind — add an `@source` entry for `node_modules/@jgengine/shell` in your CSS. AGPL-3.0-only.
+Peer deps: `react`, `three`, `@react-three/fiber`, `@react-three/drei`, `three-stdlib`. The shell's HUD classes are Tailwind — add an `@source` entry for `node_modules/@jgengine/shell` in your CSS. Apache-2.0.
 
 Weather primitives are available from `@jgengine/shell/weather` for game scene overlays:
 

package/dist/CombatPresentation.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedPresentationEffects } from "./presentationResolve.js";
+/** Mounts the opt-in combat VFX stack inside the 3D canvas. @internal */
+export declare function CombatPresentation({ effects }: {
+    effects: ResolvedPresentationEffects;
+}): import("react").JSX.Element;

package/dist/CombatPresentation.js

@@ -0,0 +1,8 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CombatCameraShake, ProjectileTracers, WorldFloatText, WorldTelegraphs, } from "./world/WorldHud.js";
+import { WorldSpellVfx } from "./world/WorldVfx.js";
+import { RetainedVfx } from "./world/RetainedVfx.js";
+/** Mounts the opt-in combat VFX stack inside the 3D canvas. @internal */
+export function CombatPresentation({ effects }) {
+    return (_jsxs(_Fragment, { children: [effects.telegraphs ? _jsx(WorldTelegraphs, {}) : null, effects.vfx ? (_jsxs(_Fragment, { children: [_jsx(WorldSpellVfx, {}), _jsx(RetainedVfx, {})] })) : null, effects.floatText ? _jsx(WorldFloatText, {}) : null, effects.tracers ? _jsx(ProjectileTracers, {}) : null, effects.shake ? _jsx(CombatCameraShake, {}) : null] }));
+}

package/dist/GameHost.d.ts

@@ -1,5 +1,16 @@
+import { type ComponentType } from "react";
+import type { EditorCatalogDefinition } from "@jgengine/core/editor/types";
 import { type ResolveShellMultiplayerArgs, type ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
+/** Structural shape of the module `GameHost`'s `editor` loader resolves — `import("@jgengine/editor")` satisfies it. */
+export interface EditorSummonModule {
+    EditorApp: ComponentType<{
+        gameId: string;
+        playable: PlayableGame;
+        catalogs?: readonly EditorCatalogDefinition[];
+    }>;
+}
+/** Props for {@link GameHost}: the playable, optional multiplayer overrides, and the optional editor loader that enables the engine-owned F2+E summon. */
 export interface GameHostProps {
     playable: PlayableGame;
     gameId?: string;
@@ -8,5 +19,18 @@ export interface GameHostProps {
     multiplayer?: ShellMultiplayer | null;
     /** Tried before the built-in {@link resolveShellMultiplayer}; falls back to it when this returns `null`. */
     resolveMultiplayer?: (args: ResolveShellMultiplayerArgs) => ShellMultiplayer | null;
+    /**
+     * Editor loader — pass `() => import("@jgengine/editor")` and the host owns the whole summon:
+     * `?mode=editor`, the F2+E chord, `window.__jgengineSummonEditor`, the dev save endpoint, and the
+     * lazy `EditorApp` mount (with the playable's `editorLayers`/`editorCatalogs`). The editor package
+     * stays a lazy chunk the game bundles only when this prop is set.
+     */
+    editor?: () => Promise<EditorSummonModule>;
 }
-export declare function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer }: GameHostProps): import("react").JSX.Element;
+/**
+ * The one documented mount: resolves multiplayer for the playable and renders the shell. With the
+ * `editor` loader prop it also owns the whole editor summon (F2+E, `?mode=editor`, dev save endpoint).
+ *
+ * @capability mount-game mount a defined game in the browser — `<GameHost playable={game} editor={() => import("@jgengine/editor")} />`
+ */
+export declare function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer, editor }: GameHostProps): import("react").JSX.Element;

package/dist/GameHost.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useMemo } from "react";
+import { lazy, Suspense, useEffect, useMemo, useState } from "react";
+import { installSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
 import { multiplayerAdapterKind } from "@jgengine/core/runtime/adapter";
 import { GamePlayerShell } from "./GamePlayerShell.js";
 import { resolveShellMultiplayer } from "./multiplayer.js";
@@ -11,13 +12,65 @@ function warnUndrivenAdapter(kind) {
     console.warn(`GameHost: game declares multiplayer adapter "${kind}", which the built-in shell resolver cannot drive. ` +
         "Running offline. Pass a prebuilt session via the multiplayer prop, or a resolveMultiplayer prop, to GameHost.");
 }
-export function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer }) {
+function initialEditorMode(enabled) {
+    if (!enabled || typeof window === "undefined")
+        return false;
+    return new URLSearchParams(window.location.search).get("mode") === "editor";
+}
+/**
+ * The one documented mount: resolves multiplayer for the playable and renders the shell. With the
+ * `editor` loader prop it also owns the whole editor summon (F2+E, `?mode=editor`, dev save endpoint).
+ *
+ * @capability mount-game mount a defined game in the browser — `<GameHost playable={game} editor={() => import("@jgengine/editor")} />`
+ */
+export function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultiplayer, editor }) {
+    const resolvedGameId = gameId ?? playable.game.name;
+    const [editorOpen, setEditorOpen] = useState(() => initialEditorMode(editor !== undefined));
+    useEffect(() => {
+        if (editor === undefined)
+            return;
+        // Self-guards against production builds; the endpoint just marks where dev saves land.
+        return installSaveEndpoint("/__jgengine/save", resolvedGameId);
+    }, [editor, resolvedGameId]);
+    useEffect(() => {
+        if (editor === undefined || editorOpen)
+            return;
+        const summon = () => setEditorOpen(true);
+        const host = window;
+        host.__jgengineSummonEditor = summon;
+        let f2Held = false;
+        const onKeyDown = (event) => {
+            if (event.code === "F2")
+                f2Held = true;
+            else if (event.code === "KeyE" && f2Held) {
+                event.preventDefault();
+                summon();
+            }
+        };
+        const onKeyUp = (event) => {
+            if (event.code === "F2")
+                f2Held = false;
+        };
+        window.addEventListener("keydown", onKeyDown);
+        window.addEventListener("keyup", onKeyUp);
+        return () => {
+            window.removeEventListener("keydown", onKeyDown);
+            window.removeEventListener("keyup", onKeyUp);
+            if (host.__jgengineSummonEditor === summon)
+                delete host.__jgengineSummonEditor;
+        };
+    }, [editor, editorOpen]);
+    const EditorLazy = useMemo(() => {
+        if (editor === undefined)
+            return null;
+        return lazy(async () => ({ default: (await editor()).EditorApp }));
+    }, [editor]);
     const resolved = useMemo(() => {
         if (multiplayer !== undefined)
             return multiplayer;
         const args = {
             game: playable.game,
-            gameId: gameId ?? playable.game.name,
+            gameId: resolvedGameId,
             url: wsUrl,
             force: wsUrl !== undefined,
         };
@@ -28,6 +81,9 @@ export function GameHost({ playable, gameId, wsUrl, multiplayer, resolveMultipla
                 warnUndrivenAdapter(kind);
         }
         return session;
-    }, [playable, gameId, wsUrl, multiplayer, resolveMultiplayer]);
+    }, [playable, resolvedGameId, wsUrl, multiplayer, resolveMultiplayer]);
+    if (editorOpen && EditorLazy !== null) {
+        return (_jsx(Suspense, { fallback: null, children: _jsx(EditorLazy, { gameId: resolvedGameId, playable: playable, catalogs: playable.editorCatalogs }) }));
+    }
     return _jsx(GamePlayerShell, { playable: playable, multiplayer: resolved });
 }

package/dist/GamePhaseStamp.d.ts

@@ -0,0 +1 @@
+export declare function GamePhaseStamp(): null;

package/dist/GamePhaseStamp.js

@@ -0,0 +1,9 @@
+import { useEffect } from "react";
+import { useGamePhase } from "@jgengine/react/hooks";
+export function GamePhaseStamp() {
+    const { phase } = useGamePhase();
+    useEffect(() => {
+        document.documentElement.dataset.jgPhase = phase;
+    }, [phase]);
+    return null;
+}

package/dist/GamePlayer.d.ts

@@ -8,4 +8,9 @@ export type GamePlayerProps = {
     loading?: ReactNode;
     multiplayer?: ShellMultiplayer | null;
 };
+/**
+ * Registry-driven lazy loader over {@link GamePlayerShell} for multi-game hosts.
+ * Games mount through `GameHost` — the one documented mount.
+ * @internal
+ */
 export declare function GamePlayer({ gameId, registry, fallbackGameId, loading, multiplayer }: GamePlayerProps): import("react").JSX.Element;

package/dist/GamePlayer.js

@@ -2,6 +2,11 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { GamePlayerShell } from "./GamePlayerShell.js";
 import { resolveGameLoader } from "./registry.js";
+/**
+ * Registry-driven lazy loader over {@link GamePlayerShell} for multi-game hosts.
+ * Games mount through `GameHost` — the one documented mount.
+ * @internal
+ */
 export function GamePlayer({ gameId, registry, fallbackGameId, loading = null, multiplayer = null }) {
     const [playable, setPlayable] = useState(null);
     useEffect(() => {

package/dist/GamePlayerShell.d.ts

@@ -1,22 +1,15 @@
-import { type ActionStateTracker } from "@jgengine/core/input/actionBindings";
-import type { Aim } from "@jgengine/core/scene/spatial";
 import { type GameContext } from "@jgengine/core/runtime/gameContext";
-import { type CommandSink } from "./commandSink.js";
-import type { SkyEnvironmentDescriptor, WorldFeature } from "@jgengine/core/world/features";
 import type { ShellMultiplayer } from "./multiplayer.js";
 import type { PlayableGame } from "./registry.js";
-/** Actions from `input` currently held down, for `ctx.input.publish` (#164.1); includes reserved movement/jump actions. */
-export declare function heldActionsFor(tracker: Pick<ActionStateTracker<string>, "isDown">, actions: readonly string[]): string[];
-/** Whether a bound action should fire this frame: on press, or on repeat interval while held (shared by `FrameDriver` and `HudOnlyDriver`). */
-export declare function shouldFireBoundAction(tracker: Pick<ActionStateTracker<string>, "isDown" | "wasPressed">, action: string, input: PlayableGame["game"]["input"], repeatFiredAt: ReadonlyMap<string, number>, now: number): boolean;
-/** Resolves and runs the command bound to `action` via the shell's action→command convention (shared by `FrameDriver` and `HudOnlyDriver`). */
-export declare function dispatchBoundAction(ctx: GameContext, action: string, yaw: number, pitch: number, aim: Aim, reserved?: ReadonlySet<string>, sink?: CommandSink): void;
 export { applyMotionImpulses } from "@jgengine/core/runtime/motionIntents";
 export { nearbyObstacles } from "@jgengine/core/movement/movementModel";
 export { resolvePhysicsTuning } from "@jgengine/core/movement/playerMovement";
 export { hasEnvironmentTerrain } from "@jgengine/core/world/terrain";
-/** The world's declared sky, when its world feature is an environment with one (#196.1). */
-export declare function resolveWorldSky(world: WorldFeature | undefined): SkyEnvironmentDescriptor | undefined;
+/**
+ * The shell body `GameHost` renders after resolving multiplayer. Hosts that resolve their own
+ * sessions (the dev runner) render it directly; games mount through `GameHost`.
+ * @internal
+ */
 export declare function GamePlayerShell({ playable, multiplayer: rawMultiplayer, poster, onContextReady, }: {
     playable: PlayableGame;
     multiplayer?: ShellMultiplayer | null;