lecodes-sdk 2.4.1 → 2.4.2

package/dist/types/gl/vehicle/Vehicle.d.ts

@@ -131,21 +131,28 @@ export declare class Vehicle extends Aspect<"vehicle", Node> {
      *  without physics or on an older host. A host that has it can still refuse a car's settings
      *  (`id` stays 0, with a warning). */
     static get supported(): boolean;
-    /** Chassis mass in kg (default 1200). Wheels are massless in this model. */
-    mass: number;
+    private _mass;
+    /** Chassis mass in kg (default 1200). Wheels are massless in this model. Structural: a write on a
+     *  live car warns and keeps the built mass. */
+    get mass(): number;
+    set mass(v: number);
     /** Centre of mass height in chassis space (metres, negative = lower). Left out, it drops to halfway
-     *  down the chassis shape — a car with its mass at the shape's centre tips over. */
+     *  down the chassis shape — a car with its mass at the shape's centre tips over. Structural. */
     centerOfMass?: number;
     /** Which axle the engine drives (default "rear") — the default for every wheel's own `driven`
-     *  share: 1 on that axle, 0 elsewhere. `none` = no drive at all (a trailer, a pushed cart). */
+     *  share: 1 on that axle, 0 elsewhere. `none` = no drive at all (a trailer, a pushed cart). Structural. */
     driveAxle: DriveLayout;
+    private _differential;
     /** Differential lock across each driven axle. `locked` is the drift setup — both wheels turn
-     *  together, so the pair lets go as a pair. Live: re-configure the aspect to switch it mid-drive. */
-    differential: DifferentialMode | number;
+     *  together, so the pair lets go as a pair. Live: switch it mid-drive. */
+    get differential(): DifferentialMode | number;
+    set differential(v: DifferentialMode | number);
+    private _antiRoll;
     /**
      * Anti-roll bars between each axle's wheels — what stops a car rolling onto its inside wheels in a
      * fast corner. `true` (default) is a bar 0.01 as stiff as the wheel's own spring; a number is that
-     * ratio directly, and `0` / `false` removes the bars.
+     * ratio directly, and `0` / `false` removes the bars. Live: the stiffness, on axles built with a
+     * bar (`false` at build = no bar to stiffen later).
      *
      * **The numbers are far smaller than they look and the gain is steep** — Jolt's bar feeds
      * `lengthDifference × stiffness × dt` as a bias into the suspension's own soft constraint, so 4%
@@ -155,24 +162,43 @@ export declare class Vehicle extends Aspect<"vehicle", Node> {
      * This is the knob for how much a car visibly LEANS, not for wheel lift: bars change how far the
      * body tips, not how much load transfers. For lift, lower `centerOfMass`.
      */
-    antiRoll: boolean | number;
-    /** Pitch/roll limit in degrees (default 60) before the constraint rights the car. 180 turns it off. */
-    maxTilt: number;
+    get antiRoll(): boolean | number;
+    set antiRoll(v: boolean | number);
+    private _maxTilt;
+    /** Pitch/roll limit in degrees (default 60) before the constraint rights the car. 180 turns it off. Live. */
+    get maxTilt(): number;
+    set maxTilt(v: number);
+    private _friction;
     /** Friction of the CHASSIS body itself — how it slides when it lands on its roof or side. Nothing
-     *  to do with the tires; those are the `Wheel`'s `tire` × the ground's friction. */
-    friction: number;
+     *  to do with the tires; those are the `Wheel`'s `tire` × the ground's friction. Live, at once. */
+    get friction(): number;
+    set friction(v: number);
+    private _clutchStrength;
     /** Strength of the clutch when fully engaged (default 10). Small values slip; large ones weld the
-     *  engine to the wheels. `clutch` (the input) scales it 0..1. */
-    clutchStrength: number;
+     *  engine to the wheels. `clutch` (the input) scales it 0..1. Live. */
+    get clutchStrength(): number;
+    set clutchStrength(v: number);
+    private _clutchCapacity;
     /** The clutch's torque CAPACITY, N·m (default 0 = none: Jolt's viscous clutch alone, torque =
      *  `clutchStrength` × slip speed, no ceiling — rigid at any real slip). Set it and the clutch
      *  SLIPS at this much torque × `clutch` — a dry clutch, emulated a physics step at a time: a
      *  launch can be feathered, and a dumped clutch in too high a gear drags the engine down instead
-     *  of lurching. A road car's is ~1.5× the engine's peak torque. */
-    clutchCapacity: number;
-    engine: EngineConfig;
-    steering: SteeringConfig;
-    aero: AeroConfig;
+     *  of lurching. A road car's is ~1.5× the engine's peak torque. Live. */
+    get clutchCapacity(): number;
+    set clutchCapacity(v: number);
+    private _engine;
+    /** The engine (`EngineConfig`). Live: `car.vehicle.engine.torque = 800`, or assign a whole config. */
+    get engine(): EngineConfig;
+    set engine(v: EngineConfig);
+    private _steering;
+    /** The steering (`SteeringConfig`). Live, one level deep: `feedback` and `driver` are each
+     *  replaced as a whole (`steering.driver = { maxTorque: 90 }`), not edited inside. */
+    get steering(): SteeringConfig;
+    set steering(v: SteeringConfig);
+    private _aero;
+    /** Aerodynamics (`AeroConfig`). Live: a wing that deploys is `car.vehicle.aero.downforce = 0.6`. */
+    get aero(): AeroConfig;
+    set aero(v: AeroConfig);
     /** Scene-editor inspector: the flat, tunable half. The grouped objects are edited in code. */
     static fields: FieldMeta<Vehicle>;
     static editor: {
@@ -194,22 +220,14 @@ export declare class Vehicle extends Aspect<"vehicle", Node> {
     private _input;
     private _sent;
     private _dirty;
-    private _retunePending;
+    private _rebuildPending;
     onAttach(): void;
     onDetach(): void;
-    /**
-     * Re-configuring an attached vehicle retunes it in place — the way a drift button switches the
-     * differential without the car so much as blinking:
-     *
-     *   car.aspect(Vehicle, { differential: drift ? 'locked' : 'lsd' })
-     *
-     * Live: `differential`, `engine`, `steering`, `aero`, `maxTilt`, `friction`, `clutchStrength`,
-     * `clutchCapacity`, `antiRoll` (its stiffness, on axles that have a bar), and every `Wheel`'s
-     * `tire`. Everything else describes the car's STRUCTURE — `mass`, `centerOfMass`, which wheels
-     * exist and where, their suspension, the driven shares — and is baked into the constraint at
-     * attach; to change one of those, re-attach the aspect.
-     */
-    onReconfigure(): void;
+    /** A live value changed on the car or a wheel: the tuning half of the blob is re-sent in
+     *  `flush()`, one send however many values changed this frame. */
+    protected flush(): void;
+    private _setup;
+    private _teardown;
     /** Native vehicle id (0 until attached / no physics support). */
     get id(): number;
     /** The chassis rigid body id (for `physicsApplyImpulse`-style calls). */
@@ -239,8 +257,9 @@ export declare class Vehicle extends Aspect<"vehicle", Node> {
     /**
      * EARLY phase: hand this frame's inputs to the engine, before the step. The vector is sent when
      * anything changed — and every frame while a throttle, steer or brake is non-zero, because that is
-     * what keeps a driven car awake (an idle car with zero input sleeps). The pending re-tune (a
-     * config or tire change) goes first, so the step runs on the new numbers.
+     * what keeps a driven car awake (an idle car with zero input sleeps). A pending re-tune (a live
+     * value of the car or a wheel changed) went out in `flush()`, before this phase, so the step runs
+     * on the new numbers.
      */
     protected updateBefore(): void;
     /** Teleport upright and clear all motion (velocity, engine rpm, wheel spin). Defaults to the

package/dist/types/gl/vehicle/Wheel.d.ts

@@ -70,12 +70,22 @@ export declare const Tire: {
     scale: (t: Tire, k: number) => Tire;
 };
 export declare function resolveTire(tire: Tire): ResolvedTire;
+/**
+ * One wheel. LIVE: `radius`, `suspension.stiffness` / `damping` and `tire` — write them and the car
+ * retunes before the next step (a tire losing air: `wheel.radius *= 0.9`, `wheel.suspension.stiffness
+ * *= 0.7`, `wheel.tire = Tire.scale(wheel.tire, 0.5)`). STRUCTURAL: `width`, `suspension.travel`, `axle`,
+ * `steer`, `driven` — baked when the car is built; to change one, build the wheel again
+ * (`hub.aspect(Wheel, {…})` — the car rebuilds itself around it, its motion reset).
+ */
 export declare class Wheel extends Aspect<"wheel", Node> {
     static readonly aspect = "wheel";
     /** Wheel radius in metres. Default: measured from the node's rendered bounds, else 0.35. Too small
-     *  and the car scrapes, too large and it floats. */
-    radius?: number;
-    /** Wheel width in metres. Default: measured, else 0.25. */
+     *  and the car scrapes, too large and it floats. Live: the ROLLING radius — the suspension hangs
+     *  where it was built, so a smaller one lowers that corner of the car, the way a tire losing air
+     *  does; the wheel's inertia keeps the radius it was built with. */
+    get radius(): number | undefined;
+    set radius(v: number | undefined);
+    /** Wheel width in metres. Default: measured, else 0.25. Structural. */
     width?: number;
     /** Axle group, front to back. Default: derived from Z. Set it for a car whose wheels are not in neat
      *  left/right pairs — an axle's wheels are paired for the differential and the anti-roll bar. */
@@ -87,10 +97,19 @@ export declare class Wheel extends Aspect<"wheel", Node> {
      *  split their ratio, so `0.6` / `0.4` front-to-rear is `driven: 0.3` on each front wheel and
      *  `0.2` on each rear. Structural: baked at attach. */
     driven?: number;
-    suspension: WheelSuspension;
-    /** The tire (default `Tire.road()`). Live: re-assign it or re-configure the aspect and the car
-     *  retunes in place — a grip slider, a tire that heats up. */
-    tire: Tire;
+    private _suspension;
+    /** The suspension. Live: `stiffness` and `damping` (a softer corner sags and rolls more) — write a
+     *  field (`wheel.suspension.stiffness = 1`) or assign a whole object (what it leaves out is the
+     *  default). `travel` is structural. */
+    get suspension(): WheelSuspension;
+    set suspension(v: WheelSuspension);
+    private _tire;
+    /** The tire (default `Tire.road()`). Live: assign one (`wheel.tire = Tire.drift()`, or
+     *  `Tire.scale(wheel.tire, 0.5)` for a grip slider, a tire that heats up) or write a field
+     *  (`wheel.tire.traction = 1`); a curve is replaced, never edited in place. A tire assigned without
+     *  `traction` / `circle` gets `road`'s. */
+    get tire(): Tire;
+    set tire(v: Tire);
     /** INPUT: brake torque on this wheel THIS frame, N·m (default 0). Sticky, like `Vehicle.throttle`:
      *  write it every frame from a driver system's `updateBefore` — the foot brake's share, the
      *  handbrake's 4500 on a rear wheel, an ABS's pulses — and the same physics step applies it. A
@@ -102,10 +121,12 @@ export declare class Wheel extends Aspect<"wheel", Node> {
     static editor: {
         rebuild: boolean;
     };
+    /** A wheel built under a car that already runs (`hub.aspect(Wheel, {…})` on a live car): the car
+     *  rebuilds itself around the new set of wheels before the next step. */
+    onAttach(): void;
     onDetach(): void;
-    /** Re-configuring a wheel on a live car retunes the car: the tire is live; size, suspension, the
-     *  driven share and the axle are structural (re-attach the Vehicle). */
-    onReconfigure(): void;
+    /** A live value changed (the tire, the radius, the spring): the car retunes in the same flush. */
+    protected flush(): void;
     private _state;
     /** Touching the ground this step. */
     get contact(): boolean;

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

@@ -0,0 +1,152 @@
+// 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.
+// What a session finds in the camera's picture and drives an entity to: an image target (a printed
+// picture, by its bytes) and, since contract version 2, a QR code (a printed symbol, by its text) —
+// both through the `image` event. Codes are the web's (WebXR) first: the native halves take them and
+// say they track none yet.
+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
+}
+
+/** A printed QR code the session tracks: found by its text in the camera's picture; while
+ *  tracked its entity is driven like an image target's — a rigid pose in metres, no scale — the
+ *  symbol's centre, Y out of it, X along its top edge, Z towards its bottom. Web (WebXR) first;
+ *  the native halves later. */
+export interface QRTarget {
+  /** The code's text: a symbol with another text is not this target. "" = ANY code (the first
+   *  one decoded): a test, or a plaque whose text is not known to the app. */
+  text: string
+  /** The printed side of the symbol (its modules, no quiet zone), metres. */
+  size: f64
+  /** The entity that follows the code (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[]
+  /** The QR codes to track (in "world" and in "images"); a half without them says so and drives
+   *  none. @since 2 */
+  codes?: QRTarget[]
+  /** 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. A QR target's
+   *  comes the same way (its frame: X along the symbol's top edge), `extent` = [size, size]. */
+  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 }
+  /** The session is over, and not by `stop()`: the user left it ("user" — the browser's back / exit
+   *  of an immersive WebXR session) or the system took it ("system"). Not an error: ARScene closes
+   *  the scene. ARKit and ARCore never end a session by themselves (an interruption is `tracking`
+   *  limited): the native halves do not send it. @since 2 */
+  ended: { reason: "user" | "system" }
+}
+
+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>
+  /** The twin of `setImages` for QR codes: replace the set of QR targets of a RUNNING session
+   *  without restarting it; a code no longer in the set stops driving its entity (`tracked: false`
+   *  once if it was tracked). Before `start`, the codes are `StartOptions.codes`. A half that tracks
+   *  no codes yet (the native ones) rejects "failed".
+   *  @since 2
+   *  @rejects notRunning failed */
+  setCodes(codes: QRTarget[]): 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/dist/types/plugins/gen/ar/sdk/ar.d.ts

@@ -41,11 +41,11 @@ export type ARPlaneEvent = {
     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`. */
+    /** "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;
 };
-export type AROpenOptions = PresentOptions & Omit<StartOptions, "mode" | "images"> & {
+export type AROpenOptions = PresentOptions & Omit<StartOptions, "mode" | "images" | "codes"> & {
     /** The scene's ambient (its `environmentIntensity`) follows the estimated light; turns
      *  `lightEstimation` on. */
     followLight?: boolean;
@@ -55,6 +55,13 @@ export type ARSceneEvents = {
     plane: (event: ARPlaneEvent) => void;
     light: (estimate: ARLightEstimate) => void;
     error: (error: ARError) => void;
+    /** The session ended on its own — the user left it (the back gesture of an immersive web session)
+     *  or the system took it — and the scene leaves: popped when it is the router's top, else closed
+     *  (`onClose` is where an app opens what comes next, as after `scene.close()`). Not an error. Sent
+     *  before the scene leaves. (A `Router.pop()` of an AR scene by the app does NOT end its session:
+     *  a covered scene comes back with it — on the web an immersive session then stays on; `close()`
+     *  ends it.) */
+    end: (reason: "user" | "system") => void;
 };
 export type AnchorEvents = NodeEvents & {
     /** The anchor began tracking: found, placed, or regained after a relocalization. */
@@ -63,9 +70,10 @@ export type AnchorEvents = NodeEvents & {
     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.
+ * A node the AR session drives: it follows a place in the room (`scene.anchor(pose)`, `scene.root`),
+ * an image (`scene.createAnchor(image)`) or a QR code (`scene.createQRAnchor(text, size)`). 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). */
@@ -76,16 +84,20 @@ export declare class Anchor extends Node {
     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`.
+ * An anchor that follows an image (`scene.createAnchor(image, physicalWidth)`) or a printed QR code
+ * (`scene.createQRAnchor(text, size)`, `code` its text): while tracked it sits on it — a rigid pose
+ * in metres, no scale: its centre, Y out of it, the image in X (its width; a code's top edge) and Z
+ * (towards its bottom). How big it 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`. */
+     *  height comes with the image's proportions, which the session reads, at the first `track`. A QR
+     *  code's is [size, size] from the start (a code is square). */
     get extent(): [number, number];
+    /** The text of the QR code the anchor follows (`createQRAnchor`); null for an image's. */
+    get code(): string | null;
 }
 /** 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. */
@@ -124,11 +136,15 @@ export declare class ARScene extends Scene {
     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. */
+     *  superseded, not failed. `images` / `codes`: the image / QR 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;
+    /** A `setImages` / `setCodes` is due at the end of this turn (`_setTargets`). */
+    private readonly _due;
+    /** The QR targets (`createQRAnchor`). */
+    private readonly _codes;
+    /** This host's half is older than the QR targets: said once. */
+    private _codesWarned;
     private _options;
     private _root;
     /** The first horizontal plane's pose: where `root` is pinned. */
@@ -167,6 +183,15 @@ export declare class ARScene extends Scene {
      *  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 that follows a printed QR code whose text is `text`: the session finds the symbol in
+     *  the camera image and keeps the anchor on it, as on an image — a rigid pose in metres (its centre,
+     *  Y out of the symbol, X along its top edge, Z towards its bottom), `anchor.extent` = [size, size].
+     *  `size` = the printed side of the symbol in metres (its modules, no quiet zone): how far it is
+     *  comes from it. Hidden while not tracked. Before `open()`, or any time: on a running scene the set
+     *  of codes is updated in place. The web finds codes first (WebXR); on a host whose `ar` plugin does
+     *  not track them the anchor is never tracked, and the console says so. `text` null or "" = ANY
+     *  code: the first symbol decoded (a test, a plaque whose text the app does not know). */
+    createQRAnchor(text: string | null, size: 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;
@@ -202,18 +227,19 @@ export declare class ARScene extends Scene {
     private _emit;
     private _startOptions;
     private _targets;
+    private _codeTargets;
     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;
+    /** The image targets or the QR targets changed (one added or removed): a running session takes the
+     *  whole set in place (`setImages` / `setCodes` — 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 target the session did not take never tracks. */
+    private _setTargets;
     /** 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. */

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

@@ -1,9 +1,9 @@
 import { ServiceChannel, type Entity, type EventReaders, type File } from "../../../../plugin";
-import type { AREvents, ARParams, HitResult, HitTarget, ImageTarget, Pose, StartOptions } from "../contract";
+import type { AREvents, ARParams, HitResult, HitTarget, ImageTarget, Pose, QRTarget, 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;
+export declare const VERSION = 2;
 /** 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".
@@ -19,6 +19,13 @@ export declare const stop: (service: ServiceChannel<AREvents>) => Promise<void>;
  *  `StartOptions.images`.
  *  Rejects with "notRunning" / "failed". */
 export declare const setImages: (service: ServiceChannel<AREvents>, images: ImageTarget[]) => Promise<void>;
+/** The twin of `setImages` for QR codes: replace the set of QR targets of a RUNNING session
+ *  without restarting it; a code no longer in the set stops driving its entity (`tracked: false`
+ *  once if it was tracked). Before `start`, the codes are `StartOptions.codes`. A half that tracks
+ *  no codes yet (the native ones) rejects "failed".
+ *  Contract version 2: an older half rejects the call — ask `supports("setCodes")`.
+ *  Rejects with "notRunning" / "failed". */
+export declare const setCodes: (service: ServiceChannel<AREvents>, codes: QRTarget[]) => 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).
@@ -35,7 +42,7 @@ export declare const release: (service: ServiceChannel<AREvents>, entity: Entity
  *  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";
+export type Method = "start" | "stop" | "setImages" | "setCodes" | "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;
@@ -55,6 +62,13 @@ export declare class ARBase extends ServiceChannel<AREvents> {
      *  `StartOptions.images`.
      *  Rejects with "notRunning" / "failed". */
     setImages(images: ImageTarget[]): Promise<void>;
+    /** The twin of `setImages` for QR codes: replace the set of QR targets of a RUNNING session
+     *  without restarting it; a code no longer in the set stops driving its entity (`tracked: false`
+     *  once if it was tracked). Before `start`, the codes are `StartOptions.codes`. A half that tracks
+     *  no codes yet (the native ones) rejects "failed".
+     *  Contract version 2: an older half rejects the call — ask `supports("setCodes")`.
+     *  Rejects with "notRunning" / "failed". */
+    setCodes(codes: QRTarget[]): 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).

package/dist/types/plugins/gen/audio-recorder/contract.d.ts

@@ -0,0 +1,64 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/audio-recorder/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.
+// audio-recorder — audio recording to a file: voice messages, voice notes.
+// A session is ONE recording (the app-facing `AudioRecorder` opens one per `start()`): start, pause
+// / resume, then `stop()` for the file or `cancel()` to discard it. The microphone permission is the
+// contract's (`@permission microphone` on start): the host asks, the halves never do.
+//
+// The format is the platform's encoder: AAC in an .m4a on iOS and Android, what the browser's
+// MediaRecorder gives on the web (webm/opus in Chrome and Firefox, mp4 in Safari) — `mimeType`
+// says which, the app's server decides whether to transcode.
+
+import type { File, Service, f64 } from "../../../plugin"
+
+export interface RecordOptions {
+  /** Kilobits per second of the encoded audio. Default 64 — speech; 128 for music. */
+  bitrate?: f64
+  /** Samples per second. Default 44100; the browser keeps its own. */
+  sampleRate?: f64
+  /** Stop on its own after this many ms: `ended` fires with "maxDuration", `stop()` then returns
+   *  the recording. Default: no limit. */
+  maxDuration?: f64
+}
+
+export type EndReason = "maxDuration" | "interrupted" | "failed"
+
+export interface Recording {
+  /** The audio file — `recording.m4a` / `.webm` / `.mp4` by the encoder. */
+  file: File
+  /** "audio/mp4", "audio/webm", … — the container, without codec parameters. */
+  mimeType: string
+  /** Seconds of audio (the pauses left out). */
+  duration: f64
+}
+
+export interface AudioRecorderParams {}
+
+export interface AudioRecorderEvents {
+  /** The input level, 0..1, about ten times a second while recording (not while paused): a meter,
+   *  a waveform. */
+  level: { value: f64 }
+  /** The recording stopped on its own: the limit (`maxDuration`), an interruption (a call came in),
+   *  a failure of the encoder. What was recorded is kept until `stop()` (which returns it) or
+   *  `cancel()`. */
+  ended: { reason: EndReason }
+}
+
+export interface AudioRecorder extends Service<"audioRecorder", AudioRecorderParams, AudioRecorderEvents> {
+  /** Start recording. One recording per session: a second start rejects "busy".
+   *  @permission microphone
+   *  @rejects busy failed */
+  start(options?: RecordOptions): Promise<void>
+  /** Pause: the level stops, the duration does not grow. Rejects "notRecording" before a start
+   *  or after the recording ended.
+   *  @rejects notRecording failed */
+  pause(): Promise<void>
+  /** @rejects notRecording failed */
+  resume(): Promise<void>
+  /** Stop and get the recording (also after `ended`: the file was kept). Rejects "failed" when
+   *  nothing could be encoded.
+   *  @rejects notRecording failed */
+  stop(): Promise<Recording>
+  /** Stop and discard. Nothing to discard is not an error. */
+  cancel(): Promise<void>
+}