@bendyline/docblocks-react 1.1.1 → 2.0.0

package/dist/DocBlocksShell/DocBlocksShell.js

@@ -1,26 +1,100 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 /**
- * DocBlocksShell — top-level layout component.
+ * DocBlocksShell -- top-level layout component.
  *
  * Composes the left sidebar (WorkspacePicker + FileExplorer) with
  * the center editor area (squisq EditorShell).
  */
-import { useState, useCallback, useEffect, useRef } from 'react';
-import { EditorShell } from '@bendyline/squisq-editor-react';
+import { useState, useCallback, useEffect, useRef, useMemo, lazy, Suspense } from 'react';
 import '@bendyline/squisq-editor-react/styles';
 import { MediaContext } from '@bendyline/squisq-react';
 import { DocumentVersionManager, } from '@bendyline/squisq/versions';
-import { IndexedDBFileSystemProvider, ElectronFileSystemProvider, FileSystemContentContainer, createFileMediaProvider, openNativeFolder, restoreNativeFolder, removeDirectoryHandle, } from '@bendyline/docblocks/filesystem';
+import { createDbkWorkspaceSnapshot, FileSystemContentContainer, createFileMediaProvider, FsError, getFileSystemProviderV2, isQuotaExceededError, parseWorkspacePath, workspacePathContains, } from '@bendyline/docblocks/filesystem';
+import { createFileSystemDocumentTarget, DocumentCommitConflictError, DocumentSessionConflictError, } from '@bendyline/docblocks/document';
 import { isElectronHost, getDocBlocksHost } from '@bendyline/docblocks/host';
-import { ensureDefaultWorkspace, getWorkspace, listWorkspaces, removeWorkspace, saveWorkspace, touchWorkspace, } from '@bendyline/docblocks/workspace';
+import { ensureDefaultWorkspace, getWorkspace, listWorkspaces, reconcileElectronWorkspaceDescriptors, removeWorkspace, saveWorkspace, touchWorkspace, registerTransientWorkspace, getTransientWorkspace, unregisterTransientWorkspace, } from '@bendyline/docblocks/workspace';
 import { AppMenu } from '../AppMenu/AppMenu.js';
-import { FileExplorer } from '../FileExplorer/FileExplorer.js';
+import { pickEmptyDocumentPrompt } from '../editor.js';
+import { FileExplorer, } from '../FileExplorer/FileExplorer.js';
 import { WorkspacePicker } from '../WorkspacePicker/WorkspacePicker.js';
 import { WorkspaceSettingsButton } from '../WorkspacePicker/WorkspaceSettingsButton.js';
+import { SplitViewIcon } from '../icons.js';
 import { WorkspaceSettingsDialog, } from '../WorkspacePicker/WorkspaceSettingsDialog.js';
-import { useAutoSave } from '../hooks/useAutoSave.js';
-import { ExportToolbarControls } from '../Export/ExportToolbarControls.js';
+import { useDocumentSession } from '../hooks/useDocumentSession.js';
+import { ExportToolbarControls, } from '../Export/DeferredExportToolbarControls.js';
+import { GitContext } from '../Git/GitContext.js';
+import { useGit } from '../Git/useGit.js';
+// The editor is only needed after a document and its media container are
+// ready. Workspace chrome stays interactive while this large feature loads.
+const EditorShell = lazy(async () => {
+    const workersReady = globalThis
+        .docBlocksMonacoWorkersReady;
+    // Worker setup is an enhancement; a host that cannot install language
+    // workers must not make the document editor unavailable.
+    await workersReady?.catch(() => undefined);
+    return import('./LazyEditorShell.js');
+});
+// The git dialogs/status bar only ever render under the Electron host, so
+// they load as a split chunk -- the site never pays for them (the entry
+// bundle budget is enforced by scripts/check-bundle-size.ts).
+const GitUI = lazy(() => import('../Git/GitUI.js').then((m) => ({ default: m.GitUI })));
+const GitToolbarControl = lazy(() => import('../Git/GitToolbarControl.js').then((m) => ({ default: m.GitToolbarControl })));
 import { loadVersioningPreference, resolveVersioningEnabled, saveVersioningPreference, } from '../preferences/versioning.js';
