lecodes-sdk 2.4.1 → 2.4.3

package/src/gl/vehicle/Vehicle.ts

@@ -28,8 +28,8 @@
 // `Wheel` aspect of the wheel's own node (which is where Jolt keeps it too); Vehicle collects every
 // Wheel under itself and groups them into axles by Z.
 //
-// The engine gets NUMBERS: the blob of settings (`_buildSettings`, live re-tunable) and one input
-// vector per frame. It never shapes them — no taper, no rate limit, no gearbox, no idle governor.
+// The engine gets NUMBERS: the blob of settings (`_buildSettings`: its tuning half re-sent from
+// `flush()` whenever a live value of the car or a wheel is written) and one input vector per frame. It never shapes them — no taper, no rate limit, no gearbox, no idle governor.
 //
 // Chassis space is forward −Z / up +Y — the SDK's own convention, the one `node.forward` reports: if
 // the model faces the other way, rotate the MODEL (a child), never the chassis node. Physics owns the
@@ -175,6 +175,12 @@ export interface AeroConfig {
   drag?: number
 }
 
+// The three groups' defaults — every key the live views carry (a key left out of an assigned object
+// takes the value here). `curve` / `feedback` / `driver` default to "not given", as the blob reads them.
+const ENGINE_DEFAULTS: EngineConfig = { torque: 500, maxRpm: 6000, idleRpm: 1000, curve: undefined, inertia: 0.5, braking: 0.2 }
+const STEERING_DEFAULTS: SteeringConfig = { maxAngle: 35, caster: 0.03, trail: 0.025, trailAtPeak: 0.5, feedback: undefined, driver: undefined }
+const AERO_DEFAULTS: AeroConfig = { downforce: 0, drag: 0.03 }
+
 /** Blob v15 — see bridges.d.ts for the field-by-field layout. */
 const BLOB_VERSION = 15
 const BLOB_HEADER = 34
