dsh-zen-remote 1.1.16 → 2.0.1

package/src/client/current-session-report.ts

@@ -0,0 +1,164 @@
+/**
+ * T62: the browser half of the current-session signal. The intercept layer
+ * that decides whether a closed-remote session hides runs in the BACKEND
+ * Node process (it wraps the host's typert gateway there — src/index.ts's
+ * installIntercept), so THIS is the only place the host's persisted
+ * selection (localStorage `dsh.sessions.current`, the workspace UI's
+ * selection store) is readable. The reporter watches it and POSTs every
+ * CHANGE to the backend route; the route stores the value and makes the
+ * intercept re-judge at once, with a 1s backend poll as the fallback.
+ *
+ * Re-check points: page load, the `storage` event (a DIFFERENT tab or
+ * window changed the key — same-tab writes fire no storage event), the
+ * page becoming visible again, and a 1s interval that doubles as the retry
+ * path: a failed POST leaves the last-reported value untouched, so the
+ * next tick re-sends it (same-tab navigations are what the interval is
+ * really for). Failures are silent — background plumbing must never log
+ * or toast.
+ *
+ * Runs only in the CLIENT role (a host has no relay and no intercept): the
+ * role comes from the SAME cached `client-config` probe the share parts
+ * use — a definite 'client' starts reporting, a 'host' never reports, and
+ * an undecided probe re-asks on each tick (once it lands the answer is
+ * stable for the process's lifetime).
+ */
+import { CURRENT_SESSION_STORAGE_KEY, currentSessionReportEquals, parseCurrentSessionStorage } from '../client-data/current-session.ts'
+import type { CurrentSessionReport } from '../client-data/current-session.ts'
+import { probeClientConfigRole } from './remote-share-register.ts'
+
+/** Default POST target, mirrored from src/client-routes.ts (the client
+ * tsconfig cannot reach the host file). */
+const CURRENT_SESSION_ROUTE = '/_dsh/zen-remote/client/current-session'
+
+/** The re-check cadence — the same 1s the backend's fallback poll uses. */
+const CHECK_INTERVAL_MS = 1_000
+
+/**
+ * How often the current value is re-sent even when unchanged (T66): the
+ * reporter otherwise posts only CHANGES, but the backend can be reset
+ * underneath the page — a plugin row reload re-runs apply() and drops its
+ * stored value — leaving the page convinced it already reported. One
+ * unconditional re-post per window keeps the two ends converging without
+ * waiting for the user to navigate.
+ */
+const RESEND_INTERVAL_MS = 30_000
+
+/** The storage face used, narrowed to the one method (structurally typed:
+ * this module compiles under the client tsconfig with DOM lib, but tests
+ * inject stubs). */
+interface StorageLike {
+  getItem(key: string): string | null
+}
+
+export interface CurrentSessionReporterOptions {
+  /** The storage reader. Default: the page's localStorage; a broken or
+   * absent one makes every read `unavailable` and nothing is ever posted. */
+  storage?: StorageLike
+  /** Outbound POST transport. Default: the page's fetch. */
+  fetchImpl?: (url: string, init: RequestInit) => Promise<unknown>
+  /** The role probe. Default: the shared cached client-config probe. */
+  probeRole?: () => Promise<'host' | 'client' | undefined>
+  /** POST target. Default: the current-session route. */
+  route?: string
+  /** The re-check interval; default 1000ms. */
+  intervalMs?: number
+  /** The unconditional re-send window (T66); default 30000ms. */
+  resendIntervalMs?: number
+}
+
+/** One reportable value — `unavailable` never travels. */
+type ReportableReport = Exclude<CurrentSessionReport, { kind: 'unavailable' }>
+
+/**
+ * Start the reporter loop. Returns the disposer (listeners + interval) the
+ * mounting effect calls on teardown.
+ */
+export function startCurrentSessionReporter(options: CurrentSessionReporterOptions = {}): () => void {
+  const readRaw = (): string | null | undefined => {
+    const storage = options.storage ?? (globalThis as { localStorage?: StorageLike | null }).localStorage
+    if (storage === null || storage === undefined || typeof storage.getItem !== 'function') return undefined
+    try {
+      return storage.getItem(CURRENT_SESSION_STORAGE_KEY)
+    } catch {
+      return undefined
+    }
+  }
+  const post = (report: ReportableReport): Promise<unknown> => {
+    const doFetch = options.fetchImpl ?? fetch
+    const body = report.kind === 'open' ? { sessionId: report.sessionId } : { sessionId: null }
+    return doFetch(options.route ?? CURRENT_SESSION_ROUTE, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json; charset=utf-8' },
+      body: JSON.stringify(body),
+    })
+  }
+  const probeRole = options.probeRole ?? probeClientConfigRole
+
+  // The last value the backend ACCEPTED (undefined = nothing posted yet).
+  // A failed POST must not advance it — that is the whole retry rule: the
+  // value still differs, so the next change or the next check re-sends.
+  // T66: the timestamp of the last accepted post drives the slow unconditional
+  // re-send (0 = due immediately, which is the page-load post).
+  let lastReported: CurrentSessionReport | undefined
+  let lastSentAt = 0
+  const resendEveryMs = options.resendIntervalMs ?? RESEND_INTERVAL_MS
+  let role: 'host' | 'client' | undefined
+  let inFlight = false
+
+  const tick = async (): Promise<void> => {
+    if (role === undefined) {
+      const answer = await probeRole()
+      // A failed probe changes nothing — the next tick asks again; a
+      // definite answer is stable for the page's life.
+      if (answer !== undefined) role = answer
+    }
+    if (role !== 'client') return
+    const report = parseCurrentSessionStorage(readRaw())
+    if (report.kind === 'unavailable') return
+    const now = Date.now()
+    // T66: inside the re-send window an unchanged value says nothing; once
+    // the window passes, the CURRENT value re-posts even unchanged — the
+    // backend may have been reset underneath the page.
+    const resendDue = now - lastSentAt >= resendEveryMs
+    if (!resendDue && lastReported !== undefined && currentSessionReportEquals(report, lastReported)) return
+    try {
+      await post(report)
+      lastReported = report
+      lastSentAt = now
+    } catch {
+      // Silent: the next tick sees the unchanged lastReported and retries.
+    }
+  }
+  const tickOnce = (): void => {
+    // One re-check at a time: a slow POST must not pile up parallel tries.
+    if (inFlight) return
+    inFlight = true
+    void tick().finally(() => { inFlight = false })
+  }
+
+  const globalObj = globalThis as {
+    window?: { addEventListener(type: string, fn: () => void): void, removeEventListener(type: string, fn: () => void): void }
+    document?: { addEventListener(type: string, fn: () => void): void, removeEventListener(type: string, fn: () => void): void }
+  }
+  const onStorage = (): void => { tickOnce() }
+  const onVisibility = (): void => { tickOnce() }
+  globalObj.window?.addEventListener('storage', onStorage)
+  globalObj.document?.addEventListener('visibilitychange', onVisibility)
+  const timer = setInterval(() => { tickOnce() }, options.intervalMs ?? CHECK_INTERVAL_MS)
+  tickOnce()
+  return () => {
+    clearInterval(timer)
+    globalObj.window?.removeEventListener('storage', onStorage)
+    globalObj.document?.removeEventListener('visibilitychange', onVisibility)
+  }
+}
+
+/**
+ * Mount the reporter as one page-lifetime effect. The caller places this
+ BEFORE the desktop-shell gate in apply(): the desktop app in the client
+ * role is exactly where remote sessions live, so the report must not wait
+ * on a width gate. On a host the loop idles after one probe answer.
+ */
+export function mountCurrentSessionReporter(ctx: { effect(fn: () => () => void, name: string): void }, options: CurrentSessionReporterOptions = {}): void {
+  ctx.effect(() => startCurrentSessionReporter(options), 'dsh-zen-remote: current-session report')
+}