+import { DB_CHROME_COLORS, loadAccentColor, loadThemePreference, saveAccentColor, saveThemePreference, } from '../preferences/theme.js';
+import { retainFileSystemProvider } from '../provider-lease.js';
+import { useDocumentTitle } from './document-title.js';
+import { UpdateAvailableNotice } from './UpdateAvailableNotice.js';
+import { WorkspaceAuthorityBarrier } from './workspace-authority-barrier.js';
+let indexedDbFileSystemModule = null;
+let memoryFileSystemModule = null;
+let nativeFileSystemModule = null;
+let electronFileSystemModule = null;
+function loadIndexedDbFileSystem() {
+    indexedDbFileSystemModule ?? (indexedDbFileSystemModule = import('@bendyline/docblocks/filesystem/indexeddb').catch((error) => {
+        indexedDbFileSystemModule = null;
+        throw error;
+    }));
+    return indexedDbFileSystemModule;
+}
+function loadMemoryFileSystem() {
+    memoryFileSystemModule ?? (memoryFileSystemModule = import('@bendyline/docblocks/filesystem/memory').catch((error) => {
+        memoryFileSystemModule = null;
+        throw error;
+    }));
+    return memoryFileSystemModule;
+}
+function loadNativeFileSystem() {
+    nativeFileSystemModule ?? (nativeFileSystemModule = import('@bendyline/docblocks/filesystem/native').catch((error) => {
+        nativeFileSystemModule = null;
+        throw error;
+    }));
+    return nativeFileSystemModule;
+}
+function loadElectronFileSystem() {
+    electronFileSystemModule ?? (electronFileSystemModule = import('@bendyline/docblocks/filesystem/electron').catch((error) => {
+        electronFileSystemModule = null;
+        throw error;
+    }));
+    return electronFileSystemModule;
+}
+async function createIndexedDbFileSystemProvider(id, label) {
+    const { IndexedDBFileSystemProvider } = await loadIndexedDbFileSystem();
+    return new IndexedDBFileSystemProvider(id, label);
+}
+async function createElectronFileSystemProvider(id, label, rootPath) {
+    const { ElectronFileSystemProvider } = await loadElectronFileSystem();
+    return new ElectronFileSystemProvider(id, label, rootPath);
+}
+async function createMemoryFileSystemProvider(id, label) {
+    const { MemoryFileSystemProvider } = await loadMemoryFileSystem();
+    return new MemoryFileSystemProvider(id, label);
+}
+function isMemoryWorkspaceProvider(provider) {
+    const candidate = provider;
+    return (typeof candidate.captureContents === 'function' &&
+        typeof candidate.replaceContents === 'function' &&
+        typeof candidate.treeVersion === 'number');
+}
 function useOsTheme() {
     const [dark, setDark] = useState(() => typeof window !== 'undefined' && window.matchMedia('(prefers-color-scheme: dark)').matches);
     useEffect(() => {
@@ -73,35 +147,34 @@ function loadLastState() {
         return null;
     }
 }
-const THEME_PREF_KEY = 'docblocks:themePreference';
-function loadThemePreference() {
+/** One-time first-run callout shown over the welcome doc's Play view.
+ *  Once the user starts writing, switches views themselves, or dismisses
+ *  it, it never comes back -- on any workspace. */
+const WELCOME_GATEWAY_KEY = 'docblocks:welcomeGatewayDismissed';
+function isWelcomeGatewayDismissed() {
     try {
-        const raw = localStorage.getItem(THEME_PREF_KEY);
-        if (raw === 'light' || raw === 'dark' || raw === 'auto')
-            return raw;
+        return localStorage.getItem(WELCOME_GATEWAY_KEY) === '1';
     }
     catch {
-        // ignore
+        return false;
     }
-    return 'auto';
 }
-function saveThemePreference(pref) {
+function markWelcomeGatewayDismissed() {
     try {
-        localStorage.setItem(THEME_PREF_KEY, pref);
+        localStorage.setItem(WELCOME_GATEWAY_KEY, '1');
     }
     catch {
         // ignore quota errors
     }
 }
 const SIDEBAR_WIDTH_KEY = 'docblocks:sidebarWidth';
-const SIDEBAR_WIDTH_DEFAULT = 260;
-const SIDEBAR_WIDTH_MIN = 180;
+const SIDEBAR_WIDTH_DEFAULT = 320;
+const SIDEBAR_WIDTH_MIN = 320;
 const SIDEBAR_WIDTH_MAX = 600;
-/** Drag below this many pixels and the sidebar collapses entirely —
- *  the editor takes the full width and a back-arrow appears in the
- *  toolbar so the user can pop the sidebar back open. Same UX as
- *  the existing mobile narrow-viewport flow. */
-const SIDEBAR_COLLAPSE_THRESHOLD = 120;
+/** Drag below this many pixels and the sidebar collapses entirely --
+ *  the workspace pane takes the full width and offers a control to
+ *  restore the side-by-side layout. */
+const SIDEBAR_COLLAPSE_THRESHOLD = SIDEBAR_WIDTH_MIN;
 function loadSidebarWidth() {
     try {
         const raw = localStorage.getItem(SIDEBAR_WIDTH_KEY);
@@ -175,11 +248,115 @@ function stripExtension(name) {
     return name.replace(/\.[^.]+$/, '');
 }
 function normaliseProviderPath(p) {
-    return '/' + p.replace(/^\/+/, '');
+    const canonical = parseWorkspacePath(p);
+    return canonical ? `/${canonical}` : '/';
 }
 function sameProviderPath(a, b) {
     return normaliseProviderPath(a) === normaliseProviderPath(b);
 }
+function relocateProviderPath(path, oldPath, newPath) {
+    const current = normaliseProviderPath(path);
+    const oldNormalised = normaliseProviderPath(oldPath);
+    if (current !== oldNormalised && !current.startsWith(`${oldNormalised}/`))
+        return path;
+    return `${newPath.replace(/\/+$/, '')}${current.slice(oldNormalised.length)}`;
+}
+function pathContains(parentPath, candidatePath) {
+    return workspacePathContains(parseWorkspacePath(parentPath), parseWorkspacePath(candidatePath));
+}
+async function readProviderDirectory(provider, path) {
+    const providerV2 = getFileSystemProviderV2(provider);
+    if (!providerV2)
+        return provider.readDirectory(path);
+    const entries = await providerV2.readDirectory(parseWorkspacePath(path));
+    return entries.map((entry) => ({ kind: entry.kind, name: entry.name, path: entry.path }));
+}
+async function readProviderText(provider, path) {
+    const providerV2 = getFileSystemProviderV2(provider);
+    if (!providerV2)
+        return provider.readFile(path);
+    const file = await providerV2.readFile(parseWorkspacePath(path));
+    return file ? new TextDecoder().decode(file.data) : null;
+}
+async function providerEntryExists(provider, path) {
+    const providerV2 = getFileSystemProviderV2(provider);
+    return providerV2
+        ? (await providerV2.stat(parseWorkspacePath(path))) !== null
+        : provider.exists(path);
+}
+async function writeProviderText(provider, path, content, mode = 'upsert') {
+    const providerV2 = getFileSystemProviderV2(provider);
+    if (providerV2) {
+        await providerV2.writeFile(parseWorkspacePath(path), new TextEncoder().encode(content), {
+            mode,
+            createParents: true,
+            expectedVersion: mode === 'create' ? null : undefined,
+        });
+        return;
+    }
+    if (mode === 'create' && (await provider.exists(path))) {
+        throw new FsError('already-exists', 'File already exists.', { operation: 'write', path });
+    }
+    await provider.writeFile(path, content);
+}
+async function removeProviderEntry(provider, path) {
+    const providerV2 = getFileSystemProviderV2(provider);
+    if (providerV2) {
+        await providerV2.remove(parseWorkspacePath(path), { recursive: true, missing: 'ignore' });
+        return;
+    }
+    await provider.delete(path);
+}
+async function readStableFileSnapshot(provider, path) {
+    const providerV2 = getFileSystemProviderV2(provider);
+    if (providerV2) {
+        const read = await providerV2.readFile(parseWorkspacePath(path));
+        return {
+            content: read ? new TextDecoder().decode(read.data) : null,
+            version: read?.entry.version ?? null,
+        };
+    }
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const before = await provider.stat(path);
+        const content = await provider.readFile(path);
+        const after = await provider.stat(path);
+        const unchanged = before?.lastModified === after?.lastModified && before?.size === after?.size;
+        const existenceMatches = (content !== null) === (after !== null);
+        if (unchanged && existenceMatches) {
+            return {
+                content,
+                version: after ? `${after.lastModified}:${after.size}` : null,
+            };
+        }
+    }
+    throw new Error('The file kept changing while DocBlocks was reading it.');
+}
+async function sha256Hex(data) {
+    const digest = await crypto.subtle.digest('SHA-256', data);
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Ask for write access to a file handle delivered by the web File Handling
+ * API. Chromium grants read on launch; readwrite needs one prompt, ideally
+ * requested while the OS-launch user activation is still fresh. The
+ * permission methods are Chromium-only extensions (same inline typing
+ * approach as core's native-provider), so absent methods are treated as
+ * writable and the write itself surfaces any failure.
+ */
+async function ensureHandleWritePermission(handle) {
+    const h = handle;
+    if (!h.queryPermission || !h.requestPermission)
+        return true;
+    try {
+        const opts = { mode: 'readwrite' };
+        if ((await h.queryPermission(opts)) === 'granted')
+            return true;
+        return (await h.requestPermission(opts)) === 'granted';
+    }
+    catch {
+        return false;
+    }
+}
 /** Portable relative link from one workspace file to another. Walks up
  *  from the source's directory and back down to the target so the link
  *  survives folder reshuffles (`../sibling.md`, `subfolder/child.md`,
@@ -211,10 +388,12 @@ async function collectMarkdownFiles(fs, root) {
         visited.add(dir);
         let entries;
         try {
-            entries = await fs.readDirectory(dir);
+            entries = await readProviderDirectory(fs, dir);
         }
-        catch {
-            return;
+        catch (error) {
+            if (error instanceof FsError && error.code === 'not-found')
+                return;
+            throw error;
         }
         for (const entry of entries) {
             if (entry.kind === 'directory') {
@@ -236,20 +415,57 @@ async function collectMarkdownFiles(fs, root) {
     await walk(root);
     return out;
 }
+/**
+ * Walk a FileSystemProvider and copy every file into a content container.
+ * Kept outside the component so document commit targets and backup actions
+ * share one implementation.
+ */
+async function copyProviderToContainer(src, container, pathPrefix) {
+    const providerV2 = getFileSystemProviderV2(src);
+    if (providerV2) {
+        const snapshot = await providerV2.snapshot();
+        for (const entry of snapshot.entries) {
+            if (entry.kind !== 'file')
+                continue;
+            const rel = entry.path;
+            const destination = pathPrefix ? `${pathPrefix}/${rel}` : rel;
+            await container.writeFile(destination, entry.data);
+        }
+        return;
+    }
+    const stack = ['/'];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        const entries = await readProviderDirectory(src, dir);
+        for (const entry of entries) {
+            if (entry.kind === 'directory') {
+                stack.push(entry.path);
+                continue;
+            }
+            const rel = entry.path.replace(/^\/+/, '');
+            const zipPath = pathPrefix ? pathPrefix + '/' + rel : rel;
+            const binary = await src.readBinary(entry.path);
+            if (binary)
+                await container.writeFile(zipPath, binary);
+            else {
+                const text = await src.readFile(entry.path);
+                if (text === null)
+                    throw new Error(`The workspace changed while reading ${entry.path}.`);
+                await container.writeFile(zipPath, new TextEncoder().encode(text));
+            }
+        }
+    }
+}
 async function createElectronProviderFromWorkspace(ws) {
     if (!ws.rootPath)
         return null;
     try {
-        await getDocBlocksHost().workspaces.register({
-            id: ws.id,
-            name: ws.name,
-            rootPath: ws.rootPath,
-        });
+        await getDocBlocksHost().workspaces.register(ws.id);
     }
     catch {
         return null;
     }
-    return new ElectronFileSystemProvider(ws.id, ws.name, ws.rootPath);
+    return createElectronFileSystemProvider(ws.id, ws.name, ws.rootPath);
 }
 function useIsMobile(breakpoint = 768) {
     const [isMobile, setIsMobile] = useState(() => typeof window !== 'undefined' && window.matchMedia(`(max-width: ${breakpoint}px)`).matches);
@@ -267,16 +483,34 @@ function FolderGlyph() {
 function FileGlyph() {
     return (_jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "1.5", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("path", { d: "M6 3h8l5 5v12a1 1 0 0 1-1 1H6a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1z" }), _jsx("path", { d: "M14 3v5h5" })] }));
 }
-export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersioning = true, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, versioningRef, }) {
+export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersioning = true, versionBasename, versioningPrunePolicy, versioningAutoSaveIdleMs, onSaveVersion, versioningRef, updateAvailable = false, onApplyUpdate, offlineReady = false, }) {
     const osTheme = useOsTheme();
     const [themePreference, setThemePreference] = useState(loadThemePreference);
-    // "System default" (auto) always follows the OS — the host's theme prop
+    const [accentColor, setAccentColor] = useState(loadAccentColor);
+    // "System default" (auto) always follows the OS -- the host's theme prop
     // is kept only for API back-compat and does not override OS detection.
     const resolvedTheme = themePreference === 'light' || themePreference === 'dark' ? themePreference : osTheme;
     const handleThemeChange = useCallback((pref) => {
         setThemePreference(pref);
         saveThemePreference(pref);
     }, []);
+    // Keep the browser's theme-color metas in sync with the resolved theme so
+    // the installed web app's titlebar (Window Controls Overlay caption area,
+    // Android status bar) matches the shell chrome. Both media-attributed
+    // metas are overwritten on purpose: an explicit user theme choice must
+    // beat the OS media query. Electron paints its own titlebar.
+    useEffect(() => {
+        if (isElectronHost() || typeof document === 'undefined')
+            return;
+        const metas = document.querySelectorAll('meta[name="theme-color"]');
+        metas.forEach((meta) => {
+            meta.content = DB_CHROME_COLORS[resolvedTheme];
+        });
+    }, [resolvedTheme]);
+    const handleAccentColorChange = useCallback((color) => {
+        setAccentColor(color);
+        saveAccentColor(color);
+    }, []);
     const [viewPreferences, setViewPreferences] = useState(loadViewPreferences);
     const handleViewPreferencesChange = useCallback((prefs) => {
         setViewPreferences(prefs);
@@ -284,21 +518,26 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
     }, []);
     const isMobile = useIsMobile();
     const [mobileShowEditor, setMobileShowEditor] = useState(false);
-    // Sidebar width — persisted across sessions, dragged via the resizer
+    // Sidebar width -- persisted across sessions, dragged via the resizer
     // between sidebar and editor area. We track the "live" width during a
     // drag in a ref so each mousemove doesn't trigger a state update; only
     // setState on commit so React doesn't churn through every pixel.
     const [sidebarWidth, setSidebarWidth] = useState(loadSidebarWidth);
     // When the user drags the resizer below SIDEBAR_COLLAPSE_THRESHOLD,
-    // we switch the layout into single-pane "compact" mode — same UX as
+    // we switch the layout into single-pane "compact" mode -- same UX as
     // the mobile narrow-viewport flow, where only the sidebar OR the
     // editor is visible at a time and a back-arrow in the toolbar pops
-    // between them. A "Restore split view" button on the editor toolbar
+    // between them. A "Restore split view" button in either pane's header
     // exits compact mode; on real mobile that button is suppressed
     // because there's not enough viewport for side-by-side. Not
     // persisted across reloads. */
     const [compactLayout, setCompactLayout] = useState(false);
     const effectiveCompact = isMobile || compactLayout;
+    const showBrowserStorageWarning = !isElectronHost();
+    const [browserStoragePersistent, setBrowserStoragePersistent] = useState(false);
+    // Browser PWA install prompt (Chromium only). The event is stashed when
+    // the browser deems the app installable and spent on first use.
+    const [installPromptEvent, setInstallPromptEvent] = useState(null);
     const sidebarRef = useRef(null);
     const dragStateRef = useRef(null);
     const handleResizerPointerDown = useCallback((e) => {
@@ -320,7 +559,7 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                 return;
             lastRaw = drag.startWidth + (ev.clientX - drag.startX);
             if (lastRaw < SIDEBAR_COLLAPSE_THRESHOLD && sidebarRef.current) {
-                // Below threshold — preview the collapse by snapping to the
+                // Below threshold -- preview the collapse by snapping to the
                 // minimum width and fading the sidebar, so the user can see
                 // they've crossed into "release to collapse" territory.
                 sidebarRef.current.style.width = `${SIDEBAR_WIDTH_MIN}px`;
@@ -344,8 +583,8 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                 sidebarRef.current.style.opacity = '';
             }
             if (lastRaw < SIDEBAR_COLLAPSE_THRESHOLD) {
-                // Released below threshold — switch to compact (single-pane)
-                // layout focused on the editor. Keep the persisted
+                // Released below threshold -- switch to compact (single-pane)
+                // layout focused on the document pane. Keep the persisted
                 // sidebarWidth so exiting compact mode restores it.
                 setCompactLayout(true);
                 setMobileShowEditor(true);
@@ -364,8 +603,15 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
         document.addEventListener('pointerup', onUp);
     }, [sidebarWidth]);
     const [provider, setProvider] = useState(null);
+    const [workspaceStartupError, setWorkspaceStartupError] = useState(null);
     const [activeWorkspaceId, setActiveWorkspaceId] = useState(null);
     const [activeWorkspaceDescriptor, setActiveWorkspaceDescriptor] = useState(null);
+    useEffect(() => {
+        if (!provider || getTransientWorkspace(provider.id))
+            return;
+        const providerV2 = getFileSystemProviderV2(provider);
+        return providerV2 ? retainFileSystemProvider(providerV2) : undefined;
+    }, [provider]);
     // Re-fetch the descriptor whenever the active id (or its versioning
     // override) changes. `descriptorRefreshKey` is bumped after writes so
     // the resolver picks up the updated override without remounting.
@@ -384,6 +630,17 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
             cancelled = true;
         };
     }, [activeWorkspaceId, descriptorRefreshKey]);
+    // All git UI state/actions -- null-renders on surfaces without git.
+    const gitWorkspaceId = provider &&
+        activeWorkspaceDescriptor?.id === activeWorkspaceId &&
+        provider.id === activeWorkspaceId &&
+        activeWorkspaceDescriptor.type === 'electron-native'
+        ? activeWorkspaceDescriptor.id
+        : null;
+    const git = useGit(provider, gitWorkspaceId, resolvedTheme);
+    const gitRef = useRef(git);
+    gitRef.current = git;
+    const { scheduleRefresh: gitScheduleRefresh } = git;
     const [workspaceSettingsOpen, setWorkspaceSettingsOpen] = useState(false);
     const [versioningPreference, setVersioningPreference] = useState(loadVersioningPreference);
     const handleVersioningPreferenceChange = useCallback((pref) => {
@@ -404,15 +661,211 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
         setWorkspaceSettingsOpen(false);
     }, [activeWorkspaceDescriptor]);
     const [selectedFile, setSelectedFile] = useState(null);
+    useDocumentTitle(selectedFile);
+    const exportDestinationAdapter = useMemo(() => {
+        if (!isElectronHost() || !activeWorkspaceId || !selectedFile)
+            return undefined;
+        const documentId = JSON.stringify([activeWorkspaceId, selectedFile]);
+        const host = getDocBlocksHost().exports;
+        return {
+            resolveTarget: (filename) => host.resolveTarget(documentId, filename),
+            pickTarget: (filename, currentTarget) => host.pickTarget(documentId, filename, currentTarget?.grantId ?? null),
+            saveBlob: async (blob, filename, target) => host.save(documentId, filename, target?.grantId ?? null, await blob.arrayBuffer()),
+        };
+    }, [activeWorkspaceId, selectedFile]);
     const [selectedFolder, setSelectedFolder] = useState(null);
     const [folderEntries, setFolderEntries] = useState([]);
-    const [editorContent, setEditorContent] = useState('');
-    const [editorKey, setEditorKey] = useState(0);
+    const { session: documentSession, snapshot: documentSnapshot } = useDocumentSession(500);
+    // The session snapshot is the sole owner of document content and edit
+    // identity. React retains only presentation state (path/folder/view).
+    const editorContent = documentSnapshot.content;
+    const editorSessionScope = useMemo(() => documentSnapshot.targetKey && !documentSnapshot.frozen
+        ? {
+            targetKey: documentSnapshot.targetKey,
+            generation: documentSnapshot.generation,
+        }
+        : null, [documentSnapshot.frozen, documentSnapshot.generation, documentSnapshot.targetKey]);
+    const [editorPresentationEpoch, setEditorPresentationEpoch] = useState(0);
+    const editorKey = `${documentSnapshot.generation}:${editorPresentationEpoch}`;
+    const editorPlaceholder = useMemo(() => {
+        // Keep the selection scoped to the same generation that remounts Squisq.
+        void editorKey;
+        return pickEmptyDocumentPrompt();
+    }, [editorKey]);
     const [explorerKey, setExplorerKey] = useState(0);
     const [initialView, setInitialView] = useState('wysiwyg');
-    /** Suppress popstate handling during programmatic navigation. */
-    const skipPopState = useRef(false);
-    const lastLocalSaveRef = useRef(null);
+    // First-run gateway over the welcome doc's Play view -- see WELCOME_GATEWAY_KEY.
+    const [showWelcomeGateway, setShowWelcomeGateway] = useState(false);
+    const navigationRequestRef = useRef(0);
+    const workspaceAuthorityBarrier = useMemo(() => new WorkspaceAuthorityBarrier(), []);
+    const preparedCloseRequestRef = useRef(null);
+    const pendingDbkConflictsRef = useRef(new Map());
+    const createDocumentTarget = useCallback((fsProvider, workspaceId, filePath) => {
+        const transient = getTransientWorkspace(workspaceId);
+        const baseTarget = createFileSystemDocumentTarget(fsProvider, filePath);
+        const originKind = transient?.descriptor.origin?.kind;
+        const needsElectronHost = originKind === 'loose-file' || originKind === 'dbk';
+        if (!transient?.descriptor.origin || (needsElectronHost && !isElectronHost())) {
+            return {
+                key: baseTarget.key,
+                async commit(request) {
+                    const result = await baseTarget.commit(request);
+                    gitScheduleRefresh();
+                    return result;
+                },
+            };
+        }
+        const origin = transient.descriptor.origin;
+        if (origin.kind === 'web-file' || origin.kind === 'web-dbk') {
+            // Launched-file origins (installed web app, File Handling API):
+            // read and write through the FileSystemFileHandle instead of the
+            // Electron host bridge, with the same optimistic external-change
+            // detection as the host-backed paths below.
+            const webOrigin = origin;
+            const transientProvider = transient.provider;
+            return {
+                key: baseTarget.key,
+                async commit(request) {
+                    if (!(await ensureHandleWritePermission(webOrigin.handle))) {
+                        throw new Error(`DocBlocks needs permission to write to "${webOrigin.name}". Save again to grant it.`);
+                    }
+                    if (webOrigin.kind === 'web-file') {
+                        const current = await (await webOrigin.handle.getFile()).text();
+                        if (request.persistedContent !== null &&
+                            current !== request.persistedContent &&
+                            current !== request.content) {
+                            pendingDbkConflictsRef.current.delete(baseTarget.key);
+                            await writeProviderText(fsProvider, filePath, current);
+                            throw new DocumentCommitConflictError('The original file changed outside DocBlocks.', current, null);
+                        }
+                        const writable = await webOrigin.handle.createWritable();
+                        await writable.write(request.content);
+                        await writable.close();
+                        await baseTarget.commit(request);
+                        pendingDbkConflictsRef.current.delete(baseTarget.key);
+                        gitScheduleRefresh();
+                        return {};
+                    }
+                    // web-dbk: package the in-memory workspace into a zip and write
+                    // it back through the handle, guarded by a SHA-256
+                    // compare-and-swap that mirrors the Electron dbk path.
+                    const [{ MemoryContentContainer }, { containerToZip, zipToContainer }] = await Promise.all([
+                        import('@bendyline/squisq/storage'),
+                        import('@bendyline/squisq-formats/container'),
+                    ]);
+                    const currentBytes = await (await webOrigin.handle.getFile()).arrayBuffer();
+                    const currentVersion = await sha256Hex(currentBytes);
+                    if (webOrigin.version !== null && currentVersion !== webOrigin.version) {
+                        if (!isMemoryWorkspaceProvider(transientProvider)) {
+                            throw new Error('A transient DBK workspace must use in-memory storage.');
+                        }
+                        const externalContainer = await zipToContainer(currentBytes);
+                        const snapshot = await createDbkWorkspaceSnapshot(externalContainer, {
+                            targetDocumentPath: filePath,
+                        });
+                        // Keep both branches intact until the user chooses -- same
+                        // semantics as the Electron dbk conflict staging below.
+                        pendingDbkConflictsRef.current.set(baseTarget.key, {
+                            provider: transientProvider,
+                            snapshot,
+                        });
+                        webOrigin.version = currentVersion;
+                        throw new DocumentCommitConflictError('The original DocBlocks bundle changed outside DocBlocks.', snapshot.documentContent, currentVersion);
+                    }
+                    const container = new MemoryContentContainer();
+                    await copyProviderToContainer(transientProvider, container, '');
+                    await container.writeFile(filePath.replace(/^\/+/, ''), new TextEncoder().encode(request.content));
+                    const blob = await containerToZip(container);
+                    const bytes = await blob.arrayBuffer();
+                    const writable = await webOrigin.handle.createWritable();
+                    await writable.write(bytes);
+                    await writable.close();
+                    webOrigin.version = await sha256Hex(bytes);
+                    // The transient provider intentionally retained the complete
+                    // local branch while external bundle B was staged for conflict
+                    // resolution. Once bundle C is committed to the origin, advance
+                    // that internal markdown baseline unconditionally; comparing its
+                    // old A content against request.persistedContent B would report a
+                    // false second conflict after the durable write already succeeded.
+                    await writeProviderText(fsProvider, filePath, request.content);
+                    pendingDbkConflictsRef.current.delete(baseTarget.key);
+                    gitScheduleRefresh();
+                    return { version: webOrigin.version };
+                },
+            };
+        }
+        return {
+            key: baseTarget.key,
+            async commit(request) {
+                const host = getDocBlocksHost();
+                if (origin.kind === 'loose-file') {
+                    const result = await host.external.commitText(origin.resourceId, request.content, request.persistedContent);
+                    if (result.status === 'conflict') {
+                        pendingDbkConflictsRef.current.delete(baseTarget.key);
+                        if (result.content === null)
+                            await removeProviderEntry(fsProvider, filePath);
+                        else
+                            await writeProviderText(fsProvider, filePath, result.content);
+                        throw new DocumentCommitConflictError('The original file changed outside DocBlocks.', result.content, result.version);
+                    }
+                    await baseTarget.commit(request);
+                    pendingDbkConflictsRef.current.delete(baseTarget.key);
+                    gitScheduleRefresh();
+                    return { version: result.version };
+                }
+                else {
+                    const [{ MemoryContentContainer }, { containerToZip, zipToContainer }] = await Promise.all([
+                        import('@bendyline/squisq/storage'),
+                        import('@bendyline/squisq-formats/container'),
+                    ]);
+                    const container = new MemoryContentContainer();
+                    await copyProviderToContainer(transient.provider, container, '');
+                    await container.writeFile(filePath.replace(/^\/+/, ''), new TextEncoder().encode(request.content));
+                    const blob = await containerToZip(container);
+                    const result = await host.external.commitBinary(origin.resourceId, await blob.arrayBuffer(), origin.version);
+                    if (result.status === 'conflict') {
+                        let externalContent = null;
+                        if (result.data) {
+                            const externalContainer = await zipToContainer(result.data);
+                            if (!isMemoryWorkspaceProvider(transient.provider)) {
+                                throw new Error('A transient DBK workspace must use in-memory storage.');
+                            }
+                            const snapshot = await createDbkWorkspaceSnapshot(externalContainer, {
+                                targetDocumentPath: filePath,
+                            });
+                            externalContent = snapshot.documentContent;
+                            // Keep both branches intact until the user chooses. Reload
+                            // replaces the whole tree; Keep mine packages this untouched
+                            // local provider against the newly observed bundle version.
+                            pendingDbkConflictsRef.current.set(baseTarget.key, {
+                                provider: transient.provider,
+                                snapshot,
+                            });
+                        }
+                        else {
+                            pendingDbkConflictsRef.current.delete(baseTarget.key);
+                        }
+                        // Advance the optimistic origin only after the external bundle
+                        // has been completely staged. A parse/read failure must retry
+                        // against the old version rather than silently authorize an
+                        // overwrite of data we could not reconcile.
+                        origin.version = result.version;
+                        throw new DocumentCommitConflictError('The original DocBlocks bundle changed outside DocBlocks.', externalContent, result.version);
+                    }
+                    origin.version = result.version;
+                    // As with web-dbk above, the in-memory provider still represents
+                    // the preserved local branch rather than the external conflict
+                    // baseline. The origin commit is the conditional authority check;
+                    // now make the internal document agree with that acknowledged C
+                    // bundle without re-comparing A against B.
+                    await writeProviderText(fsProvider, filePath, request.content);
+                    pendingDbkConflictsRef.current.delete(baseTarget.key);
+                    gitScheduleRefresh();
+                    return { version: result.version };
+                }
+            },
+        };
+    }, [gitScheduleRefresh]);
     /**
      * Per-file media container: for `notes.md`, images live in
      * `notes_files/` next to the markdown. Created lazily on first write,
@@ -421,6 +874,7 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
      */
     const mediaContainerRef = useRef(null);
     const [mediaProvider, setMediaProvider] = useState(null);
+    const [mediaEpoch, setMediaEpoch] = useState(0);
     /**
      * Per-document container scoped to `<basename>_files/`. This is what
      * the editor uses for version history (`.versions/` lives here) and
@@ -441,69 +895,112 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
     const pushHash = useCallback((wsId, filePath) => {
         const hash = buildHash(wsId, filePath);
         if (window.location.hash !== hash) {
-            skipPopState.current = true;
             window.history.pushState(null, '', hash);
         }
     }, []);
     /** Open a workspace (and optionally a file) from identifiers.
      *  Returns the FileSystemProvider on success, or null on failure. */
-    const openFromIds = useCallback(async (wsId, filePath, push, view) => {
-        const workspaces = await listWorkspaces();
-        const ws = workspaces.find((w) => w.id === wsId);
-        if (!ws)
+    const openFromIds = useCallback(async (wsId, filePath, push, view, navigationRequestId) => {
+        const requestId = navigationRequestId ?? ++navigationRequestRef.current;
+        if (requestId !== navigationRequestRef.current)
             return null;
+        // Transient (session-only) workspaces -- a loose file or `.dbk` opened
+        // from the OS -- carry a pre-built in-memory provider in the registry.
+        const transient = getTransientWorkspace(wsId);
+        let ws;
         let fsProvider = null;
-        if (ws.type === 'electron-native') {
-            fsProvider = await createElectronProviderFromWorkspace(ws);
-            if (!fsProvider)
-                return null;
-        }
-        else if (ws.type === 'native') {
-            const restored = await restoreNativeFolder(ws.id);
-            if (!restored)
-                return null;
-            fsProvider = restored;
+        if (transient) {
+            ws = transient.descriptor;
+            fsProvider = transient.provider;
         }
         else {
-            fsProvider = new IndexedDBFileSystemProvider(ws.id, ws.name);
+            const workspaces = await listWorkspaces();
+            ws = workspaces.find((w) => w.id === wsId);
+            if (!ws)
+                return null;
+            if (ws.type === 'electron-native') {
+                fsProvider = await createElectronProviderFromWorkspace(ws);
+                if (!fsProvider)
+                    return null;
+            }
+            else if (ws.type === 'native') {
+                const restored = await (await loadNativeFileSystem()).restoreNativeFolder(ws.id);
+                if (!restored)
+                    return null;
+                fsProvider = restored;
+            }
+            else {
+                fsProvider = await createIndexedDbFileSystemProvider(ws.id, ws.name);
+            }
         }
-        await touchWorkspace(ws.id);
-        setProvider(fsProvider);
-        setActiveWorkspaceId(ws.id);
-        if (filePath) {
-            const content = await fsProvider.readFile(filePath);
-            if (content !== null) {
-                setSelectedFile(filePath);
+        if (!ws || !fsProvider)
+            return null;
+        let adopted = false;
+        try {
+            await touchWorkspace(ws.id);
+            if (requestId !== navigationRequestRef.current)
+                return null;
+            let openedFile = null;
+            let openedContent = '';
+            const transitioned = await documentSession.transitionWithLoad(async () => {
+                if (requestId !== navigationRequestRef.current)
+                    return null;
+                if (filePath) {
+                    const content = await readProviderText(fsProvider, filePath);
+                    if (requestId !== navigationRequestRef.current)
+                        return null;
+                    if (content !== null) {
+                        openedFile = filePath;
+                        openedContent = content;
+                    }
+                }
+                return {
+                    target: openedFile ? createDocumentTarget(fsProvider, ws.id, openedFile) : null,
+                    content: openedContent,
+                };
+            });
+            if (!transitioned)
+                return null;
+            // Once the session has accepted this target, ownership must follow it
+            // even if a newer navigation request arrived in the final microtask.
+            // The newer request will perform the next serialized transition.
+            setProvider(fsProvider);
+            adopted = true;
+            setActiveWorkspaceId(ws.id);
+            if (openedFile) {
+                setSelectedFile(openedFile);
                 setSelectedFolder(null);
                 setFolderEntries([]);
-                setEditorContent(content);
                 const effectiveView = view ?? 'wysiwyg';
                 setInitialView(effectiveView);
-                setEditorKey((k) => k + 1);
-                saveLastState({ workspaceId: wsId, filePath, view: effectiveView });
+                // Transient workspaces are session-only; don't persist them as the
+                // "last opened" state (the id won't exist after a reload).
+                if (!transient) {
+                    saveLastState({ workspaceId: wsId, filePath: openedFile, view: effectiveView });
+                }
             }
             else {
                 setSelectedFile(null);
                 setSelectedFolder(null);
                 setFolderEntries([]);
-                setEditorContent('');
-                setEditorKey((k) => k + 1);
             }
+            if (push) {
+                pushHash(ws.id, openedFile);
+            }
+            return fsProvider;
         }
-        else {
-            setSelectedFile(null);
-            setSelectedFolder(null);
-            setFolderEntries([]);
-            setEditorContent('');
-            setEditorKey((k) => k + 1);
-        }
-        if (push) {
-            pushHash(ws.id, filePath);
+        finally {
+            if (!transient && !adopted)
+                await getFileSystemProviderV2(fsProvider)?.dispose();
         }
-        return fsProvider;
-    }, [pushHash]);
-    const seedWelcomeFile = useCallback(async (fs) => {
-        const entries = await fs.readDirectory('/');
+    }, [createDocumentTarget, documentSession, pushHash]);
+    const seedWelcomeFile = useCallback(async (fs, navigationRequestId) => {
+        const isCurrent = () => navigationRequestId === undefined || navigationRequestId === navigationRequestRef.current;
+        if (!isCurrent())
+            return;
+        const entries = await readProviderDirectory(fs, '/');
+        if (!isCurrent())
+            return;
         // If the only file is the welcome doc, auto-select it.
         // Match either casing so workspaces seeded before the rename
         // (aboutDocblocks.md) keep working alongside new ones (aboutDocBlocks.md).
@@ -511,15 +1008,18 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
             entries[0].kind === 'file' &&
             entries[0].path.replace(/^\//, '').toLowerCase() === 'aboutdocblocks.md') {
             const aboutPath = entries[0].path;
-            const content = await fs.readFile(aboutPath);
-            if (content !== null) {
+            const content = await readProviderText(fs, aboutPath);
+            if (content !== null && isCurrent()) {
+                await documentSession.transitionTo(createDocumentTarget(fs, fs.id, aboutPath), content);
+                if (!isCurrent())
+                    return;
                 setSelectedFile(aboutPath);
-                setEditorContent(content);
                 setInitialView('preview');
-                setEditorKey((k) => k + 1);
                 setExplorerKey((k) => k + 1);
                 pushHash(fs.id, aboutPath);
                 saveLastState({ workspaceId: fs.id, filePath: aboutPath, view: 'preview' });
+                if (!isWelcomeGatewayDismissed())
+                    setShowWelcomeGateway(true);
             }
             return;
         }
@@ -529,46 +1029,127 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
         const welcomeContent = [
             '# Welcome to DocBlocks',
             '',
+            'Your markdown can do anything.',
+            '',
             'DocBlocks is a free browser-based markdown document editor that lets you create, organize, and manage your documents right in the browser. What you write here can become a Word or PDF doc, a slide deck, an e-book, or a video.',
             '',
             'Simple to write. Beautiful wherever it goes.',
             '',
             '## Features',
             '',
-            '- **Rich Markdown Editing** — Write in a visual editor or switch to raw markdown anytime. Use section annotations to change the visualization for blocks of content.',
-            '- **Workspaces** — Organize your documents into separate workspaces in the browser or on your device.',
-            '- **Useful Everywhere** — Your content is usable across multiple formats — Microsoft Word .docx, PowerPoint, PDF, HTML, EPUB e-books, and Markdown.',
-            '- **Playback & Video** — Preview your documents as rich visual presentations and export them as MP4 video',
-            '- **No BS** — Free, no ads, no accounts, no tracking - everything runs locally in your browser',
+            '- **Rich Markdown Editing** -- Write in a visual editor or switch to raw markdown source anytime. Use section annotations to change the visualization for blocks of content.',
+            '- **Workspaces** -- Organize your documents into separate workspaces in the browser or on your device.',
+            '- **Useful Everywhere** -- Your content is usable across multiple formats -- Microsoft Word .docx, PowerPoint, PDF, HTML, EPUB e-books, and Markdown.',
+            '- **Playback & Video** -- Preview your documents as rich visual presentations and export them as MP4 video',
+            '- **No BS** -- Free, no ads, no accounts, no tracking - everything runs locally in your browser',
             '',
             '## Getting Started',
             '',
             '1. Create a new file using the **New File** button in the sidebar',
-            '2. Start writing in markdown — the editor supports headings, lists, links, images, and more',
+            '2. Start writing in markdown -- the editor supports headings, lists, links, images, and more',
             '3. Your work is saved automatically',
             '',
-            'Built with [Squiggly Square](https://github.com/bendyline/squisq) by [Bendyline](https://bendyline.com).',
+            'Built on [Squiggly Square markdown extensions](https://github.com/bendyline/squisq) by [Bendyline](https://bendyline.com).',
         ].join('\n');
-        await fs.writeFile(welcomePath, welcomeContent);
+        let seededContent = welcomeContent;
+        try {
+            await writeProviderText(fs, welcomePath, welcomeContent, 'create');
+        }
+        catch (error) {
+            if (!(error instanceof FsError && error.code === 'already-exists'))
+                throw error;
+            const existing = await readProviderText(fs, welcomePath);
+            if (existing === null)
+                throw error;
+            seededContent = existing;
+        }
+        if (!isCurrent())
+            return;
+        await documentSession.transitionTo(createDocumentTarget(fs, fs.id, welcomePath), seededContent);
+        if (!isCurrent())
+            return;
         setSelectedFile(welcomePath);
-        setEditorContent(welcomeContent);
         setInitialView('preview');
-        setEditorKey((k) => k + 1);
         setExplorerKey((k) => k + 1);
         pushHash(fs.id, welcomePath);
         saveLastState({ workspaceId: fs.id, filePath: welcomePath, view: 'preview' });
-    }, [pushHash]);
-    // Initialise workspace on mount — restore from hash or last-used
+        if (!isWelcomeGatewayDismissed())
+            setShowWelcomeGateway(true);
+    }, [createDocumentTarget, documentSession, pushHash]);
+    // Startup is a mount lifecycle, not a reaction to callback identity. Keep
+    // the latest implementations available without letting git/provider state
+    // changes restart initialization and supersede an OS-open navigation.
+    const startupOpenFromIdsRef = useRef(openFromIds);
+    startupOpenFromIdsRef.current = openFromIds;
+    const startupSeedWelcomeFileRef = useRef(seedWelcomeFile);
+    startupSeedWelcomeFileRef.current = seedWelcomeFile;
+    /** Hide the welcome gateway and never show it again. Safe to call from
+     *  paths where it may not be showing -- only persists when it was. */
+    const closeWelcomeGateway = useCallback(() => {
+        setShowWelcomeGateway((showing) => {
+            if (showing)
+                markWelcomeGatewayDismissed();
+            return false;
+        });
+    }, []);
+    /** Gateway CTA -- flip the welcome doc from Play into the editor. */
+    const handleStartWriting = useCallback(() => {
+        closeWelcomeGateway();
+        setInitialView('wysiwyg');
+        setEditorPresentationEpoch((epoch) => epoch + 1);
+        if (activeWorkspaceId && selectedFile) {
+            saveLastState({ workspaceId: activeWorkspaceId, filePath: selectedFile, view: 'wysiwyg' });
+        }
+    }, [closeWelcomeGateway, activeWorkspaceId, selectedFile]);
+    // Initialise workspace on mount -- restore from hash or last-used
     useEffect(() => {
-        (async () => {
+        const requestId = ++navigationRequestRef.current;
+        let cancelled = false;
+        const isCurrent = () => !cancelled && requestId === navigationRequestRef.current;
+        void (async () => {
+            const electron = isElectronHost();
+            let workspaceIdRemap = {};
+            if (electron) {
+                // Main-process persisted roots are authoritative after an upgrade or
+                // collision repair. Reconcile renderer metadata before hash or
+                // last-state restoration so an obsolete id cannot reopen a different
+                // folder that once shared its legacy id.
+                try {
+                    const localWorkspaces = await listWorkspaces();
+                    const hostWorkspaces = await getDocBlocksHost().workspaces.list();
+                    const reconciliation = reconcileElectronWorkspaceDescriptors(localWorkspaces, hostWorkspaces, getDocBlocksHost().env.platform, new Date().toISOString());
+                    for (const id of reconciliation.removeIds)
+                        await removeWorkspace(id);
+                    for (const workspace of reconciliation.upsert)
+                        await saveWorkspace(workspace);
+                    workspaceIdRemap = reconciliation.idRemap;
+                }
+                catch {
+                    workspaceAuthorityBarrier.markReady();
+                    if (isCurrent()) {
+                        setWorkspaceStartupError('DocBlocks could not verify access to your saved workspaces. Restart the app or open the folder again.');
+                    }
+                    return;
+                }
+            }
+            workspaceAuthorityBarrier.markReady();
+            if (!isCurrent())
+                return;
             // Try restoring from URL hash first
             const hashState = parseHash();
             if (hashState) {
-                const restoredProvider = await openFromIds(hashState.workspaceId, hashState.filePath, false);
+                const migratedWorkspaceId = workspaceIdRemap[hashState.workspaceId];
+                const restoredWorkspaceId = migratedWorkspaceId ?? hashState.workspaceId;
+                if (migratedWorkspaceId) {
+                    window.history.replaceState(null, '', buildHash(restoredWorkspaceId, hashState.filePath));
+                }
+                const restoredProvider = await startupOpenFromIdsRef.current(restoredWorkspaceId, hashState.filePath, false, undefined, requestId);
+                if (!isCurrent())
+                    return;
                 if (restoredProvider) {
                     // If the hash had no file, check whether we should auto-select the welcome doc
                     if (!hashState.filePath) {
-                        await seedWelcomeFile(restoredProvider);
+                        await startupSeedWelcomeFileRef.current(restoredProvider, requestId);
                     }
                     return;
                 }
@@ -576,14 +1157,21 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
             // Try restoring last viewed document from localStorage
             const lastState = loadLastState();
             if (lastState) {
-                const restoredProvider = await openFromIds(lastState.workspaceId, lastState.filePath, true, lastState.view);
+                const restoredWorkspaceId = workspaceIdRemap[lastState.workspaceId] ?? lastState.workspaceId;
+                if (restoredWorkspaceId !== lastState.workspaceId) {
+                    saveLastState({ ...lastState, workspaceId: restoredWorkspaceId });
+                }
+                const restoredProvider = await startupOpenFromIdsRef.current(restoredWorkspaceId, lastState.filePath, true, lastState.view, requestId);
+                if (!isCurrent())
+                    return;
                 if (restoredProvider)
                     return;
             }
             let fsProvider = null;
-            const electron = isElectronHost();
             const workspaces = await listWorkspaces();
-            // On desktop, hide web-only workspaces (indexeddb/native) — only
+            if (!isCurrent())
+                return;
+            // On desktop, hide web-only workspaces (indexeddb/native) -- only
             // folder-based workspaces are valid.
             const candidates = electron
                 ? workspaces.filter((w) => w.type === 'electron-native')
@@ -595,36 +1183,56 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                     const p = await createElectronProviderFromWorkspace(ws);
                     if (!p)
                         continue;
+                    if (!isCurrent()) {
+                        await getFileSystemProviderV2(p)?.dispose();
+                        return;
+                    }
                     await touchWorkspace(ws.id);
+                    if (!isCurrent()) {
+                        await getFileSystemProviderV2(p)?.dispose();
+                        return;
+                    }
                     fsProvider = p;
-                    setProvider(p);
-                    setActiveWorkspaceId(ws.id);
                     break;
                 }
                 else if (ws.type === 'native') {
-                    const restored = await restoreNativeFolder(ws.id);
+                    const restored = await (await loadNativeFileSystem()).restoreNativeFolder(ws.id);
                     if (restored) {
+                        if (!isCurrent()) {
+                            await getFileSystemProviderV2(restored)?.dispose();
+                            return;
+                        }
                         await touchWorkspace(ws.id);
+                        if (!isCurrent()) {
+                            await getFileSystemProviderV2(restored)?.dispose();
+                            return;
+                        }
                         fsProvider = restored;
-                        setProvider(restored);
-                        setActiveWorkspaceId(ws.id);
                         break;
                     }
                 }
                 else {
-                    const p = new IndexedDBFileSystemProvider(ws.id, ws.name);
+                    const p = await createIndexedDbFileSystemProvider(ws.id, ws.name);
+                    if (!isCurrent()) {
+                        await getFileSystemProviderV2(p)?.dispose();
+                        return;
+                    }
                     await touchWorkspace(ws.id);
+                    if (!isCurrent()) {
+                        await getFileSystemProviderV2(p)?.dispose();
+                        return;
+                    }
                     fsProvider = p;
-                    setProvider(p);
-                    setActiveWorkspaceId(ws.id);
                     break;
                 }
             }
             if (!fsProvider) {
                 if (electron) {
                     // Desktop: ask the host for the default folder workspace
-                    // (creates ~/Documents/DocBlocks on first launch).
+                    // (creates DocBlocks in the OS-resolved Documents folder on first launch).
                     const info = await getDocBlocksHost().workspaces.getDefault();
+                    if (!isCurrent())
+                        return;
                     const descriptor = {
                         id: info.id,
                         name: info.name,
@@ -633,47 +1241,164 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                         lastOpened: new Date().toISOString(),
                     };
                     await saveWorkspace(descriptor);
-                    const p = new ElectronFileSystemProvider(info.id, info.name, info.rootPath);
+                    if (!isCurrent())
+                        return;
+                    const p = await createElectronFileSystemProvider(info.id, info.name, info.rootPath);
+                    if (!isCurrent()) {
+                        await getFileSystemProviderV2(p)?.dispose();
+                        return;
+                    }
                     fsProvider = p;
-                    setProvider(p);
-                    setActiveWorkspaceId(info.id);
                 }
                 else {
                     // Web: create the IndexedDB default workspace
                     const defaultWs = await ensureDefaultWorkspace();
-                    const p = new IndexedDBFileSystemProvider(defaultWs.id, defaultWs.name);
+                    if (!isCurrent())
+                        return;
+                    const p = await createIndexedDbFileSystemProvider(defaultWs.id, defaultWs.name);
+                    if (!isCurrent()) {
+                        await getFileSystemProviderV2(p)?.dispose();
+                        return;
+                    }
                     fsProvider = p;
-                    setProvider(p);
-                    setActiveWorkspaceId(defaultWs.id);
                 }
             }
-            // Set initial hash
-            pushHash(fsProvider.id, null);
-            // Seed welcome file if workspace is empty
-            await seedWelcomeFile(fsProvider);
-        })();
-    }, [openFromIds, pushHash, seedWelcomeFile]);
+            let adopted = false;
+            try {
+                if (!isCurrent())
+                    return;
+                // Set the root hash before seeding; seedWelcomeFile replaces it with
+                // the welcome path when it opens that document.
+                pushHash(fsProvider.id, null);
+                await startupSeedWelcomeFileRef.current(fsProvider, requestId);
+                if (!isCurrent())
+                    return;
+                setProvider(fsProvider);
+                setActiveWorkspaceId(fsProvider.id);
+                adopted = true;
+            }
+            finally {
+                if (!adopted)
+                    await getFileSystemProviderV2(fsProvider)?.dispose();
+            }
+        })().catch(() => {
+            if (isCurrent()) {
+                setWorkspaceStartupError('DocBlocks could not initialize your workspace. Restart the app or open the folder again.');
+            }
+        });
+        return () => {
+            cancelled = true;
+            if (navigationRequestRef.current === requestId)
+                navigationRequestRef.current += 1;
+        };
+    }, [pushHash, workspaceAuthorityBarrier]);
     // Handle browser back/forward
     useEffect(() => {
         const onPopState = () => {
-            if (skipPopState.current) {
-                skipPopState.current = false;
-                return;
-            }
             const hashState = parseHash();
             if (hashState) {
-                openFromIds(hashState.workspaceId, hashState.filePath, false);
+                const requestedHash = window.location.hash;
+                const restoreCurrentHash = () => {
+                    if (!activeWorkspaceId || window.location.hash !== requestedHash)
+                        return;
+                    window.history.replaceState(null, '', buildHash(activeWorkspaceId, selectedFile));
+                };
+                void openFromIds(hashState.workspaceId, hashState.filePath, false)
+                    .then((opened) => {
+                    if (!opened)
+                        restoreCurrentHash();
+                })
+                    .catch((error) => {
+                    restoreCurrentHash();
+                    alert(error instanceof Error
+                        ? 'DocBlocks could not switch documents: ' + error.message
+                        : 'DocBlocks could not switch documents.');
+                });
             }
         };
         window.addEventListener('popstate', onPopState);
         return () => window.removeEventListener('popstate', onPopState);
-    }, [openFromIds]);
+    }, [activeWorkspaceId, openFromIds, selectedFile]);
+    useEffect(() => {
+        if (!showBrowserStorageWarning || typeof navigator === 'undefined')
+            return;
+        const storage = navigator.storage;
+        if (!storage || typeof storage.persisted !== 'function')
+            return;
+        let cancelled = false;
+        void storage
+            .persisted()
+            .then((persistent) => {
+            if (!cancelled)
+                setBrowserStoragePersistent(persistent);
+        })
+            .catch(() => {
+            // Ignore unsupported/denied checks; the menu action can still try persist().
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [showBrowserStorageWarning]);
+    // Browser PWA install plumbing. Chromium fires `beforeinstallprompt` when
+    // the app is installable; stashing it (after preventDefault) lets the app
+    // menu offer "Install DocBlocks…" on our terms. `appinstalled` fires for
+    // any install path (menu item or the browser's own omnibox affordance).
+    useEffect(() => {
+        if (isElectronHost() || typeof window === 'undefined')
+            return;
+        const onBeforeInstallPrompt = (e) => {
+            e.preventDefault();
+            setInstallPromptEvent(e);
+        };
+        const onAppInstalled = () => {
+            setInstallPromptEvent(null);
+            // Chromium auto-grants persistent storage to installed apps -- re-probe
+            // so the "Keep data in browser for longer" nag retires itself.
+            const storage = navigator.storage;
+            if (storage && typeof storage.persisted === 'function') {
+                storage
+                    .persisted()
+                    .then((persistent) => {
+                    if (persistent)
+                        setBrowserStoragePersistent(true);
+                })
+                    .catch(() => {
+                    // Probe is best-effort; the manual menu action still works.
+                });
+            }
+        };
+        window.addEventListener('beforeinstallprompt', onBeforeInstallPrompt);
+        window.addEventListener('appinstalled', onAppInstalled);
+        return () => {
+            window.removeEventListener('beforeinstallprompt', onBeforeInstallPrompt);
+            window.removeEventListener('appinstalled', onAppInstalled);
+        };
+    }, []);
+    const handleInstallApp = useCallback(async () => {
+        const promptEvent = installPromptEvent;
+        // prompt() is single-use: clear the stash up front and rely on the
+        // browser re-firing beforeinstallprompt if the user dismisses.
+        setInstallPromptEvent(null);
+        if (!promptEvent)
+            return;
+        try {
+            await promptEvent.prompt();
+            await promptEvent.userChoice;
+        }
+        catch {
+            // The prompt was already consumed or is not allowed right now.
+        }
+    }, [installPromptEvent]);
     // Track view mode changes (Editor/Raw/Play tabs) and persist to localStorage
     useEffect(() => {
         const handler = (e) => {
             const target = e.target.closest?.('[data-view]');
             if (target) {
                 const view = target.getAttribute('data-view');
+                if (view) {
+                    // The user found the view tabs on their own -- the gateway's job is done.
+                    closeWelcomeGateway();
+                }
                 if (view && activeWorkspaceId && selectedFile) {
                     saveLastState({ workspaceId: activeWorkspaceId, filePath: selectedFile, view });
                 }
@@ -681,22 +1406,10 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
         };
         window.addEventListener('click', handler, true);
         return () => window.removeEventListener('click', handler, true);
-    }, [activeWorkspaceId, selectedFile]);
-    const handleAutoSaved = useCallback((filePath, savedContent) => {
-        lastLocalSaveRef.current = {
-            filePath: normaliseProviderPath(filePath),
-            content: savedContent,
-            savedAt: Date.now(),
-        };
-    }, []);
-    // Auto-save current file. The returned `flush` is called from the
-    // Ctrl/Cmd+S handler below so the user gets immediate confirmation.
-    const { flush: flushAutoSave } = useAutoSave(provider, selectedFile, editorContent, 500, handleAutoSaved);
-    // Comfort-blanket Ctrl/Cmd+S: flushes any pending autosave and pops a
-    // small "auto-save confirmed" toast. Files are already saved on every
-    // keystroke (debounced) — this is purely UX reassurance for users who
-    // muscle-memory hit Save.
-    const [saveToastVisible, setSaveToastVisible] = useState(false);
+    }, [activeWorkspaceId, selectedFile, closeWelcomeGateway]);
+    // Ctrl/Cmd+S is a real acknowledgement of the session revision, not an
+    // optimistic toast. A failed commit remains dirty and is surfaced.
+    const [saveToast, setSaveToast] = useState(null);
     const saveToastTimerRef = useRef(null);
     useEffect(() => {
         const onKey = (e) => {
@@ -706,21 +1419,89 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                 return;
             e.preventDefault();
             e.stopPropagation();
-            void flushAutoSave().catch(() => undefined);
-            setSaveToastVisible(true);
-            if (saveToastTimerRef.current)
-                clearTimeout(saveToastTimerRef.current);
-            saveToastTimerRef.current = setTimeout(() => setSaveToastVisible(false), 1800);
+            void (async () => {
+                try {
+                    await documentSession.flush('manual');
+                    setSaveToast({ kind: 'success', message: 'Saved. You’re all set.' });
+                }
+                catch (error) {
+                    setSaveToast({
+                        kind: 'error',
+                        message: isQuotaExceededError(error)
+                            ? 'Could not save -- browser storage is full. Free up space or back up your work.'
+                            : error instanceof Error
+                                ? error.message
+                                : 'Could not save this document.',
+                    });
+                }
+                if (saveToastTimerRef.current)
+                    clearTimeout(saveToastTimerRef.current);
+                saveToastTimerRef.current = setTimeout(() => setSaveToast(null), 3000);
+            })();
         };
         window.addEventListener('keydown', onKey, true);
         return () => window.removeEventListener('keydown', onKey, true);
-    }, [flushAutoSave]);
+    }, [documentSession]);
     useEffect(() => {
         return () => {
             if (saveToastTimerRef.current)
                 clearTimeout(saveToastTimerRef.current);
         };
     }, []);
+    // One-time passive notice when the host reports the app is fully cached
+    // for offline use. Mirrors the save toast's look and self-dismissal.
+    const [offlineReadyToast, setOfflineReadyToast] = useState(false);
+    const offlineReadyAnnouncedRef = useRef(false);
+    useEffect(() => {
+        if (!offlineReady || offlineReadyAnnouncedRef.current)
+            return;
+        offlineReadyAnnouncedRef.current = true;
+        setOfflineReadyToast(true);
+        const timer = setTimeout(() => setOfflineReadyToast(false), 3000);
+        return () => clearTimeout(timer);
+    }, [offlineReady]);
+    // Quota-exhaustion banner. The session clears `error` on every keystroke
+    // and at each retry, so the raw snapshot flickers during a failing
+    // type/retry loop -- latch it, and release only when a commit succeeds.
+    // Known gap: version-snapshot writes (squisq's DocumentVersionManager)
+    // swallow their own failures upstream (`SaveVersionResult` has no error
+    // variant), but they hit the same provider, so the primary autosave
+    // latches this banner within one edit cycle anyway.
+    const [storageFull, setStorageFull] = useState(false);
+    useEffect(() => {
+        if (documentSnapshot.error && isQuotaExceededError(documentSnapshot.error)) {
+            setStorageFull(true);
+        }
+        else if (documentSnapshot.status === 'saved') {
+            setStorageFull(false);
+        }
+    }, [documentSnapshot.error, documentSnapshot.status]);
+    // Ask the browser to make origin storage durable the first time real work
+    // is saved (browser surface only, once per session). Chromium decides
+    // silently -- installed apps are auto-granted; Firefox may show one prompt
+    // at this meaningful moment rather than at page load.
+    const autoPersistRequestedRef = useRef(false);
+    useEffect(() => {
+        if (!showBrowserStorageWarning || browserStoragePersistent)
+            return;
+        if (autoPersistRequestedRef.current)
+            return;
+        if (documentSnapshot.status !== 'saved')
+            return;
+        const storage = typeof navigator !== 'undefined' ? navigator.storage : undefined;
+        if (!storage || typeof storage.persist !== 'function')
+            return;
+        autoPersistRequestedRef.current = true;
+        storage
+            .persist()
+            .then((granted) => {
+            if (granted)
+                setBrowserStoragePersistent(true);
+        })
+            .catch(() => {
+            // Best-effort; the manual menu action remains available.
+        });
+    }, [showBrowserStorageWarning, browserStoragePersistent, documentSnapshot.status]);
     // Per-file media: for `notes.md` images live in `notes_files/` beside it.
     // Rebuilds whenever the provider or selected file changes.
     useEffect(() => {
@@ -745,9 +1526,9 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
         return () => {
             mp.dispose();
         };
-    }, [provider, selectedFile]);
+    }, [provider, selectedFile, mediaEpoch]);
     // Invalidate the document-link candidate cache when the backing
