@supersuit/suggest-a-change 0.1.12 → 0.2.0

package/src/client/context.ts

@@ -0,0 +1,243 @@
+// EVERY PIECE OF CONTEXT THAT HELPS FIX IT, collected by the module with no app code. Each item says, in a line written
+// for the person sending, why it is shared; the sheet lists them all, on by default, and any one can be left out.
+//
+// The trail (the last pages, taps and errors) is kept from the moment the module first mounts, in memory only, in
+// small ring buffers. NEVER captured: what anyone typed (an input's value), cookies, storage, or a query string.
+import type { Identity } from './adapters.ts'
+
+export interface ContextItem { key: string; label: string; value: string; why: string }
+export interface Trail { routes: { route: string; at: string }[]; taps: { label: string; at: string }[]; errors: { message: string; frame?: string; at: string }[] }
+export interface ReportContext extends Trail { items: ContextItem[] }
+/** What an app adds through the `context` adapter: anything app-specific, each with why it helps. */
+export interface AppContextItem { label: string; value: string; why: string }
+
+const MAX = { routes: 10, taps: 20, errors: 10, items: 40 }
+// ONE trail per page, however many copies of the module a host bundles: the state lives on the global object under a
+// registered symbol, so a second copy finds the first one's listeners installed and shares its trail.
+type Shared = { trail: Trail; installedAt: number; undo: (() => void) | null }
+const SHARED = Symbol.for('@supersuit/suggest-a-change/context')
+const shared: Shared = ((globalThis as Record<symbol, unknown>)[SHARED] as Shared | undefined)
+  ?? ((globalThis as Record<symbol, unknown>)[SHARED] = { trail: { routes: [], taps: [], errors: [] }, installedAt: 0, undo: null }) as Shared
+const trail = shared.trail
+
+const clip = (s: string, max: number) => (s.length <= max ? s : `${s.slice(0, max - 1).trimEnd()}…`)
+const iso = () => new Date().toISOString()
+const push = <T>(list: T[], x: T, max: number) => { list.push(x); if (list.length > max) list.splice(0, list.length - max) }
+/** A URL or path with no query and no hash, wherever it appears in a piece of text. */
+export const withoutQueries = (s: string) => s.replace(/([^\s?#'"()]*)[?#][^\s'"():]*/g, (_m, before: string) => before)
+/** A path segment that is an id, a token or an address rather than a name: a uuid, a long number, a long hex or
+ *  base64 run with letters and digits, anything over 24 characters, or anything with an @. */
+const idLike = (raw: string) => {
+  let s = raw
+  try { s = decodeURIComponent(raw) } catch { /* as it is */ }
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s)
+    || /^\d{4,}$/.test(s)
+    || (/^[0-9a-f]{12,}$/i.test(s) && /\d/.test(s))
+    || (/^[A-Za-z0-9_-]{16,}$/.test(s) && /\d/.test(s) && /[A-Za-z]/.test(s))
+    || s.length > 24
+    || s.includes('@')
+}
+const routeOf = (href: string) => {
+  let path: string
+  try { path = new URL(href, 'http://x').pathname } catch { path = String(href).split(/[?#]/)[0] }
+  return path.split('/').map((seg) => (seg && idLike(seg) ? ':id' : seg)).join('/')
+}
+
+function recordRoute() {
+  if (typeof location === 'undefined') return
+  const route = routeOf(location.href)
+  if (trail.routes.at(-1)?.route === route) return
+  push(trail.routes, { route: clip(route, 300), at: iso() }, MAX.routes)
+}
+
+/** What a tapped thing is called: its label or its text, never what was typed into it. */
+function labelOf(target: EventTarget | null): string | null {
+  if (!(target instanceof Element)) return null
+  // Anything someone types into is "a text field", by its own label at most and never its text: an editable region,
+  // a text, search or combo box, wherever inside it the tap landed.
+  const typing = target.closest('[contenteditable]:not([contenteditable="false"]), [role="textbox"], [role="searchbox"], [role="combobox"]')
+  if (typing) return clip(typing.getAttribute('aria-label')?.trim() || 'a text field', 60)
+  const el = target.closest('button, a, summary, label, select, textarea, input, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="checkbox"], [aria-label]') ?? target
+  const aria = el.getAttribute('aria-label')?.trim()
+  if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) {
+    if (aria) return clip(aria, 60)
+    const byId = el.id ? document.querySelector(`label[for="${CSS.escape(el.id)}"]`)?.textContent?.trim() : ''
+    if (byId) return clip(byId.replace(/\s+/g, ' '), 60)
+    if (el instanceof HTMLTextAreaElement) return 'a text box'
+    if (el instanceof HTMLSelectElement) return 'a menu'
+    const type = el.type
+    return type === 'checkbox' ? 'a checkbox' : type === 'radio' ? 'a choice' : type === 'button' || type === 'submit' ? clip(el.value ? 'a button' : 'a button', 60) : 'a text field'
+  }
+  if (aria) return clip(aria, 60)
+  const text = (el.textContent ?? '').replace(/\s+/g, ' ').trim()
+  if (text) return clip(text, 60)
+  const title = el.getAttribute('title')?.trim()
+  return title ? clip(title, 60) : el.tagName.toLowerCase()
+}
+
+const firstFrame = (stack: unknown): string | undefined => {
+  if (typeof stack !== 'string') return undefined
+  const line = stack.split('\n').slice(1).map((l) => l.trim()).find((l) => /^at |@/.test(l))
+  return line ? clip(withoutQueries(line), 200) : undefined
+}
+const messageOf = (x: unknown): string => (x instanceof Error ? x.message : typeof x === 'string' ? x : x === undefined ? '' : typeof x === 'number' || typeof x === 'boolean' ? String(x) : '[object]')
+function recordError(message: string, stack?: unknown) {
+  push(trail.errors, { message: clip(withoutQueries(message || 'An error with no message'), 300), ...(firstFrame(stack) ? { frame: firstFrame(stack) } : {}), at: iso() }, MAX.errors)
+}
+
+/** Starts keeping the trail. Idempotent: every screen of the module calls it on mount, and it installs once. */
+export function installContextListeners(): void {
+  if (shared.undo || typeof window === 'undefined' || typeof document === 'undefined') return
+  shared.installedAt = Date.now()
+  // A wrapper a host put on top of ours may outlive a reset; once reset, ours only passes the call through.
+  let live = true
+  recordRoute()
+  const onClick = (e: Event) => { const l = labelOf(e.target); if (l) push(trail.taps, { label: l, at: iso() }, MAX.taps) }
+  const onError = (e: Event) => { const ev = e as ErrorEvent; recordError(ev.message || messageOf(ev.error), (ev.error as { stack?: unknown } | undefined)?.stack) }
+  const onRejection = (e: Event) => { const reason = (e as PromiseRejectionEvent).reason; recordError(`Unhandled rejection: ${messageOf(reason)}`, (reason as { stack?: unknown } | undefined)?.stack) }
+  const onNav = () => recordRoute()
+  document.addEventListener('click', onClick, true)
+  window.addEventListener('error', onError)
+  window.addEventListener('unhandledrejection', onRejection)
+  window.addEventListener('popstate', onNav)
+  window.addEventListener('hashchange', onNav)
+  const { pushState, replaceState } = history
+  const ourPush = function (this: History, ...a: Parameters<History['pushState']>) { const r = pushState.apply(this, a); if (live) recordRoute(); return r }
+  history.pushState = ourPush
+  const ourReplace = function (this: History, ...a: Parameters<History['replaceState']>) { const r = replaceState.apply(this, a); if (live) recordRoute(); return r }
+  history.replaceState = ourReplace
+  const consoleError = console.error
+  const ourError = function (this: Console, ...args: unknown[]) {
+    if (live) try { recordError(args.map(messageOf).filter(Boolean).join(' '), (args.find((a) => a instanceof Error) as Error | undefined)?.stack) } catch { /* the trail never breaks logging */ }
+    return consoleError.apply(this, args as [])
+  }
+  console.error = ourError
+  shared.undo = () => {
+    live = false
+    document.removeEventListener('click', onClick, true)
+    window.removeEventListener('error', onError)
+    window.removeEventListener('unhandledrejection', onRejection)
+    window.removeEventListener('popstate', onNav)
+    window.removeEventListener('hashchange', onNav)
+    // Put back only what is still ours: a wrapper the host added later stays, and calls through ours harmlessly.
+    if (history.pushState === ourPush) history.pushState = pushState
+    if (history.replaceState === ourReplace) history.replaceState = replaceState
+    if (console.error === ourError) console.error = consoleError
+  }
+}
+
+/** Stops keeping the trail and forgets it (tests, and a host that signs someone out). */
+export function resetContext(): void {
+  shared.undo?.(); shared.undo = null
+  trail.routes.length = 0; trail.taps.length = 0; trail.errors.length = 0
+}
+
+/** A copy of the trail as it stands. */
+export const contextTrail = (): Trail => ({ routes: trail.routes.map((r) => ({ ...r })), taps: trail.taps.map((t) => ({ ...t })), errors: trail.errors.map((e) => ({ ...e })) })
+
+/** A user agent in plain words: "iPhone, iOS 18.1, Safari 18.1". */
+export function parseUserAgent(ua: string): string {
+  const v = (re: RegExp) => re.exec(ua)?.[1]?.replace(/_/g, '.')
+  let device = 'Unknown device'; let os = ''
+  if (/iPhone/.test(ua)) { device = 'iPhone'; os = `iOS ${v(/OS (\d+[_.]\d+)/) ?? ''}`.trim() }
+  else if (/iPad/.test(ua)) { device = 'iPad'; os = `iPadOS ${v(/OS (\d+[_.]\d+)/) ?? ''}`.trim() }
+  else if (/Android/.test(ua)) { device = /Mobile/.test(ua) ? 'Android phone' : 'Android tablet'; os = `Android ${v(/Android (\d+(?:\.\d+)?)/) ?? ''}`.trim() }
+  else if (/Macintosh|Mac OS X/.test(ua)) { device = 'Mac'; os = 'macOS' }
+  else if (/Windows/.test(ua)) { device = 'Windows PC'; os = 'Windows' }
+  else if (/CrOS/.test(ua)) { device = 'Chromebook'; os = 'ChromeOS' }
+  else if (/Linux/.test(ua)) { device = 'Linux computer'; os = 'Linux' }
+  const browser =
+    v(/Edg(?:A|iOS)?\/(\d+)/) ? `Edge ${v(/Edg(?:A|iOS)?\/(\d+)/)}`
+      : v(/(?:Firefox|FxiOS)\/(\d+)/) ? `Firefox ${v(/(?:Firefox|FxiOS)\/(\d+)/)}`
+      : v(/(?:Chrome|CriOS)\/(\d+)/) ? `Chrome ${v(/(?:Chrome|CriOS)\/(\d+)/)}`
+      : /Safari/.test(ua) && v(/Version\/(\d+(?:\.\d+)?)/) ? `Safari ${v(/Version\/(\d+(?:\.\d+)?)/)}`
+      : ''
+  return [device, os, browser].filter(Boolean).join(', ')
+}
+
+/** The device in plain words from User-Agent Client Hints when the browser has them, else from the user agent. */
+async function deviceWords(given?: string): Promise<string> {
+  if (given) return parseUserAgent(given)
+  const nav = typeof navigator === 'undefined' ? undefined : (navigator as Navigator & { userAgentData?: { getHighEntropyValues?(h: string[]): Promise<Record<string, unknown>> } })
+  const uad = nav?.userAgentData
+  if (uad?.getHighEntropyValues) {
+    try {
+      const h = await Promise.race([uad.getHighEntropyValues(['platform', 'platformVersion', 'model', 'fullVersionList', 'mobile']), new Promise<null>((r) => setTimeout(() => r(null), 300))])
+      if (h) {
+        const brands = (h.fullVersionList as { brand: string; version: string }[] | undefined)?.filter((b) => !/Not.?A.?Brand|Chromium/i.test(b.brand)) ?? []
+        const b = brands.find((x) => /Edge/.test(x.brand)) ?? brands[0]
+        const platform = String(h.platform ?? '')
+        const device = String(h.model ?? '') || (platform === 'macOS' ? 'Mac' : platform === 'Windows' ? 'Windows PC' : platform === 'Android' ? (h.mobile ? 'Android phone' : 'Android tablet') : platform || 'Unknown device')
+        const os = [platform, String(h.platformVersion ?? '').split('.').slice(0, 2).join('.')].filter(Boolean).join(' ')
+        return [device, os, b ? `${b.brand.replace('Google ', '').replace('Microsoft ', '')} ${b.version.split('.')[0]}` : ''].filter(Boolean).join(', ')
+      }
+    } catch { /* fall back to the user agent */ }
+  }
+  return parseUserAgent(nav?.userAgent ?? '')
+}
+
+const two = (n: number) => String(n).padStart(2, '0')
+function timeWords(d: Date): string {
+  const zone = (() => { try { return Intl.DateTimeFormat().resolvedOptions().timeZone } catch { return '' } })()
+  const off = -d.getTimezoneOffset()
+  const offset = `UTC${off >= 0 ? '+' : '-'}${two(Math.floor(Math.abs(off) / 60))}:${two(Math.abs(off) % 60)}`
+  return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())} ${two(d.getHours())}:${two(d.getMinutes())} (${[zone, offset].filter(Boolean).join(', ')})`
+}
+const media = (q: string) => { try { return typeof matchMedia === 'function' && matchMedia(q).matches } catch { return false } }
+
+export interface CollectOptions {
+  identity?: Identity | null
+  where?: { screen?: string; route?: string }
+  about?: { app?: string; version?: string }
+  /** The app's own items (the `context` adapter). */
+  extra?: () => Promise<AppContextItem[]>
+  /** Ask the browser for a precise location (shows its permission prompt). Off unless the app opts in. */
+  precise?: boolean
+  /** A user agent to read instead of the browser's (tests). */
+  userAgent?: string
+  now?: () => number
+}
+
+/** Everything the module knows that would help fix it, each item with why it is shared, and the trail. */
+export async function collectContext(o: CollectOptions = {}): Promise<ReportContext> {
+  const now = new Date(o.now?.() ?? Date.now())
+  const items: ContextItem[] = []
+  const add = (key: string, label: string, value: string | undefined | null, why: string) => { if (value) items.push({ key, label: clip(label, 80), value: clip(value, 500), why: clip(why, 200) }) }
+  const who = o.identity as (Identity & { name?: string; username?: string }) | null | undefined
+  add('account', 'Your name in the app', who?.name || who?.username, 'so whoever fixes it knows who to thank, and can look at your account if the problem is in it')
+  add('time', 'Your local time', timeWords(now), 'so the fixer can line it up with what the app logged at that moment')
+  const langs = typeof navigator === 'undefined' ? [] : (navigator.languages?.length ? [...navigator.languages] : navigator.language ? [navigator.language] : [])
+  add('language', 'Your languages', langs.join(', '), 'some problems only happen in one language or date format')
+  add('device', 'Your device', await deviceWords(o.userAgent), 'so the fixer can try it on the same kind of device and browser')
+  if (typeof window !== 'undefined') {
+    const s = typeof screen === 'undefined' ? null : screen
+    add('screen', 'Screen and window', `${s ? `${s.width}x${s.height} screen, ` : ''}${window.innerWidth}x${window.innerHeight} window, ${window.devicePixelRatio || 1}x pixels`, 'how things are laid out depends on the size of the screen and window')
+    const look = [media('(prefers-color-scheme: dark)') ? 'dark mode' : 'light mode', ...(media('(prefers-reduced-motion: reduce)') ? ['reduced motion'] : [])]
+    add('appearance', 'Appearance', look.join(', '), 'some problems only show in dark mode or with animations turned down')
+  }
+  if (typeof navigator !== 'undefined') {
+    const c = (navigator as Navigator & { connection?: { type?: string; effectiveType?: string } }).connection
+    add('connection', 'Connection', [navigator.onLine === false ? 'offline' : 'online', c?.type, c?.effectiveType && `${c.effectiveType} speed`].filter(Boolean).join(', '), 'a slow or dropped connection explains many problems')
+  }
+  const since = shared.installedAt || (typeof performance !== 'undefined' ? performance.timeOrigin : 0)
+  if (since) {
+    const min = Math.max(0, Math.round((now.getTime() - since) / 60_000))
+    add('age', 'How long the page was open', min < 1 ? 'under a minute' : `${min} minute${min === 1 ? '' : 's'}`, 'some problems only start after a page has been open a while')
+  }
+  if (o.precise && typeof navigator !== 'undefined' && navigator.geolocation) {
+    const pos = await new Promise<GeolocationPosition | null>((resolve) => {
+      try { navigator.geolocation.getCurrentPosition(resolve, () => resolve(null), { maximumAge: 600_000, timeout: 5000 }) } catch { resolve(null) }
+    })
+    if (pos) add('place', 'Where you were', `${pos.coords.latitude.toFixed(3)}, ${pos.coords.longitude.toFixed(3)}`, 'this app asked for it, because some problems only happen in one place')
+  }
+  if (o.extra) {
+    try {
+      const got = await o.extra()
+      ;(Array.isArray(got) ? got : []).forEach((x) => {
+        // An app item that does not say why it is shared is not shared.
+        if (x && typeof x.label === 'string' && typeof x.value === 'string' && typeof x.why === 'string' && x.why.trim()) add(`app:${items.filter((i) => i.key.startsWith('app:')).length}`, x.label, x.value, x.why)
+      })
+    } catch { /* the app's own context failing never blocks a suggestion */ }
+  }
+  return { items: items.slice(0, MAX.items), ...contextTrail() }
+}

package/src/client/detail.tsx

@@ -3,7 +3,7 @@
 // it has an end status. A report's words are data: they are rendered as text, never as markup. A report
 // that is still only on this phone is shown from the phone's own copy, with the app's refusal if it gave one.
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { END, STATUSES } from '../contract.mjs'
+import { END, STATUSES, currentStatus } from '../contract.mjs'
 import type { Adapters, FieldProps } from './adapters.ts'
 import { DefaultField } from './default-field.tsx'
 import { draftKey } from './drafts.ts'
@@ -13,7 +13,7 @@ import { useRuntime, useTick, type FollowUp } from './runtime.ts'
 import { markSeen } from './seen.ts'
 import { Toasts } from './toast.tsx'
 import { dropCache, isRefusal, oneCacheKey, readCache, useClearOnSignOut, writeCache } from './view-cache.ts'
-import { effectiveCeilings, lengthWords, sizeWords, statusMeaning, statusWords, stringsFor } from './words.ts'
+import { effectiveCeilings, linkableIssue, lengthWords, sizeWords, statusMeaning, statusWords, stringsFor } from './words.ts'
 
 export function statusOf(r: Record<string, unknown>): string {
   if (typeof r.status === 'string') return r.status
@@ -22,7 +22,7 @@ export function statusOf(r: Record<string, unknown>): string {
   return 'received'
 }
 
-/** The step shown under "Being made". The timeline entry is the truth (that is where the receiving side puts it); a top-level `step` is read only when there is no timeline. */
+/** The step shown under the current status. The timeline entry is the truth (that is where the receiving side puts it); a top-level `step` is read only when there is no timeline. */
 export function stepOf(r: Record<string, unknown>): string | undefined {
   const t = r.timeline
   if (Array.isArray(t) && t.length) { const s = (t[t.length - 1] as { step?: unknown })?.step; return typeof s === 'string' && s ? s : undefined }
@@ -33,7 +33,10 @@ const timelineOf = (r?: Record<string, unknown>): string[] | undefined =>
 
 /** The strip is made from the contract's own statuses, one step per distinct word ("planned" reads as "With Pluma"),
  *  and a step is marked from the report's timeline: reached, skipped (the report went past it), or still ahead. */
-export function StatusStrip({ status, owner, step, timeline, label }: { status: string; owner: string; step?: string; timeline?: string[]; /** The list's accessible name; the screens pass the app's own (words.text.stepLabel). */ label?: string }) {
+export function StatusStrip({ status: given, owner, step, timeline: givenTimeline, label }: { status: string; owner: string; step?: string; timeline?: string[]; /** The list's accessible name; the screens pass the app's own (words.text.stepLabel). */ label?: string }) {
+  // An old (0.1.x) status reads as the new one it means, on the strip and in the timeline it is marked from.
+  const status = currentStatus(given)
+  const timeline = givenTimeline?.map((s) => currentStatus(s))
   const nodes = useMemo(() => {
     const out: { words: string; ids: string[] }[] = []
     for (const id of STATUSES.filter((s: string) => !END.includes(s))) {
@@ -46,7 +49,7 @@ export function StatusStrip({ status, owner, step, timeline, label }: { status:
   const ended = END.includes(status)
   const here = nodes.findIndex((n) => n.ids.includes(status))
   const at = ended ? nodes.length : Math.max(0, here)
-  const items = [...nodes, { words: statusWords(ended ? status : 'live', owner), ids: [ended ? status : 'end'] }]
+  const items = [...nodes, { words: statusWords(ended ? status : 'done', owner), ids: [ended ? status : 'end'] }]
   const reached = new Set(timeline ?? [])
   return (
     <ol className="sac-strip" aria-label={label ?? stringsFor({ app: 'x', owner }).stepLabel} data-status={status}>
@@ -60,7 +63,7 @@ export function StatusStrip({ status, owner, step, timeline, label }: { status:
         return (
           <li key={it.words + i} className="sac-step" data-state={state} aria-current={i === at ? 'step' : undefined}>
             <span>{it.words}</span>
-            {i === at && it.ids.includes('being-made') && step ? <span className="sac-step-detail">{step}</span> : null}
+            {i === at && step ? <span className="sac-step-detail">{step}</span> : null}
           </li>
         )
       })}
@@ -188,9 +191,10 @@ export function SuggestionDetail({ adapters, id }: { adapters: Adapters; id: str
   if (who === null) return <p role="alert">{S.signedOutMine}</p>
   if (report === undefined) return <p>{S.loading}</p>
   if (report === null) return <p role="alert">{S.couldNotOpen}</p>
-  const status = statusOf(report)
+  const status = currentStatus(statusOf(report))
   const owner = adapters.words.owner
   const open = !END.includes(status) && status !== 'on-phone'
+  const issue = linkableIssue(report.issue)
   const answers = (report.answers ?? {}) as Record<string, string>
   const voice = Array.isArray(report.voice) ? (report.voice as { file: string; ms: number }[]) : []
   const media = Array.isArray(report.media) ? (report.media as { file: string; type: string; bytes: number }[]) : []
@@ -229,7 +233,8 @@ export function SuggestionDetail({ adapters, id }: { adapters: Adapters; id: str
   return (
     <article className="sac-detail" data-report={id}>
       <h3 className="sac-status" data-status={status}>{statusWords(status, owner)}</h3>
-      <p className="sac-muted">{statusMeaning(status, owner)}{status === 'live' && typeof report.liveAt === 'string' ? ` (${new Date(report.liveAt).toLocaleDateString()})` : ''}</p>
+      <p className="sac-muted">{statusMeaning(status, owner, report.issue)}</p>
+      {issue ? <p><a className="sac-issue-link" href={issue.url} target="_blank" rel="noopener noreferrer">{S.issueLink(issue.number)}</a></p> : null}
       {refusal ? (
         <>
           <p role="alert" className="sac-error">{refusal}</p>

package/src/client/entry.tsx

@@ -3,9 +3,10 @@
 // Signed out, it opens nothing and says why. Signed in, it hands over to the host (`onOpen`), which
 // shows the sheet. `<ReportProblem>` is the same control for an error screen, already filled in.
 import { useEffect, useState, type AriaRole, type ReactNode } from 'react'
+import { currentStatus } from '../contract.mjs'
 import type { Adapters } from './adapters.ts'
 import { useRuntime, type Runtime } from './runtime.ts'
-import { firstToastThisOpen, moved, onSeen } from './seen.ts'
+import { firstToastThisOpen, fresh, moved, onSeen } from './seen.ts'
 import { SuggestSheet } from './sheet.tsx'
 import { toast, Toasts } from './toast.tsx'
 import { useClearOnSignOut } from './view-cache.ts'
@@ -19,7 +20,7 @@ export function KeepSending({ adapters }: { adapters: Adapters }) {
 }
 
 // THE NEWS: once per mount, asks the app for this person's reports and compares each with what they last opened. A move
-// since then is counted (the dot), and the newest one gets the page load's one toast, whichever of the entry or a
+// since then is counted (the dot), and the newest one the last page load had not already seen gets the page load's one toast, whichever of the entry or a
 // root-mounted SuggestNews asks first (the guard is per page load and account, in seen.ts). Opening a report anywhere
 // recounts. `toasted` says this mount showed the toast, so a standalone entry knows to draw a toast host for it.
 function useNews(adapters: Adapters, rt: Runtime | null): { moved: number; toasted: boolean } {
@@ -44,10 +45,13 @@ function useNews(adapters: Adapters, rt: Runtime | null): { moved: number; toast
       try { now = await adapters.identity() } catch { now = null }
       if (!live || !rows || !now || now.account !== rt.who.account) return
       const m = await count()
-      if (!live || !m?.length || !firstToastThisOpen(id)) return
+      if (!live || !m) return
+      // Only a move the last page load had not already seen is toasted; an older one keeps just the dot.
+      const f = await fresh(rt.store, id, m)
+      if (!f.length || !firstToastThisOpen(id)) return
       const at = (x: string) => rows!.find((r) => r.id === x)?.at ?? 0
-      const top = [...m].sort((a, b) => at(b.id) - at(a.id))[0]
-      const note = top.status === 'not-now' ? rows.find((r) => r.id === top.id)?.note : undefined
+      const top = [...f].sort((a, b) => at(b.id) - at(a.id))[0]
+      const note = currentStatus(top.status) === 'not-planned' ? rows.find((r) => r.id === top.id)?.note : undefined
       setToasted(true)
       toast({ id: `sac-moved-${top.id}`, text: S.movedToast(statusWords(top.status, adapters.words.owner), typeof note === 'string' && note ? note : undefined), ms: 6000 })
     })()

package/src/client/index.ts

@@ -15,3 +15,5 @@ export * from './mine.tsx'
 export { seenStatuses, markSeen, moved, onSeen, seenKey, type Seen } from './seen.ts'
 export * from './detail.tsx'
 export { refreshIdentity } from './runtime.ts'
+export { collectContext, installContextListeners, contextTrail, resetContext, parseUserAgent, withoutQueries } from './context.ts'
+export type { ContextItem, AppContextItem, ReportContext, Trail, CollectOptions } from './context.ts'

package/src/client/mine.tsx

@@ -11,7 +11,8 @@ import { useRuntime, useTick } from './runtime.ts'
 import { moved, onSeen } from './seen.ts'
 import { dropCache, isRefusal, mineCacheKey, pruneOnes, readCache, useClearOnSignOut, writeCache } from './view-cache.ts'
 import { Toasts } from './toast.tsx'
-import { statusMeaning, statusWords, stringsFor } from './words.ts'
+import { currentStatus } from '../contract.mjs'
+import { linkableIssue, statusMeaning, statusWords, stringsFor } from './words.ts'
 
 type Row = Summary & { error?: string }
 
@@ -119,14 +120,17 @@ export function MySuggestions({ adapters, onOpen }: { adapters: Adapters; onOpen
         <ul className="sac-list">
           {rows.map((r) => {
             const preview = typeof r.words === 'string' ? r.words : typeof r.title === 'string' ? r.title : ''
+            const issue = linkableIssue(r.issue)
             return (
-              <li key={r.id} className="sac-row" data-status={r.status}>
+              <li key={r.id} className="sac-row" data-status={currentStatus(r.status)}>
                 <button type="button" className="sac-row-button" onClick={() => (onOpen ? onOpen(r.id) : setOpen(r.id))}>
                   {fresh.has(r.id) ? <span className="sac-new" data-new="">{S.newMark}</span> : null}
                   {preview ? <span className="sac-row-words">{preview}</span> : null}
                   <span className="sac-row-status">{statusWords(r.status, owner)}</span>
-                  <span className="sac-muted">{statusMeaning(r.status, owner)}</span>
+                  <span className="sac-muted">{statusMeaning(r.status, owner, r.issue)}</span>
                 </button>
+                {/* The row links to the issue; someone who cannot read the repo still sees the number and the state. */}
+                {issue ? <a className="sac-issue-link" href={issue.url} target="_blank" rel="noopener noreferrer">{S.issueLink(issue.number)}</a> : null}
                 {r.error ? (
                   <>
                     <p role="alert" className="sac-error">{r.error}</p>

package/src/client/runtime.ts

@@ -7,6 +7,7 @@
 // when none of its writes is left there, because a write leaves only after the adapter said `done`.
 import { useEffect, useRef, useState } from 'react'
 import type { Adapters, Identity } from './adapters.ts'
+import { installContextListeners } from './context.ts'
 import { draftKey } from './drafts.ts'
 import { openStore, type Store } from './idb.ts'
 import { makeOutbox, type Op, type Sent } from './outbox.ts'
@@ -179,6 +180,8 @@ export function useRuntime(adapters: Adapters): { rt: Runtime | null; who: Ident
   const [signal, setSignal] = useState(0)
   const current = useRef<{ account: string | null; release: () => void }>({ account: null, release: () => {} })
   const alive = useRef(true)
+  // Every screen of the module mounts this, so the trail (pages, taps, errors) starts with the first one; it installs once.
+  useEffect(() => { installContextListeners() }, [])
   useEffect(() => { alive.current = true; return () => { alive.current = false; current.current.release(); current.current = { account: null, release: () => {} } } }, [])
   useEffect(() => { const l = () => setSignal((n) => n + 1); identityListeners.add(l); return () => { identityListeners.delete(l) } }, [])
   useEffect(() => { if (state.rt) state.rt.adapters = adapters })

package/src/client/seen.ts

@@ -4,7 +4,7 @@
 // every end) is "moved": the entry shows a dot, My suggestions marks the row New, and one toast says it. Opening
 // the report marks it seen. The record sits beside the cached views, under the same app-and-account key, so another
 // account never reads it and signing out clears it with them (clearViewCache).
-import { TOLD } from '../contract.mjs'
+import { TOLD, currentStatus } from '../contract.mjs'
 import { draftKey } from './drafts.ts'
 import type { Store } from './idb.ts'
 import { readCache, writeCache } from './view-cache.ts'
@@ -34,8 +34,9 @@ export async function seenStatuses(store: Store, id: Id): Promise<Seen> {
 export function markSeen(store: Store, id: Id, reportId: string, status: string): Promise<void> {
   return serial(seenKey(id), async () => {
     const seen = await seenStatuses(store, id)
-    if (seen[reportId] === status) return
-    seen[reportId] = status
+    const now = currentStatus(status) // kept in the new words, so an old status and the one it means are the same news
+    if (seen[reportId] === now) return
+    seen[reportId] = now
     await writeCache(store, seenKey(id), seen)
     for (const l of listeners) l()
   })
@@ -51,9 +52,10 @@ export function moved(store: Store, id: Id, rows: { id: string; status: string }
     let changed = false
     for (const r of rows) {
       if (typeof r?.id !== 'string' || typeof r.status !== 'string' || r.status === 'on-phone') continue
-      const had = seen[r.id]
-      if (had === r.status) continue
-      if (had === undefined || !TOLD.includes(r.status)) { seen[r.id] = r.status; changed = true; continue }
+      const had = seen[r.id] === undefined ? undefined : currentStatus(seen[r.id])
+      const now = currentStatus(r.status)
+      if (had === now) continue
+      if (had === undefined || !TOLD.includes(now)) { seen[r.id] = now; changed = true; continue }
       out.push({ id: r.id, status: r.status })
     }
     if (changed) await writeCache(store, seenKey(id), seen)
@@ -70,3 +72,22 @@ export function firstToastThisOpen(id: Id): boolean {
   toasted.add(k)
   return true
 }
+
+/** WHAT THE LAST PAGE LOAD ALREADY SAW. The moves (report and status) that were already news the last time the app was
+ *  loaded, so a move the person was told about, or could have been, is not toasted again on the next load; it keeps
+ *  only the dot and the New mark until they open it. Returns the moves in `m` that are new since then, and records `m`
+ *  as what this load saw. With no record yet (the first load on this release) every move is fresh, as before. */
+export const noticedKey = (id: Id) => `${draftKey(id)}#view:noticed`
+export function fresh(store: Store, id: Id, m: { id: string; status: string }[]): Promise<{ id: string; status: string }[]> {
+  return serial(noticedKey(id), async () => {
+    const had = await readCache<Seen>(store, noticedKey(id))
+    const before = had && typeof had === 'object' ? had : {}
+    const out = m.filter((r) => before[r.id] !== r.status)
+    const now: Seen = { ...before }
+    for (const r of m) now[r.id] = r.status
+    // A report no longer moved (opened, or gone) drops out, so the record stays the size of the dot.
+    for (const k of Object.keys(now)) if (!m.some((r) => r.id === k)) delete now[k]
+    await writeCache(store, noticedKey(id), now)
+    return out
+  })
+}

package/src/client/sheet.tsx

@@ -6,7 +6,11 @@
 // through the outbox, so a closed app loses nothing. A voice note alone is a whole report.
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
 import { isAcceptedMedia, sanitizeRoute, typeForFile, validateReport } from '../contract.mjs'
-import type { Adapters, FieldProps, Kind } from './adapters.ts'
+import type { Adapters, FieldProps, Kind, SheetDestination } from './adapters.ts'
+import { destinationWords, whatGoes, type GoesItem } from '../github/compose.ts'
+import { validContact } from '../contract.mjs'
+import type { Contact } from './adapters.ts'
+import { collectContext, type ReportContext } from './context.ts'
 import { useDialog } from './dialog.ts'
 import { DefaultField } from './default-field.tsx'
 import { draftKey, loadDraft, saveDraft } from './drafts.ts'
@@ -83,6 +87,32 @@ export function SuggestSheet({ adapters, where, onClose, initial }: { adapters:
   const [announce, setAnnounce] = useState('')
   const [sent, setSent] = useState<{ id: string; files: { file: string; name: string; bytes: number }[] } | null>(null)
   const [loaded, setLoaded] = useState(false)
+  const [dest, setDest] = useState<SheetDestination | null>(null)
+  // Everything shared so it can be fixed, each with why; all on by default, any one can be left out (`choice`).
+  const [ctx, setCtx] = useState<ReportContext | null>(null)
+  const [contact, setContact] = useState<Contact | null>(null)
+  const [choice, setChoice] = useState<Record<string, boolean>>({})
+  // Where it files, asked once when the sheet opens; until it answers (or with none) the one-line note stays.
+  useEffect(() => {
+    if (!adapters.destination) return
+    let live = true
+    adapters.destination().then((d) => { if (live) setDest(d && typeof d.repo === 'string' ? d : null) }, () => { if (live) setDest(null) })
+    return () => { live = false }
+  }, [adapters])
+  const contextOptions = useCallback(() => {
+    const c = adapters.context
+    return typeof c === 'function' ? { extra: c, precise: false } : { extra: c?.items ? () => c.items!() : undefined, precise: Boolean(c?.precise) }
+  }, [adapters])
+  const gather = useCallback(() => collectContext({ identity: who ?? null, where, about: adapters.about, ...contextOptions(), ...(adapters.phone?.now ? { now: adapters.phone.now } : {}) }), [who, where, adapters, contextOptions])
+  useEffect(() => {
+    if (!who) return
+    let live = true
+    void gather().then((c) => { if (live) setCtx(c) })
+    if (adapters.contact) adapters.contact().then((c) => { if (live) setContact(c && !validContact(c).length ? c : null) }, () => {})
+    return () => { live = false }
+    // where is an object the host may rebuild each render; the context is gathered once per open and again at Send.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [adapters, who])
   const chain = useRef<Promise<unknown>>(Promise.resolve())
   // What is on the sheet, kept in step with state so a second take or picture added a moment later counts the first.
   const voiceRef = useRef<Voice[]>([])
@@ -265,6 +295,30 @@ export function SuggestSheet({ adapters, where, onClose, initial }: { adapters:
   ] as { name: Diag; label: string; value: string | undefined }[]).filter((d): d is { name: Diag; label: string; value: string } => Boolean(d.value))
   const lineParts = [`this screen (${where.screen}, ${sanitizeRoute(where.route)})`, ...avail.map((d) => d.label)]
   const summary = `${S.goesTo(adapters.words.owner)} ${S.includes(lineParts)}`
+  // With a destination, the one line becomes the list of exactly what the issue will carry, built by the same function
+  // the issue is written from (`whatGoes`), so the list and the issue cannot drift. It follows the draft as it changes.
+  // Every row of the list, whether or not there is a destination; optional rows carry a tick box.
+  const rows = whatGoes({
+    kind, words, voice: voice.map((v) => ({ file: v.file, ms: v.ms })), media: media.map((m) => ({ file: m.file, type: m.type, bytes: m.bytes })),
+    where: { screen: where.screen, route: sanitizeRoute(where.route) },
+    diagnostics: Object.fromEntries(avail.map((d) => [d.name, d.value])),
+    appName: adapters.about?.app ?? adapters.words.app,
+    ...(dest?.name ? { filerName: dest.name } : {}),
+    ...(ctx ? { context: ctx } : {}),
+    ...(contact ? { who: { contact } } : {}),
+  }, dest ?? { repo: '', public: false, account: '', attaches: true })
+  const isOn = (key: string, fallback = true) => choice[key] ?? rows.find((r) => r.key === key)?.on ?? fallback
+  const goes = dest ? rows : null
+  const destWords = dest ? destinationWords(dest) : null
+  const optionalRow = (g: GoesItem) => (
+    <li key={g.key} data-goes={g.key} className="sac-goes-opt">
+      <label>
+        <input type="checkbox" checked={isOn(g.key)} onChange={(e) => setChoice((c) => ({ ...c, [g.key]: e.target.checked }))} />{' '}
+        <span className="sac-goes-label">{g.text}</span>{g.value ? <>: <span className="sac-goes-value">{g.value}</span></> : null}{' '}
+        <span className="sac-muted sac-goes-why">({g.why}{g.reason ? `; off by default because ${g.reason}` : ''})</span>
+      </label>
+    </li>
+  )
 
   const hasAnything = Boolean(words.trim() || voice.length || media.length)
 
@@ -273,13 +327,20 @@ export function SuggestSheet({ adapters, where, onClose, initial }: { adapters:
     setError('')
     await chain.current
     const d = await saveDraft(rt.store, key, { kind, words, attachments: [...voice.map((v) => v.key), ...media.map((m) => m.key)] })
+    // What was left out never leaves the phone: the context gathered again now (the trail has grown), minus every row
+    // the person unticked, and the diagnostics those rows stand for.
+    const fresh = await gather()
+    const keep = { ...fresh, items: fresh.items.filter((i) => isOn(`ctx:${i.key}`)), routes: isOn('routes') ? fresh.routes : [], taps: isOn('taps') ? fresh.taps : [], errors: isOn('errors') ? fresh.errors : [] }
+    const leftOut: Record<string, Diag> = { 'ctx:device': 'device', 'ctx:screen': 'screen', 'ctx:time': 'at' }
     const diagnostics: Record<string, string> = {}
-    for (const x of avail) diagnostics[x.name] = x.value
+    for (const x of avail) if (!Object.entries(leftOut).some(([k, d]) => d === x.name && !isOn(k))) diagnostics[x.name] = x.value
+    const reach = contact && isOn('contact') ? contact : null
     const report: Record<string, unknown> & { id: string } = {
       id: d.reportId,
       kind,
       ...(adapters.about ? { app: Object.fromEntries(Object.entries(adapters.about).filter(([k]) => k !== 'version')) } : {}),
-      who: { member: who.account, role: who.role },
+      who: { member: who.account, role: who.role, ...(reach ? { contact: reach } : {}) },
+      context: keep,
       words: words.trim(),
       voice: voice.map((v) => ({ file: v.file, ms: v.ms, field: v.field })),
       media: await Promise.all(media.map(async (m) => {
@@ -398,7 +459,20 @@ export function SuggestSheet({ adapters, where, onClose, initial }: { adapters:
               ) : null}
             </fieldset>
 
-            <p className="sac-muted sac-fyi" data-sac-summary="">{summary}</p>
+            {goes && destWords ? (
+              <div className="sac-goes sac-fyi" data-sac-goes="">
+                <p className="sac-goes-head"><strong>{destWords.headline}</strong>{' ('}<span className={destWords.danger ? 'sac-danger' : 'sac-muted'}>{destWords.privacy}</span>)</p>
+                <p className="sac-muted">It will carry:</p>
+                <ul className="sac-goes-list">{goes.filter((g) => !g.optional).map((g) => <li key={g.key} data-goes={g.key}>{g.text}</li>)}</ul>
+                {goes.some((g) => g.optional) ? <ul className="sac-goes-opts" aria-label={S.contextLegend}>{goes.filter((g) => g.optional).map(optionalRow)}</ul> : null}
+                <p className="sac-muted">{destWords.account}</p>
+              </div>
+            ) : (
+              <div className="sac-fyi">
+                <p className="sac-muted sac-fyi" data-sac-summary="">{summary}</p>
+                {rows.some((g) => g.optional) ? <ul className="sac-goes-opts" aria-label={S.contextLegend}>{rows.filter((g) => g.optional).map(optionalRow)}</ul> : null}
+              </div>
+            )}
 
             {error ? <p role="alert" className="sac-error">{error}</p> : null}
             <div className="sac-actions">

package/src/client/styles.css

@@ -56,6 +56,11 @@
 .sac-muted { color: var(--sac-muted); font-size: 0.9rem; }
 .sac-fyi { font-size: 0.8rem; margin: 0; }
 .sac-error { color: var(--sac-danger); margin: 0; }
+.sac-danger { color: var(--sac-danger); font-weight: 600; }
+.sac-goes p { margin: 0; }
+.sac-goes-list { margin: 2px 0; padding: 0; list-style: none; display: flex; flex-wrap: wrap; gap: 2px 0; }
+.sac-goes-list li:not(:last-child)::after { content: " \00b7 "; white-space: pre; color: var(--sac-muted); }
+.sac-issue-link { color: var(--sac-accent); font-size: 0.9rem; }
 .sac-receipt-line { font-weight: 600; margin: 0; }
 .sac-strip { list-style: none; margin: 0; padding: 0; display: flex; flex-wrap: wrap; gap: 6px; }
 .sac-step { border: 1px solid var(--sac-border); border-radius: 999px; padding: 4px 10px; color: var(--sac-muted); }
@@ -63,8 +68,12 @@
 .sac-step[data-state="now"] { border-color: var(--sac-accent); color: var(--sac-fg); font-weight: 600; }
 .sac-step-detail { display: block; font-weight: 400; font-size: 0.85rem; }
 .sac-words { white-space: pre-wrap; overflow-wrap: anywhere; }
-.sac-toasts { position: fixed; left: 0; right: 0; top: calc(env(safe-area-inset-top) + 8px); z-index: calc(var(--sac-z) + 1); display: flex; flex-direction: column; align-items: center; gap: 8px; padding: 0 16px; pointer-events: none; }
-.sac-toast { pointer-events: auto; font: inherit; width: 100%; max-width: 28rem; text-align: left; padding: 12px 16px; border-radius: var(--sac-radius); border: 1px solid var(--sac-border); background: var(--sac-bg); color: var(--sac-fg); }
+/* Toasts sit small at the bottom edge, never over the top of the host's page: the top is where an app opens onto
+   its own content, and a full-width bar there reads as the app's header. Each is a pill as wide as its words, with a
+   drawn x so it reads as dismissable (the whole pill is the button). */
+.sac-toasts { position: fixed; left: 0; right: 0; bottom: calc(env(safe-area-inset-bottom) + 12px); z-index: calc(var(--sac-z) + 1); display: flex; flex-direction: column; align-items: center; gap: 6px; padding: 0 16px; pointer-events: none; }
+.sac-toast { pointer-events: auto; font: inherit; font-size: 0.875rem; line-height: 1.3; width: auto; max-width: min(100%, 24rem); text-align: left; padding: 6px 12px; border-radius: 999px; border: 1px solid var(--sac-border); background: var(--sac-bg); color: var(--sac-fg); display: inline-flex; align-items: center; gap: 8px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.18); }
+.sac-toast::after { content: "\00d7"; color: var(--sac-muted); font-size: 1rem; line-height: 1; }
 .sac-toast[data-tone="warn"] { background: var(--sac-fg); color: var(--sac-bg); }
 .sac-entry-why { margin-left: 8px; color: var(--sac-muted); font-size: 0.9rem; }
 .sac-sheet :focus-visible, .sac-entry:focus-visible, .sac-button:focus-visible, .sac-record:focus-visible, .sac-row-button:focus-visible { outline: 3px solid var(--sac-focus); outline-offset: 2px; }