ruby_everywhere 0.1.15 → 0.2.0

data/bridge/everywhere/bridge.js

@@ -1,5 +1,5 @@
 // @rubyeverywhere/bridge — one API for the browser, the RubyEverywhere desktop
-// shell, and (soon) Hotwire Native mobile apps.
+// shell, and Hotwire Native mobile apps.
 //
 // App code writes to this surface only; platform differences live in the
 // adapters below. Everything degrades: the same page works in a plain browser
@@ -15,6 +15,83 @@
 //   Everywhere.confirm("Sure?")          // Promise<boolean>, native dialog when possible
 //   Everywhere.on("menu", handler)       // shell events; returns unsubscribe fn
 //   Everywhere.visit("/settings")        // Turbo.visit with location fallback
+//   Everywhere.reloadTabs()              // re-fetch native tab/nav config (mobile)
+//
+//   Everywhere.haptics.impact("medium")  // light | medium | heavy | soft | rigid
+//   Everywhere.haptics.notification("success") // success | warning | error
+//   Everywhere.haptics.selection()
+//   Everywhere.badge.set(3)              // app icon badge (mobile; PWA Badging API in browsers)
+//   Everywhere.badge.clear()
+//   Everywhere.badge.setTab("/inbox", 3) // native tab bar badge (mobile)
+//   Everywhere.badge.clearTab("/inbox")
+//
+//   Everywhere.permissions.query("camera")   // Promise<{name, status}>
+//   Everywhere.permissions.request("camera") // prompts when possible
+//     status: "granted" | "denied" | "prompt" | "undeclared" | "unsupported"
+//     (mobile permissions must be declared in everywhere.yml with a usage
+//      string — undeclared ones resolve "undeclared" and never prompt)
+//   Everywhere.permissions.openSettings()    // the denied dead-end: iOS never
+//                                            // re-prompts, so send users here
+//
+//   Everywhere.biometrics.available()    // Promise<{available, biometry, status}>
+//     biometry: "faceID" | "touchID" | "opticID" | "none"
+//     status: "available" | "notEnrolled" | "notAvailable" | "lockout"
+//           | "passcodeNotSet" | "undeclared" | "unsupported"
+//   Everywhere.biometrics.authenticate({ reason: "Unlock your vault" })
+//     // Promise<{authenticated, error?}> — shows the Face ID / Touch ID sheet.
+//     // { allowPasscode: true } lets the device passcode satisfy the check.
+//     error: "canceled" | "fallback" | "lockout" | "notEnrolled"
+//          | "notAvailable" | "passcodeNotSet" | "failed" | "undeclared" | "unsupported"
+//     (mobile only, and must be declared in everywhere.yml — that's what stamps
+//      the Face ID usage string. This gates the PAGE, not the server: pair it
+//      with real session auth for anything the backend must trust.)
+//   Everywhere.biometrics.lockEnabled    // device-local "require biometrics" pref
+//   Everywhere.biometrics.setLockEnabled(true)  // Promise<{enabled, error?}>;
+//     // authenticates before flipping, in either direction
+//
+//   Everywhere.biometrics.credential     // biometric-protected keychain secret
+//     .store(token, {reason})            // Promise<{stored, error?}>
+//     .get({reason})                     // Promise<{token?, error?}> — Face ID prompt
+//     .status()                          // Promise<{enrolled}> — no prompt
+//     .clear()                           // Promise<{cleared, error?}>
+//     ("sign in with Face ID": server issues a token, store() locks it behind
+//      biometrics, get() releases it at login to exchange for a session.
+//      Enrollment changes invalidate it → get() resolves {error: "notEnrolled"}.)
+//
+//   Declarative gate (everywhere_biometric_lock / _toggle Rails helpers):
+//     <div data-everywhere-biometric-lock="key" data-everywhere-biometric-reason="…"
+//          data-everywhere-biometric-passcode>
+//       <div data-everywhere-biometric-content hidden>…</div>
+//       <div data-everywhere-biometric-locked hidden>
+//         <button data-everywhere-biometric-unlock>Unlock</button></div>
+//     </div>
+//     <input type="checkbox" hidden disabled data-everywhere-biometric-toggle>
+//   Content stays hidden until the check passes whenever lockEnabled is on in
+//   the mobile shell; elsewhere it reveals. Passes persist per JS session.
+//
+//   Declarative (no JS): the bridge watches every page for
+//     <meta name="everywhere:badge" content="3">
+//     <meta name="everywhere:tab-badge" content='{"path":"/inbox","count":3}'>
+//   (the everywhere_badge / everywhere_tab_badge Rails helpers) and applies
+//   them on each Turbo visit, and plays haptics for taps on any element with
+//   data-everywhere-haptic (e.g. "light", "impact:heavy", "notification:error").
+//
+//   Everywhere.storage.get("key")        // Promise<any|null> — device-local settings
+//   Everywhere.storage.set("key", value) // Promise<boolean>; value is any JSON value
+//   Everywhere.storage.remove("key")     // Promise<boolean>
+//   Everywhere.storage.clear()           // Promise<boolean> — app keys only
+//     Persists in the mobile shell's UserDefaults (survives web view resets
+//     and cache clears — unlike localStorage); localStorage-backed elsewhere.
+//     Settings, not secrets: tokens belong in biometrics.credential.
+//
+//   Everywhere.instance.supported        // true when the shell allows instance switching
+//   Everywhere.instance.current          // active instance URL, or null (= default root)
+//   Everywhere.instance.set(url, {to})   // persist + full reset onto the instance
+//   Everywhere.instance.clear({to})      // back to the built-in root (the picker)
+//     Multi-instance apps (remote.instances: true in everywhere.yml): the
+//     shell boots into remote.url — your hosted instance picker — until the
+//     picker calls set(); after that every launch boots the chosen instance
+//     until clear(). In a plain browser set() just navigates to the URL.
 //
 //   Everywhere.updates.supported         // true when the shell has an update feed
 //   Everywhere.updates.channel           // effective channel ("stable", "beta", …)
