lecodes-cli 0.7.0 → 0.7.1

package/dist/index.js

@@ -1457,7 +1457,7 @@ var require_main = __commonJS((exports, module) => {
 // package.json
 var package_default = {
   name: "lecodes-cli",
-  version: "0.7.0",
+  version: "0.7.1",
   description: "Clone, edit and push LeCodes projects from your machine.",
   type: "module",
   license: "MIT",
@@ -1487,11 +1487,11 @@ var package_default = {
     prepublishOnly: "bun run sync-peers && bun run build"
   },
   dependencies: {
-    "@letary/chisel": "^0.4.0"
+    "@letary/chisel": "^0.4.1"
   },
   peerDependencies: {
     "lecodes-design": "^0.3.1",
-    "lecodes-renderer": "^0.6.0",
+    "lecodes-renderer": "^0.6.1",
     "lecodes-3d-editor": "^0.1.0"
   },
   peerDependenciesMeta: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Clone, edit and push LeCodes projects from your machine.",
   "type": "module",
   "license": "MIT",
@@ -30,11 +30,11 @@
     "prepublishOnly": "bun run sync-peers && bun run build"
   },
   "dependencies": {
-    "@letary/chisel": "^0.4.0"
+    "@letary/chisel": "^0.4.1"
   },
   "peerDependencies": {
     "lecodes-design": "^0.3.1",
-    "lecodes-renderer": "^0.6.0",
+    "lecodes-renderer": "^0.6.1",
     "lecodes-3d-editor": "^0.1.0"
   },
   "peerDependenciesMeta": {

package/runtime/sdk/g2/Scene2D.ts

@@ -3,6 +3,7 @@
 
 import { Color, type ColorInput } from "../core/color"
 import { _installAspectFrames } from "../core/Aspect"
+import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "../ui/presentable"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
@@ -48,7 +49,7 @@ class LayerHandle {
   }
 }
 
-export class Scene2D {
+export class Scene2D implements Presentable {
   /** Native scene handle. */
   readonly id: number
   readonly camera: Camera2D
@@ -111,17 +112,62 @@ export class Scene2D {
     return this
   }
 
-  /** Make this the active scene (brings up the 2D engine on the canvas; closes any other). */
-  open(): this {
+  // ---- Presentable (docs/navigation-presentable-plan.md) ----
+
+  /** @internal presentation lifecycle — fired by the host on present/dismiss (new navigation),
+   *  or synchronously by open()/close() on legacy hosts. */
+  readonly ol: (() => void)[] = []
+  readonly cl: (() => void)[] = []
+  _backButtonCallback?: () => void
+  private _vd?: object
+
+  /** Fires when the scene becomes the visible destination (incl. a pop revealing it). */
+  onOpen(callback: () => void): this {
+    this.ol.push(callback)
+    return this
+  }
+  /** Fires when the scene stops being visible (closed, replaced, or covered by a push). */
+  onClose(callback: () => void): this {
+    this.cl.push(callback)
+    return this
+  }
+  onBackPressed(callback: () => void): this {
+    this._backButtonCallback = callback
+    return this
+  }
+
+  /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
+  _viewDesc(): object {
+    return this._vd ??= { type: "scene2d", sceneId: this.id, _p: this }
+  }
+
+  /** Make this the active scene — shows it as the current destination (replaces a screen /
+   *  another scene; only the active scene renders). */
+  open(options?: PresentOptions): this {
+    _bumpNavEpoch()
     // Reassert this scene's texture filter (the sampler is global — see Scene2DOptions.filter).
     if (this._filter !== undefined) _creator2d.setDefaultFilter(this._filter === 'linear')
-    _creator2d.openScene(this.id)
+    if (_navSupported()) {
+      // The host activates the engine (openScene) as part of presenting the destination.
+      _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
+    } else {
+      _creator2d.openScene(this.id)
+      for (const cb of this.ol) cb()
+    }
     Scene2D._active = this
+    _setCurrent(this)
     return this
   }
   close(): this {
-    _creator2d.closeScene()
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      _creatorUI.closeView!()
+    } else {
+      _creator2d.closeScene()
+      for (const cb of this.cl) cb()
+    }
     if (Scene2D._active === this) Scene2D._active = null
+    if (Presentable.current === this) _setCurrent(null)
     return this
   }
   destroy(): void {

package/runtime/sdk/gl/Model.ts

@@ -17,6 +17,15 @@ export class Model extends Node {
     this.aspect(ModelAnimation)
   }
 
+  /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
+   *  the same parent and scene and sharing this model's current transform. The clone has its own
+   *  independent animation state (reach it via clone.anim). Mirrors Model.load's culling default. */
+  clone(): Model {
+    const id = _creator.cloneEntity(this.id)
+    _creator.setGlbCulling(id, false)
+    return new Model(id)
+  }
+
   /** Load a GLB model. Returns its root as a Model; play its baked clips via model.anim. */
   static load(
     source: string | FetchResponse,

package/runtime/sdk/gl/Scene.ts

@@ -7,8 +7,10 @@
 
 import { Color, type ColorInput } from "../core/color"
 import { _installAspectFrames } from "../core/Aspect"
+import { _bumpNavEpoch, _navEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "../ui/presentable"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
+import { _requestCameraPermission } from "../plugins/permission"
 import { Camera } from "./Camera"
 import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import { Material } from "./Material"
@@ -46,7 +48,7 @@ const installRenderSyncedFrames = (): void => {
   })
 }
 
-export class Scene {
+export class Scene implements Presentable {
   /** @internal native scene handle. */
   readonly _id: number
   readonly camera: Camera
@@ -115,16 +117,64 @@ export class Scene {
     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)
+  // ---- Presentable (docs/navigation-presentable-plan.md) ----
+  // A scene is a destination like a screen: opening it replaces whatever is visible (suspending
+  // an active Router until Router.restore()), and it can be pushed onto the Router stack. The
+  // scene graph survives while covered — only the view detaches and rendering pauses.
+
+  /** @internal presentation lifecycle — fired by the host on present/dismiss (new navigation),
+   *  or synchronously by open()/close() on legacy hosts. */
+  readonly ol: (() => void)[] = []
+  readonly cl: (() => void)[] = []
+  _backButtonCallback?: () => void
+  private _vd?: object
+
+  /** Fires when the scene becomes the visible destination (incl. a pop revealing it). */
+  onOpen(callback: () => void): this {
+    this.ol.push(callback)
+    return this
+  }
+  /** Fires when the scene stops being visible (closed, replaced, or covered by a push). */
+  onClose(callback: () => void): this {
+    this.cl.push(callback)
+    return this
+  }
+  onBackPressed(callback: () => void): this {
+    this._backButtonCallback = callback
+    return this
+  }
+
+  /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
+  _viewDesc(): object {
+    return this._vd ??= { type: "scene3d", sceneId: this._id, _p: this }
+  }
+
+  /** Make this the active scene — shows it as the current destination (replaces a screen /
+   *  another scene; only the active scene renders). */
+  open(options?: PresentOptions): void | Promise<void> {
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      // The host activates the engine (openScene) as part of presenting the destination.
+      _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
+    } else {
+      _creator.openScene(this._id)
+      for (const cb of this.ol) cb()
+    }
     Scene._active = this
     glState.activeScene = this
+    _setCurrent(this)
   }
   close(): void {
-    _creator.closeScene()
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      _creatorUI.closeView!()
+    } else {
+      _creator.closeScene()
+      for (const cb of this.cl) cb()
+    }
     if (Scene._active === this) Scene._active = null
     if (glState.activeScene === this) glState.activeScene = null
+    if (Presentable.current === this) _setCurrent(null)
   }
 
   addEventListener(channel: "click", callback: (ev: ClickEvent<Node | null>) => void): void
@@ -188,11 +238,26 @@ export class ARScene<T extends ARMode = "default"> extends Scene {
     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() }
+  override async open(options?: PresentOptions): Promise<void> {
+    await this._prepare()
+    super.open(options)
+  }
+
+  /** @internal Presentable prepare hook: camera permission + warm render + AR session, all while
+   *  the previous destination (typically a loading screen) stays visible — the swap to this scene
+   *  happens only after it resolves. Warm render is headless on every platform (offscreen
+   *  swapchain), so no GL view is created here — the host mounts the scene view at present time.
+   *  Rejects on camera denial / AR launch failure, or if another navigation happened while
+   *  preparing (superseded) — in every rejection case the current destination stays visible. */
+  async _prepare(): Promise<void> {
+    const epoch = _navEpoch()
+    await _requestCameraPermission()
+    if (this.useWarmRender) await this.warmRender()
     await new Promise<void>((res, rej) => _creator.launchAR(this._id, res, rej))
-    super.open()
+    if (_navEpoch() !== epoch) {
+      _creator.stopAR()
+      throw new Error("ARScene.open() superseded: another destination was opened while preparing")
+    }
   }
 
   override close(): void {
@@ -212,9 +277,9 @@ export class ARScene<T extends ARMode = "default"> extends Scene {
  * `open()` rejects on hosts without a VR runtime ("VR is not supported on this device").
  */
 export class VRScene extends Scene {
-  override async open(): Promise<void> {
+  override async open(options?: PresentOptions): Promise<void> {
     await new Promise<void>((res, rej) => _creator.launchVR(this._id, res, rej))
-    super.open()
+    super.open(options)
   }
 
   override close(): void {

package/runtime/sdk/inject.ts

@@ -25,18 +25,19 @@ export { signal, computed, effect, type Signal, type Computed } from "./core/sig
 export { Canvas, Bitmap } from "./canvas/Canvas"
 
 // ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
-export { toast, SvgSource } from "./runtime/misc"
+export { toast, openURL, SvgSource } from "./runtime/misc"
+export { app, type AppState } from "./runtime/app"
+export { clipboard } from "./runtime/clipboard"
 export { date, type DateValue, type DateInput, type Unit, type Locale } from "./runtime/datetime"
 export { fetch, fetchLocal, FormData, File } from "./runtime/fetch"
 export { localStorage } from "./runtime/storage"
-export { device } from "./runtime/device"
+export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
 export { Input } from "./runtime/input"
 export { WebSocket } from "./runtime/net"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
-export { CameraViewer } from "./runtime/camera"
 export { openFilePicker } from "./runtime/files"
 export { share } from "./runtime/share"
-export { ClickEvent, TouchStartEvent } from "./runtime/touch"
+export { ClickEvent, TouchStartEvent, LongPressEvent } from "./runtime/touch"
 
 // ---- 2D engine (creator-2d) ----
 export { Scene2D } from "./g2/Scene2D"
@@ -53,7 +54,7 @@ export { Texture2D } from "./g2/Texture2D"
 
 // ---- UI (creator-ui) ----
 export {
-  UIScreen, type UIScreenStyle,
+  UIScreen, type UIScreenStyle, type UIScrollableScreen,
   UIRow, UIColumn, UIBox, type UIContainerStyle,
   UIText, type UITextStyle,
   UIButton, type UIButtonStyle,
@@ -66,9 +67,14 @@ export {
   UISpacer, type UISpacerStyle,
   UIVirtualizedList,
   Router,
+  NativeView, type UINativeViewStyle,
   registerFont,
   __uiMap,
 } from "./ui/UI"
+// The Presentable navigation contract (docs/navigation-presentable-plan.md). `Presentable` is
+// interface + runtime companion (declaration merging): `Presentable.current` = what's on screen.
+export { Presentable } from "./ui/UI"
+export type { PresentOptions, Transition, TransitionName, TransitionSpec, TransitionTransform } from "./ui/UI"
 // The base node type + the union a container accepts as children — documented as the signature of
 // UIColumn/UIRow/append/etc., so they must be global (type-only; erased at runtime).
 export type { UINode, UINodeChild } from "./ui/UINode"
@@ -81,8 +87,10 @@ export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation }
 export { cubicBezier } from "./animate/bezier"
 export { easeIn, easeOut, easeInOut } from "./animate/easings"
 
-// ---- plugins (optional, host-provided capabilities — see src/plugins/) ----
+// ---- plugins (optional, host-provided capabilities — typed NativeView/service wrappers, see src/plugins/) ----
 export { QRScanner } from "./plugins/qr"
+export { CameraView, type CameraFacing } from "./plugins/camera"
+export { Geolocation, type GeoPosition, type GeoOptions, type GeoWatch } from "./plugins/geolocation"
 
 // ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
 export { defineScene, use, ref, make, SceneHandle } from "./scene/defineScene"

package/runtime/sdk/plugins/camera.ts

@@ -0,0 +1,81 @@
+// CameraView — the device camera (live preview + still capture) as a Presentable. A typed wrapper
+// over the `NativeView("camera")` capability (docs/navigation-presentable-plan.md): open it
+// fullscreen (`await camera.open()`), push it (`Router.push(camera)`), or embed it among a
+// screen's children as a live preview node. `takePhoto()` returns a `File` (a host buffer
+// handle) — use it as a texture (`Texture2D.load(file)`), upload it (`FormData`), or `share` it.
+//
+// Host-OPTIONAL: it exists where the host registers a "camera" view (Android; web can via
+// `_creatorUI._registerView`) — gate on `CameraView.isSupported`. Opening prepares first (camera
+// permission) while the current destination stays visible — the same contract as ARScene/QRScanner.
+//
+// The pre-Presentable `_creatorUtils.camera*` bridges are gone from the ABI (2026-07-15): hosts
+// keep their implementations only to serve previously compiled bundles.
+
+import { File } from "../runtime/fetch"
+import { _navEpoch, type PresentOptions } from "../ui/presentable"
+import { NativeView, NativeViewElement } from "../ui/NativeView"
+import { _requestCameraPermission } from "./permission"
+
+export type CameraFacing = "front" | "back"
+
+export interface CameraView extends NativeView {
+  /** Request camera permission, then present the preview. The current destination stays visible
+   *  until the camera is ready; rejects if permission is denied, the host has no camera, or
+   *  another navigation superseded this one. */
+  open(options?: PresentOptions): Promise<void>
+  /** Capture a still frame as an image `File` (host-encoded). */
+  takePhoto(): Promise<File>
+  /** Switch between the front and back camera while the preview is live. */
+  setFacingMode(facingMode: CameraFacing): Promise<void>
+}
+
+class CameraViewElement extends NativeViewElement {
+  constructor(options: { facingMode?: CameraFacing } = {}) {
+    super("camera", { facingMode: options.facingMode ?? "back" })
+  }
+
+  /** @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("CameraView.open() superseded: another destination was opened while preparing")
+    }
+  }
+
+  override async open(options?: PresentOptions): Promise<void> {
+    // Fail before prompting for the camera — see QRScanner.
+    if (!NativeView.isSupported("camera")) {
+      throw new Error("CameraView isn't available on this host — it needs a registered \"camera\" view.")
+    }
+    await this._prepare()
+    super.open(options)
+  }
+
+  async takePhoto(): Promise<File> {
+    const photo = await this.call("takePhoto")
+    return new File(photo.systemId, photo.name, photo.size)
+  }
+
+  async setFacingMode(facingMode: CameraFacing): Promise<void> {
+    await this.call("setFacingMode", facingMode)
+  }
+}
+
+/**
+ * Create a camera view (default: the back camera). `CameraView.isSupported` reports whether this
+ * host has a camera capability — check it before offering the feature.
+ */
+// PURE IIFE so an app that never uses the camera tree-shakes the whole plugin away (see NativeView).
+export const CameraView: {
+  (options?: { facingMode?: CameraFacing }): CameraView
+  /** Whether this host registered a "camera" view. */
+  readonly isSupported: boolean
+} = /*#__PURE__*/ (() => {
+  const factory = (options?: { facingMode?: CameraFacing }): CameraView =>
+    new CameraViewElement(options) as unknown as CameraView
+  Object.defineProperty(factory, "isSupported", {
+    get: (): boolean => NativeView.isSupported("camera"),
+  })
+  return factory as any
+})()

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
+})()