lecodes-cli 0.1.6 → 0.2.0

package/runtime/sdk/gl/Scene.ts

@@ -0,0 +1,179 @@
+// A 3D scene: a draw set, a Camera, lights and environment. Opening a scene asks the host to bring up
+// the 3D engine; only the active scene renders. Grown from the Phase 0 seed. Ported from
+// worker/src/Scene.ts (Scene + ARScene), with the camera exposed as scene.camera.
+//
+// Lights are explicit: a scene gets image-based ambient (IBL) by default; add a Light.sun() for
+// direct light + shadows.
+
+import { Color, type ColorInput } from "../core/color"
+import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
+import type { FetchResponse } from "../runtime/fetch"
+import { Camera } from "./Camera"
+import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
+import { Material } from "./Material"
+import { Node, nodeRegistry } from "./Node"
+import { glState } from "./state"
+import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
+
+export type SceneOptions = {
+  /** Image-based ambient lighting (default on). */
+  ibl?: boolean
+  /** IBL intensity (default 20000). */
+  environmentIntensity?: number
+  /** Bloom post-processing. */
+  bloom?: boolean
+  bloomIntensity?: number
+  /** Skybox / clear color. */
+  skybox?: ColorInput
+  /** Multisample anti-aliasing. */
+  antialias?: boolean
+}
+
+export class Scene {
+  /** @internal native scene handle. */
+  readonly _id: number
+  readonly camera: Camera
+
+  /** @internal touch listeners, read by the dispatch system. */
+  readonly _clickListeners: Array<(ev: ClickEvent<Node | null>) => void> = []
+  readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node | null>) => void> = []
+
+  private _material?: Material
+
+  private static _active: Scene | null = null
+  static get active(): Scene | null { return Scene._active }
+
+  constructor(options: SceneOptions = {}) {
+    const parent = (options as any)._parent as Scene | undefined
+    if (parent) {
+      this.camera = parent.camera
+      this._id = _creator.createOverlayScene(parent._id)
+    } else {
+      this.camera = new Camera()
+      this._id = _creator.createScene()
+    }
+    this.camera._attach(this._id)
+
+    if (options.ibl !== false) _creator.setDefaultIbl(this._id, options.environmentIntensity ?? 20000)
+    if (options.bloom) _creator.setBloomOptions(this._id, true, options.bloomIntensity ?? 0.2, 1)
+    if (options.skybox !== undefined) _creator.setSkybox(this._id, Color.toPackedRgb(options.skybox))
+    if (options.antialias) _creator.setSceneMultiSampleAntiAliasing(this._id, true, 4)
+  }
+
+  /** Scene occlusion material. */
+  get occlusionMaterial(): Material {
+    if (!this._material) this._material = new Material(_creator.getSceneMaterial(this._id))
+    return this._material
+  }
+
+  set skybox(color: ColorInput) { _creator.setSkybox(this._id, Color.toPackedRgb(color)) }
+
+  setMaterialGlobalParameter(i: number, x: number, y: number, z: number, w: number): void {
+    _creator.setMaterialGlobalParameter(this._id, i, x, y, z, w)
+  }
+  setAntialias(enabled: boolean, scale = 4): void {
+    _creator.setSceneMultiSampleAntiAliasing(this._id, enabled, scale)
+  }
+
+  add(...nodes: Node[]): this {
+    for (const n of nodes) _creator.addEntityToScene(this._id, n.id)
+    return this
+  }
+  remove(...nodes: Node[]): this {
+    for (const n of nodes) _creator.removeEntityFromScene(this._id, n.id)
+    return this
+  }
+
+  createOverlay(options: SceneOptions = {}): Scene {
+    return new Scene({ ...options, _parent: this } as any)
+  }
+
+  warmRender(): Promise<void> {
+    return new Promise<void>((res) => _creator.warmRender(this._id, res))
+  }
+
+  /** Make this the active scene (brings up the 3D engine; closes any other). */
+  open(): void {
+    _creator.openScene(this._id)
+    Scene._active = this
+    glState.activeScene = this
+  }
+  close(): void {
+    _creator.closeScene()
+    if (Scene._active === this) Scene._active = null
+    if (glState.activeScene === this) glState.activeScene = null
+  }
+
+  addEventListener(channel: "click", callback: (ev: ClickEvent<Node | null>) => void): void
+  addEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<Node | null>) => void): void
+  addEventListener(channel: "click" | "touchstart", callback: (ev: any) => void): void {
+    if (channel === "click") {
+      if (!this._clickListeners.includes(callback)) { this._clickListeners.push(callback); registerTouchEndEvent() }
+    } else if (channel === "touchstart") {
+      if (!this._touchStartListeners.includes(callback)) { this._touchStartListeners.push(callback); registerTouchStartEvent() }
+    }
+  }
+  removeEventListener(channel: "click" | "touchstart", callback: (ev: any) => void): void {
+    const list = channel === "click" ? this._clickListeners : this._touchStartListeners
+    const i = list.indexOf(callback)
+    if (i >= 0) list.splice(i, 1)
+  }
+}
+
+// --- AR ---
+
+export type ARMode = "default" | "markers" | "arcore" | "detached"
+
+const onTrackStateChange = (entityId: number, track: boolean): void => {
+  const node = nodeRegistry.get(entityId)
+  if (!node) return
+  node.isTracked = track
+  if (track) node._dispatchEvent("track")
+  else node._dispatchEvent("untrack")
+}
+
+export class ARScene<T extends ARMode = "default"> extends Scene {
+  readonly mode: T
+  useWarmRender = true
+  private _root?: Node
+
+  constructor(options: SceneOptions & { mode?: T } = {}) {
+    super(options)
+    this.mode = options.mode ?? ("default" as T)
+    _creator.createARController(this._id, this.camera.id, this.mode, onTrackStateChange)
+  }
+
+  /** Root anchor node (not available in marker mode). */
+  get root(): Node {
+    if (this._root) return this._root
+    this._root = new Node(_creator.createRootAnchor(this._id))
+    return this._root
+  }
+
+  /** Create an anchor from a tracking source (e.g. an image target). */
+  createAnchor(source: FetchResponse, physicalWidth = 0.2): Node {
+    return new Node(_creator.createAnchor(this._id, physicalWidth, (source as any)._id))
+  }
+
+  /**
+   * Let the user place & manipulate a node with touch gestures — the staple AR object-placement
+   * interaction: ONE finger drags it across the floor (relative to where the camera looks), TWO fingers
+   * pinch to scale and twist to rotate. Returns a handle; call `.remove()` to detach. Tunable via
+   * options (min/max scale, and toggles for `pan` / `pinch` / `twist`).
+   */
+  addControls(target: Node, options: ControlsOptions = {}): ControlsHandle {
+    return attachControls(this, target, options)
+  }
+
+  override async open(): Promise<void> {
+    await new Promise<void>((res, rej) => _creator.requestCamera(res, rej))
+    if (this.useWarmRender) { _creator.createGLView(); await this.warmRender() }
+    await new Promise<void>((res, rej) => _creator.launchAR(this._id, res, rej))
+    super.open()
+  }
+
+  override close(): void {
+    _creator.stopAR()
+    super.close()
+  }
+}

