lecodes-sdk 2.2.13 → 2.3.0

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/device.ts

@@ -30,11 +30,8 @@ const onResize = (width: number, height: number): void => {
 
 // --- device.hdr state ---
 // The 3D bridge is a free global that a 2D-only bundle never defines — reach it defensively. Hosts
-// without the methods are SDR by definition; the look setters are remembered so the getters read
-// back what the app asked for.
+// without the methods are SDR by definition.
 const gl = (): typeof _creator | undefined => (typeof _creator !== "undefined" ? _creator : undefined)
-let hdrStrengthLocal = 0.35
-let hdrPaperWhiteLocal = 1
 // `hdrchange` is a poll: the engine quantises the headroom to half-stops, so a change is rare and
 // a 4 Hz timer (only while someone listens) is cheaper than a per-frame bridge call.
 const hdrListeners: HdrChangeCallback[] = []
@@ -202,11 +199,13 @@ export const device = {
       return new Vec3(g.x, -g.y, g.z)
     },
   },
-  /** The display's extended dynamic range — HDR. On a screen with headroom above SDR white (Apple's
-   *  XDR panels; the macOS host today) the 3D surface is float and the engine renders past 1.0:
-   *  1.0 is the white of the UI and of a diffuse white surface, and the sun, emissives and speculars
-   *  climb up to `headroom` times that. Everywhere else it is SDR: `available` false, `headroom` 1,
-   *  the look setters remembered but invisible.
+  /** The display's extended dynamic range — HDR: the FACTS about the display. On the macOS desktop
+   *  host, in a visible window on a screen with headroom above SDR white (Apple's XDR panels, an HDR
+   *  external display), the 3D surface is float and the engine renders past 1.0: 1.0 is the white of
+   *  the UI and of a diffuse white surface, and the sun, emissives and speculars climb up to
+   *  `headroom` times that. Everywhere else it is SDR (the other hosts, a hidden window, a render to
+   *  PNG): `available` false, `headroom` 1. The LOOK on such a display — how much of the picture
+   *  reaches for the peak, where white lands — is the scene's: `scene.postProcessing.hdr`.
    *
    *  Branch content on `available`, not on `headroom` — the live value ramps up from 1 over the
    *  first seconds after launch and follows the brightness keys. Particle `emissive` is the thing
@@ -230,34 +229,6 @@ export const device = {
       const v = gl()?.getDisplayHeadroom?.() ?? 1
       return v > 1 ? v : 1
     },
-    /** How much of the picture reaches for the headroom, 0..1 (default 0.35). 0 touches only what
-     *  SDR clipped — faithful to the SDR grade, but a mostly-mid-tone frame then looks flat next to
-     *  the one bright spot; 1 lifts nearly everything above black toward the peak. A sunlit exterior
-     *  takes 1, a dim interior wants less. A host may pin it (`LECODES_HDR_STRENGTH`). */
-    get strength(): number {
-      return gl()?.getHdrStrength?.() ?? hdrStrengthLocal
-    },
-    set strength(v: number) {
-      const s = Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0.35
-      hdrStrengthLocal = s
-      gl()?.setHdrStrength?.(s)
-    },
-    /** Where white lands, as a multiple of SDR white, 1..8 (default 1) — the "HDR brightness" of a
-     *  console game's calibration screen, where paper white sits at ~200 nits against SDR's ~100.
-     *  It scales the WHOLE picture: at 1 a white wall is as bright as the UI's white, at 2 it is
-     *  twice that, and highlights still climb above it (the engine keeps `headroom / paperWhite` for
-     *  them, clamped at the peak). `strength` decides how much of the picture reaches for the
-     *  peak; this decides where the picture starts. 1.5–2 is the console norm; a game that wants to
-     *  read as "HDR on" rather than "SDR with a brighter sun" wants this over `strength`. A host may
-     *  pin it (`LECODES_HDR_PAPER_WHITE`). */
-    get paperWhite(): number {
-      return gl()?.getHdrPaperWhite?.() ?? hdrPaperWhiteLocal
-    },
-    set paperWhite(v: number) {
-      const p = Number.isFinite(v) ? Math.min(8, Math.max(1, v)) : 1
-      hdrPaperWhiteLocal = p
-      gl()?.setHdrPaperWhite?.(p)
-    },
   },
   /** Current connectivity — best-effort navigator.onLine semantics: `false` only when the platform
    *  is sure there's no network. `true` on hosts that don't track it. Change events: `"online"` /

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 }

package/src/runtime/rpc.ts

@@ -8,7 +8,8 @@
  *   export const db        = __serverOnly("schema.server.ts#db")
  *
  * Wire (implemented by the runner):
- *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
+ *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known,
+ *                               `x-lecodes-push: <address>` once the device registered for notifications
  *                               — with a `File` among the arguments: multipart, the field `args` is
  *                               that JSON with `{"$file": <i>}` where the file stood, `file<i>` the files
  *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
@@ -24,6 +25,7 @@ import { localStorage } from "./storage"
 import { WebSocket } from "./net"
 import type { ChannelGroup, ClientFrame, ServerFrame } from "./wire"
 import type { ChannelSubscription } from "../server/channel"
+import { _pushRuntime } from "./pushSeam"
 
 /** Rejection value of a failed endpoint call: `status` mirrors the server's `ApiError`
  *  (0 = the request itself failed: no network / no server). */