package/src/client/effects/header-status.ts

@@ -1,4 +1,5 @@
 import type { ClientContext } from '../compat/types.ts'
+import { mainSessionIdOf } from '../compat/types.ts'
 import { dotState } from '../session-dot.ts'
 
 /**
@@ -18,30 +19,33 @@ export function installHeaderStatusDot(ctx: ClientContext): void {
     const apply = (): void => {
       const frame = document.querySelector('[data-mobile-nav="frame"]')
       if (frame === null) return
-      const { current, byId } = ctx.sessions.list.getSnapshot()
+      // 0.1.7: SessionListState.current is gone — the main-view session
+      // derives from the catalog rows (mainSessionIdOf). The pending flag
+      // moved with it: uiSession.pendingInteractions is gone too, the fact
+      // now rides ctx.uiSession.sessionStatus (running + pendingInteraction
+      // per session). Probed fresh on every dot recompute so registration
+      // order never matters, same as before.
+      const { byId } = ctx.sessions.list.getSnapshot()
+      const current = mainSessionIdOf(byId)
       const row = current === undefined ? undefined : byId[current]
-      // 0.1.2 的待处理交互来源，每次现查：本插件的 inject 不含 uiSession（加了
-      // 0.1.1 就不激活），apply 此刻服务未必注册好；每次算 dot 时现查，注册顺序
-      // 就不再是问题。0.1.1 上没有这个服务，这里恒 undefined，黄点只由行字段决定。
-      const uiSession = ctx.get('uiSession')
-      const pending = current === undefined ? false
-        : uiSession?.pendingInteractions.getSnapshot().has(current) === true
+      const status = current === undefined ? undefined
+        : ctx.get('uiSession')?.sessionStatus.getSnapshot().get(current)
+      const pending = status?.pendingInteraction !== undefined && status.pendingInteraction !== null
       const state = row === undefined ? undefined : dotState(row, pending)
       if (state === undefined) frame.removeAttribute('data-mobile-nav-dot')
       else frame.setAttribute('data-mobile-nav-dot', state)
     }
     apply()
-    // Two sources can push the dot now (session list + the 0.1.2 pending
-    // map); probe uiSession once more right here and subscribe to whichever
-    // exist. 0.1.1 only ever has the first. Degradation note: if uiSession
-    // has not registered by this moment (this plugin ran before it), only
-    // the list subscription is attached — the dot stays correct because
-    // every later list change re-runs apply(), whose fresh probe then sees
-    // the service; a pending-only change before any list change would be
-    // missed until then.
+    // Two sources can push the dot (session list + the unified session
+    // status table); probe uiSession once more right here and subscribe to
+    // whichever exist. Degradation note: if uiSession has not registered by
+    // this moment (this plugin ran before it), only the list subscription
+    // is attached — the dot stays correct because every later list change
+    // re-runs apply(), whose fresh probe then sees the service; a
+    // pending-only change before any list change would be missed until then.
     const unsubscribes: Array<() => void> = [ctx.sessions.list.subscribe(apply)]
-    const pendingSource = ctx.get('uiSession')?.pendingInteractions
-    if (pendingSource !== undefined) unsubscribes.push(pendingSource.subscribe(apply))
+    const statusSource = ctx.get('uiSession')?.sessionStatus
+    if (statusSource !== undefined) unsubscribes.push(statusSource.subscribe(apply))
     return () => {
       for (const off of unsubscribes) off()
     }

package/src/client/effects/keyboard-guard.ts

@@ -6,6 +6,23 @@ const PHONE_QUERY = '(max-width: 767px)'
 /** The official composer slot wrapper (same marker composer.css.ts styles). */
 const COMPOSER = '[data-slot="conversation.composer.bar"]'
 
