File System (Finder)

Document renderers and data grids in Extend UI rely on browser APIs. In a server-rendered React application, keep the surrounding route server-rendered if useful, but load the document surface from a client component. Next.js users can use a client wrapper or next/dynamic with server rendering disabled for the viewer or editor.

Give the surface a measurable height. Virtualized pages, slides, and cells cannot size themselves inside an unconstrained container. A fixed height, viewport-relative height, or flex child whose ancestors all establish a height works.

Remote document URLs must be reachable by the browser, not only by the application server. Configure CORS for the application origin and preserve byte-range requests when the storage service and renderer support them. For private files, resolve a short-lived signed URL immediately before opening the document rather than embedding cloud credentials in the component.

Test with representative large files and with the same browser security headers used in production. PDFium WebAssembly, worker-based renderers, canvas export, and cross-origin images can expose deployment-only failures that a small local fixture will not.

Keep the PDF viewer as the source of page geometry and navigation. Review records should carry a one-based page number plus coordinates relative to the original page dimensions. Convert upstream extraction coordinates once at the data boundary instead of compensating independently in every overlay.

Use the viewer's active-page callback to update the review panel. In the other direction, call the viewer handle's page or page-area scroll method when a citation, OCR block, signature field, or split thumbnail is selected. This two-way controlled state keeps the panes synchronized without coupling their internal implementations.

Render page annotations through the viewer's overlay hook. The hook receives page size, scale, and rotation, which are the inputs needed to position a normalized region correctly. Recompute overlays when rotation or zoom changes instead of storing screen pixels.

The resizable shell owns layout only. Keep edited fields, split groups, signatures, and persistence in the parent workflow so a pane can remount without losing application state.

Translate object-store results into one flat list of file and folder records. Preserve the full key or path on every record. File System derives the hierarchy from those paths, so it does not need a separate nested tree from the server.

For large buckets, return folders with hasChildren: true and implement loadChildren. Pass the requested prefix and cursor to S3, R2, or the equivalent listing API, then return the next page and cursor until the folder is complete.

Resolve private file URLs with getFileUrl when a file opens. Generate signed URLs on the server and keep their lifetime long enough for the selected viewer to fetch or range-read the document. Do not expose object-store credentials to the browser.

Thumbnail generation is a separate concern. Store preview URLs with the manifest when possible. For long documents, provide the first page eagerly, the total preview page count, and load later page thumbnails on demand. Use onFileOpen when navigation, authorization, or a custom preview route must run before the built-in viewer dialog.