@jgengine/shell 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -11,7 +11,27 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
-## Unreleased
+## 0.10.0
+
+### Migrate
+
+- **Nothing to change for existing games** — the shared mobile-composition system (viewport allocation, region collision, `--jg-*` viewport vars) is wired automatically by the shell for every game; `HudPanel`s inside a `HudCanvas` register themselves. Legacy `orientation: "landscape" | "portrait"` keeps its advisory dismissible-hint behavior unchanged.
+- **Opt a driving/landscape game into the strict gate**: replace the advisory `orientation` with the contract form — `orientation: { mobile: "landscape-required" }` (rules: `any` · `portrait`/`landscape` advisory · `portrait-required`/`landscape-required` · `unsupported`). In portrait the engine now shows a polished `RotateDeviceScreen`, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.
+- **Declare HUD intent** where useful: `HudPanel` gains `priority` (`critical`/`secondary`/`tertiary`), `mobileBehavior` (`hidden` unmounts on phones, `transient` softens collision, …), `allowOverlapWith`, and `collisionGroup`. Optional — omitting them keeps prior behavior.
+- **Mobile validation now also fails on overlap**: `bun run shoot <game> --device mobile|mobile-landscape|both` exits non-zero on forbidden inter-element collisions (not just viewport overflow), naming both regions.
+
+### Added
+
+- Shared mobile layout composition — `@jgengine/core/ui/gameLayout` (pure geometry: `resolveLayoutMode`, `intersects`, `overlapArea`, `detectLayoutCollisions`, `computeGameplayRect`, `LayoutRegion`, `GameViewportLayout`) and `@jgengine/core/ui/orientation` (`resolveOrientationRequirement`, `orientationGateActive`, `MobileOrientationRule`). `@jgengine/react` adds `GameViewportProvider` (mounted by the shell), hooks (`useGameViewportLayout`, `useGameLayoutMode`, `useGameOrientation`, `useReservedControlZones`, `useLayoutCollisions`, `useRegisterLayoutRegion`), and a headless `RotateDeviceScreen`. The provider tracks `window.visualViewport`, publishes `--jg-viewport-*` / `--jg-visual-viewport-*` / `--jg-safe-*` CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps (dev `data-jg-layout-collision` + console diagnostic).
+- Mandatory orientation contract — `PlayableGame.orientation` accepts `{ mobile: <rule> }`; `landscape-required`/`portrait-required` render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; `visualViewport`-sized for mobile Safari/PWA.
+- Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as `control` regions, so HUD placement and collision validation know exactly where controls sit.
+- HUD placement metadata — `HudPanel` gains `priority`, `mobileBehavior`, `allowOverlapWith`, `collisionGroup`, and registers as a collision-tracked layout region.
+- Mobile-landscape shoot device — `bun run shoot --device mobile-landscape` (844×390) plus collision-gate reads that fail mobile validation on forbidden overlaps.
+- Canyon Chase migrated as the reference landscape-required game — declares `orientation: { mobile: "landscape-required" }`, composes its HUD through coordinated `HudPanel` regions (pursuit distance critical, border secondary, survey map hidden on mobile, radio transient) instead of independent fixed corners.
+
+### Changed
+
+- First-person projectile tracers now originate from the weapon muzzle instead of the camera/eye centerline. Hit detection is unchanged (still crosshair-accurate) — only the drawn tracer's start point moved to the viewmodel muzzle, which tracks full aim yaw and pitch. Non-viewmodel games and enemy tracers are unaffected.
 
 ## 0.9.0
 

package/dist/GamePlayerShell.d.ts

@@ -1,11 +1,8 @@
 import { type ActionStateTracker } from "@jgengine/core/input/actionBindings";
 import type { Aim } from "@jgengine/core/scene/spatial";
-import { type CollisionObstacle, type MovementTuningOverrides } from "@jgengine/core/movement/movementModel";
-import type { PhysicsConfig } from "@jgengine/core/game/defineGame";
 import { type GameContext } from "@jgengine/core/runtime/gameContext";
-import { type MotionIntentBatch } from "@jgengine/core/runtime/motionIntents";
+import { type CommandSink } from "./commandSink.js";
 import type { SkyEnvironmentDescriptor, WorldFeature } from "@jgengine/core/world/features";
-import { type SceneObject } from "@jgengine/core/scene/objectStore";
 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. */
@@ -13,25 +10,13 @@ export declare function heldActionsFor(tracker: Pick<ActionStateTracker<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): void;
-/** Placed scene objects within `radius` of `center`, as `CollisionObstacle`s for `resolveObstacleStep` (#162.1). */
-export declare function nearbyObstacles(objects: readonly SceneObject[], center: readonly [number, number, number], radius?: number): CollisionObstacle[];
-/** Applies a pending `MotionIntentBatch` to a vertical velocity: impulses add, then `verticalVelocity` replaces the result outright (#162.4). */
-export declare function applyMotionImpulses(currentVelocity: number, batch: MotionIntentBatch | null): number;
+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;
-/**
- * Maps the game's declared `physics` onto the movement controllers' tuning
- * overrides. `PhysicsConfig.gravity` is a signed world acceleration (negative
- * points down, matching every game's config and the Y-up convention), but the
- * controllers integrate `velocityY -= gravityAcceleration * dt` and so expect a
- * positive downward magnitude. Negating here is what keeps a down-pointing
- * gravity pulling the player *down*; passing the signed value straight through
- * flipped the sign and launched airborne players upward instead.
- */
-export declare function resolvePhysicsTuning(physics: PhysicsConfig | undefined): MovementTuningOverrides | undefined;
-/** True when the world is an environment feature with terrain, so the voxel controller should sample its height. */
-export declare function hasEnvironmentTerrain(world: WorldFeature | undefined): boolean;
 export declare function GamePlayerShell({ playable, multiplayer: rawMultiplayer, poster, onContextReady, }: {
     playable: PlayableGame;
     multiplayer?: ShellMultiplayer | null;