-    // workspace changes — otherwise the link dialog would surface
+    // workspace changes -- otherwise the link dialog would surface
     // neighbours from a previously-open workspace.
     useEffect(() => {
         mdFileCacheRef.current = null;
@@ -807,66 +1588,244 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
     }, [versioningRef, effectiveVersioning, versionBasename, selectedFile, versionsContainer]);
     // React to external file changes watched by the Electron host (chokidar).
     useEffect(() => {
-        if (!isElectronHost())
+        if (!provider)
             return;
-        if (!provider || !(provider instanceof ElectronFileSystemProvider))
+        const providerV2 = getFileSystemProviderV2(provider);
+        if (!providerV2?.capabilities.watch)
             return;
-        const unwatch = provider.watch((changedPath) => {
-            setExplorerKey((k) => k + 1);
-            if (!selectedFile || !sameProviderPath(changedPath, selectedFile))
+        if (!selectedFile || !documentSnapshot.targetKey)
+            return;
+        const watchedFile = selectedFile;
+        const targetKey = documentSnapshot.targetKey;
+        let disposed = false;
+        let reading = false;
+        let rerun = false;
+        let observationSequence = 0;
+        const drainWatcherReads = async () => {
+            if (reading) {
+                rerun = true;
                 return;
-            // If the open file's contents changed on disk, reload it (best-effort).
-            (async () => {
-                const content = await provider.readFile(selectedFile);
-                if (content === null || content === editorContent)
-                    return;
-                const localSave = lastLocalSaveRef.current;
-                if (localSave &&
-                    sameProviderPath(localSave.filePath, selectedFile) &&
-                    localSave.content === content &&
-                    Date.now() - localSave.savedAt < 5000) {
-                    return;
-                }
-                setEditorContent(content);
-                setEditorKey((k) => k + 1);
-            })();
+            }
+            reading = true;
+            try {
+                do {
+                    rerun = false;
+                    const sequence = ++observationSequence;
+                    const external = await readStableFileSnapshot(provider, watchedFile);
+                    if (disposed)
+                        return;
+                    const result = documentSession.observeExternal({
+                        targetKey,
+                        sequence,
+                        content: external.content,
+                        version: external.version,
+                    });
+                    if (result === 'applied') {
+                        // observeExternal increments the session generation. The editor
+                        // remount key and content both derive from that snapshot.
+                    }
+                } while (rerun && !disposed);
+            }
+            catch {
+                // The next watcher event will retry a file that was changing too
+                // quickly to obtain a stable content/metadata pair.
+            }
+            finally {
+                reading = false;
+                if (rerun && !disposed)
+                    void drainWatcherReads();
+            }
+        };
+        const subscription = providerV2.watch((event) => {
+            if (event.type === 'overflow') {
+                void drainWatcherReads();
+                return;
+            }
+            const changedCurrent = sameProviderPath(event.path, watchedFile);
+            const changedDestination = event.destinationPath !== null && sameProviderPath(event.destinationPath, watchedFile);
+            if (changedCurrent || changedDestination)
+                void drainWatcherReads();
+        }, {
+            onError: () => {
+                // Re-read the active file on watcher failure. The session decides
+                // whether the result is a clean update or an external conflict.
+                void drainWatcherReads();
+            },
         });
-        return unwatch;
-    }, [provider, selectedFile, editorContent]);
+        void subscription.ready.catch(() => undefined);
+        return () => {
+            disposed = true;
+            void subscription.dispose();
+        };
+    }, [provider, selectedFile, documentSession, documentSnapshot.targetKey]);
+    const transitionAwayFromDocument = useCallback(async (requestId) => {
+        if (requestId !== navigationRequestRef.current)
+            return false;
+        try {
+            const transitioned = await documentSession.transitionWithLoad(async () => requestId === navigationRequestRef.current ? { target: null, content: '' } : null);
+            if (!transitioned || requestId !== navigationRequestRef.current)
+                return false;
+            return true;
+        }
+        catch (error) {
+            alert(error instanceof Error
+                ? 'DocBlocks could not save this document: ' + error.message
+                : 'DocBlocks could not save this document.');
+            return false;
+        }
+    }, [documentSession]);
+    const handleUseExternalDocument = useCallback(async () => {
+        const conflictKey = documentSession.getSnapshot().conflict?.targetKey;
+        const pendingDbk = conflictKey ? pendingDbkConflictsRef.current.get(conflictKey) : undefined;
+        try {
+            if (pendingDbk) {
+                pendingDbk.provider.replaceContents(pendingDbk.snapshot);
+                pendingDbkConflictsRef.current.delete(conflictKey);
+                mdFileCacheRef.current = null;
+                setMediaEpoch((epoch) => epoch + 1);
+                setExplorerKey((key) => key + 1);
+            }
+            const snapshot = await documentSession.resolveConflict('use-external');
+            if (!snapshot.targetKey) {
+                setSelectedFile(null);
+                if (activeWorkspaceId)
+                    pushHash(activeWorkspaceId, null);
+            }
+        }
+        catch (error) {
+            setSaveToast({
+                kind: 'error',
+                message: error instanceof Error ? error.message : 'Could not reload the external document.',
+            });
+        }
+    }, [activeWorkspaceId, documentSession, pushHash]);
+    const handleKeepLocalDocument = useCallback(async () => {
+        const conflictKey = documentSession.getSnapshot().conflict?.targetKey;
+        try {
+            await documentSession.resolveConflict('use-local');
+            if (conflictKey)
+                pendingDbkConflictsRef.current.delete(conflictKey);
+            setSaveToast({ kind: 'success', message: 'Your version was saved.' });
+        }
+        catch (error) {
+            setSaveToast({
+                kind: 'error',
+                message: error instanceof Error ? error.message : 'Could not save your version.',
+            });
+        }
+    }, [documentSession]);
+    useEffect(() => {
+        const needsWarning = ['dirty', 'saving', 'error', 'conflict'].includes(documentSnapshot.status);
+        if (!documentSnapshot.targetKey)
+            return;
+        const flushBestEffort = () => {
+            void documentSession.flush('close').catch(() => {
+                // A browser cannot await asynchronous storage during teardown. The
+                // beforeunload warning remains active when persistence is unresolved.
+            });
+        };
+        const onBeforeUnload = (event) => {
+            flushBestEffort();
+            if (!needsWarning)
+                return;
+            event.preventDefault();
+            event.returnValue = '';
+        };
+        const onPageHide = () => flushBestEffort();
+        const onVisibilityChange = () => {
+            if (document.visibilityState === 'hidden')
+                flushBestEffort();
+        };
+        window.addEventListener('beforeunload', onBeforeUnload);
+        window.addEventListener('pagehide', onPageHide);
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return () => {
+            window.removeEventListener('beforeunload', onBeforeUnload);
+            window.removeEventListener('pagehide', onPageHide);
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [documentSession, documentSnapshot.status, documentSnapshot.targetKey]);
+    // Electron can defer window destruction and await this acknowledgement.
+    // Browser unload remains best-effort, which is why continuous autosave is
+    // still the primary durability mechanism.
+    useEffect(() => {
+        if (!isElectronHost())
+            return;
+        const lifecycle = getDocBlocksHost().lifecycle;
+        const stopPrepare = lifecycle.onPrepareClose(async (request) => {
+            preparedCloseRequestRef.current = request.requestId;
+            try {
+                const snapshot = await documentSession.prepareClose();
+                return { status: 'ready', persistedRevision: snapshot.persistedRevision };
+            }
+            catch (error) {
+                preparedCloseRequestRef.current = null;
+                return {
+                    status: 'blocked',
+                    code: error instanceof DocumentSessionConflictError
+                        ? 'external-conflict'
+                        : 'save-failed',
+                    message: error instanceof Error ? error.message : 'Could not save the document.',
+                };
+            }
+        });
+        const stopCancel = lifecycle.onCancelClose((requestId) => {
+            if (preparedCloseRequestRef.current !== requestId)
+                return;
+            preparedCloseRequestRef.current = null;
+            documentSession.cancelClose();
+        });
+        return () => {
+            stopPrepare();
+            stopCancel();
+        };
+    }, [documentSession]);
     const handleWorkspaceSelect = useCallback(async (ws) => {
+        const requestId = ++navigationRequestRef.current;
         await touchWorkspace(ws.id);
+        if (requestId !== navigationRequestRef.current)
+            return;
         let nextProvider = null;
-        if (ws.type === 'electron-native') {
+        const transient = getTransientWorkspace(ws.id);
+        if (transient) {
+            nextProvider = transient.provider;
+        }
+        else if (ws.type === 'electron-native') {
             nextProvider = await createElectronProviderFromWorkspace(ws);
             if (!nextProvider)
                 return;
         }
         else if (ws.type === 'native') {
-            const restored = await restoreNativeFolder(ws.id);
+            const restored = await (await loadNativeFileSystem()).restoreNativeFolder(ws.id);
             if (!restored) {
-                // Permission denied or handle lost — fall through without changing provider
+                // Permission denied or handle lost -- fall through without changing provider
                 return;
             }
             nextProvider = restored;
         }
         else {
-            nextProvider = new IndexedDBFileSystemProvider(ws.id, ws.name);
+            nextProvider = await createIndexedDbFileSystemProvider(ws.id, ws.name);
         }
+        if (requestId !== navigationRequestRef.current)
+            return;
+        if (!(await transitionAwayFromDocument(requestId)))
+            return;
         setProvider(nextProvider);
         setActiveWorkspaceId(ws.id);
         setSelectedFile(null);
         setSelectedFolder(null);
         setFolderEntries([]);
-        setEditorContent('');
-        setEditorKey((k) => k + 1);
         pushHash(ws.id, null);
-    }, [pushHash]);
+    }, [pushHash, transitionAwayFromDocument]);
     const handleOpenFolder = useCallback(async () => {
+        const requestId = ++navigationRequestRef.current;
         try {
             if (isElectronHost()) {
                 const info = await getDocBlocksHost().workspaces.pickFolder();
                 if (!info)
                     return; // user cancelled
+                if (requestId !== navigationRequestRef.current)
+                    return;
                 const descriptor = {
                     id: info.id,
                     name: info.name,
@@ -875,18 +1834,22 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                     lastOpened: new Date().toISOString(),
                 };
                 await saveWorkspace(descriptor);
-                const provider = new ElectronFileSystemProvider(info.id, info.name, info.rootPath);
+                if (requestId !== navigationRequestRef.current)
+                    return;
+                const provider = await createElectronFileSystemProvider(info.id, info.name, info.rootPath);
+                if (!(await transitionAwayFromDocument(requestId)))
+                    return;
                 setProvider(provider);
                 setActiveWorkspaceId(descriptor.id);
                 setSelectedFile(null);
                 setSelectedFolder(null);
                 setFolderEntries([]);
-                setEditorContent('');
-                setEditorKey((k) => k + 1);
                 pushHash(descriptor.id, null);
                 return;
             }
-            const nativeProvider = await openNativeFolder();
+            const nativeProvider = await (await loadNativeFileSystem()).openNativeFolder();
+            if (requestId !== navigationRequestRef.current)
+                return;
             const descriptor = {
                 id: nativeProvider.id,
                 name: nativeProvider.label,
@@ -894,19 +1857,47 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                 lastOpened: new Date().toISOString(),
             };
             await saveWorkspace(descriptor);
+            if (requestId !== navigationRequestRef.current)
+                return;
+            if (!(await transitionAwayFromDocument(requestId)))
+                return;
             setProvider(nativeProvider);
             setActiveWorkspaceId(descriptor.id);
             setSelectedFile(null);
             setSelectedFolder(null);
             setFolderEntries([]);
-            setEditorContent('');
-            setEditorKey((k) => k + 1);
             pushHash(descriptor.id, null);
         }
         catch {
             // User cancelled or API not supported
         }
-    }, [pushHash]);
+    }, [pushHash, transitionAwayFromDocument]);
+    // A clone finished: the host already registered + persisted the folder,
+    // so opening it mirrors the pickFolder success path exactly.
+    const handleWorkspaceCloned = useCallback((info) => {
+        const requestId = ++navigationRequestRef.current;
+        void (async () => {
+            const descriptor = {
+                id: info.id,
+                name: info.name,
+                type: 'electron-native',
+                rootPath: info.rootPath,
+                lastOpened: new Date().toISOString(),
+            };
+            await saveWorkspace(descriptor);
+            if (requestId !== navigationRequestRef.current)
+                return;
+            const cloneProvider = await createElectronFileSystemProvider(info.id, info.name, info.rootPath);
+            if (!(await transitionAwayFromDocument(requestId)))
+                return;
+            setProvider(cloneProvider);
+            setActiveWorkspaceId(descriptor.id);
+            setSelectedFile(null);
+            setSelectedFolder(null);
+            setFolderEntries([]);
+            pushHash(descriptor.id, null);
+        })();
+    }, [pushHash, transitionAwayFromDocument]);
     const handleNewFile = useCallback(async () => {
         if (!provider)
             return;
@@ -914,22 +1905,90 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
         if (!name)
             return;
         const filename = /\.[a-zA-Z0-9]+$/.test(name) ? name : `${name}.md`;
-        await provider.writeFile(filename, '# ' + filename.replace(/\.[^.]+$/, '') + '\n');
-        setSelectedFile('/' + filename);
-        setEditorContent('# ' + filename.replace(/\.[^.]+$/, '') + '\n');
+        const path = '/' + filename;
+        const content = '# ' + filename.replace(/\.[^.]+$/, '') + '\n';
+        const requestId = ++navigationRequestRef.current;
+        try {
+            const transitioned = await documentSession.transitionWithLoad(async () => {
+                if (requestId !== navigationRequestRef.current)
+                    return null;
+                const providerV2 = getFileSystemProviderV2(provider);
+                if (providerV2) {
+                    try {
+                        await writeProviderText(provider, path, content, 'create');
+                    }
+                    catch (error) {
+                        if (error instanceof FsError && error.code === 'already-exists') {
+                            throw new Error('A document with that name already exists.');
+                        }
+                        throw error;
+                    }
+                }
+                else if (provider.commitFile) {
+                    const result = await provider.commitFile(path, content, null);
+                    if (result.status === 'conflict') {
+                        throw new Error('A document with that name already exists.');
+                    }
+                }
+                else {
+                    if (await providerEntryExists(provider, path)) {
+                        throw new Error('A document with that name already exists.');
+                    }
+                    await writeProviderText(provider, path, content);
+                }
+                if (requestId !== navigationRequestRef.current)
+                    return null;
+                return {
+                    target: createDocumentTarget(provider, activeWorkspaceId ?? provider.id, path),
+                    content,
+                };
+            });
+            if (!transitioned)
+                return;
+        }
+        catch (error) {
+            alert(error instanceof Error ? error.message : 'Could not create the document.');
+            return;
+        }
+        setSelectedFile(path);
         setInitialView('wysiwyg');
-        setEditorKey((k) => k + 1);
         setExplorerKey((k) => k + 1);
+        closeWelcomeGateway();
         if (activeWorkspaceId) {
             pushHash(activeWorkspaceId, '/' + filename);
         }
-    }, [provider, activeWorkspaceId, pushHash]);
+    }, [
+        provider,
+        activeWorkspaceId,
+        pushHash,
+        closeWelcomeGateway,
+        createDocumentTarget,
+        documentSession,
+    ]);
+    // Manifest shortcut "New document" launches `/?action=new` (installed
+    // PWA jump list). Handled once the first workspace/provider is ready,
+    // then stripped from the URL so a reload doesn't re-trigger it.
+    const actionNewHandledRef = useRef(false);
+    useEffect(() => {
+        if (!provider || actionNewHandledRef.current)
+            return;
+        if (typeof window === 'undefined')
+            return;
+        const params = new URLSearchParams(window.location.search);
+        if (params.get('action') !== 'new')
+            return;
+        actionNewHandledRef.current = true;
+        params.delete('action');
+        const query = params.toString();
+        window.history.replaceState(null, '', window.location.pathname + (query ? `?${query}` : '') + window.location.hash);
+        void handleNewFile();
+    }, [provider, handleNewFile]);
     const handleRevealWorkspace = useCallback(async () => {
         if (!isElectronHost() || !activeWorkspaceId)
             return;
         const ws = await getWorkspace(activeWorkspaceId);
         if (ws?.type === 'electron-native' && ws.rootPath) {
-            await getDocBlocksHost().shell.revealInFolder(ws.rootPath);
+            await getDocBlocksHost().shell.revealInFolder(ws.id);
         }
     }, [activeWorkspaceId]);
     // Subscribe to native menu commands (Electron host).
