@hadoku/task-ui-components 0.0.0-stage → 4.20.3

package/src/lib/selectMenus.ts

@@ -0,0 +1,303 @@
+/**
+ * The themed list for every native <select> on a page, with no change to the
+ * markup.
+ *
+ *   import { installSelectMenus } from '@wolffm/task-ui-components/select-menus'
+ *   import '@wolffm/task-ui-components/select.css'
+ *   installSelectMenus()
+ *
+ * hadoku_site calls this once from its shell, which covers every
+ * micro-frontend; an app does not call it itself. Framework-free and
+ * React-free, like installTitleTooltips, for the same reason.
+ *
+ * A native select's closed box takes CSS, but its open list is drawn by the
+ * OS and takes almost none. So a mouse press or an opening key on the select
+ * is intercepted (preventDefault on mousedown is what stops the OS list) and
+ * the same list <Select> renders opens instead, built from the select's own
+ * <option>s and <optgroup>s at that moment.
+ *
+ * The <select> stays the source of truth. Choosing sets its selectedIndex and
+ * fires `input` and `change` exactly as the OS list would, so every framework
+ * (React's onChange included) and every plain listener sees an ordinary
+ * change, and a form still submits the select's value.
+ *
+ * Left native on purpose:
+ *   - touch: a phone's own picker is the better control there
+ *   - `multiple` or `size > 1`, which render as an inline list, not a popup
+ *   - anything under `data-native-select`
+ */
+
+import { themeScopeOf } from './themeScope'
+import { placeMenu } from './menuPlacement'
+
+const TYPEAHEAD_RESET_MS = 600
+const LIST_ID = 'hdk-select-menu'
+// `check` from the @wolffm/themes registry (Lucide circle-check), inlined so
+// this entry does not pull the whole registry into the shell.
+const CHECK_SVG =
+  '<svg class="hdk-icon hdk-select__check" width="1em" height="1em" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="10" /><path d="m9 12 2 2 4-4" /></svg>'
+
+const OPEN_KEYS = new Set(['ArrowDown', 'ArrowUp', ' ', 'F4'])
+
+let uninstallCurrent: (() => void) | null = null
+
+function eligible(el: Element | null): el is HTMLSelectElement {
+  return (
+    el instanceof HTMLSelectElement &&
+    !el.multiple &&
+    el.size <= 1 &&
+    !el.disabled &&
+    !el.closest('[data-native-select]')
+  )
+}
+
+export function installSelectMenus(): () => void {
+  if (uninstallCurrent) return uninstallCurrent
+
+  let lastPointer = 'mouse'
+  let select: HTMLSelectElement | null = null
+  let list: HTMLUListElement | null = null
+  let options: HTMLOptionElement[] = []
+  let items: HTMLLIElement[] = []
+  let active = -1
+  const typeahead = { text: '', at: 0 }
+
+  function setActive(i: number) {
+    if (items[active]) items[active].classList.remove('hdk-select__option--active')
+    active = i
+    const item = items[i]
+    if (!item || !list) return
+    item.classList.add('hdk-select__option--active')
+    list.setAttribute('aria-activedescendant', item.id)
+    item.scrollIntoView({ block: 'nearest' })
+  }
+
+  function step(from: number, dir: 1 | -1) {
+    for (let i = 1; i <= options.length; i++) {
+      const next = (from + dir * i + options.length) % options.length
+      if (!isOff(next)) return next
+    }
+    return from
+  }
+
+  const edge = (dir: 1 | -1) => step(dir === 1 ? -1 : options.length, dir)
+
+  function matchTypeahead(key: string) {
+    const now = Date.now()
+    typeahead.text = now - typeahead.at > TYPEAHEAD_RESET_MS ? key : typeahead.text + key
+    typeahead.at = now
+    const needle = typeahead.text.toLowerCase()
+    const start = Math.max(active, 0)
+    for (let i = 0; i < options.length; i++) {
+      // A single repeated key cycles; a longer prefix stays on the current match.
+      const idx = (start + (typeahead.text.length === 1 ? i + 1 : i)) % options.length
+      const o = options[idx]
+      if (!isOff(idx) && labelOf(o).toLowerCase().startsWith(needle)) return idx
+    }
+    return -1
+  }
+
+  const labelOf = (o: HTMLOptionElement) => o.label || o.text
+  // A disabled <optgroup> disables its options too.
+  const isOff = (i: number) =>
+    options[i].disabled ||
+    (options[i].parentElement as HTMLOptGroupElement | null)?.disabled === true
+
+  function place() {
+    if (!select || !list) return
+    if (!select.isConnected) {
+      close(false)
+      return
+    }
+    const p = placeMenu(select.getBoundingClientRect(), list.scrollHeight)
+    list.style.left = `${p.left}px`
+    list.style.minWidth = `${p.width}px`
+    list.style.top = p.top === undefined ? '' : `${p.top}px`
+    list.style.bottom = p.bottom === undefined ? '' : `${p.bottom}px`
+    list.style.maxHeight = `${p.maxHeight}px`
+    list.style.visibility = ''
+  }
+
+  function open(el: HTMLSelectElement, start?: 'last') {
+    close(false)
+    const scope = themeScopeOf(el)
+    if (!scope) return
+    select = el
+    options = Array.from(el.options).filter(o => !o.hidden)
+    if (options.length === 0) return
+
+    list = document.createElement('ul')
+    list.id = LIST_ID
+    list.setAttribute('role', 'listbox')
+    list.tabIndex = -1
+    list.className = 'hdk-select__menu hdk-scroll hdk-scroll--thin'
+    const name = el.getAttribute('aria-label') ?? el.labels?.[0]?.textContent?.trim()
+    if (name) list.setAttribute('aria-label', name)
+    // The list is portalled, so it cannot inherit the select's type size.
+    const cs = getComputedStyle(el)
+    list.style.fontSize = cs.fontSize
+    list.style.fontFamily = cs.fontFamily
+    list.style.visibility = 'hidden'
+
+    let group: HTMLOptGroupElement | null = null
+    items = options.map((o, i) => {
+      const g = o.parentElement instanceof HTMLOptGroupElement ? o.parentElement : null
+      if (g && g !== group) {
+        const head = document.createElement('li')
+        head.setAttribute('role', 'presentation')
+        head.className = 'hdk-select__group'
+        head.textContent = g.label
+        list?.append(head)
+      }
+      group = g
+      const item = document.createElement('li')
+      item.id = `${LIST_ID}-${i}`
+      item.setAttribute('role', 'option')
+      const selected = o.index === el.selectedIndex
+      item.setAttribute('aria-selected', String(selected))
+      if (o.disabled || g?.disabled) item.setAttribute('aria-disabled', 'true')
+      item.className = `hdk-select__option${selected ? ' hdk-select__option--selected' : ''}`
+      const text = document.createElement('span')
+      text.className = 'hdk-select__option-label'
+      text.textContent = labelOf(o)
+      const wrap = document.createElement('span')
+      wrap.className = 'hdk-select__option-text'
+      wrap.append(text)
+      item.append(wrap)
+      if (selected) item.insertAdjacentHTML('beforeend', CHECK_SVG)
+      item.addEventListener('pointermove', () => {
+        if (!isOff(i) && i !== active) setActive(i)
+      })
+      item.addEventListener('click', () => choose(i))
+      list?.append(item)
+      return item
+    })
+    list.addEventListener('keydown', onListKeyDown)
+    scope.appendChild(list)
+    el.setAttribute('aria-expanded', 'true')
+    el.setAttribute('aria-controls', LIST_ID)
+
+    const current = options.findIndex(o => o.index === el.selectedIndex)
+    setActive(start === 'last' ? edge(-1) : current >= 0 && !isOff(current) ? current : edge(1))
+    place()
+    list.focus({ preventScroll: true })
+    window.addEventListener('scroll', onScroll, true)
+    window.addEventListener('resize', place)
+  }
+
+  function close(refocus: boolean) {
+    window.removeEventListener('scroll', onScroll, true)
+    window.removeEventListener('resize', place)
+    list?.remove()
+    list = null
+    if (!select) return
+    select.removeAttribute('aria-expanded')
+    select.removeAttribute('aria-controls')
+    if (refocus) select.focus({ preventScroll: true })
+    select = null
+    items = []
+    options = []
+    active = -1
+  }
+
+  function choose(i: number) {
+    const el = select
+    const o = options[i]
+    if (!el || !o || isOff(i)) return
+    const changed = o.index !== el.selectedIndex
+    close(true)
+    if (!changed) return
+    el.selectedIndex = o.index
+    el.dispatchEvent(new Event('input', { bubbles: true }))
+    el.dispatchEvent(new Event('change', { bubbles: true }))
+  }
+
+  // Scrolling the list itself must not re-place (or close) it.
+  const onScroll = (e: Event) => {
+    if (list && e.target instanceof Node && list.contains(e.target)) return
+    place()
+  }
+
+  function onListKeyDown(e: KeyboardEvent) {
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault()
+        setActive(step(active, 1))
+        break
+      case 'ArrowUp':
+        e.preventDefault()
+        setActive(step(active, -1))
+        break
+      case 'Home':
+      case 'PageUp':
+        e.preventDefault()
+        setActive(edge(1))
+        break
+      case 'End':
+      case 'PageDown':
+        e.preventDefault()
+        setActive(edge(-1))
+        break
+      case 'Enter':
+      case ' ':
+        e.preventDefault()
+        choose(active)
+        break
+      case 'Escape':
+        // Stop here so an enclosing modal does not close along with the list.
+        e.preventDefault()
+        e.stopPropagation()
+        close(true)
+        break
+      case 'Tab':
+        close(true)
+        break
+      default:
+        if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+          const idx = matchTypeahead(e.key)
+          if (idx >= 0) setActive(idx)
+        }
+    }
+  }
+
+  const onPointerDown = (e: PointerEvent) => {
+    lastPointer = e.pointerType
+    const target = e.target as Node
+    if (list && !list.contains(target) && target !== select) close(false)
+  }
+
+  const onMouseDown = (e: MouseEvent) => {
+    if (e.button !== 0 || lastPointer === 'touch') return
+    const el = (e.target as Element | null)?.closest?.('select') ?? null
+    if (!eligible(el)) return
+    // This is what keeps the OS list from opening.
+    e.preventDefault()
+    if (select === el) {
+      close(true)
+      return
+    }
+    el.focus({ preventScroll: true })
+    open(el)
+  }
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    const el = e.target as Element | null
+    if (!eligible(el) || select === el) return
+    if (!OPEN_KEYS.has(e.key) || e.ctrlKey || e.metaKey) return
+    e.preventDefault()
+    open(el, e.key === 'ArrowUp' && !e.altKey ? 'last' : undefined)
+  }
+
+  document.addEventListener('pointerdown', onPointerDown, true)
+  document.addEventListener('mousedown', onMouseDown, true)
+  document.addEventListener('keydown', onKeyDown, true)
+
+  uninstallCurrent = () => {
+    close(false)
+    document.removeEventListener('pointerdown', onPointerDown, true)
+    document.removeEventListener('mousedown', onMouseDown, true)
+    document.removeEventListener('keydown', onKeyDown, true)
+    uninstallCurrent = null
+  }
+  return uninstallCurrent
+}

