@openmarket/rooms-client 0.1.0

package/dist/agent/topic-inbox.js

@@ -0,0 +1,266 @@
+/**
+ * The open-core topic model: one room's registry rows plus the viewer's
+ * per-bucket state (cursor, attention, unread), with the unread math,
+ * muted exclusions, merge roll-up, and the deterministic catch-up order
+ * that every surface (GUI store, TUI, inbox, keyboard nav) consumes
+ * instead of reimplementing semantics.
+ *
+ * A BUCKET is a topicId, or the reserved '' key (UNTOPICKED_BUCKET) for
+ * the room's untopicked linear messages, matching the durable store's
+ * reserved empty-string cursor row. Per the phase 2 contract the buckets
+ * are independent: reading the linear lane never marks a topic seen, and
+ * vice versa.
+ *
+ * This model is a pure state machine: no timers, no sockets, no writes.
+ * Cursor ACKs happen exclusively through the view batcher; the model only
+ * mirrors positions it is told about.
+ */
+/** The reserved bucket key for untopicked (linear) messages. */
+export const UNTOPICKED_BUCKET = "";
+function emptyBucket() {
+    return { lastSeq: 0, unreadCount: 0, cursor: 0, attention: "default" };
+}
+export class RoomTopicInbox {
+    room;
+    /** True once a withState hydration has landed; counts are trustworthy. */
+    hydrated = false;
+    headSeq = 0;
+    topics = new Map();
+    buckets = new Map();
+    constructor(room) {
+        this.room = room;
+    }
+    /** Replace registry rows and per-bucket state from a withState TOPICS
+     *  reply. Idempotent; later live frames layer on top.
+     *
+     *  Positions only move FORWARD: the server read can lag local truth by
+     *  the ack debounce plus the relay's cursor write buffer, so a rehydrate
+     *  (TOPIC_UPDATED / ENTRY_UPDATED are hot triggers) must never resurrect
+     *  a just-cleared badge. Cursors and lastSeq merge as max(local, server);
+     *  a bucket whose merged cursor reaches its lastSeq is read, whatever
+     *  count the stale server row carried. */
+    hydrate(payload) {
+        this.topics.clear();
+        for (const topic of payload.topics)
+            this.topics.set(topic.topicId, topic);
+        const previous = new Map(this.buckets);
+        this.buckets.clear();
+        for (const [key, state] of Object.entries(payload.state ?? {})) {
+            const local = previous.get(key);
+            const cursor = Math.max(state.cursor, local?.cursor ?? 0);
+            const lastSeq = Math.max(state.lastSeq, local?.lastSeq ?? 0);
+            this.buckets.set(key, {
+                ...state,
+                cursor,
+                lastSeq,
+                unreadCount: cursor >= lastSeq ? 0 : state.unreadCount,
+            });
+        }
+        if (!this.buckets.has(UNTOPICKED_BUCKET)) {
+            this.buckets.set(UNTOPICKED_BUCKET, emptyBucket());
+        }
+        this.headSeq = Math.max(this.headSeq, payload.headSeq ?? 0);
+        this.hydrated = true;
+    }
+    topicFor(topicId) {
+        return this.topics.get(topicId);
+    }
+    /** Follow a merged husk to its survivor (chains are flattened server-side
+     *  to one hop). A live id, unknown id, or the untopicked key returns
+     *  itself. */
+    survivorOf(key) {
+        if (key === UNTOPICKED_BUCKET)
+            return key;
+        const merged = this.topics.get(key)?.mergedInto;
+        return merged || key;
+    }
+    /** Merged-away buckets whose survivor is the given topic. */
+    aliasesOf(topicId) {
+        const aliases = [];
+        for (const topic of this.topics.values()) {
+            if (topic.mergedInto === topicId)
+                aliases.push(topic.topicId);
+        }
+        return aliases;
+    }
+    /** Registry rows in listed (creation) order, husks excluded. */
+    openTopics(options) {
+        const rows = [];
+        for (const topic of this.topics.values()) {
+            if (topic.mergedInto)
+                continue;
+            if (!options?.includeResolved && topic.resolved)
+                continue;
+            rows.push(topic);
+        }
+        return rows;
+    }
+    bucketFor(key) {
+        return this.buckets.get(key) ?? emptyBucket();
+    }
+    /** Every bucket still carrying unread, muted and merged husks included:
+     *  the explicit mark-channel-read verb clears ALL of them (a muted or
+     *  merged bucket left unacked would resurrect on unmute/reopen). */
+    unreadBuckets() {
+        const rows = [];
+        for (const [key, bucket] of this.buckets) {
+            if (bucket.unreadCount > 0 && bucket.lastSeq > bucket.cursor) {
+                rows.push({ key, lastSeq: bucket.lastSeq });
+            }
+        }
+        return rows;
+    }
+    attentionFor(topicId) {
+        return this.bucketFor(topicId).attention;
+    }
+    /** A registry mutation arrived (TOPIC_UPDATED, or a verb result echo). */
+    applyTopicUpdated(topic) {
+        this.topics.set(topic.topicId, topic);
+        if (!this.buckets.has(topic.topicId)) {
+            this.buckets.set(topic.topicId, emptyBucket());
+        }
+    }
+    /**
+     * A live entry arrived. viewedKey is the bucket the viewer is CURRENTLY
+     * looking at (or null): entries landing in the viewed bucket advance the
+     * local cursor instead of counting unread (the durable ACK rides the
+     * view batcher separately). Own posts never count unread, and an own
+     * post into a topic mirrors the server's auto-follow (mute survives).
+     */
+    applyEntry(entry, context) {
+        if (!Number.isFinite(entry.seq) || entry.seq <= 0)
+            return;
+        const key = entry.topicId || UNTOPICKED_BUCKET;
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = emptyBucket();
+            this.buckets.set(key, bucket);
+        }
+        bucket.lastSeq = Math.max(bucket.lastSeq, entry.seq);
+        this.headSeq = Math.max(this.headSeq, entry.seq);
+        const own = entry.userId === context.selfUserId;
+        if (own) {
+            if (key !== UNTOPICKED_BUCKET && bucket.attention !== "mute") {
+                bucket.attention = "follow";
+            }
+            return;
+        }
+        if (context.viewedKey === key) {
+            bucket.cursor = Math.max(bucket.cursor, entry.seq);
+            return;
+        }
+        bucket.unreadCount += 1;
+    }
+    /** Mirror an attention change (a TOPIC_SET_ATTENTION result, optimistic
+     *  or confirmed). */
+    applyAttention(topicId, attention) {
+        let bucket = this.buckets.get(topicId);
+        if (!bucket) {
+            bucket = emptyBucket();
+            this.buckets.set(topicId, bucket);
+        }
+        bucket.attention = attention;
+    }
+    /**
+     * The viewer saw a bucket up to seq (the view batcher owns the durable
+     * ACK; this mirrors it locally). Catching up to the bucket head clears
+     * its count; a partial view keeps the residual count as an upper bound
+     * until the next hydration trues it up.
+     */
+    noteViewed(key, seq) {
+        if (!Number.isFinite(seq) || seq <= 0)
+            return;
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = emptyBucket();
+            this.buckets.set(key, bucket);
+        }
+        bucket.cursor = Math.max(bucket.cursor, seq);
+        if (bucket.cursor >= bucket.lastSeq)
+            bucket.unreadCount = 0;
+    }
+    /**
+     * The channel-level unread badge for a topic-aware room: every non-muted
+     * bucket's count, untopicked and resolved included (new activity in a
+     * resolved topic still deserves attention), husks counted once (their
+     * unread also rolls into the survivor's inbox item for display).
+     */
+    channelUnread() {
+        let total = 0;
+        for (const bucket of this.buckets.values()) {
+            if (bucket.attention === "mute")
+                continue;
+            total += bucket.unreadCount;
+        }
+        return total;
+    }
+    /**
+     * The inbox, in THE deterministic catch-up order every surface shares:
+     * the untopicked lane first (the channel's main stream), then followed
+     * topics, then the rest; within each group oldest activity first
+     * (ascending lastSeq, topicId tie-break). Muted buckets never appear;
+     * merged husks roll their unread into the survivor's aliasUnread; a
+     * resolved topic appears only while it carries unread.
+     */
+    inboxItems() {
+        const items = [];
+        const untopicked = this.bucketFor(UNTOPICKED_BUCKET);
+        if (untopicked.unreadCount > 0 && untopicked.attention !== "mute") {
+            items.push({
+                key: UNTOPICKED_BUCKET,
+                topic: undefined,
+                state: { ...untopicked },
+                aliasUnread: 0,
+            });
+        }
+        const grouped = [];
+        for (const topic of this.topics.values()) {
+            if (topic.mergedInto)
+                continue;
+            const state = this.bucketFor(topic.topicId);
+            if (state.attention === "mute")
+                continue;
+            let aliasUnread = 0;
+            for (const alias of this.aliasesOf(topic.topicId)) {
+                const aliasState = this.bucketFor(alias);
+                if (aliasState.attention === "mute")
+                    continue;
+                aliasUnread += aliasState.unreadCount;
+            }
+            if (state.unreadCount + aliasUnread === 0)
+                continue;
+            grouped.push({ key: topic.topicId, topic, state: { ...state }, aliasUnread });
+        }
+        grouped.sort((a, b) => {
+            const aFollow = a.state.attention === "follow" ? 0 : 1;
+            const bFollow = b.state.attention === "follow" ? 0 : 1;
+            if (aFollow !== bFollow)
+                return aFollow - bFollow;
+            if (a.state.lastSeq !== b.state.lastSeq) {
+                return a.state.lastSeq - b.state.lastSeq;
+            }
+            return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+        });
+        items.push(...grouped);
+        return items;
+    }
+    /**
+     * The next bucket a catch-up walk should visit: the first inbox item
+     * after the given key (wrapping), or null when nothing is unread. The
+     * walk order is inboxItems(); keyboard nav and the catch-up flow step
+     * through the same list a user sees.
+     */
+    nextUnread(afterKey) {
+        const items = this.inboxItems();
+        if (items.length === 0)
+            return null;
+        if (afterKey === undefined || afterKey === null) {
+            return items[0]?.key ?? null;
+        }
+        const index = items.findIndex((item) => item.key === afterKey);
+        if (index < 0)
+            return items[0]?.key ?? null;
+        const next = items[(index + 1) % items.length];
+        return next && next.key !== afterKey ? next.key : null;
+    }
+}