package/runtime/sdk/gl/Texture.ts

@@ -0,0 +1,35 @@
+// A 3D GPU texture, decoded natively by creator-gl. Load from a URL or an already-fetched response.
+
+import { fetch, type FetchResponse } from "../runtime/fetch"
+
+export class Texture {
+  /** @internal native texture handle. */
+  readonly _id: number
+  readonly width: number
+  readonly height: number
+
+  /** Horizontal wrap mode (U). */
+  wrapS = 1
+  /** Vertical wrap mode (V). */
+  wrapT = 1
+
+  constructor(width: number, height: number, id: number) {
+    this.width = width
+    this.height = height
+    this._id = id
+  }
+
+  static load(source: string | FetchResponse): Promise<Texture> {
+    if (typeof source === "string") {
+      return fetch(source, { useOnce: true }).then((resp) => {
+        if (resp.status >= 400) {
+          return Promise.reject(new Error(`Failed to fetch texture from ${source}. HTTP ${resp.status}`))
+        }
+        return Texture.load(resp)
+      })
+    }
+    return new Promise<Texture>((resolve, reject) => {
+      _creator.createTexture((source as any)._id, (id, w, h) => resolve(new Texture(w, h, id)), reject)
+    })
+  }
+}

package/runtime/sdk/gl/controls.ts

