samagotchi 0.110.0 → 0.111.0

data/lib/samagotchi/web/public/notifications.js

@@ -5,6 +5,14 @@
 // several tabs show one, and none while another chi tab is in front with it
 // (notify.js, Several tabs).
 //
+// In the Home Screen app (push.js pushSupported) the bell means "push to
+// this device" instead (Web Push): chi web pushes approvals and questions to
+// it while the app is closed. chi web without push (no https public URL)
+// leaves the bell as it is in a tab. With the bell on, the app also tidies
+// the device (syncDevice): it closes the pushed notifications whose
+// question isn't open any more and sets the app's badge, as chi web sends
+// no close push (WebKit's silent-push quota).
+//
 // The browser parts come in as deps (globals by default) so the specs can
 // drive it without a DOM.
 
@@ -12,6 +20,9 @@ import { sessionHash } from "./route.js";
 import {
   NOTIFY_CHANNEL, attentionText, createNotifyGate, initialAttentionState, notifyState as bellState, trackAttention,
 } from "./notify.js";
+import {
+  isQuestionTag, openPushKeys, pushSupported, subscribe as pushSubscribe, unsubscribe as pushUnsubscribe,
+} from "./push.js";
 
 export const NOTIFY_KEY = "chi_notify";
 
@@ -21,6 +32,24 @@ const NOTIFY_TITLES = {
   denied: "Notifications are blocked for this site in the browser's settings",
 };
 
