Files Package

@prox-os/files is the shared OS-native file primitives package for Prox OS apps. It defines file and folder contracts, storage provider refs, path and breadcrumb helpers, file action refs, preview models, transfer state, mock storage data, adapter examples, React primitives, and UI Workshop stories.

It is not a cloud drive backend, upload service, download service, sync engine, permission system, browser file-system integration, virus scanner, DLP system, file manager app, notification center, search engine, collaboration system, security dashboard, or OS runtime file daemon. Runtime, apps, and future backend packages own persistence, transfer, permission enforcement, provider credentials, routing, execution, and storage policy.

Package Scope

The package provides:

serializable contracts for files, folders, shortcuts, virtual folders, artifacts, storage providers, file locations, versions, previews, metadata, transfer tasks, permissions, action refs, storage usage, filters, sorting, selection state, and file events;
helpers for file kind detection, extension parsing, labels, icon tokens, paths, breadcrumbs, size formatting, filtering, sorting, grouping, preview creation, selection toggles, transfer progress, upload queue summaries, and action refs;
adapter examples for @prox-os/actions, @prox-os/search, @prox-os/notifications, @prox-os/collaboration, workspace resources, AI artifacts, security view models, and generic resource refs;
mock data for docs, media, datasets, AI artifacts, developer artifacts, workspace files, shared files, sync conflicts, upload queues, storage providers, previews, recent files, and pinned files;
React primitives for file icons, badges, rows, cards, lists, grids, folder trees, breadcrumbs, toolbar, picker, dropzone, upload queue, previews, metadata, storage usage, empty/loading states, and conflict states.

Non-Goals

No Cloudflare R2, S3, Google Drive, Dropbox, OneDrive, WebDAV, Supabase Storage, Firebase Storage, OPFS, IndexedDB, or browser File System Access API.
No real upload, download, sync, import, export, or network transfer.
No browser file-system permission prompts.
No virus scanning, DLP, encryption, audit enforcement, or security policy.
No search system replacement. @prox-os/search owns query/filter/facet/result UX.
No notification center replacement. @prox-os/notifications owns toast, center, digest, and preferences.
No collaboration replacement. @prox-os/collaboration owns threads, sharing, reviews, presence, and comments.
No command palette, editor, forms, AI UI, workspace management, or activity timeline ownership.
No OS Shell private imports.

Core Concepts

Concept	Type	Responsibility
File node	`OsFileNode`	Normalized file, shortcut, artifact, or folder-like item shown by file UI.
Folder node	`OsFolderNode`	Folder or virtual folder with optional children and child counts.
Storage provider	`OsStorageProviderRef`	Serializable provider identity and future provider boundary.
File location	`OsFileLocation`	Path, route, href, bucket/key metadata, and provider ref.
File version	`OsFileVersion`	Version label, checksum, size, creator, and timestamp metadata.
Preview	`OsFilePreview`	Lightweight preview view model for text, markdown, image, PDF, code, table, metadata, or unsupported files.
Transfer task	`OsFileTransferTask`	Upload, download, sync, export, or import state. Phase 1 uses mock tasks only.
Selection state	`OsFileSelectionState`	Single or multiple selected file ids and focused id.
Storage usage	`OsStorageUsage`	Provider-level usage and capacity display model.
File action	`OsFileActionRef`	Action ref for open, preview, download, copy link, rename, move, delete, share, search, AI summary, or conflict resolution.
File event	`OsFileEvent`	UI callback event emitted by primitives. Runtime decides execution.

The preview component is exported as OsFilePreviewView because OsFilePreview is the data contract type.

React Primitives

OsFileIcon
OsFileKindBadge
OsFileStatusBadge
OsStorageProviderBadge
OsFileConflictBadge
OsFileRow
OsFileCard
OsFileList
OsFileGrid
OsFolderTree
OsFileBreadcrumbs
OsFileToolbar
OsFilePicker
OsFileDropzone
OsUploadTaskItem
OsUploadQueue
OsFilePreviewView
OsFilePreviewPanel
OsFileMetadataPanel
OsStorageUsageBar
OsFileEmptyState
OsFileLoadingState

