lecodes-sdk 0.19.2 → 0.20.2

package/dist/types/gl/animation/Feet.d.ts

@@ -0,0 +1,85 @@
+import { Vec3 } from "../../math/vec";
+import type { KneeAxisReport, StepHandler } from "./core";
+/** The feet settings (`anim.feet.set()` / the properties of `anim.feet`). Distances are metres, times
+ *  seconds. Every key is optional and only the keys given change. */
+export type FeetOptions = {
+    /** The contact bones per side — `'LeftFoot'`, or with a toe / ball `['LeftFoot', 'LeftToeBase']`.
+     *  Default: classified from the bone names (Mixamo / Unity / Blender / UE). Setting them re-bakes
+     *  every clip's contacts and phase. */
+    left?: string | string[];
+    right?: string | string[];
+    /** FOOT LOCK: a foot the shown clip calls planted is pinned where it landed — heel to ball, rolling
+     *  as the clip rolls — and the leg re-solved to keep it there while the body moves on. Off by default. */
+    lock?: boolean;
+    /** GROUND IK: each foot is put on the ground the engine probes under it (stairs, a slope, a kerb),
+     *  aligned to its normal, the pelvis lowered so the leg can reach. Needs a physics world to probe;
+     *  without one the ground is the node's own plane. Off by default. */
+    ik?: boolean;
+    /** How far the pelvis may drop for the ground (default 0.35). */
+    pelvis?: number;
+    /** A locked foot never absorbs more residual than this — beyond it the anchor follows the animation
+     *  instead of fighting it (default 0.10). */
+    unlockDistance?: number;
+    /** The lock's ease in / out, seconds (default 0.08 / 0.12). */
+    lockIn?: number;
+    lockOut?: number;
+    /** 0..1: how much the foot tilts onto the ground normal (default 1). */
+    align?: number;
+    /** The probe ray's reach above and below the ankle (default 0.6). */
+    probe?: number;
+    /** The lock plants only once the animated ankle moves slower than this, m/s (default 0.2). Raise it
+     *  to pin a foot a transition is still dragging. */
+    plantSpeed?: number;
+};
+/** One foot after this frame's evaluation (`anim.feet.state(side)`): whether the lock holds it, the
+ *  lock's weight (eased 0…1), where it was pinned and where the leg was asked to put the ankle — all world. */
+export type FootState = {
+    locked: boolean;
+    weight: number;
+    anchor: Vec3;
+    target: Vec3;
+};
+export declare class Feet {
+    private readonly _c;
+    private readonly _o;
+    /** Change several settings at once; only the keys given change. Chainable. */
+    set(options: FeetOptions): this;
+    /** The current settings (what was set; unset keys are the engine's defaults). */
+    get options(): Readonly<FeetOptions>;
+    get lock(): boolean;
+    set lock(v: boolean);
+    get ik(): boolean;
+    set ik(v: boolean);
+    get pelvis(): number;
+    set pelvis(v: number);
+    get unlockDistance(): number;
+    set unlockDistance(v: number);
+    get lockIn(): number;
+    set lockIn(v: number);
+    get lockOut(): number;
+    set lockOut(v: number);
+    get align(): number;
+    set align(v: number);
+    get probe(): number;
+    set probe(v: number);
+    get plantSpeed(): number;
+    set plantSpeed(v: number);
+    /** The contact bones (`undefined` = classified from the names). */
+    get left(): string | string[] | undefined;
+    set left(v: string | string[] | undefined);
+    get right(): string | string[] | undefined;
+    set right(v: string | string[] | undefined);
+    /** One foot's state after this frame's evaluation — where the lock holds it and with what weight
+     *  (a debug beam under the foot). `undefined` on a host without the feet stage, or before anything played. */
+    state(side: "left" | "right"): FootState | undefined;
+    /** The skeleton's calibrated KNEE HINGE AXIS for a side (thigh-local, unit) with its confidence report —
+     *  measured once over every bound clip's knee rotation track. `undefined` = no leg chain, or no knee
+     *  motion bound to calibrate from. */
+    kneeAxis(side: "left" | "right"): KneeAxisReport | undefined;
+    /** A foot planted (world position) — audio, dust, decals. Fires for what the BASE layer shows, from
+     *  the clip's own contacts; a clip with no contacts fires nothing. */
+    onStep(cb: StepHandler): this;
+    offStep(cb: StepHandler): this;
+    private pushBones;
+    private push;
+}

