portal-mojo 0.1.0

package/src/admin/storage/FileUploadSurface.tsx

@@ -0,0 +1,250 @@
+import {
+    useCallback, useEffect, useMemo, useRef, useState,
+    type ReactNode,
+} from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import {
+    CollectionSelect, FilePicker, UploadQueue, fmt, modal, toast,
+    useFileDrop, useUploadQueue, validateFileSelection,
+    type FileSelectionResult,
+} from '../../ui';
+import type { StartFileUploadOptions, UploadedFileRef } from '../../client/upload';
+import {
+    FileManagerUploadPolicyModel, FileModel,
+    type FileManagerUploadPolicyRow, type RelationRow,
+} from './models';
+
+const MANAGER_LIMIT = 50;
+const QUEUE_CAPACITY = 6;
+
+function policyAccept(policy: FileManagerUploadPolicyRow | null): string[] {
+    if (!policy) return [];
+    return [
+        ...policy.allowed_mime_types,
+        ...policy.allowed_extensions.map((extension) => `.${extension.replace(/^\./, '').toLowerCase()}`),
+    ];
+}
+
+function policySummary(policy: FileManagerUploadPolicyRow): ReactNode {
+    const types = [...policy.allowed_extensions.map((value) => `.${value.replace(/^\./, '')}`), ...policy.allowed_mime_types];
+    return (
+        <dl className="storage-upload-policy">
+            <div><dt>Maximum size</dt><dd>{policy.max_file_size > 0 ? fmt.filesize(policy.max_file_size) : 'No configured limit'}</dd></div>
+            <div><dt>Accepted types</dt><dd>{types.length ? types.join(', ') : 'Any type'}</dd></div>
+            <div><dt>Transfer route</dt><dd>{policy.supports_direct_upload ? 'Direct provider target' : 'Local API upload target'}</dd></div>
+        </dl>
+    );
+}
+
+interface DestinationDialogProps {
+    initialFiles: File[];
+    canChooseGroup: boolean;
+    remaining: number;
+    close: () => void;
+    enqueue: (files: File[], destination: StartFileUploadOptions) => boolean;
+}
+
+function DestinationDialog({ initialFiles, canChooseGroup, remaining, close, enqueue }: DestinationDialogProps) {
+    const [scope, setScope] = useState<'system' | 'group'>('system');
+    const [groupId, setGroupId] = useState<number | null>(null);
+    const [managerId, setManagerId] = useState<number | null>(null);
+    const [files, setFiles] = useState<File[]>(initialFiles);
+    const [rejections, setRejections] = useState<string[]>([]);
+    const groupScope = scope === 'group';
+    const params = groupScope
+        ? { group: groupId ?? undefined, user__isnull: true, size: MANAGER_LIMIT }
+        : { group__isnull: true, user__isnull: true, size: MANAGER_LIMIT };
+    const managersQuery = FileManagerUploadPolicyModel.useList(params, {
+        enabled: !groupScope || groupId != null,
+    });
+    const managers = managersQuery.data?.rows ?? [];
+    const truncated = Number(managersQuery.data?.count ?? 0) > managers.length;
+    const policy = managers.find((row) => row.id === managerId) ?? null;
+    const accept = policyAccept(policy);
+
+    useEffect(() => { setManagerId(null); }, [scope, groupId]);
+
+    const validate = useCallback((selected: Iterable<File>): FileSelectionResult => validateFileSelection(selected, {
+        accept,
+        maxFileSize: policy && policy.max_file_size > 0 ? policy.max_file_size : undefined,
+        maxFiles: Math.max(1, remaining),
+    }), [accept, policy, remaining]);
+
+    const selectFiles = (selection: FileSelectionResult) => {
+        setFiles(selection.accepted);
+        setRejections(selection.rejected.map((item) => item.message));
+    };
+    const submit = () => {
+        if (!policy) return;
+        const selection = validate(files);
+        setRejections(selection.rejected.map((item) => item.message));
+        if (!selection.accepted.length) return;
+        const accepted = enqueue(selection.accepted, {
+            fileManagerId: policy.id,
+            ...(groupScope && groupId != null ? { groupId } : {}),
+            ...(policy.use ? { use: policy.use } : {}),
+        });
+        if (accepted) close();
+    };
+
+    return (
+        <div className="modal-pad storage-upload-dialog">
+            <h2 className="modal-title">Add files</h2>
+            <p className="modal-message">Choose an explicit authorized destination. Policy checks here are guidance; the server authorizes every upload.</p>
+            {canChooseGroup && (
+                <div className="seg storage-upload-scope" aria-label="Destination scope">
+                    <button type="button" className={`seg-btn${scope === 'system' ? ' seg-active' : ''}`} onClick={() => setScope('system')}>System</button>
+                    <button type="button" className={`seg-btn${scope === 'group' ? ' seg-active' : ''}`} onClick={() => setScope('group')}>Group</button>
+                </div>
+            )}
+            {groupScope && canChooseGroup && (
+                <CollectionSelect<RelationRow>
+                    endpoint="/api/group" value={groupId}
+                    onChange={(id) => setGroupId(id == null ? null : Number(id))}
+                    defaultParams={{ is_active: true, size: 25 }} maxItems={25}
+                    label="Destination group" placeholder="Search authorized active groups" required
+                />
+            )}
+            <label className="field">
+                <span>Storage backend</span>
+                <select value={managerId ?? ''} disabled={managersQuery.isLoading || truncated || (groupScope && groupId == null)} onChange={(event) => setManagerId(event.target.value ? Number(event.target.value) : null)}>
+                    <option value="">{managersQuery.isLoading ? 'Loading authorized backends…' : 'Choose a backend'}</option>
+                    {managers.map((manager) => <option key={manager.id} value={manager.id}>{manager.name}{manager.use ? ` · ${manager.use}` : ''}</option>)}
+                </select>
+            </label>
+            {managersQuery.isError && <p className="storage-error" role="alert">Authorized upload backends could not be loaded.</p>}
+            {truncated && <p className="storage-error" role="alert">More than {MANAGER_LIMIT} backends match. Narrow the destination before uploading.</p>}
+            {!managersQuery.isLoading && !managersQuery.isError && !truncated && managers.length === 0 && (!groupScope || groupId != null) && <p className="storage-footnote">No active upload backend is available for this scope.</p>}
+            {policy && policySummary(policy)}
+            {policy && files.length === 0 && (
+                <FilePicker multiple accept={accept} maxFileSize={policy.max_file_size > 0 ? policy.max_file_size : undefined} maxFiles={Math.max(1, remaining)} onSelection={selectFiles}>
+                    Choose files
+                </FilePicker>
+            )}
+            {files.length > 0 && <p className="storage-upload-selection"><strong>{files.length}</strong> file{files.length === 1 ? '' : 's'} ready · {fmt.filesize(files.reduce((sum, file) => sum + file.size, 0))}</p>}
+            {rejections.length > 0 && <ul className="storage-upload-rejections" role="alert">{rejections.map((message, index) => <li key={`${index}:${message}`}>{message}</li>)}</ul>}
+            <div className="modal-actions">
+                <button type="button" className="btn" onClick={close}>Cancel</button>
+                <button type="button" className="btn btn-primary" disabled={!policy || files.length === 0 || truncated} onClick={submit}>Upload {files.length || ''}</button>
+            </div>
+        </div>
+    );
+}
+
+export interface FileUploadSurfaceProps {
+    canManage: boolean;
+    canChooseGroup: boolean;
+    children: (openPicker: () => void) => ReactNode;
+}
+
+/** Admin Files upload owner. Files/tasks stay queue-private and never enter Query cache. */
+export function FileUploadSurface({ canManage, canChooseGroup, children }: FileUploadSurfaceProps) {
+    const queryClient = useQueryClient();
+    const queue = useUploadQueue({ concurrency: 3, capacity: QUEUE_CAPACITY, consumerKey: 'admin-storage-files' });
+    const modalOpen = useRef(false);
+    const closeModal = useRef<(() => void) | null>(null);
+    const previousPermission = useRef(canManage);
+    const terminalSignature = useRef('');
+    const dirty = useRef(false);
+    const refreshPromise = useRef<Promise<void> | null>(null);
+    const [refreshMessage, setRefreshMessage] = useState<string | null>(null);
+
+    const cancelDestinationQueries = useCallback(() => {
+        void queryClient.cancelQueries({
+            predicate: (query) => query.queryKey[0] === FileManagerUploadPolicyModel.endpoint
+                && typeof query.queryKey[1] === 'object'
+                && (query.queryKey[1] as Record<string, unknown>)?.graph === 'upload_policy',
+        });
+        void queryClient.cancelQueries({ queryKey: ['/api/group'] });
+    }, [queryClient]);
+
+    const reconcile = useCallback(() => {
+        if (refreshPromise.current) return refreshPromise.current;
+        const run = async () => {
+            do {
+                dirty.current = false;
+                try {
+                    await queryClient.invalidateQueries({ queryKey: FileModel.keys.root, refetchType: 'none' });
+                    await queryClient.refetchQueries({ type: 'active', queryKey: FileModel.keys.root }, { throwOnError: true });
+                    setRefreshMessage('Authoritative refresh complete. Current filters may hide newly uploaded files.');
+                } catch {
+                    setRefreshMessage('Uploads may have changed, but the authoritative Files refresh failed. Refresh the table before another action.');
+                }
+            } while (dirty.current);
+        };
+        refreshPromise.current = run().finally(() => { refreshPromise.current = null; });
+        return refreshPromise.current;
+    }, [queryClient]);
+
+    const onComplete = useCallback(async (file: UploadedFileRef) => {
+        if (file.id < 1) throw new Error('Upload completion did not include an authoritative File id');
+        dirty.current = true;
+    }, []);
+
+    const enqueue = useCallback((files: File[], destination: StartFileUploadOptions): boolean => {
+        const result = queue.enqueue(files, { consumerKey: 'admin-storage-files', destination, onComplete });
+        result.rejected.forEach((item) => toast.warning(item.message));
+        if (result.acceptedIds.length) setRefreshMessage(null);
+        return result.acceptedIds.length > 0;
+    }, [queue, onComplete]);
+
+    const open = useCallback((files: File[] = []) => {
+        if (!canManage || modalOpen.current) return;
+        modalOpen.current = true;
+        const remaining = Math.max(0, QUEUE_CAPACITY - queue.snapshot.items.length);
+        if (remaining === 0) {
+            toast.warning(`The upload queue can hold ${QUEUE_CAPACITY} files.`);
+            modalOpen.current = false;
+            return;
+        }
+        files.slice(remaining).forEach((file) => toast.warning(`${file.name} was not added because the upload queue can hold ${QUEUE_CAPACITY} files.`));
+        void modal.open((close) => {
+            closeModal.current = () => close(null);
+            return <DestinationDialog initialFiles={files.slice(0, remaining)} canChooseGroup={canChooseGroup} remaining={remaining} enqueue={enqueue} close={() => close(null)} />;
+        }, { size: 'lg' }).finally(() => {
+            closeModal.current = null;
+            modalOpen.current = false;
+        });
+    }, [canManage, canChooseGroup, enqueue, queue.snapshot.items.length]);
+
+    const dropSelection = useCallback((selection: FileSelectionResult) => {
+        selection.rejected.forEach((item) => toast.warning(item.message));
+        if (selection.accepted.length) open(selection.accepted);
+    }, [open]);
+    const { isDragActive, dropProps } = useFileDrop({ disabled: !canManage, maxFiles: QUEUE_CAPACITY, onSelection: dropSelection });
+
+    useEffect(() => {
+        if (previousPermission.current && !canManage) {
+            closeModal.current?.();
+            cancelDestinationQueries();
+            queue.cancelAll();
+        }
+        previousPermission.current = canManage;
+    }, [canManage, cancelDestinationQueries, queue]);
+
+    useEffect(() => () => {
+        closeModal.current?.();
+        cancelDestinationQueries();
+        queue.cancelAll();
+    }, [cancelDestinationQueries, queue]);
+
+    const terminal = useMemo(() => queue.snapshot.items
+        .filter((item) => ['completed', 'completed-warning', 'failed', 'cancelled', 'uncertain'].includes(item.status))
+        .map((item) => `${item.id}:${item.status}:${item.file?.id ?? ''}`).join('|'), [queue.snapshot.items]);
+    useEffect(() => {
+        if (terminal !== terminalSignature.current) {
+            terminalSignature.current = terminal;
+            if (terminal) dirty.current = true;
+        }
+        if (dirty.current && queue.snapshot.activeCount === 0 && queue.snapshot.queuedCount === 0) void reconcile();
+    }, [terminal, queue.snapshot.activeCount, queue.snapshot.queuedCount, reconcile]);
+
+    return (
+        <div className={`storage-file-upload-surface${isDragActive ? ' is-drag-active' : ''}`} {...dropProps}>
+            {children(() => open())}
+            {isDragActive && <div className="storage-page-drop-overlay" aria-hidden="true"><i className="bi bi-cloud-arrow-up" /><strong>Drop files to choose their destination</strong></div>}
+            <UploadQueue queue={queue} className="storage-upload-queue" />
+            {refreshMessage && <p className={`storage-upload-refresh${refreshMessage.includes('failed') ? ' is-error' : ''}`} role="status">{refreshMessage}</p>}
+        </div>
+    );
+}