package/dist/agent/topic-view-batcher.d.ts

@@ -0,0 +1,54 @@
+/**
+ * View-time cursor batching: the ONLY path from "a surface is showing
+ * messages" to a cursor ACK. Surfaces report views (beginView, noteSeq,
+ * endView); this batcher applies the locked phase 2 contract on top:
+ *
+ * - Dwell gating: a view must survive dwellMs before anything is acked, so
+ *   a keyboard flash-through (next-unread skimming past a topic) never
+ *   marks it read. "Marks read only after actual view time."
+ * - Batching: once dwelled, the highest seen seq forwards into the
+ *   downstream ACK debouncer (one ACK frame per bucket per debounce
+ *   window at most, relay-side write buffering below that). Per-message
+ *   cursor writes are impossible by construction: the UI layer has no
+ *   other ack path.
+ *
+ * A bucket key of '' (UNTOPICKED_BUCKET) acks the room-wide cursor; any
+ * other key acks that topic's cursor.
+ */
+export interface TopicViewBatcherOptions {
+    /** Forward a dwelled view position; wire this to RoomAckDebouncer.schedule. */
+    scheduleAck: (room: string, seq: number, topicId?: string) => void;
+    /** Continuous view time required before the first ack (default 600ms). */
+    dwellMs?: number | undefined;
+    /** Injectable timers for tests. */
+    setTimeoutFn?: ((fn: () => void, ms: number) => unknown) | undefined;
+    clearTimeoutFn?: ((handle: unknown) => void) | undefined;
+}
+export declare class TopicViewBatcher {
+    private readonly scheduleAck;
+    private readonly dwellMs;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private readonly sessions;
+    constructor(options: TopicViewBatcherOptions);
+    /** A surface started showing a bucket. Idempotent per (room, key). */
+    beginView(room: string, key: string): void;
+    /** The highest seq currently visible in a bucket the surface is showing.
+     *  Before dwell it accumulates; after dwell it forwards (debounced
+     *  downstream). Calls for a bucket not being viewed are ignored: only
+     *  actual view time acks. */
+    noteSeq(room: string, key: string, seq: number): void;
+    /** The surface stopped showing the bucket. An un-dwelled view (a
+     *  flash-through) is discarded without acking. */
+    endView(room: string, key: string): void;
+    /** True while the bucket is being viewed (dwelled or not). */
+    isViewing(room: string, key: string): boolean;
+    /** The bucket key currently viewed in a room, or null. */
+    viewedKey(room: string): string | null;
+    /** Force every dwelled view forward (window hide, disconnect boundary).
+     *  Un-dwelled views stay pending: flushing must not turn a flash-through
+     *  into a read. */
+    flush(): void;
+    close(): void;
+    private forward;
+}