@@ -173,6 +250,120 @@ const browser = {
     return null
   },
 
+  // Honest approximation: the Vibration API where it exists (Android
+  // browsers); silently nothing elsewhere (iOS Safari has no equivalent).
+  haptic(kind, value) {
+    if (!navigator.vibrate) return
+    if (kind === "impact") {
+      navigator.vibrate({ light: 8, medium: 15, heavy: 25, soft: 8, rigid: 15 }[value] || 15)
+    } else if (kind === "notification") {
+      navigator.vibrate(value === "error" ? [30, 60, 30] : value === "warning" ? [20, 40, 20] : [10, 30, 10])
+    } else {
+      navigator.vibrate(5)
+    }
+  },
+
+  // App icon badge via the PWA Badging API (installed PWAs only; rejects
+  // silently elsewhere). Tab badges have no browser equivalent.
+  badgeSet(count) {
+    if (!navigator.setAppBadge) return
+    const call = count > 0 ? navigator.setAppBadge(count) : navigator.clearAppBadge()
+    if (call && call.catch) call.catch(() => {})
+  },
+
+  badgeSetTab() {},
+
+  async permissionQuery(name) {
+    if (name === "notifications" && "Notification" in window) {
+      const map = { granted: "granted", denied: "denied", default: "prompt" }
+      return { name, status: map[Notification.permission] || "prompt" }
+    }
+    if (navigator.permissions) {
+      try {
+        const result = await navigator.permissions.query({
+          name: name === "location" ? "geolocation" : name
+        })
+        return { name, status: result.state } // granted | denied | prompt
+      } catch (_) {}
+    }
+    return { name, status: "unsupported" }
+  },
+
+  // Requests use each capability's own prompt-triggering API — there is no
+  // generic "request" in browsers.
+  async permissionRequest(name) {
+    if (name === "notifications" && "Notification" in window) {
+      const result = await Notification.requestPermission()
+      return { name, status: result === "default" ? "prompt" : result }
+    }
+    if (name === "camera" && navigator.mediaDevices && navigator.mediaDevices.getUserMedia) {
+      try {
+        const stream = await navigator.mediaDevices.getUserMedia({ video: true })
+        stream.getTracks().forEach((track) => track.stop())
+        return { name, status: "granted" }
+      } catch (_) {
+        return { name, status: "denied" }
+      }
+    }
+    if (name === "location" && navigator.geolocation) {
+      return new Promise((resolve) => {
+        navigator.geolocation.getCurrentPosition(
+          () => resolve({ name, status: "granted" }),
+          (error) => resolve({ name, status: error.code === 1 ? "denied" : "prompt" })
+        )
+      })
+    }
+    return this.permissionQuery(name)
+  },
+
+  permissionOpenSettings() {},
+
+  // Web pages can't invoke Face ID / Touch ID outside WebAuthn ceremonies
+  // (which need registered credentials), so the browser answer is honest:
+  // unsupported. Gate on `available` and fall back to your normal auth.
+  biometricsAvailable() {
+    return Promise.resolve({ available: false, biometry: "none", status: "unsupported" })
+  },
+
+  biometricsAuthenticate() {
+    return Promise.resolve({ authenticated: false, error: "unsupported" })
+  },
+
+  biometricsCredential(event) {
+    return Promise.resolve(
+      event === "credentialStatus" ? { enrolled: false } : { error: "unsupported" }
+    )
+  },
+
+  // Honest fallback: localStorage under a namespaced key. Same wire shape as
+  // the mobile component — value is a JSON-encoded string or null.
+  storage(event, data) {
+    const key = data && data.key != null ? "everywhere:app:" + data.key : null
+    try {
+      switch (event) {
+        case "get":
+          return Promise.resolve({ ok: !!key, value: key ? localStorage.getItem(key) : null })
+        case "set":
+          if (!key || typeof data.value !== "string") return Promise.resolve({ ok: false })
+          localStorage.setItem(key, data.value)
+          return Promise.resolve({ ok: true })
+        case "remove":
+          if (!key) return Promise.resolve({ ok: false })
+          localStorage.removeItem(key)
+          return Promise.resolve({ ok: true })
+        case "clear":
+          for (let i = localStorage.length - 1; i >= 0; i--) {
+            const name = localStorage.key(i)
+            if (name && name.startsWith("everywhere:app:")) localStorage.removeItem(name)
+          }
+          return Promise.resolve({ ok: true })
+      }
+    } catch (_) {
+      // localStorage can throw (privacy mode, quota) — report, don't break.
+    }
+    return Promise.resolve({ ok: false })
+  },
+
   // Auto-updates only exist inside the shell; the browser tab is always "current".
   updatesCheck() {
     return Promise.resolve({ available: false, unsupported: true })
@@ -189,16 +380,266 @@ const browser = {
   }
 }
 
