lecodes-sdk 0.19.2 → 0.20.2

package/src/gl/state.ts

@@ -1,6 +1,6 @@
-// Tiny shared module to break the Node ↔ Scene ↔ touch dependency cycle. The active 3D scene is set
-// here by Scene.open()/close() and read by the touch dispatch system.
-
-import type { Scene } from "./Scene"
-
-export const glState: { activeScene: Scene | null, frame: number } = { activeScene: null, frame: 0 }
+// Tiny shared module to break the Node ↔ Scene ↔ touch dependency cycle. The active 3D scene is set
+// here by Scene.open()/close() and read by the touch dispatch system.
+
+import type { Scene } from "./Scene"
+
+export const glState: { activeScene: Scene | null } = { activeScene: null }

package/src/host.d.ts

@@ -29,6 +29,9 @@ declare global {
     error(...data: any[]): void
   }
 
+  /** Compile-time macro: `asset('./data.json')` yields the file's PARSED data (a .json file is
+   *  data, not code — it ships inside the bundle). See the `string` overload for everything else. */
+  function asset(path: `${string}.json`): any
   /** Compile-time macro: `asset('./hero.png')` is desugared by the bundler into the module import
    *  for that resource. The file must exist — a path that resolves to nothing fails the compile
    *  (`asset not found: ./hero.png (main.ts:3)`); there is no runtime fallback. Calls inside

package/src/inject.ts

@@ -44,6 +44,12 @@ export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, t
 // 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"
+// Game audio (docs/audio-plan.md): decoded clips, a voice pool, buses with effects; 3D through the
+// AudioSource / AudioZone aspects (gl/) and scene.audio.
+export { Sound, type SoundOptions } from "./audio/Sound"
+export { Voice, type VoiceEvents } from "./audio/Voice"
+export { Bus, REVERB_PRESETS, type ReverbPreset, type ReverbParams, type EchoParams } from "./audio/Bus"
+export { audio, type PlaySoundOptions, type SpatialOptions, type Rolloff, type AudioStats } from "./audio/audio"
 export { openFilePicker, files, type FileData } from "./runtime/files"
 export { share } from "./runtime/share"
 export { ClickEvent, TouchStartEvent, LongPressEvent } from "./runtime/touch"
@@ -125,6 +131,11 @@ export { easeIn, easeOut, easeInOut } from "./animate/easings"
 export { QRScanner } from "./plugins/qr"
 export { CameraView, type CameraFacing } from "./plugins/camera"
 export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation"
+export {
+  MapView, type MapOptions, type MapStyle, type MapStyleName, type MapCamera, type MapTap, type LngLat, type CameraMove, type FitOptions,
+  type MapPaddingValues, type MarkerItem, type MarkerTap, type MarkerLayer, type MarkerLayerOptions,
+  type LineLayer, type LineLayerOptions, type UserLocationOptions,
+} from "./plugins/map"
 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"
@@ -163,6 +174,9 @@ export { Model } from "./gl/Model"
 export { Shape } from "./gl/Shape"
 export { Physics } from "./gl/Physics"
 export { Trigger } from "./gl/Trigger"
+export { AudioSource, type AudioCone } from "./gl/AudioSource"
+export { AudioZone } from "./gl/AudioZone"
+export { SceneAudio } from "./gl/SceneAudio"
 export { CharacterController } from "./gl/CharacterController"
 export { Vehicle } from "./gl/Vehicle"
 export type { DriveLayout, DifferentialMode, EngineConfig, SteeringConfig, AeroConfig } from "./gl/Vehicle"
@@ -174,11 +188,15 @@ 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 type { WarpOptions, FeetOptions, FootState } from "./gl/animation/Animator"
+export type { LodMode } from "./gl/animation/Animator"
+export { Feet } from "./gl/animation/Feet"
+export type { FeetOptions, FootState } from "./gl/animation/Feet"
+export { Warp } from "./gl/animation/Warp"
+export type { WarpOptions, StepWarpOptions } from "./gl/animation/Warp"
 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, ActiveClip } from "./gl/animation/core"
+export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition, BlendMember, ActiveClip, ClipInfo, ClipCycle, ClipAlign, KneeAxisReport, StepHandler, ClipEventHandler } from "./gl/animation/core"
 export { IK } from "./gl/IK"
 export type { IKTwoBone, IKLookAt } from "./gl/IK"
 export { Light } from "./gl/Light"
@@ -196,8 +214,11 @@ export { Geometry } from "./gl/Geometry"
 export { InstancedMesh } from "./gl/InstancedMesh"
 export type { InstanceTransform } from "./gl/InstancedMesh"
 export { Texture } from "./gl/Texture"
+export type { TextureLoadOptions } 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"
+export { DecalSet } from "./gl/DecalSet"
+export type { DecalOptions, DecalSetOptions, DecalSpawnOptions, DecalPlacement } from "./gl/DecalSet"

package/src/plugins/map.ts

@@ -0,0 +1,396 @@
+// MapView — a vector map (maplibre-native on iOS/Android) as a Presentable. A typed wrapper over
+// the `NativeView("map")` capability (docs/map-plugin-plan.md): push it (`Router.push(map)`),
+// open it fullscreen (`map.open()`), or embed it among a screen's children where the host builds
+// the "native" layout node. The style is a URL, a bundled `asset()`, a read file or the style
+// object (see MapStyle). Data goes in as named layers (`map.markers(name)`, `map.line(name)`)
+// whose `set()` replaces their content; the camera is driven with `flyTo` / `fitPoints`; the user
+// puck is fed by the app (`setUserLocation`) — the plugin never touches the location hardware.
+//
+// Host-OPTIONAL: it exists where the host registers a "map" view (the `map` plugin from
+// lecodes-plugins) — gate on `MapView.isSupported`. Everything here is sugar over ONE JSON channel
+// (`call` / `on`); the wire contract is the method/event table in docs/map-plugin-plan.md.
+//
+// Ordering: the native map exists only once presented and its style loaded — the plugin emits
+// `ready` then. Data and camera calls issued before that are queued and replayed in order, so an
+// app can build the map declaratively and push it later without a ready-dance of its own.
+
+import { NativeView, NativeViewElement } from "../ui/NativeView"
+import { _channelOn } from "../runtime/channel"
+import type { FetchResponse } from "../runtime/fetch"
+
+/** The ready-made styles a map falls back on — [OpenFreeMap](https://openfreemap.org): OSM data,
+ *  no key, no registration, no request limits, commercial use allowed, and the whole stack is
+ *  open-source if you'd rather self-host. `liberty` is the default. Credit them (and OSM) in your
+ *  app: "© OpenFreeMap © OpenMapTiles, data from OpenStreetMap". A public free instance is a
+ *  donation-funded service with no SLA — for a product with real traffic, run your own tiles and
+ *  pass that style's URL instead. */
+export type MapStyleName = "liberty" | "bright" | "positron" | "dark" | "fiord"
+
+const NAMED_STYLES: Record<string, string> = {
+  liberty: "https://tiles.openfreemap.org/styles/liberty",
+  bright: "https://tiles.openfreemap.org/styles/bright",
+  positron: "https://tiles.openfreemap.org/styles/positron",
+  dark: "https://tiles.openfreemap.org/styles/dark",
+  fiord: "https://tiles.openfreemap.org/styles/fiord",
+}
+
+/**
+ * Where the map's style comes from:
+ *
+ * - a **name** — `"liberty"` (the default), `"positron"`, … see {@link MapStyleName}: a ready-made
+ *   style on a free public tile server, so `MapView()` alone already draws a world map;
+ * - a **URL** — `"https://tiles.example.com/styles/city/style.json"`, the map fetches it;
+ * - a **bundled style** — `asset("./map/style.json")`: the file ships inside the app and the
+ *   wrapper hands its text to the map, so the style itself needs no server (tiles, sprites and
+ *   glyphs are still fetched from whatever urls it names);
+ * - an **already-read file** — a `FetchResponse` from `fetchLocal("style.json")` or
+ *   `await fetch(url)` (a style downloaded once and cached in `files`);
+ * - the **style object** itself — the natural way to substitute a tile-server address at runtime:
+ *   `{ ...style, sources: { openmaptiles: { type: "vector", url: `${server}/data/v3.json` } } }`.
+ *
+ * Whichever form: **every url INSIDE the style (`sources[].url`, `sprite`, `glyphs`) must be
+ * absolute.** maplibre-native, unlike maplibre-gl-js, resolves no relative ones — a style with
+ * them loads to an empty basemap (your layers still draw). A tileserver-gl instance emits
+ * relative urls until its `publicUrl` is configured.
+ */
+// `string & {}` keeps the named suggestions in the editor while still accepting any URL.
+export type MapStyle = MapStyleName | (string & {}) | FetchResponse | object
+
+/** `[longitude, latitude]` — GeoJSON order, the same as the style, the tiles and your data. */
+export type LngLat = [number, number]
+
+export interface MapCamera {
+  center: LngLat
+  zoom: number
+  /** Degrees clockwise from north. */
+  bearing: number
+  /** Degrees from the vertical. */
+  pitch: number
+}
+
+export interface MapOptions {
+  /** The MapLibre style: a ready-made name (`"liberty"` — the default, `"positron"`, …), a URL,
+   *  a style bundled with the app (`asset("./style.json")`), an already-read file
+   *  (`fetchLocal("style.json")`, `await fetch(url)`) or the style object itself — see
+   *  {@link MapStyle}. */
+  style?: MapStyle
+  center?: LngLat
+  zoom?: number
+  minZoom?: number
+  maxZoom?: number
+  bearing?: number
+  pitch?: number
+  /** Two-finger rotate gesture (default true). */
+  rotate?: boolean
+  /** Two-finger tilt gesture (default false — most city maps stay flat). */
+  tilt?: boolean
+}
+
+/** A tap on the map itself — not on a feature of a managed layer. */
+export interface MapTap {
+  lngLat: LngLat
+  /** View-space point, px. */
+  point: [number, number]
+}
+
+export interface CameraMove {
+  zoom?: number
+  bearing?: number
+  pitch?: number
+  /** Animation length, ms (flyTo only; default 600). */
+  duration?: number
+}
+
+export interface MapPaddingValues {
+  top?: number | string
+  left?: number | string
+  bottom?: number | string
+  right?: number | string
+}
+
+export interface FitOptions {
+  /** Px around the points, or per edge. Added to the view padding set by `setPadding`. */
+  padding?: number | MapPaddingValues
+  maxZoom?: number
+  /** Default true. */
+  animate?: boolean
+}
+
+/** One marker. `id` comes back in `onTap`; `icon` names an image of the style's sprite; `color` /
+ *  `title` feed the default layers; extra keys become feature properties. */
+export interface MarkerItem {
+  id: string | number
+  lngLat: LngLat
+  icon?: string
+  color?: string
+  title?: string
+  [property: string]: any
+}
+
+export interface MarkerTap {
+  id: string | number
+  lngLat: LngLat
+  /** Every property of the tapped feature (the item's keys, `id` and `lngLat` excluded). */
+  properties: Record<string, any>
+}
+
+export interface MarkerLayerOptions {
+  /** Group nearby markers into clusters (a cluster tap zooms in). Default false. */
+  cluster?: boolean
+  /** Cluster radius, px (default 50). */
+  clusterRadius?: number
+  /** Zoom at which clusters stop forming (default: maxZoom − 1). */
+  clusterMaxZoom?: number
+}
+
+export interface LineLayerOptions {
+  color?: string
+  /** Px (default 4). */
+  width?: number
+  /** 0–1 (default 1). */
+  opacity?: number
+}
+
+export interface UserLocationOptions {
+  /** Horizontal accuracy radius, meters — drawn as the halo around the dot. */
+  accuracy?: number | null
+  /** Degrees clockwise from north — drawn as the direction wedge; null hides it. */
+  heading?: number | null
+}
+
+export interface MarkerLayer {
+  readonly name: string
+  /** Replace the layer's markers. */
+  set(items: MarkerItem[]): this
+  clear(): this
+  /** A marker (or any feature of this layer's source) was tapped. */
+  onTap(callback: (marker: MarkerTap) => void): this
+}
+
+export interface LineLayer {
+  readonly name: string
+  /** Replace the line with these vertices. */
+  set(coordinates: LngLat[]): this
+  clear(): this
+}
+
+export interface MapView extends NativeView {
+  /** The style loaded and the map is interactive (queued calls have been replayed). */
+  onReady(callback: () => void): this
+  /** A tap that hit no feature of a managed layer. */
+  onTap(callback: (tap: MapTap) => void): this
+  /** The camera settled after a gesture or an animation. */
+  onMove(callback: (camera: MapCamera) => void): this
+  /** The map reported a problem — a style that wouldn't load, a source it couldn't reach. Never
+   *  fatal; with no handler the message goes to `console.error`, so it is never silent. */
+  onError(callback: (error: { message: string }) => void): this
+
+  /** A named marker layer (one GeoJSON source). If the style already declares a source with this
+   *  name, its layers are used as-is and only the data is pushed; otherwise the plugin creates the
+   *  source and default marker layers (colored dot, `icon`, `title` label; clusters on request). */
+  markers(name: string, options?: MarkerLayerOptions): MarkerLayer
+  /** A named line layer (one GeoJSON source) — same style-first rule as `markers`. */
+  line(name: string, options?: LineLayerOptions): LineLayer
+  /** Raw escape hatch: replace the data of any GeoJSON source in the style. */
+  setData(source: string, geojson: object): this
+
+  flyTo(center: LngLat, options?: CameraMove): this
+  jumpTo(center: LngLat, options?: CameraMove): this
+  /** Fit the camera to these points (padding + the view padding respected). */
+  fitPoints(points: LngLat[], options?: FitOptions): this
+  /** Content inset: the part of the view covered by your UI (`"40%"` = of the view's size).
+   *  Camera operations center inside the remaining area. */
+  setPadding(padding: MapPaddingValues): this
+  getCamera(): Promise<MapCamera>
+
+  /** Move the user puck (the map draws it; the position comes from you — `Geolocation.watch`).
+   *  `null` hides it. */
+  setUserLocation(lngLat: LngLat | null, options?: UserLocationOptions): this
+}
+
+type Queued = { method: string, args: any[] }
+type LayerSpec = { kind: "markers" | "line", options: object }
+
+/** Methods whose effect lives in the STYLE, not in the view: a style (re)load wipes them, so the
+ *  wrapper keeps their last value and re-applies it on every `ready` instead of replaying them
+ *  from the queue. Camera calls are not here — the camera survives a style reload. */
+const STATEFUL = ["ensureLayer", "setData", "setPadding", "setUserLocation"]
+
+class MapViewElement extends NativeViewElement {
+  private _ready = false
+  private _queue: Queued[] = []
+  private readonly _layers = new Map<string, MapLayerHandle>()
+  /** Style-lifetime state, re-applied on every `ready` (see STATEFUL). */
+  private readonly _specs = new Map<string, LayerSpec>()
+  private readonly _data = new Map<string, object>()
+  private _padding?: MapPaddingValues
+  private _user?: any[]
+  private readonly _readyCallbacks: (() => void)[] = []
+  private readonly _tapCallbacks: ((tap: MapTap) => void)[] = []
+  private readonly _moveCallbacks: ((camera: MapCamera) => void)[] = []
+  private readonly _errorCallbacks: ((error: { message: string }) => void)[] = []
+
+  constructor(options: MapOptions = {}) {
+    super("map", _styleParams(options))
+    _channelOn(this.nvl, "ready", () => this._onReady())
+    _channelOn(this.nvl, "tap", (data: any) => this._onTap(data))
+    _channelOn(this.nvl, "moveEnd", (data: any) => { for (const cb of [...this._moveCallbacks]) cb(data) })
+    _channelOn(this.nvl, "error", (data: any) => this._onError(data))
+  }
+
+  onReady(callback: () => void): this { this._readyCallbacks.push(callback); return this }
+  onTap(callback: (tap: MapTap) => void): this { this._tapCallbacks.push(callback); return this }
+  onMove(callback: (camera: MapCamera) => void): this { this._moveCallbacks.push(callback); return this }
+  onError(callback: (error: { message: string }) => void): this { this._errorCallbacks.push(callback); return this }
+
+  markers(name: string, options: MarkerLayerOptions = {}): MarkerLayer {
+    return this._layer(name, "markers", options) as MarkerLayer
+  }
+  line(name: string, options: LineLayerOptions = {}): LineLayer {
+    return this._layer(name, "line", options) as LineLayer
+  }
+  setData(source: string, geojson: object): this {
+    this._data.set(source, geojson)
+    this._send("setData", [source, geojson])
+    return this
+  }
+
+  flyTo(center: LngLat, options: CameraMove = {}): this { this._send("flyTo", [center, options]); return this }
+  jumpTo(center: LngLat, options: CameraMove = {}): this { this._send("jumpTo", [center, options]); return this }
+  fitPoints(points: LngLat[], options: FitOptions = {}): this { this._send("fitPoints", [points, options]); return this }
+  setPadding(padding: MapPaddingValues): this { this._padding = padding; this._send("setPadding", [padding]); return this }
+  getCamera(): Promise<MapCamera> { return this.call("getCamera") }
+
+  setUserLocation(lngLat: LngLat | null, options: UserLocationOptions = {}): this {
+    this._user = [lngLat, options]
+    this._send("setUserLocation", [lngLat, options])
+    return this
+  }
+
+  /** @internal queue until `ready`, then straight through. Rejections are logged, never thrown:
+   *  a fire-and-forget camera/data call has no caller to reject to. */
+  _send(method: string, args: any[]): void {
+    if (!this._ready) { this._queue.push({ method, args }); return }
+    this.call(method, ...args).catch((e: Error) => console.error(`MapView.${method}: ${e.message}`))
+  }
+
+  private _layer(name: string, kind: "markers" | "line", options: object): MapLayerHandle {
+    let layer = this._layers.get(name)
+    if (!layer) {
+      layer = new MapLayerHandle(this, name)
+      this._layers.set(name, layer)
+      this._specs.set(name, { kind, options })
+      this._send("ensureLayer", [name, kind, options])
+    }
+    return layer
+  }
+
+  /** A style load — the first one or a reload — starts from a style that knows nothing about the
+   *  app's layers, so re-apply them all, then whatever else waited in the queue. Without this a
+   *  second `ready` (a host that loads its default style before the app's, a style swap) leaves a
+   *  correct-looking map with no data on it. */
+  private _onReady(): void {
+    this._ready = true
+    const queue = this._queue
+    this._queue = []
+    for (const [name, spec] of this._specs) this._send("ensureLayer", [name, spec.kind, spec.options])
+    for (const [source, geojson] of this._data) this._send("setData", [source, geojson])
+    if (this._padding) this._send("setPadding", [this._padding])
+    if (this._user) this._send("setUserLocation", this._user)
+    for (const q of queue) if (STATEFUL.indexOf(q.method) < 0) this._send(q.method, q.args)
+    for (const cb of [...this._readyCallbacks]) cb()
+  }
+
+  private _onError(data: any): void {
+    // Unhandled is not unheard: a style the host couldn't load is exactly the failure that looks
+    // like "the map is blank and nothing happened".
+    if (this._errorCallbacks.length === 0) { console.error(`MapView: ${data?.message ?? "unknown error"}`); return }
+    for (const cb of [...this._errorCallbacks]) cb(data)
+  }
+
+  private _onTap(data: any): void {
+    const feature = data?.feature
+    const layer = feature ? this._layers.get(feature.source) : undefined
+    if (layer) {
+      layer._tap({ id: feature.id, lngLat: data.lngLat, properties: feature.properties ?? {} })
+      return
+    }
+    for (const cb of [...this._tapCallbacks]) cb({ lngLat: data.lngLat, point: data.point })
+  }
+}
+
+/** One named GeoJSON source on the map — the object behind both `MarkerLayer` and `LineLayer`. */
+class MapLayerHandle {
+  private readonly _tapCallbacks: ((marker: MarkerTap) => void)[] = []
+  private readonly _map: MapViewElement
+  readonly name: string
+
+  constructor(map: MapViewElement, name: string) {
+    this._map = map
+    this.name = name
+  }
+
+  set(items: MarkerItem[] | LngLat[]): this {
+    this._map.setData(this.name, _toGeoJson(items))
+    return this
+  }
+  clear(): this {
+    this._map.setData(this.name, { type: "FeatureCollection", features: [] })
+    return this
+  }
+  onTap(callback: (marker: MarkerTap) => void): this {
+    this._tapCallbacks.push(callback)
+    return this
+  }
+  /** @internal */
+  _tap(marker: MarkerTap): void {
+    for (const cb of [...this._tapCallbacks]) cb(marker)
+  }
+}
+
+/** @internal `MapOptions` → host params. A style URL stays a url the map fetches itself; every
+ *  other form is read HERE and crosses as `styleJson` text — one string, once, at creation. A
+ *  bundled `asset()` is `"id:N"` in shell compiles (the host already holds the bytes) and a plain
+ *  url in server compiles, so the same call works on every host. */
+export const _styleParams = (options: MapOptions = {}): any => {
+  const { style = "liberty", ...rest } = options
+  if (typeof style === "string") {
+    if (!style.startsWith("id:")) return { ...rest, style: NAMED_STYLES[style] ?? style }
+    const text = _creatorUtils.fetchToText(+style.slice(3))
+    if (!text) throw new Error("MapView: the style asset is empty or missing")
+    return { ...rest, styleJson: text }
+  }
+  const response = style as FetchResponse
+  return { ...rest, styleJson: typeof response.text === "function" ? response.text() : JSON.stringify(style) }
+}
+
+/** @internal marker items → a FeatureCollection of Points; a coordinate list → one LineString. */
+export const _toGeoJson = (items: MarkerItem[] | LngLat[]): object => {
+  if (items.length > 0 && Array.isArray(items[0])) {
+    return { type: "Feature", properties: {}, geometry: { type: "LineString", coordinates: items } }
+  }
+  return {
+    type: "FeatureCollection",
+    features: (items as MarkerItem[]).map(item => {
+      const { id, lngLat, ...properties } = item
+      return { type: "Feature", id, properties: { ...properties, id }, geometry: { type: "Point", coordinates: lngLat } }
+    }),
+  }
+}
+
+/**
+ * Create a map view. `MapView.isSupported` reports whether this host registered a "map" view —
+ * check it before offering the feature (web, headless and shells without the plugin have none).
+ */
+// PURE IIFE so an app that never uses the map tree-shakes the whole plugin away (see NativeView).
+export const MapView: {
+  (options?: MapOptions): MapView
+  /** Whether this host registered a "map" view. */
+  readonly isSupported: boolean
+} = /*#__PURE__*/ (() => {
+  const factory = (options: MapOptions = {}): MapView => new MapViewElement(options) as unknown as MapView
+  Object.defineProperty(factory, "isSupported", {
+    get: (): boolean => NativeView.isSupported("map"),
+  })
+  return factory as any
+})()

