lecodes-cli 0.6.4 → 0.7.1

package/runtime/sdk/gl/scenarios.ts

@@ -0,0 +1,349 @@
+// No-code scenario aspects: ready-made behaviors a scene builder attaches in the editor without
+// writing any code — move to a target, travel a waypoint path, spin, face something, start a GLB
+// animation. They are ordinary aspects (work from hand-written code too); in the scene editor the
+// movement ones double as `static editor` generators that draw their paths as editor-only lines
+// (edges meshes under `this.generated` — play mode never calls rebuild(), so the lines cost
+// nothing at runtime).
+//
+// Conventions shared by the family:
+//   • targets/waypoints are scene nodes — place an Empty, then pick it in the inspector (`ref()`);
+//   • times are seconds, angles degrees; all motion runs in `update(dt)` (play mode only);
+//   • orientation is quaternion-composed — never euler-incremented (see math/quat.ts).
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import type { InspectorUI } from "../core/InspectorUI"
+import { Vec3 } from "../math/vec"
+import { Quat } from "../math/quat"
+import { Node } from "./Node"
+import { Mesh } from "./Mesh"
+import { Model } from "./Model"
+import { Geometry } from "./Geometry"
+import { Material } from "./Material"
+
+const MOVE_LINE = "#5b8ef0"
+const LOOK_LINE = "#d9a13f"
+const DEG2RAD = Math.PI / 180
+
+type LoopMode = "once" | "loop" | "pingpong"
+
+/** Normalized phase for elapsed time `t` over one trip of `duration`: once clamps at 1, loop
+ *  wraps, pingpong triangles 0→1→0. */
+const phase = (t: number, duration: number, mode: LoopMode): number => {
+  if (duration <= 0) return 1
+  const u = t / duration
+  if (mode === "once") return Math.min(u, 1)
+  if (mode === "loop") return u - Math.floor(u)
+  const v = u % 2
+  return v <= 1 ? v : 2 - v
+}
+
+const ease = (k: number, easing: "smooth" | "linear"): number =>
+  easing === "smooth" ? k * k * (3 - 2 * k) : k
+
+/** A world point in `node`'s PARENT space — what `node.position` is expressed in. */
+const toParentLocal = (node: Node, world: Vec3): Vec3 => {
+  const parent = node.parent
+  return parent ? parent.worldMatrix.invert().transformPoint(world) : world
+}
+
+// ---- editor line drawing (edit mode only — see rebuild() on the aspects below) -------------------
+
+/** @internal An "edges" line mesh from flat segment endpoints ([x,y,z, x,y,z] per segment) —
+ *  editor-only visuals (path lines here, node markers in defineScene). */
+export const edgesMesh = (segments: number[], color: string): Mesh => {
+  const vertices = new Float32Array(segments)
+  const count = vertices.length / 3
+  const normals = new Float32Array(count * 3)
+  for (let i = 0; i < count; i++) normals[i * 3 + 1] = 1
+  const indices = new Uint16Array(count)
+  for (let i = 0; i < count; i++) indices[i] = i
+  const geo = new Geometry(vertices, normals, indices, new Float32Array(count * 2))
+  geo.kind = "edges"
+  const mesh = Mesh.from(geo, { material: Material.unlit({ color }), name: "__editor_line" })
+  mesh.castShadows = false
+  mesh.receiveShadows = false
+  return mesh
+}
+
+const pushCross = (segments: number[], p: Vec3, s: number): void => {
+  segments.push(p.x - s, p.y, p.z, p.x + s, p.y, p.z)
+  segments.push(p.x, p.y - s, p.z, p.x, p.y + s, p.z)
+  segments.push(p.x, p.y, p.z - s, p.x, p.y, p.z + s)
+}
+
+/** `this.generated` hangs UNDER the host node, so line points (world space) must be expressed in
+ *  the host's local frame; the host is an editor-run dep of its own aspects, so dragging it
+ *  re-runs rebuild() and the conversion stays fresh. */
+const worldSegmentsToLocal = (node: Node, segments: number[]): number[] => {
+  const inv = node.worldMatrix.invert()
+  const out: number[] = []
+  for (let i = 0; i < segments.length; i += 3) {
+    const p = inv.transformPoint([ segments[i]!, segments[i + 1]!, segments[i + 2]! ])
+    out.push(p.x, p.y, p.z)
+  }
+  return out
+}
+
+/** A path node's waypoints: its children in scene-FILE order (`_sceneChildOrder`, stamped by
+ *  defineScene — the engine's live child order is insertion-based and may differ), editor helper
+ *  nodes (`__`-prefixed) excluded. Runtime-added children append in engine order. */
+const pathWaypoints = (path: Node): Node[] => {
+  const children = path.children.filter((c) => !(c.name ?? "").startsWith("__"))
+  const order = (path as { _sceneChildOrder?: string[] })._sceneChildOrder
+  if (!order) return children
+  const byName = new Map(children.map((c) => [ c.name, c ]))
+  const sorted: Node[] = []
+  for (const n of order) { const c = byName.get(n); if (c) sorted.push(c) }
+  const seen = new Set(sorted)
+  for (const c of children) if (!seen.has(c)) sorted.push(c)
+  return sorted
+}
+
+// ---- the aspects ---------------------------------------------------------------------------------
+
+/** Travel from the node's starting position to a target node in `duration` seconds. */
+export class MoveTo extends Aspect<"moveTo"> {
+  /** Where to travel — place an Empty node and pick it. */
+  target: Node | null = null
+
+  /** Seconds for the full trip. */
+  duration = 2
+
+  /** Seconds to wait before starting. */
+  delay = 0
+
+  /** once = stop at the target · loop = restart from the start point · pingpong = back and forth. */
+  mode: LoopMode = "once"
+
+  /** Motion curve. */
+  easing: "smooth" | "linear" = "smooth"
+
+  static readonly aspect = "moveTo"
+  static editor = { rebuild: true }
+  static fields: FieldMeta<MoveTo> = {
+    target: { editor: "node" },
+    duration: { min: 0.05, max: 120, step: 0.05 },
+    delay: { min: 0, max: 120, step: 0.05 },
+    mode: { options: [ "once", "loop", "pingpong" ] },
+    easing: { options: [ "smooth", "linear" ] },
+  }
+
+  private _t = 0
+  private _start: Vec3 | null = null
+
+  update(dt: number): void {
+    if (!this.target) return
+    this._start ??= this.node.position
+    this._t += dt
+    const k = ease(phase(Math.max(0, this._t - this.delay), this.duration, this.mode), this.easing)
+    const end = toParentLocal(this.node, this.target.worldPosition)
+    this.node.position = new Vec3(this._start).add(end.sub(this._start).scale(k))
+  }
+
+  /** Editor-only path line (edit mode; play mode never calls this). */
+  rebuild(): void {
+    this.generated.clear()
+    if (!this.target) return
+    const segments: number[] = []
+    const a = this.node.worldPosition
+    const b = this.target.worldPosition
+    segments.push(a.x, a.y, a.z, b.x, b.y, b.z)
+    pushCross(segments, b, 0.09)
+    this.generated.add(edgesMesh(worldSegmentsToLocal(this.node, segments), MOVE_LINE))
+  }
+}
+
+/** Travel through the children of a path node (add an Empty per waypoint) in `duration` seconds.
+ *  `loop` runs the circuit closed (last → first); `pingpong` goes back and forth along the open
+ *  path; `once` stops at the last waypoint. */
+export class FollowPath extends Aspect<"followPath"> {
+  /** A node whose CHILDREN are the waypoints, in file order. */
+  path: Node | null = null
+
+  /** Seconds for one full pass of the path. */
+  duration = 6
+
+  /** Seconds to wait before starting. */
+  delay = 0
+
+  mode: LoopMode = "loop"
+
+  /** Turn to face the direction of travel. */
+  orient = true
+
+  /** Which local axis leads when orienting. */
+  forward: "-z" | "z" | "x" | "-x" = "-z"
+
+  static readonly aspect = "followPath"
+  static editor = { rebuild: true }
+  static fields: FieldMeta<FollowPath> = {
+    path: { editor: "node" },
+    duration: { min: 0.05, max: 300, step: 0.05 },
+    delay: { min: 0, max: 120, step: 0.05 },
+    mode: { options: [ "loop", "once", "pingpong" ] },
+    forward: { options: [ "-z", "z", "x", "-x" ] },
+  }
+
+  private _t = 0
+
+  private _points(): Vec3[] {
+    if (!this.path) return []
+    const points = pathWaypoints(this.path).map((c) => c.worldPosition)
+    if (this.mode === "loop" && points.length > 1) points.push(points[0]!.clone())
+    return points
+  }
+
+  update(dt: number): void {
+    const points = this._points()
+    if (points.length < 2) return
+    this._t += dt
+    const k = phase(Math.max(0, this._t - this.delay), this.duration, this.mode === "loop" ? "loop" : this.mode)
+
+    const lengths: number[] = []
+    let total = 0
+    for (let i = 0; i < points.length - 1; i++) {
+      const l = points[i + 1]!.sub(points[i]!).length()
+      lengths.push(l)
+      total += l
+    }
+    if (total <= 0) return
+
+    let dist = k * total
+    let i = 0
+    while (i < lengths.length - 1 && dist > lengths[i]!) { dist -= lengths[i]!; i++ }
+    const a = points[i]!
+    const b = points[i + 1]!
+    const seg = b.sub(a)
+    const u = lengths[i]! > 0 ? Math.min(dist / lengths[i]!, 1) : 0
+    const world = a.add(seg.scale(u))
+    this.node.position = toParentLocal(this.node, world)
+    if (this.orient && seg.lengthSq() > 1e-12) this.node.lookAt(world.add(seg), this.forward)
+  }
+
+  /** Editor-only waypoint polyline (edit mode; play mode never calls this). */
+  rebuild(): void {
+    this.generated.clear()
+    const points = this._points()
+    if (points.length < 2) return
+    const segments: number[] = []
+    for (let i = 0; i < points.length - 1; i++) {
+      const a = points[i]!, b = points[i + 1]!
+      segments.push(a.x, a.y, a.z, b.x, b.y, b.z)
+    }
+    for (const p of points) pushCross(segments, p, 0.07)
+    this.generated.add(edgesMesh(worldSegmentsToLocal(this.node, segments), MOVE_LINE))
+  }
+}
+
+/** Continuous rotation about one of the node's local axes, degrees per second. */
+export class Spin extends Aspect<"spin"> {
+  /** Degrees per second. */
+  speed = 45
+
+  /** Local axis to spin around. */
+  axis: "x" | "y" | "z" = "y"
+
+  static readonly aspect = "spin"
+  static fields: FieldMeta<Spin> = {
+    speed: { min: -720, max: 720, step: 5 },
+    axis: { options: [ "x", "y", "z" ] },
+  }
+
+  update(dt: number): void {
+    const axis: [number, number, number] = this.axis === "x" ? [ 1, 0, 0 ] : this.axis === "y" ? [ 0, 1, 0 ] : [ 0, 0, 1 ]
+    // compose in quaternion space about the LOCAL axis (q ⊗ dq) — never euler-increment
+    this.node.quaternion = this.node.quaternion.mul(Quat.fromAxisAngle(axis, this.speed * dt * DEG2RAD))
+  }
+}
+
+/** Keep the node facing a target node (a turret tracking, a signpost, a camera aimed at a hero).
+ *  Accessor `node.facing` — NOT `lookAt`, which would shadow the `Node.lookAt()` method. */
+export class LookAt extends Aspect<"facing"> {
+  /** The node to face. */
+  target: Node | null = null
+
+  /** Which local axis points at the target. */
+  forward: "-z" | "z" | "x" | "-x" = "-z"
+
+  /** 0 = snap instantly; otherwise seconds of turn lag (bigger = slower, smoother). */
+  smoothing = 0
+
+  static readonly aspect = "facing"
+  static editor = { rebuild: true }
+  static fields: FieldMeta<LookAt> = {
+    target: { editor: "node" },
+    forward: { options: [ "-z", "z", "x", "-x" ] },
+    smoothing: { min: 0, max: 5, step: 0.05 },
+  }
+
+  update(dt: number): void {
+    if (!this.target) return
+    const point = this.target.worldPosition
+    if (this.smoothing <= 0) { this.node.lookAt(point, this.forward); return }
+    const q0 = this.node.quaternion
+    this.node.lookAt(point, this.forward)
+    const q1 = this.node.quaternion
+    this.node.quaternion = q0.slerp(q1, 1 - Math.exp(-dt / this.smoothing))
+  }
+
+  /** Editor-only sight line (edit mode; play mode never calls this). */
+  rebuild(): void {
+    this.generated.clear()
+    if (!this.target) return
+    const segments: number[] = []
+    const a = this.node.worldPosition
+    const b = this.target.worldPosition
+    segments.push(a.x, a.y, a.z, b.x, b.y, b.z)
+    pushCross(segments, b, 0.07)
+    this.generated.add(edgesMesh(worldSegmentsToLocal(this.node, segments), LOOK_LINE))
+  }
+}
+
+/** Start a GLB animation clip when the scene runs. Attach to a `model:` node; the inspector card
+ *  lists the model's clips live and can preview them while editing. */
+export class PlayAnimation extends Aspect<"playAnimation", Model> {
+  /** Clip name; empty = the model's first clip. */
+  clip = ""
+
+  loop = true
+
+  /** Playback rate (1 = authored speed). */
+  speed = 1
+
+  static readonly aspect = "playAnimation"
+  static fields: FieldMeta<PlayAnimation> = {
+    speed: { min: 0.05, max: 5, step: 0.05 },
+  }
+
+  onAttach(): void {
+    const anim = (this.node as Model | undefined)?.anim
+    if (!anim) return
+    anim.speed = this.speed
+    anim.play(this.clip === "" ? 0 : this.clip, { loop: this.loop })
+  }
+
+  static inspector(ui: InspectorUI, a: PlayAnimation): void {
+    const anim = (a.node as Model | undefined)?.anim
+    const clips = anim?.clips ?? []
+    if (clips.length === 0) {
+      ui.warn("No animation clips — attach this to a GLB model node")
+      return
+    }
+    ui.select("clip", clips.map((c) => c.name))
+    ui.auto("loop", "speed")
+    if (anim) {
+      if (ui.button(anim.playing ? "Restart preview" : "Preview")) {
+        anim.speed = a.speed
+        anim.play(a.clip === "" ? 0 : a.clip, { loop: a.loop })
+      }
+      if (anim.playing && ui.button("Stop")) {
+        anim.stop()
+        anim.time = 0
+      }
+      const clip = a.clip === "" ? clips[0]?.name : a.clip
+      const duration = clips.find((c) => c.name === clip)?.duration
+      ui.info(anim.playing ? "previewing…" : duration !== undefined ? `${duration.toFixed(2)}s` : "")
+    }
+  }
+}