@@ -199,21 +205,42 @@ export class Vehicle extends Aspect<"vehicle", Node> {
    *  (`id` stays 0, with a warning). */
   static get supported(): boolean { return Physics.supported && typeof _creator.vehicleCreate === "function" }
 
-  /** Chassis mass in kg (default 1200). Wheels are massless in this model. */
-  mass = 1200
+  // ---- the car as hardware. LIVE (a write reaches the engine before the next step — a drift button
+  // is `car.vehicle.differential = 'locked'`): differential, antiRoll, maxTilt, friction,
+  // clutchStrength, clutchCapacity, and the three groups engine / steering / aero (write a field, or
+  // assign a whole object: what it leaves out is the default). STRUCTURAL (baked when the car is
+  // built — build it again with `car.aspect(Vehicle, {…})`, which resets its motion): mass,
+  // centerOfMass, driveAxle, and which wheels exist, where, with what width and travel.
+
+  private _mass = 1200
+  /** 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 { return this._mass }
+  set mass(v: number) {
+    if (this._id && v !== this._builtMass) {
+      console.warn(`Vehicle: mass is fixed once the body exists (still ${this._builtMass} kg) — build the aspect again to change it`)
+      return
+    }
+    this._mass = v
+  }
   /** 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 = "rear"
+
+  private _differential: DifferentialMode | number = "lsd"
   /** 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 = "lsd"
+   *  together, so the pair lets go as a pair. Live: switch it mid-drive. */
+  get differential(): DifferentialMode | number { return this._differential }
+  set differential(v: DifferentialMode | number) { this._differential = v; this.dirty() }
+  private _antiRoll: boolean | number = true
   /**
    * 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%
@@ -223,25 +250,44 @@ export 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 = true
-  /** Pitch/roll limit in degrees (default 60) before the constraint rights the car. 180 turns it off. */
-  maxTilt = 60
+  get antiRoll(): boolean | number { return this._antiRoll }
+  set antiRoll(v: boolean | number) { this._antiRoll = v; this.dirty() }
+  private _maxTilt = 60
+  /** Pitch/roll limit in degrees (default 60) before the constraint rights the car. 180 turns it off. Live. */
+  get maxTilt(): number { return this._maxTilt }
+  set maxTilt(v: number) { this._maxTilt = v; this.dirty() }
+  private _friction = DEFAULT_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 = DEFAULT_FRICTION
+   *  to do with the tires; those are the `Wheel`'s `tire` × the ground's friction. Live, at once. */
+  get friction(): number { return this._friction }
+  set friction(v: number) { this._friction = v; if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, v) }
+  private _clutchStrength = 10
   /** 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 = 10
+   *  engine to the wheels. `clutch` (the input) scales it 0..1. Live. */
+  get clutchStrength(): number { return this._clutchStrength }
+  set clutchStrength(v: number) { this._clutchStrength = v; this.dirty() }
+  private _clutchCapacity = 0
   /** 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 = 0
-
-  engine: EngineConfig = { torque: 500, maxRpm: 6000, idleRpm: 1000, inertia: 0.5, braking: 0.2 }
-  steering: SteeringConfig = { maxAngle: 35 }
-  aero: AeroConfig = { downforce: 0, drag: 0.03 }
+   *  of lurching. A road car's is ~1.5× the engine's peak torque. Live. */
+  get clutchCapacity(): number { return this._clutchCapacity }
+  set clutchCapacity(v: number) { this._clutchCapacity = v; this.dirty() }
+
+  private _engine = this.live(ENGINE_DEFAULTS)
+  /** The engine (`EngineConfig`). Live: `car.vehicle.engine.torque = 800`, or assign a whole config. */
+  get engine(): EngineConfig { return this._engine }
+  set engine(v: EngineConfig) { this._engine = this.live(ENGINE_DEFAULTS, v); this.dirty() }
+  private _steering = this.live(STEERING_DEFAULTS)
+  /** 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 { return this._steering }
+  set steering(v: SteeringConfig) { this._steering = this.live(STEERING_DEFAULTS, v); this.dirty() }
+  private _aero = this.live(AERO_DEFAULTS)
+  /** Aerodynamics (`AeroConfig`). Live: a wing that deploys is `car.vehicle.aero.downforce = 0.6`. */
+  get aero(): AeroConfig { return this._aero }
+  set aero(v: AeroConfig) { this._aero = this.live(AERO_DEFAULTS, v); this.dirty() }
 
   /** Scene-editor inspector: the flat, tunable half. The grouped objects are edited in code. */
   static fields: FieldMeta<Vehicle> = {
@@ -276,9 +322,33 @@ export class Vehicle extends Aspect<"vehicle", Node> {
   private _input = new Float32Array(INPUT_FIXED)
   private _sent = new Float32Array(INPUT_FIXED)
   private _dirty = true          // an input write since the last send
-  private _retunePending = false
+  private _rebuildPending = false
+
+  onAttach(): void { this._setup(false) }
+  onDetach(): void { this._teardown() }
+
+  /** 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 {
+    if (this._rebuildPending) {
+      // A wheel came or went: the constraint is built again around the wheels that are there now,
+      // where the car stands, its motion reset (the inputs are kept and re-sent).
+      this._rebuildPending = false
+      this._teardown()
+      this._setup(true)
+      return
+    }
+    if (this._id) _creator.vehicleSetTuning?.(this._id, this._buildSettings())
+  }
+
+  /** @internal A wheel's live value changed: retune with the next flush. */
+  _retune(): void { this.dirty() }
+  /** @internal A wheel was built or removed under a live car: rebuild with the next flush. */
+  _rebuildSoon(): void { if (this._id) { this._rebuildPending = true; this.dirty() } }
 
-  onAttach(): void {
+  // `rebuild` = from flush(), after a wheel change: an author error that attach throws on is a
+  // warning here, and the car stays torn down until the next change.
+  private _setup(rebuild: boolean): void {
     if (!Physics.supported) return
     if (!_creator.vehicleCreate) {
       console.warn("Vehicle: this host has no vehicle model (Vehicle.supported is false) — the car will not move")
@@ -297,7 +367,9 @@ export class Vehicle extends Aspect<"vehicle", Node> {
 
     this._wheels = this._collectWheels()
     if (this._wheels.length === 0) {
-      throw new Error("Vehicle found no wheels — put a Wheel aspect on each wheel node under the chassis: hubFL.aspect(Wheel)")
+      const msg = "Vehicle found no wheels — put a Wheel aspect on each wheel node under the chassis: hubFL.aspect(Wheel)"
+      if (rebuild) { console.warn(msg); return }
+      throw new Error(msg)
     }
 
     const shapeId = shape._claim()  // the vehicle owns the shape; drop the pick-only body
@@ -324,7 +396,7 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     this._dirty = true
   }
 
-  onDetach(): void {
+  private _teardown(): void {
     if (this._id) { _creator.vehicleDestroy(this._id); this._id = 0; this._bodyId = 0 }
     for (const w of this._wheels) w._vehicle = null
     this._wheels = []
@@ -333,31 +405,6 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     this.node.get(Shape)?._recreatePickBody()   // hands the routing back to the pick body
   }
 
-  /**
-   * 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 {
-    if (!this._id) return
-    if (this.mass !== this._builtMass) {
-      console.warn(`Vehicle: mass is fixed once the body exists (still ${this._builtMass} kg) — re-add the aspect to change it`)
-      this.mass = this._builtMass
-    }
-    this._retunePending = true
-    if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, this.friction)
-  }
-
-  /** @internal A wheel's tire changed: re-send the tuning before the next step (one send however
-   *  many wheels changed this frame). */
-  _retuneSoon(): void { this._retunePending = true }
 
   /** Native vehicle id (0 until attached / no physics support). */
   get id(): number { return this._id }
@@ -395,15 +442,12 @@ export 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 {
     if (!this._id) return
-    if (this._retunePending) {
-      this._retunePending = false
-      _creator.vehicleSetTuning?.(this._id, this._buildSettings())
-    }
     const input = this._input
     input[0] = this._throttle
     input[1] = this._steer
@@ -567,7 +611,7 @@ export class Vehicle extends Aspect<"vehicle", Node> {
       const w = found[i]!
       const a = axleOf[i]!
       const measured = w._measure()
-      w.radius ??= measured.radius
+      w._radius ??= measured.radius
       w.width ??= measured.width
       w.steer ??= a === 0
       w.driven ??= this.driveAxle === "none" ? 0 : this.driveAxle === "all" ? 1 : (this.driveAxle === "front" ? a === 0 : a === maxAxle) ? 1 : 0

package/src/gl/vehicle/Wheel.ts

@@ -138,13 +138,28 @@ export function resolveTire(tire: Tire): ResolvedTire {
   }
 }
 
+/** `suspension`'s defaults — every key the live view carries. */
+const SUSPENSION_DEFAULTS: Required<WheelSuspension> = { travel: 0.4, stiffness: 1.4, damping: 0.5 }
+
+/**
+ * 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 class Wheel extends Aspect<"wheel", Node> {
   static readonly aspect = "wheel"
 
+  /** @internal the radius as given, or as measured at bind (`radius` reads it). */
+  _radius?: number
   /** 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 { return this._radius }
+  set radius(v: number | undefined) { this._radius = v; this.dirty() }
+  /** 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. */
@@ -157,10 +172,20 @@ export class Wheel extends Aspect<"wheel", Node> {
    *  `0.2` on each rear. Structural: baked at attach. */
   driven?: number
 
-  suspension: WheelSuspension = { travel: 0.4, stiffness: 1.4, damping: 0.5 }
-  /** 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 = Tire.road()
+  private _suspension = this.live(SUSPENSION_DEFAULTS)
+  /** 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 { return this._suspension }
+  set suspension(v: WheelSuspension) { this._suspension = this.live(SUSPENSION_DEFAULTS, v); this.dirty() }
+
+  private _tire = this.live(Tire.road())
+  /** 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 { return this._tire }
+  set tire(v: Tire) { this._tire = this.live(Tire.road(), v); this.dirty() }
 
   /** 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
@@ -189,15 +214,24 @@ export class Wheel extends Aspect<"wheel", Node> {
   /** @internal Resting centre in chassis space (what the author placed). */
   _rest = new Vec3()
 
+  /** 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 {
+    for (let n: Node | null = this.node.parent; n; n = n.parent) {
+      const v = (n as unknown as { vehicle?: Vehicle }).vehicle
+      if (v) { v._rebuildSoon(); return }
+    }
+  }
+
   onDetach(): void {
+    this._vehicle?._rebuildSoon()   // one wheel fewer: the car is built again around what is left
     this._vehicle = null
     this._index = -1
   }
 
-  /** 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 {
-    this._vehicle?._retuneSoon()
+  /** A live value changed (the tire, the radius, the spring): the car retunes in the same flush. */
+  protected flush(): void {
+    this._vehicle?._retune()
   }
 
   /** @internal Called by Vehicle once the car exists, with the geometry it resolved. */

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

@@ -5,6 +5,10 @@
 // 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 qr-anchor's on every platform: its wasm in the WebXR arm,
+// its C ABI on ARKit / ARCore (the plain-camera web arm tracks none and says so).
 import type { Service, File, Entity, Scene3D, f64 } from "../../../plugin"
 
 export type ARMode = "world" | "images"
@@ -31,6 +35,20 @@ export interface ImageTarget {
   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. WebXR, ARKit and
+ *  ARCore; a half without a detector (the plain-camera web arm) tracks none. */
+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). */
@@ -38,6 +56,9 @@ export interface StartOptions {
   /** 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. */
@@ -76,7 +97,8 @@ export interface AREvents {
   /** 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. */
+   *  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 }
@@ -86,6 +108,11 @@ export interface AREvents {
   /** 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> {
@@ -102,6 +129,13 @@ export interface AR extends Service<"ar", ARParams, AREvents> {
    *  `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 (the plain-camera web arm) 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).

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

@@ -1,18 +1,19 @@
 // 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.
+// ar: the service "ar", contract version 2.
 
 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"
+import type { AREvents, ARParams, HitResult, HitTarget, ImageTarget, Pose, QRTarget, 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
+export const VERSION = 2
 
-const _fromStartOptions = (v: StartOptions): any => ({ ...v, images: v.images === undefined ? undefined : v.images.map((x: any) => _fromImageTarget(x)) })
+const _fromStartOptions = (v: StartOptions): any => ({ ...v, images: v.images === undefined ? undefined : v.images.map((x: any) => _fromImageTarget(x)), codes: v.codes === undefined ? undefined : v.codes.map((x: any) => _fromQRTarget(x)) })
 const _fromImageTarget = (v: ImageTarget): any => ({ ...v, image: _fromFile(v.image), entity: _fromEntity(v.entity) })
+const _fromQRTarget = (v: QRTarget): any => ({ ...v, 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. */
@@ -42,6 +43,15 @@ export const stop = (service: ServiceChannel<AREvents>): Promise<void> =>
 export const setImages = (service: ServiceChannel<AREvents>, images: ImageTarget[]): Promise<void> =>
   service._call("setImages", [images.map((x: any) => _fromImageTarget(x))])
 
+/** 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 (the plain-camera web arm) rejects "failed".
+ *  Contract version 2: an older half rejects the call — ask `supports("setCodes")`.
+ *  Rejects with "notRunning" / "failed". */
+export const setCodes = (service: ServiceChannel<AREvents>, codes: QRTarget[]): Promise<void> =>
+  service._call("setCodes", [codes.map((x: any) => _fromQRTarget(x))], 2)
+
 /** 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).
@@ -68,12 +78,14 @@ export const captureFrame = (service: ServiceChannel<AREvents>): Promise<File> =
 // ---- what the host's half has --------------------------------------------------------------------
 
 /** 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"
+
+const SINCE: { [method: string]: number } = { setCodes: 2 }
 
 /** 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
+  ServiceChannel.supports(NAME, method === undefined ? 1 : SINCE[method] ?? 1)
 
 // ---- the client -----------------------------------------------------------------------------------
 
@@ -94,6 +106,13 @@ export class ARBase extends ServiceChannel<AREvents> {
    *  `StartOptions.images`.
    *  Rejects with "notRunning" / "failed". */
   setImages(images: ImageTarget[]): Promise<void> { return setImages(this, images) }
+  /** 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 (the plain-camera web arm) rejects "failed".
+   *  Contract version 2: an older half rejects the call — ask `supports("setCodes")`.
+   *  Rejects with "notRunning" / "failed". */
+  setCodes(codes: QRTarget[]): Promise<void> { return setCodes(this, codes) }
   /** 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).