lecodes-cli 0.6.4 → 0.7.1

package/runtime/sdk/plugins/geolocation.ts

@@ -0,0 +1,123 @@
+// Geolocation — the device position as a typed service plugin (docs/service-channel-plan.md).
+// A wrapper over the host-registered "geolocation" service, exactly like QRScanner wraps the
+// "qrScanner" NativeView — except services have no UI surface, so there is nothing to present:
+// just `getCurrent()` and `watch()`.
+//
+// Host-OPTIONAL, like every plugin: it exists where the host registered a "geolocation" service
+// (web hosts do out of the box; Android via MainActivity) — gate on `Geolocation.isSupported`.
+// The OS permission prompt happens on the first call that needs it (host-side); denial is a
+// rejection. Both methods reject immediately on unsupported hosts, BEFORE any permission path.
+//
+// Service contract ("geolocation"): calls `getCurrent(options) → GeoPosition`,
+// `startWatch(options)` (resolves once watching), `stopWatch()`; event `position` → GeoPosition.
+
+import { ServiceClient } from "../runtime/service"
+
+export interface GeoPosition {
+  latitude: number
+  longitude: number
+  /** Horizontal accuracy radius, meters. */
+  accuracy: number
+  /** Meters above sea level, or null when the provider doesn't know. */
+  altitude: number | null
+  /** Direction of travel in degrees clockwise from north, or null when stationary/unknown. */
+  heading: number | null
+  /** Ground speed in m/s, or null when unknown. */
+  speed: number | null
+  /** When this fix was taken, ms epoch. */
+  timestamp: number
+}
+
+export interface GeoOptions {
+  /** Prefer the precise (GPS) provider — slower first fix, more battery. Default false. */
+  highAccuracy?: boolean
+  /** getCurrent only: reject with "timeout" if no fix arrives in this many ms. */
+  timeout?: number
+}
+
+/** A live `Geolocation.watch()` subscription — `stop()` it when the screen goes away. */
+export interface GeoWatch {
+  stop(): void
+}
+
+/**
+ * The device position. `Geolocation.isSupported` reports whether this host registered the
+ * service — check it before offering location features.
+ */
+// PURE IIFE so an app that never uses location tree-shakes the whole plugin away (see NativeView).
+export const Geolocation: {
+  /** Whether this host registered a "geolocation" service. */
+  readonly isSupported: boolean
+  /** One position fix. Prompts for permission on first use; rejects on denial ("denied"), no
+   *  provider ("unavailable"), or `options.timeout` elapsing ("timeout"). */
+  getCurrent(options?: GeoOptions): Promise<GeoPosition>
+  /** Continuous updates. Resolves once watching (permission granted + provider started) — so a
+   *  denial is a rejection, never a silently dead callback. One host watch serves every
+   *  subscriber; the options of the watch that starts it win. Always `stop()` when done. */
+  watch(callback: (position: GeoPosition) => void, options?: GeoOptions): Promise<GeoWatch>
+} = /*#__PURE__*/ (() => {
+  let client: ServiceClient | null = null
+  const service = (): ServiceClient => client ??= new ServiceClient("geolocation")
+
+  // Watch state: one host watch fans out to N subscribers (SDK-side), the last stop() releases it.
+  const watchers: ((position: GeoPosition) => void)[] = []
+  let positionHooked = false
+  let startPromise: Promise<void> | null = null
+
+  const assertSupported = (): void => {
+    // Fail before the host is touched — a permission dialog for a feature that can't exist
+    // would be worse than the error (same ordering rule as QRScanner.open).
+    if (!ServiceClient.isSupported("geolocation")) {
+      throw new Error('Geolocation isn\'t available on this host — it needs a registered "geolocation" service.')
+    }
+  }
+
+  const removeWatcher = (callback: (position: GeoPosition) => void): void => {
+    const i = watchers.indexOf(callback)
+    if (i >= 0) watchers.splice(i, 1)
+    if (watchers.length === 0 && startPromise !== null) {
+      startPromise = null
+      service().call("stopWatch").catch(() => {})
+    }
+  }
+
+  const geolocation = {
+    async getCurrent(options?: GeoOptions): Promise<GeoPosition> {
+      assertSupported()
+      return await service().call("getCurrent", options ?? {})
+    },
+
+    async watch(callback: (position: GeoPosition) => void, options?: GeoOptions): Promise<GeoWatch> {
+      assertSupported()
+      if (!positionHooked) {
+        positionHooked = true
+        service().on("position", (position?: GeoPosition) => {
+          if (position) for (const cb of [...watchers]) cb(position)
+        })
+      }
+      watchers.push(callback)
+      startPromise ??= service().call("startWatch", options ?? {})
+      try {
+        await startPromise
+      } catch (e) {
+        // The watch never started — unwind without the stopWatch a live watch would need.
+        const i = watchers.indexOf(callback)
+        if (i >= 0) watchers.splice(i, 1)
+        if (watchers.length === 0) startPromise = null
+        throw e
+      }
+      let stopped = false
+      return {
+        stop(): void {
+          if (stopped) return
+          stopped = true
+          removeWatcher(callback)
+        },
+      }
+    },
+  }
+  Object.defineProperty(geolocation, "isSupported", {
+    get: (): boolean => ServiceClient.isSupported("geolocation"),
+  })
+  return geolocation as any
+})()