@@ -948,6 +2007,46 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                 case 'file:revealWorkspace':
                     handleRevealWorkspace();
                     break;
+                case 'git:commit':
+                    if (gitRef.current.repo)
+                        gitRef.current.openDialog({ kind: 'commit' });
+                    break;
+                case 'git:push':
+                    if (gitRef.current.repo)
+                        void gitRef.current.push();
+                    break;
+                case 'git:pull':
+                    if (gitRef.current.repo)
+                        void gitRef.current.pull();
+                    break;
+                case 'git:fetch':
+                    if (gitRef.current.repo)
+                        void gitRef.current.fetchRemote();
+                    break;
+                case 'git:newBranch':
+                    if (gitRef.current.repo) {
+                        gitRef.current.openDialog({ kind: 'branches', createFocus: true });
+                    }
+                    break;
+                case 'git:switchBranch':
+                    if (gitRef.current.repo)
+                        gitRef.current.openDialog({ kind: 'branches' });
+                    break;
+                case 'git:history':
+                    if (gitRef.current.repo)
+                        gitRef.current.openDialog({ kind: 'history' });
+                    break;
+                case 'git:clone':
+                    if (gitRef.current.available)
+                        gitRef.current.openDialog({ kind: 'clone' });
+                    break;
+                case 'git:openOnRemote':
+                    gitRef.current.openOnRemote();
+                    break;
+                case 'git:createPullRequest':
+                    if (gitRef.current.repo)
+                        void gitRef.current.createPullRequest();
+                    break;
                 case 'help:viewOnGitHub':
                     host.shell.openExternal('https://github.com/bendyline/docblocks');
                     break;
