@hachej/boring-ui-kit 0.1.111 → 0.2.1

package/dist/file-tree-view.js

@@ -0,0 +1,256 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as Collapsible from '@radix-ui/react-collapsible';
+import { ChevronRight, File, Folder } from 'lucide-react';
+import { SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarMenuSub } from './file-tree-shadcn.js';
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { createFileTreeController } from './file-tree.js';
+/** Every word of the tree, so a host can translate it. Functions receive what they name. */
+export const defaultFileTreeLabels = {
+    region: 'Workspace files',
+    tree: 'Files',
+    search: 'Search files',
+    searchPlaceholder: 'Search files…',
+    refresh: 'Refresh',
+    upload: 'Upload',
+    uploadFiles: 'Upload files',
+    uploads: 'Uploads',
+    loading: 'Loading files…',
+    retry: 'Retry',
+    noMatches: 'No matching files.',
+    empty: 'No files here.',
+    loadMore: 'Load more',
+    history: 'History',
+    historyOf: (path) => `History of ${path}`,
+    closeHistory: 'Close history',
+    loadingHistory: 'Loading history…',
+    noHistory: 'No retained versions.',
+    earlierVersion: 'Earlier version',
+    historyUnavailable: 'History unavailable',
+    revisionUnavailable: 'This revision is unavailable',
+    readOnlyRevision: (bytes) => `Read-only revision · ${bytes} bytes`,
+    binaryFile: (mediaType) => `Binary file (${mediaType})`,
+    uploading: 'Uploading…',
+    saved: 'Saved',
+    unconfirmed: 'Unconfirmed',
+    checkUpload: 'Check upload status',
+    uploadStatusUnavailable: 'Upload status unavailable',
+    uploadFailed: (name) => `${name}: upload failed`,
+};
+/** The tree's words in French (`locale="fr"`). */
+export const frenchFileTreeLabels = {
+    region: 'Fichiers de l’espace',
+    tree: 'Fichiers',
+    search: 'Rechercher un fichier',
+    searchPlaceholder: 'Rechercher un fichier…',
+    refresh: 'Actualiser',
+    upload: 'Importer',
+    uploadFiles: 'Importer des fichiers',
+    uploads: 'Imports',
+    loading: 'Chargement des fichiers…',
+    retry: 'Réessayer',
+    noMatches: 'Aucun fichier ne correspond.',
+    empty: 'Aucun fichier ici.',
+    loadMore: 'Afficher plus',
+    history: 'Historique',
+    historyOf: path => `Historique de ${path}`,
+    closeHistory: 'Fermer l’historique',
+    loadingHistory: 'Chargement de l’historique…',
+    noHistory: 'Aucune version conservée.',
+    earlierVersion: 'Version antérieure',
+    historyUnavailable: 'Historique indisponible',
+    revisionUnavailable: 'Cette version n’est pas disponible',
+    readOnlyRevision: bytes => `Version en lecture seule · ${bytes} octets`,
+    binaryFile: mediaType => `Fichier binaire (${mediaType})`,
+    uploading: 'Import en cours…',
+    saved: 'Enregistré',
+    unconfirmed: 'Non confirmé',
+    checkUpload: 'Vérifier l’import',
+    uploadStatusUnavailable: 'État de l’import indisponible',
+    uploadFailed: name => `${name} : échec de l’import`,
+};
+const LOCALES = { en: defaultFileTreeLabels, fr: frenchFileTreeLabels };
+/** One borrowed binding powers browsing, search, upload and history. Historical previews never replace an editor's draft. */
+export function FileTree(props) {
+    return _jsx(BoundFileTree, { ...props }, JSON.stringify([props.revisionProvider.workspace, props.revisionProvider.identity]));
+}
+function BoundFileTree(props) {
+    const [owned, setOwned] = useState();
+    useEffect(() => {
+        const controller = createFileTreeController({ revisionProvider: props.revisionProvider });
+        setOwned({ provider: props.revisionProvider, controller });
+        void controller.refresh();
+        return () => controller.dispose();
+    }, [props.revisionProvider]);
+    return owned?.provider === props.revisionProvider ? _jsx(FileTreeView, { ...props, controller: owned.controller }) : _jsx("p", { role: "status", children: props.labels?.loading ?? LOCALES[props.locale ?? 'en'].loading });
+}
+/** Renders a borrowed controller, for a workspace whose chat and tree share upload state. */
+export function FileTreeView({ controller, onOpen, selectedPath, className, uploadDirectory = 'uploads', locale = 'en', labels: given, upload = true, history = true, refreshKey, historyKey }) {
+    const labels = { ...LOCALES[locale], ...given };
+    const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const shownKey = useRef(refreshKey);
+    useEffect(() => {
+        if (Object.is(shownKey.current, refreshKey))
+            return;
+        shownKey.current = refreshKey;
+        const { query, expanded } = controller.getSnapshot();
+        if (query)
+            void controller.search(query);
+        else
+            for (const directory of ['', ...expanded])
+                void controller.refresh(directory);
+    }, [controller, refreshKey]);
+    const tree = useRef(null);
+    const [focused, setFocused] = useState('');
+    const [uploadError, setUploadError] = useState('');
+    const [historyPath, setHistoryPath] = useState();
+    const rows = [];
+    function flatten(directory, level) {
+        for (const entry of state.directories.get(directory)?.entries ?? []) {
+            rows.push({ entry, level });
+            if (entry.kind === 'directory' && state.expanded.has(entry.path))
+                flatten(entry.path, level + 1);
+        }
+    }
+    if (state.query)
+        for (const entry of state.search.entries)
+            rows.push({ entry, level: 1 });
+    else
+        flatten('', 1);
+    const focusPath = rows.some(row => row.entry.path === focused) ? focused : rows[0]?.entry.path;
+    const focus = (path) => {
+        if (path === undefined)
+            return;
+        setFocused(path);
+        const nodes = tree.current?.querySelectorAll('[role=treeitem]');
+        for (const node of Array.from(nodes ?? []))
+            if (node.dataset.path === path)
+                node.focus();
+    };
+    const keyboard = (event, entry) => {
+        const index = rows.findIndex(row => row.entry.path === entry.path);
+        const expanded = state.expanded.has(entry.path);
+        switch (event.key) {
+            case 'ArrowDown':
+                focus(rows[Math.min(rows.length - 1, index + 1)]?.entry.path);
+                break;
+            case 'ArrowUp':
+                focus(rows[Math.max(0, index - 1)]?.entry.path);
+                break;
+            case 'Home':
+                focus(rows[0]?.entry.path);
+                break;
+            case 'End':
+                focus(rows.at(-1)?.entry.path);
+                break;
+            case 'ArrowRight':
+                if (entry.kind === 'directory' && !state.query) {
+                    if (!expanded)
+                        void controller.toggle(entry.path);
+                    else {
+                        const next = rows[index + 1];
+                        if (next && next.level > (rows[index]?.level ?? 0))
+                            focus(next.entry.path);
+                    }
+                }
+                break;
+            case 'ArrowLeft':
+                if (entry.kind === 'directory' && expanded && !state.query)
+                    void controller.toggle(entry.path);
+                else
+                    focus(entry.path.includes('/') ? entry.path.slice(0, entry.path.lastIndexOf('/')) : undefined);
+                break;
+            case 'Enter':
+            case ' ':
+                if (entry.kind === 'directory')
+                    void controller.toggle(entry.path);
+                else
+                    onOpen?.(entry.path);
+                break;
+            default: return;
+        }
+        event.preventDefault();
+    };
+    const listingStatus = (listing, directory, search = false) => {
+        if (!listing || listing.kind === 'loading')
+            return _jsx("li", { role: "none", children: _jsx("span", { role: "status", children: labels.loading }) });
+        if (listing.kind === 'error')
+            return _jsxs("li", { role: "none", children: [_jsx("span", { role: "alert", children: listing.reason }), " ", _jsx("button", { type: "button", onClick: () => { void (search ? controller.search(state.query) : controller.refresh(directory)); }, children: labels.retry })] });
+        return _jsxs(_Fragment, { children: [listing.entries.length === 0 && _jsx("li", { role: "none", children: _jsx("span", { children: search ? labels.noMatches : labels.empty }) }), listing.cursor !== undefined && _jsx("li", { role: "none", children: _jsx("button", { type: "button", onClick: () => { void (search ? controller.moreSearch() : controller.more(directory)); }, children: labels.loadMore }) })] });
+    };
+    const renderEntries = (directory, level) => _jsxs(_Fragment, { children: [(state.directories.get(directory)?.entries ?? []).map(entry => renderEntry(entry, level)), listingStatus(state.directories.get(directory), directory)] });
+    const renderEntry = (entry, level) => {
+        const folder = entry.kind === 'directory';
+        // A search result shows its name, with its folder beside it in muted text.
+        const name = entry.path.split('/').at(-1);
+        const parent = state.query && entry.path.includes('/') ? entry.path.slice(0, entry.path.lastIndexOf('/')) : '';
+        const button = _jsxs(SidebarMenuButton, { tabIndex: -1, title: entry.path, isActive: selectedPath === entry.path, className: "min-w-0 flex-1 data-[active=true]:bg-transparent", onClick: () => { focus(entry.path); if (!folder)
+                onOpen?.(entry.path); }, children: [folder ? _jsxs(_Fragment, { children: [_jsx(ChevronRight, { className: "transition-transform", "aria-hidden": "true" }), _jsx(Folder, { "aria-hidden": "true" })] }) : _jsx(File, { "aria-hidden": "true" }), _jsx("span", { className: "min-w-0 truncate", children: name }), parent && _jsx("span", { className: "min-w-0 shrink truncate text-xs text-muted-foreground", children: parent })] });
+        const item = _jsxs(SidebarMenuItem, { role: "treeitem", "data-path": entry.path, "aria-level": level, "aria-selected": selectedPath === entry.path, "aria-expanded": folder ? state.expanded.has(entry.path) : undefined, tabIndex: focusPath === entry.path ? 0 : -1, onFocus: event => { if (event.target === event.currentTarget)
+                setFocused(entry.path); }, onKeyDown: event => { if (event.target === event.currentTarget)
+                keyboard(event, entry); }, className: "group/collapsible rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ring [&[data-state=open]>div>button>svg:first-child]:rotate-90", children: [_jsxs("div", { className: "flex items-center gap-1", children: [folder ? _jsx(Collapsible.Trigger, { asChild: true, children: button }) : button, !folder && history && _jsx("button", { type: "button", "aria-label": labels.historyOf(entry.path), className: "px-2 py-1 text-xs", onClick: () => setHistoryPath(entry.path), children: labels.history })] }), folder && !state.query && _jsx(Collapsible.Content, { asChild: true, children: _jsx(SidebarMenuSub, { role: "group", children: renderEntries(entry.path, level + 1) }) })] }, entry.path);
+        return folder ? _jsx(Collapsible.Root, { asChild: true, open: state.expanded.has(entry.path), onOpenChange: () => { void controller.toggle(entry.path); }, children: item }, entry.path) : item;
+    };
+    return _jsxs("section", { "data-boring": "file-tree", className: className, "aria-label": labels.region, children: [_jsxs("div", { className: "flex flex-wrap items-center gap-2 p-2", children: [_jsx("input", { type: "search", "aria-label": labels.search, placeholder: labels.searchPlaceholder, className: "min-w-0 flex-1 rounded border border-input bg-background px-2 py-1 text-sm", value: state.query, onChange: event => { void controller.search(event.currentTarget.value); } }), _jsx("button", { type: "button", onClick: () => { void (state.query ? controller.search(state.query) : controller.refresh()); }, children: labels.refresh }), upload && _jsxs("label", { className: "cursor-pointer text-sm", children: [labels.upload, _jsx("input", { "aria-label": labels.uploadFiles, type: "file", multiple: true, className: "sr-only", onChange: event => {
+                                    const files = Array.from(event.currentTarget.files ?? []);
+                                    event.currentTarget.value = '';
+                                    setUploadError('');
+                                    void (async () => {
+                                        // One refused or unreadable file does not stop the others; every refusal is reported.
+                                        const errors = [];
+                                        for (const file of files) {
+                                            const path = uploadDirectory ? `${uploadDirectory}/${file.name}` : file.name;
+                                            try {
+                                                await controller.upload({ path, bytes: new Uint8Array(await file.arrayBuffer()), mediaType: file.type || 'application/octet-stream' });
+                                            }
+                                            catch (error) {
+                                                errors.push(error instanceof Error ? error.message : labels.uploadFailed(file.name));
+                                            }
+                                        }
+                                        if (errors.length)
+                                            setUploadError(errors.join(' '));
+                                    })();
+                                } })] })] }), uploadError && _jsx("p", { role: "alert", children: uploadError }), _jsx(SidebarMenu, { ref: tree, role: "tree", "aria-label": labels.tree, className: "m-0 list-none p-2", children: state.query ? _jsxs(_Fragment, { children: [state.search.entries.map(entry => renderEntry(entry, 1)), listingStatus(state.search, '', true)] }) : renderEntries('', 1) }), state.uploads.length > 0 && _jsx("ul", { "aria-label": labels.uploads, className: "list-none p-2 text-sm", children: state.uploads.map(upload => _jsxs("li", { "data-operation": upload.operationId, children: [_jsxs("span", { children: [upload.path, ": ", upload.state.kind === 'pending' ? labels.uploading : upload.state.result.kind === 'committed' ? labels.saved : upload.state.result.kind === 'partial' ? labels.unconfirmed : upload.state.result.reason] }), upload.state.kind === 'settled' && upload.state.result.kind === 'unknown' && _jsx("button", { type: "button", onClick: () => { void controller.reconcile(upload.operationId).catch(error => setUploadError(error instanceof Error ? error.message : labels.uploadStatusUnavailable)); }, children: labels.checkUpload })] }, upload.operationId)) }), history && historyPath !== undefined && _jsx(FileHistory, { controller: controller, path: historyPath, labels: labels, reload: historyKey, onClose: () => setHistoryPath(undefined) }, historyPath)] });
+}
+function FileHistory({ controller, path, labels, reload, onClose }) {
+    const [versions, setVersions] = useState();
+    const [failure, setFailure] = useState('');
+    const [selected, setSelected] = useState();
+    const [preview, setPreview] = useState();
+    useEffect(() => {
+        const abort = new AbortController();
+        void controller.history(path, abort.signal).then(value => { if (!abort.signal.aborted)
+            setVersions(value); }, error => { if (!abort.signal.aborted)
+            setFailure(error instanceof Error ? error.message : labels.historyUnavailable); });
+        return () => abort.abort();
+    }, [controller, path, reload]);
+    useEffect(() => {
+        if (selected === undefined)
+            return;
+        const abort = new AbortController();
+        setPreview(undefined);
+        setFailure('');
+        void controller.revisionProvider.read({ target: controller.revisionProvider.locate(path), revision: { kind: 'exact', value: selected } }, abort.signal).then(result => {
+            if (abort.signal.aborted)
+                return;
+            const target = controller.revisionProvider.locate(path);
+            if (result.kind === 'available' && result.snapshot.ref.revision === selected
+                && result.snapshot.ref.resource.providerId === target.resource.providerId && result.snapshot.ref.resource.path === target.resource.path
+                && result.snapshot.ref.view.kind === target.view.kind && (target.view.kind !== 'working'
+                || (result.snapshot.ref.view.kind === 'working' && result.snapshot.ref.view.viewId === target.view.viewId)))
+                setPreview(result.snapshot);
+            else
+                setFailure(result.kind === 'denied' || result.kind === 'unavailable' ? result.reason : labels.revisionUnavailable);
+        }, () => { if (!abort.signal.aborted)
+            setFailure(labels.revisionUnavailable); });
+        return () => abort.abort();
+    }, [controller, path, selected]);
+    let text;
+    if (preview) {
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(preview.bytes);
+        }
+        catch { /* Binary history remains a byte-qualified read-only preview. */ }
+    }
+    return _jsxs("section", { "aria-label": labels.historyOf(path), className: "border-t border-border p-2 text-sm", children: [_jsxs("div", { className: "flex items-center justify-between gap-2", children: [_jsx("h3", { className: "font-medium", children: labels.historyOf(path) }), _jsx("button", { type: "button", onClick: onClose, children: labels.closeHistory })] }), failure && _jsx("p", { role: "alert", children: failure }), !versions && !failure && _jsx("p", { role: "status", children: labels.loadingHistory }), versions?.length === 0 && _jsx("p", { children: labels.noHistory }), _jsx("ul", { className: "m-0 list-none p-0", children: versions?.map(version => _jsx("li", { children: _jsxs("button", { type: "button", "aria-pressed": selected === version.revision, onClick: () => setSelected(version.revision), children: [version.savedAt ? new Date(version.savedAt).toLocaleString() : labels.earlierVersion, " \u00B7 ", version.revision.slice(0, 8)] }) }, version.revision)) }), preview && _jsxs("div", { "data-testid": "file-history-preview", "data-revision": preview.ref.revision, children: [_jsx("p", { children: labels.readOnlyRevision(preview.bytes.byteLength) }), text === undefined ? _jsx("p", { children: labels.binaryFile(preview.mediaType) }) : _jsx("pre", { className: "max-h-80 overflow-auto whitespace-pre-wrap", children: text })] })] });
+}

