lecodes-cli 0.17.2 → 0.18.1

package/runtime/sdk/inject.ts

@@ -1,162 +1,186 @@
-// THE aggregation point. Every public global the SDK provides is re-exported here under the exact
-// name user code uses it as. The bundler passes this file to esbuild's `inject:` option, so user
-// code references `Scene`, `Sprite`, `toast`, … with no imports; esbuild tree-shakes away whatever
-// a given project does not use (so a pure-2D project drops all 3D classes, and vice versa).
-//
-// Rule: this is the ONLY file that `export`s public names. Everything else is internal and imported
-// by it. Host-provided globals (setLoop, console, setTimeout, DEG2RAD, asset, …) are NOT here —
-// they live in src/host.d.ts as declarations and stay as free references at runtime.
-
-// ---- math ----
-export { Mathf } from "./math/Mathf"
-export { Vec2, Vec3 } from "./math/vec"
-export { Quat } from "./math/quat"
-export { Mat4 } from "./math/mat4"
-export { Color } from "./core/color"
-
-// ---- aspects (attachable node capabilities) ----
-export { Aspect, type With } from "./core/Aspect"
-export { InspectorUI } from "./core/InspectorUI"
-
-// ---- reactivity (signals; UI text/style props also accept `() => value` bindings) ----
-export { signal, computed, effect, type Signal, type Computed } from "./core/signals"
-
-// ---- canvas (core 2D drawing that bakes to a texture; shared by 2D/3D/UI) ----
-export { Canvas, Bitmap } from "./canvas/Canvas"
-
-// ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
-export { toast, openURL, SvgSource } from "./runtime/misc"
-export { app, type AppState } from "./runtime/app"
-export { clipboard } from "./runtime/clipboard"
-export { date, type DateValue, type DateInput, type Unit, type Locale } from "./runtime/datetime"
-export { fetch, fetchLocal, FormData, File, type FetchResponse } from "./runtime/fetch"
-export { localStorage } from "./runtime/storage"
-export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
-export { Input } from "./runtime/input"
-export { WebSocket } from "./runtime/net"
-// App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
-// only ever imports its server functions (docs/backend-plan.md §4).
-export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"
-export { AudioPlayer, VideoPlayer } from "./runtime/media"
-export { openFilePicker } from "./runtime/files"
-export { share } from "./runtime/share"
-export { ClickEvent, TouchStartEvent, LongPressEvent } from "./runtime/touch"
-
-// ---- 2D engine (creator-2d) ----
-export { Scene2D } from "./g2/Scene2D"
-export { Node2D } from "./g2/Node2D"
-export { Camera2D } from "./g2/Camera2D"
-export { Sprite } from "./g2/Sprite"
-export { SpriteAnimation } from "./g2/SpriteAnimation"
-export { Shape2D } from "./g2/Shape2D"
-export { Physics2D } from "./g2/Physics2D"
-export { Trigger2D } from "./g2/Trigger2D"
-export { CharacterController2D } from "./g2/CharacterController2D"
-export { Tilemap } from "./g2/Tilemap"
-export { Texture2D } from "./g2/Texture2D"
-// sprite sheets as data (.sprite.ts files — see src/g2/SpriteSheet.ts)
-export { SpriteSheet, defineSpriteSheet } from "./g2/SpriteSheet"
-export type { SpriteSheetDef, SheetSprite, SpriteMakeOptions } from "./g2/SpriteSheet"
-// tilesets as data (.tiles.ts files — autotile materials, see src/g2/Tileset.ts + autotile.ts)
-export { Tileset, defineTileset, Autotile2D } from "./g2/Tileset"
-export { rawCell, isRawCell, rawIndex } from "./g2/autotile"
-export { rot90, rot180, rot270, flipX, packTile, tileIndex, tileTurns, tileFlip, tileOriented } from "./g2/autotile"
-export type {
-  TilesetDef, TileMaterial, PatchMaterial, PathMaterial, PatchSlots, EdgeSlot, FillBlock, BlockEntry,
-  TileBlock, TilePart,
-} from "./g2/autotile"
-// 2D scenes as data (.scene2d.ts files — see src/g2/defineScene2d.ts) + the cells('…') payload
-export { defineScene2d, Scene2dHandle } from "./g2/defineScene2d"
-export type { Scene2dDef, Scene2dNodeDef, Scene2dEnv, SpriteSourceDef, TilemapSourceDef, Camera2dNodeDef, LoadedScene2d } from "./g2/defineScene2d"
-export { cells, encodeCells, type CellsData } from "./g2/cells"
-// no-code 2D scenario aspects (attachable in scene files — see src/g2/scenarios2d.ts)
-export { CameraFollow } from "./g2/scenarios2d"
-
-// ---- UI (creator-ui) ----
-export {
-  UIScreen, type UIScreenStyle,
-  UIRow, UIColumn, UIBox, type UIContainerStyle,
-  UIText, type UITextStyle,
-  UIButton, type UIButtonStyle,
-  UIImage, type UIImageStyle,
-  UIVideo, type UIVideoStyle,
-  UIInput, UITextArea, type UIInputStyle,
-  UIScrollable, type UIScrollableStyle,
-  UIPager, type UIPagerStyle,
-  UITabs, type UITabDef,
-  defineTabs, type TabDef, type TabsHandle,
-  UIWidget, type UIWidgetStyle,
-  UIModal, type UIModalStyle,
-  UIBottomSheet, type UIBottomSheetStyle,
-  UIPopover, type UIPopoverStyle,
-  UISpacer, type UISpacerStyle,
-  UIVirtualizedList,
-  Router,
-  NativeView, type UINativeViewStyle,
-  registerFont,
-  __uiMap,
-  __UIColumn, __UIRow, __UIBox, __UIButton, __UIScreen, __UIScrollable, __UIWidget,
-} from "./ui/UI"
-// The Presentable navigation contract (docs/navigation-presentable-plan.md). `Presentable` is
-// interface + runtime companion (declaration merging): `Presentable.current` = what's on screen.
-export { Presentable } from "./ui/UI"
-export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from "./ui/UI"
-// The base node type + the union a container accepts as children — documented as the signature of
-// UIColumn/UIRow/append/etc., so they must be global (type-only; erased at runtime).
-export type { UINode, UINodeChild } from "./ui/UINode"
-// App theme variables (docs/ui-theme-plan.md): theme({...}) merges + returns typed var()
-// accessors; system vars are static props (theme.primaryColor, theme["comfort-top"], …).
-export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme"
-
-// ---- animate ----
-export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate"
-export { cubicBezier } from "./animate/bezier"
-export { easeIn, easeOut, easeInOut } from "./animate/easings"
-
-// ---- plugins (optional, host-provided capabilities — typed NativeView/service wrappers, see src/plugins/) ----
-export { QRScanner } from "./plugins/qr"
-export { CameraView, type CameraFacing } from "./plugins/camera"
-export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation"
-export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/push"
-export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth"
-export { Service } from "./plugins/service"
-
-// ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
-export { defineScene, use, ref, make, SceneHandle } from "./scene/defineScene"
-export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, CameraNodeDef, AspectEntry, MakeEntry, LoadedScene } from "./scene/defineScene"
-export type { FieldMeta } from "./core/fields"
-
-// ---- no-code scenario aspects (attachable in the scene editor — see src/gl/scenarios.ts) ----
-export { MoveTo, FollowPath, Spin, LookAt, PlayAnimation } from "./gl/scenarios"
-
-// ---- editor plugins (called from `*.editor.ts` files — editor bundles only; DCE'd from apps) ----
-export { registerEditorWindow, registerEditorTool, __editorPlugins } from "./scene/editorPlugins"
-export type { EditorApi, EditorRayHit, EditorToolHooks, EditorWindowFn } from "./scene/editorPlugins"
-
-// ---- 3D engine (creator-gl) ----
-export { Scene, ARScene, VRScene } from "./gl/Scene"
-export { Node } from "./gl/Node"
-export { Mesh } from "./gl/Mesh"
-export { Model } from "./gl/Model"
-export { Shape } from "./gl/Shape"
-export { Physics } from "./gl/Physics"
-export { Trigger } from "./gl/Trigger"
-export { CharacterController } from "./gl/CharacterController"
-export { ModelAnimation } from "./gl/ModelAnimation"
-export { AnimationClip } from "./gl/AnimationClip"
-export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/AnimationClip"
-export { Animator } from "./gl/Animator"
-export type { AnimatorPlayOptions } from "./gl/Animator"
-export { IK } from "./gl/IK"
-export type { IKTwoBone, IKLookAt } from "./gl/IK"
-export { Light } from "./gl/Light"
-export { Material } from "./gl/Material"
-export { Geometry } from "./gl/Geometry"
-export { InstancedMesh } from "./gl/InstancedMesh"
-export type { InstanceTransform } from "./gl/InstancedMesh"
-export { Texture } from "./gl/Texture"
-export { Camera } from "./gl/Camera"
-export { Ray } from "./gl/Ray"
-export { Plane } from "./gl/Plane"
-export { Noise } from "./gl/Noise"
-export { Particles, Trail, curve, colorCurve } from "./gl/Particles"
+// THE aggregation point. Every public global the SDK provides is re-exported here under the exact
+// name user code uses it as. The bundler passes this file to esbuild's `inject:` option, so user
+// code references `Scene`, `Sprite`, `toast`, … with no imports; esbuild tree-shakes away whatever
+// a given project does not use (so a pure-2D project drops all 3D classes, and vice versa).
+//
+// Rule: this is the ONLY file that `export`s public names. Everything else is internal and imported
+// by it. Host-provided globals (setLoop, console, setTimeout, DEG2RAD, asset, …) are NOT here —
+// they live in src/host.d.ts as declarations and stay as free references at runtime.
+
+// ---- math ----
+export { Mathf } from "./math/Mathf"
+export { Vec2, Vec3 } from "./math/vec"
+export { Quat } from "./math/quat"
+export { Mat4 } from "./math/mat4"
+export { Color } from "./core/color"
+
+// ---- aspects (attachable node capabilities) ----
+export { Aspect, System, type With, type SystemHost } from "./core/Aspect"
+export { type EventMap } from "./core/events"
+export { Time } from "./core/time"
+export { InspectorUI } from "./core/InspectorUI"
+
+// ---- reactivity (signals; UI text/style props also accept `() => value` bindings) ----
+export { signal, computed, effect, type Signal, type Computed } from "./core/signals"
+export { __compWrite, __compOp, type CompAxis, type CompWriter } from "./core/compWrite"
+
+// ---- canvas (core 2D drawing that bakes to a texture; shared by 2D/3D/UI) ----
+export { Canvas, Bitmap } from "./canvas/Canvas"
+
+// ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
+export { toast, openURL, SvgSource } from "./runtime/misc"
+export { app, type AppState, type OrientationLock } from "./runtime/app"
+export { clipboard } from "./runtime/clipboard"
+export { date, type DateValue, type DateInput, type Unit, type Locale } from "./runtime/datetime"
+export { fetch, fetchLocal, FormData, File, type FetchResponse } from "./runtime/fetch"
+export { localStorage } from "./runtime/storage"
+export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
+export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input"
+export { WebSocket } from "./runtime/net"
+// App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
+// only ever imports its server functions (docs/backend-plan.md §4).
+export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc"
+export { AudioPlayer, VideoPlayer } from "./runtime/media"
+export { openFilePicker } from "./runtime/files"
+export { share } from "./runtime/share"
+export { ClickEvent, TouchStartEvent, LongPressEvent } from "./runtime/touch"
+
+// ---- 2D engine (creator-2d) ----
+export { Scene2D } from "./g2/Scene2D"
+export { Node2D } from "./g2/Node2D"
+export { Camera2D } from "./g2/Camera2D"
+export { Sprite } from "./g2/Sprite"
+export { SpriteAnimation } from "./g2/SpriteAnimation"
+export { Shape2D } from "./g2/Shape2D"
+export { Physics2D } from "./g2/Physics2D"
+export { Trigger2D } from "./g2/Trigger2D"
+export { CharacterController2D } from "./g2/CharacterController2D"
+export { OneWay2D } from "./g2/OneWay2D"
+export { PhysicsGroup2D } from "./g2/groups2d"
+export { Tilemap } from "./g2/Tilemap"
+export { Texture2D } from "./g2/Texture2D"
+// sprite sheets as data (.sprite.ts files — see src/g2/SpriteSheet.ts)
+export { SpriteSheet, defineSpriteSheet } from "./g2/SpriteSheet"
+export type { SpriteSheetDef, SheetSprite, SpriteMakeOptions } from "./g2/SpriteSheet"
+// tilesets as data (.tiles.ts files — autotile materials, see src/g2/Tileset.ts + autotile.ts)
+export { Tileset, defineTileset, Autotile2D } from "./g2/Tileset"
+export { rawCell, isRawCell, rawIndex } from "./g2/autotile"
+export { rot90, rot180, rot270, flipX, packTile, tileIndex, tileTurns, tileFlip, tileOriented } from "./g2/autotile"
+export type {
+  TilesetDef, TileMaterial, PatchMaterial, PathMaterial, PatchSlots, EdgeSlot, FillBlock, BlockEntry,
+  TileBlock, TilePart,
+} from "./g2/autotile"
+// 2D scenes as data (.scene2d.ts files — see src/g2/defineScene2d.ts) + the cells('…') payload
+export { defineScene2d, Scene2dHandle } from "./g2/defineScene2d"
+export type { Scene2dDef, Scene2dNodeDef, Scene2dEnv, SpriteSourceDef, TilemapSourceDef, Camera2dNodeDef, LoadedScene2d } from "./g2/defineScene2d"
+export { cells, encodeCells, type CellsData } from "./g2/cells"
+// no-code 2D scenario aspects (attachable in scene files — see src/g2/scenarios2d.ts)
+export { CameraFollow } from "./g2/scenarios2d"
+
+// ---- UI (creator-ui) ----
+export {
+  UIScreen, type UIScreenStyle,
+  UIRow, UIColumn, UIBox, type UIContainerStyle,
+  UIText, type UITextStyle,
+  UIButton, type UIButtonStyle,
+  UIImage, type UIImageStyle,
+  UIVideo, type UIVideoStyle,
+  UIInput, UITextArea, type UIInputStyle,
+  UIScrollable, type UIScrollableStyle,
+  UIPager, type UIPagerStyle,
+  UITabs, type UITabDef,
+  defineTabs, type TabDef, type TabsHandle,
+  UIWidget, type UIWidgetStyle,
+  UIModal, type UIModalStyle,
+  UIBottomSheet, type UIBottomSheetStyle,
+  UIPopover, type UIPopoverStyle,
+  UISpacer, type UISpacerStyle,
+  UIVirtualizedList,
+  Router,
+  NativeView, type UINativeViewStyle,
+  registerFont,
+  __uiMap,
+  __UIColumn, __UIRow, __UIBox, __UIButton, __UIScreen, __UIScrollable, __UIWidget,
+} from "./ui/UI"
+// The Presentable navigation contract (docs/navigation-presentable-plan.md). `Presentable` is
+// interface + runtime companion (declaration merging): `Presentable.current` = what's on screen.
+export { Presentable } from "./ui/UI"
+export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from "./ui/UI"
+// The base node type + the union a container accepts as children — documented as the signature of
+// UIColumn/UIRow/append/etc., so they must be global (type-only; erased at runtime).
+export type { UINode, UINodeChild } from "./ui/UINode"
+// App theme variables (docs/ui-theme-plan.md): theme({...}) merges + returns typed var()
+// accessors; system vars are static props (theme.primaryColor, theme["comfort-top"], …).
+export { theme, type ThemeValues, type ThemeAccessors } from "./ui/theme"
+
+// ---- animate ----
+export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate"
+export { cubicBezier } from "./animate/bezier"
+export { easeIn, easeOut, easeInOut } from "./animate/easings"
+
+// ---- plugins (optional, host-provided capabilities — typed NativeView/service wrappers, see src/plugins/) ----
+export { QRScanner } from "./plugins/qr"
+export { CameraView, type CameraFacing } from "./plugins/camera"
+export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation"
+export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/push"
+export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/oauth"
+export { Service } from "./plugins/service"
+
+// ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
+export { defineScene, use, ref, make, SceneHandle, applyEditorPose as __applyEditorPose } from "./scene/defineScene"
+export {
+  defineMaterial, MaterialHandle,
+  // editor-harness helpers (the scene editor's live material paths — not app API)
+  assignMaterialDef as __assignMaterialDef, applyMaterialParam as __applyMaterialParam,
+} from "./scene/material"
+export type { MaterialData, MaterialParamValue, ShaderMaterialDef, LitMaterialDef, UnlitMaterialDef } from "./scene/material"
+export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, CameraNodeDef, AspectEntry, MakeEntry, LoadedScene, SceneInstance } from "./scene/defineScene"
+export { CameraPlace } from "./gl/CameraPlace"
+export type { FieldMeta } from "./core/fields"
+// Editor-only line drawing from generator rebuild() / make() factories / tool hooks — drawn by the
+// scene editor's viewport overlay, a no-op everywhere else (see src/scene/gizmos.ts).
+export { Gizmos, GizmoBuffer as __GizmoBuffer, withGizmoScope as __withGizmoScope } from "./scene/gizmos"
+export type { GizmoStyle, GizmoAnchor } from "./scene/gizmos"
+
+// ---- no-code scenario aspects (attachable in the scene editor — see src/gl/scenarios.ts) ----
+export { MoveTo, FollowPath, Spin, LookAt, PlayAnimation } from "./gl/scenarios"
+
+// ---- editor plugins (called from `*.editor.ts` files — editor bundles only; DCE'd from apps) ----
+export { registerEditorWindow, registerEditorTool, __editorPlugins } from "./scene/editorPlugins"
+export type { EditorApi, EditorRayHit, EditorToolHooks, EditorWindowFn } from "./scene/editorPlugins"
+
+// ---- 3D engine (creator-gl) ----
+export { Scene, ARScene, VRScene } from "./gl/Scene"
+export { Node } from "./gl/Node"
+export { Mesh } from "./gl/Mesh"
+export { Model } from "./gl/Model"
+export { Shape } from "./gl/Shape"
+export { Physics } from "./gl/Physics"
+export { Trigger } from "./gl/Trigger"
+export { CharacterController } from "./gl/CharacterController"
+export { Vehicle } from "./gl/Vehicle"
+export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, AeroConfig } from "./gl/Vehicle"
+export { Wheel } from "./gl/Wheel"
+export type { TireCurve, WheelSuspension, WheelTire, WheelVisual } from "./gl/Wheel"
+export { Gearbox } from "./gl/Gearbox"
+export { AnimationClip } from "./gl/animation/AnimationClip"
+export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip"
+export { Animator } from "./gl/animation/Animator"
+export { Playback } from "./gl/animation/Playback"
+export { Loop } from "./gl/animation/Loop"
+export { Layer } from "./gl/animation/Layer"
+export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition } from "./gl/animation/core"
+export { IK } from "./gl/IK"
+export type { IKTwoBone, IKLookAt } from "./gl/IK"
+export { Light } from "./gl/Light"
+export { Lightmap } from "./gl/Lightmap"
+export { Material } from "./gl/Material"
+export { Geometry } from "./gl/Geometry"
+export { InstancedMesh } from "./gl/InstancedMesh"
+export type { InstanceTransform } from "./gl/InstancedMesh"
+export { Texture } from "./gl/Texture"
+export { Camera } from "./gl/Camera"
+export { Ray } from "./gl/Ray"
+export { Plane } from "./gl/Plane"
+export { Noise } from "./gl/Noise"
+export { Particles, Trail, curve, colorCurve } from "./gl/Particles"