+/**
+ * T72: the model sheet's search input on DSH 0.2.0-rc.2 — a `role=searchbox`
+ * `<input>` inside the portaled model menu (composer.css.ts's MODEL_MENU
+ * body form; on rc.2 the model pane portals as `role=group` with the search
+ * row inside). The host focuses it the moment the user drills into the
+ * model pane, which pops the phone keyboard over the sheet.
+ */
+const MODEL_MENU_ROOT = 'body > [id$="-menu"]'
+const MODEL_SEARCH = `${MODEL_MENU_ROOT} [role="searchbox"]`
+/** The focus target when the search's autofocus must be retracted: the
+ * currently selected model row, the exact element the host's own arrow-key
+ * navigation focuses first (model-selection-client.js moveFocus). */
+const SELECTED_OPTION = '[role="menuitemradio"][aria-checked="true"]:not([disabled])'
+/** The host's fallback when no row is checked (filtered/empty list): the
+ * first selectable option row. */
+const ANY_OPTION = '[role="menuitemradio"]:not([disabled])'
+
 /** A tap/keystroke older than this no longer explains a focus. */
 const INTENT_WINDOW_MS = 1000
 
@@ -43,6 +60,10 @@ export function installKeyboardGuard(ctx: ClientContext): void {
     const narrow = window.matchMedia(PHONE_QUERY)
     let lastIntent = 0
     let granted = false
+    // T72: the search field's own grant — separate from the composer's,
+    // cleared when the field blurs, so a later programmatic focus (drilling
+    // back into the pane) is retracted again.
+    let searchGranted = false
     let observer: MutationObserver | null = null
     let frame = 0
 
@@ -60,6 +81,31 @@ export function installKeyboardGuard(ctx: ClientContext): void {
       return node.tagName === 'TEXTAREA' ? node : null
     }
 
+    /**
+     * T72: the model sheet's search input. Unlike the composer field this
+     * one is NOT blurred to the body — the model menu's root has an onBlur
+     * that CLOSES the menu when the focus leaves root and menu (rc.2 model-
+     * selection-client.js: `relatedTarget` outside both → `close()`), so
+     * blurring would slam the sheet shut. The focus moves INSIDE the menu
+     * instead: to the selected model row, the element the host's own
+     * keyboard navigation focuses first. Phone keyboards have no arrow keys,
+     * so the host's search-focus-follows-highlight logic losing focus costs
+     * nothing there.
+     */
+    const modelSearchField = (node: unknown): HTMLElement | null => {
+      if (!(node instanceof HTMLElement)) return null
+      if (node.getAttribute('role') !== 'searchbox') return null
+      return node.closest(MODEL_SEARCH)
+    }
+
+    /** Retract the search autofocus WITHOUT closing the menu (see above). */
+    const retractSearchFocus = (field: HTMLElement): void => {
+      const menu = field.closest(MODEL_MENU_ROOT)
+      const selected = menu?.querySelector<HTMLElement>(SELECTED_OPTION) ?? menu?.querySelector<HTMLElement>(ANY_OPTION)
+      if (selected !== null && selected !== undefined) selected.focus()
+      else field.blur()
+    }
+
     const onPointerDown = (event: PointerEvent): void => {
       // Only the textarea itself grants the keyboard. A tap on any other
       // composer control (slash-command toggle, attach, model menu, send)
@@ -69,12 +115,23 @@ export function installKeyboardGuard(ctx: ClientContext): void {
         lastIntent = Date.now()
         granted = true
       }
+      // T72: a tap ON the search field is the user asking for the keyboard
+      // — typing to filter models must work.
+      if (modelSearchField(event.target) !== null) searchGranted = true
     }
     const onKeyDown = (): void => {
       lastIntent = Date.now()
       if (composerField(document.activeElement) !== null) granted = true
     }
     const sweep = (): void => {
+      // The search field is judged on its own grant, and a retracted focus
+      // never leaves the menu (see modelSearchField — blur would close it).
+      const search = modelSearchField(document.activeElement)
+      if (search !== null) {
+        if (searchGranted) return
+        retractSearchFocus(search)
+        return
+      }
       const el = composerField(document.activeElement)
       if (el === null) return
       if (granted || Date.now() - lastIntent < INTENT_WINDOW_MS) {
@@ -84,10 +141,16 @@ export function installKeyboardGuard(ctx: ClientContext): void {
       el.blur()
     }
     const onFocusIn = (event: FocusEvent): void => {
-      if (composerField(event.target) === null) return
+      if (composerField(event.target) === null && modelSearchField(event.target) === null) return
       sweep()
     }
     const onFocusOut = (event: FocusEvent): void => {
+      // T72: the search field's grant dies with its focus — the next
+      // programmatic focus is retracted again.
+      if (modelSearchField(event.target) !== null) {
+        searchGranted = false
+        return
+      }
       if (composerField(event.target) === null) return
       granted = false
     }
@@ -122,6 +185,7 @@ export function installKeyboardGuard(ctx: ClientContext): void {
       if (frame !== 0) window.clearTimeout(frame)
       frame = 0
       granted = false
+      searchGranted = false
     }
 
     if (narrow.matches) attach()

package/src/client/effects/model-group-side.ts

@@ -0,0 +1,132 @@
+import type { ClientContext } from '../compat/types.ts'
+import { classifyModelGroups, type ModelGroupHeading } from '../../client-data/model-group-side.ts'
+
+/**
+ * T74: stamp every model-menu group with the side of the pairing it belongs
+ * to, so remote-session.css.ts can hide the groups the open session cannot
+ * run. The stamps are `data-zr-group="remote|local"` on each
+ * `section[role="group"]`; which sections get one (and which get none) is
+ * the pure classifier's container rule (client-data/model-group-side.ts) —
+ * only a container holding at least one marked (WORD JOINER-prefixed, see
+ * virtual-id.ts) heading is decided at all, so every other menu and the
+ * whole rest of the page is never touched.
+ *
+ * Synchronous in the observer callback, never behind rAF: the callback is a
+ * microtask and runs before this frame paints, so a group that must be
+ * hidden is hidden the first time it is drawn. A rAF would land a frame late
+ * and show one frame of the groups the CSS is about to hide (AGENTS.md's
+ * "晚一帧" rule — the same shape the turn-fold and model-sheet-extras bugs
+ * shared). The cheap batch gate below keeps the full rescan off the hot
+ * path: most mutations (chat streaming, composer typing) touch no group.
+ */
+const GROUP_SELECTOR = 'section[role="group"]'
+
+/** The stamp this effect writes; remote-session.css.ts hides
+ * `[data-zr-group="local"]` in a remote session and
+ * `[data-zr-group="remote"]` everywhere else. */
+const STAMP = 'data-zr-group'
+
+/**
+ * The heading text a group section renders, across the two DSH layouts:
+ * 0.1.7 points `aria-labelledby` at a heading div (id `<useId>-<group.id>`);
+ * 0.2.0's MenuGroup points it at its own useId heading — which is also the
+ * first `[data-menu-group-heading]` child — and its first child is an
+ * id-less position sentinel span. Falls through in that order, then to the
+ * first id-bearing child (0.1.7's heading, should `aria-labelledby` ever be
+ * dropped), and gives up with `null`.
+ */
+export function headingTextOf(section: Element, getElementById: (id: string) => Element | null): string | null {
+  const labelledby = section.getAttribute('aria-labelledby')
+  if (labelledby !== null) {
+    const heading = getElementById(labelledby)
+    if (heading !== null) return heading.textContent
+  }
+  const own = section.querySelector(':scope > [data-menu-group-heading]')
+  if (own !== null) return own.textContent
+  for (const child of section.children) {
+    if (child.id !== '') return child.textContent
+  }
+  return null
+}
+
+/** Does this mutation involve a group section, inside or as a node? Groups
+ * are rare; everything else (streaming text, composer typing) bails here. */
+function touchesGroup(mutation: MutationRecord): boolean {
+  if (mutation.type === 'childList') {
+    for (const node of mutation.addedNodes) if (isGroupish(node)) return true
+    for (const node of mutation.removedNodes) if (isGroupish(node)) return true
+  }
+  const target = mutation.target
+  const el = target.nodeType === 1 ? (target as Element) : target.parentElement
+  return el !== null && el.closest(GROUP_SELECTOR) !== null
+}
+
+function isGroupish(node: Node): boolean {
+  if (node.nodeType !== 1) return false
+  const el = node as Element
+  return el.matches(GROUP_SELECTOR) || el.querySelector(GROUP_SELECTOR) !== null
+}
+
+export function installModelGroupSide(ctx: ClientContext): void {
+  ctx.effect(() => {
+    const applyVerdict = (section: Element, verdict: 'remote' | 'local' | undefined): void => {
+      // Write only on change — the observer does not watch attributes (so a
+      // stamp cannot re-trigger it), but a removed section's container may
+      // be re-decided, and an unconditional set would still churn
+      // style/attribute machinery for no effect.
+      if (verdict === undefined) {
+        if (section.hasAttribute(STAMP)) section.removeAttribute(STAMP)
+      } else if (section.getAttribute(STAMP) !== verdict) {
+        section.setAttribute(STAMP, verdict)
+      }
+    }
+
+    const scan = (): void => {
+      const sections = document.querySelectorAll(GROUP_SELECTOR)
+      // Group by parent element, in document order: querySelectorAll walks
+      // the document, and one parent's children form a contiguous run of it,
+      // so a running number per distinct parent is a stable container key.
+      const containerKeys = new Map<Element, number>()
+      const rows: Array<ModelGroupHeading & { section: Element }> = []
+      for (const section of sections) {
+        const parent = section.parentElement
+        if (parent === null) continue
+        let key = containerKeys.get(parent)
+        if (key === undefined) {
+          key = containerKeys.size
+          containerKeys.set(parent, key)
+        }
+        const text = headingTextOf(section, (id) => document.getElementById(id))
+        rows.push({ section, containerKey: key, headingText: text ?? '' })
+      }
+      const verdicts = classifyModelGroups(rows)
+      rows.forEach((row, i) => applyVerdict(row.section, verdicts[i]))
+    }
+
+    // childList + subtree catches mounted/unmounted/re-parented groups,
+    // characterData catches heading texts changing in place. Attributes are
+    // deliberately unwatched: this effect is their only writer.
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (touchesGroup(mutation)) {
+          scan()
+          return
+        }
+      }
+    })
+    observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+    // The initial paint may already hold groups (session restored under an
+    // open menu): stamp them synchronously at install, like every observer
+    // effect here does.
+    scan()
+
+    return () => {
+      observer.disconnect()
+      // Undo every stamp so the host DOM reads exactly as before the effect
+      // ran — the CSS rules key on the stamp, so this un-hides everything.
+      for (const section of document.querySelectorAll(`${GROUP_SELECTOR}[${STAMP}]`)) {
+        section.removeAttribute(STAMP)
+      }
+    }
+  }, 'dsh-zen-remote: model group side')
+}