@@ -0,0 +1,95 @@
+// AR object-placement controls — the classic "drop a model in the room and manipulate it" gesture
+// recipe: ONE finger drags the target across the ground plane (camera-relative), TWO fingers pinch to
+// scale and twist to rotate (yaw). Lives on ARScene (see Scene.ts) because it orchestrates the scene's
+// camera + touch input against a target node; it's built entirely on the public API (no native calls
+// the user couldn't make), so it's a convenience, not a primitive.
+
+import { Vec2, Vec3 } from "../math/vec"
+import { Quat } from "../math/quat"
+import type { Node } from "./Node"
+import type { Scene } from "./Scene"
+import type { TouchStartEvent } from "../runtime/touch"
+
+export type ControlsOptions = {
+  /** Smallest uniform scale the pinch gesture allows (default 0.08). */
+  minScale?: number
+  /** Largest uniform scale the pinch gesture allows (default 2). */
+  maxScale?: number
+  /** One-finger drag moves the target across the ground plane (default true). */
+  pan?: boolean
+  /** Two-finger pinch scales the target (default true). */
+  pinch?: boolean
+  /** Two-finger twist rotates the target around its Y axis (default true). */
+  twist?: boolean
+}
+
+/** Returned by `addControls` — call `remove()` to detach the gesture listeners. */
+export type ControlsHandle = { remove(): void }
+
+type ActiveTouch = { pointerId: number, x: number, y: number }
+
+const clamp = (v: number, lo: number, hi: number): number => (v < lo ? lo : v > hi ? hi : v)
+
+export const attachControls = (scene: Scene, target: Node, options: ControlsOptions = {}): ControlsHandle => {
+  const minScale = options.minScale ?? 0.08
+  const maxScale = options.maxScale ?? 2
+  const pan = options.pan ?? true
+  const pinch = options.pinch ?? true
+  const twist = options.twist ?? true
+
+  const active: ActiveTouch[] = []
+
+  const onTouchStart = (e: TouchStartEvent<Node | null>): void => {
+    const touch: ActiveTouch = { pointerId: e.pointerId, x: e.clientX, y: e.clientY }
+    active.push(touch)
+    e.track({
+      onMove(m) {
+        if (active.length === 2) {
+          // --- two-finger: pinch-scale + twist-rotate about the gesture axis ---
+          const other = active.find((t) => t !== touch)
+          if (other) {
+            const axis = new Vec2(other.x - touch.x, other.y - touch.y)
+            const span = axis.length()
+            if (span > 1e-3) {
+              const dir = axis.scale(1 / span)
+              const delta = new Vec2(m.deltaX, m.deltaY)
+              if (pinch) {
+                const along = -dir.dot(delta) // movement along the pinch axis
+                target.scale = clamp(target.scale.x * (span + along) / span, minScale * 0.4, maxScale * 1.5)
+              }
+              if (twist) {
+                const tangent = dir.perp().dot(delta) // movement across the axis
+                target.quaternion = target.quaternion.mul(Quat.fromAxisAngle(Vec3.up, Math.atan2(tangent, span)))
+              }
+            }
+          }
+        } else if (active.length === 1 && pan) {
+          // --- one-finger: drag across the ground plane, relative to where the camera looks ---
+          let dir = scene.camera.forward
+          const parent = target.parent
+          if (parent) dir = dir.rotate(parent.quaternion.invert()) // into the parent's local frame
+          dir = dir.withY(0)
+          const k = Math.hypot(dir.x, dir.z)
+          const screen = Math.max(...scene.camera.displaySize)
+          if (k > 1e-4 && screen > 0) {
+            const dist = target.worldPosition.distanceTo(scene.camera.worldPosition)
+            const right = new Vec3(-dir.z, 0, dir.x).scale(m.deltaX / k / screen * dist)
+            const fwd = dir.scale(-m.deltaY / k / screen * dist)
+            const move = right.add(fwd)
+            const p = target.position
+            target.position = new Vec3(p.x + move.x, p.y, p.z + move.z) // keep height fixed
+          }
+        }
+        touch.x = m.clientX
+        touch.y = m.clientY
+      },
+      onEnd() {
+        const i = active.indexOf(touch)
+        if (i >= 0) active.splice(i, 1)
+      },
+    })
+  }
+
+  scene.addEventListener("touchstart", onTouchStart)
+  return { remove() { scene.removeEventListener("touchstart", onTouchStart); active.length = 0 } }
+}