package/src/lib/settingsClient.ts

@@ -0,0 +1,377 @@
+/**
+ * Client for the unified user-settings modal (ConnectedSettings).
+ *
+ * Two concerns, both cookie-authed against the hadoku.me edge-router, which
+ * resolves the `hadoku_session` cookie / `X-Session-Id` header → X-User-Key +
+ * X-User-Id for the backend:
+ *   - display name  → POST /session/name                   (edge-router, self rename)
+ *   - content level → GET/PUT /prefs/api/v1/content-level  (prefs-api)
+ *
+ * Switching keys goes through the SITE's sign-in client, never a call of ours:
+ * see `loadSignIn()`, with `switchKeyHref()` as the fallback.
+ *
+ * These are same-origin relative paths, so ConnectedSettings is portable to any
+ * app served under hadoku.me with zero wiring. Off-origin (e.g. a Storybook or
+ * a non-hadoku host) every call resolves to null and the UI degrades to a
+ * read-only shell — it never throws.
+ *
+ * The raw key is never held in the browser (the auth page deliberately drops
+ * it), so name + content-level changes go through session identity, not a key
+ * header, and no app ever asks for a key at all.
+ *
+ * WHEN THESE RUN
+ * --------------
+ * Everything the popout displays is resolved at PAGE LOAD, not on gear-click —
+ * see `prefetchSettings()`. Opening settings must cost zero requests. Pinned by
+ * `e2e/settings-prefetch.spec.ts` in hadoku-task.
+ */
+
+/** Edge-router / prefs-api endpoints (same-origin relative). */
+const CONTENT_LEVEL_PATH = '/prefs/api/v1/content-level'
+const SESSION_NAME = '/session/name'
+const SESSION_WHOAMI = '/session/whoami'
+
+/**
+ * The ecosystem's shared boot-whoami promise. hadoku_site's `mf-loader.js`
+ * kicks `GET /session/whoami` in parallel with the micro-frontend's module
+ * import and parks the promise here precisely so the app it loads doesn't
+ * resolve identity a second time; @wolffm/prefs-client already consumes it
+ * under the same name. Reading it is what makes settings' identity free.
+ *
+ * Absent outside that shell (standalone vite, Capacitor, Storybook) — there we
+ * fetch, and publish the result under the same key so the next reader is free
+ * too.
+ */
+const WHOAMI_GLOBAL = '__hadokuWhoami'
+
+/**
+ * Raw whoami body, as both mf-loader and this module see it off the wire.
+ *
+ * `contentLevel` / `maxContentLevel` are OPTIONAL because the shape is
+ * versioned by whatever edge-router is deployed, not by this bundle. They
+ * arrive from edge-router ≥ the 2026-08-07 change, which reports the level
+ * `authGate` had already resolved to stamp X-Hadoku-Content-Level. When they
+ * are absent we fall back to the standalone GET — see resolveSettings.
+ */
+interface WhoamiBody {
+  valid?: boolean
+  userType?: Tier
+  name?: string | null
+  contentLevel?: number
+  maxContentLevel?: number
+}
+
+// Hard timeout on every settings request. Without it, a request throttled by
+// the browser (e.g. the tab going to the background) leaves the caller's
+// "saving" flag stuck true — which disabled the content-level pills until the
+// tab regained focus. AbortSignal.timeout guarantees the promise settles.
+const REQUEST_TIMEOUT_MS = 8000
+
+/** Session-id header the same way whoami() sends it (cookie is the fallback). */
+function sessionHeaders(extra?: Record<string, string>): Record<string, string> {
+  const headers: Record<string, string> = { 'Content-Type': 'application/json', ...extra }
+  const sid = typeof window !== 'undefined' ? localStorage.getItem('hadoku_session_id') : null
+  if (sid) headers['X-Session-Id'] = sid
+  return headers
+}
+
+export interface ContentLevelState {
+  /** Current global content-visibility level (1 = safest default). */
+  level: number
+  /** Highest level this caller's tier may select (friend=3, admin=4). */
+  maxLevel: number
+}
+
+/** GET the caller's current content level + tier ceiling. null on error. */
+export async function getContentLevel(): Promise<ContentLevelState | null> {
+  try {
+    const res = await fetch(CONTENT_LEVEL_PATH, {
+      credentials: 'same-origin',
+      headers: sessionHeaders(),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    })
+    if (!res.ok) return null
+    return (await res.json()) as ContentLevelState
+  } catch {
+    return null
+  }
+}
+
+/** PUT a new content level. Server clamps to the tier ceiling → 400 if out of
+ *  range. Returns the stored state on success, null on any failure. */
+export async function setContentLevel(level: number): Promise<ContentLevelState | null> {
+  try {
+    const res = await fetch(CONTENT_LEVEL_PATH, {
+      method: 'PUT',
+      credentials: 'same-origin',
+      headers: sessionHeaders(),
+      body: JSON.stringify({ level }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    })
+    if (!res.ok) return null
+    const stored = (await res.json()) as ContentLevelState
+    patchSnapshot(prev => ({ ...prev, content: stored }))
+    return stored
+  } catch {
+    return null
+  }
+}
+
+/** POST a new display name for the signed-in user. Returns the stored name
+ *  (may differ from the request for wp-* protected keys) or null on failure. */
+export async function setDisplayName(name: string): Promise<string | null> {
+  try {
+    const res = await fetch(SESSION_NAME, {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: sessionHeaders(),
+      body: JSON.stringify({ name }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    })
+    if (!res.ok) return null
+    const body = (await res.json()) as { ok: boolean; name: string | null }
+    patchSnapshot(prev => ({ ...prev, identity: { ...prev.identity, name: body.name } }))
+    return body.name
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The hadoku tier ladder, LOW to HIGH: `public < friend < service < wife < admin`.
+ * Mirrors TIER_RANK in @wolffm/worker-utils, which this browser bundle cannot
+ * import (it would pull hono into the client). A tier missing here does not
+ * error — it fails the union and, worse, drops out of every `Record<Tier, …>`
+ * lookup, so the caller renders as if unrecognised. Keep it complete.
+ */
+export type Tier = 'public' | 'friend' | 'service' | 'wife' | 'admin'
+
+export interface Identity {
+  userType: Tier
+  name: string | null
+}
+
+/**
+ * The page's one whoami body, resolved at most once no matter how many callers.
+ *
+ * Under the hadoku.me shell this costs NO request: mf-loader kicks whoami in
+ * parallel with the micro-frontend's module import and parks the promise on
+ * WHOAMI_GLOBAL for exactly this reason (@wolffm/prefs-client reads the same
+ * key). Elsewhere — standalone vite, Capacitor, Storybook — we fetch once and
+ * publish under the same key so the next reader is free too.
+ *
+ * Resolves to null rather than throwing on any failure.
+ */
+function sharedWhoami(): Promise<WhoamiBody | null> {
+  const g = globalThis as { [WHOAMI_GLOBAL]?: Promise<WhoamiBody | null> }
+  g[WHOAMI_GLOBAL] ??= fetch(SESSION_WHOAMI, {
+    credentials: 'same-origin',
+    headers: sessionHeaders(),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  })
+    .then(res => (res.ok ? (res.json() as Promise<WhoamiBody>) : null))
+    .catch(() => null)
+  return g[WHOAMI_GLOBAL]
+}
+
+/**
+ * Resolve the signed-in caller's tier + display name from the edge-router.
+ * Returns { userType: 'public', name: null } for anonymous / off-origin / any
+ * failure — never throws, so ConnectedSettings can render unconditionally.
+ */
+export async function whoami(): Promise<Identity> {
+  if (typeof window === 'undefined') return { userType: 'public', name: null }
+  try {
+    const body = await sharedWhoami()
+    if (!body?.valid) return { userType: 'public', name: null }
+    return { userType: body.userType ?? 'public', name: body.name ?? null }
+  } catch {
+    return { userType: 'public', name: null }
+  }
+}
+
+/**
+ * Where a "Switch key" control sends the user when the inline sign-in client
+ * (`loadSignIn()`) can't be loaded: the site's sign-in page, which brings them
+ * back here afterwards.
+ *
+ * A browser session is created ONLY by /auth (hadoku_site, 2026-10-25): every
+ * render of that page carries an edge-signed funnel token and the device
+ * fingerprint, and /session/create alerts on — and will refuse — a sign-in
+ * without them. So an app never posts a key itself.
+ *
+ * `switch=1` stops /auth from sending an already signed-in visitor straight
+ * back, which would make switching impossible. `return` is this page's path,
+ * query and hash; /auth redirects there with the new session cookie, and the
+ * shell's mf-loader resyncs the localStorage mirror (hadoku_session_id /
+ * hadoku_user_type) from /session/whoami on that load, so nothing here writes it.
+ */
+export function switchKeyHref(): string {
+  return (
+    '/auth?switch=1&return=' +
+    encodeURIComponent(window.location.pathname + window.location.search + window.location.hash)
+  )
+}
+
+/** What the site's sign-in client resolves to on success. */
+export interface SignInResult {
+  valid: boolean
+  userType?: string
+  sessionId?: string
+}
+
+/** `signIn` from hadoku.me's `/auth/sign-in.js`. Resolves on success; throws an
+ *  `Error` carrying the server's message on a refused or empty key. */
+export type SignIn = (key: string) => Promise<SignInResult>
+
+/**
+ * The site serves its sign-in page's own client as a module, so an app can sign
+ * in INLINE on the same code path as /auth: a fresh funnel token per call, the
+ * device fingerprint, and the `/session/create` post that sets the cookie (and
+ * writes the hadoku_session_id / hadoku_user_type mirror). This package never
+ * posts /session/create itself — a direct post would skip the fingerprint and
+ * read as off-funnel — and it does not vendor a copy.
+ *
+ * The specifier is a VARIABLE on purpose. A literal `import('/auth/sign-in.js')`
+ * would have every bundler that re-bundles this package (hadoku_site's build
+ * among them) try to resolve the path at build time; this one is only ever
+ * resolved by the browser, against whatever origin the page is on. For the
+ * same reason it is typed here (`SignIn`) rather than by an ambient module
+ * declaration, which only a literal specifier would pick up.
+ *
+ * The module starts collecting the fingerprint as soon as it evaluates, so call
+ * this when a sign-in form OPENS, not when it submits. Memoised; resolves to
+ * null when the module can't be loaded (a dev server that isn't hadoku.me),
+ * which is the caller's cue to fall back to `switchKeyHref()`.
+ */
+const SIGN_IN_MODULE = '/auth/sign-in.js'
+let signInModule: Promise<SignIn | null> | null = null
+
+export function loadSignIn(): Promise<SignIn | null> {
+  signInModule ??= import(/* @vite-ignore */ SIGN_IN_MODULE).then(
+    (m: { signIn?: unknown }) => (typeof m.signIn === 'function' ? (m.signIn as SignIn) : null),
+    () => {
+      // Let a later open retry: a failed fetch is not cached by the browser.
+      signInModule = null
+      return null
+    }
+  )
+  return signInModule
+}
+
+/* ------------------------------------------------------------------ *
+ * Prefetch
+ * ------------------------------------------------------------------ */
+
+/** Everything the settings popout displays, resolved together. */
+export interface SettingsSnapshot {
+  identity: Identity
+  /** null = public caller (no pill) or the request failed. */
+  content: ContentLevelState | null
+}
+
+/** Identity the host already knows, so we don't ask the server for it again. */
+export interface SettingsPrefetchHints {
+  /** Caller's tier. When supplied, whoami is skipped entirely. */
+  userType?: Tier
+  /** Caller's display name. Only meaningful alongside `userType`. */
+  name?: string | null
+}
+
+let snapshot: Promise<SettingsSnapshot> | null = null
+
+/**
+ * Resolve — once per page load — everything the settings popout shows.
+ *
+ * This is THE entry point, and it is called from ConnectedSettings' MOUNT, not
+ * from its open handler. Settings data is user identity: it is known at boot,
+ * it doesn't change while the page is up, and making the gear the trigger left
+ * the panel on screen but blank for a round trip (measured on prod: whoami
+ * 167ms and content-level 186ms, issued concurrently). It now rides along with
+ * the app's own boot traffic and the click costs nothing.
+ *
+ * Idempotent and shared: every caller after the first gets the same promise, so
+ * N mounted consumers still produce at most one whoami for the whole page.
+ * Mutations below write through to it rather than invalidating, so a remount
+ * never shows a value the user just changed.
+ *
+ * Against a current edge-router this issues NO requests of its own at all — the
+ * level rides on the whoami the shell already had in flight. See
+ * resolveSettings for the fallback when it doesn't.
+ */
+export function prefetchSettings(hints: SettingsPrefetchHints = {}): Promise<SettingsSnapshot> {
+  snapshot ??= resolveSettings(hints)
+  return snapshot
+}
+
+async function resolveSettings(hints: SettingsPrefetchHints): Promise<SettingsSnapshot> {
+  // The whoami body, not just the adapted identity — edge-router carries the
+  // content level on it (see below), and reading the raw body is how we get at
+  // it without a second request.
+  //
+  // Skipped entirely when the host supplied identity: that prop exists for apps
+  // that CANNOT reach /session/whoami (conjure sits behind a path-prefixed shim
+  // where it 404s), so asking anyway would spend a request to learn nothing.
+  const selfResolving = hints.userType === undefined && typeof window !== 'undefined'
+  const bodyPromise = selfResolving ? sharedWhoami() : Promise.resolve(null)
+
+  const identityPromise: Promise<Identity> =
+    hints.userType !== undefined
+      ? Promise.resolve({ userType: hints.userType, name: hints.name ?? null })
+      : whoami()
+
+  // PREFERRED PATH: take the level straight off whoami.
+  //
+  // edge-router's authGate has already resolved it (registry key → userId →
+  // prefs D1) to stamp X-Hadoku-Content-Level, so reporting it on whoami costs
+  // it nothing — and it saves us a proxied round trip to prefs-api that
+  // measured 132-420ms against prod. Better still, whoami is in flight before
+  // this bundle has even loaded, so the value is here the moment we ask.
+  //
+  // FALLBACK: the standalone GET, for any edge-router older than the
+  // 2026-08-07 change, and for callers not behind it at all (Capacitor,
+  // Storybook, a non-hadoku host). Gated on identity because the pill is
+  // hidden for public callers — fetching an anonymous visitor's level is a
+  // guaranteed-wasted request on every page view. `hadoku_user_type` is
+  // written by the loader before anything mounts, so where it already says
+  // "signed in" the fallback goes out concurrently rather than behind whoami.
+  const contentPromise = bodyPromise.then(body => {
+    const carried = contentFromWhoami(body)
+    if (carried) return carried
+    if (looksSignedIn(hints.userType)) return getContentLevel()
+    return identityPromise.then(id => (id.userType === 'public' ? null : getContentLevel()))
+  })
+
+  const [identity, content] = await Promise.all([identityPromise, contentPromise])
+  return { identity, content }
+}
+
+/**
+ * Adapt the content level off a whoami body, or null if that edge-router
+ * doesn't report it.
+ *
+ * Both fields are required, and both must be numbers: a body carrying a level
+ * without its ceiling would render a pill with zero segments — worse than the
+ * fallback fetch, because it looks like a working control that offers nothing.
+ */
+function contentFromWhoami(body: WhoamiBody | null): ContentLevelState | null {
+  if (!body?.valid) return null
+  const { contentLevel, maxContentLevel } = body
+  if (typeof contentLevel !== 'number' || typeof maxContentLevel !== 'number') return null
+  if (maxContentLevel < 1) return null
+  return { level: contentLevel, maxLevel: maxContentLevel }
+}
+
+/** Best-effort "is this caller signed in?" from state available synchronously. */
+function looksSignedIn(hinted?: Tier): boolean {
+  if (hinted !== undefined) return hinted !== 'public'
+  if (typeof window === 'undefined') return false
+  const cached = localStorage.getItem('hadoku_user_type')
+  return cached !== null && cached !== 'public'
+}
+
+/** Keep the prefetched snapshot in step with a successful mutation. */
+function patchSnapshot(patch: (prev: SettingsSnapshot) => SettingsSnapshot) {
+  if (!snapshot) return
+  snapshot = snapshot.then(patch)
+}