package/dist/agent/topic-view-batcher.js

@@ -0,0 +1,115 @@
+/**
+ * View-time cursor batching: the ONLY path from "a surface is showing
+ * messages" to a cursor ACK. Surfaces report views (beginView, noteSeq,
+ * endView); this batcher applies the locked phase 2 contract on top:
+ *
+ * - Dwell gating: a view must survive dwellMs before anything is acked, so
+ *   a keyboard flash-through (next-unread skimming past a topic) never
+ *   marks it read. "Marks read only after actual view time."
+ * - Batching: once dwelled, the highest seen seq forwards into the
+ *   downstream ACK debouncer (one ACK frame per bucket per debounce
+ *   window at most, relay-side write buffering below that). Per-message
+ *   cursor writes are impossible by construction: the UI layer has no
+ *   other ack path.
+ *
+ * A bucket key of '' (UNTOPICKED_BUCKET) acks the room-wide cursor; any
+ * other key acks that topic's cursor.
+ */
+function viewKey(room, key) {
+    return `${encodeURIComponent(room)}:${encodeURIComponent(key)}`;
+}
+export class TopicViewBatcher {
+    scheduleAck;
+    dwellMs;
+    setTimeoutFn;
+    clearTimeoutFn;
+    sessions = new Map();
+    constructor(options) {
+        this.scheduleAck = options.scheduleAck;
+        this.dwellMs = options.dwellMs ?? 600;
+        this.setTimeoutFn =
+            options.setTimeoutFn ??
+                ((fn, ms) => {
+                    const timer = setTimeout(fn, ms);
+                    timer.unref?.();
+                    return timer;
+                });
+        this.clearTimeoutFn = options.clearTimeoutFn ?? ((handle) => clearTimeout(handle));
+    }
+    /** A surface started showing a bucket. Idempotent per (room, key). */
+    beginView(room, key) {
+        const id = viewKey(room, key);
+        if (this.sessions.has(id))
+            return;
+        const session = { room, key, maxSeq: 0, dwelled: false, timer: undefined };
+        session.timer = this.setTimeoutFn(() => {
+            session.dwelled = true;
+            session.timer = undefined;
+            this.forward(session);
+        }, this.dwellMs);
+        this.sessions.set(id, session);
+    }
+    /** The highest seq currently visible in a bucket the surface is showing.
+     *  Before dwell it accumulates; after dwell it forwards (debounced
+     *  downstream). Calls for a bucket not being viewed are ignored: only
+     *  actual view time acks. */
+    noteSeq(room, key, seq) {
+        if (!Number.isFinite(seq) || seq <= 0)
+            return;
+        const session = this.sessions.get(viewKey(room, key));
+        if (!session)
+            return;
+        if (seq <= session.maxSeq)
+            return;
+        session.maxSeq = seq;
+        if (session.dwelled)
+            this.forward(session);
+    }
+    /** The surface stopped showing the bucket. An un-dwelled view (a
+     *  flash-through) is discarded without acking. */
+    endView(room, key) {
+        const id = viewKey(room, key);
+        const session = this.sessions.get(id);
+        if (!session)
+            return;
+        if (session.timer !== undefined) {
+            this.clearTimeoutFn(session.timer);
+            session.timer = undefined;
+        }
+        this.sessions.delete(id);
+    }
+    /** True while the bucket is being viewed (dwelled or not). */
+    isViewing(room, key) {
+        return this.sessions.has(viewKey(room, key));
+    }
+    /** The bucket key currently viewed in a room, or null. */
+    viewedKey(room) {
+        for (const session of this.sessions.values()) {
+            if (session.room === room)
+                return session.key;
+        }
+        return null;
+    }
+    /** Force every dwelled view forward (window hide, disconnect boundary).
+     *  Un-dwelled views stay pending: flushing must not turn a flash-through
+     *  into a read. */
+    flush() {
+        for (const session of this.sessions.values()) {
+            if (session.dwelled)
+                this.forward(session);
+        }
+    }
+    close() {
+        for (const session of this.sessions.values()) {
+            if (session.timer !== undefined)
+                this.clearTimeoutFn(session.timer);
+        }
+        this.flush();
+        this.sessions.clear();
+    }
+    forward(session) {
+        if (session.maxSeq <= 0)
+            return;
+        this.scheduleAck(session.room, session.maxSeq, session.key === "" ? undefined : session.key);
+    }
+}