lecodes-sdk 2.2.13 → 2.2.14

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.13",
+  "version": "2.2.14",
   "files": [
     "src",
     "dist",

package/src/compile/serverSplit.ts

@@ -2,14 +2,14 @@
  * The client/server split of a project (docs/backend-plan.md §4).
  *
  * `*.server.ts` files never reach the client bundle: `compileProject` swaps each one for a STUB
- * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__serverOnly` — client SDK
+ * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__pushChannel`, `__serverOnly` — client SDK
  * globals, src/runtime/rpc.ts), so `import { listNotes } from "./notes.server"` in client code keeps
  * its types and calls the server. `compileServerBundle` bundles the same files with the SERVER inject
  * behind a synthetic entry that registers every module on `globalThis.__lecodesServer` (chisel keeps
  * side effects, not entry exports) — the runner reads that (src/server/runtime.ts).
  *
  * Export kinds are found by a static scan (no TS program needed): a function export is an
- * endpoint, a `channel<…>()…` export is a channel, anything else is server-only.
+ * endpoint, a `channel<…>()…` export is a channel, a `pushChannel<…>()` export a push channel, anything else is server-only.
  */
 
 import type { AppConfig } from "../server/auth/appConfig"
@@ -29,7 +29,7 @@ export const serverModuleId = (path: string) => path.split("\\").join("/").repla
  * a helper: a function that is not async is used by server files alone, and the app's import of
  * it is refused at compile time (serverTypes.ts), never a call that silently holds a promise.
  */
-export type ServerExportKind = "fn" | "channel" | "other"
+export type ServerExportKind = "fn" | "channel" | "push" | "other"
 export type ServerExport = { name: string, kind: ServerExportKind }
 
 // ───────────────────────────── static export scan ─────────────────────────────