package/runtime/sdk/runtime/app.ts

@@ -6,6 +6,10 @@ import { appEventsOn, appEventsOff, keyboardEventsOn, keyboardEventsOff } from "
 
 export type AppState = "active" | "background"
 
+/** `"landscape"` — either landscape direction (sensor landscape), `"portrait"` — upright only,
+ *  `"auto"` — released: the device's own rotation rules apply. */
+export type OrientationLock = "auto" | "portrait" | "landscape"
+
 type AppEventMap = {
   /** The app left the foreground (home button, tab hidden, another app on top). Delivered before
    *  the host halts the frame loop — the last chance to persist state / pause work. */
@@ -40,6 +44,15 @@ export const app = {
   get keyboardHeight(): number {
     return _creatorUtils.keyboardHeight?.() ?? 0
   },
+  /** Lock the screen orientation — `"landscape"` for a horizontal game (the device rotates to
+   *  landscape right away and stays there whichever way it is held), `"portrait"` for upright
+   *  only, `"auto"` to release. Call it once at startup; the lock is per app run (it resets
+   *  when the app quits or restarts), so there is nothing to undo. The rotation arrives as an
+   *  ordinary resize — layouts reflow, a scene's viewport follows. Silent no-op on hosts
+   *  without a rotatable screen (desktop, headless, web). */
+  setOrientation(mode: OrientationLock): void {
+    _creatorUtils.setOrientation?.(mode)
+  },
   /** Re-run this app's bundle in a fresh world — the platform's `location.reload()`. Pass `url`
    *  to reboot with different launch arguments (the new run reads them via `app.launchUrl`),
    *  `null` to reboot with a cleared one, or omit it to replay the current one. No-op on hosts

package/runtime/sdk/runtime/input.ts

@@ -1,12 +1,175 @@
-// Keyboard/pointer input. Replaces worker's bare `inputKey(code)` global with a small `Input`
-// namespace so the surface reads better and has room to grow (pointer, gamepad) without new globals.
+// Keyboard / mouse / gamepad input behind one `Input` global (docs/input-plan.md).
+//
+// Two kinds of signal, two shapes of API:
+//   - BUTTONS — anything that goes down and up: keyboard keys, mouse buttons, gamepad buttons. One
+//     code vocabulary ('KeyW', 'MouseLeft', 'GamepadSouth'), one held-poll (`Input.key`) and one
+//     event pair (`Input.on('keydown' | 'keyup')`). A mouse button IS a key.
+//   - CONTINUOUS — mouse motion/wheel, sticks, triggers: polled every frame (`Input.mouse.delta`,
+//     `Input.gamepad(0).axis('leftX')`), never events.
+// Bindings ("jump = Space | GamepadSouth") are app code: compare `e.code`, OR a few `Input.key`s.
+// Hosts report physical state only (`_creatorUtils.inputKey/inputRead/registerInputEvent`).
+
+/** Continuous channel ids — the `_creatorUtils.inputRead` contract (bridges.d.ts). */
+export const InputChannel = {
+  MouseX: 0, MouseY: 1, MouseDX: 2, MouseDY: 3, WheelX: 4, WheelY: 5, PointerLocked: 6,
+  GamepadCount: 7,
+  GamepadBase: 16, GamepadStride: 16,
+  PadConnected: 0, PadLeftX: 1, PadLeftY: 2, PadRightX: 3, PadRightY: 4, PadLeftTrigger: 5, PadRightTrigger: 6,
+} as const
+
+export type InputEventName = "keydown" | "keyup" | "gamepadconnected" | "gamepaddisconnected"
+
+/** `keydown` / `keyup` payload. `code` is the same string `Input.key()` takes. */
+export interface InputKeyEvent {
+  readonly type: "keydown" | "keyup"
+  /** Button code: KeyboardEvent.code ('KeyW', 'Space'), 'MouseLeft|Right|Middle|Back|Forward', or
+   *  'GamepadSouth|East|West|North|L1|R1|L2|R2|Select|Start|L3|R3|Up|Down|Left|Right'. */
+  readonly code: string
+  /** Which device: 'keyboard' | 'mouse' | 'gamepad'. */
+  readonly source: "keyboard" | "mouse" | "gamepad"
+  /** Pad index (0..3) for gamepad buttons, undefined otherwise. */
+  readonly gamepad?: number
+  /** OS auto-repeat keydown (key still held) — ignore for one-shot actions. */
+  readonly repeat: boolean
+}
+
+export interface InputGamepadEvent {
+  readonly type: "gamepadconnected" | "gamepaddisconnected"
+  readonly gamepad: number
+}
+
+type Listener<E> = (e: E) => void
+type InputEventMap = {
+  keydown: InputKeyEvent
+  keyup: InputKeyEvent
+  gamepadconnected: InputGamepadEvent
+  gamepaddisconnected: InputGamepadEvent
+}
+
+const listeners: { [K in InputEventName]?: Listener<InputEventMap[K]>[] } = {}
+let hostListenerInstalled = false
+
+const sourceOf = (code: string): InputKeyEvent["source"] =>
+  code.startsWith("Mouse") ? "mouse" : code.startsWith("Gamepad") ? "gamepad" : "keyboard"
+
+const emit = <K extends InputEventName>(name: K, e: InputEventMap[K]) => {
+  const list = listeners[name]
+  if (!list || list.length === 0) return
+  for (const fn of [...list]) fn(e as any)
+}
+
+// One fan-out for the host channel and the test/host `_emit` seam.
+const deliver = (kind: number, code: string, gamepad: number, repeat: number) => {
+  if (kind === 0 || kind === 1) {
+    const src = sourceOf(code)
+    emit(kind === 0 ? "keydown" : "keyup", {
+      type: kind === 0 ? "keydown" : "keyup", code, source: src,
+      gamepad: src === "gamepad" && gamepad >= 0 ? gamepad : undefined, repeat: repeat !== 0,
+    })
+  } else if (kind === 2 || kind === 3) {
+    emit(kind === 2 ? "gamepadconnected" : "gamepaddisconnected",
+         { type: kind === 2 ? "gamepadconnected" : "gamepaddisconnected", gamepad })
+  }
+}
+
+// Lazily claim the host's single listener slot (never at module scope — chisel drops top-level
+// side effects, and a host without the channel simply never fires).
+const ensureHostListener = () => {
+  if (hostListenerInstalled) return
+  hostListenerInstalled = true
+  _creatorUtils.registerInputEvent?.(deliver)
+}
+
+const read = (channel: number): number => _creatorUtils.inputRead?.(channel) ?? 0
+
+/** Mouse state — polled. Position is the cursor inside the viewport in logical px; `delta` is the
+ *  motion during the previous frame (raw where the OS offers it) and keeps counting while locked —
+ *  that's FPS look. Hosts without a mouse report zeros. */
+export const mouse = {
+  get position(): { x: number, y: number } { return { x: read(InputChannel.MouseX), y: read(InputChannel.MouseY) } },
+  get delta(): { x: number, y: number } { return { x: read(InputChannel.MouseDX), y: read(InputChannel.MouseDY) } },
+  /** Wheel notches during the previous frame (+y = wheel toward you / scroll down). */
+  get wheel(): { x: number, y: number } { return { x: read(InputChannel.WheelX), y: read(InputChannel.WheelY) } },
+  /** Pointer lock: cursor hidden + confined, `delta` keeps flowing. Web grants it only from a user
+   *  gesture (call it in a 'keydown' handler for MouseLeft); hosts drop it on focus loss and
+   *  re-acquire on focus. Escape does NOT unlock by itself on native hosts — call `unlock()`. */
+  get locked(): boolean { return read(InputChannel.PointerLocked) !== 0 },
+  lock(): boolean { return _creatorUtils.inputSetPointerLock?.(true) ?? false },
+  unlock(): void { _creatorUtils.inputSetPointerLock?.(false) },
+}
+
+export type GamepadAxisName = "leftX" | "leftY" | "rightX" | "rightY" | "leftTrigger" | "rightTrigger"
+const PAD_AXIS: Record<GamepadAxisName, number> = {
+  leftX: InputChannel.PadLeftX, leftY: InputChannel.PadLeftY, rightX: InputChannel.PadRightX,
+  rightY: InputChannel.PadRightY, leftTrigger: InputChannel.PadLeftTrigger, rightTrigger: InputChannel.PadRightTrigger,
+}
+
+export interface GamepadState {
+  readonly index: number
+  readonly connected: boolean
+  /** Stick axes −1..1 (+Y = down, like the web Gamepad API), triggers 0..1. `deadzone` (default
+   *  0.15) zeroes small stick drift — pass 0 for the raw value. */
+  axis(name: GamepadAxisName, deadzone?: number): number
+  /** Held? Same as `Input.key(code, index)`. */
+  button(code: string): boolean
+}
+
+const padCache: GamepadState[] = []
+const gamepadAt = (index: number): GamepadState => {
+  let g = padCache[index]
+  if (!g) {
+    const base = InputChannel.GamepadBase + InputChannel.GamepadStride * index
+    g = padCache[index] = {
+      index,
+      get connected() { return read(base + InputChannel.PadConnected) !== 0 },
+      axis(name, deadzone = 0.15) {
+        const v = read(base + PAD_AXIS[name])
+        return deadzone > 0 && Math.abs(v) < deadzone ? 0 : v
+      },
+      button(code) { return _creatorUtils.inputKey(code, index) },
+    }
+  }
+  return g
+}
 
 export const Input = {
   /**
-   * Is a key currently held? `code` is a KeyboardEvent.code-style string, e.g. 'ArrowRight',
-   * 'KeyW', 'Space'. Poll this inside setLoop for frame-independent movement.
+   * Is a button held? `code` is the physical key (`KeyboardEvent.code`: 'ArrowRight', 'KeyW',
+   * 'Space'), a mouse button ('MouseLeft', 'MouseRight', 'MouseMiddle') or a gamepad button
+   * ('GamepadSouth' = A/Cross, 'GamepadR2' = right trigger as a button …). Poll inside setLoop for
+   * frame-independent movement. `gamepad` scopes a Gamepad* code to one pad; omitted = any pad.
    */
-  key(code: string): boolean {
-    return _creatorUtils.inputKey(code)
+  key(code: string, gamepad?: number): boolean {
+    return _creatorUtils.inputKey(code, gamepad)
+  },
+
+  /** Listen for a discrete input moment. `keydown`/`keyup` cover EVERY button — keyboard, mouse,
+   *  gamepad — filter on `e.code`. Use these for one-shot actions (jump, shoot, charge-release);
+   *  `Input.key` for continuous ones (walk). */
+  on<K extends InputEventName>(name: K, listener: Listener<InputEventMap[K]>): void {
+    ensureHostListener()
+    const list = (listeners[name] ??= []) as Listener<InputEventMap[K]>[]
+    if (!list.includes(listener)) list.push(listener)
+  },
+  off<K extends InputEventName>(name: K, listener: Listener<InputEventMap[K]>): void {
+    const list = listeners[name] as Listener<InputEventMap[K]>[] | undefined
+    if (!list) return
+    const i = list.indexOf(listener)
+    if (i >= 0) list.splice(i, 1)
   },
+
+  mouse,
+
+  /** Gamepad `index` (0..3). Always returns an object — check `.connected`. */
+  gamepad(index = 0): GamepadState { return gamepadAt(index) },
+  /** Indices of the currently connected gamepads. */
+  gamepads(): number[] {
+    const out: number[] = []
+    const n = read(InputChannel.GamepadCount)
+    for (let i = 0; i < 4 && out.length < n; i++) if (gamepadAt(i).connected) out.push(i)
+    return out
+  },
+
+  /** @internal — hosts/tests: deliver an event exactly as the host listener would. */
+  _emit(kind: number, code: string, gamepad: number, repeat: number): void { deliver(kind, code, gamepad, repeat) },
 }