package/runtime/sdk/gl/state.ts

@@ -0,0 +1,6 @@
+// Tiny shared module to break the Node ↔ Scene ↔ touch dependency cycle. The active 3D scene is set
+// here by Scene.open()/close() and read by the touch dispatch system.
+
+import type { Scene } from "./Scene"
+
+export const glState: { activeScene: Scene | null } = { activeScene: null }

package/runtime/sdk/gl/touch.ts

@@ -0,0 +1,56 @@
+// 3D pointer dispatch. Registers the host touch callbacks lazily (first listener) and routes hits to
+// the struck Node and to the active scene's listeners. Ported from worker/src/TouchEventSystem.ts.
+
+import { ClickEvent, TouchStartEvent, type TrackHandler } from "../runtime/touch"
+import { nodeRegistry } from "./Node"
+import { glState } from "./state"
+
+const onTouchEnd = (pointerId: number, clientX: number, clientY: number, entityId: number): TrackHandler | null => {
+  const scene = glState.activeScene
+  if (!scene) return null
+  const ev = new ClickEvent<any>(clientX, clientY, pointerId)
+  if (entityId > 0) {
+    const node = nodeRegistry.get(entityId) ?? null
+    ev.target = node
+    if (node) node._dispatchEvent("click", ev)
+  } else {
+    ev.target = null
+  }
+  for (const listener of scene._clickListeners.slice()) listener(ev)
+  return null
+}
+
+const onTouchStart = (pointerId: number, clientX: number, clientY: number, entityId: number): TrackHandler | null => {
+  const scene = glState.activeScene
+  if (!scene) return null
+  const ev = new TouchStartEvent<any>(clientX, clientY, pointerId)
+  if (entityId > 0) {
+    const node = nodeRegistry.get(entityId) ?? null
+    ev.target = node
+    if (node) {
+      node._dispatchEvent("touchstart", ev)
+      if (ev._trackHandler) return ev._trackHandler
+    }
+  } else {
+    ev.target = null
+  }
+  for (const listener of scene._touchStartListeners.slice()) {
+    listener(ev)
+    if (ev._trackHandler) return ev._trackHandler
+  }
+  return null
+}
+
+let touchStartRegistered = false
+export const registerTouchStartEvent = (): void => {
+  if (touchStartRegistered) return
+  touchStartRegistered = true
+  _creatorUI.registerTouchStartEvent(onTouchStart)
+}
+
+let touchEndRegistered = false
+export const registerTouchEndEvent = (): void => {
+  if (touchEndRegistered) return
+  touchEndRegistered = true
+  _creatorUI.registerTouchEndEvent(onTouchEnd)
+}

package/runtime/sdk/inject.ts