package/src/client/effects/permission-sheet.ts

@@ -0,0 +1,149 @@
+import type { ClientContext } from '../compat/types.ts'
+
+/** Phone breakpoint — the same query every phone-only effect in this plugin uses. */
+const PHONE_QUERY = '(max-width: 767px)'
+
+/**
+ * The permission trigger, addressed the way composer.css.ts addresses the
+ * whole permission seat: a structured slot plus the build-suffix trigger
+ * class (DSH 0.2.0 keeps both). The trigger carries NO aria-expanded and
+ * NO aria-controls on 0.2.0 (the Menu primitive portals its list to body
+ * and links nothing back), so the click is the only open signal there is.
+ */
+const TRIGGER_SELECTOR = '[data-slot="conversation.input.permission"] button[class$="_trigger"]'
+
+/**
+ * What the Menu primitive portals on 0.2.0: a `role=menu` div DIRECTLY under
+ * body, carrying `data-menu-material` and a randomized `--dsh-menu-anchor`
+ * (a per-instance useId) but NO id and no back-reference from the trigger —
+ * there is no pure-CSS way to pick OUR menu out of the portal crowd: the
+ * host has MANY `portal: true` Menus (agent-preset, chat preference rows,
+ * the Enter-behavior row, the workspace sidebar's 「…」, open-in-app,
+ * deliverables, the copy button's confirm, …), and none of them may become
+ * a bottom sheet. That is why this effect exists: a click on the permission
+ * trigger arms a short window and the next body-level menu to land is OURS
+ * to mark — while a marked menu still on the page (the close click) keeps
+ * the window shut.
+ */
+const PORTAL_MENU_SELECTOR = 'body > div[role="menu"]'
+
+/** The marker composer.css.ts section 4 styles into the bottom sheet. */
+const SHEET_MARKER = 'data-zen-sheet'
+const SHEET_VALUE = 'perm'
+
+/** The DOM face the two pure decisions below read — structural, so the
+ * tests drive them with plain objects instead of a DOM. */
+export interface PermissionSheetCandidate {
+  matches(selectors: string): boolean
+  getAttribute(name: string): string | null
+  /** A truthy `closest` result means the click started in the seat. */
+  closest(selectors: string): unknown
+}
+
+/**
+ * Whether ONE body-level node is a portal menu that does not yet carry the
+ * sheet marker. Pure over the node's own methods: `matches` answers the
+ * body-level role=menu shape, `getAttribute` the marker.
+ */
+export function isUnmarkedPortalMenu(node: PermissionSheetCandidate): boolean {
+  return node.matches(PORTAL_MENU_SELECTOR) && node.getAttribute(SHEET_MARKER) === null
+}
+
+/**
+ * Whether one click event's target arms the marking window: the phone shell
+ * only, and only a click that started inside the permission seat's trigger.
+ * Any other button — the sidebar's 「…」, a copy button — never arms, so
+ * the menus they open are never marked.
+ */
+export function clickArmsPermissionSheet(target: PermissionSheetCandidate | null | undefined, phoneMatches: boolean): boolean {
+  if (!phoneMatches) return false
+  const seat = target?.closest(TRIGGER_SELECTOR)
+  return seat !== undefined && seat !== null
+}
+
+/**
+ * How long an OPEN click stays armed. The portal lands in the same React
+ * commit as the state flip, so milliseconds of real latency; the window is
+ * consumed by the menu that opens with it, or expires on its own — the
+ * close path never arms at all (the marked menu is still on the page, see
+ * the guard in onCaptureClick), so the ceiling's only job is retiring a
+ * window whose menu never came.
+ */
+const ARM_MS = 1_500
+
+/**
+ * T70: turn the portaled permission menu into the bottom sheet composer.css
+ * section 4 promises, on DSH 0.2.0. Up to 0.1.7 the permission menu rendered
+ * inside the permission seat and the stylesheet's descendant selectors
+ * reached it; 0.2.0 portals it to body (`portal: true` on the Menu), the
+ * selectors stopped matching, and the phone got a tiny floating popup. The
+ * host offers no stable attribute to key the portal off — the anchor is a
+ * per-instance useId, there is no id and no aria-controls — so this effect
+ * marks it: the trigger's click arms a window, the observer stamps the next
+ * body-level menu with `data-zen-sheet="perm"`, and the stylesheet (which
+ * only the phone shell loads) turns THAT into the sheet. The portal menu
+ * unmounts on close, so the marker's lifetime is exactly the menu's; the
+ * 0.1.7 inline structure keeps working through the untouched descendant
+ * selectors, and the desktop shell never loads this stylesheet at all.
+ */
+export function installPermissionSheet(ctx: ClientContext): void {
+  ctx.effect(() => {
+    const phone = window.matchMedia(PHONE_QUERY)
+    let armed = false
+    let armTimer: ReturnType<typeof setTimeout> | undefined
+
+    const disarm = (): void => {
+      armed = false
+      if (armTimer !== undefined) {
+        clearTimeout(armTimer)
+        armTimer = undefined
+      }
+    }
+
+    const onCaptureClick = (event: Event): void => {
+      const target = event.target instanceof Element ? event.target : null
+      if (!clickArmsPermissionSheet(target, phone.matches)) return
+      // T70-fix: the trigger TOGGLES. A click that CLOSES the menu lands
+      // while the marked menu is still in the DOM (capture runs before the
+      // host's own handler unmounts it) — arming there would leave a live
+      // 1.5 s window with no menu coming to consume it, and any unrelated
+      // body-level menu opening inside that window would be mis-marked as
+      // ours. A marked menu present at click time means this click can only
+      // be the close (or a no-op re-open), never an opening we must catch.
+      if (document.querySelector(`${PORTAL_MENU_SELECTOR}[${SHEET_MARKER}="${SHEET_VALUE}"]`) !== null) return
+      armed = true
+      if (armTimer !== undefined) clearTimeout(armTimer)
+      armTimer = setTimeout(disarm, ARM_MS)
+    }
+
+    /** Mark it if this tick is armed; one menu consumes the arm. */
+    const markIfArmed = (root: Element): void => {
+      if (!armed) return
+      disarm()
+      root.setAttribute(SHEET_MARKER, SHEET_VALUE)
+    }
+
+    // Capture phase: the host's own handlers may stop the click's bubble
+    // (the trigger toggles `open` itself), so listen on the document in
+    // capture and never depend on propagation reaching us.
+    document.addEventListener('click', onCaptureClick, true)
+    const observer = new MutationObserver((records) => {
+      if (!armed) return
+      for (const record of records) {
+        for (const node of record.addedNodes) {
+          if (node instanceof Element && isUnmarkedPortalMenu(node)) markIfArmed(node)
+        }
+      }
+    })
+    observer.observe(document.body, { childList: true })
+
+    return () => {
+      document.removeEventListener('click', onCaptureClick, true)
+      observer.disconnect()
+      disarm()
+      // A still-open marked menu outliving this effect keeps its marker only
+      // until the user closes it (the element unmounts); scrubbing here
+      // would fight a React commit mid-flight for no visual gain.
+    }
+  }, 'dsh-mobile-nav: permission sheet marker')
+}