@@ -967,81 +2066,126 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
             }
         });
     }, [handleNewFile, handleOpenFolder, handleRevealWorkspace]);
-    // Subscribe to open-file / deep-link requests from the OS.
-    useEffect(() => {
-        if (!isElectronHost())
-            return;
-        const host = getDocBlocksHost();
-        return host.onOpenRequest(async (req) => {
-            if (req.filePath) {
-                const workspaces = (await listWorkspaces()).filter((w) => w.type === 'electron-native' && w.rootPath);
-                const match = workspaces.find((w) => req.filePath.startsWith((w.rootPath ?? '') + '/') || req.filePath === w.rootPath);
-                if (match && match.rootPath) {
-                    const rel = '/' + req.filePath.slice(match.rootPath.length).replace(/^\/+/, '');
-                    await openFromIds(match.id, rel, true);
-                }
-            }
-            else if (req.url) {
-                try {
-                    const u = new URL(req.url);
-                    const path = u.searchParams.get('path');
-                    if (path) {
-                        const workspaces = (await listWorkspaces()).filter((w) => w.type === 'electron-native' && w.rootPath);
-                        const match = workspaces.find((w) => path.startsWith((w.rootPath ?? '') + '/') || path === w.rootPath);
-                        if (match && match.rootPath) {
-                            const rel = '/' + path.slice(match.rootPath.length).replace(/^\/+/, '');
-                            await openFromIds(match.id, rel, true);
-                        }
-                    }
-                }
-                catch {
-                    // bad URL, ignore
-                }
-            }
-        });
-    }, [openFromIds]);
+    // OS open-file / deep-link handling lives after the container helpers it
+    // depends on -- see the `openTransient` + onOpenRequest effect below.
     const handleSelect = useCallback(async (path, kind) => {
         if (!provider || !activeWorkspaceId)
             return;
+        const requestId = ++navigationRequestRef.current;
         if (kind === 'directory') {
+            if (!(await transitionAwayFromDocument(requestId)))
+                return;
+            if (requestId !== navigationRequestRef.current)
+                return;
             setSelectedFile(null);
             setSelectedFolder(path);
-            const entries = await provider.readDirectory(path);
+            const entries = await readProviderDirectory(provider, path);
+            if (requestId !== navigationRequestRef.current)
+                return;
             setFolderEntries(entries);
-            setEditorContent('');
-            setEditorKey((k) => k + 1);
             pushHash(activeWorkspaceId, null);
         }
         else {
-            const content = await provider.readFile(path);
+            let content = null;
+            try {
+                const transitioned = await documentSession.transitionWithLoad(async () => {
+                    if (requestId !== navigationRequestRef.current)
+                        return null;
+                    content = await readProviderText(provider, path);
+                    if (requestId !== navigationRequestRef.current || content === null)
+                        return null;
+                    return {
+                        target: createDocumentTarget(provider, activeWorkspaceId, path),
+                        content,
+                    };
+                });
+                if (!transitioned)
+                    return;
+            }
+            catch (error) {
+                alert(error instanceof Error ? error.message : 'Could not switch documents.');
+                return;
+            }
+            if (requestId !== navigationRequestRef.current)
+                return;
             setSelectedFile(path);
             setSelectedFolder(null);
             setFolderEntries([]);
-            setEditorContent(content ?? '');
             setInitialView('wysiwyg');
-            setEditorKey((k) => k + 1);
+            closeWelcomeGateway();
             pushHash(activeWorkspaceId, path);
             saveLastState({ workspaceId: activeWorkspaceId, filePath: path, view: 'wysiwyg' });
             if (effectiveCompact)
                 setMobileShowEditor(true);
         }
-    }, [provider, activeWorkspaceId, pushHash, effectiveCompact]);
-    const handleTreeChange = useCallback(async () => {
+    }, [
+        provider,
+        activeWorkspaceId,
+        pushHash,
+        effectiveCompact,
+        closeWelcomeGateway,
+        createDocumentTarget,
+        documentSession,
+        transitionAwayFromDocument,
+    ]);
+    const handleTreeMutation = useCallback(async (change, mutate) => {
+        if (!provider || !activeWorkspaceId || !selectedFile) {
+            await mutate();
+            return;
+        }
+        if (change.type === 'move') {
+            const nextFile = relocateProviderPath(selectedFile, change.oldPath, change.newPath);
+            if (nextFile !== selectedFile) {
+                await documentSession.retarget(createDocumentTarget(provider, activeWorkspaceId, nextFile), mutate);
+                return;
+            }
+        }
+        if (change.type === 'delete' && pathContains(change.path, selectedFile)) {
+            await documentSession.delete(mutate);
+            return;
+        }
+        await mutate();
+    }, [provider, activeWorkspaceId, selectedFile, documentSession, createDocumentTarget]);
+    const handleTreeChange = useCallback(async (change) => {
         if (!provider)
             return;
+        if (change?.type === 'move' && change.oldPath && change.newPath) {
+            const nextFile = selectedFile
+                ? relocateProviderPath(selectedFile, change.oldPath, change.newPath)
+                : null;
+            const nextFolder = selectedFolder
+                ? relocateProviderPath(selectedFolder, change.oldPath, change.newPath)
+                : null;
+            if (nextFile !== selectedFile) {
+                setSelectedFile(nextFile);
+                if (activeWorkspaceId) {
+                    pushHash(activeWorkspaceId, nextFile);
+                    if (nextFile) {
+                        saveLastState({
+                            workspaceId: activeWorkspaceId,
+                            filePath: nextFile,
+                            view: 'wysiwyg',
+                        });
+                    }
+                }
+            }
+            if (nextFolder !== selectedFolder)
+                setSelectedFolder(nextFolder);
+            if (nextFolder)
+                setFolderEntries(await readProviderDirectory(provider, nextFolder));
+            return;
+        }
         // If the open file was deleted, clear the editor
         if (selectedFile) {
-            const exists = await provider.exists(selectedFile);
+            const exists = await providerEntryExists(provider, selectedFile);
             if (!exists) {
                 setSelectedFile(null);
-                setEditorContent('');
-                setEditorKey((k) => k + 1);
                 if (activeWorkspaceId)
                     pushHash(activeWorkspaceId, null);
             }
         }
         if (selectedFolder) {
-            const entries = await provider.readDirectory(selectedFolder);
+            const entries = await readProviderDirectory(provider, selectedFolder);
             setFolderEntries(entries);
         }
     }, [provider, selectedFile, selectedFolder, activeWorkspaceId, pushHash]);
