lecodes-sdk 2.2.9 → 2.2.10

package/dist/global.d.ts

@@ -6,11 +6,14 @@ import type * as SDK from "./types/inject"
 import type * as SERVER from "./types/server/inject"
 
 declare global {
+  const ARPlane: typeof SDK.ARPlane
   const ARScene: typeof SDK.ARScene
+  const Anchor: typeof SDK.Anchor
   const AnimationClip: typeof SDK.AnimationClip
   const Animator: typeof SDK.Animator
   const Aspect: typeof SDK.Aspect
   const AudioPlayer: typeof SDK.AudioPlayer
+  const AudioRecorder: typeof SDK.AudioRecorder
   const AudioSource: typeof SDK.AudioSource
   const AudioZone: typeof SDK.AudioZone
   const Autotile2D: typeof SDK.Autotile2D
@@ -41,6 +44,7 @@ declare global {
   const Geometry: typeof SDK.Geometry
   const Gizmos: typeof SDK.Gizmos
   const IK: typeof SDK.IK
+  const ImageAnchor: typeof SDK.ImageAnchor
   const Input: typeof SDK.Input
   const InputChannel: typeof SDK.InputChannel
   const InspectorUI: typeof SDK.InspectorUI
@@ -110,6 +114,7 @@ declare global {
   const Shape: typeof SDK.Shape
   const Shape2D: typeof SDK.Shape2D
   const Sound: typeof SDK.Sound
+  const SpeechRecognizer: typeof SDK.SpeechRecognizer
   const Spin: typeof SDK.Spin
   const Sprite: typeof SDK.Sprite
   const SpriteAnimation: typeof SDK.SpriteAnimation
@@ -208,6 +213,7 @@ declare global {
   const openFilePicker: typeof SDK.openFilePicker
   const openURL: typeof SDK.openURL
   const packTile: typeof SDK.packTile
+  const permissions: typeof SDK.permissions
   const rawCell: typeof SDK.rawCell
   const rawIndex: typeof SDK.rawIndex
   const ref: typeof SDK.ref
@@ -228,10 +234,31 @@ declare global {
   const tileTurns: typeof SDK.tileTurns
   const toast: typeof SDK.toast
   const use: typeof SDK.use
-  type ARScene<T extends ARMode = "default"> = SDK.ARScene<T>
+  type ARError = SDK.ARError
+  type ARErrorCode = SDK.ARErrorCode
+  type ARHitResult = SDK.ARHitResult
+  type ARHitTarget = SDK.ARHitTarget
+  type ARLightEstimate = SDK.ARLightEstimate
+  type ARMode = SDK.ARMode
+  type AROpenOptions = SDK.AROpenOptions
+  type ARPlane = SDK.ARPlane
+  type ARPlaneChange = SDK.ARPlaneChange
+  type ARPlaneDetection = SDK.ARPlaneDetection
+  type ARPlaneEvent = SDK.ARPlaneEvent
+  type ARPlaneType = SDK.ARPlaneType
+  type ARPose = SDK.ARPose
+  type ARPoseLike = SDK.ARPoseLike
+  type ARScene = SDK.ARScene
+  type ARSceneEvents = SDK.ARSceneEvents
+  type ARSceneOptions = SDK.ARSceneOptions
+  type ARTrackingReason = SDK.ARTrackingReason
+  type ARTrackingState = SDK.ARTrackingState
+  type ARWorldAlignment = SDK.ARWorldAlignment
   type Action<A extends unknown[], R> = SDK.Action<A, R>
   type ActiveClip = SDK.ActiveClip
   type AeroConfig = SDK.AeroConfig
+  type Anchor = SDK.Anchor
+  type AnchorEvents = SDK.AnchorEvents
   type AnimateOptions<T extends AnimateValue> = SDK.AnimateOptions<T>
   type AnimateOut<T> = SDK.AnimateOut<T>
   type AnimateValue = SDK.AnimateValue
@@ -243,6 +270,8 @@ declare global {
   type AspectEntry<A extends Aspect<any, any> = Aspect<any, any>> = SDK.AspectEntry<A>
   type AudioCone = SDK.AudioCone
   type AudioPlayer = SDK.AudioPlayer
+  type AudioRecorder = SDK.AudioRecorder
+  type AudioRecorderEvents = SDK.AudioRecorderEvents
   type AudioSource = SDK.AudioSource
   type AudioStats = SDK.AudioStats
   type AudioZone = SDK.AudioZone
@@ -305,6 +334,7 @@ declare global {
   type EditorRayHit = SDK.EditorRayHit
   type EditorToolHooks = SDK.EditorToolHooks
   type EditorWindowFn = SDK.EditorWindowFn
+  type EndReason = SDK.EndReason
   type EngineConfig = SDK.EngineConfig
   type EventMap = SDK.EventMap
   type Failure = SDK.Failure
@@ -333,6 +363,7 @@ declare global {
   type HapticStyle = SDK.HapticStyle
   type IKLookAt = SDK.IKLookAt
   type IKTwoBone = SDK.IKTwoBone
+  type ImageAnchor = SDK.ImageAnchor
   type InputEventName = SDK.InputEventName
   type InputGamepadEvent = SDK.InputGamepadEvent
   type InputKeyEvent = SDK.InputKeyEvent
@@ -434,6 +465,8 @@ declare global {
   type PatchMaterial = SDK.PatchMaterial
   type PatchSlots = SDK.PatchSlots
   type PathMaterial = SDK.PathMaterial
+  type PermissionKind = SDK.PermissionKind
+  type PermissionState = SDK.PermissionState
   type Physics = SDK.Physics
   type Physics2D = SDK.Physics2D
   type PhysicsGroup2D = SDK.PhysicsGroup2D
@@ -478,6 +511,9 @@ declare global {
   type RagdollHitOptions = SDK.RagdollHitOptions
   type RagdollPart = SDK.RagdollPart
   type Ray = SDK.Ray
+  type RecordOptions = SDK.RecordOptions
+  type RecorderState = SDK.RecorderState
+  type Recording = SDK.Recording
   type Replicated = SDK.Replicated
   type Resource<T> = SDK.Resource<T>
   type ReverbParams = SDK.ReverbParams
@@ -506,6 +542,11 @@ declare global {
   type Sound = SDK.Sound
   type SoundOptions = SDK.SoundOptions
   type SpatialOptions = SDK.SpatialOptions
+  type SpeechErrorCode = SDK.SpeechErrorCode
+  type SpeechOptions = SDK.SpeechOptions
+  type SpeechRecognizer = SDK.SpeechRecognizer
+  type SpeechRecognizerEvents = SDK.SpeechRecognizerEvents
+  type SpeechResult = SDK.SpeechResult
   type Spin = SDK.Spin
   type Sprite = SDK.Sprite
   type SpriteAnimation = SDK.SpriteAnimation

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

@@ -85,9 +85,12 @@ export declare class Camera extends Node {
         node: Node;
         applyTo(camera: Camera): void;
     } | null): this;
+    /** The scene view's [width, height] in logical units — the units of the scene's touches
+     *  (`clientX` / `clientY`) and of `getRay`, on every host; × `device.pixelRatio` for device px.
+     *  [0, 0] before the scene has a viewport. */
     get displaySize(): [number, number];
-    /** World-space ray direction through a screen pixel. */
+    /** World-space ray direction through a point of the scene view (logical units, as a touch's). */
     getViewDirection(screenX: number, screenY: number): Vec3;
-    /** A pick ray from the camera through a screen pixel. */
+    /** A pick ray from the camera through a point of the scene view (logical units, as a touch's). */
     getRay(screenX: number, screenY: number): Ray;
 }

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

@@ -20,10 +20,6 @@ export type NodeTweenProps = {
 export type NodeEvents = {
     click: (ev: ClickEvent<Node | null>) => void;
     touchstart: (ev: TouchStartEvent<Node | null>) => void;
-    /** AR anchors only (`scene.root` / `scene.createAnchor()`): the anchor began tracking. */
-    track: () => void;
-    /** AR anchors only: the anchor lost tracking. */
-    untrack: () => void;
     /** A physics contact/trigger overlap began (the other body's node). Needs a Shape + Physics/Trigger. */
     enter: (other: Node) => void;
     /** A physics contact/trigger overlap ended. */
@@ -32,9 +28,6 @@ export type NodeEvents = {
 export declare class Node extends AspectHost<NodeEvents> implements CompWriter {
     /** Native entity id. */
     get id(): number;
-    /** AR anchors only — whether the anchor is currently being tracked. Kept in step with the
-     *  'track' / 'untrack' events; `false` for any non-anchor node. */
-    isTracked: boolean;
     private _matrix?;
     private _worldMatrix?;
     private _boneCache?;

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

@@ -2,11 +2,10 @@ import { type ColorInput } from "../core/color";
 import { type Aspect, type AspectCtor, type FieldOf, type TargetOf } from "../core/Aspect";
 import { Presentable, type DismissOptions, type PresentOptions } from "../ui/presentable";
 import { type WidgetSet } from "../ui/UILayer";
+import { File } from "../runtime/fetch";
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch";
-import type { FetchResponse } from "../runtime/fetch";
 import { Camera } from "./Camera";
 import { SceneAudio } from "./audio/SceneAudio";
-import { type ControlsHandle, type ControlsOptions } from "./controls";
 import { Material } from "./Material";
 import { PostProcessing, type PostProcessingOptions } from "./postProcessing";
 import { Node } from "./Node";
@@ -214,6 +213,11 @@ export declare class Scene implements Presentable {
     destroy(): void;
     createOverlay(options?: SceneOptions): Scene;
     warmRender(): Promise<void>;
+    /** The scene's picture as a PNG `File`: the composite of its next frame — the scene, its overlays
+     *  and its background (an AR scene's camera image), not the UI over them — encoded by the host
+     *  (a share, an upload, a `UIImage` source). Rejects when the scene is not the one on screen, or
+     *  something else is shown before the frame. */
+    capture(): Promise<File>;
     /** Precompile the scene's shader variants so nothing is compiled mid-game. Every material the host
      *  knows is queued for the sun / shadow / fog / skinning variants and the dynamic-light key — the
      *  first point light (a muzzle flash, an explosion) would otherwise rebuild every lit shader in view
@@ -246,28 +250,6 @@ export declare class Scene implements Presentable {
     addEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<Node | null>) => void): void;
     removeEventListener(channel: "click" | "touchstart", callback: (ev: any) => void): void;
 }
-export type ARMode = "default" | "markers" | "arcore" | "detached";
-export declare class ARScene<T extends ARMode = "default"> extends Scene {
-    readonly mode: T;
-    useWarmRender: boolean;
-    private _root?;
-    constructor(options?: SceneOptions & {
-        mode?: T;
-    });
-    /** Root anchor node (not available in marker mode). */
-    get root(): Node;
-    /** Create an anchor from a tracking source (e.g. an image target). */
-    createAnchor(source: FetchResponse, physicalWidth?: number): Node;
-    /**
-     * Let the user place & manipulate a node with touch gestures — the staple AR object-placement
-     * interaction: ONE finger drags it across the floor (relative to where the camera looks), TWO fingers
-     * pinch to scale and twist to rotate. Returns a handle; call `.remove()` to detach. Tunable via
-     * options (min/max scale, and toggles for `pan` / `pinch` / `twist`).
-     */
-    addControls(target: Node, options?: ControlsOptions): ControlsHandle;
-    open(options?: PresentOptions): Promise<void>;
-    close(options?: DismissOptions): void;
-}
 /**
  * A 3D scene rendered in a VR headset (OpenXR — e.g. Meta Quest). The headset drives the camera:
  * every frame both eyes are rendered from the tracked head pose, so `scene.camera` position/lookAt

package/dist/types/inject.d.ts

@@ -14,6 +14,7 @@ export { Canvas, Bitmap } from "./canvas/Canvas";
 export { toast, openURL, SvgSource } from "./runtime/misc";
 export { app, type AppState, type OrientationLock } from "./runtime/app";
 export { clipboard } from "./runtime/clipboard";
+export { permissions, type PermissionKind, type PermissionState } from "./runtime/permissions";
 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";
@@ -71,6 +72,9 @@ export { easeIn, easeOut, easeInOut } from "./animate/easings";
 export { QRScanner } from "./plugins/gen/qr-scanner/sdk/qr-scanner";
 export { CameraView, type CameraFacing } from "./plugins/gen/camera/sdk/camera";
 export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/gen/geolocation/sdk/geolocation";
+export { ARScene, Anchor, ImageAnchor, ARPlane, type ARSceneOptions, type AROpenOptions, type ARSceneEvents, type AnchorEvents, type ARPose, type ARPoseLike, type ARHitResult, type ARLightEstimate, type ARError, type ARErrorCode, type ARPlaneEvent, type ARMode, type HitTarget as ARHitTarget, type PlaneDetection as ARPlaneDetection, type PlaneType as ARPlaneType, type PlaneChange as ARPlaneChange, type TrackingState as ARTrackingState, type TrackingReason as ARTrackingReason, type WorldAlignment as ARWorldAlignment, } from "./plugins/gen/ar/sdk/ar";
+export { AudioRecorder, type AudioRecorderEvents, type RecorderState, type RecordOptions, type Recording, type EndReason } from "./plugins/gen/audio-recorder/sdk/audio-recorder";
+export { SpeechRecognizer, type SpeechRecognizerEvents, type SpeechOptions, type SpeechResult, type SpeechErrorCode } from "./plugins/gen/speech/sdk/speech";
 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/gen/map/sdk/map";
 export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/gen/push/sdk/push";
 export { Browser, WebView, type BrowserOpenOptions, type WebViewParams, type WebViewEvents } from "./plugins/gen/browser/sdk/browser";
@@ -89,7 +93,7 @@ export type { GizmoStyle, GizmoAnchor } from "./scene/gizmos";
 export { MoveTo, FollowPath, Spin, LookAt, PlayAnimation } from "./gl/scenarios";
 export { registerEditorWindow, registerEditorTool } from "./scene/editorPlugins";
 export type { EditorApi, EditorRayHit, EditorToolHooks, EditorWindowFn } from "./scene/editorPlugins";
-export { Scene, ARScene, VRScene } from "./gl/Scene";
+export { Scene, VRScene } from "./gl/Scene";
 export { Node } from "./gl/Node";
 export { Mesh } from "./gl/Mesh";
 export { Model } from "./gl/Model";

package/dist/types/plugin.d.ts

@@ -1,11 +1,28 @@
 import { File as HostFile } from "./runtime/fetch";
 import { ServiceClient } from "./runtime/service";
 import { NativeViewElement } from "./ui/NativeView";
+import { _navEpoch } from "./ui/presentable";
+import { _ensurePermission } from "./runtime/permissions";
+export { permissions, type PermissionKind, type PermissionState } from "./runtime/permissions";
+import { type Node } from "./gl/Node";
+import type { Scene } from "./gl/Scene";
 export type { PresentOptions } from "./ui/presentable";
 export { Presentable, Router, UIBox, UIButton, UIColumn, UIRow, UIScreen, UIText } from "./ui/UI";
 export { theme } from "./ui/theme";
+export { Emitter } from "./core/events";
 export type { NativeView } from "./ui/NativeView";
 export type { FetchResponse } from "./runtime/fetch";
+export { Scene, type SceneOptions } from "./gl/Scene";
+export { System } from "./core/Aspect";
+export { Node, type NodeEvents } from "./gl/Node";
+export { Mesh } from "./gl/Mesh";
+export { Geometry } from "./gl/Geometry";
+export { Material } from "./gl/Material";
+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 type { DismissOptions } from "./ui/presentable";
 /** Signed 32-bit integer on the wire. */
 export type i32 = number;
 /** Double on the wire — also every integer that can leave 32 bits (a millisecond time stamp). */
@@ -14,6 +31,15 @@ export type f64 = number;
  *  app gets the SDK's `File` handle (a texture source, a `FormData` value, a share) and the bytes
  *  never enter the JS heap. For bytes the app must read itself, a contract says `Uint8Array`. */
 export type File = HostFile;
+/** A 3D node of the app (`Node`) a plugin drives — an AR anchor, the camera: its entity id on the
+ *  wire (u32, `node._h.id`); the native half receives `Entity` (a struct over the id) and moves it
+ *  through the host's gl facade (`engine.gl` / `host.gl`), never creating or freeing it. One the half
+ *  names back (an event's) is the app's own Node again. */
+export type Entity = Node;
+/** A 3D scene of the app (`Scene`) a plugin drives — its camera's projection, its background: the
+ *  scene id on the wire (`scene._id`); the native half receives `Scene3D`. From the app to the host
+ *  only: a half never names a scene back. */
+export type Scene3D = Scene;
 /** Any JSON value, opaque to the generator (GeoJSON, a developer's own payload): it crosses as is
  *  and the native half receives the platform's untyped value. */
 export type Json = null | boolean | number | string | Json[] | {
@@ -69,6 +95,7 @@ export declare class ServiceChannel<Events extends object = {}> extends ServiceC
     on<K extends keyof Events & string>(event: K, callback: Listener<Events, K>): this;
     off<K extends keyof Events & string>(event: K, callback: Listener<Events, K>): this;
 }
+export declare const _fromScene3D: (scene: Scene3D) => number;
 /** Hear the app's "url" events (a deep link while the app runs — an OAuth redirect, a checkout's
  *  return) until the returned function is called. The listener the `app` global fans out from. */
 export declare const _onAppUrl: (callback: (url: string) => void) => (() => void);

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

@@ -0,0 +1,228 @@
+import { Node, Quat, Scene, Vec3, type ClickEvent, type DismissOptions, type FetchResponse, type File, type NodeEvents, type PresentOptions, type QuatLike, type SceneOptions, type TouchStartEvent, type Vec3Like } from "../../../../plugin";
+import { type ControlsHandle, type ControlsOptions } from "./controls";
+import type { ARErrorCode, ARMode, HitTarget, PlaneChange, PlaneDetection, PlaneType, StartOptions, TrackingReason, TrackingState, WorldAlignment } from "../contract";
+export type { ARErrorCode, ARMode, ControlsHandle, ControlsOptions, HitTarget, PlaneChange, PlaneDetection, PlaneType, TrackingReason, TrackingState, WorldAlignment, };
+/** A pose in the scene's world: metres, Y up. */
+export type ARPose = {
+    position: Vec3;
+    rotation: Quat;
+};
+/** A pose as `scene.anchor()` takes it. */
+export type ARPoseLike = {
+    position: Vec3Like;
+    rotation: QuatLike;
+};
+/** What `scene.hitTest()` finds under a point, nearest first. */
+export type ARHitResult = {
+    pose: ARPose;
+    /** "plane": on a detected plane (`plane`); "estimated": on a point of the feature cloud or an
+     *  estimated surface. */
+    type: "plane" | "estimated";
+    plane: ARPlane | null;
+    /** Metres from the camera. */
+    distance: number;
+};
+/** The estimated light (`lightEstimation`): an ambient intensity (1000 = neutral) and a colour
+ *  temperature in kelvin. */
+export type ARLightEstimate = {
+    intensity: number;
+    temperature: number;
+};
+/** The session failed and is over: "unavailable" (no ARKit / ARCore, ARCore declined), "camera",
+ *  "failed". */
+export type ARError = {
+    code: ARErrorCode;
+    message: string;
+};
+/** A plane found, moved or grown, or gone (`mergedInto`: the plane that absorbed it). */
+export type ARPlaneEvent = {
+    plane: ARPlane;
+    change: PlaneChange;
+    mergedInto: ARPlane | null;
+};
+export type ARSceneOptions = SceneOptions & {
+    /** "world" (default): planes, hit tests, anchors, image targets. "images": image targets only —
+     *  lighter on iOS; no planes, no hit test, no `root`. */
+    mode?: ARMode;
+};
+export type AROpenOptions = PresentOptions & Omit<StartOptions, "mode" | "images"> & {
+    /** The scene's ambient (its `environmentIntensity`) follows the estimated light; turns
+     *  `lightEstimation` on. */
+    followLight?: boolean;
+};
+export type ARSceneEvents = {
+    tracking: (state: TrackingState, reason: TrackingReason | null) => void;
+    plane: (event: ARPlaneEvent) => void;
+    light: (estimate: ARLightEstimate) => void;
+    error: (error: ARError) => void;
+};
+export type AnchorEvents = NodeEvents & {
+    /** The anchor began tracking: found, placed, or regained after a relocalization. */
+    track: () => void;
+    /** The anchor lost tracking: it stays where it was last seen. */
+    untrack: () => void;
+};
+/**
+ * A node the AR session drives: it follows a place in the room (`scene.anchor(pose)`, `scene.root`)
+ * or an image (`scene.createAnchor(image)`). Put content under it. `tracked` says whether the session
+ * holds it now; `track` / `untrack` fire when that changes.
+ */
+export declare class Anchor extends Node {
+    /** Whether the session holds the anchor now (it moves with what it follows). */
+    get tracked(): boolean;
+    addEventListener<K extends keyof AnchorEvents>(channel: K, callback: AnchorEvents[K]): void;
+    removeEventListener<K extends keyof AnchorEvents>(channel: K, callback: AnchorEvents[K]): void;
+    /** Stop following: the session lets it go (it stays where it was) and it leaves the scene. */
+    remove(): void;
+}
+/**
+ * An anchor that follows an image (`scene.createAnchor(image, physicalWidth)`): while tracked it sits on
+ * the image — a rigid pose in metres, no scale: its centre, Y out of the image, the image in X (its
+ * width) and Z (towards its bottom). How big the image is, is `extent`.
+ */
+export declare class ImageAnchor extends Anchor {
+    constructor(physicalWidth: number);
+    /** [width, height] in metres, along the anchor's X and Z: the session's estimate of the printed
+     *  image, refined while it tracks it. Before the image is first found: [physicalWidth, 0] — the
+     *  height comes with the image's proportions, which the session reads, at the first `track`. */
+    get extent(): [number, number];
+}
+/** A surface the session found: a floor, a table, a wall. Its node sits at the plane's centre with Y
+ *  along its normal; `extent` and `polygon` are in that space. */
+export declare class ARPlane extends Anchor {
+    /** The session's id of the plane (`ARHitResult.plane`, `mergedInto`). */
+    readonly planeId: number;
+    constructor(planeId: number);
+    get type(): PlaneType;
+    /** [width, depth] in metres, along the plane's X and Z. */
+    get extent(): [number, number];
+    /** The boundary as x, z pairs in the plane's space (metres). */
+    get polygon(): readonly number[];
+    /** The plane's centre in the world. */
+    get center(): Vec3;
+}
+/**
+ * A 3D scene over the device camera with world tracking: the session (the "ar" plugin) moves
+ * `scene.camera` and draws the camera image behind everything, every frame. Everything of `Scene`
+ * applies. `ARScene.isSupported` says whether this host has the plugin.
+ *
+ * ```ts
+ * const scene = new ARScene()
+ * scene.root.add(await Model.load(asset('./chair.glb')))
+ * await scene.open()          // camera permission → warm render → session → on screen, drawn
+ * ```
+ */
+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;
+    /** `open()` warm-renders the scene first (default true). */
+    useWarmRender: boolean;
+    private _opening;
+    /** The wait of `open()` / `Router.push` for the presented scene's first frame (`_presented`), and
+     *  the navigation epoch of its present. */
+    private _shown;
+    /** The open's start while it is out (`_begin`). `closed`: close() ended its session meanwhile — the
+     *  half refuses a start its close cut short ("failed"), which is the close's doing: the open was
+     *  superseded, not failed. `images`: the image targets changed meanwhile, which the start did not
+     *  carry (it read them when it was sent) — the set goes to the session once it runs. */
+    private _startOut;
+    /** A `setImages` is due at the end of this turn (`_setImages`). */
+    private _imagesDue;
+    private _options;
+    private _root;
+    /** The first horizontal plane's pose: where `root` is pinned. */
+    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. */
+    private readonly _images;
+    /** The pose anchors: pinned again where they are when a session starts. (`root` is not one: a
+     *  session pins it on its own first floor.) */
+    private readonly _pinned;
+    private readonly _planes;
+    private _trackingState;
+    private _trackingReason;
+    private _light;
+    private _showPlanes;
+    private _baseIntensity;
+    private readonly _arListeners;
+    constructor(options?: ARSceneOptions);
+    /** The tracking quality: "notAvailable" before a session, "limited" (with `trackingReason`) while
+     *  it settles or struggles, "normal". */
+    get trackingState(): TrackingState;
+    get trackingReason(): TrackingReason | null;
+    /** The planes the session holds now. */
+    get planes(): ARPlane[];
+    /** The latest light estimate (`lightEstimation`), null before one. */
+    get lightEstimate(): ARLightEstimate | null;
+    /** 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. */
+    get root(): 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
+     *  while not tracked. Before `open()`, or any time: on a running scene the image set is updated in
+     *  place — the tracking, the planes and the anchors stay. */
+    createAnchor(source: FetchResponse | File, physicalWidth?: number): ImageAnchor;
+    /** An anchor at `pose` (a hit test's, say): the session keeps it where it is in the room as its
+     *  map of the world improves. `anchor.remove()` lets it go. */
+    anchor(pose: ARPoseLike): Anchor;
+    /** What is under a point of the scene's view, nearest first — the point as the scene's touches
+     *  give it (`ev.clientX` / `ev.clientY` of a `click` or a `touchstart`); empty when nothing is — and
+     *  always on the web, which finds no surfaces. Rejects without a running session. */
+    hitTest(x: number, y: number, target?: HitTarget): Promise<ARHitResult[]>;
+    /** The latest camera image as a JPEG `File` (the camera's alone; `capture()` is the composite).
+     *  Rejects without a running session. */
+    captureFrame(): Promise<File>;
+    /**
+     * Let the user place & manipulate a node with touch gestures — the staple AR object-placement
+     * interaction: ONE finger drags it over what the session finds under the finger (a plane), or across
+     * the ground where it finds nothing; TWO fingers pinch to scale and twist to rotate. Returns a
+     * handle; `.remove()` detaches. Tunable via options (min/max scale, `pan` / `pinch` / `twist`).
+     */
+    addControls(target: Node, options?: ControlsOptions): ControlsHandle;
+    /** Camera permission → warm render → the session → on screen, resolved at the scene's first frame:
+     *  after `await scene.open()` the scene is shown, `camera.displaySize` is its view's size, and
+     *  `hitTest` / `captureFrame` answer. The current destination (a loading screen) stays until the
+     *  session runs; rejects — and leaves it — when the camera is denied, AR is unavailable
+     *  ("unavailable": no ARKit / ARCore), or another navigation came meanwhile; one that comes before
+     *  the first frame (a `close()` too) rejects it as superseded. */
+    open(options?: AROpenOptions): Promise<void>;
+    private _settleShown;
+    /** Close the scene; its session stops (the camera is let go). An `open()` still waiting — for the
+     *  session's start or the first frame — rejects as superseded. */
+    close(options?: DismissOptions): void;
+    addEventListener(channel: "click", callback: (ev: ClickEvent<Node | null>) => void): void;
+    addEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<Node | null>) => void): void;
+    addEventListener<K extends keyof ARSceneEvents>(channel: K, callback: ARSceneEvents[K]): void;
+    removeEventListener(channel: "click" | "touchstart" | keyof ARSceneEvents, callback: (...args: any[]) => void): void;
+    private _emit;
+    private _startOptions;
+    private _targets;
+    private _begin;
+    /** The session is over (closed, failed): every anchor untracked, the planes gone. */
+    private _drop;
+    private _end;
+    private _lost;
+    /** The image targets changed (one added or removed): a running session takes the whole set in place
+     *  (`setImages` — the tracking, the planes and the anchors stay). Sent at the end of the turn: several
+     *  targets added in a row are one set. While the open's start is out it waits for it (the start
+     *  carried the set it read when it was sent); before a session there is nothing to tell — the start
+     *  carries the set. Nothing waits for it: a set the half refuses is a console line, and an anchor
+     *  whose image the session did not take never tracks. */
+    private _setImages;
+    /** A wire call to the running session; rejects without one. */
+    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;
+    private _pin;
+    /** A session began: every pose anchor is pinned where it is. */
+    private _pinAll;
+    private _onPlane;
+    private _drawPlane;
+}

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

@@ -0,0 +1,73 @@
+import { ServiceChannel, type Entity, type EventReaders, type File } from "../../../../plugin";
+import type { AREvents, ARParams, HitResult, HitTarget, ImageTarget, Pose, StartOptions } from "../contract";
+/** What the halves register under. */
+export declare const NAME = "ar";
+/** The contract's version: the highest `@since` of its members. */
+export declare const VERSION = 1;
+/** The events whose payload holds a File: read before a listener sees it. */
+export declare const READERS: EventReaders;
+/** Start tracking; resolves at the first frame. A second start rejects "busy".
+ *  Needs the "camera" permission: the host asks before the call, "denied" when refused.
+ *  Rejects with "denied" / "busy" / "unavailable" / "failed". */
+export declare const start: (service: ServiceChannel<AREvents>, options?: StartOptions) => Promise<void>;
+/** Stop tracking: the camera is released, the scene's projection and background cleared. Not
+ *  running is not an error. */
+export declare const stop: (service: ServiceChannel<AREvents>) => Promise<void>;
+/** Replace the set of image targets of a RUNNING session without restarting it (the tracking, the
+ *  planes and the anchors stay); an image no longer in the set stops driving its entity (its
+ *  `image` event says `tracked: false` once if it was tracked). Before `start`, the images are
+ *  `StartOptions.images`.
+ *  Rejects with "notRunning" / "failed". */
+export declare const setImages: (service: ServiceChannel<AREvents>, images: ImageTarget[]) => Promise<void>;
+/** What is under a point of the scene's view — in its touches' space (a scene touch's `clientX` /
+ *  `clientY`: the units of the gl facade's viewport) — nearest first. Empty when nothing is, or on
+ *  a host without surfaces (the web).
+ *  Rejects with "notRunning". */
+export declare const hitTest: (service: ServiceChannel<AREvents>, x: number, y: number, target?: HitTarget) => Promise<HitResult[]>;
+/** Pin `entity` to `pose`: the host's anchor drives its matrix from now on (and keeps it true
+ *  as the world map refines).
+ *  Rejects with "notRunning". */
+export declare const anchor: (service: ServiceChannel<AREvents>, entity: Entity, pose: Pose) => Promise<void>;
+/** Stop driving `entity` (its matrix stays where it was). */
+export declare const release: (service: ServiceChannel<AREvents>, entity: Entity) => Promise<void>;
+/** The latest camera frame as a JPEG (the raw image, not the composite — that is
+ *  `Scene.capture()`).
+ *  Rejects with "notRunning" / "failed". */
+export declare const captureFrame: (service: ServiceChannel<AREvents>) => Promise<File>;
+/** A method of the contract. */
+export type Method = "start" | "stop" | "setImages" | "hitTest" | "anchor" | "release" | "captureFrame";
+/** Whether this host has the service "ar" — and, given a method, a half new enough for it
+ *  (a method added after the first version of the contract is tagged `@since`). */
+export declare const supports: (method?: Method) => boolean;
+/** The service "ar" with the wire's methods as its own. */
+export declare class ARBase extends ServiceChannel<AREvents> {
+    constructor(params?: ARParams);
+    /** Start tracking; resolves at the first frame. A second start rejects "busy".
+     *  Needs the "camera" permission: the host asks before the call, "denied" when refused.
+     *  Rejects with "denied" / "busy" / "unavailable" / "failed". */
+    start(options?: StartOptions): Promise<void>;
+    /** Stop tracking: the camera is released, the scene's projection and background cleared. Not
+     *  running is not an error. */
+    stop(): Promise<void>;
+    /** Replace the set of image targets of a RUNNING session without restarting it (the tracking, the
+     *  planes and the anchors stay); an image no longer in the set stops driving its entity (its
+     *  `image` event says `tracked: false` once if it was tracked). Before `start`, the images are
+     *  `StartOptions.images`.
+     *  Rejects with "notRunning" / "failed". */
+    setImages(images: ImageTarget[]): Promise<void>;
+    /** What is under a point of the scene's view — in its touches' space (a scene touch's `clientX` /
+     *  `clientY`: the units of the gl facade's viewport) — nearest first. Empty when nothing is, or on
+     *  a host without surfaces (the web).
+     *  Rejects with "notRunning". */
+    hitTest(x: number, y: number, target?: HitTarget): Promise<HitResult[]>;
+    /** Pin `entity` to `pose`: the host's anchor drives its matrix from now on (and keeps it true
+     *  as the world map refines).
+     *  Rejects with "notRunning". */
+    anchor(entity: Entity, pose: Pose): Promise<void>;
+    /** Stop driving `entity` (its matrix stays where it was). */
+    release(entity: Entity): Promise<void>;
+    /** The latest camera frame as a JPEG (the raw image, not the composite — that is
+     *  `Scene.capture()`).
+     *  Rejects with "notRunning" / "failed". */
+    captureFrame(): Promise<File>;
+}

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

@@ -0,0 +1,28 @@
+import { Vec3, type Node, type Scene } from "../../../../plugin";
+import type { HitTarget } from "../contract";
+export type ControlsOptions = {
+    /** Smallest uniform scale the pinch gesture allows (default 0.08). */
+    minScale?: number;
+    /** Largest uniform scale the pinch gesture allows (default 2). */
+    maxScale?: number;
+    /** One-finger drag moves the target over the surfaces under the finger (default true). */
+    pan?: boolean;
+    /** Two-finger pinch scales the target (default true). */
+    pinch?: boolean;
+    /** Two-finger twist rotates the target around its Y axis (default true). */
+    twist?: boolean;
+};
+/** Returned by `addControls` — call `remove()` to detach the gesture listeners. */
+export type ControlsHandle = {
+    remove(): void;
+};
+/** The scene the controls work on: ARScene's hit test, a Scene's camera and touches. */
+type PlacingScene = Scene & {
+    hitTest(x: number, y: number, target?: HitTarget): Promise<{
+        pose: {
+            position: Vec3;
+        };
+    }[]>;
+};
+export declare const attachControls: (scene: PlacingScene, target: Node, options?: ControlsOptions) => ControlsHandle;
+export {};