Merge pull request #59 from huggingface/reader/remember-reading-position

docs/conversation-view.md

@@ -263,6 +263,29 @@ pane with nothing to render (a shell) simply stays a terminal.
   Writes pause between `compositionstart` and `compositionend`: a phone keyboard composes, and the
   pre-composition snapshot is a string the user meant, where a mid-composition one is half a
   syllable.
+- **It comes back to where you were reading** (`readingPosition.ts`). Opening on the end is right
+  for a conversation you have not read; it is not right for one you were half-way up. In-app
+  navigation already survived — the pane stays mounted and the browser preserves the scroll box
+  across the `display: none` that hides a warm tile — so this is about the **cold mount**: a
+  reload, an evicted tab, the Hub rebuilding the iframe. Same layer as the draft in §3.3.
+
+  The anchor is a **turn timestamp**, and the windowed reader forces that choice. Exchanges
+  *regroup* as older windows arrive — the one at the top of the list is a fragment whose prompt was
+  in the window not yet read, and the two become one when it lands — so no React key, list index or
+  pixel offset identifies a place for longer than one fetch. A turn's `ts` comes from the
+  transcript and never moves.
+
+  If the remembered turn is not in the window the reader opened with, it **pages backwards to find
+  it**, through the same public `loadOlder()` a scroll would use, bounded to six windows. Past that
+  it stays on the end — a remembered position is not worth walking a 19 MB transcript for.
+
+  Three rules decide whether it feels right rather than merely works. **Nothing is remembered until
+  you have moved the view**, and the evidence is a *gesture* — wheel, touch, pointer, keys, the turn
+  nav, the load-earlier button — never a `scroll` event, which fires when the reader re-anchors
+  under a prepend and would otherwise file a position you never chose. **If you were at the end you
+  return to the new end**, not to the row that used to be last. And a **turn that cannot be reached**
+  degrades to the end rather than the top. Bounded to 100 sessions; never expires, because unlike a
+  draft it is not text you typed.
 - **Share** moves here from the sidebar. One session, one place.
 - **Handover** ("continue from this trace in a new agent") lives in the conversation footer, beside
   the provenance line — the only place where its meaning is obvious.

web/src/components/conversation/ConversationView.tsx

@@ -18,6 +18,7 @@ import * as api from '../../api';
 import type { TraceTurn } from '../../api';
 import { useTraceWindows, type TraceSource } from '../../lib/traceWindows';
 import type { Session } from '../../types';
+import { recallReading, rememberReading } from './readingPosition';
 import { useDraft } from './useDraft';
 import { fmtTok, splitExchanges } from './exchanges';
 import ExchangeView from './Exchange';
