lecodes-sdk 2.2.8 → 2.2.10

package/src/plugin.ts

@@ -12,16 +12,41 @@ import { File as HostFile } from "./runtime/fetch"
 import { ServiceClient } from "./runtime/service"
 import { NativeView, NativeViewElement } from "./ui/NativeView"
 import { _navEpoch } from "./ui/presentable"
-import { _requestCameraPermission } from "./plugins/permission"
+import { _ensurePermission } from "./runtime/permissions"
+export { permissions, type PermissionKind, type PermissionState } from "./runtime/permissions"
 import { appEventsOff, appEventsOn } from "./runtime/appEvents"
+import { nodeOf, type Node } from "./gl/Node"
+import type { Scene } from "./gl/Scene"
+/** @internal Ask for an OS permission and reject unless it is granted: a wrapper's preparation, while
+ *  the current destination stays on screen (ARScene's camera). */
+export { _ensurePermission }
 
 export type { PresentOptions } from "./ui/presentable"
 // The SDK UI a wrapper builds its own chrome with (the browser plugin's bar over an embedded page) and
 // the navigation it presents through. Re-exported, never copied: chisel keys on these names.
 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"
+// The 3D a wrapper builds on (the "ar" plugin's ARScene — docs/plans/ar-plugin-plan.md): the scene it
+// extends, the node its anchors are, the mesh it draws a plane's grid with, the math of a pose, the
+// touch a placement gesture follows, the System its per-frame work rides on (the scene's first frame).
+// Re-exported, never copied, as the UI above.
+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"
+/** @internal The navigation epoch: a destination that prepares before it presents (ARScene) reads it
+ *  before its awaits and gives up when another navigation moved it meanwhile. */
+export { _navEpoch }
 
 // ---- the contract's vocabulary ---------------------------------------------------------------------
 
@@ -35,6 +60,17 @@ export type f64 = number
  *  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[] | { [key: string]: Json }
@@ -175,6 +211,13 @@ export const _toFile = (wire: { systemId: number, name: string, size: number }):
 export const _fromFile = (file: File): { systemId: number, name: string, size: number } =>
   ({ systemId: file._h.id, name: file.name, size: file.size })
 
