From 4c7195087583091755ced122d3ef6c4dc2f47400 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 28 Jul 2026 02:52:27 -0400
Subject: [PATCH 1/4] feat(workspaces): reveal PDF citations at cited pages

---
 .../components/WorkspaceContent.tsx           | 16 +++--
 .../components/WorkspaceFileViewer.tsx        |  8 +--
 .../components/WorkspaceImageViewer.tsx       | 12 ++--
 .../workspaces/components/WorkspaceLayout.tsx | 14 ++++-
 .../components/WorkspacePaneRenderer.tsx      |  2 +
 .../components/WorkspacePdfViewer.tsx         | 60 +++++++++++++++++--
 .../components/WorkspaceStandardTabPanes.tsx  |  2 +-
 .../ai-chat/AiChatMessageResponse.test.tsx    |  8 +--
 .../document-editor/DocumentEditorSurface.tsx | 12 ++--
 .../locations/workspace-location-context.tsx  | 48 ++++++++++++---
 .../navigation/useWorkspaceNavigation.ts      | 14 +++--
 11 files changed, 150 insertions(+), 46 deletions(-)

diff --git a/src/features/workspaces/components/WorkspaceContent.tsx b/src/features/workspaces/components/WorkspaceContent.tsx
index fb13a3bc..b85bb646 100644
--- a/src/features/workspaces/components/WorkspaceContent.tsx
+++ b/src/features/workspaces/components/WorkspaceContent.tsx
@@ -49,7 +49,7 @@ import { useNativeFileDropTarget } from "#/lib/use-native-file-drop-target";
 import { cn } from "#/lib/utils";
 
 interface WorkspaceContentProps {
-	instanceId?: string;
+	viewInstanceId: string;
 	items: WorkspaceItem[];
 	activeItem?: WorkspaceItem;
 	workspace: WorkspaceSummary;
@@ -60,7 +60,7 @@ interface WorkspaceContentProps {
 type WorkspaceItemActionDialogsState = ReturnType<typeof useWorkspaceItemActionDialogState>;
 
 export default function WorkspaceContent({
-	instanceId,
+	viewInstanceId,
 	items,
 	activeItem,
 	workspace,
@@ -75,7 +75,7 @@ export default function WorkspaceContent({
 			<>
 				<WorkspaceItemView
 					item={activeItem}
-					viewInstanceId={instanceId ?? activeItem.id}
+					viewInstanceId={viewInstanceId}
 					workspaceId={workspaceId}
 					onMoveItem={actionDialogs.openMoveDialog}
 					onRenameItem={actionDialogs.setRenamingItem}
@@ -109,7 +109,7 @@ function WorkspaceBrowseContent({
 	workspace,
 	onCreateItem,
 	onOpenItem,
-}: WorkspaceContentProps & {
+}: Omit<WorkspaceContentProps, "viewInstanceId"> & {
 	actionDialogs: WorkspaceItemActionDialogsState;
 }) {
 	const { capabilities } = useWorkspaceMutationAccess();
@@ -490,7 +490,11 @@ function WorkspaceItemView({
 
 	if (item.type === "document") {
 		return (
-			<DocumentEditorSurface item={item} toolbarSlotId={viewInstanceId} workspaceId={workspaceId} />
+			<DocumentEditorSurface
+				item={item}
+				viewInstanceId={viewInstanceId}
+				workspaceId={workspaceId}
+			/>
 		);
 	}
 
@@ -498,7 +502,7 @@ function WorkspaceItemView({
 		return (
 			<WorkspaceFileViewer
 				item={item}
-				toolbarSlotId={viewInstanceId}
+				viewInstanceId={viewInstanceId}
 				workspaceId={workspaceId}
 				onMoveItem={onMoveItem}
 				onRenameItem={onRenameItem}
diff --git a/src/features/workspaces/components/WorkspaceFileViewer.tsx b/src/features/workspaces/components/WorkspaceFileViewer.tsx
index 51855089..375b4971 100644
--- a/src/features/workspaces/components/WorkspaceFileViewer.tsx
+++ b/src/features/workspaces/components/WorkspaceFileViewer.tsx
@@ -14,7 +14,7 @@ import { cn } from "#/lib/utils";
 
 interface WorkspaceFileViewerComponentProps {
 	item: WorkspaceItem;
-	toolbarSlotId?: string;
+	viewInstanceId: string;
 	workspaceId: string;
 }
 
@@ -28,7 +28,7 @@ const workspaceFileViewers: Record<
 
 interface WorkspaceFileViewerProps {
 	item: WorkspaceItem;
-	toolbarSlotId: string;
+	viewInstanceId: string;
 	workspaceId: string;
 	onDeleteItem: (item: WorkspaceItem) => void;
 	onMoveItem: (item: WorkspaceItem) => void;
@@ -37,7 +37,7 @@ interface WorkspaceFileViewerProps {
 
 export default function WorkspaceFileViewer({
 	item,
-	toolbarSlotId,
+	viewInstanceId,
 	workspaceId,
 	onDeleteItem,
 	onMoveItem,
@@ -48,7 +48,7 @@ export default function WorkspaceFileViewer({
 	const viewCapabilities = useWorkspaceViewCapabilities();
 	const viewerContent = Viewer ? (
 		<Suspense fallback={<WorkspaceFileViewerSkeleton />}>
-			<Viewer item={item} toolbarSlotId={toolbarSlotId} workspaceId={workspaceId} />
+			<Viewer item={item} viewInstanceId={viewInstanceId} workspaceId={workspaceId} />
 		</Suspense>
 	) : (
 		<div className="flex h-full items-center justify-center bg-background">
diff --git a/src/features/workspaces/components/WorkspaceImageViewer.tsx b/src/features/workspaces/components/WorkspaceImageViewer.tsx
index 73331e13..9b0b7ce0 100644
--- a/src/features/workspaces/components/WorkspaceImageViewer.tsx
+++ b/src/features/workspaces/components/WorkspaceImageViewer.tsx
@@ -17,13 +17,13 @@ import { cn } from "#/lib/utils";
 
 interface WorkspaceImageViewerProps {
 	item: WorkspaceItem;
-	toolbarSlotId?: string;
+	viewInstanceId: string;
 	workspaceId: string;
 }
 
 export default function WorkspaceImageViewer({
 	item,
-	toolbarSlotId,
+	viewInstanceId,
 	workspaceId,
 }: WorkspaceImageViewerProps) {
 	const fileUrl = getWorkspaceFileContentUrl(workspaceId, item.id);
@@ -33,7 +33,7 @@ export default function WorkspaceImageViewer({
 			key={fileUrl}
 			fileUrl={fileUrl}
 			item={item}
-			toolbarSlotId={toolbarSlotId}
+			viewInstanceId={viewInstanceId}
 			workspaceId={workspaceId}
 		/>
 	);
@@ -42,12 +42,12 @@ export default function WorkspaceImageViewer({
 function WorkspaceImageViewerContent({
 	fileUrl,
 	item,
-	toolbarSlotId,
+	viewInstanceId,
 	workspaceId,
 }: {
 	fileUrl: string;
 	item: WorkspaceItem;
-	toolbarSlotId?: string;
+	viewInstanceId: string;
 	workspaceId: string;
 }) {
 	const imageRef = useRef<HTMLImageElement>(null);
@@ -75,7 +75,7 @@ function WorkspaceImageViewerContent({
 			: undefined,
 		fileName: item.name,
 		fileUrl,
-		slotId: toolbarSlotId ?? item.id,
+		slotId: viewInstanceId,
 	});
 
 	const handleImageLoad = useCallback(() => {
diff --git a/src/features/workspaces/components/WorkspaceLayout.tsx b/src/features/workspaces/components/WorkspaceLayout.tsx
index 4384d72e..f21fee3b 100644
--- a/src/features/workspaces/components/WorkspaceLayout.tsx
+++ b/src/features/workspaces/components/WorkspaceLayout.tsx
@@ -27,11 +27,12 @@ import type {
 	WorkspaceItemType,
 	WorkspaceSummary,
 } from "#/features/workspaces/contracts";
+import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
+import { WorkspaceLocationProvider } from "#/features/workspaces/locations/workspace-location-context";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
 import { isWorkspaceItemView } from "#/features/workspaces/model/view";
 import { workspaceItemRequiresHeavyViewerRuntime } from "#/features/workspaces/model/workspace-file";
 import { getWorkspaceMobileChatSurfaceMode } from "#/features/workspaces/model/workspace-ui";
-import { WorkspaceLocationProvider } from "#/features/workspaces/locations/workspace-location-context";
 import { useWorkspaceNavigation } from "#/features/workspaces/navigation/useWorkspaceNavigation";
 import { useWorkspaceRealtime } from "#/features/workspaces/realtime/use-workspace-presence";
 import { useWorkspacePersistedStoresHydrated } from "#/features/workspaces/state/persisted-store-hydration";
@@ -125,6 +126,15 @@ export function WorkspaceShell({
 	const { chatSurfaceMode, presentation } = normalizedUiSession;
 	const mobileChatSurfaceMode = getWorkspaceMobileChatSurfaceMode(chatSurfaceMode);
 	const hasHeavyViewerRuntimeItems = scopedItems.some(workspaceItemRequiresHeavyViewerRuntime);
+	const navigateToWorkspaceLocation = (location: WorkspaceLocation) => {
+		const viewInstanceId = revealWorkspaceLocation(location);
+
+		if (viewInstanceId && chatSurfaceMode === "fullscreen") {
+			setChatSurfaceMode(workspace.id, "hidden");
+		}
+
+		return viewInstanceId;
+	};
 	const createWorkspaceItem = (input: { type: WorkspaceItemType; parentId: string | null }) => {
 		if (!getWorkspaceMemberCapabilities(workspace.membershipRole).canMutateContent) {
 			return;
@@ -292,7 +302,7 @@ export function WorkspaceShell({
 
 	return (
 		<WorkspaceMutationAccessProvider membershipRole={workspace.membershipRole}>
-			<WorkspaceLocationProvider itemsById={itemsById} reveal={revealWorkspaceLocation}>
+			<WorkspaceLocationProvider itemsById={itemsById} navigate={navigateToWorkspaceLocation}>
 				{hasHeavyViewerRuntimeItems ? (
 					<WorkspacePdfEngineProvider>{workspaceInteractionContent}</WorkspacePdfEngineProvider>
 				) : (
diff --git a/src/features/workspaces/components/WorkspacePaneRenderer.tsx b/src/features/workspaces/components/WorkspacePaneRenderer.tsx
index f4bb144d..1ba68c8a 100644
--- a/src/features/workspaces/components/WorkspacePaneRenderer.tsx
+++ b/src/features/workspaces/components/WorkspacePaneRenderer.tsx
@@ -15,6 +15,7 @@ export default function WorkspacePaneRenderer({
 
 			return (
 				<WorkspaceContent
+					viewInstanceId={pane.id}
 					workspace={workspace}
 					items={scopedItems}
 					activeItem={item}
@@ -26,6 +27,7 @@ export default function WorkspacePaneRenderer({
 		case "root":
 			return (
 				<WorkspaceContent
+					viewInstanceId={pane.id}
 					workspace={workspace}
 					items={scopedItems}
 					activeItem={undefined}
diff --git a/src/features/workspaces/components/WorkspacePdfViewer.tsx b/src/features/workspaces/components/WorkspacePdfViewer.tsx
index 4a664c82..bf486f69 100644
--- a/src/features/workspaces/components/WorkspacePdfViewer.tsx
+++ b/src/features/workspaces/components/WorkspacePdfViewer.tsx
@@ -28,6 +28,7 @@ import {
 	ScrollPluginPackage,
 	ScrollStrategy,
 	useScroll,
+	useScrollCapability,
 } from "@embedpdf/plugin-scroll/react";
 import {
 	SelectionPluginPackage,
@@ -44,7 +45,10 @@ import {
 	WorkspaceCaptureViewerFrame,
 } from "#/features/workspaces/components/WorkspaceCaptureChrome";
 import { useFileItemToolbar } from "#/features/workspaces/components/WorkspaceItemToolbarSlot";
-import { useWorkspacePaneHotkey } from "#/features/workspaces/components/WorkspacePaneRuntime";
+import {
+	useWorkspacePaneHotkey,
+	useWorkspacePaneRuntime,
+} from "#/features/workspaces/components/WorkspacePaneRuntime";
 import { WorkspacePdfAskSelectionMenu } from "#/features/workspaces/components/WorkspacePdfAskSelectionMenu";
 import {
 	WorkspacePdfCaptureInteractionMode,
@@ -55,6 +59,7 @@ import { WorkspacePdfPageControl } from "#/features/workspaces/components/Worksp
 import { useWorkspaceViewCapabilities } from "#/features/workspaces/components/workspace-view-policy";
 import { createCaptureAttachmentFile } from "#/features/workspaces/components/workspace-region-capture";
 import { stageCaptureAttachmentToComposerWithFeedback } from "#/features/workspaces/composer/workspace-composer-actions";
+import { useWorkspacePdfPageRevealRequest } from "#/features/workspaces/locations/workspace-location-context";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
 import { getWorkspaceFileContentUrl } from "#/features/workspaces/model/workspace-file";
 import {
@@ -102,11 +107,11 @@ type WorkspacePdfInteractions = {
 
 export default function WorkspacePdfViewer({
 	item,
-	toolbarSlotId,
+	viewInstanceId,
 	workspaceId,
 }: {
 	item: WorkspaceItem;
-	toolbarSlotId?: string;
+	viewInstanceId: string;
 	workspaceId: string;
 }) {
 	const fileUrl = getWorkspaceFileContentUrl(workspaceId, item.id);
@@ -131,7 +136,7 @@ export default function WorkspacePdfViewer({
 			: undefined,
 		fileName: item.name,
 		fileUrl,
-		slotId: toolbarSlotId ?? item.id,
+		slotId: viewInstanceId,
 	});
 
 	return (
@@ -155,6 +160,7 @@ export default function WorkspacePdfViewer({
 								itemId={item.id}
 								onCaptureModeExit={exitCapture}
 								onCaptureModeToggle={toggleCapture}
+								viewInstanceId={viewInstanceId}
 								workspaceId={workspaceId}
 							/>
 						) : (
@@ -177,6 +183,7 @@ function WorkspacePdfDocumentLoader({
 	itemId,
 	onCaptureModeExit,
 	onCaptureModeToggle,
+	viewInstanceId,
 	workspaceId,
 }: {
 	activeDocumentId: string | null;
@@ -187,14 +194,19 @@ function WorkspacePdfDocumentLoader({
 	itemId: string;
 	onCaptureModeExit: () => void;
 	onCaptureModeToggle: () => void;
+	viewInstanceId: string;
 	workspaceId: string;
 }) {
 	const { provides: documentManager } = useDocumentManagerCapability();
+	const { provides: scrollCapability } = useScrollCapability();
+	const paneRuntime = useWorkspacePaneRuntime();
+	const { consume, request } = useWorkspacePdfPageRevealRequest(viewInstanceId);
 	const [openError, setOpenError] = useState<{
 		documentId: string;
 		message: string;
 	} | null>(null);
 	const currentOpenError = openError?.documentId === documentId ? openError.message : null;
+	const isActive = paneRuntime?.isActive ?? true;
 
 	useEffect(() => {
 		if (!documentManager || documentManager.isDocumentOpen(documentId)) {
@@ -240,6 +252,46 @@ function WorkspacePdfDocumentLoader({
 		};
 	}, [documentId, documentManager, fileName, fileUrl]);
 
+	useEffect(() => {
+		if (!request) {
+			return;
+		}
+
+		if (currentOpenError || request.location.itemId !== documentId) {
+			consume(request);
+			return;
+		}
+
+		if (!isActive || activeDocumentId !== documentId || !scrollCapability) {
+			return;
+		}
+
+		let handled = false;
+
+		return scrollCapability.onLayoutReady((event) => {
+			if (handled || event.documentId !== documentId) {
+				return;
+			}
+
+			handled = true;
+			if (request.location.pageNumber <= event.totalPages) {
+				scrollCapability.forDocument(documentId).scrollToPage({
+					behavior: "instant",
+					pageNumber: request.location.pageNumber,
+				});
+			}
+			consume(request);
+		});
+	}, [
+		activeDocumentId,
+		consume,
+		currentOpenError,
+		documentId,
+		isActive,
+		request,
+		scrollCapability,
+	]);
+
 	if (currentOpenError) {
 		return (
 			<WorkspacePdfLoadFailure fileName={fileName} fileUrl={fileUrl}>
diff --git a/src/features/workspaces/components/WorkspaceStandardTabPanes.tsx b/src/features/workspaces/components/WorkspaceStandardTabPanes.tsx
index 9846a3ad..27792edf 100644
--- a/src/features/workspaces/components/WorkspaceStandardTabPanes.tsx
+++ b/src/features/workspaces/components/WorkspaceStandardTabPanes.tsx
@@ -45,7 +45,7 @@ export default function WorkspaceStandardTabPanes({
 							onCloseItemView={canCloseItemView ? onCloseItemView : undefined}
 						>
 							<WorkspaceContent
-								instanceId={tab.id}
+								viewInstanceId={tab.id}
 								items={scopedItems}
 								activeItem={tab.viewItemId ? itemsById.get(tab.viewItemId) : undefined}
 								workspace={workspace}
diff --git a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx
index 89a81435..2d526a38 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx
@@ -26,7 +26,7 @@ describe("AI chat message response citations", () => {
 	it("renders a validated citation as an app-owned source button", () => {
 		const ref = "wr_AAAAAAAA" as WorkspaceReference;
 		const html = renderToStaticMarkup(
-			<WorkspaceLocationProvider itemsById={new Map()} reveal={() => false}>
+			<WorkspaceLocationProvider itemsById={new Map()} navigate={() => undefined}>
 				<AiChatMessageResponse
 					workspaceCitationLocations={
 						new Map([
@@ -58,7 +58,7 @@ describe("AI chat message response citations", () => {
 		const html = renderToStaticMarkup(
 			<WorkspaceLocationProvider
 				itemsById={new Map([[documentItem.id, documentItem]])}
-				reveal={() => true}
+				navigate={() => "tab-1"}
 			>
 				<AiChatMessageResponse
 					workspaceCitationLocations={
@@ -86,7 +86,7 @@ describe("AI chat message response citations", () => {
 
 	it("does not expose an incomplete streamed citation tag", () => {
 		const html = renderToStaticMarkup(
-			<WorkspaceLocationProvider itemsById={new Map()} reveal={() => false}>
+			<WorkspaceLocationProvider itemsById={new Map()} navigate={() => undefined}>
 				<AiChatMessageResponse isStreaming={true}>
 					{'Claim <citation ref="wr_AAAAAAAA'}
 				</AiChatMessageResponse>
@@ -101,7 +101,7 @@ describe("AI chat message response citations", () => {
 	it("renders non-empty citation markup as inert text", () => {
 		const ref = "wr_AAAAAAAA" as WorkspaceReference;
 		const html = renderToStaticMarkup(
-			<WorkspaceLocationProvider itemsById={new Map()} reveal={() => false}>
+			<WorkspaceLocationProvider itemsById={new Map()} navigate={() => undefined}>
 				<AiChatMessageResponse
 					workspaceCitationLocations={
 						new Map([
diff --git a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
index c47bb649..dfb55d6b 100644
--- a/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
+++ b/src/features/workspaces/components/document-editor/DocumentEditorSurface.tsx
@@ -24,11 +24,11 @@ import { getAuthSessionQueryOptions } from "#/lib/session-query";
 
 export function DocumentEditorSurface({
 	item,
-	toolbarSlotId,
+	viewInstanceId,
 	workspaceId,
 }: {
 	item: WorkspaceItem;
-	toolbarSlotId?: string;
+	viewInstanceId: string;
 	workspaceId: string;
 }) {
 	const { data: session } = useQuery(getAuthSessionQueryOptions());
@@ -49,7 +49,7 @@ export function DocumentEditorSurface({
 		<DocumentEditorInstance
 			collaborationSession={collaborationSession}
 			item={item}
-			toolbarSlotId={toolbarSlotId}
+			viewInstanceId={viewInstanceId}
 			workspaceId={workspaceId}
 		/>
 	);
@@ -58,12 +58,12 @@ export function DocumentEditorSurface({
 function DocumentEditorInstance({
 	collaborationSession,
 	item,
-	toolbarSlotId,
+	viewInstanceId,
 	workspaceId,
 }: {
 	collaborationSession: DocumentCollaborationSession;
 	item: WorkspaceItem;
-	toolbarSlotId?: string;
+	viewInstanceId: string;
 	workspaceId: string;
 }) {
 	const { capabilities } = useWorkspaceMutationAccess();
@@ -98,7 +98,7 @@ function DocumentEditorInstance({
 		},
 	});
 
-	useDocumentEditorToolbar(toolbarSlotId ?? item.id, capabilities.canMutateContent ? editor : null);
+	useDocumentEditorToolbar(viewInstanceId, capabilities.canMutateContent ? editor : null);
 
 	return (
 		<section className="relative flex h-full min-h-0 flex-col bg-background">
diff --git a/src/features/workspaces/locations/workspace-location-context.tsx b/src/features/workspaces/locations/workspace-location-context.tsx
index 04113131..d319ccbe 100644
--- a/src/features/workspaces/locations/workspace-location-context.tsx
+++ b/src/features/workspaces/locations/workspace-location-context.tsx
@@ -1,22 +1,31 @@
 import { FileQuestion, type LucideIcon } from "lucide-react";
-import { createContext, type ReactNode, use } from "react";
+import { createContext, type ReactNode, use, useState } from "react";
 
 import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
 import { getWorkspaceItemDisplay } from "#/features/workspaces/model/item-display";
 import type { WorkspaceItem } from "#/features/workspaces/model/types";
 
+type WorkspacePdfPageLocation = Extract<WorkspaceLocation, { kind: "pdf-page" }>;
+
 type WorkspaceLocationPresentation = {
 	Icon: LucideIcon;
 	iconClassName: string;
 	label: string;
 };
 
-type WorkspaceLocationActions = {
+type WorkspacePdfPageRevealRequest = {
+	location: WorkspacePdfPageLocation;
+	viewInstanceId: string;
+};
+
+type WorkspaceLocationContextValue = {
+	consumeRevealRequest: (request: WorkspacePdfPageRevealRequest) => void;
 	getPresentation: (location: WorkspaceLocation) => WorkspaceLocationPresentation;
 	reveal: (location: WorkspaceLocation) => boolean;
+	revealRequest: WorkspacePdfPageRevealRequest | null;
 };
 
-const WorkspaceLocationContext = createContext<WorkspaceLocationActions | null>(null);
+const WorkspaceLocationContext = createContext<WorkspaceLocationContextValue | null>(null);
 
 /**
  * Connects location-aware UI to the current workspace's items and navigation.
@@ -24,13 +33,18 @@ const WorkspaceLocationContext = createContext<WorkspaceLocationActions | null>(
 export function WorkspaceLocationProvider({
 	children,
 	itemsById,
-	reveal,
+	navigate,
 }: {
 	readonly children: ReactNode;
 	readonly itemsById: ReadonlyMap<string, WorkspaceItem>;
-	readonly reveal: WorkspaceLocationActions["reveal"];
+	readonly navigate: (location: WorkspaceLocation) => string | undefined;
 }) {
-	const value: WorkspaceLocationActions = {
+	const [revealRequest, setRevealRequest] = useState<WorkspacePdfPageRevealRequest | null>(null);
+	const consumeRevealRequest = (request: WorkspacePdfPageRevealRequest) => {
+		setRevealRequest((current) => (current === request ? null : current));
+	};
+	const value: WorkspaceLocationContextValue = {
+		consumeRevealRequest,
 		getPresentation(location) {
 			const item = itemsById.get(location.itemId);
 			const itemName = item?.name ?? "Source unavailable";
@@ -48,7 +62,15 @@ export function WorkspaceLocationProvider({
 			const { Icon, iconClassName } = getWorkspaceItemDisplay(item);
 			return { Icon, iconClassName, label };
 		},
-		reveal,
+		reveal(location) {
+			const viewInstanceId = navigate(location);
+
+			setRevealRequest(
+				viewInstanceId && location.kind === "pdf-page" ? { location, viewInstanceId } : null,
+			);
+			return Boolean(viewInstanceId);
+		},
+		revealRequest,
 	};
 
 	return <WorkspaceLocationContext value={value}>{children}</WorkspaceLocationContext>;
@@ -65,3 +87,15 @@ export function useWorkspaceLocationActions() {
 
 	return value;
 }
+
+/**
+ * Returns the latest PDF-page reveal request when it targets this mounted view.
+ */
+export function useWorkspacePdfPageRevealRequest(viewInstanceId: string) {
+	const { consumeRevealRequest, revealRequest } = useWorkspaceLocationActions();
+
+	return {
+		consume: consumeRevealRequest,
+		request: revealRequest?.viewInstanceId === viewInstanceId ? revealRequest : null,
+	};
+}
diff --git a/src/features/workspaces/navigation/useWorkspaceNavigation.ts b/src/features/workspaces/navigation/useWorkspaceNavigation.ts
index 697c8aa7..c71a3135 100644
--- a/src/features/workspaces/navigation/useWorkspaceNavigation.ts
+++ b/src/features/workspaces/navigation/useWorkspaceNavigation.ts
@@ -217,24 +217,26 @@ export function useWorkspaceNavigation({
 	const revealWorkspaceLocation = (location: WorkspaceLocation) => {
 		const item = itemsById.get(location.itemId);
 		if (!item) {
-			return false;
+			return undefined;
 		}
 
 		if (activeTab?.viewItemId === item.id) {
-			return true;
+			return activeTab.id;
 		}
 
 		const matchingTab = session?.tabs.find((tab) => tab.viewItemId === item.id);
 		if (matchingTab) {
 			activateWorkspaceTab(matchingTab);
-		} else if (activeTab && !activeTab.viewItemId) {
+			return matchingTab.id;
+		}
+
+		if (activeTab && !activeTab.viewItemId) {
 			const tab = replaceActiveTabView({ item });
 			navigateToTab(tab);
-		} else {
-			openItemInNewTab({ item });
+			return tab.id;
 		}
 
-		return true;
+		return openItemInNewTab({ item }).id;
 	};
 	const openWorkspaceRoot = () => {
 		if (!activeTab?.viewItemId) {

From cedc88767014d8d92d38ae56e5150250e7fc5005 Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 28 Jul 2026 03:18:01 -0400
Subject: [PATCH 2/4] fix(workspaces): preserve trailing metadata in compact
 rows

Keep PDF page locators and compact-row metadata visible when primary labels are long.

Preserve full citation labels for hover and assistive technology.
---
 .../components/WorkspaceMobileBreadcrumbOverflow.tsx     | 4 ++--
 .../components/ai-chat/AiChatMessageResponse.test.tsx    | 3 ++-
 .../workspaces/components/ai-chat/WorkspaceCitation.tsx  | 9 ++++++---
 .../workspaces/components/workspace-card-meta-row.tsx    | 4 ++--
 .../workspaces/locations/workspace-location-context.tsx  | 9 +++++----
 5 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/src/features/workspaces/components/WorkspaceMobileBreadcrumbOverflow.tsx b/src/features/workspaces/components/WorkspaceMobileBreadcrumbOverflow.tsx
index 0e59d89e..3604d6c2 100644
--- a/src/features/workspaces/components/WorkspaceMobileBreadcrumbOverflow.tsx
+++ b/src/features/workspaces/components/WorkspaceMobileBreadcrumbOverflow.tsx
@@ -47,10 +47,10 @@ export default function WorkspaceMobileBreadcrumbOverflow({
 
 							return (
 								<DropdownMenuItem key={item.id} onClick={() => onNavigateToItem(item)}>
-									<span className="inline-flex size-4 items-center justify-center text-muted-foreground">
+									<span className="inline-flex size-4 shrink-0 items-center justify-center text-muted-foreground">
 										<Icon className={iconClassName} aria-hidden="true" />
 									</span>
-									<span className="min-w-0 truncate">{item.name}</span>
+									<span className="min-w-0 flex-1 truncate">{item.name}</span>
 									<span className="ml-auto shrink-0 text-muted-foreground text-xs">{label}</span>
 								</DropdownMenuItem>
 							);
diff --git a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx
index 2d526a38..9a0d9439 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx
@@ -49,7 +49,8 @@ describe("AI chat message response citations", () => {
 
 		expect(html).toContain("<button");
 		expect(html).toContain("Open Source unavailable · p. 12");
-		expect(html).toContain("Source unavailable · p. 12");
+		expect(html).toContain(">Source unavailable</span>");
+		expect(html).toContain(">· p. 12</span>");
 		expect(html).not.toContain("<citation");
 	});
 
diff --git a/src/features/workspaces/components/ai-chat/WorkspaceCitation.tsx b/src/features/workspaces/components/ai-chat/WorkspaceCitation.tsx
index 56cae6fa..e8a65f57 100644
--- a/src/features/workspaces/components/ai-chat/WorkspaceCitation.tsx
+++ b/src/features/workspaces/components/ai-chat/WorkspaceCitation.tsx
@@ -6,12 +6,14 @@ import { cn } from "#/lib/utils";
 
 export function WorkspaceCitation({ location }: { readonly location: WorkspaceLocation }) {
 	const { getPresentation, reveal } = useWorkspaceLocationActions();
-	const { Icon, iconClassName, label } = getPresentation(location);
+	const { Icon, iconClassName, label, locatorLabel } = getPresentation(location);
+	const accessibleLabel = locatorLabel ? `${label} · ${locatorLabel}` : label;
 
 	return (
 		<button
 			type="button"
-			aria-label={`Open ${label}`}
+			aria-label={`Open ${accessibleLabel}`}
+			title={accessibleLabel}
 			className="mx-0.5 inline-flex max-w-48 cursor-pointer items-center gap-1 rounded-sm bg-muted px-1.5 py-0.5 align-baseline font-medium text-[0.72em] text-muted-foreground leading-none transition-colors hover:bg-muted/80 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
 			onClick={() => {
 				if (!reveal(location)) {
@@ -24,7 +26,8 @@ export function WorkspaceCitation({ location }: { readonly location: WorkspaceLo
 				strokeWidth={1.75}
 				aria-hidden="true"
 			/>
-			<span className="truncate">{label}</span>
+			<span className="min-w-0 truncate">{label}</span>
+			{locatorLabel ? <span className="shrink-0 tabular-nums">· {locatorLabel}</span> : null}
 		</button>
 	);
 }
diff --git a/src/features/workspaces/components/workspace-card-meta-row.tsx b/src/features/workspaces/components/workspace-card-meta-row.tsx
index ab4e7e67..a1b97782 100644
--- a/src/features/workspaces/components/workspace-card-meta-row.tsx
+++ b/src/features/workspaces/components/workspace-card-meta-row.tsx
@@ -15,12 +15,12 @@ export function WorkspaceCardMetaRow({ leading, trailing }: WorkspaceCardMetaRow
 
 	return (
 		<div className="flex min-w-0 items-center gap-2 text-xs text-muted-foreground">
-			{hasLeading ? <div className="min-w-0">{leading}</div> : null}
+			{hasLeading ? <div className="min-w-0 flex-1">{leading}</div> : null}
 			{hasLeading && hasTrailing ? (
 				<span aria-hidden="true" className="h-3 w-px shrink-0 bg-border/70" />
 			) : null}
 			{hasTrailing ? (
-				<span className="min-w-0 truncate" suppressHydrationWarning>
+				<span className="shrink-0 whitespace-nowrap" suppressHydrationWarning>
 					{trailing}
 				</span>
 			) : null}
diff --git a/src/features/workspaces/locations/workspace-location-context.tsx b/src/features/workspaces/locations/workspace-location-context.tsx
index d319ccbe..a54c6182 100644
--- a/src/features/workspaces/locations/workspace-location-context.tsx
+++ b/src/features/workspaces/locations/workspace-location-context.tsx
@@ -11,6 +11,7 @@ type WorkspaceLocationPresentation = {
 	Icon: LucideIcon;
 	iconClassName: string;
 	label: string;
+	locatorLabel?: string;
 };
 
 type WorkspacePdfPageRevealRequest = {
@@ -48,19 +49,19 @@ export function WorkspaceLocationProvider({
 		getPresentation(location) {
 			const item = itemsById.get(location.itemId);
 			const itemName = item?.name ?? "Source unavailable";
-			const label =
-				location.kind === "pdf-page" ? `${itemName} · p. ${location.pageNumber}` : itemName;
+			const locatorLabel = location.kind === "pdf-page" ? `p. ${location.pageNumber}` : undefined;
 
 			if (!item) {
 				return {
 					Icon: FileQuestion,
 					iconClassName: "text-muted-foreground",
-					label,
+					label: itemName,
+					locatorLabel,
 				};
 			}
 
 			const { Icon, iconClassName } = getWorkspaceItemDisplay(item);
-			return { Icon, iconClassName, label };
+			return { Icon, iconClassName, label: itemName, locatorLabel };
 		},
 		reveal(location) {
 			const viewInstanceId = navigate(location);

From 49d82b7c41b59a423f8b0ebd79a0771cd26caa0e Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 28 Jul 2026 10:17:30 -0400
Subject: [PATCH 3/4] style(ai-chat): mute tool row, refactor model picker
 trigger

Tool activity row was rendering at the same weight and near-full text
color as the surrounding chat response, so it competed with the model's
output. Drops it to text-xs + muted-foreground with medium weight so it
reads as a status label one hierarchy level below prose. Also shrinks
the leading icon slot to match.

Model picker trigger swaps the ad-hoc class string for the shared
WorkspaceToolbarTextButton primitive. Removes an unused rounded-full
class from the dictation button.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/ai-chat/AiChatModelPicker.tsx           | 10 ++++++----
 .../components/ai-chat/AiChatPromptInput.tsx           |  1 -
 .../components/ai-chat/AiChatToolActivityRow.tsx       |  8 +++-----
 3 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/src/features/workspaces/components/ai-chat/AiChatModelPicker.tsx b/src/features/workspaces/components/ai-chat/AiChatModelPicker.tsx
index a099dde1..bd03f0d3 100644
--- a/src/features/workspaces/components/ai-chat/AiChatModelPicker.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatModelPicker.tsx
@@ -11,11 +11,9 @@ import {
 	type WorkspaceAiChatModelLevel,
 } from "#/features/workspaces/ai/models";
 import { ProviderLogo } from "#/features/workspaces/components/ai-chat/ProviderLogo";
+import { WorkspaceToolbarTextButton } from "#/features/workspaces/components/WorkspaceToolbar";
 import { cn } from "#/lib/utils";
 
-const TRIGGER_CLASSNAME =
-	"flex h-8.5 items-center gap-1.5 rounded-md px-2 text-sm font-normal text-muted-foreground transition-colors outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring aria-expanded:text-foreground";
-
 interface AiChatModelPickerProps {
 	modelId: WorkspaceAiChatModelId;
 	onModelChange?: (modelId: WorkspaceAiChatModelId) => void;
@@ -55,7 +53,11 @@ export default function AiChatModelPicker({ modelId, onModelChange }: AiChatMode
 				}
 			}}
 		>
-			<PopoverTrigger className={TRIGGER_CLASSNAME}>
+			<PopoverTrigger
+				render={
+					<WorkspaceToolbarTextButton className="min-w-0 max-w-48 px-2 font-normal sm:px-2" />
+				}
+			>
 				<span className="truncate">{selectedModel.name}</span>
 				<ChevronUp className="size-3.5 shrink-0 opacity-60" />
 			</PopoverTrigger>
diff --git a/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx b/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx
index 03b5a87f..3ea7acc0 100644
--- a/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatPromptInput.tsx
@@ -203,7 +203,6 @@ export default function AiChatPromptInput({
 								aria-label={dictation.isActive ? "Stop dictation" : "Start dictation"}
 								aria-pressed={dictation.isActive}
 								className={cn(
-									"rounded-full",
 									dictation.isActive &&
 										"bg-destructive/10 text-destructive hover:bg-destructive/20 hover:text-destructive",
 								)}
diff --git a/src/features/workspaces/components/ai-chat/AiChatToolActivityRow.tsx b/src/features/workspaces/components/ai-chat/AiChatToolActivityRow.tsx
index aa387da9..f9f72e44 100644
--- a/src/features/workspaces/components/ai-chat/AiChatToolActivityRow.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatToolActivityRow.tsx
@@ -153,14 +153,12 @@ function ActivitySummary({
 			role={isRunning ? "status" : undefined}
 			aria-live={isRunning ? "polite" : undefined}
 			title={activity.summary}
-			className="group/tool-row inline-flex min-w-0 max-w-full items-center gap-1.5 py-0.5 text-sm text-muted-foreground"
+			className="group/tool-row inline-flex min-w-0 max-w-full items-center gap-1.5 py-0.5 text-muted-foreground text-xs"
 		>
-			<span className="grid size-4 shrink-0 place-items-center self-center text-muted-foreground/80">
+			<span className="grid size-3.5 shrink-0 place-items-center self-center text-muted-foreground/70">
 				<ToolActivityIcon icon={presentation.icon} />
 			</span>
-			<span
-				className={cn("min-w-0 truncate font-medium text-foreground/90", isRunning && "shimmer")}
-			>
+			<span className={cn("min-w-0 truncate font-medium", isRunning && "shimmer")}>
 				{activity.summary}
 			</span>
 			<InlineSourceFavicons sources={sourcePreviews.slice(0, INLINE_SOURCE_LIMIT)} />

From b7e033823aca137d35410727e6cee4e7ed05e31a Mon Sep 17 00:00:00 2001
From: Urjit Chakraborty <135136842+urjitc@users.noreply.github.com>
Date: Tue, 28 Jul 2026 10:27:50 -0400
Subject: [PATCH 4/4] fix(workspaces): address citation navigation reviews

Send page requests to the mounted split or maximized PDF viewer.

Load KaTeX copy support only in the browser for node tests and SSR.
---
 .../workspaces/components/WorkspaceLayout.tsx |  3 ++-
 .../ai-chat/AiChatMessageResponse.tsx         | 11 +++++----
 .../locations/workspace-location-context.tsx  |  6 ++---
 .../navigation/useWorkspaceNavigation.ts      | 24 +++++++++++++++++++
 src/types/katex-copy-tex.d.ts                 |  1 +
 5 files changed, 36 insertions(+), 9 deletions(-)
 create mode 100644 src/types/katex-copy-tex.d.ts

diff --git a/src/features/workspaces/components/WorkspaceLayout.tsx b/src/features/workspaces/components/WorkspaceLayout.tsx
index f21fee3b..766f38dc 100644
--- a/src/features/workspaces/components/WorkspaceLayout.tsx
+++ b/src/features/workspaces/components/WorkspaceLayout.tsx
@@ -80,6 +80,7 @@ export function WorkspaceShell({
 	const selectedQuotes = useWorkspaceAiComposerDraftQuotes(workspace.id);
 	const setChatSurfaceMode = useWorkspaceUiStore((state) => state.setChatSurfaceMode);
 	const toggleChatPanel = useWorkspaceUiStore((state) => state.toggleChatPanel);
+	const normalizedUiSession = useWorkspaceUiSession(workspace.id);
 	const realtime = useWorkspaceRealtime({
 		workspaceId: workspace.id,
 		lastSeenRevision: revision,
@@ -117,10 +118,10 @@ export function WorkspaceShell({
 	} = useWorkspaceNavigation({
 		workspace,
 		items,
+		presentation: normalizedUiSession.presentation,
 		activeTabIdFromUrl,
 		activeViewFromUrl,
 	});
-	const normalizedUiSession = useWorkspaceUiSession(workspace.id);
 	const { capabilities: viewCapabilities, viewportMode } = useWorkspaceViewPolicy();
 	const selectedItemIds = useWorkspaceSelectionItemIds(workspace.id);
 	const { chatSurfaceMode, presentation } = normalizedUiSession;
diff --git a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.tsx b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.tsx
index 391c3341..3c02e7c1 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.tsx
@@ -1,12 +1,8 @@
 import { cjk } from "@streamdown/cjk";
 import { createMathPlugin } from "@streamdown/math";
-import { createContext, type ComponentProps, use } from "react";
+import { createContext, type ComponentProps, use, useEffect } from "react";
 import { Streamdown, type StreamdownProps } from "streamdown";
 import "katex/dist/katex.min.css";
-// Installs a global copy listener so selecting rendered math yields its
-// LaTeX source (`$…$` / `$$…$$`) on the clipboard instead of the glyph
-// soup KaTeX renders visually. Matches ChatGPT and Claude.ai's behavior.
-import "katex/contrib/copy-tex";
 import {
 	parseWorkspaceReference,
 	type WorkspaceLocation,
@@ -78,6 +74,11 @@ export function AiChatMessageResponse({
 	workspaceCitationLocations = emptyWorkspaceCitationLocations,
 	...props
 }: AiChatMessageResponseProps) {
+	useEffect(() => {
+		// This browser-only module installs KaTeX's global copy listener.
+		void import("katex/contrib/copy-tex");
+	}, []);
+
 	const mergedComponents = {
 		...streamdownComponents,
 		...components,
diff --git a/src/features/workspaces/locations/workspace-location-context.tsx b/src/features/workspaces/locations/workspace-location-context.tsx
index a54c6182..01db9890 100644
--- a/src/features/workspaces/locations/workspace-location-context.tsx
+++ b/src/features/workspaces/locations/workspace-location-context.tsx
@@ -1,5 +1,5 @@
 import { FileQuestion, type LucideIcon } from "lucide-react";
-import { createContext, type ReactNode, use, useState } from "react";
+import { createContext, type ReactNode, use, useCallback, useState } from "react";
 
 import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
 import { getWorkspaceItemDisplay } from "#/features/workspaces/model/item-display";
@@ -41,9 +41,9 @@ export function WorkspaceLocationProvider({
 	readonly navigate: (location: WorkspaceLocation) => string | undefined;
 }) {
 	const [revealRequest, setRevealRequest] = useState<WorkspacePdfPageRevealRequest | null>(null);
-	const consumeRevealRequest = (request: WorkspacePdfPageRevealRequest) => {
+	const consumeRevealRequest = useCallback((request: WorkspacePdfPageRevealRequest) => {
 		setRevealRequest((current) => (current === request ? null : current));
-	};
+	}, []);
 	const value: WorkspaceLocationContextValue = {
 		consumeRevealRequest,
 		getPresentation(location) {
diff --git a/src/features/workspaces/navigation/useWorkspaceNavigation.ts b/src/features/workspaces/navigation/useWorkspaceNavigation.ts
index c71a3135..aab1c6ab 100644
--- a/src/features/workspaces/navigation/useWorkspaceNavigation.ts
+++ b/src/features/workspaces/navigation/useWorkspaceNavigation.ts
@@ -11,6 +11,7 @@ import {
 	useWorkspaceTabsStore,
 	type WorkspaceTab,
 } from "#/features/workspaces/state/workspace-tabs-store";
+import type { WorkspacePresentation } from "#/features/workspaces/state/workspace-ui-store";
 
 type OpenWorkspaceItemOptions = {
 	background?: boolean;
@@ -19,13 +20,31 @@ type OpenWorkspaceItemOptions = {
 interface UseWorkspaceNavigationInput {
 	workspace: WorkspaceSummary;
 	items: WorkspaceItem[];
+	presentation: WorkspacePresentation;
 	activeTabIdFromUrl?: string;
 	activeViewFromUrl?: string;
 }
 
+function findPresentedItemViewInstanceId(
+	presentation: WorkspacePresentation,
+	itemId: string,
+): string | undefined {
+	if (presentation.mode === "maximized") {
+		const { pane } = presentation;
+		return pane.kind === "item" && pane.itemId === itemId ? pane.id : undefined;
+	}
+
+	if (presentation.mode === "split") {
+		return presentation.panes.find((pane) => pane.kind === "item" && pane.itemId === itemId)?.id;
+	}
+
+	return undefined;
+}
+
 export function useWorkspaceNavigation({
 	workspace,
 	items,
+	presentation,
 	activeTabIdFromUrl,
 	activeViewFromUrl,
 }: UseWorkspaceNavigationInput) {
@@ -220,6 +239,11 @@ export function useWorkspaceNavigation({
 			return undefined;
 		}
 
+		const presentedViewInstanceId = findPresentedItemViewInstanceId(presentation, item.id);
+		if (presentedViewInstanceId) {
+			return presentedViewInstanceId;
+		}
+
 		if (activeTab?.viewItemId === item.id) {
 			return activeTab.id;
 		}
diff --git a/src/types/katex-copy-tex.d.ts b/src/types/katex-copy-tex.d.ts
new file mode 100644
index 00000000..9785ad31
--- /dev/null
+++ b/src/types/katex-copy-tex.d.ts
@@ -0,0 +1 @@
+declare module "katex/contrib/copy-tex";