lecodes-sdk 1.2.0 → 2.0.0

package/src/plugins/{map.ts → gen/map/sdk/map.ts}

@@ -1,22 +1,33 @@
-// MapView — a vector map (maplibre-native on iOS/Android) as a Presentable. A typed wrapper over
-// the `NativeView("map")` capability (docs/map-plugin-plan.md): push it (`Router.push(map)`),
-// open it fullscreen (`map.open()`), or embed it among a screen's children where the host builds
-// the "native" layout node. The style is a URL, a bundled `asset()`, a read file or the style
-// object (see MapStyle). Data goes in as named layers (`map.markers(name)`, `map.line(name)`)
-// whose `set()` replaces their content; the camera is driven with `flyTo` / `fitPoints`; the user
-// puck is fed by the app (`setUserLocation`) — the plugin never touches the location hardware.
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/map/sdk/map.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.
+// MapView — a vector map (maplibre-native on iOS / Android, maplibre-gl in the browser) as a view
+// the app pushes (`Router.push(map)`), opens fullscreen (`map.open()`) or embeds among a screen's
+// children. The style is a name, a URL, a bundled `asset()`, a read file or the style object (see
+// MapStyle). Data goes in as named layers (`map.markers(name)`, `map.line(name)`) whose `set()`
+// replaces their content; the camera is driven with `flyTo` / `fitPoints`; the user puck is fed by
+// the app (`setUserLocation`) — the plugin never touches the location hardware.
 //