-// --- mobile: Hotwire Native (stub) ------------------------------------------
-// Detection is real (Hotwire Native apps set their user agent); behavior falls
-// back to the browser adapter until the bridge-component adapter lands. The
-// native webview implements confirm() properly, so that fallback is already
-// correct on mobile.
+// --- mobile: Hotwire Native --------------------------------------------------
+// The native shell injects window.nativeBridge (the native adapter). The web
+// half of the handshake is normally @hotwired/hotwire-native-bridge; apps that
+// load it keep it (same first-loaded-wins guard the official package uses).
+// Otherwise we install a minimal wire-compatible web bridge, enough for
+// component messages with replies — which is all notify() needs.
+//
+// confirm()/clipboard fall back to the browser adapter on purpose: WKWebView
+// renders window.confirm as a real native alert, and the clipboard API works.
+
+const NOTIFY_COMPONENT = "everywhere--notification"
+const HAPTICS_COMPONENT = "everywhere--haptics"
+const PERMISSIONS_COMPONENT = "everywhere--permissions"
+const BIOMETRICS_COMPONENT = "everywhere--biometrics"
+const STORAGE_COMPONENT = "everywhere--storage"
+
+function installWebBridge() {
+  if (window.HotwireNative) return
+
+  let adapter = null
+  let lastId = 0
+  const pending = []
+  const callbacks = new Map()
+
+  const web = {
+    supportsComponent(component) {
+      return adapter ? adapter.supportsComponent(component) : false
+    },
+
+    send({ component, event, data, callback }) {
+      if (!adapter) {
+        pending.push({ component, event, data, callback })
+        return null
+      }
+      if (!this.supportsComponent(component)) return null
+
+      const id = (++lastId).toString()
+      if (callback) callbacks.set(id, callback)
+      // metadata.url rides INSIDE data (the official web bridge's wire
+      // format); the native side drops messages whose metadata.url doesn't
+      // match the destination's location (Hotwire Native ≥ 1.3).
+      adapter.receive({
+        id, component, event,
+        data: { ...(data || {}), metadata: { url: window.location.href } }
+      })
+      return id
+    },
+
+    // Replies from native arrive here (nativeBridge.replyWith).
+    receive(message) {
+      const callback = callbacks.get(message.id)
+      if (callback) callback(message)
+    },
+
+    removeCallbackFor(id) {
+      callbacks.delete(id)
+    },
+
+    setAdapter(newAdapter) {
+      adapter = newAdapter
+      document.documentElement.dataset.bridgePlatform = adapter.platform
+      this.adapterDidUpdateSupportedComponents()
+      pending.splice(0).forEach((message) => this.send(message))
+    },
+
+    adapterDidUpdateSupportedComponents() {
+      if (adapter) {
+        document.documentElement.dataset.bridgeComponents =
+          adapter.supportedComponents.join(" ")
+      }
+    }
+  }
+
+  window.HotwireNative = { web }
+  document.dispatchEvent(new Event("web-bridge:ready"))
+}
 
 const mobile = {
-  ...browser
-  // TODO: notify via a Hotwire Native bridge component ("everywhere--notification")
-  // TODO: menu/tab events dispatched as document CustomEvents ("everywhere:menu")
+  ...browser,
+
+  // Native local notification via the shell's "everywhere--notification"
+  // bridge component; web Notification fallback when the shell doesn't
+  // register it (an older shell, or before the handshake completes).
+  notify({ title, body }) {
+    const web = window.HotwireNative && window.HotwireNative.web
+    if (!web || !web.supportsComponent(NOTIFY_COMPONENT)) {
+      return browser.notify({ title, body })
+    }
+
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => resolve({ delivered: false, timedOut: true }), 10000)
+      const id = web.send({
+        component: NOTIFY_COMPONENT,
+        event: "notify",
+        data: { title, body },
+        callback: (message) => {
+          clearTimeout(timer)
+          if (id !== null && web.removeCallbackFor) web.removeCallbackFor(id)
+          resolve(message.data)
+        }
+      })
+    })
+  },
+
+  // Ask the shell to re-fetch its native navigation config (tabs + path
+  // rules) now, instead of waiting for the next app foreground. Call it after
+  // a change that affects which tabs should show — signing in or out — so the
+  // tab bar updates immediately. Uses a dedicated WKScriptMessageHandler, so
+  // it doesn't depend on a bridge component being mounted on the page.
+  reloadTabs() {
+    const control = nativeControlChannel()
+    if (control) {
+      control.postMessage({ action: "reloadConfig" })
+    } else {
+      console.debug("[everywhere] reloadTabs: no native control channel (older shell?)")
+    }
+  },
+
+  // Full app reset (fresh web views + re-fetched tabs), then land on `to`.
+  // Falls back to a plain navigation when there's no native channel.
+  resetApp(to) {
+    const target = to || window.location.pathname + window.location.search
+    const control = nativeControlChannel()
+    if (control) control.postMessage({ action: "reset", to: target })
+    else window.location.assign(target)
+  },
+
+  // Instance switching rides the control channel: it re-roots the whole app,
+  // which is shell-level state, not page state. The shell validates,
+  // persists, and resets; nothing to wait on.
+  instanceSet(url, to) {
+    const control = nativeControlChannel()
+    if (control) control.postMessage({ action: "setInstance", url, ...(to ? { to } : {}) })
+    else window.location.assign(url)
+  },
+
+  instanceClear(to) {
+    const control = nativeControlChannel()
+    if (control) control.postMessage({ action: "clearInstance", ...(to ? { to } : {}) })
+  },
+
+  // Real haptics via the shell's "everywhere--haptics" component; vibration
+  // fallback while the handshake completes or on an older shell.
+  haptic(kind, value) {
+    const web = window.HotwireNative && window.HotwireNative.web
+    if (!web || !web.supportsComponent(HAPTICS_COMPONENT)) {
+      return browser.haptic(kind, value)
+    }
+    const data = kind === "impact" ? { style: value }
+               : kind === "notification" ? { type: value }
+               : {}
+    web.send({ component: HAPTICS_COMPONENT, event: kind, data })
+  },
+
+  // Badges ride the control channel (like reloadTabs): they're app-level
+  // state, not tied to whichever page has bridge components mounted.
+  badgeSet(count) {
+    const control = nativeControlChannel()
+    if (control) control.postMessage({ action: "setBadge", count })
+    else browser.badgeSet(count)
+  },
+
+  badgeSetTab(path, count) {
+    const control = nativeControlChannel()
+    if (control) control.postMessage({ action: "setTabBadge", path, count })
+  },
+
+  permissionQuery(name) {
+    return this._permission("query", name)
+  },
+
+  permissionRequest(name) {
+    return this._permission("request", name)
+  },
+
+  permissionOpenSettings() {
+    const web = window.HotwireNative && window.HotwireNative.web
+    if (web && web.supportsComponent(PERMISSIONS_COMPONENT)) {
+      web.send({ component: PERMISSIONS_COMPONENT, event: "openSettings", data: {} })
+    }
+  },
+
+  _permission(event, name) {
+    const web = window.HotwireNative && window.HotwireNative.web
+    if (!web || !web.supportsComponent(PERMISSIONS_COMPONENT)) {
+      // Older shell without the component: answer honestly from the web APIs.
+      return event === "request" ? browser.permissionRequest(name) : browser.permissionQuery(name)
+    }
+
+    return new Promise((resolve) => {
+      const id = web.send({
+        component: PERMISSIONS_COMPONENT,
+        event,
+        data: { name },
+        callback: (message) => {
+          if (id !== null && web.removeCallbackFor) web.removeCallbackFor(id)
+          resolve(message.data)
+        }
+      })
+    })
+  },
+
+  // Device-level persistence via the shell's "everywhere--storage" component
+  // (UserDefaults — survives web view resets and cache clears, unlike
+  // localStorage); localStorage fallback on an older shell.
+  storage(event, data) {
+    const web = window.HotwireNative && window.HotwireNative.web
+    if (!web || !web.supportsComponent(STORAGE_COMPONENT)) {
+      return browser.storage(event, data)
+    }
+
+    return new Promise((resolve) => {
+      const id = web.send({
+        component: STORAGE_COMPONENT,
+        event,
+        data,
+        callback: (message) => {
+          if (id !== null && web.removeCallbackFor) web.removeCallbackFor(id)
+          resolve(message.data)
+        }
+      })
+    })
+  },
+
+  biometricsAvailable() {
+    return this._biometrics("query", {}, () => browser.biometricsAvailable())
+  },
+
+  // No timeout on purpose (same as permissions): the Face ID sheet blocks
+  // until the user answers, and the shell always replies on the message.
+  biometricsAuthenticate(options) {
+    return this._biometrics("authenticate", options || {}, () => browser.biometricsAuthenticate())
+  },
+
+  biometricsCredential(event, data) {
+    return this._biometrics(event, data || {}, () => browser.biometricsCredential(event))
+  },
+
+  _biometrics(event, data, fallback) {
+    const web = window.HotwireNative && window.HotwireNative.web
+    if (!web || !web.supportsComponent(BIOMETRICS_COMPONENT)) return fallback()
+
+    return new Promise((resolve) => {
+      const id = web.send({
+        component: BIOMETRICS_COMPONENT,
+        event,
+        data,
+        callback: (message) => {
+          if (id !== null && web.removeCallbackFor) web.removeCallbackFor(id)
+          resolve(message.data)
+        }
+      })
+    })
+  }
+}
+
+function nativeControlChannel() {
+  return window.webkit &&
+    window.webkit.messageHandlers &&
+    window.webkit.messageHandlers.everywhereControl
 }
 
 // --- public surface ----------------------------------------------------------