package/runtime/sdk/inject.ts

@@ -16,6 +16,7 @@ export { Color } from "./core/color"
 
 // ---- aspects (attachable node capabilities) ----
 export { Aspect, type With } from "./core/Aspect"
+export { InspectorUI } from "./core/InspectorUI"
 
 // ---- reactivity (signals; UI text/style props also accept `() => value` bindings) ----
 export { signal, computed, effect, type Signal, type Computed } from "./core/signals"
@@ -24,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"
@@ -52,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,
@@ -60,30 +62,48 @@ export {
   UIVideo, type UIVideoStyle,
   UIInput, UITextArea, type UIInputStyle,
   UIScrollable, type UIScrollableStyle,
+  UIScreenHost, type UIScreenHostStyle,
   UIWidget, type UIWidgetStyle,
   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"
 
+// ---- UI kit (pure-TS components built on the core UI globals; see packages/sdk/src/kit/) ----
+export { UITabs, type UITabItem } from "./kit/UITabs"
+
 // ---- 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/) ----
+// ---- 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, SceneHandle } from "./scene/defineScene"
-export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, AspectEntry, LoadedScene } from "./scene/defineScene"
+export { defineScene, use, ref, make, SceneHandle } from "./scene/defineScene"
+export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, CameraNodeDef, AspectEntry, MakeEntry, LoadedScene } from "./scene/defineScene"
 export type { FieldMeta } from "./core/fields"
 
