@oar-sh/oar 0.9.1 → 0.9.3

package/server/public/app/store.js

@@ -1,3 +1,4 @@
+import { resolveNearBottomThresholdPx } from './transcript-viewport-anchor.mjs';
 import { recordCliLifecycleEvent, recordRelayLifecycleEvent } from './status-store.mjs';
 import { resolveRelayDotState } from './relay-dot-state.mjs';
 import { readRepoBrowserPreferences } from './repo-browser-preferences.mjs';
@@ -73,6 +74,9 @@ export let relayOnline = false;
 // Latest cloudflared tunnel status, from /api/status on load and the
 // cloudflared_tunnel_status socket event thereafter. Null until first reported.
 export let cloudflaredTunnelState = null;
+// Latest self-update payload, from /api/status on load and the update_state
+// socket event thereafter. Null until first reported.
+export let updateState = null;
 export let activeRuntimeSessionCount = 0;
 export let runtimeSessionBindingCount = 0;
 export let conversations = {};
@@ -306,10 +310,23 @@ function cleanupStalePendingUserMessages(maxAgeMs = 15 * 60 * 1000) {
   }
 }
 
-export function trackPendingUserMessage(messageId, conversationId, text) {
+// An attachment-only send has no text to fingerprint; its attachments stand
+// in, so a screenshot send is tracked (and its bubble kept across rebuilds)
+// like any other.
+function pendingAttachmentFingerprint(attachments) {
+  const list = Array.isArray(attachments) ? attachments.filter(Boolean) : [];
+  if (!list.length) return '';
+  const firstSha = String(list[0]?.sha256 || list[0]?.uploaded?.sha256 || '').trim().toLowerCase();
+  return `attachments:${list.length}:${firstSha}`;
+}
+
+// Always records the entry — the conversation key is what scopes a kept
+// pending bubble to its own conversation — even when there is nothing to
+// fingerprint for the duplicate check.
+export function trackPendingUserMessage(messageId, conversationId, text, { attachments = [] } = {}) {
   const id = String(messageId || '').trim();
-  const fingerprint = normalizePendingMessageText(text);
-  if (!id || !fingerprint) return false;
+  if (!id) return false;
+  const fingerprint = normalizePendingMessageText(text) || pendingAttachmentFingerprint(attachments);
   cleanupStalePendingUserMessages();
   pendingUserMessageEntries.set(id, {
     conversationKey: pendingConversationKey(conversationId),
@@ -340,6 +357,15 @@ export function hasPendingUserMessageDuplicate(conversationId, text) {
   return false;
 }
 
+export function hasPendingUserMessageForConversation(conversationId) {
+  cleanupStalePendingUserMessages();
+  const conversationKey = pendingConversationKey(conversationId);
+  for (const entry of pendingUserMessageEntries.values()) {
+    if (entry?.conversationKey === conversationKey) return true;
+  }
+  return false;
+}
+
 export function authHeaders() {
   return TOKEN ? { Authorization: `Bearer ${TOKEN}` } : {};
 }
@@ -585,10 +611,7 @@ function resolveMessagesNearBottomThreshold(el, thresholdPx = null) {
   if (Number.isFinite(Number(thresholdPx)) && Number(thresholdPx) >= 0) {
     return Math.trunc(Number(thresholdPx));
   }
-  const viewportHeight = Number(el?.clientHeight || 0);
-  if (!Number.isFinite(viewportHeight) || viewportHeight <= 0) return 0;
-  const relativeThreshold = Math.floor(viewportHeight * 0.08);
-  return Math.min(48, Math.max(12, relativeThreshold));
+  return resolveNearBottomThresholdPx(el?.clientHeight);
 }
 
 export function isMessagesNearBottom(thresholdPx = null) {
@@ -767,6 +790,14 @@ export function setCloudflaredTunnelState(value) {
   updateCliStatus();
 }
 
+export function setUpdateState(value) {
+  updateState = value && typeof value === 'object' ? value : null;
+}
+
+export function getUpdateState() {
+  return updateState;
+}
+
 export function setImageEditTarget(value) {
   imageEditTarget = value && typeof value === 'object'
     ? {
@@ -856,6 +887,28 @@ export function resolveConversationUiState({ conversation = null, workerState =
   return fallbackUiState || 'offline';
 }
 
+// Composer steering snapshot from the worker's heartbeat: whether a typed
+// message would steer into the live turn, and why not when it wouldn't.
+function normalizeWorkerSteering(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  return {
+    turnActive: raw.turnActive === true,
+    canSteer: raw.canSteer === true,
+    holdReason: String(raw.holdReason || '').trim() || null,
+    // The turn the snapshot describes — lets the composer drop a hold that
+    // belongs to a previous turn (the heartbeat lags ~10s).
+    messageId: String(raw.messageId || '').trim() || null,
+    // The worker's own opt-in to mid-turn steering (both SDK workers send
+    // it); the composer's only steering gate — no provider rule backs it up.
+    supported: raw.supported === true,
+    // Pushed-but-unconsumed rows the worker can still pull back out of its
+    // runtime: their bubbles keep Cancel while listed here.
+    cancellableIds: Array.isArray(raw.cancellableIds)
+      ? raw.cancellableIds.map((id) => String(id || '').trim()).filter(Boolean)
+      : [],
+  };
+}
+
 function normalizeWorkerStateEntry(worker) {
   const sdkSessionId = normalizeWorkerSessionId(worker?.sdkSessionId);
   if (!sdkSessionId) return null;
@@ -869,13 +922,17 @@ function normalizeWorkerStateEntry(worker) {
     workerId: String(worker?.workerId || '').trim() || null,
     pid: Number.isInteger(Number(worker?.pid)) ? Number(worker.pid) : null,
     updatedAt: String(worker?.updatedAt || '').trim() || null,
+    steering: normalizeWorkerSteering(worker?.steering),
   };
 }
 
 function buildSessionWorkerStateHash(map) {
   const parts = [];
   for (const [sid, state] of map.entries()) {
-    parts.push(`${sid}:${state.status}:${state.uiState || ''}:${state.derivedUiState || ''}:${state.workerId || ''}:${state.pid || ''}:${state.updatedAt || ''}`);
+    const steering = state.steering
+      ? `${state.steering.turnActive ? 1 : 0}${state.steering.canSteer ? 1 : 0}${state.steering.supported ? 1 : 0}${state.steering.holdReason || ''}:${state.steering.messageId || ''}:${state.steering.cancellableIds.join(',')}`
+      : '';
+    parts.push(`${sid}:${state.status}:${state.uiState || ''}:${state.derivedUiState || ''}:${state.workerId || ''}:${state.pid || ''}:${state.updatedAt || ''}:${steering}`);
   }
   return parts.sort().join('|');
 }
@@ -897,6 +954,26 @@ export function setSessionWorkerStatesFromStatusPayload(payload) {
   return true;
 }
 
+/**
+ * Apply one worker's steering snapshot as the relay broadcasts it
+ * (`session_worker_steering`), ahead of the next status poll. Only an entry
+ * the client already knows is patched — the snapshot alone carries none of
+ * the entry's other fields. Returns null for an unknown session (the caller
+ * refreshes the whole status instead), otherwise whether anything changed.
+ */
+export function applySessionWorkerSteering(sdkSessionId, steering) {
+  const sid = normalizeWorkerSessionId(sdkSessionId);
+  const existing = sid ? sessionWorkerStates.get(sid) : null;
+  if (!existing) return null;
+  const next = new Map(sessionWorkerStates);
+  next.set(sid, { ...existing, steering: normalizeWorkerSteering(steering) });
+  const nextHash = buildSessionWorkerStateHash(next);
+  if (nextHash === sessionWorkerStateHash) return false;
+  sessionWorkerStateHash = nextHash;
+  sessionWorkerStates = next;
+  return true;
+}
+
 export function getSessionWorkerState(sdkSessionId) {
   const sid = normalizeWorkerSessionId(sdkSessionId);
   if (!sid) return null;
@@ -1174,20 +1251,86 @@ export function setModelBanner(message) {
   el.classList.add('visible');
 }
 
-export function showTransientRelayNotice(message, ms = 4000) {
+let transientNoticeSeq = 0;
+// The action notice on screen (or covered by a plain one), so a plain notice
+// that covers it hands the toast back afterwards instead of dropping the
+// action for good.
+let activeActionNotice = null;
+
+/**
+ * `action` ({ actionLabel, onAction }) adds one button to the toast; the
+ * toast then takes pointer input and hides as soon as the button is used.
+ * A plain notice shown over an action notice hands the toast back to it when
+ * it hides, for whatever time the action notice had left.
+ */
+export function showTransientRelayNotice(message, ms = 4000, action = null) {
   const text = String(message || '').trim();
   if (!text) return;
-  setModelBanner(text);
-  setTimeout(() => {
-    const el = document.getElementById('model-banner');
-    if (!el) return;
-    if (String(el.textContent || '').trim() === text) {
-      setModelBanner('');
+  // Transient notices render in the fixed #relay-toast, not #model-banner:
+  // the banner is composer-scoped and stacks below modals, while these
+  // notices must stay readable over full-screen overlays.
+  const toast = document.getElementById('relay-toast');
+  if (!toast) {
+    setModelBanner(text);
+    setTimeout(() => {
+      const el = document.getElementById('model-banner');
+      if (el && String(el.textContent || '').trim() === text) setModelBanner('');
+    }, Math.max(1500, Number(ms) || 4000));
+    return;
+  }
+  const durationMs = Math.max(1500, Number(ms) || 4000);
+  const noticeId = String(++transientNoticeSeq);
+  const actionLabel = String(action?.actionLabel || '').trim();
+  const hasAction = !!actionLabel && typeof action?.onAction === 'function';
+  const covered = !hasAction && activeActionNotice && activeActionNotice.expiresAt > Date.now()
+    ? activeActionNotice
+    : null;
+  if (hasAction) {
+    activeActionNotice = { noticeId, message: text, action, expiresAt: Date.now() + durationMs };
+  }
+  const hide = () => {
+    if (toast.dataset.noticeId !== noticeId) return;
+    toast.textContent = '';
+    toast.classList.remove('visible', 'has-action');
+    if (hasAction) {
+      if (activeActionNotice?.noticeId === noticeId) activeActionNotice = null;
+      return;
+    }
+    if (covered && activeActionNotice === covered) {
+      const remainingMs = covered.expiresAt - Date.now();
+      if (remainingMs > 0) showTransientRelayNotice(covered.message, Math.max(4000, remainingMs), covered.action);
     }
-  }, Math.max(1500, Number(ms) || 4000));
+  };
+  toast.dataset.noticeId = noticeId;
+  toast.textContent = text;
+  if (hasAction) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'relay-toast-action';
+    button.textContent = actionLabel;
+    button.addEventListener('click', () => {
+      hide();
+      action.onAction();
+    });
+    toast.appendChild(button);
+  }
+  toast.classList.toggle('has-action', hasAction);
+  toast.classList.add('visible');
+  setTimeout(hide, durationMs);
+}
+
+// The screen's short side sizes phone-landscape text (index.html); unlike
+// the viewport, the on-screen keyboard never changes it. Refreshed here for
+// foldables, whose screen changes when they unfold.
+function syncScreenShortSide() {
+  const shortSide = Math.min(Number(window.screen?.width) || 0, Number(window.screen?.height) || 0);
+  if (!shortSide) return;
+  document.documentElement.style.setProperty('--screen-short-side', `${shortSide}px`);
+  document.documentElement.toggleAttribute('data-phone-screen', shortSide <= 500);
 }
 
 export function syncViewportMetrics() {
+  syncScreenShortSide();
   const layoutHeight = window.innerHeight || document.documentElement.clientHeight || 0;
   const layoutWidth = window.innerWidth || document.documentElement.clientWidth || 0;
   const vv = window.visualViewport;

package/server/public/app/sync-outbox.mjs

@@ -1,4 +1,5 @@
 import { BASE, CLIENT_ID, authHeaders, conversations } from './store.js';
+import { draftFlushRequestBody, getSyncedDraft, isStaleDraftFlushEntry } from './conversation-draft-sync.mjs';
 
 // Durable outbox for Background Sync: message sends, ask_user answers, and
 // draft flushes that failed (or might die mid-flight on pagehide) are queued
@@ -129,6 +130,10 @@ export async function replayOutboxFromPage() {
     db = await openOutboxDb();
     const entries = await readOutboxEntries(db);
     for (const { key, value } of entries) {
+      if (isStaleDraftFlushEntry(value)) {
+        await deleteOutboxEntry(db, key);
+        continue;
+      }
       let response = null;
       try {
         response = await fetch(`${BASE}${value.path}`, {
@@ -185,23 +190,26 @@ export async function initOutboxFallbackReplay() {
  * replay treats as final. Only queues when the draft differs from the last
  * persisted state.
  */
-export async function enqueueDraftFlushForBackgroundSync(conversationId) {
+export async function enqueueDraftFlushForBackgroundSync(conversationId, { afterPendingSend = false } = {}) {
   const id = String(conversationId || '').trim();
   if (!id) return false;
   const conversation = conversations[id];
   if (!conversation) return false;
   const input = document.getElementById('msg-input');
-  const draftText = String(input ? input.value : (conversation.draftText || ''));
-  if (draftText === String(conversation.draftText || '')) return false;
+  const body = draftFlushRequestBody({
+    inputText: input ? input.value : (conversation.draftText || ''),
+    synced: getSyncedDraft(id),
+    fallbackText: conversation.draftText,
+    fallbackUpdatedAt: conversation.draftUpdatedAt,
+    clientId: CLIENT_ID,
+    afterPendingSend,
+  });
+  if (!body) return false;
   const queued = await enqueueOutboxRequest({
     kind: 'draft-flush',
     path: `/api/conversation/${encodeURIComponent(id)}/draft`,
     method: 'PATCH',
-    body: JSON.stringify({
-      draftText,
-      clientId: CLIENT_ID,
-      baseDraftUpdatedAt: conversation.draftUpdatedAt || null,
-    }),
+    body: JSON.stringify(body),
   });
   if (queued) void registerOutboxSync();
   return queued;

package/server/public/app/tool-activity-emoji.mjs

@@ -0,0 +1,36 @@
+// Leading emoji for a tool-activity line ("Tool (PowerShell): …" → "🪓 Tool
+// (PowerShell): …"), shared by the transcript's activity rows and the
+// composer's background-tasks panel so a tool reads the same everywhere.
+// Text that already starts with an emoji is returned unchanged.
+export function prefixToolActivityEmoji(text) {
+  const value = String(text || '').trim();
+  if (!value) return '';
+  if (/^[\u{1F300}-\u{1FAFF}☀-➿]/u.test(value)) return value;
+  if (value.startsWith('● ')) return `🔄 ${value.slice(2).trim()}`;
+  if (/^Model selected:/i.test(value)) return `🧠 ${value}`;
+  if (/^Search \((glob|grep)\)/i.test(value)) return `🔍 ${value}`;
+  if (/^Tool \(ask_user\)/i.test(value)) return `❓ ${value}`;
+  if (/^Tool \(view\)/i.test(value)) return `👀 ${value}`;
+  if (/^Tool \(apply_patch\)/i.test(value)) return `🪡 ${value}`;
+  if (/^Tool \(powershell\)/i.test(value)) return `🪓 ${value}`;
+  if (/^Tool \(edit\)/i.test(value)) return `📝 ${value}`;
+  if (/^Tool \(read_file\)/i.test(value)) return `📄 ${value}`;
+  if (/^Tool \((grep_search|file_search)\)/i.test(value)) return `🔎 ${value}`;
+  if (/^Tool \(semantic_search\)/i.test(value)) return `🧭 ${value}`;
+  if (/^Tool \(vscode_listCodeUsages\)/i.test(value)) return `🔗 ${value}`;
+  if (/^Tool \(vscode_renameSymbol\)/i.test(value)) return `✏️ ${value}`;
+  if (/^Tool \(list_dir\)/i.test(value)) return `📂 ${value}`;
+  if (/^Tool \(create_directory\)/i.test(value)) return `📁 ${value}`;
+  if (/^Tool \((delete|remove)\)/i.test(value)) return `🗑️ ${value}`;
+  if (/^Tool \(execution_subagent\)/i.test(value)) return `🚀 ${value}`;
+  if (/^Tool \(get_errors\)/i.test(value)) return `🚨 ${value}`;
+  if (/^Tool \(debug_[^)]+\)/i.test(value)) return `🐞 ${value}`;
+  if (/^Tool \(fetch_webpage\)/i.test(value)) return `🌐 ${value}`;
+  if (/^Tool \(github_[^)]+\)/i.test(value)) return `🐙 ${value}`;
+  if (/^Tool \(run_in_terminal\)/i.test(value)) return `🖥️ ${value}`;
+  if (/^Tool \((create_file|write)\)/i.test(value)) return `🆕 ${value}`;
+  if (/^Tool \((bash|shell|terminal)\)/i.test(value)) return `🔧 ${value}`;
+  if (/^Tool \((sql|sqlite)\)/i.test(value)) return `🗄️ ${value}`;
+  if (/^Tool \(/i.test(value)) return `🛠️ ${value}`;
+  return `ℹ️ ${value}`;
+}

package/server/public/app/transcript-viewport-anchor.mjs

@@ -0,0 +1,210 @@
+// Keeps the transcript's reading position through layout changes that
+// reflow the rows: phone rotation, the on-screen keyboard, a desktop window
+// resize, a font-scale change. The browser only preserves scrollTop as a
+// pixel count (and its own scroll anchoring pins the top-most row), so a
+// reader sitting at the end of a portrait transcript lands screens above
+// the end once the wider landscape rows shrink the content. A position is
+// therefore described by content, not pixels: "at the bottom", or "this
+// message is the top-most visible one, with this fraction of it scrolled
+// past" — a fraction, because the rows themselves change height when the
+// width changes, and a pixel offset would hide a whole shrunken row.
+
+const BOTTOM_EPSILON_PX = 1;
+
+/** Same rule the composer's follow-live logic uses: 8% of the viewport,
+ *  clamped to 12–48 px. */
+export function resolveNearBottomThresholdPx(clientHeight) {
+  const viewportHeight = Number(clientHeight || 0);
+  if (!Number.isFinite(viewportHeight) || viewportHeight <= 0) return 0;
+  return Math.min(48, Math.max(12, Math.floor(viewportHeight * 0.08)));
+}
+
+function distanceFromBottom(el) {
+  return Math.max(0, Number(el.scrollHeight || 0) - Number(el.clientHeight || 0) - Number(el.scrollTop || 0));
+}
+
+function transcriptRows(el) {
+  return Array.from(el.querySelectorAll('.msg[data-message-id]'));
+}
+
+/**
+ * Describes where the reader is. `atBottom` uses the near-bottom threshold
+ * rather than an exact pixel match: a reader a few pixels short of the end
+ * still means "the end", and a rotation must not strand them above it.
+ * Returns null for an empty transcript.
+ */
+export function captureTranscriptAnchor(el, { nearBottomThresholdPx = null } = {}) {
+  if (!el) return null;
+  const rows = transcriptRows(el);
+  if (!rows.length) return null;
+  const threshold = nearBottomThresholdPx !== null && Number.isFinite(Number(nearBottomThresholdPx))
+    ? Math.max(0, Number(nearBottomThresholdPx))
+    : Math.max(BOTTOM_EPSILON_PX, resolveNearBottomThresholdPx(el.clientHeight));
+  const atBottom = distanceFromBottom(el) <= threshold;
+  const containerRect = el.getBoundingClientRect();
+  let anchorRow = null;
+  let offsetTop = 0;
+  let rowHeight = 0;
+  for (const row of rows) {
+    const rect = row.getBoundingClientRect();
+    if (rect.bottom <= containerRect.top + 1) continue;
+    if (rect.top >= containerRect.bottom) break;
+    anchorRow = row;
+    offsetTop = rect.top - containerRect.top;
+    rowHeight = Math.max(0, rect.bottom - rect.top);
+    break;
+  }
+  const maxScroll = Math.max(1, Number(el.scrollHeight || 0) - Number(el.clientHeight || 0));
+  return {
+    atBottom,
+    messageId: String(anchorRow?.dataset?.messageId || '').trim() || null,
+    // Negative while the row's top is scrolled past the edge; scaled to the
+    // row's height so the same share of it stays hidden after a reflow.
+    offsetFraction: rowHeight > 0 ? offsetTop / rowHeight : 0,
+    ratio: Math.min(1, Math.max(0, Number(el.scrollTop || 0) / maxScroll)),
+  };
+}
+
+/**
+ * Moves the scroller so the captured position holds in the current layout.
+ * Bottom wins over the row anchor; a row that is no longer rendered falls
+ * back to the proportional position. Returns true when scrollTop changed.
+ */
+export function restoreTranscriptAnchor(el, anchor) {
+  if (!el || !anchor) return false;
+  const before = Number(el.scrollTop || 0);
+  if (anchor.atBottom) {
+    el.scrollTop = Number(el.scrollHeight || 0);
+    return Number(el.scrollTop || 0) !== before;
+  }
+  const messageId = String(anchor.messageId || '').trim();
+  const row = messageId
+    ? transcriptRows(el).find((node) => String(node.dataset?.messageId || '').trim() === messageId)
+    : null;
+  if (row) {
+    const containerRect = el.getBoundingClientRect();
+    const rect = row.getBoundingClientRect();
+    const targetOffset = Number(anchor.offsetFraction || 0) * Math.max(0, rect.bottom - rect.top);
+    const delta = rect.top - containerRect.top - targetOffset;
+    if (Math.abs(delta) > 0.5) el.scrollTop = before + delta;
+    return Number(el.scrollTop || 0) !== before;
+  }
+  const maxScroll = Math.max(0, Number(el.scrollHeight || 0) - Number(el.clientHeight || 0));
+  el.scrollTop = Math.round(maxScroll * Number(anchor.ratio || 0));
+  return Number(el.scrollTop || 0) !== before;
+}
+
+const KEYBOARD_INPUT_TYPES = new Set(['', 'text', 'search', 'email', 'url', 'tel', 'number', 'password']);
+
+/**
+ * The focused field inside the transcript that has the on-screen keyboard
+ * open (a question card's reply box or form input), or null.
+ */
+export function focusedTranscriptTextField(el, active = globalThis.document?.activeElement) {
+  if (!el || !active || active === el) return null;
+  if (typeof el.contains !== 'function' || !el.contains(active)) return null;
+  const tag = String(active.tagName || '').toUpperCase();
+  if (tag === 'TEXTAREA') return active;
+  if (tag === 'INPUT') {
+    return KEYBOARD_INPUT_TYPES.has(String(active.type ?? '').toLowerCase()) ? active : null;
+  }
+  return active.isContentEditable === true ? active : null;
+}
+
+/**
+ * Scrolls the transcript just enough to show the field whole, top-aligned
+ * when it is taller than the viewport. Arithmetic on scrollTop rather than
+ * scrollIntoView, which would scroll the page root too. Returns true when
+ * scrollTop changed.
+ */
+export function revealFieldInTranscript(el, field, { marginPx = 8 } = {}) {
+  if (!el || typeof field?.getBoundingClientRect !== 'function') return false;
+  const before = Number(el.scrollTop || 0);
+  const container = el.getBoundingClientRect();
+  const rect = field.getBoundingClientRect();
+  const viewTop = container.top + marginPx;
+  const viewBottom = container.bottom - marginPx;
+  let delta = 0;
+  if (rect.top < viewTop || rect.bottom - rect.top > viewBottom - viewTop) {
+    delta = rect.top - viewTop;
+  } else if (rect.bottom > viewBottom) {
+    delta = rect.bottom - viewBottom;
+  }
+  if (Math.abs(delta) <= 0.5) return false;
+  el.scrollTop = before + delta;
+  return Number(el.scrollTop || 0) !== before;
+}
+
+/**
+ * Tracks the position across resize storms. Scroll events commit the
+ * reader's position; a resize re-applies the last committed position and
+ * opens a settle window during which scroll events are ignored — they are
+ * the browser's own anchoring and our re-pins, not the reader. Rotation on
+ * a phone resizes in several steps (browser chrome animates), so the window
+ * extends with every step and the position is re-applied once more when it
+ * closes.
+ *
+ * The browser's reveal of a focused field when the keyboard shrinks the
+ * viewport is one of those ignored scrolls, so every re-apply reveals the
+ * focused transcript field again itself.
+ */
+export function createTranscriptResizeKeeper({
+  getElement,
+  settleMs = 500,
+  setTimer = (fn, ms) => setTimeout(fn, ms),
+  clearTimer = (id) => clearTimeout(id),
+  capture = captureTranscriptAnchor,
+  restore = restoreTranscriptAnchor,
+  getFocusedField = focusedTranscriptTextField,
+  reveal = revealFieldInTranscript,
+} = {}) {
+  let committed = null;
+  let settleTimer = null;
+
+  function element() {
+    try { return typeof getElement === 'function' ? getElement() : null; } catch { return null; }
+  }
+
+  function recordScroll() {
+    if (settleTimer !== null) return false;
+    const el = element();
+    if (!el) return false;
+    const next = capture(el);
+    if (next) committed = next;
+    return Boolean(next);
+  }
+
+  function apply(el) {
+    const restored = committed ? restore(el, committed) : false;
+    let field = null;
+    try { field = getFocusedField(el); } catch { field = null; }
+    const revealed = field ? reveal(el, field) : false;
+    return restored || revealed;
+  }
+
+  function endSettle() {
+    settleTimer = null;
+    const el = element();
+    if (el) apply(el);
+  }
+
+  function handleResize() {
+    const el = element();
+    if (!el) return false;
+    if (!committed) {
+      // Nothing committed yet (no scroll since load): the current position
+      // is the best description we have.
+      committed = capture(el);
+    }
+    if (settleTimer !== null) clearTimer(settleTimer);
+    settleTimer = setTimer(endSettle, settleMs);
+    return apply(el);
+  }
+
+  return {
+    recordScroll,
+    handleResize,
+    isSettling: () => settleTimer !== null,
+    committedAnchor: () => committed,
+  };
+}