Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
'use client'
import React, { useCallback, useEffect, useRef, useState } from 'react'
import { SingleValueEditDialog } from '@clerum/frontend-components'
import {
GFS_MOVE_MAX_NETWORK_ATTEMPTS,
GFS_UPLOAD_NAME_EXHAUSTED_MESSAGE,
GFS_UPLOAD_NAME_RETRY_LIMIT,
createGfsUploadNameReservationBook,
decideDragPathStructure,
gfsUploadNameRetryDecision,
isGfsNameConflict,
nextAvailableGfsResourceName,
normalizeCanonicalPath,
normalizeGfsResourceName,
parentPathOf,
planMoveConvergence,
} from '@clerum/gfs-interaction-policy'
import { FileUploadModal } from '@components/FileUploadModal'
import { GfsImagePreview } from '@components/GfsImagePreview'
import { GfsMarkdownPreview } from '@components/GfsMarkdownPreview'
import { GfsMoveConfirmDialog } from '@components/GfsMoveConfirmDialog'
import { GfsMoveDialog } from '@components/GfsMoveDialog'
import { GfsOpenLinkModal } from '@components/GfsOpenLinkModal'
import { GfsVideoPreview } from '@components/GfsVideoPreview'
import {
IconDocumentText,
IconFolder,
IconImage,
IconServer,
IconVideo,
} from '@components/Sidebar/icons'
import { useToast } from '@components/Toast'
import {
IconChevronRight,
IconHardDrive,
IconPaperclip,
IconUpload,
IconX,
} from '@components/icons'
import { Button, Field, TextInput } from '@components/ui'
import {
AuthExpiredError,
apiGet,
apiSend,
getGfsResourceByPath,
gfsDownload,
handleControlUIUnauthorized,
isSilentApiError,
} from '@lib/api'
import { createCoalescedRevalidation } from '@lib/coalescedRevalidation'
import {
ENTITY_CHANGE_MAX_FRAME_CHARS,
entityChangeStreamUrl,
parseEntityChangeFrame,
parseEntityChangeRetryAfterMs,
} from '@lib/entityChangeStream'
import { watchEntityChangeStreamLiveness } from '@lib/entityChangeStreamLiveness'
import { isGfsDocumentFile } from '@lib/gfsDocumentFile'
import {
GfsMoveRefusalError,
computeGfsDropHoverVerdict,
gfsDropHoverAnnouncement,
gfsDropRefusalMessage,
gfsDropRefusalTone,
} from '@lib/gfsDragFeedback'
import type {
GfsDropHoverVerdict,
GfsDropRefusalReason,
GfsEndpointRead,
GfsMoveDestination,
GfsResolvedEndpointView,
} from '@lib/gfsDragFeedback.types'
import {
GfsUploadCapabilityError,
type GfsUploadJob,
type GfsUploadJobInput,
type GfsUploadJobSnapshot,
assertGfsFileUploadSize,
createGfsUploadJob,
uploadGfsFileLegacy,
} from '@lib/gfsFileUpload'
import { resolveGfsHierarchy } from '@lib/gfsHierarchyRevalidation'
import { gfsImagePreviewMimeType } from '@lib/gfsImagePreview'
import { GfsLoadArbiter } from '@lib/gfsLoadArbitration'
import { isGfsMarkdownPreviewFile } from '@lib/gfsMarkdownPreview'
import { isGfsVideoFile } from '@lib/gfsVideoFile'
import { gfsVideoPreviewMimeType } from '@lib/gfsVideoPreview'
import { GfsGrantPanel } from './GfsGrantPanel'
import { GfsResourceMenu } from './GfsResourceMenu'
import { NewFolderModal } from './NewFolderModal'
import { TablePanelHeader } from './TablePanelHeader'
/** A child node as returned by /api/v1/gfs/tree and /resources/:id/children. */
interface GfsChild {
resourceId: string
rid: string
gfsUri: string
name: string
kind: string
path: string | null
bytes: number
version: number
}
interface TreePage {
items: GfsChild[]
nextCursor: string | null
rootResourceId?: string
loadedPageCount?: number
}
type OpenPreviewState =
| {
kind: 'image'
gfsUri: string
byteLength: number
fileName: string
mimeType: string
rid: string
version: number
reloadVersion: number
unavailable: boolean
}
| {
kind: 'markdown'
gfsUri: string
byteLength: number
fileName: string
rid: string
version: number
reloadVersion: number
unavailable: boolean
}
| {
kind: 'video'
gfsUri: string
byteLength: number
fileName: string
mimeType: string
rid: string
version: number
reloadVersion: number
unavailable: boolean
}
type ResolvedPreviewUpdate =
| Extract<OpenPreviewState, { kind: 'image' }>
| Extract<OpenPreviewState, { kind: 'markdown' }>
| Extract<OpenPreviewState, { kind: 'video' }>
interface Crumb {
/** True when this is the stable drive-root location, independent of its resource ID. */
isDriveRoot?: boolean
/** Null only until /gfs/tree resolves the drive root's resource ID. */
id: string | null
rid: string | null
name: string
/** Folder crumbs carry the identity their ⋯ menu actions need; the
* synthetic root has none and gets no menu. */
kind?: 'directory'
gfsUri?: string
version?: number
}
function isDriveRootCrumb(crumb: Crumb | undefined): boolean {
return crumb?.isDriveRoot === true || crumb?.id === null
}
function sameCrumbLocation(left: Crumb | undefined, right: Crumb): boolean {
if (isDriveRootCrumb(left) || isDriveRootCrumb(right)) {
return isDriveRootCrumb(left) && isDriveRootCrumb(right)
}
return left?.id === right.id
}
function createDriveRootCrumb(): Crumb {
return { id: null, rid: null, name: '/', isDriveRoot: true }
}
interface GfsResolvedLocation {
resourceId: string
rid: string
gfsUri: string
name: string
kind: string
path: string | null
version: number
}
/** Project every response-backed folder source through one version-preserving
* breadcrumb adapter. An incomplete runtime payload remains browseable but
* never gains a fabricated mutation precondition. */
function folderResourceToCrumb(
resource: Pick<GfsChild, 'resourceId' | 'rid' | 'gfsUri' | 'name' | 'kind'> & {
version?: number
}
): Crumb {
return {
id: resource.resourceId,
rid: resource.rid,
name: resource.name,
kind: 'directory',
gfsUri: resource.gfsUri,
...(Number.isSafeInteger(resource.version) ? { version: resource.version } : {}),
}
}
function sameCrumbTrail(left: Crumb[], right: Crumb[]): boolean {
return (
left.length === right.length &&
left.every((crumb, index) => {
const other = right[index]
return (
crumb.id === other?.id &&
isDriveRootCrumb(crumb) === isDriveRootCrumb(other) &&
crumb.rid === other.rid &&
crumb.gfsUri === other.gfsUri &&
crumb.name === other.name &&
crumb.version === other.version
)
})
)
}
/** Verdict of a breadcrumb ancestry reconstruction attempt (R7-M1 race).
* 'superseded' means a newer Move, reconstruction, rename, or navigation
* invalidated this attempt while its requests were in flight — callers must
* leave the breadcrumb trail AND the recovery notice untouched so the
* newer operation's state survives. */
type TrailReconstructionOutcome = 'applied' | 'failed' | 'superseded'
const DRIVE = 'main'
const PENDING_GFS_UPLOAD_KEY = 'evenfire:gfs-upload-v2:pending'
const GFS_RESOURCE_DRAG_TYPE = 'application/x-evenfire-gfs-resource'
interface PendingGfsUpload {
uploadId?: string
idempotencyKey?: string
fileName: string
fileSize: number
lastModified: number
target: {
operation: 'create' | 'replace'
parentRid?: string
resourceRid?: string
ifMatch?: number
}
name: string
}
function readPendingGfsUpload(): PendingGfsUpload | null {
if (typeof window === 'undefined') return null
try {
const parsed = JSON.parse(
window.localStorage.getItem(PENDING_GFS_UPLOAD_KEY) || 'null'
) as Partial<PendingGfsUpload> | null
if (
!parsed ||
(typeof parsed.uploadId !== 'string' && typeof parsed.idempotencyKey !== 'string') ||
typeof parsed.fileName !== 'string' ||
typeof parsed.fileSize !== 'number' ||
typeof parsed.lastModified !== 'number' ||
!parsed.target ||
typeof parsed.name !== 'string'
)
return null
return parsed as PendingGfsUpload
} catch {
return null
}
}
function persistPendingGfsUpload(record: PendingGfsUpload): void {
if (typeof window === 'undefined') return
window.localStorage.setItem(PENDING_GFS_UPLOAD_KEY, JSON.stringify(record))
}
function clearPendingGfsUpload(uploadId?: string): void {
if (typeof window === 'undefined') return
const current = readPendingGfsUpload()
if (!uploadId || current?.uploadId === uploadId)
window.localStorage.removeItem(PENDING_GFS_UPLOAD_KEY)
}
function matchingPendingResumeUploadId(
file: File,
target: GfsUploadJobInput['target'],
name: string
): string | undefined {
const pending = readPendingGfsUpload()
if (!pending?.uploadId) return undefined
if (
pending.fileName !== file.name ||
pending.fileSize !== file.size ||
pending.lastModified !== file.lastModified ||
pending.name !== name ||
pending.target.operation !== target.operation ||
pending.target.parentRid !== target.parentRid ||
pending.target.resourceRid !== target.resourceRid ||
pending.target.ifMatch !== target.ifMatch
)
return undefined
return pending.uploadId
}
function formatBytes(bytes: number): string {
if (!Number.isFinite(bytes) || bytes <= 0) return '0 B'
if (bytes < 1024) return `${bytes} B`
const units = ['KB', 'MB', 'GB', 'TB']
let value = bytes / 1024
let unit = units[0]
for (let index = 0; value >= 1024 && index < units.length - 1; index += 1) {
value /= 1024
unit = units[index + 1]
}
return `${value >= 10 ? value.toFixed(0) : value.toFixed(1)} ${unit}`
}
/**
* Operator browser for the Global File System. It lists the drive tree through
* control-api and uses the operator-scoped GFS proxy for create, upload,
* replace, rename, and delete operations while access grants stay on the
* control-api permission surface.
*/
function ridOfResourceId(resourceId: string): string {
return resourceId.replace(/-/g, '').toLowerCase()
}
function hasDraggedFiles(event: React.DragEvent<HTMLElement>): boolean {
return Array.from(event.dataTransfer.types || []).includes('Files')
}
function hasDraggedGfsResource(event: React.DragEvent<HTMLElement>): boolean {
return Array.from(event.dataTransfer.types || []).includes(GFS_RESOURCE_DRAG_TYPE)
}
function isGfsPreviewFile(fileName: string): boolean {
return (
gfsImagePreviewMimeType(fileName) !== null ||
isGfsMarkdownPreviewFile(fileName) ||
gfsVideoPreviewMimeType(fileName) !== null
)
}
function isEventFromNestedInteractive(
event: React.MouseEvent<HTMLLIElement> | React.KeyboardEvent<HTMLLIElement>
): boolean {
const target = event.target
if (!(target instanceof Element)) return false
return (
target.closest('button, a, input, select, textarea, [role="button"], [role="menuitem"]') !==
null
)
}
function isTransientEntityChangeRefetchError(error: unknown): boolean {
const status =
error && typeof error === 'object' ? (error as { status?: unknown }).status : undefined
if (typeof status === 'number') {
return status === 408 || status === 425 || status === 429 || status >= 500
}
if (error instanceof TypeError) return true
return (
error instanceof Error &&
/network|fetch|timeout|timed out|socket|connection/i.test(error.message)
)
}
function entityChangeErrorStatus(error: unknown): number | undefined {
if (!error || typeof error !== 'object') return undefined
const status = (error as { status?: unknown }).status
return typeof status === 'number' ? status : undefined
}
export function GfsBrowser(): React.JSX.Element {
const { showToast } = useToast()
const [crumbs, setCrumbs] = useState<Crumb[]>([createDriveRootCrumb()])
const [items, setItems] = useState<GfsChild[]>([])
const [nextCursor, setNextCursor] = useState<string | null>(null)
const [loading, setLoading] = useState(true)
const [loadingMore, setLoadingMore] = useState(false)
const [error, setError] = useState('')
const loadArbiterRef = useRef(new GfsLoadArbiter())
const entityChangeRefetchControllerRef = useRef<AbortController | null>(null)
const loadedPageCountRef = useRef(1)
const foregroundLoadsInFlightRef = useRef(0)
const pendingStreamRevalidationRef = useRef(false)
const requestStreamRevalidationRef = useRef<(cursor?: string) => void>(() => undefined)
const loadedLocationRef = useRef<string | null | undefined>(undefined)
// Operator selects a resource to delegate access on (grant panel).
const [selected, setSelected] = useState<GfsChild | null>(null)
const selectedRef = useRef(selected)
selectedRef.current = selected
const [renameTarget, setRenameTarget] = useState<GfsChild | null>(null)
const renameTargetRef = useRef(renameTarget)
renameTargetRef.current = renameTarget
const [renaming, setRenaming] = useState(false)
const [renameError, setRenameError] = useState('')
const [renameValid, setRenameValid] = useState(true)
const [deleteOpen, setDeleteOpen] = useState(false)
const deleteOpenRef = useRef(deleteOpen)
deleteOpenRef.current = deleteOpen
// "Open EvenDrive link" dialog launched from the folder ⋯ menus.
const [openLinkOpen, setOpenLinkOpen] = useState(false)
const [openLinkResolving, setOpenLinkResolving] = useState(false)
const [openLinkError, setOpenLinkError] = useState<string | null>(null)
// New-folder dialog (replaces the native window.prompt flow).
const [newFolderOpen, setNewFolderOpen] = useState(false)
const [creatingFolder, setCreatingFolder] = useState(false)
const [createFolderError, setCreateFolderError] = useState<string | null>(null)
const [uploadOpen, setUploadOpen] = useState(false)
const [uploadCandidate, setUploadCandidate] = useState<File | null>(null)
const [uploading, setUploading] = useState(false)
const uploadJobRef = useRef<GfsUploadJob | null>(null)
const uploadNameReservationsRef = useRef(createGfsUploadNameReservationBook())
const [uploadSnapshot, setUploadSnapshot] = useState<GfsUploadJobSnapshot | null>(null)
const [dragActive, setDragActive] = useState(false)
const [droppedUploadCount, setDroppedUploadCount] = useState(0)
const [draggingResourceId, setDraggingResourceId] = useState<string | null>(null)
const [dragOverFolderId, setDragOverFolderId] = useState<string | null>(null)
const [dragOverCrumbIndex, setDragOverCrumbIndex] = useState<number | null>(null)
const [movingResourceId, setMovingResourceId] = useState<string | null>(null)
const [moveTarget, setMoveTarget] = useState<GfsChild | null>(null)
// rev-2 §1 + breadcrumb plan §3.2: a drag DROP stops at ONE confirmation
// (impact + naming policy) for folders AND for breadcrumb drops of either
// kind; row file drops keep moving directly; the Move dialog is its own
// confirmation. The destination is captured IMMUTABLY at drop so a later
// trail rebuild can never re-anchor the commit (R7-M1).
const [confirmMoveTarget, setConfirmMoveTarget] = useState<{
source: GfsChild
destination: GfsMoveDestination
suggestedName?: string
epoch: number
/** Physical source parent captured at the drop boundary (R7): drives
* convergence invalidation when the commit finally runs. */
oldParentId: string | null
} | null>(null)
const moveTargetRef = useRef(moveTarget)
moveTargetRef.current = moveTarget
// R5-M1 recovery: the Move PATCH succeeded but the breadcrumb trail could
// not be reconstructed from the folder's new location. The trail stays
// as-was — explicitly stale, never shortened and presented as
// authoritative — with this notice until a retry rebuilds it or the
// operator navigates away from the moved folder. The snapshot carries
// IMMUTABLE identity only (R7-M1): name and version are deliberately NOT
// captured, so a retry can never replay move-time metadata over a crumb
// that a later rename/mutation has since advanced.
const [trailRecovery, setTrailRecovery] = useState<{
resourceId: string
gfsUri: string
reason: 'move' | 'hierarchy'
} | null>(null)
// Matrix A11: an endpoint read that came back 401 during a drag move.
// Session loss is TERMINAL for the gesture and must stay visible while the
// surface is mounted — a transient toast read as a connection hiccup and
// invited retries that could never succeed.
const [sessionLost, setSessionLost] = useState(false)
// Monotonic epoch for breadcrumb-reconstruction attempts (R7-M1 race). A
// reconstruction (a move's rebuild or a Retry) captures the epoch at start
// and may apply its result only while it is still the LATEST attempt. Any
// newer reconstruction, a later Move's rebuild, a rename, or a navigation
// that replaces/leaves the trail bumps the epoch, so a superseded in-flight
// response is discarded instead of overwriting the newer ancestry or
// clearing the newer operation's recovery notice. Appending a DESCENDANT
// (openDirectory) does not bump: it never invalidates the retry target's
// ancestors and the functional apply carries the live tail along.
const trailReconstructionEpochRef = useRef(0)
const draggingResourceRef = useRef<GfsChild | null>(null)
const movingResourceRef = useRef<string | null>(null)
// Monotonic drag-gesture epoch (breadcrumb plan §3.4). A newer dragstart
// bumps it and thereby supersedes every pending admission read, the open
// confirmation, and any commit read that has not dispatched its PATCH yet.
// Dragend does NOT bump it: it only clears presentation, so a drop the
// browser already accepted keeps its async admission/commit. Unmount bumps
// it as well, so no stale closure can dispatch after the surface is gone.
const dragGestureEpochRef = useRef(0)
const mountedRef = useRef(true)
useEffect(() => {
mountedRef.current = true
return () => {
mountedRef.current = false
dragGestureEpochRef.current += 1
}
}, [])
// The physical source-parent ID observed at dragstart (null = the synthetic
// drive root). Active-crumb and own-parent drops resolve to same-parent
// from this observation without any network round-trip.
const dragSourceParentIdRef = useRef<string | null>(null)
const isGestureEpochCurrent = useCallback((epoch: number): boolean => {
return mountedRef.current && epoch === dragGestureEpochRef.current
}, [])
const [imagePreview, setImagePreview] = useState<Extract<
OpenPreviewState,
{ kind: 'image' }
> | null>(null)
const [markdownPreview, setMarkdownPreview] = useState<Extract<
OpenPreviewState,
{ kind: 'markdown' }
> | null>(null)
const [videoPreview, setVideoPreview] = useState<Extract<
OpenPreviewState,
{ kind: 'video' }
> | null>(null)
const previewRefreshGenerationRef = useRef(0)
const openPreviewsRef = useRef<OpenPreviewState[]>([])
openPreviewsRef.current = [imagePreview, markdownPreview, videoPreview].filter(
(preview): preview is OpenPreviewState => preview !== null
)
// Resource IDs currently streaming a download (disables that row's button).
const [downloadingIds, setDownloadingIds] = useState<ReadonlySet<string>>(() => new Set())
/**
* Keep progress truthful when in-flight part observations arrive out of
* order. Only stale uploading snapshots are monotonic; direct progress and
* terminal/paused snapshots are accepted exactly.
*/
const mergeUploadSnapshot = useCallback((next: GfsUploadJobSnapshot): void => {
setUploadSnapshot(previous => {
if (!previous) return next
const previousUploadId = previous.session?.uploadId
const nextUploadId = next.session?.uploadId
if (
(previousUploadId && nextUploadId && previousUploadId !== nextUploadId) ||
previous.totalBytes !== next.totalBytes
)
return next
const uploadedBytes =
previous.state === 'uploading' && next.state === 'uploading'
? Math.max(previous.uploadedBytes, next.uploadedBytes)
: next.uploadedBytes
return {
...next,
uploadedBytes: Math.min(Math.max(0, uploadedBytes), next.totalBytes),
}
})
}, [])
const mergeUploadProgress = useCallback((uploadedBytes: number): void => {
setUploadSnapshot(previous => {
if (!previous) return previous
return {
...previous,
uploadedBytes: Math.min(Math.max(0, uploadedBytes), previous.totalBytes),
}
})
}, [])
const current = crumbs[crumbs.length - 1]
const currentCrumbRef = useRef(current)
currentCrumbRef.current = current
const crumbsRef = useRef(crumbs)
crumbsRef.current = crumbs
const currentLabel = current?.name === '/' ? DRIVE : current?.name || DRIVE
const load = useCallback(
async (
crumb: Crumb,
cursor?: string,
options?: { background?: boolean; signal?: AbortSignal }
): Promise<void> => {
const appending = Boolean(cursor)
const background = Boolean(options?.background)
if (!background) {
foregroundLoadsInFlightRef.current += 1
// User navigation or a foreground mutation refresh owns the next
// visible result. Cancel stream-triggered reads so an older response
// for the same folder cannot overwrite it.
const activeStreamRefetch = entityChangeRefetchControllerRef.current
if (activeStreamRefetch) {
activeStreamRefetch.abort()
pendingStreamRevalidationRef.current = true
}
entityChangeRefetchControllerRef.current = null
}
const loadArbiter = loadArbiterRef.current
const loadToken = background ? loadArbiter.beginBackground() : loadArbiter.beginForeground()
const isCurrent = () =>
!options?.signal?.aborted &&
loadArbiter.isCurrent(loadToken) &&
sameCrumbLocation(currentCrumbRef.current, crumb)
if (!background && !cursor) loadedPageCountRef.current = 1
if (appending) {
setLoadingMore(true)
} else if (!background) {
setLoading(true)
setItems([])
setNextCursor(null)
}
if (!background) setError('')
try {
const path = isDriveRootCrumb(crumb)
? '/api/v1/gfs/tree'
: `/api/v1/gfs/resources/${encodeURIComponent(crumb.id!)}/children`
const query: Record<string, string> = { drive: DRIVE }
if (cursor) query.cursor = cursor
const fetchPage = (pageQuery: Record<string, string>) =>
options?.signal
? apiGet(path, pageQuery, { signal: options.signal })
: apiGet(path, pageQuery)
let page = (await fetchPage(query)) as TreePage
let allItems = [...page.items]
let finalCursor = page.nextCursor
let fetchedPageCount = 1
if (background) {
const targetPageCount = loadedPageCountRef.current
for (let index = 1; index < targetPageCount && finalCursor; index += 1) {
page = (await fetchPage({ drive: DRIVE, cursor: finalCursor })) as TreePage
allItems.push(...page.items)
finalCursor = page.nextCursor
fetchedPageCount += 1
if (!isCurrent()) return
}
}
if (!isCurrent()) return
if (isDriveRootCrumb(crumb) && page.rootResourceId) {
const rootRid = ridOfResourceId(page.rootResourceId)
setCrumbs(prev => {
const root = prev[0]
if (!isDriveRootCrumb(root)) return prev
if (root.id === page.rootResourceId && root.rid === rootRid) return prev
return [{ ...root, id: page.rootResourceId, rid: rootRid }, ...prev.slice(1)]
})
}
const sortedItems = sortChildrenWithDirectoriesFirst(allItems)
setItems(prev => (cursor ? [...prev, ...sortedItems] : sortedItems))
setNextCursor(finalCursor)
if (background) loadedPageCountRef.current = fetchedPageCount
else if (cursor) loadedPageCountRef.current += 1
// Keep the folder cache coherent with what the server just returned:
// navigation, refresh-after-mutation, and pagination all land here, so
// a later openDirectory() can never serve rows older than this load.
if (crumb.id !== null) {
const existing = childCacheRef.current.get(crumb.id)
childCacheRef.current.set(crumb.id, {
items: cursor ? [...(existing?.items ?? []), ...allItems] : allItems,
nextCursor: finalCursor,
loadedPageCount: cursor
? (existing?.loadedPageCount ?? 1) + 1
: background
? fetchedPageCount
: 1,
})
}
} catch (err) {
if (!isCurrent()) return
if (!isSilentApiError(err)) {
setError(err instanceof Error ? err.message : 'Failed to load EvenDrive')
}
} finally {
if (!background) {
foregroundLoadsInFlightRef.current = Math.max(0, foregroundLoadsInFlightRef.current - 1)
if (foregroundLoadsInFlightRef.current === 0 && pendingStreamRevalidationRef.current) {
pendingStreamRevalidationRef.current = false
requestStreamRevalidationRef.current()
}
}
if (isCurrent()) {
if (appending) setLoadingMore(false)
else if (!background) setLoading(false)
}
}
},
[]
)
function sortChildrenWithDirectoriesFirst(children: GfsChild[]): GfsChild[] {
return [...children].sort((a, b) => {
if (a.kind === b.kind) return a.name.localeCompare(b.name)
return a.kind === 'directory' ? -1 : 1
})
}
// ┌─────────────────────────────────────────────────────────────────────────┐
// │ GfsBrowser data-path decision table (keep behavior and tests aligned). │
// ├─────────────────────────────────────────────────────────────────────────┤
// │ UPLOAD TRANSPORT (create & replace) │
// │ • Default: resumable Upload v2 (createGfsUploadJob) for EVERY size; │
// │ the writer-advertised maxFileBytes (≤ 1 GiB protocol ceiling) is │
// │ enforced before any bytes move. 8 MiB streamed parts. │
// │ • Legacy contentBase64 runs ONLY for fresh (non-resume) uploads after │
// │ a capability error with allowLegacyFallback, and is refused above │
// │ the legacy 16 MiB raw limit. Persisted resume sessions never │
// │ downgrade (see tests: legacy-*.test, persisted-resume, >16 MiB). │
// ├─────────────────────────────────────────────────────────────────────────┤
// │ FOLDER CACHE (childCacheRef) — revalidate vs. invalidate │
// │ • Prefetch warms UNcached folder rows (best-effort, non-fatal) and │
// │ never overwrites an entry a load() wrote meanwhile. │
// │ • openDirectory serves a cached page instantly and marks the next │
// │ effect pass for BACKGROUND revalidation (stale-while-revalidate): │
// │ no spinner/row-clear; rows are replaced when the server diverged. │
// │ • Every completed load() (navigation, refresh-after-mutation, │
// │ pagination) writes the fresh page back into the cache, so uploads, │
// │ folder creation, rename, and delete keep cached folders coherent. │
// │ • Deleting a directory row drops its cache entry. │
// │ • Loads are sequence-guarded: a response from a superseded navigation │
// │ can no longer overwrite the folder on screen (covers the background │
// │ path too). │
// ├─────────────────────────────────────────────────────────────────────────┤
// │ AUTHORITATIVE SERVER STATE │
// │ • Listings, resource versions (ifMatch), grants, and share rows always │
// │ come from control-api responses; this cache is never an authority for │
// │ permissions or versions. │
// └─────────────────────────────────────────────────────────────────────────┘
// Cache of prefetched directory children, keyed by the folder's
// resourceId. Refs over state because we don't want to re-render
// every time a prefetch resolves — the data is consumed lazily in
// openDirectory(). Survives across navigation; cleared on unmount.
const childCacheRef = useRef<Map<string, TreePage>>(new Map())
// Monotonic load sequence: only the newest load() may apply its results,
// so a slow response cannot clobber the folder the user navigated to next.
// True after openDirectory() served cached data; the next useEffect pass
// runs a BACKGROUND revalidation instead of a clearing reload, so the user
// keeps the cached rows (no spinner) while the server state re-syncs.
const revalidateNextLoadRef = useRef(false)
const streamCursorRef = useRef<string | null>(null)
const hierarchyRefreshGenerationRef = useRef(0)
// Warm the cache for every folder row visible in the current view.
// Re-runs whenever the listing changes (folder navigation, refresh,
// …) and silently no-ops if a folder was already cached. Failed
// prefetches are non-fatal; the real navigation surfaces the error.
useEffect(() => {
const folders = items.filter(child => child.kind === 'directory')
if (folders.length === 0) return
let cancelled = false
async function prefetchFolder(folder: GfsChild): Promise<void> {
try {
const page = (await apiGet(
`/api/v1/gfs/resources/${encodeURIComponent(folder.resourceId)}/children`,
{ drive: DRIVE }
)) as TreePage | undefined
if (cancelled || !page) return
// A load() may have cached a fresher page while this prefetch was in
// flight (the user navigated into the folder); never overwrite it.
if (childCacheRef.current.has(folder.resourceId)) return
childCacheRef.current.set(folder.resourceId, page)
} catch {
/* ignore — openDirectory will surface the real error */
}
}
folders.forEach(folder => {
if (childCacheRef.current.has(folder.resourceId)) return
void prefetchFolder(folder)
})
return () => {
cancelled = true
}
}, [items])
const currentLocationKey = isDriveRootCrumb(current) ? '$root' : (current.id ?? '$root')
useEffect(() => {
const locationCrumb = currentCrumbRef.current
if (!locationCrumb) return
const sameLocation = loadedLocationRef.current === currentLocationKey
loadedLocationRef.current = currentLocationKey
if (!sameLocation) setLoadingMore(false)
if (revalidateNextLoadRef.current) {
revalidateNextLoadRef.current = false
// Stale-while-revalidate: cached rows stay on screen (no spinner) while
// the server state re-syncs; divergence overwrites the rows in place.
void load(locationCrumb, undefined, { background: true })
return
}
void load(locationCrumb, undefined, sameLocation ? { background: true } : undefined)
// Reload whenever the current folder changes (navigation).
}, [currentLocationKey, load])
// Navigating away from the moved folder retires the recovery notice: the
// stale trail it labels is no longer on screen.
useEffect(() => {
if (!trailRecovery) return
if (!crumbs.some(crumb => crumb.id === trailRecovery.resourceId)) {
setTrailRecovery(null)
}
}, [crumbs, trailRecovery])
useEffect(() => {
const controller = new AbortController()
let retryTimer: ReturnType<typeof setTimeout> | null = null
let recoveryTimer: ReturnType<typeof setTimeout> | null = null
let retryDelay = 500
let recoveryDelay = 500
let active = true
let performVisibleStateRevalidation: (cursor?: string) => Promise<void> = async () => undefined
let invalidateVisibleState: (cursor?: string) => void = () => undefined
const scheduleRecovery = () => {
if (!active || recoveryTimer) return
const delay = recoveryDelay
recoveryDelay = Math.min(recoveryDelay * 2, 5000)
recoveryTimer = setTimeout(() => {
recoveryTimer = null
invalidateVisibleState()
}, delay)
}
const revalidationScheduler = createCoalescedRevalidation<string>(
cursor => performVisibleStateRevalidation(cursor),
error => {
if (!active) return
if (!isSilentApiError(error)) {
setError(error instanceof Error ? error.message : 'Failed to refresh EvenDrive')
}
scheduleRecovery()
},
100
)
invalidateVisibleState = cursor => revalidationScheduler.request(cursor)
requestStreamRevalidationRef.current = invalidateVisibleState
const revalidateActionTargets = async (signal: AbortSignal) => {
const targets = new Map<string, GfsChild>()
for (const target of [selectedRef.current, renameTargetRef.current, moveTargetRef.current]) {
if (target) targets.set(target.resourceId, target)
}
await Promise.all(
Array.from(targets.values(), async target => {
try {
await apiGet('/api/v1/gfs/resolve', { uri: target.gfsUri }, { signal })
if (signal.aborted) return
// This read confirms the dialog's target is still visible; it must
// not silently advance the version the operator is confirming.
// Keep the original target snapshot so the existing ifMatch CAS can
// report a stale write rather than applying to unconfirmed state.
} catch (error) {
if (signal.aborted) return
const status = entityChangeErrorStatus(error)
if (status === 403 || status === 404) {
setSelected(value => (value?.resourceId === target.resourceId ? null : value))
setRenameTarget(value => (value?.resourceId === target.resourceId ? null : value))
setMoveTarget(value => (value?.resourceId === target.resourceId ? null : value))
if (selectedRef.current?.resourceId === target.resourceId && deleteOpenRef.current) {
setDeleteOpen(false)
}
} else if (isTransientEntityChangeRefetchError(error)) {
scheduleRecovery()
}
}
})
)
}
const refreshVisibleDirectory = async (crumb: Crumb, signal: AbortSignal): Promise<void> => {
const path = isDriveRootCrumb(crumb)
? '/api/v1/gfs/tree'
: `/api/v1/gfs/resources/${encodeURIComponent(crumb.id!)}/children`
const targetPageCount = Math.max(1, loadedPageCountRef.current)
try {
let page = (await apiGet(path, { drive: DRIVE }, { signal })) as TreePage
const rootResourceId = page.rootResourceId
const refreshedItems = [...page.items]
let nextPageCursor = page.nextCursor
let fetchedPageCount = 1
for (let index = 1; index < targetPageCount && nextPageCursor; index += 1) {
page = (await apiGet(
path,
{ drive: DRIVE, cursor: nextPageCursor },
{ signal }
)) as TreePage
refreshedItems.push(...page.items)
nextPageCursor = page.nextCursor
fetchedPageCount += 1
if (signal.aborted) return
}
if (signal.aborted || !sameCrumbLocation(currentCrumbRef.current, crumb)) return
if (isDriveRootCrumb(crumb) && rootResourceId) {
const rootRid = ridOfResourceId(rootResourceId)
setCrumbs(previous => {
const root = previous[0]
if (!isDriveRootCrumb(root)) return previous
if (root.id === rootResourceId && root.rid === rootRid) return previous
return [{ ...root, id: rootResourceId, rid: rootRid }, ...previous.slice(1)]
})
}
setItems(sortChildrenWithDirectoriesFirst(refreshedItems))
setNextCursor(nextPageCursor)
loadedPageCountRef.current = fetchedPageCount
if (crumb.id !== null) {
childCacheRef.current.set(crumb.id, {
items: refreshedItems,
nextCursor: nextPageCursor,
loadedPageCount: fetchedPageCount,
})
}
setError('')
} catch (error) {
if (signal.aborted || !sameCrumbLocation(currentCrumbRef.current, crumb)) return
if (!isSilentApiError(error)) {
setError(error instanceof Error ? error.message : 'Failed to refresh EvenDrive')
}
const status = entityChangeErrorStatus(error)
if (status === 403 || status === 404) {
// A soft invalidation preserves rows until the authoritative read
// resolves. Once that read proves this folder cannot be listed, its
// old rows are no longer safe to display or reuse on navigation.
setItems([])
setNextCursor(null)
loadedPageCountRef.current = 1
if (crumb.id !== null) childCacheRef.current.delete(crumb.id)
} else if (isTransientEntityChangeRefetchError(error)) {
scheduleRecovery()
}
}
}
performVisibleStateRevalidation = async (cursor?: string) => {
// Foreground navigation and pagination own their results. If a stream
// invalidation arrives while either is in flight, run one authoritative
// refresh after the user operation settles rather than superseding it or
// losing the invalidation.
if (foregroundLoadsInFlightRef.current > 0) {
pendingStreamRevalidationRef.current = true
return
}
// Retire an older same-folder focus/cache refresh before publishing the
// newer stream-authoritative listing. Its late response must not win.
loadArbiterRef.current.beginStreamRevalidation()
// A committed remote change supersedes any local move/retry ancestry
// reconstruction still in flight. Its older response must not replace
// the hierarchy we are about to refetch from the authoritative API.
trailReconstructionEpochRef.current += 1
if (cursor) {
streamCursorRef.current = cursor
if (recoveryTimer) clearTimeout(recoveryTimer)
recoveryTimer = null
recoveryDelay = 500
}
const revalidationController = new AbortController()
entityChangeRefetchControllerRef.current = revalidationController
const signal = revalidationController.signal
childCacheRef.current.clear()
revalidateNextLoadRef.current = false
const revalidationTasks: Promise<void>[] = [revalidateActionTargets(signal)]
const previews = openPreviewsRef.current
if (previews.length > 0) {
const generation = ++previewRefreshGenerationRef.current
const markUnavailable = (preview: OpenPreviewState) => {
setImagePreview(current =>
current?.gfsUri === preview.gfsUri && !current.unavailable
? { ...current, unavailable: true, reloadVersion: current.reloadVersion + 1 }
: current
)
setMarkdownPreview(current =>
current?.gfsUri === preview.gfsUri && !current.unavailable
? { ...current, unavailable: true, reloadVersion: current.reloadVersion + 1 }
: current
)
setVideoPreview(current =>
current?.gfsUri === preview.gfsUri && !current.unavailable
? { ...current, unavailable: true, reloadVersion: current.reloadVersion + 1 }
: current
)
}
revalidationTasks.push(
Promise.all<ResolvedPreviewUpdate | null>(
previews.map(async preview => {
try {
const resolved = (await apiGet(
'/api/v1/gfs/resolve',
{ uri: preview.gfsUri },
{ signal }
)) as {
kind: string
name: string
bytes: number
version: number
rid: string
resourceId: string
gfsUri: string
}
if (signal.aborted || generation !== previewRefreshGenerationRef.current)
return null
if (resolved.kind !== 'file') {
markUnavailable(preview)
return null
}
const imageMimeType = gfsImagePreviewMimeType(resolved.name)
const videoMimeType = gfsVideoPreviewMimeType(resolved.name)
let candidate: ResolvedPreviewUpdate | null = null
if (preview.kind === 'image') {
candidate = imageMimeType
? {
kind: 'image',
gfsUri: resolved.gfsUri,
byteLength: resolved.bytes,
fileName: resolved.name,
rid: resolved.rid,
version: resolved.version,
mimeType: imageMimeType,
reloadVersion: preview.reloadVersion + 1,
unavailable: false,
}
: null
} else if (preview.kind === 'video') {
candidate = videoMimeType
? {
kind: 'video',
gfsUri: resolved.gfsUri,
byteLength: resolved.bytes,
fileName: resolved.name,
rid: resolved.rid,
version: resolved.version,
mimeType: videoMimeType,
reloadVersion: preview.reloadVersion + 1,
unavailable: false,
}
: null
} else {
candidate = isGfsMarkdownPreviewFile(resolved.name)
? {
kind: 'markdown',
gfsUri: resolved.gfsUri,
byteLength: resolved.bytes,
fileName: resolved.name,
rid: resolved.rid,
version: resolved.version,
reloadVersion: preview.reloadVersion + 1,
unavailable: false,
}
: null
}
if (!candidate) {
markUnavailable(preview)
return null
}
if (candidate.version < preview.version) return null
const candidateMimeType = 'mimeType' in candidate ? candidate.mimeType : undefined
const currentMimeType = 'mimeType' in preview ? preview.mimeType : undefined
const unchanged =
!preview.unavailable &&
candidate.kind === preview.kind &&
candidate.gfsUri === preview.gfsUri &&
candidate.rid === preview.rid &&
candidate.fileName === preview.fileName &&
candidate.byteLength === preview.byteLength &&
candidate.version === preview.version &&
candidateMimeType === currentMimeType
return unchanged ? null : candidate
} catch (error) {
if (signal.aborted || generation !== previewRefreshGenerationRef.current)
return null
const status = entityChangeErrorStatus(error)
if (status === 403 || status === 404) markUnavailable(preview)
if (isTransientEntityChangeRefetchError(error)) scheduleRecovery()
return null
}
})
).then(updates => {
if (signal.aborted || generation !== previewRefreshGenerationRef.current) return
for (const update of updates) {
if (!update) continue
if (update.kind === 'image') {
setImagePreview(current => (current?.gfsUri === update.gfsUri ? update : current))
setMarkdownPreview(current => (current?.gfsUri === update.gfsUri ? null : current))
setVideoPreview(current => (current?.gfsUri === update.gfsUri ? null : current))
} else if (update.kind === 'video') {
setVideoPreview(current => (current?.gfsUri === update.gfsUri ? update : current))
setImagePreview(current => (current?.gfsUri === update.gfsUri ? null : current))
setMarkdownPreview(current => (current?.gfsUri === update.gfsUri ? null : current))
} else {
setMarkdownPreview(current =>
current?.gfsUri === update.gfsUri ? update : current
)
setImagePreview(current => (current?.gfsUri === update.gfsUri ? null : current))
setVideoPreview(current => (current?.gfsUri === update.gfsUri ? null : current))
}
}
})
)
}
const visibleCrumb = currentCrumbRef.current
if (!visibleCrumb) {
await Promise.all(revalidationTasks)
return
}
// Stream-triggered reads have their own non-destructive path. They never
// enter the navigation/paging loader or clear its rows, dialogs, or error.
revalidationTasks.push(refreshVisibleDirectory(visibleCrumb, signal))
if (isDriveRootCrumb(visibleCrumb)) {
await Promise.all(revalidationTasks)
return
}
const visibleResourceId = visibleCrumb.id
const generation = ++hierarchyRefreshGenerationRef.current
const trailEpoch = trailReconstructionEpochRef.current
const hierarchyRefresh = (async () => {
const rootCrumb = {
...(isDriveRootCrumb(crumbsRef.current[0])
? crumbsRef.current[0]!
: createDriveRootCrumb()),
}
const hierarchy = await resolveGfsHierarchy({
readCurrent: () =>
apiGet(
'/api/v1/gfs/resolve',
{ uri: `gfs://${DRIVE}/${visibleCrumb.rid ?? ridOfResourceId(visibleResourceId)}` },
{ signal }
) as Promise<GfsResolvedLocation>,
readAncestor: path =>
apiGet(
'/api/v1/gfs/by-path',
{ drive: DRIVE, path },
{ signal }
) as Promise<GfsResolvedLocation>,
isTransient: isTransientEntityChangeRefetchError,
})
if (
generation !== hierarchyRefreshGenerationRef.current ||
signal.aborted ||
trailEpoch !== trailReconstructionEpochRef.current ||
currentCrumbRef.current?.id !== visibleResourceId
) {
return
}
if (hierarchy.kind === 'missing') {
// Only denial of the stable-ID current-folder resolve is authority
// to leave this location. A failed ancestor lookup is not revocation.
setCrumbs([rootCrumb])
setTrailRecovery(null)
return
}
if (hierarchy.kind === 'retry' || hierarchy.kind === 'preserve') {
setTrailRecovery(previous =>
previous?.resourceId === visibleResourceId && previous.reason === 'hierarchy'
? previous
: {
resourceId: visibleResourceId,
gfsUri:
visibleCrumb.gfsUri ??
`gfs://${DRIVE}/${visibleCrumb.rid ?? ridOfResourceId(visibleResourceId)}`,
reason: 'hierarchy',
}
)
if (hierarchy.kind === 'retry') scheduleRecovery()
return
}
const refreshed = [rootCrumb, ...hierarchy.ancestors.map(folderResourceToCrumb)]
if (!sameCrumbTrail(crumbsRef.current, refreshed)) setCrumbs(refreshed)
setTrailRecovery(null)
})()
revalidationTasks.push(hierarchyRefresh)
await Promise.all(revalidationTasks)
}
async function consume(): Promise<void> {
while (active && !controller.signal.aborted) {
try {
const cursor = streamCursorRef.current
const response = await fetch(entityChangeStreamUrl(cursor), {
cache: 'no-store',
credentials: 'include',
headers: { accept: 'application/x-ndjson' },
signal: controller.signal,
})
if (response.status === 401) {
active = false
handleControlUIUnauthorized()
return
}
if (!response.ok || !response.body) {
const error = new Error(`Entity-change stream returned ${response.status}`) as Error & {
retryAfterMs?: number
}
error.retryAfterMs = parseEntityChangeRetryAfterMs(response.headers.get('retry-after'))
throw error
}
retryDelay = 500
const reader = response.body.getReader()
const liveness = watchEntityChangeStreamLiveness(() => {
void reader.cancel().catch(() => undefined)
})
const decoder = new TextDecoder()
let pending = ''
try {
for (;;) {
const { done, value } = await reader.read()
if (done) break
pending += decoder.decode(value, { stream: true })
let newline = pending.indexOf('\n')
while (newline >= 0) {
const line = pending.slice(0, newline).replace(/\r$/, '')
pending = pending.slice(newline + 1)
const frame = parseEntityChangeFrame(line)
if (line.trim()) liveness.receivedFrame()
if (!frame) {
newline = pending.indexOf('\n')
continue
}
streamCursorRef.current = frame.cursor
if (frame.type === 'resync_required' || frame.type === 'scope.invalidated') {
invalidateVisibleState(frame.cursor)
} else if (frame.type === 'stream.closing') {
await reader.cancel()
if (frame.reason === 'session_expired') {
active = false
handleControlUIUnauthorized()
return
}
break
}
newline = pending.indexOf('\n')
}
if (pending.length > ENTITY_CHANGE_MAX_FRAME_CHARS) {
throw new Error('Entity-change frame exceeded its limit')
}
}
} finally {
liveness.dispose()
// A malformed or unsupported frame exits through the outer retry
// path. Releasing the lock alone leaves the HTTP response alive,
// consuming a server stream slot while the next connection opens.
await reader.cancel().catch(() => undefined)
reader.releaseLock()
}
if (!controller.signal.aborted) throw new Error('Entity-change stream ended')
} catch (error) {
if (!active || controller.signal.aborted) return
// A transport failure is not evidence that authorization or resource
// state changed. The feed cursor remains authoritative for recovery;
// preserve visible state and reconnect with bounded backoff.
const retryAfterMs =
error &&
typeof error === 'object' &&
typeof (error as { retryAfterMs?: unknown }).retryAfterMs === 'number'
? (error as { retryAfterMs: number }).retryAfterMs
: undefined
await new Promise<void>(resolve => {
retryTimer = setTimeout(
resolve,
Math.max(retryDelay + Math.random() * retryDelay, retryAfterMs ?? 0)
)
})
retryTimer = null
retryDelay = Math.min(retryDelay * 2, 15_000)
}
}
}
void consume()
return () => {
active = false
controller.abort()
revalidationScheduler.dispose()
entityChangeRefetchControllerRef.current?.abort()
entityChangeRefetchControllerRef.current = null
requestStreamRevalidationRef.current = () => undefined
if (retryTimer) clearTimeout(retryTimer)
if (recoveryTimer) clearTimeout(recoveryTimer)
}
}, [load])
useEffect(() => {
if ((!selected && !renameTarget) || imagePreview || markdownPreview || videoPreview) return
function handleKeyDown(event: KeyboardEvent) {
if (event.key !== 'Escape') return
setSelected(null)
setRenameTarget(null)
}
window.addEventListener('keydown', handleKeyDown)
return () => window.removeEventListener('keydown', handleKeyDown)
}, [imagePreview, markdownPreview, renameTarget, selected, videoPreview])
function openDirectory(child: GfsChild): void {
if (child.kind !== 'directory') return
setRenameTarget(null)
setCrumbs(prev => [...prev, folderResourceToCrumb(child)])
const cached = childCacheRef.current.get(child.resourceId)
if (cached) {
// Render the cached listing instantly; the effect-driven background
// revalidation refreshes in place if the server state diverged, so the
// user gets fresh data without a loading spinner (decision table above).
setItems(sortChildrenWithDirectoriesFirst(cached.items))
setNextCursor(cached.nextCursor)
loadedPageCountRef.current = cached.loadedPageCount ?? 1
setError('')
setLoading(false)
revalidateNextLoadRef.current = true
return
}
setLoading(true)
}
function openFilePreview(child: GfsChild): boolean {
if (child.kind === 'directory') return false
const mimeType = gfsImagePreviewMimeType(child.name)
if (mimeType) {
setImagePreview({
kind: 'image',
gfsUri: child.gfsUri,
byteLength: child.bytes,
fileName: child.name,
mimeType,
rid: child.rid,
version: child.version,
reloadVersion: 0,
unavailable: false,
})
return true
}
if (isGfsMarkdownPreviewFile(child.name)) {
setMarkdownPreview({
kind: 'markdown',
gfsUri: child.gfsUri,
byteLength: child.bytes,
fileName: child.name,
rid: child.rid,
version: child.version,
reloadVersion: 0,
unavailable: false,
})
return true
}
const videoMimeType = gfsVideoPreviewMimeType(child.name)
if (videoMimeType) {
setVideoPreview({
kind: 'video',
gfsUri: child.gfsUri,
byteLength: child.bytes,
fileName: child.name,
mimeType: videoMimeType,
rid: child.rid,
version: child.version,
reloadVersion: 0,
unavailable: false,
})
return true
}
return false
}
function goToCrumb(index: number): void {
if (index === crumbs.length - 1) return
// A navigation that leaves the current trail supersedes any in-flight
// breadcrumb reconstruction (R7-M1): its late response must not re-anchor
// a trail the operator just navigated away from.
trailReconstructionEpochRef.current += 1
setRenameTarget(null)
setLoading(true)
setCrumbs(crumbs.slice(0, index + 1))
}
async function copyGfsUri(uri: string): Promise<void> {
try {
await navigator.clipboard.writeText(uri)
showToast('EvenDrive link copied.', { tone: 'success' })
} catch {
showToast('Could not copy the EvenDrive link.', { tone: 'error' })
}
}
async function refreshCurrent(): Promise<void> {
if (!current) return
await load(current)
}
/** Refresh whatever folder is LIVE on screen, read at call time. Async
* drag work must use this: a render-time `current` can name a folder the
* operator navigated away from while the work was in flight, and loading
* it would clear-and-discard against the visible listing. */
async function refreshLiveCurrent(): Promise<void> {
const liveCrumb = currentCrumbRef.current
if (!liveCrumb) return
await load(liveCrumb)
}
function handleResourceDragStart(event: React.DragEvent<HTMLLIElement>, child: GfsChild): void {
// Files AND folders drag (rev-2 D2); an in-flight move freezes sources.
if (movingResourceRef.current) {
event.preventDefault()
return
}
// A newer gesture supersedes every pending admission read and any
// confirmation still open from an older one (plan §3.4).
dragGestureEpochRef.current += 1
setConfirmMoveTarget(null)
dragSourceParentIdRef.current = currentCrumbRef.current?.id ?? null
event.dataTransfer.effectAllowed = 'move'
event.dataTransfer.setData(GFS_RESOURCE_DRAG_TYPE, child.resourceId)
event.dataTransfer.setData('text/plain', child.name)
draggingResourceRef.current = child
setDraggingResourceId(child.resourceId)
}
function handleResourceDragEnd(): void {
// Presentation-only: an accepted drop's async admission/commit keeps
// running under the same gesture epoch (plan §3.4 — dragend must not
// cancel its own accepted drop).
draggingResourceRef.current = null
setDraggingResourceId(null)
setDragOverFolderId(null)
setDragOverCrumbIndex(null)
}
/** Trail observed ancestors of the SOURCE: the physical parent (the
* current folder) plus every crumb above it. */
function knownSourceAncestorIdsForCurrentTrail(): Set<string> {
const ids = new Set<string>()
for (const crumb of crumbsRef.current) {
if (crumb.id) ids.add(crumb.id)
}
return ids
}
/** Nearest-first ancestor chain of a breadcrumb target, observed through
* the live trail. The trailing null marks the chain walked to the
* physical drive root (the trail always starts there, hydrated or not). */
function crumbTargetAncestorIds(index: number): (string | null)[] {
const chain: (string | null)[] = []
for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
const crumb = crumbsRef.current[cursor]
chain.push(crumb?.id ?? null)
}
chain.push(null)
return chain
}
/** Nearest-first ancestor chain of a listing ROW target: its parent (the
* current folder) plus the trail above, observed to the physical root. */
function rowTargetAncestorIds(): (string | null)[] {
const chain: (string | null)[] = [currentCrumbRef.current?.id ?? null]
for (let cursor = crumbsRef.current.length - 2; cursor >= 0; cursor -= 1) {
const crumb = crumbsRef.current[cursor]
chain.push(crumb?.id ?? null)
}
chain.push(null)
return chain
}
function rowHoverVerdict(source: GfsChild, folder: GfsChild): GfsDropHoverVerdict | null {
if (folder.kind !== 'directory' && folder.resourceId !== source.resourceId) return null
return computeGfsDropHoverVerdict({
drive: DRIVE,
sourceResourceId: source.resourceId,
sourceKind: source.kind === 'file' ? 'file' : 'directory',
sourceParentKnown: (currentCrumbRef.current?.id ?? null) !== null,
sourceParentResourceId: currentCrumbRef.current?.id ?? null,
targetResourceId: folder.resourceId,
targetName: folder.name,
targetIsActiveLocation: false,
targetIsSourceParent: false,
targetAncestorIds: rowTargetAncestorIds(),
knownSourceAncestorIds: knownSourceAncestorIdsForCurrentTrail(),
})
}
function crumbHoverVerdict(source: GfsChild, index: number): GfsDropHoverVerdict | null {
const crumb = crumbsRef.current[index]
if (!crumb) return null
const parentId = dragSourceParentIdRef.current
return computeGfsDropHoverVerdict({
drive: DRIVE,
sourceResourceId: source.resourceId,
sourceKind: source.kind === 'file' ? 'file' : 'directory',
sourceParentKnown: parentId !== null,
sourceParentResourceId: parentId,
targetResourceId: crumb.id,
targetName: isDriveRootCrumb(crumb) ? DRIVE : crumb.name,
targetIsActiveLocation: index === crumbsRef.current.length - 1,
targetIsSourceParent:
parentId !== null
? crumb.id === parentId
: isDriveRootCrumb(crumb) && dragSourceParentIdRef.current === null,
targetAncestorIds: crumbTargetAncestorIds(index),
knownSourceAncestorIds: knownSourceAncestorIdsForCurrentTrail(),
})
}
/** Internal directory drops stay DELIVERABLE even for an observed refusal,
* so release can present the reason (UX matrix §5.3). Admission still
* refuses the mutation. */
function deliverInternalMoveDrag(event: React.DragEvent<HTMLElement>): boolean {
if (!hasDraggedGfsResource(event)) return false
if (!draggingResourceRef.current) return false
event.preventDefault()
event.stopPropagation()
event.dataTransfer.dropEffect = 'move'
return true
}
function handleFolderDragOver(event: React.DragEvent<HTMLLIElement>, folder: GfsChild): void {
const source = draggingResourceRef.current
if (!hasDraggedGfsResource(event) || !source) return
// Self and directory targets stay deliverable and painted; a plain file
// row is not a move destination and keeps today's pass-through.
if (folder.kind !== 'directory' && folder.resourceId !== source.resourceId) return
deliverInternalMoveDrag(event)
setDragOverFolderId(folder.resourceId)
}
function handleFolderDragEnter(event: React.DragEvent<HTMLLIElement>, folder: GfsChild): void {
handleFolderDragOver(event, folder)
}
function handleFolderDragLeave(event: React.DragEvent<HTMLLIElement>): void {
if (!hasDraggedGfsResource(event)) return
event.preventDefault()
event.stopPropagation()
if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
setDragOverFolderId(null)
}
}
function handleCrumbDragOver(event: React.DragEvent<HTMLButtonElement>, index: number): void {
const source = draggingResourceRef.current
if (!hasDraggedGfsResource(event) || !source) return
deliverInternalMoveDrag(event)
setDragOverCrumbIndex(index)
}
function handleCrumbDragEnter(event: React.DragEvent<HTMLButtonElement>, index: number): void {
handleCrumbDragOver(event, index)
}
function handleCrumbDragLeave(event: React.DragEvent<HTMLButtonElement>, index: number): void {
if (!hasDraggedGfsResource(event)) return
event.preventDefault()
event.stopPropagation()
if (
dragOverCrumbIndex === index &&
!event.currentTarget.contains(event.relatedTarget as Node | null)
) {
setDragOverCrumbIndex(null)
}
}
function handleCrumbDrop(
event: React.DragEvent<HTMLButtonElement>,
crumb: Crumb,
index: number
): void {
if (!hasDraggedGfsResource(event)) return
// Stop propagation/default FIRST so the upload container can never
// process an internal crumb drop (plan §3.4).
event.preventDefault()
event.stopPropagation()
setDragOverCrumbIndex(null)
const source = draggingResourceRef.current
if (!source) return
const epoch = dragGestureEpochRef.current
// EVERY same-parent/no-op fact is computed synchronously HERE, against
// the trail as dropped on (R7): a reconstruction landing while admission
// awaits must never turn a captured ancestor index into the live active
// index and falsely refuse same-parent. Nothing after an await may read
// live trail state for these checks.
const parentId = dragSourceParentIdRef.current
const sameParentDrop =
index === crumbsRef.current.length - 1 ||
(parentId !== null ? crumb.id === parentId : isDriveRootCrumb(crumb) && parentId === null)
void admitCrumbDropMove(source, crumb, sameParentDrop, epoch)
}
/** Refuse a drop honestly: matrix wording, reason tone, no mutation. */
function refuseDropMove(
reason: GfsDropRefusalReason,
names: { sourceName?: string; targetName?: string }
): void {
showToast(gfsDropRefusalMessage(reason, names), {
tone: gfsDropRefusalTone(reason),
})
}
/** Matrix A11: a 401 from the drag pipeline's own reads. The API layer's
* unauthorized boundary has already run (global auth-error handler); this
* surfaces the session loss persistently for this surface instead of a
* connection-flavored warning. */
function raiseSessionLostNotice(): void {
setSessionLost(true)
}
/** True when a read error is an authentication expiry: either the API
* layer's AuthExpiredError or a raw 401 status (tests and non-GET paths). */
function isUnauthorizedRead(error: unknown): boolean {
return error instanceof AuthExpiredError || entityChangeErrorStatus(error) === 401
}
/** One bounded read to (re)hydrate the drive root's resource identity.
* A 401 stays session-lost (matrix A11): the persistent sign-in alert is
* raised and the caller must NOT report a connection warning. */
async function hydrateDriveRootIdentity(
epoch: number
): Promise<{ kind: 'hydrated'; rootId: string } | { kind: 'session-lost' } | { kind: 'failed' }> {
try {
const page = (await apiGet('/api/v1/gfs/tree', { drive: DRIVE })) as TreePage
if (!page.rootResourceId || !isGestureEpochCurrent(epoch)) return { kind: 'failed' }
const rootRid = ridOfResourceId(page.rootResourceId)
setCrumbs(prev => {
const root = prev[0]
if (!isDriveRootCrumb(root)) return prev
if (root.id === page.rootResourceId && root.rid === rootRid) return prev
return [{ ...root, id: page.rootResourceId, rid: rootRid }, ...prev.slice(1)]
})
return { kind: 'hydrated', rootId: page.rootResourceId }
} catch (error) {
if (isUnauthorizedRead(error)) {
raiseSessionLostNotice()
return { kind: 'session-lost' }
}
return { kind: 'failed' }
}
}
/** Immutable destination capture for a breadcrumb target, synchronously
* derivable from the crumb. Null for the not-yet-hydrated root. */
function crumbToMoveDestination(crumb: Crumb): GfsMoveDestination | null {
if (isDriveRootCrumb(crumb)) {
if (!crumb.id || !crumb.rid) return null
return {
resourceId: crumb.id,
rid: crumb.rid,
name: DRIVE,
kind: 'directory',
gfsUri: `gfs://${DRIVE}/${crumb.rid}`,
path: '/',
origin: 'crumb',
}
}
if (!crumb.id) return null
const gfsUri = crumb.gfsUri ?? (crumb.rid ? `gfs://${DRIVE}/${crumb.rid}` : null)
return {
resourceId: crumb.id,
rid: crumb.rid,
name: crumb.name,
kind: 'directory',
gfsUri,
path: null,
...(crumb.version !== undefined ? { version: crumb.version } : {}),
origin: 'crumb',
}
}
function rowToMoveDestination(folder: GfsChild): GfsMoveDestination {
return {
resourceId: folder.resourceId,
rid: folder.rid,
name: folder.name,
kind: 'directory',
gfsUri: folder.gfsUri,
path: folder.path,
...(folder.version !== undefined ? { version: folder.version } : {}),
origin: 'row',
}
}
async function admitCrumbDropMove(
source: GfsChild,
crumb: Crumb,
sameParentDrop: boolean,
epoch: number
): Promise<void> {
// 1. Destination identity. The unhydrated root retries resolution here
// (plan §3.1); a failed retry warns honestly and dispatches nothing,
// and a session-lost retry raises the sign-in alert instead.
let destination = crumbToMoveDestination(crumb)
if (!destination) {
const hydration = await hydrateDriveRootIdentity(epoch)
if (!isGestureEpochCurrent(epoch)) return
if (hydration.kind === 'session-lost') return
if (hydration.kind === 'failed') {
refuseDropMove('unavailable', { targetName: DRIVE })
return
}
destination = {
resourceId: hydration.rootId,
rid: ridOfResourceId(hydration.rootId),
name: DRIVE,
kind: 'directory',
gfsUri: `gfs://${DRIVE}/${ridOfResourceId(hydration.rootId)}`,
path: '/',
origin: 'crumb',
}
}
// 2. Identity/no-op checks from the drop-boundary capture — the boolean
// was computed synchronously at drop, never from live trail state.
if (destination.resourceId === source.resourceId) {
refuseDropMove('self', { sourceName: source.name, targetName: destination.name })
return
}
if (sameParentDrop) {
refuseDropMove('same-parent', {
sourceName: source.name,
targetName: destination.name,
})
return
}
// 3. Fresh-path structural admission: both endpoints re-resolved by
// immutable URI; failed resolution prevents dispatch with honest
// feedback, a missing path defers to the atomic server guard.
const admitted = await admitMoveEndpoints(source, destination, epoch)
if (!admitted.ok) {
if (admitted.sessionLost) return
if (admitted.refusal) {
refuseDropMove(admitted.refusal.reason, {
sourceName: source.name,
targetName: destination.name,
})
}
return
}
// 4. ONE confirmation for both files and folders (plan §3.2).
openMoveConfirmation(source, destination, epoch, dragSourceParentIdRef.current)
}
/** Fresh endpoint resolution + structural check shared by row and crumb
* admissions. `refusal` is set for every honest refusal; `sessionLost`
* outranks it (the persistent sign-in alert was already raised);
* ok=true means the move is structurally admissible (observed or
* deferred to the server guard). */
async function admitMoveEndpoints(
source: GfsChild,
destination: GfsMoveDestination,
epoch: number
): Promise<{
ok: boolean
refusal?: { reason: GfsDropRefusalReason }
sessionLost?: boolean
}> {
if (!destination.gfsUri) return { ok: false, refusal: { reason: 'unavailable' } }
const [sourceRead, targetRead] = await Promise.all([
resolveEndpointView(source.gfsUri, source.resourceId),
resolveEndpointView(destination.gfsUri, destination.resourceId),
])
if (!isGestureEpochCurrent(epoch)) return { ok: false }
if (sourceRead.status === 'unauthorized' || targetRead.status === 'unauthorized') {
raiseSessionLostNotice()
return { ok: false, sessionLost: true }
}
if (sourceRead.status === 'missing' || sourceRead.status === 'mismatched') {
return { ok: false, refusal: { reason: 'source-location-unknown' } }
}
if (sourceRead.status === 'failed') return { ok: false, refusal: { reason: 'unavailable' } }
if (targetRead.status === 'missing' || targetRead.status === 'mismatched') {
return { ok: false, refusal: { reason: 'target-unavailable' } }
}
if (targetRead.status === 'failed') return { ok: false, refusal: { reason: 'unavailable' } }
if (targetRead.view.kind !== 'directory') {
return { ok: false, refusal: { reason: 'target-unavailable' } }
}
const targetPath = destination.path === '/' ? '/' : targetRead.view.path
const structure = decideDragPathStructure({
sourcePath: sourceRead.view.path,
targetPath,
})
if (structure.kind === 'deny') {
return { ok: false, refusal: { reason: structure.reason } }
}
return { ok: true }
}
/** Seed the confirmation dialog exactly like the row path: the same cache
* the numbered-name ladder will consult. */
function openMoveConfirmation(
source: GfsChild,
destination: GfsMoveDestination,
epoch: number,
oldParentId: string | null
): void {
const occupiedNames = new Set<string>(
(childCacheRef.current.get(destination.resourceId)?.items ?? []).map(item => item.name)
)
const suggested =
occupiedNames.size > 0 && occupiedNames.has(source.name)
? nextAvailableGfsResourceName(source.name, occupiedNames)
: undefined
setConfirmMoveTarget({
source,
destination,
...(suggested !== undefined ? { suggestedName: suggested } : {}),
epoch,
oldParentId,
})
}
/** GET /gfs/resolve by immutable URI, classified for admission/commit.
* `expectedResourceId` turns an identity drift (the immutable URI now
* resolves to a different resource id) into an explicit mismatch, and a
* 401 stays session-lost (matrix A11) instead of reading as a connection
* failure. The API layer's own unauthorized boundary (global auth-error
* handler + AuthExpiredError) remains untouched. */
async function resolveEndpointView(
uri: string,
expectedResourceId?: string
): Promise<GfsEndpointRead> {
try {
const view = (await apiGet('/api/v1/gfs/resolve', { uri })) as GfsResolvedEndpointView
if (expectedResourceId && view.resourceId !== expectedResourceId) {
return { status: 'mismatched' }
}
return { status: 'resolved', view }
} catch (error) {
if (isUnauthorizedRead(error)) return { status: 'unauthorized' }
if (entityChangeErrorStatus(error) === 404) return { status: 'missing' }
return { status: 'failed' }
}
}
async function handleFolderDrop(
event: React.DragEvent<HTMLLIElement>,
folder: GfsChild
): Promise<void> {
if (!hasDraggedGfsResource(event)) return
event.preventDefault()
event.stopPropagation()
setDragOverFolderId(null)
const source = draggingResourceRef.current
if (!source) return
const epoch = dragGestureEpochRef.current
if (source.resourceId === folder.resourceId) {
refuseDropMove('self', { sourceName: source.name, targetName: folder.name })
return
}
const destination = rowToMoveDestination(folder)
if (source.kind === 'file') {
// Files cannot be ancestors: no structural risk; move directly — the
// commit runner still re-resolves both endpoints before dispatch.
await moveResource(source, destination, {
revalidate: { epoch, oldParentId: dragSourceParentIdRef.current },
})
return
}
// Folder drops stop at ONE confirmation (rev-2 §1) after the fresh-path
// structural guard — the impact dialog also records the naming policy.
const admitted = await admitMoveEndpoints(source, destination, epoch)
if (!admitted.ok) {
if (admitted.sessionLost) return
if (admitted.refusal) {
refuseDropMove(admitted.refusal.reason, {
sourceName: source.name,
targetName: destination.name,
})
}
return
}
openMoveConfirmation(source, destination, epoch, dragSourceParentIdRef.current)
}
async function moveResource(
source: GfsChild,
destination: Pick<GfsChild, 'resourceId' | 'name' | 'kind'> & {
gfsUri?: string
path?: string | null
},
options: {
bubbleError?: boolean
allowNumberedRename?: boolean
/**
* Names the caller already knows the destination holds (the Move
* dialog loads them while it shows the destination tree). They are
* merged into the ladder seed, so a destination the browser's children
* cache never saw does not cost three blind attempts on names that
* are already taken (RP-003).
*/
occupiedNames?: readonly string[]
/**
* Drag commits re-resolve BOTH endpoints by immutable URI immediately
* before dispatch (plan §3.4): validate returned identity and
* destination kind, use the fresh source version, and stop without
* dispatching when the gesture epoch was superseded. The keyboard Move
* dialog keeps its established single-read behavior.
*/
revalidate?: {
epoch: number
/**
* The physical old parent observed at the drag boundary, used for
* convergence invalidation — never a response-time guess at what
* folder held the source.
*/
oldParentId: string | null
}
} = {}
): Promise<void> {
const { bubbleError = false, allowNumberedRename = true } = options
if (
destination.kind !== 'directory' ||
source.resourceId === destination.resourceId ||
movingResourceRef.current
) {
return
}
movingResourceRef.current = source.resourceId
setMovingResourceId(source.resourceId)
try {
let ifMatchVersion = source.version
let verifiedDestinationPath: string | null = null
if (options.revalidate) {
const epoch = options.revalidate.epoch
if (!isGestureEpochCurrent(epoch)) return
const sourceRead = await resolveEndpointView(source.gfsUri, source.resourceId)
if (!isGestureEpochCurrent(epoch)) return
if (sourceRead.status === 'unauthorized') {
raiseSessionLostNotice()
return
}
if (sourceRead.status === 'missing' || sourceRead.status === 'mismatched') {
throw new GfsMoveRefusalError(
'source-location-unknown',
gfsDropRefusalMessage('source-location-unknown', { sourceName: source.name })
)
}
if (sourceRead.status === 'failed') {
throw new GfsMoveRefusalError('unavailable', gfsDropRefusalMessage('unavailable'))
}
// The captured source kind must still be the resource's kind: a
// flip means the immutable URI no longer names the captured item.
if (sourceRead.view.kind !== source.kind) {
throw new GfsMoveRefusalError(
'source-location-unknown',
gfsDropRefusalMessage('source-location-unknown', { sourceName: source.name })
)
}
// Fresh-precondition contract: the dispatched ifMatch must be the
// version the fresh authorized read just returned. A missing,
// negative, or non-safe-integer version is NOT downgraded to the
// stale row version — the move refuses instead.
const freshVersion = sourceRead.view.version
if (
typeof freshVersion !== 'number' ||
!Number.isSafeInteger(freshVersion) ||
freshVersion < 0
) {
throw new GfsMoveRefusalError(
'source-precondition-unavailable',
gfsDropRefusalMessage('source-precondition-unavailable')
)
}
ifMatchVersion = freshVersion
// The destination identity is ALWAYS revalidated through its
// immutable URI; a cached path observation is never a substitute.
if (!destination.gfsUri) {
throw new GfsMoveRefusalError('unavailable', gfsDropRefusalMessage('unavailable'))
}
const targetRead = await resolveEndpointView(destination.gfsUri, destination.resourceId)
if (!isGestureEpochCurrent(epoch)) return
if (targetRead.status === 'unauthorized') {
raiseSessionLostNotice()
return
}
if (targetRead.status === 'missing' || targetRead.status === 'mismatched') {
throw new GfsMoveRefusalError(
'target-unavailable',
gfsDropRefusalMessage('target-unavailable')
)
}
if (targetRead.status === 'failed') {
throw new GfsMoveRefusalError('unavailable', gfsDropRefusalMessage('unavailable'))
}
if (targetRead.view.kind !== 'directory') {
throw new GfsMoveRefusalError(
'target-unavailable',
gfsDropRefusalMessage('target-unavailable')
)
}
verifiedDestinationPath = destination.path === '/' ? '/' : targetRead.view.path
const structure = decideDragPathStructure({
sourcePath: sourceRead.view.path,
targetPath: verifiedDestinationPath,
})
if (structure.kind === 'deny') {
throw new GfsMoveRefusalError(
structure.reason,
gfsDropRefusalMessage(structure.reason, {
sourceName: source.name,
targetName: destination.name,
})
)
}
}
// Seed the ladder with the destination's known children (the same cache
// the confirmation suggestion came from, plus whatever the caller
// observed) so the first 409 skips every already-taken numbered name
// instead of guessing it blind.
const occupiedNames = new Set<string>([
...(childCacheRef.current.get(destination.resourceId)?.items ?? []).map(item => item.name),
...(options.occupiedNames ?? []),
])
let moveName = source.name
let moved = false
let moveResult: unknown
// rev-2 §5: at most three network attempts per gesture under an
// approved numbered-name policy; a single attempt otherwise.
const maxAttempts = allowNumberedRename ? GFS_MOVE_MAX_NETWORK_ATTEMPTS : 1
for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
// The gesture must still own the dispatch the instant the PATCH
// leaves (plan §3.4); an already-dispatched request is never recalled.
if (options.revalidate && !isGestureEpochCurrent(options.revalidate.epoch)) return
try {
moveResult = await apiSend(
'PATCH',
`/api/v1/gfs/resources/${encodeURIComponent(source.resourceId)}`,
{
drive: DRIVE,
newParentId: destination.resourceId,
ifMatch: ifMatchVersion,
...(moveName === source.name ? {} : { newName: moveName }),
},
{ drive: DRIVE }
)
moved = true
break
} catch (error) {
if (!isGfsNameConflict(error)) {
// A 401 from the PATCH itself is session loss (A11), not a
// transient failure: raise the persistent sign-in alert and stop
// — no ladder retry can succeed against a dead session. The API
// layer's global unauthorized boundary has already run.
if (isUnauthorizedRead(error)) {
if (options.revalidate) {
raiseSessionLostNotice()
return
}
throw error
}
if (
options.revalidate &&
entityChangeErrorStatus(error) === undefined &&
movingResourceRef.current === source.resourceId
) {
// Transport loss with the request possibly dispatched: the
// outcome is UNKNOWN. Never claim the move failed and never
// repeat the PATCH — verify once by identity (matrix B7/B8).
// Anything the single read cannot PROVE stays unknown: the
// PATCH may still be executing, or another actor may have
// moved the source, so a differing parent is not a failure
// verdict.
const settled = await settleUnknownTransportMove(
source,
destination,
moveName,
options.revalidate.epoch
)
if (!isGestureEpochCurrent(options.revalidate.epoch)) return
if (settled === 'moved') {
moved = true
moveResult = undefined
break
}
throw new GfsMoveRefusalError(
'unknown-outcome',
gfsDropRefusalMessage('unknown-outcome')
)
}
throw error
}
if (!allowNumberedRename) {
throw new Error(
'An item with this name already exists. Choose another folder, or use Move to change its name.'
)
}
occupiedNames.add(moveName)
if (attempt + 1 >= maxAttempts) break
moveName = nextAvailableGfsResourceName(source.name, occupiedNames)
}
}
if (!moved) {
// A concurrent naming storm, not "all numbered names used".
throw new Error('The destination changed. Refresh it or choose another folder.')
}
const movedResource = (
moveResult as { data?: { resourceId?: string; version?: number } } | undefined
)?.data
const nextVersion =
movedResource?.resourceId && movedResource.resourceId !== source.resourceId
? undefined
: movedResource?.version
// plan §3.4 convergence: invalidate the observed OLD and NEW parent
// listings through the shared pure planner. For drag commits the old
// parent is the PHYSICAL source parent captured at the drag boundary —
// never a response-time guess, because the operator may have navigated
// while the commit was in flight. Non-drag callers (the Move dialog)
// keep the trail-derived observation.
const movedCrumbIndex = crumbs.findIndex(crumb => crumb.id === source.resourceId)
const oldParentId =
options.revalidate?.oldParentId !== undefined
? options.revalidate.oldParentId
: movedCrumbIndex > 0
? (crumbs[movedCrumbIndex - 1]?.id ?? null)
: (currentCrumbRef.current?.id ?? null)
const childParentByResourceId = new Map<string, string | null>()
for (const [folderId, page] of childCacheRef.current.entries()) {
for (const item of page.items) childParentByResourceId.set(item.resourceId, folderId)
}
const convergence = planMoveConvergence(
{ resourceId: source.resourceId, oldParentId, newParentId: destination.resourceId },
{ childParentByResourceId }
)
for (const staleFolderId of convergence.refetchChildIds) {
childCacheRef.current.delete(staleFolderId)
}
showToast(
moveName === source.name
? `Moved "${source.name}" to "${destination.name}".`
: `Moved "${source.name}" to "${destination.name}" as "${moveName}".`,
{ tone: 'success' }
)
if (source.kind === 'directory') {
showToast(
'Moving a folder changes who can access its contents — access now follows the new location.',
{ tone: 'info' }
)
}
// A move changes the moved folder's ANCESTRY. When the moved resource
// is part of the open breadcrumb trail, patching only its own crumb
// would leave every crumb above it describing the OLD location (R5-M1):
// with /org open and /org moved under /archive, the trail must become
// main / archive / org — not stay main / org. (The old parent's cache
// entry was already invalidated through the convergence plan above.)
if (movedCrumbIndex >= 0) {
// The crumb adopts the receipt metadata FIRST — this is the
// resource's truthful post-move state. The ancestry rebuild below
// (and any later retry of it) preserves this metadata from LIVE
// crumb state, never from a move-time snapshot (R7-M1), so a rename
// that lands while recovery is pending is never rolled back.
setCrumbs(prev =>
prev.map(crumb =>
crumb.id === source.resourceId
? {
...crumb,
name: moveName,
...(nextVersion === undefined
? { version: undefined }
: { version: nextVersion }),
}
: crumb
)
)
const outcome = await rebuildTrailFromNewLocation(source.resourceId, source.gfsUri)
if (outcome === 'failed') {
// The MOVE succeeded but the trail could not be reconstructed from
// the new location. Keep the trail the operator was looking at
// (explicitly stale — never a shortened path presented as
// authoritative) and surface a recovery notice with a retry until
// reconstruction succeeds. ('applied' clears any older notice for
// this resource inside the rebuild; 'superseded' leaves state to
// the newer attempt that displaced this one.)
setTrailRecovery({ resourceId: source.resourceId, gfsUri: source.gfsUri, reason: 'move' })
}
return
}
// Refresh the LIVE current location — the user stays where they are;
// a drag move never auto-navigates to the destination (plan §3.4).
// Reading currentCrumbRef HERE (not a render-time crumb) is what makes
// the refresh truthful when the operator navigated while the commit
// was in flight: the folder on screen is the one that reloads.
await refreshLiveCurrent()
} catch (err) {
if (bubbleError) throw err
if (err instanceof GfsMoveRefusalError) {
showToast(err.message, { tone: err.tone })
} else {
showToast(err instanceof Error ? err.message : 'Could not move resource.', {
tone: 'error',
})
}
} finally {
movingResourceRef.current = null
setMovingResourceId(null)
}
}
/** Resolve the outcome of a transport-lost move PATCH (matrix B7/B8) with
* ONE bounded read per endpoint and no repeat dispatch.
*
* 'moved' requires POSITIVE proof: the source resolves by immutable URI
* under the destination's CURRENT canonical path — re-resolved by URI so
* a remotely moved destination still verifies identity-correctly — AND
* carries the exact name this PATCH requested (or its unrenamed name).
* Everything else stays 'unknown': the PATCH may still be executing, the
* source may have been moved by another actor, or the endpoints cannot
* be established at all. A differing parent NEVER reads as a failure
* verdict, and a source resolved AT the root path ('/' — the drive root
* itself) can never prove a move into root landed: a moved item lives at
* '/<name>'. */
async function settleUnknownTransportMove(
source: GfsChild,
destination: { resourceId: string; gfsUri?: string | null },
requestedName: string,
epoch: number
): Promise<'moved' | 'unknown'> {
if (!destination.gfsUri) return 'unknown'
const [sourceRead, targetRead] = await Promise.all([
resolveEndpointView(source.gfsUri, source.resourceId),
resolveEndpointView(destination.gfsUri, destination.resourceId),
])
if (!isGestureEpochCurrent(epoch)) return 'unknown'
if (sourceRead.status === 'unauthorized' || targetRead.status === 'unauthorized') {
// The session died after the PATCH was dispatched: the move outcome
// stays HONESTLY UNKNOWN (the PATCH may have landed first), and the
// session loss surfaces alongside it through the persistent alert —
// never as a connection-flavored warning.
raiseSessionLostNotice()
return 'unknown'
}
if (sourceRead.status !== 'resolved' || targetRead.status !== 'resolved') return 'unknown'
if (targetRead.view.kind !== 'directory') return 'unknown'
if (typeof sourceRead.view.path !== 'string' || typeof targetRead.view.path !== 'string') {
return 'unknown'
}
const sourcePath = normalizeCanonicalPath(sourceRead.view.path)
const destinationPath = normalizeCanonicalPath(targetRead.view.path)
if (sourcePath === null || destinationPath === null) return 'unknown'
// The drive root itself: a completed move into any folder — including
// the root — lands at '/<name>', never at '/'.
if (sourcePath === '/') return 'unknown'
const parent = parentPathOf(sourcePath)
if (parent !== destinationPath) return 'unknown'
const leaf = sourcePath.split('/').filter(Boolean).pop()
if ((leaf ?? '') !== requestedName) return 'unknown'
return 'moved'
}
/** Rebuild the breadcrumb trail ANCESTRY for a moved trail-folder. The
* resolve contract answers with the folder's new `path`; every ancestor
* prefix is then resolved by-path so the trail reflects the new ancestor
* chain rather than the old one.
*
* This touches ancestry ONLY: the moved crumb and every crumb below it
* are carried over from the LIVE trail (R7-M1), so a rename or other
* mutation that landed while recovery was pending keeps its newer
* name/version — no move-time snapshot is ever replayed.
*
* Each attempt is EPOCH-VERSIONED (R7-M1 race): it may apply its result
* only while it is still the latest reconstruction attempt. A newer Move,
* reconstruction, rename, or trail-replacing navigation that lands while
* this attempt's requests are in flight bumps the epoch, and the stale
* response is then discarded whole — it can neither overwrite the newer
* ancestry nor clear the newer operation's recovery notice.
*
* Reconstruction is ALL-OR-NOTHING: a failed leaf resolve, a null `path`,
* or any failed ancestor by-path lookup leaves the current trail
* UNTOUCHED (never a partial ancestry presented as authoritative) so the
* caller can surface recovery state instead. */
async function rebuildTrailFromNewLocation(
resourceId: string,
gfsUri: string
): Promise<TrailReconstructionOutcome> {
const epoch = ++trailReconstructionEpochRef.current
// A displaced attempt is 'superseded' no matter how its own requests
// settle — its verdict must never reach breadcrumb or recovery state.
const verdict = (outcome: TrailReconstructionOutcome): TrailReconstructionOutcome =>
epoch === trailReconstructionEpochRef.current ? outcome : 'superseded'
let view: { path?: string | null }
try {
view = (await apiGet('/api/v1/gfs/resolve', { uri: gfsUri })) as {
path?: string | null
}
} catch {
return verdict('failed')
}
// A null path means the server could not name the new location — that is
// a failed reconstruction, not a root-level folder ('/org' is).
if (typeof view.path !== 'string' || view.path.length <= 1) {
return verdict('failed')
}
const segments = view.path.split('/').filter(segment => segment.length > 0)
const ancestors: Crumb[] = []
for (let depth = 1; depth < segments.length; depth += 1) {
let ancestor: Awaited<ReturnType<typeof getGfsResourceByPath>>
try {
ancestor = await getGfsResourceByPath(DRIVE, '/' + segments.slice(0, depth).join('/'))
} catch {
return verdict('failed')
}
ancestors.push(folderResourceToCrumb(ancestor))
}
if (epoch !== trailReconstructionEpochRef.current) return 'superseded'
setCrumbs(prev => {
if (epoch !== trailReconstructionEpochRef.current) return prev
const index = prev.findIndex(crumb => crumb.id === resourceId)
// The user navigated while the resolve walk was in flight — never
// clobber the trail they navigated to.
if (index < 0) return prev
return [
isDriveRootCrumb(prev[0]) ? prev[0]! : createDriveRootCrumb(),
...ancestors,
// Live crumb state (name/version included) — see the doc note above.
...prev.slice(index),
]
})
// The trail is canonical for this resource as of the LATEST attempt —
// any older recovery notice for it is obsolete.
setTrailRecovery(null)
return 'applied'
}
/** Retry a failed post-move trail ancestry reconstruction. Runs from the
* recovery snapshot's IMMUTABLE identity plus the live trail — never a
* captured name/version — so the rebuilt crumb reflects every mutation
* that landed since the move. The rebuild owns the notice entirely: an
* 'applied' retry clears it (the trail is canonical again), a 'failed'
* retry keeps it, and a 'superseded' retry touches NOTHING — a newer
* Move/reconstruction owns the breadcrumb and its recovery state now. */
async function retryTrailRecovery(): Promise<void> {
const recovery = trailRecovery
if (!recovery) return
await rebuildTrailFromNewLocation(recovery.resourceId, recovery.gfsUri)
}
async function uploadWithCompatibility(
input: GfsUploadJobInput
): Promise<'completed' | 'paused'> {
setUploadCandidate(input.file)
setUploadOpen(true)
setUploading(true)
const job = createGfsUploadJob({
...input,
onProgress: progress => {
mergeUploadProgress(progress.uploadedBytes)
input.onProgress?.(progress)
},
onState: snapshot => {
mergeUploadSnapshot(snapshot)
input.onState?.(snapshot)
},
onPersistPending: record => {
persistPendingGfsUpload({
idempotencyKey: record.idempotencyKey,
fileName: record.fileName,
fileSize: record.fileSize,
lastModified: record.lastModified,
target: record.target,
name: record.name,
})
void input.onPersistPending?.(record)
},
onPersist: record => {
persistPendingGfsUpload({
uploadId: record.uploadId,
fileName: record.fileName,
fileSize: record.fileSize,
lastModified: record.lastModified,
target: record.target,
name: record.name,
})
void input.onPersist?.(record)
},
onClearPersisted: uploadId => {
clearPendingGfsUpload(uploadId)
void input.onClearPersisted?.(uploadId)
},
})
uploadJobRef.current = job
try {
const receipt = await job.start()
if (receipt.state === 'paused') {
setUploading(false)
return 'paused'
}
setUploadCandidate(null)
setUploadOpen(false)
setUploadSnapshot(null)
uploadJobRef.current = null
await refreshCurrent()
return 'completed'
} catch (error) {
if (!(error instanceof GfsUploadCapabilityError) || !error.allowLegacyFallback) throw error
if (input.resumeUploadId) {
throw new GfsUploadCapabilityError(
'The persisted resumable session cannot be resumed while EvenDrive Upload v2 is unavailable.',
{ cause: error }
)
}
showToast('Resumable upload is unavailable; using the legacy 16 MiB path.', { tone: 'info' })
await uploadGfsFileLegacy(input)
clearPendingGfsUpload()
setUploadCandidate(null)
setUploadOpen(false)
setUploadSnapshot(null)
uploadJobRef.current = null
await refreshCurrent()
return 'completed'
} finally {
setUploading(false)
}
}
function openNewFolder(): void {
if (!current?.id) return
setCreateFolderError(null)
setNewFolderOpen(true)
}
async function createFolder(requestedName: string): Promise<void> {
const rid = current?.rid ?? (current?.id ? ridOfResourceId(current.id) : null)
if (!rid) return
setCreatingFolder(true)
setCreateFolderError(null)
try {
const name = await normalizeGfsResourceName(requestedName)
await apiSend('POST', `/api/v1/gfs/proxy/v1/resources/${encodeURIComponent(rid)}/children`, {
name,
kind: 'directory',
})
showToast('Folder created.', { tone: 'success' })
setNewFolderOpen(false)
await refreshCurrent()
} catch (err) {
// Keep the modal open so the operator can adjust the name and retry.
setCreateFolderError(err instanceof Error ? err.message : 'Could not create folder.')
} finally {
setCreatingFolder(false)
}
}
async function uploadFile(
file: File | null | undefined,
occupiedNames = new Set(items.map(item => item.name))
): Promise<void> {
const rid = current?.rid ?? (current?.id ? ridOfResourceId(current.id) : null)
if (!rid || !file) return
setUploading(true)
let resumeUploadId: string | undefined
let legacyFallbackAnnounced = false
try {
assertGfsFileUploadSize(file.size)
const normalizedName = await normalizeGfsResourceName(file.name)
const target = { operation: 'create' as const, parentRid: rid }
resumeUploadId = matchingPendingResumeUploadId(file, target, normalizedName)
const nameReservation = uploadNameReservationsRef.current.begin(
rid,
normalizedName,
occupiedNames
)
try {
for (let attempt = 0; attempt < GFS_UPLOAD_NAME_RETRY_LIMIT; attempt += 1) {
const resumeUploadIdForAttempt = attempt === 0 ? resumeUploadId : undefined
const name = nameReservation.reserveNext({ exact: Boolean(resumeUploadIdForAttempt) })
try {
try {
const job = createGfsUploadJob({
file,
name,
target,
resumeUploadId: resumeUploadIdForAttempt,
onPersistPending: record => {
persistPendingGfsUpload({
idempotencyKey: record.idempotencyKey,
fileName: record.fileName,
fileSize: record.fileSize,
lastModified: record.lastModified,
target: record.target,
name: record.name,
})
},
onProgress: progress => mergeUploadProgress(progress.uploadedBytes),
onState: snapshot => mergeUploadSnapshot(snapshot),
onPersist: record => {
persistPendingGfsUpload({
uploadId: record.uploadId,
fileName: record.fileName,
fileSize: record.fileSize,
lastModified: record.lastModified,
target: record.target,
name: record.name,
})
},
onClearPersisted: uploadId => clearPendingGfsUpload(uploadId),
})
uploadJobRef.current = job
const receipt = await job.start()
if (receipt.state === 'paused') {
setUploading(false)
return
}
} catch (err) {
if (!(err instanceof GfsUploadCapabilityError) || !err.allowLegacyFallback) throw err
if (resumeUploadIdForAttempt) {
throw new GfsUploadCapabilityError(
'The persisted resumable session cannot be resumed while EvenDrive Upload v2 is unavailable.',
{ cause: err }
)
}
if (!legacyFallbackAnnounced) {
showToast('Resumable upload is unavailable; using the legacy 16 MiB path.', {
tone: 'info',
})
legacyFallbackAnnounced = true
}
await uploadGfsFileLegacy({ file, name, target })
clearPendingGfsUpload()
setUploadCandidate(null)
setUploadOpen(false)
setUploadSnapshot(null)
uploadJobRef.current = null
}
nameReservation.markSuccess(name)
showToast('File uploaded.', { tone: 'success' })
setUploadCandidate(null)
setUploadOpen(false)
setUploadSnapshot(null)
uploadJobRef.current = null
await refreshCurrent()
return
} catch (err) {
if (uploadJobRef.current?.snapshot().state === 'aborted') return
const decision = gfsUploadNameRetryDecision(err, {
attempt,
resuming: Boolean(resumeUploadIdForAttempt),
})
if (decision === 'terminal') throw err
nameReservation.markConflict(name)
clearPendingGfsUpload()
uploadJobRef.current = null
setUploadSnapshot(null)
if (decision === 'exhausted') throw new Error(GFS_UPLOAD_NAME_EXHAUSTED_MESSAGE)
}
}
throw new Error(GFS_UPLOAD_NAME_EXHAUSTED_MESSAGE)
} finally {
nameReservation.release()
}
} catch (err) {
if (uploadJobRef.current?.snapshot().state === 'aborted') return
showToast(err instanceof Error ? err.message : 'Could not upload file.', { tone: 'error' })
} finally {
setUploading(false)
}
}
function handleGfsDragEnter(event: React.DragEvent<HTMLElement>): void {
if (hasDraggedGfsResource(event)) {
event.preventDefault()
return
}
if (!hasDraggedFiles(event)) return
event.preventDefault()
setDragActive(true)
}
function handleGfsDragOver(event: React.DragEvent<HTMLElement>): void {
if (hasDraggedGfsResource(event)) {
event.preventDefault()
event.dataTransfer.dropEffect = 'none'
return
}
if (!hasDraggedFiles(event)) return
event.preventDefault()
event.dataTransfer.dropEffect = current?.id ? 'copy' : 'none'
setDragActive(true)
}
function handleGfsDragLeave(event: React.DragEvent<HTMLElement>): void {
if (hasDraggedGfsResource(event)) return
if (event.currentTarget.contains(event.relatedTarget as Node | null)) return
setDragActive(false)
}
async function handleGfsDrop(event: React.DragEvent<HTMLElement>): Promise<void> {
if (hasDraggedGfsResource(event)) {
event.preventDefault()
return
}
if (!hasDraggedFiles(event)) return
event.preventDefault()
setDragActive(false)
if (!current?.id) {
showToast('Files cannot be uploaded until a destination folder is available.', {
tone: 'error',
})
return
}
const droppedFiles = Array.from(event.dataTransfer.files || [])
if (!droppedFiles.length) {
showToast('No files were dropped.', { tone: 'error' })
return
}
setDroppedUploadCount(droppedFiles.length)
const occupiedNames = new Set(items.map(item => item.name))
try {
for (const file of droppedFiles) {
await uploadFile(file, occupiedNames)
}
} finally {
setDroppedUploadCount(0)
}
}
function closeUploadModal(): void {
if (uploading) return
setUploadOpen(false)
if (!uploadSnapshot || uploadSnapshot.state !== 'paused') {
setUploadCandidate(null)
uploadJobRef.current = null
setUploadSnapshot(null)
}
}
function openManage(child: GfsChild, mode?: 'delete'): void {
setRenameTarget(null)
setSelected(child)
setDeleteOpen(mode === 'delete')
}
function openMove(child: GfsChild): void {
setSelected(null)
setDeleteOpen(false)
setMoveTarget(child)
}
function openRowRename(child: GfsChild): void {
setSelected(null)
setDeleteOpen(false)
setRenameError('')
setRenameValid(true)
setRenameTarget(child)
}
/** Adapt a folder crumb for the row-action handlers (share, rename, move,
* delete) so a breadcrumb menu acts on exactly the same shape a
* parent-view row does. Returns null for the synthetic root. */
function crumbToChild(crumb: Crumb): GfsChild | null {
if (!crumb.id || !crumb.rid || crumb.kind !== 'directory' || crumb.version === undefined)
return null
return {
resourceId: crumb.id,
rid: crumb.rid,
gfsUri: crumb.gfsUri ?? `gfs://${DRIVE}/${crumb.rid}`,
name: crumb.name,
kind: crumb.kind,
path: null,
bytes: 0,
version: crumb.version,
}
}
/** Single construction path for a FOLDER's ⋯ menu. Parent-view rows and
* breadcrumb crumb menus both build their props here, so their option
* lists cannot drift apart. File-only actions stay on the file rows. */
function folderMenuProps(folder: GfsChild) {
return {
resourceName: folder.name,
resourceUri: folder.gfsUri,
onManage: () => openManage(folder),
onCopyLink: () => void copyGfsUri(folder.gfsUri),
onOpenLink: () => setOpenLinkOpen(true),
onRename: () => openRowRename(folder),
onMove: () => openMove(folder),
onDelete: () => openManage(folder, 'delete'),
}
}
/** "Open EvenDrive link": resolve a pasted gfs:// URI through control-api
* and navigate the breadcrumb straight to that folder, mirroring Desktop. */
async function openEvenDriveLink(uri: string): Promise<void> {
setOpenLinkError(null)
setOpenLinkResolving(true)
try {
const view = (await apiGet('/api/v1/gfs/resolve', { uri })) as GfsResolvedLocation
if (view.kind !== 'directory') {
setOpenLinkError('Only folder links can be opened here.')
return
}
setRenameTarget(null)
setSelected(null)
setDeleteOpen(false)
// Replacing the whole trail supersedes any in-flight breadcrumb
// reconstruction (R7-M1): its late response must not re-anchor the
// trail this link-open just replaced.
trailReconstructionEpochRef.current += 1
setCrumbs(prev => [
isDriveRootCrumb(prev[0]) ? prev[0]! : createDriveRootCrumb(),
folderResourceToCrumb(view),
])
setOpenLinkOpen(false)
} catch (err) {
setOpenLinkError(err instanceof Error ? err.message : 'Could not open the EvenDrive link.')
} finally {
setOpenLinkResolving(false)
}
}
async function renameResource(child: GfsChild, requestedName: string): Promise<void> {
if (!requestedName.trim() || renaming) return
setRenaming(true)
setRenameError('')
try {
const name = await normalizeGfsResourceName(requestedName.trim())
if (name === child.name) {
setRenameTarget(null)
return
}
const patchResult = await apiSend(
'PATCH',
'/api/v1/gfs/resources/' + encodeURIComponent(child.resourceId),
{ drive: DRIVE, newName: name, ifMatch: child.version },
{ drive: DRIVE }
)
const nextVersion = (
patchResult as { data?: { resourceId?: string; version?: number } } | undefined
)?.data?.version
showToast('Resource renamed.', { tone: 'success' })
// A crumb rename must retitle the breadcrumb segment too, not just the
// listing rows refreshed below. It also supersedes any in-flight
// breadcrumb reconstruction (R7-M1): a stale retry response must not
// land over a trail the rename just advanced.
trailReconstructionEpochRef.current += 1
setCrumbs(prev =>
prev.map(crumb =>
crumb.id === child.resourceId
? { ...crumb, name, ...(nextVersion === undefined ? {} : { version: nextVersion }) }
: crumb
)
)
setRenameTarget(null)
setSelected(null)
await refreshCurrent()
} catch (err) {
// The rename dialog stays open with the draft and the failure reason —
// a toast alone gave the operator no retry path.
setRenameError(err instanceof Error ? err.message : 'Could not rename resource.')
} finally {
setRenaming(false)
}
}
async function replaceFile(child: GfsChild, file: File | null | undefined): Promise<void> {
if (!file) return
try {
const target = {
operation: 'replace' as const,
resourceRid: child.rid,
ifMatch: child.version,
}
const state = await uploadWithCompatibility({
file,
name: file.name,
target,
resumeUploadId: matchingPendingResumeUploadId(file, target, file.name),
})
if (state === 'completed') {
showToast('File replaced.', { tone: 'success' })
if (selected?.resourceId === child.resourceId) setSelected(null)
} else {
showToast('Replace paused. Resume it from the upload panel.', { tone: 'info' })
}
} catch (err) {
showToast(err instanceof Error ? err.message : 'Could not replace file.', { tone: 'error' })
}
}
async function pauseUpload(): Promise<void> {
const job = uploadJobRef.current
if (!job) return
try {
await job.pause()
setUploading(false)
} catch (err) {
showToast(err instanceof Error ? err.message : 'Could not pause upload.', { tone: 'error' })
}
}
async function resumeUpload(): Promise<void> {
const job = uploadJobRef.current
if (!job) return
setUploading(true)
try {
const receipt = await job.resume()
if (receipt.state === 'completed') {
showToast('File uploaded.', { tone: 'success' })
setUploadCandidate(null)
setUploadOpen(false)
setUploadSnapshot(null)
uploadJobRef.current = null
await refreshCurrent()
}
} catch (err) {
showToast(err instanceof Error ? err.message : 'Could not resume upload.', { tone: 'error' })
} finally {
setUploading(false)
}
}
async function cancelUpload(): Promise<void> {
const job = uploadJobRef.current
if (!job) {
closeUploadModal()
return
}
try {
await job.cancel()
setUploading(false)
setUploadSnapshot(null)
setUploadCandidate(null)
setUploadOpen(false)
uploadJobRef.current = null
} catch (err) {
showToast(err instanceof Error ? err.message : 'Could not cancel upload.', { tone: 'error' })
setUploading(false)
}
}
async function downloadFile(child: GfsChild): Promise<void> {
if (downloadingIds.has(child.resourceId)) return
setDownloadingIds(prev => new Set(prev).add(child.resourceId))
try {
await gfsDownload(child.rid, child.name)
showToast('File downloaded.', { tone: 'success' })
} catch (err) {
showToast(err instanceof Error ? err.message : 'Could not download file.', { tone: 'error' })
} finally {
setDownloadingIds(prev => {
const next = new Set(prev)
next.delete(child.resourceId)
return next
})
}
}
async function deleteResource(child: GfsChild): Promise<void> {
try {
await apiSend('DELETE', `/api/v1/gfs/proxy/v1/resources/${encodeURIComponent(child.rid)}`, {
ifMatch: child.version,
})
// A deleted directory's cached children must never be served again.
if (child.kind === 'directory') childCacheRef.current.delete(child.resourceId)
showToast('Resource deleted.', { tone: 'success' })
setSelected(null)
// Deleting a breadcrumb folder removes the open location with it —
// navigate up to its parent instead of refreshing a dead trail.
const crumbIndex = crumbs.findIndex(crumb => crumb.id === child.resourceId)
if (crumbIndex >= 0) {
goToCrumb(crumbIndex - 1)
return
}
await refreshCurrent()
} catch (err) {
showToast(err instanceof Error ? err.message : 'Could not delete resource.', {
tone: 'error',
})
}
}
/** Move-dialog navigation context. Rows keep the full trail; a crumb target
* ends the trail at ITS parent so the dialog's current-location pill and
* no-op guard match the parent-view row semantics. */
const moveTargetCrumbIndex = moveTarget
? crumbs.findIndex(crumb => crumb.id === moveTarget.resourceId)
: -1
const moveDialogCrumbs =
moveTargetCrumbIndex >= 0 ? crumbs.slice(0, moveTargetCrumbIndex) : crumbs
// Hover verdict announcement (RP-026 shape, plan §3.3): the live region
// carries the hovered target's verdict sentence. Text CHANGES announce;
// repeated identical text stays silent, so repeated dragover events never
// spam. Refused drops additionally use the toast stack, which is itself a
// live region.
const draggedSourceNow = draggingResourceId !== null ? draggingResourceRef.current : null
let dropHoverAnnouncement = ''
if (sessionLost) {
// Matrix A11: the session-lost sentence is spoken once through the same
// live region that carries hover verdicts, alongside the persistent
// banner for sighted users.
dropHoverAnnouncement = gfsDropRefusalMessage('session-lost')
} else if (draggedSourceNow && dragOverCrumbIndex !== null) {
const hoveredCrumb = crumbs[dragOverCrumbIndex]
const verdict = crumbHoverVerdict(draggedSourceNow, dragOverCrumbIndex)
if (verdict && hoveredCrumb) {
dropHoverAnnouncement = gfsDropHoverAnnouncement(verdict, {
sourceName: draggedSourceNow.name,
targetName: isDriveRootCrumb(hoveredCrumb) ? DRIVE : hoveredCrumb.name,
})
}
} else if (draggedSourceNow && dragOverFolderId !== null) {
const hoveredRow = items.find(item => item.resourceId === dragOverFolderId)
const verdict = hoveredRow ? rowHoverVerdict(draggedSourceNow, hoveredRow) : null
if (verdict && hoveredRow) {
dropHoverAnnouncement = gfsDropHoverAnnouncement(verdict, {
sourceName: draggedSourceNow.name,
targetName: hoveredRow.name,
})
}
}
return (
<section
className="cu-gfs"
aria-label="EvenDrive browser"
aria-busy={loading || droppedUploadCount > 0 || movingResourceId !== null}
>
<div aria-live="polite" className="cu-gfs-drop-announce" data-testid="gfs-drop-announce">
{dropHoverAnnouncement}
</div>
<div
className="cu-card cu-card--viewport-fill cu-gfs-card"
onDragEnter={handleGfsDragEnter}
onDragLeave={handleGfsDragLeave}
onDragOver={handleGfsDragOver}
onDrop={event => void handleGfsDrop(event)}
>
<TablePanelHeader
title={
<>
<IconHardDrive /> EvenDrive
</>
}
subtitle="Browse and manage drive resources and access grants from the admin plane."
/>
{dragActive || droppedUploadCount > 0 ? (
<div className="cu-gfs-drop-overlay" role="status">
{droppedUploadCount > 0
? `Uploading ${droppedUploadCount} ${droppedUploadCount === 1 ? 'file' : 'files'}…`
: current?.id
? `Drop files to upload to ${currentLabel}`
: 'Files cannot be uploaded until a destination folder is available.'}
</div>
) : null}
{error ? (
<div className="cu-banner cu-banner--error" role="alert">
{error}
</div>
) : null}
{sessionLost ? (
<div className="cu-banner cu-banner--error" role="alert">
{gfsDropRefusalMessage('session-lost')}
</div>
) : null}
{trailRecovery ? (
<div className="cu-banner cu-banner--warning cu-banner--dismissible" role="alert">
{trailRecovery.reason === 'move' ? (
<span>
“
{crumbs.find(crumb => crumb.id === trailRecovery.resourceId)?.name ??
trailRecovery.resourceId}
” moved, but its folder path could not be refreshed — the breadcrumb may not
show the real location.
</span>
) : (
<span>
The current folder path could not be refreshed. Your current location is still
shown.
</span>
)}
<Button
size="sm"
onClick={() => void retryTrailRecovery()}
aria-label={trailRecovery.reason === 'hierarchy' ? 'Retry folder path' : undefined}
>
Retry
</Button>
</div>
) : null}
<div className="cu-gfs-panel">
<div className="cu-gfs-panel__toolbar">
<nav aria-label="Breadcrumb" className="cu-gfs-breadcrumb">
{crumbs.map((crumb, index) => {
// Only the ACTIVE folder segment carries a ⋯ menu — mounted to
// the right of its name, mirroring the Desktop Files pattern.
// The synthetic drive root and ancestor crumbs stay plain.
const activeFolder = index === crumbs.length - 1 ? crumbToChild(crumb) : null
// Every crumb is a drop target (plan §3.1): the drop-state
// verdict is painted token-driven alongside the reason; click
// and keyboard navigation stay untouched.
const draggedSource =
draggingResourceId !== null ? draggingResourceRef.current : null
const crumbVerdict =
draggedSource && dragOverCrumbIndex === index
? crumbHoverVerdict(draggedSource, index)
: null
return (
<span
className="cu-gfs-breadcrumb__item"
key={`${isDriveRootCrumb(crumb) ? 'root' : crumb.id}-${index}`}
>
{index > 0 ? <IconChevronRight width={14} height={14} /> : null}
<button
className={`cu-gfs-breadcrumb__button${
crumb.name === '/' ? ' cu-gfs-breadcrumb__button--root' : ''
}`}
type="button"
onClick={() => goToCrumb(index)}
onDragEnter={event => handleCrumbDragEnter(event, index)}
onDragOver={event => handleCrumbDragOver(event, index)}
onDragLeave={event => handleCrumbDragLeave(event, index)}
onDrop={event => handleCrumbDrop(event, crumb, index)}
aria-current={index === crumbs.length - 1 ? 'page' : undefined}
data-drop-state={crumbVerdict ? crumbVerdict.state : undefined}
data-drop-reason={
crumbVerdict &&
crumbVerdict.state !== 'allowed' &&
crumbVerdict.state !== 'checking'
? crumbVerdict.reason
: undefined
}
>
{crumb.name === '/' ? (
<>
<span className="cu-gfs-breadcrumb__drive-icon" aria-hidden="true">
<IconFolder />
</span>
<span>{DRIVE}</span>
</>
) : (
crumb.name
)}
</button>
{activeFolder ? <GfsResourceMenu {...folderMenuProps(activeFolder)} /> : null}
</span>
)
})}
</nav>
<div className="cu-gfs-panel__actions">
<Button
className="cu-gfs-create-action"
disabled={!current?.id}
onClick={openNewFolder}
size="sm"
variant="primary"
>
<IconFolder />
New folder
</Button>
<Button
className="cu-gfs-create-action"
disabled={!current?.id}
onClick={() => {
setUploadCandidate(null)
setUploadOpen(true)
}}
size="sm"
>
<IconUpload width={16} height={16} />
Upload file
</Button>
</div>
</div>
{loading ? (
<div
className="cu-gfs-loading"
role="status"
aria-label="Loading files"
aria-live="polite"
>
<span className="cu-gfs-loading__dots" aria-hidden="true">
<span className="cu-gfs-loading__dot" />
<span className="cu-gfs-loading__dot" />
<span className="cu-gfs-loading__dot" />
</span>
<span>Loading files…</span>
</div>
) : (
<div className="cu-gfs-list-frame">
<div className="cu-gfs-list__head" aria-hidden="true">
<span />
<span>Name</span>
<span className="cu-gfs-list__head-size">Size</span>
<span className="cu-gfs-list__head-actions">Actions</span>
</div>
<ul className="cu-gfs-list" aria-label="Current folder resources">
{items.map(child => {
const rowOpenable = child.kind === 'directory' || isGfsPreviewFile(child.name)
const isDragging = draggingResourceId === child.resourceId
const canDragResource = movingResourceId === null
// Directory rows and the dragged row itself stay hoverable
// drop zones so a refused drop can explain its reason
// (matrix A1/§5.3); plain file rows are not move targets.
const rowIsDropZone =
canDragResource &&
(child.kind === 'directory' ||
(isDragging && draggingResourceId === child.resourceId))
const draggedSource =
draggingResourceId !== null ? draggingResourceRef.current : null
const rowVerdict =
draggedSource && dragOverFolderId === child.resourceId
? rowHoverVerdict(draggedSource, child)
: null
const openRow = () => {
if (child.kind === 'directory') openDirectory(child)
else openFilePreview(child)
}
return (
<li
className={`cu-gfs-list__row${rowOpenable ? ' cu-gfs-list__row--clickable' : ''}`}
key={child.resourceId}
draggable={canDragResource}
title={
canDragResource
? `Drag ${child.name} into a folder or breadcrumb to move it`
: undefined
}
onDragStart={
canDragResource ? event => handleResourceDragStart(event, child) : undefined
}
onDragEnd={canDragResource ? handleResourceDragEnd : undefined}
onDragEnter={
rowIsDropZone ? event => handleFolderDragEnter(event, child) : undefined
}
onDragOver={
rowIsDropZone ? event => handleFolderDragOver(event, child) : undefined
}
onDragLeave={rowIsDropZone ? handleFolderDragLeave : undefined}
onDrop={
rowIsDropZone ? event => void handleFolderDrop(event, child) : undefined
}
data-dragging={isDragging ? 'true' : undefined}
data-drop-target={rowVerdict?.state === 'allowed' ? 'true' : undefined}
data-drop-state={rowVerdict ? rowVerdict.state : undefined}
data-drop-reason={
rowVerdict &&
rowVerdict.state !== 'allowed' &&
rowVerdict.state !== 'checking'
? rowVerdict.reason
: undefined
}
role={rowOpenable ? 'button' : undefined}
tabIndex={rowOpenable ? 0 : undefined}
aria-label={rowOpenable ? `Open ${child.name}` : undefined}
onClick={
rowOpenable
? event => {
if (isEventFromNestedInteractive(event)) return
openRow()
}
: undefined
}
onKeyDown={
rowOpenable
? event => {
if (event.key !== 'Enter' && event.key !== ' ') return
if (isEventFromNestedInteractive(event)) return
event.preventDefault()
openRow()
}
: undefined
}
>
<span className="cu-gfs-list__icon" aria-hidden="true">
{child.kind === 'directory' ? (
<IconFolder />
) : gfsImagePreviewMimeType(child.name) ? (
<IconImage />
) : isGfsVideoFile(child.name) ? (
<IconVideo />
) : isGfsDocumentFile(child.name) ? (
<IconDocumentText />
) : (
<IconServer />
)}
</span>
<span className="cu-gfs-list__identity">
<span className="cu-gfs-list__name">
{child.kind === 'directory' ? (
<button
className="cu-gfs-list__name-button"
type="button"
onClick={() => openDirectory(child)}
>
{child.name}
</button>
) : (
<>
{isGfsPreviewFile(child.name) ? (
<button
className="cu-gfs-list__name-button"
type="button"
onClick={() => openFilePreview(child)}
>
{child.name}
</button>
) : (
<span>{child.name}</span>
)}
</>
)}
</span>
</span>
<span className="cu-gfs-list__value">
{child.kind === 'directory' ? '—' : formatBytes(child.bytes)}
</span>
<span
className="cu-gfs-list__actions"
onClick={event => {
const target = event.target
if (target instanceof Element) {
const interactive = target.closest(
'button, a, input, select, textarea, [tabindex]'
)
if (interactive && event.currentTarget.contains(interactive)) return
}
event.preventDefault()
event.stopPropagation()
event.currentTarget
.querySelector<HTMLButtonElement>('button[aria-haspopup="menu"]')
?.click()
}}
>
<GfsResourceMenu
resourceName={child.name}
resourceUri={child.gfsUri}
downloading={downloadingIds.has(child.resourceId)}
onManage={() => openManage(child)}
onPreview={
isGfsPreviewFile(child.name) ? () => openFilePreview(child) : undefined
}
onDownload={
child.kind !== 'directory' ? () => void downloadFile(child) : undefined
}
onReplace={
child.kind !== 'directory'
? file => void replaceFile(child, file)
: undefined
}
onCopyLink={() => void copyGfsUri(child.gfsUri)}
// Folders keep the EvenDrive link flow reachable from
// their row menu, matching the breadcrumb crumb menu.
onOpenLink={
child.kind === 'directory' ? () => setOpenLinkOpen(true) : undefined
}
onRename={() => openRowRename(child)}
onMove={() => openMove(child)}
onDelete={() => openManage(child, 'delete')}
/>
</span>
</li>
)
})}
{items.length === 0 && !loading ? (
<li className="cu-gfs-list__empty">No resources are visible in this folder.</li>
) : null}
</ul>
</div>
)}
{!loading && items.length > 0 ? (
<p className="cu-gfs-list-count" aria-live="polite">
{nextCursor
? `Showing the first ${items.length} ${items.length === 1 ? 'item' : 'items'}.`
: `Showing all ${items.length} ${items.length === 1 ? 'item' : 'items'}.`}
</p>
) : null}
{nextCursor && !loading ? (
<p className="cu-gfs-list-count cu-gfs-list-count--truncated">
The listing is truncated at the page cap — Load more fetches the next page.
</p>
) : null}
{nextCursor && !loading ? (
<Button
className="cu-gfs__load-more"
size="sm"
disabled={loadingMore}
aria-busy={loadingMore}
onClick={() => void load(current, nextCursor)}
>
{loadingMore ? 'Loading…' : 'Load more'}
</Button>
) : null}
</div>
</div>
{selected && !deleteOpen ? (
<div
className="cu-modal-backdrop cu-gfs-manage-modal"
role="presentation"
onMouseDown={event => {
if (event.target === event.currentTarget) setSelected(null)
}}
>
<section
className="cu-gfs-manage-dialog"
role="dialog"
aria-modal="true"
aria-label={`Share ${selected.kind === 'directory' ? 'folder' : 'file'} ${selected.name}`}
>
<header className="cu-gfs-manage-dialog__header">
<span
className={`cu-gfs-manage-dialog__icon${
selected.kind === 'directory' ? ' cu-gfs-manage-dialog__icon--folder' : ''
}`}
aria-hidden="true"
>
{selected.kind === 'directory' ? (
<IconFolder />
) : gfsImagePreviewMimeType(selected.name) ? (
<IconImage />
) : isGfsVideoFile(selected.name) ? (
<IconVideo />
) : isGfsDocumentFile(selected.name) ? (
<IconDocumentText />
) : (
<IconPaperclip />
)}
</span>
<span className="cu-gfs-manage-dialog__heading">
<h3>Share “{selected.name}”</h3>
</span>
<span className="cu-gfs-manage-dialog__top-actions">
<Button
autoFocus
className="cu-gfs-manage-dialog__close"
variant="ghost"
aria-label="Close share dialog"
onClick={() => setSelected(null)}
>
<IconX width={18} height={18} />
</Button>
</span>
</header>
<div className="cu-gfs-manage-dialog__body">
<section className="cu-gfs-manage-section cu-gfs-manage-section--access">
<div className="cu-gfs-manage-section__header">
<h4>Add people, teams, agents, or workflows</h4>
</div>
<GfsGrantPanel
resource={{
resourceId: selected.resourceId,
name: selected.name,
gfsUri: selected.gfsUri,
kind: selected.kind,
path: selected.path,
}}
/>
</section>
</div>
</section>
</div>
) : null}
{renameTarget ? (
<SingleValueEditDialog
open
initialValue={renameTarget.name}
title={`Rename ${renameTarget.kind === 'directory' ? 'folder' : 'file'}`}
description={`Change the name without moving this ${
renameTarget.kind === 'directory' ? 'folder' : 'file'
} to another folder.`}
pending={renaming}
error={renameError || undefined}
isValid={renameValid}
discardLabel="Cancel"
saveLabel="Rename"
onDismiss={() => {
setRenameError('')
setRenameTarget(null)
}}
onSave={value => void renameResource(renameTarget, value)}
renderEditor={({ value, onChange, disabled }) => (
<Field label="New name" htmlFor="gfs-resource-name" required>
<TextInput
id="gfs-resource-name"
aria-label="New name"
value={value}
disabled={disabled}
onChange={event => {
const next = event.target.value
setRenameValid(next.trim().length > 0)
onChange(next)
}}
/>
</Field>
)}
/>
) : null}
{selected && deleteOpen ? (
<div
className="cu-modal-backdrop cu-gfs-manage-modal"
role="presentation"
onMouseDown={event => {
if (event.target === event.currentTarget) setSelected(null)
}}
>
<section
className="cu-gfs-delete-dialog"
role="alertdialog"
aria-modal="true"
aria-label="Delete resource"
>
<div className="cu-gfs-delete-dialog__copy">
<h3>Delete {selected.name}?</h3>
<p>This action cannot be undone.</p>
</div>
<div className="cu-gfs-delete-dialog__actions">
<Button
autoFocus
variant="ghost"
onClick={() => {
setDeleteOpen(false)
setSelected(null)
}}
>
Cancel
</Button>
<Button variant="danger" onClick={() => void deleteResource(selected)}>
Delete
</Button>
</div>
</section>
</div>
) : null}
{newFolderOpen ? (
<NewFolderModal
folderLabel={currentLabel}
pending={creatingFolder}
error={createFolderError}
onCreate={name => void createFolder(name)}
onCancel={() => setNewFolderOpen(false)}
/>
) : null}
{openLinkOpen ? (
<GfsOpenLinkModal
pending={openLinkResolving}
error={openLinkError}
onOpen={uri => void openEvenDriveLink(uri)}
onCancel={() => {
setOpenLinkOpen(false)
setOpenLinkError(null)
}}
/>
) : null}
{moveTarget ? (
<GfsMoveDialog
busy={movingResourceId === moveTarget.resourceId}
initialCrumbs={moveDialogCrumbs}
onClose={() => setMoveTarget(null)}
onMove={async destination => {
await moveResource(
moveTarget,
{ resourceId: destination.resourceId, name: destination.name, kind: 'directory' },
{ bubbleError: true, occupiedNames: destination.occupiedNames }
)
setMoveTarget(null)
}}
target={moveTarget}
/>
) : null}
{confirmMoveTarget ? (
<GfsMoveConfirmDialog
busy={movingResourceId === confirmMoveTarget.source.resourceId}
onCancel={() => setConfirmMoveTarget(null)}
onConfirm={({ allowNumberedRename }) => {
const pending = confirmMoveTarget
setConfirmMoveTarget(null)
if (pending) {
void moveResource(pending.source, pending.destination, {
allowNumberedRename,
revalidate: { epoch: pending.epoch, oldParentId: pending.oldParentId },
})
}
}}
request={{
sourceName: confirmMoveTarget.source.name,
sourceKind: confirmMoveTarget.source.kind === 'directory' ? 'directory' : 'file',
destinationName: confirmMoveTarget.destination.name,
canRename: true,
...(confirmMoveTarget.suggestedName !== undefined
? { suggestedName: confirmMoveTarget.suggestedName }
: {}),
}}
/>
) : null}
{uploadOpen ? (
<FileUploadModal
busy={uploading}
file={uploadCandidate}
fileSummary={
uploadCandidate ? `${formatBytes(uploadCandidate.size)} selected` : undefined
}
progress={
uploadSnapshot
? {
uploadedBytes: uploadSnapshot.uploadedBytes,
totalBytes: uploadSnapshot.totalBytes,
state: uploadSnapshot.state,
}
: undefined
}
onCancelUpload={() => void cancelUpload()}
onPauseUpload={() => void pauseUpload()}
onResumeUpload={() => void resumeUpload()}
onClose={closeUploadModal}
onFileChange={setUploadCandidate}
onUpload={() => void uploadFile(uploadCandidate)}
/>
) : null}
{imagePreview ? (
<GfsImagePreview
key={`${imagePreview.gfsUri}:${imagePreview.reloadVersion}`}
byteLength={imagePreview.byteLength}
fileName={imagePreview.fileName}
mimeType={imagePreview.mimeType}
rid={imagePreview.rid}
unavailable={imagePreview.unavailable}
onClose={() => setImagePreview(null)}
/>
) : null}
{markdownPreview ? (
<GfsMarkdownPreview
key={`${markdownPreview.gfsUri}:${markdownPreview.reloadVersion}`}
byteLength={markdownPreview.byteLength}
fileName={markdownPreview.fileName}
rid={markdownPreview.rid}
unavailable={markdownPreview.unavailable}
onClose={() => setMarkdownPreview(null)}
/>
) : null}
{videoPreview ? (
<GfsVideoPreview
key={`${videoPreview.gfsUri}:${videoPreview.reloadVersion}`}
byteLength={videoPreview.byteLength}
fileName={videoPreview.fileName}
mimeType={videoPreview.mimeType}
rid={videoPreview.rid}
unavailable={videoPreview.unavailable}
onClose={() => setVideoPreview(null)}
/>
) : null}
</section>
)
}