@@ -1055,6 +2199,7 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
         const folder = basenameOf(importedMarkdownPath).replace(/\.[^.]+$/, '') + '_files';
         const mediaRoot = parentDir ? `${parentDir}/${folder}` : folder;
         const entries = await source.listFiles();
+        const targetV2 = getFileSystemProviderV2(target);
         for (const entry of entries) {
             if (entry.path.endsWith('.md'))
                 continue;
@@ -1062,7 +2207,16 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
             if (!data)
                 continue;
             const cleanPath = entry.path.replace(/^\/+/, '');
-            await target.writeBinary(`${mediaRoot}/${cleanPath}`, new Uint8Array(data));
+            const destination = `${mediaRoot}/${cleanPath}`;
+            if (targetV2) {
+                await targetV2.writeFile(parseWorkspacePath(destination), data, {
+                    mode: 'upsert',
+                    createParents: true,
+                });
+            }
+            else {
+                await target.writeBinary(destination, data);
+            }
         }
     }, []);
     const handleImportFiles = useCallback(async (files) => {
@@ -1098,7 +2252,7 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                 else {
                     continue;
                 }
-                await provider.writeFile(destPath, markdown);
+                await writeProviderText(provider, destPath, markdown);
             }
             catch (err) {
                 console.error(`Failed to import ${file.name}:`, err);
@@ -1108,8 +2262,16 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
         setExplorerKey((k) => k + 1);
     }, [provider, persistImportedMedia]);
     const handleEditorChange = useCallback((source) => {
-        setEditorContent(source);
-    }, []);
+        if (!editorSessionScope)
+            return;
+        try {
+            documentSession.edit(source, editorSessionScope);
+        }
+        catch {
+            // A close/transition has frozen the session. Do not let a late editor
+            // callback create view state that cannot be persisted.
+        }
+    }, [documentSession, editorSessionScope]);
     const handleRenameWorkspace = useCallback(async () => {
         if (!activeWorkspaceId)
             return;
@@ -1120,45 +2282,210 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
         if (!newName || newName === ws.name)
             return;
         await saveWorkspace({ ...ws, name: newName });
-        // Bump key to trigger re-render — workspace name is read from the descriptor, not the provider
-        setEditorKey((k) => k + 1);
+        setDescriptorRefreshKey((key) => key + 1);
     }, [activeWorkspaceId]);
     /**
-     * Walk a FileSystemProvider and copy every file into `container` under
-     * `pathPrefix` (no leading slash; empty string for the root). Used by
-     * both single- and all-workspace downloads.
+     * Open a loose file or `.dbk` bundle delivered by the OS into a session-only
+     * *transient* workspace backed by an in-memory provider. Loose files save
+     * straight back to disk; bundles are re-zipped by the session commit target.
      */
