lecodes-sdk 2.2.9 → 2.2.11

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

@@ -0,0 +1,104 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/speech/sdk/speech.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.
+// SpeechRecognizer — speech recognition: the microphone to text, live (dictation, voice commands).
+//
+// Hand-written over the generated wire because the app's object is not the wire's session: a
+// `SpeechRecognizer` is reusable — every `start()` opens a fresh host session (one listening),
+// `end` closes it — and its events are the SDK's `addEventListener` pattern.
+//
+// The permissions (speech recognition, the microphone) are asked by the host on `start()` (the
+// contract's `@permission`); to ask earlier, or to act on a denial, `permissions`.
+
+import { Emitter } from "../../../../plugin"
+import { SpeechBase, NAME } from "./speech.gen"
+import type { SpeechErrorCode, SpeechOptions, SpeechResult } from "../contract"
+
+export type { SpeechErrorCode, SpeechOptions, SpeechResult }
+
+export type SpeechRecognizerEvents = {
+  /** A result: partials while the user speaks (`interimResults`), then the final one. */
+  result: (result: SpeechResult) => void
+  /** The user started speaking. */
+  speechStart: () => void
+  /** The user stopped speaking: the final result follows. */
+  speechEnd: () => void
+  /** The listening is over — after the final result, after `stop()` / `abort()`, after an error. */
+  end: () => void
+  /** The listening failed; `end` follows. */
+  error: (code: SpeechErrorCode, message: string) => void
+}
+
+/**
+ * Recognizes speech from the microphone. `SpeechRecognizer.isSupported` reports whether this host
+ * registered the service — check it before showing a dictation button.
+ *
+ * ```ts
+ * const speech = new SpeechRecognizer()
+ * speech.addEventListener('result', r => input.value = r.transcript)
+ * speech.addEventListener('end', () => micButton.style({ opacity: 1 }))
+ * await speech.start({ language: 'en-US' })
+ * ```
+ */
+export class SpeechRecognizer extends Emitter<SpeechRecognizerEvents> {
+  /** Whether this host registered a "speech" service. */
+  static get isSupported(): boolean { return SpeechBase.supports(NAME) }
+
+  private _session: SpeechBase | null = null
+
+  /** Whether a listening is under way. */
+  get listening(): boolean { return this._session !== null }
+
+  /** Start listening. The host asks for the permissions first; rejects `"denied"` when refused,
+   *  `"unavailable"` when there is no recognizer for the language or on the device, and before
+   *  touching the host when the plugin is not there or a listening is under way. */
+  async start(options?: SpeechOptions): Promise<void> {
+    if (!SpeechRecognizer.isSupported) {
+      throw new Error('SpeechRecognizer isn\'t available on this host — it needs a registered "speech" service.')
+    }
+    if (this._session) throw new Error("SpeechRecognizer: a listening is under way — stop() or abort() it first")
+    const session = new SpeechBase()
+    session.on("result", result => { if (result && this._session === session) this.dispatch("result", result) })
+    session.on("speechStart", () => { if (this._session === session) this.dispatch("speechStart") })
+    session.on("speechEnd", () => { if (this._session === session) this.dispatch("speechEnd") })
+    session.on("error", payload => { if (payload && this._session === session) this.dispatch("error", payload.code, payload.message) })
+    session.on("end", () => {
+      if (this._session !== session) return
+      this._drop(session)
+      this.dispatch("end")
+    })
+    this._session = session
+    try {
+      await session.start(options ?? {})
+    } catch (e) {
+      this._drop(session)
+      throw e
+    }
+  }
+
+  /** Stop listening and finish: the final result of what was heard, then `end`. */
+  stop(): void {
+    this._session?.stop().catch(() => {})
+  }
+
+  /** Stop and drop what was heard: `end`, no result. */
+  abort(): void {
+    this._session?.abort().catch(() => {})
+  }
+
+  /** The languages this host recognizes (BCP-47), sorted; empty when it cannot say (the web). */
+  static async supportedLanguages(): Promise<string[]> {
+    if (!SpeechRecognizer.isSupported) return []
+    const session = new SpeechBase()
+    try {
+      return await session.supportedLanguages()
+    } finally {
+      session.close()
+    }
+  }
+
+  private _drop(session: SpeechBase): void {
+    if (this._session !== session) return
+    session.close()
+    this._session = null
+  }
+}

