lecodes-sdk 2.8.0 → 2.8.2

package/dist/global.d.ts

@@ -248,6 +248,7 @@ declare global {
   const tileOriented: typeof SDK.tileOriented
   const tileTurns: typeof SDK.tileTurns
   const toast: typeof SDK.toast
+  const trackGesture: typeof SDK.trackGesture
   const use: typeof SDK.use
   type ARError = SDK.ARError
   type ARErrorCode = SDK.ARErrorCode
@@ -378,6 +379,9 @@ declare global {
   type GeoPosition = SDK.GeoPosition
   type GeoWatch = SDK.GeoWatch
   type Geometry = SDK.Geometry
+  type Gesture = SDK.Gesture
+  type GestureHandler = SDK.GestureHandler
+  type GestureTarget = SDK.GestureTarget
   type GizmoAnchor = SDK.GizmoAnchor
   type GizmoStyle = SDK.GizmoStyle
   type HapticStyle = SDK.HapticStyle

package/dist/types/core/Aspect.d.ts

@@ -78,6 +78,13 @@ export declare abstract class Aspect<K extends string, P = Node, E extends Event
     static after?: Function[];
     /** Tick BEFORE these classes within the same phase (`static before = [Camera]`). */
     static before?: Function[];
+    /** DATA ONLY. A `use(...)` of this aspect in a scene file leaves its node STATIC for the level cache (gl/Statics.ts):
+     *  the engine builds the node without a JS object, and the aspect is attached the first time a hit, a contact or
+     *  a pick reaches the node — `hit.node.get(Surface)` answers then. So: fields and the methods the game calls on a
+     *  hit (a tag like `Surface { kind }`, a breakable's hit points), no `update()` (`use()` refuses one) and nothing in
+     *  `onAttach()` the level needs from its first frame. Without it a custom aspect keeps its node on the JS path,
+     *  built at load like any mover. */
+    static passive?: boolean;
     /** Every live instance of an aspect/system class, in attach order — the registry a game used to
      *  hand-roll as `static all[]`. Live, read-only: copy it (`[...Aspect.all(Barrel)]`) before a loop
      *  that detaches. Empty in the scene editor (aspects are inert data there). */

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

@@ -3,6 +3,7 @@ import { Model, type FoliageKind } from "./Model";
 import { Node } from "./Node";
 import { Scene } from "./Scene";
 import type { SceneDef, SceneNodeDef } from "../scene/defineScene";
+import type { AspectEntry } from "../scene/grammar";
 import type { BakeData } from "./Lightmap";
 import { type Digest } from "./staticsFormat";
 export { bakeDigest, type Digest } from "./staticsFormat";
@@ -17,6 +18,16 @@ export type CoveredRoot = {
     path: string;
     def: SceneNodeDef;
 };
+/** A passive aspect (Aspect.passive): data the engine does not need — attached to the placement's wrapper on the
+ *  first hit (`attachPassive`), never built at load. */
+export declare const isPassive: (e: AspectEntry<any>) => boolean;
+/** Attach the passive aspects of `def` to `node` (props as written: a passive aspect is data, `ref()`s are not
+ *  resolved). Who gets them: the entity a hit comes back with. A placement's clone, on the first hit, through
+ *  `lazyPlacements` — a covered root with a model included, since its clone is what the ray strikes, not the plain
+ *  JS node the clone hangs under. A root WITHOUT a model (a group tagged `Surface` over its walls) has no clone:
+ *  its JS node takes them at load, and a hit on a wall under it finds them one `parent` up (a game's surface lookup
+ *  walks `hit.node.parent`). */
+export declare const attachPassive: (node: Node, def: SceneNodeDef) => void;
 /** The maximal cacheable subtrees among `defs`, depth first: through `children`, and through a prefab's nodes
  *  (paths run through the prefab's path, as the bake's keys do). */
 export declare const coveredRoots: (defs: Record<string, SceneNodeDef> | undefined, scene: SceneDef) => CoveredRoot[];
@@ -53,4 +64,4 @@ export declare const open: (url: string, defs: Digest, bake: Digest) => Promise<
  *  templates load through `template` (one per kind, as the level's slow path would load them), the engine clones
  *  each at its placements as it resolves. `pages` = the bake's light/aux texture ids interleaved (empty = no bake
  *  bound). Resolves to the placements made. */
-export declare const build: (opened: OpenedCache, scene: Scene, roots: Node[], pages: Uint32Array, template: (url: string, lightmap: boolean, foliage: FoliageKind) => Promise<Model>) => Promise<number>;
+export declare const build: (opened: OpenedCache, scene: Scene, roots: Node[], pages: Uint32Array, template: (url: string, lightmap: boolean, foliage: FoliageKind) => Promise<Model>, covered: CoveredRoot[], def: SceneDef) => Promise<number>;

package/dist/types/gl/physics/CharacterController.d.ts

@@ -47,13 +47,18 @@ export declare class CharacterController extends Aspect<"controller", Node> impl
      * True while a requested collider resize hasn't taken — you asked to stand up and there is something
      * overhead. Resizing goes through the `Shape` aspect itself:
      *
-     *     hero.aspect(Shape, { capsule: CROUCHED })   // always fits — you are shrinking
-     *     hero.aspect(Shape, { capsule: STANDING })   // may be refused under a low ceiling
-     *     if (hero.controller.resizing) …             // still crouched; call it again next frame
+     *     hero.shape.capsule = CROUCHED               // always fits — you are shrinking
+     *     hero.shape.capsule = STANDING               // may be refused under a low ceiling
+     *     if (hero.controller.resizing) …             // still crouched; write it again next frame
      *
      * A refusal changes nothing, so the retry is just the same call again — and it is an exact headroom
      * test against the real capsule, unlike a hand-rolled raycast (a ray is a line; a capsule has girth).
-     * The FEET stay planted across a resize, so the character neither hovers nor sinks.
+     * The FEET stay planted across a resize, so the character neither hovers nor sinks — which means the
+     * node (the capsule's centre) has ALREADY moved by the feet difference when the write returns. Place
+     * a first-person camera from the feet (`node.y − (halfHeight + radius)` of the capsule worn) plus an
+     * eased eye height; placed from the node it pops by that difference. Write the property: a second
+     * `node.aspect(Shape, …)` builds a fresh Shape (it is handed to the character too, but it is a
+     * rebuild per stance, not a resize).
      */
     get resizing(): boolean;
     /** True while standing on walkable ground. */

package/dist/types/gl/physics/Physics.d.ts

@@ -87,6 +87,12 @@ export declare class Physics extends Aspect<"physics", Node> implements CompWrit
     /** Whether this host has 3D physics (an engine built with CREATOR_GL_PHYSICS). False, never a
      *  throw, where there is no 3D engine at all. */
     static get supported(): boolean;
-    /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. */
+    /** The motion of the body on `node`, read off the engine: it answers for a body the SDK never made (a static the
+     *  level cache built, which has no `Physics` aspect until a hit reaches it, and no body-making one ever). null = no
+     *  body on this node. The way to tell a wall from a prop on a hit: `Physics.motionOf(hit.node) === "static"`. */
+    static motionOf(node: Node | null): MotionType | null;
+    /** Closest pickable body hit by the ray from `origin` along `dir` (up to `maxDist`), or null. `node` is the body's
+     *  node — for a static the level cache built, a wrapper made on this hit (Node.ts nodeOf), carrying the placement's
+     *  passive aspects; its `Physics` is read with `Physics.motionOf`. */
     static raycast(origin: Vec3Like, dir: Vec3Like, maxDist?: number): RayHit | null;
 }

package/dist/types/gl/physics/Shape.d.ts

@@ -138,6 +138,10 @@ export declare class Shape extends Aspect<"shape", Node> {
     static fitBounds(bounds: ShapeBounds, scale: Vec3Like, kind?: ShapeKind): ShapeFit;
     private _createPickBody;
     private _rebuild;
+    /** The character this node belongs to tries the geometry on. Jolt validates the fit (standing up
+     *  under a pipe) and can refuse; a refusal changes nothing in the engine. The feet stay planted, so
+     *  on success the node has already moved by the change in the shape's lower bound when this returns. */
+    private _offerToCharacter;
     private _build;
     private _applyOrigin;
     private _signature;

package/dist/types/inject.d.ts

@@ -37,6 +37,7 @@ export { audio, type PlaySoundOptions, type SpatialOptions, type Rolloff, type A
 export { openFilePicker, files, type FileData } from "./runtime/files";
 export { share } from "./runtime/share";
 export { ClickEvent, TouchStartEvent, LongPressEvent, MouseEnterEvent } from "./runtime/touch";
+export { trackGesture, type Gesture, type GestureHandler, type GestureTarget } from "./runtime/gestures";
 export { Scene2D } from "./g2/Scene2D";
 export { Node2D } from "./g2/Node2D";
 export { Camera2D } from "./g2/Camera2D";

package/dist/types/plugin.d.ts

@@ -22,6 +22,7 @@ export { Vec2, Vec3, type Vec3Like } from "./math/vec";
 export { Quat, type QuatLike } from "./math/quat";
 export { Mat4 } from "./math/mat4";
 export type { ClickEvent, TouchStartEvent } from "./runtime/touch";
+export { trackGesture, type Gesture, type GestureHandler, type GestureTarget } from "./runtime/gestures";
 export type { DismissOptions } from "./ui/presentable";
 /** The seam the push plugin's wrapper installs its runtime on (src/runtime/pushSeam.ts): what the app's transport
  *  reads the device's address from, registers through, and a push channel's handlers are kept by. */

package/dist/types/plugins/gen/ar/sdk/ar.d.ts

@@ -44,6 +44,9 @@ export type ARSceneOptions = SceneOptions & {
     /** "world" (default): planes, hit tests, anchors, image and QR targets. "images": image and QR
      *  targets only — lighter on iOS; no planes, no hit test, no `root`. */
     mode?: ARMode;
+    /** How far in front of the user `root` is placed, metres (default 1): along the camera's heading,
+     *  on the floor. */
+    rootDistance?: number;
 };
 export type AROpenOptions = PresentOptions & Omit<StartOptions, "mode" | "images" | "codes"> & {
     /** The scene's ambient (its `environmentIntensity`) follows the estimated light; turns
@@ -128,6 +131,8 @@ export declare class ARScene extends Scene {
     /** Whether this host registered the "ar" service (the app lists the plugin, the host has a half). */
     static get isSupported(): boolean;
     readonly mode: ARMode;
+    /** Metres between the user and `root` when it is placed (`rootDistance` option, default 1). */
+    readonly rootDistance: number;
     /** `open()` warm-renders the scene first (default true). */
     useWarmRender: boolean;
     private _opening;
@@ -147,7 +152,8 @@ export declare class ARScene extends Scene {
     private _codesWarned;
     private _options;
     private _root;
-    /** The first horizontal plane's pose: where `root` is pinned. */
+    /** The floor's height (world Y, metres): the first horizontal plane below the camera this session
+     *  found. Null until one is; `root` is placed on it. */
     private _floor;
     /** The image targets. `source` is held for the bytes: a fetched response owns its buffer, which the
      *  host frees once the response is collected — the File the session is handed only names it. */
@@ -174,9 +180,17 @@ export declare class ARScene extends Scene {
     /** A grid drawn on every plane (each plane's child mesh). */
     get showPlanes(): boolean;
     set showPlanes(on: boolean);
-    /** The floor: an anchor pinned on the first horizontal plane the session finds (it fires `track`
-     *  then). Until that it is the world's origin — where the session began. Not in "images" mode. */
+    /** The place in front of the user: an anchor `rootDistance` metres ahead of the camera along its
+     *  heading, on the floor — the first horizontal plane below the camera the session finds; it is
+     *  pinned there and fires `track` then — turned the way the user looks (its −Z along the heading,
+     *  so a model's front, +Z, faces the user). Until the floor is found (and on the web, which finds
+     *  none) it sits the same way at the camera's own height, not pinned. Made on first use; put
+     *  content under it. `placeRoot()` puts it in front of the user again. Not in "images" mode. */
     get root(): Anchor;
+    /** Put `root` in front of the user again — where they look now, `rootDistance` metres ahead, on the
+     *  floor if one is known (the camera's height otherwise), facing them: a "reset" button, or a
+     *  placement after the user has moved. Makes `root` when there is none yet. */
+    placeRoot(): Anchor;
     /** An anchor that follows an image (a printed marker, a poster): the session finds it in the camera
      *  image and keeps the anchor on it — a rigid pose in metres (its centre, Y out of the image, the
      *  image in XZ), its size `anchor.extent`. `physicalWidth` = the printed width in metres. Hidden
@@ -244,8 +258,14 @@ export declare class ARScene extends Scene {
     private _wire;
     /** Pin `anchor` at `pose` (where it is until the session holds it) — now, or when a session starts. */
     private _place;
-    /** `root` onto the floor (the first horizontal plane of this session). */
-    private _pinRoot;
+    /** Where `root` goes now: `rootDistance` metres from the camera along its heading (its forward
+     *  flattened to the floor; looking straight down or up, the way the top of the screen points), at
+     *  the floor's height when one is known, else the camera's; turned so its −Z runs along the
+     *  heading — a model's front (+Z) faces the user. */
+    private _rootPose;
+    /** `root` in front of the user: moved there now, and pinned there when the floor is known (a
+     *  session holds a pin; without one `_pinAll` does not re-pin root — it waits for its own floor). */
+    private _placeRoot;
     private _pin;
     /** A session began: every pose anchor is pinned where it is. */
     private _pinAll;

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

@@ -0,0 +1,52 @@
+import type { TouchStartEvent, TrackHandler } from "./touch";
+/** One reading of a gesture, handed to `onStart` / `onMove` / `onEnd` (a fresh object each time). */
+export interface Gesture {
+    /** The centroid of the live fingers, in the event's client coordinates (logical px). */
+    centerX: number;
+    centerY: number;
+    /** The centroid's move since the previous `onMove` (0 on start / end). */
+    deltaX: number;
+    deltaY: number;
+    /** Mean finger distance to the centroid over the previous one (1 with one finger, 1 on start / end). */
+    scale: number;
+    /** The mean change of each finger's angle about the centroid since the previous `onMove`, radians,
+     *  positive = clockwise on screen (0 with one finger, 0 on start / end). */
+    rotation: number;
+    /** The number of live fingers (0 in `onEnd`: the last one lifted). */
+    pointers: number;
+}
+/** What `trackGesture` takes: the gesture's callbacks and the claim every finger's track makes. */
+export interface GestureHandler {
+    /** Passed to every finger's `ev.track(...)` (default `true`: a scrollable above never takes the pan). */
+    claim?: TrackHandler["claim"];
+    /** The first finger landed. */
+    onStart?(g: Gesture): void;
+    /** Any finger moved: the change since the previous `onMove`. */
+    onMove?(g: Gesture): void;
+    /** The last finger lifted. */
+    onEnd?(g: Gesture): void;
+    /** The host cancelled one of the fingers: the whole gesture is over. */
+    onCancel?(): void;
+}
+/** Anything that hands out touchstarts: a UI element (`onTouchStart`) or a scene / node
+ *  (`addEventListener("touchstart", …)`). */
+export type GestureTarget = {
+    onTouchStart(callback: (ev: TouchStartEvent<any>) => void): unknown;
+} | {
+    addEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<any>) => void): void;
+    removeEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<any>) => void): void;
+};
+/**
+ * Follow pan, pinch and twist on `target` as one gesture: every finger that lands on it is tracked,
+ * and `onMove` reports the change of the whole set since the previous move — the centroid's move,
+ * the spread's ratio, the twist's angle. One finger is a gesture too (a pan, scale 1, rotation 0).
+ *
+ * ```ts
+ * trackGesture(scene, {
+ *   onMove(g) { zoom *= g.scale; angle += g.rotation; panX += g.deltaX; panY += g.deltaY },
+ * })
+ * ```
+ */
+export declare const trackGesture: (target: GestureTarget, handler: GestureHandler) => {
+    remove(): void;
+};

package/dist/types/ui/UIModal.d.ts

@@ -28,9 +28,10 @@ export type UIModalShow = (() => boolean) | Signal<boolean>;
  * request, `onDismiss`. By default it hides an unbound modal and writes `false` into a bound
  * signal; a bound function has nowhere to write, so a modal bound to one without `onDismiss`
  * cannot be dismissed (a forced choice — the same as `dismissible(false)`). `display` is not a
- * modal's switch: a `.style({ display })` on it throws (a bound display died on the first
- * dismissal, which wrote a static `display: "none"` over the binding — the dialog never opened
- * again).
+ * modal's switch (a bound display died on the first dismissal, which wrote a static
+ * `display: "none"` over the binding — the dialog never opened again). Deprecated, for the
+ * transition period a `.style({ display })` is still accepted, with a warning: a function becomes
+ * `bindShow(() => fn() !== "none")`, a value a show() / hide(); it will throw again.
  */
 export interface UIModal extends UIWidget {
     /**
@@ -82,6 +83,7 @@ export declare class ModalElement extends WidgetElement {
     private _poseObj?;
     private _poseKey;
     constructor(style: UIModalStyle, children: UINodeChild[] | ChildrenFn);
+    private _bindDisplay;
     private _pose;
     transition(hidden: UIModalTransition): this;
     bindShow(value: UIModalShow): this;

package/dist/types/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "2.8.0";
+export declare const SDK_VERSION = "2.8.2";
 /** The major of a semver string, or null when it is not one. */
 export declare const sdkMajor: (version: string | null | undefined) => number | null;
 /** The `// sdk: <version>` line of a compiled bundle's header (sdk/src/compile/header.ts), read from