@opengeni/react 4.4.1 → 4.5.1-canary.39832248373001

package/src/app/components/rail/session-row-content.tsx

@@ -110,12 +110,15 @@ export function RailTrailingMetadata({
   summary,
   scheduled = false,
   relativeTime,
+  jumpKey,
   creator,
   quickActionSlots = 0,
 }: {
   summary: RailAggregateStatus;
   scheduled?: boolean | undefined;
   relativeTime?: string | undefined;
+  /** The key that opens this row ("⌘3"), shown in place of the time while ⌘ is held. */
+  jumpKey?: string | undefined;
   /** Rightmost items replaced in place by the row's desktop quick actions. */
   quickActionSlots?: number | undefined;
   /**
@@ -135,7 +138,14 @@ export function RailTrailingMetadata({
     summary.kind === "needs_attention" && summary.attentionSince
       ? formatWaitingSince(summary.attentionSince)
       : "";
-  if (!scheduled && !hasStatusMarker && !hasRelativeTime && !hasMonogram && !quickActionSlots)
+  if (
+    !scheduled &&
+    !hasStatusMarker &&
+    !hasRelativeTime &&
+    !jumpKey &&
+    !hasMonogram &&
+    !quickActionSlots
+  )
     return null;
   const items = Children.toArray([
     scheduled ? (
@@ -163,7 +173,15 @@ export function RailTrailingMetadata({
         <RailAggregateDot summary={summary} />
       </span>
     ) : null,
-    hasRelativeTime ? (
+    jumpKey ? (
+      <kbd
+        key="time"
+        data-session-row-jump-key
+        className="inline-flex h-4.5 min-w-9 shrink-0 items-center justify-center rounded-[4px] border border-border bg-surface-2 px-1 font-sans text-2xs leading-none font-medium whitespace-nowrap text-fg-muted"
+      >
+        {jumpKey}
+      </kbd>
+    ) : hasRelativeTime ? (
       <span
         key="time"
         className="min-w-9 shrink-0 whitespace-nowrap text-right text-2xs tabular-nums text-fg"
@@ -213,6 +231,7 @@ export function SessionRowContent({
   summary,
   scheduled = false,
   relativeTime,
+  jumpKey,
   creator,
   quickActionSlots = 0,
 }: {
@@ -224,6 +243,8 @@ export function SessionRowContent({
   summary: RailAggregateStatus;
   scheduled?: boolean | undefined;
   relativeTime?: string | undefined;
+  /** See RailTrailingMetadata. */
+  jumpKey?: string | undefined;
   quickActionSlots?: number | undefined;
   /** Session creator for a top-level row, else null. See RailTrailingMetadata. */
   creator?: CreatorRef | null | undefined;
@@ -251,6 +272,7 @@ export function SessionRowContent({
         summary={summary}
         scheduled={scheduled}
         relativeTime={relativeTime}
+        jumpKey={jumpKey}
         creator={creator}
       />
     </>

package/src/app/components/rail/session-shell.tsx

@@ -415,6 +415,7 @@ function SessionShellFrame({ children }: { children: ReactNode }) {
 function CanvasTopStrip({ hamburgerRef }: { hamburgerRef: RefObject<HTMLButtonElement | null> }) {
   const rail = useRail();
   const chatList = useSessionUiFeature("chatList");
+  const brand = useSessionUiFeature("brand");
   const context = useAppContext();
   const pathname = useRouterState({
     select: (state) => state.location.pathname,
@@ -490,18 +491,22 @@ function CanvasTopStrip({ hamburgerRef }: { hamburgerRef: RefObject<HTMLButtonEl
     );
   }
 
-  // Mobile, off a session route: the slim brand strip.
+  // Mobile, off a session route: the slim brand strip. A host without
+  // Opengeni's brand keeps only the menu button, or no strip at all.
+  if (!brand && !hamburger) return null;
   return (
     <header className="flex h-12 shrink-0 items-center gap-3 border-b border-border bg-canvas/75 px-3 backdrop-blur sm:px-4">
       {hamburger}
-      <Link
-        to="/workspaces/$workspaceId/sessions"
-        params={{ workspaceId: rail.workspaceId }}
-        className="flex items-center gap-2 text-fg"
-      >
-        <BrandMark className="w-5" />
-        <Wordmark className="text-[17px]" />
-      </Link>
+      {brand ? (
+        <Link
+          to="/workspaces/$workspaceId/sessions"
+          params={{ workspaceId: rail.workspaceId }}
+          className="flex items-center gap-2 text-fg"
+        >
+          <BrandMark className="w-5" />
+          <Wordmark className="text-[17px]" />
+        </Link>
+      ) : null}
     </header>
   );
 }

package/src/app/components/rail/site-session-group-heading.tsx

@@ -1,46 +1,85 @@
 import { Link } from "../../lib/navigation";
-import { ChevronDownIcon, ChevronRightIcon, PanelsTopLeftIcon } from "lucide-react";
+import { ChevronRightIcon, PanelsTopLeftIcon } from "lucide-react";
 import { RailTrailingMetadata } from "./session-row-content";
+import { cn } from "../../lib/utils";
+import { visualTreeDepth } from "../../lib/session-rail";
 import type { RailAggregateStatus } from "../../lib/sessions-group";
 import type { SessionSiteOrigin } from "../../lib/session-site-origin";
 
+/** A Site's row in the rail: open the Site view, or disclose its conversations. */
 export function SiteSessionGroupHeading({
   origin,
   workspaceId,
   expanded,
   onToggle,
   summary,
+  count,
+  relativeTime,
+  depth = 0,
+  active = false,
 }: {
   origin: SessionSiteOrigin;
   workspaceId: string;
   expanded: boolean;
   onToggle: () => void;
   summary: RailAggregateStatus;
+  /** Conversations behind the row, loaded or not. */
+  count: number;
+  relativeTime?: string | undefined;
+  depth?: number | undefined;
+  active?: boolean | undefined;
 }) {
+  const conversations = `${count} ${count === 1 ? "conversation" : "conversations"}`;
+  // A Site without conversations is a plain row: nothing to disclose.
+  const disclosable = count > 0 || expanded;
   return (
-    <div className="flex min-h-8 items-center gap-1 rounded-md px-1 hover:bg-hover">
-      <button
-        type="button"
-        aria-label={`${expanded ? "Collapse" : "Expand"} conversations from ${origin.title}`}
-        aria-expanded={expanded}
-        onClick={onToggle}
-        className="flex size-7 shrink-0 items-center justify-center rounded focus-visible:ring-2 focus-visible:ring-accent"
+    <div
+      data-site-row={origin.siteId}
+      className={cn(
+        "group relative flex h-8 w-full items-center gap-1.5 rounded-md border py-1 pr-1 pl-1.5 text-left text-sm pointer-coarse:h-11 pointer-coarse:py-0",
+        active
+          ? "border-brand/20 bg-selection text-fg"
+          : "border-transparent text-fg-label hover:bg-hover hover:text-fg",
+      )}
+    >
+      <span
+        className="flex w-4 shrink-0 items-center"
+        style={depth > 0 ? { marginLeft: visualTreeDepth(depth) * 12 } : undefined}
       >
-        {expanded ? (
-          <ChevronDownIcon className="size-3" />
-        ) : (
-          <ChevronRightIcon className="size-3" />
-        )}
-      </button>
+        {disclosable ? (
+          <button
+            type="button"
+            aria-label={`${expanded ? "Collapse" : "Expand"} ${conversations} from ${origin.title}`}
+            aria-expanded={expanded}
+            onClick={onToggle}
+            className="flex h-4 w-4 shrink-0 items-center justify-center rounded text-fg-muted outline-hidden hover:text-fg focus-visible:ring-1 focus-visible:ring-ring pointer-coarse:h-11 pointer-coarse:w-11"
+          >
+            <ChevronRightIcon
+              className={cn("size-3 shrink-0 transition-transform", expanded && "rotate-90")}
+            />
+          </button>
+        ) : null}
+      </span>
       <Link
-        className="flex min-w-0 flex-1 items-center gap-1.5 text-sm focus-visible:ring-2 focus-visible:ring-accent"
-        to="/workspaces/$workspaceId/artifacts/$artifactId"
-        params={{ workspaceId, artifactId: origin.siteId }}
+        to="/workspaces/$workspaceId/sites/$siteId"
+        params={{ workspaceId, siteId: origin.siteId }}
+        // The Site is the open page only while none of its conversations is.
+        activeOptions={{ exact: true, includeSearch: true }}
+        aria-current={active ? "page" : undefined}
+        // Without conversations there is no status to announce.
+        aria-label={`Open ${origin.title}. Site${count > 0 ? `, ${conversations}. ${summary.label}` : ""}`}
+        className="flex h-full min-w-0 flex-1 items-center gap-1.5 rounded-sm outline-hidden focus-visible:ring-2 focus-visible:ring-ring/40 focus-visible:ring-offset-1 focus-visible:ring-offset-surface"
       >
-        <PanelsTopLeftIcon className="size-3.5 shrink-0" aria-hidden="true" />
-        <span className="truncate">{origin.title}</span>
+        <PanelsTopLeftIcon aria-hidden="true" className="size-3.5 shrink-0 text-fg-muted" />
+        <span className="min-w-0 truncate">{origin.title}</span>
+        {count > 0 ? (
+          <span aria-hidden="true" className="shrink-0 text-xs tabular-nums text-fg-subtle">
+            {count}
+          </span>
+        ) : null}
+        <span className="min-w-0 flex-1" />
+        <RailTrailingMetadata summary={summary} relativeTime={relativeTime} />
       </Link>
-      <RailTrailingMetadata summary={summary} />
     </div>
   );
 }

package/src/app/components/session/session-tenancy-control.tsx

@@ -1,4 +1,5 @@
 import type { OpenGeniBrowserClient } from "@opengeni/sdk/browser";
+import { isTransientRequestError } from "@opengeni/sdk";
 import type {
   Session,
   SessionEvent,
@@ -85,12 +86,29 @@ export default function SessionRouteAuxiliary(
         workspaceId: string;
         sessionId: string;
         loadError: unknown;
+        /** Retry the session read now (it also keeps retrying in the background). */
+        onRetry?: (() => void) | undefined;
         session?: never | undefined;
         events?: never | undefined;
       },
 ) {
   return props.session ? (
     <SessionTenancyRouteControl session={props.session} events={props.events} />
+  ) : isTransientRequestError(props.loadError) ? (
+    // The session read has failed transiently for a while (an outage outlasting
+    // a rolling deploy). The read keeps retrying and the page opens the session
+    // on its own when it succeeds.
+    <ProblemPanel
+      title="Temporarily unavailable"
+      description="Retrying automatically."
+      action={
+        props.onRetry ? (
+          <Button type="button" variant="outline" onClick={props.onRetry}>
+            Try again
+          </Button>
+        ) : undefined
+      }
+    />
   ) : !isApiErrorStatus(props.loadError, 404) ? (
     <ProblemPanel
       title="Unable to open session"

package/src/app/components/session/site-origin-link.test.tsx

@@ -0,0 +1,73 @@
+import { afterAll, beforeAll, expect, mock, test } from "bun:test";
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+import type { ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import type { Session } from "../../types";
+
+const workspaceId = "11111111-1111-4111-8111-111111111111";
+const siteId = "22222222-2222-4222-8222-222222222222";
+const sessionId = "33333333-3333-4333-8333-333333333333";
+
+mock.module("../../lib/navigation", () => ({
+  Link: ({
+    children,
+    to,
+    params,
+    search,
+  }: {
+    children: ReactNode;
+    to: string;
+    params: Record<string, string>;
+    search?: Record<string, string>;
+  }) => <a href={JSON.stringify({ to, params, search: search ?? null })}>{children}</a>,
+}));
+
+let module: typeof import("./site-origin-link");
+let ownsDom = false;
+beforeAll(async () => {
+  ownsDom = !GlobalRegistrator.isRegistered;
+  if (ownsDom) GlobalRegistrator.register({ url: "https://example.test" });
+  module = await import("./site-origin-link");
+});
+afterAll(async () => {
+  if (ownsDom) await GlobalRegistrator.unregister();
+});
+
+const session = (parentSessionId: string | null) =>
+  ({
+    id: sessionId,
+    workspaceId,
+    parentSessionId,
+    metadata: { _opengeniSiteOrigin: { siteId, title: "Opengeni usage" } },
+  }) as unknown as Session;
+const target = (markup: string) => {
+  const container = document.createElement("div");
+  container.innerHTML = markup;
+  return JSON.parse(container.querySelector("a")!.getAttribute("href")!);
+};
+
+test("a Site's own conversation opens the Site with it selected", () => {
+  expect(target(renderToStaticMarkup(<module.SiteOriginLink session={session(null)} />))).toEqual({
+    to: "/workspaces/$workspaceId/sites/$siteId",
+    params: { workspaceId, siteId },
+    search: { conversation: sessionId },
+  });
+});
+
+test("a session spawned inside one opens the Site without selecting it", () => {
+  expect(
+    target(renderToStaticMarkup(<module.SiteOriginLink session={session(sessionId)} />)),
+  ).toEqual({
+    to: "/workspaces/$workspaceId/sites/$siteId",
+    params: { workspaceId, siteId },
+    search: null,
+  });
+});
+
+test("a session that didn't start in a Site has no link", () => {
+  expect(
+    renderToStaticMarkup(
+      <module.SiteOriginLink session={{ ...session(null), metadata: {} } as Session} />,
+    ),
+  ).toBe("");
+});

package/src/app/components/session/site-origin-link.tsx

@@ -2,6 +2,7 @@ import { Link } from "../../lib/navigation";
 import { PanelsTopLeftIcon } from "lucide-react";
 import { sessionSiteOrigin } from "../../lib/session-site-origin";
 import type { RailSession as Session } from "../../lib/session-list-entry";
+/** Where a session came from: opens its Site view with this conversation selected. */
 export function SiteOriginLink({
   session,
   compact = false,
@@ -13,8 +14,9 @@ export function SiteOriginLink({
   if (!origin) return null;
   return (
     <Link
-      to="/workspaces/$workspaceId/artifacts/$artifactId"
-      params={{ workspaceId: session.workspaceId, artifactId: origin.siteId }}
+      to="/workspaces/$workspaceId/sites/$siteId"
+      params={{ workspaceId: session.workspaceId, siteId: origin.siteId }}
+      search={session.parentSessionId === null ? { conversation: session.id } : undefined}
       title={`Created through ${origin.title}`}
       aria-label={`Created through ${origin.title}. Open Site`}
       className="inline-flex shrink-0 items-center gap-1 rounded px-1 py-1 text-xs text-fg-muted hover:bg-surface-2 hover:text-fg focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-accent"

package/src/app/embed/memory-navigation.tsx

@@ -177,6 +177,7 @@ function createMemoryNavigation(options: MemoryNavigationOptions): NavigationHos
     reloadDocument: _reloadDocument,
     href: hrefOption,
     preload: _preload,
+    activeOptions: _activeOptions,
     disabled,
     children,
     onClick,

package/src/app/lib/actions/held-modifier.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+
+import { createHeldModifierTracker } from "./held-modifier";
+
+function harness(platform: "mac" | "other" = "mac") {
+  const listeners = new Map<string, Set<(event: Event) => void>>();
+  const target = {
+    addEventListener: (type: string, listener: (event: Event) => void) => {
+      if (!listeners.has(type)) listeners.set(type, new Set());
+      listeners.get(type)!.add(listener);
+    },
+    removeEventListener: (type: string, listener: (event: Event) => void) => {
+      listeners.get(type)?.delete(listener);
+    },
+  } as unknown as Pick<Window, "addEventListener" | "removeEventListener">;
+  let pending: (() => void) | null = null;
+  const timers = {
+    setTimeout: ((callback: () => void) => {
+      pending = callback;
+      return 1;
+    }) as unknown as typeof setTimeout,
+    clearTimeout: (() => {
+      pending = null;
+    }) as unknown as typeof clearTimeout,
+  };
+  const tracker = createHeldModifierTracker(target, platform, timers);
+  let changes = 0;
+  const unsubscribe = tracker.subscribe(() => changes++);
+  const fire = (type: string, init: Partial<KeyboardEvent> = {}) => {
+    for (const listener of listeners.get(type) ?? []) listener(init as unknown as Event);
+  };
+  return {
+    tracker,
+    fire,
+    elapse: () => {
+      const callback = pending;
+      pending = null;
+      callback?.();
+    },
+    changes: () => changes,
+    unsubscribe,
+    listenerCount: () => [...listeners.values()].reduce((sum, set) => sum + set.size, 0),
+  };
+}
+
+describe("held modifier", () => {
+  test("shows after ⌘ is held alone, hides on release", () => {
+    const h = harness();
+    h.fire("keydown", { key: "Meta", metaKey: true });
+    expect(h.tracker.held()).toBe(false);
+    h.elapse();
+    expect(h.tracker.held()).toBe(true);
+    h.fire("keyup", { key: "Meta" });
+    expect(h.tracker.held()).toBe(false);
+    expect(h.changes()).toBe(2);
+  });
+
+  test("a quick ⌘ shortcut never shows the hint", () => {
+    const h = harness();
+    h.fire("keydown", { key: "Meta", metaKey: true });
+    h.fire("keydown", { key: "c", code: "KeyC", metaKey: true });
+    h.elapse();
+    expect(h.tracker.held()).toBe(false);
+  });
+
+  test("another key or leaving the window hides it", () => {
+    const h = harness();
+    h.fire("keydown", { key: "Meta", metaKey: true });
+    h.elapse();
+    h.fire("keydown", { key: "1", code: "Digit1", metaKey: true });
+    expect(h.tracker.held()).toBe(false);
+    h.fire("keydown", { key: "Meta", metaKey: true });
+    h.elapse();
+    h.fire("blur");
+    expect(h.tracker.held()).toBe(false);
+  });
+
+  test("⌘ with other modifiers is not the hint", () => {
+    const h = harness();
+    h.fire("keydown", { key: "Meta", metaKey: true, shiftKey: true });
+    h.elapse();
+    expect(h.tracker.held()).toBe(false);
+  });
+
+  test("Ctrl is the key on Windows and Linux", () => {
+    const h = harness("other");
+    h.fire("keydown", { key: "Meta", metaKey: true });
+    h.elapse();
+    expect(h.tracker.held()).toBe(false);
+    h.fire("keydown", { key: "Control", ctrlKey: true });
+    h.elapse();
+    expect(h.tracker.held()).toBe(true);
+  });
+
+  test("stops listening when the last row goes away", () => {
+    const h = harness();
+    expect(h.listenerCount()).toBeGreaterThan(0);
+    h.unsubscribe();
+    expect(h.listenerCount()).toBe(0);
+  });
+});

package/src/app/lib/actions/held-modifier.ts

@@ -0,0 +1,108 @@
+/**
+ * Whether ⌘ (Mac) or Ctrl (elsewhere) is being held on its own, so the page
+ * can show which keys it unlocks: the pinned chats show ⌘1 to ⌘9.
+ *
+ * The hint waits a moment before appearing, so a quick ⌘C or ⌘K never flashes
+ * it, and it goes away on release, on any other key, and when the window loses
+ * focus (⌘Tab to another app releases the key where the page can't see it).
+ */
+import { useSyncExternalStore } from "react";
+
+import type { ChordPlatform } from "./chords";
+
+export const HELD_MODIFIER_DELAY_MS = 350;
+
+type HeldModifierTracker = {
+  subscribe(listener: () => void): () => void;
+  held(): boolean;
+};
+
+/** One tracker per window and platform; every row reads the same state. */
+export function createHeldModifierTracker(
+  target: Pick<Window, "addEventListener" | "removeEventListener">,
+  platform: ChordPlatform,
+  timers: Pick<typeof globalThis, "setTimeout" | "clearTimeout"> = globalThis,
+): HeldModifierTracker {
+  const modifierKey = platform === "mac" ? "Meta" : "Control";
+  const listeners = new Set<() => void>();
+  let held = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const set = (next: boolean) => {
+    if (held === next) return;
+    held = next;
+    for (const listener of listeners) listener();
+  };
+  const reset = () => {
+    if (timer !== null) timers.clearTimeout(timer);
+    timer = null;
+    set(false);
+  };
+  const onKeyDown = (event: Event) => {
+    const keyEvent = event as KeyboardEvent;
+    const alone =
+      keyEvent.key === modifierKey &&
+      !keyEvent.shiftKey &&
+      !keyEvent.altKey &&
+      (platform === "mac" ? !keyEvent.ctrlKey : !keyEvent.metaKey);
+    if (!alone) {
+      reset();
+      return;
+    }
+    if (keyEvent.repeat || held || timer !== null) return;
+    timer = timers.setTimeout(() => {
+      timer = null;
+      set(true);
+    }, HELD_MODIFIER_DELAY_MS);
+  };
+  const onKeyUp = (event: Event) => {
+    if ((event as KeyboardEvent).key === modifierKey) reset();
+  };
+  const onVisibility = () => reset();
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      if (listeners.size === 1) {
+        target.addEventListener("keydown", onKeyDown, true);
+        target.addEventListener("keyup", onKeyUp, true);
+        target.addEventListener("blur", reset);
+        target.addEventListener("visibilitychange", onVisibility);
+        target.addEventListener("pointerdown", reset, true);
+      }
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size > 0) return;
+        target.removeEventListener("keydown", onKeyDown, true);
+        target.removeEventListener("keyup", onKeyUp, true);
+        target.removeEventListener("blur", reset);
+        target.removeEventListener("visibilitychange", onVisibility);
+        target.removeEventListener("pointerdown", reset, true);
+        if (timer !== null) timers.clearTimeout(timer);
+        timer = null;
+        held = false;
+      };
+    },
+    held: () => held,
+  };
+}
+
+const trackers = new Map<ChordPlatform, HeldModifierTracker>();
+
+function windowTracker(platform: ChordPlatform): HeldModifierTracker | null {
+  if (typeof window === "undefined") return null;
+  let tracker = trackers.get(platform);
+  if (!tracker) {
+    tracker = createHeldModifierTracker(window, platform);
+    trackers.set(platform, tracker);
+  }
+  return tracker;
+}
+
+const NEVER: HeldModifierTracker = { subscribe: () => () => {}, held: () => false };
+
+/** True while ⌘ (Ctrl elsewhere) is held alone; `enabled: false` never listens. */
+export function useHeldModifier(platform: ChordPlatform, enabled: boolean): boolean {
+  const tracker = (enabled ? windowTracker(platform) : null) ?? NEVER;
+  return useSyncExternalStore(tracker.subscribe, tracker.held, () => false);
+}

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

@@ -0,0 +1,38 @@
+import type { SiteViewer } from "@opengeni/sdk";
+import { useCallback, useMemo } from "react";
+import type { SiteToolBridgeFactory } from "../../artifacts";
+import { useAppContext } from "../app-context";
+import { useAppApi } from "./app-api";
+import { createSiteToolBridge } from "./site-tool-bridge";
+
+/** The signed-in member as Site code sees them (`site.viewer`) in the console. */
+export function useConsoleSiteViewer(): SiteViewer {
+  const { accessContext, authSession } = useAppContext();
+  const subjectId = accessContext.subjectId;
+  const name = authSession?.user?.name ?? null;
+  const email = authSession?.user?.email ?? null;
+  return useMemo(
+    () => ({ kind: "member", id: `user:${subjectId}`, name, email, signedIn: true }),
+    [email, name, subjectId],
+  );
+}
+
+/** Console tool access for a `SiteView`, pinned to the loaded Site version. */
+export function useConsoleSiteToolBridge(workspaceId: string): SiteToolBridgeFactory {
+  const { client } = useAppContext();
+  const api = useAppApi();
+  return useCallback<SiteToolBridgeFactory>(
+    (site) => {
+      const scope = { workspaceTools: client.tools.forWorkspace(workspaceId), workspaceId };
+      return site
+        ? createSiteToolBridge(api, {
+            ...scope,
+            artifactId: site.artifactId,
+            siteVersionId: site.siteVersionId,
+            requestedTools: site.requestedTools,
+          })
+        : createSiteToolBridge(api, scope);
+    },
+    [api, client, workspaceId],
+  );
+}

package/src/app/lib/navigation.tsx

@@ -55,6 +55,10 @@ export type LinkProps = NavigateOptions &
       | undefined;
     preload?: false | "intent" | "viewport" | "render" | undefined;
     disabled?: boolean | undefined;
+    /** When the link counts as the current page (`aria-current`); the router's default otherwise. */
+    activeOptions?:
+      | { exact?: boolean | undefined; includeSearch?: boolean | undefined }
+      | undefined;
     ref?: Ref<HTMLAnchorElement> | undefined;
   };
 

package/src/app/lib/routes.tsx

@@ -106,3 +106,45 @@ export function artifactReturnSearch(search: Record<string, unknown>): ArtifactR
         : undefined,
   };
 }
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+
+/** The Site view: the Site with its conversations beside it, one of them open. */
+export type SiteViewSearch = { conversation?: string | undefined };
+
+export function siteViewSearch(search: Record<string, unknown>): SiteViewSearch {
+  return {
+    conversation:
+      typeof search.conversation === "string" && UUID.test(search.conversation)
+        ? search.conversation
+        : undefined,
+  };
+}
+
+export function workspaceSitePath(
+  workspaceId: string,
+  siteId: string,
+  conversation?: string | undefined,
+): string {
+  const path = `${workspacePath(workspaceId)}/sites/${encodeURIComponent(siteId)}`;
+  return conversation ? `${path}?conversation=${encodeURIComponent(conversation)}` : path;
+}
+
+/**
+ * What the rail marks as open for a location: a session page's session, or a
+ * Site view's Site and its selected conversation.
+ */
+export function railRouteSelection(location: {
+  pathname: string;
+  search: Record<string, unknown>;
+}): { sessionId: string | null; siteId: string | null } {
+  const session = /\/sessions\/([^/]+)/u.exec(location.pathname);
+  if (session) return { sessionId: session[1] ?? null, siteId: null };
+  const site = /^\/workspaces\/[^/]+\/sites\/([^/]+)\/?$/u.exec(location.pathname);
+  // Site ids are UUIDs; anything else (including a malformed escape) is no Site.
+  if (!site || !UUID.test(site[1] ?? "")) return { sessionId: null, siteId: null };
+  return {
+    sessionId: siteViewSearch(location.search).conversation ?? null,
+    siteId: site[1]!.toLowerCase(),
+  };
+}