package/src/runtime/input.ts

@@ -12,7 +12,7 @@
 /** 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,
+  GamepadCount: 7, PointerOnUI: 8,
   GamepadBase: 16, GamepadStride: 16,
   PadConnected: 0, PadLeftX: 1, PadLeftY: 2, PadRightX: 3, PadRightY: 4, PadLeftTrigger: 5, PadRightTrigger: 6,
 } as const
@@ -94,6 +94,11 @@ export const mouse = {
    *  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 },
+  /** The primary button went down on a UI element (a button, a scrollable, an input, a modal
+   *  backdrop) and is still held. Stays true wherever the cursor drifts until the release, so
+   *  `if (!Input.mouse.onUI) look(Input.mouse.delta)` never turns a HUD drag into camera look.
+   *  Always false while `locked`. A press that fell through to the scene reads false. */
+  get onUI(): boolean { return read(InputChannel.PointerOnUI) !== 0 },
   lock(): boolean { return _creatorUtils.inputSetPointerLock?.(true) ?? false },
   unlock(): void { _creatorUtils.inputSetPointerLock?.(false) },
 }

package/src/ui/UIImage.ts

@@ -2,6 +2,7 @@ import type { FetchResponse } from "../runtime/fetch"
 import type { SvgSourceValue as SvgSource } from "../runtime/misc"
 import type { File } from "../runtime/fetch"
 import { Canvas, isCanvas } from "../canvas/Canvas"