+// ---- no-code scenario aspects (attachable in the scene editor — see src/gl/scenarios.ts) ----
+export { MoveTo, FollowPath, Spin, LookAt, PlayAnimation } from "./gl/scenarios"
+
+// ---- editor plugins (called from `*.editor.ts` files — editor bundles only; DCE'd from apps) ----
+export { registerEditorWindow, registerEditorTool, __editorPlugins } from "./scene/editorPlugins"
+export type { EditorApi, EditorRayHit, EditorToolHooks, EditorWindowFn } from "./scene/editorPlugins"
+
 // ---- 3D engine (creator-gl) ----
 export { Scene, ARScene, VRScene } from "./gl/Scene"
 export { Node } from "./gl/Node"

package/runtime/sdk/kit/UITabs.ts

@@ -0,0 +1,105 @@
+// UITabs — a self-contained tab component: a swipe-disabled UIScreenHost of tab screens + a bar of
+// tap-to-switch buttons. Pure TS over UIScreenHost, no native work. It's just an element — you place
+// it inside your own UIScreen and own the routing; UITabs only switches the visible tab.
+//
+//   Router.push(UIScreen([
+//     UITabs([
+//       { icon: homeSvg, label: "Home",    content: HomeScreen() },
+//       { icon: userSvg, label: "Profile", content: ProfileScreen() },
+//     ]),
+//   ]))
+//
+// A tab's content is a full UIScreen (screens are the only page kind UIScreenHost accepts): it gets
+// onOpen/onClose from the host's settle lifecycle, plus makeScrollable/onRefresh. All tabs stay
+// mounted, so switching is instant and per-tab state survives.
+
+import { UIScreenHost, type HostedScreen } from "../ui/UIScreenHost"
+import { UIRow, UIColumn, type UIColumn as UIColumnType } from "../ui/UIContainer"
+import { UIButton } from "../ui/UIButton"
+import { UIText } from "../ui/UIText"
+import { UIImage, type ImageSource } from "../ui/UIImage"
+import type { UINodeChild } from "../ui/UINode"
+
+export interface UITabItem {
+  /** Icon image source (SvgSource / url / File / Canvas). Optional. */
+  icon?: ImageSource
+  /** Label under the icon. Optional. */
+  label?: string
+  /** Tab content — a full UIScreen (wrap a plain element: `UIScreen([el])`). */
+  content: HostedScreen
+}
+
+/** The tabs element (a UIColumn) plus a small control surface. Embed it like any element. */
+export interface UITabs extends UIColumnType {
+  /** Switch the visible tab. */
+  select(index: number): this
+  onChange(callback: (index: number) => void): this
+  /** Active tab index. */
+  readonly index: number
+  /** The bar row — style it or its item buttons directly. */
+  readonly bar: UIRow
+}
+
+const clamp = (v: number, min: number, max: number) => Math.max(min, Math.min(max, v))
+
+function tabButton(item: UITabItem, i: number, onSelect: (i: number) => void): ReturnType<typeof UIButton> {
+  const parts: UINodeChild[] = []
+  if (item.icon) parts.push(UIImage({ width: 24, height: 24 }, item.icon))
+  if (item.label) parts.push(UIText({ fontSize: 11, lineHeight: 14, textAlign: "center" }, item.label))
+
+  // Chained .style() (not the legacy first-arg object) — required for the `$active` class block.
+  const btn = UIButton(parts).style({
+    flexGrow: 1,
+    flexBase: 0,
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 3,
+    paddingVertical: 4,
+    opacity: 0.55,
+    $active: { opacity: 1, duration: 150 },
+  })
+  btn.onClick(() => onSelect(i))
+  return btn
+}
+
+export function UITabs(items: UITabItem[]): UITabs {
+  let index = 0
+  const listeners: ((index: number) => void)[] = []
+
+  const host = UIScreenHost(items.map(it => it.content))
+    .style({ swipeEnabled: false, flexGrow: 1, flexShrink: 1 })
+
+  const barItems = items.map((it, i) => tabButton(it, i, select))
+  const bar = UIRow({
+    flexShrink: 0,
+    paddingTop: 8,
+    paddingBottom: "safe-bottom",
+    borderTopWidth: 1,
+    borderTopColor: "#00000022",
+  }, barItems)
+
+  const applyActive = (i: number) => {
+    for (let k = 0; k < barItems.length; k++) barItems[k].setClass("active", k === i)
+  }
+
+  function select(i: number): UITabs {
+    i = clamp(i, 0, Math.max(0, items.length - 1))
+    if (i !== index) {
+      index = i
+      host.setPage(i, false)
+      applyActive(i)
+      for (const cb of listeners) cb(i)
+    }
+    return view
+  }
+
+  applyActive(0)
+
+  const view = UIColumn([ host, bar ]) as unknown as UITabs
+  ;(view as any).select = select
+  ;(view as any).onChange = (cb: (index: number) => void) => { listeners.push(cb); return view }
+  ;(view as any).bar = bar
+  Object.defineProperty(view, "index", { get: () => index })
+  return view
+}

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