+const PUSH_TITLES = {
+  on: "Notifications to this phone: on (approvals and questions, also while the app is closed). Tap to turn off",
+  off: "Notify this phone when a session needs approval or an answer, also while the app is closed",
+  denied: "Notifications are blocked for this app in the phone's settings",
+};
+
+// fetch's JSON, or an Error with chi web's detail.
+async function defaultApi(method, path, body) {
+  const res = await fetch(path, {
+    method,
+    headers: body === undefined ? {} : { "Content-Type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const data = res.status === 204 ? null : await res.json().catch(() => null);
+  if (!res.ok) throw new Error(data?.detail || `HTTP ${res.status}`);
+  return data;
+}
+
 function defaultChannel() {
   try {
     if (typeof globalThis.BroadcastChannel === "function") return new BroadcastChannel(NOTIFY_CHANNEL);
@@ -35,6 +64,10 @@ function defaultChannel() {
 // @param storage () => localStorage (it can throw)
 // @param channel the BroadcastChannel to the other chi tabs, or null
 // @param gateOptions passed to createNotifyGate (specs: schedule, now)
+// @param nav the navigator (serviceWorker; push.js pushSupported)
+// @param api (method, path, body) => Promise of chi web's JSON
+// @param scoped the page shows one project's sessions (?dir=): it never
+//   tidies the device, as it doesn't see the others'
 // @return {noticeSessions(type, data), noticeList(sessions), setBaseTitle(title), clearBadge()}
 export function createNotifications({
   button,
@@ -44,8 +77,17 @@ export function createNotifications({
   storage = () => globalThis.localStorage,
   channel = defaultChannel(),
   gateOptions = {},
+  nav = globalThis.navigator,
+  api = defaultApi,
+  scoped = false,
 }) {
   let attention = initialAttentionState();
+  // Web Push in the Home Screen app: null until chi web says it pushes
+  // ({reg, key, on}), and for good in a tab or without push.
+  let push = null;
+  let pushBusy = false;
+  let syncing = null;
+  let syncAgain = false;
   const badgeKeys = new Set();
   let baseTitle = "Chi";
 
@@ -65,6 +107,10 @@ export function createNotifications({
 
   // "on" | "off" | "denied" | "unsupported" (notify.js)
   function notifyState() {
+    if (push) {
+      if (typeof NotificationApi === "function" && NotificationApi.permission === "denied") return "denied";
+      return push.on ? "on" : "off";
+    }
     const hasNotification = typeof NotificationApi === "function";
     return bellState({
       hasNotification,
@@ -78,11 +124,12 @@ export function createNotifications({
     const state = notifyState();
     button.hidden = state === "unsupported";
     button.dataset.state = state;
-    button.title = NOTIFY_TITLES[state] || "";
+    button.title = (push ? PUSH_TITLES : NOTIFY_TITLES)[state] || "";
     button.setAttribute("aria-pressed", state === "on" ? "true" : "false");
   }
 
   async function toggleNotify() {
+    if (push) return togglePush();
     const state = notifyState();
     if (state === "unsupported" || state === "denied") return;
     let wanted = state !== "on";
@@ -93,8 +140,87 @@ export function createNotifications({
     renderNotifyBtn();
   }
 
+  // This device's subscription on (permission from the tap: iOS asks only
+  // from one), a test push to show it works; or off.
+  async function togglePush() {
+    if (pushBusy || notifyState() === "denied") return;
+    pushBusy = true;
+    let failed = null;
+    try {
+      if (push.on) {
+        await pushUnsubscribe({ reg: push.reg, del: (endpoint) => api("DELETE", "/api/push/subscriptions", { endpoint }) });
+        push.on = false;
+        setDeviceBadge(0);
+      } else if (NotificationApi.permission === "granted" || (await NotificationApi.requestPermission()) === "granted") {
+        const { subscription } = await pushSubscribe({
+          reg: push.reg, key: push.key, post: (json) => api("POST", "/api/push/subscriptions", { subscription: json }),
+        });
+        push.on = true;
+        api("POST", "/api/push/test", { endpoint: subscription.endpoint }).catch(() => {});
+        syncDevice();
+      }
+    } catch (e) {
+      failed = e?.message || String(e);
+    } finally {
+      pushBusy = false;
+    }
+    renderNotifyBtn();
+    // Said on the bell (its tooltip); the next tap tries again.
+    if (failed) button.title = `Notifications to this phone failed: ${failed}`;
+  }
+
+  // The Home Screen app: its service worker, chi web's key, and whether
+  // chi web has this device. A tab, or chi web without push: the bell as is.
+  async function startPush() {
+    if (typeof NotificationApi !== "function" || !pushSupported({ win, nav })) return;
+    try {
+      const reg = await nav.serviceWorker.register("/sw.js", { scope: "/" });
+      const sub = await reg.pushManager.getSubscription();
+      const query = sub ? `?endpoint=${encodeURIComponent(sub.endpoint)}` : "";
+      const info = await api("GET", `/api/push${query}`);
+      if (!info?.enabled || !info.public_key) return;
+      push = { reg, key: info.public_key, on: !!(sub && info.this) };
+      renderNotifyBtn();
+    } catch (_) {}
+    syncDevice();
+  }
+
+  function setDeviceBadge(count) {
+    try {
+      const done = count > 0 && typeof nav?.setAppBadge === "function" ? nav.setAppBadge(count)
+        : typeof nav?.clearAppBadge === "function" ? nav.clearAppBadge() : null;
+      done?.catch?.(() => {});
+    } catch (_) {}
+  }
+
+  // The Home Screen app with the bell on: closes the pushed notifications
+  // whose question isn't open (chi's own, chi:test, stay) and sets the
+  // app's badge. Never before the first snapshot (an empty byId would close
+  // them all) nor on a project's page (its byId lacks the others). One at a
+  // time; asked again meanwhile, it runs once more after.
+  function syncDevice() {
+    if (!push || !push.on || scoped || !attention.seeded) return syncing;
+    if (syncing) {
+      syncAgain = true;
+      return syncing;
+    }
+    syncing = (async () => {
+      do {
+        syncAgain = false;
+        const open = new Set(openPushKeys(attention.byId));
+        try {
+          const shown = await push.reg.getNotifications();
+          for (const n of shown || []) if (isQuestionTag(n.tag) && !open.has(n.tag)) n.close();
+        } catch (_) {}
+        if (push?.on) setDeviceBadge(open.size);
+      } while (syncAgain);
+    })().finally(() => { syncing = null; });
+    return syncing;
+  }
+
   function showNotification(session, a) {
-    if (notifyState() !== "on") return;
+    // The app gets chi web's pushes instead.
+    if (push || notifyState() !== "on") return;
     const { title, body } = attentionText(session, a);
     try {
       const n = new NotificationApi(title, { body, tag: a.key });
@@ -135,6 +261,7 @@ export function createNotifications({
       }
     }
     if (badgeKeys.size !== size) setTitle();
+    if (doc.visibilityState === "visible") syncDevice();
   }
 
   // The user is here: the badge goes, and the other tabs drop what it had.
@@ -149,7 +276,9 @@ export function createNotifications({
   // before it has focus, and a tab switch inside a focused window sends no
   // focus event), the window got focus, or they touched the page.
   function backInFront() {
-    if (doc.visibilityState === "visible") clearBadge();
+    if (doc.visibilityState !== "visible") return;
+    clearBadge();
+    syncDevice();
   }
   doc.addEventListener("visibilitychange", backInFront);
   win.addEventListener("focus", backInFront);
@@ -157,6 +286,7 @@ export function createNotifications({
   doc.addEventListener("keydown", clearBadge, true);
   button.addEventListener("click", toggleNotify);
   renderNotifyBtn();
+  const pushReady = startPush();
 
   return {
     noticeSessions,
@@ -170,5 +300,9 @@ export function createNotifications({
       setTitle();
     },
     clearBadge,
+    // Settles once the Home Screen app's push state is known (specs).
+    pushReady,
+    // The device's tidy-up in flight, or null (specs await it).
+    syncing: () => syncing,
   };
 }

data/lib/samagotchi/web/public/notify.js

@@ -23,7 +23,7 @@ const UNWATCHED_ORIGINS = ["delegate_report", "context", "task"];
 
 // The step-limit question (kind "continue": a turn ran out of iterations
 // and asks whether to go on) has its own reason: "out of steps".
-const questionReason = (q) => (q.kind === "approval" ? "approval" : q.kind === "continue" ? "continue" : "question");
+export const questionReason = (q) => (q.kind === "approval" ? "approval" : q.kind === "continue" ? "continue" : "question");
 
 // What a session waits on the user for right now, from one summary: an open
 // question or approval, or a running turn's card with actions (check-in's

data/lib/samagotchi/web/public/push.js

@@ -0,0 +1,95 @@
+// Web Push, the page's pure parts (notifications.js drives them): whether
+// this page can get pushes, subscribing this device with chi web's key
+// and telling chi web (POST /api/push/subscriptions) or the reverse, and
+// which pushed notifications are still open (the page's cleanup). Only
+// the Home Screen app subscribes (iOS gives push to a standalone app only;
+// a browser tab keeps the in-tab notifications). See
+// docs/internals/web-push.md.
+
+import { questionReason } from "./notify.js";
+
+// The reasons chi web pushes (Web::Push::Attention::PUSHED).
+const PUSHED = new Set(["approval", "question"]);
+
+// The keys still open in a byId (notify.js trackAttention's: session id →
+// summary): a pending question with an id, not relayed, of a reason chi
+// web pushes. Attention.open_keys's rule, so the page, the worker's open
+// list and the badge agree.
+// @return [String] "<session id>:<question id>" keys
+export function openPushKeys(byId) {
+  const keys = [];
+  for (const summary of Object.values(byId || {})) {
+    const q = summary?.pending_question;
+    if (!q || !q.id || q.relayed_to || !PUSHED.has(questionReason(q))) continue;
+    keys.push(`${summary.id}:${q.id}`);
+  }
+  return keys;
+}
+
+// A pushed question's tag ("<session id>:<question id>"), not one of chi's
+// own (chi:test, chi:other): only these are ever cleaned up. sw.js keeps
+// the same pattern (a classic script imports nothing).
+export const QUESTION_TAG = /^(?!chi:)[^:]+:[^:]+$/;
+export const isQuestionTag = (tag) => typeof tag === "string" && QUESTION_TAG.test(tag);
+
+// A standalone app with a service worker and PushManager, on a secure
+// context (chi web's https public URL; the LAN's plain http has none).
+// @param win the window (isSecureContext, PushManager, matchMedia)
+// @param nav the navigator (serviceWorker, standalone on iOS)
+export function pushSupported({ win, nav }) {
+  if (!win || !nav || win.isSecureContext !== true) return false;
+  if (!nav.serviceWorker || typeof win.PushManager !== "function") return false;
+  let standalone = nav.standalone === true;
+  try {
+    if (!standalone && typeof win.matchMedia === "function") standalone = win.matchMedia("(display-mode: standalone)").matches === true;
+  } catch (_) {}
+  return standalone;
+}
+
+// base64url (padded or not) → bytes: applicationServerKey's form.
+export function urlBase64ToBytes(text) {
+  const b64 = String(text).replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
+  const raw = atob(padded);
+  const bytes = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) bytes[i] = raw.charCodeAt(i);
+  return bytes;
+}
+
+function sameBytes(a, b) {
+  if (!a || !b) return false;
+  const x = new Uint8Array(a);
+  const y = new Uint8Array(b);
+  return x.length === y.length && x.every((v, i) => v === y[i]);
+}
+
+// Subscribes this device with chi web's key (a subscription made with
+// another key, an older vapid.pem's, is dropped first: the push service
+// would refuse chi web's token for it) and posts it.
+// @param reg the service worker's registration
+// @param key chi web's public key (GET /api/push's public_key)
+// @param post (subscriptionJson) => Promise of chi web's answer ({id, label})
+// @return {subscription, answer}
+export async function subscribe({ reg, key, post }) {
+  const want = urlBase64ToBytes(key);
+  let sub = await reg.pushManager.getSubscription();
+  if (sub && !sameBytes(sub.options?.applicationServerKey, want)) {
+    await sub.unsubscribe();
+    sub = null;
+  }
+  if (!sub) sub = await reg.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: want });
+  const answer = await post(typeof sub.toJSON === "function" ? sub.toJSON() : sub);
+  return { subscription: sub, answer };
+}
+
+// Unsubscribes this device and tells chi web to forget it.
+// @param del (endpoint) => Promise
+// @return whether there was a subscription
+export async function unsubscribe({ reg, del }) {
+  const sub = await reg.pushManager.getSubscription();
+  if (!sub) return false;
+  const endpoint = sub.endpoint;
+  await sub.unsubscribe();
+  await del(endpoint);
+  return true;
+}

data/lib/samagotchi/web/public/stage_view.js

@@ -565,6 +565,14 @@ export function createStageView({
 
   function emptySlots() {
     for (const slot of [promptSlot, extras, answer, tail, cloudBody, queuedSlot, timingSlot]) slot.replaceChildren();
+    // The turn left the stage: the status row and the chip say nothing until
+    // the next one. Kept as they were, a hidden stage still reads "thinking ·
+    // step 1" — the stale stage of a turn the page stopped following.
+    mark.textContent = "";
+    phaseEl.textContent = "";
+    stepEl.textContent = "";
+    miniTool.textContent = "";
+    chipLabel.textContent = "";
     slotsView.reset();
     rail?.reset();
     promptSlot.classList.remove("full");

data/lib/samagotchi/web/public/sw.js

@@ -0,0 +1,101 @@
+// chi web's service worker (Web Push, docs/internals/web-push.md): shows
+// what chi web pushes and opens the session on a tap. A classic script
+// (module service workers on iOS are unverified), registered at scope "/"
+// by notifications.js in the Home Screen app only. No fetch handler and no
+// caching: chi web has no offline mode, and a fetch handler would change
+// how the page loads.
+//
+// A push's payload (JSON, end-to-end encrypted by chi web):
+//   {v: 1, kind: "show", tag, title, body, url, badge?, open?: [tag…]}
+// Every push shows a notification: WebKit removes a subscription after a
+// few pushes that show none (its silent-push quota), so anything else (an
+// unreadable payload, another version or kind, a show iOS refuses) shows a
+// fallback "open chi". There is no close push: a show's open list (the
+// keys chi web still has open) lets it close the answered ones after it
+// shows itself (closing before showNotification fails on iOS), and the
+// page does the same when the app opens.
+
+const ICON = "/icons/chi-192.png";
+const FALLBACK = { title: "chi", body: "open chi", tag: "chi:other", url: "/" };
+// push.js QUESTION_TAG: a pushed question's "<session id>:<question id>",
+// never chi's own (chi:test, chi:other).
+const QUESTION_TAG = /^(?!chi:)[^:]+:[^:]+$/;
+
+function payloadOf(event) {
+  try {
+    return event.data ? event.data.json() : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+async function setBadge(count) {
+  const nav = self.navigator;
+  try {
+    if (count > 0 && nav && typeof nav.setAppBadge === "function") await nav.setAppBadge(count);
+    else if (nav && typeof nav.clearAppBadge === "function") await nav.clearAppBadge();
+    else if (nav && typeof nav.setAppBadge === "function") await nav.setAppBadge(0);
+  } catch (_) {}
+}
+
+// Only a same-origin path opens: a payload names where in chi web to go.
+function pagePath(url) {
+  // Not "//host" nor "/\host" (a browser reads a backslash as a slash).
+  return typeof url === "string" && /^\/(?![/\\])/.test(url) && !url.includes("\\") ? url : "/";
+}
+
+// Shows it, or once more without the icon and data if that is refused.
+async function show({ title, body, tag, url }) {
+  try {
+    await self.registration.showNotification(title, { body, tag, icon: ICON, data: { url: pagePath(url) } });
+  } catch (_) {
+    await self.registration.showNotification(title, { body, tag });
+  }
+}
+
+// Closes the shown question notifications chi web no longer has open
+// (never the new one nor chi's own). The unfiltered list only names the
+// tags: on the iPhone (iOS 26, 2026-10-24) close() on a notification from
+// it did nothing, while one looked up by its tag closes (the probe in
+// docs/internals/web-push.md, iOS facts).
+async function closeAnswered(open, keep) {
+  try {
+    const still = new Set(open.map(String));
+    const tags = new Set();
+    for (const n of await self.registration.getNotifications()) {
+      if (n.tag !== keep && QUESTION_TAG.test(n.tag || "") && !still.has(n.tag)) tags.add(n.tag);
+    }
+    for (const tag of tags) {
+      for (const n of await self.registration.getNotifications({ tag })) n.close();
+    }
+  } catch (_) {}
+}
+
+async function onPush(data) {
+  if (!data || data.v !== 1 || data.kind !== "show") {
+    await show(FALLBACK);
+    return;
+  }
+  const tag = String(data.tag || "");
+  await show({ title: String(data.title || "chi"), body: String(data.body || ""), tag, url: data.url });
+  if (Array.isArray(data.open)) await closeAnswered(data.open, tag);
+  if (typeof data.badge === "number") await setBadge(data.badge);
+}
+
+async function onClick(notification) {
+  notification.close();
+  const url = pagePath(notification.data && notification.data.url);
+  const windows = await clients.matchAll({ type: "window", includeUncontrolled: true });
+  const win = windows[0];
+  if (win) {
+    await win.focus();
+    if (typeof win.navigate === "function") await win.navigate(url);
+    return;
+  }
+  await clients.openWindow(url);
+}
+
+self.addEventListener("install", () => self.skipWaiting());
+self.addEventListener("activate", (event) => event.waitUntil(clients.claim()));
+self.addEventListener("push", (event) => event.waitUntil(onPush(payloadOf(event))));
+self.addEventListener("notificationclick", (event) => event.waitUntil(onClick(event.notification)));

data/lib/samagotchi/web/public/turn_events.js

@@ -21,6 +21,28 @@ export function workerGoneText({ turnRunning, stopped = false }) {
   return stopped ? "\u25A0 canceled (session stopped)" : "\u2715 canceled (worker exited)";
 }
 
+// Whether the turn view ends now, or waits for the session re-read: a stream
+// that was open and dropped with no stop (a phone briefly offline) says
+// nothing about the worker, and `resync` re-renders the turn and adds the end
+// line only when no worker took it — ending the view first is a wrong flash.
+// A stop, or a stream that never opened at all, is the worker leaving: end
+// now, and the re-read repeats it only when nothing took the turn.
+// @return {{endNow: Boolean, endText: String|null}}
+export function streamDropEnd({ turnRunning, stopped = false, opened = true }) {
+  const endText = workerGoneText({ turnRunning, stopped });
+  return { endNow: Boolean(endText) && (stopped || !opened), endText };
+}
+
+// A session re-read that failed (the phone still offline, chi web restarting):
+// try again, backing off (3 s, 6 s, 9 s), and stop after +max+ tries — the
+// hub's next event for the session re-reads it then. Nothing else changes in
+// the meantime: a turn a worker still owns keeps showing as running.
+// @return {{attempt: number, delayMs: number|null}}  (null: stop trying)
+export function resyncRetry({ attempts = 0, max = 3, baseMs = 3000 }) {
+  const next = attempts + 1;
+  return next <= max ? { attempt: next, delayMs: next * baseMs } : { attempt: attempts, delayMs: null };
+}
+
 // How long a turn's answer waits for the after_turn hooks' answer_display
 // before the page stops waiting and pops what it has (4.14).
 const DISPLAY_WAIT_MS = 20000;

data/lib/samagotchi/web/push/attention.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Web
+    module Push
+      # When a session needs the user, decided from two of the hub's session
+      # summaries (SessionSummary.build: symbol keys): the server's port of
+      # the page's rules (web/public/notify.js attentionFor, closedKeys,
+      # attentionText), so a push and the tab's notification ring for the
+      # same thing under the same key. P1 pushes approvals and questions
+      # only (the plan's D1): a step-limit question, a card, a failed or
+      # done turn come later. See docs/internals/web-push.md.
+      module Attention
+        module_function
+
+        # One thing that needs the user. +key+ names it everywhere (the
+        # notification's tag, notify.js's key); +hold+ the seconds it waits
+        # before it pushes, nil for the Notifier's own (a delegated child's
+        # approval waits longer: its parent may relay it).
+        Event = Data.define(:reason, :session_id, :key, :hold)
+
+        # notify.js RELAY_HOLD_MS: how long a delegated child's new approval
+        # (or hook question) waits, as its parent may relay it.
+        RELAY_HOLD = 3.5
+        RELAYED_KINDS = %w[approval hook].freeze
+        # The reasons P1 pushes.
+        PUSHED = %w[approval question].freeze
+        TITLE_MAX = 61
+        BODIES = { "question" => "needs an answer", "approval" => "needs approval", "continue" => "hit its step limit",
+                   "card" => "needs you" }.freeze
+
+        # notify.js questionReason: a hook's question is a question.
+        def reason_of(question)
+          case question[:kind]
+          when "approval" then "approval"
+          when "continue" then "continue"
+          else "question"
+          end
+        end
+
+        # What +nxt+ newly needs the user for, compared with +prev+ (nil for
+        # a session not seen yet).
+        # @return [Event, nil]
+        def for(prev, nxt)
+          return nil unless nxt && nxt[:id]
+
+          question = nxt[:pending_question]
+          return nil unless question && question[:id] && question[:id] != prev&.dig(:pending_question, :id)
+          # Relayed to the parent already: the parent's notifies.
+          return nil if question[:relayed_to]
+
+          reason = reason_of(question)
+          return nil unless PUSHED.include?(reason)
+
+          hold = RELAY_HOLD if nxt[:parent_id] && RELAYED_KINDS.include?(question[:kind])
+          Event.new(reason: reason, session_id: nxt[:id], key: key(nxt[:id], question[:id]), hold: hold)
+        end
+
+        # The keys of what +prev+ had open and +nxt+ no longer has: its
+        # question answered (anywhere), gone or newly relayed; everything
+        # when the session is gone (+nxt+ nil).
+        # @return [Array<String>]
+        def closed_keys(prev, nxt)
+          question = prev&.dig(:pending_question)
+          return [] unless question && question[:id]
+
+          now = nxt&.dig(:pending_question)
+          gone = now.nil? || now[:id] != question[:id] || (now[:relayed_to] && !question[:relayed_to])
+          gone ? [key(prev[:id], question[:id])] : []
+        end
+
+        # Every key still open in +by_id+ (session id → summary): a
+        # pending question with an id, not relayed, of a reason P1 pushes.
+        # The rule push.js openPushKeys keeps, so the show's +open+ list,
+        # the page's cleanup and the badge agree.
+        # @return [Array<String>]
+        def open_keys(by_id)
+          by_id.each_value.filter_map do |summary|
+            question = summary[:pending_question]
+            next unless question.is_a?(Hash) && question[:id] && !question[:relayed_to]
+            next unless PUSHED.include?(reason_of(question))
+
+            key(summary[:id], question[:id])
+          end
+        end
+
+        def key(session_id, question_id) = "#{session_id}:#{question_id}"
+
+        # notify.js attentionText: the session's name (clipped) and the
+        # reason, never the question or the command (a lock screen shows it).
+        # @return [Array(String, String)] title, body
+        def text(summary, reason)
+          name = (summary && [summary[:title], summary[:first_preview], summary[:last_prompt]].find { |v| present?(v) }) ||
+                 "chi session"
+          [clip(name.to_s.strip, TITLE_MAX), BODIES.fetch(reason, "")]
+        end
+
+        def present?(value) = !value.nil? && !value.to_s.strip.empty?
+
+        # format.js clip.
+        def clip(text, max) = text.length > max ? "#{text[0, max - 1].rstrip}…" : text
+      end
+    end
+  end
+end