package/src/runtime/media.ts

@@ -7,10 +7,14 @@
 // then; a paused player you stop referencing is released at once. There is nothing to dispose. The
 // end-of-playback report comes by id through ONE emitter per world; a playing player is pinned so
 // the report finds it.
+//
+// `src` is a url, or a `File` / `FetchResponse`: those play from the host's buffer store
+// (`"id:<bufferId>"`, the whole bytes in memory, no streaming).
 
 import { Emitter } from "../core/events"
 import { Pins } from "../core/pins"
 import { Texture } from "../gl/Texture"
+import type { File, FetchResponse } from "./fetch"
 
 type MediaEvents = {
   /** Fired at each loop boundary while `loop` is true. */
@@ -30,6 +34,9 @@ const ensureEmitter = (): void => {
   emitterInstalled = true
   m.setEmitter((id) => { players.get(id)?._finished() })
 }
+/** The wire spelling of a source: a url as is, a buffer (File / FetchResponse) as "id:<bufferId>". */
+const wireSrc = (src?: string | File | FetchResponse): string =>
+  src == null ? "" : typeof src === "string" ? src : "id:" + (src as any)._h.id
 
 abstract class MediaPlayer extends Emitter<MediaEvents> {
   /** @internal The player's owned handle (`_h.id` = the host player id; -1 = no host player). */
@@ -92,18 +99,18 @@ abstract class MediaPlayer extends Emitter<MediaEvents> {
 }
 
 export class AudioPlayer extends MediaPlayer {
-  constructor(src?: string) {
+  constructor(src?: string | File | FetchResponse) {
     super()
-    this._src = src ?? ""
+    this._src = wireSrc(src)
     ensureEmitter()
     this._h = media()?.createAudio(this._src) ?? { id: -1 }
   }
 }
 
 export class VideoPlayer extends MediaPlayer {
-  constructor(src?: string) {
+  constructor(src?: string | File | FetchResponse) {
     super()
-    this._src = src ?? ""
+    this._src = wireSrc(src)
     ensureEmitter()
     this._h = media()?.createVideo(this._src) ?? { id: -1 }
   }

package/src/runtime/permissions.ts

@@ -0,0 +1,40 @@
+// The OS permissions: what the app may ask the platform for, and when. ONE door, host-gated
+// (`_creatorDevice.queryPermission / requestPermission / openSettings`): the SDK's own camera
+// users (ARScene.prepare, QRScanner, CameraView) go through `_ensurePermission`, apps through
+// `permissions`, a plugin's native half through the host's same service (a method tagged
+// `@permission` in its contract is gated by the generated glue, never by the plugin's code).
+//
+// Hosts without a dialog (headless, desktop, the web for `query` where the browser has no answer)
+// leave the slots out, and both answers are "granted": nothing there stands between an app and a
+// feature — the feature itself says whether it exists (`isSupported`, a rejection of its own).
+
+export type PermissionKind = "camera" | "microphone" | "location" | "speech"
+/** "prompt" = never asked: `request` shows the dialog. "denied" = refused, or restricted by the
+ *  device's policy; the OS decides whether a `request` asks again (iOS never does: `openSettings`). */
+export type PermissionState = "granted" | "denied" | "prompt"
+
+const slot = (name: "queryPermission" | "requestPermission", kind: PermissionKind): Promise<PermissionState> => {
+  const fn = _creatorDevice[name]
+  if (typeof fn !== "function") return Promise.resolve("granted")
+  return new Promise((resolve, reject) => fn(kind, s => resolve(s as PermissionState), err => reject(new Error(err))))
+}
+
+export const permissions = {
+  /** The state of `kind` without a prompt. On the web the browser may not know before a request
+   *  (Safari before 16, Firefox for the camera): "prompt" then. */
+  query(kind: PermissionKind): Promise<PermissionState> { return slot("queryPermission", kind) },
+  /** Ask for `kind`: the dialog when it was never asked, the state after it (or the state as it
+   *  stands when the OS will not ask again). Ask where the user expects it — the first tap on the
+   *  record button, not the start of the call. */
+  request(kind: PermissionKind): Promise<PermissionState> { return slot("requestPermission", kind) },
+  /** Open the app's own page of the system settings: where a denied permission is turned back on
+   *  (iOS asks exactly once). A no-op where there is no such page (web). */
+  openSettings(): void { _creatorDevice.openSettings?.() },
+}
+
+/** Request `kind` and reject when it was not granted — the SDK's own gate before a camera view
+ *  opens. @internal */
+export const _ensurePermission = async (kind: PermissionKind): Promise<void> => {
+  const state = await permissions.request(kind)
+  if (state !== "granted") throw new Error(`The ${kind} permission was ${state === "denied" ? "denied" : "not granted"}`)
+}

package/src/server/auth/host.ts

@@ -40,7 +40,7 @@ export type AuthHostConfig = {
   appName?: string
   /** Sends the sign-in code (the platform mailer). Absent = codes are only echoed to the console. */
   mail?: (msg: AuthMail) => Promise<void>
-  /** Echo every code to the server console (the draft slot: the developer is the only user). */
+  /** Echo every code to the server console (a developer's own backend — `lecodes dev`, a check: the developer is the only user). */
   echoCodes?: boolean
   /** Server console sink (default console). */
   log?: (level: "warn" | "info", text: string) => void

package/src/ui/presentable.ts

@@ -113,6 +113,11 @@ export interface Presentable {
    *  await it and skip the swap entirely if it rejects (permission denied, or superseded by
    *  another navigation that happened while preparing). */
   _prepare?(): Promise<void>
+  /** @internal What a destination that prepared waits for once it is presented — ARScene: its first
+   *  frame drawn (the view mounted and sized, the session's frame shown). `open()` and
+   *  `Router.push/replace` settle with it: they resolve then, or reject when another navigation came
+   *  first. */
+  _presented?(): Promise<void>
   /** @internal The destination tuple (see DestTuple). */
   _dest(): DestTuple
 }

package/src/ui/router.ts

@@ -97,9 +97,10 @@ export const Router: Router = /*#__PURE__*/ Object.freeze({
       _setCurrent(page)   // optimistic — the runtime's change event confirms
     }
     // A preparing destination (ARScene) keeps the current page visible until it's ready; a
-    // rejection (camera denied / superseded) propagates to the caller and nothing is pushed.
+    // rejection (camera denied / superseded) propagates to the caller and nothing is pushed. Pushed,
+    // it settles the push once it is on screen (`_presented`: ARScene's first frame), as its open().
     const prep = page._prepare?.()
-    return prep ? prep.then(go) : go()
+    return prep ? prep.then(() => { go(); return page._presented?.() }) : go()
   },
   replace(page: Presentable, opts?: NavigateOptions): void | Promise<void> {
     const go = () => {
@@ -110,7 +111,7 @@ export const Router: Router = /*#__PURE__*/ Object.freeze({
       _setCurrent(page)   // optimistic — the runtime's change event confirms
     }
     const prep = page._prepare?.()
-    return prep ? prep.then(go) : go()
+    return prep ? prep.then(() => { go(); return page._presented?.() }) : go()
   },
   pop(to?: number, opts?: PopOptions): void {
     _bumpNavEpoch()

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.2.9"
+export const SDK_VERSION = "2.2.11"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {

package/dist/types/gl/controls.d.ts

@@ -1,19 +0,0 @@
-import type { Node } from "./Node";
-import type { Scene } from "./Scene";
-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;
-};
-export declare const attachControls: (scene: Scene, target: Node, options?: ControlsOptions) => ControlsHandle;

package/dist/types/plugins/permission.d.ts

@@ -1 +0,0 @@
-export declare const _requestCameraPermission: () => Promise<void>;

package/src/gl/controls.ts

@@ -1,95 +0,0 @@
-// 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/src/plugins/permission.ts

@@ -1,8 +0,0 @@
-// Camera permission, host-gated: hosts expose it as `_creatorDevice.requestCamera`. Hosts without
-// that slot resolve immediately — their view factory prompts on its own (e.g. getUserMedia on
-// the web). Shared by ARScene.prepare, QRScanner and CameraView.
-
-export const _requestCameraPermission = (): Promise<void> =>
-  typeof _creatorDevice.requestCamera === "function"
-    ? new Promise<void>((res, rej) => _creatorDevice.requestCamera!(res, rej))
-    : Promise.resolve()