Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

perf(community): don't double read-PUT on channel open (seed the watermark)

Shelly4aeb297f072e
diff --git a/src/web/src/hooks/community/use-channel-watermark.test.ts b/src/web/src/hooks/community/use-channel-watermark.test.ts
index f75386ca2..1b76b4d25 100644
--- a/src/web/src/hooks/community/use-channel-watermark.test.ts
+++ b/src/web/src/hooks/community/use-channel-watermark.test.ts
@@ -8,9 +8,19 @@
import { describe, it, expect, vi, beforeEach } from "vitest"
// ── React shim ────────────────────────────────────────────────────────────
+// Positional hooks, React-faithful: `useRef`/`useEffect` are keyed by call
+// order within a render, and `useEffect` honors its deps array (runs only when
+// a dep changed vs the previous render — deps: [] runs once, no deps runs
+// always). Faithful deps matter here: the hook resets its read watermark on a
+// `[channelId]` effect and seeds once via a guarded ref — a shim that re-ran
+// every effect on every render would spuriously reset/re-seed on a plain
+// re-render (e.g. a WS message arriving), which React does not do.
let refs: Map<string, { current: unknown }> = new Map()
let refCounter = 0
-let pendingEffects: Array<{ fn: () => void | (() => void); deps: unknown[] }> = []
+let effectCounter = 0
+const effectPrevDeps: Map<number, unknown[] | undefined> = new Map()
+const effectCleanupBySlot: Map<number, () => void> = new Map()
+let pendingEffects: Array<{ slot: number; fn: () => void | (() => void); deps: unknown[] | undefined }> = []
let effectCleanups: Array<() => void> = []
vi.mock("react", () => ({
@@ -19,17 +29,32 @@ vi.mock("react", () => ({
if (!refs.has(id)) refs.set(id, { current: initial })
return refs.get(id)!
},
- useEffect: (fn: () => void | (() => void), deps: unknown[]) => {
- pendingEffects.push({ fn, deps })
+ useEffect: (fn: () => void | (() => void), deps?: unknown[]) => {
+ pendingEffects.push({ slot: effectCounter++, fn, deps })
},
}))
+function depsChanged(prev: unknown[] | undefined, next: unknown[] | undefined): boolean {
+ if (next === undefined) return true // no deps → run every render
+ if (prev === undefined) return true // first render
+ if (prev.length !== next.length) return true
+ return next.some((d, i) => !Object.is(d, prev[i]))
+}
+
function flushEffects() {
const effects = pendingEffects
pendingEffects = []
for (const e of effects) {
+ if (!depsChanged(effectPrevDeps.get(e.slot), e.deps)) continue
+ // React runs the cleanup from the prior invocation before re-running.
+ effectCleanupBySlot.get(e.slot)?.()
+ effectCleanupBySlot.delete(e.slot)
const cleanup = e.fn()
- if (typeof cleanup === "function") effectCleanups.push(cleanup)
+ if (typeof cleanup === "function") {
+ effectCleanupBySlot.set(e.slot, cleanup)
+ effectCleanups.push(cleanup)
+ }
+ effectPrevDeps.set(e.slot, e.deps)
}
}
@@ -39,6 +64,15 @@ function runCleanups() {
for (const fn of c) fn()
}
+// Simulate a React re-render: refs + effect slots persist (same call order →
+// same ref / same effect identity), but the per-render counters rewind so the
+// hook's `useRef`/`useEffect` calls map back onto the same slots. Effects then
+// re-run only if their deps changed — faithful to React.
+function rerender() {
+ refCounter = 0
+ effectCounter = 0
+}
+
// ── IntersectionObserver polyfill ────────────────────────────────────────
type ObserverInstance = {
callback: IntersectionObserverCallback
@@ -157,6 +191,9 @@ vi.mock("@/contexts/community/current-user", () => ({
function resetHarness() {
refs = new Map()
refCounter = 0
+ effectCounter = 0
+ effectPrevDeps.clear()
+ effectCleanupBySlot.clear()
pendingEffects = []
effectCleanups = []
observers = []
@@ -209,8 +246,34 @@ beforeEach(() => {
MockMutationObserver
})
+// A message NEWER than everything in the mount window — used to exercise the
+// watermark's advance path under the read-dedupe seed (the mount window is
+// pre-seeded as "already read by the eager mark-read", so only a genuinely
+// newer arrival advances). Its createdAt is later than any fixture below.
+const NEWER = { id: "m_newer", createdAt: "2026-09-01T00:00:00.000Z", authorId: "u_other" }
+
describe("useChannelWatermark — visibility gate", () => {
- it("advances the watermark when a row hits >=0.2 visibility", async () => {
+ it("advances the watermark when a NEWER-than-seed row hits >=0.2 visibility", async () => {
+ const useHook = await loadHook()
+ const root = makeRoot()
+ // Mount window: m_1 (already read by the eager mark-read → seeded, won't
+ // advance). A newer message then arrives (WS) and its row mounts.
+ const seedMsg = { id: "m_1", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" }
+ attachRows(root, [makeRow("m_1")])
+ useHook({ channelId: "ch_1", messages: [seedMsg], scrollRootEl: root })
+ flushEffects()
+ // Re-render with the newer message present (WS arrival) so the hook's
+ // messagesRef sees it; its row mounts via a DOM mutation.
+ rerender()
+ useHook({ channelId: "ch_1", messages: [seedMsg, NEWER], scrollRootEl: root })
+ flushEffects()
+ const newerRow = makeRow(NEWER.id)
+ fireAddedNodes([newerRow])
+ fireIntersections([{ target: newerRow, isIntersecting: true, intersectionRatio: 0.3 }])
+ expect(advanceSpy).toHaveBeenCalledWith("ch_1", NEWER.id)
+ })
+
+ it("does NOT re-advance a message already in the mount window (eager mark-read covered it)", async () => {
const useHook = await loadHook()
const root = makeRoot()
const row = makeRow("m_1")
@@ -223,8 +286,10 @@ describe("useChannelWatermark — visibility gate", () => {
scrollRootEl: root,
})
flushEffects()
- fireIntersections([{ target: row, isIntersecting: true, intersectionRatio: 0.3 }])
- expect(advanceSpy).toHaveBeenCalledWith("ch_1", "m_1")
+ // m_1 was present at mount → seeded as read by the eager PUT → the
+ // watermark must NOT fire a second, redundant read PUT for it.
+ fireIntersections([{ target: row, isIntersecting: true, intersectionRatio: 0.9 }])
+ expect(advanceSpy).not.toHaveBeenCalled()
})
it("does NOT advance when ratio is below 0.2", async () => {
@@ -262,66 +327,70 @@ describe("useChannelWatermark — visibility gate", () => {
})
})
+// A message older than every advancing fixture below — used to seed the mount
+// window so the read-dedupe seed lands on it, leaving the (newer) test messages
+// to arrive post-mount and exercise the advance path exactly as before the seed.
+const SEED_BASELINE = { id: "m_seed", createdAt: "2026-06-01T00:00:00.000Z", authorId: "u_other" }
+
+// Mount with just the seed baseline, then re-render with the baseline + the
+// given post-mount arrivals (WS/scroll), mounting their rows via a DOM
+// mutation. Returns the arrival row objects (keyed by id) so callers fire
+// intersections on the SAME element instances the observer is tracking.
+function mountThenArrive(
+ // Not named `use…` on purpose — a plain helper isn't a React hook/component,
+ // and the rules-of-hooks lint forbids calling a `use*` binding here.
+ runWatermark: (a: { channelId: string; messages: unknown[]; scrollRootEl: HTMLElement }) => void,
+ root: HTMLElement,
+ arrivals: Array<{ id: string; createdAt: string; authorId: string }>,
+): Record<string, Element> {
+ attachRows(root, [makeRow(SEED_BASELINE.id)])
+ runWatermark({ channelId: "ch_1", messages: [SEED_BASELINE], scrollRootEl: root })
+ flushEffects()
+ rerender()
+ runWatermark({ channelId: "ch_1", messages: [SEED_BASELINE, ...arrivals], scrollRootEl: root })
+ flushEffects()
+ const rows: Record<string, Element> = {}
+ for (const a of arrivals) rows[a.id] = makeRow(a.id)
+ fireAddedNodes(Object.values(rows))
+ return rows
+}
+
describe("useChannelWatermark — monotone forward", () => {
it("advances forward across two newer intersections", async () => {
const useHook = await loadHook()
const root = makeRoot()
- const row1 = makeRow("m_1")
- const row2 = makeRow("m_2")
- attachRows(root, [row1, row2])
- useHook({
- channelId: "ch_1",
- messages: [
- { id: "m_1", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" },
- { id: "m_2", createdAt: "2026-07-01T00:00:01.000Z", authorId: "u_other" },
- ],
- scrollRootEl: root,
- })
- flushEffects()
- fireIntersections([{ target: row1, isIntersecting: true, intersectionRatio: 0.9 }])
- fireIntersections([{ target: row2, isIntersecting: true, intersectionRatio: 0.9 }])
+ const rows = mountThenArrive(useHook, root, [
+ { id: "m_1", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" },
+ { id: "m_2", createdAt: "2026-07-01T00:00:01.000Z", authorId: "u_other" },
+ ])
+ fireIntersections([{ target: rows.m_1, isIntersecting: true, intersectionRatio: 0.9 }])
+ fireIntersections([{ target: rows.m_2, isIntersecting: true, intersectionRatio: 0.9 }])
expect(advanceSpy.mock.calls.map((c) => c[1])).toEqual(["m_1", "m_2"])
})
it("NEVER regresses — a stale-older intersection after seeing a newer row is ignored", async () => {
const useHook = await loadHook()
const root = makeRoot()
- const rowOld = makeRow("m_old")
- const rowNew = makeRow("m_new")
- attachRows(root, [rowOld, rowNew])
- useHook({
- channelId: "ch_1",
- messages: [
- { id: "m_old", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" },
- { id: "m_new", createdAt: "2026-07-02T00:00:00.000Z", authorId: "u_other" },
- ],
- scrollRootEl: root,
- })
- flushEffects()
+ const rows = mountThenArrive(useHook, root, [
+ { id: "m_old", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" },
+ { id: "m_new", createdAt: "2026-07-02T00:00:00.000Z", authorId: "u_other" },
+ ])
// See the newer one first.
- fireIntersections([{ target: rowNew, isIntersecting: true, intersectionRatio: 0.9 }])
+ fireIntersections([{ target: rows.m_new, isIntersecting: true, intersectionRatio: 0.9 }])
// Then scroll back — an older row briefly clears the threshold again.
- fireIntersections([{ target: rowOld, isIntersecting: true, intersectionRatio: 0.9 }])
+ fireIntersections([{ target: rows.m_old, isIntersecting: true, intersectionRatio: 0.9 }])
expect(advanceSpy.mock.calls.map((c) => c[1])).toEqual(["m_new"])
})
it("breaks (createdAt, id) ties lexicographically on id", async () => {
const useHook = await loadHook()
const root = makeRoot()
- const rowA = makeRow("m_a")
- const rowB = makeRow("m_b")
- attachRows(root, [rowA, rowB])
- useHook({
- channelId: "ch_1",
- messages: [
- { id: "m_a", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" },
- { id: "m_b", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" },
- ],
- scrollRootEl: root,
- })
- flushEffects()
- fireIntersections([{ target: rowA, isIntersecting: true, intersectionRatio: 0.9 }])
- fireIntersections([{ target: rowB, isIntersecting: true, intersectionRatio: 0.9 }])
+ const rows = mountThenArrive(useHook, root, [
+ { id: "m_a", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" },
+ { id: "m_b", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" },
+ ])
+ fireIntersections([{ target: rows.m_a, isIntersecting: true, intersectionRatio: 0.9 }])
+ fireIntersections([{ target: rows.m_b, isIntersecting: true, intersectionRatio: 0.9 }])
// b > a lexicographically at the same createdAt, so both advance.
expect(advanceSpy.mock.calls.map((c) => c[1])).toEqual(["m_a", "m_b"])
})
@@ -331,33 +400,22 @@ describe("useChannelWatermark — virtualized rows (mounted on scroll, no messag
it("observes a row the virtualizer mounts AFTER the initial seed, so scrolling clears unreads", async () => {
// Regression: with the virtualized message list, rows enter the DOM as
// the user scrolls — the `messages` array reference doesn't change, so
- // the seed effect (deps: [channelId, messages, scrollRootEl, viewerId])
- // never re-runs and the newly-mounted row is never observed. The read
- // watermark then never advances past whatever was on-screen at mount,
- // so "NEW" unreads never clear on scroll. A MutationObserver on the
- // scroll root must pick up the added row and observe it.
+ // the seed effect never re-runs and the newly-mounted row is never
+ // observed. The read watermark then never advances past whatever was
+ // on-screen at mount, so "NEW" unreads never clear on scroll. A
+ // MutationObserver on the scroll root must pick up the added row.
+ //
+ // Under read-dedupe, the advancing row must also be NEWER than the mount
+ // seed — a message already in the mount window was covered by the eager
+ // mark-read, so scrolling to it correctly does not re-PUT. Here m_2 arrives
+ // after the seed baseline and is genuinely newer.
const useHook = await loadHook()
const root = makeRoot()
- // At mount only the top row is rendered by the virtualizer.
- const topRow = makeRow("m_1")
- attachRows(root, [topRow])
- useHook({
- channelId: "ch_1",
- messages: [
- { id: "m_1", createdAt: "2026-07-01T00:00:00.000Z", authorId: "u_other" },
- { id: "m_2", createdAt: "2026-07-01T00:00:05.000Z", authorId: "u_other" },
- ],
- scrollRootEl: root,
- })
- flushEffects()
-
- // User scrolls down — the virtualizer mounts m_2's row into the DOM.
- // No `messages` change fires; only a DOM mutation.
- const scrolledRow = makeRow("m_2")
- fireAddedNodes([scrolledRow])
-
- // The newly-mounted row must now be observed and advance the watermark.
- fireIntersections([{ target: scrolledRow, isIntersecting: true, intersectionRatio: 0.9 }])
+ const rows = mountThenArrive(useHook, root, [
+ { id: "m_2", createdAt: "2026-07-01T00:00:05.000Z", authorId: "u_other" },
+ ])
+ // The newly-mounted (newer) row is observed and advances the watermark.
+ fireIntersections([{ target: rows.m_2, isIntersecting: true, intersectionRatio: 0.9 }])
expect(advanceSpy).toHaveBeenCalledWith("ch_1", "m_2")
})
})
diff --git a/src/web/src/hooks/community/use-channel-watermark.ts b/src/web/src/hooks/community/use-channel-watermark.ts
index 9a1ab33ea..07628e806 100644
--- a/src/web/src/hooks/community/use-channel-watermark.ts
+++ b/src/web/src/hooks/community/use-channel-watermark.ts
@@ -56,8 +56,20 @@ export function useChannelWatermark({
// channel changes so a switch between channels doesn't leak the prior
// channel's pointer.
const maxSeenRef = useRef<{ createdAt: string; id: string } | null>(null)
+ // Read-PUT de-dupe (W-READ-DEDUPE, necessity plan): opening a channel already
+ // fires ONE mark-read-to-latest via `useEagerChannelRead`. Without a seed the
+ // watermark would then observe the already-visible tail and fire a SECOND,
+ // redundant read PUT for messages the eager read just covered. So seed
+ // `maxSeen` once per channel to the newest loaded message — the same point
+ // the eager read marks — so the initial visible rows don't advance. Only a
+ // genuinely newer message (a WS arrival, or one scrolled to beyond the seed)
+ // moves the watermark and PUTs, which is a real read the eager PUT didn't
+ // cover. `seededForRef` gates the one-shot per channel (mirrors eager-read's
+ // `firedForRef`); the channel-change reset re-arms it.
+ const seededForRef = useRef<string | null>(null)
useEffect(() => {
maxSeenRef.current = null
+ seededForRef.current = null
}, [channelId])
// Keep the freshest `messages` array visible to the IntersectionObserver
@@ -72,6 +84,33 @@ export function useChannelWatermark({
advanceRef.current = advance
})
+ // Seed `maxSeen` to the newest loaded message once per channel (see the
+ // `seededForRef` comment above). Runs before the observer effect below and on
+ // the first non-empty `messages`, so the initial visible tail is already
+ // "seen" by the time the IntersectionObserver fires — no redundant read PUT
+ // on open. A later message with a strictly greater (createdAt, id) still
+ // advances past this seed.
+ useEffect(() => {
+ if (!channelId) return
+ if (seededForRef.current === channelId) return
+ if (messages.length === 0) return
+ let newest: { createdAt: string; id: string } | null = null
+ for (const m of messages) {
+ if (!m.createdAt) continue
+ if (
+ !newest ||
+ m.createdAt > newest.createdAt ||
+ (m.createdAt === newest.createdAt && m.id > newest.id)
+ ) {
+ newest = { createdAt: m.createdAt, id: m.id }
+ }
+ }
+ if (newest) {
+ maxSeenRef.current = newest
+ seededForRef.current = channelId
+ }
+ }, [channelId, messages])
+
useEffect(() => {
if (!channelId) return
if (!scrollRootEl) return