package/runtime/sdk/plugins/permission.ts

@@ -0,0 +1,7 @@
+// Camera permission, host-gated: hosts expose it as `_creatorUtils.requestCamera`. Hosts without
+// that bridge 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 _creatorUtils.requestCamera === "function"
+    ? new Promise<void>((res, rej) => _creatorUtils.requestCamera!(res, rej))
+    : Promise.resolve()

package/runtime/sdk/plugins/qr.ts

@@ -1,36 +1,73 @@
-// QRScanner — an OPTIONAL, host-provided capability. The native scanner is implemented by some hosts
-// (the le.codes app) and not others (the generic web viewer), so it's gated on host support and throws
-// a clear error where it's missing — the same approach as physics (`physicsHasSupport`) and AR
-// (`requestCamera`). Ported 1:1 from worker/src/utils/QRScanner.ts.
+// QRScanner — the host's camera QR scanner as a Presentable. A typed wrapper over the
+// `NativeView("qrScanner")` capability (docs/navigation-presentable-plan.md): open it fullscreen
+// (`await scanner.open()`), push it (`Router.push(scanner)`), or embed it among a screen's
+// children as a live preview node — everything a NativeView can do, plus a typed `onScan`.
 //
-// It lives under `plugins/` rather than the core engine folders to mark it as host-optional. This is a
-// *convention*, not a plugin *system* — when there are several of these (NFC, Bluetooth, …) we can
-// extract a real mechanism; for one capability that would be premature.
+// Host-OPTIONAL, like every plugin: it exists where the host registers a "qrScanner" view
+// (Android; web can via `_creatorUI._registerView`) — gate on `QRScanner.isSupported`. Opening
+// prepares first (camera permission) while the current destination stays visible — the same
+// prepare-then-present contract as ARScene.
+//
+// The pre-Presentable `_creatorUtils.openScanner/closeScanner` bridges are gone from the ABI
+// (2026-07-15): hosts keep their implementations only to serve previously compiled bundles.
+
+import { _navEpoch, type PresentOptions } from "../ui/presentable"
+import { NativeView, NativeViewElement } from "../ui/NativeView"
+import { _requestCameraPermission } from "./permission"
 