@@ -0,0 +1,85 @@
+// THE aggregation point. Every public global the SDK provides is re-exported here under the exact
+// name user code uses it as. The bundler passes this file to esbuild's `inject:` option, so user
+// code references `Scene`, `Sprite`, `toast`, … with no imports; esbuild tree-shakes away whatever
+// a given project does not use (so a pure-2D project drops all 3D classes, and vice versa).
+//
+// Rule: this is the ONLY file that `export`s public names. Everything else is internal and imported
+// by it. Host-provided globals (setLoop, console, setTimeout, DEG2RAD, asset, …) are NOT here —
+// they live in src/host.d.ts as declarations and stay as free references at runtime.
+
+// ---- math ----
+export { Mathf } from "./math/Mathf"
+export { Vec2, Vec3 } from "./math/vec"
+export { Quat } from "./math/quat"
+export { Mat4 } from "./math/mat4"
+export { Color } from "./core/color"
+
+// ---- aspects (attachable node capabilities) ----
+export { Aspect, type With } from "./core/Aspect"
+
+// ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
+export { toast, SvgSource } from "./runtime/misc"
+export { fetch, fetchLocal, FormData, File } from "./runtime/fetch"
+export { localStorage } from "./runtime/storage"
+export { device } from "./runtime/device"
+export { Input } from "./runtime/input"
+export { WebSocket } from "./runtime/net"
+export { AudioPlayer, VideoPlayer } from "./runtime/media"
+export { openFilePicker } from "./runtime/files"
+export { ClickEvent, TouchStartEvent } from "./runtime/touch"
+
+// ---- 2D engine (creator-2d) ----
+export { Scene2D } from "./g2/Scene2D"
+export { Node2D } from "./g2/Node2D"
+export { Camera2D } from "./g2/Camera2D"
+export { Sprite } from "./g2/Sprite"
+export { SpriteAnimation } from "./g2/SpriteAnimation"
+export { Shape } from "./g2/Shape"
+export { Physics2D } from "./g2/Physics2D"
+export { Trigger } from "./g2/Trigger"
+export { CharacterController2D } from "./g2/CharacterController2D"
+export { Tilemap } from "./g2/Tilemap"
+export { Texture2D } from "./g2/Texture2D"
+
+// ---- UI (creator-ui) ----
+export {
+  UIScreen, type UIScreenStyle,
+  UIRow, UIColumn, UIBox, type UIContainerStyle,
+  UIText, type UITextStyle,
+  UIButton, type UIButtonStyle,
+  UIImage, type UIImageStyle,
+  UIVideo, type UIVideoStyle,
+  UIInput, UITextArea, type UIInputStyle,
+  UIScrollable, type UIScrollableStyle,
+  UIWidget, type UIWidgetStyle,
+  UISpacer, type UISpacerStyle,
+  UIVirtualizedList,
+  Router,
+  registerFont,
+} from "./ui/UI"
+
+// ---- animate ----
+export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate"
+export { cubicBezier } from "./animate/bezier"
+export { easeIn, easeOut, easeInOut } from "./animate/easings"
+
+// ---- plugins (optional, host-provided capabilities — see src/plugins/) ----
+export { QRScanner } from "./plugins/qr"
+
+// ---- 3D engine (creator-gl) ----
+export { Scene, ARScene } from "./gl/Scene"
+export { Node } from "./gl/Node"
+export { Mesh } from "./gl/Mesh"
+export { Model } from "./gl/Model"
+export { Physics } from "./gl/Physics"
+export { Collider } from "./gl/Collider"
+export { ModelAnimation } from "./gl/ModelAnimation"
+export { Light } from "./gl/Light"
+export { Material } from "./gl/Material"
+export { Geometry } from "./gl/Geometry"
+export { Texture } from "./gl/Texture"
+export { Camera } from "./gl/Camera"
+export { Ray } from "./gl/Ray"
+export { Plane } from "./gl/Plane"
+export { Noise } from "./gl/Noise"
+export { Particles, dynamic, dynamicColor } from "./gl/Particles"

package/runtime/sdk/math/Mathf.ts

