Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(desktop): make files multi-instance, deduped by live path (§3)

Diego Zacarias4d499d624107
diff --git a/desktop-app/ui/src/App.tsx b/desktop-app/ui/src/App.tsx
index fd03d866f..e65f21839 100644
--- a/desktop-app/ui/src/App.tsx
+++ b/desktop-app/ui/src/App.tsx
@@ -73,6 +73,7 @@ import {
selectWorkspaceTabAt,
setAppTabSavedRoutePath,
setAppTabTitle,
+ setFilesTabPath,
} from '@lib/workspaceTabs'
import type { WorkspaceTab } from '@lib/workspaceTabs.types'
import { AgentsPage } from '@pages/AgentsPage'
@@ -798,7 +799,6 @@ export function App() {
bytes: number
mimeType: string
} | null>(null)
- const [pendingGfsUri, setPendingGfsUri] = React.useState<string | null>(null)
React.useEffect(() => {
const off = window.clerum.pluginSdk?.onOpenGfsResource?.(resource => {
@@ -816,12 +816,42 @@ export function App() {
return
}
// Folders and non-previewable files belong in the full browser, where the
- // user gets breadcrumbs, download, and sharing.
- setPendingGfsUri(resource.gfsUri)
- vm.handleNavSelect(DESKTOP_ROUTES.files)
+ // user gets breadcrumbs, download, and sharing. Open (or focus) a files tab
+ // AT this gfsUri — dedupe by path focuses the tab already showing it, or
+ // spawns a new instance (mini-spec 06 §3).
+ vm.openFilesSection(resource.gfsUri)
})
return () => off?.()
- }, [vm.handleNavSelect])
+ }, [vm.openFilesSection])
+
+ // Files tab render seam (mini-spec 06 §3). Only the ACTIVE files tab mounts a
+ // FilesPage; it is keyed by that tab's id so switching files tabs remounts and
+ // re-seeds from the incoming tab's persisted path. `filesSeedPath` is captured
+ // at activation (keyed by tab id via a ref) so the live location updates the
+ // page reports back don't re-arm FilesPage's open-once seed effect.
+ const activeFilesTab = vm.activeWorkspaceTab?.kind === 'files' ? vm.activeWorkspaceTab : undefined
+ const activeFilesTabId = activeFilesTab?.id ?? null
+ const activeFilesTabIdRef = React.useRef<string | null>(null)
+ activeFilesTabIdRef.current = activeFilesTabId
+ const filesSeedRef = React.useRef<{ id: string | null; path: string | null }>({
+ id: null,
+ path: null,
+ })
+ if (filesSeedRef.current.id !== activeFilesTabId) {
+ filesSeedRef.current = { id: activeFilesTabId, path: activeFilesTab?.files?.path ?? null }
+ }
+ const filesSeedPath = filesSeedRef.current.path
+ // Persist the browser's live location onto the active files tab. Stable
+ // (reads the active id from a ref), so FilesPage's effect fires only when the
+ // location actually changes; `setFilesTabPath` no-ops when nothing moved.
+ const handleFilesLocationChange = React.useCallback(
+ (gfsUri: string | null, name: string | null) => {
+ const id = activeFilesTabIdRef.current
+ if (!id) return
+ setWorkspaceTabs(state => setFilesTabPath(state, id, gfsUri, name ?? undefined))
+ },
+ [setWorkspaceTabs]
+ )
const closePluginGfsPreview = React.useCallback(() => {
setPluginGfsPreview(null)
@@ -2466,9 +2496,10 @@ export function App() {
)}
{vm.navItem === DESKTOP_ROUTES.files && (
<FilesPage
+ key={activeFilesTabId ?? 'files'}
pushToast={vm.pushToast}
- pendingGfsUri={pendingGfsUri}
- onPendingGfsUriHandled={() => setPendingGfsUri(null)}
+ pendingGfsUri={filesSeedPath}
+ onLocationChange={handleFilesLocationChange}
/>
)}
{vm.navItem === DESKTOP_ROUTES.connectors && <McpServersPage />}
diff --git a/desktop-app/ui/src/__tests__/App.chatDrawer.test.tsx b/desktop-app/ui/src/__tests__/App.chatDrawer.test.tsx
index bad70024c..483a034fb 100644
--- a/desktop-app/ui/src/__tests__/App.chatDrawer.test.tsx
+++ b/desktop-app/ui/src/__tests__/App.chatDrawer.test.tsx
@@ -175,6 +175,15 @@ function makeController(overrides: Partial<AppController> = {}): AppController {
controller.appsPickerActive = false
forceControllerRender()
})
+ // Faithful to the real controller's openFilesSection: open/focus a files tab at
+ // `path` through the real store producer (dedupe by path lives in the store).
+ const openFilesSection = vi.fn((path: string | null = null) => {
+ clearAppsPicker()
+ setWorkspaceTabs((state: WorkspaceState) =>
+ openFilesTab(state, { id: nextWorkspaceTabId(), path })
+ )
+ forceControllerRender()
+ })
const showAppsPicker = vi.fn(() => {
// The picker residual is redundant when an app tab is already active.
if (controller.appsPickerActive) return
@@ -282,6 +291,8 @@ function makeController(overrides: Partial<AppController> = {}): AppController {
showAppsPicker,
clearAppsPicker,
activateWorkspaceChatTab: noop,
+ openFilesSection,
+ lastActiveChatTabId: null,
activeChatId: null,
chatList: [],
latestChatSessions: [],
@@ -1045,6 +1056,84 @@ describe('App app-tab title — live document.title (mini-spec 06 §2)', () => {
})
})
+// Mini-spec 06 §3 — files is multi-instance, deduped by path. A plugin deep-link
+// (`pluginSdk.onOpenGfsResource`, folder / non-previewable) opens or focuses a
+// files tab AT that gfsUri; two distinct gfsUris yield two tabs, re-opening the
+// same one focuses it. Driven through the real store producer (openFilesTab);
+// asserted on the observable files-tab list (T4).
+describe('App files multi-instance — deep-link opens by path (mini-spec 06 §3)', () => {
+ let currentController: AppController
+ let openGfsResourceCb:
+ | ((resource: { kind: string; name: string; gfsUri: string; bytes: number }) => void)
+ | null
+
+ beforeEach(() => {
+ vi.clearAllMocks()
+ sidebarHarness.props = null
+ sandboxUiPageHarness.props = null
+ appHeaderHarness.props = null
+ appHeaderHarness.openNotification = null
+ openGfsResourceCb = null
+ currentController = makeController()
+ vi.mocked(useAppController).mockImplementation(() => useReactiveController(currentController))
+ Object.defineProperty(window, 'clerum', {
+ configurable: true,
+ value: {
+ shortcuts: { onCommand: vi.fn(() => vi.fn()) },
+ app: { rendererReady: vi.fn().mockResolvedValue(undefined) },
+ sandboxUi: {
+ listApps: vi.fn().mockResolvedValue({ apps: [] }),
+ listPendingDeepLinks: vi.fn().mockResolvedValue({ links: [] }),
+ clearPendingDeepLinks: vi.fn().mockResolvedValue(undefined),
+ onDeepLink: vi.fn(() => vi.fn()),
+ setVisible: vi.fn().mockResolvedValue(undefined),
+ setBounds: vi.fn().mockResolvedValue(undefined),
+ focusActive: vi.fn().mockResolvedValue(true),
+ close: vi.fn().mockResolvedValue(undefined),
+ },
+ pluginSdk: {
+ onOpenGfsResource: vi.fn(
+ (
+ cb: (resource: { kind: string; name: string; gfsUri: string; bytes: number }) => void
+ ) => {
+ openGfsResourceCb = cb
+ return vi.fn()
+ }
+ ),
+ },
+ } as unknown as Window['clerum'],
+ })
+ })
+
+ afterEach(() => {
+ cleanup()
+ delete (window as { clerum?: unknown }).clerum
+ })
+
+ it('opens two files tabs for two distinct gfsUris and focuses the existing one on re-open', () => {
+ render(<App />)
+ const filesTabs = () => currentController.workspaceTabs.tabs.filter(t => t.kind === 'files')
+
+ // Two distinct deep-links -> two separate files tabs, in open order.
+ act(() =>
+ openGfsResourceCb?.({ kind: 'directory', name: 'A', gfsUri: 'gfs://main/aaa', bytes: 0 })
+ )
+ act(() =>
+ openGfsResourceCb?.({ kind: 'directory', name: 'B', gfsUri: 'gfs://main/bbb', bytes: 0 })
+ )
+ expect(filesTabs().map(t => t.files?.path)).toEqual(['gfs://main/aaa', 'gfs://main/bbb'])
+ expect(currentController.navItem).toBe(DESKTOP_ROUTES.files)
+
+ // Re-opening the FIRST gfsUri focuses the existing tab — no third tab.
+ const firstId = filesTabs()[0]!.id
+ act(() =>
+ openGfsResourceCb?.({ kind: 'directory', name: 'A', gfsUri: 'gfs://main/aaa', bytes: 0 })
+ )
+ expect(filesTabs()).toHaveLength(2)
+ expect(currentController.workspaceTabs.activeTabId).toBe(firstId)
+ })
+})
+
// Mini-spec 05: below the minimum panel width the drawer is SUPPRESSED (hidden,
// app takes full width) without clearing the user's open intent, so it reappears
// when the window re-widens; a MANUAL close clears the intent, so it stays gone.
diff --git a/desktop-app/ui/src/hooks/domain/useNavigationController.ts b/desktop-app/ui/src/hooks/domain/useNavigationController.ts
index f72ca8042..c39064278 100644
--- a/desktop-app/ui/src/hooks/domain/useNavigationController.ts
+++ b/desktop-app/ui/src/hooks/domain/useNavigationController.ts
@@ -133,10 +133,16 @@ export function useNavigationController() {
[nextWorkspaceTabId]
)
- const openFilesSection = useCallback(() => {
- setAppsPickerActive(false)
- setWorkspaceTabs(current => openFilesTab(current, { id: nextWorkspaceTabId() }))
- }, [nextWorkspaceTabId])
+ // Open/focus a files tab at `path` (a gfsUri, or `null` for the virtual root).
+ // Dedupes by path in the store: the sidebar "Files" entry (root) and a plugin
+ // deep-link to a specific gfsUri both route here (mini-spec 06 §3).
+ const openFilesSection = useCallback(
+ (path: string | null = null) => {
+ setAppsPickerActive(false)
+ setWorkspaceTabs(current => openFilesTab(current, { id: nextWorkspaceTabId(), path }))
+ },
+ [nextWorkspaceTabId]
+ )
// Base section navigation: every legacy `handleNavSelect(route)` call-site
// routes here and becomes an open/focus tab action (the single writer). For
@@ -189,6 +195,7 @@ export function useNavigationController() {
clearAppsPicker,
activateChatTab,
lastActiveChatTabId,
+ openFilesSection,
// Agent/chat selection state (stays here through this slice; §4).
selectedAgent,
selectedAgentRoute,
diff --git a/desktop-app/ui/src/hooks/useAppController.ts b/desktop-app/ui/src/hooks/useAppController.ts
index d5440d2db..bfe29b13d 100644
--- a/desktop-app/ui/src/hooks/useAppController.ts
+++ b/desktop-app/ui/src/hooks/useAppController.ts
@@ -1350,6 +1350,7 @@ export function useAppController() {
clearAppsPicker: nav.clearAppsPicker,
activateWorkspaceChatTab: nav.activateChatTab,
lastActiveChatTabId: nav.lastActiveChatTabId,
+ openFilesSection: nav.openFilesSection,
handleOpenAgentWorkspace,
handleSelectChatAgent,
handleEnsureTeamContext: ensureTeamContext,
diff --git a/desktop-app/ui/src/lib/__tests__/workspaceTabs.test.ts b/desktop-app/ui/src/lib/__tests__/workspaceTabs.test.ts
index 0adb9871d..d7a77a13c 100644
--- a/desktop-app/ui/src/lib/__tests__/workspaceTabs.test.ts
+++ b/desktop-app/ui/src/lib/__tests__/workspaceTabs.test.ts
@@ -19,6 +19,7 @@ import {
selectWorkspaceTabAt,
setAppTabSavedRoutePath,
setAppTabTitle,
+ setFilesTabPath,
} from '../workspaceTabs'
import type { ActiveChat, SettingsSection, WorkspaceTabsState } from '../workspaceTabs.types'
@@ -217,6 +218,99 @@ describe('workspaceTabs — setAppTabTitle (mini-spec 06 §2)', () => {
})
})
+describe('workspaceTabs — files multi-instance by path (mini-spec 06 §3)', () => {
+ it('opens distinct tabs for distinct paths and dedupes (focuses) the same path', () => {
+ let state = createEmptyWorkspaceTabsState()
+ state = openFilesTab(state, { id: 'f-root', path: null })
+ state = openFilesTab(state, { id: 'f-a', path: 'gfs://main/aaa' })
+ state = openFilesTab(state, { id: 'f-b', path: 'gfs://main/bbb' })
+ expect(state.tabs.filter(t => t.kind === 'files')).toHaveLength(3)
+ expect(state.activeTabId).toBe('f-b')
+
+ // Re-opening an existing path FOCUSES it — no new tab.
+ const before = state.tabs.length
+ state = openFilesTab(state, { id: 'f-a-again', path: 'gfs://main/aaa' })
+ expect(state.tabs.length).toBe(before)
+ expect(state.activeTabId).toBe('f-a')
+ // Root (absent path) dedupes to the single root tab.
+ state = openFilesTab(state, { id: 'f-root-again' })
+ expect(state.tabs.filter(t => t.kind === 'files')).toHaveLength(3)
+ expect(state.activeTabId).toBe('f-root')
+ })
+
+ it('aligns the title when focusing an existing path', () => {
+ let state = createEmptyWorkspaceTabsState()
+ state = openFilesTab(state, { id: 'f-a', path: 'gfs://main/aaa', title: 'Old' })
+ state = openFilesTab(state, { id: 'f-a2', path: 'gfs://main/aaa', title: 'Reports' })
+ expect(state.tabs.filter(t => t.kind === 'files')).toHaveLength(1)
+ expect(state.tabs.find(t => t.kind === 'files')?.title).toBe('Reports')
+ })
+
+ it('setFilesTabPath persists the live gfsUri + folder-name title', () => {
+ let state = createEmptyWorkspaceTabsState()
+ state = openFilesTab(state, { id: 'f-1', path: null })
+ state = setFilesTabPath(state, 'f-1', 'gfs://main/ccc', 'Invoices')
+ const tab = state.tabs.find(t => t.id === 'f-1')
+ expect(tab?.files?.path).toBe('gfs://main/ccc')
+ expect(tab?.title).toBe('Invoices')
+ // Back to the virtual root: path null, title 'Files'.
+ state = setFilesTabPath(state, 'f-1', null)
+ const rooted = state.tabs.find(t => t.id === 'f-1')
+ expect(rooted?.files?.path).toBeNull()
+ expect(rooted?.title).toBe('Files')
+ })
+
+ it('setFilesTabPath is a no-op (same ref) when nothing moved, or the tab is missing / not files', () => {
+ let state = createEmptyWorkspaceTabsState()
+ state = openFilesTab(state, { id: 'f-1', path: 'gfs://main/aaa', title: 'Reports' })
+ state = openAppTab(state, { id: 'app-1', appRef: 'x' })
+ // Same path + same title -> same reference.
+ expect(setFilesTabPath(state, 'f-1', 'gfs://main/aaa', 'Reports')).toBe(state)
+ // Empty title normalizes to 'Files', so if the title already differs this is
+ // NOT a no-op; here the stored title is 'Reports', so passing '' would change
+ // it — assert the missing/not-files no-ops instead.
+ expect(setFilesTabPath(state, 'gone', 'gfs://main/zzz', 'Z')).toBe(state)
+ expect(setFilesTabPath(state, 'app-1', 'gfs://main/zzz', 'Z')).toBe(state)
+ })
+
+ it('does NOT re-dedupe: two tabs may hold the same path after setFilesTabPath (open-time only)', () => {
+ let state = createEmptyWorkspaceTabsState()
+ state = openFilesTab(state, { id: 'f-a', path: 'gfs://main/aaa' })
+ state = openFilesTab(state, { id: 'f-b', path: 'gfs://main/bbb' })
+ // f-b navigates to the SAME path as f-a — no hot re-dedupe collapses them.
+ state = setFilesTabPath(state, 'f-b', 'gfs://main/aaa', 'Same')
+ const filesTabs = state.tabs.filter(t => t.kind === 'files')
+ expect(filesTabs).toHaveLength(2)
+ expect(filesTabs.every(t => t.files?.path === 'gfs://main/aaa')).toBe(true)
+ })
+
+ // T2 property: dedupe by path is an equivalence on the files sub-slice.
+ it('property: one files tab per distinct path; root is a single tab', () => {
+ const pathArb = fc.option(fc.constantFrom('gfs://main/a', 'gfs://main/b', 'gfs://main/c'), {
+ nil: null,
+ })
+ fc.assert(
+ fc.property(fc.array(pathArb, { maxLength: 40 }), paths => {
+ let state = createEmptyWorkspaceTabsState()
+ paths.forEach((path, i) => {
+ state = openFilesTab(state, { id: `f-${i}`, path })
+ })
+ const filesTabs = state.tabs.filter(t => t.kind === 'files')
+ // One tab per DISTINCT path (null included) that was opened.
+ const distinctPaths = new Set(paths.map(p => p ?? null))
+ expect(filesTabs.length).toBe(paths.length === 0 ? 0 : distinctPaths.size)
+ // No two files tabs share a path (open-time dedupe).
+ const seen = new Set<string | null>()
+ for (const t of filesTabs) {
+ const p = t.files?.path ?? null
+ expect(seen.has(p)).toBe(false)
+ seen.add(p)
+ }
+ })
+ )
+ })
+})
+
describe('workspaceTabs — new chat (blank) with kind guard', () => {
it('reuses the active blank chat tab (aligns the agent)', () => {
let state = createWorkspaceTabsState('boot', null)
diff --git a/desktop-app/ui/src/lib/workspaceTabs.ts b/desktop-app/ui/src/lib/workspaceTabs.ts
index 9061a5165..89a40cef9 100644
--- a/desktop-app/ui/src/lib/workspaceTabs.ts
+++ b/desktop-app/ui/src/lib/workspaceTabs.ts
@@ -214,12 +214,22 @@ export function setAppTabTitle(
}
}
-/** Files: single instance — focus the existing tab if present (R8). */
+/**
+ * Files: multi-instance, deduped by `path` (mini-spec 06 §3, supersedes R8's
+ * single instance). Opening a `path` that already has a files tab FOCUSES it
+ * (aligning its title); otherwise a new files tab is created. An absent path is
+ * the virtual root (`null`), which collapses to a single root files tab. Dedupe
+ * is applied ONLY here (open-time): two tabs may later navigate to the same
+ * path independently, and that is left as-is (no hot re-dedupe).
+ */
export function openFilesTab(
state: WorkspaceTabsState,
input: OpenFilesTabInput
): WorkspaceTabsState {
- const existing = state.tabs.find(tab => tab.kind === 'files')
+ const path = input.path ?? null
+ const existing = state.tabs.find(
+ tab => tab.kind === 'files' && (tab.files?.path ?? null) === path
+ )
const title = input.title?.trim()
if (existing) {
return {
@@ -230,10 +240,45 @@ export function openFilesTab(
activeTabId: existing.id,
}
}
- const tab: WorkspaceTab = { id: input.id, kind: 'files', title: title || 'Files' }
+ const tab: WorkspaceTab = {
+ id: input.id,
+ kind: 'files',
+ title: title || 'Files',
+ files: { path },
+ }
return { tabs: [...state.tabs, tab], activeTabId: input.id }
}
+/**
+ * Persist the live location of a files tab (mini-spec 06 §3), the files analogue
+ * of `setAppTabSavedRoutePath`: as the browser navigates, its leaf `gfsUri` is
+ * written back onto the tab (with the current folder name as the title; the
+ * virtual root → 'Files'). A no-op (same reference) when the tab is missing, is
+ * not a files tab, or already holds this path AND title, so a `setState` bails
+ * out. It does NOT re-dedupe — dedupe is an open-time rule only (§3).
+ *
+ * `title` is the current folder's display name (which the opaque `gfsUri` does
+ * not carry), supplied by the browser; absent / empty ⇒ 'Files'.
+ */
+export function setFilesTabPath(
+ state: WorkspaceTabsState,
+ tabId: string,
+ path: string | null,
+ title?: string
+): WorkspaceTabsState {
+ const target = state.tabs.find(tab => tab.id === tabId && tab.kind === 'files')
+ if (!target) return state
+ const nextPath = path ?? null
+ const nextTitle = title?.trim() || 'Files'
+ if ((target.files?.path ?? null) === nextPath && target.title === nextTitle) return state
+ return {
+ ...state,
+ tabs: state.tabs.map(tab =>
+ tab.id === tabId ? { ...tab, title: nextTitle, files: { path: nextPath } } : tab
+ ),
+ }
+}
+
/** Settings: unique per `section` — focus the existing section tab (R6). */
export function openSettingsTab(
state: WorkspaceTabsState,
diff --git a/desktop-app/ui/src/lib/workspaceTabs.types.ts b/desktop-app/ui/src/lib/workspaceTabs.types.ts
index a6073f9b8..96feb816f 100644
--- a/desktop-app/ui/src/lib/workspaceTabs.types.ts
+++ b/desktop-app/ui/src/lib/workspaceTabs.types.ts
@@ -16,10 +16,21 @@ export type SettingsTabPayload = {
section: SettingsSection
}
+/**
+ * A files tab's live location (mini-spec 06 §3): `path` is the leaf `gfsUri`
+ * (`gfs://<drive>/<rid>`) the browser is currently showing, or `null` for the
+ * virtual root ("Shared with me"). It is the tab's dedupe key AND its
+ * live-persisted location — the files analogue of `AppTabPayload.savedRoutePath`.
+ */
+export type FilesTabPayload = {
+ path: string | null
+}
+
/**
* A single tab in the universal strip. `kind` discriminates the payload:
* `chat` carries `chat`, `app` carries `app`, `settings` carries `settings`,
- * and `files` carries no payload (single instance, R8).
+ * and `files` carries `files` (its live gfsUri; multi-instance by path, §3 —
+ * supersedes R8's single instance).
*/
export type WorkspaceTab = {
id: string
@@ -28,6 +39,7 @@ export type WorkspaceTab = {
chat?: ChatTabPayload
app?: AppTabPayload
settings?: SettingsTabPayload
+ files?: FilesTabPayload
}
/**
@@ -57,6 +69,11 @@ export type OpenAppTabInput = {
export type OpenFilesTabInput = {
id: string
title?: string
+ /**
+ * The gfsUri to open at (dedupe key). Absent / `undefined` ⇒ `null` (the
+ * virtual root — a single root files tab).
+ */
+ path?: string | null
}
export type OpenSettingsTabInput = {
diff --git a/desktop-app/ui/src/pages/FilesPage.tsx b/desktop-app/ui/src/pages/FilesPage.tsx
index 7b8c38569..c22092044 100644
--- a/desktop-app/ui/src/pages/FilesPage.tsx
+++ b/desktop-app/ui/src/pages/FilesPage.tsx
@@ -208,7 +208,12 @@ function GfsInlineRename({
)
}
-export function FilesPage({ pushToast, pendingGfsUri, onPendingGfsUriHandled }: FilesPageProps) {
+export function FilesPage({
+ pushToast,
+ pendingGfsUri,
+ onPendingGfsUriHandled,
+ onLocationChange,
+}: FilesPageProps) {
const [createFolderName, setCreateFolderName] = useState('')
const [createFolderOpen, setCreateFolderOpen] = useState(false)
const [createFolderError, setCreateFolderError] = useState<string | null>(null)
@@ -606,6 +611,16 @@ export function FilesPage({ pushToast, pendingGfsUri, onPendingGfsUriHandled }:
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [pendingGfsUri])
+ // Report the live location (leaf gfsUri + folder name) so the owning files tab
+ // persists it (mini-spec 06 §3). `current` is the top of the breadcrumb stack;
+ // `null` is the virtual root. Deps track the primitive fields so a re-render
+ // that leaves the location unchanged does not re-emit.
+ const currentGfsUri = current?.gfsUri ?? null
+ const currentName = current?.name ?? null
+ useEffect(() => {
+ onLocationChange?.(currentGfsUri, currentName)
+ }, [currentGfsUri, currentName, onLocationChange])
+
const handleCreateFolder = async () => {
const requestedName = createFolderName.trim()
if (!requestedName) return
diff --git a/desktop-app/ui/src/pages/FilesPage.types.ts b/desktop-app/ui/src/pages/FilesPage.types.ts
index f4a4c37a0..01e109adf 100644
--- a/desktop-app/ui/src/pages/FilesPage.types.ts
+++ b/desktop-app/ui/src/pages/FilesPage.types.ts
@@ -20,6 +20,14 @@ export interface FilesPageProps {
*/
pendingGfsUri?: string | null
onPendingGfsUriHandled?: () => void
+ /**
+ * Reports the browser's live location so the owning files tab can persist it
+ * (mini-spec 06 §3). Emits the current leaf `gfsUri` (the stable identity) and
+ * the current folder's display name (the tab title) whenever the location
+ * changes, including back to the virtual root (`null`, `null`). The opaque
+ * `gfsUri` carries no name, hence the second argument.
+ */
+ onLocationChange?: (gfsUri: string | null, name: string | null) => void
}
/**