package/dist/file-tree.d.ts

@@ -0,0 +1,57 @@
+import type { PublicationResult, ResourceRef } from '@hachej/boring-files';
+import type { FileEntry, RevisionProvider, SavedRevision } from '@hachej/boring-files/revision';
+export type FileListing = {
+    readonly kind: 'loading';
+    readonly entries: readonly FileEntry[];
+} | {
+    readonly kind: 'ready';
+    readonly entries: readonly FileEntry[];
+    readonly cursor?: string;
+} | {
+    readonly kind: 'error';
+    readonly entries: readonly FileEntry[];
+    readonly reason: string;
+};
+export interface FileUpload {
+    readonly operationId: string;
+    readonly path: string;
+    readonly state: {
+        readonly kind: 'pending';
+    } | {
+        readonly kind: 'settled';
+        readonly result: PublicationResult;
+    };
+}
+export interface FileTreeState {
+    readonly lifecycle: 'active' | 'disposed';
+    readonly directories: ReadonlyMap<string, FileListing>;
+    readonly expanded: ReadonlySet<string>;
+    readonly query: string;
+    readonly search: FileListing;
+    readonly uploads: readonly FileUpload[];
+}
+export interface FileTreeController {
+    readonly revisionProvider: RevisionProvider;
+    readonly getSnapshot: () => FileTreeState;
+    readonly subscribe: (listener: () => void) => () => void;
+    readonly refresh: (directory?: string) => Promise<void>;
+    readonly more: (directory?: string) => Promise<void>;
+    readonly toggle: (directory: string) => Promise<void>;
+    readonly search: (query: string) => Promise<void>;
+    readonly moreSearch: () => Promise<void>;
+    readonly upload: (input: {
+        readonly path: string;
+        readonly bytes: Uint8Array;
+        readonly mediaType?: string;
+        readonly replace?: ResourceRef;
+        readonly signal?: AbortSignal;
+    }) => Promise<FileUpload>;
+    readonly reconcile: (operationId: string) => Promise<FileUpload>;
+    readonly history: (path: string, signal?: AbortSignal) => Promise<readonly SavedRevision[]>;
+    readonly dispose: () => void;
+}
+/** Browsing state belongs to one borrowed binding. Disposal fences late results; it never closes the workspace. */
+export declare function createFileTreeController({ revisionProvider }: {
+    readonly revisionProvider: RevisionProvider;
+}): FileTreeController;
+//# sourceMappingURL=file-tree.d.ts.map

