@opengeni/react 4.4.1 → 4.5.1-canary.39832248373001

package/src/app/lib/session-failure-toasts.ts

@@ -0,0 +1,26 @@
+import { useEffect } from "react";
+
+import { isApiErrorStatus } from "./app-api";
+import { toast } from "./toast";
+
+/**
+ * Toast the session page's read failures, once per error. The read hooks keep
+ * transient failures (a rolling deploy, a network blip) quiet while they retry
+ * and keep one stable error per outage, so an error reaches here only when it
+ * is definitive or outlasted the quiet window. A 404 renders the unavailable
+ * route instead of a toast.
+ */
+export function useSessionFailureToasts(loadError: Error | null, streamError: Error | null): void {
+  useEffect(() => {
+    if (streamError && !isApiErrorStatus(streamError, 404)) {
+      toast.error("Event stream disconnected", {
+        description: streamError.message,
+      });
+    }
+  }, [streamError]);
+  useEffect(() => {
+    if (loadError && !isApiErrorStatus(loadError, 404)) {
+      toast.error("Failed to load session", { description: String(loadError) });
+    }
+  }, [loadError]);
+}

package/src/app/lib/session-ui-features.tsx

@@ -19,15 +19,27 @@ export type SessionUiFeatures = Readonly<{
    * chat, ⌘/Ctrl+K, next and previous chat, the shortcut sheet).
    */
   keyboardShortcuts: boolean;
-  /** The Opengeni logo and wordmark at the top of the chat list. */
+  /** The Opengeni logo and wordmark at the top of the chat list and the mobile header. */
   brand: boolean;
+  /**
+   * Opengeni's suggested first tasks under the new-chat composer (connect
+   * Slack, GitHub or Linear, schedule a brief, and so on).
+   */
+  starters: boolean;
 }>;
 
 export type SessionUiPreset = "app" | "companion" | "embed";
 
 export const SESSION_UI_PRESETS: Readonly<Record<SessionUiPreset, SessionUiFeatures>> = {
   /** The web app and the desktop app. */
-  app: { chatList: true, dock: true, adminAccess: true, keyboardShortcuts: true, brand: true },
+  app: {
+    chatList: true,
+    dock: true,
+    adminAccess: true,
+    keyboardShortcuts: true,
+    brand: true,
+    starters: true,
+  },
   /**
    * First-party side panes (the Excel add-in): everything but admin access and
    * page-wide keyboard shortcuts.
@@ -38,11 +50,12 @@ export const SESSION_UI_PRESETS: Readonly<Record<SessionUiPreset, SessionUiFeatu
     adminAccess: false,
     keyboardShortcuts: false,
     brand: true,
+    starters: true,
   },
   /**
    * A customer product page (the default): the chat list, chats and composer,
-   * without Opengeni's brand, the session panel, admin access or page-wide
-   * shortcuts until the host turns them on.
+   * without Opengeni's brand and suggested tasks, the session panel, admin
+   * access or page-wide shortcuts until the host turns them on.
    */
   embed: {
     chatList: true,
@@ -50,6 +63,7 @@ export const SESSION_UI_PRESETS: Readonly<Record<SessionUiPreset, SessionUiFeatu
     adminAccess: false,
     keyboardShortcuts: false,
     brand: false,
+    starters: false,
   },
 };
 

package/src/app/lib/sessions-group.tsx

@@ -7,7 +7,7 @@ import { formatWaitingSince } from "./format";
 import { awaitsPerson } from "./needs-you";
 import { sessionInputWait } from "./session-rail";
 import { sessionSiteOrigin, type SessionSiteOrigin } from "./session-site-origin";
-import type { SessionListTotals } from "@opengeni/sdk";
+import type { SessionListTotals, SiteConversationGroup } from "@opengeni/sdk";
 import type { RailSession as Session } from "./session-list-entry";
 
 // The flat list rules are shared with native renderers through the pure