@@ -69,6 +71,9 @@ export const __rpc = (serverUrl: string, id: string) => {
     const headers: Record<string, string> = {}
     const session = getSession(serverUrl)
     if (session) headers.authorization = `Bearer ${session}`
+    // the device's push address, for the session to carry (src/server/auth/host.ts) — what a push channel reaches the user by
+    const pushAddress = _pushRuntime.current?.address()
+    if (pushAddress) headers["x-lecodes-push"] = pushAddress
     // a File anywhere among the arguments leaves its place to a marker and travels beside them
     const files: File[] = []
     const json = JSON.stringify({ args }, (_key, value) => value instanceof File ? { $file: files.push(value) - 1 } : value)
@@ -88,6 +93,8 @@ export const __rpc = (serverUrl: string, id: string) => {
     let body: any
     try { body = res.json() } catch { body = null }
     if (body && typeof body === "object" && "session" in body) setSession(serverUrl, body.session ?? null)
+    // the server asks this device to register for notifications: a signed-in session without an address, and push channels to hear
+    if (body && typeof body === "object" && body.push === true) _pushRuntime.current?.requestRegister()
     if (body && body.ok === true) return body.result
     if (body && body.ok === false) throw new RpcError(body.status ?? res.status, body.message ?? "")
     throw new RpcError(res.status, `Endpoint ${id}: unexpected response (HTTP ${res.status})`)
@@ -287,3 +294,30 @@ export const __channel = (serverUrl: string, id: string) => ({
     throw new RpcError(0, `Channel ${id}: the server publishes, the app subscribes — call a server function that publishes`)
   },
 })
+
+// ───────────────────────────── push channels ─────────────────────────────
+
+/**
+ * Build the client proxy of push channel `id` — what a `pushChannel()` export of a `*.server.ts` file is
+ * in the app (its type is the server's: src/server/pushChannel.ts). The notifications come off the push
+ * plugin, through the runtime its wrapper installed (`__pushEnable()`, the first line of the stubs of a
+ * project with push channels — ./pushSeam.ts): `onTap` hears this channel's taps (the one that started
+ * the app included), `onMessage` its arrivals while the app is in the foreground. On a host without the
+ * plugin a handler is recorded and never called, like the plugin's own listeners.
+ */
+export const __pushChannel = (serverUrl: string, id: string) => {
+  const listen = (kind: "tap" | "message", handler: unknown): ChannelSubscription => {
+    if (typeof handler !== "function") throw new RpcError(0, `Push channel ${id}: ${kind === "tap" ? "onTap" : "onMessage"}(handler) — no handler given`)
+    const runtime = _pushRuntime.current
+    if (!runtime) throw new RpcError(0, `Push channel ${id}: the push runtime is not installed — the compiler puts __pushEnable() in the stub of a project with push channels`)
+    const off = runtime.on(kind, id, handler as (payload: unknown) => void)
+    return { close: off }
+  }
+  return {
+    onTap: (handler: unknown): ChannelSubscription => listen("tap", handler),
+    onMessage: (handler: unknown): ChannelSubscription => listen("message", handler),
+    send(): never {
+      throw new RpcError(0, `Push channel ${id}: the server sends, the app listens — call a server function that sends${serverUrl ? "" : " (and compile with serverUrl)"}`)
+    },
+  }
+}

package/src/server/auth/host.ts

@@ -12,7 +12,13 @@
  *
  * Tokens: 32 random bytes (base64url) held by the client transport; only `sha256(token)` is stored.
  * A request without a valid token gets a fresh guest session and the token travels back in the
- * envelope (`session`); sign-in/out ROTATE the token the same way.
+ * envelope (`session`); sign-in/out ROTATE the token the same way (the row stays: what it holds of the
+ * device — its push address — survives a sign-out, and a sign-in on the same device finds it there).
+ *
+ * The push address: the transport sends the device's address at the platform's push relay in the
+ * `x-lecodes-push` header of every call (once the device registered); `resolve` keeps the session's
+ * `pushAddress` equal to it. That is the whole binding of a device to a user — a push channel's `send`
+ * reaches a user through the live sessions that carry an address (../push/host.ts).
  *
  * Identities: every sign-in method is an `Identity` row `(provider, subject)` of a user — `email:<address>`
  * or `login:<name>` (its `hash` = the password). The one rule that keeps passwords honest: proving an
@@ -114,6 +120,17 @@ const parseLogin = (login: unknown): { provider: "email" | "login", subject: str
 
 const identityKey = (provider: IdentityProvider, subject: string) => `${provider}:${subject}`
 
+/** The header the transport tells the device's push address in (src/runtime/rpc.ts). */
+export const PUSH_ADDRESS_HEADER = "x-lecodes-push"
+const PUSH_ADDRESS_RE = /^[A-Za-z0-9_-]{1,128}$/
+/** The address of this request's device, when the header carries a well-formed one. */
+const pushAddressOf = (ctx: RequestContext): string | null => {
+  const headers = ctx.headers ?? {}
+  const raw = headers[PUSH_ADDRESS_HEADER] ?? Object.entries(headers).find(([k]) => k.toLowerCase() === PUSH_ADDRESS_HEADER)?.[1]
+  const value = typeof raw === "string" ? raw.trim() : ""
+  return PUSH_ADDRESS_RE.test(value) ? value : null
+}
+
 /** A sliding-window counter per key (in-worker; the persistent limits live on the rows). */
 const window = (map: Map<string, number[]>, key: string, now: number, span: number): number[] => {
   const list = (map.get(key) ?? []).filter(x => now - x < span)
@@ -146,7 +163,7 @@ export const createAuthHost = (cfg: AuthHostConfig): AuthHost => {
   const log = cfg.log ?? ((level, text) => (level === "warn" ? console.warn(text) : console.info(text)))
 
   // token → session (60 s). Cleared on every mutation — correctness over reuse.
-  const sessionCache = new Map<string, { sessionId: number, userId: number | null, at: number }>()
+  const sessionCache = new Map<string, { sessionId: number, userId: number | null, pushAddress: string | null, at: number }>()
   const clearCache = () => { sessionCache.clear() }
 
   const requireAuth = () => {
@@ -165,9 +182,10 @@ export const createAuthHost = (cfg: AuthHostConfig): AuthHost => {
 
   const mint = async (ctx: RequestContext): Promise<AuthState> => {
     const token = randomToken()
-    const { id } = await sessions.insert({ tokenHash: await sha256(token) })
-    const state: AuthState = { sessionId: id, userId: null, issuedToken: token }
-    sessionCache.set(token, { sessionId: id, userId: null, at: now() })
+    const pushAddress = pushAddressOf(ctx)
+    const { id } = await sessions.insert({ tokenHash: await sha256(token), ...(pushAddress ? { pushAddress } : {}) })
+    const state: AuthState = { sessionId: id, userId: null, pushAddress, issuedToken: token }
+    sessionCache.set(token, { sessionId: id, userId: null, pushAddress, at: now() })
     ctx.auth = state
     ctx.sessionToken = token
     return state
@@ -188,21 +206,34 @@ export const createAuthHost = (cfg: AuthHostConfig): AuthHost => {
     if (opts.rotate) await rotate(ctx)
   }
 
+  /** The session's push address follows the header: written when it differs (a registration, a new address
+   *  after the OS rotated the token) — never cleared by a call without the header: the app may not have
+   *  asked the plugin yet in this run. */
+  const followPushAddress = async (token: string, sessionId: number, held: string | null, told: string | null): Promise<string | null> => {
+    if (!told || told === held) return held
+    await sessions.update(sessionId, { pushAddress: told })
+    const c = sessionCache.get(token)
+    if (c) c.pushAddress = told
+    return told
+  }
+
   const resolve = async (ctx: RequestContext): Promise<void> => {
     if (!tables) return
     const token = ctx.sessionToken
     if (token) {
       const c = sessionCache.get(token)
       if (c && now() - c.at < CACHE_TTL_MS) {
-        ctx.auth = { sessionId: c.sessionId, userId: c.userId }
+        const pushAddress = await followPushAddress(token, c.sessionId, c.pushAddress, pushAddressOf(ctx))
+        ctx.auth = { sessionId: c.sessionId, userId: c.userId, pushAddress }
         return
       }
-      const row = await sessions.where({ tokenHash: await sha256(token) }).select({ id: true, revoked: true, lastSeenAt: true, user: { id: true } }).first()
+      const row = await sessions.where({ tokenHash: await sha256(token) }).select({ id: true, revoked: true, lastSeenAt: true, pushAddress: true, user: { id: true } }).first()
       if (row && !row.revoked) {
         const userId: number | null = row.user ? row.user.id : null
         if (now() - (row.lastSeenAt ?? 0) > SEEN_UPDATE_MS) sessions.update(row.id, { lastSeenAt: now() }).then(undefined, () => {})
-        sessionCache.set(token, { sessionId: row.id, userId, at: now() })
-        ctx.auth = { sessionId: row.id, userId }
+        sessionCache.set(token, { sessionId: row.id, userId, pushAddress: row.pushAddress ?? null, at: now() })
+        const pushAddress = await followPushAddress(token, row.id, row.pushAddress ?? null, pushAddressOf(ctx))
+        ctx.auth = { sessionId: row.id, userId, pushAddress }
         return
       }
     }