+import type { Scene2D } from "../g2/Scene2D"
 import { Element, type Color, type ElementStyle, type UIElementBase } from "./UINode"
 
 export type UIImageStyle = ElementStyle & { borderRadius?: number, objectFit?: "cover" | "contain" | "fill", tintColor?: Color }
@@ -10,19 +11,32 @@ export type UIImageStyle = ElementStyle & { borderRadius?: number, objectFit?: "
  *  docs/canvas-contract.md ("Pending"). */
 export type CanvasImageSource = { canvasSurface: number }
 
-/** Accepted image sources. A Canvas is baked to a surface marker on assign. */
-export type ImageSource = string | FetchResponse | File | SvgSource | Canvas
+/** A live 2D scene as an image source: the host draws the scene into the node's box every frame
+ *  (the scene's camera, projected into the box). No intrinsic size — give the node a width and
+ *  height. */
+export type Scene2DImageSource = { scene2d: number }
 
-const toSrc = (src: ImageSource): string | FetchResponse | File | SvgSource | CanvasImageSource =>
+/** Accepted image sources. A Canvas is baked to a surface marker on assign; a Scene2D becomes a
+ *  live-scene marker. */
+export type ImageSource = string | FetchResponse | File | SvgSource | Canvas | Scene2D
+
+// An engine object that knows how to present itself as an image source (Scene2D._imageSrc). Duck-typed
+// so the UI layer never imports an engine class — a UI-only bundle carries no engine bridge.
+const hasImageSrc = (v: unknown): v is { _imageSrc(): Scene2DImageSource } =>
+  typeof v === "object" && v !== null && typeof (v as { _imageSrc?: unknown })._imageSrc === "function"
+
+const toSrc = (src: ImageSource): ResolvedImageSource =>
   // _bakeSurfaceForUI (not _bakeSurface) also flags the canvas UI-bound, so canvas.update() later
   // refreshes this image node in place — that's what makes an animated UIImage(canvas) update.
-  isCanvas(src) ? { canvasSurface: src._bakeSurfaceForUI() } : src
+  isCanvas(src) ? { canvasSurface: src._bakeSurfaceForUI() } : hasImageSrc(src) ? src._imageSrc() : src
 
-/** The stored/resolved image source (a Canvas is resolved to a surface marker). */
-export type ResolvedImageSource = string | FetchResponse | File | SvgSource | CanvasImageSource
+/** The stored/resolved image source (a Canvas is resolved to a surface marker, a Scene2D to a
+ *  live-scene marker). */
+export type ResolvedImageSource = string | FetchResponse | File | SvgSource | CanvasImageSource | Scene2DImageSource
 
 /** An image element. Sources: URL / `asset(...)`, fetch response / File, an SVG source
- *  (`assetIcon`), or a live Canvas (`canvas.update()` refreshes the node in place). */
+ *  (`assetIcon`), a live Canvas (`canvas.update()` refreshes the node in place), or a live Scene2D
+ *  (drawn into the box every frame — a minimap). */
 export interface UIImage extends UIElementBase<UIImageStyle> {
   readonly type: "image",
   /** The image source — writable to swap the picture in place. */