+/** @internal The generated wrapper's: an Entity / a Scene3D the app hands a half crosses as its id… */
+export const _fromEntity = (node: Entity): number => node._h.id
+export const _fromScene3D = (scene: Scene3D): number => scene._id
+/** @internal …and an Entity a half names back is the app's own Node (the pinned one, the app's live
+ *  handle, else a wrapper over the engine's id). */
+export const _toEntity = (id: number): Entity => nodeOf(id)
+
 // ---- for the hand-written part ---------------------------------------------------------------------
 
 /** Hear the app's "url" events (a deep link while the app runs — an OAuth redirect, a checkout's
@@ -197,7 +240,7 @@ export const prepareCamera = async (view: ViewChannel<any>): Promise<void> => {
     throw new Error(`${view._iface} isn't available on this host — it needs a registered "${view.viewName}" view.`)
   }
   const epoch = _navEpoch()
-  await _requestCameraPermission()
+  await _ensurePermission("camera")
   if (_navEpoch() !== epoch) {
     throw new Error(`${view._iface}.open() superseded: another destination was opened while preparing`)
   }

package/src/plugins/gen/ar/contract.d.ts

@@ -0,0 +1,118 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/ar/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// ar — world tracking over the device camera: ARKit on iOS, ARCore on Android, the camera under the
+// scene turned by the sensors on the web. The app's side is ARScene (sdk/ar.ts), a Scene whose
+// camera and background the session drives every frame through the host's gl facade.
+// A session is ONE AR scene: ARScene opens it with the scene and its camera entity as params and
+// closes it with the scene. `@permission camera` on start: the host asks, the halves never do.
+import type { Service, File, Entity, Scene3D, f64 } from "../../../plugin"
+
+export type ARMode = "world" | "images"
+export type PlaneDetection = "horizontal" | "vertical" | "both" | "none"
+export type WorldAlignment = "gravity" | "gravityAndHeading"
+export type TrackingState = "notAvailable" | "limited" | "normal"
+export type TrackingReason = "initializing" | "excessiveMotion" | "insufficientFeatures" | "relocalizing"
+export type PlaneType = "horizontal" | "vertical"
+export type PlaneChange = "added" | "updated" | "removed"
+export type HitTarget = "planes" | "estimated" | "any"
+export type ARErrorCode = "unavailable" | "camera" | "failed"
+
+export interface Vec3 { x: f64, y: f64, z: f64 }
+export interface Quat { x: f64, y: f64, z: f64, w: f64 }
+/** A pose in the scene's world: metres, Y up. */
+export interface Pose { position: Vec3, rotation: Quat }
+
+export interface ImageTarget {
+  image: File
+  /** The printed width, metres: the size the session starts from (the height by the image's
+   *  proportions) — the framework refines it (the `image` event's `extent`). */
+  physicalWidth: f64
+  /** The entity that follows the image (its Anchor node). */
+  entity: Entity
+}
+
+export interface StartOptions {
+  /** Default "world". "images": image tracking only (no planes, no hit test; iOS runs
+   *  ARImageTrackingConfiguration, which is lighter). */
+  mode?: ARMode
+  /** Default "horizontal". Ignored in "images". */
+  planes?: PlaneDetection
+  images?: ImageTarget[]
+  /** Default "gravity". "gravityAndHeading": -Z points north (the compass). */
+  worldAlignment?: WorldAlignment
+  /** Deliver `light` events. Default false. */
+  lightEstimation?: boolean
+  /** Default true. */
+  autoFocus?: boolean
+}
+
+export interface HitResult {
+  pose: Pose
+  /** "plane": on a detected plane (`plane` = its id); "estimated": on a point of the feature
+   *  cloud / an estimated plane. */
+  type: "plane" | "estimated"
+  plane?: f64
+  /** Metres from the camera. */
+  distance: f64
+}
+
+/** Both are ARScene's, always sent. Optional because a channel's params are (the generator's rule: a
+ *  param a half cannot read has no one to reject to); a session opened without them rejects `start`
+ *  with "failed". */
+export interface ARParams {
+  scene?: Scene3D
+  /** The scene's camera entity: the session sets its matrix and the scene's projection each frame. */
+  camera?: Entity
+}
+
+export interface AREvents {
+  /** The tracking quality; the first event of a session. */
+  tracking: { state: TrackingState, reason?: TrackingReason }
+  /** A detected plane: added, moved / grown (throttled: a change over 1 cm, at most 10 per second),
+   *  or gone (`mergedInto` = the plane that absorbed it, ARCore). `pose` = the plane's centre, its
+   *  Y the normal; `extent` = [width, height] metres; `polygon` = the boundary as x,z pairs in the
+   *  plane's space. */
+  plane: { change: PlaneChange, id: f64, type: PlaneType, pose: Pose, extent: f64[], polygon: f64[], mergedInto?: f64 }
+  /** An image target found, lost, or its size refined. While tracked its entity is driven: a rigid
+   *  pose in metres, no scale — the image's centre, Y out of it, the image in XZ (X along its width,
+   *  Z towards its bottom). `extent` = [width, height] metres, the framework's estimate (sent again
+   *  when it changes by a millimetre, at most 10 per second); the last one when lost. */
+  image: { entity: Entity, tracked: boolean, extent: f64[] }
+  /** An anchor made by `anchor()` lost or regained after a relocalization. */
+  anchor: { entity: Entity, tracked: boolean }
+  /** The estimated light (`lightEstimation`): lumens-ish ambient intensity (1000 = ARKit's
+   *  neutral), colour temperature in kelvin; at most 10 per second. */
+  light: { intensity: f64, temperature: f64 }
+  /** The session failed and is over: "unavailable" (no ARKit / ARCore support, ARCore not
+   *  installed and declined), "camera" (the camera could not be used), "failed". */
+  error: { code: ARErrorCode, message: string }
+}
+
+export interface AR extends Service<"ar", ARParams, AREvents> {
+  /** Start tracking; resolves at the first frame. A second start rejects "busy".
+   *  @permission camera
+   *  @rejects 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 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 notRunning */
+  hitTest(x: f64, y: f64, 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 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 notRunning failed */
+  captureFrame(): Promise<File>
+}

package/src/plugins/gen/ar/sdk/ar.gen.ts

@@ -0,0 +1,112 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/ar/sdk/ar.gen.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// GENERATED by `lecodes plugin gen` from contract.d.ts — do not edit.
+// ar: the service "ar", contract version 1.
+
+import { ServiceChannel, _fromEntity, _fromFile, _fromScene3D, _toEntity, _toFile, 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 const NAME = "ar"
+/** The contract's version: the highest `@since` of its members. */
+export const VERSION = 1
+
+const _fromStartOptions = (v: StartOptions): any => ({ ...v, images: v.images === undefined ? undefined : v.images.map((x: any) => _fromImageTarget(x)) })
+const _fromImageTarget = (v: ImageTarget): any => ({ ...v, image: _fromFile(v.image), entity: _fromEntity(v.entity) })
+const _fromARParams = (v: ARParams): any => ({ ...v, scene: v.scene === undefined ? undefined : _fromScene3D(v.scene), camera: v.camera === undefined ? undefined : _fromEntity(v.camera) })
+
+/** The events whose payload holds a File: read before a listener sees it. */
+export const READERS: EventReaders = {
+  image: (w: any) => ({ ...w, entity: _toEntity(w.entity) }),
+  anchor: (w: any) => ({ ...w, entity: _toEntity(w.entity) }),
+}
+
+// ---- the wire, call by call ----------------------------------------------------------------------
+
+/** 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 const start = (service: ServiceChannel<AREvents>, options?: StartOptions): Promise<void> =>
+  service._call("start", [options === undefined ? undefined : _fromStartOptions(options)])
+
+/** Stop tracking: the camera is released, the scene's projection and background cleared. Not
+ *  running is not an error. */
+export const stop = (service: ServiceChannel<AREvents>): Promise<void> =>
+  service._call("stop", [])
+
+/** 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 const setImages = (service: ServiceChannel<AREvents>, images: ImageTarget[]): Promise<void> =>
+  service._call("setImages", [images.map((x: any) => _fromImageTarget(x))])
+
+/** 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 const hitTest = (service: ServiceChannel<AREvents>, x: number, y: number, target?: HitTarget): Promise<HitResult[]> =>
+  service._call("hitTest", [x, y, target])
+
+/** 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 const anchor = (service: ServiceChannel<AREvents>, entity: Entity, pose: Pose): Promise<void> =>
+  service._call("anchor", [_fromEntity(entity), pose])
+
+/** Stop driving `entity` (its matrix stays where it was). */
+export const release = (service: ServiceChannel<AREvents>, entity: Entity): Promise<void> =>
+  service._call("release", [_fromEntity(entity)])
+
+/** The latest camera frame as a JPEG (the raw image, not the composite — that is
+ *  `Scene.capture()`).
+ *  Rejects with "notRunning" / "failed". */
+export const captureFrame = (service: ServiceChannel<AREvents>): Promise<File> =>
+  service._call("captureFrame", []).then((w: any) => _toFile(w))
+
+// ---- what the host's half has --------------------------------------------------------------------
+
+/** 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 const supports = (method?: Method): boolean =>
+  ServiceChannel.supports(NAME)   // every method is of version 1
+
+// ---- the client -----------------------------------------------------------------------------------
+
+/** The service "ar" with the wire's methods as its own. */
+export class ARBase extends ServiceChannel<AREvents> {
+  constructor(params: ARParams = {}) { super("AR", NAME, _fromARParams(params), READERS) }
+
+  /** 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> { return start(this, options) }
+  /** Stop tracking: the camera is released, the scene's projection and background cleared. Not
+   *  running is not an error. */
+  stop(): Promise<void> { return stop(this) }
+  /** 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> { return setImages(this, images) }
+  /** 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[]> { return hitTest(this, x, y, target) }
+  /** 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> { return anchor(this, entity, pose) }
+  /** Stop driving `entity` (its matrix stays where it was). */
+  release(entity: Entity): Promise<void> { return release(this, entity) }
+  /** The latest camera frame as a JPEG (the raw image, not the composite — that is
+   *  `Scene.capture()`).
+   *  Rejects with "notRunning" / "failed". */
+  captureFrame(): Promise<File> { return captureFrame(this) }
+}