package/dist/file-tree.js

@@ -0,0 +1,204 @@
+import { parsePublicationResult, PublicationNotDispatchedError, publicationDigest, publicationSnapshot } from '@hachej/boring-files/publication';
+import { randomUUID } from '@hachej/boring-files/platform';
+const message = (error) => error instanceof Error ? error.message : 'Files could not be loaded';
+const empty = { kind: 'ready', entries: [] };
+const parentOf = (path) => path.slice(0, Math.max(0, path.lastIndexOf('/')));
+const sameBytes = (left, right) => left.length === right.length && left.every((byte, index) => byte === right[index]);
+const sameTarget = (left, right) => left.resource.providerId === right.resource.providerId && left.resource.path === right.resource.path
+    && left.view.kind === right.view.kind && (left.view.kind !== 'working' || (right.view.kind === 'working' && left.view.viewId === right.view.viewId));
+/** Browsing state belongs to one borrowed binding. Disposal fences late results; it never closes the workspace. */
+export function createFileTreeController({ revisionProvider }) {
+    let state = { lifecycle: 'active', directories: new Map(), expanded: new Set(), query: '', search: empty, uploads: [] };
+    const listeners = new Set();
+    const lifetime = new AbortController();
+    const loads = new Map();
+    const attempts = new Map();
+    const update = (next) => { if (state.lifecycle === 'active') {
+        state = next;
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch { /* A subscriber cannot interrupt publication or other subscribers. */ }
+        }
+    } };
+    const active = () => { if (state.lifecycle !== 'active')
+        throw new Error('The file tree is disposed'); };
+    const directory = (path, listing) => update({ ...state, directories: new Map(state.directories).set(path, listing) });
+    async function load(path, append, search = false) {
+        active();
+        const key = search ? 'search' : `directory:${path}`;
+        const previous = search ? state.search : state.directories.get(path) ?? empty;
+        const cursor = append && previous.kind === 'ready' ? previous.cursor : undefined;
+        if (append && cursor === undefined)
+            return;
+        loads.get(key)?.abort();
+        const abort = new AbortController();
+        loads.set(key, abort);
+        const signal = AbortSignal.any([abort.signal, lifetime.signal]);
+        const query = state.query;
+        const set = (value) => search ? update({ ...state, search: value }) : directory(path, value);
+        set({ kind: 'loading', entries: previous.entries });
+        try {
+            const page = await (search ? revisionProvider.search({ query, ...(cursor ? { cursor } : {}) }, signal)
+                : revisionProvider.list({ directory: path, ...(cursor ? { cursor } : {}) }, signal));
+            if (signal.aborted || loads.get(key) !== abort)
+                return;
+            const entries = append ? [...new Map([...previous.entries, ...page.entries].map(entry => [entry.path, entry])).values()] : [...page.entries];
+            set({ kind: 'ready', entries, ...(page.cursor === undefined ? {} : { cursor: page.cursor }) });
+        }
+        catch (error) {
+            if (!signal.aborted && loads.get(key) === abort)
+                set({ kind: 'error', entries: previous.entries, reason: message(error) });
+        }
+        finally {
+            if (loads.get(key) === abort)
+                loads.delete(key);
+        }
+    }
+    const refresh = (path = '') => load(path, false);
+    function uploadState(operationId, result) {
+        const attempt = attempts.get(operationId);
+        if (!attempt)
+            throw new Error('Unknown upload operation');
+        const current = { operationId, path: attempt.current.path, state: { kind: 'settled', result } };
+        attempt.current = current;
+        update({ ...state, uploads: state.uploads.map(item => item.operationId === operationId ? current : item) });
+        if (result.kind === 'committed' && state.lifecycle === 'active') {
+            let path = parentOf(current.path);
+            const parents = new Set(['', path]);
+            while (path.includes('/')) {
+                path = parentOf(path);
+                parents.add(path);
+            }
+            update({ ...state, expanded: new Set([...state.expanded, ...[...parents].filter(Boolean)]) });
+            for (const parent of parents)
+                void refresh(parent);
+        }
+        return current;
+    }
+    const unknown = (operationId, reason) => ({ kind: 'unknown', operationId, reason });
+    function checked(operationId, input) {
+        const attempt = attempts.get(operationId);
+        if (!attempt)
+            throw new Error('Unknown upload operation');
+        let result;
+        try {
+            result = parsePublicationResult(input);
+        }
+        catch {
+            return unknown(operationId, 'The upload acknowledgement was invalid; check its status');
+        }
+        if (result.kind === 'partial' || (result.kind === 'unknown' && result.operationId !== operationId))
+            return unknown(operationId, 'The upload acknowledgement did not match its operation');
+        if (result.kind !== 'committed')
+            return result;
+        const receipt = result.receipt, change = receipt.changes[0], expected = attempt.request.changes[0], identity = revisionProvider.identity;
+        if (receipt.operationId !== operationId || receipt.argumentDigest !== attempt.digest || !receipt.evidenceRef
+            || receipt.principalId !== identity.principalId || receipt.scopeId !== identity.scopeId || receipt.initiatorId !== identity.initiatorId
+            || receipt.changes.length !== 1 || !change?.after || !sameTarget(change.after, expected.target)
+            || (expected.kind === 'create' ? change.kind !== 'create' || change.before !== null
+                : expected.kind !== 'replace' || change.kind !== 'replace' || !change.before || !sameTarget(change.before, expected.target) || change.before.revision !== expected.target.revision)) {
+            return unknown(operationId, 'The upload receipt did not match its request');
+        }
+        return result;
+    }
+    const controller = {
+        revisionProvider, getSnapshot: () => state,
+        subscribe: listener => { if (state.lifecycle === 'disposed')
+            return () => { }; listeners.add(listener); return () => { listeners.delete(listener); }; },
+        refresh, more: (path = '') => load(path, true),
+        toggle: async (path) => {
+            active();
+            const expanded = new Set(state.expanded);
+            if (expanded.has(path))
+                expanded.delete(path);
+            else
+                expanded.add(path);
+            update({ ...state, expanded });
+            if (expanded.has(path) && !state.directories.has(path))
+                await refresh(path);
+        },
+        search: async (query) => {
+            active();
+            loads.get('search')?.abort();
+            update({ ...state, query, search: empty });
+            if (query)
+                await load('', false, true);
+        },
+        moreSearch: () => load('', true, true),
+        upload: async (input) => {
+            active();
+            // An unresolved upload of the same path answers a new one, so nothing is published twice: an unconfirmed one must be checked
+            // first, and a pending one answers a repeat of its bytes (a double click or drop). Different bytes while one is still pending
+            // are refused outright: answering with the earlier upload would report them as saved when they were not.
+            const bytes = input.bytes.slice();
+            const unresolved = () => {
+                const attempt = [...attempts.values()].find(item => item.current.path === input.path
+                    && (item.current.state.kind === 'pending' || item.current.state.result.kind === 'unknown'));
+                if (attempt?.current.state.kind === 'pending' && !sameBytes(attempt.bytes, bytes))
+                    throw new Error(`${input.path} is already being uploaded; wait for it to finish`);
+                return attempt?.current;
+            };
+            const earlier = unresolved();
+            if (earlier)
+                return earlier;
+            const operationId = randomUUID();
+            const target = revisionProvider.locate(input.path);
+            if (input.replace && !sameTarget(input.replace, target))
+                throw new TypeError('The replacement revision belongs to another file');
+            const request = publicationSnapshot({ operationId, atomicity: 'all-or-nothing', changes: [input.replace
+                        ? { kind: 'replace', target: input.replace, bytes, mediaType: input.mediaType ?? 'application/octet-stream' }
+                        : { kind: 'create', target, expected: { kind: 'absent' }, bytes, mediaType: input.mediaType ?? 'application/octet-stream' }] });
+            const current = { operationId, path: input.path, state: { kind: 'pending' } };
+            const digest = await publicationDigest(request);
+            active();
+            const concurrent = unresolved();
+            if (concurrent)
+                return concurrent;
+            attempts.set(operationId, { request, digest, bytes, current });
+            update({ ...state, uploads: [...state.uploads, current] });
+            const signal = input.signal ? AbortSignal.any([input.signal, lifetime.signal]) : lifetime.signal;
+            if (signal.aborted)
+                return uploadState(operationId, { kind: 'unavailable', reason: 'Upload cancelled before publication' });
+            try {
+                return uploadState(operationId, checked(operationId, await revisionProvider.publish(request, signal)));
+            }
+            catch (error) {
+                return uploadState(operationId, error instanceof PublicationNotDispatchedError && error.operationId === operationId
+                    ? { kind: 'unavailable', reason: 'Upload was not sent' }
+                    : unknown(operationId, 'Upload outcome is unconfirmed; check its status before trying again'));
+            }
+        },
+        reconcile: operationId => {
+            active();
+            const attempt = attempts.get(operationId);
+            if (!attempt)
+                return Promise.reject(new Error('Unknown upload operation'));
+            if (attempt.current.state.kind === 'pending')
+                return Promise.reject(new Error('Upload is still in progress'));
+            if (attempt.current.state.result.kind !== 'unknown')
+                return Promise.resolve(attempt.current);
+            if (attempt.reconciling)
+                return attempt.reconciling;
+            const run = async () => {
+                try {
+                    const result = await revisionProvider.lookup(operationId, lifetime.signal);
+                    return uploadState(operationId, result.kind === 'not-found' ? unknown(operationId, 'No retained receipt. Keep the local file; do not replay this upload blindly.') : checked(operationId, result));
+                }
+                catch {
+                    return uploadState(operationId, unknown(operationId, 'The upload status could not be confirmed'));
+                }
+                finally {
+                    delete attempt.reconciling;
+                }
+            };
+            return attempt.reconciling = run();
+        },
+        history: (path, signal) => { active(); return revisionProvider.history(path, signal ? AbortSignal.any([signal, lifetime.signal]) : lifetime.signal); },
+        dispose: () => { if (state.lifecycle === 'disposed')
+            return; lifetime.abort(); for (const load of loads.values())
+            load.abort(); loads.clear(); state = { ...state, lifecycle: 'disposed' }; listeners.clear(); },
+    };
+    return controller;
+}