@@ -66,6 +66,7 @@ const IDENT = "[A-Za-z_$][\\w$]*"
 const classifyInit = (init: string): ServerExportKind => {
   const s = init.trimStart()
   if (/^channel\s*[<(]/.test(s)) return "channel"
+  if (/^pushChannel\s*[<(]/.test(s)) return "push"
   if (/^async\s+function\b/.test(s)) return "fn"
   if (/^async\b/.test(s)) return "fn"                              // async (…) => / async x =>
   return "other"                                                    // a sync function, a value: the server's own
@@ -113,38 +114,43 @@ export const scanServerExports = (source: string, path = "<server module>"): Ser
 // ───────────────────────────── client stubs ─────────────────────────────
 
 /** The client-side replacement of a `*.server.ts` module. `serverUrl` is baked in (draft/prod are
- *  separate compiles); "" means "no server deployed" — calls fail with a clear error. */
-export const serverStubSource = (path: string, exports: ServerExport[], serverUrl: string): string => {
+ *  separate compiles); "" means "no server deployed" — calls fail with a clear error. `push` = the project
+ *  has push channels (in this module or another): the stub opens by installing the push runtime, so the
+ *  transport registers the device when the server asks, whether or not the app hears a channel itself. */
+export const serverStubSource = (path: string, exports: ServerExport[], serverUrl: string, push = exports.some(e => e.kind === "push")): string => {
   const mod = serverModuleId(path)
   const url = JSON.stringify(serverUrl)
   const lines = exports.map(({ name, kind }) => {
     const id = JSON.stringify(`${mod}#${name}`)
     if (kind === "fn") return `export const ${name} = __rpc(${url}, ${id})`
     if (kind === "channel") return `export const ${name} = __channel(${url}, ${id})`
+    if (kind === "push") return `export const ${name} = __pushChannel(${url}, ${id})`
     return `export const ${name} = __serverOnly(${id})`
   })
+  if (push) lines.unshift("__pushEnable()")
   return `// client stub of ${mod} — generated by the lecodes compiler\n${lines.join("\n")}\n`
 }
 
 // ───────────────────────────── a channel in the app ─────────────────────────────
 
 /** A channel export has ONE type on both sides, so `publish` type-checks in the app — where the
- *  export is the subscribing proxy. Said at compile time, with what to do instead. */
+ *  export is the subscribing proxy; a push channel's `send` likewise. Said at compile time, with what to do instead. */
 export class ClientPublishError extends Error {
   readonly problems: string[]
   constructor(problems: string[]) {
-    super(`a channel goes from the server to the app — the app subscribes; to send, call a server function that publishes:\n  ${problems.join("\n  ")}`)
+    super(`a channel goes from the server to the app — the app listens; to send, call a server function that publishes (a push channel: that sends):\n  ${problems.join("\n  ")}`)
     this.name = "ClientPublishError"
     this.problems = problems
   }
 }
 
-/** `<channel>.publish(` in the project's client files, for every channel imported from a `*.server.ts`. */
+/** `<channel>.publish(` and `<pushChannel>.send(` in the project's client files, for every channel imported from a `*.server.ts`. */
 export const clientPublishes = (entries: CompileEntry[]): string[] => {
-  const channels = new Map<string, Set<string>>()
+  /** module → export name → the server's verb */
+  const channels = new Map<string, Map<string, string>>()
   for (const [path, exports] of Object.entries(scanServerModules(entries))) {
-    const names = exports.filter(e => e.kind === "channel").map(e => e.name)
-    if (names.length) channels.set(path.replace(/\.[tj]s$/, ""), new Set(names))
+    const names = new Map(exports.filter(e => e.kind === "channel" || e.kind === "push").map(e => [e.name, e.kind === "push" ? "send" : "publish"]))
+    if (names.size) channels.set(path.replace(/\.[tj]s$/, ""), names)
   }
   if (channels.size === 0) return []
   const out: string[] = []
@@ -152,21 +158,22 @@ export const clientPublishes = (entries: CompileEntry[]): string[] => {
     if (e.type !== "text" || isServerPath(e.path) || !/\.[tj]sx?$/.test(e.path)) continue
     const src = e.text ?? ""
     const dir = normalizePath(e.path).replace(/\/[^/]*$/, "")
-    const locals: string[] = []
+    const locals: [string, string][] = []
     for (const m of src.matchAll(/import\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g)) {
       if (!m[2].startsWith(".")) continue
       const names = channels.get(normalizePath(`${dir}/${m[2]}`).replace(/\.[tj]s$/, ""))
       if (!names) continue
       for (const part of m[1].split(",")) {
         const [imported, local] = part.split(/\s+as\s+/).map(s => s.trim())
-        if (imported && names.has(imported)) locals.push(local ?? imported)
+        const verb = imported ? names.get(imported) : undefined
+        if (verb) locals.push([local ?? imported, verb])
       }
     }
     if (!locals.length) continue
     const code = blankCommentsAndStrings(src)
-    for (const local of locals) {
-      for (const m of code.matchAll(new RegExp(`(?<![\\w$.])${local.replace(/\$/g, "\\$")}\\s*\\.\\s*publish\\s*\\(`, "g"))) {
-        out.push(`${serverModuleId(e.path)}:${code.slice(0, m.index).split("\n").length}: ${local}.publish(…)`)
+    for (const [local, verb] of locals) {
+      for (const m of code.matchAll(new RegExp(`(?<![\\w$.])${local.replace(/\$/g, "\\$")}\\s*\\.\\s*${verb}\\s*\\(`, "g"))) {
+        out.push(`${serverModuleId(e.path)}:${code.slice(0, m.index).split("\n").length}: ${local}.${verb}(…)`)
       }
     }
   }
@@ -228,10 +235,13 @@ export const scanServerModules = (entries: CompileEntry[]): Record<string, Serve
 }
 
 /** Replace each `*.server.ts` entry with its client stub (returns a new entries array). */
-export const stubServerEntries = (entries: CompileEntry[], serverUrl: string): CompileEntry[] =>
-  entries.map(e => e.type === "text" && isServerPath(e.path)
-    ? { ...e, text: serverStubSource(e.path, scanServerExports(e.text ?? "", serverModuleId(e.path)), serverUrl) }
+export const stubServerEntries = (entries: CompileEntry[], serverUrl: string): CompileEntry[] => {
+  const modules = scanServerModules(entries)
+  const push = Object.values(modules).some(exports => exports.some(e => e.kind === "push"))
+  return entries.map(e => e.type === "text" && isServerPath(e.path)
+    ? { ...e, text: serverStubSource(e.path, modules[normalizePath(e.path)] ?? [], serverUrl, push) }
     : e)
+}
 
 export type CompileServerOptions = {
   entries: CompileEntry[]

package/src/compile/serverTypes.ts

@@ -237,7 +237,7 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     if (!modSym) continue
     const exported = new Map(checker.getExportsOfModule(modSym).map(s => [s.name, s]))
     for (const ex of exports) {
-      if (ex.kind === "other") continue
+      if (ex.kind === "other" || ex.kind === "push") continue
       const id = `${serverModuleId(path)}#${ex.name}`
       let sym = exported.get(ex.name)
       if (!sym) { warnings.push(`${id}: export not found by the checker — unvalidated`); continue }

package/src/inject.ts

@@ -43,10 +43,11 @@ export { WebSocket } from "./runtime/net"
 export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform, type NetCorrection } from "./net"
 // App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
 // only ever imports its server functions (docs/backend-plan.md §4).
-export { __rpc, __channel, __serverOnly, RpcError } from "./runtime/rpc"
+export { __rpc, __channel, __pushChannel, __serverOnly, RpcError } from "./runtime/rpc"
 // What a screen asks of the server, as reactive state: a request a screen follows, an action with its own busy / error.
 export { resource, action, dataOf, failureOf, type Loaded, type Failure, type Resource, type Action } from "./runtime/resource"
 export type { ChannelSubscription } from "./server/channel"
+export type { PushChannel, PushMessage, PushNotification, PushTarget } from "./server/pushChannel"
 export type { StoredFile, StoredImage } from "./server/files/models"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
 // Game audio (docs/audio-plan.md): decoded clips, a voice pool, buses with effects; 3D through the
@@ -162,7 +163,7 @@ export {
   type MapPaddingValues, type MarkerItem, type MarkerTap, type MarkerLayer, type MarkerLayerOptions,
   type LineLayer, type LineLayerOptions, type UserLocationOptions,
 } from "./plugins/gen/map/sdk/map"
-export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/gen/push/sdk/push"
+export { Push, __pushEnable, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/gen/push/sdk/push"
 export { Browser, WebView, type BrowserOpenOptions, type WebViewParams, type WebViewEvents } from "./plugins/gen/browser/sdk/browser"
 export {
   RTCPeerConnection, MediaStream, MediaStreamTrack, RTCDataChannel, RTCRtpSender, RTCRtpReceiver, RTCRtpTransceiver,

package/src/plugin.ts

@@ -44,6 +44,9 @@ export { Quat, type QuatLike } from "./math/quat"
 export { Mat4 } from "./math/mat4"
 export type { ClickEvent, TouchStartEvent } from "./runtime/touch"
 export type { DismissOptions } from "./ui/presentable"
+/** The seam the push plugin's wrapper installs its runtime on (src/runtime/pushSeam.ts): what the app's transport
+ *  reads the device's address from, registers through, and a push channel's handlers are kept by. */
+export { _pushRuntime, type PushRuntime } from "./runtime/pushSeam"
 /** @internal The navigation epoch: a destination that prepares before it presents (ARScene) reads it
  *  before its awaits and gives up when another navigation moved it meanwhile. */
 export { _navEpoch }

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

@@ -7,14 +7,22 @@
 // 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.
+//
+// A notification reaches the JS world through this channel ALONE: a tap is the "tap" event (or
+// `getLaunch()` for the one that started the process — the SDK's wrapper replays it into the first
+// "tap" listener), a foreground arrival is "message". Its `url` is the app's to route — it does NOT
+// ride the app's deep-link path (`app.launchUrl`, the "url" event).
 
 import type { Json, Service, i32 } from "../../../plugin"
 
 /** A delivered notification, as the app sees it. */
 export interface PushPayload {
+  /** The push channel it was sent through — the id of the `pushChannel()` export of the project's
+   *  server (`<path>#<name>`). Absent = sent outside one (a push key, `lecodes pn send`). */
+  channel?: string
   title: string
   body?: string
-  /** A deep link — it also rides the app's own link path (`app.launchUrl`, the "url" event). */
+  /** A deep link, for the app to open itself (it does not ride `app.launchUrl`). */
   url?: string
   /** The developer's own JSON object, ≤ 2 KB serialized. */
   data?: { [key: string]: Json }
@@ -26,6 +34,8 @@ export interface PushStatus {
   permission: "granted" | "denied" | "prompt"
   /** Whether this device holds a registration (an address) for this app. */
   registered: boolean
+  /** The device's address for this app, when it is registered. @since 2 */
+  address?: string
 }
 
 export interface PushRegisterOptions {
@@ -38,10 +48,19 @@ export interface PushRegistration {
   address: string
 }
 
+/** What the app shows itself when a notification arrives while it is in the foreground (the
+ *  "message" event): the host shows the system banner for every other one. */
+export interface PushHandled {
+  /** The push channels with a foreground handler. */
+  channels: string[]
+  /** Whether notifications sent outside a channel have one. */
+  untyped: boolean
+}
+
 export interface PushParams {}
 
 export interface PushEvents {
-  /** Arrived while this app was in the foreground (the host shows no banner). */
+  /** Arrived while this app was in the foreground and the app handles it (PushHandled): no banner. */
   message: PushPayload
   /** Tapped while the world was alive. */
   tap: PushPayload
@@ -58,4 +77,7 @@ export interface Push extends Service<"push", PushParams, PushEvents> {
   unregister(): Promise<void>
   /** The notification that cold-started this world, or null. Stable across calls. */
   getLaunch(): Promise<PushPayload | null>
+  /** Which notifications the app handles itself in the foreground; the rest get the system banner.
+   *  Until it is called nothing is handled. @since 2 */
+  setMessageHandled(handled: PushHandled): Promise<void>
 }

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

@@ -1,15 +1,15 @@
 // 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.
+// push: the service "push", contract version 2.
 
 import { ServiceChannel } from "../../../../plugin"
-import type { PushEvents, PushParams, PushPayload, PushRegisterOptions, PushRegistration, PushStatus } from "../contract"
+import type { PushEvents, PushHandled, 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
+export const VERSION = 2
 
 // ---- the wire, call by call ----------------------------------------------------------------------
 
@@ -31,15 +31,23 @@ export const unregister = (service: ServiceChannel<PushEvents>): Promise<void> =
 export const getLaunch = (service: ServiceChannel<PushEvents>): Promise<PushPayload | null> =>
   service._call("getLaunch", []).then((w: any) => w ?? null)
 
+/** Which notifications the app handles itself in the foreground; the rest get the system banner.
+ *  Until it is called nothing is handled.
+ *  Contract version 2: an older half rejects the call — ask `supports("setMessageHandled")`. */
+export const setMessageHandled = (service: ServiceChannel<PushEvents>, handled: PushHandled): Promise<void> =>
+  service._call("setMessageHandled", [handled], 2)
+
 // ---- what the host's half has --------------------------------------------------------------------
 
 /** A method of the contract. */
-export type Method = "getStatus" | "register" | "unregister" | "getLaunch"
+export type Method = "getStatus" | "register" | "unregister" | "getLaunch" | "setMessageHandled"
+
+const SINCE: { [method: string]: number } = { setMessageHandled: 2 }
 
 /** 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
+  ServiceChannel.supports(NAME, method === undefined ? 1 : SINCE[method] ?? 1)
 
 // ---- the client -----------------------------------------------------------------------------------
 
@@ -57,4 +65,8 @@ export class PushBase extends ServiceChannel<PushEvents> {
   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) }
+  /** Which notifications the app handles itself in the foreground; the rest get the system banner.
+   *  Until it is called nothing is handled.
+   *  Contract version 2: an older half rejects the call — ask `supports("setMessageHandled")`. */
+  setMessageHandled(handled: PushHandled): Promise<void> { return setMessageHandled(this, handled) }
 }

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

@@ -4,102 +4,206 @@
 // 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.
+// Two readers of this module:
+//   - the app, through `Push`: the permission (`register`), the state (`getStatus`), and the
+//     notifications sent OUTSIDE a push channel — a push key, `lecodes pn send` — as events;
+//   - the SDK's transport and its push-channel proxies, through the runtime `__pushEnable()`
+//     installs (lecodes-sdk/plugin `_pushRuntime`): the device's address for the `x-lecodes-push`
+//     header, the registration the server asks for, the handlers of each `pushChannel()` export.
+//     The compiler puts `__pushEnable()` at the top of every server stub of a project with push
+//     channels, so an app that has none never carries this module.
 //
 // 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.
+// exactly two delivery paths:
+//   - "tap":     tapped, whether the app was running or the tap started it (the cold start is
+//                read with the service's getLaunch once and replayed into the first matching
+//                tap handler, AFTER the top-level code — the handler may route);
+//   - "message": arrived while this app was in the foreground AND the app handles it (a message
+//                handler of its channel, or an untyped one): the host shows no banner for those,
+//                and the system banner for every other.
+// A payload's `url` is the app's to route; it does not ride the deep-link path.
 //
-// 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.
+// A notification is heard ONCE: one sent through a push channel by its channel's handlers, one
+// sent outside a channel by the untyped listeners (`Push.addEventListener`).
+//
+// The OS permission prompt happens inside `register()`; `getStatus()` never prompts. On a host
+// without the service every method rejects at once, BEFORE any permission path.
 
-import { NAME, PushBase } from "./push.gen"
+import { NAME, PushBase, supports } from "./push.gen"
+import { _pushRuntime } from "../../../../plugin"
 import type { PushEvents, PushPayload, PushRegisterOptions, PushRegistration, PushStatus } from "../contract"
 
 export type { PushPayload, PushRegisterOptions, PushStatus }
 
 export type PushEvent = keyof PushEvents
+type Handler = (payload: PushPayload) => void
+/** Handlers by push channel id; "" = the untyped ones. */
+type Handlers = Map<string, Set<Handler>>
 
-/**
- * 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__*/ (() => {
+const built = /*#__PURE__*/ (() => {
   let client: PushBase | null = null
   const service = (): PushBase => client ??= new PushBase()
+  const supported = (): boolean => supports()
 
   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)) {
+    if (!supported()) {
       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
+  // ── the address: what the transport tells the server ──
+  let address: string | null = null
+  const learn = (a: string | null | undefined): void => { if (a) address = a }
+
+  // ── the handlers ──
+  const taps: Handlers = new Map()
+  const messages: Handlers = new Map()
+  const add = (map: Handlers, key: string, fn: Handler): void => {
+    let set = map.get(key)
+    if (!set) map.set(key, set = new Set())
+    set.add(fn)
+  }
+  const remove = (map: Handlers, key: string, fn: Handler): void => { map.get(key)?.delete(fn) }
+  /** A payload's handlers: its channel's, or the untyped ones when it was sent outside a channel. */
+  const handlersOf = (map: Handlers, p: PushPayload): Set<Handler> | undefined => map.get(p.channel ?? "")
+  const dispatch = (map: Handlers, p: PushPayload): void => {
+    const set = handlersOf(map, p)
+    if (set) for (const fn of [...set]) fn(p)
+  }
+
+  // Events arrive on a live session only; a handler opens the pipe. The prompt-free getStatus is the
+  // opening call, and it tells the address of an earlier registration.
+  let piped = false
   const ensurePipe = (): void => {
-    if (pipeOpened || !PushBase.supports(NAME)) return
-    pipeOpened = true
-    service().getStatus().catch(() => { pipeOpened = false })
+    if (piped || !supported()) return
+    piped = true
+    const s = service()
+    s.on("tap", (p: PushPayload) => dispatch(taps, p))
+    s.on("message", (p: PushPayload) => dispatch(messages, p))
+    s.getStatus().then(st => learn(st.address), () => {})
+  }
+
+  // The notification that started the process: replayed into the first tap handler that matches it,
+  // asynchronously — after the top-level code that attached the handler, so it may route.
+  let launch: Promise<PushPayload | null> | null = null
+  let launchDelivered = false
+  const replayLaunch = (): void => {
+    if (launchDelivered || !supported()) return
+    launch ??= service().getLaunch().catch(() => null)
+    launch.then(p => {
+      if (!p || launchDelivered) return
+      const set = handlersOf(taps, p)
+      if (!set?.size) return                       // its handler may be attached later: tried again then
+      launchDelivered = true
+      for (const fn of [...set]) fn(p)
+    })
+  }
+
+  // What the host shows no banner for in the foreground: the channels with a message handler.
+  const announceHandled = (): void => {
+    if (!supports("setMessageHandled")) return
+    const channels = [...messages].filter(([key, set]) => key && set.size).map(([key]) => key)
+    service().setMessageHandled({ channels, untyped: (messages.get("")?.size ?? 0) > 0 }).catch(() => {})
+  }
+
+  /** One handler of one kind for one channel ("" = untyped); returns its remover. Recording on an
+   *  unsupported host is a silent no-op (the events never fire), like app / device listeners. */
+  const listen = (kind: PushEvent, channel: string, fn: Handler): () => void => {
+    const map = kind === "tap" ? taps : messages
+    add(map, channel, fn)
+    ensurePipe()
+    if (kind === "tap") replayLaunch()
+    else announceHandled()
+    return () => {
+      remove(map, channel, fn)
+      if (kind === "message") announceHandled()
+    }
+  }
+
+  // The server asked this device to register (the envelope's `push: true`): once per run. The prompt
+  // appears only when the permission was never asked; a refusal is final (the OS asks no twice).
+  let asked = false
+  const requestRegister = (): void => {
+    if (asked || !supported()) return
+    asked = true
+    service().getStatus()
+      .then(st => {
+        learn(st.address)
+        if (st.permission === "denied") return
+        return service().register({}).then(r => learn(r.address))
+      })
+      .catch(() => {})
   }
 
   const push = {
     async getStatus(): Promise<PushStatus> {
       assertSupported()
-      return await service().getStatus()
+      const st = await service().getStatus()
+      learn(st.address)
+      return st
     },
 
     async register(options?: PushRegisterOptions): Promise<PushRegistration> {
       assertSupported()
-      return await service().register(options ?? {})
+      const r = await service().register(options ?? {})
+      learn(r.address)
+      return r
     },
 
     async unregister(): Promise<void> {
       assertSupported()
       await service().unregister()
+      address = null
     },
 
-    async getLaunch(): Promise<PushPayload | null> {
-      assertSupported()
-      return (await service().getLaunch()) ?? null
+    addEventListener(event: PushEvent, callback: Handler): void {
+      listen(event, "", callback)
     },
-
-    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)
+    removeEventListener(event: PushEvent, callback: Handler): void {
+      remove(event === "tap" ? taps : messages, "", callback)
+      if (event === "message") announceHandled()
     },
   }
   Object.defineProperty(push, "isSupported", {
-    get: (): boolean => PushBase.supports(NAME),
+    get: (): boolean => supported(),
   })
-  return push as any
+
+  const runtime = {
+    address: (): string | null => address,
+    requestRegister,
+    on: listen,
+  }
+  return { push, runtime }
 })()
+
+/**
+ * Remote push notifications. `Push.isSupported` reports whether this host registered the
+ * service — check it before offering notification features.
+ *
+ * A project with a backend needs none of this: its `pushChannel()` exports are heard with their
+ * own `onTap` / `onMessage`, and the device is registered when the server asks (after a sign-in).
+ * `Push` is for the rest — a permission asked at a moment of the app's choosing, and the
+ * notifications sent outside a channel (a push key, `lecodes pn send`).
+ */
+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 notifications sent outside a push channel: "tap" = tapped (the one that started the app
+   *  too); "message" = arrived while the app is open (the app shows it, the host no banner). */
+  addEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void
+  removeEventListener(event: PushEvent, callback: (payload: PushPayload) => void): void
+} = built.push as any
+
+/** Installs the push runtime for the SDK's transport and its push-channel proxies (lecodes-sdk/plugin
+ *  `_pushRuntime`). A line of every server stub of a project with push channels — never app code. */
+export const __pushEnable = (): void => { _pushRuntime.current = built.runtime }

package/src/runtime/pushSeam.ts

@@ -0,0 +1,22 @@
+/**
+ * The seam between the app's transport (./rpc.ts) and the push plugin's wrapper (src/plugins/gen/push/sdk/push.ts).
+ *
+ * A push channel (`pushChannel()` of a *.server.ts file — src/server/pushChannel.ts) is heard in the app through
+ * the plugin: its taps and foreground arrivals come off the plugin's service. The transport, for its part, tells
+ * the server the device's address (the `x-lecodes-push` header of every call) and registers the device when the
+ * server asks for it (the envelope's `push: true`). Neither may import the wrapper: an app without push channels
+ * would then carry the plugin. So the wrapper installs itself here — `__pushEnable()`, a line the compiler puts at
+ * the top of every server stub of a project with push channels — and the transport reads what is installed.
+ */
+export type PushRuntime = {
+  /** This device's address for the app, once known (after a registration, or the status of an earlier one). */
+  address(): string | null
+  /** The server asked this device to register: once per run, prompt-free when the permission was given,
+   *  nothing past a refusal. */
+  requestRegister(): void
+  /** Hear the taps ("tap") or the foreground arrivals ("message") of one push channel, by its id. Returns the remover. */
+  on(kind: "tap" | "message", channel: string, handler: (payload: any) => void): () => void
+}
+
+/** What the wrapper installed; null = the app has no push channels (or the plugin is not in the bundle). */
+export const _pushRuntime: { current: PushRuntime | null } = { current: null }