lecodes-sdk 2.2.9 → 2.2.11

package/prompts/index.md

@@ -34,4 +34,6 @@ implement what you can with the loaded ones.
 //            default export is a SceneHandle: load()/open()) + use/ref/make in the def,
 //            scenario aspects MoveTo/FollowPath/Spin/LookAt/PlayAnimation;
 //            *.editor.ts + EDITOR/InspectorUI are editor-plugin files — never edit or import them
-// AR: ARScene (camera passthrough, anchors, placement gestures via addControls)
+// AR: ARScene, Anchor, ImageAnchor, ARPlane — the "ar" plugin (app.json "plugins": { "ar": "*" }): camera
+//            passthrough, tracking, planes, hitTest, anchors (root / pose / image), light,
+//            captureFrame, placement gestures via addControls

package/src/animate/tween/Timeline.ts

@@ -1,175 +1,175 @@
-// `Timeline` (docs/timeline-plan.md §2.4): choreography over the keyframe core. Tracks on any
-// number of targets (UI elements, 3D / 2D nodes, lights, cameras) at absolute positions, JS calls
-// at times, labels, holds — one clock, one handle. Also the `animateTo` / `animateFrom` bag
-// builder every target class delegates to (`tweenBag`).
-
-import { TweenAnimation, type Animation } from "./Animation"
-import { makeValueTrack, type AnimateOptions, type AnimateValue } from "./animateValue"
-import { CLOCK_GAME, CLOCK_UI, bagProps, iterationsOf, makeTrack, type Track, type TweenMeta, type TweenSpec, type TweenTarget } from "./spec"
-
-/** Vector-valued props: an array value is ONE keyframe unless it is an array of vectors. */
-const VECTOR_PROPS = new Set(["position", "scale", "quaternion", "eulerAngles", "color"])
-
-const clockOf = (clock: TweenMeta["clock"], fallback: number): number =>
-  clock === "game" ? CLOCK_GAME : clock === "ui" ? CLOCK_UI : fallback
-
-/** @internal Build the tracks of one options bag on one target. `fromCurrent` = animateTo shape. */
-export const bagTracks = (target: TweenTarget, bag: Record<string, unknown>, atMs: number, fromCurrent: boolean): Track[] => {
-  const meta = bag as TweenMeta
-  const tracks: Track[] = []
-  for (const [prop, value] of bagProps(bag)) {
-    const track = makeTrack(target, prop, value, meta, atMs, fromCurrent, VECTOR_PROPS.has(prop))
-    if (track) tracks.push(track)
-  }
-  return tracks
-}
-
-/** @internal The `animateTo` / `animateFrom` implementation: one bag → one animation, played now. */
-export const tweenBag = (target: TweenTarget, bag: Record<string, unknown>, fromCurrent: boolean): Animation => {
-  const meta = bag as TweenMeta
-  const tracks = bagTracks(target, bag, 0, fromCurrent)
-  let durationMs = 0
-  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
-  const spec: TweenSpec = {
-    clock: clockOf(meta.clock, target._tweenClock),
-    durationMs, delayMs: 0,
-    iterations: iterationsOf(meta.loop),
-    pingPong: meta.loopMode !== "restart",
-    rate: 1, tracks, calls: [],
-  }
-  return new TweenAnimation(spec).play()
-}
-
-export type TimelineOptions = {
-  /** `'ui'` (default) = wall time; `'game'` follows `Time.scale` and pauses with the game. */
-  clock?: "ui" | "game",
-  /** Repeat the whole timeline: `true` = forever, a number = cycles. */
-  loop?: boolean | number,
-  loopMode?: "restart" | "ping-pong",
-  /** Wait before the first play, ms. */
-  delay?: number,
-}
-
-/** Where a track goes: ms, a label, or `[label, offsetMs]`. Default = the current end (sequencing). */
-export type TimelinePosition = number | string | [string, number]
-
-export type TimelineAddOptions = {
-  at?: TimelinePosition,
-  /** With several targets: each starts this many ms after the previous one. */
-  stagger?: number,
-}
-
-/** A choreography: tracks on many targets at absolute times, JS calls, labels and holds, driven by
- *  one clock. Build it once, `play()` on every entrance — `play()` restarts from t = 0 and the pose
- *  at any time is fully defined by the tracks (the first keyframe of a track holds before it
- *  starts, the last one after it ends). */
-export class TimelineImpl extends TweenAnimation {
-  private _labels = new Map<string, number>()
-  private _end = 0
-
-  constructor(options: TimelineOptions = {}) {
-    super({
-      clock: clockOf(options.clock, CLOCK_UI),
-      durationMs: 0,
-      delayMs: options.delay ?? 0,
-      iterations: iterationsOf(options.loop),
-      pingPong: options.loopMode !== "restart",
-      rate: 1, tracks: [], calls: [],
-    })
-  }
-
-  private _at(at: TimelinePosition | undefined): number {
-    if (at === undefined) return this._end
-    if (typeof at === "number") return at
-    const name = Array.isArray(at) ? at[0] : at
-    const offset = Array.isArray(at) ? at[1] : 0
-    const base = this._labels.get(name)
-    if (base === undefined) throw new Error(`Timeline: unknown label "${name}"`)
-    return base + offset
-  }
-
-  private _grow(endMs: number): void {
-    if (endMs > this._end) this._end = endMs
-    this._spec.durationMs = this._end
-  }
-
-  /** Animate `props` on one target or several (staggered), like `animateTo` — arrays are keyframes,
-   *  `duration` / `easing` / `times` / `commit` apply. The bag's `delay` shifts the track after `at`. */
-  add(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
-    const at = this._at(options.at)
-    const targets = Array.isArray(target) ? target : [target]
-    const stagger = options.stagger ?? 0
-    targets.forEach((t, i) => {
-      const tracks = bagTracks(t, props, at + i * stagger, true)
-      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
-    })
-    return this
-  }
-
-  /** Like `add` with the `animateFrom` shape: the target's own state is the implicit last keyframe. */
-  addFrom(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
-    const at = this._at(options.at)
-    const targets = Array.isArray(target) ? target : [target]
-    const stagger = options.stagger ?? 0
-    targets.forEach((t, i) => {
-      const tracks = bagTracks(t, props, at + i * stagger, false)
-      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
-    })
-    return this
-  }
-
-  /** A free-value track (see the `animate()` global): the host evaluates it and calls `onUpdate`
-   *  every frame with the value. */
-  animate<T extends AnimateValue>(options: AnimateOptions<T>, at?: TimelinePosition): this {
-    const { track, deliver, slot } = makeValueTrack(options, this._at(at))
-    this._values.set(slot, deliver)
-    this._spec.tracks.push(track)
-    this._grow(track.atMs + track.durMs)
-    return this
-  }
-
-  /** Call `fn` when playback crosses `at` (forward or backward), in time order, always before
-   *  finish, never from a previous run. */
-  call(at: TimelinePosition, fn: () => void): this {
-    const t = this._at(at)
-    this._spec.calls.push(t)
-    this._calls.push(fn)
-    this._grow(t)
-    return this
-  }
-
-  /** Name a time — for `at`, `seek` and callers (`tl.labels.landed`). Default = the current end. */
-  label(name: string, at?: TimelinePosition): this {
-    this._labels.set(name, this._at(at))
-    return this
-  }
-
-  /** Named times, ms. */
-  get labels(): Record<string, number> {
-    const o: Record<string, number> = {}
-    for (const [k, v] of this._labels) o[k] = v
-    return o
-  }
-
-  /** Extend the timeline with stillness after its current end. */
-  hold(ms: number): this {
-    this._grow(this._end + Math.max(0, ms))
-    return this
-  }
-
-  /** The current end, ms (tracks, calls and holds). */
-  get end(): number { return this._end }
-
-  /** `seek` also accepts a label. */
-  override seek(at: number | string): this {
-    return super.seek(typeof at === "string" ? this._at(at) : at)
-  }
-}
-
-/** The timeline handle type (see {@link TimelineImpl} for the members). */
-export type Timeline = TimelineImpl
-
-/** Create a timeline — `Timeline()` / `Timeline({ clock: 'game', loop: true })`. */
-export function Timeline(options?: TimelineOptions): Timeline {
-  return new TimelineImpl(options)
-}
+// `Timeline` (docs/timeline-plan.md §2.4): choreography over the keyframe core. Tracks on any
+// number of targets (UI elements, 3D / 2D nodes, lights, cameras) at absolute positions, JS calls
+// at times, labels, holds — one clock, one handle. Also the `animateTo` / `animateFrom` bag
+// builder every target class delegates to (`tweenBag`).
+
+import { TweenAnimation, type Animation } from "./Animation"
+import { makeValueTrack, type AnimateOptions, type AnimateValue } from "./animateValue"
+import { CLOCK_GAME, CLOCK_UI, bagProps, iterationsOf, makeTrack, type Track, type TweenMeta, type TweenSpec, type TweenTarget } from "./spec"
+
+/** Vector-valued props: an array value is ONE keyframe unless it is an array of vectors. */
+const VECTOR_PROPS = new Set(["position", "scale", "quaternion", "eulerAngles", "color"])
+
+const clockOf = (clock: TweenMeta["clock"], fallback: number): number =>
+  clock === "game" ? CLOCK_GAME : clock === "ui" ? CLOCK_UI : fallback
+
+/** @internal Build the tracks of one options bag on one target. `fromCurrent` = animateTo shape. */
+export const bagTracks = (target: TweenTarget, bag: Record<string, unknown>, atMs: number, fromCurrent: boolean): Track[] => {
+  const meta = bag as TweenMeta
+  const tracks: Track[] = []
+  for (const [prop, value] of bagProps(bag)) {
+    const track = makeTrack(target, prop, value, meta, atMs, fromCurrent, VECTOR_PROPS.has(prop))
+    if (track) tracks.push(track)
+  }
+  return tracks
+}
+
+/** @internal The `animateTo` / `animateFrom` implementation: one bag → one animation, played now. */
+export const tweenBag = (target: TweenTarget, bag: Record<string, unknown>, fromCurrent: boolean): Animation => {
+  const meta = bag as TweenMeta
+  const tracks = bagTracks(target, bag, 0, fromCurrent)
+  let durationMs = 0
+  for (const t of tracks) durationMs = Math.max(durationMs, t.atMs + t.durMs)
+  const spec: TweenSpec = {
+    clock: clockOf(meta.clock, target._tweenClock),
+    durationMs, delayMs: 0,
+    iterations: iterationsOf(meta.loop),
+    pingPong: meta.loopMode !== "restart",
+    rate: 1, tracks, calls: [],
+  }
+  return new TweenAnimation(spec).play()
+}
+
+export type TimelineOptions = {
+  /** `'ui'` (default) = wall time; `'game'` follows `Time.scale` and pauses with the game. */
+  clock?: "ui" | "game",
+  /** Repeat the whole timeline: `true` = forever, a number = cycles. */
+  loop?: boolean | number,
+  loopMode?: "restart" | "ping-pong",
+  /** Wait before the first play, ms. */
+  delay?: number,
+}
+
+/** Where a track goes: ms, a label, or `[label, offsetMs]`. Default = the current end (sequencing). */
+export type TimelinePosition = number | string | [string, number]
+
+export type TimelineAddOptions = {
+  at?: TimelinePosition,
+  /** With several targets: each starts this many ms after the previous one. */
+  stagger?: number,
+}
+
+/** A choreography: tracks on many targets at absolute times, JS calls, labels and holds, driven by
+ *  one clock. Build it once, `play()` on every entrance — `play()` restarts from t = 0 and the pose
+ *  at any time is fully defined by the tracks (the first keyframe of a track holds before it
+ *  starts, the last one after it ends). */
+export class TimelineImpl extends TweenAnimation {
+  private _labels = new Map<string, number>()
+  private _end = 0
+
+  constructor(options: TimelineOptions = {}) {
+    super({
+      clock: clockOf(options.clock, CLOCK_UI),
+      durationMs: 0,
+      delayMs: options.delay ?? 0,
+      iterations: iterationsOf(options.loop),
+      pingPong: options.loopMode !== "restart",
+      rate: 1, tracks: [], calls: [],
+    })
+  }
+
+  private _at(at: TimelinePosition | undefined): number {
+    if (at === undefined) return this._end
+    if (typeof at === "number") return at
+    const name = Array.isArray(at) ? at[0] : at
+    const offset = Array.isArray(at) ? at[1] : 0
+    const base = this._labels.get(name)
+    if (base === undefined) throw new Error(`Timeline: unknown label "${name}"`)
+    return base + offset
+  }
+
+  private _grow(endMs: number): void {
+    if (endMs > this._end) this._end = endMs
+    this._spec.durationMs = this._end
+  }
+
+  /** Animate `props` on one target or several (staggered), like `animateTo` — arrays are keyframes,
+   *  `duration` / `easing` / `times` / `commit` apply. The bag's `delay` shifts the track after `at`. */
+  add(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
+    const at = this._at(options.at)
+    const targets = Array.isArray(target) ? target : [target]
+    const stagger = options.stagger ?? 0
+    targets.forEach((t, i) => {
+      const tracks = bagTracks(t, props, at + i * stagger, true)
+      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
+    })
+    return this
+  }
+
+  /** Like `add` with the `animateFrom` shape: the target's own state is the implicit last keyframe. */
+  addFrom(target: TweenTarget | TweenTarget[], props: Record<string, unknown> & TweenMeta, options: TimelineAddOptions = {}): this {
+    const at = this._at(options.at)
+    const targets = Array.isArray(target) ? target : [target]
+    const stagger = options.stagger ?? 0
+    targets.forEach((t, i) => {
+      const tracks = bagTracks(t, props, at + i * stagger, false)
+      for (const tr of tracks) { this._spec.tracks.push(tr); this._grow(tr.atMs + tr.durMs) }
+    })
+    return this
+  }
+
+  /** A free-value track (see the `animate()` global): the host evaluates it and calls `onUpdate`
+   *  every frame with the value. */
+  animate<T extends AnimateValue>(options: AnimateOptions<T>, at?: TimelinePosition): this {
+    const { track, deliver, slot } = makeValueTrack(options, this._at(at))
+    this._values.set(slot, deliver)
+    this._spec.tracks.push(track)
+    this._grow(track.atMs + track.durMs)
+    return this
+  }
+
+  /** Call `fn` when playback crosses `at` (forward or backward), in time order, always before
+   *  finish, never from a previous run. */
+  call(at: TimelinePosition, fn: () => void): this {
+    const t = this._at(at)
+    this._spec.calls.push(t)
+    this._calls.push(fn)
+    this._grow(t)
+    return this
+  }
+
+  /** Name a time — for `at`, `seek` and callers (`tl.labels.landed`). Default = the current end. */
+  label(name: string, at?: TimelinePosition): this {
+    this._labels.set(name, this._at(at))
+    return this
+  }
+
+  /** Named times, ms. */
+  get labels(): Record<string, number> {
+    const o: Record<string, number> = {}
+    for (const [k, v] of this._labels) o[k] = v
+    return o
+  }
+
+  /** Extend the timeline with stillness after its current end. */
+  hold(ms: number): this {
+    this._grow(this._end + Math.max(0, ms))
+    return this
+  }
+
+  /** The current end, ms (tracks, calls and holds). */
+  get end(): number { return this._end }
+
+  /** `seek` also accepts a label. */
+  override seek(at: number | string): this {
+    return super.seek(typeof at === "string" ? this._at(at) : at)
+  }
+}
+
+/** The timeline handle type (see {@link TimelineImpl} for the members). */
+export type Timeline = TimelineImpl
+
+/** Create a timeline — `Timeline()` / `Timeline({ clock: 'game', loop: true })`. */
+export function Timeline(options?: TimelineOptions): Timeline {
+  return new TimelineImpl(options)
+}