package/dist/types/gl/animation/Warp.d.ts

@@ -0,0 +1,53 @@
+/** What `anim.warp` turns on. Speeds are m/s, angles degrees, distances metres. */
+export type WarpOptions = {
+    /** Fit the stride to the speed the body actually travels at. `[min, max]` clamps the scale (default
+     *  0.85…1.2). A CORRECTION: a pack whose takes already read right at the speeds it is played at wants
+     *  none of this; open the range for a pack that must cover speeds it was never recorded at. */
+    stride?: boolean | [number, number];
+    /** Turn the lower body toward where the body really travels; a number caps the turn in degrees
+     *  (default 20). The whole twist lives in one joint: a few degrees read as a lean, a lot as a broken
+     *  back. Only applied while the gait LOOP shows — a start, a turn or a stop walks a path of its own. */
+    orientation?: boolean | number;
+    /** Below this speed — the game's or the clip's — both warps are off (default 0.2). */
+    minSpeed?: number;
+    /** How far the pelvis may drop to keep a stretched leg from locking straight (default 0.25). */
+    pelvis?: number;
+    /** The stride scale's own spring, seconds (default 0.15): the shown clip's recorded speed steps at every
+     *  switch, so the scale is smoothed rather than followed. */
+    strideTime?: number;
+};
+/** STEP WARP dials (`anim.warp.step`): `stride` scales each foot's travel-direction offset from its hip,
+ *  `lift` = metres ADDED to its height (swing-gated; negative = a shuffle; half of it raises the pelvis),
+ *  `pitch` (degrees, + = toes up) rotates each foot about its lateral axis, `slope` (degrees, + = ascending)
+ *  the invisible staircase — feet on the incline, auto pitch, the character raised to hold each planted
+ *  foot on its tread. A tuning bench's dial; locomotion will drive this itself later. */
+export type StepWarpOptions = {
+    stride?: number;
+    lift?: number;
+    pitch?: number;
+    slope?: number;
+};
+export declare class Warp {
+    private readonly _c;
+    private _o;
+    private _step;
+    /** Replace the settings: `true` = both warps with the defaults, `false` / `{}` = off, or the options.
+     *  (Replaces, does not merge — what is not asked for is off.) Chainable. */
+    set(w: WarpOptions | boolean): this;
+    /** The current settings. */
+    get options(): Readonly<WarpOptions>;
+    get stride(): boolean | [number, number];
+    set stride(v: boolean | [number, number]);
+    get orientation(): boolean | number;
+    set orientation(v: boolean | number);
+    get minSpeed(): number;
+    set minSpeed(v: number);
+    get pelvis(): number;
+    set pelvis(v: number);
+    get strideTime(): number;
+    set strideTime(v: number);
+    /** The step warp dials; `null` = off. */
+    get step(): StepWarpOptions | null;
+    set step(v: StepWarpOptions | null | undefined);
+    private push;
+}

package/dist/types/gl/animation/core.d.ts

@@ -6,18 +6,17 @@ import { Vec3 } from "../../math/vec";
 import type { Node } from "../Node";
 /** A position on a blend axis (1D) or plane (2D). */
 export type BlendPosition = number | readonly [number, number];