Storybook

Open UI Workshop and browse:

Files / Overview
Files / Icons & Badges
Files / List & Grid
Files / Folder Tree & Breadcrumbs
Files / File Picker
Files / Dropzone & Upload Queue
Files / Preview Panel
Files / Metadata Panel
Files / Storage Usage
Files / Actions Integration
Files / Search Notification Collaboration Adapters
Files / AI Workspace Security Files

The stories use mock files, mock transfer tasks, mock storage providers, and adapter output only. They do not upload, download, sync, request browser file permissions, or connect to storage services.

Package Relationships

Package	Relationship
`@prox-os/actions`	File action refs can become action intents such as open, preview, download, copy link, rename, delete, share, summarize with AI, or resolve conflict. Files does not execute actions.
`@prox-os/search`	File nodes can map to searchable documents. Search owns query, filters, facets, result UI, and indexing providers.
`@prox-os/notifications`	Transfer tasks and file events can become notification drafts. Notifications owns toast, center, digest, and preferences.
`@prox-os/collaboration`	File nodes can map to collaboration resource refs. Collaboration owns comments, threads, sharing, reviews, and presence.
`@prox-os/command`	Future command entries can trigger file actions or open recent files. Files does not render command palette UX.
`@prox-os/forms`	Future rename, move, create folder, upload metadata, and permission dialogs can use form primitives. Phase 1 keeps files lightweight.
`@prox-os/editor`	Markdown, code, and text files can open in editors later. Files does not implement editors.
Future AI UI	AI artifacts, summaries, reports, generated images, and dataset extracts can use file nodes. Files does not run AI.
Future security UI	Sensitive, restricted, scan status, and public link metadata can feed security surfaces. Files does not enforce policy.
Future workspace UI	Workspace storage, ownership, and team folder views can consume storage refs and file nodes.
Future activity	File events can become timeline entries without making files own activity UI.

Phase Roadmap

Phase 1: Contracts, Mock Data, And UI Primitives

TypeScript contracts.
Mock file tree, storage providers, upload tasks, previews, recent files, and shared files.
File browser, picker, preview, upload queue, metadata, and storage usage UI primitives.
Helpers and adapters.
Storybook examples.
Docs.
No real storage backend.
No real upload or download.
No browser file-system permission prompt.

Phase 2: Provider Boundary And Local State

Define OsFileProvider.
Mock provider and local storage provider.
File picker provider boundary.
Upload queue state adapter.
Recent and pinned file persistence.
Optimistic rename, move, delete, and restore UI state.

Phase 3: OS Runtime Integration

OS file picker runtime API.
App, window, and resource-level file open handoff.
Recent files in launcher, command palette, and search.
Notification and activity integration for file events.
Workspace-scoped storage view.

Phase 4: Real Storage Providers

Cloudflare R2 provider.
S3-compatible provider.
WebDAV provider.
Google Drive and Dropbox adapters.
OPFS or browser File System Access provider.
Signed upload and download URLs.
File versioning, retention, and recycle bin.
Permission-aware storage routing.

Phase 5: AI And Community Artifacts

AI artifact lifecycle.
File summarization and question answering.
Public dataset and media sharing for creator routes.
Community app assets and resource packs.

Acceptance Checklist

Package exports contracts, helpers, adapters, mock data, and React primitives.
Helpers can detect file kind, format sizes, build breadcrumbs, filter/sort files, create previews, and summarize transfers.
UI Workshop exposes all core file stories.
No OS Shell private imports.
No real storage SDK, upload backend, browser file-system permission, OPFS, or IndexedDB persistence.
Docs state the storage provider boundary and Phase 1 mock-first scope.

Files Package

On this page