package/src/bridges/device.d.ts

@@ -1,5 +1,5 @@
 // The device bridge (`_creatorDevice`): what the app runs on — platform facts, haptics, the motion
-// sensor, the clipboard, the share sheet, the file picker, the camera permission.
+// sensor, the clipboard, the share sheet, the file picker, the OS permissions.
 // Part of the host contract: every runtime implements this global (runtime/native in C++, the web
 // runtimes in TS). A HOST bridge (`@host`, see ./app.d.ts): the native side is the `HostDevice`
 // table of runtime/native/include/creator-pkg/host.gen.h, generated from this file. Data properties
@@ -70,11 +70,25 @@ declare global {
      *  error. Absent on hosts without a dialog (headless, CREATOR_HIDDEN runs): the SDK resolves
      *  "nothing picked". */
     openFilePicker?(onComplete: (files: [id: number, name: string, size: number][] | null) => void, onReject: (err: Error) => void, multiple: boolean, accept?: string): void
-    /** Prompt for camera permission (resolve = granted, reject = denied). Shared by everything that
-     *  needs the camera — ARScene.prepare, QRScanner, CameraView. Optional: hosts whose view
-     *  factory prompts on its own (web getUserMedia) don't implement it and the SDK resolves
-     *  immediately, so callers go through `_requestCameraPermission()`. */
-    requestCamera?(onComplete: () => void, onReject: () => void): void
+
+    // ---- Permissions -----------------------------------------------------------------------------
+    // The OS permissions, ONE door for the SDK (ARScene.prepare, the camera views), the apps
+    // (`permissions.query / request`) and the plugins' generated glue (`@permission` on a method of
+    // a contract: the native half asks through the host's same service before the call). `kind` is
+    // "camera" | "microphone" | "location" | "speech"; a state is "granted" | "denied" | "prompt"
+    // (never asked). Both slots are async because the browser's Permissions API is. Hosts without
+    // a dialog (headless, desktop) leave them null and the SDK answers "granted": nothing there
+    // stands between an app and a feature; the feature itself says whether it exists.
+    /** The state of `kind` without a prompt. `onReject`: an unknown kind. */
+    queryPermission?(kind: string, onComplete: (state: string) => void, onReject: (err: string) => void): void
+    /** Ask the OS for `kind` — the dialog when it was never asked (the OS decides whether a denied
+     *  one is asked again) — and complete with the state after. Prompts are queued by the host: two
+     *  callers get one dialog after another, one kind asked twice while its dialog is up gets one
+     *  dialog and two answers. `onReject`: an unknown kind, or nowhere to present the dialog. */
+    requestPermission?(kind: string, onComplete: (state: string) => void, onReject: (err: string) => void): void
+    /** Open the app's own page of the system settings (where a denied permission is turned on).
+     *  Absent where there is no such page (web). */
+    openSettings?(): void
   }
 }
 