@@ -0,0 +1,118 @@
+// Scalar / general math helpers, exposed to user code as the `Mathf` global. Vector & quaternion
+// helpers live with the engine that uses them (vec2 in g2/, vec3+quat in gl/). `smoothDamp` works on
+// both numbers and numeric arrays here (no gl-matrix), which covers 2D (vec2) and 3D position damping.
+
+export type Damper<T extends number | number[]> = ((target: T, dt: number) => T) & {
+  /** Snap the damper's internal current value (e.g. on teleport). */
+  setValue(value: T): void
+}
+
+const clamp = (v: number, min: number, max: number): number => (v < min ? min : v > max ? max : v)
+
+const smoothDampNumber = (initial: number, smoothTime: number, maxSpeed: number): Damper<number> => {
+  let current = initial
+  let velocity = 0
+  const damp = ((target: number, dt: number): number => {
+    smoothTime = Math.max(0.0001, smoothTime)
+    const omega = 2 / smoothTime
+    const x = omega * dt
+    const exp = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x)
+    const maxDelta = maxSpeed * smoothTime
+    let delta = clamp(current - target, -maxDelta, maxDelta)
+    const newTarget = current - delta
+    const temp = (velocity + omega * delta) * dt
+    velocity = (velocity - omega * temp) * exp
+    current = newTarget + (delta + temp) * exp
+    return current
+  }) as Damper<number>
+  damp.setValue = (v) => { current = v; velocity = 0 }
+  return damp
+}
+
+function smoothDamp(initial: number, smoothTime: number, maxSpeed?: number): Damper<number>
+function smoothDamp(initial: number[], smoothTime: number, maxSpeed?: number): Damper<number[]>
+function smoothDamp(initial: any, smoothTime: number, maxSpeed = Infinity): any {
+  return typeof initial === "number"
+    ? smoothDampNumber(initial, smoothTime, maxSpeed)
+    : smoothDampArray(initial, smoothTime, maxSpeed)
+}
+
+const smoothDampArray = (initial: number[], smoothTime: number, maxSpeed: number): Damper<number[]> => {
+  const n = initial.length
+  let current = initial.slice()
+  const velocity = new Array(n).fill(0)
+  const damp = ((target: number[], dt: number): number[] => {
+    smoothTime = Math.max(0.0001, smoothTime)
+    const omega = 2 / smoothTime
+    const x = omega * dt
+    const exp = 1 / (1 + x + 0.48 * x * x + 0.235 * x * x * x)
+    const maxDelta = maxSpeed * smoothTime
+
+    const delta = new Array(n)
+    let mag = 0
+    for (let i = 0; i < n; i++) { delta[i] = current[i] - target[i]; mag += delta[i] * delta[i] }
+    mag = Math.sqrt(mag)
+    if (mag > maxDelta && mag > 0) {
+      const s = maxDelta / mag
+      for (let i = 0; i < n; i++) delta[i] *= s
+    }
+
+    const out = new Array(n)
+    for (let i = 0; i < n; i++) {
+      const newTarget = current[i] - delta[i]
+      const temp = (velocity[i] + omega * delta[i]) * dt
+      velocity[i] = (velocity[i] - omega * temp) * exp
+      out[i] = newTarget + (delta[i] + temp) * exp
+    }
+    current = out
+    return out.slice()
+  }) as Damper<number[]>
+  damp.setValue = (v) => { current = v.slice(); velocity.fill(0) }
+  return damp
+}
+
+export const Mathf = {
+  PI: Math.PI,
+  TAU: Math.PI * 2,
+  EPSILON: 1e-6,
+  DEG2RAD: Math.PI / 180,
+  RAD2DEG: 180 / Math.PI,
+
+  deg2rad: (deg: number): number => deg * (Math.PI / 180),
+  rad2deg: (rad: number): number => rad * (180 / Math.PI),
+
+  clamp,
+  clamp01: (v: number): number => clamp(v, 0, 1),
+  lerp: (a: number, b: number, t: number): number => a + (b - a) * t,
+  inverseLerp: (a: number, b: number, v: number): number => (a === b ? 0 : (v - a) / (b - a)),
+  remap: (v: number, inMin: number, inMax: number, outMin: number, outMax: number): number =>
+    outMin + ((v - inMin) / (inMax - inMin)) * (outMax - outMin),
+
+  /** Move `a` toward `b` by at most `maxDelta`. */
+  moveTowards: (a: number, b: number, maxDelta: number): number => {
+    const d = b - a
+    return Math.abs(d) <= maxDelta ? b : a + Math.sign(d) * maxDelta
+  },
+  /** Frame-rate-independent exponential approach (good default: lambda 5..15). */
+  damp: (a: number, b: number, lambda: number, dt: number): number => a + (b - a) * (1 - Math.exp(-lambda * dt)),
+
+  sign: Math.sign,
+  /** Loop a value into [0, length). */
+  repeat: (t: number, length: number): number => clamp(t - Math.floor(t / length) * length, 0, length),
+  /** Ping-pong a value in [0, length]. */
+  pingPong: (t: number, length: number): number => {
+    const r = clamp(t - Math.floor(t / (length * 2)) * (length * 2), 0, length * 2)
+    return length - Math.abs(r - length)
+  },
+
+  random: (min = 0, max = 1): number => min + Math.random() * (max - min),
+  randomInt: (min: number, max: number): number => Math.floor(min + Math.random() * (max - min + 1)),
+
+  /**
+   * Critically-damped follow (Unity SmoothDamp). Returns a stateful damper you call every frame:
+   *   const d = Mathf.smoothDamp([x, y], 0.15)
+   *   pos = d(targetPos, dt)
+   * Works on a number or a numeric array (vec2 / vec3).
+   */
+  smoothDamp,
+}