@openmarket/rooms-client 0.1.0

package/dist/agent/room-context.js

@@ -0,0 +1,251 @@
+/**
+ * The context spine for agent-native rooms.
+ *
+ * Two jobs, both about spending tokens on the ask and not on the room's whole
+ * history:
+ *  - resolve a conversational scope ("the last 200", "since 'ok new plan'",
+ *    "since my last message") to a concrete history cursor the agent fetches;
+ *  - render the per-room BRIEF (a generated, human-readable doc: purpose,
+ *    running summary, open threads, decisions, and every doc the room refers to
+ *    with its freshness) and assemble a turn's context in cheapest-first tiers,
+ *    stopping at a budget so a turn never eats the ledger.
+ *
+ * Pure and dependency-free so every rule is unit-pinned; the runtime supplies
+ * the live history, the LLM summary, and the doc writes.
+ */
+/** Lane seeding: how many recent messages a lane turn carries room-wide when
+ *  the whisper starts from the plain channel stream (today's behavior). */
+export const LANE_ROOM_WINDOW = 30;
+/** Lane seeding: how many of the topic's recent messages a lane turn carries
+ *  when the whisper starts from inside a topic. */
+export const LANE_TOPIC_WINDOW = 30;
+/** Lane seeding: the smaller room-wide window that rides ALONGSIDE a topic
+ *  slice so cross-topic references still resolve without a tool call. */
+export const LANE_SCOPED_ROOM_WINDOW = 10;
+/**
+ * Slice the loaded ledger into the lane's seed windows. Unscoped (plain
+ * channel whisper): the room-wide recent window, exactly as before. Scoped
+ * (whisper from inside a topic): that topic's recent slice (what exists, up
+ * to the window) PLUS a smaller room-wide window for cross-topic references.
+ * Entries arrive pre-filtered (no deleted rows, no empty text), oldest first.
+ */
+export function laneSeedWindows(entries, topic) {
+    if (!topic?.topicId) {
+        return { recentWindow: renderRecentWindow(entries.slice(-LANE_ROOM_WINDOW)) };
+    }
+    const topicEntries = entries
+        .filter((entry) => entry.topicId === topic.topicId)
+        .slice(-LANE_TOPIC_WINDOW);
+    return {
+        recentWindow: renderRecentWindow(entries.slice(-LANE_SCOPED_ROOM_WINDOW)),
+        topicWindow: { name: topic.name, lines: renderRecentWindow(topicEntries) },
+    };
+}
+/** Parse a free-text scope argument into a structured scope. Accepts a bare
+ *  count ("200"), `last N`, `since <text or "quoted marker">`, `since me` /
+ *  `since my last`, or `thread <seq>`. A leading `from @handle` scopes to one
+ *  author and composes with the rest ("from @henry", "from @henry last 100",
+ *  "from @henry since 'ok new plan'"). Defaults to a recent count. */
+export function parseHistoryScope(arg, myHandle) {
+    const raw = (arg ?? "").trim();
+    if (raw.length === 0)
+        return { kind: "count", n: 50 };
+    const from = /^from\s+@([\w.-]+)\s*/i.exec(raw);
+    if (from?.[1]) {
+        return { ...parseHistoryScope(raw.slice(from[0].length), myHandle), author: from[1] };
+    }
+    const lower = raw.toLowerCase();
+    const countOnly = /^(?:last\s+)?(\d{1,4})$/.exec(lower);
+    if (countOnly?.[1])
+        return { kind: "count", n: Number(countOnly[1]) };
+    if (lower === "since me" || lower === "since my last" || lower === "since my last message") {
+        return { kind: "sinceMyLast", myHandle };
+    }
+    const thread = /^thread\s+(\d{1,9})$/.exec(lower);
+    if (thread?.[1])
+        return { kind: "thread", rootSeq: Number(thread[1]) };
+    const since = /^since\s+(.+)$/i.exec(raw);
+    if (since?.[1]) {
+        const marker = since[1].trim().replace(/^["']|["']$/g, "");
+        return { kind: "sinceMarker", marker };
+    }
+    // A bare phrase is treated as a marker to find.
+    return { kind: "sinceMarker", marker: raw.replace(/^["']|["']$/g, "") };
+}
+/** Resolve a scope against the room's recent entries. Returns null when a
+ *  marker or my-last-message cannot be found (the caller reports it). An
+ *  author filter rides through: the window resolves the same way, and the
+ *  caller keeps only that handle's messages inside it. */
+export function resolveHistoryScope(scope, entries) {
+    const base = resolveScopeWindow(scope, entries);
+    if (!base || !scope.author)
+        return base;
+    const author = scope.author.replace(/^@/, "");
+    return { ...base, author, label: `${base.label} from @${author}` };
+}
+function resolveScopeWindow(scope, entries) {
+    switch (scope.kind) {
+        case "count":
+            return { limit: Math.max(1, Math.min(scope.n, 500)), label: `the last ${scope.n}` };
+        case "thread":
+            return { threadRootSeq: scope.rootSeq, label: `thread at ${scope.rootSeq}` };
+        case "sinceMyLast": {
+            const mine = [...entries]
+                .filter((e) => e.handle.replace(/^@/, "") === scope.myHandle.replace(/^@/, ""))
+                .sort((a, b) => a.seq - b.seq)
+                .at(-1);
+            if (!mine)
+                return null;
+            return { sinceSeq: mine.seq, label: "since your last message" };
+        }
+        case "sinceMarker": {
+            const needle = scope.marker.toLowerCase();
+            if (needle.length === 0)
+                return null;
+            // The LAST message that matches, so "since 'X'" starts at the most recent
+            // occurrence, not an older stray mention.
+            const match = [...entries]
+                .sort((a, b) => a.seq - b.seq)
+                .reverse()
+                .find((e) => e.text.toLowerCase().includes(needle));
+            if (!match)
+                return null;
+            // Inclusive of the marker message itself: fetch seq > (markerSeq - 1).
+            return { sinceSeq: match.seq - 1, label: `since "${scope.marker}"` };
+        }
+    }
+}
+/** `#btc` → `briefs/btc.md`. The brief for a room is a real doc in the space's
+ *  library, so it rides the sync to disk and can be linked and read like any
+ *  other note. */
+export function briefPath(roomName) {
+    const slug = roomName
+        .trim()
+        .replace(/^#/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60) || "room";
+    return `briefs/${slug}.md`;
+}
+/** Render the canonical brief markdown. Deterministic shell; the LLM only
+ *  supplies the summary/threads/decisions prose. */
+export function renderBrief(input) {
+    const lines = [];
+    lines.push(`# Brief: ${input.room}`);
+    lines.push("");
+    lines.push(`> Auto-generated by the room agent, read-only. Updated ${input.updatedAtLabel}.`);
+    lines.push("");
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(input.summary.trim() || "_No summary yet._");
+    lines.push("");
+    lines.push("## Open threads");
+    lines.push("");
+    if (input.openThreads.length === 0)
+        lines.push("_None._");
+    else
+        for (const t of input.openThreads)
+            lines.push(`- ${t}`);
+    lines.push("");
+    lines.push("## Decisions");
+    lines.push("");
+    if (input.decisions.length === 0)
+        lines.push("_None yet._");
+    else
+        for (const d of input.decisions)
+            lines.push(`- ${d}`);
+    lines.push("");
+    lines.push("## Docs in play");
+    lines.push("");
+    if (input.docs.length === 0)
+        lines.push("_None referenced._");
+    else
+        for (const d of input.docs)
+            lines.push(`- \`${d.path}\` (r${d.headRev}, ${d.ageLabel})`);
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Assemble a turn's context cheapest-first within a character budget. The brief
+ * (tier 0) always goes in; epoch summaries (tier 1) and the recent window (tier
+ * 2) fill the remaining budget and STOP. This is the hard token-efficiency
+ * rule: a turn's cost scales with the budget, never with the room's history.
+ */
+export function assembleTieredContext(input, budgetChars = 8000) {
+    const parts = [];
+    const includedTiers = [];
+    let used = 0;
+    const brief = input.brief?.trim();
+    if (brief) {
+        parts.push(`## Room brief\n${brief}`);
+        includedTiers.push("brief");
+        used += brief.length;
+    }
+    const epochs = input.epochSummaries ?? [];
+    if (epochs.length > 0 && used < budgetChars) {
+        const chosen = [];
+        for (const e of epochs) {
+            if (used + e.length > budgetChars)
+                break;
+            chosen.push(e);
+            used += e.length;
+        }
+        if (chosen.length > 0) {
+            parts.push(`## Earlier context\n${chosen.join("\n")}`);
+            includedTiers.push("epochs");
+        }
+    }
+    // Freshest-first fill shared by both message tiers: take lines from the
+    // end (newest) until the budget fills, keeping oldest-to-newest order.
+    const fillFreshest = (lines) => {
+        const chosen = [];
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i];
+            if (used + line.length > budgetChars)
+                break;
+            chosen.unshift(line);
+            used += line.length;
+        }
+        return chosen;
+    };
+    const topic = input.topicWindow;
+    if (topic && topic.lines.length > 0 && used < budgetChars) {
+        const chosen = fillFreshest(topic.lines);
+        if (chosen.length > 0) {
+            parts.push(`## Recent messages in this topic: ⌗ ${topic.name}\n${chosen.join("\n")}`);
+            includedTiers.push("topic");
+        }
+    }
+    const recent = input.recentWindow ?? [];
+    if (recent.length > 0 && used < budgetChars) {
+        const chosen = fillFreshest(recent);
+        if (chosen.length > 0) {
+            // When a topic slice rides above, say plainly what this wider window is.
+            const header = input.topicWindow
+                ? "## Recent messages across the channel (all topics)"
+                : "## Recent messages";
+            parts.push(`${header}\n${chosen.join("\n")}`);
+            includedTiers.push("recent");
+        }
+    }
+    return { text: parts.join("\n\n"), includedTiers, usedChars: used };
+}
+/**
+ * Render history entries as prompt lines for the recent-window tier:
+ * `[seq] @handle: text`, one line per message, whitespace-flattened and
+ * clamped. The bracketed seq is the message's address: it is what
+ * om://msg/<room>/<seq> citations and room_history paging key on.
+ */
+export function renderRecentWindow(entries, opts = {}) {
+    const clamp = Math.max(16, opts.clampChars ?? 240);
+    return entries.map((entry) => {
+        const handle = entry.handle.replace(/^@+/, "") || "unknown";
+        if (entry.sealed) {
+            return `[${entry.seq}] @${handle}${entry.isAgent ? "✦" : ""}: 🔒 sealed message (encrypted; content not available)`;
+        }
+        const flat = entry.text.replace(/\s+/g, " ").trim();
+        const text = flat.length > clamp ? `${flat.slice(0, clamp - 1)}…` : flat;
+        return `[${entry.seq}] @${handle}${entry.isAgent ? "✦" : ""}: ${text}`;
+    });
+}

package/dist/agent/sidebar-model.d.ts

@@ -0,0 +1,86 @@
+import type { RoomMeta, RoomSpace } from "../types.js";
+/**
+ * Navigation data for the Discord-style sidebar: rooms grouped by space,
+ * DM conversations, and a heat-ranked "popular" tail of unjoined rooms.
+ *
+ * Unread semantics:
+ *  - Rooms the user has OPEN (a live context) are authoritative: the live
+ *    context's counter is injected and always wins.
+ *  - Unjoined rooms diff the server head sequence (headSeq, attached by the
+ *    backend room lists) against the user's read cursor. Missing data means
+ *    no badge, never a guess.
+ */
+export interface SidebarRoom {
+    name: string;
+    title: string;
+    spaceId: string | null;
+    category: string | null;
+    sortOrder: number;
+    access: RoomMeta["access"];
+    online: number;
+    heatScore: number;
+    headSeq: number | null;
+    lastReadSeq: number | null;
+    unread: number;
+    joined: boolean;
+    /** Topics dial from room meta. Absent reads as "allowed" since the
+     *  2026-07-12 dial-default flip; explicit "off" keeps topics inert. */
+    topicsPolicy: RoomMeta["topicsPolicy"] | null;
+}
+export interface SidebarDm {
+    username: string;
+    unread: number;
+}
+export interface SidebarSnapshot {
+    spaces: Array<{
+        space: RoomSpace;
+        rooms: SidebarRoom[];
+    }>;
+    unspaced: SidebarRoom[];
+    dms: SidebarDm[];
+    popular: SidebarRoom[];
+    globalReplyUnread: number;
+    fetchedAt: number;
+}
+export declare const EMPTY_SIDEBAR_SNAPSHOT: SidebarSnapshot;
+export declare function computeRoomUnread(input: {
+    joinedUnread: number | null;
+    headSeq: number | null;
+    lastReadSeq: number | null;
+}): number;
+export declare function buildSidebarSnapshot(input: {
+    rooms: RoomMeta[];
+    spaces: RoomSpace[];
+    readState: Record<string, number>;
+    dms: SidebarDm[];
+    globalReplyUnread: number;
+    joinedUnread: (roomName: string) => number | null;
+    now: number;
+}): SidebarSnapshot;
+export interface SidebarModelDeps {
+    fetchRooms: () => Promise<RoomMeta[]>;
+    fetchSpaces: () => Promise<RoomSpace[]>;
+    fetchReadState: (roomNames: string[]) => Promise<Record<string, number>>;
+    fetchDms: () => Promise<SidebarDm[]>;
+    fetchGlobalReplyUnread: () => Promise<number>;
+    joinedUnread: (roomName: string) => number | null;
+    now?: () => number;
+}
+export declare class SidebarModel {
+    private readonly deps;
+    private snapshotValue;
+    private inflight;
+    private readonly listeners;
+    constructor(deps: SidebarModelDeps);
+    snapshot(): SidebarSnapshot;
+    onUpdate(listener: () => void): () => void;
+    /**
+     * Post-mutation refresh: if a poll-triggered load is already in flight it
+     * may predate the caller's writes, so wait it out and load AGAIN. Readers
+     * keep using the coalescing refresh(); writers use this barrier.
+     */
+    refreshAfterWrite(): Promise<SidebarSnapshot>;
+    /** Single-flight refresh; failures keep the previous snapshot. */
+    refresh(): Promise<SidebarSnapshot>;
+    private load;
+}

package/dist/agent/sidebar-model.js

@@ -0,0 +1,162 @@
+export const EMPTY_SIDEBAR_SNAPSHOT = {
+    spaces: [],
+    unspaced: [],
+    dms: [],
+    popular: [],
+    globalReplyUnread: 0,
+    fetchedAt: 0,
+};
+const POPULAR_MAX = 6;
+export function computeRoomUnread(input) {
+    if (input.joinedUnread !== null)
+        return Math.max(0, input.joinedUnread);
+    if (input.headSeq === null || input.headSeq <= 0)
+        return 0;
+    if (input.lastReadSeq === null)
+        return 0;
+    return Math.max(0, input.headSeq - input.lastReadSeq);
+}
+export function buildSidebarSnapshot(input) {
+    const toSidebarRoom = (room) => {
+        const name = room.name;
+        const joinedUnread = input.joinedUnread(name);
+        const headSeq = typeof room.headSeq === "number" ? room.headSeq : null;
+        const lastReadSeq = Object.hasOwn(input.readState, name) ? (input.readState[name] ?? 0) : null;
+        return {
+            name,
+            title: room.title || `#${name}`,
+            spaceId: room.spaceId ?? null,
+            category: room.category ?? null,
+            sortOrder: room.sortOrder ?? 0,
+            access: room.access,
+            online: room.onlineCount ?? room.heat?.onlineCount ?? 0,
+            heatScore: room.heat?.score ?? 0,
+            headSeq,
+            lastReadSeq,
+            unread: computeRoomUnread({ joinedUnread, headSeq, lastReadSeq }),
+            // Joined = an open context OR a server read cursor (you only get a
+            // cursor by having been in the room). This is what decides whether a
+            // room lives in your channel tree or in the POPULAR discovery shelf.
+            joined: joinedUnread !== null || lastReadSeq !== null,
+            topicsPolicy: room.topicsPolicy ?? null,
+        };
+    };
+    const rooms = input.rooms.map(toSidebarRoom);
+    const bySpace = new Map();
+    const unspaced = [];
+    for (const room of rooms) {
+        if (room.spaceId) {
+            const list = bySpace.get(room.spaceId) ?? [];
+            list.push(room);
+            bySpace.set(room.spaceId, list);
+        }
+        else {
+            unspaced.push(room);
+        }
+    }
+    const knownSpaces = new Map(input.spaces.map((space) => [space.spaceId, space]));
+    const spaces = [];
+    // Your servers render even when empty: a freshly created server must be
+    // visible and enterable immediately, not appear only once it has rooms.
+    for (const space of input.spaces) {
+        if (!space.joined)
+            continue;
+        spaces.push({ space, rooms: bySpace.get(space.spaceId) ?? [] });
+        bySpace.delete(space.spaceId);
+    }
+    for (const [spaceId, spaceRooms] of bySpace) {
+        const space = knownSpaces.get(spaceId) ?? {
+            spaceId,
+            name: spaceId,
+            ownerUserId: "",
+            createdAt: "",
+        };
+        spaces.push({ space, rooms: spaceRooms });
+    }
+    // Discord-stable server order: creation time, never name. Names arrive
+    // late for spaces synthesized from room leftovers, and sorting by them
+    // made the rail reshuffle mid-session. Unknown createdAt sorts last,
+    // deterministically by id.
+    const createdKey = (space) => {
+        const at = new Date(space.createdAt).getTime();
+        return Number.isFinite(at) && at > 0 ? at : Number.MAX_SAFE_INTEGER;
+    };
+    spaces.sort((a, b) => createdKey(a.space) - createdKey(b.space) || a.space.spaceId.localeCompare(b.space.spaceId));
+    const popular = rooms
+        .filter((room) => !room.joined)
+        .sort((a, b) => b.heatScore - a.heatScore || b.online - a.online)
+        .slice(0, POPULAR_MAX);
+    return {
+        spaces,
+        unspaced,
+        dms: input.dms,
+        popular,
+        globalReplyUnread: Math.max(0, input.globalReplyUnread),
+        fetchedAt: input.now,
+    };
+}
+export class SidebarModel {
+    deps;
+    snapshotValue = EMPTY_SIDEBAR_SNAPSHOT;
+    inflight = null;
+    listeners = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    snapshot() {
+        return this.snapshotValue;
+    }
+    onUpdate(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Post-mutation refresh: if a poll-triggered load is already in flight it
+     * may predate the caller's writes, so wait it out and load AGAIN. Readers
+     * keep using the coalescing refresh(); writers use this barrier.
+     */
+    async refreshAfterWrite() {
+        if (this.inflight)
+            await this.inflight.catch(() => undefined);
+        return this.refresh();
+    }
+    /** Single-flight refresh; failures keep the previous snapshot. */
+    refresh() {
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.load()
+            .then((snapshot) => {
+            this.snapshotValue = snapshot;
+            for (const listener of this.listeners)
+                listener();
+            return snapshot;
+        })
+            .catch(() => this.snapshotValue)
+            .finally(() => {
+            this.inflight = null;
+        });
+        return this.inflight;
+    }
+    async load() {
+        const [rooms, spaces, dms, globalReplyUnread] = await Promise.all([
+            this.deps.fetchRooms(),
+            this.deps.fetchSpaces().catch(() => []),
+            this.deps.fetchDms().catch(() => []),
+            this.deps.fetchGlobalReplyUnread().catch(() => 0),
+        ]);
+        const readState = await this.deps
+            .fetchReadState(rooms.map((room) => room.name))
+            .catch(() => ({}));
+        return buildSidebarSnapshot({
+            rooms,
+            spaces,
+            readState,
+            dms,
+            globalReplyUnread,
+            joinedUnread: this.deps.joinedUnread,
+            now: (this.deps.now ?? Date.now)(),
+        });
+    }
+}

package/dist/agent/topic-inbox.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+import type { RoomTopic, RoomTopicAttention, RoomTopicBucketState, RoomTopicsResultPayload } from "../shared/rooms-protocol.js";
+/** The reserved bucket key for untopicked (linear) messages. */
+export declare const UNTOPICKED_BUCKET = "";
+export interface TopicInboxItem {
+    /** Bucket key: a topicId, or UNTOPICKED_BUCKET for the linear lane. */
+    key: string;
+    /** The registry row; undefined for the untopicked bucket. */
+    topic: RoomTopic | undefined;
+    state: RoomTopicBucketState;
+    /** Unread rolled up from merged-away alias buckets (survivors only). */
+    aliasUnread: number;
+}
+export interface TopicInboxEntry {
+    seq: number;
+    userId: string;
+    topicId?: string | undefined;
+}
+export declare class RoomTopicInbox {
+    readonly room: string;
+    /** True once a withState hydration has landed; counts are trustworthy. */
+    hydrated: boolean;
+    headSeq: number;
+    private readonly topics;
+    private readonly buckets;
+    constructor(room: string);
+    /** 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: Pick<RoomTopicsResultPayload, "topics" | "state" | "headSeq">): void;
+    topicFor(topicId: string): RoomTopic | undefined;
+    /** 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: string): string;
+    /** Merged-away buckets whose survivor is the given topic. */
+    aliasesOf(topicId: string): string[];
+    /** Registry rows in listed (creation) order, husks excluded. */
+    openTopics(options?: {
+        includeResolved?: boolean;
+    }): RoomTopic[];
+    bucketFor(key: string): RoomTopicBucketState;
+    /** 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(): Array<{
+        key: string;
+        lastSeq: number;
+    }>;
+    attentionFor(topicId: string): RoomTopicAttention;
+    /** A registry mutation arrived (TOPIC_UPDATED, or a verb result echo). */
+    applyTopicUpdated(topic: RoomTopic): void;
+    /**
+     * 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: TopicInboxEntry, context: {
+        selfUserId: string;
+        viewedKey?: string | null;
+    }): void;
+    /** Mirror an attention change (a TOPIC_SET_ATTENTION result, optimistic
+     *  or confirmed). */
+    applyAttention(topicId: string, attention: RoomTopicAttention): void;
+    /**
+     * 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: string, seq: number): void;
+    /**
+     * 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(): number;
+    /**
+     * 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(): TopicInboxItem[];
+    /**
+     * 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?: string | null): string | null;
+}