@@ -176,7 +177,7 @@ export default function ConversationView({ session, paused, isMobile, readOnly,
       : tops.find((t) => t > cur + 8);
     if (next != null) el.scrollTo({ top: Math.max(0, next - 4), behavior: 'smooth' });
   };
-  const nav = (dir: -1 | 1) => (q && hits ? stepHit(dir) : goTurn(dir));
+  const nav = (dir: -1 | 1) => { moved(); return q && hits ? stepHit(dir) : goTurn(dir); };
 
   // Land on the end of the conversation, and stay there until the reader
   // decides otherwise. This is not only for a working agent: switching a pane
@@ -218,6 +219,120 @@ export default function ConversationView({ session, paused, isMobile, readOnly,
     anchor.current = null;
   }, [version, live, sent]);
 
+  // ---- where you had got to -----------------------------------------------
+  // Opening on the end is right for a conversation you have not read; it is not
+  // right for one you were half-way up. See readingPosition.ts for why the anchor
+  // is a turn timestamp and not a key, an index or a pixel.
+
+  /** Distance from the reading area's top edge to a row, in scroll coordinates. */
+  const rowTop = (el: HTMLElement, node: HTMLElement) =>
+    node.getBoundingClientRect().top - (el.getBoundingClientRect().top - el.scrollTop);
+
+  // Nothing is remembered until you have actually moved the view. `stick` starts
+  // true as an ASSUMPTION (follow the work), not an observation, so recording on
+  // it would file "you were at the end" for every session you merely glanced at.
+  // And the evidence is a GESTURE, not a `scroll` event: a scroll fires for
+  // reasons that are not you — the reader re-anchoring as older windows arrive,
+  // above all — and gating on that still filed phantom positions.
+  const touched = useRef(false);
+  const moved = () => { touched.current = true; };
+
+  const shownRef = useRef(shown);
+  shownRef.current = shown;
+
+  const capture = useCallback(() => {
+    const el = scroller.current;
+    if (!el || !touched.current) return;
+    if (stick.current) { rememberReading(session.id, { ts: 0, off: 0, end: true }); return; }
+    const list = shownRef.current;
+    const hit = [...rows.current.entries()]
+      .sort((a, b) => a[0] - b[0])
+      // The first row still showing at the top edge is the turn you are reading —
+      // skipping any whose prompt is in a window we have not read yet, because a
+      // fragment has no timestamp of its own to come back to.
+      .find(([i, node]) => rowTop(el, node) + node.offsetHeight > el.scrollTop + 4
+        && (list[i]?.startTs ?? 0) > 0);
+    if (!hit) return;
+    const [i, node] = hit;
+    rememberReading(session.id, {
+      ts: list[i].startTs, off: el.scrollTop - rowTop(el, node), end: false,
+    });
+  }, [session.id]);
+
+  // Scroll fires in bursts; one write per quiet moment is plenty.
+  const settle = useRef<number>(0);
+  const onScrolled = () => {
+    window.clearTimeout(settle.current);
+    settle.current = window.setTimeout(capture, 150);
+  };
+  // Flush on the way out. Through a ref, because an effect that depended on
+  // `capture` would run its cleanup on every dependency change, and this has to
+  // mean unmount rather than "something moved".
+  const flush = useRef(capture);
+  flush.current = capture;
+  useEffect(() => () => { window.clearTimeout(settle.current); flush.current(); }, []);
+
+  /**
+   * Looking for the remembered turn, paging backwards until it shows up. Bounded:
+   * the reader holds one window and the turn may be several behind it, but a
+   * remembered position is not worth walking a 19 MB transcript for, so past this
+   * we give up and stay on the end — which is where the reader would have been
+   * anyway.
+   */
+  const MAX_HOPS = 6;
+  const seeking = useRef<{ ts: number; off: number; hops: number } | null>(null);
+
+  /** One attempt to land on the remembered turn, or one window back towards it. */
+  const trySeek = useCallback(() => {
+    const st = seeking.current;
+    const el = scroller.current;
+    if (!st || !el) return;
+    const list = shownRef.current;
+    const idx = list.findIndex((x) => x.startTs === st.ts);
+    const node = idx >= 0 ? rows.current.get(idx) : undefined;
+    if (node) {
+      el.scrollTop = Math.max(0, rowTop(el, node) + st.off);
+      stick.current = el.scrollHeight - el.scrollTop - el.clientHeight < 48;
+      seeking.current = null;
+      return;
+    }
+    // Not in what we hold. Either walk back a window, or stop pretending: the end
+    // is where the reader would have been anyway.
+    if (atStart || blocked || st.hops >= MAX_HOPS) {
+      seeking.current = null;
+      stick.current = true;
+      el.scrollTop = el.scrollHeight;
+      return;
+    }
+    st.hops += 1;
+    loadOlder();
+  }, [atStart, blocked, loadOlder]);
+
+  const wantRestore = useRef(true);
+  // Restore on mount, and again on coming back into view: a pane can stay mounted
+  // while its tile is hidden, so a browser that drops the scroll offset of a
+  // `display: none` scroller would otherwise leave no re-mount to hook.
+  useEffect(() => { if (!paused) wantRestore.current = true; }, [paused]);
+  useEffect(() => {
+    if (!wantRestore.current || !head) return;
+    wantRestore.current = false;
+    const want = recallReading(session.id);
+    // No memory, or you were at the end: leave the landing to whoever owns it,
+    // which is the open-on-the-end rule above.
+    if (!want || want.end || !want.ts) return;
+    seeking.current = { ts: want.ts, off: want.off, hops: 0 };
+    stick.current = false;  // do not follow the end while we look for the place
+    // Start here rather than waiting for the effect below. Passive effects run
+    // AFTER layout effects, so arming the seek on this commit and leaving the
+    // landing to a layout effect meant nothing tried until the next render — and
+    // a quiet trace does not have one.
+    trySeek();
+  }, [head, paused, session.id, trySeek]);
+
+  // Every window that arrives is another chance to land. After the hook's own
+  // anchor effect, so this has the last word on scrollTop.
+  useLayoutEffect(() => { trySeek(); }, [version, trySeek]);
+
   if (!head) return <div className="cxv-empty mono">{error || 'reading the trace…'}</div>;
 
   return (
@@ -246,12 +361,17 @@ export default function ConversationView({ session, paused, isMobile, readOnly,
       </div>
 
       <div className="cxv-body" ref={scroller}
+        onWheel={moved}
+        onTouchStart={moved}
+        onPointerDown={moved}
+        onKeyDown={moved}
         onScroll={(e) => {
           const el = e.currentTarget;
           stick.current = el.scrollHeight - el.scrollTop - el.clientHeight < 48;
           // Reading back into the conversation: fetch the stretch in front of
           // what we hold before the reader arrives at it.
           if (el.scrollTop < NEAR_TOP_PX) loadOlder();
+          onScrolled();
         }}>
         <div className="cxv-col">
           {error && <div className="cxv-msg bad mono">{error} · showing the last read</div>}
@@ -259,7 +379,7 @@ export default function ConversationView({ session, paused, isMobile, readOnly,
             type="button"
             className="cxv-msg mono cxv-top"
             disabled={atStart || blocked}
-            onClick={() => loadOlder()}
+            onClick={() => { moved(); loadOlder(); }}
             title={atStart || blocked ? undefined : 'Load the previous stretch of the conversation'}
           >
             {blocked

web/src/components/conversation/readingPosition.ts

@@ -0,0 +1,126 @@
+// Where you had got to in a conversation.
+//
+// The reader keeps no memory of this, so every cold mount opens on the end of the
+// trace (§3.3, and #55) — better than the top it used to open on, but still not
+// the place you had scrolled to. In-app navigation happens to survive, because
+// the pane stays mounted and the browser preserves the scroll box across the
+// `display: none` that hides a warm tile; that is why this looks fine on a
+// desktop and not on a phone, where coming back is a reload, an evicted tab, or
+// the Hub rebuilding the Space's iframe. Same layer as drafts.ts, same reason.
+//
+// The anchor is a **turn timestamp**, and that choice is forced by how the reader
+// reads. It holds a byte window of the transcript and pages backwards, and when
+// an older window arrives the exchanges REGROUP: an exchange at the top of the
+// list is a fragment whose prompt was in the window not yet read, and the two
+// become one exchange when it lands. So neither the React key, nor an index into
+// the list, nor a pixel offset identifies a place for longer than one fetch. A
+// turn's `ts` comes from the transcript and never moves. `off` then only carries
+// where inside that turn you were.
+//
+// `end` is the case that matters most: if you were reading the tail and the agent
+// added six turns while you were away, you want the new bottom, not the row that
+// used to be at the bottom.
+
+const KEY = 'am.reading';
+const VERSION = 2;
+
+/**
+ * How many sessions' positions to keep. Each entry is a few dozen bytes, so this
+ * is about not growing without bound rather than about the storage budget.
+ * Unlike a draft this never expires: a reading position is not text you typed, so
+ * it carries nothing worth forgetting for its own sake, and it stays useful for
+ * exactly as long as the conversation does.
+ */
+const MAX_ENTRIES = 100;
+
+export interface Reading {
+  /** `ts` of the turn that opened the exchange at the top of the reading area. */
+  ts: number;
+  /** How far below the reading area's top edge that exchange started, in px. */
+  off: number;
+  /** You were at the end of the conversation — follow the end, not the turn. */
+  end: boolean;
+}
+
+interface Entry { t: number; o: number; e: 0 | 1; at: number }
+type Store = Record<string, Entry>;
+
+const mem = new Map<string, Reading>();
+
+// Same reason as drafts.ts: `at` orders the set as well as dating it, and
+// Date.now() cannot separate two writes in the same millisecond.
+let stamped = 0;
+const stamp = () => {
+  stamped = Math.max(Date.now(), stamped + 1);
+  return stamped;
+};
+
+function load(): Store {
+  try {
+    const raw = localStorage.getItem(KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as { v?: number; d?: Store };
+    // A v1 blob anchored on an absolute turn number, which the windowed reader
+    // cannot resolve. Not upgradeable; dropped, and the next write replaces it.
+    if (parsed?.v !== VERSION || !parsed.d || typeof parsed.d !== 'object') return {};
+    const out: Store = {};
+    for (const [id, e] of Object.entries(parsed.d)) {
+      if (e && typeof e.t === 'number' && typeof e.o === 'number' && typeof e.at === 'number') out[id] = e;
+    }
+    return out;
+  } catch {
+    // Denied (private mode, a third-party iframe under tracking prevention) or
+    // nonsense under our key. No remembered positions, which is where we were.
+    return {};
+  }
+}
+
+function save(store: Store) {
+  // Newest first; the tail past MAX_ENTRIES falls off, so the session you are
+  // reading right now is the last thing to go.
+  const byNewest = Object.entries(store).sort((a, b) => b[1].at - a[1].at);
+  let out: Store = Object.fromEntries(byNewest.slice(0, MAX_ENTRIES));
+  // A scroll position is never worth an exception on the way past. If the quota
+  // is full — of other things, mostly — shed the oldest and try again, then give
+  // up in silence.
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    try {
+      localStorage.setItem(KEY, JSON.stringify({ v: VERSION, d: out }));
+      return;
+    } catch {
+      const oldest = Object.keys(out).sort((a, b) => out[a].at - out[b].at)[0];
+      if (!oldest) {
+        try { localStorage.removeItem(KEY); } catch { /* nothing left to try */ }
+        return;
+      }
+      const next = { ...out };
+      delete next[oldest];
+      out = next;
+    }
+  }
+}
+
+/** Where this session was last being read, or null if we have never seen it. */
+export function recallReading(id: string): Reading | null {
+  const held = mem.get(id);
+  if (held) return held;
+  const e = load()[id];
+  if (!e) return null;
+  const r: Reading = { ts: e.t, off: e.o, end: !!e.e };
+  mem.set(id, r);
+  return r;
+}
+
+export function rememberReading(id: string, r: Reading | null) {
+  if (!r) {
+    mem.delete(id);
+    const store = load();
+    delete store[id];
+    save(store);
+    return;
+  }
+  mem.set(id, r);
+  const store = load();
+  store[id] = { t: Math.round(r.ts), o: Math.round(r.off), e: r.end ? 1 : 0, at: stamp() };
+  save(store);
+}