-    const copyProviderToContainer = useCallback(async (src, container, pathPrefix) => {
-        const encoder = new TextEncoder();
-        const stack = ['/'];
-        while (stack.length > 0) {
-            const dir = stack.pop();
-            const entries = await src.readDirectory(dir);
-            for (const entry of entries) {
-                if (entry.kind === 'directory') {
-                    stack.push(entry.path);
-                    continue;
+    const openTransient = useCallback(async (req, navigationRequestId) => {
+        const isCurrent = () => navigationRequestId === navigationRequestRef.current;
+        const host = getDocBlocksHost();
+        const revokeAbandonedResource = () => host.external.revoke(req.resourceId).catch(() => undefined);
+        if (!isCurrent()) {
+            await revokeAbandonedResource();
+            return;
+        }
+        const id = `transient-${req.kind}-${req.resourceId}`;
+        let mem;
+        try {
+            mem = await createMemoryFileSystemProvider(id, req.name);
+        }
+        catch (error) {
+            await revokeAbandonedResource();
+            throw error;
+        }
+        if (!isCurrent()) {
+            await getFileSystemProviderV2(mem)?.dispose();
+            await revokeAbandonedResource();
+            return;
+        }
+        let primaryFile;
+        let origin;
+        let registered = false;
+        let opened = false;
+        try {
+            if (req.kind === 'external-file') {
+                const content = await host.external.readText(req.resourceId);
+                if (content === null) {
+                    throw new Error('The external file is no longer available.');
                 }
-                const rel = entry.path.replace(/^\/+/, '');
-                const zipPath = pathPrefix ? `${pathPrefix}/${rel}` : rel;
-                // Files may be stored as text (writeFile) or binary (writeBinary);
-                // try binary first, fall back to text and encode as UTF-8.
-                const binary = await src.readBinary(entry.path);
-                if (binary) {
-                    await container.writeFile(zipPath, binary);
-                    continue;
+                if (!isCurrent())
+                    return;
+                primaryFile = req.name; // e.g. "notes.md"
+                mem.seedText(primaryFile, content);
+                origin = { kind: 'loose-file', resourceId: req.resourceId };
+            }
+            else {
+                const bytes = await host.external.readBinary(req.resourceId);
+                if (!bytes) {
+                    throw new Error('The external bundle is no longer available.');
                 }
-                const text = await src.readFile(entry.path);
-                if (text !== null) {
-                    await container.writeFile(zipPath, encoder.encode(text));
+                if (!isCurrent())
+                    return;
+                const version = await sha256Hex(bytes);
+                if (!isCurrent())
+                    return;
+                const { zipToContainer } = await import('@bendyline/squisq-formats/container');
+                if (!isCurrent())
+                    return;
+                const container = await zipToContainer(bytes);
+                if (!isCurrent())
+                    return;
+                const base = req.name.replace(/\.[^.]+$/, '');
+                primaryFile = `${base}.md`;
+                const snapshot = await createDbkWorkspaceSnapshot(container, {
+                    targetDocumentPath: primaryFile,
+                });
+                if (!isCurrent())
+                    return;
+                mem.replaceContents(snapshot);
+                origin = { kind: 'dbk', resourceId: req.resourceId, version };
+            }
+            const descriptor = {
+                id,
+                name: req.name,
+                type: 'transient',
+                lastOpened: new Date().toISOString(),
+                origin,
+            };
+            registerTransientWorkspace(descriptor, mem);
+            registered = true;
+            opened =
+                (await openFromIds(id, `/${primaryFile}`, true, undefined, navigationRequestId)) !== null;
+        }
+        finally {
+            try {
+                if (!opened && registered && getTransientWorkspace(id)?.provider === mem) {
+                    await unregisterTransientWorkspace(id);
+                    registered = false;
                 }
+                else if (!registered) {
+                    await getFileSystemProviderV2(mem)?.dispose();
+                }
+            }
+            finally {
+                if (!opened)
+                    await revokeAbandonedResource();
             }
         }
-    }, []);
+    }, [openFromIds]);
+    // Subscribe to OS open-file / deep-link requests.
+    useEffect(() => {
+        if (!isElectronHost())
+            return;
+        const host = getDocBlocksHost();
+        return host.onOpenRequest((req) => {
+            // Claim the navigation when the OS request arrives, before any external
+            // file read or bundle decoding. A slower older request can no longer
+            // finish after and replace a newer document.
+            const requestId = ++navigationRequestRef.current;
+            void (req.kind === 'workspace-file'
+                ? workspaceAuthorityBarrier.wait().then(() => {
+                    if (requestId !== navigationRequestRef.current)
+                        return null;
+                    return openFromIds(req.workspaceId, req.path, true, undefined, requestId).then((opened) => {
+                        if (!opened && requestId === navigationRequestRef.current) {
+                            throw new Error('The requested workspace file is no longer available.');
+                        }
+                        return opened;
+                    });
+                })
+                : openTransient(req, requestId)).catch((error) => {
+                if (requestId !== navigationRequestRef.current)
+                    return;
+                alert(error instanceof Error
+                    ? 'DocBlocks could not open the requested file: ' + error.message
+                    : 'DocBlocks could not open the requested file.');
+            });
+        });
+    }, [openFromIds, openTransient, workspaceAuthorityBarrier]);
+    /**
+     * Web counterpart of `openTransient`: a `.md` or `.dbk` launched into the
+     * installed PWA (File Handling API) arrives as a FileSystemFileHandle.
+     * Contents are seeded into the same session-only in-memory workspace;
+     * saves write back through the handle (see `createDocumentTarget`).
+     */
+    const openTransientFromHandle = useCallback(async (handle) => {
+        const name = handle.name;
+        const isBundle = /\.(dbk|zip)$/i.test(name);
+        // Keyed by file name: relaunching the same file replaces the registry
+        // entry instead of piling up session workspaces. Two different files
+        // that share a name would collide -- acceptable for session-only state.
+        const id = `transient-web-${isBundle ? 'bundle' : 'file'}-${name}`;
+        // Ask for write access while the OS-launch user activation is fresh so
+        // autosave doesn't have to prompt mid-typing. Best-effort: a denial
+        // surfaces on save, not on open.
+        await ensureHandleWritePermission(handle);
+        const mem = await createMemoryFileSystemProvider(id, name);
+        const file = await handle.getFile();
+        let primaryFile;
+        let origin;
+        if (!isBundle) {
+            primaryFile = name;
+            mem.seedText(primaryFile, await file.text());
+            origin = { kind: 'web-file', handle, name };
+        }
+        else {
+            const bytes = await file.arrayBuffer();
+            const version = await sha256Hex(bytes);
+            const { zipToContainer } = await import('@bendyline/squisq-formats/container');
+            const container = await zipToContainer(bytes);
+            const base = name.replace(/\.[^.]+$/, '');
+            primaryFile = `${base}.md`;
+            const snapshot = await createDbkWorkspaceSnapshot(container, {
+                targetDocumentPath: primaryFile,
+            });
+            mem.replaceContents(snapshot);
+            origin = { kind: 'web-dbk', handle, name, version };
+        }
+        const descriptor = {
+            id,
+            name,
+            type: 'transient',
+            lastOpened: new Date().toISOString(),
+            origin,
+        };
+        registerTransientWorkspace(descriptor, mem);
+        await openFromIds(id, `/${primaryFile}`, true);
+    }, [openFromIds]);
+    // Consume files the OS delivers to the installed PWA (Chromium desktop).
+    // launchQueue buffers launch params until a consumer is set, so a
+    // post-mount effect is early enough to catch the launching file.
+    useEffect(() => {
+        if (isElectronHost() || typeof window === 'undefined')
+            return;
+        const launchQueue = window.launchQueue;
+        if (!launchQueue)
+            return;
+        launchQueue.setConsumer((params) => {
+            if (params.files.length === 0)
+                return;
+            const handle = params.files[0];
+            void openTransientFromHandle(handle).catch((error) => {
+                alert(error instanceof Error
+                    ? 'DocBlocks could not open the launched file: ' + error.message
+                    : 'DocBlocks could not open the launched file.');
+            });
+        });
+    }, [openTransientFromHandle]);
+    const updateStatusBarVisible = viewPreferences.showStatusBar === true && selectedFile !== null && mediaProvider !== null;
     const handleDownloadWorkspace = useCallback(async () => {
         if (!provider)
             return;
         try {
+            await documentSession.flush('backup');
             const [{ MemoryContentContainer }, { containerToZip }] = await Promise.all([
                 import('@bendyline/squisq/storage'),
                 import('@bendyline/squisq-formats/container'),
@@ -1178,23 +2505,26 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
             console.error('Failed to download workspace', err);
             alert('Failed to download workspace. See console for details.');
         }
-    }, [provider, copyProviderToContainer]);
+    }, [provider, documentSession]);
     /**
      * Bundle every workspace the host can open without further prompting
      * into a single zip, with each workspace nested under its own folder.
      * Native (browser-picked) workspaces whose handle hasn't been re-granted
-     * for this session are skipped — restoring them would require a user
+     * for this session are skipped -- restoring them would require a user
      * gesture per workspace.
      */
     const handleDownloadAllWorkspaces = useCallback(async () => {
         try {
+            await documentSession.flush('backup');
             const [{ MemoryContentContainer }, { containerToZip }] = await Promise.all([
                 import('@bendyline/squisq/storage'),
                 import('@bendyline/squisq-formats/container'),
             ]);
             const electron = isElectronHost();
             const all = await listWorkspaces();
-            const candidates = all.filter((w) => electron ? w.type === 'electron-native' : w.type !== 'electron-native');
+            const candidates = all.filter((w) => electron
+                ? w.type === 'electron-native' || w.type === 'transient'
+                : w.type !== 'electron-native');
             if (candidates.length === 0) {
                 alert('No workspaces to download.');
                 return;
@@ -1204,17 +2534,25 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
             const skipped = [];
             for (const ws of candidates) {
                 let p = null;
+                let ownsProvider = false;
                 try {
-                    if (ws.type === 'electron-native') {
+                    const transient = getTransientWorkspace(ws.id);
+                    if (transient) {
+                        p = transient.provider;
+                    }
+                    else if (ws.type === 'electron-native') {
                         p = await createElectronProviderFromWorkspace(ws);
+                        ownsProvider = p !== null;
                     }
                     else if (ws.type === 'native') {
-                        // Restore without prompting — only succeeds when the browser
+                        // Restore without prompting -- only succeeds when the browser
                         // still remembers the granted handle for this origin/session.
-                        p = await restoreNativeFolder(ws.id);
+                        p = await (await loadNativeFileSystem()).restoreNativeFolder(ws.id);
+                        ownsProvider = p !== null;
                     }
                     else {
-                        p = new IndexedDBFileSystemProvider(ws.id, ws.name);
+                        p = await createIndexedDbFileSystemProvider(ws.id, ws.name);
+                        ownsProvider = true;
                     }
                 }
                 catch (err) {
@@ -1232,7 +2570,13 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                     folder = `${base} (${suffix++})`;
                 }
                 usedFolders.add(folder);
-                await copyProviderToContainer(p, container, folder);
+                try {
+                    await copyProviderToContainer(p, container, folder);
+                }
+                finally {
+                    if (ownsProvider)
+                        await getFileSystemProviderV2(p)?.dispose();
+                }
             }
             if (usedFolders.size === 0) {
                 alert('No workspaces could be opened for download.');
@@ -1254,7 +2598,52 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
             console.error('Failed to download all workspaces', err);
             alert('Failed to download all workspaces. See console for details.');
         }
-    }, [copyProviderToContainer]);
+    }, [documentSession]);
+    const handleKeepBrowserData = useCallback(async () => {
+        if (typeof navigator === 'undefined')
+            return;
+        const storage = navigator.storage;
+        if (!storage || typeof storage.persist !== 'function') {
+            alert('This browser does not support persistent storage requests. Please back up browser docs frequently.');
+            return;
+        }
+        try {
+            const alreadyPersistent = typeof storage.persisted === 'function' ? await storage.persisted() : false;
+            if (alreadyPersistent) {
+                setBrowserStoragePersistent(true);
+                alert('DocBlocks browser data is already marked as persistent by this browser.');
+                return;
+            }
+            const granted = await storage.persist();
+            if (granted) {
+                setBrowserStoragePersistent(true);
+                alert('This browser will try to keep DocBlocks data for longer. Please still back up browser docs frequently.');
+            }
+            else {
+                alert('The browser did not grant permanent storage for DocBlocks. Please try again in a day or two. Meanwhile, please back up browser documents frequently.');
+            }
+        }
+        catch {
+            alert('DocBlocks could not request persistent browser storage. Please back up browser docs frequently.');
+        }
+    }, []);
+    // Settings dialog "Storage" row (browser surface): usage/quota estimate.
+    const getBrowserStorageEstimate = useCallback(async () => {
+        if (typeof navigator === 'undefined')
+            return null;
+        const storage = navigator.storage;
+        if (!storage || typeof storage.estimate !== 'function')
+            return null;
+        try {
+            const { usage, quota } = await storage.estimate();
+            if (typeof usage !== 'number' || typeof quota !== 'number')
+                return null;
+            return { usage, quota };
+        }
+        catch {
+            return null;
+        }
+    }, []);
     const handleRemoveWorkspace = useCallback(async () => {
         if (!activeWorkspaceId)
             return;
@@ -1263,19 +2652,35 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
             : 'Remove this workspace? This cannot be undone.';
         if (!confirm(confirmMsg))
             return;
+        const requestId = ++navigationRequestRef.current;
+        if (!(await transitionAwayFromDocument(requestId)))
+            return;
         const ws = await getWorkspace(activeWorkspaceId);
         if (ws?.type === 'electron-native') {
             try {
                 await getDocBlocksHost().workspaces.unregister(activeWorkspaceId);
             }
             catch {
-                // ignore — host cleanup is best-effort
+                // ignore -- host cleanup is best-effort
             }
         }
-        else {
-            await removeDirectoryHandle(activeWorkspaceId);
+        else if (ws?.type === 'transient') {
+            const origin = ws.origin;
+            if (isElectronHost() && origin && (origin.kind === 'loose-file' || origin.kind === 'dbk')) {
+                try {
+                    await getDocBlocksHost().external.revoke(origin.resourceId);
+                }
+                catch {
+                    // Navigation/destruction also revokes the capability; removal is best effort.
+                }
+            }
+        }
+        else if (ws?.type === 'native') {
+            await (await loadNativeFileSystem()).removeDirectoryHandle(activeWorkspaceId);
         }
         await removeWorkspace(activeWorkspaceId);
+        if (requestId !== navigationRequestRef.current)
+            return;
         const electron = isElectronHost();
         // Switch to most recent remaining workspace or create default
         const remaining = (await listWorkspaces()).filter((w) => electron ? w.type === 'electron-native' : w.type !== 'electron-native');
@@ -1293,27 +2698,33 @@ export function DocBlocksShell({ theme: _themeProp = 'auto', logoUrl, allowVersi
                 lastOpened: new Date().toISOString(),
             };
             await saveWorkspace(descriptor);
-            const p = new ElectronFileSystemProvider(info.id, info.name, info.rootPath);
+            const p = await createElectronFileSystemProvider(info.id, info.name, info.rootPath);
             setProvider(p);
             setActiveWorkspaceId(info.id);
             setSelectedFile(null);
             setSelectedFolder(null);
             setFolderEntries([]);
-            setEditorContent('');
-            setEditorKey((k) => k + 1);
         }
         else {
             const defaultWs = await ensureDefaultWorkspace();
-            const fsProvider = new IndexedDBFileSystemProvider(defaultWs.id, defaultWs.name);
+            const fsProvider = await createIndexedDbFileSystemProvider(defaultWs.id, defaultWs.name);
             setProvider(fsProvider);
             setActiveWorkspaceId(defaultWs.id);
             setSelectedFile(null);
             setSelectedFolder(null);
             setFolderEntries([]);
-            setEditorContent('');
-            setEditorKey((k) => k + 1);
         }
-    }, [activeWorkspaceId, handleWorkspaceSelect]);
-    return (_jsxs("div", { className: `db-shell${effectiveCompact ? ' db-shell--mobile' : ''}`, "data-theme": resolvedTheme, children: [saveToastVisible && (_jsx("div", { className: "db-save-toast", role: "status", "aria-live": "polite", children: "Autosaved. You're all set." })), workspaceSettingsOpen && activeWorkspaceDescriptor && (_jsx(WorkspaceSettingsDialog, { workspace: activeWorkspaceDescriptor, globalVersioningPreference: versioningPreference, onChange: handleWorkspaceVersioningOverrideChange, onClose: () => setWorkspaceSettingsOpen(false) })), _jsxs("div", { style: { display: 'flex', flex: 1, overflow: 'hidden' }, children: [(!effectiveCompact || !mobileShowEditor) && (_jsxs("div", { ref: sidebarRef, className: "db-shell-sidebar", style: effectiveCompact ? undefined : { width: `${sidebarWidth}px` }, children: [_jsxs("div", { className: "db-shell-sidebar-header", children: [_jsx(AppMenu, { logoUrl: logoUrl, themePreference: themePreference, onThemeChange: handleThemeChange, versioningPreference: versioningPreference, onVersioningPreferenceChange: handleVersioningPreferenceChange, onDownloadAllWorkspaces: handleDownloadAllWorkspaces }), _jsx(WorkspacePicker, { activeWorkspaceId: activeWorkspaceId, onSelect: handleWorkspaceSelect, onOpenFolder: handleOpenFolder }), _jsx(WorkspaceSettingsButton, { onSettings: handleOpenWorkspaceSettings, onRename: handleRenameWorkspace, onDownload: handleDownloadWorkspace, onRemove: handleRemoveWorkspace })] }), _jsx(FileExplorer, { provider: provider, onSelect: handleSelect, onTreeChange: handleTreeChange, onImportFiles: handleImportFiles }, explorerKey), _jsx("div", { className: "db-shell-sidebar-footer", children: _jsx("a", { href: "https://github.com/bendyline/docblocks/blob/main/LICENSE", target: "_blank", rel: "noopener noreferrer", children: "Terms of Use" }) })] })), !effectiveCompact && (_jsx("div", { className: "db-shell-sidebar-resizer", role: "separator", "aria-orientation": "vertical", "aria-label": "Resize sidebar", onPointerDown: handleResizerPointerDown })), (!effectiveCompact || mobileShowEditor) && (_jsx("div", { style: { flex: 1, overflow: 'hidden', display: 'flex', flexDirection: 'column' }, children: selectedFile && mediaProvider ? (_jsx(MediaContext.Provider, { value: mediaProvider, children: _jsx(EditorShell, { initialMarkdown: editorContent, initialView: initialView, articleId: selectedFile, fileName: selectedFile, onChange: handleEditorChange, theme: resolvedTheme, height: "100%", outlineWidth: 280, mediaProvider: mediaProvider, documentLinkProvider: documentLinkProvider, container: versionsContainer ?? undefined, allowVersioning: effectiveVersioning, viewPreferences: viewPreferences, onViewPreferencesChange: handleViewPreferencesChange, versionBasename: versionBasename ?? stripExtension(basenameOf(selectedFile)), versioningPrunePolicy: versioningPrunePolicy, versioningAutoSaveIdleMs: versioningAutoSaveIdleMs, onSaveVersion: onSaveVersion, toolbarSlotLeft: effectiveCompact ? (_jsx("button", { className: "db-mobile-back", onClick: () => setMobileShowEditor(false), "aria-label": "Show file list", children: _jsx("span", { className: "db-mobile-back-arrow", children: "\u2190" }) })) : undefined, toolbarSlotRight: _jsxs(_Fragment, { children: [compactLayout && !isMobile && (_jsx("button", { className: "db-restore-split", onClick: () => setCompactLayout(false), "aria-label": "Restore split view", title: "Restore split view", children: _jsxs("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("rect", { x: "1.5", y: "2.5", width: "13", height: "11", rx: "1" }), _jsx("line", { x1: "6", y1: "2.5", x2: "6", y2: "13.5" })] }) })), _jsx(ExportToolbarControls, { selectedFile: selectedFile, mediaContainer: mediaContainerRef.current })] }) }, `${selectedFile}-${editorKey}`) })) : selectedFolder ? (_jsxs("div", { className: "db-folder-view", children: [effectiveCompact && (_jsxs("button", { className: "db-mobile-back", onClick: () => setMobileShowEditor(false), children: [_jsx("span", { className: "db-mobile-back-arrow", children: "\u2190" }), "Back to files"] })), _jsxs("div", { className: "db-folder-view-header", children: [_jsx("span", { className: "db-folder-view-icon", children: _jsx(FolderGlyph, {}) }), _jsx("span", { className: "db-folder-view-path", children: selectedFolder })] }), folderEntries.length === 0 ? (_jsx("p", { className: "db-folder-view-empty", children: "This folder is empty." })) : (_jsx("ul", { className: "db-folder-view-list", children: folderEntries.map((entry) => (_jsxs("li", { className: "db-folder-view-item", onClick: () => handleSelect(entry.path, entry.kind), children: [_jsx("span", { className: "db-folder-view-item-icon", children: entry.kind === 'directory' ? _jsx(FolderGlyph, {}) : _jsx(FileGlyph, {}) }), entry.name] }, entry.path))) }))] })) : (_jsxs("div", { className: "db-shell-empty", children: [effectiveCompact && (_jsxs("button", { className: "db-mobile-back", onClick: () => setMobileShowEditor(false), children: [_jsx("span", { className: "db-mobile-back-arrow", children: "\u2190" }), "Back to files"] })), _jsx("p", { children: "Select a file to start editing, or create a new one." })] })) }))] })] }));
+    }, [activeWorkspaceId, handleWorkspaceSelect, transitionAwayFromDocument]);
+    return (_jsx("div", { className: `db-shell${effectiveCompact ? ' db-shell--mobile' : ''}`, "data-theme": resolvedTheme, "data-accent": accentColor, "data-document-status": documentSnapshot.status, children: _jsxs(GitContext.Provider, { value: git, children: [workspaceStartupError && (_jsx("div", { className: "db-save-toast db-save-toast--error", role: "alert", "aria-live": "assertive", children: workspaceStartupError })), saveToast && (_jsx("div", { className: 'db-save-toast db-save-toast--' + saveToast.kind, role: saveToast.kind === 'error' ? 'alert' : 'status', "aria-live": saveToast.kind === 'error' ? 'assertive' : 'polite', children: saveToast.message })), offlineReadyToast && !saveToast && (_jsx("div", { className: "db-save-toast db-save-toast--success", role: "status", "aria-live": "polite", children: "DocBlocks is ready to work offline." })), documentSnapshot.conflict && (_jsxs("div", { className: "db-document-conflict", role: "alert", children: [_jsx("span", { children: "This document changed outside DocBlocks. Your unsaved version is still intact." }), _jsxs("div", { className: "db-document-conflict-actions", children: [_jsx("button", { type: "button", onClick: () => void handleKeepLocalDocument(), children: "Keep mine" }), _jsx("button", { type: "button", onClick: () => void handleUseExternalDocument(), children: "Reload external" })] })] })), storageFull && !documentSnapshot.conflict && (_jsxs("div", { className: "db-storage-full-banner", role: "alert", children: [_jsx("span", { children: "Browser storage is full -- changes can\u2019t be saved. Free up space or back up your work now." }), _jsxs("div", { className: "db-storage-full-banner-actions", children: [_jsx("button", { type: "button", onClick: () => void handleDownloadAllWorkspaces(), children: "Download all workspaces" }), _jsx("button", { type: "button", onClick: () => setStorageFull(false), children: "Dismiss" })] })] })), workspaceSettingsOpen && activeWorkspaceDescriptor && (_jsx(WorkspaceSettingsDialog, { workspace: activeWorkspaceDescriptor, globalVersioningPreference: versioningPreference, onChange: handleWorkspaceVersioningOverrideChange, onClose: () => setWorkspaceSettingsOpen(false) })), _jsxs("div", { style: { display: 'flex', flex: 1, overflow: 'hidden' }, children: [(!effectiveCompact || !mobileShowEditor) && (_jsxs("div", { ref: sidebarRef, className: "db-shell-sidebar", style: effectiveCompact ? undefined : { width: `${sidebarWidth}px` }, children: [_jsxs("div", { className: "db-shell-sidebar-header", children: [_jsx(AppMenu, { logoUrl: logoUrl, themePreference: themePreference, onThemeChange: handleThemeChange, accentColor: accentColor, onAccentColorChange: handleAccentColorChange, versioningPreference: versioningPreference, onVersioningPreferenceChange: handleVersioningPreferenceChange, onDownloadAllWorkspaces: handleDownloadAllWorkspaces, onKeepBrowserData: showBrowserStorageWarning && !browserStoragePersistent
+                                                ? handleKeepBrowserData
+                                                : undefined, onInstallApp: installPromptEvent ? handleInstallApp : undefined, getStorageEstimate: showBrowserStorageWarning ? getBrowserStorageEstimate : undefined, storagePersistent: showBrowserStorageWarning ? browserStoragePersistent : undefined }), _jsx(WorkspacePicker, { activeWorkspaceId: activeWorkspaceId, onSelect: handleWorkspaceSelect, onOpenFolder: handleOpenFolder, onCloneRepository: git.available ? () => git.openDialog({ kind: 'clone' }) : undefined }), _jsx(WorkspaceSettingsButton, { onSettings: handleOpenWorkspaceSettings, onRename: handleRenameWorkspace, onDownload: handleDownloadWorkspace, onRemove: handleRemoveWorkspace }), compactLayout && !isMobile && (_jsx("button", { className: "db-restore-split", onClick: () => setCompactLayout(false), "aria-label": "Restore split view", title: "Restore split view", children: _jsx(SplitViewIcon, {}) }))] }), git.available && (_jsx(Suspense, { fallback: null, children: _jsx(GitUI, { onOpenFile: (path) => void handleSelect(path, 'file'), onWorkspaceCloned: handleWorkspaceCloned }) })), _jsx(FileExplorer, { provider: provider, activeFilePath: selectedFile, onSelect: handleSelect, onTreeMutation: handleTreeMutation, onTreeChange: handleTreeChange, onImportFiles: handleImportFiles }, explorerKey), _jsxs("div", { className: "db-shell-sidebar-footer", children: [_jsx("a", { href: "https://github.com/bendyline/docblocks/blob/main/LICENSE", target: "_blank", rel: "noopener noreferrer", children: "Terms of Use" }), showBrowserStorageWarning && (_jsxs(_Fragment, { children: [_jsx("span", { className: "db-shell-sidebar-footer-separator", "aria-hidden": "true", children: "\u2022" }), _jsx("button", { type: "button", className: "db-shell-sidebar-footer-action", onClick: () => void handleDownloadAllWorkspaces(), title: "Browser docs can get auto-removed. Download all workspaces.", children: "Backup browser docs frequently" })] }))] })] })), !effectiveCompact && (_jsx("div", { className: "db-shell-sidebar-resizer", role: "separator", "aria-orientation": "vertical", "aria-label": "Resize sidebar", onPointerDown: handleResizerPointerDown })), (!effectiveCompact || mobileShowEditor) && (_jsxs("div", { className: updateAvailable && onApplyUpdate && updateStatusBarVisible
+                                ? 'db-shell-editor-area db-shell-editor-area--has-update'
+                                : 'db-shell-editor-area', style: {
+                                flex: 1,
+                                overflow: 'hidden',
+                                display: 'flex',
+                                flexDirection: 'column',
+                                position: 'relative',
+                            }, children: [selectedFile && mediaProvider ? (_jsxs(MediaContext.Provider, { value: mediaProvider, children: [_jsx(Suspense, { fallback: _jsx("div", { className: "db-shell-empty", role: "status", children: "Loading editor\u2026" }), children: _jsx(EditorShell, { initialMarkdown: editorContent, initialView: initialView, articleId: selectedFile, fileName: selectedFile, onChange: handleEditorChange, colorScheme: resolvedTheme, height: "100%", placeholder: editorPlaceholder, outlineWidth: 280, mediaProvider: mediaProvider, documentLinkProvider: documentLinkProvider, workspaceContainer: versionsContainer ?? undefined, allowVersioning: effectiveVersioning, viewPreferences: viewPreferences, onViewPreferencesChange: handleViewPreferencesChange, versionBasename: versionBasename ?? stripExtension(basenameOf(selectedFile)), versioningPrunePolicy: versioningPrunePolicy, versioningAutoSaveIdleMs: versioningAutoSaveIdleMs, onSaveVersion: onSaveVersion, toolbarSlotLeft: effectiveCompact ? (_jsx("button", { className: "db-mobile-back", onClick: () => setMobileShowEditor(false), "aria-label": "Show file list", children: _jsx("span", { className: "db-mobile-back-arrow", children: "\u2190" }) })) : undefined, toolbarSlotRight: _jsxs(_Fragment, { children: [compactLayout && !isMobile && (_jsx("button", { className: "db-restore-split", onClick: () => setCompactLayout(false), "aria-label": "Restore split view", title: "Restore split view", children: _jsx(SplitViewIcon, {}) })), git.repo && (_jsx(Suspense, { fallback: null, children: _jsx(GitToolbarControl, { selectedFile: selectedFile }) })), _jsx(ExportToolbarControls, { selectedFile: selectedFile, mediaContainer: mediaContainerRef.current, destinationAdapter: exportDestinationAdapter })] }) }, `${selectedFile}-${editorKey}`) }), showWelcomeGateway && (_jsxs("div", { className: "db-welcome-gateway", role: "note", "aria-label": "Welcome tip", children: [_jsxs("span", { className: "db-welcome-gateway-text", children: ["You\u2019re watching this welcome doc in ", _jsx("strong", { children: "Slideshow" }), " view -- it\u2019s a regular markdown file, and so is everything you\u2019ll write."] }), _jsx("button", { className: "db-welcome-gateway-cta", onClick: handleStartWriting, children: "Start writing" }), _jsx("button", { className: "db-welcome-gateway-dismiss", onClick: closeWelcomeGateway, "aria-label": "Dismiss welcome tip", title: "Dismiss", children: "\u00D7" })] }))] })) : selectedFolder ? (_jsxs("div", { className: "db-folder-view", children: [effectiveCompact && (_jsxs("button", { className: "db-mobile-back", onClick: () => setMobileShowEditor(false), children: [_jsx("span", { className: "db-mobile-back-arrow", children: "\u2190" }), "Back to files"] })), _jsxs("div", { className: "db-folder-view-header", children: [_jsx("span", { className: "db-folder-view-icon", children: _jsx(FolderGlyph, {}) }), _jsx("span", { className: "db-folder-view-path", children: selectedFolder })] }), folderEntries.length === 0 ? (_jsx("p", { className: "db-folder-view-empty", children: "This folder is empty." })) : (_jsx("ul", { className: "db-folder-view-list", children: folderEntries.map((entry) => (_jsxs("li", { className: "db-folder-view-item", onClick: () => handleSelect(entry.path, entry.kind), children: [_jsx("span", { className: "db-folder-view-item-icon", children: entry.kind === 'directory' ? _jsx(FolderGlyph, {}) : _jsx(FileGlyph, {}) }), entry.name] }, entry.path))) }))] })) : (_jsxs("div", { className: "db-shell-empty", children: [effectiveCompact && (_jsxs("button", { className: "db-mobile-back", onClick: () => setMobileShowEditor(false), children: [_jsx("span", { className: "db-mobile-back-arrow", children: "\u2190" }), "Back to files"] })), _jsx("p", { children: "Select a file to start editing, or create a new one." })] })), _jsx(UpdateAvailableNotice, { available: updateAvailable, onApplyUpdate: onApplyUpdate, blocked: documentSnapshot.conflict !== null || storageFull, statusBarVisible: updateStatusBarVisible })] }))] })] }) }));
 }
 //# sourceMappingURL=DocBlocksShell.js.map