@@ -208,9 +649,16 @@ const platform = detectPlatform()
 const os = detectOS()
 const adapter = adapters[platform]
 
+// Complete the Hotwire Native handshake early so the shell's components are
+// registered by the time app code first calls notify().
+if (platform === "mobile") installWebBridge()
+
 // Mutable so setChannel can keep updates.channel truthful without a reload.
 let updatesChannel = (config.updates && config.updates.channel) || null
 
+// Device-local "require biometrics" preference (see biometrics.lockEnabled).
+const BIOMETRIC_LOCK_KEY = "everywhere:biometric-lock"
+
 export const Everywhere = {
   platform,
   os,
@@ -241,6 +689,21 @@ export const Everywhere = {
     else window.location.assign(path)
   },
 
+  // Refresh the native tab bar / navigation config now (mobile only; a no-op
+  // in the browser and desktop shell, where there's nothing to refresh).
+  reloadTabs() {
+    if (adapter.reloadTabs) adapter.reloadTabs()
+  },
+
+  // Reset the native app after an auth change — clears cached web content and
+  // rebuilds tabs, then lands on `to` (defaults to the current path). In the
+  // browser / desktop it's a plain navigation. Usually you don't call this
+  // directly: redirect to /everywhere/reset (everywhere_auth_redirect) instead.
+  resetApp(to) {
+    if (adapter.resetApp) adapter.resetApp(to)
+    else this.visit(to || window.location.pathname)
+  },
+
   clipboard: {
     write(text) {
       return adapter.clipboardWrite(text)
@@ -250,6 +713,184 @@ export const Everywhere = {
     }
   },
 
+  // Tactile feedback. Real haptics in the mobile shell, Vibration API where
+  // browsers have one, silently nothing elsewhere (including desktop).
+  haptics: {
+    impact(style = "medium") {
+      if (adapter.haptic) adapter.haptic("impact", style)
+    },
+    notification(type = "success") {
+      if (adapter.haptic) adapter.haptic("notification", type)
+    },
+    selection() {
+      if (adapter.haptic) adapter.haptic("selection")
+    }
+  },
+
+  // Native permission state. Mobile permissions must be declared in
+  // everywhere.yml (with the usage string iOS shows in its prompt) —
+  // undeclared ones resolve {status: "undeclared"} and never prompt. A
+  // "denied" status is final on iOS: offer openSettings() instead of asking again.
+  permissions: {
+    query(name) {
+      return adapter.permissionQuery
+        ? adapter.permissionQuery(name)
+        : Promise.resolve({ name, status: "unsupported" })
+    },
+    request(name) {
+      return adapter.permissionRequest
+        ? adapter.permissionRequest(name)
+        : Promise.resolve({ name, status: "unsupported" })
+    },
+    openSettings() {
+      if (adapter.permissionOpenSettings) adapter.permissionOpenSettings()
+    }
+  },
+
+  // Face ID / Touch ID. Mobile-shell only, and `biometrics` must be declared
+  // in everywhere.yml (that stamps the Face ID usage string). A passed check
+  // proves presence to the PAGE — gate a screen or confirm an action with it —
+  // but the server can't trust it; keep real session auth for the backend.
+  biometrics: {
+    available() {
+      return adapter.biometricsAvailable
+        ? adapter.biometricsAvailable()
+        : Promise.resolve({ available: false, biometry: "none", status: "unsupported" })
+    },
+    authenticate(options = {}) {
+      return adapter.biometricsAuthenticate
+        ? adapter.biometricsAuthenticate(options)
+        : Promise.resolve({ authenticated: false, error: "unsupported" })
+    },
+
+    // The device-local "require biometrics" preference honored by the
+    // declarative gate (data-everywhere-biometric-lock elements). Stored per
+    // device on purpose: locking your phone shouldn't lock your desktop.
+    get lockEnabled() {
+      try { return localStorage.getItem(BIOMETRIC_LOCK_KEY) === "1" } catch (_) { return false }
+    },
+
+    // Flip the preference — in either direction the biometric check runs
+    // first, so whoever toggles it must pass it.
+    async setLockEnabled(enabled, { reason } = {}) {
+      enabled = !!enabled
+      if (enabled === this.lockEnabled) return { enabled }
+
+      const probe = await this.available()
+      if (!probe.available) return { enabled: this.lockEnabled, error: probe.status || "unsupported" }
+
+      const check = await this.authenticate({
+        reason: reason || (enabled ? "Confirm to require biometric unlock." : "Confirm to remove the biometric lock."),
+        allowPasscode: true
+      })
+      if (!check.authenticated) return { enabled: this.lockEnabled, error: check.error || "failed" }
+
+      try {
+        if (enabled) localStorage.setItem(BIOMETRIC_LOCK_KEY, "1")
+        else localStorage.removeItem(BIOMETRIC_LOCK_KEY)
+      } catch (_) {}
+      return { enabled }
+    },
+
+    // A server-issued secret in the device keychain, readable only after
+    // Face ID / Touch ID passes — the storage half of "sign in with Face ID".
+    // The app's server still owns the other half: issue a token, store it
+    // here, and exchange it for a session at login. iOS invalidates the item
+    // when biometric enrollment changes, so a stale credential resolves
+    // {error: "notEnrolled"} — treat that as "offer password sign-in".
+    credential: {
+      store(token, options = {}) {
+        return adapter.biometricsCredential
+          ? adapter.biometricsCredential("credentialStore", { ...options, token })
+          : Promise.resolve({ stored: false, error: "unsupported" })
+      },
+      get(options = {}) {
+        return adapter.biometricsCredential
+          ? adapter.biometricsCredential("credentialGet", options)
+          : Promise.resolve({ error: "unsupported" })
+      },
+      status() {
+        return adapter.biometricsCredential
+          ? adapter.biometricsCredential("credentialStatus", {})
+          : Promise.resolve({ enrolled: false })
+      },
+      clear() {
+        return adapter.biometricsCredential
+          ? adapter.biometricsCredential("credentialClear", {})
+          : Promise.resolve({ cleared: true })
+      }
+    }
+  },
+
+  // Multi-instance apps (remote.instances: true in everywhere.yml): the shell
+  // boots into your hosted picker page until it calls set(url) with the
+  // chosen instance's root; that persists across launches until clear().
+  // Both trigger a full native reset (same as resetApp), landing on `to` or
+  // the instance's entry path. In a plain browser, set() just navigates —
+  // going there IS picking the instance on the web.
+  instance: {
+    get supported() {
+      return platform === "mobile" && config.instances === true
+    },
+    // The active instance root, or null when the app is on its built-in root.
+    get current() {
+      return config.instance || null
+    },
+    set(url, { to } = {}) {
+      if (adapter.instanceSet) adapter.instanceSet(String(url), to)
+      else window.location.assign(String(url))
+    },
+    clear({ to } = {}) {
+      if (adapter.instanceClear) adapter.instanceClear(to)
+    }
+  },
+
+  // Device-local key/value settings. In the mobile shell they live in
+  // UserDefaults — outliving web view resets, cache clears, and resetApp() —
+  // making this the right home for per-device preferences the server
+  // shouldn't own. localStorage-backed in browsers and the desktop shell.
+  // Any JSON value round-trips; get() resolves null for missing keys.
+  storage: {
+    _call(event, data) {
+      return adapter.storage ? adapter.storage(event, data) : browser.storage(event, data)
+    },
+    async get(key) {
+      const result = await this._call("get", { key: String(key) })
+      if (!result || result.value == null) return null
+      try { return JSON.parse(result.value) } catch (_) { return null }
+    },
+    async set(key, value) {
+      const encoded = JSON.stringify(value === undefined ? null : value)
+      const result = await this._call("set", { key: String(key), value: encoded })
+      return !!(result && result.ok)
+    },
+    async remove(key) {
+      const result = await this._call("remove", { key: String(key) })
+      return !!(result && result.ok)
+    },
+    async clear() {
+      const result = await this._call("clear", {})
+      return !!(result && result.ok)
+    }
+  },
+
+  // Badge counts. App icon badge on mobile (and installed PWAs); native tab
+  // bar badges on mobile, keyed by the tab's path from everywhere.yml.
+  badge: {
+    set(count) {
+      if (adapter.badgeSet) adapter.badgeSet(Math.max(0, count | 0))
+    },
+    clear() {
+      this.set(0)
+    },
+    setTab(path, count) {
+      if (adapter.badgeSetTab) adapter.badgeSetTab(path, Math.max(0, count | 0))
+    },
+    clearTab(path) {
+      this.setTab(path, 0)
+    }
+  },
+
   updates: {
     // True only when the shell actually has a feed to check (everywhere.yml
     // updates: url + public_key made it into the shipped config).
@@ -290,4 +931,157 @@ export const Everywhere = {
   }
 }
 
+// --- declarative page glue ---------------------------------------------------
+// Server-rendered badge counts (the everywhere_badge / everywhere_tab_badge
+// helpers emit meta tags — CSP-safe, no inline JS) applied on every Turbo
+// visit, and haptics for taps on [data-everywhere-haptic] elements.
+
+function applyBadgeMetas() {
+  const badge = document.querySelector('meta[name="everywhere:badge"]')
+  if (badge) Everywhere.badge.set(parseInt(badge.content, 10) || 0)
+
+  document.querySelectorAll('meta[name="everywhere:tab-badge"]').forEach((meta) => {
+    try {
+      const { path, count } = JSON.parse(meta.content)
+      if (path) Everywhere.badge.setTab(path, count || 0)
+    } catch (_) {}
+  })
+}
+
+function playDeclaredHaptic(el) {
+  const [kind, value] = (el.dataset.everywhereHaptic || "impact").split(":")
+  if (kind === "notification") Everywhere.haptics.notification(value)
+  else if (kind === "selection") Everywhere.haptics.selection()
+  else if (kind === "impact") Everywhere.haptics.impact(value)
+  else Everywhere.haptics.impact(kind) // shorthand: data-everywhere-haptic="light"
+}
+
+// Biometric gate. A [data-everywhere-biometric-lock] wrapper holds
+// [data-everywhere-biometric-content] (server-rendered hidden) and a
+// [data-everywhere-biometric-locked] overlay; when the device-local lock
+// preference is on in the mobile shell, content stays hidden until Face ID /
+// Touch ID passes. A pass is remembered for the JS session, so Turbo
+// revisits don't re-prompt. [data-everywhere-biometric-unlock] buttons retry
+// after a cancel. Everywhere else (browser, desktop, lock off) the content
+// just reveals.
+const unlockedGates = new Set()
+
+function gateKey(el) {
+  return el.getAttribute("data-everywhere-biometric-lock") || window.location.pathname
+}
+
+function setGateLocked(el, locked) {
+  const content = el.querySelector("[data-everywhere-biometric-content]")
+  const overlay = el.querySelector("[data-everywhere-biometric-locked]")
+  if (content) content.hidden = locked
+  if (overlay) overlay.hidden = !locked
+}
+
+async function resolveBiometricGate(el, { prompt } = {}) {
+  if (platform !== "mobile" || !Everywhere.biometrics.lockEnabled || unlockedGates.has(gateKey(el))) {
+    return setGateLocked(el, false)
+  }
+
+  const probe = await Everywhere.biometrics.available()
+  // A device that can't authenticate (nothing enrolled, older shell) reveals
+  // rather than bricking the page — except lockout, where authenticate()'s
+  // passcode path can still clear it.
+  if (!probe.available && probe.status !== "lockout") return setGateLocked(el, false)
+
+  setGateLocked(el, true)
+  if (!prompt) return
+
+  const result = await Everywhere.biometrics.authenticate({
+    reason: el.getAttribute("data-everywhere-biometric-reason") || "Unlock to continue",
+    allowPasscode: el.hasAttribute("data-everywhere-biometric-passcode")
+  })
+  if (result.authenticated) {
+    unlockedGates.add(gateKey(el))
+    setGateLocked(el, false)
+  }
+}
+
+// Auto-prompt only when this page is actually on screen. Hotwire Native
+// loads tab web views in the background at launch, so a gated page in a
+// non-selected tab must lock silently and prompt when its tab is opened
+// (the visibilitychange listener below) — not flash Face ID over another tab.
+function applyBiometricGates() {
+  const prompt = document.visibilityState === "visible"
+  document.querySelectorAll("[data-everywhere-biometric-lock]").forEach((el) => {
+    resolveBiometricGate(el, { prompt })
+  })
+}
+
+// [data-everywhere-biometric-toggle] checkboxes (server-rendered hidden +
+// disabled) become live switches for the lock preference — revealed only in
+// the mobile shell with working biometrics, along with their closest
+// [data-everywhere-biometric-toggle-row] container.
+async function wireBiometricToggles() {
+  const toggles = document.querySelectorAll("[data-everywhere-biometric-toggle]")
+  if (!toggles.length) return
+
+  const available = platform === "mobile" && (await Everywhere.biometrics.available()).available
+  if (!available) return
+
+  toggles.forEach((input) => {
+    const row = input.closest("[data-everywhere-biometric-toggle-row]")
+    if (row) row.hidden = false
+    input.hidden = false
+    input.disabled = false
+    input.checked = Everywhere.biometrics.lockEnabled
+  })
+}
+
+function applyDeclarative() {
+  applyBadgeMetas()
+  applyBiometricGates()
+  wireBiometricToggles()
+}
+
+if (typeof document !== "undefined") {
+  document.addEventListener("turbo:load", applyDeclarative)
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", applyDeclarative)
+  } else {
+    applyDeclarative()
+  }
+
+  // A gated page that loaded hidden (a background tab) prompts when it
+  // actually comes on screen; already-unlocked gates resolve instantly.
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "visible") applyBiometricGates()
+  })
+
+  // Reset gates to fully-hidden before Turbo snapshots the page, so a cached
+  // copy never carries unlocked content; turbo:load re-resolves on restore.
+  document.addEventListener("turbo:before-cache", () => {
+    document.querySelectorAll("[data-everywhere-biometric-lock]").forEach((el) => {
+      const content = el.querySelector("[data-everywhere-biometric-content]")
+      const overlay = el.querySelector("[data-everywhere-biometric-locked]")
+      if (content) content.hidden = true
+      if (overlay) overlay.hidden = true
+    })
+  })
+
+  document.addEventListener("click", (event) => {
+    if (!(event.target instanceof Element)) return
+    const el = event.target.closest("[data-everywhere-haptic]")
+    if (el) playDeclaredHaptic(el)
+
+    const unlock = event.target.closest("[data-everywhere-biometric-unlock]")
+    const gate = unlock && unlock.closest("[data-everywhere-biometric-lock]")
+    if (gate) resolveBiometricGate(gate, { prompt: true })
+  })
+
+  document.addEventListener("change", async (event) => {
+    const input = event.target
+    if (!(input instanceof Element) || !input.hasAttribute("data-everywhere-biometric-toggle")) return
+
+    input.disabled = true
+    const result = await Everywhere.biometrics.setLockEnabled(input.checked)
+    input.checked = result.enabled
+    input.disabled = false
+  })
+}
+
 export default Everywhere