-export class QRScanner {
-  private readonly _onData: (data: string | null) => void
+export interface QRScanner extends NativeView {
+  /** Fires per decoded camera frame: the decoded string, or `null` for a frame with no readable
+   *  code (expect those repeatedly while the user aims). The same code can be reported more than
+   *  once — `close()` or debounce once you have what you need. */
+  onScan(callback: (data: string | null) => void): this
+  /** Request camera permission, then present the scanner. The current destination (and its
+   *  loading state) stays visible until the scanner is ready; rejects if the camera is denied,
+   *  the host can't scan, or another navigation superseded this one. */
+  open(options?: PresentOptions): Promise<void>
+}
 
-  /** `onData` fires for every value the scanner decodes (null = a frame with no readable code). */
-  constructor(onData: (data: string | null) => void) {
-    this._onData = onData
+class QRScannerElement extends NativeViewElement {
+  constructor() {
+    super("qrScanner", {})
   }
 
-  /** Whether this host provides a native QR scanner (the le.codes app does; many hosts don't). */
-  static get isSupported(): boolean {
-    return typeof _creatorUtils.openScanner === "function"
+  onScan(callback: (data: string | null) => void): this {
+    return this.on("scan", (payload?: { data?: string | null }) => callback(payload?.data ?? null))
   }
 
-  /** Ask for camera access, then open the native scanner. Rejects if the host can't scan or access is denied. */
-  async open(): Promise<void> {
-    if (!QRScanner.isSupported) {
-      throw new Error("QRScanner isn't available on this host — it needs the le.codes app's native scanner.")
+  /** @internal prepare-then-present: permission before the swap (see Presentable._prepare). */
+  async _prepare(): Promise<void> {
+    const epoch = _navEpoch()
+    await _requestCameraPermission()
+    if (_navEpoch() !== epoch) {
+      throw new Error("QRScanner.open() superseded: another destination was opened while preparing")
     }
-    await new Promise<void>((res, rej) => _creator.requestCamera(res, rej))
-    await new Promise<void>((res, rej) => _creatorUtils.openScanner(res, rej, this._onData))
   }
 
-  /** Close the scanner and release the camera. */
-  close(): void {
-    _creatorUtils.closeScanner()
+  override async open(options?: PresentOptions): Promise<void> {
+    // Fail before prompting for the camera — a permission dialog for a scanner that can't exist
+    // would be worse than the error.
+    if (!NativeView.isSupported("qrScanner")) {
+      throw new Error("QRScanner isn't available on this host — it needs a registered \"qrScanner\" view.")
+    }
+    await this._prepare()
+    super.open(options)
   }
 }
+
+/**
+ * Create a QR scanner view. `QRScanner.isSupported` reports whether this host can scan at all —
+ * check it before offering the feature.
+ */
+// PURE IIFE so an app that never scans tree-shakes the whole plugin away (see NativeView).
+export const QRScanner: {
+  (): QRScanner
+  /** Whether this host registered a "qrScanner" view. */
+  readonly isSupported: boolean
+} = /*#__PURE__*/ (() => {
+  const factory = (): QRScanner => new QRScannerElement() as unknown as QRScanner
+  Object.defineProperty(factory, "isSupported", {
+    get: (): boolean => NativeView.isSupported("qrScanner"),
+  })
+  return factory as any
+})()

package/runtime/sdk/runtime/app.ts

@@ -0,0 +1,37 @@
+// The app's own lifecycle + how it was opened (docs/app-lifecycle-plan.md). Events are semantic —
+// "pause"/"resume", never Activity/Scene vocabulary — and the current values are synchronous pulls
+// so render-loop code can read them without subscribing.
+
+import { appEventsOn, appEventsOff } from "./appEvents"
+
+export type AppState = "active" | "background"
+
+type AppEventMap = {
+  /** The app left the foreground (home button, tab hidden, another app on top). Delivered before
+   *  the host halts the frame loop — the last chance to persist state / pause work. */
+  pause: () => void
+  /** The app returned to the foreground; frames are running again. */
+  resume: () => void
+  /** A link arrived while the app was running (warm deep link). `app.launchUrl` is already
+   *  updated to the same value when this fires. */
+  url: (url: string) => void
+}
+
+export const app = {
+  /** Current lifecycle state. `"background"` while the app is not the foreground app / the tab is
+   *  hidden. `"active"` on hosts that don't track it. */
+  get state(): AppState {
+    return _creatorUtils.appState?.() === "background" ? "background" : "active"
+  },
+  /** The URL the app was (most recently) opened with — the deep link — or `null` for a plain
+   *  launch. Warm links update it and fire the `"url"` event. */
+  get launchUrl(): string | null {
+    return _creatorUtils.getLaunchUrl?.() ?? null
+  },
+  addEventListener<E extends keyof AppEventMap>(event: E, callback: AppEventMap[E]): void {
+    appEventsOn(event, callback as (data?: string) => void)
+  },
+  removeEventListener<E extends keyof AppEventMap>(event: E, callback: AppEventMap[E]): void {
+    appEventsOff(event, callback as (data?: string) => void)
+  },
+}

package/runtime/sdk/runtime/appEvents.ts

@@ -0,0 +1,29 @@
+// The shared app-event dispatcher. The host exposes ONE registerAppEvent slot per JS world
+// (docs/app-lifecycle-plan.md), so every SDK consumer (the `app` global's pause/resume/url, the
+// `device` global's online/offline) subscribes here and this module registers with the host once,
+// lazily on the first subscription — no top-level side effect, tree-shaking drops it when unused.
+
+type AppEventCallback = (data?: string) => void
+
+const listeners: Record<string, AppEventCallback[]> = {}
+let registered = false
+
+const dispatch = (event: string, data?: string): void => {
+  const arr = listeners[event]
+  if (arr) for (const cb of arr.slice()) cb(data)
+}
+
+export const appEventsOn = (event: string, cb: AppEventCallback): void => {
+  ;(listeners[event] ??= []).push(cb)
+  if (!registered) {
+    registered = true
+    _creatorUtils.registerAppEvent?.(dispatch)
+  }
+}
+
+export const appEventsOff = (event: string, cb: AppEventCallback): void => {
+  const arr = listeners[event]
+  if (!arr) return
+  const i = arr.indexOf(cb)
+  if (i >= 0) arr.splice(i, 1)
+}

package/runtime/sdk/runtime/channel.ts

@@ -0,0 +1,50 @@
+// The JSON wire protocol shared by the two host plugin channels — NativeView
+// (`_creatorUI.viewCall`, see ui/NativeView.ts) and headless services
+// (`_creatorUtils.serviceCall`, see runtime/service.ts). One protocol, two transports:
+// `args`, results, and event payloads travel as JSON strings, and an absent/empty string
+// decodes to `undefined`. Typed plugins (QRScanner, CameraView, Geolocation) layer methods
+// over this — see src/plugins/.
+
+/** @internal event-name → listeners. NativeView exposes it as `nvl` (host contract). */
+export type ChannelListeners = Record<string, ((data?: any) => void)[]>
+
+/** @internal */
+export const _channelOn = (listeners: ChannelListeners, event: string, callback: (data?: any) => void): void => {
+  (listeners[event] ??= []).push(callback)
+}
+
+/** @internal */
+export const _channelOff = (listeners: ChannelListeners, event: string, callback: (data?: any) => void): void => {
+  const list = listeners[event]
+  if (!list) return
+  const i = list.indexOf(callback)
+  if (i >= 0) list.splice(i, 1)
+}
+
+/** @internal deliver a host event: decode the JSON payload, fan out (copy-before-iterate). */
+export const _channelEmit = (listeners: ChannelListeners, event: string, dataJson?: string): void => {
+  const list = listeners[event]
+  if (!list || list.length === 0) return
+  const data = dataJson === undefined || dataJson === "" ? undefined : JSON.parse(dataJson)
+  for (const cb of [...list]) cb(data)
+}
+
+type ChannelCallBridge = (
+  id: number, method: string, args: string,
+  onComplete: (result?: string) => void, onError: (err: string) => void,
+) => void
+
+/** @internal one JSON call over a channel bridge; `bridge` may be absent (optional ABI member). */
+export const _channelCall = (
+  bridge: ChannelCallBridge | undefined, unsupportedError: string,
+  id: number, method: string, args: any[],
+): Promise<any> =>
+  new Promise((res, rej) => {
+    if (typeof bridge !== "function") {
+      rej(new Error(unsupportedError))
+      return
+    }
+    bridge(id, method, JSON.stringify(args),
+      (result?: string) => res(result === undefined || result === "" ? undefined : JSON.parse(result)),
+      (err: string) => rej(new Error(err)))
+  })

package/runtime/sdk/runtime/clipboard.ts

@@ -0,0 +1,20 @@
+// System clipboard (docs/app-lifecycle-plan.md). Write is fire-and-forget; read is async because
+// web gates it behind a permission prompt (native hosts complete synchronously).
+
+export const clipboard = {
+  /** Put `text` on the system clipboard. Silent no-op on hosts without clipboard access. */
+  write(text: string): void {
+    _creatorUtils.clipboardWrite?.(text)
+  },
+  /** Read text from the system clipboard. Rejects when the platform has no clipboard access, the
+   *  user denied it, or there is nothing readable. */
+  read(): Promise<string> {
+    return new Promise((resolve, reject) => {
+      if (typeof _creatorUtils.clipboardRead !== "function") {
+        reject(new Error("Clipboard is not supported on this platform"))
+        return
+      }
+      _creatorUtils.clipboardRead(resolve, (err: string) => reject(new Error(err)))
+    })
+  },
+}

package/runtime/sdk/runtime/datetime.ts

@@ -243,10 +243,8 @@ export class DateValue {
   startOf(unit: Unit): DateValue {
     const d = new Date(this.t)
     switch (unit) {
-      case "year": d.setMonth(0)
-      // falls through
-      case "month": d.setDate(1)
-      // falls through
+      case "year": d.setMonth(0); d.setDate(1); d.setHours(0, 0, 0, 0); break
+      case "month": d.setDate(1); d.setHours(0, 0, 0, 0); break
       case "day": d.setHours(0, 0, 0, 0); break
       case "hour": d.setMinutes(0, 0, 0); break
       case "minute": d.setSeconds(0, 0); break

package/runtime/sdk/runtime/device.ts

@@ -1,8 +1,20 @@
 // Platform info + the host resize event. The resize listener registers with the host lazily on the
 // first subscription (no top-level side effect, so tree-shaking can drop this entirely if unused).
 
+import { Quat } from "../math/quat"
+import { Vec3 } from "../math/vec"
+import { appEventsOn, appEventsOff } from "./appEvents"
+
 type ResizeCallback = (width: number, height: number) => void
 
+type DeviceEventMap = {
+  resize: ResizeCallback
+  /** Connectivity came back (best-effort, navigator.onLine semantics). */
+  online: () => void
+  /** Connectivity was lost. */
+  offline: () => void
+}
+
 const resizeListeners: ResizeCallback[] = []
 let resizeRegistered = false
 
@@ -10,6 +22,49 @@ const onResize = (width: number, height: number): void => {
   for (const cb of resizeListeners.slice()) cb(width, height)
 }
 
+/** Semantic haptic styles for `device.vibrate`. Impact styles (`light`/`medium`/`heavy`/`soft`/
+ *  `rigid`) are a physical "tap" of varying weight; notification styles (`success`/`warning`/`error`)
+ *  cue an outcome; `selection` is a light tick for a value change. Chosen to map 1:1 onto iOS
+ *  `UIFeedbackGenerator` and, on Android, `HapticFeedbackConstants` / `VibrationEffect` — so the same
+ *  call feels native everywhere, rather than a duration that only web/Android can honor. */
+export type HapticStyle =
+  | "light" | "medium" | "heavy" | "soft" | "rigid"
+  | "success" | "warning" | "error"
+  | "selection"
+
+/** Options for `device.motion.start`. */
+export interface MotionOptions {
+  /** Sensor update interval in seconds (default 1/60). The sensor fuses at ≥ this rate in the
+   *  background; you poll the freshest sample each frame, so this is a floor, not a sync. */
+  interval?: number
+  /** Frame the readables are delivered in. "world" (default): engine Y-up, screen-oriented — drops
+   *  straight into `camera.quaternion` / any node. "device": the raw sensor frame, no conversion. */
+  frame?: "world" | "device"
+}
+
+// --- device.motion state (pull-per-frame model) ---
+let motionEnabled = false
+let motionFrame: "world" | "device" = "world"
+let motionYawOffset = 0   // radians about world up, captured by recenter()
+
+// Calibration constants — VERIFY ON A PHYSICAL DEVICE (the simulator reports no motion).
+//  • CM_TO_WORLD: Core Motion's reference frame is Z-up; the engine world is Y-up. If a level horizon
+//    reads tilted ~90°, this is the term to check.
+//  • ORIENTATION_ROLL: roll about the view axis so camera-up tracks screen-up, indexed by the native
+//    interface-orientation code [portrait, landscapeLeft, landscapeRight, upsideDown]. If landscape is
+//    upside-down or rolled the wrong way, flip the ±π/2 signs.
+// If the whole panorama turns the wrong way (look right → view goes left), conjugate `raw` below.
+const CM_TO_WORLD = Quat.fromAxisAngle([1, 0, 0], -Math.PI / 2)
+const ORIENTATION_ROLL = [0, Math.PI / 2, -Math.PI / 2, Math.PI]
+
+// Device attitude → engine world frame, with the interface-orientation roll folded in (yaw NOT yet
+// recentered). Shared by `attitude` (which adds the recenter) and `gravity` (which is yaw-invariant).
+const orientedAttitude = (s: ArrayLike<number>): Quat => {
+  const raw = new Quat(s[0], s[1], s[2], s[3])
+  const roll = Quat.fromAxisAngle([0, 0, 1], ORIENTATION_ROLL[s[7]] ?? 0)
+  return CM_TO_WORLD.mul(raw).mul(roll)
+}
+
 export const device = {
   get platform(): "web" | "android" | "ios" | string {
     return _creatorUtils.platform
@@ -43,17 +98,95 @@ export const device = {
   setPreciseTouch(enabled: boolean): void {
     _creatorUtils.setPreciseTouch?.(enabled)
   },
-  addEventListener(channel: "resize", callback: ResizeCallback): void {
+  /** Fire a one-shot haptic of the given semantic `style` (default `"medium"`) — a physical tap on
+   *  supported hardware (iOS Taptic Engine, Android vibrator). Chosen by meaning, not duration, so it
+   *  feels native on each platform; see {@link HapticStyle}. Host-gated: a silent no-op where there's
+   *  no haptic hardware (iPad, older iPhones, web, headless). */
+  vibrate(style: HapticStyle = "medium"): void {
+    _creatorUtils.vibrate?.(style)
+  },
+  /** Device-orientation sensor (gyro + accelerometer, fused) for tilt/steering and magic-window /
+   *  360° panoramas. Poll `attitude` / `gravity` inside setLoop; they return the freshest fused
+   *  sample, so the sensor rate need not match your frame rate. Host-gated: a no-op with no sensor. */
+  motion: {
+    /** Whether this device has the motion sensors at all (no gyro → false; iPad/older, web, headless). */
+    get available(): boolean {
+      return _creatorUtils.motionAvailable?.() ?? false
+    },
+    /** Whether updates are currently running (start succeeded and stop hasn't been called). */
+    get enabled(): boolean {
+      return motionEnabled
+    },
+    /** Begin sensor updates. Resolves to whether it actually started (false = no sensor / denied).
+     *  Async so a web host can await its permission prompt; native resolves immediately. */
+    async start(options: MotionOptions = {}): Promise<boolean> {
+      motionFrame = options.frame ?? "world"
+      motionEnabled = !!(await (_creatorUtils.motionStart?.(options.interval ?? 1 / 60) ?? false))
+      return motionEnabled
+    },
+    /** Stop sensor updates and release the sensor (battery). */
+    stop(): void {
+      _creatorUtils.motionStop?.()
+      motionEnabled = false
+    },
+    /** Capture the current heading as "forward" — a yaw-only recenter (pitch/roll stay gravity-
+     *  referenced, so the horizon stays level). No-op in the "device" frame. */
+    recenter(): void {
+      const s = _creatorUtils.getMotionSample?.()
+      if (!s || motionFrame === "device") { motionYawOffset = 0; return }
+      const f = orientedAttitude(s).rotateVec3([0, 0, -1])   // world-space camera forward
+      motionYawOffset = Math.atan2(-f.x, -f.z)               // heading about world up
+    },
+    /** The device's current orientation as a `Quat`. In the "world" frame (default) it's engine Y-up
+     *  and screen-oriented, so `camera.quaternion = device.motion.attitude` is a complete magic-window
+     *  / panorama camera. `Quat.identity` until the first sample arrives / when not running. */
+    get attitude(): Quat {
+      const s = _creatorUtils.getMotionSample?.()
+      if (!s) return Quat.identity
+      if (motionFrame === "device") return new Quat(s[0], s[1], s[2], s[3])
+      const q = orientedAttitude(s)
+      return Quat.fromAxisAngle([0, 1, 0], -motionYawOffset).mul(q)   // yaw recenter (world-frame)
+    },
+    /** Gravity direction for tilt controls. In the "world" frame it's SCREEN space (x → right, y →
+     *  down, matching clientX/clientY), orientation-aware — a 2D game reads `gravity.x / gravity.y`.
+     *  `(0,0,0)` when not running. */
+    get gravity(): Vec3 {
+      const s = _creatorUtils.getMotionSample?.()
+      if (!s) return new Vec3(0, 0, 0)
+      if (motionFrame === "device") return new Vec3(s[4], s[5], s[6])
+      // Re-express the raw device-frame gravity in screen space: undo the interface roll (about the
+      // screen normal), then flip Y to screen-down. Uses the unambiguous CMDeviceMotion.gravity, so
+      // it stays correct regardless of the attitude-quaternion convention above.
+      const unroll = Quat.fromAxisAngle([0, 0, 1], -(ORIENTATION_ROLL[s[7]] ?? 0))
+      const g = new Vec3(s[4], s[5], s[6]).rotate(unroll)
+      return new Vec3(g.x, -g.y, g.z)
+    },
+  },
+  /** Current connectivity — best-effort navigator.onLine semantics: `false` only when the platform
+   *  is sure there's no network. `true` on hosts that don't track it. Change events: `"online"` /
+   *  `"offline"`. */
+  get online(): boolean {
+    return _creatorUtils.isOnline?.() ?? true
+  },
+  addEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void {
+    if (channel === "online" || channel === "offline") {
+      appEventsOn(channel, callback as () => void)
+      return
+    }
     if (channel !== "resize") return
-    resizeListeners.push(callback)
+    resizeListeners.push(callback as ResizeCallback)
     if (!resizeRegistered) {
       resizeRegistered = true
       _creatorUI.registerResizeEvent(onResize)
     }
   },
-  removeEventListener(channel: "resize", callback: ResizeCallback): void {
+  removeEventListener<E extends keyof DeviceEventMap>(channel: E, callback: DeviceEventMap[E]): void {
+    if (channel === "online" || channel === "offline") {
+      appEventsOff(channel, callback as () => void)
+      return
+    }
     if (channel !== "resize") return
-    const i = resizeListeners.indexOf(callback)
+    const i = resizeListeners.indexOf(callback as ResizeCallback)
     if (i >= 0) resizeListeners.splice(i, 1)
   },
 }

package/runtime/sdk/runtime/misc.ts

@@ -3,6 +3,10 @@
 /** Show a transient toast notification. */
 export const toast = (msg: string): void => _creatorUI.toast(msg)
 
+/** Open `url` in the system browser / external handler (fire-and-forget, like `share`). Silent
+ *  no-op on hosts without one (headless). */
+export const openURL = (url: string): void => _creatorUtils.openUrl?.(url)
+
 export type SvgSourceValue = {
   readonly svg: string
   tintColor: string | null

package/runtime/sdk/runtime/service.ts

@@ -0,0 +1,82 @@
+// A host-registered headless service (geolocation, bluetooth, contacts, …) — the UI-less sibling
+// of NativeView (docs/service-channel-plan.md). The host registers a *capability*
+// (`registerService("geolocation") { params, channel -> ... }`); the SDK talks to it over the
+// shared JSON call/event protocol (runtime/channel.ts) via `_creatorUtils.service*`.
+//
+// Not a public global: apps meet services only through typed plugin wrappers (Geolocation —
+// src/plugins/), which subclass or wrap this exactly like QRScanner wraps NativeViewElement.
+
+import { _channelCall, _channelEmit, _channelOff, _channelOn, type ChannelListeners } from "./channel"
+
+/** @internal Base for typed service plugins. The host session opens lazily on the first `call()`
+ *  (`on()` only records listeners), and `close()` releases it — a later `call()` reopens a fresh
+ *  session. Session ids are host-allocated (websocket model): the `onEvent` callback is handed
+ *  over at open, so no SDK-side ref registry is needed. */
+export class ServiceClient {
+  readonly serviceName: string
+  readonly params: any
+  private _serviceId: number | null = null
+  private readonly _listeners: ChannelListeners = {}
+
+  constructor(serviceName: string, params: any = {}) {
+    this.serviceName = serviceName
+    this.params = params
+  }
+
+  /** Whether this host registered a `registerService` factory under `name`. */
+  static isSupported(name: string): boolean {
+    return typeof _creatorUtils !== "undefined" && typeof _creatorUtils.isServiceSupported === "function"
+      && _creatorUtils.isServiceSupported(name)
+  }
+
+  /** @internal open (or reuse) the host session; throws when the host has no channel/factory. */
+  private _ensureOpen(): number {
+    if (this._serviceId !== null) return this._serviceId
+    if (typeof _creatorUtils === "undefined" || typeof _creatorUtils.serviceOpen !== "function") {
+      throw new Error(`Service("${this.serviceName}") is not supported on this host (requires _creatorUtils.serviceOpen)`)
+    }
+    const id = _creatorUtils.serviceOpen(this.serviceName, JSON.stringify(this.params ?? {}),
+      (event: string, dataJson?: string) => _channelEmit(this._listeners, event, dataJson))
+    if (id < 0) {
+      throw new Error(`Service("${this.serviceName}") is not registered on this host`)
+    }
+    this._serviceId = id
+    return id
+  }
+
+  /** Invoke a method on the service (`geo.call("getCurrent", options)`). Args and the result are
+   *  JSON-serialized. Rejects if the host has no such service/method. */
+  call(method: string, ...args: any[]): Promise<any> {
+    let id: number
+    try {
+      id = this._ensureOpen()
+    } catch (e) {
+      return Promise.reject(e)
+    }
+    return _channelCall(
+      typeof _creatorUtils !== "undefined" ? _creatorUtils.serviceCall : undefined,
+      `Service("${this.serviceName}") is not supported on this host (requires _creatorUtils.serviceCall)`,
+      id, method, args)
+  }
+
+  /** Subscribe to an event the service emits (`geo.on("position", cb)`). */
+  on(event: string, callback: (data?: any) => void): this {
+    _channelOn(this._listeners, event, callback)
+    return this
+  }
+  off(event: string, callback: (data?: any) => void): this {
+    _channelOff(this._listeners, event, callback)
+    return this
+  }
+
+  /** Close the host session (stops whatever the service was doing). Listeners stay registered —
+   *  a later `call()` opens a fresh session that delivers to them again. */
+  close(): void {
+    if (this._serviceId === null) return
+    const id = this._serviceId
+    this._serviceId = null
+    if (typeof _creatorUtils !== "undefined" && typeof _creatorUtils.serviceClose === "function") {
+      _creatorUtils.serviceClose(id)
+    }
+  }
+}