package/dist/html-preview.d.ts

@@ -0,0 +1,2 @@
+export declare function passiveHtml(source: string, document: Document): string;
+//# sourceMappingURL=html-preview.d.ts.map

package/dist/html-preview.js

@@ -0,0 +1,47 @@
+const formatting = new Set(['p', 'div', 'span', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'blockquote', 'pre', 'code', 'strong', 'em', 'b', 'i', 'u', 's', 'small', 'sub', 'sup', 'kbd', 'samp', 'var', 'mark', 'ul', 'ol', 'li', 'dl', 'dt', 'dd', 'table', 'caption', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'section', 'article', 'header', 'footer', 'main', 'aside', 'figure', 'figcaption', 'br', 'hr']);
+const htmlNamespace = 'http://www.w3.org/1999/xhtml';
+const prefix = '<!doctype html><html><head><meta http-equiv="Content-Security-Policy" content="default-src \'none\'; base-uri \'none\'; form-action \'none\'"><meta charset="utf-8"><meta name="referrer" content="no-referrer"><meta name="format-detection" content="telephone=no,email=no,address=no"><title>HTML preview</title></head><body>';
+export function passiveHtml(source, document) {
+    if (source.length > 262_144)
+        throw new RangeError('HTML preview source exceeds its limit');
+    const template = document.createElement('template');
+    template.innerHTML = source;
+    let nodes = 0, length = prefix.length;
+    const output = [prefix];
+    function emit(text) {
+        length += text.length;
+        if (length > 1_048_576)
+            throw new RangeError('HTML preview output exceeds its limit');
+        output.push(text);
+    }
+    function visit(node, depth) {
+        if (++nodes > 20_000 || depth > 128)
+            throw new RangeError('HTML preview structure exceeds its limit');
+        if (node.nodeType === 3) {
+            emit((node.textContent ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;'));
+            return;
+        }
+        if (node.nodeType !== 1 || !('namespaceURI' in node) || node.namespaceURI !== htmlNamespace || !('localName' in node) || typeof node.localName !== 'string')
+            return;
+        if (node.localName === 'html' || node.localName === 'head' || node.localName === 'body') {
+            for (let child = node.firstChild; child; child = child.nextSibling)
+                visit(child, depth + 1);
+            return;
+        }
+        const tag = node.localName === 'a' ? 'span' : node.localName;
+        if (!formatting.has(tag))
+            return;
+        emit('<' + tag + '>');
+        if (tag === 'br' || tag === 'hr')
+            return;
+        if (tag === 'pre')
+            emit('\n');
+        for (let child = node.firstChild; child; child = child.nextSibling)
+            visit(child, depth + 1);
+        emit('</' + tag + '>');
+    }
+    for (let child = template.content.firstChild; child; child = child.nextSibling)
+        visit(child, 0);
+    emit('</body></html>');
+    return output.join('');
+}

package/dist/html-viewer.d.ts

@@ -0,0 +1,13 @@
+import type { HtmlController } from './html.js';
+export interface HtmlViewerProps {
+    readonly controller: HtmlController;
+    readonly title?: string;
+    readonly className?: string;
+    /** `false` omits the built-in header and toolbar (mode, Save, Refresh, reconcile, discard) so a host bar such as the viewer frame supplies them. */
+    readonly header?: boolean;
+    /** Controlled mode; without it the viewer keeps its own and starts on the preview. */
+    readonly mode?: 'source' | 'preview';
+    readonly onModeChange?: (mode: 'source' | 'preview') => void;
+}
+export declare function HtmlViewer(props: HtmlViewerProps): import("react").JSX.Element;
+//# sourceMappingURL=html-viewer.d.ts.map