-// Host-OPTIONAL: it exists where the host registers a "map" view (the `map` plugin from
-// lecodes-plugins) — gate on `MapView.isSupported`. Everything here is sugar over ONE JSON channel
-// (`call` / `on`); the wire contract is the method/event table in docs/map-plugin-plan.md.
-//
-// Ordering: the native map exists only once presented and its style loaded — the plugin emits
-// `ready` then. Data and camera calls issued before that are queued and replayed in order, so an
-// app can build the map declaratively and push it later without a ready-dance of its own.
-
-import { NativeView, NativeViewElement } from "../ui/NativeView"
-import { _channelOn } from "../runtime/channel"
-import type { FetchResponse } from "../runtime/fetch"
+// Hand-written over the generated wire because the public API is higher than the wire:
+//   - a style is resolved to a url or to text HERE, once, at creation;
+//   - marker items and coordinate lists become GeoJSON here;
+//   - the native map exists only once presented and its style loaded (`ready`): calls issued before
+//     that are queued and replayed in order, so an app builds the map declaratively and pushes it
+//     later without a ready-dance of its own;
+//   - what lives in the STYLE (layers, data, the padding, the user puck) is kept and re-applied
+//     after every style load.
+
+import { ViewChannel, bufferText, type FetchResponse, type Json, type NativeView } from "../../../../plugin"
+import { NAME, ensureLayer, fitPoints, flyTo, getCamera, jumpTo, setData, setPadding, setUserLocation } from "./map.gen"
+import type {
+  LngLat, MapCamera, MapCameraMove, MapEvents, MapFitOptions, MapLayerKind, MapPadding, MapParams,
+  MapTap as WireTap, MapUserLocationOptions,
+} from "../contract"
+
+export type { LngLat, MapCamera }
+export type CameraMove = MapCameraMove
+export type FitOptions = MapFitOptions
+export type MapPaddingValues = MapPadding
+export type UserLocationOptions = MapUserLocationOptions
 
 /** The ready-made styles a map falls back on — [OpenFreeMap](https://openfreemap.org): OSM data,
  *  no key, no registration, no request limits, commercial use allowed, and the whole stack is
@@ -56,34 +67,12 @@ const NAMED_STYLES: Record<string, string> = {
 // `string & {}` keeps the named suggestions in the editor while still accepting any URL.
 export type MapStyle = MapStyleName | (string & {}) | FetchResponse | object
 
-/** `[longitude, latitude]` — GeoJSON order, the same as the style, the tiles and your data. */
-export type LngLat = [number, number]
-
-export interface MapCamera {
-  center: LngLat
-  zoom: number
-  /** Degrees clockwise from north. */
-  bearing: number
-  /** Degrees from the vertical. */
-  pitch: number
-}
-
-export interface MapOptions {
+export interface MapOptions extends Omit<MapParams, "style" | "styleJson"> {
   /** The MapLibre style: a ready-made name (`"liberty"` — the default, `"positron"`, …), a URL,
    *  a style bundled with the app (`asset("./style.json")`), an already-read file
    *  (`fetchLocal("style.json")`, `await fetch(url)`) or the style object itself — see
    *  {@link MapStyle}. */
   style?: MapStyle
-  center?: LngLat
-  zoom?: number
-  minZoom?: number
-  maxZoom?: number
-  bearing?: number
-  pitch?: number
-  /** Two-finger rotate gesture (default true). */
-  rotate?: boolean
-  /** Two-finger tilt gesture (default false — most city maps stay flat). */
-  tilt?: boolean
 }
 
 /** A tap on the map itself — not on a feature of a managed layer. */
@@ -93,29 +82,6 @@ export interface MapTap {
   point: [number, number]
 }
 
-export interface CameraMove {
-  zoom?: number
-  bearing?: number
-  pitch?: number
-  /** Animation length, ms (flyTo only; default 600). */
-  duration?: number
-}
-
-export interface MapPaddingValues {
-  top?: number | string
-  left?: number | string
-  bottom?: number | string
-  right?: number | string
-}
-
-export interface FitOptions {
-  /** Px around the points, or per edge. Added to the view padding set by `setPadding`. */
-  padding?: number | MapPaddingValues
-  maxZoom?: number
-  /** Default true. */
-  animate?: boolean
-}
-
 /** One marker. `id` comes back in `onTap`; `icon` names an image of the style's sprite; `color` /
  *  `title` feed the default layers; extra keys become feature properties. */
 export interface MarkerItem {
@@ -151,13 +117,6 @@ export interface LineLayerOptions {
   opacity?: number
 }
 
-export interface UserLocationOptions {
-  /** Horizontal accuracy radius, meters — drawn as the halo around the dot. */
-  accuracy?: number | null
-  /** Degrees clockwise from north — drawn as the direction wedge; null hides it. */
-  heading?: number | null
-}
-
 export interface MarkerLayer {
   readonly name: string
   /** Replace the layer's markers. */
@@ -208,15 +167,21 @@ export interface MapView extends NativeView {
   setUserLocation(lngLat: LngLat | null, options?: UserLocationOptions): this
 }
 
+/** The wire's calls the wrapper sends without waiting for an answer, by name: what a queue entry
+ *  replays. Every one takes the view first. */
+const SEND = { ensureLayer, setData, flyTo, jumpTo, fitPoints, setPadding, setUserLocation }
+type Send = typeof SEND
+type SendArgs<M extends keyof Send> = Send[M] extends (view: any, ...args: infer A) => any ? A : never
+
 type Queued = { method: string, args: any[] }
-type LayerSpec = { kind: "markers" | "line", options: object }
+type LayerSpec = { kind: MapLayerKind, options: object }
 
 /** Methods whose effect lives in the STYLE, not in the view: a style (re)load wipes them, so the
  *  wrapper keeps their last value and re-applies it on every `ready` instead of replaying them
  *  from the queue. Camera calls are not here — the camera survives a style reload. */
 const STATEFUL = ["ensureLayer", "setData", "setPadding", "setUserLocation"]
 
-class MapViewElement extends NativeViewElement {
+class MapViewElement extends ViewChannel<MapEvents> {
   private _ready = false
   private _queue: Queued[] = []
   private readonly _layers = new Map<string, MapLayerHandle>()
@@ -224,18 +189,18 @@ class MapViewElement extends NativeViewElement {
   private readonly _specs = new Map<string, LayerSpec>()
   private readonly _data = new Map<string, object>()
   private _padding?: MapPaddingValues
-  private _user?: any[]
+  private _user?: SendArgs<"setUserLocation">
   private readonly _readyCallbacks: (() => void)[] = []
   private readonly _tapCallbacks: ((tap: MapTap) => void)[] = []
   private readonly _moveCallbacks: ((camera: MapCamera) => void)[] = []
   private readonly _errorCallbacks: ((error: { message: string }) => void)[] = []
 
   constructor(options: MapOptions = {}) {
-    super("map", _styleParams(options))
-    _channelOn(this.nvl, "ready", () => this._onReady())
-    _channelOn(this.nvl, "tap", (data: any) => this._onTap(data))
-    _channelOn(this.nvl, "moveEnd", (data: any) => { for (const cb of [...this._moveCallbacks]) cb(data) })
-    _channelOn(this.nvl, "error", (data: any) => this._onError(data))
+    super("MapView", NAME, _styleParams(options))
+    this.on("ready", () => this._onReady())
+    this.on("tap", tap => this._onTap(tap))
+    this.on("moveEnd", camera => { for (const cb of [...this._moveCallbacks]) cb(camera) })
+    this.on("error", error => this._onError(error))
   }
 
   onReady(callback: () => void): this { this._readyCallbacks.push(callback); return this }
@@ -251,7 +216,7 @@ class MapViewElement extends NativeViewElement {
   }
   setData(source: string, geojson: object): this {
     this._data.set(source, geojson)
-    this._send("setData", [source, geojson])
+    this._send("setData", [source, geojson as Json])
     return this
   }
 
@@ -259,22 +224,23 @@ class MapViewElement extends NativeViewElement {
   jumpTo(center: LngLat, options: CameraMove = {}): this { this._send("jumpTo", [center, options]); return this }
   fitPoints(points: LngLat[], options: FitOptions = {}): this { this._send("fitPoints", [points, options]); return this }
   setPadding(padding: MapPaddingValues): this { this._padding = padding; this._send("setPadding", [padding]); return this }
-  getCamera(): Promise<MapCamera> { return this.call("getCamera") }
+  getCamera(): Promise<MapCamera> { return getCamera(this) }
 
   setUserLocation(lngLat: LngLat | null, options: UserLocationOptions = {}): this {
     this._user = [lngLat, options]
-    this._send("setUserLocation", [lngLat, options])
+    this._send("setUserLocation", this._user)
     return this
   }
 
   /** @internal queue until `ready`, then straight through. Rejections are logged, never thrown:
-   *  a fire-and-forget camera/data call has no caller to reject to. */
-  _send(method: string, args: any[]): void {
+   *  a fire-and-forget camera / data call has no caller to reject to. */
+  _send<M extends keyof Send>(method: M, args: SendArgs<M>): void {
     if (!this._ready) { this._queue.push({ method, args }); return }
-    this.call(method, ...args).catch((e: Error) => console.error(`MapView.${method}: ${e.message}`))
+    const call: (view: this, ...args: any[]) => Promise<void> = SEND[method] ?? ((view, ...rest) => view._call(method, rest))
+    call(this, ...args).catch((e: Error) => console.error(`MapView.${method}: ${e.message}`))
   }
 
-  private _layer(name: string, kind: "markers" | "line", options: object): MapLayerHandle {
+  private _layer(name: string, kind: MapLayerKind, options: object): MapLayerHandle {
     let layer = this._layers.get(name)
     if (!layer) {
       layer = new MapLayerHandle(this, name)
@@ -294,28 +260,28 @@ class MapViewElement extends NativeViewElement {
     const queue = this._queue
     this._queue = []
     for (const [name, spec] of this._specs) this._send("ensureLayer", [name, spec.kind, spec.options])
-    for (const [source, geojson] of this._data) this._send("setData", [source, geojson])
+    for (const [source, geojson] of this._data) this._send("setData", [source, geojson as Json])
     if (this._padding) this._send("setPadding", [this._padding])
     if (this._user) this._send("setUserLocation", this._user)
-    for (const q of queue) if (STATEFUL.indexOf(q.method) < 0) this._send(q.method, q.args)
+    for (const q of queue) if (STATEFUL.indexOf(q.method) < 0) this._send(q.method as keyof Send, q.args as any)
     for (const cb of [...this._readyCallbacks]) cb()
   }
 
-  private _onError(data: any): void {
+  private _onError(error: { message: string }): void {
     // Unhandled is not unheard: a style the host couldn't load is exactly the failure that looks
     // like "the map is blank and nothing happened".
-    if (this._errorCallbacks.length === 0) { console.error(`MapView: ${data?.message ?? "unknown error"}`); return }
-    for (const cb of [...this._errorCallbacks]) cb(data)
+    if (this._errorCallbacks.length === 0) { console.error(`MapView: ${error?.message ?? "unknown error"}`); return }
+    for (const cb of [...this._errorCallbacks]) cb(error)
   }
 
-  private _onTap(data: any): void {
-    const feature = data?.feature
+  private _onTap(tap: WireTap): void {
+    const feature = tap?.feature
     const layer = feature ? this._layers.get(feature.source) : undefined
-    if (layer) {
-      layer._tap({ id: feature.id, lngLat: data.lngLat, properties: feature.properties ?? {} })
+    if (feature && layer) {
+      layer._tap({ id: feature.id as string | number, lngLat: tap.lngLat, properties: feature.properties ?? {} })
       return
     }
-    for (const cb of [...this._tapCallbacks]) cb({ lngLat: data.lngLat, point: data.point })
+    for (const cb of [...this._tapCallbacks]) cb({ lngLat: tap.lngLat, point: tap.point })
   }
 }
 
@@ -348,15 +314,15 @@ class MapLayerHandle {
   }
 }
 
-/** @internal `MapOptions` → host params. A style URL stays a url the map fetches itself; every
+/** @internal `MapOptions` → the wire's params. A style URL stays a url the map fetches itself; every
  *  other form is read HERE and crosses as `styleJson` text — one string, once, at creation. A
  *  bundled `asset()` is `"id:N"` in shell compiles (the host already holds the bytes) and a plain
  *  url in server compiles, so the same call works on every host. */
-export const _styleParams = (options: MapOptions = {}): any => {
+export const _styleParams = (options: MapOptions = {}): MapParams => {
   const { style = "liberty", ...rest } = options
   if (typeof style === "string") {
     if (!style.startsWith("id:")) return { ...rest, style: NAMED_STYLES[style] ?? style }
-    const text = _creatorUtils.fetchToText(+style.slice(3))
+    const text = bufferText(+style.slice(3))
     if (!text) throw new Error("MapView: the style asset is empty or missing")
     return { ...rest, styleJson: text }
   }
@@ -380,9 +346,9 @@ export const _toGeoJson = (items: MarkerItem[] | LngLat[]): object => {
 
 /**
  * Create a map view. `MapView.isSupported` reports whether this host registered a "map" view —
- * check it before offering the feature (web, headless and shells without the plugin have none).
+ * check it before offering the feature.
  */
-// PURE IIFE so an app that never uses the map tree-shakes the whole plugin away (see NativeView).
+// PURE IIFE so an app that never uses the map tree-shakes the whole plugin away.
 export const MapView: {
   (options?: MapOptions): MapView
   /** Whether this host registered a "map" view. */
@@ -390,7 +356,7 @@ export const MapView: {
 } = /*#__PURE__*/ (() => {
   const factory = (options: MapOptions = {}): MapView => new MapViewElement(options) as unknown as MapView
   Object.defineProperty(factory, "isSupported", {
-    get: (): boolean => NativeView.isSupported("map"),
+    get: (): boolean => ViewChannel.supports(NAME),
   })
   return factory as any
 })()

package/src/plugins/gen/push/contract.d.ts

@@ -0,0 +1,61 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/push/contract.d.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.
+// push — remote notifications (APNs on iOS, FCM on Android).
+// The host owns the OS token, the permission prompt and the registration with the le.codes relay;
+// the app sees the opaque project-scoped ADDRESS and the payloads, never the raw token.
+//
+// An OPEN SESSION is the delivery pipe of the events. Opening one is free (no prompt, no I/O).
+// Identity: every call is attributed to the world that makes it (the project's uuid, held by the
+// host); a world without one rejects "unavailable" BEFORE any permission path.
+
+import type { Json, Service, i32 } from "../../../plugin"
+
+/** A delivered notification, as the app sees it. */
+export interface PushPayload {
+  title: string
+  body?: string
+  /** A deep link — it also rides the app's own link path (`app.launchUrl`, the "url" event). */
+  url?: string
+  /** The developer's own JSON object, ≤ 2 KB serialized. */
+  data?: { [key: string]: Json }
+  badge?: i32
+}
+
+export interface PushStatus {
+  /** The OS permission of the host app. "prompt" = not asked yet. */
+  permission: "granted" | "denied" | "prompt"
+  /** Whether this device holds a registration (an address) for this app. */
+  registered: boolean
+}
+
+export interface PushRegisterOptions {
+  /** The app's OWN user id. Client-asserted and unverified. The registration reflects the latest
+   *  call: registering without it clears it. */
+  user?: string
+}
+
+export interface PushRegistration {
+  address: string
+}
+
+export interface PushParams {}
+
+export interface PushEvents {
+  /** Arrived while this app was in the foreground (the host shows no banner). */
+  message: PushPayload
+  /** Tapped while the world was alive. */
+  tap: PushPayload
+}
+
+export interface Push extends Service<"push", PushParams, PushEvents> {
+  /** Permission + registration state. Never prompts. */
+  getStatus(): Promise<PushStatus>
+  /** Ask for the permission (the first time) and register this device. Idempotent.
+   *  @rejects denied unavailable */
+  register(options?: PushRegisterOptions): Promise<PushRegistration>
+  /** Remove this device's registration.
+   *  @rejects unavailable */
+  unregister(): Promise<void>
+  /** The notification that cold-started this world, or null. Stable across calls. */
+  getLaunch(): Promise<PushPayload | null>
+}

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

@@ -0,0 +1,60 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/push/sdk/push.gen.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.
+// GENERATED by `lecodes plugin gen` from contract.d.ts — do not edit.
+// push: the service "push", contract version 1.
+
+import { ServiceChannel } from "../../../../plugin"
+import type { PushEvents, PushParams, PushPayload, PushRegisterOptions, PushRegistration, PushStatus } from "../contract"
+
+/** What the halves register under. */
+export const NAME = "push"
+/** The contract's version: the highest `@since` of its members. */
+export const VERSION = 1
+
+// ---- the wire, call by call ----------------------------------------------------------------------
+
+/** Permission + registration state. Never prompts. */
+export const getStatus = (service: ServiceChannel<PushEvents>): Promise<PushStatus> =>
+  service._call("getStatus", [])
+
+/** Ask for the permission (the first time) and register this device. Idempotent.
+ *  Rejects with "denied" / "unavailable". */
+export const register = (service: ServiceChannel<PushEvents>, options?: PushRegisterOptions): Promise<PushRegistration> =>
+  service._call("register", [options])
+
+/** Remove this device's registration.
+ *  Rejects with "unavailable". */
+export const unregister = (service: ServiceChannel<PushEvents>): Promise<void> =>
+  service._call("unregister", [])
+
+/** The notification that cold-started this world, or null. Stable across calls. */
+export const getLaunch = (service: ServiceChannel<PushEvents>): Promise<PushPayload | null> =>
+  service._call("getLaunch", []).then((w: any) => w ?? null)
+
+// ---- what the host's half has --------------------------------------------------------------------
+
+/** A method of the contract. */
+export type Method = "getStatus" | "register" | "unregister" | "getLaunch"
+
+/** Whether this host has the service "push" — and, given a method, a half new enough for it
+ *  (a method added after the first version of the contract is tagged `@since`). */
+export const supports = (method?: Method): boolean =>
+  ServiceChannel.supports(NAME)   // every method is of version 1
+
+// ---- the client -----------------------------------------------------------------------------------
+
+/** The service "push" with the wire's methods as its own. */
+export class PushBase extends ServiceChannel<PushEvents> {
+  constructor(params: PushParams = {}) { super("Push", NAME, params) }
+
+  /** Permission + registration state. Never prompts. */
+  getStatus(): Promise<PushStatus> { return getStatus(this) }
+  /** Ask for the permission (the first time) and register this device. Idempotent.
+   *  Rejects with "denied" / "unavailable". */
+  register(options?: PushRegisterOptions): Promise<PushRegistration> { return register(this, options) }
+  /** Remove this device's registration.
+   *  Rejects with "unavailable". */
+  unregister(): Promise<void> { return unregister(this) }
+  /** The notification that cold-started this world, or null. Stable across calls. */
+  getLaunch(): Promise<PushPayload | null> { return getLaunch(this) }
+}

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

@@ -0,0 +1,105 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/push/sdk/push.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.
+// Push — remote notifications. The host owns the OS token, the permission prompt and the
+// registration with the le.codes relay; the app only ever sees the opaque project-scoped ADDRESS
+// (never the raw APNs / FCM token) plus payloads.
+//
+// Hand-written over the generated wire because the public API is a module singleton with
+// `addEventListener`, and a listener must OPEN the session: events arrive on a live one only.
+//
+// The app is not running when a push arrives — display is host / OS work. The JS world sees
+// exactly three delivery paths:
+//   - event "message": arrived while this app was foregrounded (the host suppresses the banner)
+//   - event "tap":     tapped while the world was alive (warm)
+//   - getLaunch():     the notification that cold-started this world (stable pull, or null)
+// A payload's `url` additionally rides the app-lifecycle deep-link path (`app.launchUrl` /
+// the "url" event), so apps that already route links get notification routing for free.
+//
+// The OS permission prompt happens inside `register()`; `getStatus()` and `getLaunch()` never
+// prompt. On a host without the service every method rejects at once, BEFORE any permission path.
+
+import { NAME, PushBase } from "./push.gen"
+import type { PushEvents, PushPayload, PushRegisterOptions, PushRegistration, PushStatus } from "../contract"
+
+export type { PushPayload, PushRegisterOptions, PushStatus }
+
+export type PushEvent = keyof PushEvents
+
+/**
+ * Remote push notifications. `Push.isSupported` reports whether this host registered the
+ * service — check it before offering notification features.
+ */
+// PURE IIFE so an app that never uses push tree-shakes the whole plugin away.
+export const Push: {
+  /** Whether this host registered a "push" service. */
+  readonly isSupported: boolean
+  /** Permission + registration state. Never prompts. */
+  getStatus(): Promise<PushStatus>
+  /** Ask for permission (first time) and register this device → the opaque address your server
+   *  targets. Idempotent — safe to call every launch; rejects "denied" / "unavailable". */
+  register(options?: PushRegisterOptions): Promise<PushRegistration>
+  /** Remove this device's registration (the address stops receiving). */
+  unregister(): Promise<void>
+  /** The notification that cold-started this app run, or null. Stable across calls. */
+  getLaunch(): Promise<PushPayload | null>
+  /** "message" = received while the app is open; "tap" = the user tapped one while it ran. */
+  addEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void
+  removeEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void
+} = /*#__PURE__*/ (() => {
+  let client: PushBase | null = null
+  const service = (): PushBase => client ??= new PushBase()
+
+  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.
+    if (!PushBase.supports(NAME)) {
+      throw new Error('Push isn\'t available on this host — it needs a registered "push" service.')
+    }
+  }
+
+  // `on` only records listeners; events need a live session to arrive on. Poke the host with the
+  // prompt-free getStatus once so a listener-only app (already registered on a previous run)
+  // still hears warm taps.
+  let pipeOpened = false
+  const ensurePipe = (): void => {
+    if (pipeOpened || !PushBase.supports(NAME)) return
+    pipeOpened = true
+    service().getStatus().catch(() => { pipeOpened = false })
+  }
+
+  const push = {
+    async getStatus(): Promise<PushStatus> {
+      assertSupported()
+      return await service().getStatus()
+    },
+
+    async register(options?: PushRegisterOptions): Promise<PushRegistration> {
+      assertSupported()
+      return await service().register(options ?? {})
+    },
+
+    async unregister(): Promise<void> {
+      assertSupported()
+      await service().unregister()
+    },
+
+    async getLaunch(): Promise<PushPayload | null> {
+      assertSupported()
+      return (await service().getLaunch()) ?? null
+    },
+
+    addEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void {
+      // Recording on an unsupported host is a silent no-op (the events just never fire),
+      // like app / device listeners — only the promise-returning methods reject loudly.
+      service().on(event, callback)
+      ensurePipe()
+    },
+    removeEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void {
+      service().off(event, callback)
+    },
+  }
+  Object.defineProperty(push, "isSupported", {
+    get: (): boolean => PushBase.supports(NAME),
+  })
+  return push as any
+})()

package/src/plugins/gen/qr-scanner/contract.d.ts

@@ -0,0 +1,16 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/qr-scanner/contract.d.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.
+// qr-scanner — a camera view that decodes QR codes.
+// A view with events only: the app opens / embeds it and listens.
+
+import type { View } from "../../../plugin"
+
+export interface QRScannerParams {}
+
+export interface QRScannerEvents {
+  /** One per decoded camera frame: the payload, or null for a frame with no readable code (it
+   *  repeats while the user aims). The same code may be reported more than once. */
+  scan: { data: string | null }
+}
+
+export interface QRScanner extends View<"qrScanner", QRScannerParams, QRScannerEvents> {}

package/src/plugins/gen/qr-scanner/sdk/qr-scanner.gen.ts

@@ -0,0 +1,29 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/qr-scanner/sdk/qr-scanner.gen.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.
+// GENERATED by `lecodes plugin gen` from contract.d.ts — do not edit.
+// qr-scanner: the view "qrScanner", contract version 1.
+
+import { ViewChannel } from "../../../../plugin"
+import type { QRScannerEvents, QRScannerParams } from "../contract"
+
+/** What the halves register under. */
+export const NAME = "qrScanner"
+/** The contract's version: the highest `@since` of its members. */
+export const VERSION = 1
+
+// ---- what the host's half has --------------------------------------------------------------------
+
+/** A method of the contract. */
+export type Method = never
+
+/** Whether this host has the view "qrScanner" — and, given a method, a half new enough for it
+ *  (a method added after the first version of the contract is tagged `@since`). */
+export const supports = (method?: Method): boolean =>
+  ViewChannel.supports(NAME)   // every method is of version 1
+
+// ---- the element ----------------------------------------------------------------------------------
+
+/** The view "qrScanner" with the wire's methods as its own. */
+export class QRScannerBase extends ViewChannel<QRScannerEvents> {
+  constructor(params: QRScannerParams = {}) { super("QRScanner", NAME, params) }
+}

package/src/plugins/gen/qr-scanner/sdk/qr-scanner.ts

@@ -0,0 +1,52 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/qr-scanner/sdk/qr-scanner.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.
+// QRScanner — the host's camera QR scanner as a view the app opens fullscreen
+// (`await scanner.open()`), pushes (`Router.push(scanner)`) or embeds as a live preview.
+//
+// Hand-written over the generated wire for two things: `onScan` hands over the decoded string, not
+// the event's payload, and the permission is asked BEFORE the view is presented.
+
+import { prepareCamera, type NativeView, type PresentOptions } from "../../../../plugin"
+import { NAME, QRScannerBase } from "./qr-scanner.gen"
+
+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 the 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>
+}
+
+class QRScannerElement extends QRScannerBase {
+  onScan(callback: (data: string | null) => void): this {
+    return this.on("scan", payload => callback(payload?.data ?? null))
+  }
+
+  /** @internal prepare-then-present (see Presentable._prepare). */
+  _prepare(): Promise<void> { return prepareCamera(this) }
+
+  override async open(options?: PresentOptions): Promise<void> {
+    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.
+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 => QRScannerBase.supports(NAME),
+  })
+  return factory as any
+})()

package/src/plugins/permission.ts

@@ -1,7 +1,8 @@
-// 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
+// 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 _creatorUtils.requestCamera === "function"
-    ? new Promise<void>((res, rej) => _creatorUtils.requestCamera!(res, rej))
+  typeof _creatorDevice.requestCamera === "function"
+    ? new Promise<void>((res, rej) => _creatorDevice.requestCamera!(res, rej))
     : Promise.resolve()