-/** The transition time (seconds) a play / playLoop without `fade` uses. */
-export declare const DEFAULT_FADE = 0.2;
 export type PlayOptions = {
-    /** Transition seconds — how long the difference to the pose the layer SHOWED takes to decay
-     *  (default 0.2; `0` = cut). Also the transition back at the end unless `fadeOut` overrides it. */
+    /** Transition seconds — how long the difference to the pose the layer SHOWED (its loop, a one-shot,
+     *  or rest) takes to decay. Default `0` = cut: a fade is always asked for, never implied. Also the
+     *  transition back to the loop at the end unless `fadeOut` overrides it. */
     fade?: number;
     /** Transition seconds for the way in only (overrides `fade`). */
     fadeIn?: number;
-    /** One-shots: the transition BACK at the end (overrides `fade`). It starts this long before the
-     *  clip ends — while it still plays — so the hand-over lands on the last pose, not after it. On a
-     *  layer with no loop to return to, giving `fadeOut` releases the layer at the end instead of
-     *  holding the last frame. */
+    /** One-shots: the transition BACK to the loop at the end (overrides `fade`; `0` = cut at the end).
+     *  It starts this long before the clip ends — while it still plays — so the hand-over lands on the
+     *  last pose, not after it. On a layer with no loop the clip HOLDS its last frame (a rock that broke
+     *  stays broken) — `anim.stop({ fade })` is the way back to rest. */
     fadeOut?: number;
     /** Playback rate for this clip (default 1). */
     speed?: number;
@@ -39,8 +38,8 @@ export type StopOptions = {
     fade?: number;
 };
 export type LoopOptions = {
-    /** Transition seconds from whatever the layer shows — its previous loop, or a one-shot still
-     *  playing (default 0.2; `0` = cut). */
+    /** Transition seconds from whatever the layer shows — its previous loop, a one-shot still playing,
+     *  or rest. Default `0` = cut: a loop wanting a transition asks for one (`{ fade: 0.2 }`). */
     fade?: number;
     /** Playback rate of the loop's clips (default 1). */
     speed?: number;
@@ -48,8 +47,17 @@ export type LoopOptions = {
      *  over from a start / turn clip wants). The members share one clock, so this is every member's phase. */
     phase?: number | "match";
 };
-/** What a layer loops: one clip (name / index), or a blend space `{ name: position }`. */
-export type LoopDef = string | number | Record<string, BlendPosition>;
+/** A blend member with its CYCLE given explicitly: `at` = its position, `offset` = its gait phase at t = 0
+ *  (0 = a left-foot-down, 0.5 = a right-foot-down, 0–1), `cycles` = how many gait cycles the clip holds
+ *  (a two-stride loop: 2). Both are measured offline from the clip's foot marks. Members given as a
+ *  bare position run in normalized time and have no cycle (nothing phase-matches to them). */
+export type BlendMember = {
+    at: BlendPosition;
+    offset?: number;
+    cycles?: number;
+};
+/** What a layer loops: one clip (name / index), or a blend space `{ name: position | { at, offset, cycles } }`. */
+export type LoopDef = string | number | Record<string, BlendPosition | BlendMember>;
 /** One clip the layer shows this frame — `layer.active` / `anim.active` (a debug overlay's list). */
 export type ActiveClip = {
     name: string;
@@ -73,9 +81,28 @@ export type LayerOptions = {
 export type ClipEventHandler = (clip: string, layer: Layer) => void;
 /** A foot planted: which one, and where in the world it landed. */
 export type StepHandler = (side: "left" | "right", position: Vec3) => void;
-/** What the engine measured on a clip once it was bound to this skeleton (`anim.curves('Walk')`).
+/** A loop's GAIT CYCLE as two numbers — what a blend member's `{ offset, cycles }` wants: φ(t) = offset +
+ *  cycles · t / duration, 0 = a left-foot-down. `residual` = the worst foot-down's distance from that line
+ *  (cycles; a clean loop sits under 0.03), `steps` = the foot-downs it was fitted through. */
+export type ClipCycle = {
+    offset: number;
+    cycles: number;
+    residual: number;
+    steps: number;
+};
+/** A loop's cycle found by POSE against a reference loop (`clipInfo(clip).alignTo(ref)`): the `{ offset,
+ *  cycles }` under which it shows the reference's pose at the reference's phase. `score` = the fit at that
+ *  alignment (metres, the joint distance + velocity measure), `margin` = how much worse the runner-up
+ *  alignment ≥ 0.2 cycle away is — near 0 means ambiguous (a mirror pair, an in-place idle). */
+export type ClipAlign = {
+    offset: number;
+    cycles: number;
+    score: number;
+    margin: number;
+};
+/** What the engine measured on a clip once it was bound to this skeleton (`anim.clipInfo('Walk')`).
  *  The root curves are of the clip's ROOT bone — its travel is what root motion would move. */
-export type ClipCurves = {
+export type ClipInfo = {
     /** total horizontal root travel, metres */
     travel: number;
     /** mean root speed over the clip, m/s */
@@ -84,6 +111,17 @@ export type ClipCurves = {
     turn: number;
     /** the root barely moves — an in-place clip */
     inPlace: boolean;
+    /** The gait cycle fitted through the foot contacts (a foot already down at t = 0 is not a step) —
+     *  the numbers a blend member takes as `{ offset, cycles }`. Undefined: no steps. */
+    cycle(): ClipCycle | undefined;
+    /** This loop's cycle found by POSE against `reference` (its cycle given, else `reference`'s `cycle()`,
+     *  else offset 0 / one cycle — the answer is then relative to the reference's own time). Reads no marks:
+     *  a markless loop (swimming, breathing, an upper-body sway) gets a cycle, and a marked one gets a
+     *  second opinion — a mirrored anchor shows as a 0.5 disagreement with `cycle()`. Undefined: nothing to compare. */
+    alignTo(reference: string | number, cycle?: {
+        offset: number;
+        cycles: number;
+    }): ClipAlign | undefined;
     /** the clip has a gait cycle (feet planting in turn) — `phaseAt` is meaningful */
     hasPhase: boolean;
     /** When each foot TOUCHES the ground, seconds — the phase anchor. `still` is the window inside it
@@ -126,6 +164,12 @@ export type ClipCurves = {
     turnAt(time: number): number;
     /** the root's own speed at `time`, m/s — how fast the clip is moving the body right there */
     speedAt(time: number): number;
+    /** the PELVIS' yaw relative to the clip's heading at `time` (rad, + = left, wrapped to ±π): the stance twist
+     *  the heading leaves out — an idle stands ~43° off the course it starts along, a stop's tail turns into that
+     *  stance while the heading holds. A controller that switches clips mid-pose can keep the PELVIS continuous
+     *  (turn the node by the difference between the two clips' values) where keeping the course would swing
+     *  the body. Without a baked heading: the pelvis' yaw at frame 0 throughout. */
+    pelvisYawAt(time: number): number;
     /** the unit travel direction at `time` ([x, z], model space, held through stills) — integrate
      *  direction × d(travel) to reconstruct the root's 2D path (a treadmill display, a turn's arc) */
     directionAt(time: number): [number, number];
@@ -185,7 +229,7 @@ export type ClipCurves = {
      *  relative to the root, no turn). Starts, stops and turns are not. */
     cyclic: boolean;
 };
-/** The calibrated knee hinge-axis report (`anim.kneeAxis('left')`): the axis in the thigh's local
+/** The calibrated knee hinge-axis report (`anim.feet.kneeAxis('left')`): the axis in the thigh's local
  *  frame, and the calibration's own confidence — the angular spread of its measurements (radians;
  *  a real knee comes in at a few degrees) over `samples` consecutive-frame deltas of the pack.
  *  `plant` = the calibrated PLANT HEIGHTS (model space): where the ankle / toe actually sit under
@@ -309,7 +353,7 @@ export declare class Core {
     /** A bound clip's current playhead, seconds (-1 = not bound). */
     timeOf(ref: string | number): number;
     /** What the engine measured on the clip once it was bound to this skeleton — binds it if needed. */
-    curves(ref: string | number): ClipCurves | undefined;
+    clipInfo(ref: string | number): ClipInfo | undefined;
     /** The skeleton's calibrated knee hinge axis for a side, with its confidence report — measured once
      *  over every bound clip's knee rotation track. Undefined = no leg chain / no knee motion bound. */
     kneeAxis(side: "left" | "right"): KneeAxisReport | undefined;
@@ -321,7 +365,7 @@ export declare class Core {
      *  own lateral axis — a slope's foot rotation; `slope` (degrees, + = ascending) is the INVISIBLE
      *  STAIRCASE: foot heights follow the incline (leading foot higher) and the feet auto-pitch by
      *  the same angle — pair it with raising the character by tan(slope) × the stride-scaled clip
-     *  travel (`curves(clip).travelAt`), which holds every planted foot's world height constant on
+     *  travel (`clipInfo(clip).travelAt`), which holds every planted foot's world height constant on
      *  its own tread. Solved in the calibrated knee hinge plane with a SOFT reach (a leg at its limit
      *  keeps a residual knee bend instead of popping against the clamp), and whenever a leg would
      *  overreach — a descent, a long stride — the pelvis lowers by exactly the excess (weighted by

package/dist/types/gl/state.d.ts

@@ -1,5 +1,4 @@
 import type { Scene } from "./Scene";
 export declare const glState: {
     activeScene: Scene | null;
-    frame: number;
 };

package/dist/types/inject.d.ts

@@ -23,6 +23,10 @@ export { WebSocket } from "./runtime/net";
 export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform } from "./net";
 export { __rpc, __channel, __serverOnly, RpcError, type ClientChannel } from "./runtime/rpc";
 export { AudioPlayer, VideoPlayer } from "./runtime/media";
+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";
@@ -60,6 +64,7 @@ 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";
@@ -83,6 +88,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";
@@ -94,11 +102,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";
@@ -116,8 +128,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/dist/types/plugins/map.d.ts

@@ -0,0 +1,174 @@
+import { NativeView } from "../ui/NativeView";
+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";
+/**
+ * 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.
+ */
+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;
+}
+/**
+ * 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).
+ */
+export declare const MapView: {
+    (options?: MapOptions): MapView;
+    /** Whether this host registered a "map" view. */
+    readonly isSupported: boolean;
+};

package/dist/types/runtime/input.d.ts

@@ -8,6 +8,7 @@ export declare const InputChannel: {
     readonly WheelY: 5;
     readonly PointerLocked: 6;
     readonly GamepadCount: 7;
+    readonly PointerOnUI: 8;
     readonly GamepadBase: 16;
     readonly GamepadStride: 16;
     readonly PadConnected: 0;
@@ -64,6 +65,11 @@ export declare 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()`. */
     readonly locked: boolean;
+    /** 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. */
+    readonly onUI: boolean;
     lock(): boolean;
     unlock(): void;
 };
@@ -108,6 +114,11 @@ export declare const Input: {
          *  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()`. */
         readonly locked: boolean;
+        /** 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. */
+        readonly onUI: boolean;
         lock(): boolean;
         unlock(): void;
     };

package/dist/types/ui/UIImage.d.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 } from "../canvas/Canvas";
+import type { Scene2D } from "../g2/Scene2D";
 import { type Color, type ElementStyle, type UIElementBase } from "./UINode";
 export type UIImageStyle = ElementStyle & {
     borderRadius?: number;
@@ -13,12 +14,21 @@ export type UIImageStyle = ElementStyle & {
 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;
-/** The stored/resolved image source (a Canvas is resolved to a surface marker). */
-export type ResolvedImageSource = string | FetchResponse | File | SvgSource | CanvasImageSource;
+/** 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;
+};
+/** 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;
+/** 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. */