package/src/bridges/gl.d.ts

@@ -41,9 +41,11 @@ declare global {
     openScene(sceneId: u32): void
     /** @custom */
     closeScene(): void
-    /** @custom */
+    /** Throws — AR is the "ar" plugin since 2.3 (docs/plans/ar-plugin-plan.md decision 6); kept for ONE
+     *  minor so a bundle of an older SDK says so instead of failing on a missing method, gone in 3.0.
+     *  @custom */
     launchAR(sceneId: u32, onComplete: () => void, onReject: () => void): void
-    /** @custom */
+    /** Throws, as launchAR. @custom */
     stopAR(): void
     /** @custom */
     launchVR(sceneId: u32, onComplete: () => void, onReject: (err?: unknown) => void): void
@@ -231,6 +233,21 @@ declare global {
     setLodBias?(bias: f64): void
     setMaterialGlobalParameter(sceneId: u32, i: u32, x: f32, y: f32, z: f32, w: f32): void
     getCameraFov(sceneId: u32, fovType: u8): f64
+    /** The pose of the scene's camera: its entity's WORLD matrix (column-major). What a host's gl facade
+     *  sets for a plugin that tracks the device (AR); an app moves the Camera node instead. Optional. */
+    setCameraMatrix?(sceneId: u32, mat: Float32Array): void
+    /** A projection the host computes, as a matrix (column-major, OpenGL clip conventions) with the
+     *  near / far it was built with: it replaces the scene's fov projection until
+     *  clearCameraProjectionMatrix (an AR framework's camera intrinsics and display crop). Optional:
+     *  the gl facade's setProjection is a no-op on a host without it. */
+    setCameraProjectionMatrix?(sceneId: u32, mat: Float32Array, near: f32, far: f32): void
+    clearCameraProjectionMatrix?(sceneId: u32): void
+    /** The scene's background: texture `textureId` behind everything, filling the viewport, through
+     *  the affine map `uv` (6 floats, row-major [a b tx  c d ty]) from the viewport's normalized
+     *  coordinates (0,0 top-left) to the texture's; 0xFFFFFFFF = none (the sky comes back). The engine
+     *  draws it (creator.h setSceneBackground); the runtime registers its built-in material from the
+     *  materials archive. Optional. @custom */
+    setSceneBackground?(sceneId: u32, textureId: u32, uv: Float32Array): void
     /** The scene camera's projection: VERTICAL fov in degrees + near/far clip distances (defaults
      *  60 / 0.01 / 1000). Aspect stays host-owned — the host STORES these per scene and re-applies
      *  them whenever the viewport changes, so one call outlives every resize. Optional: hosts that
@@ -330,9 +347,11 @@ declare global {
     setUniformArray(materialId: u32, uniform: string, value: Float32Array): void
     setUniformNull(materialId: u32, uniform: string): void
 
-    /** @custom */
+    /** The scene's camera = this entity (every Scene's Camera attaches through it; the name is a
+     *  relic of the AR it first served — it is not AR). @custom */
     attachCameraToAR(sceneId: u32, cameraEntityId: u32, onProjectionChange: (mat: Float32Array, fov: number) => void): void
-    /** @custom */
+    /** The scene view's [width, height] in logical units — the units of the scene's touches on every
+     *  host: the viewport over the density the host set (Camera.displaySize). @custom */
     getDisplaySize(): Float32Array
 
     setVisible(entityId: u32, visible: boolean): void
@@ -1106,11 +1125,11 @@ declare global {
 
     hasMesh(entityId: u32): boolean
 
-    /** @custom */
+    /** Throws, as launchAR (decision 6 of docs/plans/ar-plugin-plan.md). @custom */
     createARController(sceneId: u32, cameraId: u32, mode: string, onTrack: (entityId: number, track: boolean) => void): void
-    /** @custom */
+    /** Throws, as launchAR. @custom */
     createRootAnchor(sceneId: u32): u32
-    /** @custom */
+    /** Throws, as launchAR. @custom */
     createAnchor(sceneId: u32, physicalWidth: f64, systemId: bytes): u32
 
     // Particles. All emitter/curve config crosses as ONE Float32Array of [tag, payloadLen,
@@ -1146,15 +1165,19 @@ declare global {
     getNoise2D(noiseId: u32, x: f32, y: f32): f64
     getNoise3D(noiseId: u32, x: f32, y: f32, z: f32): f64
 
-    /** @custom */
+    /** The scene's picture as a PNG File: the composite of its next frame (the scene and its overlays,
+     *  under the platform's UI — creator.h readPixels), encoded by the core, in the host's buffer store;
+     *  settled through the dispatch queue. Rejects when the scene is not the one presented, or it
+     *  changes before the frame. @custom */
     captureImage(sceneId: number, onComplete: (bufferId: number, name: string, size: number) => void, onReject: () => void): void
   }
 }
 
 /** The 3D HOST's side of the contract — what the engine needs from the platform around Filament
  *  (`HostGL` of creator-pkg/host.gen.h): the GL context to share, the scene view's lifecycle, image
- *  decoding into textures, AR / VR sessions. OPTIONAL as a whole (a UI-only build has no 3D); every
- *  slot but `createTexture` is optional — the runtime skips what a host does not fill.
+ *  decoding into textures, VR sessions. OPTIONAL as a whole (a UI-only build has no 3D); every
+ *  slot but `createTexture` is optional — the runtime skips what a host does not fill. AR is not
+ *  here: it is a plugin, which drives the engine through the host's gl facade (docs/plans/ar-plugin-plan.md).
  *  @host gl HostGL @optional */
 export interface HostGL {
   /** The host's GL context Filament shares with (a desktop master context, the XR context on Quest);
@@ -1173,18 +1196,9 @@ export interface HostGL {
   createTexture(systemId: bytes, flags: u32, onComplete: (textureId: u32, width: i32, height: i32) => void, onReject: (err: string) => void): void
   /** Import a media player's frames as an engine texture (`_creator.createMediaPlayerTexture`); 0 = none. */
   createMediaPlayerTexture?(playerId: i32): i32
-  /** Start an AR session for the scene; settle one callback through the dispatch bridge. */
-  launchAR?(sceneId: u32, onComplete: () => void, onReject: (err: string) => void): void
-  stopAR?(): void
   /** Start a VR (OpenXR) session for the scene; absent = "VR is not supported on this device". */
   launchVR?(sceneId: u32, onComplete: () => void, onReject: (err: string) => void): void
   stopVR?(): void
-  /** Bind the AR camera of `sceneId` to `cameraId` in `mode` ("world" / "face" / …). */
-  createARController?(sceneId: u32, cameraId: u32, mode: string): void
-  /** The AR root anchor entity of a scene. */
-  createRootAnchor?(sceneId: u32, entityId: u32): void
-  /** An image anchor: track the image in host buffer `systemId` (`physicalWidth` in metres) on `entityId`. */
-  createAnchor?(sceneId: u32, entityId: u32, physicalWidth: f32, systemId: bytes): void
 }
 
 export {}

package/src/bridges/media.d.ts

@@ -18,7 +18,9 @@ import type { f32, f64, i32 } from "./types"
 declare global {
   /** @host media @optional */
   var _creatorMedia: {
-    /** A player for `src` as an owned Handle (null = the host failed to create one). @custom */
+    /** A player for `src` as an owned Handle (null = the host failed to create one). `src` is a url
+     *  or `"id:<bufferId>"` (a host buffer: a local asset, a File, a FetchResponse), which the host
+     *  resolves. @custom */
     createAudio(src: string): Handle | null
     /** @custom */
     createVideo(src: string): Handle | null

package/src/canvas/Canvas.ts

@@ -115,14 +115,14 @@ export class Canvas extends Recorder {
   }
 
   /** Decode an image source into a standalone `Bitmap` you can blit with `drawImage()` — either an
-   *  `SvgSource(...)` (drawn by the core, painted by the host) or a `FetchResponse` holding already-fetched
-   *  image bytes (decoded; an SVG file is detected). This is async because the web host decodes with the
-   *  browser; `await` it ONCE, then `drawImage(bitmap, …)` is synchronous and the Bitmap is reusable. The
-   *  returned Bitmap owns a native surface at the image's natural pixel size (`pixelRatio` 1), freed
-   *  once nothing references the Bitmap (`destroy()` frees it early). Typical use:
+   *  `SvgSource(...)` (drawn by the core, painted by the host) or a `FetchResponse` / `File` holding
+   *  already-fetched image bytes (decoded; an SVG file is detected). This is async because the web host
+   *  decodes with the browser; `await` it ONCE, then `drawImage(bitmap, …)` is synchronous and the Bitmap
+   *  is reusable. The returned Bitmap owns a native surface at the image's natural pixel size
+   *  (`pixelRatio` 1), freed once nothing references the Bitmap (`destroy()` frees it early). Typical use:
    *    const logo = await canvas.loadImage(SvgSource(svg))   // or: await fetch(url) → the response
    *    canvas.drawImage(logo, 0, 0)                          // sync, blit as often as you like */
-  loadImage(source: SvgSourceValue | FetchResponse): Promise<Bitmap> {
+  loadImage(source: SvgSourceValue | FetchResponse | File): Promise<Bitmap> {
     // Discriminate without touching FetchResponse internals: only an SvgSource carries `.svg`.
     const isSvg = typeof (source as SvgSourceValue).svg === "string"
     const svg = isSvg ? (source as SvgSourceValue).svg : ""

package/src/compile/header.ts

@@ -51,7 +51,7 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
   // bundle, and nothing 2D works without a Scene2D anyway.
   if (code.includes("_creator2d.createScene")) header += `// 2d: enable\n`
 
-  if (code.includes("_creator.createARController")) header += `// ar: enable\n`
+  if (usesAR(code, opts.plugins)) header += `// ar: enable\n`
 
   // Short, so with the engine lines: a host reads it before it registers anything.
   if (opts.plugins?.length) header += `// plugins: ${opts.plugins.join(";")}\n`
@@ -82,9 +82,16 @@ export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}
   return header
 }
 
-/** Same engine signals the header uses, for callers that need the project kind (e.g. icon type). */
-export const detectProjectKind = (code: string): "ar" | "ui" | "2d" | "3d" => {
-  if (code.includes("_creator.createARController")) return "ar"
+/** `// ar: enable` (the platform's backend reads it: an AR app is offered to the LeCodes app): AR is the
+ *  "ar" plugin since 2.3 (docs/plans/ar-plugin-plan.md) — an app that lists it and makes a 3D scene.
+ *  Its ARScene is the plugin's wrapper, whose calls name no engine member a bundle could be read for. */
+const usesAR = (code: string, plugins: readonly string[] | undefined): boolean =>
+  !!plugins?.includes("ar") && code.includes("_creator.createScene")
+
+/** Same engine signals the header uses, for callers that need the project kind (e.g. icon type).
+ *  `plugins` = the app's (app.json), what tells an AR app. */
+export const detectProjectKind = (code: string, plugins?: readonly string[]): "ar" | "ui" | "2d" | "3d" => {
+  if (usesAR(code, plugins)) return "ar"
   if (code.includes("_creator2d.createScene")) return "2d"
   if (!code.includes("_creator.")) return "ui"
   return "3d"

package/src/gl/Camera.ts

@@ -173,12 +173,15 @@ export class Camera extends Node {
     return 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] {
     const s = _creator.getDisplaySize()
     return [ s[0], s[1] ]
   }
 
-  /** 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 {
     if (this._sceneId < 0) throw new Error("Camera is not attached to a scene")
     const v = new Float32Array(3)
@@ -186,7 +189,7 @@ export class Camera extends Node {
     return new Vec3(v[0], v[1], v[2])
   }
 
-  /** 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 {
     return new Ray(this.worldPosition, this.getViewDirection(screenX, screenY))
   }