@@ -54,6 +54,11 @@ export {
 export type SessionTreeNode = {
   /** Presentation-only group; never persisted or used for session actions. */
   siteGroup?: SessionSiteOrigin | undefined;
+  /**
+   * A Site row's complete server counts, independent of which conversations
+   * are loaded. Absent when the row was built from loaded conversations only.
+   */
+  siteSummary?: SiteRowSummary | undefined;
   session: Session;
   children: SessionTreeNode[];
   /** A descendant (any depth, not the node itself) is running/queued/awaiting action. */
@@ -189,6 +194,26 @@ function railStatusCounts(
   node: SessionTreeNode,
   localDeliveryAttention: ReadonlyMap<string, number>,
 ): RailStatusCounts {
+  if (node.siteGroup && node.siteSummary) {
+    // Complete server counts; loaded rows add only browser-local send failures.
+    const summary = node.siteSummary;
+    const waiting = Math.min(summary.waiting, summary.active);
+    return {
+      total: summary.total,
+      sendFailed: node.children.reduce(
+        (total, child) => total + loadedLocalDeliveryFailureCount(child, localDeliveryAttention),
+        0,
+      ),
+      attention: summary.attention,
+      attentionSince: summary.attentionSince,
+      failed: summary.failed,
+      active: summary.active - waiting,
+      queued: summary.queued,
+      waiting,
+      unread: summary.unread,
+      activeWork: summary.activeWork,
+    };
+  }
   if (node.siteGroup) {
     const counts = ownRailStatusCounts(node.session, localDeliveryAttention);
     for (const key of [
@@ -773,37 +798,188 @@ export function groupScheduledRuns(roots: SessionTreeNode[]): SessionTreeNode[]
   return grouped;
 }
 
-/** Explicit project placement wins; pins have already been split out. */
-export function groupSiteConversations(roots: SessionTreeNode[]): SessionTreeNode[] {
-  const groups = new Map<string, SessionTreeNode[]>();
+export type SiteRowSummary = Omit<SiteConversationGroup, "siteId" | "channelId" | "title">;
+
+/**
+ * A Site row's stable id. Rows are per project when the rail shows projects,
+ * so a Site used from two projects appears in each; otherwise one per Site.
+ */
+export function siteRowKey(siteId: string, channelId?: string | null): string {
+  return channelId === undefined ? `site:${siteId}` : `site:${siteId}:${channelId ?? "default"}`;
+}
+
+/** The Site and project a Site row stands for, or null for an ordinary id. */
+export function parseSiteRowKey(
+  key: string,
+): { siteId: string; channelId?: string | null | undefined } | null {
+  const match = /^site:([0-9a-f-]{36})(?::(.+))?$/iu.exec(key);
+  if (!match) return null;
+  const channel = match[2];
+  return channel === undefined
+    ? { siteId: match[1]! }
+    : { siteId: match[1]!, channelId: channel === "default" ? null : channel };
+}
+
+function laterIso(a: string, b: string | undefined): string {
+  if (!b) return a;
+  return Date.parse(b) > Date.parse(a) ? b : a;
+}
+
+/** Merge per-project server groups into one per Site for rails without projects. */
+function siteRowSummaries(
+  groups: readonly SiteConversationGroup[],
+  byProject: boolean,
+): Map<string, { origin: SessionSiteOrigin; channelId: string | null; summary: SiteRowSummary }> {
+  const rows = new Map<
+    string,
+    { origin: SessionSiteOrigin; channelId: string | null; summary: SiteRowSummary }
+  >();
+  for (const group of groups) {
+    const key = siteRowKey(group.siteId, byProject ? group.channelId : undefined);
+    const { siteId, channelId, title, ...summary } = group;
+    const current = rows.get(key);
+    if (!current) {
+      // A Site this viewer cannot read and that kept no label still needs a name.
+      const origin = { siteId, title: title.trim() || "Untitled Site" };
+      rows.set(key, { origin, channelId, summary: { ...summary } });
+      continue;
+    }
+    const merged = current.summary;
+    for (const field of [
+      "conversations",
+      "total",
+      "attention",
+      "failed",
+      "active",
+      "queued",
+      "waiting",
+      "unread",
+      "activeWork",
+    ] as const)
+      merged[field] += summary[field];
+    merged.attentionSince = earliestIso(merged.attentionSince, summary.attentionSince);
+    merged.updatedAt = laterIso(merged.updatedAt, summary.updatedAt);
+    merged.createdAt = laterIso(merged.createdAt, summary.createdAt);
+  }
+  return rows;
+}
+
+/** The presentation-only row a Site's conversations nest under. */
+function siteRowSession(
+  key: string,
+  origin: SessionSiteOrigin,
+  channelId: string | null,
+  latest: Session | undefined,
+  summary: SiteRowSummary | undefined,
+  options: { workspaceId?: string | undefined; creator?: Session["createdBy"] | undefined },
+): Session {
+  const updatedAt = laterIso(summary?.updatedAt ?? latest?.updatedAt ?? "", latest?.updatedAt);
+  const createdAt = laterIso(summary?.createdAt ?? latest?.createdAt ?? "", latest?.createdAt);
+  // Only the fields the rail reads for ordering, grouping and links. It is
+  // never sent to the server or used for a session action.
+  return {
+    id: key,
+    workspaceId: latest?.workspaceId ?? options.workspaceId ?? "",
+    accountId: latest?.accountId ?? "",
+    rootSessionId: key,
+    parentSessionId: null,
+    channelId,
+    status: "idle",
+    title: origin.title,
+    displayTitle: origin.title,
+    renameSeed: origin.title,
+    titleSource: "user",
+    createdBy: latest?.createdBy ?? options.creator ?? { kind: "subject", subjectId: "" },
+    effectiveControl: { state: "active" },
+    inputWait: null,
+    pinned: false,
+    pinnedAt: null,
+    archived: false,
+    archivedAt: null,
+    unread: false,
+    activelyWorking: false,
+    lastSequence: 0,
+    treeStats: undefined,
+    scheduledTaskId: null,
+    siteOrigin: origin,
+    metadata: { _opengeniSiteOrigin: origin },
+    createdAt,
+    updatedAt,
+  } as unknown as Session;
+}
+
+/**
+ * Fold Site conversations into stable Site rows. `groups` are the complete
+ * rows from the server; loaded conversations (an expanded Site, the open
+ * session, a legacy labelled chat) join their row, so which session is
+ * selected never decides whether a Site or its conversations are listed.
+ * Pins have already been split out.
+ */
+export function attachSiteRows(
+  roots: SessionTreeNode[],
+  options: {
+    groups?: readonly SiteConversationGroup[] | undefined;
+    /** Rows per project when the rail shows projects. */
+    byProject?: boolean | undefined;
+    workspaceId?: string | undefined;
+    creator?: Session["createdBy"] | undefined;
+  } = {},
+): SessionTreeNode[] {
+  const byProject = options.byProject ?? false;
+  const rows = new Map<
+    string,
+    {
+      origin: SessionSiteOrigin;
+      channelId: string | null;
+      summary?: SiteRowSummary | undefined;
+      members: SessionTreeNode[];
+    }
+  >();
+  for (const [key, row] of siteRowSummaries(options.groups ?? [], byProject))
+    rows.set(key, { ...row, members: [] });
+  const rest: SessionTreeNode[] = [];
   for (const node of roots) {
     const origin = sessionSiteOrigin(node.session);
-    if (!origin || node.session.channelId || node.session.parentSessionId) continue;
-    const members = groups.get(origin.siteId) ?? [];
-    members.push(node);
-    groups.set(origin.siteId, members);
+    if (!origin || node.session.parentSessionId) {
+      rest.push(node);
+      continue;
+    }
+    const channelId = node.session.channelId ?? null;
+    const key = siteRowKey(origin.siteId, byProject ? channelId : undefined);
+    const row = rows.get(key) ?? { origin, channelId, members: [] };
+    row.members.push(node);
+    rows.set(key, row);
   }
-  const emitted = new Set<string>();
-  return roots.flatMap((node) => {
-    const origin = sessionSiteOrigin(node.session);
-    const members =
-      origin && !node.session.channelId && !node.session.parentSessionId
-        ? groups.get(origin.siteId)
-        : undefined;
-    if (!members || !origin) return [node];
-    if (emitted.has(origin.siteId)) return [];
-    emitted.add(origin.siteId);
-    members.sort((a, b) => compareSessionActivity(a.session, b.session));
-    const latest = members[0]!;
-    return [
-      {
-        siteGroup: origin,
-        session: { ...latest.session, id: `site:${origin.siteId}`, treeStats: undefined },
-        children: members,
-        hasActiveDescendant: members.some(nodeIsActive),
-      },
-    ];
+  const siteRows = [...rows].map(([key, row]): SessionTreeNode => {
+    const members = row.members.sort((a, b) => compareSessionActivity(a.session, b.session));
+    const summary = row.summary;
+    return {
+      siteGroup: row.origin,
+      ...(summary ? { siteSummary: summary } : {}),
+      session: siteRowSession(
+        key,
+        row.origin,
+        row.channelId,
+        members[0]?.session,
+        summary,
+        options,
+      ),
+      children: members,
+      hasActiveDescendant:
+        members.some(nodeIsActive) ||
+        Boolean(summary && summary.active + summary.queued + summary.attention > 0),
+    };
   });
+  return [...rest, ...siteRows];
+}
+
+/**
+ * How many conversations a Site row stands for, loaded or not. The server
+ * counts Site conversations; an older chat that only carries a Site label
+ * joins the row when loaded, so the count can grow by those on expansion.
+ */
+export function siteRowConversationCount(node: SessionTreeNode): number {
+  return Math.max(node.siteSummary?.conversations ?? 0, node.children.length);
 }
 
 export function categorizeRailRoots(
@@ -1076,7 +1252,15 @@ export function projectRailSessions<T extends Session>(sessions: T[], hierarchyM
 export function buildPinnedRailSections(
   sessions: Session[],
   now: Date = new Date(),
-  options: { groupSites?: boolean | undefined } = {},
+  options: {
+    groupSites?: boolean | undefined;
+    /** Complete Site rows from a grouped root page. */
+    siteGroups?: readonly SiteConversationGroup[] | undefined;
+    /** Split Site rows by project (the rail's project view). */
+    siteRowsByProject?: boolean | undefined;
+    workspaceId?: string | undefined;
+    creator?: Session["createdBy"] | undefined;
+  } = {},
 ): PinnedRailSections {
   const complete = buildRailForest(sessions, now);
   const roots = forestRoots(complete);
@@ -1109,7 +1293,12 @@ export function buildPinnedRailSections(
     ordinary: categorizeRailRoots(
       options.groupSites === false
         ? groupScheduledRuns(ordinaryRoots)
-        : groupSiteConversations(groupScheduledRuns(ordinaryRoots)),
+        : attachSiteRows(groupScheduledRuns(ordinaryRoots), {
+            groups: options.siteGroups,
+            byProject: options.siteRowsByProject,
+            workspaceId: options.workspaceId,
+            creator: options.creator,
+          }),
       now,
     ),
   };

package/src/app/lib/site-opened.tsx

@@ -0,0 +1,48 @@
+import { useEffect } from "react";
+
+const SITE_OPENED_EVENT = "opengeni:site-opened";
+
+type SiteOpenedDetail = { workspaceId: string; siteId: string };
+
+/** Opening a Site in the app counts as activity on its sidebar row. */
+export function useRecordSiteOpened(
+  client: { recordSiteOpened?: (workspaceId: string, siteId: string) => Promise<unknown> },
+  workspaceId: string,
+  siteId: string,
+): void {
+  useEffect(() => {
+    if (typeof client.recordSiteOpened !== "function") return;
+    let current = true;
+    client
+      .recordSiteOpened(workspaceId, siteId)
+      .then(() => {
+        if (!current) return;
+        window.dispatchEvent(
+          new CustomEvent<SiteOpenedDetail>(SITE_OPENED_EVENT, { detail: { workspaceId, siteId } }),
+        );
+      })
+      // Ordering is a convenience: a server without it, or a failed write,
+      // leaves the Site and its row as they were.
+      .catch(() => undefined);
+    return () => {
+      current = false;
+    };
+  }, [client, workspaceId, siteId]);
+}
+
+/** Calls `onOpened` after this workspace records a Site open. */
+export function useSiteOpenedListener(
+  workspaceId: string,
+  onOpened: () => void,
+  enabled = true,
+): void {
+  useEffect(() => {
+    if (!enabled) return;
+    const listener = (event: Event) => {
+      const detail = (event as CustomEvent<SiteOpenedDetail>).detail;
+      if (detail?.workspaceId === workspaceId) onOpened();
+    };
+    window.addEventListener(SITE_OPENED_EVENT, listener);
+    return () => window.removeEventListener(SITE_OPENED_EVENT, listener);
+  }, [workspaceId, onOpened, enabled]);
+}

package/src/app/lib/site-session-groups.test.ts

@@ -1,8 +1,19 @@
 import { expect, test } from "bun:test";
-import { buildPinnedRailSections, summarizeRailNodes, visibleTreeRows } from "./sessions-group";
+import type { SiteConversationGroup } from "@opengeni/sdk";
+import {
+  buildPinnedRailSections,
+  channelRailSections,
+  parseSiteRowKey,
+  siteRowConversationCount,
+  siteRowKey,
+  summarizeRailNodes,
+  visibleTreeRows,
+  type SessionTreeNode,
+} from "./sessions-group";
 import type { Session } from "../types";
 
 const siteId = "11111111-1111-4111-8111-111111111111";
+const otherSiteId = "22222222-2222-4222-8222-222222222222";
 function session(id: string, patch: Partial<Session> = {}): Session {
   return {
     id,
@@ -36,17 +47,173 @@ test("Site group has stable identity, real children, aggregate activity and no d
   ).toEqual(["newer", "older"]);
   expect(running.parentSessionId).toBeNull();
 });
-test("projects and pins win, while Site origin survives and a single unfiled chat still groups", () => {
+function siteGroup(patch: Partial<SiteConversationGroup> = {}): SiteConversationGroup {
+  return {
+    siteId,
+    channelId: null,
+    title: "Analytics",
+    conversations: 3,
+    updatedAt: "2026-09-08T09:00:00.000Z",
+    createdAt: "2026-09-08T09:00:00.000Z",
+    total: 3,
+    attention: 0,
+    attentionSince: null,
+    failed: 0,
+    active: 0,
+    queued: 0,
+    waiting: 0,
+    unread: 0,
+    activeWork: 0,
+    ...patch,
+  };
+}
+
+function railRoots(result: ReturnType<typeof buildPinnedRailSections>): SessionTreeNode[] {
+  return [...result.ordinary.running, ...result.ordinary.grouped.flatMap((g) => g.sessions)];
+}
+
+test("pins win; projects split Site rows only when the rail shows projects", () => {
   const placed = session("project", { channelId: "project-id" });
   const pinned = session("pin", { pinned: true, pinnedAt: "2026-09-08T10:00:00Z" });
-  const result = buildPinnedRailSections([placed, pinned, session("unfiled")]);
+  const sessions = [placed, pinned, session("unfiled")];
+  const result = buildPinnedRailSections(sessions);
   expect(result.pinned.map((n) => n.session.id)).toEqual(["pin"]);
-  const roots = [...result.ordinary.running, ...result.ordinary.grouped.flatMap((g) => g.sessions)];
-  expect(roots.find((n) => n.session.id === "project")?.siteGroup).toBeUndefined();
-  expect(roots.find((n) => n.siteGroup)?.children.map((n) => n.session.id)).toEqual(["unfiled"]);
+  expect(
+    railRoots(result).map((n) => [n.session.id, n.children.map((c) => c.session.id).sort()]),
+  ).toEqual([[`site:${siteId}`, ["project", "unfiled"]]]);
+  const byProject = buildPinnedRailSections(sessions, new Date(), { siteRowsByProject: true });
+  const sections = channelRailSections(byProject.ordinary, [
+    { id: "project-id", name: "Project" } as never,
+  ]);
+  expect(
+    sections.map((section) => [
+      section.channelId,
+      section.sessions.map((n) => [n.session.id, n.children.map((c) => c.session.id)]),
+    ]),
+  ).toEqual(
+    expect.arrayContaining([
+      ["project-id", [[siteRowKey(siteId, "project-id"), ["project"]]]],
+      [null, [[siteRowKey(siteId, null), ["unfiled"]]]],
+    ]),
+  );
   expect(placed.metadata._opengeniSiteOrigin).toBeDefined();
 });
 
+test("Site rows are complete from the server and never depend on the open session", () => {
+  const ordinary = session("ordinary", {
+    metadata: {},
+    updatedAt: "2026-09-08T08:00:00Z",
+  });
+  const nested = session("nested", { updatedAt: "2026-09-08T09:00:00Z" });
+  const groups = [
+    siteGroup(),
+    siteGroup({ siteId: otherSiteId, title: "Budget", conversations: 1 }),
+  ];
+  const build = (loaded: Session[]) =>
+    railRoots(buildPinnedRailSections(loaded, new Date(), { siteGroups: groups }));
+  // The nested conversation is open: the route injects it into the rail.
+  const whileOpen = build([ordinary, nested]);
+  const site = whileOpen.find((n) => n.session.id === `site:${siteId}`)!;
+  expect(site.children.map((n) => n.session.id)).toEqual(["nested"]);
+  expect(siteRowConversationCount(site)).toBe(3);
+  expect(visibleTreeRows(whileOpen, new Set(), "nested").map((r) => r.node.session.id)).toContain(
+    "nested",
+  );
+  // Another session is selected, so the conversation is no longer injected.
+  // Both Sites keep their rows and counts; nothing appears at the top level.
+  const afterSelectingAnother = build([ordinary]);
+  expect(afterSelectingAnother.map((n) => n.session.id).sort()).toEqual(
+    ["ordinary", `site:${otherSiteId}`, `site:${siteId}`].sort(),
+  );
+  const stable = afterSelectingAnother.find((n) => n.session.id === `site:${siteId}`)!;
+  expect(stable.siteGroup).toEqual({ siteId, title: "Analytics" });
+  expect(siteRowConversationCount(stable)).toBe(3);
+  expect(
+    visibleTreeRows(afterSelectingAnother, new Set(), "ordinary").map((r) => r.node.session.id),
+  ).toEqual(["ordinary"]);
+  // Expanding lists the Site's loaded conversations under the same row.
+  const expanded = build([
+    ordinary,
+    nested,
+    session("older", { updatedAt: "2026-09-08T07:00:00Z" }),
+  ]);
+  expect(
+    visibleTreeRows(expanded, new Set([`site:${siteId}`]), "ordinary")
+      .map((r) => r.node.session.id)
+      .filter((id) => id !== "ordinary"),
+  ).toEqual(["nested", "older"]);
+});
+
+test("Site rows sort by activity among ordinary rows and summarize complete counts", () => {
+  const recent = session("recent", { metadata: {}, updatedAt: "2026-09-08T12:00:00Z" });
+  const old = session("old", { metadata: {}, updatedAt: "2026-09-08T06:00:00Z" });
+  const result = buildPinnedRailSections([recent, old], new Date("2026-09-08T13:00:00Z"), {
+    siteGroups: [siteGroup({ total: 4, unread: 2 })],
+  });
+  expect(railRoots(result).map((n) => n.session.id)).toEqual(["recent", `site:${siteId}`, "old"]);
+  const site = railRoots(result)[1]!;
+  expect(summarizeRailNodes([site])).toMatchObject({ kind: "unread", count: 2, total: 4 });
+  // Live or waiting conversations float their Site row with the running rows.
+  for (const live of [{ active: 1 }, { attention: 1, attentionSince: "2026-09-08T08:30:00Z" }]) {
+    const running = buildPinnedRailSections([recent], new Date(), {
+      siteGroups: [siteGroup(live)],
+    });
+    expect(running.ordinary.running.map((n) => n.session.id)).toEqual([`site:${siteId}`]);
+  }
+});
+
+test("a Site without conversations is a plain row in its creating chat's project", () => {
+  const chat = session("chat", {
+    metadata: {},
+    channelId: "project-id",
+    updatedAt: "2026-09-08T11:00:00Z",
+  });
+  const older = session("older", { metadata: {}, updatedAt: "2026-09-08T06:00:00Z" });
+  const created = siteGroup({
+    channelId: "project-id",
+    conversations: 0,
+    total: 0,
+    updatedAt: "2026-09-08T10:00:00Z",
+  });
+  const result = buildPinnedRailSections([chat, older], new Date("2026-09-08T13:00:00Z"), {
+    siteGroups: [created],
+    siteRowsByProject: true,
+  });
+  const sections = channelRailSections(result.ordinary, [
+    { id: "project-id", name: "Project" } as never,
+  ]);
+  const project = sections.find((section) => section.channelId === "project-id")!;
+  // Top-level beside the chat that made it, ordered by its own activity.
+  expect(project.sessions.map((n) => n.session.id)).toEqual([
+    "chat",
+    siteRowKey(siteId, "project-id"),
+  ]);
+  const site = project.sessions[1]!;
+  expect(site.children).toEqual([]);
+  expect(siteRowConversationCount(site)).toBe(0);
+  expect(summarizeRailNodes([site])).toMatchObject({ total: 0 });
+  // Opening it later is newer activity, so it moves above the chat.
+  const opened = buildPinnedRailSections([chat, older], new Date("2026-09-08T13:00:00Z"), {
+    siteGroups: [{ ...created, updatedAt: "2026-09-08T12:30:00Z" }],
+    siteRowsByProject: true,
+  });
+  expect(
+    channelRailSections(opened.ordinary, [{ id: "project-id", name: "Project" } as never])
+      .find((section) => section.channelId === "project-id")!
+      .sessions.map((n) => n.session.id),
+  ).toEqual([siteRowKey(siteId, "project-id"), "chat"]);
+});
+
+test("Site row keys round-trip their Site and project", () => {
+  expect(parseSiteRowKey(siteRowKey(siteId))).toEqual({ siteId });
+  expect(parseSiteRowKey(siteRowKey(siteId, null))).toEqual({ siteId, channelId: null });
+  expect(parseSiteRowKey(siteRowKey(siteId, "project-id"))).toEqual({
+    siteId,
+    channelId: "project-id",
+  });
+  expect(parseSiteRowKey(siteId)).toBeNull();
+});
+
 test("search and custom browse can keep matched conversations flat", () => {
   const result = buildPinnedRailSections([session("one"), session("two")], new Date(), {
     groupSites: false,

package/src/app/lib/site-view-routes.test.ts

@@ -0,0 +1,55 @@
+import { expect, test } from "bun:test";
+import { railRouteSelection, siteViewSearch, workspaceSitePath } from "./routes";
+
+const workspaceId = "11111111-1111-4111-8111-111111111111";
+const siteId = "22222222-2222-4222-8222-222222222222";
+const sessionId = "33333333-3333-4333-8333-333333333333";
+
+test("the rail marks a session page's session", () => {
+  expect(
+    railRouteSelection({
+      pathname: `/workspaces/${workspaceId}/sessions/${sessionId}`,
+      search: {},
+    }),
+  ).toEqual({ sessionId, siteId: null });
+});
+
+test("the rail marks a Site view's Site, and its selected conversation", () => {
+  const pathname = `/workspaces/${workspaceId}/sites/${siteId}`;
+  expect(railRouteSelection({ pathname, search: {} })).toEqual({ sessionId: null, siteId });
+  expect(railRouteSelection({ pathname, search: { conversation: sessionId } })).toEqual({
+    sessionId,
+    siteId,
+  });
+  // A malformed conversation selects nothing rather than an arbitrary row.
+  expect(railRouteSelection({ pathname, search: { conversation: "../x" } })).toEqual({
+    sessionId: null,
+    siteId,
+  });
+});
+
+test("other pages mark nothing", () => {
+  for (const pathname of [
+    `/workspaces/${workspaceId}/artifacts/${siteId}`,
+    `/workspaces/${workspaceId}/sites`,
+    `/workspaces/${workspaceId}/sites/${siteId}/extra`,
+    // Not a Site id, including a malformed escape that can't be decoded.
+    `/workspaces/${workspaceId}/sites/%E0`,
+    `/workspaces/${workspaceId}/sites/not-a-site`,
+  ])
+    expect(railRouteSelection({ pathname, search: { conversation: sessionId } })).toEqual({
+      sessionId: null,
+      siteId: null,
+    });
+});
+
+test("Site view links and search", () => {
+  expect(workspaceSitePath(workspaceId, siteId)).toBe(`/workspaces/${workspaceId}/sites/${siteId}`);
+  expect(workspaceSitePath(workspaceId, siteId, sessionId)).toBe(
+    `/workspaces/${workspaceId}/sites/${siteId}?conversation=${sessionId}`,
+  );
+  expect(siteViewSearch({ conversation: sessionId, other: 1 })).toEqual({
+    conversation: sessionId,
+  });
+  expect(siteViewSearch({ conversation: 42 })).toEqual({ conversation: undefined });
+});