package/src/admin/storage/FileView.tsx

@@ -0,0 +1,109 @@
+import { useEffect, useRef, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { ArmedButton, Badge, DataView, DetailView, FlatRow, SchemaForm, fmt, modal, toast } from '../../ui';
+import { useCan } from '../../client';
+import { FilePreview, filePreviewCategory } from './FilePreview';
+import { normalizeRenditions, normalizeRenditionRoles, pollRenditionConvergence, renditionTargetSignature, type RenditionPollStop } from './file-renditions';
+import { FileModel, ShortLinkShareModel, STORAGE_MANAGE_PERMS, createFileShare, deleteFileShare, isSafeCapabilityUrl, openCapabilityUrl, setFileShareActive, saveFileAndReconcileGroup, type FileRenditionRow } from './models';
+
+function ShareResult({ url, close }: { url: string; close: () => void }) {
+    return <div className="modal-pad"><h2 className="modal-title">Share link created</h2><p className="modal-message">This newly minted capability is shown once from component-local state.</p><code className="storage-capability">{url}</code><div className="modal-actions"><button className="btn" onClick={() => void navigator.clipboard.writeText(url)}>Copy</button><button className="btn btn-primary" onClick={close}>Done</button></div></div>;
+}
+
+function RenditionRows({ rows, canManage, pollingDisabled, onRegenerate }: { rows: FileRenditionRow[]; canManage: boolean; pollingDisabled: boolean; onRegenerate: (roles: string[]) => void }) {
+    if (!rows.length) return <p className="dim">No renditions have appeared yet.</p>;
+    return <div className="storage-renditions">{rows.map((row) => <div className="storage-rendition" key={`${row.role}:${row.id}`}><div><b>{row.role}</b><small>{row.content_type} · {row.width && row.height ? `${row.width}×${row.height} · ` : ''}{row.file_size == null ? 'unknown size' : fmt.filesize(row.file_size)} · {row.upload_status}</small></div><div className="storage-action-row">{isSafeCapabilityUrl(row.url) && <><button className="btn-icon" title="Open rendition" onClick={() => openCapabilityUrl(row.url!)}><i className="bi bi-box-arrow-up-right" /></button><button className="btn-icon" title="Download rendition" onClick={() => openCapabilityUrl(row.url!, true)}><i className="bi bi-download" /></button></>}{canManage && <button className="btn-icon" disabled={pollingDisabled} title={`Regenerate ${row.role}`} onClick={() => onRegenerate([row.role])}><i className="bi bi-arrow-clockwise" /></button>}</div></div>)}</div>;
+}
+
+export function FileView({ id, onClose }: { id: number; onClose: () => void }) {
+    const queryClient = useQueryClient();
+    const query = FileModel.useOne(id);
+    const canManage = useCan(STORAGE_MANAGE_PERMS).can;
+    const regenerate = FileModel.useAction('regenerate_renditions');
+    const remove = FileModel.useDelete();
+    const shares = ShortLinkShareModel.useList({ file: id, start: 0, size: 25 }, { enabled: canManage });
+    const alive = useRef(true);
+    const initialPollStarted = useRef(false);
+    const pollGeneration = useRef(0);
+    const pollInFlightRef = useRef(false);
+    const regenerationBusyRef = useRef(false);
+    const [regenerationBusy, setRegenerationBusy] = useState(false);
+    const [pollState, setPollState] = useState<RenditionPollStop | 'polling' | null>(null);
+    useEffect(() => {
+        alive.current = true;
+        return () => {
+            alive.current = false;
+            initialPollStarted.current = false;
+            pollGeneration.current += 1;
+        };
+    }, []);
+
+    const startPoll = async (before: string, targetRoles: readonly string[] | null) => {
+        const generation = ++pollGeneration.current;
+        pollInFlightRef.current = true;
+        setPollState('polling');
+        try {
+            const reason = await pollRenditionConvergence({ fileId: id, beforeSignature: before, targetRoles, isCurrent: () => alive.current && pollGeneration.current === generation, fetch: async () => { const result = await query.refetch(); if (!result.data) throw new Error('File refresh returned no record'); return result.data; } });
+            if (alive.current && pollGeneration.current === generation) setPollState(reason);
+        } catch (error) {
+            if (alive.current && pollGeneration.current === generation) { setPollState('timeout'); toast.error(error instanceof Error ? error.message : 'Rendition refresh failed'); }
+        } finally { if (pollGeneration.current === generation) pollInFlightRef.current = false; }
+    };
+
+    const file = query.data;
+    useEffect(() => {
+        if (!file || initialPollStarted.current || file.upload_status !== 'completed' || normalizeRenditions(file.renditions).length > 0) return;
+        if (!['image', 'video', 'document', 'spreadsheet', 'presentation', 'pdf'].includes(filePreviewCategory(file))) return;
+        initialPollStarted.current = true;
+        void startPoll(renditionTargetSignature(file, null), null);
+    }, [file?.id]);
+
+    if (query.isLoading) return <div className="empty"><p>Loading file…</p></div>;
+    if (!file) return <div className="empty"><h2>File unavailable</h2><p>{query.error instanceof Error ? query.error.message : 'The record was not returned.'}</p><button className="btn" onClick={onClose}>Close</button></div>;
+    const renditionRows = normalizeRenditions(file.renditions);
+
+    const updatePublic = async () => {
+        const next = !file.is_public;
+        const ok = await modal.confirm({ title: next ? 'Make file public?' : 'Make file private?', message: <>Change access for <b>{file.filename}</b>?</>, confirmText: next ? 'Make public' : 'Make private', danger: next });
+        if (!ok) return;
+        try { await saveFileAndReconcileGroup(queryClient, id, { is_public: next }); await query.refetch(); } catch (error) { toast.error(error instanceof Error ? error.message : 'Access change failed'); }
+    };
+    const createShare = async () => {
+        const values = await modal.open<Record<string, unknown>>((close) => <div className="modal-pad"><h2 className="modal-title">Create share link</h2><SchemaForm fields={[{ name: 'expire_days', type: 'text', label: 'Expire after days', help: '0 means no expiry.' }, { name: 'track_clicks', type: 'switch', label: 'Track clicks' }, { name: 'note', type: 'textarea', label: 'Audit note' }]} initial={{ expire_days: '30', track_clicks: false, note: '' }} submitText="Create share" onCancel={() => close(null as never)} onSubmit={(data) => close(data as unknown as Record<string, unknown>)} /></div>);
+        if (!values) return;
+        try {
+            const result = await createFileShare(id, { expire_days: Number(values.expire_days ?? 30), track_clicks: Boolean(values.track_clicks), note: String(values.note ?? '') });
+            await modal.open((close) => <ShareResult url={result.url} close={() => close(null)} />, { size: 'sm' });
+            await shares.refetch().catch(() => undefined);
+        } catch (error) { toast.error(error instanceof Error ? error.message : 'Share creation failed'); }
+    };
+    const runRegenerate = async (roles: string[] = []) => {
+        if (regenerationBusyRef.current || pollInFlightRef.current || pollState === 'polling') return;
+        regenerationBusyRef.current = true;
+        setRegenerationBusy(true);
+        const normalized = normalizeRenditionRoles(roles);
+        try {
+            const ok = await modal.confirm({ title: normalized.length ? `Regenerate ${normalized.join(', ')}?` : 'Regenerate all renditions?', message: 'The renderer is asynchronous. This viewer polls finite observable state for up to 12 attempts.', confirmText: 'Queue regeneration' });
+            if (!ok) return;
+            const currentRoles = normalizeRenditions(file.renditions).map((row) => row.role);
+            const targetRoles = normalized.length > 0 ? normalized : currentRoles.length > 0 ? currentRoles : ['thumbnail', 'preview'];
+            const before = renditionTargetSignature(file, targetRoles);
+            await regenerate.mutateAsync({ id, payload: normalized.length ? normalized : true });
+            await startPoll(before, targetRoles);
+        } catch (error) { toast.error(error instanceof Error ? error.message : 'Could not queue renditions'); }
+        finally { regenerationBusyRef.current = false; setRegenerationBusy(false); }
+    };
+    const deleteOne = async () => {
+        await modal.open((close) => <div className="modal-pad"><h2 className="modal-title">Delete {file.filename}</h2><p className="modal-message">Enter the exact filename. This deletes the record, original backend object, and renditions.</p><SchemaForm fields={[{ name: 'filename', type: 'text', label: 'Exact filename', required: true }]} submitText="Delete file" onCancel={() => close(null)} onSubmit={async (data) => { if (String(data.filename ?? '') !== file.filename) throw new Error('Filename does not match. No request was sent.'); await remove.mutateAsync({ id }); close(true); onClose(); }} /></div>, { size: 'sm' });
+    };
+
+    return <DetailView title={file.filename} subtitle={`${file.content_type} · ${file.file_size == null ? 'unknown size' : fmt.filesize(file.file_size)}`} icon="bi-file-earmark" chips={[{ text: file.upload_status, tone: file.upload_status === 'completed' ? 'success' : file.upload_status === 'failed' ? 'danger' : 'warning' }, { text: file.is_public ? 'Public' : 'Private', tone: file.is_public ? 'warning' : 'muted' }]} sections={[
+        { key: 'overview', label: 'Overview', icon: 'bi-info-circle', render: () => <div className="detail-section"><div className="storage-action-row">{isSafeCapabilityUrl(file.url) && <><button className="btn" onClick={() => openCapabilityUrl(file.url!)}><i className="bi bi-box-arrow-up-right" /> Open</button><button className="btn" onClick={() => openCapabilityUrl(file.url!, true)}><i className="bi bi-download" /> Download</button><button className="btn" onClick={() => void navigator.clipboard.writeText(file.url!)}><i className="bi bi-copy" /> Copy URL</button></>}{canManage && <button className="btn" onClick={() => void updatePublic()}>{file.is_public ? 'Make private…' : 'Make public…'}</button>}</div>{!isSafeCapabilityUrl(file.url) && <p className="storage-unsafe">The backend URL is absent or unsafe; Open, Download, and Copy are refused.</p>}<FlatRow label="Filename">{file.filename}</FlatRow><FlatRow label="Category">{file.category || 'Unknown'}</FlatRow><FlatRow label="Upload status"><Badge tone={file.upload_status === 'completed' ? 'success' : 'warning'}>{file.upload_status}</Badge></FlatRow><FlatRow label="Public">{file.is_public ? 'Yes' : 'No'}</FlatRow><FlatRow label="Active">{file.is_active ? 'Yes' : 'No'}</FlatRow></div> },
+        { key: 'preview', label: 'Preview', icon: 'bi-eye', render: () => <div className="detail-section"><FilePreview file={file} /></div> },
+        { key: 'details', label: 'Details', icon: 'bi-card-list', render: () => <div className="detail-section"><FlatRow label="ID">{file.id}</FlatRow><FlatRow label="Content type">{file.content_type}</FlatRow><FlatRow label="Size">{file.file_size == null ? 'Unknown' : fmt.filesize(file.file_size)}</FlatRow><FlatRow label="Group">{typeof file.group === 'object' && file.group ? file.group.name || `#${file.group.id}` : file.group == null ? 'System' : `#${file.group}`}</FlatRow><FlatRow label="Backend">{typeof file.file_manager === 'object' && file.file_manager ? file.file_manager.name || `#${file.file_manager.id}` : `#${file.file_manager ?? '—'}`}</FlatRow><FlatRow label="Created">{fmt.datetime(file.created)}</FlatRow><FlatRow label="Modified">{fmt.datetime(file.modified)}</FlatRow></div> },
+        { key: 'renditions', label: 'Renditions', icon: 'bi-images', render: () => { const pollingDisabled = regenerationBusy || pollState === 'polling'; return <div className="detail-section"><div className="storage-section-head"><div><h3>Renditions</h3><p className="dim">Derived from the role-keyed File graph; no duplicate rendition store.</p></div>{canManage && <button className="btn" disabled={pollingDisabled} onClick={() => void runRegenerate()}>Regenerate all…</button>}</div><RenditionRows rows={renditionRows} canManage={canManage} pollingDisabled={pollingDisabled} onRegenerate={(roles) => void runRegenerate(roles)} />{pollState === 'polling' && <p className="dim"><i className="bi bi-arrow-repeat spin" /> Waiting for observable rendition change…</p>}{pollState === 'timeout' && <div className="form-alert">No convergence after 12 attempts. The job may still be running. <button className="btn btn-compact" onClick={() => void query.refetch()}>Refresh now</button></div>}{pollState && ['failed', 'expired'].includes(pollState) && <div className="form-alert">Polling stopped because upload state is {pollState}.</div>}</div>; } },
+        { key: 'shares', label: 'Shares', icon: 'bi-share', render: () => <div className="detail-section"><div className="storage-section-head"><div><h3>Visible shares</h3><p className="dim">Owner-visible rows only unless the caller separately holds global shortlink authority.</p></div>{canManage && <button className="btn btn-primary" onClick={() => void createShare()}>Create share…</button>}</div>{!canManage ? <p className="dim">Share controls are unavailable for this viewer.</p> : shares.isError ? <div className="form-alert">Visible shares unavailable. File inspection remains available.</div> : (shares.data?.rows ?? []).length === 0 ? <p className="dim">No visible shares.</p> : <div className="storage-shares">{shares.data!.rows.map((share) => <div key={share.id}><span><code>{share.code}</code><small>{share.is_active ? 'Active' : 'Inactive'} · {share.expires_at ? fmt.datetime(share.expires_at) : 'No expiry'} · {share.hit_count} hits · {share.track_clicks ? 'tracking' : 'not tracking'}{share.note ? ` · ${share.note}` : ''}</small></span><div className="storage-action-row"><button className="btn btn-compact" onClick={async () => { await setFileShareActive(share.id, !share.is_active); await shares.refetch(); }}>{share.is_active ? 'Deactivate' : 'Activate'}</button><button className="btn btn-compact" onClick={async () => { if (!await modal.confirm({ title: `Delete ${share.code}?`, message: 'This permanently deletes the share and its click history.', confirmText: 'Delete', danger: true })) return; await deleteFileShare(share.id); await shares.refetch(); }}>Delete</button></div></div>)}</div>}</div> },
+        { key: 'metadata', label: 'Metadata', icon: 'bi-braces', render: () => <div className="detail-section"><DataView data={file.metadata ?? {}} columns={2} /></div> },
+        ...(canManage ? [{ key: 'danger', label: 'Danger zone', icon: 'bi-exclamation-octagon', permissions: STORAGE_MANAGE_PERMS, render: () => <div className="detail-section storage-danger"><h3>Delete file</h3><p>This removes the backend object and derived renditions. It cannot be undone.</p><ArmedButton className="btn-danger" icon="bi-trash" label="Delete file" armedLabel="Click again — open exact-filename confirmation" onConfirm={deleteOne} /></div> }] : []),
+    ]} initialSection="overview" onClose={onClose} />;
+}

package/src/admin/storage/FilesPage.tsx

@@ -0,0 +1,53 @@
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { Badge, CollectionSelect, ModelTable, fmt, modal, type BatchAction, type Column, type FilterDef } from '../../ui';
+import { useCan } from '../../client';
+import { FileView } from './FileView';
+import { FileUploadSurface } from './FileUploadSurface';
+import { FileModel, GROUP_DIRECTORY_PERMS, STORAGE_MANAGE_PERMS, exportFiles, openCapabilityUrl, saveFileAndReconcileGroup, type FileRow, type RelationRow } from './models';
+
+const COLUMNS: Column<FileRow>[] = [
+    { key: 'filename', label: 'Filename', sortable: true, hideable: false },
+    { key: 'category', label: 'Category', sortable: true, render: (row) => <Badge tone="info">{row.category || 'unknown'}</Badge> },
+    { key: 'content_type', label: 'Content type', sortable: true },
+    { key: 'file_size', label: 'Size', sortable: true, align: 'end', render: (row) => row.file_size == null ? '—' : fmt.filesize(row.file_size) },
+    { key: 'group', label: 'Group', render: (row) => typeof row.group === 'object' && row.group ? row.group.name || `#${row.group.id}` : row.group == null ? 'System' : `#${row.group}` },
+    { key: 'file_manager', label: 'Backend', render: (row) => typeof row.file_manager === 'object' && row.file_manager ? row.file_manager.name || `#${row.file_manager.id}` : `#${row.file_manager ?? '—'}` },
+    { key: 'upload_status', label: 'Upload', sortable: true, render: (row) => <Badge tone={row.upload_status === 'completed' ? 'success' : row.upload_status === 'failed' ? 'danger' : 'warning'}>{row.upload_status}</Badge> },
+    { key: 'is_public', label: 'Access', sortable: true, render: (row) => <Badge tone={row.is_public ? 'warning' : 'muted'}>{row.is_public ? 'Public' : 'Private'}</Badge> },
+    { key: 'user', label: 'Uploader', render: (row) => typeof row.user === 'object' && row.user ? row.user.display_name || row.user.name || `#${row.user.id}` : `#${row.user ?? '—'}` },
+    { key: 'created', label: 'Created', sortable: true, render: (row) => fmt.datetime(row.created) },
+];
+const FILTERS: FilterDef[] = [
+    { key: 'upload_status', label: 'Upload status', type: 'select', options: ['pending', 'uploading', 'completed', 'failed', 'expired'].map((value) => ({ value, label: value })) },
+    { key: 'is_public', label: 'Public', type: 'boolean' },
+    { key: 'category', label: 'Category', type: 'select', options: ['image', 'video', 'audio', 'document', 'spreadsheet', 'presentation', 'archive', 'text'].map((value) => ({ value, label: value })) },
+    { key: 'created', label: 'Created', type: 'daterange' },
+];
+
+function MoveGroupDialog({ rows, close }: { rows: FileRow[]; close: (value: number | null) => void }) {
+    const [group, setGroup] = useState<number | null>(null);
+    return <div className="modal-pad"><h2 className="modal-title">Move {rows.length} selected file{rows.length === 1 ? '' : 's'}</h2><p className="modal-message">Choose the explicit target group. Cancelling sends no request.</p><CollectionSelect<RelationRow> endpoint="/api/group" value={group} onChange={(id) => setGroup(id == null ? null : Number(id))} label="Target group" required placeholder="Search authorized groups" /><div className="modal-actions"><button className="btn" onClick={() => close(null)}>Cancel</button><button className="btn btn-primary" disabled={group == null} onClick={() => close(group)}>Move files</button></div></div>;
+}
+
+export function showFileView(id: number): void { void modal.detail((close) => <FileView id={id} onClose={() => close(null)} />); }
+
+export function FilesPage() {
+    const queryClient = useQueryClient();
+    const canManage = useCan(STORAGE_MANAGE_PERMS).can;
+    const canChooseGroup = useCan(GROUP_DIRECTORY_PERMS).can;
+    const remove = FileModel.useDelete();
+    const saveAccess = (row: FileRow, value: boolean) => saveFileAndReconcileGroup(queryClient, row.id, { is_public: value });
+    const batches: BatchAction<FileRow>[] = [
+        { key: 'public', label: 'Make public', eligible: (row) => !row.is_public, confirm: 'Make the selected files public?', run: (row) => saveAccess(row, true) },
+        { key: 'private', label: 'Make private', eligible: (row) => row.is_public, run: (row) => saveAccess(row, false) },
+        ...(canChooseGroup ? [{ key: 'move', label: 'Move to group', confirm: false as const, prepare: (rows: FileRow[]) => modal.open<number>((close) => <MoveGroupDialog rows={rows} close={(value) => close(value as number)} />), run: (row: FileRow, prepared: unknown) => saveFileAndReconcileGroup(queryClient, row.id, { group: Number(prepared) }, Number(prepared)) }] : []),
+        { key: 'download', label: 'Download selected', confirm: false, run: async (row) => { if (!openCapabilityUrl(row.url ?? '', true)) throw new Error(`${row.filename} has no safe download URL`); } },
+        { key: 'delete', label: 'Delete', danger: true, confirm: 'Delete the selected files and their backend objects? This cannot be undone.', run: (row) => remove.mutateAsync({ id: row.id }) },
+    ];
+    const table = (openUpload?: () => void) => <ModelTable model={FileModel} eyebrow="Infrastructure · Storage" title="Files" columns={COLUMNS} filters={FILTERS} presets={[{ key: 'all', label: 'All', params: {} }, { key: 'ready', label: 'Ready', params: { upload_status: 'completed' } }, { key: 'failed', label: 'Failed', params: { upload_status: 'failed' } }, { key: 'public', label: 'Public', params: { is_public: 'true' } }]} defaultSort="-created" searchable searchPlaceholder="Search filename or content type" selectable={canManage} batchActions={canManage ? batches : []} columnChooser persistState persistKey="admin:storage:files" exportFormats={['csv', 'json']} exporter={exportFiles} onAdd={openUpload} addLabel="Add File" onRowClick={(row) => showFileView(row.id)} />;
+    // Do not mount picker/drop/manager queries for view-only operators.
+    return canManage
+        ? <FileUploadSurface canManage canChooseGroup={canChooseGroup}>{(openUpload) => table(openUpload)}</FileUploadSurface>
+        : table();
+}

package/src/admin/storage/file-renditions.ts

@@ -0,0 +1,99 @@
+import type { FileRenditionRow, FileRow } from './models';
+
+export const RENDITION_POLL_DELAY_MS = 5_000;
+export const RENDITION_POLL_MAX_ATTEMPTS = 12;
+export const MAX_RENDITION_ROLES = 20;
+
+export function normalizeRenditions(
+    value: Record<string, FileRenditionRow> | null | undefined,
+): FileRenditionRow[] {
+    return Object.entries(value ?? {}).map(([role, row]) => ({ ...row, role: row.role || role }))
+        .sort((a, b) => a.role.localeCompare(b.role));
+}
+
+export function renditionSignature(row: FileRenditionRow | null | undefined): string | null {
+    if (!row) return null;
+    return JSON.stringify([
+        row.role, row.id, row.upload_status, row.modified,
+        row.width ?? null, row.height ?? null, row.file_size ?? null,
+    ]);
+}
+
+export function renditionMapSignature(file: Pick<FileRow, 'renditions'>): string {
+    return normalizeRenditions(file.renditions)
+        .map((row) => renditionSignature(row))
+        .join('|');
+}
+
+/** Signature only the roles queued by one regeneration generation can satisfy. */
+export function renditionTargetSignature(
+    file: Pick<FileRow, 'renditions'>,
+    targetRoles: readonly string[] | null,
+): string {
+    if (targetRoles === null) return renditionMapSignature(file);
+    const byRole = new Map(normalizeRenditions(file.renditions).map((row) => [row.role, row]));
+    return normalizeRenditionRoles(targetRoles)
+        .map((role) => `${role}:${renditionSignature(byRole.get(role)) ?? 'missing'}`)
+        .join('|');
+}
+
+export function normalizeRenditionRoles(roles: readonly string[]): string[] {
+    return [...new Set(roles.map((role) => role.trim()).filter(Boolean))].slice(0, MAX_RENDITION_ROLES);
+}
+
+export type RenditionPollStop = 'changed' | 'failed' | 'expired' | 'file-changed' | 'closed' | 'timeout';
+
+export interface RenditionPollDecision {
+    done: boolean;
+    reason: RenditionPollStop | null;
+}
+
+export function decideRenditionPoll(args: {
+    expectedFileId: number;
+    currentFileId: number | null;
+    open: boolean;
+    attempt: number;
+    beforeSignature: string;
+    targetRoles: readonly string[] | null;
+    file: Pick<FileRow, 'upload_status' | 'renditions'> | null;
+}): RenditionPollDecision {
+    if (!args.open) return { done: true, reason: 'closed' };
+    if (args.currentFileId !== args.expectedFileId) return { done: true, reason: 'file-changed' };
+    if (args.file?.upload_status === 'failed') return { done: true, reason: 'failed' };
+    if (args.file?.upload_status === 'expired') return { done: true, reason: 'expired' };
+    if (args.file && renditionTargetSignature(args.file, args.targetRoles) !== args.beforeSignature) {
+        return { done: true, reason: 'changed' };
+    }
+    if (args.attempt >= RENDITION_POLL_MAX_ATTEMPTS) return { done: true, reason: 'timeout' };
+    return { done: false, reason: null };
+}
+
+/** Recursive, non-overlapping convergence polling. */
+export async function pollRenditionConvergence(args: {
+    fileId: number;
+    beforeSignature: string;
+    targetRoles: readonly string[] | null;
+    isCurrent: () => boolean;
+    fetch: () => Promise<FileRow>;
+    wait?: (ms: number) => Promise<void>;
+    onAttempt?: (attempt: number, file: FileRow) => void;
+}): Promise<RenditionPollStop> {
+    const wait = args.wait ?? ((ms) => new Promise<void>((resolve) => window.setTimeout(resolve, ms)));
+    for (let attempt = 1; attempt <= RENDITION_POLL_MAX_ATTEMPTS; attempt += 1) {
+        await wait(RENDITION_POLL_DELAY_MS);
+        if (!args.isCurrent()) return 'closed';
+        const file = await args.fetch();
+        args.onAttempt?.(attempt, file);
+        const decision = decideRenditionPoll({
+            expectedFileId: args.fileId,
+            currentFileId: file.id,
+            open: args.isCurrent(),
+            attempt,
+            beforeSignature: args.beforeSignature,
+            targetRoles: args.targetRoles,
+            file,
+        });
+        if (decision.done) return decision.reason!;
+    }
+    return 'timeout';
+}

package/src/admin/storage/index.ts

@@ -0,0 +1,31 @@
+import type { AdminSection } from '../index';
+import { BackendsPage } from './BackendsPage';
+import { BucketsPage } from './BucketsPage';
+import { FilesPage } from './FilesPage';
+import { BUCKET_MANAGE_PERMS, STORAGE_VIEW_PERMS } from './models';
+
+export * from './models';
+export * from './file-renditions';
+export * from './BucketsPage';
+export * from './BucketDetail';
+export * from './BackendsPage';
+export * from './FileManagerDetail';
+export * from './FilesPage';
+export * from './FileUploadSurface';
+export * from './FileView';
+export * from './FilePreview';
+export * from './storage-dialogs';
+
+export const STORAGE_ADMIN_SECTION: AdminSection = {
+    id: 'storage',
+    basePath: 'storage',
+    title: 'Storage',
+    icon: 'bi-hdd-stack',
+    navigationGroup: 'infrastructure',
+    permissions: ['sys.view_fileman', 'sys.manage_files', 'sys.manage_aws', 'sys.files'],
+    routes: [
+        { path: 'buckets', label: 'Buckets', component: BucketsPage, permissions: BUCKET_MANAGE_PERMS },
+        { path: 'backends', label: 'Backends', component: BackendsPage, permissions: STORAGE_VIEW_PERMS },
+        { path: 'files', label: 'Files', component: FilesPage, permissions: STORAGE_VIEW_PERMS },
+    ],
+};